2 Copyright (C) 2005, 2006, 2007, 2008, 2009, 2010
3 Free Software Foundation, Inc.
4 This is part of the GNU Fortran manual.
5 For copying conditions, see the file gfortran.texi.
7 Permission is granted to copy, distribute and/or modify this document
8 under the terms of the GNU Free Documentation License, Version 1.3 or
9 any later version published by the Free Software Foundation; with the
10 Invariant Sections being ``Funding Free Software'', the Front-Cover
11 Texts being (a) (see below), and with the Back-Cover Texts being (b)
12 (see below). A copy of the license is included in the gfdl(7) man page.
15 Some basic guidelines for editing this document:
17 (1) The intrinsic procedures are to be listed in alphabetical order.
18 (2) The generic name is to be used.
19 (3) The specific names are included in the function index and in a
20 table at the end of the node (See ABS entry).
21 (4) Try to maintain the same style for each entry.
27 \gdef\acos{\mathop{\rm acos}\nolimits}
28 \gdef\asin{\mathop{\rm asin}\nolimits}
29 \gdef\atan{\mathop{\rm atan}\nolimits}
30 \gdef\acosh{\mathop{\rm acosh}\nolimits}
31 \gdef\asinh{\mathop{\rm asinh}\nolimits}
32 \gdef\atanh{\mathop{\rm atanh}\nolimits}
36 @node Intrinsic Procedures
37 @chapter Intrinsic Procedures
38 @cindex intrinsic procedures
41 * Introduction: Introduction to Intrinsics
42 * @code{ABORT}: ABORT, Abort the program
43 * @code{ABS}: ABS, Absolute value
44 * @code{ACCESS}: ACCESS, Checks file access modes
45 * @code{ACHAR}: ACHAR, Character in @acronym{ASCII} collating sequence
46 * @code{ACOS}: ACOS, Arccosine function
47 * @code{ACOSH}: ACOSH, Inverse hyperbolic cosine function
48 * @code{ADJUSTL}: ADJUSTL, Left adjust a string
49 * @code{ADJUSTR}: ADJUSTR, Right adjust a string
50 * @code{AIMAG}: AIMAG, Imaginary part of complex number
51 * @code{AINT}: AINT, Truncate to a whole number
52 * @code{ALARM}: ALARM, Set an alarm clock
53 * @code{ALL}: ALL, Determine if all values are true
54 * @code{ALLOCATED}: ALLOCATED, Status of allocatable entity
55 * @code{AND}: AND, Bitwise logical AND
56 * @code{ANINT}: ANINT, Nearest whole number
57 * @code{ANY}: ANY, Determine if any values are true
58 * @code{ASIN}: ASIN, Arcsine function
59 * @code{ASINH}: ASINH, Inverse hyperbolic sine function
60 * @code{ASSOCIATED}: ASSOCIATED, Status of a pointer or pointer/target pair
61 * @code{ATAN}: ATAN, Arctangent function
62 * @code{ATAN2}: ATAN2, Arctangent function
63 * @code{ATANH}: ATANH, Inverse hyperbolic tangent function
64 * @code{BESSEL_J0}: BESSEL_J0, Bessel function of the first kind of order 0
65 * @code{BESSEL_J1}: BESSEL_J1, Bessel function of the first kind of order 1
66 * @code{BESSEL_JN}: BESSEL_JN, Bessel function of the first kind
67 * @code{BESSEL_Y0}: BESSEL_Y0, Bessel function of the second kind of order 0
68 * @code{BESSEL_Y1}: BESSEL_Y1, Bessel function of the second kind of order 1
69 * @code{BESSEL_YN}: BESSEL_YN, Bessel function of the second kind
70 * @code{BGE}: BGE, Bitwise greater than or equal to
71 * @code{BGT}: BGT, Bitwise greater than
72 * @code{BIT_SIZE}: BIT_SIZE, Bit size inquiry function
73 * @code{BLE}: BLE, Bitwise less than or equal to
74 * @code{BLT}: BLT, Bitwise less than
75 * @code{BTEST}: BTEST, Bit test function
76 * @code{C_ASSOCIATED}: C_ASSOCIATED, Status of a C pointer
77 * @code{C_F_POINTER}: C_F_POINTER, Convert C into Fortran pointer
78 * @code{C_F_PROCPOINTER}: C_F_PROCPOINTER, Convert C into Fortran procedure pointer
79 * @code{C_FUNLOC}: C_FUNLOC, Obtain the C address of a procedure
80 * @code{C_LOC}: C_LOC, Obtain the C address of an object
81 * @code{C_SIZEOF}: C_SIZEOF, Size in bytes of an expression
82 * @code{CEILING}: CEILING, Integer ceiling function
83 * @code{CHAR}: CHAR, Integer-to-character conversion function
84 * @code{CHDIR}: CHDIR, Change working directory
85 * @code{CHMOD}: CHMOD, Change access permissions of files
86 * @code{CMPLX}: CMPLX, Complex conversion function
87 * @code{COMMAND_ARGUMENT_COUNT}: COMMAND_ARGUMENT_COUNT, Get number of command line arguments
88 * @code{COMPLEX}: COMPLEX, Complex conversion function
89 * @code{COMPILER_VERSION}: COMPILER_VERSION, Compiler version string
90 * @code{COMPILER_OPTIONS}: COMPILER_OPTIONS, Options passed to the compiler
91 * @code{CONJG}: CONJG, Complex conjugate function
92 * @code{COS}: COS, Cosine function
93 * @code{COSH}: COSH, Hyperbolic cosine function
94 * @code{COUNT}: COUNT, Count occurrences of TRUE in an array
95 * @code{CPU_TIME}: CPU_TIME, CPU time subroutine
96 * @code{CSHIFT}: CSHIFT, Circular shift elements of an array
97 * @code{CTIME}: CTIME, Subroutine (or function) to convert a time into a string
98 * @code{DATE_AND_TIME}: DATE_AND_TIME, Date and time subroutine
99 * @code{DBLE}: DBLE, Double precision conversion function
100 * @code{DCMPLX}: DCMPLX, Double complex conversion function
101 * @code{DIGITS}: DIGITS, Significant digits function
102 * @code{DIM}: DIM, Positive difference
103 * @code{DOT_PRODUCT}: DOT_PRODUCT, Dot product function
104 * @code{DPROD}: DPROD, Double product function
105 * @code{DREAL}: DREAL, Double real part function
106 * @code{DSHIFTL}: DSHIFTL, Combined left shift
107 * @code{DSHIFTR}: DSHIFTR, Combined right shift
108 * @code{DTIME}: DTIME, Execution time subroutine (or function)
109 * @code{EOSHIFT}: EOSHIFT, End-off shift elements of an array
110 * @code{EPSILON}: EPSILON, Epsilon function
111 * @code{ERF}: ERF, Error function
112 * @code{ERFC}: ERFC, Complementary error function
113 * @code{ERFC_SCALED}: ERFC_SCALED, Exponentially-scaled complementary error function
114 * @code{ETIME}: ETIME, Execution time subroutine (or function)
115 * @code{EXECUTE_COMMAND_LINE}: EXECUTE_COMMAND_LINE, Execute a shell command
116 * @code{EXIT}: EXIT, Exit the program with status.
117 * @code{EXP}: EXP, Exponential function
118 * @code{EXPONENT}: EXPONENT, Exponent function
119 * @code{EXTENDS_TYPE_OF}: EXTENDS_TYPE_OF, Query dynamic type for extension
120 * @code{FDATE}: FDATE, Subroutine (or function) to get the current time as a string
121 * @code{FGET}: FGET, Read a single character in stream mode from stdin
122 * @code{FGETC}: FGETC, Read a single character in stream mode
123 * @code{FLOOR}: FLOOR, Integer floor function
124 * @code{FLUSH}: FLUSH, Flush I/O unit(s)
125 * @code{FNUM}: FNUM, File number function
126 * @code{FPUT}: FPUT, Write a single character in stream mode to stdout
127 * @code{FPUTC}: FPUTC, Write a single character in stream mode
128 * @code{FRACTION}: FRACTION, Fractional part of the model representation
129 * @code{FREE}: FREE, Memory de-allocation subroutine
130 * @code{FSEEK}: FSEEK, Low level file positioning subroutine
131 * @code{FSTAT}: FSTAT, Get file status
132 * @code{FTELL}: FTELL, Current stream position
133 * @code{GAMMA}: GAMMA, Gamma function
134 * @code{GERROR}: GERROR, Get last system error message
135 * @code{GETARG}: GETARG, Get command line arguments
136 * @code{GET_COMMAND}: GET_COMMAND, Get the entire command line
137 * @code{GET_COMMAND_ARGUMENT}: GET_COMMAND_ARGUMENT, Get command line arguments
138 * @code{GETCWD}: GETCWD, Get current working directory
139 * @code{GETENV}: GETENV, Get an environmental variable
140 * @code{GET_ENVIRONMENT_VARIABLE}: GET_ENVIRONMENT_VARIABLE, Get an environmental variable
141 * @code{GETGID}: GETGID, Group ID function
142 * @code{GETLOG}: GETLOG, Get login name
143 * @code{GETPID}: GETPID, Process ID function
144 * @code{GETUID}: GETUID, User ID function
145 * @code{GMTIME}: GMTIME, Convert time to GMT info
146 * @code{HOSTNM}: HOSTNM, Get system host name
147 * @code{HUGE}: HUGE, Largest number of a kind
148 * @code{HYPOT}: HYPOT, Euclidean distance function
149 * @code{IACHAR}: IACHAR, Code in @acronym{ASCII} collating sequence
150 * @code{IALL}: IALL, Bitwise AND of array elements
151 * @code{IAND}: IAND, Bitwise logical and
152 * @code{IANY}: IANY, Bitwise OR of array elements
153 * @code{IARGC}: IARGC, Get the number of command line arguments
154 * @code{IBCLR}: IBCLR, Clear bit
155 * @code{IBITS}: IBITS, Bit extraction
156 * @code{IBSET}: IBSET, Set bit
157 * @code{ICHAR}: ICHAR, Character-to-integer conversion function
158 * @code{IDATE}: IDATE, Current local time (day/month/year)
159 * @code{IEOR}: IEOR, Bitwise logical exclusive or
160 * @code{IERRNO}: IERRNO, Function to get the last system error number
161 * @code{IMAGE_INDEX}: IMAGE_INDEX, Cosubscript to image index conversion
162 * @code{INDEX}: INDEX intrinsic, Position of a substring within a string
163 * @code{INT}: INT, Convert to integer type
164 * @code{INT2}: INT2, Convert to 16-bit integer type
165 * @code{INT8}: INT8, Convert to 64-bit integer type
166 * @code{IOR}: IOR, Bitwise logical or
167 * @code{IPARITY}: IPARITY, Bitwise XOR of array elements
168 * @code{IRAND}: IRAND, Integer pseudo-random number
169 * @code{IS_IOSTAT_END}: IS_IOSTAT_END, Test for end-of-file value
170 * @code{IS_IOSTAT_EOR}: IS_IOSTAT_EOR, Test for end-of-record value
171 * @code{ISATTY}: ISATTY, Whether a unit is a terminal device
172 * @code{ISHFT}: ISHFT, Shift bits
173 * @code{ISHFTC}: ISHFTC, Shift bits circularly
174 * @code{ISNAN}: ISNAN, Tests for a NaN
175 * @code{ITIME}: ITIME, Current local time (hour/minutes/seconds)
176 * @code{KILL}: KILL, Send a signal to a process
177 * @code{KIND}: KIND, Kind of an entity
178 * @code{LBOUND}: LBOUND, Lower dimension bounds of an array
179 * @code{LCOBOUND}: LCOBOUND, Lower codimension bounds of an array
180 * @code{LEADZ}: LEADZ, Number of leading zero bits of an integer
181 * @code{LEN}: LEN, Length of a character entity
182 * @code{LEN_TRIM}: LEN_TRIM, Length of a character entity without trailing blank characters
183 * @code{LGE}: LGE, Lexical greater than or equal
184 * @code{LGT}: LGT, Lexical greater than
185 * @code{LINK}: LINK, Create a hard link
186 * @code{LLE}: LLE, Lexical less than or equal
187 * @code{LLT}: LLT, Lexical less than
188 * @code{LNBLNK}: LNBLNK, Index of the last non-blank character in a string
189 * @code{LOC}: LOC, Returns the address of a variable
190 * @code{LOG}: LOG, Logarithm function
191 * @code{LOG10}: LOG10, Base 10 logarithm function
192 * @code{LOG_GAMMA}: LOG_GAMMA, Logarithm of the Gamma function
193 * @code{LOGICAL}: LOGICAL, Convert to logical type
194 * @code{LONG}: LONG, Convert to integer type
195 * @code{LSHIFT}: LSHIFT, Left shift bits
196 * @code{LSTAT}: LSTAT, Get file status
197 * @code{LTIME}: LTIME, Convert time to local time info
198 * @code{MALLOC}: MALLOC, Dynamic memory allocation function
199 * @code{MASKL}: MASKL, Left justified mask
200 * @code{MASKR}: MASKR, Right justified mask
201 * @code{MATMUL}: MATMUL, matrix multiplication
202 * @code{MAX}: MAX, Maximum value of an argument list
203 * @code{MAXEXPONENT}: MAXEXPONENT, Maximum exponent of a real kind
204 * @code{MAXLOC}: MAXLOC, Location of the maximum value within an array
205 * @code{MAXVAL}: MAXVAL, Maximum value of an array
206 * @code{MCLOCK}: MCLOCK, Time function
207 * @code{MCLOCK8}: MCLOCK8, Time function (64-bit)
208 * @code{MERGE}: MERGE, Merge arrays
209 * @code{MERGE_BITS}: MERGE_BITS, Merge of bits under mask
210 * @code{MIN}: MIN, Minimum value of an argument list
211 * @code{MINEXPONENT}: MINEXPONENT, Minimum exponent of a real kind
212 * @code{MINLOC}: MINLOC, Location of the minimum value within an array
213 * @code{MINVAL}: MINVAL, Minimum value of an array
214 * @code{MOD}: MOD, Remainder function
215 * @code{MODULO}: MODULO, Modulo function
216 * @code{MOVE_ALLOC}: MOVE_ALLOC, Move allocation from one object to another
217 * @code{MVBITS}: MVBITS, Move bits from one integer to another
218 * @code{NEAREST}: NEAREST, Nearest representable number
219 * @code{NEW_LINE}: NEW_LINE, New line character
220 * @code{NINT}: NINT, Nearest whole number
221 * @code{NORM2}: NORM2, Euclidean vector norm
222 * @code{NOT}: NOT, Logical negation
223 * @code{NULL}: NULL, Function that returns an disassociated pointer
224 * @code{NUM_IMAGES}: NUM_IMAGES, Number of images
225 * @code{OR}: OR, Bitwise logical OR
226 * @code{PACK}: PACK, Pack an array into an array of rank one
227 * @code{PARITY}: PARITY, Reduction with exclusive OR
228 * @code{PERROR}: PERROR, Print system error message
229 * @code{POPCNT}: POPCNT, Number of bits set
230 * @code{POPPAR}: POPPAR, Parity of the number of bits set
231 * @code{PRECISION}: PRECISION, Decimal precision of a real kind
232 * @code{PRESENT}: PRESENT, Determine whether an optional dummy argument is specified
233 * @code{PRODUCT}: PRODUCT, Product of array elements
234 * @code{RADIX}: RADIX, Base of a data model
235 * @code{RANDOM_NUMBER}: RANDOM_NUMBER, Pseudo-random number
236 * @code{RANDOM_SEED}: RANDOM_SEED, Initialize a pseudo-random number sequence
237 * @code{RAND}: RAND, Real pseudo-random number
238 * @code{RANGE}: RANGE, Decimal exponent range
239 * @code{RAN}: RAN, Real pseudo-random number
240 * @code{REAL}: REAL, Convert to real type
241 * @code{RENAME}: RENAME, Rename a file
242 * @code{REPEAT}: REPEAT, Repeated string concatenation
243 * @code{RESHAPE}: RESHAPE, Function to reshape an array
244 * @code{RRSPACING}: RRSPACING, Reciprocal of the relative spacing
245 * @code{RSHIFT}: RSHIFT, Right shift bits
246 * @code{SAME_TYPE_AS}: SAME_TYPE_AS, Query dynamic types for equality
247 * @code{SCALE}: SCALE, Scale a real value
248 * @code{SCAN}: SCAN, Scan a string for the presence of a set of characters
249 * @code{SECNDS}: SECNDS, Time function
250 * @code{SECOND}: SECOND, CPU time function
251 * @code{SELECTED_CHAR_KIND}: SELECTED_CHAR_KIND, Choose character kind
252 * @code{SELECTED_INT_KIND}: SELECTED_INT_KIND, Choose integer kind
253 * @code{SELECTED_REAL_KIND}: SELECTED_REAL_KIND, Choose real kind
254 * @code{SET_EXPONENT}: SET_EXPONENT, Set the exponent of the model
255 * @code{SHAPE}: SHAPE, Determine the shape of an array
256 * @code{SHIFTA}: SHIFTA, Right shift with fill
257 * @code{SHIFTL}: SHIFTL, Left shift
258 * @code{SHIFTR}: SHIFTR, Right shift
259 * @code{SIGN}: SIGN, Sign copying function
260 * @code{SIGNAL}: SIGNAL, Signal handling subroutine (or function)
261 * @code{SIN}: SIN, Sine function
262 * @code{SINH}: SINH, Hyperbolic sine function
263 * @code{SIZE}: SIZE, Function to determine the size of an array
264 * @code{SIZEOF}: SIZEOF, Determine the size in bytes of an expression
265 * @code{SLEEP}: SLEEP, Sleep for the specified number of seconds
266 * @code{SPACING}: SPACING, Smallest distance between two numbers of a given type
267 * @code{SPREAD}: SPREAD, Add a dimension to an array
268 * @code{SQRT}: SQRT, Square-root function
269 * @code{SRAND}: SRAND, Reinitialize the random number generator
270 * @code{STAT}: STAT, Get file status
271 * @code{STORAGE_SIZE}: STORAGE_SIZE, Storage size in bits
272 * @code{SUM}: SUM, Sum of array elements
273 * @code{SYMLNK}: SYMLNK, Create a symbolic link
274 * @code{SYSTEM}: SYSTEM, Execute a shell command
275 * @code{SYSTEM_CLOCK}: SYSTEM_CLOCK, Time function
276 * @code{TAN}: TAN, Tangent function
277 * @code{TANH}: TANH, Hyperbolic tangent function
278 * @code{THIS_IMAGE}: THIS_IMAGE, Cosubscript index of this image
279 * @code{TIME}: TIME, Time function
280 * @code{TIME8}: TIME8, Time function (64-bit)
281 * @code{TINY}: TINY, Smallest positive number of a real kind
282 * @code{TRAILZ}: TRAILZ, Number of trailing zero bits of an integer
283 * @code{TRANSFER}: TRANSFER, Transfer bit patterns
284 * @code{TRANSPOSE}: TRANSPOSE, Transpose an array of rank two
285 * @code{TRIM}: TRIM, Remove trailing blank characters of a string
286 * @code{TTYNAM}: TTYNAM, Get the name of a terminal device.
287 * @code{UBOUND}: UBOUND, Upper dimension bounds of an array
288 * @code{UCOBOUND}: UCOBOUND, Upper codimension bounds of an array
289 * @code{UMASK}: UMASK, Set the file creation mask
290 * @code{UNLINK}: UNLINK, Remove a file from the file system
291 * @code{UNPACK}: UNPACK, Unpack an array of rank one into an array
292 * @code{VERIFY}: VERIFY, Scan a string for the absence of a set of characters
293 * @code{XOR}: XOR, Bitwise logical exclusive or
296 @node Introduction to Intrinsics
297 @section Introduction to intrinsic procedures
299 The intrinsic procedures provided by GNU Fortran include all of the
300 intrinsic procedures required by the Fortran 95 standard, a set of
301 intrinsic procedures for backwards compatibility with G77, and a
302 selection of intrinsic procedures from the Fortran 2003 and Fortran 2008
303 standards. Any conflict between a description here and a description in
304 either the Fortran 95 standard, the Fortran 2003 standard or the Fortran
305 2008 standard is unintentional, and the standard(s) should be considered
308 The enumeration of the @code{KIND} type parameter is processor defined in
309 the Fortran 95 standard. GNU Fortran defines the default integer type and
310 default real type by @code{INTEGER(KIND=4)} and @code{REAL(KIND=4)},
311 respectively. The standard mandates that both data types shall have
312 another kind, which have more precision. On typical target architectures
313 supported by @command{gfortran}, this kind type parameter is @code{KIND=8}.
314 Hence, @code{REAL(KIND=8)} and @code{DOUBLE PRECISION} are equivalent.
315 In the description of generic intrinsic procedures, the kind type parameter
316 will be specified by @code{KIND=*}, and in the description of specific
317 names for an intrinsic procedure the kind type parameter will be explicitly
318 given (e.g., @code{REAL(KIND=4)} or @code{REAL(KIND=8)}). Finally, for
319 brevity the optional @code{KIND=} syntax will be omitted.
321 Many of the intrinsic procedures take one or more optional arguments.
322 This document follows the convention used in the Fortran 95 standard,
323 and denotes such arguments by square brackets.
325 GNU Fortran offers the @option{-std=f95} and @option{-std=gnu} options,
326 which can be used to restrict the set of intrinsic procedures to a
327 given standard. By default, @command{gfortran} sets the @option{-std=gnu}
328 option, and so all intrinsic procedures described here are accepted. There
329 is one caveat. For a select group of intrinsic procedures, @command{g77}
330 implemented both a function and a subroutine. Both classes
331 have been implemented in @command{gfortran} for backwards compatibility
332 with @command{g77}. It is noted here that these functions and subroutines
333 cannot be intermixed in a given subprogram. In the descriptions that follow,
334 the applicable standard for each intrinsic procedure is noted.
339 @section @code{ABORT} --- Abort the program
341 @cindex program termination, with core dump
342 @cindex terminate program, with core dump
346 @item @emph{Description}:
347 @code{ABORT} causes immediate termination of the program. On operating
348 systems that support a core dump, @code{ABORT} will produce a core dump even if
349 the option @option{-fno-dump-core} is in effect, which is suitable for debugging
351 @c TODO: Check if this (with -fno-dump-core) is correct.
353 @item @emph{Standard}:
362 @item @emph{Return value}:
365 @item @emph{Example}:
368 integer :: i = 1, j = 2
369 if (i /= j) call abort
370 end program test_abort
373 @item @emph{See also}:
374 @ref{EXIT}, @ref{KILL}
381 @section @code{ABS} --- Absolute value
388 @cindex absolute value
391 @item @emph{Description}:
392 @code{ABS(A)} computes the absolute value of @code{A}.
394 @item @emph{Standard}:
395 Fortran 77 and later, has overloads that are GNU extensions
401 @code{RESULT = ABS(A)}
403 @item @emph{Arguments}:
404 @multitable @columnfractions .15 .70
405 @item @var{A} @tab The type of the argument shall be an @code{INTEGER},
406 @code{REAL}, or @code{COMPLEX}.
409 @item @emph{Return value}:
410 The return value is of the same type and
411 kind as the argument except the return value is @code{REAL} for a
412 @code{COMPLEX} argument.
414 @item @emph{Example}:
419 complex :: z = (-1.e0,0.e0)
426 @item @emph{Specific names}:
427 @multitable @columnfractions .20 .20 .20 .25
428 @item Name @tab Argument @tab Return type @tab Standard
429 @item @code{ABS(A)} @tab @code{REAL(4) A} @tab @code{REAL(4)} @tab Fortran 77 and later
430 @item @code{CABS(A)} @tab @code{COMPLEX(4) A} @tab @code{REAL(4)} @tab Fortran 77 and later
431 @item @code{DABS(A)} @tab @code{REAL(8) A} @tab @code{REAL(8)} @tab Fortran 77 and later
432 @item @code{IABS(A)} @tab @code{INTEGER(4) A} @tab @code{INTEGER(4)} @tab Fortran 77 and later
433 @item @code{ZABS(A)} @tab @code{COMPLEX(8) A} @tab @code{COMPLEX(8)} @tab GNU extension
434 @item @code{CDABS(A)} @tab @code{COMPLEX(8) A} @tab @code{COMPLEX(8)} @tab GNU extension
441 @section @code{ACCESS} --- Checks file access modes
443 @cindex file system, access mode
446 @item @emph{Description}:
447 @code{ACCESS(NAME, MODE)} checks whether the file @var{NAME}
448 exists, is readable, writable or executable. Except for the
449 executable check, @code{ACCESS} can be replaced by
450 Fortran 95's @code{INQUIRE}.
452 @item @emph{Standard}:
459 @code{RESULT = ACCESS(NAME, MODE)}
461 @item @emph{Arguments}:
462 @multitable @columnfractions .15 .70
463 @item @var{NAME} @tab Scalar @code{CHARACTER} of default kind with the
464 file name. Tailing blank are ignored unless the character @code{achar(0)}
465 is present, then all characters up to and excluding @code{achar(0)} are
467 @item @var{MODE} @tab Scalar @code{CHARACTER} of default kind with the
468 file access mode, may be any concatenation of @code{"r"} (readable),
469 @code{"w"} (writable) and @code{"x"} (executable), or @code{" "} to check
473 @item @emph{Return value}:
474 Returns a scalar @code{INTEGER}, which is @code{0} if the file is
475 accessible in the given mode; otherwise or if an invalid argument
476 has been given for @code{MODE} the value @code{1} is returned.
478 @item @emph{Example}:
482 character(len=*), parameter :: file = 'test.dat'
483 character(len=*), parameter :: file2 = 'test.dat '//achar(0)
484 if(access(file,' ') == 0) print *, trim(file),' is exists'
485 if(access(file,'r') == 0) print *, trim(file),' is readable'
486 if(access(file,'w') == 0) print *, trim(file),' is writable'
487 if(access(file,'x') == 0) print *, trim(file),' is executable'
488 if(access(file2,'rwx') == 0) &
489 print *, trim(file2),' is readable, writable and executable'
490 end program access_test
492 @item @emph{Specific names}:
493 @item @emph{See also}:
500 @section @code{ACHAR} --- Character in @acronym{ASCII} collating sequence
502 @cindex @acronym{ASCII} collating sequence
503 @cindex collating sequence, @acronym{ASCII}
506 @item @emph{Description}:
507 @code{ACHAR(I)} returns the character located at position @code{I}
508 in the @acronym{ASCII} collating sequence.
510 @item @emph{Standard}:
511 Fortran 77 and later, with @var{KIND} argument Fortran 2003 and later
517 @code{RESULT = ACHAR(I [, KIND])}
519 @item @emph{Arguments}:
520 @multitable @columnfractions .15 .70
521 @item @var{I} @tab The type shall be @code{INTEGER}.
522 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
523 expression indicating the kind parameter of the result.
526 @item @emph{Return value}:
527 The return value is of type @code{CHARACTER} with a length of one.
528 If the @var{KIND} argument is present, the return value is of the
529 specified kind and of the default kind otherwise.
531 @item @emph{Example}:
536 end program test_achar
540 See @ref{ICHAR} for a discussion of converting between numerical values
541 and formatted string representations.
543 @item @emph{See also}:
544 @ref{CHAR}, @ref{IACHAR}, @ref{ICHAR}
551 @section @code{ACOS} --- Arccosine function
554 @cindex trigonometric function, cosine, inverse
555 @cindex cosine, inverse
558 @item @emph{Description}:
559 @code{ACOS(X)} computes the arccosine of @var{X} (inverse of @code{COS(X)}).
561 @item @emph{Standard}:
562 Fortran 77 and later, for a complex argument Fortran 2008 or later
568 @code{RESULT = ACOS(X)}
570 @item @emph{Arguments}:
571 @multitable @columnfractions .15 .70
572 @item @var{X} @tab The type shall either be @code{REAL} with a magnitude that is
573 less than or equal to one - or the type shall be @code{COMPLEX}.
576 @item @emph{Return value}:
577 The return value is of the same type and kind as @var{X}.
578 The real part of the result is in radians and lies in the range
579 @math{0 \leq \Re \acos(x) \leq \pi}.
581 @item @emph{Example}:
584 real(8) :: x = 0.866_8
586 end program test_acos
589 @item @emph{Specific names}:
590 @multitable @columnfractions .20 .20 .20 .25
591 @item Name @tab Argument @tab Return type @tab Standard
592 @item @code{ACOS(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab Fortran 77 and later
593 @item @code{DACOS(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab Fortran 77 and later
596 @item @emph{See also}:
597 Inverse function: @ref{COS}
604 @section @code{ACOSH} --- Inverse hyperbolic cosine function
607 @cindex area hyperbolic cosine
608 @cindex inverse hyperbolic cosine
609 @cindex hyperbolic function, cosine, inverse
610 @cindex cosine, hyperbolic, inverse
613 @item @emph{Description}:
614 @code{ACOSH(X)} computes the inverse hyperbolic cosine of @var{X}.
616 @item @emph{Standard}:
617 Fortran 2008 and later
623 @code{RESULT = ACOSH(X)}
625 @item @emph{Arguments}:
626 @multitable @columnfractions .15 .70
627 @item @var{X} @tab The type shall be @code{REAL} or @code{COMPLEX}.
630 @item @emph{Return value}:
631 The return value has the same type and kind as @var{X}. If @var{X} is
632 complex, the imaginary part of the result is in radians and lies between
633 @math{ 0 \leq \Im \acosh(x) \leq \pi}.
635 @item @emph{Example}:
638 REAL(8), DIMENSION(3) :: x = (/ 1.0, 2.0, 3.0 /)
643 @item @emph{Specific names}:
644 @multitable @columnfractions .20 .20 .20 .25
645 @item Name @tab Argument @tab Return type @tab Standard
646 @item @code{DACOSH(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU extension
649 @item @emph{See also}:
650 Inverse function: @ref{COSH}
656 @section @code{ADJUSTL} --- Left adjust a string
658 @cindex string, adjust left
659 @cindex adjust string
662 @item @emph{Description}:
663 @code{ADJUSTL(STRING)} will left adjust a string by removing leading spaces.
664 Spaces are inserted at the end of the string as needed.
666 @item @emph{Standard}:
673 @code{RESULT = ADJUSTL(STRING)}
675 @item @emph{Arguments}:
676 @multitable @columnfractions .15 .70
677 @item @var{STRING} @tab The type shall be @code{CHARACTER}.
680 @item @emph{Return value}:
681 The return value is of type @code{CHARACTER} and of the same kind as
682 @var{STRING} where leading spaces are removed and the same number of
683 spaces are inserted on the end of @var{STRING}.
685 @item @emph{Example}:
688 character(len=20) :: str = ' gfortran'
691 end program test_adjustl
694 @item @emph{See also}:
695 @ref{ADJUSTR}, @ref{TRIM}
701 @section @code{ADJUSTR} --- Right adjust a string
703 @cindex string, adjust right
704 @cindex adjust string
707 @item @emph{Description}:
708 @code{ADJUSTR(STRING)} will right adjust a string by removing trailing spaces.
709 Spaces are inserted at the start of the string as needed.
711 @item @emph{Standard}:
718 @code{RESULT = ADJUSTR(STRING)}
720 @item @emph{Arguments}:
721 @multitable @columnfractions .15 .70
722 @item @var{STR} @tab The type shall be @code{CHARACTER}.
725 @item @emph{Return value}:
726 The return value is of type @code{CHARACTER} and of the same kind as
727 @var{STRING} where trailing spaces are removed and the same number of
728 spaces are inserted at the start of @var{STRING}.
730 @item @emph{Example}:
733 character(len=20) :: str = 'gfortran'
736 end program test_adjustr
739 @item @emph{See also}:
740 @ref{ADJUSTL}, @ref{TRIM}
746 @section @code{AIMAG} --- Imaginary part of complex number
751 @cindex complex numbers, imaginary part
754 @item @emph{Description}:
755 @code{AIMAG(Z)} yields the imaginary part of complex argument @code{Z}.
756 The @code{IMAG(Z)} and @code{IMAGPART(Z)} intrinsic functions are provided
757 for compatibility with @command{g77}, and their use in new code is
758 strongly discouraged.
760 @item @emph{Standard}:
761 Fortran 77 and later, has overloads that are GNU extensions
767 @code{RESULT = AIMAG(Z)}
769 @item @emph{Arguments}:
770 @multitable @columnfractions .15 .70
771 @item @var{Z} @tab The type of the argument shall be @code{COMPLEX}.
774 @item @emph{Return value}:
775 The return value is of type @code{REAL} with the
776 kind type parameter of the argument.
778 @item @emph{Example}:
783 z4 = cmplx(1.e0_4, 0.e0_4)
784 z8 = cmplx(0.e0_8, 1.e0_8)
785 print *, aimag(z4), dimag(z8)
786 end program test_aimag
789 @item @emph{Specific names}:
790 @multitable @columnfractions .20 .20 .20 .25
791 @item Name @tab Argument @tab Return type @tab Standard
792 @item @code{AIMAG(Z)} @tab @code{COMPLEX Z} @tab @code{REAL} @tab GNU extension
793 @item @code{DIMAG(Z)} @tab @code{COMPLEX(8) Z} @tab @code{REAL(8)} @tab GNU extension
794 @item @code{IMAG(Z)} @tab @code{COMPLEX Z} @tab @code{REAL} @tab GNU extension
795 @item @code{IMAGPART(Z)} @tab @code{COMPLEX Z} @tab @code{REAL} @tab GNU extension
802 @section @code{AINT} --- Truncate to a whole number
806 @cindex rounding, floor
809 @item @emph{Description}:
810 @code{AINT(A [, KIND])} truncates its argument to a whole number.
812 @item @emph{Standard}:
819 @code{RESULT = AINT(A [, KIND])}
821 @item @emph{Arguments}:
822 @multitable @columnfractions .15 .70
823 @item @var{A} @tab The type of the argument shall be @code{REAL}.
824 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
825 expression indicating the kind parameter of the result.
828 @item @emph{Return value}:
829 The return value is of type @code{REAL} with the kind type parameter of the
830 argument if the optional @var{KIND} is absent; otherwise, the kind
831 type parameter will be given by @var{KIND}. If the magnitude of
832 @var{X} is less than one, @code{AINT(X)} returns zero. If the
833 magnitude is equal to or greater than one then it returns the largest
834 whole number that does not exceed its magnitude. The sign is the same
835 as the sign of @var{X}.
837 @item @emph{Example}:
844 print *, aint(x4), dint(x8)
846 end program test_aint
849 @item @emph{Specific names}:
850 @multitable @columnfractions .20 .20 .20 .25
851 @item Name @tab Argument @tab Return type @tab Standard
852 @item @code{AINT(A)} @tab @code{REAL(4) A} @tab @code{REAL(4)} @tab Fortran 77 and later
853 @item @code{DINT(A)} @tab @code{REAL(8) A} @tab @code{REAL(8)} @tab Fortran 77 and later
860 @section @code{ALARM} --- Execute a routine after a given delay
862 @cindex delayed execution
865 @item @emph{Description}:
866 @code{ALARM(SECONDS, HANDLER [, STATUS])} causes external subroutine @var{HANDLER}
867 to be executed after a delay of @var{SECONDS} by using @code{alarm(2)} to
868 set up a signal and @code{signal(2)} to catch it. If @var{STATUS} is
869 supplied, it will be returned with the number of seconds remaining until
870 any previously scheduled alarm was due to be delivered, or zero if there
871 was no previously scheduled alarm.
873 @item @emph{Standard}:
880 @code{CALL ALARM(SECONDS, HANDLER [, STATUS])}
882 @item @emph{Arguments}:
883 @multitable @columnfractions .15 .70
884 @item @var{SECONDS} @tab The type of the argument shall be a scalar
885 @code{INTEGER}. It is @code{INTENT(IN)}.
886 @item @var{HANDLER} @tab Signal handler (@code{INTEGER FUNCTION} or
887 @code{SUBROUTINE}) or dummy/global @code{INTEGER} scalar. The scalar
888 values may be either @code{SIG_IGN=1} to ignore the alarm generated
889 or @code{SIG_DFL=0} to set the default action. It is @code{INTENT(IN)}.
890 @item @var{STATUS} @tab (Optional) @var{STATUS} shall be a scalar
891 variable of the default @code{INTEGER} kind. It is @code{INTENT(OUT)}.
894 @item @emph{Example}:
897 external handler_print
899 call alarm (3, handler_print, i)
902 end program test_alarm
904 This will cause the external routine @var{handler_print} to be called
911 @section @code{ALL} --- All values in @var{MASK} along @var{DIM} are true
913 @cindex array, apply condition
914 @cindex array, condition testing
917 @item @emph{Description}:
918 @code{ALL(MASK [, DIM])} determines if all the values are true in @var{MASK}
919 in the array along dimension @var{DIM}.
921 @item @emph{Standard}:
925 Transformational function
928 @code{RESULT = ALL(MASK [, DIM])}
930 @item @emph{Arguments}:
931 @multitable @columnfractions .15 .70
932 @item @var{MASK} @tab The type of the argument shall be @code{LOGICAL} and
933 it shall not be scalar.
934 @item @var{DIM} @tab (Optional) @var{DIM} shall be a scalar integer
935 with a value that lies between one and the rank of @var{MASK}.
938 @item @emph{Return value}:
939 @code{ALL(MASK)} returns a scalar value of type @code{LOGICAL} where
940 the kind type parameter is the same as the kind type parameter of
941 @var{MASK}. If @var{DIM} is present, then @code{ALL(MASK, DIM)} returns
942 an array with the rank of @var{MASK} minus 1. The shape is determined from
943 the shape of @var{MASK} where the @var{DIM} dimension is elided.
947 @code{ALL(MASK)} is true if all elements of @var{MASK} are true.
948 It also is true if @var{MASK} has zero size; otherwise, it is false.
950 If the rank of @var{MASK} is one, then @code{ALL(MASK,DIM)} is equivalent
951 to @code{ALL(MASK)}. If the rank is greater than one, then @code{ALL(MASK,DIM)}
952 is determined by applying @code{ALL} to the array sections.
955 @item @emph{Example}:
959 l = all((/.true., .true., .true./))
964 integer a(2,3), b(2,3)
968 print *, all(a .eq. b, 1)
969 print *, all(a .eq. b, 2)
970 end subroutine section
978 @section @code{ALLOCATED} --- Status of an allocatable entity
980 @cindex allocation, status
983 @item @emph{Description}:
984 @code{ALLOCATED(ARRAY)} and @code{ALLOCATED(SCALAR)} check the allocation
985 status of @var{ARRAY} and @var{SCALAR}, respectively.
987 @item @emph{Standard}:
988 Fortran 95 and later. Note, the @code{SCALAR=} keyword and allocatable
989 scalar entities are available in Fortran 2003 and later.
995 @code{RESULT = ALLOCATED(ARRAY)} or @code{RESULT = ALLOCATED(SCALAR)}
997 @item @emph{Arguments}:
998 @multitable @columnfractions .15 .70
999 @item @var{ARRAY} @tab The argument shall be an @code{ALLOCATABLE} array.
1000 @item @var{SCALAR} @tab The argument shall be an @code{ALLOCATABLE} scalar.
1003 @item @emph{Return value}:
1004 The return value is a scalar @code{LOGICAL} with the default logical
1005 kind type parameter. If the argument is allocated, then the result is
1006 @code{.TRUE.}; otherwise, it returns @code{.FALSE.}
1008 @item @emph{Example}:
1010 program test_allocated
1012 real(4), allocatable :: x(:)
1013 if (.not. allocated(x)) allocate(x(i))
1014 end program test_allocated
1021 @section @code{AND} --- Bitwise logical AND
1023 @cindex bitwise logical and
1024 @cindex logical and, bitwise
1027 @item @emph{Description}:
1028 Bitwise logical @code{AND}.
1030 This intrinsic routine is provided for backwards compatibility with
1031 GNU Fortran 77. For integer arguments, programmers should consider
1032 the use of the @ref{IAND} intrinsic defined by the Fortran standard.
1034 @item @emph{Standard}:
1040 @item @emph{Syntax}:
1041 @code{RESULT = AND(I, J)}
1043 @item @emph{Arguments}:
1044 @multitable @columnfractions .15 .70
1045 @item @var{I} @tab The type shall be either a scalar @code{INTEGER}
1046 type or a scalar @code{LOGICAL} type.
1047 @item @var{J} @tab The type shall be the same as the type of @var{I}.
1050 @item @emph{Return value}:
1051 The return type is either a scalar @code{INTEGER} or a scalar
1052 @code{LOGICAL}. If the kind type parameters differ, then the
1053 smaller kind type is implicitly converted to larger kind, and the
1054 return has the larger kind.
1056 @item @emph{Example}:
1059 LOGICAL :: T = .TRUE., F = .FALSE.
1061 DATA a / Z'F' /, b / Z'3' /
1063 WRITE (*,*) AND(T, T), AND(T, F), AND(F, T), AND(F, F)
1064 WRITE (*,*) AND(a, b)
1068 @item @emph{See also}:
1069 Fortran 95 elemental function: @ref{IAND}
1075 @section @code{ANINT} --- Nearest whole number
1079 @cindex rounding, ceiling
1082 @item @emph{Description}:
1083 @code{ANINT(A [, KIND])} rounds its argument to the nearest whole number.
1085 @item @emph{Standard}:
1086 Fortran 77 and later
1091 @item @emph{Syntax}:
1092 @code{RESULT = ANINT(A [, KIND])}
1094 @item @emph{Arguments}:
1095 @multitable @columnfractions .15 .70
1096 @item @var{A} @tab The type of the argument shall be @code{REAL}.
1097 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
1098 expression indicating the kind parameter of the result.
1101 @item @emph{Return value}:
1102 The return value is of type real with the kind type parameter of the
1103 argument if the optional @var{KIND} is absent; otherwise, the kind
1104 type parameter will be given by @var{KIND}. If @var{A} is greater than
1105 zero, @code{ANINT(A)} returns @code{AINT(X+0.5)}. If @var{A} is
1106 less than or equal to zero then it returns @code{AINT(X-0.5)}.
1108 @item @emph{Example}:
1115 print *, anint(x4), dnint(x8)
1117 end program test_anint
1120 @item @emph{Specific names}:
1121 @multitable @columnfractions .20 .20 .20 .25
1122 @item Name @tab Argument @tab Return type @tab Standard
1123 @item @code{AINT(A)} @tab @code{REAL(4) A} @tab @code{REAL(4)} @tab Fortran 77 and later
1124 @item @code{DNINT(A)} @tab @code{REAL(8) A} @tab @code{REAL(8)} @tab Fortran 77 and later
1131 @section @code{ANY} --- Any value in @var{MASK} along @var{DIM} is true
1133 @cindex array, apply condition
1134 @cindex array, condition testing
1137 @item @emph{Description}:
1138 @code{ANY(MASK [, DIM])} determines if any of the values in the logical array
1139 @var{MASK} along dimension @var{DIM} are @code{.TRUE.}.
1141 @item @emph{Standard}:
1142 Fortran 95 and later
1145 Transformational function
1147 @item @emph{Syntax}:
1148 @code{RESULT = ANY(MASK [, DIM])}
1150 @item @emph{Arguments}:
1151 @multitable @columnfractions .15 .70
1152 @item @var{MASK} @tab The type of the argument shall be @code{LOGICAL} and
1153 it shall not be scalar.
1154 @item @var{DIM} @tab (Optional) @var{DIM} shall be a scalar integer
1155 with a value that lies between one and the rank of @var{MASK}.
1158 @item @emph{Return value}:
1159 @code{ANY(MASK)} returns a scalar value of type @code{LOGICAL} where
1160 the kind type parameter is the same as the kind type parameter of
1161 @var{MASK}. If @var{DIM} is present, then @code{ANY(MASK, DIM)} returns
1162 an array with the rank of @var{MASK} minus 1. The shape is determined from
1163 the shape of @var{MASK} where the @var{DIM} dimension is elided.
1167 @code{ANY(MASK)} is true if any element of @var{MASK} is true;
1168 otherwise, it is false. It also is false if @var{MASK} has zero size.
1170 If the rank of @var{MASK} is one, then @code{ANY(MASK,DIM)} is equivalent
1171 to @code{ANY(MASK)}. If the rank is greater than one, then @code{ANY(MASK,DIM)}
1172 is determined by applying @code{ANY} to the array sections.
1175 @item @emph{Example}:
1179 l = any((/.true., .true., .true./))
1184 integer a(2,3), b(2,3)
1188 print *, any(a .eq. b, 1)
1189 print *, any(a .eq. b, 2)
1190 end subroutine section
1191 end program test_any
1198 @section @code{ASIN} --- Arcsine function
1201 @cindex trigonometric function, sine, inverse
1202 @cindex sine, inverse
1205 @item @emph{Description}:
1206 @code{ASIN(X)} computes the arcsine of its @var{X} (inverse of @code{SIN(X)}).
1208 @item @emph{Standard}:
1209 Fortran 77 and later, for a complex argument Fortran 2008 or later
1214 @item @emph{Syntax}:
1215 @code{RESULT = ASIN(X)}
1217 @item @emph{Arguments}:
1218 @multitable @columnfractions .15 .70
1219 @item @var{X} @tab The type shall be either @code{REAL} and a magnitude that is
1220 less than or equal to one - or be @code{COMPLEX}.
1223 @item @emph{Return value}:
1224 The return value is of the same type and kind as @var{X}.
1225 The real part of the result is in radians and lies in the range
1226 @math{-\pi/2 \leq \Re \asin(x) \leq \pi/2}.
1228 @item @emph{Example}:
1231 real(8) :: x = 0.866_8
1233 end program test_asin
1236 @item @emph{Specific names}:
1237 @multitable @columnfractions .20 .20 .20 .25
1238 @item Name @tab Argument @tab Return type @tab Standard
1239 @item @code{ASIN(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab Fortran 77 and later
1240 @item @code{DASIN(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab Fortran 77 and later
1243 @item @emph{See also}:
1244 Inverse function: @ref{SIN}
1251 @section @code{ASINH} --- Inverse hyperbolic sine function
1254 @cindex area hyperbolic sine
1255 @cindex inverse hyperbolic sine
1256 @cindex hyperbolic function, sine, inverse
1257 @cindex sine, hyperbolic, inverse
1260 @item @emph{Description}:
1261 @code{ASINH(X)} computes the inverse hyperbolic sine of @var{X}.
1263 @item @emph{Standard}:
1264 Fortran 2008 and later
1269 @item @emph{Syntax}:
1270 @code{RESULT = ASINH(X)}
1272 @item @emph{Arguments}:
1273 @multitable @columnfractions .15 .70
1274 @item @var{X} @tab The type shall be @code{REAL} or @code{COMPLEX}.
1277 @item @emph{Return value}:
1278 The return value is of the same type and kind as @var{X}. If @var{X} is
1279 complex, the imaginary part of the result is in radians and lies between
1280 @math{-\pi/2 \leq \Im \asinh(x) \leq \pi/2}.
1282 @item @emph{Example}:
1285 REAL(8), DIMENSION(3) :: x = (/ -1.0, 0.0, 1.0 /)
1286 WRITE (*,*) ASINH(x)
1290 @item @emph{Specific names}:
1291 @multitable @columnfractions .20 .20 .20 .25
1292 @item Name @tab Argument @tab Return type @tab Standard
1293 @item @code{DASINH(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU extension.
1296 @item @emph{See also}:
1297 Inverse function: @ref{SINH}
1303 @section @code{ASSOCIATED} --- Status of a pointer or pointer/target pair
1305 @cindex pointer, status
1306 @cindex association status
1309 @item @emph{Description}:
1310 @code{ASSOCIATED(POINTER [, TARGET])} determines the status of the pointer
1311 @var{POINTER} or if @var{POINTER} is associated with the target @var{TARGET}.
1313 @item @emph{Standard}:
1314 Fortran 95 and later
1319 @item @emph{Syntax}:
1320 @code{RESULT = ASSOCIATED(POINTER [, TARGET])}
1322 @item @emph{Arguments}:
1323 @multitable @columnfractions .15 .70
1324 @item @var{POINTER} @tab @var{POINTER} shall have the @code{POINTER} attribute
1325 and it can be of any type.
1326 @item @var{TARGET} @tab (Optional) @var{TARGET} shall be a pointer or
1327 a target. It must have the same type, kind type parameter, and
1328 array rank as @var{POINTER}.
1330 The association status of neither @var{POINTER} nor @var{TARGET} shall be
1333 @item @emph{Return value}:
1334 @code{ASSOCIATED(POINTER)} returns a scalar value of type @code{LOGICAL(4)}.
1335 There are several cases:
1337 @item (A) When the optional @var{TARGET} is not present then
1338 @code{ASSOCIATED(POINTER)} is true if @var{POINTER} is associated with a target; otherwise, it returns false.
1339 @item (B) If @var{TARGET} is present and a scalar target, the result is true if
1340 @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
1341 disassociated, the result is false.
1342 @item (C) If @var{TARGET} is present and an array target, the result is true if
1343 @var{TARGET} and @var{POINTER} have the same shape, are not zero-sized arrays,
1344 are arrays whose elements are not zero-sized storage sequences, and
1345 @var{TARGET} and @var{POINTER} occupy the same storage units in array element
1347 As in case(B), the result is false, if @var{POINTER} is disassociated.
1348 @item (D) If @var{TARGET} is present and an scalar pointer, the result is true
1349 if @var{TARGET} is associated with @var{POINTER}, the target associated with
1350 @var{TARGET} are not zero-sized storage sequences and occupy the same storage
1352 The result is false, if either @var{TARGET} or @var{POINTER} is disassociated.
1353 @item (E) If @var{TARGET} is present and an array pointer, the result is true if
1354 target associated with @var{POINTER} and the target associated with @var{TARGET}
1355 have the same shape, are not zero-sized arrays, are arrays whose elements are
1356 not zero-sized storage sequences, and @var{TARGET} and @var{POINTER} occupy
1357 the same storage units in array element order.
1358 The result is false, if either @var{TARGET} or @var{POINTER} is disassociated.
1361 @item @emph{Example}:
1363 program test_associated
1365 real, target :: tgt(2) = (/1., 2./)
1366 real, pointer :: ptr(:)
1368 if (associated(ptr) .eqv. .false.) call abort
1369 if (associated(ptr,tgt) .eqv. .false.) call abort
1370 end program test_associated
1373 @item @emph{See also}:
1380 @section @code{ATAN} --- Arctangent function
1383 @cindex trigonometric function, tangent, inverse
1384 @cindex tangent, inverse
1387 @item @emph{Description}:
1388 @code{ATAN(X)} computes the arctangent of @var{X}.
1390 @item @emph{Standard}:
1391 Fortran 77 and later, for a complex argument and for two arguments
1392 Fortran 2008 or later
1397 @item @emph{Syntax}:
1398 @code{RESULT = ATAN(X)}
1399 @code{RESULT = ATAN(Y, X)}
1401 @item @emph{Arguments}:
1402 @multitable @columnfractions .15 .70
1403 @item @var{X} @tab The type shall be @code{REAL} or @code{COMPLEX};
1404 if @var{Y} is present, @var{X} shall be REAL.
1405 @item @var{Y} shall be of the same type and kind as @var{X}.
1408 @item @emph{Return value}:
1409 The return value is of the same type and kind as @var{X}.
1410 If @var{Y} is present, the result is identical to @code{ATAN2(Y,X)}.
1411 Otherwise, it the arcus tangent of @var{X}, where the real part of
1412 the result is in radians and lies in the range
1413 @math{-\pi/2 \leq \Re \atan(x) \leq \pi/2}.
1415 @item @emph{Example}:
1418 real(8) :: x = 2.866_8
1420 end program test_atan
1423 @item @emph{Specific names}:
1424 @multitable @columnfractions .20 .20 .20 .25
1425 @item Name @tab Argument @tab Return type @tab Standard
1426 @item @code{ATAN(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab Fortran 77 and later
1427 @item @code{DATAN(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab Fortran 77 and later
1430 @item @emph{See also}:
1431 Inverse function: @ref{TAN}
1438 @section @code{ATAN2} --- Arctangent function
1441 @cindex trigonometric function, tangent, inverse
1442 @cindex tangent, inverse
1445 @item @emph{Description}:
1446 @code{ATAN2(Y, X)} computes the principal value of the argument
1447 function of the complex number @math{X + i Y}. This function can
1448 be used to transform from Cartesian into polar coordinates and
1449 allows to determine the angle in the correct quadrant.
1451 @item @emph{Standard}:
1452 Fortran 77 and later
1457 @item @emph{Syntax}:
1458 @code{RESULT = ATAN2(Y, X)}
1460 @item @emph{Arguments}:
1461 @multitable @columnfractions .15 .70
1462 @item @var{Y} @tab The type shall be @code{REAL}.
1463 @item @var{X} @tab The type and kind type parameter shall be the same as @var{Y}.
1464 If @var{Y} is zero, then @var{X} must be nonzero.
1467 @item @emph{Return value}:
1468 The return value has the same type and kind type parameter as @var{Y}.
1469 It is the principal value of the complex number @math{X + i Y}. If
1470 @var{X} is nonzero, then it lies in the range @math{-\pi \le \atan (x) \leq \pi}.
1471 The sign is positive if @var{Y} is positive. If @var{Y} is zero, then
1472 the return value is zero if @var{X} is positive and @math{\pi} if @var{X}
1473 is negative. Finally, if @var{X} is zero, then the magnitude of the result
1476 @item @emph{Example}:
1479 real(4) :: x = 1.e0_4, y = 0.5e0_4
1481 end program test_atan2
1484 @item @emph{Specific names}:
1485 @multitable @columnfractions .20 .20 .20 .25
1486 @item Name @tab Argument @tab Return type @tab Standard
1487 @item @code{ATAN2(X, Y)} @tab @code{REAL(4) X, Y} @tab @code{REAL(4)} @tab Fortran 77 and later
1488 @item @code{DATAN2(X, Y)} @tab @code{REAL(8) X, Y} @tab @code{REAL(8)} @tab Fortran 77 and later
1495 @section @code{ATANH} --- Inverse hyperbolic tangent function
1498 @cindex area hyperbolic tangent
1499 @cindex inverse hyperbolic tangent
1500 @cindex hyperbolic function, tangent, inverse
1501 @cindex tangent, hyperbolic, inverse
1504 @item @emph{Description}:
1505 @code{ATANH(X)} computes the inverse hyperbolic tangent of @var{X}.
1507 @item @emph{Standard}:
1508 Fortran 2008 and later
1513 @item @emph{Syntax}:
1514 @code{RESULT = ATANH(X)}
1516 @item @emph{Arguments}:
1517 @multitable @columnfractions .15 .70
1518 @item @var{X} @tab The type shall be @code{REAL} or @code{COMPLEX}.
1521 @item @emph{Return value}:
1522 The return value has same type and kind as @var{X}. If @var{X} is
1523 complex, the imaginary part of the result is in radians and lies between
1524 @math{-\pi/2 \leq \Im \atanh(x) \leq \pi/2}.
1526 @item @emph{Example}:
1529 REAL, DIMENSION(3) :: x = (/ -1.0, 0.0, 1.0 /)
1530 WRITE (*,*) ATANH(x)
1534 @item @emph{Specific names}:
1535 @multitable @columnfractions .20 .20 .20 .25
1536 @item Name @tab Argument @tab Return type @tab Standard
1537 @item @code{DATANH(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU extension
1540 @item @emph{See also}:
1541 Inverse function: @ref{TANH}
1547 @section @code{BESSEL_J0} --- Bessel function of the first kind of order 0
1551 @cindex Bessel function, first kind
1554 @item @emph{Description}:
1555 @code{BESSEL_J0(X)} computes the Bessel function of the first kind of
1556 order 0 of @var{X}. This function is available under the name
1557 @code{BESJ0} as a GNU extension.
1559 @item @emph{Standard}:
1560 Fortran 2008 and later
1565 @item @emph{Syntax}:
1566 @code{RESULT = BESSEL_J0(X)}
1568 @item @emph{Arguments}:
1569 @multitable @columnfractions .15 .70
1570 @item @var{X} @tab The type shall be @code{REAL}, and it shall be scalar.
1573 @item @emph{Return value}:
1574 The return value is of type @code{REAL} and lies in the
1575 range @math{ - 0.4027... \leq Bessel (0,x) \leq 1}. It has the same
1578 @item @emph{Example}:
1581 real(8) :: x = 0.0_8
1583 end program test_besj0
1586 @item @emph{Specific names}:
1587 @multitable @columnfractions .20 .20 .20 .25
1588 @item Name @tab Argument @tab Return type @tab Standard
1589 @item @code{DBESJ0(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU extension
1596 @section @code{BESSEL_J1} --- Bessel function of the first kind of order 1
1600 @cindex Bessel function, first kind
1603 @item @emph{Description}:
1604 @code{BESSEL_J1(X)} computes the Bessel function of the first kind of
1605 order 1 of @var{X}. This function is available under the name
1606 @code{BESJ1} as a GNU extension.
1608 @item @emph{Standard}:
1614 @item @emph{Syntax}:
1615 @code{RESULT = BESSEL_J1(X)}
1617 @item @emph{Arguments}:
1618 @multitable @columnfractions .15 .70
1619 @item @var{X} @tab The type shall be @code{REAL}, and it shall be scalar.
1622 @item @emph{Return value}:
1623 The return value is of type @code{REAL} and it lies in the
1624 range @math{ - 0.5818... \leq Bessel (0,x) \leq 0.5818 }. It has the same
1627 @item @emph{Example}:
1630 real(8) :: x = 1.0_8
1632 end program test_besj1
1635 @item @emph{Specific names}:
1636 @multitable @columnfractions .20 .20 .20 .25
1637 @item Name @tab Argument @tab Return type @tab Standard
1638 @item @code{DBESJ1(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU extension
1645 @section @code{BESSEL_JN} --- Bessel function of the first kind
1649 @cindex Bessel function, first kind
1652 @item @emph{Description}:
1653 @code{BESSEL_JN(N, X)} computes the Bessel function of the first kind of
1654 order @var{N} of @var{X}. This function is available under the name
1655 @code{BESJN} as a GNU extension. If @var{N} and @var{X} are arrays,
1656 their ranks and shapes shall conform.
1658 @code{BESSEL_JN(N1, N2, X)} returns an array with the Bessel functions
1659 of the first kind of the orders @var{N1} to @var{N2}.
1661 @item @emph{Standard}:
1662 Fortran 2008 and later, negative @var{N} is allowed as GNU extension
1665 Elemental function, except for the transformational function
1666 @code{BESSEL_JN(N1, N2, X)}
1668 @item @emph{Syntax}:
1669 @code{RESULT = BESSEL_JN(N, X)}
1670 @code{RESULT = BESSEL_JN(N1, N2, X)}
1672 @item @emph{Arguments}:
1673 @multitable @columnfractions .15 .70
1674 @item @var{N} @tab Shall be a scalar or an array of type @code{INTEGER}.
1675 @item @var{N1} @tab Shall be a non-negative scalar of type @code{INTEGER}.
1676 @item @var{N2} @tab Shall be a non-negative scalar of type @code{INTEGER}.
1677 @item @var{X} @tab Shall be a scalar or an array of type @code{REAL};
1678 for @code{BESSEL_JN(N1, N2, X)} it shall be scalar.
1681 @item @emph{Return value}:
1682 The return value is a scalar of type @code{REAL}. It has the same
1686 The transformational function uses a recurrence algorithm which might,
1687 for some values of @var{X}, lead to different results than calls to
1688 the elemental function.
1690 @item @emph{Example}:
1693 real(8) :: x = 1.0_8
1695 end program test_besjn
1698 @item @emph{Specific names}:
1699 @multitable @columnfractions .20 .20 .20 .25
1700 @item Name @tab Argument @tab Return type @tab Standard
1701 @item @code{DBESJN(N, X)} @tab @code{INTEGER N} @tab @code{REAL(8)} @tab GNU extension
1702 @item @tab @code{REAL(8) X} @tab @tab
1709 @section @code{BESSEL_Y0} --- Bessel function of the second kind of order 0
1713 @cindex Bessel function, second kind
1716 @item @emph{Description}:
1717 @code{BESSEL_Y0(X)} computes the Bessel function of the second kind of
1718 order 0 of @var{X}. This function is available under the name
1719 @code{BESY0} as a GNU extension.
1721 @item @emph{Standard}:
1722 Fortran 2008 and later
1727 @item @emph{Syntax}:
1728 @code{RESULT = BESSEL_Y0(X)}
1730 @item @emph{Arguments}:
1731 @multitable @columnfractions .15 .70
1732 @item @var{X} @tab The type shall be @code{REAL}, and it shall be scalar.
1735 @item @emph{Return value}:
1736 The return value is a scalar of type @code{REAL}. It has the same
1739 @item @emph{Example}:
1742 real(8) :: x = 0.0_8
1744 end program test_besy0
1747 @item @emph{Specific names}:
1748 @multitable @columnfractions .20 .20 .20 .25
1749 @item Name @tab Argument @tab Return type @tab Standard
1750 @item @code{DBESY0(X)}@tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU extension
1757 @section @code{BESSEL_Y1} --- Bessel function of the second kind of order 1
1761 @cindex Bessel function, second kind
1764 @item @emph{Description}:
1765 @code{BESSEL_Y1(X)} computes the Bessel function of the second kind of
1766 order 1 of @var{X}. This function is available under the name
1767 @code{BESY1} as a GNU extension.
1769 @item @emph{Standard}:
1770 Fortran 2008 and later
1775 @item @emph{Syntax}:
1776 @code{RESULT = BESSEL_Y1(X)}
1778 @item @emph{Arguments}:
1779 @multitable @columnfractions .15 .70
1780 @item @var{X} @tab The type shall be @code{REAL}, and it shall be scalar.
1783 @item @emph{Return value}:
1784 The return value is a scalar of type @code{REAL}. It has the same
1787 @item @emph{Example}:
1790 real(8) :: x = 1.0_8
1792 end program test_besy1
1795 @item @emph{Specific names}:
1796 @multitable @columnfractions .20 .20 .20 .25
1797 @item Name @tab Argument @tab Return type @tab Standard
1798 @item @code{DBESY1(X)}@tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU extension
1805 @section @code{BESSEL_YN} --- Bessel function of the second kind
1809 @cindex Bessel function, second kind
1812 @item @emph{Description}:
1813 @code{BESSEL_YN(N, X)} computes the Bessel function of the second kind of
1814 order @var{N} of @var{X}. This function is available under the name
1815 @code{BESYN} as a GNU extension. If @var{N} and @var{X} are arrays,
1816 their ranks and shapes shall conform.
1818 @code{BESSEL_YN(N1, N2, X)} returns an array with the Bessel functions
1819 of the first kind of the orders @var{N1} to @var{N2}.
1821 @item @emph{Standard}:
1822 Fortran 2008 and later, negative @var{N} is allowed as GNU extension
1825 Elemental function, except for the transformational function
1826 @code{BESSEL_YN(N1, N2, X)}
1828 @item @emph{Syntax}:
1829 @code{RESULT = BESSEL_YN(N, X)}
1830 @code{RESULT = BESSEL_YN(N1, N2, X)}
1832 @item @emph{Arguments}:
1833 @multitable @columnfractions .15 .70
1834 @item @var{N} @tab Shall be a scalar or an array of type @code{INTEGER} .
1835 @item @var{N1} @tab Shall be a non-negative scalar of type @code{INTEGER}.
1836 @item @var{N2} @tab Shall be a non-negative scalar of type @code{INTEGER}.
1837 @item @var{X} @tab Shall be a scalar or an array of type @code{REAL};
1838 for @code{BESSEL_YN(N1, N2, X)} it shall be scalar.
1841 @item @emph{Return value}:
1842 The return value is a scalar of type @code{REAL}. It has the same
1846 The transformational function uses a recurrence algorithm which might,
1847 for some values of @var{X}, lead to different results than calls to
1848 the elemental function.
1850 @item @emph{Example}:
1853 real(8) :: x = 1.0_8
1855 end program test_besyn
1858 @item @emph{Specific names}:
1859 @multitable @columnfractions .20 .20 .20 .25
1860 @item Name @tab Argument @tab Return type @tab Standard
1861 @item @code{DBESYN(N,X)} @tab @code{INTEGER N} @tab @code{REAL(8)} @tab GNU extension
1862 @item @tab @code{REAL(8) X} @tab @tab
1869 @section @code{BGE} --- Bitwise greater than or equal to
1871 @cindex bitwise comparison
1874 @item @emph{Description}:
1875 Determines whether an integral is a bitwise greater than or equal to
1878 @item @emph{Standard}:
1879 Fortran 2008 and later
1884 @item @emph{Syntax}:
1885 @code{RESULT = BGE(I, J)}
1887 @item @emph{Arguments}:
1888 @multitable @columnfractions .15 .70
1889 @item @var{I} @tab Shall be of @code{INTEGER} type.
1890 @item @var{J} @tab Shall be of @code{INTEGER} type, and of the same kind
1894 @item @emph{Return value}:
1895 The return value is of type @code{LOGICAL} and of the default kind.
1897 @item @emph{See also}:
1898 @ref{BGT}, @ref{BLE}, @ref{BLT}
1904 @section @code{BGT} --- Bitwise greater than
1906 @cindex bitwise comparison
1909 @item @emph{Description}:
1910 Determines whether an integral is a bitwise greater than another.
1912 @item @emph{Standard}:
1913 Fortran 2008 and later
1918 @item @emph{Syntax}:
1919 @code{RESULT = BGT(I, J)}
1921 @item @emph{Arguments}:
1922 @multitable @columnfractions .15 .70
1923 @item @var{I} @tab Shall be of @code{INTEGER} type.
1924 @item @var{J} @tab Shall be of @code{INTEGER} type, and of the same kind
1928 @item @emph{Return value}:
1929 The return value is of type @code{LOGICAL} and of the default kind.
1931 @item @emph{See also}:
1932 @ref{BGE}, @ref{BLE}, @ref{BLT}
1938 @section @code{BIT_SIZE} --- Bit size inquiry function
1940 @cindex bits, number of
1941 @cindex size of a variable, in bits
1944 @item @emph{Description}:
1945 @code{BIT_SIZE(I)} returns the number of bits (integer precision plus sign bit)
1946 represented by the type of @var{I}. The result of @code{BIT_SIZE(I)} is
1947 independent of the actual value of @var{I}.
1949 @item @emph{Standard}:
1950 Fortran 95 and later
1955 @item @emph{Syntax}:
1956 @code{RESULT = BIT_SIZE(I)}
1958 @item @emph{Arguments}:
1959 @multitable @columnfractions .15 .70
1960 @item @var{I} @tab The type shall be @code{INTEGER}.
1963 @item @emph{Return value}:
1964 The return value is of type @code{INTEGER}
1966 @item @emph{Example}:
1968 program test_bit_size
1973 end program test_bit_size
1980 @section @code{BLE} --- Bitwise less than or equal to
1982 @cindex bitwise comparison
1985 @item @emph{Description}:
1986 Determines whether an integral is a bitwise less than or equal to
1989 @item @emph{Standard}:
1990 Fortran 2008 and later
1995 @item @emph{Syntax}:
1996 @code{RESULT = BLE(I, J)}
1998 @item @emph{Arguments}:
1999 @multitable @columnfractions .15 .70
2000 @item @var{I} @tab Shall be of @code{INTEGER} type.
2001 @item @var{J} @tab Shall be of @code{INTEGER} type, and of the same kind
2005 @item @emph{Return value}:
2006 The return value is of type @code{LOGICAL} and of the default kind.
2008 @item @emph{See also}:
2009 @ref{BGT}, @ref{BGE}, @ref{BLT}
2015 @section @code{BLT} --- Bitwise less than
2017 @cindex bitwise comparison
2020 @item @emph{Description}:
2021 Determines whether an integral is a bitwise less than another.
2023 @item @emph{Standard}:
2024 Fortran 2008 and later
2029 @item @emph{Syntax}:
2030 @code{RESULT = BLT(I, J)}
2032 @item @emph{Arguments}:
2033 @multitable @columnfractions .15 .70
2034 @item @var{I} @tab Shall be of @code{INTEGER} type.
2035 @item @var{J} @tab Shall be of @code{INTEGER} type, and of the same kind
2039 @item @emph{Return value}:
2040 The return value is of type @code{LOGICAL} and of the default kind.
2042 @item @emph{See also}:
2043 @ref{BGE}, @ref{BGT}, @ref{BLE}
2049 @section @code{BTEST} --- Bit test function
2051 @cindex bits, testing
2054 @item @emph{Description}:
2055 @code{BTEST(I,POS)} returns logical @code{.TRUE.} if the bit at @var{POS}
2056 in @var{I} is set. The counting of the bits starts at 0.
2058 @item @emph{Standard}:
2059 Fortran 95 and later
2064 @item @emph{Syntax}:
2065 @code{RESULT = BTEST(I, POS)}
2067 @item @emph{Arguments}:
2068 @multitable @columnfractions .15 .70
2069 @item @var{I} @tab The type shall be @code{INTEGER}.
2070 @item @var{POS} @tab The type shall be @code{INTEGER}.
2073 @item @emph{Return value}:
2074 The return value is of type @code{LOGICAL}
2076 @item @emph{Example}:
2079 integer :: i = 32768 + 1024 + 64
2083 bool = btest(i, pos)
2086 end program test_btest
2092 @section @code{C_ASSOCIATED} --- Status of a C pointer
2093 @fnindex C_ASSOCIATED
2094 @cindex association status, C pointer
2095 @cindex pointer, C association status
2098 @item @emph{Description}:
2099 @code{C_ASSOCIATED(c_prt_1[, c_ptr_2])} determines the status of the C pointer
2100 @var{c_ptr_1} or if @var{c_ptr_1} is associated with the target @var{c_ptr_2}.
2102 @item @emph{Standard}:
2103 Fortran 2003 and later
2108 @item @emph{Syntax}:
2109 @code{RESULT = C_ASSOCIATED(c_prt_1[, c_ptr_2])}
2111 @item @emph{Arguments}:
2112 @multitable @columnfractions .15 .70
2113 @item @var{c_ptr_1} @tab Scalar of the type @code{C_PTR} or @code{C_FUNPTR}.
2114 @item @var{c_ptr_2} @tab (Optional) Scalar of the same type as @var{c_ptr_1}.
2117 @item @emph{Return value}:
2118 The return value is of type @code{LOGICAL}; it is @code{.false.} if either
2119 @var{c_ptr_1} is a C NULL pointer or if @var{c_ptr1} and @var{c_ptr_2}
2120 point to different addresses.
2122 @item @emph{Example}:
2124 subroutine association_test(a,b)
2125 use iso_c_binding, only: c_associated, c_loc, c_ptr
2129 if(c_associated(b, c_loc(a))) &
2130 stop 'b and a do not point to same target'
2131 end subroutine association_test
2134 @item @emph{See also}:
2135 @ref{C_LOC}, @ref{C_FUNLOC}
2140 @section @code{C_FUNLOC} --- Obtain the C address of a procedure
2142 @cindex pointer, C address of procedures
2145 @item @emph{Description}:
2146 @code{C_FUNLOC(x)} determines the C address of the argument.
2148 @item @emph{Standard}:
2149 Fortran 2003 and later
2154 @item @emph{Syntax}:
2155 @code{RESULT = C_FUNLOC(x)}
2157 @item @emph{Arguments}:
2158 @multitable @columnfractions .15 .70
2159 @item @var{x} @tab Interoperable function or pointer to such function.
2162 @item @emph{Return value}:
2163 The return value is of type @code{C_FUNPTR} and contains the C address
2166 @item @emph{Example}:
2172 subroutine sub(a) bind(c)
2182 subroutine my_routine(p) bind(c,name='myC_func')
2184 type(c_funptr), intent(in) :: p
2187 call my_routine(c_funloc(sub))
2191 @item @emph{See also}:
2192 @ref{C_ASSOCIATED}, @ref{C_LOC}, @ref{C_F_POINTER}, @ref{C_F_PROCPOINTER}
2196 @node C_F_PROCPOINTER
2197 @section @code{C_F_PROCPOINTER} --- Convert C into Fortran procedure pointer
2198 @fnindex C_F_PROCPOINTER
2199 @cindex pointer, C address of pointers
2202 @item @emph{Description}:
2203 @code{C_F_PROCPOINTER(CPTR, FPTR)} Assign the target of the C function pointer
2204 @var{CPTR} to the Fortran procedure pointer @var{FPTR}.
2206 @item @emph{Standard}:
2207 Fortran 2003 and later
2212 @item @emph{Syntax}:
2213 @code{CALL C_F_PROCPOINTER(cptr, fptr)}
2215 @item @emph{Arguments}:
2216 @multitable @columnfractions .15 .70
2217 @item @var{CPTR} @tab scalar of the type @code{C_FUNPTR}. It is
2219 @item @var{FPTR} @tab procedure pointer interoperable with @var{cptr}. It is
2223 @item @emph{Example}:
2231 real(c_float), intent(in) :: a
2232 real(c_float) :: func
2236 function getIterFunc() bind(c,name="getIterFunc")
2238 type(c_funptr) :: getIterFunc
2241 type(c_funptr) :: cfunptr
2242 procedure(func), pointer :: myFunc
2243 cfunptr = getIterFunc()
2244 call c_f_procpointer(cfunptr, myFunc)
2248 @item @emph{See also}:
2249 @ref{C_LOC}, @ref{C_F_POINTER}
2254 @section @code{C_F_POINTER} --- Convert C into Fortran pointer
2255 @fnindex C_F_POINTER
2256 @cindex pointer, convert C to Fortran
2259 @item @emph{Description}:
2260 @code{C_F_POINTER(CPTR, FPTR[, SHAPE])} Assign the target the C pointer
2261 @var{CPTR} to the Fortran pointer @var{FPTR} and specify its
2264 @item @emph{Standard}:
2265 Fortran 2003 and later
2270 @item @emph{Syntax}:
2271 @code{CALL C_F_POINTER(CPTR, FPTR[, SHAPE])}
2273 @item @emph{Arguments}:
2274 @multitable @columnfractions .15 .70
2275 @item @var{CPTR} @tab scalar of the type @code{C_PTR}. It is
2277 @item @var{FPTR} @tab pointer interoperable with @var{cptr}. It is
2279 @item @var{SHAPE} @tab (Optional) Rank-one array of type @code{INTEGER}
2280 with @code{INTENT(IN)}. It shall be present
2281 if and only if @var{fptr} is an array. The size
2282 must be equal to the rank of @var{fptr}.
2285 @item @emph{Example}:
2291 subroutine my_routine(p) bind(c,name='myC_func')
2293 type(c_ptr), intent(out) :: p
2297 real,pointer :: a(:)
2298 call my_routine(cptr)
2299 call c_f_pointer(cptr, a, [12])
2303 @item @emph{See also}:
2304 @ref{C_LOC}, @ref{C_F_PROCPOINTER}
2309 @section @code{C_LOC} --- Obtain the C address of an object
2311 @cindex procedure pointer, convert C to Fortran
2314 @item @emph{Description}:
2315 @code{C_LOC(X)} determines the C address of the argument.
2317 @item @emph{Standard}:
2318 Fortran 2003 and later
2323 @item @emph{Syntax}:
2324 @code{RESULT = C_LOC(X)}
2326 @item @emph{Arguments}:
2327 @multitable @columnfractions .10 .75
2328 @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.
2332 @item @emph{Return value}:
2333 The return value is of type @code{C_PTR} and contains the C address
2336 @item @emph{Example}:
2338 subroutine association_test(a,b)
2339 use iso_c_binding, only: c_associated, c_loc, c_ptr
2343 if(c_associated(b, c_loc(a))) &
2344 stop 'b and a do not point to same target'
2345 end subroutine association_test
2348 @item @emph{See also}:
2349 @ref{C_ASSOCIATED}, @ref{C_FUNLOC}, @ref{C_F_POINTER}, @ref{C_F_PROCPOINTER}
2354 @section @code{C_SIZEOF} --- Size in bytes of an expression
2356 @cindex expression size
2357 @cindex size of an expression
2360 @item @emph{Description}:
2361 @code{C_SIZEOF(X)} calculates the number of bytes of storage the
2362 expression @code{X} occupies.
2364 @item @emph{Standard}:
2368 Inquiry function of the module @code{ISO_C_BINDING}
2370 @item @emph{Syntax}:
2371 @code{N = C_SIZEOF(X)}
2373 @item @emph{Arguments}:
2374 @multitable @columnfractions .15 .70
2375 @item @var{X} @tab The argument shall be an interoperable data entity.
2378 @item @emph{Return value}:
2379 The return value is of type integer and of the system-dependent kind
2380 @code{C_SIZE_T} (from the @code{ISO_C_BINDING} module). Its value is the
2381 number of bytes occupied by the argument. If the argument has the
2382 @code{POINTER} attribute, the number of bytes of the storage area pointed
2383 to is returned. If the argument is of a derived type with @code{POINTER}
2384 or @code{ALLOCATABLE} components, the return value doesn't account for
2385 the sizes of the data pointed to by these components.
2387 @item @emph{Example}:
2391 real(c_float) :: r, s(5)
2392 print *, (c_sizeof(s)/c_sizeof(r) == 5)
2395 The example will print @code{.TRUE.} unless you are using a platform
2396 where default @code{REAL} variables are unusually padded.
2398 @item @emph{See also}:
2399 @ref{SIZEOF}, @ref{STORAGE_SIZE}
2404 @section @code{CEILING} --- Integer ceiling function
2407 @cindex rounding, ceiling
2410 @item @emph{Description}:
2411 @code{CEILING(A)} returns the least integer greater than or equal to @var{A}.
2413 @item @emph{Standard}:
2414 Fortran 95 and later
2419 @item @emph{Syntax}:
2420 @code{RESULT = CEILING(A [, KIND])}
2422 @item @emph{Arguments}:
2423 @multitable @columnfractions .15 .70
2424 @item @var{A} @tab The type shall be @code{REAL}.
2425 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
2426 expression indicating the kind parameter of the result.
2429 @item @emph{Return value}:
2430 The return value is of type @code{INTEGER(KIND)} if @var{KIND} is present
2431 and a default-kind @code{INTEGER} otherwise.
2433 @item @emph{Example}:
2435 program test_ceiling
2438 print *, ceiling(x) ! returns 64
2439 print *, ceiling(y) ! returns -63
2440 end program test_ceiling
2443 @item @emph{See also}:
2444 @ref{FLOOR}, @ref{NINT}
2451 @section @code{CHAR} --- Character conversion function
2453 @cindex conversion, to character
2456 @item @emph{Description}:
2457 @code{CHAR(I [, KIND])} returns the character represented by the integer @var{I}.
2459 @item @emph{Standard}:
2460 Fortran 77 and later
2465 @item @emph{Syntax}:
2466 @code{RESULT = CHAR(I [, KIND])}
2468 @item @emph{Arguments}:
2469 @multitable @columnfractions .15 .70
2470 @item @var{I} @tab The type shall be @code{INTEGER}.
2471 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
2472 expression indicating the kind parameter of the result.
2475 @item @emph{Return value}:
2476 The return value is of type @code{CHARACTER(1)}
2478 @item @emph{Example}:
2484 print *, i, c ! returns 'J'
2485 end program test_char
2488 @item @emph{Specific names}:
2489 @multitable @columnfractions .20 .20 .20 .25
2490 @item Name @tab Argument @tab Return type @tab Standard
2491 @item @code{CHAR(I)} @tab @code{INTEGER I} @tab @code{CHARACTER(LEN=1)} @tab F77 and later
2495 See @ref{ICHAR} for a discussion of converting between numerical values
2496 and formatted string representations.
2498 @item @emph{See also}:
2499 @ref{ACHAR}, @ref{IACHAR}, @ref{ICHAR}
2506 @section @code{CHDIR} --- Change working directory
2508 @cindex system, working directory
2511 @item @emph{Description}:
2512 Change current working directory to a specified path.
2514 This intrinsic is provided in both subroutine and function forms; however,
2515 only one form can be used in any given program unit.
2517 @item @emph{Standard}:
2521 Subroutine, function
2523 @item @emph{Syntax}:
2524 @multitable @columnfractions .80
2525 @item @code{CALL CHDIR(NAME [, STATUS])}
2526 @item @code{STATUS = CHDIR(NAME)}
2529 @item @emph{Arguments}:
2530 @multitable @columnfractions .15 .70
2531 @item @var{NAME} @tab The type shall be @code{CHARACTER} of default
2532 kind and shall specify a valid path within the file system.
2533 @item @var{STATUS} @tab (Optional) @code{INTEGER} status flag of the default
2534 kind. Returns 0 on success, and a system specific and nonzero error code
2538 @item @emph{Example}:
2541 CHARACTER(len=255) :: path
2543 WRITE(*,*) TRIM(path)
2546 WRITE(*,*) TRIM(path)
2550 @item @emph{See also}:
2557 @section @code{CHMOD} --- Change access permissions of files
2559 @cindex file system, change access mode
2562 @item @emph{Description}:
2563 @code{CHMOD} changes the permissions of a file. This function invokes
2564 @code{/bin/chmod} and might therefore not work on all platforms.
2566 This intrinsic is provided in both subroutine and function forms; however,
2567 only one form can be used in any given program unit.
2569 @item @emph{Standard}:
2573 Subroutine, function
2575 @item @emph{Syntax}:
2576 @multitable @columnfractions .80
2577 @item @code{CALL CHMOD(NAME, MODE[, STATUS])}
2578 @item @code{STATUS = CHMOD(NAME, MODE)}
2581 @item @emph{Arguments}:
2582 @multitable @columnfractions .15 .70
2584 @item @var{NAME} @tab Scalar @code{CHARACTER} of default kind with the
2585 file name. Trailing blanks are ignored unless the character
2586 @code{achar(0)} is present, then all characters up to and excluding
2587 @code{achar(0)} are used as the file name.
2589 @item @var{MODE} @tab Scalar @code{CHARACTER} of default kind giving the
2590 file permission. @var{MODE} uses the same syntax as the @var{MODE}
2591 argument of @code{/bin/chmod}.
2593 @item @var{STATUS} @tab (optional) scalar @code{INTEGER}, which is
2594 @code{0} on success and nonzero otherwise.
2597 @item @emph{Return value}:
2598 In either syntax, @var{STATUS} is set to @code{0} on success and nonzero
2601 @item @emph{Example}:
2602 @code{CHMOD} as subroutine
2607 call chmod('test.dat','u+x',status)
2608 print *, 'Status: ', status
2609 end program chmod_test
2611 @code{CHMOD} as function:
2616 status = chmod('test.dat','u+x')
2617 print *, 'Status: ', status
2618 end program chmod_test
2626 @section @code{CMPLX} --- Complex conversion function
2628 @cindex complex numbers, conversion to
2629 @cindex conversion, to complex
2632 @item @emph{Description}:
2633 @code{CMPLX(X [, Y [, KIND]])} returns a complex number where @var{X} is converted to
2634 the real component. If @var{Y} is present it is converted to the imaginary
2635 component. If @var{Y} is not present then the imaginary component is set to
2636 0.0. If @var{X} is complex then @var{Y} must not be present.
2638 @item @emph{Standard}:
2639 Fortran 77 and later
2644 @item @emph{Syntax}:
2645 @code{RESULT = CMPLX(X [, Y [, KIND]])}
2647 @item @emph{Arguments}:
2648 @multitable @columnfractions .15 .70
2649 @item @var{X} @tab The type may be @code{INTEGER}, @code{REAL},
2651 @item @var{Y} @tab (Optional; only allowed if @var{X} is not
2652 @code{COMPLEX}.) May be @code{INTEGER} or @code{REAL}.
2653 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
2654 expression indicating the kind parameter of the result.
2657 @item @emph{Return value}:
2658 The return value is of @code{COMPLEX} type, with a kind equal to
2659 @var{KIND} if it is specified. If @var{KIND} is not specified, the
2660 result is of the default @code{COMPLEX} kind, regardless of the kinds of
2661 @var{X} and @var{Y}.
2663 @item @emph{Example}:
2670 print *, z, cmplx(x)
2671 end program test_cmplx
2674 @item @emph{See also}:
2680 @node COMMAND_ARGUMENT_COUNT
2681 @section @code{COMMAND_ARGUMENT_COUNT} --- Get number of command line arguments
2682 @fnindex COMMAND_ARGUMENT_COUNT
2683 @cindex command-line arguments
2684 @cindex command-line arguments, number of
2685 @cindex arguments, to program
2688 @item @emph{Description}:
2689 @code{COMMAND_ARGUMENT_COUNT()} returns the number of arguments passed on the
2690 command line when the containing program was invoked.
2692 @item @emph{Standard}:
2693 Fortran 2003 and later
2698 @item @emph{Syntax}:
2699 @code{RESULT = COMMAND_ARGUMENT_COUNT()}
2701 @item @emph{Arguments}:
2702 @multitable @columnfractions .15 .70
2706 @item @emph{Return value}:
2707 The return value is an @code{INTEGER} of default kind.
2709 @item @emph{Example}:
2711 program test_command_argument_count
2713 count = command_argument_count()
2715 end program test_command_argument_count
2718 @item @emph{See also}:
2719 @ref{GET_COMMAND}, @ref{GET_COMMAND_ARGUMENT}
2724 @node COMPILER_OPTIONS
2725 @section @code{COMPILER_OPTIONS} --- Options passed to the compiler
2726 @fnindex COMPILER_OPTIONS
2727 @cindex flags inquiry function
2728 @cindex options inquiry function
2729 @cindex compiler flags inquiry function
2732 @item @emph{Description}:
2733 @code{COMPILER_OPTIONS()} returns a string with the options used for
2736 @item @emph{Standard}:
2740 Inquiry function of the module @code{ISO_FORTRAN_ENV}
2742 @item @emph{Syntax}:
2743 @code{STR = COMPILER_OPTIONS()}
2745 @item @emph{Arguments}:
2748 @item @emph{Return value}:
2749 The return value is a default-kind string with system-dependent length.
2750 It contains the compiler flags used to compile the file, which called
2751 the @code{COMPILER_OPTIONS} intrinsic.
2753 @item @emph{Example}:
2756 print '(4a)', 'This file was compiled by ', &
2757 compiler_version(), ' using the the options ', &
2762 @item @emph{See also}:
2763 @ref{COMPILER_VERSION}, @ref{ISO_FORTRAN_ENV}
2768 @node COMPILER_VERSION
2769 @section @code{COMPILER_VERSION} --- Compiler version string
2770 @fnindex COMPILER_VERSION
2771 @cindex compiler, name and version
2772 @cindex version of the compiler
2775 @item @emph{Description}:
2776 @code{COMPILER_VERSION()} returns a string with the name and the
2777 version of the compiler.
2779 @item @emph{Standard}:
2783 Inquiry function of the module @code{ISO_FORTRAN_ENV}
2785 @item @emph{Syntax}:
2786 @code{STR = COMPILER_VERSION()}
2788 @item @emph{Arguments}:
2791 @item @emph{Return value}:
2792 The return value is a default-kind string with system-dependent length.
2793 It contains the name of the compiler and its version number.
2795 @item @emph{Example}:
2798 print '(4a)', 'This file was compiled by ', &
2799 compiler_version(), ' using the the options ', &
2804 @item @emph{See also}:
2805 @ref{COMPILER_OPTIONS}, @ref{ISO_FORTRAN_ENV}
2811 @section @code{COMPLEX} --- Complex conversion function
2813 @cindex complex numbers, conversion to
2814 @cindex conversion, to complex
2817 @item @emph{Description}:
2818 @code{COMPLEX(X, Y)} returns a complex number where @var{X} is converted
2819 to the real component and @var{Y} is converted to the imaginary
2822 @item @emph{Standard}:
2828 @item @emph{Syntax}:
2829 @code{RESULT = COMPLEX(X, Y)}
2831 @item @emph{Arguments}:
2832 @multitable @columnfractions .15 .70
2833 @item @var{X} @tab The type may be @code{INTEGER} or @code{REAL}.
2834 @item @var{Y} @tab The type may be @code{INTEGER} or @code{REAL}.
2837 @item @emph{Return value}:
2838 If @var{X} and @var{Y} are both of @code{INTEGER} type, then the return
2839 value is of default @code{COMPLEX} type.
2841 If @var{X} and @var{Y} are of @code{REAL} type, or one is of @code{REAL}
2842 type and one is of @code{INTEGER} type, then the return value is of
2843 @code{COMPLEX} type with a kind equal to that of the @code{REAL}
2844 argument with the highest precision.
2846 @item @emph{Example}:
2848 program test_complex
2851 print *, complex(i, x)
2852 end program test_complex
2855 @item @emph{See also}:
2862 @section @code{CONJG} --- Complex conjugate function
2865 @cindex complex conjugate
2868 @item @emph{Description}:
2869 @code{CONJG(Z)} returns the conjugate of @var{Z}. If @var{Z} is @code{(x, y)}
2870 then the result is @code{(x, -y)}
2872 @item @emph{Standard}:
2873 Fortran 77 and later, has overloads that are GNU extensions
2878 @item @emph{Syntax}:
2881 @item @emph{Arguments}:
2882 @multitable @columnfractions .15 .70
2883 @item @var{Z} @tab The type shall be @code{COMPLEX}.
2886 @item @emph{Return value}:
2887 The return value is of type @code{COMPLEX}.
2889 @item @emph{Example}:
2892 complex :: z = (2.0, 3.0)
2893 complex(8) :: dz = (2.71_8, -3.14_8)
2898 end program test_conjg
2901 @item @emph{Specific names}:
2902 @multitable @columnfractions .20 .20 .20 .25
2903 @item Name @tab Argument @tab Return type @tab Standard
2904 @item @code{CONJG(Z)} @tab @code{COMPLEX Z} @tab @code{COMPLEX} @tab GNU extension
2905 @item @code{DCONJG(Z)} @tab @code{COMPLEX(8) Z} @tab @code{COMPLEX(8)} @tab GNU extension
2912 @section @code{COS} --- Cosine function
2918 @cindex trigonometric function, cosine
2922 @item @emph{Description}:
2923 @code{COS(X)} computes the cosine of @var{X}.
2925 @item @emph{Standard}:
2926 Fortran 77 and later, has overloads that are GNU extensions
2931 @item @emph{Syntax}:
2932 @code{RESULT = COS(X)}
2934 @item @emph{Arguments}:
2935 @multitable @columnfractions .15 .70
2936 @item @var{X} @tab The type shall be @code{REAL} or
2940 @item @emph{Return value}:
2941 The return value is of the same type and kind as @var{X}. The real part
2942 of the result is in radians. If @var{X} is of the type @code{REAL},
2943 the return value lies in the range @math{ -1 \leq \cos (x) \leq 1}.
2945 @item @emph{Example}:
2950 end program test_cos
2953 @item @emph{Specific names}:
2954 @multitable @columnfractions .20 .20 .20 .25
2955 @item Name @tab Argument @tab Return type @tab Standard
2956 @item @code{COS(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab Fortran 77 and later
2957 @item @code{DCOS(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab Fortran 77 and later
2958 @item @code{CCOS(X)} @tab @code{COMPLEX(4) X} @tab @code{COMPLEX(4)} @tab Fortran 77 and later
2959 @item @code{ZCOS(X)} @tab @code{COMPLEX(8) X} @tab @code{COMPLEX(8)} @tab GNU extension
2960 @item @code{CDCOS(X)} @tab @code{COMPLEX(8) X} @tab @code{COMPLEX(8)} @tab GNU extension
2963 @item @emph{See also}:
2964 Inverse function: @ref{ACOS}
2971 @section @code{COSH} --- Hyperbolic cosine function
2974 @cindex hyperbolic cosine
2975 @cindex hyperbolic function, cosine
2976 @cindex cosine, hyperbolic
2979 @item @emph{Description}:
2980 @code{COSH(X)} computes the hyperbolic cosine of @var{X}.
2982 @item @emph{Standard}:
2983 Fortran 77 and later, for a complex argument Fortran 2008 or later
2988 @item @emph{Syntax}:
2991 @item @emph{Arguments}:
2992 @multitable @columnfractions .15 .70
2993 @item @var{X} @tab The type shall be @code{REAL} or @code{COMPLEX}.
2996 @item @emph{Return value}:
2997 The return value has same type and kind as @var{X}. If @var{X} is
2998 complex, the imaginary part of the result is in radians. If @var{X}
2999 is @code{REAL}, the return value has a lower bound of one,
3000 @math{\cosh (x) \geq 1}.
3002 @item @emph{Example}:
3005 real(8) :: x = 1.0_8
3007 end program test_cosh
3010 @item @emph{Specific names}:
3011 @multitable @columnfractions .20 .20 .20 .25
3012 @item Name @tab Argument @tab Return type @tab Standard
3013 @item @code{COSH(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab Fortran 77 and later
3014 @item @code{DCOSH(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab Fortran 77 and later
3017 @item @emph{See also}:
3018 Inverse function: @ref{ACOSH}
3025 @section @code{COUNT} --- Count function
3027 @cindex array, conditionally count elements
3028 @cindex array, element counting
3029 @cindex array, number of elements
3032 @item @emph{Description}:
3034 Counts the number of @code{.TRUE.} elements in a logical @var{MASK},
3035 or, if the @var{DIM} argument is supplied, counts the number of
3036 elements along each row of the array in the @var{DIM} direction.
3037 If the array has zero size, or all of the elements of @var{MASK} are
3038 @code{.FALSE.}, then the result is @code{0}.
3040 @item @emph{Standard}:
3041 Fortran 95 and later, with @var{KIND} argument Fortran 2003 and later
3044 Transformational function
3046 @item @emph{Syntax}:
3047 @code{RESULT = COUNT(MASK [, DIM, KIND])}
3049 @item @emph{Arguments}:
3050 @multitable @columnfractions .15 .70
3051 @item @var{MASK} @tab The type shall be @code{LOGICAL}.
3052 @item @var{DIM} @tab (Optional) The type shall be @code{INTEGER}.
3053 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
3054 expression indicating the kind parameter of the result.
3057 @item @emph{Return value}:
3058 The return value is of type @code{INTEGER} and of kind @var{KIND}. If
3059 @var{KIND} is absent, the return value is of default integer kind.
3060 If @var{DIM} is present, the result is an array with a rank one less
3061 than the rank of @var{ARRAY}, and a size corresponding to the shape
3062 of @var{ARRAY} with the @var{DIM} dimension removed.
3064 @item @emph{Example}:
3067 integer, dimension(2,3) :: a, b
3068 logical, dimension(2,3) :: mask
3069 a = reshape( (/ 1, 2, 3, 4, 5, 6 /), (/ 2, 3 /))
3070 b = reshape( (/ 0, 7, 3, 4, 5, 8 /), (/ 2, 3 /))
3071 print '(3i3)', a(1,:)
3072 print '(3i3)', a(2,:)
3074 print '(3i3)', b(1,:)
3075 print '(3i3)', b(2,:)
3078 print '(3l3)', mask(1,:)
3079 print '(3l3)', mask(2,:)
3081 print '(3i3)', count(mask)
3083 print '(3i3)', count(mask, 1)
3085 print '(3i3)', count(mask, 2)
3086 end program test_count
3093 @section @code{CPU_TIME} --- CPU elapsed time in seconds
3095 @cindex time, elapsed
3098 @item @emph{Description}:
3099 Returns a @code{REAL} value representing the elapsed CPU time in
3100 seconds. This is useful for testing segments of code to determine
3103 If a time source is available, time will be reported with microsecond
3104 resolution. If no time source is available, @var{TIME} is set to
3107 Note that @var{TIME} may contain a, system dependent, arbitrary offset
3108 and may not start with @code{0.0}. For @code{CPU_TIME}, the absolute
3109 value is meaningless, only differences between subsequent calls to
3110 this subroutine, as shown in the example below, should be used.
3113 @item @emph{Standard}:
3114 Fortran 95 and later
3119 @item @emph{Syntax}:
3120 @code{CALL CPU_TIME(TIME)}
3122 @item @emph{Arguments}:
3123 @multitable @columnfractions .15 .70
3124 @item @var{TIME} @tab The type shall be @code{REAL} with @code{INTENT(OUT)}.
3127 @item @emph{Return value}:
3130 @item @emph{Example}:
3132 program test_cpu_time
3133 real :: start, finish
3134 call cpu_time(start)
3135 ! put code to test here
3136 call cpu_time(finish)
3137 print '("Time = ",f6.3," seconds.")',finish-start
3138 end program test_cpu_time
3141 @item @emph{See also}:
3142 @ref{SYSTEM_CLOCK}, @ref{DATE_AND_TIME}
3148 @section @code{CSHIFT} --- Circular shift elements of an array
3150 @cindex array, shift circularly
3151 @cindex array, permutation
3152 @cindex array, rotate
3155 @item @emph{Description}:
3156 @code{CSHIFT(ARRAY, SHIFT [, DIM])} performs a circular shift on elements of
3157 @var{ARRAY} along the dimension of @var{DIM}. If @var{DIM} is omitted it is
3158 taken to be @code{1}. @var{DIM} is a scalar of type @code{INTEGER} in the
3159 range of @math{1 \leq DIM \leq n)} where @math{n} is the rank of @var{ARRAY}.
3160 If the rank of @var{ARRAY} is one, then all elements of @var{ARRAY} are shifted
3161 by @var{SHIFT} places. If rank is greater than one, then all complete rank one
3162 sections of @var{ARRAY} along the given dimension are shifted. Elements
3163 shifted out one end of each rank one section are shifted back in the other end.
3165 @item @emph{Standard}:
3166 Fortran 95 and later
3169 Transformational function
3171 @item @emph{Syntax}:
3172 @code{RESULT = CSHIFT(ARRAY, SHIFT [, DIM])}
3174 @item @emph{Arguments}:
3175 @multitable @columnfractions .15 .70
3176 @item @var{ARRAY} @tab Shall be an array of any type.
3177 @item @var{SHIFT} @tab The type shall be @code{INTEGER}.
3178 @item @var{DIM} @tab The type shall be @code{INTEGER}.
3181 @item @emph{Return value}:
3182 Returns an array of same type and rank as the @var{ARRAY} argument.
3184 @item @emph{Example}:
3187 integer, dimension(3,3) :: a
3188 a = reshape( (/ 1, 2, 3, 4, 5, 6, 7, 8, 9 /), (/ 3, 3 /))
3189 print '(3i3)', a(1,:)
3190 print '(3i3)', a(2,:)
3191 print '(3i3)', a(3,:)
3192 a = cshift(a, SHIFT=(/1, 2, -1/), DIM=2)
3194 print '(3i3)', a(1,:)
3195 print '(3i3)', a(2,:)
3196 print '(3i3)', a(3,:)
3197 end program test_cshift
3204 @section @code{CTIME} --- Convert a time into a string
3206 @cindex time, conversion to string
3207 @cindex conversion, to string
3210 @item @emph{Description}:
3211 @code{CTIME} converts a system time value, such as returned by
3212 @code{TIME8()}, to a string of the form @samp{Sat Aug 19 18:13:14 1995}.
3214 This intrinsic is provided in both subroutine and function forms; however,
3215 only one form can be used in any given program unit.
3217 @item @emph{Standard}:
3221 Subroutine, function
3223 @item @emph{Syntax}:
3224 @multitable @columnfractions .80
3225 @item @code{CALL CTIME(TIME, RESULT)}.
3226 @item @code{RESULT = CTIME(TIME)}, (not recommended).
3229 @item @emph{Arguments}:
3230 @multitable @columnfractions .15 .70
3231 @item @var{TIME} @tab The type shall be of type @code{INTEGER(KIND=8)}.
3232 @item @var{RESULT} @tab The type shall be of type @code{CHARACTER} and
3236 @item @emph{Return value}:
3237 The converted date and time as a string.
3239 @item @emph{Example}:
3243 character(len=30) :: date
3246 ! Do something, main part of the program
3249 print *, 'Program was started on ', date
3250 end program test_ctime
3253 @item @emph{See Also}:
3254 @ref{GMTIME}, @ref{LTIME}, @ref{TIME}, @ref{TIME8}
3260 @section @code{DATE_AND_TIME} --- Date and time subroutine
3261 @fnindex DATE_AND_TIME
3262 @cindex date, current
3263 @cindex current date
3264 @cindex time, current
3265 @cindex current time
3268 @item @emph{Description}:
3269 @code{DATE_AND_TIME(DATE, TIME, ZONE, VALUES)} gets the corresponding date and
3270 time information from the real-time system clock. @var{DATE} is
3271 @code{INTENT(OUT)} and has form ccyymmdd. @var{TIME} is @code{INTENT(OUT)} and
3272 has form hhmmss.sss. @var{ZONE} is @code{INTENT(OUT)} and has form (+-)hhmm,
3273 representing the difference with respect to Coordinated Universal Time (UTC).
3274 Unavailable time and date parameters return blanks.
3276 @var{VALUES} is @code{INTENT(OUT)} and provides the following:
3278 @multitable @columnfractions .15 .30 .40
3279 @item @tab @code{VALUE(1)}: @tab The year
3280 @item @tab @code{VALUE(2)}: @tab The month
3281 @item @tab @code{VALUE(3)}: @tab The day of the month
3282 @item @tab @code{VALUE(4)}: @tab Time difference with UTC in minutes
3283 @item @tab @code{VALUE(5)}: @tab The hour of the day
3284 @item @tab @code{VALUE(6)}: @tab The minutes of the hour
3285 @item @tab @code{VALUE(7)}: @tab The seconds of the minute
3286 @item @tab @code{VALUE(8)}: @tab The milliseconds of the second
3289 @item @emph{Standard}:
3290 Fortran 95 and later
3295 @item @emph{Syntax}:
3296 @code{CALL DATE_AND_TIME([DATE, TIME, ZONE, VALUES])}
3298 @item @emph{Arguments}:
3299 @multitable @columnfractions .15 .70
3300 @item @var{DATE} @tab (Optional) The type shall be @code{CHARACTER(LEN=8)}
3301 or larger, and of default kind.
3302 @item @var{TIME} @tab (Optional) The type shall be @code{CHARACTER(LEN=10)}
3303 or larger, and of default kind.
3304 @item @var{ZONE} @tab (Optional) The type shall be @code{CHARACTER(LEN=5)}
3305 or larger, and of default kind.
3306 @item @var{VALUES}@tab (Optional) The type shall be @code{INTEGER(8)}.
3309 @item @emph{Return value}:
3312 @item @emph{Example}:
3314 program test_time_and_date
3315 character(8) :: date
3316 character(10) :: time
3317 character(5) :: zone
3318 integer,dimension(8) :: values
3319 ! using keyword arguments
3320 call date_and_time(date,time,zone,values)
3321 call date_and_time(DATE=date,ZONE=zone)
3322 call date_and_time(TIME=time)
3323 call date_and_time(VALUES=values)
3324 print '(a,2x,a,2x,a)', date, time, zone
3325 print '(8i5))', values
3326 end program test_time_and_date
3329 @item @emph{See also}:
3330 @ref{CPU_TIME}, @ref{SYSTEM_CLOCK}
3336 @section @code{DBLE} --- Double conversion function
3338 @cindex conversion, to real
3341 @item @emph{Description}:
3342 @code{DBLE(A)} Converts @var{A} to double precision real type.
3344 @item @emph{Standard}:
3345 Fortran 77 and later
3350 @item @emph{Syntax}:
3351 @code{RESULT = DBLE(A)}
3353 @item @emph{Arguments}:
3354 @multitable @columnfractions .15 .70
3355 @item @var{A} @tab The type shall be @code{INTEGER}, @code{REAL},
3359 @item @emph{Return value}:
3360 The return value is of type double precision real.
3362 @item @emph{Example}:
3367 complex :: z = (2.3,1.14)
3368 print *, dble(x), dble(i), dble(z)
3369 end program test_dble
3372 @item @emph{See also}:
3379 @section @code{DCMPLX} --- Double complex conversion function
3381 @cindex complex numbers, conversion to
3382 @cindex conversion, to complex
3385 @item @emph{Description}:
3386 @code{DCMPLX(X [,Y])} returns a double complex number where @var{X} is
3387 converted to the real component. If @var{Y} is present it is converted to the
3388 imaginary component. If @var{Y} is not present then the imaginary component is
3389 set to 0.0. If @var{X} is complex then @var{Y} must not be present.
3391 @item @emph{Standard}:
3397 @item @emph{Syntax}:
3398 @code{RESULT = DCMPLX(X [, Y])}
3400 @item @emph{Arguments}:
3401 @multitable @columnfractions .15 .70
3402 @item @var{X} @tab The type may be @code{INTEGER}, @code{REAL},
3404 @item @var{Y} @tab (Optional if @var{X} is not @code{COMPLEX}.) May be
3405 @code{INTEGER} or @code{REAL}.
3408 @item @emph{Return value}:
3409 The return value is of type @code{COMPLEX(8)}
3411 @item @emph{Example}:
3421 print *, dcmplx(x,i)
3422 end program test_dcmplx
3428 @section @code{DIGITS} --- Significant binary digits function
3430 @cindex model representation, significant digits
3433 @item @emph{Description}:
3434 @code{DIGITS(X)} returns the number of significant binary digits of the internal
3435 model representation of @var{X}. For example, on a system using a 32-bit
3436 floating point representation, a default real number would likely return 24.
3438 @item @emph{Standard}:
3439 Fortran 95 and later
3444 @item @emph{Syntax}:
3445 @code{RESULT = DIGITS(X)}
3447 @item @emph{Arguments}:
3448 @multitable @columnfractions .15 .70
3449 @item @var{X} @tab The type may be @code{INTEGER} or @code{REAL}.
3452 @item @emph{Return value}:
3453 The return value is of type @code{INTEGER}.
3455 @item @emph{Example}:
3458 integer :: i = 12345
3464 end program test_digits
3471 @section @code{DIM} --- Positive difference
3475 @cindex positive difference
3478 @item @emph{Description}:
3479 @code{DIM(X,Y)} returns the difference @code{X-Y} if the result is positive;
3480 otherwise returns zero.
3482 @item @emph{Standard}:
3483 Fortran 77 and later
3488 @item @emph{Syntax}:
3489 @code{RESULT = DIM(X, Y)}
3491 @item @emph{Arguments}:
3492 @multitable @columnfractions .15 .70
3493 @item @var{X} @tab The type shall be @code{INTEGER} or @code{REAL}
3494 @item @var{Y} @tab The type shall be the same type and kind as @var{X}.
3497 @item @emph{Return value}:
3498 The return value is of type @code{INTEGER} or @code{REAL}.
3500 @item @emph{Example}:
3506 x = dim(4.345_8, 2.111_8)
3509 end program test_dim
3512 @item @emph{Specific names}:
3513 @multitable @columnfractions .20 .20 .20 .25
3514 @item Name @tab Argument @tab Return type @tab Standard
3515 @item @code{DIM(X,Y)} @tab @code{REAL(4) X, Y} @tab @code{REAL(4)} @tab Fortran 77 and later
3516 @item @code{IDIM(X,Y)} @tab @code{INTEGER(4) X, Y} @tab @code{INTEGER(4)} @tab Fortran 77 and later
3517 @item @code{DDIM(X,Y)} @tab @code{REAL(8) X, Y} @tab @code{REAL(8)} @tab Fortran 77 and later
3524 @section @code{DOT_PRODUCT} --- Dot product function
3525 @fnindex DOT_PRODUCT
3527 @cindex vector product
3528 @cindex product, vector
3531 @item @emph{Description}:
3532 @code{DOT_PRODUCT(VECTOR_A, VECTOR_B)} computes the dot product multiplication
3533 of two vectors @var{VECTOR_A} and @var{VECTOR_B}. The two vectors may be
3534 either numeric or logical and must be arrays of rank one and of equal size. If
3535 the vectors are @code{INTEGER} or @code{REAL}, the result is
3536 @code{SUM(VECTOR_A*VECTOR_B)}. If the vectors are @code{COMPLEX}, the result
3537 is @code{SUM(CONJG(VECTOR_A)*VECTOR_B)}. If the vectors are @code{LOGICAL},
3538 the result is @code{ANY(VECTOR_A .AND. VECTOR_B)}.
3540 @item @emph{Standard}:
3541 Fortran 95 and later
3544 Transformational function
3546 @item @emph{Syntax}:
3547 @code{RESULT = DOT_PRODUCT(VECTOR_A, VECTOR_B)}
3549 @item @emph{Arguments}:
3550 @multitable @columnfractions .15 .70
3551 @item @var{VECTOR_A} @tab The type shall be numeric or @code{LOGICAL}, rank 1.
3552 @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.
3555 @item @emph{Return value}:
3556 If the arguments are numeric, the return value is a scalar of numeric type,
3557 @code{INTEGER}, @code{REAL}, or @code{COMPLEX}. If the arguments are
3558 @code{LOGICAL}, the return value is @code{.TRUE.} or @code{.FALSE.}.
3560 @item @emph{Example}:
3562 program test_dot_prod
3563 integer, dimension(3) :: a, b
3570 print *, dot_product(a,b)
3571 end program test_dot_prod
3578 @section @code{DPROD} --- Double product function
3580 @cindex product, double-precision
3583 @item @emph{Description}:
3584 @code{DPROD(X,Y)} returns the product @code{X*Y}.
3586 @item @emph{Standard}:
3587 Fortran 77 and later
3592 @item @emph{Syntax}:
3593 @code{RESULT = DPROD(X, Y)}
3595 @item @emph{Arguments}:
3596 @multitable @columnfractions .15 .70
3597 @item @var{X} @tab The type shall be @code{REAL}.
3598 @item @var{Y} @tab The type shall be @code{REAL}.
3601 @item @emph{Return value}:
3602 The return value is of type @code{REAL(8)}.
3604 @item @emph{Example}:
3612 end program test_dprod
3615 @item @emph{Specific names}:
3616 @multitable @columnfractions .20 .20 .20 .25
3617 @item Name @tab Argument @tab Return type @tab Standard
3618 @item @code{DPROD(X,Y)} @tab @code{REAL(4) X, Y} @tab @code{REAL(4)} @tab Fortran 77 and later
3625 @section @code{DREAL} --- Double real part function
3627 @cindex complex numbers, real part
3630 @item @emph{Description}:
3631 @code{DREAL(Z)} returns the real part of complex variable @var{Z}.
3633 @item @emph{Standard}:
3639 @item @emph{Syntax}:
3640 @code{RESULT = DREAL(A)}
3642 @item @emph{Arguments}:
3643 @multitable @columnfractions .15 .70
3644 @item @var{A} @tab The type shall be @code{COMPLEX(8)}.
3647 @item @emph{Return value}:
3648 The return value is of type @code{REAL(8)}.
3650 @item @emph{Example}:
3653 complex(8) :: z = (1.3_8,7.2_8)
3655 end program test_dreal
3658 @item @emph{See also}:
3666 @section @code{DSHIFTL} --- Combined left shift
3668 @cindex left shift, combined
3672 @item @emph{Description}:
3673 @code{DSHIFTL(I, J, SHIFT)} combines bits of @var{I} and @var{J}. The
3674 rightmost @var{SHIFT} bits of the result are the leftmost @var{SHIFT}
3675 bits of @var{J}, and the remaining bits are the rightmost bits of
3678 @item @emph{Standard}:
3679 Fortran 2008 and later
3684 @item @emph{Syntax}:
3685 @code{RESULT = DSHIFTL(I, J, SHIFT)}
3687 @item @emph{Arguments}:
3688 @multitable @columnfractions .15 .70
3689 @item @var{I} @tab Shall be of type @code{INTEGER}.
3690 @item @var{J} @tab Shall be of type @code{INTEGER}, and of the same kind
3692 @item @var{SHIFT} @tab Shall be of type @code{INTEGER}.
3695 @item @emph{Return value}:
3696 The return value has same type and kind as @var{I}.
3698 @item @emph{See also}:
3706 @section @code{DSHIFTR} --- Combined right shift
3708 @cindex right shift, combined
3709 @cindex shift, right
3712 @item @emph{Description}:
3713 @code{DSHIFTR(I, J, SHIFT)} combines bits of @var{I} and @var{J}. The
3714 leftmost @var{SHIFT} bits of the result are the rightmost @var{SHIFT}
3715 bits of @var{I}, and the remaining bits are the leftmost bits of
3718 @item @emph{Standard}:
3719 Fortran 2008 and later
3724 @item @emph{Syntax}:
3725 @code{RESULT = DSHIFTR(I, J, SHIFT)}
3727 @item @emph{Arguments}:
3728 @multitable @columnfractions .15 .70
3729 @item @var{I} @tab Shall be of type @code{INTEGER}.
3730 @item @var{J} @tab Shall be of type @code{INTEGER}, and of the same kind
3732 @item @var{SHIFT} @tab Shall be of type @code{INTEGER}.
3735 @item @emph{Return value}:
3736 The return value has same type and kind as @var{I}.
3738 @item @emph{See also}:
3746 @section @code{DTIME} --- Execution time subroutine (or function)
3748 @cindex time, elapsed
3749 @cindex elapsed time
3752 @item @emph{Description}:
3753 @code{DTIME(VALUES, TIME)} initially returns the number of seconds of runtime
3754 since the start of the process's execution in @var{TIME}. @var{VALUES}
3755 returns the user and system components of this time in @code{VALUES(1)} and
3756 @code{VALUES(2)} respectively. @var{TIME} is equal to @code{VALUES(1) +
3759 Subsequent invocations of @code{DTIME} return values accumulated since the
3760 previous invocation.
3762 On some systems, the underlying timings are represented using types with
3763 sufficiently small limits that overflows (wrap around) are possible, such as
3764 32-bit types. Therefore, the values returned by this intrinsic might be, or
3765 become, negative, or numerically less than previous values, during a single
3766 run of the compiled program.
3768 Please note, that this implementation is thread safe if used within OpenMP
3769 directives, i.e., its state will be consistent while called from multiple
3770 threads. However, if @code{DTIME} is called from multiple threads, the result
3771 is still the time since the last invocation. This may not give the intended
3772 results. If possible, use @code{CPU_TIME} instead.
3774 This intrinsic is provided in both subroutine and function forms; however,
3775 only one form can be used in any given program unit.
3777 @var{VALUES} and @var{TIME} are @code{INTENT(OUT)} and provide the following:
3779 @multitable @columnfractions .15 .30 .40
3780 @item @tab @code{VALUES(1)}: @tab User time in seconds.
3781 @item @tab @code{VALUES(2)}: @tab System time in seconds.
3782 @item @tab @code{TIME}: @tab Run time since start in seconds.
3785 @item @emph{Standard}:
3789 Subroutine, function
3791 @item @emph{Syntax}:
3792 @multitable @columnfractions .80
3793 @item @code{CALL DTIME(VALUES, TIME)}.
3794 @item @code{TIME = DTIME(VALUES)}, (not recommended).
3797 @item @emph{Arguments}:
3798 @multitable @columnfractions .15 .70
3799 @item @var{VALUES}@tab The type shall be @code{REAL(4), DIMENSION(2)}.
3800 @item @var{TIME}@tab The type shall be @code{REAL(4)}.
3803 @item @emph{Return value}:
3804 Elapsed time in seconds since the last invocation or since the start of program
3805 execution if not called before.
3807 @item @emph{Example}:
3811 real, dimension(2) :: tarray
3813 call dtime(tarray, result)
3817 do i=1,100000000 ! Just a delay
3820 call dtime(tarray, result)
3824 end program test_dtime
3827 @item @emph{See also}:
3835 @section @code{EOSHIFT} --- End-off shift elements of an array
3837 @cindex array, shift
3840 @item @emph{Description}:
3841 @code{EOSHIFT(ARRAY, SHIFT[, BOUNDARY, DIM])} performs an end-off shift on
3842 elements of @var{ARRAY} along the dimension of @var{DIM}. If @var{DIM} is
3843 omitted it is taken to be @code{1}. @var{DIM} is a scalar of type
3844 @code{INTEGER} in the range of @math{1 \leq DIM \leq n)} where @math{n} is the
3845 rank of @var{ARRAY}. If the rank of @var{ARRAY} is one, then all elements of
3846 @var{ARRAY} are shifted by @var{SHIFT} places. If rank is greater than one,
3847 then all complete rank one sections of @var{ARRAY} along the given dimension are
3848 shifted. Elements shifted out one end of each rank one section are dropped. If
3849 @var{BOUNDARY} is present then the corresponding value of from @var{BOUNDARY}
3850 is copied back in the other end. If @var{BOUNDARY} is not present then the
3851 following are copied in depending on the type of @var{ARRAY}.
3853 @multitable @columnfractions .15 .80
3854 @item @emph{Array Type} @tab @emph{Boundary Value}
3855 @item Numeric @tab 0 of the type and kind of @var{ARRAY}.
3856 @item Logical @tab @code{.FALSE.}.
3857 @item Character(@var{len}) @tab @var{len} blanks.
3860 @item @emph{Standard}:
3861 Fortran 95 and later
3864 Transformational function
3866 @item @emph{Syntax}:
3867 @code{RESULT = EOSHIFT(ARRAY, SHIFT [, BOUNDARY, DIM])}
3869 @item @emph{Arguments}:
3870 @multitable @columnfractions .15 .70
3871 @item @var{ARRAY} @tab May be any type, not scalar.
3872 @item @var{SHIFT} @tab The type shall be @code{INTEGER}.
3873 @item @var{BOUNDARY} @tab Same type as @var{ARRAY}.
3874 @item @var{DIM} @tab The type shall be @code{INTEGER}.
3877 @item @emph{Return value}:
3878 Returns an array of same type and rank as the @var{ARRAY} argument.
3880 @item @emph{Example}:
3882 program test_eoshift
3883 integer, dimension(3,3) :: a
3884 a = reshape( (/ 1, 2, 3, 4, 5, 6, 7, 8, 9 /), (/ 3, 3 /))
3885 print '(3i3)', a(1,:)
3886 print '(3i3)', a(2,:)
3887 print '(3i3)', a(3,:)
3888 a = EOSHIFT(a, SHIFT=(/1, 2, 1/), BOUNDARY=-5, DIM=2)
3890 print '(3i3)', a(1,:)
3891 print '(3i3)', a(2,:)
3892 print '(3i3)', a(3,:)
3893 end program test_eoshift
3900 @section @code{EPSILON} --- Epsilon function
3902 @cindex model representation, epsilon
3905 @item @emph{Description}:
3906 @code{EPSILON(X)} returns the smallest number @var{E} of the same kind
3907 as @var{X} such that @math{1 + E > 1}.
3909 @item @emph{Standard}:
3910 Fortran 95 and later
3915 @item @emph{Syntax}:
3916 @code{RESULT = EPSILON(X)}
3918 @item @emph{Arguments}:
3919 @multitable @columnfractions .15 .70
3920 @item @var{X} @tab The type shall be @code{REAL}.
3923 @item @emph{Return value}:
3924 The return value is of same type as the argument.
3926 @item @emph{Example}:
3928 program test_epsilon
3933 end program test_epsilon
3940 @section @code{ERF} --- Error function
3942 @cindex error function
3945 @item @emph{Description}:
3946 @code{ERF(X)} computes the error function of @var{X}.
3948 @item @emph{Standard}:
3949 Fortran 2008 and later
3954 @item @emph{Syntax}:
3955 @code{RESULT = ERF(X)}
3957 @item @emph{Arguments}:
3958 @multitable @columnfractions .15 .70
3959 @item @var{X} @tab The type shall be @code{REAL}.
3962 @item @emph{Return value}:
3963 The return value is of type @code{REAL}, of the same kind as
3964 @var{X} and lies in the range @math{-1 \leq erf (x) \leq 1 }.
3966 @item @emph{Example}:
3969 real(8) :: x = 0.17_8
3971 end program test_erf
3974 @item @emph{Specific names}:
3975 @multitable @columnfractions .20 .20 .20 .25
3976 @item Name @tab Argument @tab Return type @tab Standard
3977 @item @code{DERF(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU extension
3984 @section @code{ERFC} --- Error function
3986 @cindex error function, complementary
3989 @item @emph{Description}:
3990 @code{ERFC(X)} computes the complementary error function of @var{X}.
3992 @item @emph{Standard}:
3993 Fortran 2008 and later
3998 @item @emph{Syntax}:
3999 @code{RESULT = ERFC(X)}
4001 @item @emph{Arguments}:
4002 @multitable @columnfractions .15 .70
4003 @item @var{X} @tab The type shall be @code{REAL}.
4006 @item @emph{Return value}:
4007 The return value is of type @code{REAL} and of the same kind as @var{X}.
4008 It lies in the range @math{ 0 \leq erfc (x) \leq 2 }.
4010 @item @emph{Example}:
4013 real(8) :: x = 0.17_8
4015 end program test_erfc
4018 @item @emph{Specific names}:
4019 @multitable @columnfractions .20 .20 .20 .25
4020 @item Name @tab Argument @tab Return type @tab Standard
4021 @item @code{DERFC(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU extension
4028 @section @code{ERFC_SCALED} --- Error function
4029 @fnindex ERFC_SCALED
4030 @cindex error function, complementary, exponentially-scaled
4033 @item @emph{Description}:
4034 @code{ERFC_SCALED(X)} computes the exponentially-scaled complementary
4035 error function of @var{X}.
4037 @item @emph{Standard}:
4038 Fortran 2008 and later
4043 @item @emph{Syntax}:
4044 @code{RESULT = ERFC_SCALED(X)}
4046 @item @emph{Arguments}:
4047 @multitable @columnfractions .15 .70
4048 @item @var{X} @tab The type shall be @code{REAL}.
4051 @item @emph{Return value}:
4052 The return value is of type @code{REAL} and of the same kind as @var{X}.
4054 @item @emph{Example}:
4056 program test_erfc_scaled
4057 real(8) :: x = 0.17_8
4059 end program test_erfc_scaled
4066 @section @code{ETIME} --- Execution time subroutine (or function)
4068 @cindex time, elapsed
4071 @item @emph{Description}:
4072 @code{ETIME(VALUES, TIME)} returns the number of seconds of runtime
4073 since the start of the process's execution in @var{TIME}. @var{VALUES}
4074 returns the user and system components of this time in @code{VALUES(1)} and
4075 @code{VALUES(2)} respectively. @var{TIME} is equal to @code{VALUES(1) + VALUES(2)}.
4077 On some systems, the underlying timings are represented using types with
4078 sufficiently small limits that overflows (wrap around) are possible, such as
4079 32-bit types. Therefore, the values returned by this intrinsic might be, or
4080 become, negative, or numerically less than previous values, during a single
4081 run of the compiled program.
4083 This intrinsic is provided in both subroutine and function forms; however,
4084 only one form can be used in any given program unit.
4086 @var{VALUES} and @var{TIME} are @code{INTENT(OUT)} and provide the following:
4088 @multitable @columnfractions .15 .30 .60
4089 @item @tab @code{VALUES(1)}: @tab User time in seconds.
4090 @item @tab @code{VALUES(2)}: @tab System time in seconds.
4091 @item @tab @code{TIME}: @tab Run time since start in seconds.
4094 @item @emph{Standard}:
4098 Subroutine, function
4100 @item @emph{Syntax}:
4101 @multitable @columnfractions .80
4102 @item @code{CALL ETIME(VALUES, TIME)}.
4103 @item @code{TIME = ETIME(VALUES)}, (not recommended).
4106 @item @emph{Arguments}:
4107 @multitable @columnfractions .15 .70
4108 @item @var{VALUES}@tab The type shall be @code{REAL(4), DIMENSION(2)}.
4109 @item @var{TIME}@tab The type shall be @code{REAL(4)}.
4112 @item @emph{Return value}:
4113 Elapsed time in seconds since the start of program execution.
4115 @item @emph{Example}:
4119 real, dimension(2) :: tarray
4121 call ETIME(tarray, result)
4125 do i=1,100000000 ! Just a delay
4128 call ETIME(tarray, result)
4132 end program test_etime
4135 @item @emph{See also}:
4142 @node EXECUTE_COMMAND_LINE
4143 @section @code{EXECUTE_COMMAND_LINE} --- Execute a shell command
4144 @fnindex EXECUTE_COMMAND_LINE
4145 @cindex system, system call
4146 @cindex command line
4149 @item @emph{Description}:
4150 @code{EXECUTE_COMMAND_LINE} runs a shell command, synchronously or
4153 The @code{COMMAND} argument is passed to the shell and executed, using
4154 the C library's @code{system()} call. (The shell is @code{sh} on Unix
4155 systems, and @code{cmd.exe} on Windows.) If @code{WAIT} is present and
4156 has the value false, the execution of the command is asynchronous if the
4157 system supports it; otherwise, the command is executed synchronously.
4159 The three last arguments allow the user to get status information. After
4160 synchronous execution, @code{EXITSTAT} contains the integer exit code of
4161 the command, as returned by @code{system}. @code{CMDSTAT} is set to zero
4162 if the command line was executed (whatever its exit status was).
4163 @code{CMDMSG} is assigned an error message if an error has occurred.
4166 @item @emph{Standard}:
4167 Fortran 2008 and later
4172 @item @emph{Syntax}:
4173 @code{CALL EXECUTE_COMMAND_LINE(COMMAND [, WAIT, EXITSTAT, CMDSTAT, CMDMSG ])}
4175 @item @emph{Arguments}:
4176 @multitable @columnfractions .15 .70
4177 @item @var{COMMAND} @tab Shall be a default @code{CHARACTER} scalar.
4178 @item @var{WAIT} @tab (Optional) Shall be a default @code{LOGICAL} scalar.
4179 @item @var{EXITSTAT} @tab (Optional) Shall be an @code{INTEGER} of the
4181 @item @var{CMDSTAT} @tab (Optional) Shall be an @code{INTEGER} of the
4183 @item @var{CMDMSG} @tab (Optional) Shall be an @code{CHARACTER} scalar of the
4187 @item @emph{Example}:
4192 call execute_command_line ("external_prog.exe", exitstat=i)
4193 print *, "Exit status of external_prog.exe was ", i
4195 call execute_command_line ("reindex_files.exe", wait=.false.)
4196 print *, "Now reindexing files in the background"
4198 end program test_exec
4204 Because this intrinsic is implemented in terms of the @code{system()}
4205 function call, its behavior with respect to signaling is processor
4206 dependent. In particular, on POSIX-compliant systems, the SIGINT and
4207 SIGQUIT signals will be ignored, and the SIGCHLD will be blocked. As
4208 such, if the parent process is terminated, the child process might not be
4209 terminated alongside.
4212 @item @emph{See also}:
4219 @section @code{EXIT} --- Exit the program with status.
4221 @cindex program termination
4222 @cindex terminate program
4225 @item @emph{Description}:
4226 @code{EXIT} causes immediate termination of the program with status. If status
4227 is omitted it returns the canonical @emph{success} for the system. All Fortran
4228 I/O units are closed.
4230 @item @emph{Standard}:
4236 @item @emph{Syntax}:
4237 @code{CALL EXIT([STATUS])}
4239 @item @emph{Arguments}:
4240 @multitable @columnfractions .15 .70
4241 @item @var{STATUS} @tab Shall be an @code{INTEGER} of the default kind.
4244 @item @emph{Return value}:
4245 @code{STATUS} is passed to the parent process on exit.
4247 @item @emph{Example}:
4250 integer :: STATUS = 0
4251 print *, 'This program is going to exit.'
4253 end program test_exit
4256 @item @emph{See also}:
4257 @ref{ABORT}, @ref{KILL}
4263 @section @code{EXP} --- Exponential function
4269 @cindex exponential function
4270 @cindex logarithmic function, inverse
4273 @item @emph{Description}:
4274 @code{EXP(X)} computes the base @math{e} exponential of @var{X}.
4276 @item @emph{Standard}:
4277 Fortran 77 and later, has overloads that are GNU extensions
4282 @item @emph{Syntax}:
4283 @code{RESULT = EXP(X)}
4285 @item @emph{Arguments}:
4286 @multitable @columnfractions .15 .70
4287 @item @var{X} @tab The type shall be @code{REAL} or
4291 @item @emph{Return value}:
4292 The return value has same type and kind as @var{X}.
4294 @item @emph{Example}:
4299 end program test_exp
4302 @item @emph{Specific names}:
4303 @multitable @columnfractions .20 .20 .20 .25
4304 @item Name @tab Argument @tab Return type @tab Standard
4305 @item @code{EXP(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab Fortran 77 and later
4306 @item @code{DEXP(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab Fortran 77 and later
4307 @item @code{CEXP(X)} @tab @code{COMPLEX(4) X} @tab @code{COMPLEX(4)} @tab Fortran 77 and later
4308 @item @code{ZEXP(X)} @tab @code{COMPLEX(8) X} @tab @code{COMPLEX(8)} @tab GNU extension
4309 @item @code{CDEXP(X)} @tab @code{COMPLEX(8) X} @tab @code{COMPLEX(8)} @tab GNU extension
4316 @section @code{EXPONENT} --- Exponent function
4318 @cindex real number, exponent
4319 @cindex floating point, exponent
4322 @item @emph{Description}:
4323 @code{EXPONENT(X)} returns the value of the exponent part of @var{X}. If @var{X}
4324 is zero the value returned is zero.
4326 @item @emph{Standard}:
4327 Fortran 95 and later
4332 @item @emph{Syntax}:
4333 @code{RESULT = EXPONENT(X)}
4335 @item @emph{Arguments}:
4336 @multitable @columnfractions .15 .70
4337 @item @var{X} @tab The type shall be @code{REAL}.
4340 @item @emph{Return value}:
4341 The return value is of type default @code{INTEGER}.
4343 @item @emph{Example}:
4345 program test_exponent
4350 print *, exponent(0.0)
4351 end program test_exponent
4357 @node EXTENDS_TYPE_OF
4358 @section @code{EXTENDS_TYPE_OF} --- Query dynamic type for extension
4359 @fnindex EXTENDS_TYPE_OF
4362 @item @emph{Description}:
4363 Query dynamic type for extension.
4365 @item @emph{Standard}:
4366 Fortran 2003 and later
4371 @item @emph{Syntax}:
4372 @code{RESULT = EXTENDS_TYPE_OF(A, MOLD)}
4374 @item @emph{Arguments}:
4375 @multitable @columnfractions .15 .70
4376 @item @var{A} @tab Shall be an object of extensible declared type or
4377 unlimited polymorphic.
4378 @item @var{MOLD} @tab Shall be an object of extensible declared type or
4379 unlimited polymorphic.
4382 @item @emph{Return value}:
4383 The return value is a scalar of type default logical. It is true if and only if
4384 the dynamic type of A is an extension type of the dynamic type of MOLD.
4387 @item @emph{See also}:
4394 @section @code{FDATE} --- Get the current time as a string
4396 @cindex time, current
4397 @cindex current time
4398 @cindex date, current
4399 @cindex current date
4402 @item @emph{Description}:
4403 @code{FDATE(DATE)} returns the current date (using the same format as
4404 @code{CTIME}) in @var{DATE}. It is equivalent to @code{CALL CTIME(DATE,
4407 This intrinsic is provided in both subroutine and function forms; however,
4408 only one form can be used in any given program unit.
4410 @var{DATE} is an @code{INTENT(OUT)} @code{CHARACTER} variable of the
4413 @item @emph{Standard}:
4417 Subroutine, function
4419 @item @emph{Syntax}:
4420 @multitable @columnfractions .80
4421 @item @code{CALL FDATE(DATE)}.
4422 @item @code{DATE = FDATE()}, (not recommended).
4425 @item @emph{Arguments}:
4426 @multitable @columnfractions .15 .70
4427 @item @var{DATE}@tab The type shall be of type @code{CHARACTER} of the
4431 @item @emph{Return value}:
4432 The current date as a string.
4434 @item @emph{Example}:
4438 character(len=30) :: date
4440 print *, 'Program started on ', date
4441 do i = 1, 100000000 ! Just a delay
4445 print *, 'Program ended on ', date
4446 end program test_fdate
4453 @section @code{FGET} --- Read a single character in stream mode from stdin
4455 @cindex read character, stream mode
4456 @cindex stream mode, read character
4457 @cindex file operation, read character
4460 @item @emph{Description}:
4461 Read a single character in stream mode from stdin by bypassing normal
4462 formatted output. Stream I/O should not be mixed with normal record-oriented
4463 (formatted or unformatted) I/O on the same unit; the results are unpredictable.
4465 This intrinsic is provided in both subroutine and function forms; however,
4466 only one form can be used in any given program unit.
4468 Note that the @code{FGET} intrinsic is provided for backwards compatibility with
4469 @command{g77}. GNU Fortran provides the Fortran 2003 Stream facility.
4470 Programmers should consider the use of new stream IO feature in new code
4471 for future portability. See also @ref{Fortran 2003 status}.
4473 @item @emph{Standard}:
4477 Subroutine, function
4479 @item @emph{Syntax}:
4480 @multitable @columnfractions .80
4481 @item @code{CALL FGET(C [, STATUS])}
4482 @item @code{STATUS = FGET(C)}
4485 @item @emph{Arguments}:
4486 @multitable @columnfractions .15 .70
4487 @item @var{C} @tab The type shall be @code{CHARACTER} and of default
4489 @item @var{STATUS} @tab (Optional) status flag of type @code{INTEGER}.
4490 Returns 0 on success, -1 on end-of-file, and a system specific positive
4491 error code otherwise.
4494 @item @emph{Example}:
4497 INTEGER, PARAMETER :: strlen = 100
4498 INTEGER :: status, i = 1
4499 CHARACTER(len=strlen) :: str = ""
4501 WRITE (*,*) 'Enter text:'
4503 CALL fget(str(i:i), status)
4504 if (status /= 0 .OR. i > strlen) exit
4507 WRITE (*,*) TRIM(str)
4511 @item @emph{See also}:
4512 @ref{FGETC}, @ref{FPUT}, @ref{FPUTC}
4518 @section @code{FGETC} --- Read a single character in stream mode
4520 @cindex read character, stream mode
4521 @cindex stream mode, read character
4522 @cindex file operation, read character
4525 @item @emph{Description}:
4526 Read a single character in stream mode by bypassing normal formatted output.
4527 Stream I/O should not be mixed with normal record-oriented (formatted or
4528 unformatted) I/O on the same unit; the results are unpredictable.
4530 This intrinsic is provided in both subroutine and function forms; however,
4531 only one form can be used in any given program unit.
4533 Note that the @code{FGET} intrinsic is provided for backwards compatibility
4534 with @command{g77}. GNU Fortran provides the Fortran 2003 Stream facility.
4535 Programmers should consider the use of new stream IO feature in new code
4536 for future portability. See also @ref{Fortran 2003 status}.
4538 @item @emph{Standard}:
4542 Subroutine, function
4544 @item @emph{Syntax}:
4545 @multitable @columnfractions .80
4546 @item @code{CALL FGETC(UNIT, C [, STATUS])}
4547 @item @code{STATUS = FGETC(UNIT, C)}
4550 @item @emph{Arguments}:
4551 @multitable @columnfractions .15 .70
4552 @item @var{UNIT} @tab The type shall be @code{INTEGER}.
4553 @item @var{C} @tab The type shall be @code{CHARACTER} and of default
4555 @item @var{STATUS} @tab (Optional) status flag of type @code{INTEGER}.
4556 Returns 0 on success, -1 on end-of-file and a system specific positive
4557 error code otherwise.
4560 @item @emph{Example}:
4563 INTEGER :: fd = 42, status
4566 OPEN(UNIT=fd, FILE="/etc/passwd", ACTION="READ", STATUS = "OLD")
4568 CALL fgetc(fd, c, status)
4569 IF (status /= 0) EXIT
4576 @item @emph{See also}:
4577 @ref{FGET}, @ref{FPUT}, @ref{FPUTC}
4583 @section @code{FLOOR} --- Integer floor function
4586 @cindex rounding, floor
4589 @item @emph{Description}:
4590 @code{FLOOR(A)} returns the greatest integer less than or equal to @var{X}.
4592 @item @emph{Standard}:
4593 Fortran 95 and later
4598 @item @emph{Syntax}:
4599 @code{RESULT = FLOOR(A [, KIND])}
4601 @item @emph{Arguments}:
4602 @multitable @columnfractions .15 .70
4603 @item @var{A} @tab The type shall be @code{REAL}.
4604 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
4605 expression indicating the kind parameter of the result.
4608 @item @emph{Return value}:
4609 The return value is of type @code{INTEGER(KIND)} if @var{KIND} is present
4610 and of default-kind @code{INTEGER} otherwise.
4612 @item @emph{Example}:
4617 print *, floor(x) ! returns 63
4618 print *, floor(y) ! returns -64
4619 end program test_floor
4622 @item @emph{See also}:
4623 @ref{CEILING}, @ref{NINT}
4630 @section @code{FLUSH} --- Flush I/O unit(s)
4632 @cindex file operation, flush
4635 @item @emph{Description}:
4636 Flushes Fortran unit(s) currently open for output. Without the optional
4637 argument, all units are flushed, otherwise just the unit specified.
4639 @item @emph{Standard}:
4645 @item @emph{Syntax}:
4646 @code{CALL FLUSH(UNIT)}
4648 @item @emph{Arguments}:
4649 @multitable @columnfractions .15 .70
4650 @item @var{UNIT} @tab (Optional) The type shall be @code{INTEGER}.
4654 Beginning with the Fortran 2003 standard, there is a @code{FLUSH}
4655 statement that should be preferred over the @code{FLUSH} intrinsic.
4657 The @code{FLUSH} intrinsic and the Fortran 2003 @code{FLUSH} statement
4658 have identical effect: they flush the runtime library's I/O buffer so
4659 that the data becomes visible to other processes. This does not guarantee
4660 that the data is committed to disk.
4662 On POSIX systems, you can request that all data is transferred to the
4663 storage device by calling the @code{fsync} function, with the POSIX file
4664 descriptor of the I/O unit as argument (retrieved with GNU intrinsic
4665 @code{FNUM}). The following example shows how:
4668 ! Declare the interface for POSIX fsync function
4670 function fsync (fd) bind(c,name="fsync")
4671 use iso_c_binding, only: c_int
4672 integer(c_int), value :: fd
4673 integer(c_int) :: fsync
4677 ! Variable declaration
4681 open (10,file="foo")
4684 ! Perform I/O on unit 10
4689 ret = fsync(fnum(10))
4691 ! Handle possible error
4692 if (ret /= 0) stop "Error calling FSYNC"
4700 @section @code{FNUM} --- File number function
4702 @cindex file operation, file number
4705 @item @emph{Description}:
4706 @code{FNUM(UNIT)} returns the POSIX file descriptor number corresponding to the
4707 open Fortran I/O unit @code{UNIT}.
4709 @item @emph{Standard}:
4715 @item @emph{Syntax}:
4716 @code{RESULT = FNUM(UNIT)}
4718 @item @emph{Arguments}:
4719 @multitable @columnfractions .15 .70
4720 @item @var{UNIT} @tab The type shall be @code{INTEGER}.
4723 @item @emph{Return value}:
4724 The return value is of type @code{INTEGER}
4726 @item @emph{Example}:
4730 open (unit=10, status = "scratch")
4734 end program test_fnum
4741 @section @code{FPUT} --- Write a single character in stream mode to stdout
4743 @cindex write character, stream mode
4744 @cindex stream mode, write character
4745 @cindex file operation, write character
4748 @item @emph{Description}:
4749 Write a single character in stream mode to stdout by bypassing normal
4750 formatted output. Stream I/O should not be mixed with normal record-oriented
4751 (formatted or unformatted) I/O on the same unit; the results are unpredictable.
4753 This intrinsic is provided in both subroutine and function forms; however,
4754 only one form can be used in any given program unit.
4756 Note that the @code{FGET} intrinsic is provided for backwards compatibility with
4757 @command{g77}. GNU Fortran provides the Fortran 2003 Stream facility.
4758 Programmers should consider the use of new stream IO feature in new code
4759 for future portability. See also @ref{Fortran 2003 status}.
4761 @item @emph{Standard}:
4765 Subroutine, function
4767 @item @emph{Syntax}:
4768 @multitable @columnfractions .80
4769 @item @code{CALL FPUT(C [, STATUS])}
4770 @item @code{STATUS = FPUT(C)}
4773 @item @emph{Arguments}:
4774 @multitable @columnfractions .15 .70
4775 @item @var{C} @tab The type shall be @code{CHARACTER} and of default
4777 @item @var{STATUS} @tab (Optional) status flag of type @code{INTEGER}.
4778 Returns 0 on success, -1 on end-of-file and a system specific positive
4779 error code otherwise.
4782 @item @emph{Example}:
4785 CHARACTER(len=10) :: str = "gfortran"
4787 DO i = 1, len_trim(str)
4793 @item @emph{See also}:
4794 @ref{FPUTC}, @ref{FGET}, @ref{FGETC}
4800 @section @code{FPUTC} --- Write a single character in stream mode
4802 @cindex write character, stream mode
4803 @cindex stream mode, write character
4804 @cindex file operation, write character
4807 @item @emph{Description}:
4808 Write a single character in stream mode by bypassing normal formatted
4809 output. Stream I/O should not be mixed with normal record-oriented
4810 (formatted or unformatted) I/O on the same unit; the results are unpredictable.
4812 This intrinsic is provided in both subroutine and function forms; however,
4813 only one form can be used in any given program unit.
4815 Note that the @code{FGET} intrinsic is provided for backwards compatibility with
4816 @command{g77}. GNU Fortran provides the Fortran 2003 Stream facility.
4817 Programmers should consider the use of new stream IO feature in new code
4818 for future portability. See also @ref{Fortran 2003 status}.
4820 @item @emph{Standard}:
4824 Subroutine, function
4826 @item @emph{Syntax}:
4827 @multitable @columnfractions .80
4828 @item @code{CALL FPUTC(UNIT, C [, STATUS])}
4829 @item @code{STATUS = FPUTC(UNIT, C)}
4832 @item @emph{Arguments}:
4833 @multitable @columnfractions .15 .70
4834 @item @var{UNIT} @tab The type shall be @code{INTEGER}.
4835 @item @var{C} @tab The type shall be @code{CHARACTER} and of default
4837 @item @var{STATUS} @tab (Optional) status flag of type @code{INTEGER}.
4838 Returns 0 on success, -1 on end-of-file and a system specific positive
4839 error code otherwise.
4842 @item @emph{Example}:
4845 CHARACTER(len=10) :: str = "gfortran"
4846 INTEGER :: fd = 42, i
4848 OPEN(UNIT = fd, FILE = "out", ACTION = "WRITE", STATUS="NEW")
4849 DO i = 1, len_trim(str)
4850 CALL fputc(fd, str(i:i))
4856 @item @emph{See also}:
4857 @ref{FPUT}, @ref{FGET}, @ref{FGETC}
4863 @section @code{FRACTION} --- Fractional part of the model representation
4865 @cindex real number, fraction
4866 @cindex floating point, fraction
4869 @item @emph{Description}:
4870 @code{FRACTION(X)} returns the fractional part of the model
4871 representation of @code{X}.
4873 @item @emph{Standard}:
4874 Fortran 95 and later
4879 @item @emph{Syntax}:
4880 @code{Y = FRACTION(X)}
4882 @item @emph{Arguments}:
4883 @multitable @columnfractions .15 .70
4884 @item @var{X} @tab The type of the argument shall be a @code{REAL}.
4887 @item @emph{Return value}:
4888 The return value is of the same type and kind as the argument.
4889 The fractional part of the model representation of @code{X} is returned;
4890 it is @code{X * RADIX(X)**(-EXPONENT(X))}.
4892 @item @emph{Example}:
4894 program test_fraction
4897 print *, fraction(x), x * radix(x)**(-exponent(x))
4898 end program test_fraction
4906 @section @code{FREE} --- Frees memory
4908 @cindex pointer, cray
4911 @item @emph{Description}:
4912 Frees memory previously allocated by @code{MALLOC()}. The @code{FREE}
4913 intrinsic is an extension intended to be used with Cray pointers, and is
4914 provided in GNU Fortran to allow user to compile legacy code. For
4915 new code using Fortran 95 pointers, the memory de-allocation intrinsic is
4918 @item @emph{Standard}:
4924 @item @emph{Syntax}:
4925 @code{CALL FREE(PTR)}
4927 @item @emph{Arguments}:
4928 @multitable @columnfractions .15 .70
4929 @item @var{PTR} @tab The type shall be @code{INTEGER}. It represents the
4930 location of the memory that should be de-allocated.
4933 @item @emph{Return value}:
4936 @item @emph{Example}:
4937 See @code{MALLOC} for an example.
4939 @item @emph{See also}:
4946 @section @code{FSEEK} --- Low level file positioning subroutine
4948 @cindex file operation, seek
4949 @cindex file operation, position
4952 @item @emph{Description}:
4953 Moves @var{UNIT} to the specified @var{OFFSET}. If @var{WHENCE}
4954 is set to 0, the @var{OFFSET} is taken as an absolute value @code{SEEK_SET},
4955 if set to 1, @var{OFFSET} is taken to be relative to the current position
4956 @code{SEEK_CUR}, and if set to 2 relative to the end of the file @code{SEEK_END}.
4957 On error, @var{STATUS} is set to a nonzero value. If @var{STATUS} the seek
4960 This intrinsic routine is not fully backwards compatible with @command{g77}.
4961 In @command{g77}, the @code{FSEEK} takes a statement label instead of a
4962 @var{STATUS} variable. If FSEEK is used in old code, change
4964 CALL FSEEK(UNIT, OFFSET, WHENCE, *label)
4969 CALL FSEEK(UNIT, OFFSET, WHENCE, status)
4970 IF (status /= 0) GOTO label
4973 Please note that GNU Fortran provides the Fortran 2003 Stream facility.
4974 Programmers should consider the use of new stream IO feature in new code
4975 for future portability. See also @ref{Fortran 2003 status}.
4977 @item @emph{Standard}:
4983 @item @emph{Syntax}:
4984 @code{CALL FSEEK(UNIT, OFFSET, WHENCE[, STATUS])}
4986 @item @emph{Arguments}:
4987 @multitable @columnfractions .15 .70
4988 @item @var{UNIT} @tab Shall be a scalar of type @code{INTEGER}.
4989 @item @var{OFFSET} @tab Shall be a scalar of type @code{INTEGER}.
4990 @item @var{WHENCE} @tab Shall be a scalar of type @code{INTEGER}.
4991 Its value shall be either 0, 1 or 2.
4992 @item @var{STATUS} @tab (Optional) shall be a scalar of type
4996 @item @emph{Example}:
4999 INTEGER, PARAMETER :: SEEK_SET = 0, SEEK_CUR = 1, SEEK_END = 2
5000 INTEGER :: fd, offset, ierr
5006 OPEN(UNIT=fd, FILE="fseek.test")
5007 CALL FSEEK(fd, offset, SEEK_SET, ierr) ! move to OFFSET
5008 print *, FTELL(fd), ierr
5010 CALL FSEEK(fd, 0, SEEK_END, ierr) ! move to end
5011 print *, FTELL(fd), ierr
5013 CALL FSEEK(fd, 0, SEEK_SET, ierr) ! move to beginning
5014 print *, FTELL(fd), ierr
5020 @item @emph{See also}:
5027 @section @code{FSTAT} --- Get file status
5029 @cindex file system, file status
5032 @item @emph{Description}:
5033 @code{FSTAT} is identical to @ref{STAT}, except that information about an
5034 already opened file is obtained.
5036 The elements in @code{VALUES} are the same as described by @ref{STAT}.
5038 This intrinsic is provided in both subroutine and function forms; however,
5039 only one form can be used in any given program unit.
5041 @item @emph{Standard}:
5045 Subroutine, function
5047 @item @emph{Syntax}:
5048 @multitable @columnfractions .80
5049 @item @code{CALL FSTAT(UNIT, VALUES [, STATUS])}
5050 @item @code{STATUS = FSTAT(UNIT, VALUES)}
5053 @item @emph{Arguments}:
5054 @multitable @columnfractions .15 .70
5055 @item @var{UNIT} @tab An open I/O unit number of type @code{INTEGER}.
5056 @item @var{VALUES} @tab The type shall be @code{INTEGER(4), DIMENSION(13)}.
5057 @item @var{STATUS} @tab (Optional) status flag of type @code{INTEGER(4)}. Returns 0
5058 on success and a system specific error code otherwise.
5061 @item @emph{Example}:
5062 See @ref{STAT} for an example.
5064 @item @emph{See also}:
5065 To stat a link: @ref{LSTAT}, to stat a file: @ref{STAT}
5071 @section @code{FTELL} --- Current stream position
5073 @cindex file operation, position
5076 @item @emph{Description}:
5077 Retrieves the current position within an open file.
5079 This intrinsic is provided in both subroutine and function forms; however,
5080 only one form can be used in any given program unit.
5082 @item @emph{Standard}:
5086 Subroutine, function
5088 @item @emph{Syntax}:
5089 @multitable @columnfractions .80
5090 @item @code{CALL FTELL(UNIT, OFFSET)}
5091 @item @code{OFFSET = FTELL(UNIT)}
5094 @item @emph{Arguments}:
5095 @multitable @columnfractions .15 .70
5096 @item @var{OFFSET} @tab Shall of type @code{INTEGER}.
5097 @item @var{UNIT} @tab Shall of type @code{INTEGER}.
5100 @item @emph{Return value}:
5101 In either syntax, @var{OFFSET} is set to the current offset of unit
5102 number @var{UNIT}, or to @math{-1} if the unit is not currently open.
5104 @item @emph{Example}:
5108 OPEN(10, FILE="temp.dat")
5114 @item @emph{See also}:
5121 @section @code{GAMMA} --- Gamma function
5124 @cindex Gamma function
5125 @cindex Factorial function
5128 @item @emph{Description}:
5129 @code{GAMMA(X)} computes Gamma (@math{\Gamma}) of @var{X}. For positive,
5130 integer values of @var{X} the Gamma function simplifies to the factorial
5131 function @math{\Gamma(x)=(x-1)!}.
5135 \Gamma(x) = \int_0^\infty t^{x-1}{\rm e}^{-t}\,{\rm d}t
5139 @item @emph{Standard}:
5140 Fortran 2008 and later
5145 @item @emph{Syntax}:
5148 @item @emph{Arguments}:
5149 @multitable @columnfractions .15 .70
5150 @item @var{X} @tab Shall be of type @code{REAL} and neither zero
5151 nor a negative integer.
5154 @item @emph{Return value}:
5155 The return value is of type @code{REAL} of the same kind as @var{X}.
5157 @item @emph{Example}:
5161 x = gamma(x) ! returns 1.0
5162 end program test_gamma
5165 @item @emph{Specific names}:
5166 @multitable @columnfractions .20 .20 .20 .25
5167 @item Name @tab Argument @tab Return type @tab Standard
5168 @item @code{GAMMA(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab GNU Extension
5169 @item @code{DGAMMA(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU Extension
5172 @item @emph{See also}:
5173 Logarithm of the Gamma function: @ref{LOG_GAMMA}
5180 @section @code{GERROR} --- Get last system error message
5182 @cindex system, error handling
5185 @item @emph{Description}:
5186 Returns the system error message corresponding to the last system error.
5187 This resembles the functionality of @code{strerror(3)} in C.
5189 @item @emph{Standard}:
5195 @item @emph{Syntax}:
5196 @code{CALL GERROR(RESULT)}
5198 @item @emph{Arguments}:
5199 @multitable @columnfractions .15 .70
5200 @item @var{RESULT} @tab Shall of type @code{CHARACTER} and of default
5203 @item @emph{Example}:
5206 CHARACTER(len=100) :: msg
5212 @item @emph{See also}:
5213 @ref{IERRNO}, @ref{PERROR}
5219 @section @code{GETARG} --- Get command line arguments
5221 @cindex command-line arguments
5222 @cindex arguments, to program
5225 @item @emph{Description}:
5226 Retrieve the @var{POS}-th argument that was passed on the
5227 command line when the containing program was invoked.
5229 This intrinsic routine is provided for backwards compatibility with
5230 GNU Fortran 77. In new code, programmers should consider the use of
5231 the @ref{GET_COMMAND_ARGUMENT} intrinsic defined by the Fortran 2003
5234 @item @emph{Standard}:
5240 @item @emph{Syntax}:
5241 @code{CALL GETARG(POS, VALUE)}
5243 @item @emph{Arguments}:
5244 @multitable @columnfractions .15 .70
5245 @item @var{POS} @tab Shall be of type @code{INTEGER} and not wider than
5246 the default integer kind; @math{@var{POS} \geq 0}
5247 @item @var{VALUE} @tab Shall be of type @code{CHARACTER} and of default
5249 @item @var{VALUE} @tab Shall be of type @code{CHARACTER}.
5252 @item @emph{Return value}:
5253 After @code{GETARG} returns, the @var{VALUE} argument holds the
5254 @var{POS}th command line argument. If @var{VALUE} can not hold the
5255 argument, it is truncated to fit the length of @var{VALUE}. If there are
5256 less than @var{POS} arguments specified at the command line, @var{VALUE}
5257 will be filled with blanks. If @math{@var{POS} = 0}, @var{VALUE} is set
5258 to the name of the program (on systems that support this feature).
5260 @item @emph{Example}:
5264 CHARACTER(len=32) :: arg
5273 @item @emph{See also}:
5274 GNU Fortran 77 compatibility function: @ref{IARGC}
5276 Fortran 2003 functions and subroutines: @ref{GET_COMMAND},
5277 @ref{GET_COMMAND_ARGUMENT}, @ref{COMMAND_ARGUMENT_COUNT}
5283 @section @code{GET_COMMAND} --- Get the entire command line
5284 @fnindex GET_COMMAND
5285 @cindex command-line arguments
5286 @cindex arguments, to program
5289 @item @emph{Description}:
5290 Retrieve the entire command line that was used to invoke the program.
5292 @item @emph{Standard}:
5293 Fortran 2003 and later
5298 @item @emph{Syntax}:
5299 @code{CALL GET_COMMAND([COMMAND, LENGTH, STATUS])}
5301 @item @emph{Arguments}:
5302 @multitable @columnfractions .15 .70
5303 @item @var{COMMAND} @tab (Optional) shall be of type @code{CHARACTER} and
5305 @item @var{LENGTH} @tab (Optional) Shall be of type @code{INTEGER} and of
5307 @item @var{STATUS} @tab (Optional) Shall be of type @code{INTEGER} and of
5311 @item @emph{Return value}:
5312 If @var{COMMAND} is present, stores the entire command line that was used
5313 to invoke the program in @var{COMMAND}. If @var{LENGTH} is present, it is
5314 assigned the length of the command line. If @var{STATUS} is present, it
5315 is assigned 0 upon success of the command, -1 if @var{COMMAND} is too
5316 short to store the command line, or a positive value in case of an error.
5318 @item @emph{Example}:
5320 PROGRAM test_get_command
5321 CHARACTER(len=255) :: cmd
5322 CALL get_command(cmd)
5323 WRITE (*,*) TRIM(cmd)
5327 @item @emph{See also}:
5328 @ref{GET_COMMAND_ARGUMENT}, @ref{COMMAND_ARGUMENT_COUNT}
5333 @node GET_COMMAND_ARGUMENT
5334 @section @code{GET_COMMAND_ARGUMENT} --- Get command line arguments
5335 @fnindex GET_COMMAND_ARGUMENT
5336 @cindex command-line arguments
5337 @cindex arguments, to program
5340 @item @emph{Description}:
5341 Retrieve the @var{NUMBER}-th argument that was passed on the
5342 command line when the containing program was invoked.
5344 @item @emph{Standard}:
5345 Fortran 2003 and later
5350 @item @emph{Syntax}:
5351 @code{CALL GET_COMMAND_ARGUMENT(NUMBER [, VALUE, LENGTH, STATUS])}
5353 @item @emph{Arguments}:
5354 @multitable @columnfractions .15 .70
5355 @item @var{NUMBER} @tab Shall be a scalar of type @code{INTEGER} and of
5356 default kind, @math{@var{NUMBER} \geq 0}
5357 @item @var{VALUE} @tab (Optional) Shall be a scalar of type @code{CHARACTER}
5358 and of default kind.
5359 @item @var{LENGTH} @tab (Optional) Shall be a scalar of type @code{INTEGER}
5360 and of default kind.
5361 @item @var{STATUS} @tab (Optional) Shall be a scalar of type @code{INTEGER}
5362 and of default kind.
5365 @item @emph{Return value}:
5366 After @code{GET_COMMAND_ARGUMENT} returns, the @var{VALUE} argument holds the
5367 @var{NUMBER}-th command line argument. If @var{VALUE} can not hold the argument, it is
5368 truncated to fit the length of @var{VALUE}. If there are less than @var{NUMBER}
5369 arguments specified at the command line, @var{VALUE} will be filled with blanks.
5370 If @math{@var{NUMBER} = 0}, @var{VALUE} is set to the name of the program (on
5371 systems that support this feature). The @var{LENGTH} argument contains the
5372 length of the @var{NUMBER}-th command line argument. If the argument retrieval
5373 fails, @var{STATUS} is a positive number; if @var{VALUE} contains a truncated
5374 command line argument, @var{STATUS} is -1; and otherwise the @var{STATUS} is
5377 @item @emph{Example}:
5379 PROGRAM test_get_command_argument
5381 CHARACTER(len=32) :: arg
5385 CALL get_command_argument(i, arg)
5386 IF (LEN_TRIM(arg) == 0) EXIT
5388 WRITE (*,*) TRIM(arg)
5394 @item @emph{See also}:
5395 @ref{GET_COMMAND}, @ref{COMMAND_ARGUMENT_COUNT}
5401 @section @code{GETCWD} --- Get current working directory
5403 @cindex system, working directory
5406 @item @emph{Description}:
5407 Get current working directory.
5409 This intrinsic is provided in both subroutine and function forms; however,
5410 only one form can be used in any given program unit.
5412 @item @emph{Standard}:
5416 Subroutine, function
5418 @item @emph{Syntax}:
5419 @multitable @columnfractions .80
5420 @item @code{CALL GETCWD(C [, STATUS])}
5421 @item @code{STATUS = GETCWD(C)}
5424 @item @emph{Arguments}:
5425 @multitable @columnfractions .15 .70
5426 @item @var{C} @tab The type shall be @code{CHARACTER} and of default kind.
5427 @item @var{STATUS} @tab (Optional) status flag. Returns 0 on success,
5428 a system specific and nonzero error code otherwise.
5431 @item @emph{Example}:
5434 CHARACTER(len=255) :: cwd
5436 WRITE(*,*) TRIM(cwd)
5440 @item @emph{See also}:
5447 @section @code{GETENV} --- Get an environmental variable
5449 @cindex environment variable
5452 @item @emph{Description}:
5453 Get the @var{VALUE} of the environmental variable @var{NAME}.
5455 This intrinsic routine is provided for backwards compatibility with
5456 GNU Fortran 77. In new code, programmers should consider the use of
5457 the @ref{GET_ENVIRONMENT_VARIABLE} intrinsic defined by the Fortran
5460 @item @emph{Standard}:
5466 @item @emph{Syntax}:
5467 @code{CALL GETENV(NAME, VALUE)}
5469 @item @emph{Arguments}:
5470 @multitable @columnfractions .15 .70
5471 @item @var{NAME} @tab Shall be of type @code{CHARACTER} and of default kind.
5472 @item @var{VALUE} @tab Shall be of type @code{CHARACTER} and of default kind.
5475 @item @emph{Return value}:
5476 Stores the value of @var{NAME} in @var{VALUE}. If @var{VALUE} is
5477 not large enough to hold the data, it is truncated. If @var{NAME}
5478 is not set, @var{VALUE} will be filled with blanks.
5480 @item @emph{Example}:
5483 CHARACTER(len=255) :: homedir
5484 CALL getenv("HOME", homedir)
5485 WRITE (*,*) TRIM(homedir)
5489 @item @emph{See also}:
5490 @ref{GET_ENVIRONMENT_VARIABLE}
5495 @node GET_ENVIRONMENT_VARIABLE
5496 @section @code{GET_ENVIRONMENT_VARIABLE} --- Get an environmental variable
5497 @fnindex GET_ENVIRONMENT_VARIABLE
5498 @cindex environment variable
5501 @item @emph{Description}:
5502 Get the @var{VALUE} of the environmental variable @var{NAME}.
5504 @item @emph{Standard}:
5505 Fortran 2003 and later
5510 @item @emph{Syntax}:
5511 @code{CALL GET_ENVIRONMENT_VARIABLE(NAME[, VALUE, LENGTH, STATUS, TRIM_NAME)}
5513 @item @emph{Arguments}:
5514 @multitable @columnfractions .15 .70
5515 @item @var{NAME} @tab Shall be a scalar of type @code{CHARACTER}
5516 and of default kind.
5517 @item @var{VALUE} @tab (Optional) Shall be a scalar of type @code{CHARACTER}
5518 and of default kind.
5519 @item @var{LENGTH} @tab (Optional) Shall be a scalar of type @code{INTEGER}
5520 and of default kind.
5521 @item @var{STATUS} @tab (Optional) Shall be a scalar of type @code{INTEGER}
5522 and of default kind.
5523 @item @var{TRIM_NAME} @tab (Optional) Shall be a scalar of type @code{LOGICAL}
5524 and of default kind.
5527 @item @emph{Return value}:
5528 Stores the value of @var{NAME} in @var{VALUE}. If @var{VALUE} is
5529 not large enough to hold the data, it is truncated. If @var{NAME}
5530 is not set, @var{VALUE} will be filled with blanks. Argument @var{LENGTH}
5531 contains the length needed for storing the environment variable @var{NAME}
5532 or zero if it is not present. @var{STATUS} is -1 if @var{VALUE} is present
5533 but too short for the environment variable; it is 1 if the environment
5534 variable does not exist and 2 if the processor does not support environment
5535 variables; in all other cases @var{STATUS} is zero. If @var{TRIM_NAME} is
5536 present with the value @code{.FALSE.}, the trailing blanks in @var{NAME}
5537 are significant; otherwise they are not part of the environment variable
5540 @item @emph{Example}:
5543 CHARACTER(len=255) :: homedir
5544 CALL get_environment_variable("HOME", homedir)
5545 WRITE (*,*) TRIM(homedir)
5553 @section @code{GETGID} --- Group ID function
5555 @cindex system, group ID
5558 @item @emph{Description}:
5559 Returns the numerical group ID of the current process.
5561 @item @emph{Standard}:
5567 @item @emph{Syntax}:
5568 @code{RESULT = GETGID()}
5570 @item @emph{Return value}:
5571 The return value of @code{GETGID} is an @code{INTEGER} of the default
5575 @item @emph{Example}:
5576 See @code{GETPID} for an example.
5578 @item @emph{See also}:
5579 @ref{GETPID}, @ref{GETUID}
5585 @section @code{GETLOG} --- Get login name
5587 @cindex system, login name
5591 @item @emph{Description}:
5592 Gets the username under which the program is running.
5594 @item @emph{Standard}:
5600 @item @emph{Syntax}:
5601 @code{CALL GETLOG(C)}
5603 @item @emph{Arguments}:
5604 @multitable @columnfractions .15 .70
5605 @item @var{C} @tab Shall be of type @code{CHARACTER} and of default kind.
5608 @item @emph{Return value}:
5609 Stores the current user name in @var{LOGIN}. (On systems where POSIX
5610 functions @code{geteuid} and @code{getpwuid} are not available, and
5611 the @code{getlogin} function is not implemented either, this will
5612 return a blank string.)
5614 @item @emph{Example}:
5617 CHARACTER(32) :: login
5623 @item @emph{See also}:
5630 @section @code{GETPID} --- Process ID function
5632 @cindex system, process ID
5636 @item @emph{Description}:
5637 Returns the numerical process identifier of the current process.
5639 @item @emph{Standard}:
5645 @item @emph{Syntax}:
5646 @code{RESULT = GETPID()}
5648 @item @emph{Return value}:
5649 The return value of @code{GETPID} is an @code{INTEGER} of the default
5653 @item @emph{Example}:
5656 print *, "The current process ID is ", getpid()
5657 print *, "Your numerical user ID is ", getuid()
5658 print *, "Your numerical group ID is ", getgid()
5662 @item @emph{See also}:
5663 @ref{GETGID}, @ref{GETUID}
5669 @section @code{GETUID} --- User ID function
5671 @cindex system, user ID
5675 @item @emph{Description}:
5676 Returns the numerical user ID of the current process.
5678 @item @emph{Standard}:
5684 @item @emph{Syntax}:
5685 @code{RESULT = GETUID()}
5687 @item @emph{Return value}:
5688 The return value of @code{GETUID} is an @code{INTEGER} of the default
5692 @item @emph{Example}:
5693 See @code{GETPID} for an example.
5695 @item @emph{See also}:
5696 @ref{GETPID}, @ref{GETLOG}
5702 @section @code{GMTIME} --- Convert time to GMT info
5704 @cindex time, conversion to GMT info
5707 @item @emph{Description}:
5708 Given a system time value @var{TIME} (as provided by the @code{TIME8()}
5709 intrinsic), fills @var{VALUES} with values extracted from it appropriate
5710 to the UTC time zone (Universal Coordinated Time, also known in some
5711 countries as GMT, Greenwich Mean Time), using @code{gmtime(3)}.
5713 @item @emph{Standard}:
5719 @item @emph{Syntax}:
5720 @code{CALL GMTIME(TIME, VALUES)}
5722 @item @emph{Arguments}:
5723 @multitable @columnfractions .15 .70
5724 @item @var{TIME} @tab An @code{INTEGER} scalar expression
5725 corresponding to a system time, with @code{INTENT(IN)}.
5726 @item @var{VALUES} @tab A default @code{INTEGER} array with 9 elements,
5727 with @code{INTENT(OUT)}.
5730 @item @emph{Return value}:
5731 The elements of @var{VALUES} are assigned as follows:
5733 @item Seconds after the minute, range 0--59 or 0--61 to allow for leap
5735 @item Minutes after the hour, range 0--59
5736 @item Hours past midnight, range 0--23
5737 @item Day of month, range 0--31
5738 @item Number of months since January, range 0--12
5739 @item Years since 1900
5740 @item Number of days since Sunday, range 0--6
5741 @item Days since January 1
5742 @item Daylight savings indicator: positive if daylight savings is in
5743 effect, zero if not, and negative if the information is not available.
5746 @item @emph{See also}:
5747 @ref{CTIME}, @ref{LTIME}, @ref{TIME}, @ref{TIME8}
5754 @section @code{HOSTNM} --- Get system host name
5756 @cindex system, host name
5759 @item @emph{Description}:
5760 Retrieves the host name of the system on which the program is running.
5762 This intrinsic is provided in both subroutine and function forms; however,
5763 only one form can be used in any given program unit.
5765 @item @emph{Standard}:
5769 Subroutine, function
5771 @item @emph{Syntax}:
5772 @multitable @columnfractions .80
5773 @item @code{CALL HOSTNM(C [, STATUS])}
5774 @item @code{STATUS = HOSTNM(NAME)}
5777 @item @emph{Arguments}:
5778 @multitable @columnfractions .15 .70
5779 @item @var{C} @tab Shall of type @code{CHARACTER} and of default kind.
5780 @item @var{STATUS} @tab (Optional) status flag of type @code{INTEGER}.
5781 Returns 0 on success, or a system specific error code otherwise.
5784 @item @emph{Return value}:
5785 In either syntax, @var{NAME} is set to the current hostname if it can
5786 be obtained, or to a blank string otherwise.
5793 @section @code{HUGE} --- Largest number of a kind
5795 @cindex limits, largest number
5796 @cindex model representation, largest number
5799 @item @emph{Description}:
5800 @code{HUGE(X)} returns the largest number that is not an infinity in
5801 the model of the type of @code{X}.
5803 @item @emph{Standard}:
5804 Fortran 95 and later
5809 @item @emph{Syntax}:
5810 @code{RESULT = HUGE(X)}
5812 @item @emph{Arguments}:
5813 @multitable @columnfractions .15 .70
5814 @item @var{X} @tab Shall be of type @code{REAL} or @code{INTEGER}.
5817 @item @emph{Return value}:
5818 The return value is of the same type and kind as @var{X}
5820 @item @emph{Example}:
5822 program test_huge_tiny
5823 print *, huge(0), huge(0.0), huge(0.0d0)
5824 print *, tiny(0.0), tiny(0.0d0)
5825 end program test_huge_tiny
5832 @section @code{HYPOT} --- Euclidean distance function
5834 @cindex Euclidean distance
5837 @item @emph{Description}:
5838 @code{HYPOT(X,Y)} is the Euclidean distance function. It is equal to
5839 @math{\sqrt{X^2 + Y^2}}, without undue underflow or overflow.
5841 @item @emph{Standard}:
5842 Fortran 2008 and later
5847 @item @emph{Syntax}:
5848 @code{RESULT = HYPOT(X, Y)}
5850 @item @emph{Arguments}:
5851 @multitable @columnfractions .15 .70
5852 @item @var{X} @tab The type shall be @code{REAL}.
5853 @item @var{Y} @tab The type and kind type parameter shall be the same as
5857 @item @emph{Return value}:
5858 The return value has the same type and kind type parameter as @var{X}.
5860 @item @emph{Example}:
5863 real(4) :: x = 1.e0_4, y = 0.5e0_4
5865 end program test_hypot
5872 @section @code{IACHAR} --- Code in @acronym{ASCII} collating sequence
5874 @cindex @acronym{ASCII} collating sequence
5875 @cindex collating sequence, @acronym{ASCII}
5876 @cindex conversion, to integer
5879 @item @emph{Description}:
5880 @code{IACHAR(C)} returns the code for the @acronym{ASCII} character
5881 in the first character position of @code{C}.
5883 @item @emph{Standard}:
5884 Fortran 95 and later, with @var{KIND} argument Fortran 2003 and later
5889 @item @emph{Syntax}:
5890 @code{RESULT = IACHAR(C [, KIND])}
5892 @item @emph{Arguments}:
5893 @multitable @columnfractions .15 .70
5894 @item @var{C} @tab Shall be a scalar @code{CHARACTER}, with @code{INTENT(IN)}
5895 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
5896 expression indicating the kind parameter of the result.
5899 @item @emph{Return value}:
5900 The return value is of type @code{INTEGER} and of kind @var{KIND}. If
5901 @var{KIND} is absent, the return value is of default integer kind.
5903 @item @emph{Example}:
5908 end program test_iachar
5912 See @ref{ICHAR} for a discussion of converting between numerical values
5913 and formatted string representations.
5915 @item @emph{See also}:
5916 @ref{ACHAR}, @ref{CHAR}, @ref{ICHAR}
5923 @section @code{IALL} --- Bitwise AND of array elements
5926 @cindex bits, AND of array elements
5929 @item @emph{Description}:
5930 Reduces with bitwise AND the elements of @var{ARRAY} along dimension @var{DIM}
5931 if the corresponding element in @var{MASK} is @code{TRUE}.
5933 @item @emph{Standard}:
5934 Fortran 2008 and later
5937 Transformational function
5939 @item @emph{Syntax}:
5940 @multitable @columnfractions .80
5941 @item @code{RESULT = IALL(ARRAY[, MASK])}
5942 @item @code{RESULT = IALL(ARRAY, DIM[, MASK])}
5945 @item @emph{Arguments}:
5946 @multitable @columnfractions .15 .70
5947 @item @var{ARRAY} @tab Shall be an array of type @code{INTEGER}
5948 @item @var{DIM} @tab (Optional) shall be a scalar of type
5949 @code{INTEGER} with a value in the range from 1 to n, where n
5950 equals the rank of @var{ARRAY}.
5951 @item @var{MASK} @tab (Optional) shall be of type @code{LOGICAL}
5952 and either be a scalar or an array of the same shape as @var{ARRAY}.
5955 @item @emph{Return value}:
5956 The result is of the same type as @var{ARRAY}.
5958 If @var{DIM} is absent, a scalar with the bitwise ALL of all elements in
5959 @var{ARRAY} is returned. Otherwise, an array of rank n-1, where n equals
5960 the rank of @var{ARRAY}, and a shape similar to that of @var{ARRAY} with
5961 dimension @var{DIM} dropped is returned.
5963 @item @emph{Example}:
5972 PRINT '(b8.8)', IALL(a)
5976 @item @emph{See also}:
5977 @ref{IANY}, @ref{IPARITY}, @ref{IAND}
5983 @section @code{IAND} --- Bitwise logical and
5985 @cindex bitwise logical and
5986 @cindex logical and, bitwise
5989 @item @emph{Description}:
5990 Bitwise logical @code{AND}.
5992 @item @emph{Standard}:
5993 Fortran 95 and later
5998 @item @emph{Syntax}:
5999 @code{RESULT = IAND(I, J)}
6001 @item @emph{Arguments}:
6002 @multitable @columnfractions .15 .70
6003 @item @var{I} @tab The type shall be @code{INTEGER}.
6004 @item @var{J} @tab The type shall be @code{INTEGER}, of the same
6005 kind as @var{I}. (As a GNU extension, different kinds are also
6009 @item @emph{Return value}:
6010 The return type is @code{INTEGER}, of the same kind as the
6011 arguments. (If the argument kinds differ, it is of the same kind as
6012 the larger argument.)
6014 @item @emph{Example}:
6018 DATA a / Z'F' /, b / Z'3' /
6019 WRITE (*,*) IAND(a, b)
6023 @item @emph{See also}:
6024 @ref{IOR}, @ref{IEOR}, @ref{IBITS}, @ref{IBSET}, @ref{IBCLR}, @ref{NOT}
6031 @section @code{IANY} --- Bitwise OR of array elements
6034 @cindex bits, OR of array elements
6037 @item @emph{Description}:
6038 Reduces with bitwise OR (inclusive or) the elements of @var{ARRAY} along
6039 dimension @var{DIM} if the corresponding element in @var{MASK} is @code{TRUE}.
6041 @item @emph{Standard}:
6042 Fortran 2008 and later
6045 Transformational function
6047 @item @emph{Syntax}:
6048 @multitable @columnfractions .80
6049 @item @code{RESULT = IANY(ARRAY[, MASK])}
6050 @item @code{RESULT = IANY(ARRAY, DIM[, MASK])}
6053 @item @emph{Arguments}:
6054 @multitable @columnfractions .15 .70
6055 @item @var{ARRAY} @tab Shall be an array of type @code{INTEGER}
6056 @item @var{DIM} @tab (Optional) shall be a scalar of type
6057 @code{INTEGER} with a value in the range from 1 to n, where n
6058 equals the rank of @var{ARRAY}.
6059 @item @var{MASK} @tab (Optional) shall be of type @code{LOGICAL}
6060 and either be a scalar or an array of the same shape as @var{ARRAY}.
6063 @item @emph{Return value}:
6064 The result is of the same type as @var{ARRAY}.
6066 If @var{DIM} is absent, a scalar with the bitwise OR of all elements in
6067 @var{ARRAY} is returned. Otherwise, an array of rank n-1, where n equals
6068 the rank of @var{ARRAY}, and a shape similar to that of @var{ARRAY} with
6069 dimension @var{DIM} dropped is returned.
6071 @item @emph{Example}:
6080 PRINT '(b8.8)', IANY(a)
6084 @item @emph{See also}:
6085 @ref{IPARITY}, @ref{IALL}, @ref{IOR}
6091 @section @code{IARGC} --- Get the number of command line arguments
6093 @cindex command-line arguments
6094 @cindex command-line arguments, number of
6095 @cindex arguments, to program
6098 @item @emph{Description}:
6099 @code{IARGC()} returns the number of arguments passed on the
6100 command line when the containing program was invoked.
6102 This intrinsic routine is provided for backwards compatibility with
6103 GNU Fortran 77. In new code, programmers should consider the use of
6104 the @ref{COMMAND_ARGUMENT_COUNT} intrinsic defined by the Fortran 2003
6107 @item @emph{Standard}:
6113 @item @emph{Syntax}:
6114 @code{RESULT = IARGC()}
6116 @item @emph{Arguments}:
6119 @item @emph{Return value}:
6120 The number of command line arguments, type @code{INTEGER(4)}.
6122 @item @emph{Example}:
6125 @item @emph{See also}:
6126 GNU Fortran 77 compatibility subroutine: @ref{GETARG}
6128 Fortran 2003 functions and subroutines: @ref{GET_COMMAND},
6129 @ref{GET_COMMAND_ARGUMENT}, @ref{COMMAND_ARGUMENT_COUNT}
6135 @section @code{IBCLR} --- Clear bit
6141 @item @emph{Description}:
6142 @code{IBCLR} returns the value of @var{I} with the bit at position
6143 @var{POS} set to zero.
6145 @item @emph{Standard}:
6146 Fortran 95 and later
6151 @item @emph{Syntax}:
6152 @code{RESULT = IBCLR(I, POS)}
6154 @item @emph{Arguments}:
6155 @multitable @columnfractions .15 .70
6156 @item @var{I} @tab The type shall be @code{INTEGER}.
6157 @item @var{POS} @tab The type shall be @code{INTEGER}.
6160 @item @emph{Return value}:
6161 The return value is of type @code{INTEGER} and of the same kind as
6164 @item @emph{See also}:
6165 @ref{IBITS}, @ref{IBSET}, @ref{IAND}, @ref{IOR}, @ref{IEOR}, @ref{MVBITS}
6172 @section @code{IBITS} --- Bit extraction
6175 @cindex bits, extract
6178 @item @emph{Description}:
6179 @code{IBITS} extracts a field of length @var{LEN} from @var{I},
6180 starting from bit position @var{POS} and extending left for @var{LEN}
6181 bits. The result is right-justified and the remaining bits are
6182 zeroed. The value of @code{POS+LEN} must be less than or equal to the
6183 value @code{BIT_SIZE(I)}.
6185 @item @emph{Standard}:
6186 Fortran 95 and later
6191 @item @emph{Syntax}:
6192 @code{RESULT = IBITS(I, POS, LEN)}
6194 @item @emph{Arguments}:
6195 @multitable @columnfractions .15 .70
6196 @item @var{I} @tab The type shall be @code{INTEGER}.
6197 @item @var{POS} @tab The type shall be @code{INTEGER}.
6198 @item @var{LEN} @tab The type shall be @code{INTEGER}.
6201 @item @emph{Return value}:
6202 The return value is of type @code{INTEGER} and of the same kind as
6205 @item @emph{See also}:
6206 @ref{BIT_SIZE}, @ref{IBCLR}, @ref{IBSET}, @ref{IAND}, @ref{IOR}, @ref{IEOR}
6212 @section @code{IBSET} --- Set bit
6217 @item @emph{Description}:
6218 @code{IBSET} returns the value of @var{I} with the bit at position
6219 @var{POS} set to one.
6221 @item @emph{Standard}:
6222 Fortran 95 and later
6227 @item @emph{Syntax}:
6228 @code{RESULT = IBSET(I, POS)}
6230 @item @emph{Arguments}:
6231 @multitable @columnfractions .15 .70
6232 @item @var{I} @tab The type shall be @code{INTEGER}.
6233 @item @var{POS} @tab The type shall be @code{INTEGER}.
6236 @item @emph{Return value}:
6237 The return value is of type @code{INTEGER} and of the same kind as
6240 @item @emph{See also}:
6241 @ref{IBCLR}, @ref{IBITS}, @ref{IAND}, @ref{IOR}, @ref{IEOR}, @ref{MVBITS}
6248 @section @code{ICHAR} --- Character-to-integer conversion function
6250 @cindex conversion, to integer
6253 @item @emph{Description}:
6254 @code{ICHAR(C)} returns the code for the character in the first character
6255 position of @code{C} in the system's native character set.
6256 The correspondence between characters and their codes is not necessarily
6257 the same across different GNU Fortran implementations.
6259 @item @emph{Standard}:
6260 Fortran 95 and later, with @var{KIND} argument Fortran 2003 and later
6265 @item @emph{Syntax}:
6266 @code{RESULT = ICHAR(C [, KIND])}
6268 @item @emph{Arguments}:
6269 @multitable @columnfractions .15 .70
6270 @item @var{C} @tab Shall be a scalar @code{CHARACTER}, with @code{INTENT(IN)}
6271 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
6272 expression indicating the kind parameter of the result.
6275 @item @emph{Return value}:
6276 The return value is of type @code{INTEGER} and of kind @var{KIND}. If
6277 @var{KIND} is absent, the return value is of default integer kind.
6279 @item @emph{Example}:
6284 end program test_ichar
6287 @item @emph{Specific names}:
6288 @multitable @columnfractions .20 .20 .20 .25
6289 @item Name @tab Argument @tab Return type @tab Standard
6290 @item @code{ICHAR(C)} @tab @code{CHARACTER C} @tab @code{INTEGER(4)} @tab Fortran 77 and later
6294 No intrinsic exists to convert between a numeric value and a formatted
6295 character string representation -- for instance, given the
6296 @code{CHARACTER} value @code{'154'}, obtaining an @code{INTEGER} or
6297 @code{REAL} value with the value 154, or vice versa. Instead, this
6298 functionality is provided by internal-file I/O, as in the following
6303 character(len=10) string, string2
6306 ! Convert a string to a numeric value
6307 read (string,'(I10)') value
6310 ! Convert a value to a formatted string
6311 write (string2,'(I10)') value
6313 end program read_val
6316 @item @emph{See also}:
6317 @ref{ACHAR}, @ref{CHAR}, @ref{IACHAR}
6324 @section @code{IDATE} --- Get current local time subroutine (day/month/year)
6326 @cindex date, current
6327 @cindex current date
6330 @item @emph{Description}:
6331 @code{IDATE(VALUES)} Fills @var{VALUES} with the numerical values at the
6332 current local time. The day (in the range 1-31), month (in the range 1-12),
6333 and year appear in elements 1, 2, and 3 of @var{VALUES}, respectively.
6334 The year has four significant digits.
6336 @item @emph{Standard}:
6342 @item @emph{Syntax}:
6343 @code{CALL IDATE(VALUES)}
6345 @item @emph{Arguments}:
6346 @multitable @columnfractions .15 .70
6347 @item @var{VALUES} @tab The type shall be @code{INTEGER, DIMENSION(3)} and
6348 the kind shall be the default integer kind.
6351 @item @emph{Return value}:
6352 Does not return anything.
6354 @item @emph{Example}:
6357 integer, dimension(3) :: tarray
6362 end program test_idate
6369 @section @code{IEOR} --- Bitwise logical exclusive or
6371 @cindex bitwise logical exclusive or
6372 @cindex logical exclusive or, bitwise
6375 @item @emph{Description}:
6376 @code{IEOR} returns the bitwise Boolean exclusive-OR of @var{I} and
6379 @item @emph{Standard}:
6380 Fortran 95 and later
6385 @item @emph{Syntax}:
6386 @code{RESULT = IEOR(I, J)}
6388 @item @emph{Arguments}:
6389 @multitable @columnfractions .15 .70
6390 @item @var{I} @tab The type shall be @code{INTEGER}.
6391 @item @var{J} @tab The type shall be @code{INTEGER}, of the same
6392 kind as @var{I}. (As a GNU extension, different kinds are also
6396 @item @emph{Return value}:
6397 The return type is @code{INTEGER}, of the same kind as the
6398 arguments. (If the argument kinds differ, it is of the same kind as
6399 the larger argument.)
6401 @item @emph{See also}:
6402 @ref{IOR}, @ref{IAND}, @ref{IBITS}, @ref{IBSET}, @ref{IBCLR}, @ref{NOT}
6408 @section @code{IERRNO} --- Get the last system error number
6410 @cindex system, error handling
6413 @item @emph{Description}:
6414 Returns the last system error number, as given by the C @code{errno()}
6417 @item @emph{Standard}:
6423 @item @emph{Syntax}:
6424 @code{RESULT = IERRNO()}
6426 @item @emph{Arguments}:
6429 @item @emph{Return value}:
6430 The return value is of type @code{INTEGER} and of the default integer
6433 @item @emph{See also}:
6440 @section @code{IMAGE_INDEX} --- Function that converts a cosubscript to an image index
6441 @fnindex IMAGE_INDEX
6442 @cindex coarray, @code{IMAGE_INDEX}
6443 @cindex images, cosubscript to image index conversion
6446 @item @emph{Description}:
6447 Returns the image index belonging to a cosubscript.
6449 @item @emph{Standard}:
6450 Fortran 2008 and later
6455 @item @emph{Syntax}:
6456 @code{RESULT = IMAGE_INDEX(COARRAY, SUB)}
6458 @item @emph{Arguments}: None.
6459 @multitable @columnfractions .15 .70
6460 @item @var{COARRAY} @tab Coarray of any type.
6461 @item @var{SUB} @tab default integer rank-1 array of a size equal to
6462 the corank of @var{COARRAY}.
6466 @item @emph{Return value}:
6467 Scalar default integer with the value of the image index which corresponds
6468 to the cosubscripts. For invalid cosubscripts the result is zero.
6470 @item @emph{Example}:
6472 INTEGER :: array[2,-1:4,8,*]
6473 ! Writes 28 (or 0 if there are fewer than 28 images)
6474 WRITE (*,*) IMAGE_INDEX (array, [2,0,3,1])
6477 @item @emph{See also}:
6478 @ref{THIS_IMAGE}, @ref{NUM_IMAGES}
6483 @node INDEX intrinsic
6484 @section @code{INDEX} --- Position of a substring within a string
6486 @cindex substring position
6487 @cindex string, find substring
6490 @item @emph{Description}:
6491 Returns the position of the start of the first occurrence of string
6492 @var{SUBSTRING} as a substring in @var{STRING}, counting from one. If
6493 @var{SUBSTRING} is not present in @var{STRING}, zero is returned. If
6494 the @var{BACK} argument is present and true, the return value is the
6495 start of the last occurrence rather than the first.
6497 @item @emph{Standard}:
6498 Fortran 77 and later, with @var{KIND} argument Fortran 2003 and later
6503 @item @emph{Syntax}:
6504 @code{RESULT = INDEX(STRING, SUBSTRING [, BACK [, KIND]])}
6506 @item @emph{Arguments}:
6507 @multitable @columnfractions .15 .70
6508 @item @var{STRING} @tab Shall be a scalar @code{CHARACTER}, with
6510 @item @var{SUBSTRING} @tab Shall be a scalar @code{CHARACTER}, with
6512 @item @var{BACK} @tab (Optional) Shall be a scalar @code{LOGICAL}, with
6514 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
6515 expression indicating the kind parameter of the result.
6518 @item @emph{Return value}:
6519 The return value is of type @code{INTEGER} and of kind @var{KIND}. If
6520 @var{KIND} is absent, the return value is of default integer kind.
6522 @item @emph{Specific names}:
6523 @multitable @columnfractions .20 .20 .20 .25
6524 @item Name @tab Argument @tab Return type @tab Standard
6525 @item @code{INDEX(STRING, SUBSTRING)} @tab @code{CHARACTER} @tab @code{INTEGER(4)} @tab Fortran 77 and later
6528 @item @emph{See also}:
6529 @ref{SCAN}, @ref{VERIFY}
6535 @section @code{INT} --- Convert to integer type
6539 @cindex conversion, to integer
6542 @item @emph{Description}:
6543 Convert to integer type
6545 @item @emph{Standard}:
6546 Fortran 77 and later
6551 @item @emph{Syntax}:
6552 @code{RESULT = INT(A [, KIND))}
6554 @item @emph{Arguments}:
6555 @multitable @columnfractions .15 .70
6556 @item @var{A} @tab Shall be of type @code{INTEGER},
6557 @code{REAL}, or @code{COMPLEX}.
6558 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
6559 expression indicating the kind parameter of the result.
6562 @item @emph{Return value}:
6563 These functions return a @code{INTEGER} variable or array under
6564 the following rules:
6568 If @var{A} is of type @code{INTEGER}, @code{INT(A) = A}
6570 If @var{A} is of type @code{REAL} and @math{|A| < 1}, @code{INT(A)} equals @code{0}.
6571 If @math{|A| \geq 1}, then @code{INT(A)} equals the largest integer that does not exceed
6572 the range of @var{A} and whose sign is the same as the sign of @var{A}.
6574 If @var{A} is of type @code{COMPLEX}, rule B is applied to the real part of @var{A}.
6577 @item @emph{Example}:
6581 complex :: z = (-3.7, 1.0)
6583 print *, int(z), int(z,8)
6587 @item @emph{Specific names}:
6588 @multitable @columnfractions .20 .20 .20 .25
6589 @item Name @tab Argument @tab Return type @tab Standard
6590 @item @code{INT(A)} @tab @code{REAL(4) A} @tab @code{INTEGER} @tab Fortran 77 and later
6591 @item @code{IFIX(A)} @tab @code{REAL(4) A} @tab @code{INTEGER} @tab Fortran 77 and later
6592 @item @code{IDINT(A)} @tab @code{REAL(8) A} @tab @code{INTEGER} @tab Fortran 77 and later
6599 @section @code{INT2} --- Convert to 16-bit integer type
6602 @cindex conversion, to integer
6605 @item @emph{Description}:
6606 Convert to a @code{KIND=2} integer type. This is equivalent to the
6607 standard @code{INT} intrinsic with an optional argument of
6608 @code{KIND=2}, and is only included for backwards compatibility.
6610 The @code{SHORT} intrinsic is equivalent to @code{INT2}.
6612 @item @emph{Standard}:
6618 @item @emph{Syntax}:
6619 @code{RESULT = INT2(A)}
6621 @item @emph{Arguments}:
6622 @multitable @columnfractions .15 .70
6623 @item @var{A} @tab Shall be of type @code{INTEGER},
6624 @code{REAL}, or @code{COMPLEX}.
6627 @item @emph{Return value}:
6628 The return value is a @code{INTEGER(2)} variable.
6630 @item @emph{See also}:
6631 @ref{INT}, @ref{INT8}, @ref{LONG}
6637 @section @code{INT8} --- Convert to 64-bit integer type
6639 @cindex conversion, to integer
6642 @item @emph{Description}:
6643 Convert to a @code{KIND=8} integer type. This is equivalent to the
6644 standard @code{INT} intrinsic with an optional argument of
6645 @code{KIND=8}, and is only included for backwards compatibility.
6647 @item @emph{Standard}:
6653 @item @emph{Syntax}:
6654 @code{RESULT = INT8(A)}
6656 @item @emph{Arguments}:
6657 @multitable @columnfractions .15 .70
6658 @item @var{A} @tab Shall be of type @code{INTEGER},
6659 @code{REAL}, or @code{COMPLEX}.
6662 @item @emph{Return value}:
6663 The return value is a @code{INTEGER(8)} variable.
6665 @item @emph{See also}:
6666 @ref{INT}, @ref{INT2}, @ref{LONG}
6672 @section @code{IOR} --- Bitwise logical or
6674 @cindex bitwise logical or
6675 @cindex logical or, bitwise
6678 @item @emph{Description}:
6679 @code{IOR} returns the bitwise Boolean inclusive-OR of @var{I} and
6682 @item @emph{Standard}:
6683 Fortran 95 and later
6688 @item @emph{Syntax}:
6689 @code{RESULT = IOR(I, J)}
6691 @item @emph{Arguments}:
6692 @multitable @columnfractions .15 .70
6693 @item @var{I} @tab The type shall be @code{INTEGER}.
6694 @item @var{J} @tab The type shall be @code{INTEGER}, of the same
6695 kind as @var{I}. (As a GNU extension, different kinds are also
6699 @item @emph{Return value}:
6700 The return type is @code{INTEGER}, of the same kind as the
6701 arguments. (If the argument kinds differ, it is of the same kind as
6702 the larger argument.)
6704 @item @emph{See also}:
6705 @ref{IEOR}, @ref{IAND}, @ref{IBITS}, @ref{IBSET}, @ref{IBCLR}, @ref{NOT}
6711 @section @code{IPARITY} --- Bitwise XOR of array elements
6713 @cindex array, parity
6715 @cindex bits, XOR of array elements
6718 @item @emph{Description}:
6719 Reduces with bitwise XOR (exclusive or) the elements of @var{ARRAY} along
6720 dimension @var{DIM} if the corresponding element in @var{MASK} is @code{TRUE}.
6722 @item @emph{Standard}:
6723 Fortran 2008 and later
6726 Transformational function
6728 @item @emph{Syntax}:
6729 @multitable @columnfractions .80
6730 @item @code{RESULT = IPARITY(ARRAY[, MASK])}
6731 @item @code{RESULT = IPARITY(ARRAY, DIM[, MASK])}
6734 @item @emph{Arguments}:
6735 @multitable @columnfractions .15 .70
6736 @item @var{ARRAY} @tab Shall be an array of type @code{INTEGER}
6737 @item @var{DIM} @tab (Optional) shall be a scalar of type
6738 @code{INTEGER} with a value in the range from 1 to n, where n
6739 equals the rank of @var{ARRAY}.
6740 @item @var{MASK} @tab (Optional) shall be of type @code{LOGICAL}
6741 and either be a scalar or an array of the same shape as @var{ARRAY}.
6744 @item @emph{Return value}:
6745 The result is of the same type as @var{ARRAY}.
6747 If @var{DIM} is absent, a scalar with the bitwise XOR of all elements in
6748 @var{ARRAY} is returned. Otherwise, an array of rank n-1, where n equals
6749 the rank of @var{ARRAY}, and a shape similar to that of @var{ARRAY} with
6750 dimension @var{DIM} dropped is returned.
6752 @item @emph{Example}:
6754 PROGRAM test_iparity
6761 PRINT '(b8.8)', IPARITY(a)
6765 @item @emph{See also}:
6766 @ref{IANY}, @ref{IALL}, @ref{IEOR}, @ref{PARITY}
6772 @section @code{IRAND} --- Integer pseudo-random number
6774 @cindex random number generation
6777 @item @emph{Description}:
6778 @code{IRAND(FLAG)} returns a pseudo-random number from a uniform
6779 distribution between 0 and a system-dependent limit (which is in most
6780 cases 2147483647). If @var{FLAG} is 0, the next number
6781 in the current sequence is returned; if @var{FLAG} is 1, the generator
6782 is restarted by @code{CALL SRAND(0)}; if @var{FLAG} has any other value,
6783 it is used as a new seed with @code{SRAND}.
6785 This intrinsic routine is provided for backwards compatibility with
6786 GNU Fortran 77. It implements a simple modulo generator as provided
6787 by @command{g77}. For new code, one should consider the use of
6788 @ref{RANDOM_NUMBER} as it implements a superior algorithm.
6790 @item @emph{Standard}:
6796 @item @emph{Syntax}:
6797 @code{RESULT = IRAND(I)}
6799 @item @emph{Arguments}:
6800 @multitable @columnfractions .15 .70
6801 @item @var{I} @tab Shall be a scalar @code{INTEGER} of kind 4.
6804 @item @emph{Return value}:
6805 The return value is of @code{INTEGER(kind=4)} type.
6807 @item @emph{Example}:
6810 integer,parameter :: seed = 86456
6813 print *, irand(), irand(), irand(), irand()
6814 print *, irand(seed), irand(), irand(), irand()
6815 end program test_irand
6823 @section @code{IS_IOSTAT_END} --- Test for end-of-file value
6824 @fnindex IS_IOSTAT_END
6825 @cindex @code{IOSTAT}, end of file
6828 @item @emph{Description}:
6829 @code{IS_IOSTAT_END} tests whether an variable has the value of the I/O
6830 status ``end of file''. The function is equivalent to comparing the variable
6831 with the @code{IOSTAT_END} parameter of the intrinsic module
6832 @code{ISO_FORTRAN_ENV}.
6834 @item @emph{Standard}:
6835 Fortran 2003 and later
6840 @item @emph{Syntax}:
6841 @code{RESULT = IS_IOSTAT_END(I)}
6843 @item @emph{Arguments}:
6844 @multitable @columnfractions .15 .70
6845 @item @var{I} @tab Shall be of the type @code{INTEGER}.
6848 @item @emph{Return value}:
6849 Returns a @code{LOGICAL} of the default kind, which @code{.TRUE.} if
6850 @var{I} has the value which indicates an end of file condition for
6851 @code{IOSTAT=} specifiers, and is @code{.FALSE.} otherwise.
6853 @item @emph{Example}:
6858 OPEN(88, FILE='test.dat')
6859 READ(88, *, IOSTAT=stat) i
6860 IF(IS_IOSTAT_END(stat)) STOP 'END OF FILE'
6868 @section @code{IS_IOSTAT_EOR} --- Test for end-of-record value
6869 @fnindex IS_IOSTAT_EOR
6870 @cindex @code{IOSTAT}, end of record
6873 @item @emph{Description}:
6874 @code{IS_IOSTAT_EOR} tests whether an variable has the value of the I/O
6875 status ``end of record''. The function is equivalent to comparing the
6876 variable with the @code{IOSTAT_EOR} parameter of the intrinsic module
6877 @code{ISO_FORTRAN_ENV}.
6879 @item @emph{Standard}:
6880 Fortran 2003 and later
6885 @item @emph{Syntax}:
6886 @code{RESULT = IS_IOSTAT_EOR(I)}
6888 @item @emph{Arguments}:
6889 @multitable @columnfractions .15 .70
6890 @item @var{I} @tab Shall be of the type @code{INTEGER}.
6893 @item @emph{Return value}:
6894 Returns a @code{LOGICAL} of the default kind, which @code{.TRUE.} if
6895 @var{I} has the value which indicates an end of file condition for
6896 @code{IOSTAT=} specifiers, and is @code{.FALSE.} otherwise.
6898 @item @emph{Example}:
6902 INTEGER :: stat, i(50)
6903 OPEN(88, FILE='test.dat', FORM='UNFORMATTED')
6904 READ(88, IOSTAT=stat) i
6905 IF(IS_IOSTAT_EOR(stat)) STOP 'END OF RECORD'
6913 @section @code{ISATTY} --- Whether a unit is a terminal device.
6915 @cindex system, terminal
6918 @item @emph{Description}:
6919 Determine whether a unit is connected to a terminal device.
6921 @item @emph{Standard}:
6927 @item @emph{Syntax}:
6928 @code{RESULT = ISATTY(UNIT)}
6930 @item @emph{Arguments}:
6931 @multitable @columnfractions .15 .70
6932 @item @var{UNIT} @tab Shall be a scalar @code{INTEGER}.
6935 @item @emph{Return value}:
6936 Returns @code{.TRUE.} if the @var{UNIT} is connected to a terminal
6937 device, @code{.FALSE.} otherwise.
6939 @item @emph{Example}:
6942 INTEGER(kind=1) :: unit
6944 write(*,*) isatty(unit=unit)
6948 @item @emph{See also}:
6955 @section @code{ISHFT} --- Shift bits
6960 @item @emph{Description}:
6961 @code{ISHFT} returns a value corresponding to @var{I} with all of the
6962 bits shifted @var{SHIFT} places. A value of @var{SHIFT} greater than
6963 zero corresponds to a left shift, a value of zero corresponds to no
6964 shift, and a value less than zero corresponds to a right shift. If the
6965 absolute value of @var{SHIFT} is greater than @code{BIT_SIZE(I)}, the
6966 value is undefined. Bits shifted out from the left end or right end are
6967 lost; zeros are shifted in from the opposite end.
6969 @item @emph{Standard}:
6970 Fortran 95 and later
6975 @item @emph{Syntax}:
6976 @code{RESULT = ISHFT(I, SHIFT)}
6978 @item @emph{Arguments}:
6979 @multitable @columnfractions .15 .70
6980 @item @var{I} @tab The type shall be @code{INTEGER}.
6981 @item @var{SHIFT} @tab The type shall be @code{INTEGER}.
6984 @item @emph{Return value}:
6985 The return value is of type @code{INTEGER} and of the same kind as
6988 @item @emph{See also}:
6995 @section @code{ISHFTC} --- Shift bits circularly
6997 @cindex bits, shift circular
7000 @item @emph{Description}:
7001 @code{ISHFTC} returns a value corresponding to @var{I} with the
7002 rightmost @var{SIZE} bits shifted circularly @var{SHIFT} places; that
7003 is, bits shifted out one end are shifted into the opposite end. A value
7004 of @var{SHIFT} greater than zero corresponds to a left shift, a value of
7005 zero corresponds to no shift, and a value less than zero corresponds to
7006 a right shift. The absolute value of @var{SHIFT} must be less than
7007 @var{SIZE}. If the @var{SIZE} argument is omitted, it is taken to be
7008 equivalent to @code{BIT_SIZE(I)}.
7010 @item @emph{Standard}:
7011 Fortran 95 and later
7016 @item @emph{Syntax}:
7017 @code{RESULT = ISHFTC(I, SHIFT [, SIZE])}
7019 @item @emph{Arguments}:
7020 @multitable @columnfractions .15 .70
7021 @item @var{I} @tab The type shall be @code{INTEGER}.
7022 @item @var{SHIFT} @tab The type shall be @code{INTEGER}.
7023 @item @var{SIZE} @tab (Optional) The type shall be @code{INTEGER};
7024 the value must be greater than zero and less than or equal to
7028 @item @emph{Return value}:
7029 The return value is of type @code{INTEGER} and of the same kind as
7032 @item @emph{See also}:
7039 @section @code{ISNAN} --- Test for a NaN
7044 @item @emph{Description}:
7045 @code{ISNAN} tests whether a floating-point value is an IEEE
7047 @item @emph{Standard}:
7053 @item @emph{Syntax}:
7056 @item @emph{Arguments}:
7057 @multitable @columnfractions .15 .70
7058 @item @var{X} @tab Variable of the type @code{REAL}.
7062 @item @emph{Return value}:
7063 Returns a default-kind @code{LOGICAL}. The returned value is @code{TRUE}
7064 if @var{X} is a NaN and @code{FALSE} otherwise.
7066 @item @emph{Example}:
7073 if (isnan(x)) stop '"x" is a NaN'
7074 end program test_nan
7081 @section @code{ITIME} --- Get current local time subroutine (hour/minutes/seconds)
7083 @cindex time, current
7084 @cindex current time
7087 @item @emph{Description}:
7088 @code{IDATE(VALUES)} Fills @var{VALUES} with the numerical values at the
7089 current local time. The hour (in the range 1-24), minute (in the range 1-60),
7090 and seconds (in the range 1-60) appear in elements 1, 2, and 3 of @var{VALUES},
7093 @item @emph{Standard}:
7099 @item @emph{Syntax}:
7100 @code{CALL ITIME(VALUES)}
7102 @item @emph{Arguments}:
7103 @multitable @columnfractions .15 .70
7104 @item @var{VALUES} @tab The type shall be @code{INTEGER, DIMENSION(3)}
7105 and the kind shall be the default integer kind.
7108 @item @emph{Return value}:
7109 Does not return anything.
7112 @item @emph{Example}:
7115 integer, dimension(3) :: tarray
7120 end program test_itime
7127 @section @code{KILL} --- Send a signal to a process
7131 @item @emph{Description}:
7132 @item @emph{Standard}:
7133 Sends the signal specified by @var{SIGNAL} to the process @var{PID}.
7136 This intrinsic is provided in both subroutine and function forms; however,
7137 only one form can be used in any given program unit.
7140 Subroutine, function
7142 @item @emph{Syntax}:
7143 @multitable @columnfractions .80
7144 @item @code{CALL KILL(C, VALUE [, STATUS])}
7145 @item @code{STATUS = KILL(C, VALUE)}
7148 @item @emph{Arguments}:
7149 @multitable @columnfractions .15 .70
7150 @item @var{C} @tab Shall be a scalar @code{INTEGER}, with
7152 @item @var{VALUE} @tab Shall be a scalar @code{INTEGER}, with
7154 @item @var{STATUS} @tab (Optional) status flag of type @code{INTEGER(4)} or
7155 @code{INTEGER(8)}. Returns 0 on success, or a system-specific error code
7159 @item @emph{See also}:
7160 @ref{ABORT}, @ref{EXIT}
7166 @section @code{KIND} --- Kind of an entity
7171 @item @emph{Description}:
7172 @code{KIND(X)} returns the kind value of the entity @var{X}.
7174 @item @emph{Standard}:
7175 Fortran 95 and later
7180 @item @emph{Syntax}:
7183 @item @emph{Arguments}:
7184 @multitable @columnfractions .15 .70
7185 @item @var{X} @tab Shall be of type @code{LOGICAL}, @code{INTEGER},
7186 @code{REAL}, @code{COMPLEX} or @code{CHARACTER}.
7189 @item @emph{Return value}:
7190 The return value is a scalar of type @code{INTEGER} and of the default
7193 @item @emph{Example}:
7196 integer,parameter :: kc = kind(' ')
7197 integer,parameter :: kl = kind(.true.)
7199 print *, "The default character kind is ", kc
7200 print *, "The default logical kind is ", kl
7201 end program test_kind
7209 @section @code{LBOUND} --- Lower dimension bounds of an array
7211 @cindex array, lower bound
7214 @item @emph{Description}:
7215 Returns the lower bounds of an array, or a single lower bound
7216 along the @var{DIM} dimension.
7217 @item @emph{Standard}:
7218 Fortran 95 and later, with @var{KIND} argument Fortran 2003 and later
7223 @item @emph{Syntax}:
7224 @code{RESULT = LBOUND(ARRAY [, DIM [, KIND]])}
7226 @item @emph{Arguments}:
7227 @multitable @columnfractions .15 .70
7228 @item @var{ARRAY} @tab Shall be an array, of any type.
7229 @item @var{DIM} @tab (Optional) Shall be a scalar @code{INTEGER}.
7230 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
7231 expression indicating the kind parameter of the result.
7234 @item @emph{Return value}:
7235 The return value is of type @code{INTEGER} and of kind @var{KIND}. If
7236 @var{KIND} is absent, the return value is of default integer kind.
7237 If @var{DIM} is absent, the result is an array of the lower bounds of
7238 @var{ARRAY}. If @var{DIM} is present, the result is a scalar
7239 corresponding to the lower bound of the array along that dimension. If
7240 @var{ARRAY} is an expression rather than a whole array or array
7241 structure component, or if it has a zero extent along the relevant
7242 dimension, the lower bound is taken to be 1.
7244 @item @emph{See also}:
7245 @ref{UBOUND}, @ref{LCOBOUND}
7251 @section @code{LCOBOUND} --- Lower codimension bounds of an array
7253 @cindex coarray, lower bound
7256 @item @emph{Description}:
7257 Returns the lower bounds of a coarray, or a single lower cobound
7258 along the @var{DIM} codimension.
7259 @item @emph{Standard}:
7260 Fortran 2008 and later
7265 @item @emph{Syntax}:
7266 @code{RESULT = LCOBOUND(COARRAY [, DIM [, KIND]])}
7268 @item @emph{Arguments}:
7269 @multitable @columnfractions .15 .70
7270 @item @var{ARRAY} @tab Shall be an coarray, of any type.
7271 @item @var{DIM} @tab (Optional) Shall be a scalar @code{INTEGER}.
7272 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
7273 expression indicating the kind parameter of the result.
7276 @item @emph{Return value}:
7277 The return value is of type @code{INTEGER} and of kind @var{KIND}. If
7278 @var{KIND} is absent, the return value is of default integer kind.
7279 If @var{DIM} is absent, the result is an array of the lower cobounds of
7280 @var{COARRAY}. If @var{DIM} is present, the result is a scalar
7281 corresponding to the lower cobound of the array along that codimension.
7283 @item @emph{See also}:
7284 @ref{UCOBOUND}, @ref{LBOUND}
7290 @section @code{LEADZ} --- Number of leading zero bits of an integer
7295 @item @emph{Description}:
7296 @code{LEADZ} returns the number of leading zero bits of an integer.
7298 @item @emph{Standard}:
7299 Fortran 2008 and later
7304 @item @emph{Syntax}:
7305 @code{RESULT = LEADZ(I)}
7307 @item @emph{Arguments}:
7308 @multitable @columnfractions .15 .70
7309 @item @var{I} @tab Shall be of type @code{INTEGER}.
7312 @item @emph{Return value}:
7313 The type of the return value is the default @code{INTEGER}.
7314 If all the bits of @code{I} are zero, the result value is @code{BIT_SIZE(I)}.
7316 @item @emph{Example}:
7319 WRITE (*,*) BIT_SIZE(1) ! prints 32
7320 WRITE (*,*) LEADZ(1) ! prints 31
7324 @item @emph{See also}:
7325 @ref{BIT_SIZE}, @ref{TRAILZ}, @ref{POPCNT}, @ref{POPPAR}
7331 @section @code{LEN} --- Length of a character entity
7333 @cindex string, length
7336 @item @emph{Description}:
7337 Returns the length of a character string. If @var{STRING} is an array,
7338 the length of an element of @var{STRING} is returned. Note that
7339 @var{STRING} need not be defined when this intrinsic is invoked, since
7340 only the length, not the content, of @var{STRING} is needed.
7342 @item @emph{Standard}:
7343 Fortran 77 and later, with @var{KIND} argument Fortran 2003 and later
7348 @item @emph{Syntax}:
7349 @code{L = LEN(STRING [, KIND])}
7351 @item @emph{Arguments}:
7352 @multitable @columnfractions .15 .70
7353 @item @var{STRING} @tab Shall be a scalar or array of type
7354 @code{CHARACTER}, with @code{INTENT(IN)}
7355 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
7356 expression indicating the kind parameter of the result.
7359 @item @emph{Return value}:
7360 The return value is of type @code{INTEGER} and of kind @var{KIND}. If
7361 @var{KIND} is absent, the return value is of default integer kind.
7364 @item @emph{Specific names}:
7365 @multitable @columnfractions .20 .20 .20 .25
7366 @item Name @tab Argument @tab Return type @tab Standard
7367 @item @code{LEN(STRING)} @tab @code{CHARACTER} @tab @code{INTEGER} @tab Fortran 77 and later
7371 @item @emph{See also}:
7372 @ref{LEN_TRIM}, @ref{ADJUSTL}, @ref{ADJUSTR}
7378 @section @code{LEN_TRIM} --- Length of a character entity without trailing blank characters
7380 @cindex string, length, without trailing whitespace
7383 @item @emph{Description}:
7384 Returns the length of a character string, ignoring any trailing blanks.
7386 @item @emph{Standard}:
7387 Fortran 95 and later, with @var{KIND} argument Fortran 2003 and later
7392 @item @emph{Syntax}:
7393 @code{RESULT = LEN_TRIM(STRING [, KIND])}
7395 @item @emph{Arguments}:
7396 @multitable @columnfractions .15 .70
7397 @item @var{STRING} @tab Shall be a scalar of type @code{CHARACTER},
7398 with @code{INTENT(IN)}
7399 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
7400 expression indicating the kind parameter of the result.
7403 @item @emph{Return value}:
7404 The return value is of type @code{INTEGER} and of kind @var{KIND}. If
7405 @var{KIND} is absent, the return value is of default integer kind.
7407 @item @emph{See also}:
7408 @ref{LEN}, @ref{ADJUSTL}, @ref{ADJUSTR}
7414 @section @code{LGE} --- Lexical greater than or equal
7416 @cindex lexical comparison of strings
7417 @cindex string, comparison
7420 @item @emph{Description}:
7421 Determines whether one string is lexically greater than or equal to
7422 another string, where the two strings are interpreted as containing
7423 ASCII character codes. If the String A and String B are not the same
7424 length, the shorter is compared as if spaces were appended to it to form
7425 a value that has the same length as the longer.
7427 In general, the lexical comparison intrinsics @code{LGE}, @code{LGT},
7428 @code{LLE}, and @code{LLT} differ from the corresponding intrinsic
7429 operators @code{.GE.}, @code{.GT.}, @code{.LE.}, and @code{.LT.}, in
7430 that the latter use the processor's character ordering (which is not
7431 ASCII on some targets), whereas the former always use the ASCII
7434 @item @emph{Standard}:
7435 Fortran 77 and later
7440 @item @emph{Syntax}:
7441 @code{RESULT = LGE(STRING_A, STRING_B)}
7443 @item @emph{Arguments}:
7444 @multitable @columnfractions .15 .70
7445 @item @var{STRING_A} @tab Shall be of default @code{CHARACTER} type.
7446 @item @var{STRING_B} @tab Shall be of default @code{CHARACTER} type.
7449 @item @emph{Return value}:
7450 Returns @code{.TRUE.} if @code{STRING_A >= STRING_B}, and @code{.FALSE.}
7451 otherwise, based on the ASCII ordering.
7453 @item @emph{Specific names}:
7454 @multitable @columnfractions .20 .20 .20 .25
7455 @item Name @tab Argument @tab Return type @tab Standard
7456 @item @code{LGE(STRING_A, STRING_B)} @tab @code{CHARACTER} @tab @code{LOGICAL} @tab Fortran 77 and later
7459 @item @emph{See also}:
7460 @ref{LGT}, @ref{LLE}, @ref{LLT}
7466 @section @code{LGT} --- Lexical greater than
7468 @cindex lexical comparison of strings
7469 @cindex string, comparison
7472 @item @emph{Description}:
7473 Determines whether one string is lexically greater than another string,
7474 where the two strings are interpreted as containing ASCII character
7475 codes. If the String A and String B are not the same length, the
7476 shorter is compared as if spaces were appended to it to form a value
7477 that has the same length as the longer.
7479 In general, the lexical comparison intrinsics @code{LGE}, @code{LGT},
7480 @code{LLE}, and @code{LLT} differ from the corresponding intrinsic
7481 operators @code{.GE.}, @code{.GT.}, @code{.LE.}, and @code{.LT.}, in
7482 that the latter use the processor's character ordering (which is not
7483 ASCII on some targets), whereas the former always use the ASCII
7486 @item @emph{Standard}:
7487 Fortran 77 and later
7492 @item @emph{Syntax}:
7493 @code{RESULT = LGT(STRING_A, STRING_B)}
7495 @item @emph{Arguments}:
7496 @multitable @columnfractions .15 .70
7497 @item @var{STRING_A} @tab Shall be of default @code{CHARACTER} type.
7498 @item @var{STRING_B} @tab Shall be of default @code{CHARACTER} type.
7501 @item @emph{Return value}:
7502 Returns @code{.TRUE.} if @code{STRING_A > STRING_B}, and @code{.FALSE.}
7503 otherwise, based on the ASCII ordering.
7505 @item @emph{Specific names}:
7506 @multitable @columnfractions .20 .20 .20 .25
7507 @item Name @tab Argument @tab Return type @tab Standard
7508 @item @code{LGT(STRING_A, STRING_B)} @tab @code{CHARACTER} @tab @code{LOGICAL} @tab Fortran 77 and later
7511 @item @emph{See also}:
7512 @ref{LGE}, @ref{LLE}, @ref{LLT}
7518 @section @code{LINK} --- Create a hard link
7520 @cindex file system, create link
7521 @cindex file system, hard link
7524 @item @emph{Description}:
7525 Makes a (hard) link from file @var{PATH1} to @var{PATH2}. A null
7526 character (@code{CHAR(0)}) can be used to mark the end of the names in
7527 @var{PATH1} and @var{PATH2}; otherwise, trailing blanks in the file
7528 names are ignored. If the @var{STATUS} argument is supplied, it
7529 contains 0 on success or a nonzero error code upon return; see
7532 This intrinsic is provided in both subroutine and function forms;
7533 however, only one form can be used in any given program unit.
7535 @item @emph{Standard}:
7539 Subroutine, function
7541 @item @emph{Syntax}:
7542 @multitable @columnfractions .80
7543 @item @code{CALL LINK(PATH1, PATH2 [, STATUS])}
7544 @item @code{STATUS = LINK(PATH1, PATH2)}
7547 @item @emph{Arguments}:
7548 @multitable @columnfractions .15 .70
7549 @item @var{PATH1} @tab Shall be of default @code{CHARACTER} type.
7550 @item @var{PATH2} @tab Shall be of default @code{CHARACTER} type.
7551 @item @var{STATUS} @tab (Optional) Shall be of default @code{INTEGER} type.
7554 @item @emph{See also}:
7555 @ref{SYMLNK}, @ref{UNLINK}
7561 @section @code{LLE} --- Lexical less than or equal
7563 @cindex lexical comparison of strings
7564 @cindex string, comparison
7567 @item @emph{Description}:
7568 Determines whether one string is lexically less than or equal to another
7569 string, where the two strings are interpreted as containing ASCII
7570 character codes. If the String A and String B are not the same length,
7571 the shorter is compared as if spaces were appended to it to form a value
7572 that has the same length as the longer.
7574 In general, the lexical comparison intrinsics @code{LGE}, @code{LGT},
7575 @code{LLE}, and @code{LLT} differ from the corresponding intrinsic
7576 operators @code{.GE.}, @code{.GT.}, @code{.LE.}, and @code{.LT.}, in
7577 that the latter use the processor's character ordering (which is not
7578 ASCII on some targets), whereas the former always use the ASCII
7581 @item @emph{Standard}:
7582 Fortran 77 and later
7587 @item @emph{Syntax}:
7588 @code{RESULT = LLE(STRING_A, STRING_B)}
7590 @item @emph{Arguments}:
7591 @multitable @columnfractions .15 .70
7592 @item @var{STRING_A} @tab Shall be of default @code{CHARACTER} type.
7593 @item @var{STRING_B} @tab Shall be of default @code{CHARACTER} type.
7596 @item @emph{Return value}:
7597 Returns @code{.TRUE.} if @code{STRING_A <= STRING_B}, and @code{.FALSE.}
7598 otherwise, based on the ASCII ordering.
7600 @item @emph{Specific names}:
7601 @multitable @columnfractions .20 .20 .20 .25
7602 @item Name @tab Argument @tab Return type @tab Standard
7603 @item @code{LLE(STRING_A, STRING_B)} @tab @code{CHARACTER} @tab @code{LOGICAL} @tab Fortran 77 and later
7606 @item @emph{See also}:
7607 @ref{LGE}, @ref{LGT}, @ref{LLT}
7613 @section @code{LLT} --- Lexical less than
7615 @cindex lexical comparison of strings
7616 @cindex string, comparison
7619 @item @emph{Description}:
7620 Determines whether one string is lexically less than another string,
7621 where the two strings are interpreted as containing ASCII character
7622 codes. If the String A and String B are not the same length, the
7623 shorter is compared as if spaces were appended to it to form a value
7624 that has the same length as the longer.
7626 In general, the lexical comparison intrinsics @code{LGE}, @code{LGT},
7627 @code{LLE}, and @code{LLT} differ from the corresponding intrinsic
7628 operators @code{.GE.}, @code{.GT.}, @code{.LE.}, and @code{.LT.}, in
7629 that the latter use the processor's character ordering (which is not
7630 ASCII on some targets), whereas the former always use the ASCII
7633 @item @emph{Standard}:
7634 Fortran 77 and later
7639 @item @emph{Syntax}:
7640 @code{RESULT = LLT(STRING_A, STRING_B)}
7642 @item @emph{Arguments}:
7643 @multitable @columnfractions .15 .70
7644 @item @var{STRING_A} @tab Shall be of default @code{CHARACTER} type.
7645 @item @var{STRING_B} @tab Shall be of default @code{CHARACTER} type.
7648 @item @emph{Return value}:
7649 Returns @code{.TRUE.} if @code{STRING_A < STRING_B}, and @code{.FALSE.}
7650 otherwise, based on the ASCII ordering.
7652 @item @emph{Specific names}:
7653 @multitable @columnfractions .20 .20 .20 .25
7654 @item Name @tab Argument @tab Return type @tab Standard
7655 @item @code{LLT(STRING_A, STRING_B)} @tab @code{CHARACTER} @tab @code{LOGICAL} @tab Fortran 77 and later
7658 @item @emph{See also}:
7659 @ref{LGE}, @ref{LGT}, @ref{LLE}
7665 @section @code{LNBLNK} --- Index of the last non-blank character in a string
7667 @cindex string, find non-blank character
7670 @item @emph{Description}:
7671 Returns the length of a character string, ignoring any trailing blanks.
7672 This is identical to the standard @code{LEN_TRIM} intrinsic, and is only
7673 included for backwards compatibility.
7675 @item @emph{Standard}:
7681 @item @emph{Syntax}:
7682 @code{RESULT = LNBLNK(STRING)}
7684 @item @emph{Arguments}:
7685 @multitable @columnfractions .15 .70
7686 @item @var{STRING} @tab Shall be a scalar of type @code{CHARACTER},
7687 with @code{INTENT(IN)}
7690 @item @emph{Return value}:
7691 The return value is of @code{INTEGER(kind=4)} type.
7693 @item @emph{See also}:
7694 @ref{INDEX intrinsic}, @ref{LEN_TRIM}
7700 @section @code{LOC} --- Returns the address of a variable
7702 @cindex location of a variable in memory
7705 @item @emph{Description}:
7706 @code{LOC(X)} returns the address of @var{X} as an integer.
7708 @item @emph{Standard}:
7714 @item @emph{Syntax}:
7715 @code{RESULT = LOC(X)}
7717 @item @emph{Arguments}:
7718 @multitable @columnfractions .15 .70
7719 @item @var{X} @tab Variable of any type.
7722 @item @emph{Return value}:
7723 The return value is of type @code{INTEGER}, with a @code{KIND}
7724 corresponding to the size (in bytes) of a memory address on the target
7727 @item @emph{Example}:
7734 end program test_loc
7741 @section @code{LOG} --- Logarithm function
7748 @cindex exponential function, inverse
7749 @cindex logarithmic function
7752 @item @emph{Description}:
7753 @code{LOG(X)} computes the logarithm of @var{X}.
7755 @item @emph{Standard}:
7756 Fortran 77 and later
7761 @item @emph{Syntax}:
7762 @code{RESULT = LOG(X)}
7764 @item @emph{Arguments}:
7765 @multitable @columnfractions .15 .70
7766 @item @var{X} @tab The type shall be @code{REAL} or
7770 @item @emph{Return value}:
7771 The return value is of type @code{REAL} or @code{COMPLEX}.
7772 The kind type parameter is the same as @var{X}.
7773 If @var{X} is @code{COMPLEX}, the imaginary part @math{\omega} is in the range
7774 @math{-\pi \leq \omega \leq \pi}.
7776 @item @emph{Example}:
7779 real(8) :: x = 1.0_8
7780 complex :: z = (1.0, 2.0)
7783 end program test_log
7786 @item @emph{Specific names}:
7787 @multitable @columnfractions .20 .20 .20 .25
7788 @item Name @tab Argument @tab Return type @tab Standard
7789 @item @code{ALOG(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab f95, gnu
7790 @item @code{DLOG(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab f95, gnu
7791 @item @code{CLOG(X)} @tab @code{COMPLEX(4) X} @tab @code{COMPLEX(4)} @tab f95, gnu
7792 @item @code{ZLOG(X)} @tab @code{COMPLEX(8) X} @tab @code{COMPLEX(8)} @tab f95, gnu
7793 @item @code{CDLOG(X)} @tab @code{COMPLEX(8) X} @tab @code{COMPLEX(8)} @tab f95, gnu
7800 @section @code{LOG10} --- Base 10 logarithm function
7804 @cindex exponential function, inverse
7805 @cindex logarithmic function
7808 @item @emph{Description}:
7809 @code{LOG10(X)} computes the base 10 logarithm of @var{X}.
7811 @item @emph{Standard}:
7812 Fortran 77 and later
7817 @item @emph{Syntax}:
7818 @code{RESULT = LOG10(X)}
7820 @item @emph{Arguments}:
7821 @multitable @columnfractions .15 .70
7822 @item @var{X} @tab The type shall be @code{REAL}.
7825 @item @emph{Return value}:
7826 The return value is of type @code{REAL} or @code{COMPLEX}.
7827 The kind type parameter is the same as @var{X}.
7829 @item @emph{Example}:
7832 real(8) :: x = 10.0_8
7834 end program test_log10
7837 @item @emph{Specific names}:
7838 @multitable @columnfractions .20 .20 .20 .25
7839 @item Name @tab Argument @tab Return type @tab Standard
7840 @item @code{ALOG10(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab Fortran 95 and later
7841 @item @code{DLOG10(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab Fortran 95 and later
7848 @section @code{LOG_GAMMA} --- Logarithm of the Gamma function
7853 @cindex Gamma function, logarithm of
7856 @item @emph{Description}:
7857 @code{LOG_GAMMA(X)} computes the natural logarithm of the absolute value
7858 of the Gamma (@math{\Gamma}) function.
7860 @item @emph{Standard}:
7861 Fortran 2008 and later
7866 @item @emph{Syntax}:
7867 @code{X = LOG_GAMMA(X)}
7869 @item @emph{Arguments}:
7870 @multitable @columnfractions .15 .70
7871 @item @var{X} @tab Shall be of type @code{REAL} and neither zero
7872 nor a negative integer.
7875 @item @emph{Return value}:
7876 The return value is of type @code{REAL} of the same kind as @var{X}.
7878 @item @emph{Example}:
7880 program test_log_gamma
7882 x = lgamma(x) ! returns 0.0
7883 end program test_log_gamma
7886 @item @emph{Specific names}:
7887 @multitable @columnfractions .20 .20 .20 .25
7888 @item Name @tab Argument @tab Return type @tab Standard
7889 @item @code{LGAMMA(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab GNU Extension
7890 @item @code{ALGAMA(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab GNU Extension
7891 @item @code{DLGAMA(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU Extension
7894 @item @emph{See also}:
7895 Gamma function: @ref{GAMMA}
7902 @section @code{LOGICAL} --- Convert to logical type
7904 @cindex conversion, to logical
7907 @item @emph{Description}:
7908 Converts one kind of @code{LOGICAL} variable to another.
7910 @item @emph{Standard}:
7911 Fortran 95 and later
7916 @item @emph{Syntax}:
7917 @code{RESULT = LOGICAL(L [, KIND])}
7919 @item @emph{Arguments}:
7920 @multitable @columnfractions .15 .70
7921 @item @var{L} @tab The type shall be @code{LOGICAL}.
7922 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
7923 expression indicating the kind parameter of the result.
7926 @item @emph{Return value}:
7927 The return value is a @code{LOGICAL} value equal to @var{L}, with a
7928 kind corresponding to @var{KIND}, or of the default logical kind if
7929 @var{KIND} is not given.
7931 @item @emph{See also}:
7932 @ref{INT}, @ref{REAL}, @ref{CMPLX}
7938 @section @code{LONG} --- Convert to integer type
7940 @cindex conversion, to integer
7943 @item @emph{Description}:
7944 Convert to a @code{KIND=4} integer type, which is the same size as a C
7945 @code{long} integer. This is equivalent to the standard @code{INT}
7946 intrinsic with an optional argument of @code{KIND=4}, and is only
7947 included for backwards compatibility.
7949 @item @emph{Standard}:
7955 @item @emph{Syntax}:
7956 @code{RESULT = LONG(A)}
7958 @item @emph{Arguments}:
7959 @multitable @columnfractions .15 .70
7960 @item @var{A} @tab Shall be of type @code{INTEGER},
7961 @code{REAL}, or @code{COMPLEX}.
7964 @item @emph{Return value}:
7965 The return value is a @code{INTEGER(4)} variable.
7967 @item @emph{See also}:
7968 @ref{INT}, @ref{INT2}, @ref{INT8}
7974 @section @code{LSHIFT} --- Left shift bits
7976 @cindex bits, shift left
7979 @item @emph{Description}:
7980 @code{LSHIFT} returns a value corresponding to @var{I} with all of the
7981 bits shifted left by @var{SHIFT} places. If the absolute value of
7982 @var{SHIFT} is greater than @code{BIT_SIZE(I)}, the value is undefined.
7983 Bits shifted out from the left end are lost; zeros are shifted in from
7986 This function has been superseded by the @code{ISHFT} intrinsic, which
7987 is standard in Fortran 95 and later, and the @code{SHIFTL} intrinsic,
7988 which is standard in Fortran 2008 and later.
7990 @item @emph{Standard}:
7996 @item @emph{Syntax}:
7997 @code{RESULT = LSHIFT(I, SHIFT)}
7999 @item @emph{Arguments}:
8000 @multitable @columnfractions .15 .70
8001 @item @var{I} @tab The type shall be @code{INTEGER}.
8002 @item @var{SHIFT} @tab The type shall be @code{INTEGER}.
8005 @item @emph{Return value}:
8006 The return value is of type @code{INTEGER} and of the same kind as
8009 @item @emph{See also}:
8010 @ref{ISHFT}, @ref{ISHFTC}, @ref{RSHIFT}, @ref{SHIFTA}, @ref{SHIFTL},
8018 @section @code{LSTAT} --- Get file status
8020 @cindex file system, file status
8023 @item @emph{Description}:
8024 @code{LSTAT} is identical to @ref{STAT}, except that if path is a
8025 symbolic link, then the link itself is statted, not the file that it
8028 The elements in @code{VALUES} are the same as described by @ref{STAT}.
8030 This intrinsic is provided in both subroutine and function forms;
8031 however, only one form can be used in any given program unit.
8033 @item @emph{Standard}:
8037 Subroutine, function
8039 @item @emph{Syntax}:
8040 @multitable @columnfractions .80
8041 @item @code{CALL LSTAT(NAME, VALUES [, STATUS])}
8042 @item @code{STATUS = LSTAT(NAME, VALUES)}
8045 @item @emph{Arguments}:
8046 @multitable @columnfractions .15 .70
8047 @item @var{NAME} @tab The type shall be @code{CHARACTER} of the default
8048 kind, a valid path within the file system.
8049 @item @var{VALUES} @tab The type shall be @code{INTEGER(4), DIMENSION(13)}.
8050 @item @var{STATUS} @tab (Optional) status flag of type @code{INTEGER(4)}.
8051 Returns 0 on success and a system specific error code otherwise.
8054 @item @emph{Example}:
8055 See @ref{STAT} for an example.
8057 @item @emph{See also}:
8058 To stat an open file: @ref{FSTAT}, to stat a file: @ref{STAT}
8064 @section @code{LTIME} --- Convert time to local time info
8066 @cindex time, conversion to local time info
8069 @item @emph{Description}:
8070 Given a system time value @var{TIME} (as provided by the @code{TIME8()}
8071 intrinsic), fills @var{VALUES} with values extracted from it appropriate
8072 to the local time zone using @code{localtime(3)}.
8074 @item @emph{Standard}:
8080 @item @emph{Syntax}:
8081 @code{CALL LTIME(TIME, VALUES)}
8083 @item @emph{Arguments}:
8084 @multitable @columnfractions .15 .70
8085 @item @var{TIME} @tab An @code{INTEGER} scalar expression
8086 corresponding to a system time, with @code{INTENT(IN)}.
8087 @item @var{VALUES} @tab A default @code{INTEGER} array with 9 elements,
8088 with @code{INTENT(OUT)}.
8091 @item @emph{Return value}:
8092 The elements of @var{VALUES} are assigned as follows:
8094 @item Seconds after the minute, range 0--59 or 0--61 to allow for leap
8096 @item Minutes after the hour, range 0--59
8097 @item Hours past midnight, range 0--23
8098 @item Day of month, range 0--31
8099 @item Number of months since January, range 0--12
8100 @item Years since 1900
8101 @item Number of days since Sunday, range 0--6
8102 @item Days since January 1
8103 @item Daylight savings indicator: positive if daylight savings is in
8104 effect, zero if not, and negative if the information is not available.
8107 @item @emph{See also}:
8108 @ref{CTIME}, @ref{GMTIME}, @ref{TIME}, @ref{TIME8}
8115 @section @code{MALLOC} --- Allocate dynamic memory
8117 @cindex pointer, cray
8120 @item @emph{Description}:
8121 @code{MALLOC(SIZE)} allocates @var{SIZE} bytes of dynamic memory and
8122 returns the address of the allocated memory. The @code{MALLOC} intrinsic
8123 is an extension intended to be used with Cray pointers, and is provided
8124 in GNU Fortran to allow the user to compile legacy code. For new code
8125 using Fortran 95 pointers, the memory allocation intrinsic is
8128 @item @emph{Standard}:
8134 @item @emph{Syntax}:
8135 @code{PTR = MALLOC(SIZE)}
8137 @item @emph{Arguments}:
8138 @multitable @columnfractions .15 .70
8139 @item @var{SIZE} @tab The type shall be @code{INTEGER}.
8142 @item @emph{Return value}:
8143 The return value is of type @code{INTEGER(K)}, with @var{K} such that
8144 variables of type @code{INTEGER(K)} have the same size as
8145 C pointers (@code{sizeof(void *)}).
8147 @item @emph{Example}:
8148 The following example demonstrates the use of @code{MALLOC} and
8149 @code{FREE} with Cray pointers.
8158 ptr_x = malloc(20*8)
8160 x(i) = sqrt(1.0d0 / i)
8168 end program test_malloc
8171 @item @emph{See also}:
8178 @section @code{MASKL} --- Left justified mask
8180 @cindex mask, left justified
8183 @item @emph{Description}:
8184 @code{MASKL(I[, KIND])} has its leftmost @var{I} bits set to 1, and the
8185 remaining bits set to 0.
8187 @item @emph{Standard}:
8188 Fortran 2008 and later
8193 @item @emph{Syntax}:
8194 @code{RESULT = MASKL(I[, KIND])}
8196 @item @emph{Arguments}:
8197 @multitable @columnfractions .15 .70
8198 @item @var{I} @tab Shall be of type @code{INTEGER}.
8199 @item @var{KIND} @tab Shall be a scalar constant expression of type
8203 @item @emph{Return value}:
8204 The return value is of type @code{INTEGER}. If @var{KIND} is present, it
8205 specifies the kind value of the return type; otherwise, it is of the
8206 default integer kind.
8208 @item @emph{See also}:
8215 @section @code{MASKR} --- Right justified mask
8217 @cindex mask, right justified
8220 @item @emph{Description}:
8221 @code{MASKL(I[, KIND])} has its rightmost @var{I} bits set to 1, and the
8222 remaining bits set to 0.
8224 @item @emph{Standard}:
8225 Fortran 2008 and later
8230 @item @emph{Syntax}:
8231 @code{RESULT = MASKR(I[, KIND])}
8233 @item @emph{Arguments}:
8234 @multitable @columnfractions .15 .70
8235 @item @var{I} @tab Shall be of type @code{INTEGER}.
8236 @item @var{KIND} @tab Shall be a scalar constant expression of type
8240 @item @emph{Return value}:
8241 The return value is of type @code{INTEGER}. If @var{KIND} is present, it
8242 specifies the kind value of the return type; otherwise, it is of the
8243 default integer kind.
8245 @item @emph{See also}:
8252 @section @code{MATMUL} --- matrix multiplication
8254 @cindex matrix multiplication
8255 @cindex product, matrix
8258 @item @emph{Description}:
8259 Performs a matrix multiplication on numeric or logical arguments.
8261 @item @emph{Standard}:
8262 Fortran 95 and later
8265 Transformational function
8267 @item @emph{Syntax}:
8268 @code{RESULT = MATMUL(MATRIX_A, MATRIX_B)}
8270 @item @emph{Arguments}:
8271 @multitable @columnfractions .15 .70
8272 @item @var{MATRIX_A} @tab An array of @code{INTEGER},
8273 @code{REAL}, @code{COMPLEX}, or @code{LOGICAL} type, with a rank of
8275 @item @var{MATRIX_B} @tab An array of @code{INTEGER},
8276 @code{REAL}, or @code{COMPLEX} type if @var{MATRIX_A} is of a numeric
8277 type; otherwise, an array of @code{LOGICAL} type. The rank shall be one
8278 or two, and the first (or only) dimension of @var{MATRIX_B} shall be
8279 equal to the last (or only) dimension of @var{MATRIX_A}.
8282 @item @emph{Return value}:
8283 The matrix product of @var{MATRIX_A} and @var{MATRIX_B}. The type and
8284 kind of the result follow the usual type and kind promotion rules, as
8285 for the @code{*} or @code{.AND.} operators.
8287 @item @emph{See also}:
8293 @section @code{MAX} --- Maximum value of an argument list
8300 @cindex maximum value
8303 @item @emph{Description}:
8304 Returns the argument with the largest (most positive) value.
8306 @item @emph{Standard}:
8307 Fortran 77 and later
8312 @item @emph{Syntax}:
8313 @code{RESULT = MAX(A1, A2 [, A3 [, ...]])}
8315 @item @emph{Arguments}:
8316 @multitable @columnfractions .15 .70
8317 @item @var{A1} @tab The type shall be @code{INTEGER} or
8319 @item @var{A2}, @var{A3}, ... @tab An expression of the same type and kind
8320 as @var{A1}. (As a GNU extension, arguments of different kinds are
8324 @item @emph{Return value}:
8325 The return value corresponds to the maximum value among the arguments,
8326 and has the same type and kind as the first argument.
8328 @item @emph{Specific names}:
8329 @multitable @columnfractions .20 .20 .20 .25
8330 @item Name @tab Argument @tab Return type @tab Standard
8331 @item @code{MAX0(A1)} @tab @code{INTEGER(4) A1} @tab @code{INTEGER(4)} @tab Fortran 77 and later
8332 @item @code{AMAX0(A1)} @tab @code{INTEGER(4) A1} @tab @code{REAL(MAX(X))} @tab Fortran 77 and later
8333 @item @code{MAX1(A1)} @tab @code{REAL A1} @tab @code{INT(MAX(X))} @tab Fortran 77 and later
8334 @item @code{AMAX1(A1)} @tab @code{REAL(4) A1} @tab @code{REAL(4)} @tab Fortran 77 and later
8335 @item @code{DMAX1(A1)} @tab @code{REAL(8) A1} @tab @code{REAL(8)} @tab Fortran 77 and later
8338 @item @emph{See also}:
8339 @ref{MAXLOC} @ref{MAXVAL}, @ref{MIN}
8346 @section @code{MAXEXPONENT} --- Maximum exponent of a real kind
8347 @fnindex MAXEXPONENT
8348 @cindex model representation, maximum exponent
8351 @item @emph{Description}:
8352 @code{MAXEXPONENT(X)} returns the maximum exponent in the model of the
8355 @item @emph{Standard}:
8356 Fortran 95 and later
8361 @item @emph{Syntax}:
8362 @code{RESULT = MAXEXPONENT(X)}
8364 @item @emph{Arguments}:
8365 @multitable @columnfractions .15 .70
8366 @item @var{X} @tab Shall be of type @code{REAL}.
8369 @item @emph{Return value}:
8370 The return value is of type @code{INTEGER} and of the default integer
8373 @item @emph{Example}:
8379 print *, minexponent(x), maxexponent(x)
8380 print *, minexponent(y), maxexponent(y)
8381 end program exponents
8388 @section @code{MAXLOC} --- Location of the maximum value within an array
8390 @cindex array, location of maximum element
8393 @item @emph{Description}:
8394 Determines the location of the element in the array with the maximum
8395 value, or, if the @var{DIM} argument is supplied, determines the
8396 locations of the maximum element along each row of the array in the
8397 @var{DIM} direction. If @var{MASK} is present, only the elements for
8398 which @var{MASK} is @code{.TRUE.} are considered. If more than one
8399 element in the array has the maximum value, the location returned is
8400 that of the first such element in array element order. If the array has
8401 zero size, or all of the elements of @var{MASK} are @code{.FALSE.}, then
8402 the result is an array of zeroes. Similarly, if @var{DIM} is supplied
8403 and all of the elements of @var{MASK} along a given row are zero, the
8404 result value for that row is zero.
8406 @item @emph{Standard}:
8407 Fortran 95 and later
8410 Transformational function
8412 @item @emph{Syntax}:
8413 @multitable @columnfractions .80
8414 @item @code{RESULT = MAXLOC(ARRAY, DIM [, MASK])}
8415 @item @code{RESULT = MAXLOC(ARRAY [, MASK])}
8418 @item @emph{Arguments}:
8419 @multitable @columnfractions .15 .70
8420 @item @var{ARRAY} @tab Shall be an array of type @code{INTEGER} or
8422 @item @var{DIM} @tab (Optional) Shall be a scalar of type
8423 @code{INTEGER}, with a value between one and the rank of @var{ARRAY},
8424 inclusive. It may not be an optional dummy argument.
8425 @item @var{MASK} @tab Shall be an array of type @code{LOGICAL},
8426 and conformable with @var{ARRAY}.
8429 @item @emph{Return value}:
8430 If @var{DIM} is absent, the result is a rank-one array with a length
8431 equal to the rank of @var{ARRAY}. If @var{DIM} is present, the result
8432 is an array with a rank one less than the rank of @var{ARRAY}, and a
8433 size corresponding to the size of @var{ARRAY} with the @var{DIM}
8434 dimension removed. If @var{DIM} is present and @var{ARRAY} has a rank
8435 of one, the result is a scalar. In all cases, the result is of default
8436 @code{INTEGER} type.
8438 @item @emph{See also}:
8439 @ref{MAX}, @ref{MAXVAL}
8446 @section @code{MAXVAL} --- Maximum value of an array
8448 @cindex array, maximum value
8449 @cindex maximum value
8452 @item @emph{Description}:
8453 Determines the maximum value of the elements in an array value, or, if
8454 the @var{DIM} argument is supplied, determines the maximum value along
8455 each row of the array in the @var{DIM} direction. If @var{MASK} is
8456 present, only the elements for which @var{MASK} is @code{.TRUE.} are
8457 considered. If the array has zero size, or all of the elements of
8458 @var{MASK} are @code{.FALSE.}, then the result is @code{-HUGE(ARRAY)}
8459 if @var{ARRAY} is numeric, or a string of nulls if @var{ARRAY} is of character
8462 @item @emph{Standard}:
8463 Fortran 95 and later
8466 Transformational function
8468 @item @emph{Syntax}:
8469 @multitable @columnfractions .80
8470 @item @code{RESULT = MAXVAL(ARRAY, DIM [, MASK])}
8471 @item @code{RESULT = MAXVAL(ARRAY [, MASK])}
8474 @item @emph{Arguments}:
8475 @multitable @columnfractions .15 .70
8476 @item @var{ARRAY} @tab Shall be an array of type @code{INTEGER} or
8478 @item @var{DIM} @tab (Optional) Shall be a scalar of type
8479 @code{INTEGER}, with a value between one and the rank of @var{ARRAY},
8480 inclusive. It may not be an optional dummy argument.
8481 @item @var{MASK} @tab Shall be an array of type @code{LOGICAL},
8482 and conformable with @var{ARRAY}.
8485 @item @emph{Return value}:
8486 If @var{DIM} is absent, or if @var{ARRAY} has a rank of one, the result
8487 is a scalar. If @var{DIM} is present, the result is an array with a
8488 rank one less than the rank of @var{ARRAY}, and a size corresponding to
8489 the size of @var{ARRAY} with the @var{DIM} dimension removed. In all
8490 cases, the result is of the same type and kind as @var{ARRAY}.
8492 @item @emph{See also}:
8493 @ref{MAX}, @ref{MAXLOC}
8499 @section @code{MCLOCK} --- Time function
8501 @cindex time, clock ticks
8505 @item @emph{Description}:
8506 Returns the number of clock ticks since the start of the process, based
8507 on the UNIX function @code{clock(3)}.
8509 This intrinsic is not fully portable, such as to systems with 32-bit
8510 @code{INTEGER} types but supporting times wider than 32 bits. Therefore,
8511 the values returned by this intrinsic might be, or become, negative, or
8512 numerically less than previous values, during a single run of the
8515 @item @emph{Standard}:
8521 @item @emph{Syntax}:
8522 @code{RESULT = MCLOCK()}
8524 @item @emph{Return value}:
8525 The return value is a scalar of type @code{INTEGER(4)}, equal to the
8526 number of clock ticks since the start of the process, or @code{-1} if
8527 the system does not support @code{clock(3)}.
8529 @item @emph{See also}:
8530 @ref{CTIME}, @ref{GMTIME}, @ref{LTIME}, @ref{MCLOCK}, @ref{TIME}
8537 @section @code{MCLOCK8} --- Time function (64-bit)
8539 @cindex time, clock ticks
8543 @item @emph{Description}:
8544 Returns the number of clock ticks since the start of the process, based
8545 on the UNIX function @code{clock(3)}.
8547 @emph{Warning:} this intrinsic does not increase the range of the timing
8548 values over that returned by @code{clock(3)}. On a system with a 32-bit
8549 @code{clock(3)}, @code{MCLOCK8()} will return a 32-bit value, even though
8550 it is converted to a 64-bit @code{INTEGER(8)} value. That means
8551 overflows of the 32-bit value can still occur. Therefore, the values
8552 returned by this intrinsic might be or become negative or numerically
8553 less than previous values during a single run of the compiled program.
8555 @item @emph{Standard}:
8561 @item @emph{Syntax}:
8562 @code{RESULT = MCLOCK8()}
8564 @item @emph{Return value}:
8565 The return value is a scalar of type @code{INTEGER(8)}, equal to the
8566 number of clock ticks since the start of the process, or @code{-1} if
8567 the system does not support @code{clock(3)}.
8569 @item @emph{See also}:
8570 @ref{CTIME}, @ref{GMTIME}, @ref{LTIME}, @ref{MCLOCK}, @ref{TIME8}
8577 @section @code{MERGE} --- Merge variables
8579 @cindex array, merge arrays
8580 @cindex array, combine arrays
8583 @item @emph{Description}:
8584 Select values from two arrays according to a logical mask. The result
8585 is equal to @var{TSOURCE} if @var{MASK} is @code{.TRUE.}, or equal to
8586 @var{FSOURCE} if it is @code{.FALSE.}.
8588 @item @emph{Standard}:
8589 Fortran 95 and later
8594 @item @emph{Syntax}:
8595 @code{RESULT = MERGE(TSOURCE, FSOURCE, MASK)}
8597 @item @emph{Arguments}:
8598 @multitable @columnfractions .15 .70
8599 @item @var{TSOURCE} @tab May be of any type.
8600 @item @var{FSOURCE} @tab Shall be of the same type and type parameters
8602 @item @var{MASK} @tab Shall be of type @code{LOGICAL}.
8605 @item @emph{Return value}:
8606 The result is of the same type and type parameters as @var{TSOURCE}.
8613 @section @code{MERGE_BITS} --- Merge of bits under mask
8618 @item @emph{Description}:
8619 @code{MERGE_BITS(I, J, MASK)} merges the bits of @var{I} and @var{J}
8620 as determined by the mask. The i-th bit of the result is equal to the
8621 i-th bit of @var{I} if the i-th bit of @var{MASK} is 1; it is equal to
8622 the i-th bit of @var{J} otherwise.
8624 @item @emph{Standard}:
8625 Fortran 2008 and later
8630 @item @emph{Syntax}:
8631 @code{RESULT = MERGE_BITS(I, J, MASK)}
8633 @item @emph{Arguments}:
8634 @multitable @columnfractions .15 .70
8635 @item @var{I} @tab Shall be of type @code{INTEGER}.
8636 @item @var{J} @tab Shall be of type @code{INTEGER} and of the same
8638 @item @var{MASK} @tab Shall be of type @code{INTEGER} and of the same
8642 @item @emph{Return value}:
8643 The result is of the same type and kind as @var{I}.
8650 @section @code{MIN} --- Minimum value of an argument list
8657 @cindex minimum value
8660 @item @emph{Description}:
8661 Returns the argument with the smallest (most negative) value.
8663 @item @emph{Standard}:
8664 Fortran 77 and later
8669 @item @emph{Syntax}:
8670 @code{RESULT = MIN(A1, A2 [, A3, ...])}
8672 @item @emph{Arguments}:
8673 @multitable @columnfractions .15 .70
8674 @item @var{A1} @tab The type shall be @code{INTEGER} or
8676 @item @var{A2}, @var{A3}, ... @tab An expression of the same type and kind
8677 as @var{A1}. (As a GNU extension, arguments of different kinds are
8681 @item @emph{Return value}:
8682 The return value corresponds to the maximum value among the arguments,
8683 and has the same type and kind as the first argument.
8685 @item @emph{Specific names}:
8686 @multitable @columnfractions .20 .20 .20 .25
8687 @item Name @tab Argument @tab Return type @tab Standard
8688 @item @code{MIN0(A1)} @tab @code{INTEGER(4) A1} @tab @code{INTEGER(4)} @tab Fortran 77 and later
8689 @item @code{AMIN0(A1)} @tab @code{INTEGER(4) A1} @tab @code{REAL(4)} @tab Fortran 77 and later
8690 @item @code{MIN1(A1)} @tab @code{REAL A1} @tab @code{INTEGER(4)} @tab Fortran 77 and later
8691 @item @code{AMIN1(A1)} @tab @code{REAL(4) A1} @tab @code{REAL(4)} @tab Fortran 77 and later
8692 @item @code{DMIN1(A1)} @tab @code{REAL(8) A1} @tab @code{REAL(8)} @tab Fortran 77 and later
8695 @item @emph{See also}:
8696 @ref{MAX}, @ref{MINLOC}, @ref{MINVAL}
8702 @section @code{MINEXPONENT} --- Minimum exponent of a real kind
8703 @fnindex MINEXPONENT
8704 @cindex model representation, minimum exponent
8707 @item @emph{Description}:
8708 @code{MINEXPONENT(X)} returns the minimum exponent in the model of the
8711 @item @emph{Standard}:
8712 Fortran 95 and later
8717 @item @emph{Syntax}:
8718 @code{RESULT = MINEXPONENT(X)}
8720 @item @emph{Arguments}:
8721 @multitable @columnfractions .15 .70
8722 @item @var{X} @tab Shall be of type @code{REAL}.
8725 @item @emph{Return value}:
8726 The return value is of type @code{INTEGER} and of the default integer
8729 @item @emph{Example}:
8730 See @code{MAXEXPONENT} for an example.
8736 @section @code{MINLOC} --- Location of the minimum value within an array
8738 @cindex array, location of minimum element
8741 @item @emph{Description}:
8742 Determines the location of the element in the array with the minimum
8743 value, or, if the @var{DIM} argument is supplied, determines the
8744 locations of the minimum element along each row of the array in the
8745 @var{DIM} direction. If @var{MASK} is present, only the elements for
8746 which @var{MASK} is @code{.TRUE.} are considered. If more than one
8747 element in the array has the minimum value, the location returned is
8748 that of the first such element in array element order. If the array has
8749 zero size, or all of the elements of @var{MASK} are @code{.FALSE.}, then
8750 the result is an array of zeroes. Similarly, if @var{DIM} is supplied
8751 and all of the elements of @var{MASK} along a given row are zero, the
8752 result value for that row is zero.
8754 @item @emph{Standard}:
8755 Fortran 95 and later
8758 Transformational function
8760 @item @emph{Syntax}:
8761 @multitable @columnfractions .80
8762 @item @code{RESULT = MINLOC(ARRAY, DIM [, MASK])}
8763 @item @code{RESULT = MINLOC(ARRAY [, MASK])}
8766 @item @emph{Arguments}:
8767 @multitable @columnfractions .15 .70
8768 @item @var{ARRAY} @tab Shall be an array of type @code{INTEGER} or
8770 @item @var{DIM} @tab (Optional) Shall be a scalar of type
8771 @code{INTEGER}, with a value between one and the rank of @var{ARRAY},
8772 inclusive. It may not be an optional dummy argument.
8773 @item @var{MASK} @tab Shall be an array of type @code{LOGICAL},
8774 and conformable with @var{ARRAY}.
8777 @item @emph{Return value}:
8778 If @var{DIM} is absent, the result is a rank-one array with a length
8779 equal to the rank of @var{ARRAY}. If @var{DIM} is present, the result
8780 is an array with a rank one less than the rank of @var{ARRAY}, and a
8781 size corresponding to the size of @var{ARRAY} with the @var{DIM}
8782 dimension removed. If @var{DIM} is present and @var{ARRAY} has a rank
8783 of one, the result is a scalar. In all cases, the result is of default
8784 @code{INTEGER} type.
8786 @item @emph{See also}:
8787 @ref{MIN}, @ref{MINVAL}
8794 @section @code{MINVAL} --- Minimum value of an array
8796 @cindex array, minimum value
8797 @cindex minimum value
8800 @item @emph{Description}:
8801 Determines the minimum value of the elements in an array value, or, if
8802 the @var{DIM} argument is supplied, determines the minimum value along
8803 each row of the array in the @var{DIM} direction. If @var{MASK} is
8804 present, only the elements for which @var{MASK} is @code{.TRUE.} are
8805 considered. If the array has zero size, or all of the elements of
8806 @var{MASK} are @code{.FALSE.}, then the result is @code{HUGE(ARRAY)} if
8807 @var{ARRAY} is numeric, or a string of @code{CHAR(255)} characters if
8808 @var{ARRAY} is of character type.
8810 @item @emph{Standard}:
8811 Fortran 95 and later
8814 Transformational function
8816 @item @emph{Syntax}:
8817 @multitable @columnfractions .80
8818 @item @code{RESULT = MINVAL(ARRAY, DIM [, MASK])}
8819 @item @code{RESULT = MINVAL(ARRAY [, MASK])}
8822 @item @emph{Arguments}:
8823 @multitable @columnfractions .15 .70
8824 @item @var{ARRAY} @tab Shall be an array of type @code{INTEGER} or
8826 @item @var{DIM} @tab (Optional) Shall be a scalar of type
8827 @code{INTEGER}, with a value between one and the rank of @var{ARRAY},
8828 inclusive. It may not be an optional dummy argument.
8829 @item @var{MASK} @tab Shall be an array of type @code{LOGICAL},
8830 and conformable with @var{ARRAY}.
8833 @item @emph{Return value}:
8834 If @var{DIM} is absent, or if @var{ARRAY} has a rank of one, the result
8835 is a scalar. If @var{DIM} is present, the result is an array with a
8836 rank one less than the rank of @var{ARRAY}, and a size corresponding to
8837 the size of @var{ARRAY} with the @var{DIM} dimension removed. In all
8838 cases, the result is of the same type and kind as @var{ARRAY}.
8840 @item @emph{See also}:
8841 @ref{MIN}, @ref{MINLOC}
8848 @section @code{MOD} --- Remainder function
8853 @cindex division, remainder
8856 @item @emph{Description}:
8857 @code{MOD(A,P)} computes the remainder of the division of A by P@. It is
8858 calculated as @code{A - (INT(A/P) * P)}.
8860 @item @emph{Standard}:
8861 Fortran 77 and later
8866 @item @emph{Syntax}:
8867 @code{RESULT = MOD(A, P)}
8869 @item @emph{Arguments}:
8870 @multitable @columnfractions .15 .70
8871 @item @var{A} @tab Shall be a scalar of type @code{INTEGER} or @code{REAL}
8872 @item @var{P} @tab Shall be a scalar of the same type as @var{A} and not
8876 @item @emph{Return value}:
8877 The kind of the return value is the result of cross-promoting
8878 the kinds of the arguments.
8880 @item @emph{Example}:
8884 print *, mod(17.5,5.5)
8885 print *, mod(17.5d0,5.5)
8886 print *, mod(17.5,5.5d0)
8889 print *, mod(-17.5,5.5)
8890 print *, mod(-17.5d0,5.5)
8891 print *, mod(-17.5,5.5d0)
8894 print *, mod(17.5,-5.5)
8895 print *, mod(17.5d0,-5.5)
8896 print *, mod(17.5,-5.5d0)
8897 end program test_mod
8900 @item @emph{Specific names}:
8901 @multitable @columnfractions .20 .20 .20 .25
8902 @item Name @tab Arguments @tab Return type @tab Standard
8903 @item @code{MOD(A,P)} @tab @code{INTEGER A,P} @tab @code{INTEGER} @tab Fortran 95 and later
8904 @item @code{AMOD(A,P)} @tab @code{REAL(4) A,P} @tab @code{REAL(4)} @tab Fortran 95 and later
8905 @item @code{DMOD(A,P)} @tab @code{REAL(8) A,P} @tab @code{REAL(8)} @tab Fortran 95 and later
8912 @section @code{MODULO} --- Modulo function
8915 @cindex division, modulo
8918 @item @emph{Description}:
8919 @code{MODULO(A,P)} computes the @var{A} modulo @var{P}.
8921 @item @emph{Standard}:
8922 Fortran 95 and later
8927 @item @emph{Syntax}:
8928 @code{RESULT = MODULO(A, P)}
8930 @item @emph{Arguments}:
8931 @multitable @columnfractions .15 .70
8932 @item @var{A} @tab Shall be a scalar of type @code{INTEGER} or @code{REAL}
8933 @item @var{P} @tab Shall be a scalar of the same type and kind as @var{A}
8936 @item @emph{Return value}:
8937 The type and kind of the result are those of the arguments.
8939 @item If @var{A} and @var{P} are of type @code{INTEGER}:
8940 @code{MODULO(A,P)} has the value @var{R} such that @code{A=Q*P+R}, where
8941 @var{Q} is an integer and @var{R} is between 0 (inclusive) and @var{P}
8943 @item If @var{A} and @var{P} are of type @code{REAL}:
8944 @code{MODULO(A,P)} has the value of @code{A - FLOOR (A / P) * P}.
8946 In all cases, if @var{P} is zero the result is processor-dependent.
8948 @item @emph{Example}:
8951 print *, modulo(17,3)
8952 print *, modulo(17.5,5.5)
8954 print *, modulo(-17,3)
8955 print *, modulo(-17.5,5.5)
8957 print *, modulo(17,-3)
8958 print *, modulo(17.5,-5.5)
8967 @section @code{MOVE_ALLOC} --- Move allocation from one object to another
8969 @cindex moving allocation
8970 @cindex allocation, moving
8973 @item @emph{Description}:
8974 @code{MOVE_ALLOC(FROM, TO)} moves the allocation from @var{FROM} to
8975 @var{TO}. @var{FROM} will become deallocated in the process.
8977 @item @emph{Standard}:
8978 Fortran 2003 and later
8983 @item @emph{Syntax}:
8984 @code{CALL MOVE_ALLOC(FROM, TO)}
8986 @item @emph{Arguments}:
8987 @multitable @columnfractions .15 .70
8988 @item @var{FROM} @tab @code{ALLOCATABLE}, @code{INTENT(INOUT)}, may be
8989 of any type and kind.
8990 @item @var{TO} @tab @code{ALLOCATABLE}, @code{INTENT(OUT)}, shall be
8991 of the same type, kind and rank as @var{FROM}.
8994 @item @emph{Return value}:
8997 @item @emph{Example}:
8999 program test_move_alloc
9000 integer, allocatable :: a(:), b(:)
9004 call move_alloc(a, b)
9005 print *, allocated(a), allocated(b)
9007 end program test_move_alloc
9014 @section @code{MVBITS} --- Move bits from one integer to another
9019 @item @emph{Description}:
9020 Moves @var{LEN} bits from positions @var{FROMPOS} through
9021 @code{FROMPOS+LEN-1} of @var{FROM} to positions @var{TOPOS} through
9022 @code{TOPOS+LEN-1} of @var{TO}. The portion of argument @var{TO} not
9023 affected by the movement of bits is unchanged. The values of
9024 @code{FROMPOS+LEN-1} and @code{TOPOS+LEN-1} must be less than
9025 @code{BIT_SIZE(FROM)}.
9027 @item @emph{Standard}:
9028 Fortran 95 and later
9031 Elemental subroutine
9033 @item @emph{Syntax}:
9034 @code{CALL MVBITS(FROM, FROMPOS, LEN, TO, TOPOS)}
9036 @item @emph{Arguments}:
9037 @multitable @columnfractions .15 .70
9038 @item @var{FROM} @tab The type shall be @code{INTEGER}.
9039 @item @var{FROMPOS} @tab The type shall be @code{INTEGER}.
9040 @item @var{LEN} @tab The type shall be @code{INTEGER}.
9041 @item @var{TO} @tab The type shall be @code{INTEGER}, of the
9042 same kind as @var{FROM}.
9043 @item @var{TOPOS} @tab The type shall be @code{INTEGER}.
9046 @item @emph{See also}:
9047 @ref{IBCLR}, @ref{IBSET}, @ref{IBITS}, @ref{IAND}, @ref{IOR}, @ref{IEOR}
9053 @section @code{NEAREST} --- Nearest representable number
9055 @cindex real number, nearest different
9056 @cindex floating point, nearest different
9059 @item @emph{Description}:
9060 @code{NEAREST(X, S)} returns the processor-representable number nearest
9061 to @code{X} in the direction indicated by the sign of @code{S}.
9063 @item @emph{Standard}:
9064 Fortran 95 and later
9069 @item @emph{Syntax}:
9070 @code{RESULT = NEAREST(X, S)}
9072 @item @emph{Arguments}:
9073 @multitable @columnfractions .15 .70
9074 @item @var{X} @tab Shall be of type @code{REAL}.
9075 @item @var{S} @tab (Optional) shall be of type @code{REAL} and
9079 @item @emph{Return value}:
9080 The return value is of the same type as @code{X}. If @code{S} is
9081 positive, @code{NEAREST} returns the processor-representable number
9082 greater than @code{X} and nearest to it. If @code{S} is negative,
9083 @code{NEAREST} returns the processor-representable number smaller than
9084 @code{X} and nearest to it.
9086 @item @emph{Example}:
9088 program test_nearest
9090 x = nearest(42.0, 1.0)
9091 y = nearest(42.0, -1.0)
9092 write (*,"(3(G20.15))") x, y, x - y
9093 end program test_nearest
9100 @section @code{NEW_LINE} --- New line character
9103 @cindex output, newline
9106 @item @emph{Description}:
9107 @code{NEW_LINE(C)} returns the new-line character.
9109 @item @emph{Standard}:
9110 Fortran 2003 and later
9115 @item @emph{Syntax}:
9116 @code{RESULT = NEW_LINE(C)}
9118 @item @emph{Arguments}:
9119 @multitable @columnfractions .15 .70
9120 @item @var{C} @tab The argument shall be a scalar or array of the
9121 type @code{CHARACTER}.
9124 @item @emph{Return value}:
9125 Returns a @var{CHARACTER} scalar of length one with the new-line character of
9126 the same kind as parameter @var{C}.
9128 @item @emph{Example}:
9132 write(*,'(A)') 'This is record 1.'//NEW_LINE('A')//'This is record 2.'
9140 @section @code{NINT} --- Nearest whole number
9143 @cindex rounding, nearest whole number
9146 @item @emph{Description}:
9147 @code{NINT(A)} rounds its argument to the nearest whole number.
9149 @item @emph{Standard}:
9150 Fortran 77 and later, with @var{KIND} argument Fortran 90 and later
9155 @item @emph{Syntax}:
9156 @code{RESULT = NINT(A [, KIND])}
9158 @item @emph{Arguments}:
9159 @multitable @columnfractions .15 .70
9160 @item @var{A} @tab The type of the argument shall be @code{REAL}.
9161 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
9162 expression indicating the kind parameter of the result.
9165 @item @emph{Return value}:
9166 Returns @var{A} with the fractional portion of its magnitude eliminated by
9167 rounding to the nearest whole number and with its sign preserved,
9168 converted to an @code{INTEGER} of the default kind.
9170 @item @emph{Example}:
9177 print *, nint(x4), idnint(x8)
9178 end program test_nint
9181 @item @emph{Specific names}:
9182 @multitable @columnfractions .20 .20 .20 .25
9183 @item Name @tab Argument @tab Return Type @tab Standard
9184 @item @code{NINT(A)} @tab @code{REAL(4) A} @tab @code{INTEGER} @tab Fortran 95 and later
9185 @item @code{IDNINT(A)} @tab @code{REAL(8) A} @tab @code{INTEGER} @tab Fortran 95 and later
9188 @item @emph{See also}:
9189 @ref{CEILING}, @ref{FLOOR}
9196 @section @code{NORM2} --- Euclidean vector norms
9198 @cindex Euclidean vector norm
9199 @cindex L2 vector norm
9200 @cindex norm, Euclidean
9203 @item @emph{Description}:
9204 Calculates the Euclidean vector norm (@math{L_2} norm) of
9205 of @var{ARRAY} along dimension @var{DIM}.
9207 @item @emph{Standard}:
9208 Fortran 2008 and later
9211 Transformational function
9213 @item @emph{Syntax}:
9214 @multitable @columnfractions .80
9215 @item @code{RESULT = NORM2(ARRAY[, DIM])}
9218 @item @emph{Arguments}:
9219 @multitable @columnfractions .15 .70
9220 @item @var{ARRAY} @tab Shall be an array of type @code{REAL}
9221 @item @var{DIM} @tab (Optional) shall be a scalar of type
9222 @code{INTEGER} with a value in the range from 1 to n, where n
9223 equals the rank of @var{ARRAY}.
9226 @item @emph{Return value}:
9227 The result is of the same type as @var{ARRAY}.
9229 If @var{DIM} is absent, a scalar with the square root of the sum of all
9230 elements in @var{ARRAY} squared is returned. Otherwise, an array of
9231 rank @math{n-1}, where @math{n} equals the rank of @var{ARRAY}, and a
9232 shape similar to that of @var{ARRAY} with dimension @var{DIM} dropped
9235 @item @emph{Example}:
9238 REAL :: x(5) = [ real :: 1, 2, 3, 4, 5 ]
9239 print *, NORM2(x) ! = sqrt(55.) ~ 7.416
9247 @section @code{NOT} --- Logical negation
9249 @cindex bits, negate
9250 @cindex bitwise logical not
9251 @cindex logical not, bitwise
9254 @item @emph{Description}:
9255 @code{NOT} returns the bitwise Boolean inverse of @var{I}.
9257 @item @emph{Standard}:
9258 Fortran 95 and later
9263 @item @emph{Syntax}:
9264 @code{RESULT = NOT(I)}
9266 @item @emph{Arguments}:
9267 @multitable @columnfractions .15 .70
9268 @item @var{I} @tab The type shall be @code{INTEGER}.
9271 @item @emph{Return value}:
9272 The return type is @code{INTEGER}, of the same kind as the
9275 @item @emph{See also}:
9276 @ref{IAND}, @ref{IEOR}, @ref{IOR}, @ref{IBITS}, @ref{IBSET}, @ref{IBCLR}
9283 @section @code{NULL} --- Function that returns an disassociated pointer
9285 @cindex pointer, status
9286 @cindex pointer, disassociated
9289 @item @emph{Description}:
9290 Returns a disassociated pointer.
9292 If @var{MOLD} is present, a disassociated pointer of the same type is
9293 returned, otherwise the type is determined by context.
9295 In Fortran 95, @var{MOLD} is optional. Please note that Fortran 2003
9296 includes cases where it is required.
9298 @item @emph{Standard}:
9299 Fortran 95 and later
9302 Transformational function
9304 @item @emph{Syntax}:
9305 @code{PTR => NULL([MOLD])}
9307 @item @emph{Arguments}:
9308 @multitable @columnfractions .15 .70
9309 @item @var{MOLD} @tab (Optional) shall be a pointer of any association
9310 status and of any type.
9313 @item @emph{Return value}:
9314 A disassociated pointer.
9316 @item @emph{Example}:
9318 REAL, POINTER, DIMENSION(:) :: VEC => NULL ()
9321 @item @emph{See also}:
9328 @section @code{NUM_IMAGES} --- Function that returns the number of images
9330 @cindex coarray, @code{NUM_IMAGES}
9331 @cindex images, number of
9334 @item @emph{Description}:
9335 Returns the number of images.
9337 @item @emph{Standard}:
9338 Fortran 2008 and later
9341 Transformational function
9343 @item @emph{Syntax}:
9344 @code{RESULT = NUM_IMAGES()}
9346 @item @emph{Arguments}: None.
9348 @item @emph{Return value}:
9349 Scalar default-kind integer.
9351 @item @emph{Example}:
9355 value = THIS_IMAGE()
9357 IF (THIS_IMAGE() == 1) THEN
9358 DO i = 1, NUM_IMAGES()
9359 WRITE(*,'(2(a,i0))') 'value[', i, '] is ', value[i]
9364 @item @emph{See also}:
9365 @ref{THIS_IMAGE}, @ref{IMAGE_INDEX}
9371 @section @code{OR} --- Bitwise logical OR
9373 @cindex bitwise logical or
9374 @cindex logical or, bitwise
9377 @item @emph{Description}:
9378 Bitwise logical @code{OR}.
9380 This intrinsic routine is provided for backwards compatibility with
9381 GNU Fortran 77. For integer arguments, programmers should consider
9382 the use of the @ref{IOR} intrinsic defined by the Fortran standard.
9384 @item @emph{Standard}:
9390 @item @emph{Syntax}:
9391 @code{RESULT = OR(I, J)}
9393 @item @emph{Arguments}:
9394 @multitable @columnfractions .15 .70
9395 @item @var{I} @tab The type shall be either a scalar @code{INTEGER}
9396 type or a scalar @code{LOGICAL} type.
9397 @item @var{J} @tab The type shall be the same as the type of @var{J}.
9400 @item @emph{Return value}:
9401 The return type is either a scalar @code{INTEGER} or a scalar
9402 @code{LOGICAL}. If the kind type parameters differ, then the
9403 smaller kind type is implicitly converted to larger kind, and the
9404 return has the larger kind.
9406 @item @emph{Example}:
9409 LOGICAL :: T = .TRUE., F = .FALSE.
9411 DATA a / Z'F' /, b / Z'3' /
9413 WRITE (*,*) OR(T, T), OR(T, F), OR(F, T), OR(F, F)
9414 WRITE (*,*) OR(a, b)
9418 @item @emph{See also}:
9419 Fortran 95 elemental function: @ref{IOR}
9425 @section @code{PACK} --- Pack an array into an array of rank one
9427 @cindex array, packing
9428 @cindex array, reduce dimension
9429 @cindex array, gather elements
9432 @item @emph{Description}:
9433 Stores the elements of @var{ARRAY} in an array of rank one.
9435 The beginning of the resulting array is made up of elements whose @var{MASK}
9436 equals @code{TRUE}. Afterwards, positions are filled with elements taken from
9439 @item @emph{Standard}:
9440 Fortran 95 and later
9443 Transformational function
9445 @item @emph{Syntax}:
9446 @code{RESULT = PACK(ARRAY, MASK[,VECTOR]}
9448 @item @emph{Arguments}:
9449 @multitable @columnfractions .15 .70
9450 @item @var{ARRAY} @tab Shall be an array of any type.
9451 @item @var{MASK} @tab Shall be an array of type @code{LOGICAL} and
9452 of the same size as @var{ARRAY}. Alternatively, it may be a @code{LOGICAL}
9454 @item @var{VECTOR} @tab (Optional) shall be an array of the same type
9455 as @var{ARRAY} and of rank one. If present, the number of elements in
9456 @var{VECTOR} shall be equal to or greater than the number of true elements
9457 in @var{MASK}. If @var{MASK} is scalar, the number of elements in
9458 @var{VECTOR} shall be equal to or greater than the number of elements in
9462 @item @emph{Return value}:
9463 The result is an array of rank one and the same type as that of @var{ARRAY}.
9464 If @var{VECTOR} is present, the result size is that of @var{VECTOR}, the
9465 number of @code{TRUE} values in @var{MASK} otherwise.
9467 @item @emph{Example}:
9468 Gathering nonzero elements from an array:
9472 m = (/ 1, 0, 0, 0, 5, 0 /)
9473 WRITE(*, FMT="(6(I0, ' '))") pack(m, m /= 0) ! "1 5"
9477 Gathering nonzero elements from an array and appending elements from @var{VECTOR}:
9481 m = (/ 1, 0, 0, 2 /)
9482 WRITE(*, FMT="(4(I0, ' '))") pack(m, m /= 0, (/ 0, 0, 3, 4 /)) ! "1 2 3 4"
9486 @item @emph{See also}:
9493 @section @code{PARITY} --- Reduction with exclusive OR
9496 @cindex Reduction, XOR
9497 @cindex XOR reduction
9500 @item @emph{Description}:
9501 Calculates the parity, i.e. the reduction using @code{.XOR.},
9502 of @var{MASK} along dimension @var{DIM}.
9504 @item @emph{Standard}:
9505 Fortran 2008 and later
9508 Transformational function
9510 @item @emph{Syntax}:
9511 @multitable @columnfractions .80
9512 @item @code{RESULT = PARITY(MASK[, DIM])}
9515 @item @emph{Arguments}:
9516 @multitable @columnfractions .15 .70
9517 @item @var{LOGICAL} @tab Shall be an array of type @code{LOGICAL}
9518 @item @var{DIM} @tab (Optional) shall be a scalar of type
9519 @code{INTEGER} with a value in the range from 1 to n, where n
9520 equals the rank of @var{MASK}.
9523 @item @emph{Return value}:
9524 The result is of the same type as @var{MASK}.
9526 If @var{DIM} is absent, a scalar with the parity of all elements in
9527 @var{MASK} is returned, i.e. true if an odd number of elements is
9528 @code{.true.} and false otherwise. If @var{DIM} is present, an array
9529 of rank @math{n-1}, where @math{n} equals the rank of @var{ARRAY},
9530 and a shape similar to that of @var{MASK} with dimension @var{DIM}
9531 dropped is returned.
9533 @item @emph{Example}:
9536 LOGICAL :: x(2) = [ .true., .false. ]
9537 print *, PARITY(x) ! prints "T" (true).
9545 @section @code{PERROR} --- Print system error message
9547 @cindex system, error handling
9550 @item @emph{Description}:
9551 Prints (on the C @code{stderr} stream) a newline-terminated error
9552 message corresponding to the last system error. This is prefixed by
9553 @var{STRING}, a colon and a space. See @code{perror(3)}.
9555 @item @emph{Standard}:
9561 @item @emph{Syntax}:
9562 @code{CALL PERROR(STRING)}
9564 @item @emph{Arguments}:
9565 @multitable @columnfractions .15 .70
9566 @item @var{STRING} @tab A scalar of type @code{CHARACTER} and of the
9570 @item @emph{See also}:
9577 @section @code{PRECISION} --- Decimal precision of a real kind
9579 @cindex model representation, precision
9582 @item @emph{Description}:
9583 @code{PRECISION(X)} returns the decimal precision in the model of the
9586 @item @emph{Standard}:
9587 Fortran 95 and later
9592 @item @emph{Syntax}:
9593 @code{RESULT = PRECISION(X)}
9595 @item @emph{Arguments}:
9596 @multitable @columnfractions .15 .70
9597 @item @var{X} @tab Shall be of type @code{REAL} or @code{COMPLEX}.
9600 @item @emph{Return value}:
9601 The return value is of type @code{INTEGER} and of the default integer
9604 @item @emph{See also}:
9605 @ref{SELECTED_REAL_KIND}, @ref{RANGE}
9607 @item @emph{Example}:
9609 program prec_and_range
9610 real(kind=4) :: x(2)
9611 complex(kind=8) :: y
9613 print *, precision(x), range(x)
9614 print *, precision(y), range(y)
9615 end program prec_and_range
9622 @section @code{POPCNT} --- Number of bits set
9624 @cindex binary representation
9628 @item @emph{Description}:
9629 @code{POPCNT(I)} returns the number of bits set ('1' bits) in the binary
9630 representation of @code{I}.
9632 @item @emph{Standard}:
9633 Fortran 2008 and later
9638 @item @emph{Syntax}:
9639 @code{RESULT = POPCNT(I)}
9641 @item @emph{Arguments}:
9642 @multitable @columnfractions .15 .70
9643 @item @var{I} @tab Shall be of type @code{INTEGER}.
9646 @item @emph{Return value}:
9647 The return value is of type @code{INTEGER} and of the default integer
9650 @item @emph{See also}:
9651 @ref{POPPAR}, @ref{LEADZ}, @ref{TRAILZ}
9653 @item @emph{Example}:
9655 program test_population
9656 print *, popcnt(127), poppar(127)
9657 print *, popcnt(huge(0_4)), poppar(huge(0_4))
9658 print *, popcnt(huge(0_8)), poppar(huge(0_8))
9659 end program test_population
9665 @section @code{POPPAR} --- Parity of the number of bits set
9667 @cindex binary representation
9671 @item @emph{Description}:
9672 @code{POPPAR(I)} returns parity of the integer @code{I}, i.e. the parity
9673 of the number of bits set ('1' bits) in the binary representation of
9674 @code{I}. It is equal to 0 if @code{I} has an even number of bits set,
9675 and 1 for an odd number of '1' bits.
9677 @item @emph{Standard}:
9678 Fortran 2008 and later
9683 @item @emph{Syntax}:
9684 @code{RESULT = POPPAR(I)}
9686 @item @emph{Arguments}:
9687 @multitable @columnfractions .15 .70
9688 @item @var{I} @tab Shall be of type @code{INTEGER}.
9691 @item @emph{Return value}:
9692 The return value is of type @code{INTEGER} and of the default integer
9695 @item @emph{See also}:
9696 @ref{POPCNT}, @ref{LEADZ}, @ref{TRAILZ}
9698 @item @emph{Example}:
9700 program test_population
9701 print *, popcnt(127), poppar(127)
9702 print *, popcnt(huge(0_4)), poppar(huge(0_4))
9703 print *, popcnt(huge(0_8)), poppar(huge(0_8))
9704 end program test_population
9711 @section @code{PRESENT} --- Determine whether an optional dummy argument is specified
9715 @item @emph{Description}:
9716 Determines whether an optional dummy argument is present.
9718 @item @emph{Standard}:
9719 Fortran 95 and later
9724 @item @emph{Syntax}:
9725 @code{RESULT = PRESENT(A)}
9727 @item @emph{Arguments}:
9728 @multitable @columnfractions .15 .70
9729 @item @var{A} @tab May be of any type and may be a pointer, scalar or array
9730 value, or a dummy procedure. It shall be the name of an optional dummy argument
9731 accessible within the current subroutine or function.
9734 @item @emph{Return value}:
9735 Returns either @code{TRUE} if the optional argument @var{A} is present, or
9736 @code{FALSE} otherwise.
9738 @item @emph{Example}:
9740 PROGRAM test_present
9741 WRITE(*,*) f(), f(42) ! "F T"
9743 LOGICAL FUNCTION f(x)
9744 INTEGER, INTENT(IN), OPTIONAL :: x
9754 @section @code{PRODUCT} --- Product of array elements
9756 @cindex array, product
9757 @cindex array, multiply elements
9758 @cindex array, conditionally multiply elements
9759 @cindex multiply array elements
9762 @item @emph{Description}:
9763 Multiplies the elements of @var{ARRAY} along dimension @var{DIM} if
9764 the corresponding element in @var{MASK} is @code{TRUE}.
9766 @item @emph{Standard}:
9767 Fortran 95 and later
9770 Transformational function
9772 @item @emph{Syntax}:
9773 @multitable @columnfractions .80
9774 @item @code{RESULT = PRODUCT(ARRAY[, MASK])}
9775 @item @code{RESULT = PRODUCT(ARRAY, DIM[, MASK])}
9778 @item @emph{Arguments}:
9779 @multitable @columnfractions .15 .70
9780 @item @var{ARRAY} @tab Shall be an array of type @code{INTEGER},
9781 @code{REAL} or @code{COMPLEX}.
9782 @item @var{DIM} @tab (Optional) shall be a scalar of type
9783 @code{INTEGER} with a value in the range from 1 to n, where n
9784 equals the rank of @var{ARRAY}.
9785 @item @var{MASK} @tab (Optional) shall be of type @code{LOGICAL}
9786 and either be a scalar or an array of the same shape as @var{ARRAY}.
9789 @item @emph{Return value}:
9790 The result is of the same type as @var{ARRAY}.
9792 If @var{DIM} is absent, a scalar with the product of all elements in
9793 @var{ARRAY} is returned. Otherwise, an array of rank n-1, where n equals
9794 the rank of @var{ARRAY}, and a shape similar to that of @var{ARRAY} with
9795 dimension @var{DIM} dropped is returned.
9798 @item @emph{Example}:
9800 PROGRAM test_product
9801 INTEGER :: x(5) = (/ 1, 2, 3, 4 ,5 /)
9802 print *, PRODUCT(x) ! all elements, product = 120
9803 print *, PRODUCT(x, MASK=MOD(x, 2)==1) ! odd elements, product = 15
9807 @item @emph{See also}:
9814 @section @code{RADIX} --- Base of a model number
9816 @cindex model representation, base
9817 @cindex model representation, radix
9820 @item @emph{Description}:
9821 @code{RADIX(X)} returns the base of the model representing the entity @var{X}.
9823 @item @emph{Standard}:
9824 Fortran 95 and later
9829 @item @emph{Syntax}:
9830 @code{RESULT = RADIX(X)}
9832 @item @emph{Arguments}:
9833 @multitable @columnfractions .15 .70
9834 @item @var{X} @tab Shall be of type @code{INTEGER} or @code{REAL}
9837 @item @emph{Return value}:
9838 The return value is a scalar of type @code{INTEGER} and of the default
9841 @item @emph{See also}:
9842 @ref{SELECTED_REAL_KIND}
9844 @item @emph{Example}:
9847 print *, "The radix for the default integer kind is", radix(0)
9848 print *, "The radix for the default real kind is", radix(0.0)
9849 end program test_radix
9857 @section @code{RAN} --- Real pseudo-random number
9859 @cindex random number generation
9862 @item @emph{Description}:
9863 For compatibility with HP FORTRAN 77/iX, the @code{RAN} intrinsic is
9864 provided as an alias for @code{RAND}. See @ref{RAND} for complete
9867 @item @emph{Standard}:
9873 @item @emph{See also}:
9874 @ref{RAND}, @ref{RANDOM_NUMBER}
9880 @section @code{RAND} --- Real pseudo-random number
9882 @cindex random number generation
9885 @item @emph{Description}:
9886 @code{RAND(FLAG)} returns a pseudo-random number from a uniform
9887 distribution between 0 and 1. If @var{FLAG} is 0, the next number
9888 in the current sequence is returned; if @var{FLAG} is 1, the generator
9889 is restarted by @code{CALL SRAND(0)}; if @var{FLAG} has any other value,
9890 it is used as a new seed with @code{SRAND}.
9892 This intrinsic routine is provided for backwards compatibility with
9893 GNU Fortran 77. It implements a simple modulo generator as provided
9894 by @command{g77}. For new code, one should consider the use of
9895 @ref{RANDOM_NUMBER} as it implements a superior algorithm.
9897 @item @emph{Standard}:
9903 @item @emph{Syntax}:
9904 @code{RESULT = RAND(I)}
9906 @item @emph{Arguments}:
9907 @multitable @columnfractions .15 .70
9908 @item @var{I} @tab Shall be a scalar @code{INTEGER} of kind 4.
9911 @item @emph{Return value}:
9912 The return value is of @code{REAL} type and the default kind.
9914 @item @emph{Example}:
9917 integer,parameter :: seed = 86456
9920 print *, rand(), rand(), rand(), rand()
9921 print *, rand(seed), rand(), rand(), rand()
9922 end program test_rand
9925 @item @emph{See also}:
9926 @ref{SRAND}, @ref{RANDOM_NUMBER}
9933 @section @code{RANDOM_NUMBER} --- Pseudo-random number
9934 @fnindex RANDOM_NUMBER
9935 @cindex random number generation
9938 @item @emph{Description}:
9939 Returns a single pseudorandom number or an array of pseudorandom numbers
9940 from the uniform distribution over the range @math{ 0 \leq x < 1}.
9942 The runtime-library implements George Marsaglia's KISS (Keep It Simple
9943 Stupid) random number generator (RNG). This RNG combines:
9945 @item The congruential generator @math{x(n) = 69069 \cdot x(n-1) + 1327217885}
9946 with a period of @math{2^{32}},
9947 @item A 3-shift shift-register generator with a period of @math{2^{32} - 1},
9948 @item Two 16-bit multiply-with-carry generators with a period of
9949 @math{597273182964842497 > 2^{59}}.
9951 The overall period exceeds @math{2^{123}}.
9953 Please note, this RNG is thread safe if used within OpenMP directives,
9954 i.e., its state will be consistent while called from multiple threads.
9955 However, the KISS generator does not create random numbers in parallel
9956 from multiple sources, but in sequence from a single source. If an
9957 OpenMP-enabled application heavily relies on random numbers, one should
9958 consider employing a dedicated parallel random number generator instead.
9960 @item @emph{Standard}:
9961 Fortran 95 and later
9966 @item @emph{Syntax}:
9967 @code{RANDOM_NUMBER(HARVEST)}
9969 @item @emph{Arguments}:
9970 @multitable @columnfractions .15 .70
9971 @item @var{HARVEST} @tab Shall be a scalar or an array of type @code{REAL}.
9974 @item @emph{Example}:
9976 program test_random_number
9978 CALL init_random_seed() ! see example of RANDOM_SEED
9979 CALL RANDOM_NUMBER(r)
9983 @item @emph{See also}:
9990 @section @code{RANDOM_SEED} --- Initialize a pseudo-random number sequence
9991 @fnindex RANDOM_SEED
9992 @cindex random number generation, seeding
9993 @cindex seeding a random number generator
9996 @item @emph{Description}:
9997 Restarts or queries the state of the pseudorandom number generator used by
9998 @code{RANDOM_NUMBER}.
10000 If @code{RANDOM_SEED} is called without arguments, it is initialized to
10001 a default state. The example below shows how to initialize the random
10002 seed based on the system's time.
10004 @item @emph{Standard}:
10005 Fortran 95 and later
10007 @item @emph{Class}:
10010 @item @emph{Syntax}:
10011 @code{CALL RANDOM_SEED([SIZE, PUT, GET])}
10013 @item @emph{Arguments}:
10014 @multitable @columnfractions .15 .70
10015 @item @var{SIZE} @tab (Optional) Shall be a scalar and of type default
10016 @code{INTEGER}, with @code{INTENT(OUT)}. It specifies the minimum size
10017 of the arrays used with the @var{PUT} and @var{GET} arguments.
10018 @item @var{PUT} @tab (Optional) Shall be an array of type default
10019 @code{INTEGER} and rank one. It is @code{INTENT(IN)} and the size of
10020 the array must be larger than or equal to the number returned by the
10021 @var{SIZE} argument.
10022 @item @var{GET} @tab (Optional) Shall be an array of type default
10023 @code{INTEGER} and rank one. It is @code{INTENT(OUT)} and the size
10024 of the array must be larger than or equal to the number returned by
10025 the @var{SIZE} argument.
10028 @item @emph{Example}:
10030 SUBROUTINE init_random_seed()
10031 INTEGER :: i, n, clock
10032 INTEGER, DIMENSION(:), ALLOCATABLE :: seed
10034 CALL RANDOM_SEED(size = n)
10037 CALL SYSTEM_CLOCK(COUNT=clock)
10039 seed = clock + 37 * (/ (i - 1, i = 1, n) /)
10040 CALL RANDOM_SEED(PUT = seed)
10046 @item @emph{See also}:
10047 @ref{RANDOM_NUMBER}
10053 @section @code{RANGE} --- Decimal exponent range
10055 @cindex model representation, range
10058 @item @emph{Description}:
10059 @code{RANGE(X)} returns the decimal exponent range in the model of the
10062 @item @emph{Standard}:
10063 Fortran 95 and later
10065 @item @emph{Class}:
10068 @item @emph{Syntax}:
10069 @code{RESULT = RANGE(X)}
10071 @item @emph{Arguments}:
10072 @multitable @columnfractions .15 .70
10073 @item @var{X} @tab Shall be of type @code{INTEGER}, @code{REAL}
10077 @item @emph{Return value}:
10078 The return value is of type @code{INTEGER} and of the default integer
10081 @item @emph{See also}:
10082 @ref{SELECTED_REAL_KIND}, @ref{PRECISION}
10084 @item @emph{Example}:
10085 See @code{PRECISION} for an example.
10091 @section @code{REAL} --- Convert to real type
10097 @cindex conversion, to real
10098 @cindex complex numbers, real part
10101 @item @emph{Description}:
10102 @code{REAL(A [, KIND])} converts its argument @var{A} to a real type. The
10103 @code{REALPART} function is provided for compatibility with @command{g77},
10104 and its use is strongly discouraged.
10106 @item @emph{Standard}:
10107 Fortran 77 and later
10109 @item @emph{Class}:
10112 @item @emph{Syntax}:
10113 @multitable @columnfractions .80
10114 @item @code{RESULT = REAL(A [, KIND])}
10115 @item @code{RESULT = REALPART(Z)}
10118 @item @emph{Arguments}:
10119 @multitable @columnfractions .15 .70
10120 @item @var{A} @tab Shall be @code{INTEGER}, @code{REAL}, or
10122 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
10123 expression indicating the kind parameter of the result.
10126 @item @emph{Return value}:
10127 These functions return a @code{REAL} variable or array under
10128 the following rules:
10132 @code{REAL(A)} is converted to a default real type if @var{A} is an
10133 integer or real variable.
10135 @code{REAL(A)} is converted to a real type with the kind type parameter
10136 of @var{A} if @var{A} is a complex variable.
10138 @code{REAL(A, KIND)} is converted to a real type with kind type
10139 parameter @var{KIND} if @var{A} is a complex, integer, or real
10143 @item @emph{Example}:
10146 complex :: x = (1.0, 2.0)
10147 print *, real(x), real(x,8), realpart(x)
10148 end program test_real
10151 @item @emph{Specific names}:
10152 @multitable @columnfractions .20 .20 .20 .25
10153 @item Name @tab Argument @tab Return type @tab Standard
10154 @item @code{FLOAT(A)} @tab @code{INTEGER(4)} @tab @code{REAL(4)} @tab Fortran 77 and later
10155 @item @code{DFLOAT(A)} @tab @code{INTEGER(4)} @tab @code{REAL(8)} @tab GNU extension
10156 @item @code{SNGL(A)} @tab @code{INTEGER(8)} @tab @code{REAL(4)} @tab Fortran 77 and later
10160 @item @emph{See also}:
10168 @section @code{RENAME} --- Rename a file
10170 @cindex file system, rename file
10173 @item @emph{Description}:
10174 Renames a file from file @var{PATH1} to @var{PATH2}. A null
10175 character (@code{CHAR(0)}) can be used to mark the end of the names in
10176 @var{PATH1} and @var{PATH2}; otherwise, trailing blanks in the file
10177 names are ignored. If the @var{STATUS} argument is supplied, it
10178 contains 0 on success or a nonzero error code upon return; see
10181 This intrinsic is provided in both subroutine and function forms;
10182 however, only one form can be used in any given program unit.
10184 @item @emph{Standard}:
10187 @item @emph{Class}:
10188 Subroutine, function
10190 @item @emph{Syntax}:
10191 @multitable @columnfractions .80
10192 @item @code{CALL RENAME(PATH1, PATH2 [, STATUS])}
10193 @item @code{STATUS = RENAME(PATH1, PATH2)}
10196 @item @emph{Arguments}:
10197 @multitable @columnfractions .15 .70
10198 @item @var{PATH1} @tab Shall be of default @code{CHARACTER} type.
10199 @item @var{PATH2} @tab Shall be of default @code{CHARACTER} type.
10200 @item @var{STATUS} @tab (Optional) Shall be of default @code{INTEGER} type.
10203 @item @emph{See also}:
10211 @section @code{REPEAT} --- Repeated string concatenation
10213 @cindex string, repeat
10214 @cindex string, concatenate
10217 @item @emph{Description}:
10218 Concatenates @var{NCOPIES} copies of a string.
10220 @item @emph{Standard}:
10221 Fortran 95 and later
10223 @item @emph{Class}:
10224 Transformational function
10226 @item @emph{Syntax}:
10227 @code{RESULT = REPEAT(STRING, NCOPIES)}
10229 @item @emph{Arguments}:
10230 @multitable @columnfractions .15 .70
10231 @item @var{STRING} @tab Shall be scalar and of type @code{CHARACTER}.
10232 @item @var{NCOPIES} @tab Shall be scalar and of type @code{INTEGER}.
10235 @item @emph{Return value}:
10236 A new scalar of type @code{CHARACTER} built up from @var{NCOPIES} copies
10239 @item @emph{Example}:
10241 program test_repeat
10242 write(*,*) repeat("x", 5) ! "xxxxx"
10250 @section @code{RESHAPE} --- Function to reshape an array
10252 @cindex array, change dimensions
10253 @cindex array, transmogrify
10256 @item @emph{Description}:
10257 Reshapes @var{SOURCE} to correspond to @var{SHAPE}. If necessary,
10258 the new array may be padded with elements from @var{PAD} or permuted
10259 as defined by @var{ORDER}.
10261 @item @emph{Standard}:
10262 Fortran 95 and later
10264 @item @emph{Class}:
10265 Transformational function
10267 @item @emph{Syntax}:
10268 @code{RESULT = RESHAPE(SOURCE, SHAPE[, PAD, ORDER])}
10270 @item @emph{Arguments}:
10271 @multitable @columnfractions .15 .70
10272 @item @var{SOURCE} @tab Shall be an array of any type.
10273 @item @var{SHAPE} @tab Shall be of type @code{INTEGER} and an
10274 array of rank one. Its values must be positive or zero.
10275 @item @var{PAD} @tab (Optional) shall be an array of the same
10276 type as @var{SOURCE}.
10277 @item @var{ORDER} @tab (Optional) shall be of type @code{INTEGER}
10278 and an array of the same shape as @var{SHAPE}. Its values shall
10279 be a permutation of the numbers from 1 to n, where n is the size of
10280 @var{SHAPE}. If @var{ORDER} is absent, the natural ordering shall
10284 @item @emph{Return value}:
10285 The result is an array of shape @var{SHAPE} with the same type as
10288 @item @emph{Example}:
10290 PROGRAM test_reshape
10291 INTEGER, DIMENSION(4) :: x
10292 WRITE(*,*) SHAPE(x) ! prints "4"
10293 WRITE(*,*) SHAPE(RESHAPE(x, (/2, 2/))) ! prints "2 2"
10297 @item @emph{See also}:
10304 @section @code{RRSPACING} --- Reciprocal of the relative spacing
10306 @cindex real number, relative spacing
10307 @cindex floating point, relative spacing
10311 @item @emph{Description}:
10312 @code{RRSPACING(X)} returns the reciprocal of the relative spacing of
10313 model numbers near @var{X}.
10315 @item @emph{Standard}:
10316 Fortran 95 and later
10318 @item @emph{Class}:
10321 @item @emph{Syntax}:
10322 @code{RESULT = RRSPACING(X)}
10324 @item @emph{Arguments}:
10325 @multitable @columnfractions .15 .70
10326 @item @var{X} @tab Shall be of type @code{REAL}.
10329 @item @emph{Return value}:
10330 The return value is of the same type and kind as @var{X}.
10331 The value returned is equal to
10332 @code{ABS(FRACTION(X)) * FLOAT(RADIX(X))**DIGITS(X)}.
10334 @item @emph{See also}:
10341 @section @code{RSHIFT} --- Right shift bits
10343 @cindex bits, shift right
10346 @item @emph{Description}:
10347 @code{RSHIFT} returns a value corresponding to @var{I} with all of the
10348 bits shifted right by @var{SHIFT} places. If the absolute value of
10349 @var{SHIFT} is greater than @code{BIT_SIZE(I)}, the value is undefined.
10350 Bits shifted out from the right end are lost. The fill is arithmetic: the
10351 bits shifted in from the left end are equal to the leftmost bit, which in
10352 two's complement representation is the sign bit.
10354 This function has been superseded by the @code{SHIFTA} intrinsic, which
10355 is standard in Fortran 2008 and later.
10357 @item @emph{Standard}:
10360 @item @emph{Class}:
10363 @item @emph{Syntax}:
10364 @code{RESULT = RSHIFT(I, SHIFT)}
10366 @item @emph{Arguments}:
10367 @multitable @columnfractions .15 .70
10368 @item @var{I} @tab The type shall be @code{INTEGER}.
10369 @item @var{SHIFT} @tab The type shall be @code{INTEGER}.
10372 @item @emph{Return value}:
10373 The return value is of type @code{INTEGER} and of the same kind as
10376 @item @emph{See also}:
10377 @ref{ISHFT}, @ref{ISHFTC}, @ref{LSHIFT}, @ref{SHIFTA}, @ref{SHIFTR},
10385 @section @code{SAME_TYPE_AS} --- Query dynamic types for equality
10386 @fnindex SAME_TYPE_AS
10389 @item @emph{Description}:
10390 Query dynamic types for equality.
10392 @item @emph{Standard}:
10393 Fortran 2003 and later
10395 @item @emph{Class}:
10398 @item @emph{Syntax}:
10399 @code{RESULT = SAME_TYPE_AS(A, B)}
10401 @item @emph{Arguments}:
10402 @multitable @columnfractions .15 .70
10403 @item @var{A} @tab Shall be an object of extensible declared type or
10404 unlimited polymorphic.
10405 @item @var{B} @tab Shall be an object of extensible declared type or
10406 unlimited polymorphic.
10409 @item @emph{Return value}:
10410 The return value is a scalar of type default logical. It is true if and
10411 only if the dynamic type of A is the same as the dynamic type of B.
10413 @item @emph{See also}:
10414 @ref{EXTENDS_TYPE_OF}
10421 @section @code{SCALE} --- Scale a real value
10423 @cindex real number, scale
10424 @cindex floating point, scale
10427 @item @emph{Description}:
10428 @code{SCALE(X,I)} returns @code{X * RADIX(X)**I}.
10430 @item @emph{Standard}:
10431 Fortran 95 and later
10433 @item @emph{Class}:
10436 @item @emph{Syntax}:
10437 @code{RESULT = SCALE(X, I)}
10439 @item @emph{Arguments}:
10440 @multitable @columnfractions .15 .70
10441 @item @var{X} @tab The type of the argument shall be a @code{REAL}.
10442 @item @var{I} @tab The type of the argument shall be a @code{INTEGER}.
10445 @item @emph{Return value}:
10446 The return value is of the same type and kind as @var{X}.
10447 Its value is @code{X * RADIX(X)**I}.
10449 @item @emph{Example}:
10452 real :: x = 178.1387e-4
10454 print *, scale(x,i), x*radix(x)**i
10455 end program test_scale
10463 @section @code{SCAN} --- Scan a string for the presence of a set of characters
10465 @cindex string, find subset
10468 @item @emph{Description}:
10469 Scans a @var{STRING} for any of the characters in a @var{SET}
10472 If @var{BACK} is either absent or equals @code{FALSE}, this function
10473 returns the position of the leftmost character of @var{STRING} that is
10474 in @var{SET}. If @var{BACK} equals @code{TRUE}, the rightmost position
10475 is returned. If no character of @var{SET} is found in @var{STRING}, the
10478 @item @emph{Standard}:
10479 Fortran 95 and later, with @var{KIND} argument Fortran 2003 and later
10481 @item @emph{Class}:
10484 @item @emph{Syntax}:
10485 @code{RESULT = SCAN(STRING, SET[, BACK [, KIND]])}
10487 @item @emph{Arguments}:
10488 @multitable @columnfractions .15 .70
10489 @item @var{STRING} @tab Shall be of type @code{CHARACTER}.
10490 @item @var{SET} @tab Shall be of type @code{CHARACTER}.
10491 @item @var{BACK} @tab (Optional) shall be of type @code{LOGICAL}.
10492 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
10493 expression indicating the kind parameter of the result.
10496 @item @emph{Return value}:
10497 The return value is of type @code{INTEGER} and of kind @var{KIND}. If
10498 @var{KIND} is absent, the return value is of default integer kind.
10500 @item @emph{Example}:
10503 WRITE(*,*) SCAN("FORTRAN", "AO") ! 2, found 'O'
10504 WRITE(*,*) SCAN("FORTRAN", "AO", .TRUE.) ! 6, found 'A'
10505 WRITE(*,*) SCAN("FORTRAN", "C++") ! 0, found none
10509 @item @emph{See also}:
10510 @ref{INDEX intrinsic}, @ref{VERIFY}
10516 @section @code{SECNDS} --- Time function
10518 @cindex time, elapsed
10519 @cindex elapsed time
10522 @item @emph{Description}:
10523 @code{SECNDS(X)} gets the time in seconds from the real-time system clock.
10524 @var{X} is a reference time, also in seconds. If this is zero, the time in
10525 seconds from midnight is returned. This function is non-standard and its
10526 use is discouraged.
10528 @item @emph{Standard}:
10531 @item @emph{Class}:
10534 @item @emph{Syntax}:
10535 @code{RESULT = SECNDS (X)}
10537 @item @emph{Arguments}:
10538 @multitable @columnfractions .15 .70
10539 @item @var{T} @tab Shall be of type @code{REAL(4)}.
10540 @item @var{X} @tab Shall be of type @code{REAL(4)}.
10543 @item @emph{Return value}:
10546 @item @emph{Example}:
10548 program test_secnds
10551 print *, secnds (0.0) ! seconds since midnight
10552 t1 = secnds (0.0) ! reference time
10553 do i = 1, 10000000 ! do something
10555 t2 = secnds (t1) ! elapsed time
10556 print *, "Something took ", t2, " seconds."
10557 end program test_secnds
10564 @section @code{SECOND} --- CPU time function
10566 @cindex time, elapsed
10567 @cindex elapsed time
10570 @item @emph{Description}:
10571 Returns a @code{REAL(4)} value representing the elapsed CPU time in
10572 seconds. This provides the same functionality as the standard
10573 @code{CPU_TIME} intrinsic, and is only included for backwards
10576 This intrinsic is provided in both subroutine and function forms;
10577 however, only one form can be used in any given program unit.
10579 @item @emph{Standard}:
10582 @item @emph{Class}:
10583 Subroutine, function
10585 @item @emph{Syntax}:
10586 @multitable @columnfractions .80
10587 @item @code{CALL SECOND(TIME)}
10588 @item @code{TIME = SECOND()}
10591 @item @emph{Arguments}:
10592 @multitable @columnfractions .15 .70
10593 @item @var{TIME} @tab Shall be of type @code{REAL(4)}.
10596 @item @emph{Return value}:
10597 In either syntax, @var{TIME} is set to the process's current runtime in
10600 @item @emph{See also}:
10607 @node SELECTED_CHAR_KIND
10608 @section @code{SELECTED_CHAR_KIND} --- Choose character kind
10609 @fnindex SELECTED_CHAR_KIND
10610 @cindex character kind
10611 @cindex kind, character
10614 @item @emph{Description}:
10616 @code{SELECTED_CHAR_KIND(NAME)} returns the kind value for the character
10617 set named @var{NAME}, if a character set with such a name is supported,
10618 or @math{-1} otherwise. Currently, supported character sets include
10619 ``ASCII'' and ``DEFAULT'', which are equivalent, and ``ISO_10646''
10620 (Universal Character Set, UCS-4) which is commonly known as Unicode.
10622 @item @emph{Standard}:
10623 Fortran 2003 and later
10625 @item @emph{Class}:
10626 Transformational function
10628 @item @emph{Syntax}:
10629 @code{RESULT = SELECTED_CHAR_KIND(NAME)}
10631 @item @emph{Arguments}:
10632 @multitable @columnfractions .15 .70
10633 @item @var{NAME} @tab Shall be a scalar and of the default character type.
10636 @item @emph{Example}:
10638 program character_kind
10639 use iso_fortran_env
10641 integer, parameter :: ascii = selected_char_kind ("ascii")
10642 integer, parameter :: ucs4 = selected_char_kind ('ISO_10646')
10644 character(kind=ascii, len=26) :: alphabet
10645 character(kind=ucs4, len=30) :: hello_world
10647 alphabet = ascii_"abcdefghijklmnopqrstuvwxyz"
10648 hello_world = ucs4_'Hello World and Ni Hao -- ' &
10649 // char (int (z'4F60'), ucs4) &
10650 // char (int (z'597D'), ucs4)
10652 write (*,*) alphabet
10654 open (output_unit, encoding='UTF-8')
10655 write (*,*) trim (hello_world)
10656 end program character_kind
10662 @node SELECTED_INT_KIND
10663 @section @code{SELECTED_INT_KIND} --- Choose integer kind
10664 @fnindex SELECTED_INT_KIND
10665 @cindex integer kind
10666 @cindex kind, integer
10669 @item @emph{Description}:
10670 @code{SELECTED_INT_KIND(R)} return the kind value of the smallest integer
10671 type that can represent all values ranging from @math{-10^R} (exclusive)
10672 to @math{10^R} (exclusive). If there is no integer kind that accommodates
10673 this range, @code{SELECTED_INT_KIND} returns @math{-1}.
10675 @item @emph{Standard}:
10676 Fortran 95 and later
10678 @item @emph{Class}:
10679 Transformational function
10681 @item @emph{Syntax}:
10682 @code{RESULT = SELECTED_INT_KIND(R)}
10684 @item @emph{Arguments}:
10685 @multitable @columnfractions .15 .70
10686 @item @var{R} @tab Shall be a scalar and of type @code{INTEGER}.
10689 @item @emph{Example}:
10691 program large_integers
10692 integer,parameter :: k5 = selected_int_kind(5)
10693 integer,parameter :: k15 = selected_int_kind(15)
10694 integer(kind=k5) :: i5
10695 integer(kind=k15) :: i15
10697 print *, huge(i5), huge(i15)
10699 ! The following inequalities are always true
10700 print *, huge(i5) >= 10_k5**5-1
10701 print *, huge(i15) >= 10_k15**15-1
10702 end program large_integers
10708 @node SELECTED_REAL_KIND
10709 @section @code{SELECTED_REAL_KIND} --- Choose real kind
10710 @fnindex SELECTED_REAL_KIND
10713 @cindex radix, real
10716 @item @emph{Description}:
10717 @code{SELECTED_REAL_KIND(P,R)} returns the kind value of a real data type
10718 with decimal precision of at least @code{P} digits, exponent range of
10719 at least @code{R}, and with a radix of @code{RADIX}.
10721 @item @emph{Standard}:
10722 Fortran 95 and later, with @code{RADIX} Fortran 2008 or later
10724 @item @emph{Class}:
10725 Transformational function
10727 @item @emph{Syntax}:
10728 @code{RESULT = SELECTED_REAL_KIND([P, R, RADIX])}
10730 @item @emph{Arguments}:
10731 @multitable @columnfractions .15 .70
10732 @item @var{P} @tab (Optional) shall be a scalar and of type @code{INTEGER}.
10733 @item @var{R} @tab (Optional) shall be a scalar and of type @code{INTEGER}.
10734 @item @var{RADIX} @tab (Optional) shall be a scalar and of type @code{INTEGER}.
10736 Before Fortran 2008, at least one of the arguments @var{R} or @var{P} shall
10737 be present; since Fortran 2008, they are assumed to be zero if absent.
10739 @item @emph{Return value}:
10741 @code{SELECTED_REAL_KIND} returns the value of the kind type parameter of
10742 a real data type with decimal precision of at least @code{P} digits, a
10743 decimal exponent range of at least @code{R}, and with the requested
10744 @code{RADIX}. If the @code{RADIX} parameter is absent, real kinds with
10745 any radix can be returned. If more than one real data type meet the
10746 criteria, the kind of the data type with the smallest decimal precision
10747 is returned. If no real data type matches the criteria, the result is
10749 @item -1 if the processor does not support a real data type with a
10750 precision greater than or equal to @code{P}, but the @code{R} and
10751 @code{RADIX} requirements can be fulfilled
10752 @item -2 if the processor does not support a real type with an exponent
10753 range greater than or equal to @code{R}, but @code{P} and @code{RADIX}
10755 @item -3 if @code{RADIX} but not @code{P} and @code{R} requirements
10757 @item -4 if @code{RADIX} and either @code{P} or @code{R} requirements
10759 @item -5 if there is no real type with the given @code{RADIX}
10762 @item @emph{See also}:
10763 @ref{PRECISION}, @ref{RANGE}, @ref{RADIX}
10765 @item @emph{Example}:
10768 integer,parameter :: p6 = selected_real_kind(6)
10769 integer,parameter :: p10r100 = selected_real_kind(10,100)
10770 integer,parameter :: r400 = selected_real_kind(r=400)
10772 real(kind=p10r100) :: y
10773 real(kind=r400) :: z
10775 print *, precision(x), range(x)
10776 print *, precision(y), range(y)
10777 print *, precision(z), range(z)
10778 end program real_kinds
10785 @section @code{SET_EXPONENT} --- Set the exponent of the model
10786 @fnindex SET_EXPONENT
10787 @cindex real number, set exponent
10788 @cindex floating point, set exponent
10791 @item @emph{Description}:
10792 @code{SET_EXPONENT(X, I)} returns the real number whose fractional part
10793 is that that of @var{X} and whose exponent part is @var{I}.
10795 @item @emph{Standard}:
10796 Fortran 95 and later
10798 @item @emph{Class}:
10801 @item @emph{Syntax}:
10802 @code{RESULT = SET_EXPONENT(X, I)}
10804 @item @emph{Arguments}:
10805 @multitable @columnfractions .15 .70
10806 @item @var{X} @tab Shall be of type @code{REAL}.
10807 @item @var{I} @tab Shall be of type @code{INTEGER}.
10810 @item @emph{Return value}:
10811 The return value is of the same type and kind as @var{X}.
10812 The real number whose fractional part
10813 is that that of @var{X} and whose exponent part if @var{I} is returned;
10814 it is @code{FRACTION(X) * RADIX(X)**I}.
10816 @item @emph{Example}:
10818 PROGRAM test_setexp
10819 REAL :: x = 178.1387e-4
10821 PRINT *, SET_EXPONENT(x, i), FRACTION(x) * RADIX(x)**i
10830 @section @code{SHAPE} --- Determine the shape of an array
10832 @cindex array, shape
10835 @item @emph{Description}:
10836 Determines the shape of an array.
10838 @item @emph{Standard}:
10839 Fortran 95 and later, with @var{KIND} argument Fortran 2003 and later
10841 @item @emph{Class}:
10844 @item @emph{Syntax}:
10845 @code{RESULT = SHAPE(SOURCE [, KIND])}
10847 @item @emph{Arguments}:
10848 @multitable @columnfractions .15 .70
10849 @item @var{SOURCE} @tab Shall be an array or scalar of any type.
10850 If @var{SOURCE} is a pointer it must be associated and allocatable
10851 arrays must be allocated.
10852 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
10853 expression indicating the kind parameter of the result.
10856 @item @emph{Return value}:
10857 An @code{INTEGER} array of rank one with as many elements as @var{SOURCE}
10858 has dimensions. The elements of the resulting array correspond to the extend
10859 of @var{SOURCE} along the respective dimensions. If @var{SOURCE} is a scalar,
10860 the result is the rank one array of size zero. If @var{KIND} is absent, the
10861 return value has the default integer kind otherwise the specified kind.
10863 @item @emph{Example}:
10866 INTEGER, DIMENSION(-1:1, -1:2) :: A
10867 WRITE(*,*) SHAPE(A) ! (/ 3, 4 /)
10868 WRITE(*,*) SIZE(SHAPE(42)) ! (/ /)
10872 @item @emph{See also}:
10873 @ref{RESHAPE}, @ref{SIZE}
10879 @section @code{SHIFTA} --- Right shift with fill
10881 @cindex bits, shift right
10882 @cindex shift, right with fill
10885 @item @emph{Description}:
10886 @code{SHIFTA} returns a value corresponding to @var{I} with all of the
10887 bits shifted right by @var{SHIFT} places. If the absolute value of
10888 @var{SHIFT} is greater than @code{BIT_SIZE(I)}, the value is undefined.
10889 Bits shifted out from the right end are lost. The fill is arithmetic: the
10890 bits shifted in from the left end are equal to the leftmost bit, which in
10891 two's complement representation is the sign bit.
10893 @item @emph{Standard}:
10894 Fortran 2008 and later
10896 @item @emph{Class}:
10899 @item @emph{Syntax}:
10900 @code{RESULT = SHIFTA(I, SHIFT)}
10902 @item @emph{Arguments}:
10903 @multitable @columnfractions .15 .70
10904 @item @var{I} @tab The type shall be @code{INTEGER}.
10905 @item @var{SHIFT} @tab The type shall be @code{INTEGER}.
10908 @item @emph{Return value}:
10909 The return value is of type @code{INTEGER} and of the same kind as
10912 @item @emph{See also}:
10913 @ref{SHIFTL}, @ref{SHIFTR}
10919 @section @code{SHIFTL} --- Left shift
10921 @cindex bits, shift left
10922 @cindex shift, left
10925 @item @emph{Description}:
10926 @code{SHIFTL} returns a value corresponding to @var{I} with all of the
10927 bits shifted left by @var{SHIFT} places. If the absolute value of
10928 @var{SHIFT} is greater than @code{BIT_SIZE(I)}, the value is undefined.
10929 Bits shifted out from the left end are lost, and bits shifted in from
10930 the right end are set to 0.
10932 @item @emph{Standard}:
10933 Fortran 2008 and later
10935 @item @emph{Class}:
10938 @item @emph{Syntax}:
10939 @code{RESULT = SHIFTL(I, SHIFT)}
10941 @item @emph{Arguments}:
10942 @multitable @columnfractions .15 .70
10943 @item @var{I} @tab The type shall be @code{INTEGER}.
10944 @item @var{SHIFT} @tab The type shall be @code{INTEGER}.
10947 @item @emph{Return value}:
10948 The return value is of type @code{INTEGER} and of the same kind as
10951 @item @emph{See also}:
10952 @ref{SHIFTA}, @ref{SHIFTR}
10958 @section @code{SHIFTR} --- Right shift
10960 @cindex bits, shift right
10961 @cindex shift, right
10964 @item @emph{Description}:
10965 @code{SHIFTR} returns a value corresponding to @var{I} with all of the
10966 bits shifted right by @var{SHIFT} places. If the absolute value of
10967 @var{SHIFT} is greater than @code{BIT_SIZE(I)}, the value is undefined.
10968 Bits shifted out from the right end are lost, and bits shifted in from
10969 the left end are set to 0.
10971 @item @emph{Standard}:
10972 Fortran 2008 and later
10974 @item @emph{Class}:
10977 @item @emph{Syntax}:
10978 @code{RESULT = SHIFTR(I, SHIFT)}
10980 @item @emph{Arguments}:
10981 @multitable @columnfractions .15 .70
10982 @item @var{I} @tab The type shall be @code{INTEGER}.
10983 @item @var{SHIFT} @tab The type shall be @code{INTEGER}.
10986 @item @emph{Return value}:
10987 The return value is of type @code{INTEGER} and of the same kind as
10990 @item @emph{See also}:
10991 @ref{SHIFTA}, @ref{SHIFTL}
10997 @section @code{SIGN} --- Sign copying function
11001 @cindex sign copying
11004 @item @emph{Description}:
11005 @code{SIGN(A,B)} returns the value of @var{A} with the sign of @var{B}.
11007 @item @emph{Standard}:
11008 Fortran 77 and later
11010 @item @emph{Class}:
11013 @item @emph{Syntax}:
11014 @code{RESULT = SIGN(A, B)}
11016 @item @emph{Arguments}:
11017 @multitable @columnfractions .15 .70
11018 @item @var{A} @tab Shall be of type @code{INTEGER} or @code{REAL}
11019 @item @var{B} @tab Shall be of the same type and kind as @var{A}
11022 @item @emph{Return value}:
11023 The kind of the return value is that of @var{A} and @var{B}.
11024 If @math{B\ge 0} then the result is @code{ABS(A)}, else
11025 it is @code{-ABS(A)}.
11027 @item @emph{Example}:
11030 print *, sign(-12,1)
11031 print *, sign(-12,0)
11032 print *, sign(-12,-1)
11034 print *, sign(-12.,1.)
11035 print *, sign(-12.,0.)
11036 print *, sign(-12.,-1.)
11037 end program test_sign
11040 @item @emph{Specific names}:
11041 @multitable @columnfractions .20 .20 .20 .25
11042 @item Name @tab Arguments @tab Return type @tab Standard
11043 @item @code{SIGN(A,B)} @tab @code{REAL(4) A, B} @tab @code{REAL(4)} @tab f77, gnu
11044 @item @code{ISIGN(A,B)} @tab @code{INTEGER(4) A, B} @tab @code{INTEGER(4)} @tab f77, gnu
11045 @item @code{DSIGN(A,B)} @tab @code{REAL(8) A, B} @tab @code{REAL(8)} @tab f77, gnu
11052 @section @code{SIGNAL} --- Signal handling subroutine (or function)
11054 @cindex system, signal handling
11057 @item @emph{Description}:
11058 @code{SIGNAL(NUMBER, HANDLER [, STATUS])} causes external subroutine
11059 @var{HANDLER} to be executed with a single integer argument when signal
11060 @var{NUMBER} occurs. If @var{HANDLER} is an integer, it can be used to
11061 turn off handling of signal @var{NUMBER} or revert to its default
11062 action. See @code{signal(2)}.
11064 If @code{SIGNAL} is called as a subroutine and the @var{STATUS} argument
11065 is supplied, it is set to the value returned by @code{signal(2)}.
11067 @item @emph{Standard}:
11070 @item @emph{Class}:
11071 Subroutine, function
11073 @item @emph{Syntax}:
11074 @multitable @columnfractions .80
11075 @item @code{CALL SIGNAL(NUMBER, HANDLER [, STATUS])}
11076 @item @code{STATUS = SIGNAL(NUMBER, HANDLER)}
11079 @item @emph{Arguments}:
11080 @multitable @columnfractions .15 .70
11081 @item @var{NUMBER} @tab Shall be a scalar integer, with @code{INTENT(IN)}
11082 @item @var{HANDLER}@tab Signal handler (@code{INTEGER FUNCTION} or
11083 @code{SUBROUTINE}) or dummy/global @code{INTEGER} scalar.
11084 @code{INTEGER}. It is @code{INTENT(IN)}.
11085 @item @var{STATUS} @tab (Optional) @var{STATUS} shall be a scalar
11086 integer. It has @code{INTENT(OUT)}.
11088 @c TODO: What should the interface of the handler be? Does it take arguments?
11090 @item @emph{Return value}:
11091 The @code{SIGNAL} function returns the value returned by @code{signal(2)}.
11093 @item @emph{Example}:
11095 program test_signal
11097 external handler_print
11099 call signal (12, handler_print)
11100 call signal (10, 1)
11103 end program test_signal
11110 @section @code{SIN} --- Sine function
11116 @cindex trigonometric function, sine
11120 @item @emph{Description}:
11121 @code{SIN(X)} computes the sine of @var{X}.
11123 @item @emph{Standard}:
11124 Fortran 77 and later
11126 @item @emph{Class}:
11129 @item @emph{Syntax}:
11130 @code{RESULT = SIN(X)}
11132 @item @emph{Arguments}:
11133 @multitable @columnfractions .15 .70
11134 @item @var{X} @tab The type shall be @code{REAL} or
11138 @item @emph{Return value}:
11139 The return value has same type and kind as @var{X}.
11141 @item @emph{Example}:
11146 end program test_sin
11149 @item @emph{Specific names}:
11150 @multitable @columnfractions .20 .20 .20 .25
11151 @item Name @tab Argument @tab Return type @tab Standard
11152 @item @code{SIN(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab f77, gnu
11153 @item @code{DSIN(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab f95, gnu
11154 @item @code{CSIN(X)} @tab @code{COMPLEX(4) X} @tab @code{COMPLEX(4)} @tab f95, gnu
11155 @item @code{ZSIN(X)} @tab @code{COMPLEX(8) X} @tab @code{COMPLEX(8)} @tab f95, gnu
11156 @item @code{CDSIN(X)} @tab @code{COMPLEX(8) X} @tab @code{COMPLEX(8)} @tab f95, gnu
11159 @item @emph{See also}:
11166 @section @code{SINH} --- Hyperbolic sine function
11169 @cindex hyperbolic sine
11170 @cindex hyperbolic function, sine
11171 @cindex sine, hyperbolic
11174 @item @emph{Description}:
11175 @code{SINH(X)} computes the hyperbolic sine of @var{X}.
11177 @item @emph{Standard}:
11178 Fortran 95 and later, for a complex argument Fortran 2008 or later
11180 @item @emph{Class}:
11183 @item @emph{Syntax}:
11184 @code{RESULT = SINH(X)}
11186 @item @emph{Arguments}:
11187 @multitable @columnfractions .15 .70
11188 @item @var{X} @tab The type shall be @code{REAL} or @code{COMPLEX}.
11191 @item @emph{Return value}:
11192 The return value has same type and kind as @var{X}.
11194 @item @emph{Example}:
11197 real(8) :: x = - 1.0_8
11199 end program test_sinh
11202 @item @emph{Specific names}:
11203 @multitable @columnfractions .20 .20 .20 .25
11204 @item Name @tab Argument @tab Return type @tab Standard
11205 @item @code{SINH(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab Fortran 95 and later
11206 @item @code{DSINH(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab Fortran 95 and later
11209 @item @emph{See also}:
11216 @section @code{SIZE} --- Determine the size of an array
11218 @cindex array, size
11219 @cindex array, number of elements
11220 @cindex array, count elements
11223 @item @emph{Description}:
11224 Determine the extent of @var{ARRAY} along a specified dimension @var{DIM},
11225 or the total number of elements in @var{ARRAY} if @var{DIM} is absent.
11227 @item @emph{Standard}:
11228 Fortran 95 and later, with @var{KIND} argument Fortran 2003 and later
11230 @item @emph{Class}:
11233 @item @emph{Syntax}:
11234 @code{RESULT = SIZE(ARRAY[, DIM [, KIND]])}
11236 @item @emph{Arguments}:
11237 @multitable @columnfractions .15 .70
11238 @item @var{ARRAY} @tab Shall be an array of any type. If @var{ARRAY} is
11239 a pointer it must be associated and allocatable arrays must be allocated.
11240 @item @var{DIM} @tab (Optional) shall be a scalar of type @code{INTEGER}
11241 and its value shall be in the range from 1 to n, where n equals the rank
11243 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
11244 expression indicating the kind parameter of the result.
11247 @item @emph{Return value}:
11248 The return value is of type @code{INTEGER} and of kind @var{KIND}. If
11249 @var{KIND} is absent, the return value is of default integer kind.
11251 @item @emph{Example}:
11254 WRITE(*,*) SIZE((/ 1, 2 /)) ! 2
11258 @item @emph{See also}:
11259 @ref{SHAPE}, @ref{RESHAPE}
11264 @section @code{SIZEOF} --- Size in bytes of an expression
11266 @cindex expression size
11267 @cindex size of an expression
11270 @item @emph{Description}:
11271 @code{SIZEOF(X)} calculates the number of bytes of storage the
11272 expression @code{X} occupies.
11274 @item @emph{Standard}:
11277 @item @emph{Class}:
11280 @item @emph{Syntax}:
11281 @code{N = SIZEOF(X)}
11283 @item @emph{Arguments}:
11284 @multitable @columnfractions .15 .70
11285 @item @var{X} @tab The argument shall be of any type, rank or shape.
11288 @item @emph{Return value}:
11289 The return value is of type integer and of the system-dependent kind
11290 @var{C_SIZE_T} (from the @var{ISO_C_BINDING} module). Its value is the
11291 number of bytes occupied by the argument. If the argument has the
11292 @code{POINTER} attribute, the number of bytes of the storage area pointed
11293 to is returned. If the argument is of a derived type with @code{POINTER}
11294 or @code{ALLOCATABLE} components, the return value doesn't account for
11295 the sizes of the data pointed to by these components. If the argument is
11296 polymorphic, the size according to the declared type is returned.
11298 @item @emph{Example}:
11302 print *, (sizeof(s)/sizeof(r) == 5)
11305 The example will print @code{.TRUE.} unless you are using a platform
11306 where default @code{REAL} variables are unusually padded.
11308 @item @emph{See also}:
11309 @ref{C_SIZEOF}, @ref{STORAGE_SIZE}
11314 @section @code{SLEEP} --- Sleep for the specified number of seconds
11316 @cindex delayed execution
11319 @item @emph{Description}:
11320 Calling this subroutine causes the process to pause for @var{SECONDS} seconds.
11322 @item @emph{Standard}:
11325 @item @emph{Class}:
11328 @item @emph{Syntax}:
11329 @code{CALL SLEEP(SECONDS)}
11331 @item @emph{Arguments}:
11332 @multitable @columnfractions .15 .70
11333 @item @var{SECONDS} @tab The type shall be of default @code{INTEGER}.
11336 @item @emph{Example}:
11347 @section @code{SPACING} --- Smallest distance between two numbers of a given type
11349 @cindex real number, relative spacing
11350 @cindex floating point, relative spacing
11353 @item @emph{Description}:
11354 Determines the distance between the argument @var{X} and the nearest
11355 adjacent number of the same type.
11357 @item @emph{Standard}:
11358 Fortran 95 and later
11360 @item @emph{Class}:
11363 @item @emph{Syntax}:
11364 @code{RESULT = SPACING(X)}
11366 @item @emph{Arguments}:
11367 @multitable @columnfractions .15 .70
11368 @item @var{X} @tab Shall be of type @code{REAL}.
11371 @item @emph{Return value}:
11372 The result is of the same type as the input argument @var{X}.
11374 @item @emph{Example}:
11376 PROGRAM test_spacing
11377 INTEGER, PARAMETER :: SGL = SELECTED_REAL_KIND(p=6, r=37)
11378 INTEGER, PARAMETER :: DBL = SELECTED_REAL_KIND(p=13, r=200)
11380 WRITE(*,*) spacing(1.0_SGL) ! "1.1920929E-07" on i686
11381 WRITE(*,*) spacing(1.0_DBL) ! "2.220446049250313E-016" on i686
11385 @item @emph{See also}:
11392 @section @code{SPREAD} --- Add a dimension to an array
11394 @cindex array, increase dimension
11395 @cindex array, duplicate elements
11396 @cindex array, duplicate dimensions
11399 @item @emph{Description}:
11400 Replicates a @var{SOURCE} array @var{NCOPIES} times along a specified
11401 dimension @var{DIM}.
11403 @item @emph{Standard}:
11404 Fortran 95 and later
11406 @item @emph{Class}:
11407 Transformational function
11409 @item @emph{Syntax}:
11410 @code{RESULT = SPREAD(SOURCE, DIM, NCOPIES)}
11412 @item @emph{Arguments}:
11413 @multitable @columnfractions .15 .70
11414 @item @var{SOURCE} @tab Shall be a scalar or an array of any type and
11415 a rank less than seven.
11416 @item @var{DIM} @tab Shall be a scalar of type @code{INTEGER} with a
11417 value in the range from 1 to n+1, where n equals the rank of @var{SOURCE}.
11418 @item @var{NCOPIES} @tab Shall be a scalar of type @code{INTEGER}.
11421 @item @emph{Return value}:
11422 The result is an array of the same type as @var{SOURCE} and has rank n+1
11423 where n equals the rank of @var{SOURCE}.
11425 @item @emph{Example}:
11427 PROGRAM test_spread
11428 INTEGER :: a = 1, b(2) = (/ 1, 2 /)
11429 WRITE(*,*) SPREAD(A, 1, 2) ! "1 1"
11430 WRITE(*,*) SPREAD(B, 1, 2) ! "1 1 2 2"
11434 @item @emph{See also}:
11441 @section @code{SQRT} --- Square-root function
11448 @cindex square-root
11451 @item @emph{Description}:
11452 @code{SQRT(X)} computes the square root of @var{X}.
11454 @item @emph{Standard}:
11455 Fortran 77 and later
11457 @item @emph{Class}:
11460 @item @emph{Syntax}:
11461 @code{RESULT = SQRT(X)}
11463 @item @emph{Arguments}:
11464 @multitable @columnfractions .15 .70
11465 @item @var{X} @tab The type shall be @code{REAL} or
11469 @item @emph{Return value}:
11470 The return value is of type @code{REAL} or @code{COMPLEX}.
11471 The kind type parameter is the same as @var{X}.
11473 @item @emph{Example}:
11476 real(8) :: x = 2.0_8
11477 complex :: z = (1.0, 2.0)
11480 end program test_sqrt
11483 @item @emph{Specific names}:
11484 @multitable @columnfractions .20 .20 .20 .25
11485 @item Name @tab Argument @tab Return type @tab Standard
11486 @item @code{SQRT(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab Fortran 95 and later
11487 @item @code{DSQRT(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab Fortran 95 and later
11488 @item @code{CSQRT(X)} @tab @code{COMPLEX(4) X} @tab @code{COMPLEX(4)} @tab Fortran 95 and later
11489 @item @code{ZSQRT(X)} @tab @code{COMPLEX(8) X} @tab @code{COMPLEX(8)} @tab GNU extension
11490 @item @code{CDSQRT(X)} @tab @code{COMPLEX(8) X} @tab @code{COMPLEX(8)} @tab GNU extension
11497 @section @code{SRAND} --- Reinitialize the random number generator
11499 @cindex random number generation, seeding
11500 @cindex seeding a random number generator
11503 @item @emph{Description}:
11504 @code{SRAND} reinitializes the pseudo-random number generator
11505 called by @code{RAND} and @code{IRAND}. The new seed used by the
11506 generator is specified by the required argument @var{SEED}.
11508 @item @emph{Standard}:
11511 @item @emph{Class}:
11514 @item @emph{Syntax}:
11515 @code{CALL SRAND(SEED)}
11517 @item @emph{Arguments}:
11518 @multitable @columnfractions .15 .70
11519 @item @var{SEED} @tab Shall be a scalar @code{INTEGER(kind=4)}.
11522 @item @emph{Return value}:
11523 Does not return anything.
11525 @item @emph{Example}:
11526 See @code{RAND} and @code{IRAND} for examples.
11528 @item @emph{Notes}:
11529 The Fortran 2003 standard specifies the intrinsic @code{RANDOM_SEED} to
11530 initialize the pseudo-random numbers generator and @code{RANDOM_NUMBER}
11531 to generate pseudo-random numbers. Please note that in
11532 GNU Fortran, these two sets of intrinsics (@code{RAND},
11533 @code{IRAND} and @code{SRAND} on the one hand, @code{RANDOM_NUMBER} and
11534 @code{RANDOM_SEED} on the other hand) access two independent
11535 pseudo-random number generators.
11537 @item @emph{See also}:
11538 @ref{RAND}, @ref{RANDOM_SEED}, @ref{RANDOM_NUMBER}
11545 @section @code{STAT} --- Get file status
11547 @cindex file system, file status
11550 @item @emph{Description}:
11551 This function returns information about a file. No permissions are required on
11552 the file itself, but execute (search) permission is required on all of the
11553 directories in path that lead to the file.
11555 The elements that are obtained and stored in the array @code{VALUES}:
11556 @multitable @columnfractions .15 .70
11557 @item @code{VALUES(1)} @tab Device ID
11558 @item @code{VALUES(2)} @tab Inode number
11559 @item @code{VALUES(3)} @tab File mode
11560 @item @code{VALUES(4)} @tab Number of links
11561 @item @code{VALUES(5)} @tab Owner's uid
11562 @item @code{VALUES(6)} @tab Owner's gid
11563 @item @code{VALUES(7)} @tab ID of device containing directory entry for file (0 if not available)
11564 @item @code{VALUES(8)} @tab File size (bytes)
11565 @item @code{VALUES(9)} @tab Last access time
11566 @item @code{VALUES(10)} @tab Last modification time
11567 @item @code{VALUES(11)} @tab Last file status change time
11568 @item @code{VALUES(12)} @tab Preferred I/O block size (-1 if not available)
11569 @item @code{VALUES(13)} @tab Number of blocks allocated (-1 if not available)
11572 Not all these elements are relevant on all systems.
11573 If an element is not relevant, it is returned as 0.
11575 This intrinsic is provided in both subroutine and function forms; however,
11576 only one form can be used in any given program unit.
11578 @item @emph{Standard}:
11581 @item @emph{Class}:
11582 Subroutine, function
11584 @item @emph{Syntax}:
11585 @multitable @columnfractions .80
11586 @item @code{CALL STAT(NAME, VALUES [, STATUS])}
11587 @item @code{STATUS = STAT(NAME, VALUES)}
11590 @item @emph{Arguments}:
11591 @multitable @columnfractions .15 .70
11592 @item @var{NAME} @tab The type shall be @code{CHARACTER}, of the
11593 default kind and a valid path within the file system.
11594 @item @var{VALUES} @tab The type shall be @code{INTEGER(4), DIMENSION(13)}.
11595 @item @var{STATUS} @tab (Optional) status flag of type @code{INTEGER(4)}. Returns 0
11596 on success and a system specific error code otherwise.
11599 @item @emph{Example}:
11602 INTEGER, DIMENSION(13) :: buff
11605 CALL STAT("/etc/passwd", buff, status)
11607 IF (status == 0) THEN
11608 WRITE (*, FMT="('Device ID:', T30, I19)") buff(1)
11609 WRITE (*, FMT="('Inode number:', T30, I19)") buff(2)
11610 WRITE (*, FMT="('File mode (octal):', T30, O19)") buff(3)
11611 WRITE (*, FMT="('Number of links:', T30, I19)") buff(4)
11612 WRITE (*, FMT="('Owner''s uid:', T30, I19)") buff(5)
11613 WRITE (*, FMT="('Owner''s gid:', T30, I19)") buff(6)
11614 WRITE (*, FMT="('Device where located:', T30, I19)") buff(7)
11615 WRITE (*, FMT="('File size:', T30, I19)") buff(8)
11616 WRITE (*, FMT="('Last access time:', T30, A19)") CTIME(buff(9))
11617 WRITE (*, FMT="('Last modification time', T30, A19)") CTIME(buff(10))
11618 WRITE (*, FMT="('Last status change time:', T30, A19)") CTIME(buff(11))
11619 WRITE (*, FMT="('Preferred block size:', T30, I19)") buff(12)
11620 WRITE (*, FMT="('No. of blocks allocated:', T30, I19)") buff(13)
11625 @item @emph{See also}:
11626 To stat an open file: @ref{FSTAT}, to stat a link: @ref{LSTAT}
11632 @section @code{STORAGE_SIZE} --- Storage size in bits
11633 @fnindex STORAGE_SIZE
11634 @cindex storage size
11637 @item @emph{Description}:
11638 Returns the storage size of argument @var{A} in bits.
11639 @item @emph{Standard}:
11640 Fortran 2008 and later
11641 @item @emph{Class}:
11643 @item @emph{Syntax}:
11644 @code{RESULT = STORAGE_SIZE(A [, KIND])}
11646 @item @emph{Arguments}:
11647 @multitable @columnfractions .15 .70
11648 @item @var{A} @tab Shall be a scalar or array of any type.
11649 @item @var{KIND} @tab (Optional) shall be a scalar integer constant expression.
11652 @item @emph{Return Value}:
11653 The result is a scalar integer with the kind type parameter specified by KIND (or default integer type if KIND is missing). The result value is the size expressed in bits for an element of an array that
11654 has the dynamic type and type parameters of A.
11656 @item @emph{See also}:
11657 @ref{C_SIZEOF}, @ref{SIZEOF}
11663 @section @code{SUM} --- Sum of array elements
11666 @cindex array, add elements
11667 @cindex array, conditionally add elements
11668 @cindex sum array elements
11671 @item @emph{Description}:
11672 Adds the elements of @var{ARRAY} along dimension @var{DIM} if
11673 the corresponding element in @var{MASK} is @code{TRUE}.
11675 @item @emph{Standard}:
11676 Fortran 95 and later
11678 @item @emph{Class}:
11679 Transformational function
11681 @item @emph{Syntax}:
11682 @multitable @columnfractions .80
11683 @item @code{RESULT = SUM(ARRAY[, MASK])}
11684 @item @code{RESULT = SUM(ARRAY, DIM[, MASK])}
11687 @item @emph{Arguments}:
11688 @multitable @columnfractions .15 .70
11689 @item @var{ARRAY} @tab Shall be an array of type @code{INTEGER},
11690 @code{REAL} or @code{COMPLEX}.
11691 @item @var{DIM} @tab (Optional) shall be a scalar of type
11692 @code{INTEGER} with a value in the range from 1 to n, where n
11693 equals the rank of @var{ARRAY}.
11694 @item @var{MASK} @tab (Optional) shall be of type @code{LOGICAL}
11695 and either be a scalar or an array of the same shape as @var{ARRAY}.
11698 @item @emph{Return value}:
11699 The result is of the same type as @var{ARRAY}.
11701 If @var{DIM} is absent, a scalar with the sum of all elements in @var{ARRAY}
11702 is returned. Otherwise, an array of rank n-1, where n equals the rank of
11703 @var{ARRAY}, and a shape similar to that of @var{ARRAY} with dimension @var{DIM}
11704 dropped is returned.
11706 @item @emph{Example}:
11709 INTEGER :: x(5) = (/ 1, 2, 3, 4 ,5 /)
11710 print *, SUM(x) ! all elements, sum = 15
11711 print *, SUM(x, MASK=MOD(x, 2)==1) ! odd elements, sum = 9
11715 @item @emph{See also}:
11722 @section @code{SYMLNK} --- Create a symbolic link
11724 @cindex file system, create link
11725 @cindex file system, soft link
11728 @item @emph{Description}:
11729 Makes a symbolic link from file @var{PATH1} to @var{PATH2}. A null
11730 character (@code{CHAR(0)}) can be used to mark the end of the names in
11731 @var{PATH1} and @var{PATH2}; otherwise, trailing blanks in the file
11732 names are ignored. If the @var{STATUS} argument is supplied, it
11733 contains 0 on success or a nonzero error code upon return; see
11734 @code{symlink(2)}. If the system does not supply @code{symlink(2)},
11735 @code{ENOSYS} is returned.
11737 This intrinsic is provided in both subroutine and function forms;
11738 however, only one form can be used in any given program unit.
11740 @item @emph{Standard}:
11743 @item @emph{Class}:
11744 Subroutine, function
11746 @item @emph{Syntax}:
11747 @multitable @columnfractions .80
11748 @item @code{CALL SYMLNK(PATH1, PATH2 [, STATUS])}
11749 @item @code{STATUS = SYMLNK(PATH1, PATH2)}
11752 @item @emph{Arguments}:
11753 @multitable @columnfractions .15 .70
11754 @item @var{PATH1} @tab Shall be of default @code{CHARACTER} type.
11755 @item @var{PATH2} @tab Shall be of default @code{CHARACTER} type.
11756 @item @var{STATUS} @tab (Optional) Shall be of default @code{INTEGER} type.
11759 @item @emph{See also}:
11760 @ref{LINK}, @ref{UNLINK}
11767 @section @code{SYSTEM} --- Execute a shell command
11769 @cindex system, system call
11772 @item @emph{Description}:
11773 Passes the command @var{COMMAND} to a shell (see @code{system(3)}). If
11774 argument @var{STATUS} is present, it contains the value returned by
11775 @code{system(3)}, which is presumably 0 if the shell command succeeded.
11776 Note that which shell is used to invoke the command is system-dependent
11777 and environment-dependent.
11779 This intrinsic is provided in both subroutine and function forms;
11780 however, only one form can be used in any given program unit.
11782 @item @emph{Standard}:
11785 @item @emph{Class}:
11786 Subroutine, function
11788 @item @emph{Syntax}:
11789 @multitable @columnfractions .80
11790 @item @code{CALL SYSTEM(COMMAND [, STATUS])}
11791 @item @code{STATUS = SYSTEM(COMMAND)}
11794 @item @emph{Arguments}:
11795 @multitable @columnfractions .15 .70
11796 @item @var{COMMAND} @tab Shall be of default @code{CHARACTER} type.
11797 @item @var{STATUS} @tab (Optional) Shall be of default @code{INTEGER} type.
11800 @item @emph{See also}:
11801 @ref{EXECUTE_COMMAND_LINE}, which is part of the Fortran 2008 standard
11802 and should considered in new code for future portability.
11808 @section @code{SYSTEM_CLOCK} --- Time function
11809 @fnindex SYSTEM_CLOCK
11810 @cindex time, clock ticks
11811 @cindex clock ticks
11814 @item @emph{Description}:
11815 Determines the @var{COUNT} of a processor clock since an unspecified
11816 time in the past modulo @var{COUNT_MAX}, @var{COUNT_RATE} determines
11817 the number of clock ticks per second. If the platform supports a high
11818 resolution monotonic clock, that clock is used and can provide up to
11819 nanosecond resolution. If a high resolution monotonic clock is not
11820 available, the implementation falls back to a potentially lower
11821 resolution realtime clock.
11823 @var{COUNT_RATE} and @var{COUNT_MAX} vary depending on the kind of the
11824 arguments. For @var{kind=8} arguments, @var{COUNT} represents
11825 nanoseconds, and for @var{kind=4} arguments, @var{COUNT} represents
11826 milliseconds. Other than the kind dependency, @var{COUNT_RATE} and
11827 @var{COUNT_MAX} are constant, however the particular values are
11828 specific to @command{gfortran}.
11830 If there is no clock, @var{COUNT} is set to @code{-HUGE(COUNT)}, and
11831 @var{COUNT_RATE} and @var{COUNT_MAX} are set to zero.
11833 When running on a platform using the GNU C library (glibc), or a
11834 derivative thereof, the high resolution monotonic clock is available
11835 only when linking with the @var{rt} library. This can be done
11836 explicitly by adding the @code{-lrt} flag when linking the
11837 application, but is also done implicitly when using OpenMP.
11839 @item @emph{Standard}:
11840 Fortran 95 and later
11842 @item @emph{Class}:
11845 @item @emph{Syntax}:
11846 @code{CALL SYSTEM_CLOCK([COUNT, COUNT_RATE, COUNT_MAX])}
11848 @item @emph{Arguments}:
11849 @multitable @columnfractions .15 .70
11850 @item @var{COUNT} @tab (Optional) shall be a scalar of type
11851 @code{INTEGER} with @code{INTENT(OUT)}.
11852 @item @var{COUNT_RATE} @tab (Optional) shall be a scalar of type
11853 @code{INTEGER} with @code{INTENT(OUT)}.
11854 @item @var{COUNT_MAX} @tab (Optional) shall be a scalar of type
11855 @code{INTEGER} with @code{INTENT(OUT)}.
11858 @item @emph{Example}:
11860 PROGRAM test_system_clock
11861 INTEGER :: count, count_rate, count_max
11862 CALL SYSTEM_CLOCK(count, count_rate, count_max)
11863 WRITE(*,*) count, count_rate, count_max
11867 @item @emph{See also}:
11868 @ref{DATE_AND_TIME}, @ref{CPU_TIME}
11874 @section @code{TAN} --- Tangent function
11877 @cindex trigonometric function, tangent
11881 @item @emph{Description}:
11882 @code{TAN(X)} computes the tangent of @var{X}.
11884 @item @emph{Standard}:
11885 Fortran 77 and later, for a complex argument Fortran 2008 or later
11887 @item @emph{Class}:
11890 @item @emph{Syntax}:
11891 @code{RESULT = TAN(X)}
11893 @item @emph{Arguments}:
11894 @multitable @columnfractions .15 .70
11895 @item @var{X} @tab The type shall be @code{REAL} or @code{COMPLEX}.
11898 @item @emph{Return value}:
11899 The return value has same type and kind as @var{X}.
11901 @item @emph{Example}:
11904 real(8) :: x = 0.165_8
11906 end program test_tan
11909 @item @emph{Specific names}:
11910 @multitable @columnfractions .20 .20 .20 .25
11911 @item Name @tab Argument @tab Return type @tab Standard
11912 @item @code{TAN(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab Fortran 95 and later
11913 @item @code{DTAN(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab Fortran 95 and later
11916 @item @emph{See also}:
11923 @section @code{TANH} --- Hyperbolic tangent function
11926 @cindex hyperbolic tangent
11927 @cindex hyperbolic function, tangent
11928 @cindex tangent, hyperbolic
11931 @item @emph{Description}:
11932 @code{TANH(X)} computes the hyperbolic tangent of @var{X}.
11934 @item @emph{Standard}:
11935 Fortran 77 and later, for a complex argument Fortran 2008 or later
11937 @item @emph{Class}:
11940 @item @emph{Syntax}:
11943 @item @emph{Arguments}:
11944 @multitable @columnfractions .15 .70
11945 @item @var{X} @tab The type shall be @code{REAL} or @code{COMPLEX}.
11948 @item @emph{Return value}:
11949 The return value has same type and kind as @var{X}. If @var{X} is
11950 complex, the imaginary part of the result is in radians. If @var{X}
11951 is @code{REAL}, the return value lies in the range
11952 @math{ - 1 \leq tanh(x) \leq 1 }.
11954 @item @emph{Example}:
11957 real(8) :: x = 2.1_8
11959 end program test_tanh
11962 @item @emph{Specific names}:
11963 @multitable @columnfractions .20 .20 .20 .25
11964 @item Name @tab Argument @tab Return type @tab Standard
11965 @item @code{TANH(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab Fortran 95 and later
11966 @item @code{DTANH(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab Fortran 95 and later
11969 @item @emph{See also}:
11976 @section @code{THIS_IMAGE} --- Function that returns the cosubscript index of this image
11977 @fnindex THIS_IMAGE
11978 @cindex coarray, @code{THIS_IMAGE}
11979 @cindex images, index of this image
11982 @item @emph{Description}:
11983 Returns the cosubscript for this image.
11985 @item @emph{Standard}:
11986 Fortran 2008 and later
11988 @item @emph{Class}:
11989 Transformational function
11991 @item @emph{Syntax}:
11992 @multitable @columnfractions .80
11993 @item @code{RESULT = THIS_IMAGE()}
11994 @item @code{RESULT = THIS_IMAGE(COARRAY [, DIM])}
11997 @item @emph{Arguments}:
11998 @multitable @columnfractions .15 .70
11999 @item @var{COARRAY} @tab Coarray of any type (optional; if @var{DIM}
12000 present, required).
12001 @item @var{DIM} @tab default integer scalar (optional). If present,
12002 @var{DIM} shall be between one and the corank of @var{COARRAY}.
12006 @item @emph{Return value}:
12007 Default integer. If @var{COARRAY} is not present, it is scalar and its value
12008 is the index of the invoking image. Otherwise, if @var{DIM} is not present,
12009 a rank-1 array with corank elements is returned, containing the cosubscripts
12010 for @var{COARRAY} specifying the invoking image. If @var{DIM} is present,
12011 a scalar is returned, with the value of the @var{DIM} element of
12012 @code{THIS_IMAGE(COARRAY)}.
12014 @item @emph{Example}:
12016 INTEGER :: value[*]
12018 value = THIS_IMAGE()
12020 IF (THIS_IMAGE() == 1) THEN
12021 DO i = 1, NUM_IMAGES()
12022 WRITE(*,'(2(a,i0))') 'value[', i, '] is ', value[i]
12027 @item @emph{See also}:
12028 @ref{NUM_IMAGES}, @ref{IMAGE_INDEX}
12034 @section @code{TIME} --- Time function
12036 @cindex time, current
12037 @cindex current time
12040 @item @emph{Description}:
12041 Returns the current time encoded as an integer (in the manner of the
12042 UNIX function @code{time(3)}). This value is suitable for passing to
12043 @code{CTIME()}, @code{GMTIME()}, and @code{LTIME()}.
12045 This intrinsic is not fully portable, such as to systems with 32-bit
12046 @code{INTEGER} types but supporting times wider than 32 bits. Therefore,
12047 the values returned by this intrinsic might be, or become, negative, or
12048 numerically less than previous values, during a single run of the
12051 See @ref{TIME8}, for information on a similar intrinsic that might be
12052 portable to more GNU Fortran implementations, though to fewer Fortran
12055 @item @emph{Standard}:
12058 @item @emph{Class}:
12061 @item @emph{Syntax}:
12062 @code{RESULT = TIME()}
12064 @item @emph{Return value}:
12065 The return value is a scalar of type @code{INTEGER(4)}.
12067 @item @emph{See also}:
12068 @ref{CTIME}, @ref{GMTIME}, @ref{LTIME}, @ref{MCLOCK}, @ref{TIME8}
12075 @section @code{TIME8} --- Time function (64-bit)
12077 @cindex time, current
12078 @cindex current time
12081 @item @emph{Description}:
12082 Returns the current time encoded as an integer (in the manner of the
12083 UNIX function @code{time(3)}). This value is suitable for passing to
12084 @code{CTIME()}, @code{GMTIME()}, and @code{LTIME()}.
12086 @emph{Warning:} this intrinsic does not increase the range of the timing
12087 values over that returned by @code{time(3)}. On a system with a 32-bit
12088 @code{time(3)}, @code{TIME8()} will return a 32-bit value, even though
12089 it is converted to a 64-bit @code{INTEGER(8)} value. That means
12090 overflows of the 32-bit value can still occur. Therefore, the values
12091 returned by this intrinsic might be or become negative or numerically
12092 less than previous values during a single run of the compiled program.
12094 @item @emph{Standard}:
12097 @item @emph{Class}:
12100 @item @emph{Syntax}:
12101 @code{RESULT = TIME8()}
12103 @item @emph{Return value}:
12104 The return value is a scalar of type @code{INTEGER(8)}.
12106 @item @emph{See also}:
12107 @ref{CTIME}, @ref{GMTIME}, @ref{LTIME}, @ref{MCLOCK8}, @ref{TIME}
12114 @section @code{TINY} --- Smallest positive number of a real kind
12116 @cindex limits, smallest number
12117 @cindex model representation, smallest number
12120 @item @emph{Description}:
12121 @code{TINY(X)} returns the smallest positive (non zero) number
12122 in the model of the type of @code{X}.
12124 @item @emph{Standard}:
12125 Fortran 95 and later
12127 @item @emph{Class}:
12130 @item @emph{Syntax}:
12131 @code{RESULT = TINY(X)}
12133 @item @emph{Arguments}:
12134 @multitable @columnfractions .15 .70
12135 @item @var{X} @tab Shall be of type @code{REAL}.
12138 @item @emph{Return value}:
12139 The return value is of the same type and kind as @var{X}
12141 @item @emph{Example}:
12142 See @code{HUGE} for an example.
12148 @section @code{TRAILZ} --- Number of trailing zero bits of an integer
12153 @item @emph{Description}:
12154 @code{TRAILZ} returns the number of trailing zero bits of an integer.
12156 @item @emph{Standard}:
12157 Fortran 2008 and later
12159 @item @emph{Class}:
12162 @item @emph{Syntax}:
12163 @code{RESULT = TRAILZ(I)}
12165 @item @emph{Arguments}:
12166 @multitable @columnfractions .15 .70
12167 @item @var{I} @tab Shall be of type @code{INTEGER}.
12170 @item @emph{Return value}:
12171 The type of the return value is the default @code{INTEGER}.
12172 If all the bits of @code{I} are zero, the result value is @code{BIT_SIZE(I)}.
12174 @item @emph{Example}:
12176 PROGRAM test_trailz
12177 WRITE (*,*) TRAILZ(8) ! prints 3
12181 @item @emph{See also}:
12182 @ref{BIT_SIZE}, @ref{LEADZ}, @ref{POPPAR}, @ref{POPCNT}
12188 @section @code{TRANSFER} --- Transfer bit patterns
12194 @item @emph{Description}:
12195 Interprets the bitwise representation of @var{SOURCE} in memory as if it
12196 is the representation of a variable or array of the same type and type
12197 parameters as @var{MOLD}.
12199 This is approximately equivalent to the C concept of @emph{casting} one
12202 @item @emph{Standard}:
12203 Fortran 95 and later
12205 @item @emph{Class}:
12206 Transformational function
12208 @item @emph{Syntax}:
12209 @code{RESULT = TRANSFER(SOURCE, MOLD[, SIZE])}
12211 @item @emph{Arguments}:
12212 @multitable @columnfractions .15 .70
12213 @item @var{SOURCE} @tab Shall be a scalar or an array of any type.
12214 @item @var{MOLD} @tab Shall be a scalar or an array of any type.
12215 @item @var{SIZE} @tab (Optional) shall be a scalar of type
12219 @item @emph{Return value}:
12220 The result has the same type as @var{MOLD}, with the bit level
12221 representation of @var{SOURCE}. If @var{SIZE} is present, the result is
12222 a one-dimensional array of length @var{SIZE}. If @var{SIZE} is absent
12223 but @var{MOLD} is an array (of any size or shape), the result is a one-
12224 dimensional array of the minimum length needed to contain the entirety
12225 of the bitwise representation of @var{SOURCE}. If @var{SIZE} is absent
12226 and @var{MOLD} is a scalar, the result is a scalar.
12228 If the bitwise representation of the result is longer than that of
12229 @var{SOURCE}, then the leading bits of the result correspond to those of
12230 @var{SOURCE} and any trailing bits are filled arbitrarily.
12232 When the resulting bit representation does not correspond to a valid
12233 representation of a variable of the same type as @var{MOLD}, the results
12234 are undefined, and subsequent operations on the result cannot be
12235 guaranteed to produce sensible behavior. For example, it is possible to
12236 create @code{LOGICAL} variables for which @code{@var{VAR}} and
12237 @code{.NOT.@var{VAR}} both appear to be true.
12239 @item @emph{Example}:
12241 PROGRAM test_transfer
12242 integer :: x = 2143289344
12243 print *, transfer(x, 1.0) ! prints "NaN" on i686
12251 @section @code{TRANSPOSE} --- Transpose an array of rank two
12253 @cindex array, transpose
12254 @cindex matrix, transpose
12258 @item @emph{Description}:
12259 Transpose an array of rank two. Element (i, j) of the result has the value
12260 @code{MATRIX(j, i)}, for all i, j.
12262 @item @emph{Standard}:
12263 Fortran 95 and later
12265 @item @emph{Class}:
12266 Transformational function
12268 @item @emph{Syntax}:
12269 @code{RESULT = TRANSPOSE(MATRIX)}
12271 @item @emph{Arguments}:
12272 @multitable @columnfractions .15 .70
12273 @item @var{MATRIX} @tab Shall be an array of any type and have a rank of two.
12276 @item @emph{Return value}:
12277 The result has the same type as @var{MATRIX}, and has shape
12278 @code{(/ m, n /)} if @var{MATRIX} has shape @code{(/ n, m /)}.
12284 @section @code{TRIM} --- Remove trailing blank characters of a string
12286 @cindex string, remove trailing whitespace
12289 @item @emph{Description}:
12290 Removes trailing blank characters of a string.
12292 @item @emph{Standard}:
12293 Fortran 95 and later
12295 @item @emph{Class}:
12296 Transformational function
12298 @item @emph{Syntax}:
12299 @code{RESULT = TRIM(STRING)}
12301 @item @emph{Arguments}:
12302 @multitable @columnfractions .15 .70
12303 @item @var{STRING} @tab Shall be a scalar of type @code{CHARACTER}.
12306 @item @emph{Return value}:
12307 A scalar of type @code{CHARACTER} which length is that of @var{STRING}
12308 less the number of trailing blanks.
12310 @item @emph{Example}:
12313 CHARACTER(len=10), PARAMETER :: s = "GFORTRAN "
12314 WRITE(*,*) LEN(s), LEN(TRIM(s)) ! "10 8", with/without trailing blanks
12318 @item @emph{See also}:
12319 @ref{ADJUSTL}, @ref{ADJUSTR}
12325 @section @code{TTYNAM} --- Get the name of a terminal device.
12327 @cindex system, terminal
12330 @item @emph{Description}:
12331 Get the name of a terminal device. For more information,
12332 see @code{ttyname(3)}.
12334 This intrinsic is provided in both subroutine and function forms;
12335 however, only one form can be used in any given program unit.
12337 @item @emph{Standard}:
12340 @item @emph{Class}:
12341 Subroutine, function
12343 @item @emph{Syntax}:
12344 @multitable @columnfractions .80
12345 @item @code{CALL TTYNAM(UNIT, NAME)}
12346 @item @code{NAME = TTYNAM(UNIT)}
12349 @item @emph{Arguments}:
12350 @multitable @columnfractions .15 .70
12351 @item @var{UNIT} @tab Shall be a scalar @code{INTEGER}.
12352 @item @var{NAME} @tab Shall be of type @code{CHARACTER}.
12355 @item @emph{Example}:
12357 PROGRAM test_ttynam
12360 IF (isatty(unit=unit)) write(*,*) ttynam(unit)
12365 @item @emph{See also}:
12372 @section @code{UBOUND} --- Upper dimension bounds of an array
12374 @cindex array, upper bound
12377 @item @emph{Description}:
12378 Returns the upper bounds of an array, or a single upper bound
12379 along the @var{DIM} dimension.
12380 @item @emph{Standard}:
12381 Fortran 95 and later, with @var{KIND} argument Fortran 2003 and later
12383 @item @emph{Class}:
12386 @item @emph{Syntax}:
12387 @code{RESULT = UBOUND(ARRAY [, DIM [, KIND]])}
12389 @item @emph{Arguments}:
12390 @multitable @columnfractions .15 .70
12391 @item @var{ARRAY} @tab Shall be an array, of any type.
12392 @item @var{DIM} @tab (Optional) Shall be a scalar @code{INTEGER}.
12393 @item @var{KIND}@tab (Optional) An @code{INTEGER} initialization
12394 expression indicating the kind parameter of the result.
12397 @item @emph{Return value}:
12398 The return value is of type @code{INTEGER} and of kind @var{KIND}. If
12399 @var{KIND} is absent, the return value is of default integer kind.
12400 If @var{DIM} is absent, the result is an array of the upper bounds of
12401 @var{ARRAY}. If @var{DIM} is present, the result is a scalar
12402 corresponding to the upper bound of the array along that dimension. If
12403 @var{ARRAY} is an expression rather than a whole array or array
12404 structure component, or if it has a zero extent along the relevant
12405 dimension, the upper bound is taken to be the number of elements along
12406 the relevant dimension.
12408 @item @emph{See also}:
12409 @ref{LBOUND}, @ref{LCOBOUND}
12415 @section @code{UCOBOUND} --- Upper codimension bounds of an array
12417 @cindex coarray, upper bound
12420 @item @emph{Description}:
12421 Returns the upper cobounds of a coarray, or a single upper cobound
12422 along the @var{DIM} codimension.
12423 @item @emph{Standard}:
12424 Fortran 2008 and later
12426 @item @emph{Class}:
12429 @item @emph{Syntax}:
12430 @code{RESULT = UCOBOUND(COARRAY [, DIM [, KIND]])}
12432 @item @emph{Arguments}:
12433 @multitable @columnfractions .15 .70
12434 @item @var{ARRAY} @tab Shall be an coarray, of any type.
12435 @item @var{DIM} @tab (Optional) Shall be a scalar @code{INTEGER}.
12436 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
12437 expression indicating the kind parameter of the result.
12440 @item @emph{Return value}:
12441 The return value is of type @code{INTEGER} and of kind @var{KIND}. If
12442 @var{KIND} is absent, the return value is of default integer kind.
12443 If @var{DIM} is absent, the result is an array of the lower cobounds of
12444 @var{COARRAY}. If @var{DIM} is present, the result is a scalar
12445 corresponding to the lower cobound of the array along that codimension.
12447 @item @emph{See also}:
12448 @ref{LCOBOUND}, @ref{LBOUND}
12454 @section @code{UMASK} --- Set the file creation mask
12456 @cindex file system, file creation mask
12459 @item @emph{Description}:
12460 Sets the file creation mask to @var{MASK}. If called as a function, it
12461 returns the old value. If called as a subroutine and argument @var{OLD}
12462 if it is supplied, it is set to the old value. See @code{umask(2)}.
12464 @item @emph{Standard}:
12467 @item @emph{Class}:
12468 Subroutine, function
12470 @item @emph{Syntax}:
12471 @multitable @columnfractions .80
12472 @item @code{CALL UMASK(MASK [, OLD])}
12473 @item @code{OLD = UMASK(MASK)}
12476 @item @emph{Arguments}:
12477 @multitable @columnfractions .15 .70
12478 @item @var{MASK} @tab Shall be a scalar of type @code{INTEGER}.
12479 @item @var{OLD} @tab (Optional) Shall be a scalar of type
12488 @section @code{UNLINK} --- Remove a file from the file system
12490 @cindex file system, remove file
12493 @item @emph{Description}:
12494 Unlinks the file @var{PATH}. A null character (@code{CHAR(0)}) can be
12495 used to mark the end of the name in @var{PATH}; otherwise, trailing
12496 blanks in the file name are ignored. If the @var{STATUS} argument is
12497 supplied, it contains 0 on success or a nonzero error code upon return;
12498 see @code{unlink(2)}.
12500 This intrinsic is provided in both subroutine and function forms;
12501 however, only one form can be used in any given program unit.
12503 @item @emph{Standard}:
12506 @item @emph{Class}:
12507 Subroutine, function
12509 @item @emph{Syntax}:
12510 @multitable @columnfractions .80
12511 @item @code{CALL UNLINK(PATH [, STATUS])}
12512 @item @code{STATUS = UNLINK(PATH)}
12515 @item @emph{Arguments}:
12516 @multitable @columnfractions .15 .70
12517 @item @var{PATH} @tab Shall be of default @code{CHARACTER} type.
12518 @item @var{STATUS} @tab (Optional) Shall be of default @code{INTEGER} type.
12521 @item @emph{See also}:
12522 @ref{LINK}, @ref{SYMLNK}
12528 @section @code{UNPACK} --- Unpack an array of rank one into an array
12530 @cindex array, unpacking
12531 @cindex array, increase dimension
12532 @cindex array, scatter elements
12535 @item @emph{Description}:
12536 Store the elements of @var{VECTOR} in an array of higher rank.
12538 @item @emph{Standard}:
12539 Fortran 95 and later
12541 @item @emph{Class}:
12542 Transformational function
12544 @item @emph{Syntax}:
12545 @code{RESULT = UNPACK(VECTOR, MASK, FIELD)}
12547 @item @emph{Arguments}:
12548 @multitable @columnfractions .15 .70
12549 @item @var{VECTOR} @tab Shall be an array of any type and rank one. It
12550 shall have at least as many elements as @var{MASK} has @code{TRUE} values.
12551 @item @var{MASK} @tab Shall be an array of type @code{LOGICAL}.
12552 @item @var{FIELD} @tab Shall be of the same type as @var{VECTOR} and have
12553 the same shape as @var{MASK}.
12556 @item @emph{Return value}:
12557 The resulting array corresponds to @var{FIELD} with @code{TRUE} elements
12558 of @var{MASK} replaced by values from @var{VECTOR} in array element order.
12560 @item @emph{Example}:
12562 PROGRAM test_unpack
12563 integer :: vector(2) = (/1,1/)
12564 logical :: mask(4) = (/ .TRUE., .FALSE., .FALSE., .TRUE. /)
12565 integer :: field(2,2) = 0, unity(2,2)
12567 ! result: unity matrix
12568 unity = unpack(vector, reshape(mask, (/2,2/)), field)
12572 @item @emph{See also}:
12573 @ref{PACK}, @ref{SPREAD}
12579 @section @code{VERIFY} --- Scan a string for the absence of a set of characters
12581 @cindex string, find missing set
12584 @item @emph{Description}:
12585 Verifies that all the characters in a @var{SET} are present in a @var{STRING}.
12587 If @var{BACK} is either absent or equals @code{FALSE}, this function
12588 returns the position of the leftmost character of @var{STRING} that is
12589 not in @var{SET}. If @var{BACK} equals @code{TRUE}, the rightmost position
12590 is returned. If all characters of @var{SET} are found in @var{STRING}, the
12593 @item @emph{Standard}:
12594 Fortran 95 and later, with @var{KIND} argument Fortran 2003 and later
12596 @item @emph{Class}:
12599 @item @emph{Syntax}:
12600 @code{RESULT = VERIFY(STRING, SET[, BACK [, KIND]])}
12602 @item @emph{Arguments}:
12603 @multitable @columnfractions .15 .70
12604 @item @var{STRING} @tab Shall be of type @code{CHARACTER}.
12605 @item @var{SET} @tab Shall be of type @code{CHARACTER}.
12606 @item @var{BACK} @tab (Optional) shall be of type @code{LOGICAL}.
12607 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
12608 expression indicating the kind parameter of the result.
12611 @item @emph{Return value}:
12612 The return value is of type @code{INTEGER} and of kind @var{KIND}. If
12613 @var{KIND} is absent, the return value is of default integer kind.
12615 @item @emph{Example}:
12617 PROGRAM test_verify
12618 WRITE(*,*) VERIFY("FORTRAN", "AO") ! 1, found 'F'
12619 WRITE(*,*) VERIFY("FORTRAN", "FOO") ! 3, found 'R'
12620 WRITE(*,*) VERIFY("FORTRAN", "C++") ! 1, found 'F'
12621 WRITE(*,*) VERIFY("FORTRAN", "C++", .TRUE.) ! 7, found 'N'
12622 WRITE(*,*) VERIFY("FORTRAN", "FORTRAN") ! 0' found none
12626 @item @emph{See also}:
12627 @ref{SCAN}, @ref{INDEX intrinsic}
12633 @section @code{XOR} --- Bitwise logical exclusive OR
12635 @cindex bitwise logical exclusive or
12636 @cindex logical exclusive or, bitwise
12639 @item @emph{Description}:
12640 Bitwise logical exclusive or.
12642 This intrinsic routine is provided for backwards compatibility with
12643 GNU Fortran 77. For integer arguments, programmers should consider
12644 the use of the @ref{IEOR} intrinsic and for logical arguments the
12645 @code{.NEQV.} operator, which are both defined by the Fortran standard.
12647 @item @emph{Standard}:
12650 @item @emph{Class}:
12653 @item @emph{Syntax}:
12654 @code{RESULT = XOR(I, J)}
12656 @item @emph{Arguments}:
12657 @multitable @columnfractions .15 .70
12658 @item @var{I} @tab The type shall be either a scalar @code{INTEGER}
12659 type or a scalar @code{LOGICAL} type.
12660 @item @var{J} @tab The type shall be the same as the type of @var{I}.
12663 @item @emph{Return value}:
12664 The return type is either a scalar @code{INTEGER} or a scalar
12665 @code{LOGICAL}. If the kind type parameters differ, then the
12666 smaller kind type is implicitly converted to larger kind, and the
12667 return has the larger kind.
12669 @item @emph{Example}:
12672 LOGICAL :: T = .TRUE., F = .FALSE.
12674 DATA a / Z'F' /, b / Z'3' /
12676 WRITE (*,*) XOR(T, T), XOR(T, F), XOR(F, T), XOR(F, F)
12677 WRITE (*,*) XOR(a, b)
12681 @item @emph{See also}:
12682 Fortran 95 elemental function: @ref{IEOR}
12687 @node Intrinsic Modules
12688 @chapter Intrinsic Modules
12689 @cindex intrinsic Modules
12692 * ISO_FORTRAN_ENV::
12694 * OpenMP Modules OMP_LIB and OMP_LIB_KINDS::
12697 @node ISO_FORTRAN_ENV
12698 @section @code{ISO_FORTRAN_ENV}
12700 @item @emph{Standard}:
12701 Fortran 2003 and later, except when otherwise noted
12704 The @code{ISO_FORTRAN_ENV} module provides the following scalar default-integer
12708 @item @code{ATOMIC_INT_KIND}:
12709 Default-kind integer constant to be used as kind parameter when defining
12710 integer variables used in atomic operations. (Fortran 2008 or later.)
12712 @item @code{ATOMIC_LOGICAL_KIND}:
12713 Default-kind integer constant to be used as kind parameter when defining
12714 logical variables used in atomic operations. (Fortran 2008 or later.)
12716 @item @code{CHARACTER_KINDS}:
12717 Default-kind integer constant array of rank one containing the supported kind
12718 parameters of the @code{CHARACTER} type. (Fortran 2008 or later.)
12720 @item @code{CHARACTER_STORAGE_SIZE}:
12721 Size in bits of the character storage unit.
12723 @item @code{ERROR_UNIT}:
12724 Identifies the preconnected unit used for error reporting.
12726 @item @code{FILE_STORAGE_SIZE}:
12727 Size in bits of the file-storage unit.
12729 @item @code{INPUT_UNIT}:
12730 Identifies the preconnected unit identified by the asterisk
12731 (@code{*}) in @code{READ} statement.
12733 @item @code{INT8}, @code{INT16}, @code{INT32}, @code{INT64}:
12734 Kind type parameters to specify an INTEGER type with a storage
12735 size of 16, 32, and 64 bits. It is negative if a target platform
12736 does not support the particular kind. (Fortran 2008 or later.)
12738 @item @code{INTEGER_KINDS}:
12739 Default-kind integer constant array of rank one containing the supported kind
12740 parameters of the @code{INTEGER} type. (Fortran 2008 or later.)
12742 @item @code{IOSTAT_END}:
12743 The value assigned to the variable passed to the @code{IOSTAT=} specifier of
12744 an input/output statement if an end-of-file condition occurred.
12746 @item @code{IOSTAT_EOR}:
12747 The value assigned to the variable passed to the @code{IOSTAT=} specifier of
12748 an input/output statement if an end-of-record condition occurred.
12750 @item @code{IOSTAT_INQUIRE_INTERNAL_UNIT}:
12751 Scalar default-integer constant, used by @code{INQUIRE} for the
12752 @code{IOSTAT=} specifier to denote an that a unit number identifies an
12753 internal unit. (Fortran 2008 or later.)
12755 @item @code{NUMERIC_STORAGE_SIZE}:
12756 The size in bits of the numeric storage unit.
12758 @item @code{LOGICAL_KINDS}:
12759 Default-kind integer constant array of rank one containing the supported kind
12760 parameters of the @code{LOGICAL} type. (Fortran 2008 or later.)
12762 @item @code{OUTPUT_UNIT}:
12763 Identifies the preconnected unit identified by the asterisk
12764 (@code{*}) in @code{WRITE} statement.
12766 @item @code{REAL32}, @code{REAL64}, @code{REAL128}:
12767 Kind type parameters to specify a REAL type with a storage
12768 size of 32, 64, and 128 bits. It is negative if a target platform
12769 does not support the particular kind. (Fortran 2008 or later.)
12771 @item @code{REAL_KINDS}:
12772 Default-kind integer constant array of rank one containing the supported kind
12773 parameters of the @code{REAL} type. (Fortran 2008 or later.)
12775 @item @code{STAT_LOCKED}:
12776 Scalar default-integer constant used as STAT= return value by @code{LOCK} to
12777 denote that the lock variable is locked by the executing image. (Fortran 2008
12780 @item @code{STAT_LOCKED_OTHER_IMAGE}:
12781 Scalar default-integer constant used as STAT= return value by @code{UNLOCK} to
12782 denote that the lock variable is locked by another image. (Fortran 2008 or
12785 @item @code{STAT_STOPPED_IMAGE}:
12786 Positive, scalar default-integer constant used as STAT= return value if the
12787 argument in the statement requires synchronisation with an image, which has
12788 initiated the termination of the execution. (Fortran 2008 or later.)
12790 @item @code{STAT_UNLOCKED}:
12791 Scalar default-integer constant used as STAT= return value by @code{UNLOCK} to
12792 denote that the lock variable is unlocked. (Fortran 2008 or later.)
12795 The module also provides the following intrinsic procedures:
12796 @ref{COMPILER_OPTIONS} and @ref{COMPILER_VERSION}.
12800 @node ISO_C_BINDING
12801 @section @code{ISO_C_BINDING}
12803 @item @emph{Standard}:
12804 Fortran 2003 and later, GNU extensions
12807 The following intrinsic procedures are provided by the module; their
12808 definition can be found in the section Intrinsic Procedures of this
12812 @item @code{C_ASSOCIATED}
12813 @item @code{C_F_POINTER}
12814 @item @code{C_F_PROCPOINTER}
12815 @item @code{C_FUNLOC}
12817 @item @code{C_SIZEOF}
12819 @c TODO: Vertical spacing between C_FUNLOC and C_LOC wrong in PDF,
12820 @c don't really know why.
12822 The @code{ISO_C_BINDING} module provides the following named constants of
12823 type default integer, which can be used as KIND type parameters.
12825 In addition to the integer named constants required by the Fortran 2003
12826 standard, GNU Fortran provides as an extension named constants for the
12827 128-bit integer types supported by the C compiler: @code{C_INT128_T,
12828 C_INT_LEAST128_T, C_INT_FAST128_T}.
12830 @multitable @columnfractions .15 .35 .35 .35
12831 @item Fortran Type @tab Named constant @tab C type @tab Extension
12832 @item @code{INTEGER}@tab @code{C_INT} @tab @code{int}
12833 @item @code{INTEGER}@tab @code{C_SHORT} @tab @code{short int}
12834 @item @code{INTEGER}@tab @code{C_LONG} @tab @code{long int}
12835 @item @code{INTEGER}@tab @code{C_LONG_LONG} @tab @code{long long int}
12836 @item @code{INTEGER}@tab @code{C_SIGNED_CHAR} @tab @code{signed char}/@code{unsigned char}
12837 @item @code{INTEGER}@tab @code{C_SIZE_T} @tab @code{size_t}
12838 @item @code{INTEGER}@tab @code{C_INT8_T} @tab @code{int8_t}
12839 @item @code{INTEGER}@tab @code{C_INT16_T} @tab @code{int16_t}
12840 @item @code{INTEGER}@tab @code{C_INT32_T} @tab @code{int32_t}
12841 @item @code{INTEGER}@tab @code{C_INT64_T} @tab @code{int64_t}
12842 @item @code{INTEGER}@tab @code{C_INT128_T} @tab @code{int128_t} @tab Ext.
12843 @item @code{INTEGER}@tab @code{C_INT_LEAST8_T} @tab @code{int_least8_t}
12844 @item @code{INTEGER}@tab @code{C_INT_LEAST16_T} @tab @code{int_least16_t}
12845 @item @code{INTEGER}@tab @code{C_INT_LEAST32_T} @tab @code{int_least32_t}
12846 @item @code{INTEGER}@tab @code{C_INT_LEAST64_T} @tab @code{int_least64_t}
12847 @item @code{INTEGER}@tab @code{C_INT_LEAST128_T}@tab @code{int_least128_t} @tab Ext.
12848 @item @code{INTEGER}@tab @code{C_INT_FAST8_T} @tab @code{int_fast8_t}
12849 @item @code{INTEGER}@tab @code{C_INT_FAST16_T} @tab @code{int_fast16_t}
12850 @item @code{INTEGER}@tab @code{C_INT_FAST32_T} @tab @code{int_fast32_t}
12851 @item @code{INTEGER}@tab @code{C_INT_FAST64_T} @tab @code{int_fast64_t}
12852 @item @code{INTEGER}@tab @code{C_INT_FAST128_T} @tab @code{int_fast128_t} @tab Ext.
12853 @item @code{INTEGER}@tab @code{C_INTMAX_T} @tab @code{intmax_t}
12854 @item @code{INTEGER}@tab @code{C_INTPTR_T} @tab @code{intptr_t}
12855 @item @code{REAL} @tab @code{C_FLOAT} @tab @code{float}
12856 @item @code{REAL} @tab @code{C_DOUBLE} @tab @code{double}
12857 @item @code{REAL} @tab @code{C_LONG_DOUBLE} @tab @code{long double}
12858 @item @code{COMPLEX}@tab @code{C_FLOAT_COMPLEX} @tab @code{float _Complex}
12859 @item @code{COMPLEX}@tab @code{C_DOUBLE_COMPLEX}@tab @code{double _Complex}
12860 @item @code{COMPLEX}@tab @code{C_LONG_DOUBLE_COMPLEX}@tab @code{long double _Complex}
12861 @item @code{LOGICAL}@tab @code{C_BOOL} @tab @code{_Bool}
12862 @item @code{CHARACTER}@tab @code{C_CHAR} @tab @code{char}
12865 Additionally, the following parameters of type @code{CHARACTER(KIND=C_CHAR)}
12868 @multitable @columnfractions .20 .45 .15
12869 @item Name @tab C definition @tab Value
12870 @item @code{C_NULL_CHAR} @tab null character @tab @code{'\0'}
12871 @item @code{C_ALERT} @tab alert @tab @code{'\a'}
12872 @item @code{C_BACKSPACE} @tab backspace @tab @code{'\b'}
12873 @item @code{C_FORM_FEED} @tab form feed @tab @code{'\f'}
12874 @item @code{C_NEW_LINE} @tab new line @tab @code{'\n'}
12875 @item @code{C_CARRIAGE_RETURN} @tab carriage return @tab @code{'\r'}
12876 @item @code{C_HORIZONTAL_TAB} @tab horizontal tab @tab @code{'\t'}
12877 @item @code{C_VERTICAL_TAB} @tab vertical tab @tab @code{'\v'}
12880 Moreover, the following two named constants are defined:
12882 @multitable @columnfractions .20 .80
12883 @item Name @tab Type
12884 @item @code{C_NULL_PTR} @tab @code{C_PTR}
12885 @item @code{C_NULL_FUNPTR} @tab @code{C_FUNPTR}
12888 Both are equivalent to the value @code{NULL} in C.
12890 @node OpenMP Modules OMP_LIB and OMP_LIB_KINDS
12891 @section OpenMP Modules @code{OMP_LIB} and @code{OMP_LIB_KINDS}
12893 @item @emph{Standard}:
12894 OpenMP Application Program Interface v3.0
12898 The OpenMP Fortran runtime library routines are provided both in
12899 a form of two Fortran 90 modules, named @code{OMP_LIB} and
12900 @code{OMP_LIB_KINDS}, and in a form of a Fortran @code{include} file named
12901 @file{omp_lib.h}. The procedures provided by @code{OMP_LIB} can be found
12902 in the @ref{Top,,Introduction,libgomp,GNU OpenMP runtime library} manual,
12903 the named constants defined in the modules are listed
12906 For details refer to the actual
12907 @uref{http://www.openmp.org/mp-documents/spec30.pdf,
12908 OpenMP Application Program Interface v3.0}.
12910 @code{OMP_LIB_KINDS} provides the following scalar default-integer
12914 @item @code{omp_integer_kind}
12915 @item @code{omp_logical_kind}
12916 @item @code{omp_lock_kind}
12917 @item @code{omp_nest_lock_kind}
12918 @item @code{omp_sched_kind}
12921 @code{OMP_LIB} provides the scalar default-integer
12922 named constant @code{openmp_version} with a value of the form
12923 @var{yyyymm}, where @code{yyyy} is the year and @var{mm} the month
12924 of the OpenMP version; for OpenMP v3.0 the value is @code{200805}.
12926 And the following scalar integer named constants of the
12927 kind @code{omp_sched_kind}:
12930 @item @code{omp_sched_static}
12931 @item @code{omp_sched_dynamic}
12932 @item @code{omp_sched_guided}
12933 @item @code{omp_sched_auto}