2 Copyright (C) 2005-2013 Free Software Foundation, Inc.
3 This is part of the GNU Fortran manual.
4 For copying conditions, see the file gfortran.texi.
6 Permission is granted to copy, distribute and/or modify this document
7 under the terms of the GNU Free Documentation License, Version 1.3 or
8 any later version published by the Free Software Foundation; with the
9 Invariant Sections being ``Funding Free Software'', the Front-Cover
10 Texts being (a) (see below), and with the Back-Cover Texts being (b)
11 (see below). A copy of the license is included in the gfdl(7) man page.
14 Some basic guidelines for editing this document:
16 (1) The intrinsic procedures are to be listed in alphabetical order.
17 (2) The generic name is to be used.
18 (3) The specific names are included in the function index and in a
19 table at the end of the node (See ABS entry).
20 (4) Try to maintain the same style for each entry.
26 \gdef\acos{\mathop{\rm acos}\nolimits}
27 \gdef\asin{\mathop{\rm asin}\nolimits}
28 \gdef\atan{\mathop{\rm atan}\nolimits}
29 \gdef\acosh{\mathop{\rm acosh}\nolimits}
30 \gdef\asinh{\mathop{\rm asinh}\nolimits}
31 \gdef\atanh{\mathop{\rm atanh}\nolimits}
35 @node Intrinsic Procedures
36 @chapter Intrinsic Procedures
37 @cindex intrinsic procedures
40 * Introduction: Introduction to Intrinsics
41 * @code{ABORT}: ABORT, Abort the program
42 * @code{ABS}: ABS, Absolute value
43 * @code{ACCESS}: ACCESS, Checks file access modes
44 * @code{ACHAR}: ACHAR, Character in @acronym{ASCII} collating sequence
45 * @code{ACOS}: ACOS, Arccosine function
46 * @code{ACOSH}: ACOSH, Inverse hyperbolic cosine function
47 * @code{ADJUSTL}: ADJUSTL, Left adjust a string
48 * @code{ADJUSTR}: ADJUSTR, Right adjust a string
49 * @code{AIMAG}: AIMAG, Imaginary part of complex number
50 * @code{AINT}: AINT, Truncate to a whole number
51 * @code{ALARM}: ALARM, Set an alarm clock
52 * @code{ALL}: ALL, Determine if all values are true
53 * @code{ALLOCATED}: ALLOCATED, Status of allocatable entity
54 * @code{AND}: AND, Bitwise logical AND
55 * @code{ANINT}: ANINT, Nearest whole number
56 * @code{ANY}: ANY, Determine if any values are true
57 * @code{ASIN}: ASIN, Arcsine function
58 * @code{ASINH}: ASINH, Inverse hyperbolic sine function
59 * @code{ASSOCIATED}: ASSOCIATED, Status of a pointer or pointer/target pair
60 * @code{ATAN}: ATAN, Arctangent function
61 * @code{ATAN2}: ATAN2, Arctangent function
62 * @code{ATANH}: ATANH, Inverse hyperbolic tangent function
63 * @code{ATOMIC_DEFINE}: ATOMIC_DEFINE, Setting a variable atomically
64 * @code{ATOMIC_REF}: ATOMIC_REF, Obtaining the value of a variable atomically
65 * @code{BACKTRACE}: BACKTRACE, Show a backtrace
66 * @code{BESSEL_J0}: BESSEL_J0, Bessel function of the first kind of order 0
67 * @code{BESSEL_J1}: BESSEL_J1, Bessel function of the first kind of order 1
68 * @code{BESSEL_JN}: BESSEL_JN, Bessel function of the first kind
69 * @code{BESSEL_Y0}: BESSEL_Y0, Bessel function of the second kind of order 0
70 * @code{BESSEL_Y1}: BESSEL_Y1, Bessel function of the second kind of order 1
71 * @code{BESSEL_YN}: BESSEL_YN, Bessel function of the second kind
72 * @code{BGE}: BGE, Bitwise greater than or equal to
73 * @code{BGT}: BGT, Bitwise greater than
74 * @code{BIT_SIZE}: BIT_SIZE, Bit size inquiry function
75 * @code{BLE}: BLE, Bitwise less than or equal to
76 * @code{BLT}: BLT, Bitwise less than
77 * @code{BTEST}: BTEST, Bit test function
78 * @code{C_ASSOCIATED}: C_ASSOCIATED, Status of a C pointer
79 * @code{C_F_POINTER}: C_F_POINTER, Convert C into Fortran pointer
80 * @code{C_F_PROCPOINTER}: C_F_PROCPOINTER, Convert C into Fortran procedure pointer
81 * @code{C_FUNLOC}: C_FUNLOC, Obtain the C address of a procedure
82 * @code{C_LOC}: C_LOC, Obtain the C address of an object
83 * @code{C_SIZEOF}: C_SIZEOF, Size in bytes of an expression
84 * @code{CEILING}: CEILING, Integer ceiling function
85 * @code{CHAR}: CHAR, Integer-to-character conversion function
86 * @code{CHDIR}: CHDIR, Change working directory
87 * @code{CHMOD}: CHMOD, Change access permissions of files
88 * @code{CMPLX}: CMPLX, Complex conversion function
89 * @code{COMMAND_ARGUMENT_COUNT}: COMMAND_ARGUMENT_COUNT, Get number of command line arguments
90 * @code{COMPLEX}: COMPLEX, Complex conversion function
91 * @code{COMPILER_VERSION}: COMPILER_VERSION, Compiler version string
92 * @code{COMPILER_OPTIONS}: COMPILER_OPTIONS, Options passed to the compiler
93 * @code{CONJG}: CONJG, Complex conjugate function
94 * @code{COS}: COS, Cosine function
95 * @code{COSH}: COSH, Hyperbolic cosine function
96 * @code{COUNT}: COUNT, Count occurrences of TRUE in an array
97 * @code{CPU_TIME}: CPU_TIME, CPU time subroutine
98 * @code{CSHIFT}: CSHIFT, Circular shift elements of an array
99 * @code{CTIME}: CTIME, Subroutine (or function) to convert a time into a string
100 * @code{DATE_AND_TIME}: DATE_AND_TIME, Date and time subroutine
101 * @code{DBLE}: DBLE, Double precision conversion function
102 * @code{DCMPLX}: DCMPLX, Double complex conversion function
103 * @code{DIGITS}: DIGITS, Significant digits function
104 * @code{DIM}: DIM, Positive difference
105 * @code{DOT_PRODUCT}: DOT_PRODUCT, Dot product function
106 * @code{DPROD}: DPROD, Double product function
107 * @code{DREAL}: DREAL, Double real part function
108 * @code{DSHIFTL}: DSHIFTL, Combined left shift
109 * @code{DSHIFTR}: DSHIFTR, Combined right shift
110 * @code{DTIME}: DTIME, Execution time subroutine (or function)
111 * @code{EOSHIFT}: EOSHIFT, End-off shift elements of an array
112 * @code{EPSILON}: EPSILON, Epsilon function
113 * @code{ERF}: ERF, Error function
114 * @code{ERFC}: ERFC, Complementary error function
115 * @code{ERFC_SCALED}: ERFC_SCALED, Exponentially-scaled complementary error function
116 * @code{ETIME}: ETIME, Execution time subroutine (or function)
117 * @code{EXECUTE_COMMAND_LINE}: EXECUTE_COMMAND_LINE, Execute a shell command
118 * @code{EXIT}: EXIT, Exit the program with status.
119 * @code{EXP}: EXP, Exponential function
120 * @code{EXPONENT}: EXPONENT, Exponent function
121 * @code{EXTENDS_TYPE_OF}: EXTENDS_TYPE_OF, Query dynamic type for extension
122 * @code{FDATE}: FDATE, Subroutine (or function) to get the current time as a string
123 * @code{FGET}: FGET, Read a single character in stream mode from stdin
124 * @code{FGETC}: FGETC, Read a single character in stream mode
125 * @code{FLOOR}: FLOOR, Integer floor function
126 * @code{FLUSH}: FLUSH, Flush I/O unit(s)
127 * @code{FNUM}: FNUM, File number function
128 * @code{FPUT}: FPUT, Write a single character in stream mode to stdout
129 * @code{FPUTC}: FPUTC, Write a single character in stream mode
130 * @code{FRACTION}: FRACTION, Fractional part of the model representation
131 * @code{FREE}: FREE, Memory de-allocation subroutine
132 * @code{FSEEK}: FSEEK, Low level file positioning subroutine
133 * @code{FSTAT}: FSTAT, Get file status
134 * @code{FTELL}: FTELL, Current stream position
135 * @code{GAMMA}: GAMMA, Gamma function
136 * @code{GERROR}: GERROR, Get last system error message
137 * @code{GETARG}: GETARG, Get command line arguments
138 * @code{GET_COMMAND}: GET_COMMAND, Get the entire command line
139 * @code{GET_COMMAND_ARGUMENT}: GET_COMMAND_ARGUMENT, Get command line arguments
140 * @code{GETCWD}: GETCWD, Get current working directory
141 * @code{GETENV}: GETENV, Get an environmental variable
142 * @code{GET_ENVIRONMENT_VARIABLE}: GET_ENVIRONMENT_VARIABLE, Get an environmental variable
143 * @code{GETGID}: GETGID, Group ID function
144 * @code{GETLOG}: GETLOG, Get login name
145 * @code{GETPID}: GETPID, Process ID function
146 * @code{GETUID}: GETUID, User ID function
147 * @code{GMTIME}: GMTIME, Convert time to GMT info
148 * @code{HOSTNM}: HOSTNM, Get system host name
149 * @code{HUGE}: HUGE, Largest number of a kind
150 * @code{HYPOT}: HYPOT, Euclidean distance function
151 * @code{IACHAR}: IACHAR, Code in @acronym{ASCII} collating sequence
152 * @code{IALL}: IALL, Bitwise AND of array elements
153 * @code{IAND}: IAND, Bitwise logical and
154 * @code{IANY}: IANY, Bitwise OR of array elements
155 * @code{IARGC}: IARGC, Get the number of command line arguments
156 * @code{IBCLR}: IBCLR, Clear bit
157 * @code{IBITS}: IBITS, Bit extraction
158 * @code{IBSET}: IBSET, Set bit
159 * @code{ICHAR}: ICHAR, Character-to-integer conversion function
160 * @code{IDATE}: IDATE, Current local time (day/month/year)
161 * @code{IEOR}: IEOR, Bitwise logical exclusive or
162 * @code{IERRNO}: IERRNO, Function to get the last system error number
163 * @code{IMAGE_INDEX}: IMAGE_INDEX, Cosubscript to image index conversion
164 * @code{INDEX}: INDEX intrinsic, Position of a substring within a string
165 * @code{INT}: INT, Convert to integer type
166 * @code{INT2}: INT2, Convert to 16-bit integer type
167 * @code{INT8}: INT8, Convert to 64-bit integer type
168 * @code{IOR}: IOR, Bitwise logical or
169 * @code{IPARITY}: IPARITY, Bitwise XOR of array elements
170 * @code{IRAND}: IRAND, Integer pseudo-random number
171 * @code{IS_IOSTAT_END}: IS_IOSTAT_END, Test for end-of-file value
172 * @code{IS_IOSTAT_EOR}: IS_IOSTAT_EOR, Test for end-of-record value
173 * @code{ISATTY}: ISATTY, Whether a unit is a terminal device
174 * @code{ISHFT}: ISHFT, Shift bits
175 * @code{ISHFTC}: ISHFTC, Shift bits circularly
176 * @code{ISNAN}: ISNAN, Tests for a NaN
177 * @code{ITIME}: ITIME, Current local time (hour/minutes/seconds)
178 * @code{KILL}: KILL, Send a signal to a process
179 * @code{KIND}: KIND, Kind of an entity
180 * @code{LBOUND}: LBOUND, Lower dimension bounds of an array
181 * @code{LCOBOUND}: LCOBOUND, Lower codimension bounds of an array
182 * @code{LEADZ}: LEADZ, Number of leading zero bits of an integer
183 * @code{LEN}: LEN, Length of a character entity
184 * @code{LEN_TRIM}: LEN_TRIM, Length of a character entity without trailing blank characters
185 * @code{LGE}: LGE, Lexical greater than or equal
186 * @code{LGT}: LGT, Lexical greater than
187 * @code{LINK}: LINK, Create a hard link
188 * @code{LLE}: LLE, Lexical less than or equal
189 * @code{LLT}: LLT, Lexical less than
190 * @code{LNBLNK}: LNBLNK, Index of the last non-blank character in a string
191 * @code{LOC}: LOC, Returns the address of a variable
192 * @code{LOG}: LOG, Logarithm function
193 * @code{LOG10}: LOG10, Base 10 logarithm function
194 * @code{LOG_GAMMA}: LOG_GAMMA, Logarithm of the Gamma function
195 * @code{LOGICAL}: LOGICAL, Convert to logical type
196 * @code{LONG}: LONG, Convert to integer type
197 * @code{LSHIFT}: LSHIFT, Left shift bits
198 * @code{LSTAT}: LSTAT, Get file status
199 * @code{LTIME}: LTIME, Convert time to local time info
200 * @code{MALLOC}: MALLOC, Dynamic memory allocation function
201 * @code{MASKL}: MASKL, Left justified mask
202 * @code{MASKR}: MASKR, Right justified mask
203 * @code{MATMUL}: MATMUL, matrix multiplication
204 * @code{MAX}: MAX, Maximum value of an argument list
205 * @code{MAXEXPONENT}: MAXEXPONENT, Maximum exponent of a real kind
206 * @code{MAXLOC}: MAXLOC, Location of the maximum value within an array
207 * @code{MAXVAL}: MAXVAL, Maximum value of an array
208 * @code{MCLOCK}: MCLOCK, Time function
209 * @code{MCLOCK8}: MCLOCK8, Time function (64-bit)
210 * @code{MERGE}: MERGE, Merge arrays
211 * @code{MERGE_BITS}: MERGE_BITS, Merge of bits under mask
212 * @code{MIN}: MIN, Minimum value of an argument list
213 * @code{MINEXPONENT}: MINEXPONENT, Minimum exponent of a real kind
214 * @code{MINLOC}: MINLOC, Location of the minimum value within an array
215 * @code{MINVAL}: MINVAL, Minimum value of an array
216 * @code{MOD}: MOD, Remainder function
217 * @code{MODULO}: MODULO, Modulo function
218 * @code{MOVE_ALLOC}: MOVE_ALLOC, Move allocation from one object to another
219 * @code{MVBITS}: MVBITS, Move bits from one integer to another
220 * @code{NEAREST}: NEAREST, Nearest representable number
221 * @code{NEW_LINE}: NEW_LINE, New line character
222 * @code{NINT}: NINT, Nearest whole number
223 * @code{NORM2}: NORM2, Euclidean vector norm
224 * @code{NOT}: NOT, Logical negation
225 * @code{NULL}: NULL, Function that returns an disassociated pointer
226 * @code{NUM_IMAGES}: NUM_IMAGES, Number of images
227 * @code{OR}: OR, Bitwise logical OR
228 * @code{PACK}: PACK, Pack an array into an array of rank one
229 * @code{PARITY}: PARITY, Reduction with exclusive OR
230 * @code{PERROR}: PERROR, Print system error message
231 * @code{POPCNT}: POPCNT, Number of bits set
232 * @code{POPPAR}: POPPAR, Parity of the number of bits set
233 * @code{PRECISION}: PRECISION, Decimal precision of a real kind
234 * @code{PRESENT}: PRESENT, Determine whether an optional dummy argument is specified
235 * @code{PRODUCT}: PRODUCT, Product of array elements
236 * @code{RADIX}: RADIX, Base of a data model
237 * @code{RANDOM_NUMBER}: RANDOM_NUMBER, Pseudo-random number
238 * @code{RANDOM_SEED}: RANDOM_SEED, Initialize a pseudo-random number sequence
239 * @code{RAND}: RAND, Real pseudo-random number
240 * @code{RANGE}: RANGE, Decimal exponent range
241 * @code{RANK} : RANK, Rank of a data object
242 * @code{RAN}: RAN, Real pseudo-random number
243 * @code{REAL}: REAL, Convert to real type
244 * @code{RENAME}: RENAME, Rename a file
245 * @code{REPEAT}: REPEAT, Repeated string concatenation
246 * @code{RESHAPE}: RESHAPE, Function to reshape an array
247 * @code{RRSPACING}: RRSPACING, Reciprocal of the relative spacing
248 * @code{RSHIFT}: RSHIFT, Right shift bits
249 * @code{SAME_TYPE_AS}: SAME_TYPE_AS, Query dynamic types for equality
250 * @code{SCALE}: SCALE, Scale a real value
251 * @code{SCAN}: SCAN, Scan a string for the presence of a set of characters
252 * @code{SECNDS}: SECNDS, Time function
253 * @code{SECOND}: SECOND, CPU time function
254 * @code{SELECTED_CHAR_KIND}: SELECTED_CHAR_KIND, Choose character kind
255 * @code{SELECTED_INT_KIND}: SELECTED_INT_KIND, Choose integer kind
256 * @code{SELECTED_REAL_KIND}: SELECTED_REAL_KIND, Choose real kind
257 * @code{SET_EXPONENT}: SET_EXPONENT, Set the exponent of the model
258 * @code{SHAPE}: SHAPE, Determine the shape of an array
259 * @code{SHIFTA}: SHIFTA, Right shift with fill
260 * @code{SHIFTL}: SHIFTL, Left shift
261 * @code{SHIFTR}: SHIFTR, Right shift
262 * @code{SIGN}: SIGN, Sign copying function
263 * @code{SIGNAL}: SIGNAL, Signal handling subroutine (or function)
264 * @code{SIN}: SIN, Sine function
265 * @code{SINH}: SINH, Hyperbolic sine function
266 * @code{SIZE}: SIZE, Function to determine the size of an array
267 * @code{SIZEOF}: SIZEOF, Determine the size in bytes of an expression
268 * @code{SLEEP}: SLEEP, Sleep for the specified number of seconds
269 * @code{SPACING}: SPACING, Smallest distance between two numbers of a given type
270 * @code{SPREAD}: SPREAD, Add a dimension to an array
271 * @code{SQRT}: SQRT, Square-root function
272 * @code{SRAND}: SRAND, Reinitialize the random number generator
273 * @code{STAT}: STAT, Get file status
274 * @code{STORAGE_SIZE}: STORAGE_SIZE, Storage size in bits
275 * @code{SUM}: SUM, Sum of array elements
276 * @code{SYMLNK}: SYMLNK, Create a symbolic link
277 * @code{SYSTEM}: SYSTEM, Execute a shell command
278 * @code{SYSTEM_CLOCK}: SYSTEM_CLOCK, Time function
279 * @code{TAN}: TAN, Tangent function
280 * @code{TANH}: TANH, Hyperbolic tangent function
281 * @code{THIS_IMAGE}: THIS_IMAGE, Cosubscript index of this image
282 * @code{TIME}: TIME, Time function
283 * @code{TIME8}: TIME8, Time function (64-bit)
284 * @code{TINY}: TINY, Smallest positive number of a real kind
285 * @code{TRAILZ}: TRAILZ, Number of trailing zero bits of an integer
286 * @code{TRANSFER}: TRANSFER, Transfer bit patterns
287 * @code{TRANSPOSE}: TRANSPOSE, Transpose an array of rank two
288 * @code{TRIM}: TRIM, Remove trailing blank characters of a string
289 * @code{TTYNAM}: TTYNAM, Get the name of a terminal device.
290 * @code{UBOUND}: UBOUND, Upper dimension bounds of an array
291 * @code{UCOBOUND}: UCOBOUND, Upper codimension bounds of an array
292 * @code{UMASK}: UMASK, Set the file creation mask
293 * @code{UNLINK}: UNLINK, Remove a file from the file system
294 * @code{UNPACK}: UNPACK, Unpack an array of rank one into an array
295 * @code{VERIFY}: VERIFY, Scan a string for the absence of a set of characters
296 * @code{XOR}: XOR, Bitwise logical exclusive or
299 @node Introduction to Intrinsics
300 @section Introduction to intrinsic procedures
302 The intrinsic procedures provided by GNU Fortran include all of the
303 intrinsic procedures required by the Fortran 95 standard, a set of
304 intrinsic procedures for backwards compatibility with G77, and a
305 selection of intrinsic procedures from the Fortran 2003 and Fortran 2008
306 standards. Any conflict between a description here and a description in
307 either the Fortran 95 standard, the Fortran 2003 standard or the Fortran
308 2008 standard is unintentional, and the standard(s) should be considered
311 The enumeration of the @code{KIND} type parameter is processor defined in
312 the Fortran 95 standard. GNU Fortran defines the default integer type and
313 default real type by @code{INTEGER(KIND=4)} and @code{REAL(KIND=4)},
314 respectively. The standard mandates that both data types shall have
315 another kind, which have more precision. On typical target architectures
316 supported by @command{gfortran}, this kind type parameter is @code{KIND=8}.
317 Hence, @code{REAL(KIND=8)} and @code{DOUBLE PRECISION} are equivalent.
318 In the description of generic intrinsic procedures, the kind type parameter
319 will be specified by @code{KIND=*}, and in the description of specific
320 names for an intrinsic procedure the kind type parameter will be explicitly
321 given (e.g., @code{REAL(KIND=4)} or @code{REAL(KIND=8)}). Finally, for
322 brevity the optional @code{KIND=} syntax will be omitted.
324 Many of the intrinsic procedures take one or more optional arguments.
325 This document follows the convention used in the Fortran 95 standard,
326 and denotes such arguments by square brackets.
328 GNU Fortran offers the @option{-std=f95} and @option{-std=gnu} options,
329 which can be used to restrict the set of intrinsic procedures to a
330 given standard. By default, @command{gfortran} sets the @option{-std=gnu}
331 option, and so all intrinsic procedures described here are accepted. There
332 is one caveat. For a select group of intrinsic procedures, @command{g77}
333 implemented both a function and a subroutine. Both classes
334 have been implemented in @command{gfortran} for backwards compatibility
335 with @command{g77}. It is noted here that these functions and subroutines
336 cannot be intermixed in a given subprogram. In the descriptions that follow,
337 the applicable standard for each intrinsic procedure is noted.
342 @section @code{ABORT} --- Abort the program
344 @cindex program termination, with core dump
345 @cindex terminate program, with core dump
349 @item @emph{Description}:
350 @code{ABORT} causes immediate termination of the program. On operating
351 systems that support a core dump, @code{ABORT} will produce a core dump.
352 It will also print a backtrace, unless @code{-fno-backtrace} is given.
354 @item @emph{Standard}:
363 @item @emph{Return value}:
366 @item @emph{Example}:
369 integer :: i = 1, j = 2
370 if (i /= j) call abort
371 end program test_abort
374 @item @emph{See also}:
375 @ref{EXIT}, @ref{KILL}, @ref{BACKTRACE}
382 @section @code{ABS} --- Absolute value
389 @cindex absolute value
392 @item @emph{Description}:
393 @code{ABS(A)} computes the absolute value of @code{A}.
395 @item @emph{Standard}:
396 Fortran 77 and later, has overloads that are GNU extensions
402 @code{RESULT = ABS(A)}
404 @item @emph{Arguments}:
405 @multitable @columnfractions .15 .70
406 @item @var{A} @tab The type of the argument shall be an @code{INTEGER},
407 @code{REAL}, or @code{COMPLEX}.
410 @item @emph{Return value}:
411 The return value is of the same type and
412 kind as the argument except the return value is @code{REAL} for a
413 @code{COMPLEX} argument.
415 @item @emph{Example}:
420 complex :: z = (-1.e0,0.e0)
427 @item @emph{Specific names}:
428 @multitable @columnfractions .20 .20 .20 .25
429 @item Name @tab Argument @tab Return type @tab Standard
430 @item @code{ABS(A)} @tab @code{REAL(4) A} @tab @code{REAL(4)} @tab Fortran 77 and later
431 @item @code{CABS(A)} @tab @code{COMPLEX(4) A} @tab @code{REAL(4)} @tab Fortran 77 and later
432 @item @code{DABS(A)} @tab @code{REAL(8) A} @tab @code{REAL(8)} @tab Fortran 77 and later
433 @item @code{IABS(A)} @tab @code{INTEGER(4) A} @tab @code{INTEGER(4)} @tab Fortran 77 and later
434 @item @code{ZABS(A)} @tab @code{COMPLEX(8) A} @tab @code{COMPLEX(8)} @tab GNU extension
435 @item @code{CDABS(A)} @tab @code{COMPLEX(8) A} @tab @code{COMPLEX(8)} @tab GNU extension
442 @section @code{ACCESS} --- Checks file access modes
444 @cindex file system, access mode
447 @item @emph{Description}:
448 @code{ACCESS(NAME, MODE)} checks whether the file @var{NAME}
449 exists, is readable, writable or executable. Except for the
450 executable check, @code{ACCESS} can be replaced by
451 Fortran 95's @code{INQUIRE}.
453 @item @emph{Standard}:
460 @code{RESULT = ACCESS(NAME, MODE)}
462 @item @emph{Arguments}:
463 @multitable @columnfractions .15 .70
464 @item @var{NAME} @tab Scalar @code{CHARACTER} of default kind with the
465 file name. Tailing blank are ignored unless the character @code{achar(0)}
466 is present, then all characters up to and excluding @code{achar(0)} are
468 @item @var{MODE} @tab Scalar @code{CHARACTER} of default kind with the
469 file access mode, may be any concatenation of @code{"r"} (readable),
470 @code{"w"} (writable) and @code{"x"} (executable), or @code{" "} to check
474 @item @emph{Return value}:
475 Returns a scalar @code{INTEGER}, which is @code{0} if the file is
476 accessible in the given mode; otherwise or if an invalid argument
477 has been given for @code{MODE} the value @code{1} is returned.
479 @item @emph{Example}:
483 character(len=*), parameter :: file = 'test.dat'
484 character(len=*), parameter :: file2 = 'test.dat '//achar(0)
485 if(access(file,' ') == 0) print *, trim(file),' is exists'
486 if(access(file,'r') == 0) print *, trim(file),' is readable'
487 if(access(file,'w') == 0) print *, trim(file),' is writable'
488 if(access(file,'x') == 0) print *, trim(file),' is executable'
489 if(access(file2,'rwx') == 0) &
490 print *, trim(file2),' is readable, writable and executable'
491 end program access_test
493 @item @emph{Specific names}:
494 @item @emph{See also}:
501 @section @code{ACHAR} --- Character in @acronym{ASCII} collating sequence
503 @cindex @acronym{ASCII} collating sequence
504 @cindex collating sequence, @acronym{ASCII}
507 @item @emph{Description}:
508 @code{ACHAR(I)} returns the character located at position @code{I}
509 in the @acronym{ASCII} collating sequence.
511 @item @emph{Standard}:
512 Fortran 77 and later, with @var{KIND} argument Fortran 2003 and later
518 @code{RESULT = ACHAR(I [, KIND])}
520 @item @emph{Arguments}:
521 @multitable @columnfractions .15 .70
522 @item @var{I} @tab The type shall be @code{INTEGER}.
523 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
524 expression indicating the kind parameter of the result.
527 @item @emph{Return value}:
528 The return value is of type @code{CHARACTER} with a length of one.
529 If the @var{KIND} argument is present, the return value is of the
530 specified kind and of the default kind otherwise.
532 @item @emph{Example}:
537 end program test_achar
541 See @ref{ICHAR} for a discussion of converting between numerical values
542 and formatted string representations.
544 @item @emph{See also}:
545 @ref{CHAR}, @ref{IACHAR}, @ref{ICHAR}
552 @section @code{ACOS} --- Arccosine function
555 @cindex trigonometric function, cosine, inverse
556 @cindex cosine, inverse
559 @item @emph{Description}:
560 @code{ACOS(X)} computes the arccosine of @var{X} (inverse of @code{COS(X)}).
562 @item @emph{Standard}:
563 Fortran 77 and later, for a complex argument Fortran 2008 or later
569 @code{RESULT = ACOS(X)}
571 @item @emph{Arguments}:
572 @multitable @columnfractions .15 .70
573 @item @var{X} @tab The type shall either be @code{REAL} with a magnitude that is
574 less than or equal to one - or the type shall be @code{COMPLEX}.
577 @item @emph{Return value}:
578 The return value is of the same type and kind as @var{X}.
579 The real part of the result is in radians and lies in the range
580 @math{0 \leq \Re \acos(x) \leq \pi}.
582 @item @emph{Example}:
585 real(8) :: x = 0.866_8
587 end program test_acos
590 @item @emph{Specific names}:
591 @multitable @columnfractions .20 .20 .20 .25
592 @item Name @tab Argument @tab Return type @tab Standard
593 @item @code{ACOS(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab Fortran 77 and later
594 @item @code{DACOS(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab Fortran 77 and later
597 @item @emph{See also}:
598 Inverse function: @ref{COS}
605 @section @code{ACOSH} --- Inverse hyperbolic cosine function
608 @cindex area hyperbolic cosine
609 @cindex inverse hyperbolic cosine
610 @cindex hyperbolic function, cosine, inverse
611 @cindex cosine, hyperbolic, inverse
614 @item @emph{Description}:
615 @code{ACOSH(X)} computes the inverse hyperbolic cosine of @var{X}.
617 @item @emph{Standard}:
618 Fortran 2008 and later
624 @code{RESULT = ACOSH(X)}
626 @item @emph{Arguments}:
627 @multitable @columnfractions .15 .70
628 @item @var{X} @tab The type shall be @code{REAL} or @code{COMPLEX}.
631 @item @emph{Return value}:
632 The return value has the same type and kind as @var{X}. If @var{X} is
633 complex, the imaginary part of the result is in radians and lies between
634 @math{ 0 \leq \Im \acosh(x) \leq \pi}.
636 @item @emph{Example}:
639 REAL(8), DIMENSION(3) :: x = (/ 1.0, 2.0, 3.0 /)
644 @item @emph{Specific names}:
645 @multitable @columnfractions .20 .20 .20 .25
646 @item Name @tab Argument @tab Return type @tab Standard
647 @item @code{DACOSH(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU extension
650 @item @emph{See also}:
651 Inverse function: @ref{COSH}
657 @section @code{ADJUSTL} --- Left adjust a string
659 @cindex string, adjust left
660 @cindex adjust string
663 @item @emph{Description}:
664 @code{ADJUSTL(STRING)} will left adjust a string by removing leading spaces.
665 Spaces are inserted at the end of the string as needed.
667 @item @emph{Standard}:
674 @code{RESULT = ADJUSTL(STRING)}
676 @item @emph{Arguments}:
677 @multitable @columnfractions .15 .70
678 @item @var{STRING} @tab The type shall be @code{CHARACTER}.
681 @item @emph{Return value}:
682 The return value is of type @code{CHARACTER} and of the same kind as
683 @var{STRING} where leading spaces are removed and the same number of
684 spaces are inserted on the end of @var{STRING}.
686 @item @emph{Example}:
689 character(len=20) :: str = ' gfortran'
692 end program test_adjustl
695 @item @emph{See also}:
696 @ref{ADJUSTR}, @ref{TRIM}
702 @section @code{ADJUSTR} --- Right adjust a string
704 @cindex string, adjust right
705 @cindex adjust string
708 @item @emph{Description}:
709 @code{ADJUSTR(STRING)} will right adjust a string by removing trailing spaces.
710 Spaces are inserted at the start of the string as needed.
712 @item @emph{Standard}:
719 @code{RESULT = ADJUSTR(STRING)}
721 @item @emph{Arguments}:
722 @multitable @columnfractions .15 .70
723 @item @var{STR} @tab The type shall be @code{CHARACTER}.
726 @item @emph{Return value}:
727 The return value is of type @code{CHARACTER} and of the same kind as
728 @var{STRING} where trailing spaces are removed and the same number of
729 spaces are inserted at the start of @var{STRING}.
731 @item @emph{Example}:
734 character(len=20) :: str = 'gfortran'
737 end program test_adjustr
740 @item @emph{See also}:
741 @ref{ADJUSTL}, @ref{TRIM}
747 @section @code{AIMAG} --- Imaginary part of complex number
752 @cindex complex numbers, imaginary part
755 @item @emph{Description}:
756 @code{AIMAG(Z)} yields the imaginary part of complex argument @code{Z}.
757 The @code{IMAG(Z)} and @code{IMAGPART(Z)} intrinsic functions are provided
758 for compatibility with @command{g77}, and their use in new code is
759 strongly discouraged.
761 @item @emph{Standard}:
762 Fortran 77 and later, has overloads that are GNU extensions
768 @code{RESULT = AIMAG(Z)}
770 @item @emph{Arguments}:
771 @multitable @columnfractions .15 .70
772 @item @var{Z} @tab The type of the argument shall be @code{COMPLEX}.
775 @item @emph{Return value}:
776 The return value is of type @code{REAL} with the
777 kind type parameter of the argument.
779 @item @emph{Example}:
784 z4 = cmplx(1.e0_4, 0.e0_4)
785 z8 = cmplx(0.e0_8, 1.e0_8)
786 print *, aimag(z4), dimag(z8)
787 end program test_aimag
790 @item @emph{Specific names}:
791 @multitable @columnfractions .20 .20 .20 .25
792 @item Name @tab Argument @tab Return type @tab Standard
793 @item @code{AIMAG(Z)} @tab @code{COMPLEX Z} @tab @code{REAL} @tab GNU extension
794 @item @code{DIMAG(Z)} @tab @code{COMPLEX(8) Z} @tab @code{REAL(8)} @tab GNU extension
795 @item @code{IMAG(Z)} @tab @code{COMPLEX Z} @tab @code{REAL} @tab GNU extension
796 @item @code{IMAGPART(Z)} @tab @code{COMPLEX Z} @tab @code{REAL} @tab GNU extension
803 @section @code{AINT} --- Truncate to a whole number
807 @cindex rounding, floor
810 @item @emph{Description}:
811 @code{AINT(A [, KIND])} truncates its argument to a whole number.
813 @item @emph{Standard}:
820 @code{RESULT = AINT(A [, KIND])}
822 @item @emph{Arguments}:
823 @multitable @columnfractions .15 .70
824 @item @var{A} @tab The type of the argument shall be @code{REAL}.
825 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
826 expression indicating the kind parameter of the result.
829 @item @emph{Return value}:
830 The return value is of type @code{REAL} with the kind type parameter of the
831 argument if the optional @var{KIND} is absent; otherwise, the kind
832 type parameter will be given by @var{KIND}. If the magnitude of
833 @var{X} is less than one, @code{AINT(X)} returns zero. If the
834 magnitude is equal to or greater than one then it returns the largest
835 whole number that does not exceed its magnitude. The sign is the same
836 as the sign of @var{X}.
838 @item @emph{Example}:
845 print *, aint(x4), dint(x8)
847 end program test_aint
850 @item @emph{Specific names}:
851 @multitable @columnfractions .20 .20 .20 .25
852 @item Name @tab Argument @tab Return type @tab Standard
853 @item @code{AINT(A)} @tab @code{REAL(4) A} @tab @code{REAL(4)} @tab Fortran 77 and later
854 @item @code{DINT(A)} @tab @code{REAL(8) A} @tab @code{REAL(8)} @tab Fortran 77 and later
861 @section @code{ALARM} --- Execute a routine after a given delay
863 @cindex delayed execution
866 @item @emph{Description}:
867 @code{ALARM(SECONDS, HANDLER [, STATUS])} causes external subroutine @var{HANDLER}
868 to be executed after a delay of @var{SECONDS} by using @code{alarm(2)} to
869 set up a signal and @code{signal(2)} to catch it. If @var{STATUS} is
870 supplied, it will be returned with the number of seconds remaining until
871 any previously scheduled alarm was due to be delivered, or zero if there
872 was no previously scheduled alarm.
874 @item @emph{Standard}:
881 @code{CALL ALARM(SECONDS, HANDLER [, STATUS])}
883 @item @emph{Arguments}:
884 @multitable @columnfractions .15 .70
885 @item @var{SECONDS} @tab The type of the argument shall be a scalar
886 @code{INTEGER}. It is @code{INTENT(IN)}.
887 @item @var{HANDLER} @tab Signal handler (@code{INTEGER FUNCTION} or
888 @code{SUBROUTINE}) or dummy/global @code{INTEGER} scalar. The scalar
889 values may be either @code{SIG_IGN=1} to ignore the alarm generated
890 or @code{SIG_DFL=0} to set the default action. It is @code{INTENT(IN)}.
891 @item @var{STATUS} @tab (Optional) @var{STATUS} shall be a scalar
892 variable of the default @code{INTEGER} kind. It is @code{INTENT(OUT)}.
895 @item @emph{Example}:
898 external handler_print
900 call alarm (3, handler_print, i)
903 end program test_alarm
905 This will cause the external routine @var{handler_print} to be called
912 @section @code{ALL} --- All values in @var{MASK} along @var{DIM} are true
914 @cindex array, apply condition
915 @cindex array, condition testing
918 @item @emph{Description}:
919 @code{ALL(MASK [, DIM])} determines if all the values are true in @var{MASK}
920 in the array along dimension @var{DIM}.
922 @item @emph{Standard}:
926 Transformational function
929 @code{RESULT = ALL(MASK [, DIM])}
931 @item @emph{Arguments}:
932 @multitable @columnfractions .15 .70
933 @item @var{MASK} @tab The type of the argument shall be @code{LOGICAL} and
934 it shall not be scalar.
935 @item @var{DIM} @tab (Optional) @var{DIM} shall be a scalar integer
936 with a value that lies between one and the rank of @var{MASK}.
939 @item @emph{Return value}:
940 @code{ALL(MASK)} returns a scalar value of type @code{LOGICAL} where
941 the kind type parameter is the same as the kind type parameter of
942 @var{MASK}. If @var{DIM} is present, then @code{ALL(MASK, DIM)} returns
943 an array with the rank of @var{MASK} minus 1. The shape is determined from
944 the shape of @var{MASK} where the @var{DIM} dimension is elided.
948 @code{ALL(MASK)} is true if all elements of @var{MASK} are true.
949 It also is true if @var{MASK} has zero size; otherwise, it is false.
951 If the rank of @var{MASK} is one, then @code{ALL(MASK,DIM)} is equivalent
952 to @code{ALL(MASK)}. If the rank is greater than one, then @code{ALL(MASK,DIM)}
953 is determined by applying @code{ALL} to the array sections.
956 @item @emph{Example}:
960 l = all((/.true., .true., .true./))
965 integer a(2,3), b(2,3)
969 print *, all(a .eq. b, 1)
970 print *, all(a .eq. b, 2)
971 end subroutine section
979 @section @code{ALLOCATED} --- Status of an allocatable entity
981 @cindex allocation, status
984 @item @emph{Description}:
985 @code{ALLOCATED(ARRAY)} and @code{ALLOCATED(SCALAR)} check the allocation
986 status of @var{ARRAY} and @var{SCALAR}, respectively.
988 @item @emph{Standard}:
989 Fortran 95 and later. Note, the @code{SCALAR=} keyword and allocatable
990 scalar entities are available in Fortran 2003 and later.
996 @multitable @columnfractions .80
997 @item @code{RESULT = ALLOCATED(ARRAY)}
998 @item @code{RESULT = ALLOCATED(SCALAR)}
1001 @item @emph{Arguments}:
1002 @multitable @columnfractions .15 .70
1003 @item @var{ARRAY} @tab The argument shall be an @code{ALLOCATABLE} array.
1004 @item @var{SCALAR} @tab The argument shall be an @code{ALLOCATABLE} scalar.
1007 @item @emph{Return value}:
1008 The return value is a scalar @code{LOGICAL} with the default logical
1009 kind type parameter. If the argument is allocated, then the result is
1010 @code{.TRUE.}; otherwise, it returns @code{.FALSE.}
1012 @item @emph{Example}:
1014 program test_allocated
1016 real(4), allocatable :: x(:)
1017 if (.not. allocated(x)) allocate(x(i))
1018 end program test_allocated
1025 @section @code{AND} --- Bitwise logical AND
1027 @cindex bitwise logical and
1028 @cindex logical and, bitwise
1031 @item @emph{Description}:
1032 Bitwise logical @code{AND}.
1034 This intrinsic routine is provided for backwards compatibility with
1035 GNU Fortran 77. For integer arguments, programmers should consider
1036 the use of the @ref{IAND} intrinsic defined by the Fortran standard.
1038 @item @emph{Standard}:
1044 @item @emph{Syntax}:
1045 @code{RESULT = AND(I, J)}
1047 @item @emph{Arguments}:
1048 @multitable @columnfractions .15 .70
1049 @item @var{I} @tab The type shall be either a scalar @code{INTEGER}
1050 type or a scalar @code{LOGICAL} type.
1051 @item @var{J} @tab The type shall be the same as the type of @var{I}.
1054 @item @emph{Return value}:
1055 The return type is either a scalar @code{INTEGER} or a scalar
1056 @code{LOGICAL}. If the kind type parameters differ, then the
1057 smaller kind type is implicitly converted to larger kind, and the
1058 return has the larger kind.
1060 @item @emph{Example}:
1063 LOGICAL :: T = .TRUE., F = .FALSE.
1065 DATA a / Z'F' /, b / Z'3' /
1067 WRITE (*,*) AND(T, T), AND(T, F), AND(F, T), AND(F, F)
1068 WRITE (*,*) AND(a, b)
1072 @item @emph{See also}:
1073 Fortran 95 elemental function: @ref{IAND}
1079 @section @code{ANINT} --- Nearest whole number
1083 @cindex rounding, ceiling
1086 @item @emph{Description}:
1087 @code{ANINT(A [, KIND])} rounds its argument to the nearest whole number.
1089 @item @emph{Standard}:
1090 Fortran 77 and later
1095 @item @emph{Syntax}:
1096 @code{RESULT = ANINT(A [, KIND])}
1098 @item @emph{Arguments}:
1099 @multitable @columnfractions .15 .70
1100 @item @var{A} @tab The type of the argument shall be @code{REAL}.
1101 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
1102 expression indicating the kind parameter of the result.
1105 @item @emph{Return value}:
1106 The return value is of type real with the kind type parameter of the
1107 argument if the optional @var{KIND} is absent; otherwise, the kind
1108 type parameter will be given by @var{KIND}. If @var{A} is greater than
1109 zero, @code{ANINT(A)} returns @code{AINT(X+0.5)}. If @var{A} is
1110 less than or equal to zero then it returns @code{AINT(X-0.5)}.
1112 @item @emph{Example}:
1119 print *, anint(x4), dnint(x8)
1121 end program test_anint
1124 @item @emph{Specific names}:
1125 @multitable @columnfractions .20 .20 .20 .25
1126 @item Name @tab Argument @tab Return type @tab Standard
1127 @item @code{AINT(A)} @tab @code{REAL(4) A} @tab @code{REAL(4)} @tab Fortran 77 and later
1128 @item @code{DNINT(A)} @tab @code{REAL(8) A} @tab @code{REAL(8)} @tab Fortran 77 and later
1135 @section @code{ANY} --- Any value in @var{MASK} along @var{DIM} is true
1137 @cindex array, apply condition
1138 @cindex array, condition testing
1141 @item @emph{Description}:
1142 @code{ANY(MASK [, DIM])} determines if any of the values in the logical array
1143 @var{MASK} along dimension @var{DIM} are @code{.TRUE.}.
1145 @item @emph{Standard}:
1146 Fortran 95 and later
1149 Transformational function
1151 @item @emph{Syntax}:
1152 @code{RESULT = ANY(MASK [, DIM])}
1154 @item @emph{Arguments}:
1155 @multitable @columnfractions .15 .70
1156 @item @var{MASK} @tab The type of the argument shall be @code{LOGICAL} and
1157 it shall not be scalar.
1158 @item @var{DIM} @tab (Optional) @var{DIM} shall be a scalar integer
1159 with a value that lies between one and the rank of @var{MASK}.
1162 @item @emph{Return value}:
1163 @code{ANY(MASK)} returns a scalar value of type @code{LOGICAL} where
1164 the kind type parameter is the same as the kind type parameter of
1165 @var{MASK}. If @var{DIM} is present, then @code{ANY(MASK, DIM)} returns
1166 an array with the rank of @var{MASK} minus 1. The shape is determined from
1167 the shape of @var{MASK} where the @var{DIM} dimension is elided.
1171 @code{ANY(MASK)} is true if any element of @var{MASK} is true;
1172 otherwise, it is false. It also is false if @var{MASK} has zero size.
1174 If the rank of @var{MASK} is one, then @code{ANY(MASK,DIM)} is equivalent
1175 to @code{ANY(MASK)}. If the rank is greater than one, then @code{ANY(MASK,DIM)}
1176 is determined by applying @code{ANY} to the array sections.
1179 @item @emph{Example}:
1183 l = any((/.true., .true., .true./))
1188 integer a(2,3), b(2,3)
1192 print *, any(a .eq. b, 1)
1193 print *, any(a .eq. b, 2)
1194 end subroutine section
1195 end program test_any
1202 @section @code{ASIN} --- Arcsine function
1205 @cindex trigonometric function, sine, inverse
1206 @cindex sine, inverse
1209 @item @emph{Description}:
1210 @code{ASIN(X)} computes the arcsine of its @var{X} (inverse of @code{SIN(X)}).
1212 @item @emph{Standard}:
1213 Fortran 77 and later, for a complex argument Fortran 2008 or later
1218 @item @emph{Syntax}:
1219 @code{RESULT = ASIN(X)}
1221 @item @emph{Arguments}:
1222 @multitable @columnfractions .15 .70
1223 @item @var{X} @tab The type shall be either @code{REAL} and a magnitude that is
1224 less than or equal to one - or be @code{COMPLEX}.
1227 @item @emph{Return value}:
1228 The return value is of the same type and kind as @var{X}.
1229 The real part of the result is in radians and lies in the range
1230 @math{-\pi/2 \leq \Re \asin(x) \leq \pi/2}.
1232 @item @emph{Example}:
1235 real(8) :: x = 0.866_8
1237 end program test_asin
1240 @item @emph{Specific names}:
1241 @multitable @columnfractions .20 .20 .20 .25
1242 @item Name @tab Argument @tab Return type @tab Standard
1243 @item @code{ASIN(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab Fortran 77 and later
1244 @item @code{DASIN(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab Fortran 77 and later
1247 @item @emph{See also}:
1248 Inverse function: @ref{SIN}
1255 @section @code{ASINH} --- Inverse hyperbolic sine function
1258 @cindex area hyperbolic sine
1259 @cindex inverse hyperbolic sine
1260 @cindex hyperbolic function, sine, inverse
1261 @cindex sine, hyperbolic, inverse
1264 @item @emph{Description}:
1265 @code{ASINH(X)} computes the inverse hyperbolic sine of @var{X}.
1267 @item @emph{Standard}:
1268 Fortran 2008 and later
1273 @item @emph{Syntax}:
1274 @code{RESULT = ASINH(X)}
1276 @item @emph{Arguments}:
1277 @multitable @columnfractions .15 .70
1278 @item @var{X} @tab The type shall be @code{REAL} or @code{COMPLEX}.
1281 @item @emph{Return value}:
1282 The return value is of the same type and kind as @var{X}. If @var{X} is
1283 complex, the imaginary part of the result is in radians and lies between
1284 @math{-\pi/2 \leq \Im \asinh(x) \leq \pi/2}.
1286 @item @emph{Example}:
1289 REAL(8), DIMENSION(3) :: x = (/ -1.0, 0.0, 1.0 /)
1290 WRITE (*,*) ASINH(x)
1294 @item @emph{Specific names}:
1295 @multitable @columnfractions .20 .20 .20 .25
1296 @item Name @tab Argument @tab Return type @tab Standard
1297 @item @code{DASINH(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU extension.
1300 @item @emph{See also}:
1301 Inverse function: @ref{SINH}
1307 @section @code{ASSOCIATED} --- Status of a pointer or pointer/target pair
1309 @cindex pointer, status
1310 @cindex association status
1313 @item @emph{Description}:
1314 @code{ASSOCIATED(POINTER [, TARGET])} determines the status of the pointer
1315 @var{POINTER} or if @var{POINTER} is associated with the target @var{TARGET}.
1317 @item @emph{Standard}:
1318 Fortran 95 and later
1323 @item @emph{Syntax}:
1324 @code{RESULT = ASSOCIATED(POINTER [, TARGET])}
1326 @item @emph{Arguments}:
1327 @multitable @columnfractions .15 .70
1328 @item @var{POINTER} @tab @var{POINTER} shall have the @code{POINTER} attribute
1329 and it can be of any type.
1330 @item @var{TARGET} @tab (Optional) @var{TARGET} shall be a pointer or
1331 a target. It must have the same type, kind type parameter, and
1332 array rank as @var{POINTER}.
1334 The association status of neither @var{POINTER} nor @var{TARGET} shall be
1337 @item @emph{Return value}:
1338 @code{ASSOCIATED(POINTER)} returns a scalar value of type @code{LOGICAL(4)}.
1339 There are several cases:
1341 @item (A) When the optional @var{TARGET} is not present then
1342 @code{ASSOCIATED(POINTER)} is true if @var{POINTER} is associated with a target; otherwise, it returns false.
1343 @item (B) If @var{TARGET} is present and a scalar target, the result is true if
1344 @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
1345 disassociated, the result is false.
1346 @item (C) If @var{TARGET} is present and an array target, the result is true if
1347 @var{TARGET} and @var{POINTER} have the same shape, are not zero-sized arrays,
1348 are arrays whose elements are not zero-sized storage sequences, and
1349 @var{TARGET} and @var{POINTER} occupy the same storage units in array element
1351 As in case(B), the result is false, if @var{POINTER} is disassociated.
1352 @item (D) If @var{TARGET} is present and an scalar pointer, the result is true
1353 if @var{TARGET} is associated with @var{POINTER}, the target associated with
1354 @var{TARGET} are not zero-sized storage sequences and occupy the same storage
1356 The result is false, if either @var{TARGET} or @var{POINTER} is disassociated.
1357 @item (E) If @var{TARGET} is present and an array pointer, the result is true if
1358 target associated with @var{POINTER} and the target associated with @var{TARGET}
1359 have the same shape, are not zero-sized arrays, are arrays whose elements are
1360 not zero-sized storage sequences, and @var{TARGET} and @var{POINTER} occupy
1361 the same storage units in array element order.
1362 The result is false, if either @var{TARGET} or @var{POINTER} is disassociated.
1365 @item @emph{Example}:
1367 program test_associated
1369 real, target :: tgt(2) = (/1., 2./)
1370 real, pointer :: ptr(:)
1372 if (associated(ptr) .eqv. .false.) call abort
1373 if (associated(ptr,tgt) .eqv. .false.) call abort
1374 end program test_associated
1377 @item @emph{See also}:
1384 @section @code{ATAN} --- Arctangent function
1387 @cindex trigonometric function, tangent, inverse
1388 @cindex tangent, inverse
1391 @item @emph{Description}:
1392 @code{ATAN(X)} computes the arctangent of @var{X}.
1394 @item @emph{Standard}:
1395 Fortran 77 and later, for a complex argument and for two arguments
1396 Fortran 2008 or later
1401 @item @emph{Syntax}:
1402 @multitable @columnfractions .80
1403 @item @code{RESULT = ATAN(X)}
1404 @item @code{RESULT = ATAN(Y, X)}
1407 @item @emph{Arguments}:
1408 @multitable @columnfractions .15 .70
1409 @item @var{X} @tab The type shall be @code{REAL} or @code{COMPLEX};
1410 if @var{Y} is present, @var{X} shall be REAL.
1411 @item @var{Y} shall be of the same type and kind as @var{X}.
1414 @item @emph{Return value}:
1415 The return value is of the same type and kind as @var{X}.
1416 If @var{Y} is present, the result is identical to @code{ATAN2(Y,X)}.
1417 Otherwise, it the arcus tangent of @var{X}, where the real part of
1418 the result is in radians and lies in the range
1419 @math{-\pi/2 \leq \Re \atan(x) \leq \pi/2}.
1421 @item @emph{Example}:
1424 real(8) :: x = 2.866_8
1426 end program test_atan
1429 @item @emph{Specific names}:
1430 @multitable @columnfractions .20 .20 .20 .25
1431 @item Name @tab Argument @tab Return type @tab Standard
1432 @item @code{ATAN(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab Fortran 77 and later
1433 @item @code{DATAN(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab Fortran 77 and later
1436 @item @emph{See also}:
1437 Inverse function: @ref{TAN}
1444 @section @code{ATAN2} --- Arctangent function
1447 @cindex trigonometric function, tangent, inverse
1448 @cindex tangent, inverse
1451 @item @emph{Description}:
1452 @code{ATAN2(Y, X)} computes the principal value of the argument
1453 function of the complex number @math{X + i Y}. This function can
1454 be used to transform from Cartesian into polar coordinates and
1455 allows to determine the angle in the correct quadrant.
1457 @item @emph{Standard}:
1458 Fortran 77 and later
1463 @item @emph{Syntax}:
1464 @code{RESULT = ATAN2(Y, X)}
1466 @item @emph{Arguments}:
1467 @multitable @columnfractions .15 .70
1468 @item @var{Y} @tab The type shall be @code{REAL}.
1469 @item @var{X} @tab The type and kind type parameter shall be the same as @var{Y}.
1470 If @var{Y} is zero, then @var{X} must be nonzero.
1473 @item @emph{Return value}:
1474 The return value has the same type and kind type parameter as @var{Y}. It
1475 is the principal value of the complex number @math{X + i Y}. If @var{X}
1476 is nonzero, then it lies in the range @math{-\pi \le \atan (x) \leq \pi}.
1477 The sign is positive if @var{Y} is positive. If @var{Y} is zero, then
1478 the return value is zero if @var{X} is strictly positive, @math{\pi} if
1479 @var{X} is negative and @var{Y} is positive zero (or the processor does
1480 not handle signed zeros), and @math{-\pi} if @var{X} is negative and
1481 @var{Y} is negative zero. Finally, if @var{X} is zero, then the
1482 magnitude of the result is @math{\pi/2}.
1484 @item @emph{Example}:
1487 real(4) :: x = 1.e0_4, y = 0.5e0_4
1489 end program test_atan2
1492 @item @emph{Specific names}:
1493 @multitable @columnfractions .20 .20 .20 .25
1494 @item Name @tab Argument @tab Return type @tab Standard
1495 @item @code{ATAN2(X, Y)} @tab @code{REAL(4) X, Y} @tab @code{REAL(4)} @tab Fortran 77 and later
1496 @item @code{DATAN2(X, Y)} @tab @code{REAL(8) X, Y} @tab @code{REAL(8)} @tab Fortran 77 and later
1503 @section @code{ATANH} --- Inverse hyperbolic tangent function
1506 @cindex area hyperbolic tangent
1507 @cindex inverse hyperbolic tangent
1508 @cindex hyperbolic function, tangent, inverse
1509 @cindex tangent, hyperbolic, inverse
1512 @item @emph{Description}:
1513 @code{ATANH(X)} computes the inverse hyperbolic tangent of @var{X}.
1515 @item @emph{Standard}:
1516 Fortran 2008 and later
1521 @item @emph{Syntax}:
1522 @code{RESULT = ATANH(X)}
1524 @item @emph{Arguments}:
1525 @multitable @columnfractions .15 .70
1526 @item @var{X} @tab The type shall be @code{REAL} or @code{COMPLEX}.
1529 @item @emph{Return value}:
1530 The return value has same type and kind as @var{X}. If @var{X} is
1531 complex, the imaginary part of the result is in radians and lies between
1532 @math{-\pi/2 \leq \Im \atanh(x) \leq \pi/2}.
1534 @item @emph{Example}:
1537 REAL, DIMENSION(3) :: x = (/ -1.0, 0.0, 1.0 /)
1538 WRITE (*,*) ATANH(x)
1542 @item @emph{Specific names}:
1543 @multitable @columnfractions .20 .20 .20 .25
1544 @item Name @tab Argument @tab Return type @tab Standard
1545 @item @code{DATANH(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU extension
1548 @item @emph{See also}:
1549 Inverse function: @ref{TANH}
1555 @section @code{ATOMIC_DEFINE} --- Setting a variable atomically
1556 @fnindex ATOMIC_DEFINE
1557 @cindex Atomic subroutine, define
1560 @item @emph{Description}:
1561 @code{ATOMIC_DEFINE(ATOM, VALUE)} defines the variable @var{ATOM} with the value
1562 @var{VALUE} atomically.
1564 @item @emph{Standard}:
1565 Fortran 2008 and later
1570 @item @emph{Syntax}:
1571 @code{CALL ATOMIC_DEFINE(ATOM, VALUE)}
1573 @item @emph{Arguments}:
1574 @multitable @columnfractions .15 .70
1575 @item @var{ATOM} @tab Scalar coarray or coindexed variable of either integer
1576 type with @code{ATOMIC_INT_KIND} kind or logical type
1577 with @code{ATOMIC_LOGICAL_KIND} kind.
1578 @item @var{VALURE} @tab Scalar and of the same type as @var{ATOM}. If the kind
1579 is different, the value is converted to the kind of
1583 @item @emph{Example}:
1587 integer(atomic_int_kind) :: atom[*]
1588 call atomic_define (atom[1], this_image())
1592 @item @emph{See also}:
1593 @ref{ATOMIC_REF}, @ref{ISO_FORTRAN_ENV}
1599 @section @code{ATOMIC_REF} --- Obtaining the value of a variable atomically
1601 @cindex Atomic subroutine, reference
1604 @item @emph{Description}:
1605 @code{ATOMIC_DEFINE(ATOM, VALUE)} atomically assigns the value of the
1606 variable @var{ATOM} to @var{VALUE}.
1608 @item @emph{Standard}:
1609 Fortran 2008 and later
1614 @item @emph{Syntax}:
1615 @code{CALL ATOMIC_REF(VALUE, ATOM)}
1617 @item @emph{Arguments}:
1618 @multitable @columnfractions .15 .70
1619 @item @var{VALURE} @tab Scalar and of the same type as @var{ATOM}. If the kind
1620 is different, the value is converted to the kind of
1622 @item @var{ATOM} @tab Scalar coarray or coindexed variable of either integer
1623 type with @code{ATOMIC_INT_KIND} kind or logical type
1624 with @code{ATOMIC_LOGICAL_KIND} kind.
1627 @item @emph{Example}:
1631 logical(atomic_logical_kind) :: atom[*]
1633 call atomic_ref (atom, .false.)
1635 call atomic_ref (atom, val)
1642 @item @emph{See also}:
1643 @ref{ATOMIC_DEFINE}, @ref{ISO_FORTRAN_ENV}
1649 @section @code{BACKTRACE} --- Show a backtrace
1654 @item @emph{Description}:
1655 @code{BACKTRACE} shows a backtrace at an arbitrary place in user code. Program
1656 execution continues normally afterwards. The backtrace information is printed
1657 to the unit corresponding to @code{ERROR_UNIT} in @code{ISO_FORTRAN_ENV}.
1659 @item @emph{Standard}:
1665 @item @emph{Syntax}:
1666 @code{CALL BACKTRACE}
1668 @item @emph{Arguments}:
1671 @item @emph{See also}:
1678 @section @code{BESSEL_J0} --- Bessel function of the first kind of order 0
1682 @cindex Bessel function, first kind
1685 @item @emph{Description}:
1686 @code{BESSEL_J0(X)} computes the Bessel function of the first kind of
1687 order 0 of @var{X}. This function is available under the name
1688 @code{BESJ0} as a GNU extension.
1690 @item @emph{Standard}:
1691 Fortran 2008 and later
1696 @item @emph{Syntax}:
1697 @code{RESULT = BESSEL_J0(X)}
1699 @item @emph{Arguments}:
1700 @multitable @columnfractions .15 .70
1701 @item @var{X} @tab The type shall be @code{REAL}, and it shall be scalar.
1704 @item @emph{Return value}:
1705 The return value is of type @code{REAL} and lies in the
1706 range @math{ - 0.4027... \leq Bessel (0,x) \leq 1}. It has the same
1709 @item @emph{Example}:
1712 real(8) :: x = 0.0_8
1714 end program test_besj0
1717 @item @emph{Specific names}:
1718 @multitable @columnfractions .20 .20 .20 .25
1719 @item Name @tab Argument @tab Return type @tab Standard
1720 @item @code{DBESJ0(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU extension
1727 @section @code{BESSEL_J1} --- Bessel function of the first kind of order 1
1731 @cindex Bessel function, first kind
1734 @item @emph{Description}:
1735 @code{BESSEL_J1(X)} computes the Bessel function of the first kind of
1736 order 1 of @var{X}. This function is available under the name
1737 @code{BESJ1} as a GNU extension.
1739 @item @emph{Standard}:
1745 @item @emph{Syntax}:
1746 @code{RESULT = BESSEL_J1(X)}
1748 @item @emph{Arguments}:
1749 @multitable @columnfractions .15 .70
1750 @item @var{X} @tab The type shall be @code{REAL}, and it shall be scalar.
1753 @item @emph{Return value}:
1754 The return value is of type @code{REAL} and it lies in the
1755 range @math{ - 0.5818... \leq Bessel (0,x) \leq 0.5818 }. It has the same
1758 @item @emph{Example}:
1761 real(8) :: x = 1.0_8
1763 end program test_besj1
1766 @item @emph{Specific names}:
1767 @multitable @columnfractions .20 .20 .20 .25
1768 @item Name @tab Argument @tab Return type @tab Standard
1769 @item @code{DBESJ1(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU extension
1776 @section @code{BESSEL_JN} --- Bessel function of the first kind
1780 @cindex Bessel function, first kind
1783 @item @emph{Description}:
1784 @code{BESSEL_JN(N, X)} computes the Bessel function of the first kind of
1785 order @var{N} of @var{X}. This function is available under the name
1786 @code{BESJN} as a GNU extension. If @var{N} and @var{X} are arrays,
1787 their ranks and shapes shall conform.
1789 @code{BESSEL_JN(N1, N2, X)} returns an array with the Bessel functions
1790 of the first kind of the orders @var{N1} to @var{N2}.
1792 @item @emph{Standard}:
1793 Fortran 2008 and later, negative @var{N} is allowed as GNU extension
1796 Elemental function, except for the transformational function
1797 @code{BESSEL_JN(N1, N2, X)}
1799 @item @emph{Syntax}:
1800 @multitable @columnfractions .80
1801 @item @code{RESULT = BESSEL_JN(N, X)}
1802 @item @code{RESULT = BESSEL_JN(N1, N2, X)}
1805 @item @emph{Arguments}:
1806 @multitable @columnfractions .15 .70
1807 @item @var{N} @tab Shall be a scalar or an array of type @code{INTEGER}.
1808 @item @var{N1} @tab Shall be a non-negative scalar of type @code{INTEGER}.
1809 @item @var{N2} @tab Shall be a non-negative scalar of type @code{INTEGER}.
1810 @item @var{X} @tab Shall be a scalar or an array of type @code{REAL};
1811 for @code{BESSEL_JN(N1, N2, X)} it shall be scalar.
1814 @item @emph{Return value}:
1815 The return value is a scalar of type @code{REAL}. It has the same
1819 The transformational function uses a recurrence algorithm which might,
1820 for some values of @var{X}, lead to different results than calls to
1821 the elemental function.
1823 @item @emph{Example}:
1826 real(8) :: x = 1.0_8
1828 end program test_besjn
1831 @item @emph{Specific names}:
1832 @multitable @columnfractions .20 .20 .20 .25
1833 @item Name @tab Argument @tab Return type @tab Standard
1834 @item @code{DBESJN(N, X)} @tab @code{INTEGER N} @tab @code{REAL(8)} @tab GNU extension
1835 @item @tab @code{REAL(8) X} @tab @tab
1842 @section @code{BESSEL_Y0} --- Bessel function of the second kind of order 0
1846 @cindex Bessel function, second kind
1849 @item @emph{Description}:
1850 @code{BESSEL_Y0(X)} computes the Bessel function of the second kind of
1851 order 0 of @var{X}. This function is available under the name
1852 @code{BESY0} as a GNU extension.
1854 @item @emph{Standard}:
1855 Fortran 2008 and later
1860 @item @emph{Syntax}:
1861 @code{RESULT = BESSEL_Y0(X)}
1863 @item @emph{Arguments}:
1864 @multitable @columnfractions .15 .70
1865 @item @var{X} @tab The type shall be @code{REAL}, and it shall be scalar.
1868 @item @emph{Return value}:
1869 The return value is a scalar of type @code{REAL}. It has the same
1872 @item @emph{Example}:
1875 real(8) :: x = 0.0_8
1877 end program test_besy0
1880 @item @emph{Specific names}:
1881 @multitable @columnfractions .20 .20 .20 .25
1882 @item Name @tab Argument @tab Return type @tab Standard
1883 @item @code{DBESY0(X)}@tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU extension
1890 @section @code{BESSEL_Y1} --- Bessel function of the second kind of order 1
1894 @cindex Bessel function, second kind
1897 @item @emph{Description}:
1898 @code{BESSEL_Y1(X)} computes the Bessel function of the second kind of
1899 order 1 of @var{X}. This function is available under the name
1900 @code{BESY1} as a GNU extension.
1902 @item @emph{Standard}:
1903 Fortran 2008 and later
1908 @item @emph{Syntax}:
1909 @code{RESULT = BESSEL_Y1(X)}
1911 @item @emph{Arguments}:
1912 @multitable @columnfractions .15 .70
1913 @item @var{X} @tab The type shall be @code{REAL}, and it shall be scalar.
1916 @item @emph{Return value}:
1917 The return value is a scalar of type @code{REAL}. It has the same
1920 @item @emph{Example}:
1923 real(8) :: x = 1.0_8
1925 end program test_besy1
1928 @item @emph{Specific names}:
1929 @multitable @columnfractions .20 .20 .20 .25
1930 @item Name @tab Argument @tab Return type @tab Standard
1931 @item @code{DBESY1(X)}@tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU extension
1938 @section @code{BESSEL_YN} --- Bessel function of the second kind
1942 @cindex Bessel function, second kind
1945 @item @emph{Description}:
1946 @code{BESSEL_YN(N, X)} computes the Bessel function of the second kind of
1947 order @var{N} of @var{X}. This function is available under the name
1948 @code{BESYN} as a GNU extension. If @var{N} and @var{X} are arrays,
1949 their ranks and shapes shall conform.
1951 @code{BESSEL_YN(N1, N2, X)} returns an array with the Bessel functions
1952 of the first kind of the orders @var{N1} to @var{N2}.
1954 @item @emph{Standard}:
1955 Fortran 2008 and later, negative @var{N} is allowed as GNU extension
1958 Elemental function, except for the transformational function
1959 @code{BESSEL_YN(N1, N2, X)}
1961 @item @emph{Syntax}:
1962 @multitable @columnfractions .80
1963 @item @code{RESULT = BESSEL_YN(N, X)}
1964 @item @code{RESULT = BESSEL_YN(N1, N2, X)}
1967 @item @emph{Arguments}:
1968 @multitable @columnfractions .15 .70
1969 @item @var{N} @tab Shall be a scalar or an array of type @code{INTEGER} .
1970 @item @var{N1} @tab Shall be a non-negative scalar of type @code{INTEGER}.
1971 @item @var{N2} @tab Shall be a non-negative scalar of type @code{INTEGER}.
1972 @item @var{X} @tab Shall be a scalar or an array of type @code{REAL};
1973 for @code{BESSEL_YN(N1, N2, X)} it shall be scalar.
1976 @item @emph{Return value}:
1977 The return value is a scalar of type @code{REAL}. It has the same
1981 The transformational function uses a recurrence algorithm which might,
1982 for some values of @var{X}, lead to different results than calls to
1983 the elemental function.
1985 @item @emph{Example}:
1988 real(8) :: x = 1.0_8
1990 end program test_besyn
1993 @item @emph{Specific names}:
1994 @multitable @columnfractions .20 .20 .20 .25
1995 @item Name @tab Argument @tab Return type @tab Standard
1996 @item @code{DBESYN(N,X)} @tab @code{INTEGER N} @tab @code{REAL(8)} @tab GNU extension
1997 @item @tab @code{REAL(8) X} @tab @tab
2004 @section @code{BGE} --- Bitwise greater than or equal to
2006 @cindex bitwise comparison
2009 @item @emph{Description}:
2010 Determines whether an integral is a bitwise greater than or equal to
2013 @item @emph{Standard}:
2014 Fortran 2008 and later
2019 @item @emph{Syntax}:
2020 @code{RESULT = BGE(I, J)}
2022 @item @emph{Arguments}:
2023 @multitable @columnfractions .15 .70
2024 @item @var{I} @tab Shall be of @code{INTEGER} type.
2025 @item @var{J} @tab Shall be of @code{INTEGER} type, and of the same kind
2029 @item @emph{Return value}:
2030 The return value is of type @code{LOGICAL} and of the default kind.
2032 @item @emph{See also}:
2033 @ref{BGT}, @ref{BLE}, @ref{BLT}
2039 @section @code{BGT} --- Bitwise greater than
2041 @cindex bitwise comparison
2044 @item @emph{Description}:
2045 Determines whether an integral is a bitwise greater than another.
2047 @item @emph{Standard}:
2048 Fortran 2008 and later
2053 @item @emph{Syntax}:
2054 @code{RESULT = BGT(I, J)}
2056 @item @emph{Arguments}:
2057 @multitable @columnfractions .15 .70
2058 @item @var{I} @tab Shall be of @code{INTEGER} type.
2059 @item @var{J} @tab Shall be of @code{INTEGER} type, and of the same kind
2063 @item @emph{Return value}:
2064 The return value is of type @code{LOGICAL} and of the default kind.
2066 @item @emph{See also}:
2067 @ref{BGE}, @ref{BLE}, @ref{BLT}
2073 @section @code{BIT_SIZE} --- Bit size inquiry function
2075 @cindex bits, number of
2076 @cindex size of a variable, in bits
2079 @item @emph{Description}:
2080 @code{BIT_SIZE(I)} returns the number of bits (integer precision plus sign bit)
2081 represented by the type of @var{I}. The result of @code{BIT_SIZE(I)} is
2082 independent of the actual value of @var{I}.
2084 @item @emph{Standard}:
2085 Fortran 95 and later
2090 @item @emph{Syntax}:
2091 @code{RESULT = BIT_SIZE(I)}
2093 @item @emph{Arguments}:
2094 @multitable @columnfractions .15 .70
2095 @item @var{I} @tab The type shall be @code{INTEGER}.
2098 @item @emph{Return value}:
2099 The return value is of type @code{INTEGER}
2101 @item @emph{Example}:
2103 program test_bit_size
2108 end program test_bit_size
2115 @section @code{BLE} --- Bitwise less than or equal to
2117 @cindex bitwise comparison
2120 @item @emph{Description}:
2121 Determines whether an integral is a bitwise less than or equal to
2124 @item @emph{Standard}:
2125 Fortran 2008 and later
2130 @item @emph{Syntax}:
2131 @code{RESULT = BLE(I, J)}
2133 @item @emph{Arguments}:
2134 @multitable @columnfractions .15 .70
2135 @item @var{I} @tab Shall be of @code{INTEGER} type.
2136 @item @var{J} @tab Shall be of @code{INTEGER} type, and of the same kind
2140 @item @emph{Return value}:
2141 The return value is of type @code{LOGICAL} and of the default kind.
2143 @item @emph{See also}:
2144 @ref{BGT}, @ref{BGE}, @ref{BLT}
2150 @section @code{BLT} --- Bitwise less than
2152 @cindex bitwise comparison
2155 @item @emph{Description}:
2156 Determines whether an integral is a bitwise less than another.
2158 @item @emph{Standard}:
2159 Fortran 2008 and later
2164 @item @emph{Syntax}:
2165 @code{RESULT = BLT(I, J)}
2167 @item @emph{Arguments}:
2168 @multitable @columnfractions .15 .70
2169 @item @var{I} @tab Shall be of @code{INTEGER} type.
2170 @item @var{J} @tab Shall be of @code{INTEGER} type, and of the same kind
2174 @item @emph{Return value}:
2175 The return value is of type @code{LOGICAL} and of the default kind.
2177 @item @emph{See also}:
2178 @ref{BGE}, @ref{BGT}, @ref{BLE}
2184 @section @code{BTEST} --- Bit test function
2186 @cindex bits, testing
2189 @item @emph{Description}:
2190 @code{BTEST(I,POS)} returns logical @code{.TRUE.} if the bit at @var{POS}
2191 in @var{I} is set. The counting of the bits starts at 0.
2193 @item @emph{Standard}:
2194 Fortran 95 and later
2199 @item @emph{Syntax}:
2200 @code{RESULT = BTEST(I, POS)}
2202 @item @emph{Arguments}:
2203 @multitable @columnfractions .15 .70
2204 @item @var{I} @tab The type shall be @code{INTEGER}.
2205 @item @var{POS} @tab The type shall be @code{INTEGER}.
2208 @item @emph{Return value}:
2209 The return value is of type @code{LOGICAL}
2211 @item @emph{Example}:
2214 integer :: i = 32768 + 1024 + 64
2218 bool = btest(i, pos)
2221 end program test_btest
2227 @section @code{C_ASSOCIATED} --- Status of a C pointer
2228 @fnindex C_ASSOCIATED
2229 @cindex association status, C pointer
2230 @cindex pointer, C association status
2233 @item @emph{Description}:
2234 @code{C_ASSOCIATED(c_prt_1[, c_ptr_2])} determines the status of the C pointer
2235 @var{c_ptr_1} or if @var{c_ptr_1} is associated with the target @var{c_ptr_2}.
2237 @item @emph{Standard}:
2238 Fortran 2003 and later
2243 @item @emph{Syntax}:
2244 @code{RESULT = C_ASSOCIATED(c_prt_1[, c_ptr_2])}
2246 @item @emph{Arguments}:
2247 @multitable @columnfractions .15 .70
2248 @item @var{c_ptr_1} @tab Scalar of the type @code{C_PTR} or @code{C_FUNPTR}.
2249 @item @var{c_ptr_2} @tab (Optional) Scalar of the same type as @var{c_ptr_1}.
2252 @item @emph{Return value}:
2253 The return value is of type @code{LOGICAL}; it is @code{.false.} if either
2254 @var{c_ptr_1} is a C NULL pointer or if @var{c_ptr1} and @var{c_ptr_2}
2255 point to different addresses.
2257 @item @emph{Example}:
2259 subroutine association_test(a,b)
2260 use iso_c_binding, only: c_associated, c_loc, c_ptr
2264 if(c_associated(b, c_loc(a))) &
2265 stop 'b and a do not point to same target'
2266 end subroutine association_test
2269 @item @emph{See also}:
2270 @ref{C_LOC}, @ref{C_FUNLOC}
2275 @section @code{C_FUNLOC} --- Obtain the C address of a procedure
2277 @cindex pointer, C address of procedures
2280 @item @emph{Description}:
2281 @code{C_FUNLOC(x)} determines the C address of the argument.
2283 @item @emph{Standard}:
2284 Fortran 2003 and later
2289 @item @emph{Syntax}:
2290 @code{RESULT = C_FUNLOC(x)}
2292 @item @emph{Arguments}:
2293 @multitable @columnfractions .15 .70
2294 @item @var{x} @tab Interoperable function or pointer to such function.
2297 @item @emph{Return value}:
2298 The return value is of type @code{C_FUNPTR} and contains the C address
2301 @item @emph{Example}:
2307 subroutine sub(a) bind(c)
2317 subroutine my_routine(p) bind(c,name='myC_func')
2319 type(c_funptr), intent(in) :: p
2322 call my_routine(c_funloc(sub))
2326 @item @emph{See also}:
2327 @ref{C_ASSOCIATED}, @ref{C_LOC}, @ref{C_F_POINTER}, @ref{C_F_PROCPOINTER}
2331 @node C_F_PROCPOINTER
2332 @section @code{C_F_PROCPOINTER} --- Convert C into Fortran procedure pointer
2333 @fnindex C_F_PROCPOINTER
2334 @cindex pointer, C address of pointers
2337 @item @emph{Description}:
2338 @code{C_F_PROCPOINTER(CPTR, FPTR)} Assign the target of the C function pointer
2339 @var{CPTR} to the Fortran procedure pointer @var{FPTR}.
2341 @item @emph{Standard}:
2342 Fortran 2003 and later
2347 @item @emph{Syntax}:
2348 @code{CALL C_F_PROCPOINTER(cptr, fptr)}
2350 @item @emph{Arguments}:
2351 @multitable @columnfractions .15 .70
2352 @item @var{CPTR} @tab scalar of the type @code{C_FUNPTR}. It is
2354 @item @var{FPTR} @tab procedure pointer interoperable with @var{cptr}. It is
2358 @item @emph{Example}:
2366 real(c_float), intent(in) :: a
2367 real(c_float) :: func
2371 function getIterFunc() bind(c,name="getIterFunc")
2373 type(c_funptr) :: getIterFunc
2376 type(c_funptr) :: cfunptr
2377 procedure(func), pointer :: myFunc
2378 cfunptr = getIterFunc()
2379 call c_f_procpointer(cfunptr, myFunc)
2383 @item @emph{See also}:
2384 @ref{C_LOC}, @ref{C_F_POINTER}
2389 @section @code{C_F_POINTER} --- Convert C into Fortran pointer
2390 @fnindex C_F_POINTER
2391 @cindex pointer, convert C to Fortran
2394 @item @emph{Description}:
2395 @code{C_F_POINTER(CPTR, FPTR[, SHAPE])} assigns the target of the C pointer
2396 @var{CPTR} to the Fortran pointer @var{FPTR} and specifies its shape.
2398 @item @emph{Standard}:
2399 Fortran 2003 and later
2404 @item @emph{Syntax}:
2405 @code{CALL C_F_POINTER(CPTR, FPTR[, SHAPE])}
2407 @item @emph{Arguments}:
2408 @multitable @columnfractions .15 .70
2409 @item @var{CPTR} @tab scalar of the type @code{C_PTR}. It is
2411 @item @var{FPTR} @tab pointer interoperable with @var{cptr}. It is
2413 @item @var{SHAPE} @tab (Optional) Rank-one array of type @code{INTEGER}
2414 with @code{INTENT(IN)}. It shall be present
2415 if and only if @var{fptr} is an array. The size
2416 must be equal to the rank of @var{fptr}.
2419 @item @emph{Example}:
2425 subroutine my_routine(p) bind(c,name='myC_func')
2427 type(c_ptr), intent(out) :: p
2431 real,pointer :: a(:)
2432 call my_routine(cptr)
2433 call c_f_pointer(cptr, a, [12])
2437 @item @emph{See also}:
2438 @ref{C_LOC}, @ref{C_F_PROCPOINTER}
2443 @section @code{C_LOC} --- Obtain the C address of an object
2445 @cindex procedure pointer, convert C to Fortran
2448 @item @emph{Description}:
2449 @code{C_LOC(X)} determines the C address of the argument.
2451 @item @emph{Standard}:
2452 Fortran 2003 and later
2457 @item @emph{Syntax}:
2458 @code{RESULT = C_LOC(X)}
2460 @item @emph{Arguments}:
2461 @multitable @columnfractions .10 .75
2462 @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.
2466 @item @emph{Return value}:
2467 The return value is of type @code{C_PTR} and contains the C address
2470 @item @emph{Example}:
2472 subroutine association_test(a,b)
2473 use iso_c_binding, only: c_associated, c_loc, c_ptr
2477 if(c_associated(b, c_loc(a))) &
2478 stop 'b and a do not point to same target'
2479 end subroutine association_test
2482 @item @emph{See also}:
2483 @ref{C_ASSOCIATED}, @ref{C_FUNLOC}, @ref{C_F_POINTER}, @ref{C_F_PROCPOINTER}
2488 @section @code{C_SIZEOF} --- Size in bytes of an expression
2490 @cindex expression size
2491 @cindex size of an expression
2494 @item @emph{Description}:
2495 @code{C_SIZEOF(X)} calculates the number of bytes of storage the
2496 expression @code{X} occupies.
2498 @item @emph{Standard}:
2502 Inquiry function of the module @code{ISO_C_BINDING}
2504 @item @emph{Syntax}:
2505 @code{N = C_SIZEOF(X)}
2507 @item @emph{Arguments}:
2508 @multitable @columnfractions .15 .70
2509 @item @var{X} @tab The argument shall be an interoperable data entity.
2512 @item @emph{Return value}:
2513 The return value is of type integer and of the system-dependent kind
2514 @code{C_SIZE_T} (from the @code{ISO_C_BINDING} module). Its value is the
2515 number of bytes occupied by the argument. If the argument has the
2516 @code{POINTER} attribute, the number of bytes of the storage area pointed
2517 to is returned. If the argument is of a derived type with @code{POINTER}
2518 or @code{ALLOCATABLE} components, the return value does not account for
2519 the sizes of the data pointed to by these components.
2521 @item @emph{Example}:
2525 real(c_float) :: r, s(5)
2526 print *, (c_sizeof(s)/c_sizeof(r) == 5)
2529 The example will print @code{.TRUE.} unless you are using a platform
2530 where default @code{REAL} variables are unusually padded.
2532 @item @emph{See also}:
2533 @ref{SIZEOF}, @ref{STORAGE_SIZE}
2538 @section @code{CEILING} --- Integer ceiling function
2541 @cindex rounding, ceiling
2544 @item @emph{Description}:
2545 @code{CEILING(A)} returns the least integer greater than or equal to @var{A}.
2547 @item @emph{Standard}:
2548 Fortran 95 and later
2553 @item @emph{Syntax}:
2554 @code{RESULT = CEILING(A [, KIND])}
2556 @item @emph{Arguments}:
2557 @multitable @columnfractions .15 .70
2558 @item @var{A} @tab The type shall be @code{REAL}.
2559 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
2560 expression indicating the kind parameter of the result.
2563 @item @emph{Return value}:
2564 The return value is of type @code{INTEGER(KIND)} if @var{KIND} is present
2565 and a default-kind @code{INTEGER} otherwise.
2567 @item @emph{Example}:
2569 program test_ceiling
2572 print *, ceiling(x) ! returns 64
2573 print *, ceiling(y) ! returns -63
2574 end program test_ceiling
2577 @item @emph{See also}:
2578 @ref{FLOOR}, @ref{NINT}
2585 @section @code{CHAR} --- Character conversion function
2587 @cindex conversion, to character
2590 @item @emph{Description}:
2591 @code{CHAR(I [, KIND])} returns the character represented by the integer @var{I}.
2593 @item @emph{Standard}:
2594 Fortran 77 and later
2599 @item @emph{Syntax}:
2600 @code{RESULT = CHAR(I [, KIND])}
2602 @item @emph{Arguments}:
2603 @multitable @columnfractions .15 .70
2604 @item @var{I} @tab The type shall be @code{INTEGER}.
2605 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
2606 expression indicating the kind parameter of the result.
2609 @item @emph{Return value}:
2610 The return value is of type @code{CHARACTER(1)}
2612 @item @emph{Example}:
2618 print *, i, c ! returns 'J'
2619 end program test_char
2622 @item @emph{Specific names}:
2623 @multitable @columnfractions .20 .20 .20 .25
2624 @item Name @tab Argument @tab Return type @tab Standard
2625 @item @code{CHAR(I)} @tab @code{INTEGER I} @tab @code{CHARACTER(LEN=1)} @tab F77 and later
2629 See @ref{ICHAR} for a discussion of converting between numerical values
2630 and formatted string representations.
2632 @item @emph{See also}:
2633 @ref{ACHAR}, @ref{IACHAR}, @ref{ICHAR}
2640 @section @code{CHDIR} --- Change working directory
2642 @cindex system, working directory
2645 @item @emph{Description}:
2646 Change current working directory to a specified path.
2648 This intrinsic is provided in both subroutine and function forms; however,
2649 only one form can be used in any given program unit.
2651 @item @emph{Standard}:
2655 Subroutine, function
2657 @item @emph{Syntax}:
2658 @multitable @columnfractions .80
2659 @item @code{CALL CHDIR(NAME [, STATUS])}
2660 @item @code{STATUS = CHDIR(NAME)}
2663 @item @emph{Arguments}:
2664 @multitable @columnfractions .15 .70
2665 @item @var{NAME} @tab The type shall be @code{CHARACTER} of default
2666 kind and shall specify a valid path within the file system.
2667 @item @var{STATUS} @tab (Optional) @code{INTEGER} status flag of the default
2668 kind. Returns 0 on success, and a system specific and nonzero error code
2672 @item @emph{Example}:
2675 CHARACTER(len=255) :: path
2677 WRITE(*,*) TRIM(path)
2680 WRITE(*,*) TRIM(path)
2684 @item @emph{See also}:
2691 @section @code{CHMOD} --- Change access permissions of files
2693 @cindex file system, change access mode
2696 @item @emph{Description}:
2697 @code{CHMOD} changes the permissions of a file.
2699 This intrinsic is provided in both subroutine and function forms; however,
2700 only one form can be used in any given program unit.
2702 @item @emph{Standard}:
2706 Subroutine, function
2708 @item @emph{Syntax}:
2709 @multitable @columnfractions .80
2710 @item @code{CALL CHMOD(NAME, MODE[, STATUS])}
2711 @item @code{STATUS = CHMOD(NAME, MODE)}
2714 @item @emph{Arguments}:
2715 @multitable @columnfractions .15 .70
2717 @item @var{NAME} @tab Scalar @code{CHARACTER} of default kind with the
2718 file name. Trailing blanks are ignored unless the character
2719 @code{achar(0)} is present, then all characters up to and excluding
2720 @code{achar(0)} are used as the file name.
2722 @item @var{MODE} @tab Scalar @code{CHARACTER} of default kind giving the
2723 file permission. @var{MODE} uses the same syntax as the @code{chmod} utility
2724 as defined by the POSIX standard. The argument shall either be a string of
2725 a nonnegative octal number or a symbolic mode.
2727 @item @var{STATUS} @tab (optional) scalar @code{INTEGER}, which is
2728 @code{0} on success and nonzero otherwise.
2731 @item @emph{Return value}:
2732 In either syntax, @var{STATUS} is set to @code{0} on success and nonzero
2735 @item @emph{Example}:
2736 @code{CHMOD} as subroutine
2741 call chmod('test.dat','u+x',status)
2742 print *, 'Status: ', status
2743 end program chmod_test
2745 @code{CHMOD} as function:
2750 status = chmod('test.dat','u+x')
2751 print *, 'Status: ', status
2752 end program chmod_test
2760 @section @code{CMPLX} --- Complex conversion function
2762 @cindex complex numbers, conversion to
2763 @cindex conversion, to complex
2766 @item @emph{Description}:
2767 @code{CMPLX(X [, Y [, KIND]])} returns a complex number where @var{X} is converted to
2768 the real component. If @var{Y} is present it is converted to the imaginary
2769 component. If @var{Y} is not present then the imaginary component is set to
2770 0.0. If @var{X} is complex then @var{Y} must not be present.
2772 @item @emph{Standard}:
2773 Fortran 77 and later
2778 @item @emph{Syntax}:
2779 @code{RESULT = CMPLX(X [, Y [, KIND]])}
2781 @item @emph{Arguments}:
2782 @multitable @columnfractions .15 .70
2783 @item @var{X} @tab The type may be @code{INTEGER}, @code{REAL},
2785 @item @var{Y} @tab (Optional; only allowed if @var{X} is not
2786 @code{COMPLEX}.) May be @code{INTEGER} or @code{REAL}.
2787 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
2788 expression indicating the kind parameter of the result.
2791 @item @emph{Return value}:
2792 The return value is of @code{COMPLEX} type, with a kind equal to
2793 @var{KIND} if it is specified. If @var{KIND} is not specified, the
2794 result is of the default @code{COMPLEX} kind, regardless of the kinds of
2795 @var{X} and @var{Y}.
2797 @item @emph{Example}:
2804 print *, z, cmplx(x)
2805 end program test_cmplx
2808 @item @emph{See also}:
2814 @node COMMAND_ARGUMENT_COUNT
2815 @section @code{COMMAND_ARGUMENT_COUNT} --- Get number of command line arguments
2816 @fnindex COMMAND_ARGUMENT_COUNT
2817 @cindex command-line arguments
2818 @cindex command-line arguments, number of
2819 @cindex arguments, to program
2822 @item @emph{Description}:
2823 @code{COMMAND_ARGUMENT_COUNT} returns the number of arguments passed on the
2824 command line when the containing program was invoked.
2826 @item @emph{Standard}:
2827 Fortran 2003 and later
2832 @item @emph{Syntax}:
2833 @code{RESULT = COMMAND_ARGUMENT_COUNT()}
2835 @item @emph{Arguments}:
2836 @multitable @columnfractions .15 .70
2840 @item @emph{Return value}:
2841 The return value is an @code{INTEGER} of default kind.
2843 @item @emph{Example}:
2845 program test_command_argument_count
2847 count = command_argument_count()
2849 end program test_command_argument_count
2852 @item @emph{See also}:
2853 @ref{GET_COMMAND}, @ref{GET_COMMAND_ARGUMENT}
2858 @node COMPILER_OPTIONS
2859 @section @code{COMPILER_OPTIONS} --- Options passed to the compiler
2860 @fnindex COMPILER_OPTIONS
2861 @cindex flags inquiry function
2862 @cindex options inquiry function
2863 @cindex compiler flags inquiry function
2866 @item @emph{Description}:
2867 @code{COMPILER_OPTIONS} returns a string with the options used for
2870 @item @emph{Standard}:
2874 Inquiry function of the module @code{ISO_FORTRAN_ENV}
2876 @item @emph{Syntax}:
2877 @code{STR = COMPILER_OPTIONS()}
2879 @item @emph{Arguments}:
2882 @item @emph{Return value}:
2883 The return value is a default-kind string with system-dependent length.
2884 It contains the compiler flags used to compile the file, which called
2885 the @code{COMPILER_OPTIONS} intrinsic.
2887 @item @emph{Example}:
2890 print '(4a)', 'This file was compiled by ', &
2891 compiler_version(), ' using the options ', &
2896 @item @emph{See also}:
2897 @ref{COMPILER_VERSION}, @ref{ISO_FORTRAN_ENV}
2902 @node COMPILER_VERSION
2903 @section @code{COMPILER_VERSION} --- Compiler version string
2904 @fnindex COMPILER_VERSION
2905 @cindex compiler, name and version
2906 @cindex version of the compiler
2909 @item @emph{Description}:
2910 @code{COMPILER_VERSION} returns a string with the name and the
2911 version of the compiler.
2913 @item @emph{Standard}:
2917 Inquiry function of the module @code{ISO_FORTRAN_ENV}
2919 @item @emph{Syntax}:
2920 @code{STR = COMPILER_VERSION()}
2922 @item @emph{Arguments}:
2925 @item @emph{Return value}:
2926 The return value is a default-kind string with system-dependent length.
2927 It contains the name of the compiler and its version number.
2929 @item @emph{Example}:
2932 print '(4a)', 'This file was compiled by ', &
2933 compiler_version(), ' using the options ', &
2938 @item @emph{See also}:
2939 @ref{COMPILER_OPTIONS}, @ref{ISO_FORTRAN_ENV}
2945 @section @code{COMPLEX} --- Complex conversion function
2947 @cindex complex numbers, conversion to
2948 @cindex conversion, to complex
2951 @item @emph{Description}:
2952 @code{COMPLEX(X, Y)} returns a complex number where @var{X} is converted
2953 to the real component and @var{Y} is converted to the imaginary
2956 @item @emph{Standard}:
2962 @item @emph{Syntax}:
2963 @code{RESULT = COMPLEX(X, Y)}
2965 @item @emph{Arguments}:
2966 @multitable @columnfractions .15 .70
2967 @item @var{X} @tab The type may be @code{INTEGER} or @code{REAL}.
2968 @item @var{Y} @tab The type may be @code{INTEGER} or @code{REAL}.
2971 @item @emph{Return value}:
2972 If @var{X} and @var{Y} are both of @code{INTEGER} type, then the return
2973 value is of default @code{COMPLEX} type.
2975 If @var{X} and @var{Y} are of @code{REAL} type, or one is of @code{REAL}
2976 type and one is of @code{INTEGER} type, then the return value is of
2977 @code{COMPLEX} type with a kind equal to that of the @code{REAL}
2978 argument with the highest precision.
2980 @item @emph{Example}:
2982 program test_complex
2985 print *, complex(i, x)
2986 end program test_complex
2989 @item @emph{See also}:
2996 @section @code{CONJG} --- Complex conjugate function
2999 @cindex complex conjugate
3002 @item @emph{Description}:
3003 @code{CONJG(Z)} returns the conjugate of @var{Z}. If @var{Z} is @code{(x, y)}
3004 then the result is @code{(x, -y)}
3006 @item @emph{Standard}:
3007 Fortran 77 and later, has overloads that are GNU extensions
3012 @item @emph{Syntax}:
3015 @item @emph{Arguments}:
3016 @multitable @columnfractions .15 .70
3017 @item @var{Z} @tab The type shall be @code{COMPLEX}.
3020 @item @emph{Return value}:
3021 The return value is of type @code{COMPLEX}.
3023 @item @emph{Example}:
3026 complex :: z = (2.0, 3.0)
3027 complex(8) :: dz = (2.71_8, -3.14_8)
3032 end program test_conjg
3035 @item @emph{Specific names}:
3036 @multitable @columnfractions .20 .20 .20 .25
3037 @item Name @tab Argument @tab Return type @tab Standard
3038 @item @code{CONJG(Z)} @tab @code{COMPLEX Z} @tab @code{COMPLEX} @tab GNU extension
3039 @item @code{DCONJG(Z)} @tab @code{COMPLEX(8) Z} @tab @code{COMPLEX(8)} @tab GNU extension
3046 @section @code{COS} --- Cosine function
3052 @cindex trigonometric function, cosine
3056 @item @emph{Description}:
3057 @code{COS(X)} computes the cosine of @var{X}.
3059 @item @emph{Standard}:
3060 Fortran 77 and later, has overloads that are GNU extensions
3065 @item @emph{Syntax}:
3066 @code{RESULT = COS(X)}
3068 @item @emph{Arguments}:
3069 @multitable @columnfractions .15 .70
3070 @item @var{X} @tab The type shall be @code{REAL} or
3074 @item @emph{Return value}:
3075 The return value is of the same type and kind as @var{X}. The real part
3076 of the result is in radians. If @var{X} is of the type @code{REAL},
3077 the return value lies in the range @math{ -1 \leq \cos (x) \leq 1}.
3079 @item @emph{Example}:
3084 end program test_cos
3087 @item @emph{Specific names}:
3088 @multitable @columnfractions .20 .20 .20 .25
3089 @item Name @tab Argument @tab Return type @tab Standard
3090 @item @code{COS(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab Fortran 77 and later
3091 @item @code{DCOS(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab Fortran 77 and later
3092 @item @code{CCOS(X)} @tab @code{COMPLEX(4) X} @tab @code{COMPLEX(4)} @tab Fortran 77 and later
3093 @item @code{ZCOS(X)} @tab @code{COMPLEX(8) X} @tab @code{COMPLEX(8)} @tab GNU extension
3094 @item @code{CDCOS(X)} @tab @code{COMPLEX(8) X} @tab @code{COMPLEX(8)} @tab GNU extension
3097 @item @emph{See also}:
3098 Inverse function: @ref{ACOS}
3105 @section @code{COSH} --- Hyperbolic cosine function
3108 @cindex hyperbolic cosine
3109 @cindex hyperbolic function, cosine
3110 @cindex cosine, hyperbolic
3113 @item @emph{Description}:
3114 @code{COSH(X)} computes the hyperbolic cosine of @var{X}.
3116 @item @emph{Standard}:
3117 Fortran 77 and later, for a complex argument Fortran 2008 or later
3122 @item @emph{Syntax}:
3125 @item @emph{Arguments}:
3126 @multitable @columnfractions .15 .70
3127 @item @var{X} @tab The type shall be @code{REAL} or @code{COMPLEX}.
3130 @item @emph{Return value}:
3131 The return value has same type and kind as @var{X}. If @var{X} is
3132 complex, the imaginary part of the result is in radians. If @var{X}
3133 is @code{REAL}, the return value has a lower bound of one,
3134 @math{\cosh (x) \geq 1}.
3136 @item @emph{Example}:
3139 real(8) :: x = 1.0_8
3141 end program test_cosh
3144 @item @emph{Specific names}:
3145 @multitable @columnfractions .20 .20 .20 .25
3146 @item Name @tab Argument @tab Return type @tab Standard
3147 @item @code{COSH(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab Fortran 77 and later
3148 @item @code{DCOSH(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab Fortran 77 and later
3151 @item @emph{See also}:
3152 Inverse function: @ref{ACOSH}
3159 @section @code{COUNT} --- Count function
3161 @cindex array, conditionally count elements
3162 @cindex array, element counting
3163 @cindex array, number of elements
3166 @item @emph{Description}:
3168 Counts the number of @code{.TRUE.} elements in a logical @var{MASK},
3169 or, if the @var{DIM} argument is supplied, counts the number of
3170 elements along each row of the array in the @var{DIM} direction.
3171 If the array has zero size, or all of the elements of @var{MASK} are
3172 @code{.FALSE.}, then the result is @code{0}.
3174 @item @emph{Standard}:
3175 Fortran 95 and later, with @var{KIND} argument Fortran 2003 and later
3178 Transformational function
3180 @item @emph{Syntax}:
3181 @code{RESULT = COUNT(MASK [, DIM, KIND])}
3183 @item @emph{Arguments}:
3184 @multitable @columnfractions .15 .70
3185 @item @var{MASK} @tab The type shall be @code{LOGICAL}.
3186 @item @var{DIM} @tab (Optional) The type shall be @code{INTEGER}.
3187 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
3188 expression indicating the kind parameter of the result.
3191 @item @emph{Return value}:
3192 The return value is of type @code{INTEGER} and of kind @var{KIND}. If
3193 @var{KIND} is absent, the return value is of default integer kind.
3194 If @var{DIM} is present, the result is an array with a rank one less
3195 than the rank of @var{ARRAY}, and a size corresponding to the shape
3196 of @var{ARRAY} with the @var{DIM} dimension removed.
3198 @item @emph{Example}:
3201 integer, dimension(2,3) :: a, b
3202 logical, dimension(2,3) :: mask
3203 a = reshape( (/ 1, 2, 3, 4, 5, 6 /), (/ 2, 3 /))
3204 b = reshape( (/ 0, 7, 3, 4, 5, 8 /), (/ 2, 3 /))
3205 print '(3i3)', a(1,:)
3206 print '(3i3)', a(2,:)
3208 print '(3i3)', b(1,:)
3209 print '(3i3)', b(2,:)
3212 print '(3l3)', mask(1,:)
3213 print '(3l3)', mask(2,:)
3215 print '(3i3)', count(mask)
3217 print '(3i3)', count(mask, 1)
3219 print '(3i3)', count(mask, 2)
3220 end program test_count
3227 @section @code{CPU_TIME} --- CPU elapsed time in seconds
3229 @cindex time, elapsed
3232 @item @emph{Description}:
3233 Returns a @code{REAL} value representing the elapsed CPU time in
3234 seconds. This is useful for testing segments of code to determine
3237 If a time source is available, time will be reported with microsecond
3238 resolution. If no time source is available, @var{TIME} is set to
3241 Note that @var{TIME} may contain a, system dependent, arbitrary offset
3242 and may not start with @code{0.0}. For @code{CPU_TIME}, the absolute
3243 value is meaningless, only differences between subsequent calls to
3244 this subroutine, as shown in the example below, should be used.
3247 @item @emph{Standard}:
3248 Fortran 95 and later
3253 @item @emph{Syntax}:
3254 @code{CALL CPU_TIME(TIME)}
3256 @item @emph{Arguments}:
3257 @multitable @columnfractions .15 .70
3258 @item @var{TIME} @tab The type shall be @code{REAL} with @code{INTENT(OUT)}.
3261 @item @emph{Return value}:
3264 @item @emph{Example}:
3266 program test_cpu_time
3267 real :: start, finish
3268 call cpu_time(start)
3269 ! put code to test here
3270 call cpu_time(finish)
3271 print '("Time = ",f6.3," seconds.")',finish-start
3272 end program test_cpu_time
3275 @item @emph{See also}:
3276 @ref{SYSTEM_CLOCK}, @ref{DATE_AND_TIME}
3282 @section @code{CSHIFT} --- Circular shift elements of an array
3284 @cindex array, shift circularly
3285 @cindex array, permutation
3286 @cindex array, rotate
3289 @item @emph{Description}:
3290 @code{CSHIFT(ARRAY, SHIFT [, DIM])} performs a circular shift on elements of
3291 @var{ARRAY} along the dimension of @var{DIM}. If @var{DIM} is omitted it is
3292 taken to be @code{1}. @var{DIM} is a scalar of type @code{INTEGER} in the
3293 range of @math{1 \leq DIM \leq n)} where @math{n} is the rank of @var{ARRAY}.
3294 If the rank of @var{ARRAY} is one, then all elements of @var{ARRAY} are shifted
3295 by @var{SHIFT} places. If rank is greater than one, then all complete rank one
3296 sections of @var{ARRAY} along the given dimension are shifted. Elements
3297 shifted out one end of each rank one section are shifted back in the other end.
3299 @item @emph{Standard}:
3300 Fortran 95 and later
3303 Transformational function
3305 @item @emph{Syntax}:
3306 @code{RESULT = CSHIFT(ARRAY, SHIFT [, DIM])}
3308 @item @emph{Arguments}:
3309 @multitable @columnfractions .15 .70
3310 @item @var{ARRAY} @tab Shall be an array of any type.
3311 @item @var{SHIFT} @tab The type shall be @code{INTEGER}.
3312 @item @var{DIM} @tab The type shall be @code{INTEGER}.
3315 @item @emph{Return value}:
3316 Returns an array of same type and rank as the @var{ARRAY} argument.
3318 @item @emph{Example}:
3321 integer, dimension(3,3) :: a
3322 a = reshape( (/ 1, 2, 3, 4, 5, 6, 7, 8, 9 /), (/ 3, 3 /))
3323 print '(3i3)', a(1,:)
3324 print '(3i3)', a(2,:)
3325 print '(3i3)', a(3,:)
3326 a = cshift(a, SHIFT=(/1, 2, -1/), DIM=2)
3328 print '(3i3)', a(1,:)
3329 print '(3i3)', a(2,:)
3330 print '(3i3)', a(3,:)
3331 end program test_cshift
3338 @section @code{CTIME} --- Convert a time into a string
3340 @cindex time, conversion to string
3341 @cindex conversion, to string
3344 @item @emph{Description}:
3345 @code{CTIME} converts a system time value, such as returned by
3346 @code{TIME8}, to a string. Unless the application has called
3347 @code{setlocale}, the output will be in the default locale, of length
3348 24 and of the form @samp{Sat Aug 19 18:13:14 1995}. In other locales,
3349 a longer string may result.
3351 This intrinsic is provided in both subroutine and function forms; however,
3352 only one form can be used in any given program unit.
3354 @item @emph{Standard}:
3358 Subroutine, function
3360 @item @emph{Syntax}:
3361 @multitable @columnfractions .80
3362 @item @code{CALL CTIME(TIME, RESULT)}.
3363 @item @code{RESULT = CTIME(TIME)}.
3366 @item @emph{Arguments}:
3367 @multitable @columnfractions .15 .70
3368 @item @var{TIME} @tab The type shall be of type @code{INTEGER}.
3369 @item @var{RESULT} @tab The type shall be of type @code{CHARACTER} and
3370 of default kind. It is an @code{INTENT(OUT)} argument. If the length
3371 of this variable is too short for the time and date string to fit
3372 completely, it will be blank on procedure return.
3375 @item @emph{Return value}:
3376 The converted date and time as a string.
3378 @item @emph{Example}:
3382 character(len=30) :: date
3385 ! Do something, main part of the program
3388 print *, 'Program was started on ', date
3389 end program test_ctime
3392 @item @emph{See Also}:
3393 @ref{DATE_AND_TIME}, @ref{GMTIME}, @ref{LTIME}, @ref{TIME}, @ref{TIME8}
3399 @section @code{DATE_AND_TIME} --- Date and time subroutine
3400 @fnindex DATE_AND_TIME
3401 @cindex date, current
3402 @cindex current date
3403 @cindex time, current
3404 @cindex current time
3407 @item @emph{Description}:
3408 @code{DATE_AND_TIME(DATE, TIME, ZONE, VALUES)} gets the corresponding date and
3409 time information from the real-time system clock. @var{DATE} is
3410 @code{INTENT(OUT)} and has form ccyymmdd. @var{TIME} is @code{INTENT(OUT)} and
3411 has form hhmmss.sss. @var{ZONE} is @code{INTENT(OUT)} and has form (+-)hhmm,
3412 representing the difference with respect to Coordinated Universal Time (UTC).
3413 Unavailable time and date parameters return blanks.
3415 @var{VALUES} is @code{INTENT(OUT)} and provides the following:
3417 @multitable @columnfractions .15 .30 .40
3418 @item @tab @code{VALUE(1)}: @tab The year
3419 @item @tab @code{VALUE(2)}: @tab The month
3420 @item @tab @code{VALUE(3)}: @tab The day of the month
3421 @item @tab @code{VALUE(4)}: @tab Time difference with UTC in minutes
3422 @item @tab @code{VALUE(5)}: @tab The hour of the day
3423 @item @tab @code{VALUE(6)}: @tab The minutes of the hour
3424 @item @tab @code{VALUE(7)}: @tab The seconds of the minute
3425 @item @tab @code{VALUE(8)}: @tab The milliseconds of the second
3428 @item @emph{Standard}:
3429 Fortran 95 and later
3434 @item @emph{Syntax}:
3435 @code{CALL DATE_AND_TIME([DATE, TIME, ZONE, VALUES])}
3437 @item @emph{Arguments}:
3438 @multitable @columnfractions .15 .70
3439 @item @var{DATE} @tab (Optional) The type shall be @code{CHARACTER(LEN=8)}
3440 or larger, and of default kind.
3441 @item @var{TIME} @tab (Optional) The type shall be @code{CHARACTER(LEN=10)}
3442 or larger, and of default kind.
3443 @item @var{ZONE} @tab (Optional) The type shall be @code{CHARACTER(LEN=5)}
3444 or larger, and of default kind.
3445 @item @var{VALUES}@tab (Optional) The type shall be @code{INTEGER(8)}.
3448 @item @emph{Return value}:
3451 @item @emph{Example}:
3453 program test_time_and_date
3454 character(8) :: date
3455 character(10) :: time
3456 character(5) :: zone
3457 integer,dimension(8) :: values
3458 ! using keyword arguments
3459 call date_and_time(date,time,zone,values)
3460 call date_and_time(DATE=date,ZONE=zone)
3461 call date_and_time(TIME=time)
3462 call date_and_time(VALUES=values)
3463 print '(a,2x,a,2x,a)', date, time, zone
3464 print '(8i5))', values
3465 end program test_time_and_date
3468 @item @emph{See also}:
3469 @ref{CPU_TIME}, @ref{SYSTEM_CLOCK}
3475 @section @code{DBLE} --- Double conversion function
3477 @cindex conversion, to real
3480 @item @emph{Description}:
3481 @code{DBLE(A)} Converts @var{A} to double precision real type.
3483 @item @emph{Standard}:
3484 Fortran 77 and later
3489 @item @emph{Syntax}:
3490 @code{RESULT = DBLE(A)}
3492 @item @emph{Arguments}:
3493 @multitable @columnfractions .15 .70
3494 @item @var{A} @tab The type shall be @code{INTEGER}, @code{REAL},
3498 @item @emph{Return value}:
3499 The return value is of type double precision real.
3501 @item @emph{Example}:
3506 complex :: z = (2.3,1.14)
3507 print *, dble(x), dble(i), dble(z)
3508 end program test_dble
3511 @item @emph{See also}:
3518 @section @code{DCMPLX} --- Double complex conversion function
3520 @cindex complex numbers, conversion to
3521 @cindex conversion, to complex
3524 @item @emph{Description}:
3525 @code{DCMPLX(X [,Y])} returns a double complex number where @var{X} is
3526 converted to the real component. If @var{Y} is present it is converted to the
3527 imaginary component. If @var{Y} is not present then the imaginary component is
3528 set to 0.0. If @var{X} is complex then @var{Y} must not be present.
3530 @item @emph{Standard}:
3536 @item @emph{Syntax}:
3537 @code{RESULT = DCMPLX(X [, Y])}
3539 @item @emph{Arguments}:
3540 @multitable @columnfractions .15 .70
3541 @item @var{X} @tab The type may be @code{INTEGER}, @code{REAL},
3543 @item @var{Y} @tab (Optional if @var{X} is not @code{COMPLEX}.) May be
3544 @code{INTEGER} or @code{REAL}.
3547 @item @emph{Return value}:
3548 The return value is of type @code{COMPLEX(8)}
3550 @item @emph{Example}:
3560 print *, dcmplx(x,i)
3561 end program test_dcmplx
3567 @section @code{DIGITS} --- Significant binary digits function
3569 @cindex model representation, significant digits
3572 @item @emph{Description}:
3573 @code{DIGITS(X)} returns the number of significant binary digits of the internal
3574 model representation of @var{X}. For example, on a system using a 32-bit
3575 floating point representation, a default real number would likely return 24.
3577 @item @emph{Standard}:
3578 Fortran 95 and later
3583 @item @emph{Syntax}:
3584 @code{RESULT = DIGITS(X)}
3586 @item @emph{Arguments}:
3587 @multitable @columnfractions .15 .70
3588 @item @var{X} @tab The type may be @code{INTEGER} or @code{REAL}.
3591 @item @emph{Return value}:
3592 The return value is of type @code{INTEGER}.
3594 @item @emph{Example}:
3597 integer :: i = 12345
3603 end program test_digits
3610 @section @code{DIM} --- Positive difference
3614 @cindex positive difference
3617 @item @emph{Description}:
3618 @code{DIM(X,Y)} returns the difference @code{X-Y} if the result is positive;
3619 otherwise returns zero.
3621 @item @emph{Standard}:
3622 Fortran 77 and later
3627 @item @emph{Syntax}:
3628 @code{RESULT = DIM(X, Y)}
3630 @item @emph{Arguments}:
3631 @multitable @columnfractions .15 .70
3632 @item @var{X} @tab The type shall be @code{INTEGER} or @code{REAL}
3633 @item @var{Y} @tab The type shall be the same type and kind as @var{X}.
3636 @item @emph{Return value}:
3637 The return value is of type @code{INTEGER} or @code{REAL}.
3639 @item @emph{Example}:
3645 x = dim(4.345_8, 2.111_8)
3648 end program test_dim
3651 @item @emph{Specific names}:
3652 @multitable @columnfractions .20 .20 .20 .25
3653 @item Name @tab Argument @tab Return type @tab Standard
3654 @item @code{DIM(X,Y)} @tab @code{REAL(4) X, Y} @tab @code{REAL(4)} @tab Fortran 77 and later
3655 @item @code{IDIM(X,Y)} @tab @code{INTEGER(4) X, Y} @tab @code{INTEGER(4)} @tab Fortran 77 and later
3656 @item @code{DDIM(X,Y)} @tab @code{REAL(8) X, Y} @tab @code{REAL(8)} @tab Fortran 77 and later
3663 @section @code{DOT_PRODUCT} --- Dot product function
3664 @fnindex DOT_PRODUCT
3666 @cindex vector product
3667 @cindex product, vector
3670 @item @emph{Description}:
3671 @code{DOT_PRODUCT(VECTOR_A, VECTOR_B)} computes the dot product multiplication
3672 of two vectors @var{VECTOR_A} and @var{VECTOR_B}. The two vectors may be
3673 either numeric or logical and must be arrays of rank one and of equal size. If
3674 the vectors are @code{INTEGER} or @code{REAL}, the result is
3675 @code{SUM(VECTOR_A*VECTOR_B)}. If the vectors are @code{COMPLEX}, the result
3676 is @code{SUM(CONJG(VECTOR_A)*VECTOR_B)}. If the vectors are @code{LOGICAL},
3677 the result is @code{ANY(VECTOR_A .AND. VECTOR_B)}.
3679 @item @emph{Standard}:
3680 Fortran 95 and later
3683 Transformational function
3685 @item @emph{Syntax}:
3686 @code{RESULT = DOT_PRODUCT(VECTOR_A, VECTOR_B)}
3688 @item @emph{Arguments}:
3689 @multitable @columnfractions .15 .70
3690 @item @var{VECTOR_A} @tab The type shall be numeric or @code{LOGICAL}, rank 1.
3691 @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.
3694 @item @emph{Return value}:
3695 If the arguments are numeric, the return value is a scalar of numeric type,
3696 @code{INTEGER}, @code{REAL}, or @code{COMPLEX}. If the arguments are
3697 @code{LOGICAL}, the return value is @code{.TRUE.} or @code{.FALSE.}.
3699 @item @emph{Example}:
3701 program test_dot_prod
3702 integer, dimension(3) :: a, b
3709 print *, dot_product(a,b)
3710 end program test_dot_prod
3717 @section @code{DPROD} --- Double product function
3719 @cindex product, double-precision
3722 @item @emph{Description}:
3723 @code{DPROD(X,Y)} returns the product @code{X*Y}.
3725 @item @emph{Standard}:
3726 Fortran 77 and later
3731 @item @emph{Syntax}:
3732 @code{RESULT = DPROD(X, Y)}
3734 @item @emph{Arguments}:
3735 @multitable @columnfractions .15 .70
3736 @item @var{X} @tab The type shall be @code{REAL}.
3737 @item @var{Y} @tab The type shall be @code{REAL}.
3740 @item @emph{Return value}:
3741 The return value is of type @code{REAL(8)}.
3743 @item @emph{Example}:
3751 end program test_dprod
3754 @item @emph{Specific names}:
3755 @multitable @columnfractions .20 .20 .20 .25
3756 @item Name @tab Argument @tab Return type @tab Standard
3757 @item @code{DPROD(X,Y)} @tab @code{REAL(4) X, Y} @tab @code{REAL(4)} @tab Fortran 77 and later
3764 @section @code{DREAL} --- Double real part function
3766 @cindex complex numbers, real part
3769 @item @emph{Description}:
3770 @code{DREAL(Z)} returns the real part of complex variable @var{Z}.
3772 @item @emph{Standard}:
3778 @item @emph{Syntax}:
3779 @code{RESULT = DREAL(A)}
3781 @item @emph{Arguments}:
3782 @multitable @columnfractions .15 .70
3783 @item @var{A} @tab The type shall be @code{COMPLEX(8)}.
3786 @item @emph{Return value}:
3787 The return value is of type @code{REAL(8)}.
3789 @item @emph{Example}:
3792 complex(8) :: z = (1.3_8,7.2_8)
3794 end program test_dreal
3797 @item @emph{See also}:
3805 @section @code{DSHIFTL} --- Combined left shift
3807 @cindex left shift, combined
3811 @item @emph{Description}:
3812 @code{DSHIFTL(I, J, SHIFT)} combines bits of @var{I} and @var{J}. The
3813 rightmost @var{SHIFT} bits of the result are the leftmost @var{SHIFT}
3814 bits of @var{J}, and the remaining bits are the rightmost bits of
3817 @item @emph{Standard}:
3818 Fortran 2008 and later
3823 @item @emph{Syntax}:
3824 @code{RESULT = DSHIFTL(I, J, SHIFT)}
3826 @item @emph{Arguments}:
3827 @multitable @columnfractions .15 .70
3828 @item @var{I} @tab Shall be of type @code{INTEGER} or a BOZ constant.
3829 @item @var{J} @tab Shall be of type @code{INTEGER} or a BOZ constant.
3830 If both @var{I} and @var{J} have integer type, then they shall have
3831 the same kind type parameter. @var{I} and @var{J} shall not both be
3833 @item @var{SHIFT} @tab Shall be of type @code{INTEGER}. It shall
3834 be nonnegative. If @var{I} is not a BOZ constant, then @var{SHIFT}
3835 shall be less than or equal to @code{BIT_SIZE(I)}; otherwise,
3836 @var{SHIFT} shall be less than or equal to @code{BIT_SIZE(J)}.
3839 @item @emph{Return value}:
3840 If either @var{I} or @var{J} is a BOZ constant, it is first converted
3841 as if by the intrinsic function @code{INT} to an integer type with the
3842 kind type parameter of the other.
3844 @item @emph{See also}:
3850 @section @code{DSHIFTR} --- Combined right shift
3852 @cindex right shift, combined
3853 @cindex shift, right
3856 @item @emph{Description}:
3857 @code{DSHIFTR(I, J, SHIFT)} combines bits of @var{I} and @var{J}. The
3858 leftmost @var{SHIFT} bits of the result are the rightmost @var{SHIFT}
3859 bits of @var{I}, and the remaining bits are the leftmost bits of
3862 @item @emph{Standard}:
3863 Fortran 2008 and later
3868 @item @emph{Syntax}:
3869 @code{RESULT = DSHIFTR(I, J, SHIFT)}
3871 @item @emph{Arguments}:
3872 @multitable @columnfractions .15 .70
3873 @item @var{I} @tab Shall be of type @code{INTEGER} or a BOZ constant.
3874 @item @var{J} @tab Shall be of type @code{INTEGER} or a BOZ constant.
3875 If both @var{I} and @var{J} have integer type, then they shall have
3876 the same kind type parameter. @var{I} and @var{J} shall not both be
3878 @item @var{SHIFT} @tab Shall be of type @code{INTEGER}. It shall
3879 be nonnegative. If @var{I} is not a BOZ constant, then @var{SHIFT}
3880 shall be less than or equal to @code{BIT_SIZE(I)}; otherwise,
3881 @var{SHIFT} shall be less than or equal to @code{BIT_SIZE(J)}.
3884 @item @emph{Return value}:
3885 If either @var{I} or @var{J} is a BOZ constant, it is first converted
3886 as if by the intrinsic function @code{INT} to an integer type with the
3887 kind type parameter of the other.
3889 @item @emph{See also}:
3895 @section @code{DTIME} --- Execution time subroutine (or function)
3897 @cindex time, elapsed
3898 @cindex elapsed time
3901 @item @emph{Description}:
3902 @code{DTIME(VALUES, TIME)} initially returns the number of seconds of runtime
3903 since the start of the process's execution in @var{TIME}. @var{VALUES}
3904 returns the user and system components of this time in @code{VALUES(1)} and
3905 @code{VALUES(2)} respectively. @var{TIME} is equal to @code{VALUES(1) +
3908 Subsequent invocations of @code{DTIME} return values accumulated since the
3909 previous invocation.
3911 On some systems, the underlying timings are represented using types with
3912 sufficiently small limits that overflows (wrap around) are possible, such as
3913 32-bit types. Therefore, the values returned by this intrinsic might be, or
3914 become, negative, or numerically less than previous values, during a single
3915 run of the compiled program.
3917 Please note, that this implementation is thread safe if used within OpenMP
3918 directives, i.e., its state will be consistent while called from multiple
3919 threads. However, if @code{DTIME} is called from multiple threads, the result
3920 is still the time since the last invocation. This may not give the intended
3921 results. If possible, use @code{CPU_TIME} instead.
3923 This intrinsic is provided in both subroutine and function forms; however,
3924 only one form can be used in any given program unit.
3926 @var{VALUES} and @var{TIME} are @code{INTENT(OUT)} and provide the following:
3928 @multitable @columnfractions .15 .30 .40
3929 @item @tab @code{VALUES(1)}: @tab User time in seconds.
3930 @item @tab @code{VALUES(2)}: @tab System time in seconds.
3931 @item @tab @code{TIME}: @tab Run time since start in seconds.
3934 @item @emph{Standard}:
3938 Subroutine, function
3940 @item @emph{Syntax}:
3941 @multitable @columnfractions .80
3942 @item @code{CALL DTIME(VALUES, TIME)}.
3943 @item @code{TIME = DTIME(VALUES)}, (not recommended).
3946 @item @emph{Arguments}:
3947 @multitable @columnfractions .15 .70
3948 @item @var{VALUES}@tab The type shall be @code{REAL(4), DIMENSION(2)}.
3949 @item @var{TIME}@tab The type shall be @code{REAL(4)}.
3952 @item @emph{Return value}:
3953 Elapsed time in seconds since the last invocation or since the start of program
3954 execution if not called before.
3956 @item @emph{Example}:
3960 real, dimension(2) :: tarray
3962 call dtime(tarray, result)
3966 do i=1,100000000 ! Just a delay
3969 call dtime(tarray, result)
3973 end program test_dtime
3976 @item @emph{See also}:
3984 @section @code{EOSHIFT} --- End-off shift elements of an array
3986 @cindex array, shift
3989 @item @emph{Description}:
3990 @code{EOSHIFT(ARRAY, SHIFT[, BOUNDARY, DIM])} performs an end-off shift on
3991 elements of @var{ARRAY} along the dimension of @var{DIM}. If @var{DIM} is
3992 omitted it is taken to be @code{1}. @var{DIM} is a scalar of type
3993 @code{INTEGER} in the range of @math{1 \leq DIM \leq n)} where @math{n} is the
3994 rank of @var{ARRAY}. If the rank of @var{ARRAY} is one, then all elements of
3995 @var{ARRAY} are shifted by @var{SHIFT} places. If rank is greater than one,
3996 then all complete rank one sections of @var{ARRAY} along the given dimension are
3997 shifted. Elements shifted out one end of each rank one section are dropped. If
3998 @var{BOUNDARY} is present then the corresponding value of from @var{BOUNDARY}
3999 is copied back in the other end. If @var{BOUNDARY} is not present then the
4000 following are copied in depending on the type of @var{ARRAY}.
4002 @multitable @columnfractions .15 .80
4003 @item @emph{Array Type} @tab @emph{Boundary Value}
4004 @item Numeric @tab 0 of the type and kind of @var{ARRAY}.
4005 @item Logical @tab @code{.FALSE.}.
4006 @item Character(@var{len}) @tab @var{len} blanks.
4009 @item @emph{Standard}:
4010 Fortran 95 and later
4013 Transformational function
4015 @item @emph{Syntax}:
4016 @code{RESULT = EOSHIFT(ARRAY, SHIFT [, BOUNDARY, DIM])}
4018 @item @emph{Arguments}:
4019 @multitable @columnfractions .15 .70
4020 @item @var{ARRAY} @tab May be any type, not scalar.
4021 @item @var{SHIFT} @tab The type shall be @code{INTEGER}.
4022 @item @var{BOUNDARY} @tab Same type as @var{ARRAY}.
4023 @item @var{DIM} @tab The type shall be @code{INTEGER}.
4026 @item @emph{Return value}:
4027 Returns an array of same type and rank as the @var{ARRAY} argument.
4029 @item @emph{Example}:
4031 program test_eoshift
4032 integer, dimension(3,3) :: a
4033 a = reshape( (/ 1, 2, 3, 4, 5, 6, 7, 8, 9 /), (/ 3, 3 /))
4034 print '(3i3)', a(1,:)
4035 print '(3i3)', a(2,:)
4036 print '(3i3)', a(3,:)
4037 a = EOSHIFT(a, SHIFT=(/1, 2, 1/), BOUNDARY=-5, DIM=2)
4039 print '(3i3)', a(1,:)
4040 print '(3i3)', a(2,:)
4041 print '(3i3)', a(3,:)
4042 end program test_eoshift
4049 @section @code{EPSILON} --- Epsilon function
4051 @cindex model representation, epsilon
4054 @item @emph{Description}:
4055 @code{EPSILON(X)} returns the smallest number @var{E} of the same kind
4056 as @var{X} such that @math{1 + E > 1}.
4058 @item @emph{Standard}:
4059 Fortran 95 and later
4064 @item @emph{Syntax}:
4065 @code{RESULT = EPSILON(X)}
4067 @item @emph{Arguments}:
4068 @multitable @columnfractions .15 .70
4069 @item @var{X} @tab The type shall be @code{REAL}.
4072 @item @emph{Return value}:
4073 The return value is of same type as the argument.
4075 @item @emph{Example}:
4077 program test_epsilon
4082 end program test_epsilon
4089 @section @code{ERF} --- Error function
4091 @cindex error function
4094 @item @emph{Description}:
4095 @code{ERF(X)} computes the error function of @var{X}.
4097 @item @emph{Standard}:
4098 Fortran 2008 and later
4103 @item @emph{Syntax}:
4104 @code{RESULT = ERF(X)}
4106 @item @emph{Arguments}:
4107 @multitable @columnfractions .15 .70
4108 @item @var{X} @tab The type shall be @code{REAL}.
4111 @item @emph{Return value}:
4112 The return value is of type @code{REAL}, of the same kind as
4113 @var{X} and lies in the range @math{-1 \leq erf (x) \leq 1 }.
4115 @item @emph{Example}:
4118 real(8) :: x = 0.17_8
4120 end program test_erf
4123 @item @emph{Specific names}:
4124 @multitable @columnfractions .20 .20 .20 .25
4125 @item Name @tab Argument @tab Return type @tab Standard
4126 @item @code{DERF(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU extension
4133 @section @code{ERFC} --- Error function
4135 @cindex error function, complementary
4138 @item @emph{Description}:
4139 @code{ERFC(X)} computes the complementary error function of @var{X}.
4141 @item @emph{Standard}:
4142 Fortran 2008 and later
4147 @item @emph{Syntax}:
4148 @code{RESULT = ERFC(X)}
4150 @item @emph{Arguments}:
4151 @multitable @columnfractions .15 .70
4152 @item @var{X} @tab The type shall be @code{REAL}.
4155 @item @emph{Return value}:
4156 The return value is of type @code{REAL} and of the same kind as @var{X}.
4157 It lies in the range @math{ 0 \leq erfc (x) \leq 2 }.
4159 @item @emph{Example}:
4162 real(8) :: x = 0.17_8
4164 end program test_erfc
4167 @item @emph{Specific names}:
4168 @multitable @columnfractions .20 .20 .20 .25
4169 @item Name @tab Argument @tab Return type @tab Standard
4170 @item @code{DERFC(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU extension
4177 @section @code{ERFC_SCALED} --- Error function
4178 @fnindex ERFC_SCALED
4179 @cindex error function, complementary, exponentially-scaled
4182 @item @emph{Description}:
4183 @code{ERFC_SCALED(X)} computes the exponentially-scaled complementary
4184 error function of @var{X}.
4186 @item @emph{Standard}:
4187 Fortran 2008 and later
4192 @item @emph{Syntax}:
4193 @code{RESULT = ERFC_SCALED(X)}
4195 @item @emph{Arguments}:
4196 @multitable @columnfractions .15 .70
4197 @item @var{X} @tab The type shall be @code{REAL}.
4200 @item @emph{Return value}:
4201 The return value is of type @code{REAL} and of the same kind as @var{X}.
4203 @item @emph{Example}:
4205 program test_erfc_scaled
4206 real(8) :: x = 0.17_8
4208 end program test_erfc_scaled
4215 @section @code{ETIME} --- Execution time subroutine (or function)
4217 @cindex time, elapsed
4220 @item @emph{Description}:
4221 @code{ETIME(VALUES, TIME)} returns the number of seconds of runtime
4222 since the start of the process's execution in @var{TIME}. @var{VALUES}
4223 returns the user and system components of this time in @code{VALUES(1)} and
4224 @code{VALUES(2)} respectively. @var{TIME} is equal to @code{VALUES(1) + VALUES(2)}.
4226 On some systems, the underlying timings are represented using types with
4227 sufficiently small limits that overflows (wrap around) are possible, such as
4228 32-bit types. Therefore, the values returned by this intrinsic might be, or
4229 become, negative, or numerically less than previous values, during a single
4230 run of the compiled program.
4232 This intrinsic is provided in both subroutine and function forms; however,
4233 only one form can be used in any given program unit.
4235 @var{VALUES} and @var{TIME} are @code{INTENT(OUT)} and provide the following:
4237 @multitable @columnfractions .15 .30 .60
4238 @item @tab @code{VALUES(1)}: @tab User time in seconds.
4239 @item @tab @code{VALUES(2)}: @tab System time in seconds.
4240 @item @tab @code{TIME}: @tab Run time since start in seconds.
4243 @item @emph{Standard}:
4247 Subroutine, function
4249 @item @emph{Syntax}:
4250 @multitable @columnfractions .80
4251 @item @code{CALL ETIME(VALUES, TIME)}.
4252 @item @code{TIME = ETIME(VALUES)}, (not recommended).
4255 @item @emph{Arguments}:
4256 @multitable @columnfractions .15 .70
4257 @item @var{VALUES}@tab The type shall be @code{REAL(4), DIMENSION(2)}.
4258 @item @var{TIME}@tab The type shall be @code{REAL(4)}.
4261 @item @emph{Return value}:
4262 Elapsed time in seconds since the start of program execution.
4264 @item @emph{Example}:
4268 real, dimension(2) :: tarray
4270 call ETIME(tarray, result)
4274 do i=1,100000000 ! Just a delay
4277 call ETIME(tarray, result)
4281 end program test_etime
4284 @item @emph{See also}:
4291 @node EXECUTE_COMMAND_LINE
4292 @section @code{EXECUTE_COMMAND_LINE} --- Execute a shell command
4293 @fnindex EXECUTE_COMMAND_LINE
4294 @cindex system, system call
4295 @cindex command line
4298 @item @emph{Description}:
4299 @code{EXECUTE_COMMAND_LINE} runs a shell command, synchronously or
4302 The @code{COMMAND} argument is passed to the shell and executed, using
4303 the C library's @code{system} call. (The shell is @code{sh} on Unix
4304 systems, and @code{cmd.exe} on Windows.) If @code{WAIT} is present
4305 and has the value false, the execution of the command is asynchronous
4306 if the system supports it; otherwise, the command is executed
4309 The three last arguments allow the user to get status information. After
4310 synchronous execution, @code{EXITSTAT} contains the integer exit code of
4311 the command, as returned by @code{system}. @code{CMDSTAT} is set to zero
4312 if the command line was executed (whatever its exit status was).
4313 @code{CMDMSG} is assigned an error message if an error has occurred.
4315 Note that the @code{system} function need not be thread-safe. It is
4316 the responsibility of the user to ensure that @code{system} is not
4317 called concurrently.
4319 @item @emph{Standard}:
4320 Fortran 2008 and later
4325 @item @emph{Syntax}:
4326 @code{CALL EXECUTE_COMMAND_LINE(COMMAND [, WAIT, EXITSTAT, CMDSTAT, CMDMSG ])}
4328 @item @emph{Arguments}:
4329 @multitable @columnfractions .15 .70
4330 @item @var{COMMAND} @tab Shall be a default @code{CHARACTER} scalar.
4331 @item @var{WAIT} @tab (Optional) Shall be a default @code{LOGICAL} scalar.
4332 @item @var{EXITSTAT} @tab (Optional) Shall be an @code{INTEGER} of the
4334 @item @var{CMDSTAT} @tab (Optional) Shall be an @code{INTEGER} of the
4336 @item @var{CMDMSG} @tab (Optional) Shall be an @code{CHARACTER} scalar of the
4340 @item @emph{Example}:
4345 call execute_command_line ("external_prog.exe", exitstat=i)
4346 print *, "Exit status of external_prog.exe was ", i
4348 call execute_command_line ("reindex_files.exe", wait=.false.)
4349 print *, "Now reindexing files in the background"
4351 end program test_exec
4357 Because this intrinsic is implemented in terms of the @code{system}
4358 function call, its behavior with respect to signaling is processor
4359 dependent. In particular, on POSIX-compliant systems, the SIGINT and
4360 SIGQUIT signals will be ignored, and the SIGCHLD will be blocked. As
4361 such, if the parent process is terminated, the child process might not be
4362 terminated alongside.
4365 @item @emph{See also}:
4372 @section @code{EXIT} --- Exit the program with status.
4374 @cindex program termination
4375 @cindex terminate program
4378 @item @emph{Description}:
4379 @code{EXIT} causes immediate termination of the program with status. If status
4380 is omitted it returns the canonical @emph{success} for the system. All Fortran
4381 I/O units are closed.
4383 @item @emph{Standard}:
4389 @item @emph{Syntax}:
4390 @code{CALL EXIT([STATUS])}
4392 @item @emph{Arguments}:
4393 @multitable @columnfractions .15 .70
4394 @item @var{STATUS} @tab Shall be an @code{INTEGER} of the default kind.
4397 @item @emph{Return value}:
4398 @code{STATUS} is passed to the parent process on exit.
4400 @item @emph{Example}:
4403 integer :: STATUS = 0
4404 print *, 'This program is going to exit.'
4406 end program test_exit
4409 @item @emph{See also}:
4410 @ref{ABORT}, @ref{KILL}
4416 @section @code{EXP} --- Exponential function
4422 @cindex exponential function
4423 @cindex logarithm function, inverse
4426 @item @emph{Description}:
4427 @code{EXP(X)} computes the base @math{e} exponential of @var{X}.
4429 @item @emph{Standard}:
4430 Fortran 77 and later, has overloads that are GNU extensions
4435 @item @emph{Syntax}:
4436 @code{RESULT = EXP(X)}
4438 @item @emph{Arguments}:
4439 @multitable @columnfractions .15 .70
4440 @item @var{X} @tab The type shall be @code{REAL} or
4444 @item @emph{Return value}:
4445 The return value has same type and kind as @var{X}.
4447 @item @emph{Example}:
4452 end program test_exp
4455 @item @emph{Specific names}:
4456 @multitable @columnfractions .20 .20 .20 .25
4457 @item Name @tab Argument @tab Return type @tab Standard
4458 @item @code{EXP(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab Fortran 77 and later
4459 @item @code{DEXP(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab Fortran 77 and later
4460 @item @code{CEXP(X)} @tab @code{COMPLEX(4) X} @tab @code{COMPLEX(4)} @tab Fortran 77 and later
4461 @item @code{ZEXP(X)} @tab @code{COMPLEX(8) X} @tab @code{COMPLEX(8)} @tab GNU extension
4462 @item @code{CDEXP(X)} @tab @code{COMPLEX(8) X} @tab @code{COMPLEX(8)} @tab GNU extension
4469 @section @code{EXPONENT} --- Exponent function
4471 @cindex real number, exponent
4472 @cindex floating point, exponent
4475 @item @emph{Description}:
4476 @code{EXPONENT(X)} returns the value of the exponent part of @var{X}. If @var{X}
4477 is zero the value returned is zero.
4479 @item @emph{Standard}:
4480 Fortran 95 and later
4485 @item @emph{Syntax}:
4486 @code{RESULT = EXPONENT(X)}
4488 @item @emph{Arguments}:
4489 @multitable @columnfractions .15 .70
4490 @item @var{X} @tab The type shall be @code{REAL}.
4493 @item @emph{Return value}:
4494 The return value is of type default @code{INTEGER}.
4496 @item @emph{Example}:
4498 program test_exponent
4503 print *, exponent(0.0)
4504 end program test_exponent
4510 @node EXTENDS_TYPE_OF
4511 @section @code{EXTENDS_TYPE_OF} --- Query dynamic type for extension
4512 @fnindex EXTENDS_TYPE_OF
4515 @item @emph{Description}:
4516 Query dynamic type for extension.
4518 @item @emph{Standard}:
4519 Fortran 2003 and later
4524 @item @emph{Syntax}:
4525 @code{RESULT = EXTENDS_TYPE_OF(A, MOLD)}
4527 @item @emph{Arguments}:
4528 @multitable @columnfractions .15 .70
4529 @item @var{A} @tab Shall be an object of extensible declared type or
4530 unlimited polymorphic.
4531 @item @var{MOLD} @tab Shall be an object of extensible declared type or
4532 unlimited polymorphic.
4535 @item @emph{Return value}:
4536 The return value is a scalar of type default logical. It is true if and only if
4537 the dynamic type of A is an extension type of the dynamic type of MOLD.
4540 @item @emph{See also}:
4547 @section @code{FDATE} --- Get the current time as a string
4549 @cindex time, current
4550 @cindex current time
4551 @cindex date, current
4552 @cindex current date
4555 @item @emph{Description}:
4556 @code{FDATE(DATE)} returns the current date (using the same format as
4557 @code{CTIME}) in @var{DATE}. It is equivalent to @code{CALL CTIME(DATE,
4560 This intrinsic is provided in both subroutine and function forms; however,
4561 only one form can be used in any given program unit.
4563 @item @emph{Standard}:
4567 Subroutine, function
4569 @item @emph{Syntax}:
4570 @multitable @columnfractions .80
4571 @item @code{CALL FDATE(DATE)}.
4572 @item @code{DATE = FDATE()}.
4575 @item @emph{Arguments}:
4576 @multitable @columnfractions .15 .70
4577 @item @var{DATE}@tab The type shall be of type @code{CHARACTER} of the
4578 default kind. It is an @code{INTENT(OUT)} argument. If the length of
4579 this variable is too short for the date and time string to fit
4580 completely, it will be blank on procedure return.
4583 @item @emph{Return value}:
4584 The current date and time as a string.
4586 @item @emph{Example}:
4590 character(len=30) :: date
4592 print *, 'Program started on ', date
4593 do i = 1, 100000000 ! Just a delay
4597 print *, 'Program ended on ', date
4598 end program test_fdate
4601 @item @emph{See also}:
4602 @ref{DATE_AND_TIME}, @ref{CTIME}
4607 @section @code{FGET} --- Read a single character in stream mode from stdin
4609 @cindex read character, stream mode
4610 @cindex stream mode, read character
4611 @cindex file operation, read character
4614 @item @emph{Description}:
4615 Read a single character in stream mode from stdin by bypassing normal
4616 formatted output. Stream I/O should not be mixed with normal record-oriented
4617 (formatted or unformatted) I/O on the same unit; the results are unpredictable.
4619 This intrinsic is provided in both subroutine and function forms; however,
4620 only one form can be used in any given program unit.
4622 Note that the @code{FGET} intrinsic is provided for backwards compatibility with
4623 @command{g77}. GNU Fortran provides the Fortran 2003 Stream facility.
4624 Programmers should consider the use of new stream IO feature in new code
4625 for future portability. See also @ref{Fortran 2003 status}.
4627 @item @emph{Standard}:
4631 Subroutine, function
4633 @item @emph{Syntax}:
4634 @multitable @columnfractions .80
4635 @item @code{CALL FGET(C [, STATUS])}
4636 @item @code{STATUS = FGET(C)}
4639 @item @emph{Arguments}:
4640 @multitable @columnfractions .15 .70
4641 @item @var{C} @tab The type shall be @code{CHARACTER} and of default
4643 @item @var{STATUS} @tab (Optional) status flag of type @code{INTEGER}.
4644 Returns 0 on success, -1 on end-of-file, and a system specific positive
4645 error code otherwise.
4648 @item @emph{Example}:
4651 INTEGER, PARAMETER :: strlen = 100
4652 INTEGER :: status, i = 1
4653 CHARACTER(len=strlen) :: str = ""
4655 WRITE (*,*) 'Enter text:'
4657 CALL fget(str(i:i), status)
4658 if (status /= 0 .OR. i > strlen) exit
4661 WRITE (*,*) TRIM(str)
4665 @item @emph{See also}:
4666 @ref{FGETC}, @ref{FPUT}, @ref{FPUTC}
4672 @section @code{FGETC} --- Read a single character in stream mode
4674 @cindex read character, stream mode
4675 @cindex stream mode, read character
4676 @cindex file operation, read character
4679 @item @emph{Description}:
4680 Read a single character in stream mode by bypassing normal formatted output.
4681 Stream I/O should not be mixed with normal record-oriented (formatted or
4682 unformatted) I/O on the same unit; the results are unpredictable.
4684 This intrinsic is provided in both subroutine and function forms; however,
4685 only one form can be used in any given program unit.
4687 Note that the @code{FGET} intrinsic is provided for backwards compatibility
4688 with @command{g77}. GNU Fortran provides the Fortran 2003 Stream facility.
4689 Programmers should consider the use of new stream IO feature in new code
4690 for future portability. See also @ref{Fortran 2003 status}.
4692 @item @emph{Standard}:
4696 Subroutine, function
4698 @item @emph{Syntax}:
4699 @multitable @columnfractions .80
4700 @item @code{CALL FGETC(UNIT, C [, STATUS])}
4701 @item @code{STATUS = FGETC(UNIT, C)}
4704 @item @emph{Arguments}:
4705 @multitable @columnfractions .15 .70
4706 @item @var{UNIT} @tab The type shall be @code{INTEGER}.
4707 @item @var{C} @tab The type shall be @code{CHARACTER} and of default
4709 @item @var{STATUS} @tab (Optional) status flag of type @code{INTEGER}.
4710 Returns 0 on success, -1 on end-of-file and a system specific positive
4711 error code otherwise.
4714 @item @emph{Example}:
4717 INTEGER :: fd = 42, status
4720 OPEN(UNIT=fd, FILE="/etc/passwd", ACTION="READ", STATUS = "OLD")
4722 CALL fgetc(fd, c, status)
4723 IF (status /= 0) EXIT
4730 @item @emph{See also}:
4731 @ref{FGET}, @ref{FPUT}, @ref{FPUTC}
4737 @section @code{FLOOR} --- Integer floor function
4740 @cindex rounding, floor
4743 @item @emph{Description}:
4744 @code{FLOOR(A)} returns the greatest integer less than or equal to @var{X}.
4746 @item @emph{Standard}:
4747 Fortran 95 and later
4752 @item @emph{Syntax}:
4753 @code{RESULT = FLOOR(A [, KIND])}
4755 @item @emph{Arguments}:
4756 @multitable @columnfractions .15 .70
4757 @item @var{A} @tab The type shall be @code{REAL}.
4758 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
4759 expression indicating the kind parameter of the result.
4762 @item @emph{Return value}:
4763 The return value is of type @code{INTEGER(KIND)} if @var{KIND} is present
4764 and of default-kind @code{INTEGER} otherwise.
4766 @item @emph{Example}:
4771 print *, floor(x) ! returns 63
4772 print *, floor(y) ! returns -64
4773 end program test_floor
4776 @item @emph{See also}:
4777 @ref{CEILING}, @ref{NINT}
4784 @section @code{FLUSH} --- Flush I/O unit(s)
4786 @cindex file operation, flush
4789 @item @emph{Description}:
4790 Flushes Fortran unit(s) currently open for output. Without the optional
4791 argument, all units are flushed, otherwise just the unit specified.
4793 @item @emph{Standard}:
4799 @item @emph{Syntax}:
4800 @code{CALL FLUSH(UNIT)}
4802 @item @emph{Arguments}:
4803 @multitable @columnfractions .15 .70
4804 @item @var{UNIT} @tab (Optional) The type shall be @code{INTEGER}.
4808 Beginning with the Fortran 2003 standard, there is a @code{FLUSH}
4809 statement that should be preferred over the @code{FLUSH} intrinsic.
4811 The @code{FLUSH} intrinsic and the Fortran 2003 @code{FLUSH} statement
4812 have identical effect: they flush the runtime library's I/O buffer so
4813 that the data becomes visible to other processes. This does not guarantee
4814 that the data is committed to disk.
4816 On POSIX systems, you can request that all data is transferred to the
4817 storage device by calling the @code{fsync} function, with the POSIX file
4818 descriptor of the I/O unit as argument (retrieved with GNU intrinsic
4819 @code{FNUM}). The following example shows how:
4822 ! Declare the interface for POSIX fsync function
4824 function fsync (fd) bind(c,name="fsync")
4825 use iso_c_binding, only: c_int
4826 integer(c_int), value :: fd
4827 integer(c_int) :: fsync
4831 ! Variable declaration
4835 open (10,file="foo")
4838 ! Perform I/O on unit 10
4843 ret = fsync(fnum(10))
4845 ! Handle possible error
4846 if (ret /= 0) stop "Error calling FSYNC"
4854 @section @code{FNUM} --- File number function
4856 @cindex file operation, file number
4859 @item @emph{Description}:
4860 @code{FNUM(UNIT)} returns the POSIX file descriptor number corresponding to the
4861 open Fortran I/O unit @code{UNIT}.
4863 @item @emph{Standard}:
4869 @item @emph{Syntax}:
4870 @code{RESULT = FNUM(UNIT)}
4872 @item @emph{Arguments}:
4873 @multitable @columnfractions .15 .70
4874 @item @var{UNIT} @tab The type shall be @code{INTEGER}.
4877 @item @emph{Return value}:
4878 The return value is of type @code{INTEGER}
4880 @item @emph{Example}:
4884 open (unit=10, status = "scratch")
4888 end program test_fnum
4895 @section @code{FPUT} --- Write a single character in stream mode to stdout
4897 @cindex write character, stream mode
4898 @cindex stream mode, write character
4899 @cindex file operation, write character
4902 @item @emph{Description}:
4903 Write a single character in stream mode to stdout by bypassing normal
4904 formatted output. Stream I/O should not be mixed with normal record-oriented
4905 (formatted or unformatted) I/O on the same unit; the results are unpredictable.
4907 This intrinsic is provided in both subroutine and function forms; however,
4908 only one form can be used in any given program unit.
4910 Note that the @code{FGET} intrinsic is provided for backwards compatibility with
4911 @command{g77}. GNU Fortran provides the Fortran 2003 Stream facility.
4912 Programmers should consider the use of new stream IO feature in new code
4913 for future portability. See also @ref{Fortran 2003 status}.
4915 @item @emph{Standard}:
4919 Subroutine, function
4921 @item @emph{Syntax}:
4922 @multitable @columnfractions .80
4923 @item @code{CALL FPUT(C [, STATUS])}
4924 @item @code{STATUS = FPUT(C)}
4927 @item @emph{Arguments}:
4928 @multitable @columnfractions .15 .70
4929 @item @var{C} @tab The type shall be @code{CHARACTER} and of default
4931 @item @var{STATUS} @tab (Optional) status flag of type @code{INTEGER}.
4932 Returns 0 on success, -1 on end-of-file and a system specific positive
4933 error code otherwise.
4936 @item @emph{Example}:
4939 CHARACTER(len=10) :: str = "gfortran"
4941 DO i = 1, len_trim(str)
4947 @item @emph{See also}:
4948 @ref{FPUTC}, @ref{FGET}, @ref{FGETC}
4954 @section @code{FPUTC} --- Write a single character in stream mode
4956 @cindex write character, stream mode
4957 @cindex stream mode, write character
4958 @cindex file operation, write character
4961 @item @emph{Description}:
4962 Write a single character in stream mode by bypassing normal formatted
4963 output. Stream I/O should not be mixed with normal record-oriented
4964 (formatted or unformatted) I/O on the same unit; the results are unpredictable.
4966 This intrinsic is provided in both subroutine and function forms; however,
4967 only one form can be used in any given program unit.
4969 Note that the @code{FGET} intrinsic is provided for backwards compatibility with
4970 @command{g77}. GNU Fortran provides the Fortran 2003 Stream facility.
4971 Programmers should consider the use of new stream IO feature in new code
4972 for future portability. See also @ref{Fortran 2003 status}.
4974 @item @emph{Standard}:
4978 Subroutine, function
4980 @item @emph{Syntax}:
4981 @multitable @columnfractions .80
4982 @item @code{CALL FPUTC(UNIT, C [, STATUS])}
4983 @item @code{STATUS = FPUTC(UNIT, C)}
4986 @item @emph{Arguments}:
4987 @multitable @columnfractions .15 .70
4988 @item @var{UNIT} @tab The type shall be @code{INTEGER}.
4989 @item @var{C} @tab The type shall be @code{CHARACTER} and of default
4991 @item @var{STATUS} @tab (Optional) status flag of type @code{INTEGER}.
4992 Returns 0 on success, -1 on end-of-file and a system specific positive
4993 error code otherwise.
4996 @item @emph{Example}:
4999 CHARACTER(len=10) :: str = "gfortran"
5000 INTEGER :: fd = 42, i
5002 OPEN(UNIT = fd, FILE = "out", ACTION = "WRITE", STATUS="NEW")
5003 DO i = 1, len_trim(str)
5004 CALL fputc(fd, str(i:i))
5010 @item @emph{See also}:
5011 @ref{FPUT}, @ref{FGET}, @ref{FGETC}
5017 @section @code{FRACTION} --- Fractional part of the model representation
5019 @cindex real number, fraction
5020 @cindex floating point, fraction
5023 @item @emph{Description}:
5024 @code{FRACTION(X)} returns the fractional part of the model
5025 representation of @code{X}.
5027 @item @emph{Standard}:
5028 Fortran 95 and later
5033 @item @emph{Syntax}:
5034 @code{Y = FRACTION(X)}
5036 @item @emph{Arguments}:
5037 @multitable @columnfractions .15 .70
5038 @item @var{X} @tab The type of the argument shall be a @code{REAL}.
5041 @item @emph{Return value}:
5042 The return value is of the same type and kind as the argument.
5043 The fractional part of the model representation of @code{X} is returned;
5044 it is @code{X * RADIX(X)**(-EXPONENT(X))}.
5046 @item @emph{Example}:
5048 program test_fraction
5051 print *, fraction(x), x * radix(x)**(-exponent(x))
5052 end program test_fraction
5060 @section @code{FREE} --- Frees memory
5062 @cindex pointer, cray
5065 @item @emph{Description}:
5066 Frees memory previously allocated by @code{MALLOC}. The @code{FREE}
5067 intrinsic is an extension intended to be used with Cray pointers, and is
5068 provided in GNU Fortran to allow user to compile legacy code. For
5069 new code using Fortran 95 pointers, the memory de-allocation intrinsic is
5072 @item @emph{Standard}:
5078 @item @emph{Syntax}:
5079 @code{CALL FREE(PTR)}
5081 @item @emph{Arguments}:
5082 @multitable @columnfractions .15 .70
5083 @item @var{PTR} @tab The type shall be @code{INTEGER}. It represents the
5084 location of the memory that should be de-allocated.
5087 @item @emph{Return value}:
5090 @item @emph{Example}:
5091 See @code{MALLOC} for an example.
5093 @item @emph{See also}:
5100 @section @code{FSEEK} --- Low level file positioning subroutine
5102 @cindex file operation, seek
5103 @cindex file operation, position
5106 @item @emph{Description}:
5107 Moves @var{UNIT} to the specified @var{OFFSET}. If @var{WHENCE}
5108 is set to 0, the @var{OFFSET} is taken as an absolute value @code{SEEK_SET},
5109 if set to 1, @var{OFFSET} is taken to be relative to the current position
5110 @code{SEEK_CUR}, and if set to 2 relative to the end of the file @code{SEEK_END}.
5111 On error, @var{STATUS} is set to a nonzero value. If @var{STATUS} the seek
5114 This intrinsic routine is not fully backwards compatible with @command{g77}.
5115 In @command{g77}, the @code{FSEEK} takes a statement label instead of a
5116 @var{STATUS} variable. If FSEEK is used in old code, change
5118 CALL FSEEK(UNIT, OFFSET, WHENCE, *label)
5123 CALL FSEEK(UNIT, OFFSET, WHENCE, status)
5124 IF (status /= 0) GOTO label
5127 Please note that GNU Fortran provides the Fortran 2003 Stream facility.
5128 Programmers should consider the use of new stream IO feature in new code
5129 for future portability. See also @ref{Fortran 2003 status}.
5131 @item @emph{Standard}:
5137 @item @emph{Syntax}:
5138 @code{CALL FSEEK(UNIT, OFFSET, WHENCE[, STATUS])}
5140 @item @emph{Arguments}:
5141 @multitable @columnfractions .15 .70
5142 @item @var{UNIT} @tab Shall be a scalar of type @code{INTEGER}.
5143 @item @var{OFFSET} @tab Shall be a scalar of type @code{INTEGER}.
5144 @item @var{WHENCE} @tab Shall be a scalar of type @code{INTEGER}.
5145 Its value shall be either 0, 1 or 2.
5146 @item @var{STATUS} @tab (Optional) shall be a scalar of type
5150 @item @emph{Example}:
5153 INTEGER, PARAMETER :: SEEK_SET = 0, SEEK_CUR = 1, SEEK_END = 2
5154 INTEGER :: fd, offset, ierr
5160 OPEN(UNIT=fd, FILE="fseek.test")
5161 CALL FSEEK(fd, offset, SEEK_SET, ierr) ! move to OFFSET
5162 print *, FTELL(fd), ierr
5164 CALL FSEEK(fd, 0, SEEK_END, ierr) ! move to end
5165 print *, FTELL(fd), ierr
5167 CALL FSEEK(fd, 0, SEEK_SET, ierr) ! move to beginning
5168 print *, FTELL(fd), ierr
5174 @item @emph{See also}:
5181 @section @code{FSTAT} --- Get file status
5183 @cindex file system, file status
5186 @item @emph{Description}:
5187 @code{FSTAT} is identical to @ref{STAT}, except that information about an
5188 already opened file is obtained.
5190 The elements in @code{VALUES} are the same as described by @ref{STAT}.
5192 This intrinsic is provided in both subroutine and function forms; however,
5193 only one form can be used in any given program unit.
5195 @item @emph{Standard}:
5199 Subroutine, function
5201 @item @emph{Syntax}:
5202 @multitable @columnfractions .80
5203 @item @code{CALL FSTAT(UNIT, VALUES [, STATUS])}
5204 @item @code{STATUS = FSTAT(UNIT, VALUES)}
5207 @item @emph{Arguments}:
5208 @multitable @columnfractions .15 .70
5209 @item @var{UNIT} @tab An open I/O unit number of type @code{INTEGER}.
5210 @item @var{VALUES} @tab The type shall be @code{INTEGER(4), DIMENSION(13)}.
5211 @item @var{STATUS} @tab (Optional) status flag of type @code{INTEGER(4)}. Returns 0
5212 on success and a system specific error code otherwise.
5215 @item @emph{Example}:
5216 See @ref{STAT} for an example.
5218 @item @emph{See also}:
5219 To stat a link: @ref{LSTAT}, to stat a file: @ref{STAT}
5225 @section @code{FTELL} --- Current stream position
5227 @cindex file operation, position
5230 @item @emph{Description}:
5231 Retrieves the current position within an open file.
5233 This intrinsic is provided in both subroutine and function forms; however,
5234 only one form can be used in any given program unit.
5236 @item @emph{Standard}:
5240 Subroutine, function
5242 @item @emph{Syntax}:
5243 @multitable @columnfractions .80
5244 @item @code{CALL FTELL(UNIT, OFFSET)}
5245 @item @code{OFFSET = FTELL(UNIT)}
5248 @item @emph{Arguments}:
5249 @multitable @columnfractions .15 .70
5250 @item @var{OFFSET} @tab Shall of type @code{INTEGER}.
5251 @item @var{UNIT} @tab Shall of type @code{INTEGER}.
5254 @item @emph{Return value}:
5255 In either syntax, @var{OFFSET} is set to the current offset of unit
5256 number @var{UNIT}, or to @math{-1} if the unit is not currently open.
5258 @item @emph{Example}:
5262 OPEN(10, FILE="temp.dat")
5268 @item @emph{See also}:
5275 @section @code{GAMMA} --- Gamma function
5278 @cindex Gamma function
5279 @cindex Factorial function
5282 @item @emph{Description}:
5283 @code{GAMMA(X)} computes Gamma (@math{\Gamma}) of @var{X}. For positive,
5284 integer values of @var{X} the Gamma function simplifies to the factorial
5285 function @math{\Gamma(x)=(x-1)!}.
5289 \Gamma(x) = \int_0^\infty t^{x-1}{\rm e}^{-t}\,{\rm d}t
5293 @item @emph{Standard}:
5294 Fortran 2008 and later
5299 @item @emph{Syntax}:
5302 @item @emph{Arguments}:
5303 @multitable @columnfractions .15 .70
5304 @item @var{X} @tab Shall be of type @code{REAL} and neither zero
5305 nor a negative integer.
5308 @item @emph{Return value}:
5309 The return value is of type @code{REAL} of the same kind as @var{X}.
5311 @item @emph{Example}:
5315 x = gamma(x) ! returns 1.0
5316 end program test_gamma
5319 @item @emph{Specific names}:
5320 @multitable @columnfractions .20 .20 .20 .25
5321 @item Name @tab Argument @tab Return type @tab Standard
5322 @item @code{GAMMA(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab GNU Extension
5323 @item @code{DGAMMA(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU Extension
5326 @item @emph{See also}:
5327 Logarithm of the Gamma function: @ref{LOG_GAMMA}
5334 @section @code{GERROR} --- Get last system error message
5336 @cindex system, error handling
5339 @item @emph{Description}:
5340 Returns the system error message corresponding to the last system error.
5341 This resembles the functionality of @code{strerror(3)} in C.
5343 @item @emph{Standard}:
5349 @item @emph{Syntax}:
5350 @code{CALL GERROR(RESULT)}
5352 @item @emph{Arguments}:
5353 @multitable @columnfractions .15 .70
5354 @item @var{RESULT} @tab Shall of type @code{CHARACTER} and of default
5357 @item @emph{Example}:
5360 CHARACTER(len=100) :: msg
5366 @item @emph{See also}:
5367 @ref{IERRNO}, @ref{PERROR}
5373 @section @code{GETARG} --- Get command line arguments
5375 @cindex command-line arguments
5376 @cindex arguments, to program
5379 @item @emph{Description}:
5380 Retrieve the @var{POS}-th argument that was passed on the
5381 command line when the containing program was invoked.
5383 This intrinsic routine is provided for backwards compatibility with
5384 GNU Fortran 77. In new code, programmers should consider the use of
5385 the @ref{GET_COMMAND_ARGUMENT} intrinsic defined by the Fortran 2003
5388 @item @emph{Standard}:
5394 @item @emph{Syntax}:
5395 @code{CALL GETARG(POS, VALUE)}
5397 @item @emph{Arguments}:
5398 @multitable @columnfractions .15 .70
5399 @item @var{POS} @tab Shall be of type @code{INTEGER} and not wider than
5400 the default integer kind; @math{@var{POS} \geq 0}
5401 @item @var{VALUE} @tab Shall be of type @code{CHARACTER} and of default
5403 @item @var{VALUE} @tab Shall be of type @code{CHARACTER}.
5406 @item @emph{Return value}:
5407 After @code{GETARG} returns, the @var{VALUE} argument holds the
5408 @var{POS}th command line argument. If @var{VALUE} can not hold the
5409 argument, it is truncated to fit the length of @var{VALUE}. If there are
5410 less than @var{POS} arguments specified at the command line, @var{VALUE}
5411 will be filled with blanks. If @math{@var{POS} = 0}, @var{VALUE} is set
5412 to the name of the program (on systems that support this feature).
5414 @item @emph{Example}:
5418 CHARACTER(len=32) :: arg
5427 @item @emph{See also}:
5428 GNU Fortran 77 compatibility function: @ref{IARGC}
5430 Fortran 2003 functions and subroutines: @ref{GET_COMMAND},
5431 @ref{GET_COMMAND_ARGUMENT}, @ref{COMMAND_ARGUMENT_COUNT}
5437 @section @code{GET_COMMAND} --- Get the entire command line
5438 @fnindex GET_COMMAND
5439 @cindex command-line arguments
5440 @cindex arguments, to program
5443 @item @emph{Description}:
5444 Retrieve the entire command line that was used to invoke the program.
5446 @item @emph{Standard}:
5447 Fortran 2003 and later
5452 @item @emph{Syntax}:
5453 @code{CALL GET_COMMAND([COMMAND, LENGTH, STATUS])}
5455 @item @emph{Arguments}:
5456 @multitable @columnfractions .15 .70
5457 @item @var{COMMAND} @tab (Optional) shall be of type @code{CHARACTER} and
5459 @item @var{LENGTH} @tab (Optional) Shall be of type @code{INTEGER} and of
5461 @item @var{STATUS} @tab (Optional) Shall be of type @code{INTEGER} and of
5465 @item @emph{Return value}:
5466 If @var{COMMAND} is present, stores the entire command line that was used
5467 to invoke the program in @var{COMMAND}. If @var{LENGTH} is present, it is
5468 assigned the length of the command line. If @var{STATUS} is present, it
5469 is assigned 0 upon success of the command, -1 if @var{COMMAND} is too
5470 short to store the command line, or a positive value in case of an error.
5472 @item @emph{Example}:
5474 PROGRAM test_get_command
5475 CHARACTER(len=255) :: cmd
5476 CALL get_command(cmd)
5477 WRITE (*,*) TRIM(cmd)
5481 @item @emph{See also}:
5482 @ref{GET_COMMAND_ARGUMENT}, @ref{COMMAND_ARGUMENT_COUNT}
5487 @node GET_COMMAND_ARGUMENT
5488 @section @code{GET_COMMAND_ARGUMENT} --- Get command line arguments
5489 @fnindex GET_COMMAND_ARGUMENT
5490 @cindex command-line arguments
5491 @cindex arguments, to program
5494 @item @emph{Description}:
5495 Retrieve the @var{NUMBER}-th argument that was passed on the
5496 command line when the containing program was invoked.
5498 @item @emph{Standard}:
5499 Fortran 2003 and later
5504 @item @emph{Syntax}:
5505 @code{CALL GET_COMMAND_ARGUMENT(NUMBER [, VALUE, LENGTH, STATUS])}
5507 @item @emph{Arguments}:
5508 @multitable @columnfractions .15 .70
5509 @item @var{NUMBER} @tab Shall be a scalar of type @code{INTEGER} and of
5510 default kind, @math{@var{NUMBER} \geq 0}
5511 @item @var{VALUE} @tab (Optional) Shall be a scalar of type @code{CHARACTER}
5512 and of default kind.
5513 @item @var{LENGTH} @tab (Optional) Shall be a scalar of type @code{INTEGER}
5514 and of default kind.
5515 @item @var{STATUS} @tab (Optional) Shall be a scalar of type @code{INTEGER}
5516 and of default kind.
5519 @item @emph{Return value}:
5520 After @code{GET_COMMAND_ARGUMENT} returns, the @var{VALUE} argument holds the
5521 @var{NUMBER}-th command line argument. If @var{VALUE} can not hold the argument, it is
5522 truncated to fit the length of @var{VALUE}. If there are less than @var{NUMBER}
5523 arguments specified at the command line, @var{VALUE} will be filled with blanks.
5524 If @math{@var{NUMBER} = 0}, @var{VALUE} is set to the name of the program (on
5525 systems that support this feature). The @var{LENGTH} argument contains the
5526 length of the @var{NUMBER}-th command line argument. If the argument retrieval
5527 fails, @var{STATUS} is a positive number; if @var{VALUE} contains a truncated
5528 command line argument, @var{STATUS} is -1; and otherwise the @var{STATUS} is
5531 @item @emph{Example}:
5533 PROGRAM test_get_command_argument
5535 CHARACTER(len=32) :: arg
5539 CALL get_command_argument(i, arg)
5540 IF (LEN_TRIM(arg) == 0) EXIT
5542 WRITE (*,*) TRIM(arg)
5548 @item @emph{See also}:
5549 @ref{GET_COMMAND}, @ref{COMMAND_ARGUMENT_COUNT}
5555 @section @code{GETCWD} --- Get current working directory
5557 @cindex system, working directory
5560 @item @emph{Description}:
5561 Get current working directory.
5563 This intrinsic is provided in both subroutine and function forms; however,
5564 only one form can be used in any given program unit.
5566 @item @emph{Standard}:
5570 Subroutine, function
5572 @item @emph{Syntax}:
5573 @multitable @columnfractions .80
5574 @item @code{CALL GETCWD(C [, STATUS])}
5575 @item @code{STATUS = GETCWD(C)}
5578 @item @emph{Arguments}:
5579 @multitable @columnfractions .15 .70
5580 @item @var{C} @tab The type shall be @code{CHARACTER} and of default kind.
5581 @item @var{STATUS} @tab (Optional) status flag. Returns 0 on success,
5582 a system specific and nonzero error code otherwise.
5585 @item @emph{Example}:
5588 CHARACTER(len=255) :: cwd
5590 WRITE(*,*) TRIM(cwd)
5594 @item @emph{See also}:
5601 @section @code{GETENV} --- Get an environmental variable
5603 @cindex environment variable
5606 @item @emph{Description}:
5607 Get the @var{VALUE} of the environmental variable @var{NAME}.
5609 This intrinsic routine is provided for backwards compatibility with
5610 GNU Fortran 77. In new code, programmers should consider the use of
5611 the @ref{GET_ENVIRONMENT_VARIABLE} intrinsic defined by the Fortran
5614 Note that @code{GETENV} need not be thread-safe. It is the
5615 responsibility of the user to ensure that the environment is not being
5616 updated concurrently with a call to the @code{GETENV} intrinsic.
5618 @item @emph{Standard}:
5624 @item @emph{Syntax}:
5625 @code{CALL GETENV(NAME, VALUE)}
5627 @item @emph{Arguments}:
5628 @multitable @columnfractions .15 .70
5629 @item @var{NAME} @tab Shall be of type @code{CHARACTER} and of default kind.
5630 @item @var{VALUE} @tab Shall be of type @code{CHARACTER} and of default kind.
5633 @item @emph{Return value}:
5634 Stores the value of @var{NAME} in @var{VALUE}. If @var{VALUE} is
5635 not large enough to hold the data, it is truncated. If @var{NAME}
5636 is not set, @var{VALUE} will be filled with blanks.
5638 @item @emph{Example}:
5641 CHARACTER(len=255) :: homedir
5642 CALL getenv("HOME", homedir)
5643 WRITE (*,*) TRIM(homedir)
5647 @item @emph{See also}:
5648 @ref{GET_ENVIRONMENT_VARIABLE}
5653 @node GET_ENVIRONMENT_VARIABLE
5654 @section @code{GET_ENVIRONMENT_VARIABLE} --- Get an environmental variable
5655 @fnindex GET_ENVIRONMENT_VARIABLE
5656 @cindex environment variable
5659 @item @emph{Description}:
5660 Get the @var{VALUE} of the environmental variable @var{NAME}.
5662 Note that @code{GET_ENVIRONMENT_VARIABLE} need not be thread-safe. It
5663 is the responsibility of the user to ensure that the environment is
5664 not being updated concurrently with a call to the
5665 @code{GET_ENVIRONMENT_VARIABLE} intrinsic.
5667 @item @emph{Standard}:
5668 Fortran 2003 and later
5673 @item @emph{Syntax}:
5674 @code{CALL GET_ENVIRONMENT_VARIABLE(NAME[, VALUE, LENGTH, STATUS, TRIM_NAME)}
5676 @item @emph{Arguments}:
5677 @multitable @columnfractions .15 .70
5678 @item @var{NAME} @tab Shall be a scalar of type @code{CHARACTER}
5679 and of default kind.
5680 @item @var{VALUE} @tab (Optional) Shall be a scalar of type @code{CHARACTER}
5681 and of default kind.
5682 @item @var{LENGTH} @tab (Optional) Shall be a scalar of type @code{INTEGER}
5683 and of default kind.
5684 @item @var{STATUS} @tab (Optional) Shall be a scalar of type @code{INTEGER}
5685 and of default kind.
5686 @item @var{TRIM_NAME} @tab (Optional) Shall be a scalar of type @code{LOGICAL}
5687 and of default kind.
5690 @item @emph{Return value}:
5691 Stores the value of @var{NAME} in @var{VALUE}. If @var{VALUE} is
5692 not large enough to hold the data, it is truncated. If @var{NAME}
5693 is not set, @var{VALUE} will be filled with blanks. Argument @var{LENGTH}
5694 contains the length needed for storing the environment variable @var{NAME}
5695 or zero if it is not present. @var{STATUS} is -1 if @var{VALUE} is present
5696 but too short for the environment variable; it is 1 if the environment
5697 variable does not exist and 2 if the processor does not support environment
5698 variables; in all other cases @var{STATUS} is zero. If @var{TRIM_NAME} is
5699 present with the value @code{.FALSE.}, the trailing blanks in @var{NAME}
5700 are significant; otherwise they are not part of the environment variable
5703 @item @emph{Example}:
5706 CHARACTER(len=255) :: homedir
5707 CALL get_environment_variable("HOME", homedir)
5708 WRITE (*,*) TRIM(homedir)
5716 @section @code{GETGID} --- Group ID function
5718 @cindex system, group ID
5721 @item @emph{Description}:
5722 Returns the numerical group ID of the current process.
5724 @item @emph{Standard}:
5730 @item @emph{Syntax}:
5731 @code{RESULT = GETGID()}
5733 @item @emph{Return value}:
5734 The return value of @code{GETGID} is an @code{INTEGER} of the default
5738 @item @emph{Example}:
5739 See @code{GETPID} for an example.
5741 @item @emph{See also}:
5742 @ref{GETPID}, @ref{GETUID}
5748 @section @code{GETLOG} --- Get login name
5750 @cindex system, login name
5754 @item @emph{Description}:
5755 Gets the username under which the program is running.
5757 @item @emph{Standard}:
5763 @item @emph{Syntax}:
5764 @code{CALL GETLOG(C)}
5766 @item @emph{Arguments}:
5767 @multitable @columnfractions .15 .70
5768 @item @var{C} @tab Shall be of type @code{CHARACTER} and of default kind.
5771 @item @emph{Return value}:
5772 Stores the current user name in @var{LOGIN}. (On systems where POSIX
5773 functions @code{geteuid} and @code{getpwuid} are not available, and
5774 the @code{getlogin} function is not implemented either, this will
5775 return a blank string.)
5777 @item @emph{Example}:
5780 CHARACTER(32) :: login
5786 @item @emph{See also}:
5793 @section @code{GETPID} --- Process ID function
5795 @cindex system, process ID
5799 @item @emph{Description}:
5800 Returns the numerical process identifier of the current process.
5802 @item @emph{Standard}:
5808 @item @emph{Syntax}:
5809 @code{RESULT = GETPID()}
5811 @item @emph{Return value}:
5812 The return value of @code{GETPID} is an @code{INTEGER} of the default
5816 @item @emph{Example}:
5819 print *, "The current process ID is ", getpid()
5820 print *, "Your numerical user ID is ", getuid()
5821 print *, "Your numerical group ID is ", getgid()
5825 @item @emph{See also}:
5826 @ref{GETGID}, @ref{GETUID}
5832 @section @code{GETUID} --- User ID function
5834 @cindex system, user ID
5838 @item @emph{Description}:
5839 Returns the numerical user ID of the current process.
5841 @item @emph{Standard}:
5847 @item @emph{Syntax}:
5848 @code{RESULT = GETUID()}
5850 @item @emph{Return value}:
5851 The return value of @code{GETUID} is an @code{INTEGER} of the default
5855 @item @emph{Example}:
5856 See @code{GETPID} for an example.
5858 @item @emph{See also}:
5859 @ref{GETPID}, @ref{GETLOG}
5865 @section @code{GMTIME} --- Convert time to GMT info
5867 @cindex time, conversion to GMT info
5870 @item @emph{Description}:
5871 Given a system time value @var{TIME} (as provided by the @code{TIME8}
5872 intrinsic), fills @var{VALUES} with values extracted from it appropriate
5873 to the UTC time zone (Universal Coordinated Time, also known in some
5874 countries as GMT, Greenwich Mean Time), using @code{gmtime(3)}.
5876 @item @emph{Standard}:
5882 @item @emph{Syntax}:
5883 @code{CALL GMTIME(TIME, VALUES)}
5885 @item @emph{Arguments}:
5886 @multitable @columnfractions .15 .70
5887 @item @var{TIME} @tab An @code{INTEGER} scalar expression
5888 corresponding to a system time, with @code{INTENT(IN)}.
5889 @item @var{VALUES} @tab A default @code{INTEGER} array with 9 elements,
5890 with @code{INTENT(OUT)}.
5893 @item @emph{Return value}:
5894 The elements of @var{VALUES} are assigned as follows:
5896 @item Seconds after the minute, range 0--59 or 0--61 to allow for leap
5898 @item Minutes after the hour, range 0--59
5899 @item Hours past midnight, range 0--23
5900 @item Day of month, range 0--31
5901 @item Number of months since January, range 0--12
5902 @item Years since 1900
5903 @item Number of days since Sunday, range 0--6
5904 @item Days since January 1
5905 @item Daylight savings indicator: positive if daylight savings is in
5906 effect, zero if not, and negative if the information is not available.
5909 @item @emph{See also}:
5910 @ref{CTIME}, @ref{LTIME}, @ref{TIME}, @ref{TIME8}
5917 @section @code{HOSTNM} --- Get system host name
5919 @cindex system, host name
5922 @item @emph{Description}:
5923 Retrieves the host name of the system on which the program is running.
5925 This intrinsic is provided in both subroutine and function forms; however,
5926 only one form can be used in any given program unit.
5928 @item @emph{Standard}:
5932 Subroutine, function
5934 @item @emph{Syntax}:
5935 @multitable @columnfractions .80
5936 @item @code{CALL HOSTNM(C [, STATUS])}
5937 @item @code{STATUS = HOSTNM(NAME)}
5940 @item @emph{Arguments}:
5941 @multitable @columnfractions .15 .70
5942 @item @var{C} @tab Shall of type @code{CHARACTER} and of default kind.
5943 @item @var{STATUS} @tab (Optional) status flag of type @code{INTEGER}.
5944 Returns 0 on success, or a system specific error code otherwise.
5947 @item @emph{Return value}:
5948 In either syntax, @var{NAME} is set to the current hostname if it can
5949 be obtained, or to a blank string otherwise.
5956 @section @code{HUGE} --- Largest number of a kind
5958 @cindex limits, largest number
5959 @cindex model representation, largest number
5962 @item @emph{Description}:
5963 @code{HUGE(X)} returns the largest number that is not an infinity in
5964 the model of the type of @code{X}.
5966 @item @emph{Standard}:
5967 Fortran 95 and later
5972 @item @emph{Syntax}:
5973 @code{RESULT = HUGE(X)}
5975 @item @emph{Arguments}:
5976 @multitable @columnfractions .15 .70
5977 @item @var{X} @tab Shall be of type @code{REAL} or @code{INTEGER}.
5980 @item @emph{Return value}:
5981 The return value is of the same type and kind as @var{X}
5983 @item @emph{Example}:
5985 program test_huge_tiny
5986 print *, huge(0), huge(0.0), huge(0.0d0)
5987 print *, tiny(0.0), tiny(0.0d0)
5988 end program test_huge_tiny
5995 @section @code{HYPOT} --- Euclidean distance function
5997 @cindex Euclidean distance
6000 @item @emph{Description}:
6001 @code{HYPOT(X,Y)} is the Euclidean distance function. It is equal to
6002 @math{\sqrt{X^2 + Y^2}}, without undue underflow or overflow.
6004 @item @emph{Standard}:
6005 Fortran 2008 and later
6010 @item @emph{Syntax}:
6011 @code{RESULT = HYPOT(X, Y)}
6013 @item @emph{Arguments}:
6014 @multitable @columnfractions .15 .70
6015 @item @var{X} @tab The type shall be @code{REAL}.
6016 @item @var{Y} @tab The type and kind type parameter shall be the same as
6020 @item @emph{Return value}:
6021 The return value has the same type and kind type parameter as @var{X}.
6023 @item @emph{Example}:
6026 real(4) :: x = 1.e0_4, y = 0.5e0_4
6028 end program test_hypot
6035 @section @code{IACHAR} --- Code in @acronym{ASCII} collating sequence
6037 @cindex @acronym{ASCII} collating sequence
6038 @cindex collating sequence, @acronym{ASCII}
6039 @cindex conversion, to integer
6042 @item @emph{Description}:
6043 @code{IACHAR(C)} returns the code for the @acronym{ASCII} character
6044 in the first character position of @code{C}.
6046 @item @emph{Standard}:
6047 Fortran 95 and later, with @var{KIND} argument Fortran 2003 and later
6052 @item @emph{Syntax}:
6053 @code{RESULT = IACHAR(C [, KIND])}
6055 @item @emph{Arguments}:
6056 @multitable @columnfractions .15 .70
6057 @item @var{C} @tab Shall be a scalar @code{CHARACTER}, with @code{INTENT(IN)}
6058 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
6059 expression indicating the kind parameter of the result.
6062 @item @emph{Return value}:
6063 The return value is of type @code{INTEGER} and of kind @var{KIND}. If
6064 @var{KIND} is absent, the return value is of default integer kind.
6066 @item @emph{Example}:
6071 end program test_iachar
6075 See @ref{ICHAR} for a discussion of converting between numerical values
6076 and formatted string representations.
6078 @item @emph{See also}:
6079 @ref{ACHAR}, @ref{CHAR}, @ref{ICHAR}
6086 @section @code{IALL} --- Bitwise AND of array elements
6089 @cindex bits, AND of array elements
6092 @item @emph{Description}:
6093 Reduces with bitwise AND the elements of @var{ARRAY} along dimension @var{DIM}
6094 if the corresponding element in @var{MASK} is @code{TRUE}.
6096 @item @emph{Standard}:
6097 Fortran 2008 and later
6100 Transformational function
6102 @item @emph{Syntax}:
6103 @multitable @columnfractions .80
6104 @item @code{RESULT = IALL(ARRAY[, MASK])}
6105 @item @code{RESULT = IALL(ARRAY, DIM[, MASK])}
6108 @item @emph{Arguments}:
6109 @multitable @columnfractions .15 .70
6110 @item @var{ARRAY} @tab Shall be an array of type @code{INTEGER}
6111 @item @var{DIM} @tab (Optional) shall be a scalar of type
6112 @code{INTEGER} with a value in the range from 1 to n, where n
6113 equals the rank of @var{ARRAY}.
6114 @item @var{MASK} @tab (Optional) shall be of type @code{LOGICAL}
6115 and either be a scalar or an array of the same shape as @var{ARRAY}.
6118 @item @emph{Return value}:
6119 The result is of the same type as @var{ARRAY}.
6121 If @var{DIM} is absent, a scalar with the bitwise ALL of all elements in
6122 @var{ARRAY} is returned. Otherwise, an array of rank n-1, where n equals
6123 the rank of @var{ARRAY}, and a shape similar to that of @var{ARRAY} with
6124 dimension @var{DIM} dropped is returned.
6126 @item @emph{Example}:
6135 PRINT '(b8.8)', IALL(a)
6139 @item @emph{See also}:
6140 @ref{IANY}, @ref{IPARITY}, @ref{IAND}
6146 @section @code{IAND} --- Bitwise logical and
6148 @cindex bitwise logical and
6149 @cindex logical and, bitwise
6152 @item @emph{Description}:
6153 Bitwise logical @code{AND}.
6155 @item @emph{Standard}:
6156 Fortran 95 and later
6161 @item @emph{Syntax}:
6162 @code{RESULT = IAND(I, J)}
6164 @item @emph{Arguments}:
6165 @multitable @columnfractions .15 .70
6166 @item @var{I} @tab The type shall be @code{INTEGER}.
6167 @item @var{J} @tab The type shall be @code{INTEGER}, of the same
6168 kind as @var{I}. (As a GNU extension, different kinds are also
6172 @item @emph{Return value}:
6173 The return type is @code{INTEGER}, of the same kind as the
6174 arguments. (If the argument kinds differ, it is of the same kind as
6175 the larger argument.)
6177 @item @emph{Example}:
6181 DATA a / Z'F' /, b / Z'3' /
6182 WRITE (*,*) IAND(a, b)
6186 @item @emph{See also}:
6187 @ref{IOR}, @ref{IEOR}, @ref{IBITS}, @ref{IBSET}, @ref{IBCLR}, @ref{NOT}
6194 @section @code{IANY} --- Bitwise OR of array elements
6197 @cindex bits, OR of array elements
6200 @item @emph{Description}:
6201 Reduces with bitwise OR (inclusive or) the elements of @var{ARRAY} along
6202 dimension @var{DIM} if the corresponding element in @var{MASK} is @code{TRUE}.
6204 @item @emph{Standard}:
6205 Fortran 2008 and later
6208 Transformational function
6210 @item @emph{Syntax}:
6211 @multitable @columnfractions .80
6212 @item @code{RESULT = IANY(ARRAY[, MASK])}
6213 @item @code{RESULT = IANY(ARRAY, DIM[, MASK])}
6216 @item @emph{Arguments}:
6217 @multitable @columnfractions .15 .70
6218 @item @var{ARRAY} @tab Shall be an array of type @code{INTEGER}
6219 @item @var{DIM} @tab (Optional) shall be a scalar of type
6220 @code{INTEGER} with a value in the range from 1 to n, where n
6221 equals the rank of @var{ARRAY}.
6222 @item @var{MASK} @tab (Optional) shall be of type @code{LOGICAL}
6223 and either be a scalar or an array of the same shape as @var{ARRAY}.
6226 @item @emph{Return value}:
6227 The result is of the same type as @var{ARRAY}.
6229 If @var{DIM} is absent, a scalar with the bitwise OR of all elements in
6230 @var{ARRAY} is returned. Otherwise, an array of rank n-1, where n equals
6231 the rank of @var{ARRAY}, and a shape similar to that of @var{ARRAY} with
6232 dimension @var{DIM} dropped is returned.
6234 @item @emph{Example}:
6243 PRINT '(b8.8)', IANY(a)
6247 @item @emph{See also}:
6248 @ref{IPARITY}, @ref{IALL}, @ref{IOR}
6254 @section @code{IARGC} --- Get the number of command line arguments
6256 @cindex command-line arguments
6257 @cindex command-line arguments, number of
6258 @cindex arguments, to program
6261 @item @emph{Description}:
6262 @code{IARGC} returns the number of arguments passed on the
6263 command line when the containing program was invoked.
6265 This intrinsic routine is provided for backwards compatibility with
6266 GNU Fortran 77. In new code, programmers should consider the use of
6267 the @ref{COMMAND_ARGUMENT_COUNT} intrinsic defined by the Fortran 2003
6270 @item @emph{Standard}:
6276 @item @emph{Syntax}:
6277 @code{RESULT = IARGC()}
6279 @item @emph{Arguments}:
6282 @item @emph{Return value}:
6283 The number of command line arguments, type @code{INTEGER(4)}.
6285 @item @emph{Example}:
6288 @item @emph{See also}:
6289 GNU Fortran 77 compatibility subroutine: @ref{GETARG}
6291 Fortran 2003 functions and subroutines: @ref{GET_COMMAND},
6292 @ref{GET_COMMAND_ARGUMENT}, @ref{COMMAND_ARGUMENT_COUNT}
6298 @section @code{IBCLR} --- Clear bit
6304 @item @emph{Description}:
6305 @code{IBCLR} returns the value of @var{I} with the bit at position
6306 @var{POS} set to zero.
6308 @item @emph{Standard}:
6309 Fortran 95 and later
6314 @item @emph{Syntax}:
6315 @code{RESULT = IBCLR(I, POS)}
6317 @item @emph{Arguments}:
6318 @multitable @columnfractions .15 .70
6319 @item @var{I} @tab The type shall be @code{INTEGER}.
6320 @item @var{POS} @tab The type shall be @code{INTEGER}.
6323 @item @emph{Return value}:
6324 The return value is of type @code{INTEGER} and of the same kind as
6327 @item @emph{See also}:
6328 @ref{IBITS}, @ref{IBSET}, @ref{IAND}, @ref{IOR}, @ref{IEOR}, @ref{MVBITS}
6335 @section @code{IBITS} --- Bit extraction
6338 @cindex bits, extract
6341 @item @emph{Description}:
6342 @code{IBITS} extracts a field of length @var{LEN} from @var{I},
6343 starting from bit position @var{POS} and extending left for @var{LEN}
6344 bits. The result is right-justified and the remaining bits are
6345 zeroed. The value of @code{POS+LEN} must be less than or equal to the
6346 value @code{BIT_SIZE(I)}.
6348 @item @emph{Standard}:
6349 Fortran 95 and later
6354 @item @emph{Syntax}:
6355 @code{RESULT = IBITS(I, POS, LEN)}
6357 @item @emph{Arguments}:
6358 @multitable @columnfractions .15 .70
6359 @item @var{I} @tab The type shall be @code{INTEGER}.
6360 @item @var{POS} @tab The type shall be @code{INTEGER}.
6361 @item @var{LEN} @tab The type shall be @code{INTEGER}.
6364 @item @emph{Return value}:
6365 The return value is of type @code{INTEGER} and of the same kind as
6368 @item @emph{See also}:
6369 @ref{BIT_SIZE}, @ref{IBCLR}, @ref{IBSET}, @ref{IAND}, @ref{IOR}, @ref{IEOR}
6375 @section @code{IBSET} --- Set bit
6380 @item @emph{Description}:
6381 @code{IBSET} returns the value of @var{I} with the bit at position
6382 @var{POS} set to one.
6384 @item @emph{Standard}:
6385 Fortran 95 and later
6390 @item @emph{Syntax}:
6391 @code{RESULT = IBSET(I, POS)}
6393 @item @emph{Arguments}:
6394 @multitable @columnfractions .15 .70
6395 @item @var{I} @tab The type shall be @code{INTEGER}.
6396 @item @var{POS} @tab The type shall be @code{INTEGER}.
6399 @item @emph{Return value}:
6400 The return value is of type @code{INTEGER} and of the same kind as
6403 @item @emph{See also}:
6404 @ref{IBCLR}, @ref{IBITS}, @ref{IAND}, @ref{IOR}, @ref{IEOR}, @ref{MVBITS}
6411 @section @code{ICHAR} --- Character-to-integer conversion function
6413 @cindex conversion, to integer
6416 @item @emph{Description}:
6417 @code{ICHAR(C)} returns the code for the character in the first character
6418 position of @code{C} in the system's native character set.
6419 The correspondence between characters and their codes is not necessarily
6420 the same across different GNU Fortran implementations.
6422 @item @emph{Standard}:
6423 Fortran 95 and later, with @var{KIND} argument Fortran 2003 and later
6428 @item @emph{Syntax}:
6429 @code{RESULT = ICHAR(C [, KIND])}
6431 @item @emph{Arguments}:
6432 @multitable @columnfractions .15 .70
6433 @item @var{C} @tab Shall be a scalar @code{CHARACTER}, with @code{INTENT(IN)}
6434 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
6435 expression indicating the kind parameter of the result.
6438 @item @emph{Return value}:
6439 The return value is of type @code{INTEGER} and of kind @var{KIND}. If
6440 @var{KIND} is absent, the return value is of default integer kind.
6442 @item @emph{Example}:
6447 end program test_ichar
6450 @item @emph{Specific names}:
6451 @multitable @columnfractions .20 .20 .20 .25
6452 @item Name @tab Argument @tab Return type @tab Standard
6453 @item @code{ICHAR(C)} @tab @code{CHARACTER C} @tab @code{INTEGER(4)} @tab Fortran 77 and later
6457 No intrinsic exists to convert between a numeric value and a formatted
6458 character string representation -- for instance, given the
6459 @code{CHARACTER} value @code{'154'}, obtaining an @code{INTEGER} or
6460 @code{REAL} value with the value 154, or vice versa. Instead, this
6461 functionality is provided by internal-file I/O, as in the following
6466 character(len=10) string, string2
6469 ! Convert a string to a numeric value
6470 read (string,'(I10)') value
6473 ! Convert a value to a formatted string
6474 write (string2,'(I10)') value
6476 end program read_val
6479 @item @emph{See also}:
6480 @ref{ACHAR}, @ref{CHAR}, @ref{IACHAR}
6487 @section @code{IDATE} --- Get current local time subroutine (day/month/year)
6489 @cindex date, current
6490 @cindex current date
6493 @item @emph{Description}:
6494 @code{IDATE(VALUES)} Fills @var{VALUES} with the numerical values at the
6495 current local time. The day (in the range 1-31), month (in the range 1-12),
6496 and year appear in elements 1, 2, and 3 of @var{VALUES}, respectively.
6497 The year has four significant digits.
6499 @item @emph{Standard}:
6505 @item @emph{Syntax}:
6506 @code{CALL IDATE(VALUES)}
6508 @item @emph{Arguments}:
6509 @multitable @columnfractions .15 .70
6510 @item @var{VALUES} @tab The type shall be @code{INTEGER, DIMENSION(3)} and
6511 the kind shall be the default integer kind.
6514 @item @emph{Return value}:
6515 Does not return anything.
6517 @item @emph{Example}:
6520 integer, dimension(3) :: tarray
6525 end program test_idate
6532 @section @code{IEOR} --- Bitwise logical exclusive or
6534 @cindex bitwise logical exclusive or
6535 @cindex logical exclusive or, bitwise
6538 @item @emph{Description}:
6539 @code{IEOR} returns the bitwise Boolean exclusive-OR of @var{I} and
6542 @item @emph{Standard}:
6543 Fortran 95 and later
6548 @item @emph{Syntax}:
6549 @code{RESULT = IEOR(I, J)}
6551 @item @emph{Arguments}:
6552 @multitable @columnfractions .15 .70
6553 @item @var{I} @tab The type shall be @code{INTEGER}.
6554 @item @var{J} @tab The type shall be @code{INTEGER}, of the same
6555 kind as @var{I}. (As a GNU extension, different kinds are also
6559 @item @emph{Return value}:
6560 The return type is @code{INTEGER}, of the same kind as the
6561 arguments. (If the argument kinds differ, it is of the same kind as
6562 the larger argument.)
6564 @item @emph{See also}:
6565 @ref{IOR}, @ref{IAND}, @ref{IBITS}, @ref{IBSET}, @ref{IBCLR}, @ref{NOT}
6571 @section @code{IERRNO} --- Get the last system error number
6573 @cindex system, error handling
6576 @item @emph{Description}:
6577 Returns the last system error number, as given by the C @code{errno}
6580 @item @emph{Standard}:
6586 @item @emph{Syntax}:
6587 @code{RESULT = IERRNO()}
6589 @item @emph{Arguments}:
6592 @item @emph{Return value}:
6593 The return value is of type @code{INTEGER} and of the default integer
6596 @item @emph{See also}:
6603 @section @code{IMAGE_INDEX} --- Function that converts a cosubscript to an image index
6604 @fnindex IMAGE_INDEX
6605 @cindex coarray, @code{IMAGE_INDEX}
6606 @cindex images, cosubscript to image index conversion
6609 @item @emph{Description}:
6610 Returns the image index belonging to a cosubscript.
6612 @item @emph{Standard}:
6613 Fortran 2008 and later
6618 @item @emph{Syntax}:
6619 @code{RESULT = IMAGE_INDEX(COARRAY, SUB)}
6621 @item @emph{Arguments}: None.
6622 @multitable @columnfractions .15 .70
6623 @item @var{COARRAY} @tab Coarray of any type.
6624 @item @var{SUB} @tab default integer rank-1 array of a size equal to
6625 the corank of @var{COARRAY}.
6629 @item @emph{Return value}:
6630 Scalar default integer with the value of the image index which corresponds
6631 to the cosubscripts. For invalid cosubscripts the result is zero.
6633 @item @emph{Example}:
6635 INTEGER :: array[2,-1:4,8,*]
6636 ! Writes 28 (or 0 if there are fewer than 28 images)
6637 WRITE (*,*) IMAGE_INDEX (array, [2,0,3,1])
6640 @item @emph{See also}:
6641 @ref{THIS_IMAGE}, @ref{NUM_IMAGES}
6646 @node INDEX intrinsic
6647 @section @code{INDEX} --- Position of a substring within a string
6649 @cindex substring position
6650 @cindex string, find substring
6653 @item @emph{Description}:
6654 Returns the position of the start of the first occurrence of string
6655 @var{SUBSTRING} as a substring in @var{STRING}, counting from one. If
6656 @var{SUBSTRING} is not present in @var{STRING}, zero is returned. If
6657 the @var{BACK} argument is present and true, the return value is the
6658 start of the last occurrence rather than the first.
6660 @item @emph{Standard}:
6661 Fortran 77 and later, with @var{KIND} argument Fortran 2003 and later
6666 @item @emph{Syntax}:
6667 @code{RESULT = INDEX(STRING, SUBSTRING [, BACK [, KIND]])}
6669 @item @emph{Arguments}:
6670 @multitable @columnfractions .15 .70
6671 @item @var{STRING} @tab Shall be a scalar @code{CHARACTER}, with
6673 @item @var{SUBSTRING} @tab Shall be a scalar @code{CHARACTER}, with
6675 @item @var{BACK} @tab (Optional) Shall be a scalar @code{LOGICAL}, with
6677 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
6678 expression indicating the kind parameter of the result.
6681 @item @emph{Return value}:
6682 The return value is of type @code{INTEGER} and of kind @var{KIND}. If
6683 @var{KIND} is absent, the return value is of default integer kind.
6685 @item @emph{Specific names}:
6686 @multitable @columnfractions .20 .20 .20 .25
6687 @item Name @tab Argument @tab Return type @tab Standard
6688 @item @code{INDEX(STRING, SUBSTRING)} @tab @code{CHARACTER} @tab @code{INTEGER(4)} @tab Fortran 77 and later
6691 @item @emph{See also}:
6692 @ref{SCAN}, @ref{VERIFY}
6698 @section @code{INT} --- Convert to integer type
6702 @cindex conversion, to integer
6705 @item @emph{Description}:
6706 Convert to integer type
6708 @item @emph{Standard}:
6709 Fortran 77 and later
6714 @item @emph{Syntax}:
6715 @code{RESULT = INT(A [, KIND))}
6717 @item @emph{Arguments}:
6718 @multitable @columnfractions .15 .70
6719 @item @var{A} @tab Shall be of type @code{INTEGER},
6720 @code{REAL}, or @code{COMPLEX}.
6721 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
6722 expression indicating the kind parameter of the result.
6725 @item @emph{Return value}:
6726 These functions return a @code{INTEGER} variable or array under
6727 the following rules:
6731 If @var{A} is of type @code{INTEGER}, @code{INT(A) = A}
6733 If @var{A} is of type @code{REAL} and @math{|A| < 1}, @code{INT(A)} equals @code{0}.
6734 If @math{|A| \geq 1}, then @code{INT(A)} equals the largest integer that does not exceed
6735 the range of @var{A} and whose sign is the same as the sign of @var{A}.
6737 If @var{A} is of type @code{COMPLEX}, rule B is applied to the real part of @var{A}.
6740 @item @emph{Example}:
6744 complex :: z = (-3.7, 1.0)
6746 print *, int(z), int(z,8)
6750 @item @emph{Specific names}:
6751 @multitable @columnfractions .20 .20 .20 .25
6752 @item Name @tab Argument @tab Return type @tab Standard
6753 @item @code{INT(A)} @tab @code{REAL(4) A} @tab @code{INTEGER} @tab Fortran 77 and later
6754 @item @code{IFIX(A)} @tab @code{REAL(4) A} @tab @code{INTEGER} @tab Fortran 77 and later
6755 @item @code{IDINT(A)} @tab @code{REAL(8) A} @tab @code{INTEGER} @tab Fortran 77 and later
6762 @section @code{INT2} --- Convert to 16-bit integer type
6765 @cindex conversion, to integer
6768 @item @emph{Description}:
6769 Convert to a @code{KIND=2} integer type. This is equivalent to the
6770 standard @code{INT} intrinsic with an optional argument of
6771 @code{KIND=2}, and is only included for backwards compatibility.
6773 The @code{SHORT} intrinsic is equivalent to @code{INT2}.
6775 @item @emph{Standard}:
6781 @item @emph{Syntax}:
6782 @code{RESULT = INT2(A)}
6784 @item @emph{Arguments}:
6785 @multitable @columnfractions .15 .70
6786 @item @var{A} @tab Shall be of type @code{INTEGER},
6787 @code{REAL}, or @code{COMPLEX}.
6790 @item @emph{Return value}:
6791 The return value is a @code{INTEGER(2)} variable.
6793 @item @emph{See also}:
6794 @ref{INT}, @ref{INT8}, @ref{LONG}
6800 @section @code{INT8} --- Convert to 64-bit integer type
6802 @cindex conversion, to integer
6805 @item @emph{Description}:
6806 Convert to a @code{KIND=8} integer type. This is equivalent to the
6807 standard @code{INT} intrinsic with an optional argument of
6808 @code{KIND=8}, and is only included for backwards compatibility.
6810 @item @emph{Standard}:
6816 @item @emph{Syntax}:
6817 @code{RESULT = INT8(A)}
6819 @item @emph{Arguments}:
6820 @multitable @columnfractions .15 .70
6821 @item @var{A} @tab Shall be of type @code{INTEGER},
6822 @code{REAL}, or @code{COMPLEX}.
6825 @item @emph{Return value}:
6826 The return value is a @code{INTEGER(8)} variable.
6828 @item @emph{See also}:
6829 @ref{INT}, @ref{INT2}, @ref{LONG}
6835 @section @code{IOR} --- Bitwise logical or
6837 @cindex bitwise logical or
6838 @cindex logical or, bitwise
6841 @item @emph{Description}:
6842 @code{IOR} returns the bitwise Boolean inclusive-OR of @var{I} and
6845 @item @emph{Standard}:
6846 Fortran 95 and later
6851 @item @emph{Syntax}:
6852 @code{RESULT = IOR(I, J)}
6854 @item @emph{Arguments}:
6855 @multitable @columnfractions .15 .70
6856 @item @var{I} @tab The type shall be @code{INTEGER}.
6857 @item @var{J} @tab The type shall be @code{INTEGER}, of the same
6858 kind as @var{I}. (As a GNU extension, different kinds are also
6862 @item @emph{Return value}:
6863 The return type is @code{INTEGER}, of the same kind as the
6864 arguments. (If the argument kinds differ, it is of the same kind as
6865 the larger argument.)
6867 @item @emph{See also}:
6868 @ref{IEOR}, @ref{IAND}, @ref{IBITS}, @ref{IBSET}, @ref{IBCLR}, @ref{NOT}
6874 @section @code{IPARITY} --- Bitwise XOR of array elements
6876 @cindex array, parity
6878 @cindex bits, XOR of array elements
6881 @item @emph{Description}:
6882 Reduces with bitwise XOR (exclusive or) the elements of @var{ARRAY} along
6883 dimension @var{DIM} if the corresponding element in @var{MASK} is @code{TRUE}.
6885 @item @emph{Standard}:
6886 Fortran 2008 and later
6889 Transformational function
6891 @item @emph{Syntax}:
6892 @multitable @columnfractions .80
6893 @item @code{RESULT = IPARITY(ARRAY[, MASK])}
6894 @item @code{RESULT = IPARITY(ARRAY, DIM[, MASK])}
6897 @item @emph{Arguments}:
6898 @multitable @columnfractions .15 .70
6899 @item @var{ARRAY} @tab Shall be an array of type @code{INTEGER}
6900 @item @var{DIM} @tab (Optional) shall be a scalar of type
6901 @code{INTEGER} with a value in the range from 1 to n, where n
6902 equals the rank of @var{ARRAY}.
6903 @item @var{MASK} @tab (Optional) shall be of type @code{LOGICAL}
6904 and either be a scalar or an array of the same shape as @var{ARRAY}.
6907 @item @emph{Return value}:
6908 The result is of the same type as @var{ARRAY}.
6910 If @var{DIM} is absent, a scalar with the bitwise XOR of all elements in
6911 @var{ARRAY} is returned. Otherwise, an array of rank n-1, where n equals
6912 the rank of @var{ARRAY}, and a shape similar to that of @var{ARRAY} with
6913 dimension @var{DIM} dropped is returned.
6915 @item @emph{Example}:
6917 PROGRAM test_iparity
6924 PRINT '(b8.8)', IPARITY(a)
6928 @item @emph{See also}:
6929 @ref{IANY}, @ref{IALL}, @ref{IEOR}, @ref{PARITY}
6935 @section @code{IRAND} --- Integer pseudo-random number
6937 @cindex random number generation
6940 @item @emph{Description}:
6941 @code{IRAND(FLAG)} returns a pseudo-random number from a uniform
6942 distribution between 0 and a system-dependent limit (which is in most
6943 cases 2147483647). If @var{FLAG} is 0, the next number
6944 in the current sequence is returned; if @var{FLAG} is 1, the generator
6945 is restarted by @code{CALL SRAND(0)}; if @var{FLAG} has any other value,
6946 it is used as a new seed with @code{SRAND}.
6948 This intrinsic routine is provided for backwards compatibility with
6949 GNU Fortran 77. It implements a simple modulo generator as provided
6950 by @command{g77}. For new code, one should consider the use of
6951 @ref{RANDOM_NUMBER} as it implements a superior algorithm.
6953 @item @emph{Standard}:
6959 @item @emph{Syntax}:
6960 @code{RESULT = IRAND(I)}
6962 @item @emph{Arguments}:
6963 @multitable @columnfractions .15 .70
6964 @item @var{I} @tab Shall be a scalar @code{INTEGER} of kind 4.
6967 @item @emph{Return value}:
6968 The return value is of @code{INTEGER(kind=4)} type.
6970 @item @emph{Example}:
6973 integer,parameter :: seed = 86456
6976 print *, irand(), irand(), irand(), irand()
6977 print *, irand(seed), irand(), irand(), irand()
6978 end program test_irand
6986 @section @code{IS_IOSTAT_END} --- Test for end-of-file value
6987 @fnindex IS_IOSTAT_END
6988 @cindex @code{IOSTAT}, end of file
6991 @item @emph{Description}:
6992 @code{IS_IOSTAT_END} tests whether an variable has the value of the I/O
6993 status ``end of file''. The function is equivalent to comparing the variable
6994 with the @code{IOSTAT_END} parameter of the intrinsic module
6995 @code{ISO_FORTRAN_ENV}.
6997 @item @emph{Standard}:
6998 Fortran 2003 and later
7003 @item @emph{Syntax}:
7004 @code{RESULT = IS_IOSTAT_END(I)}
7006 @item @emph{Arguments}:
7007 @multitable @columnfractions .15 .70
7008 @item @var{I} @tab Shall be of the type @code{INTEGER}.
7011 @item @emph{Return value}:
7012 Returns a @code{LOGICAL} of the default kind, which @code{.TRUE.} if
7013 @var{I} has the value which indicates an end of file condition for
7014 @code{IOSTAT=} specifiers, and is @code{.FALSE.} otherwise.
7016 @item @emph{Example}:
7021 OPEN(88, FILE='test.dat')
7022 READ(88, *, IOSTAT=stat) i
7023 IF(IS_IOSTAT_END(stat)) STOP 'END OF FILE'
7031 @section @code{IS_IOSTAT_EOR} --- Test for end-of-record value
7032 @fnindex IS_IOSTAT_EOR
7033 @cindex @code{IOSTAT}, end of record
7036 @item @emph{Description}:
7037 @code{IS_IOSTAT_EOR} tests whether an variable has the value of the I/O
7038 status ``end of record''. The function is equivalent to comparing the
7039 variable with the @code{IOSTAT_EOR} parameter of the intrinsic module
7040 @code{ISO_FORTRAN_ENV}.
7042 @item @emph{Standard}:
7043 Fortran 2003 and later
7048 @item @emph{Syntax}:
7049 @code{RESULT = IS_IOSTAT_EOR(I)}
7051 @item @emph{Arguments}:
7052 @multitable @columnfractions .15 .70
7053 @item @var{I} @tab Shall be of the type @code{INTEGER}.
7056 @item @emph{Return value}:
7057 Returns a @code{LOGICAL} of the default kind, which @code{.TRUE.} if
7058 @var{I} has the value which indicates an end of file condition for
7059 @code{IOSTAT=} specifiers, and is @code{.FALSE.} otherwise.
7061 @item @emph{Example}:
7065 INTEGER :: stat, i(50)
7066 OPEN(88, FILE='test.dat', FORM='UNFORMATTED')
7067 READ(88, IOSTAT=stat) i
7068 IF(IS_IOSTAT_EOR(stat)) STOP 'END OF RECORD'
7076 @section @code{ISATTY} --- Whether a unit is a terminal device.
7078 @cindex system, terminal
7081 @item @emph{Description}:
7082 Determine whether a unit is connected to a terminal device.
7084 @item @emph{Standard}:
7090 @item @emph{Syntax}:
7091 @code{RESULT = ISATTY(UNIT)}
7093 @item @emph{Arguments}:
7094 @multitable @columnfractions .15 .70
7095 @item @var{UNIT} @tab Shall be a scalar @code{INTEGER}.
7098 @item @emph{Return value}:
7099 Returns @code{.TRUE.} if the @var{UNIT} is connected to a terminal
7100 device, @code{.FALSE.} otherwise.
7102 @item @emph{Example}:
7105 INTEGER(kind=1) :: unit
7107 write(*,*) isatty(unit=unit)
7111 @item @emph{See also}:
7118 @section @code{ISHFT} --- Shift bits
7123 @item @emph{Description}:
7124 @code{ISHFT} returns a value corresponding to @var{I} with all of the
7125 bits shifted @var{SHIFT} places. A value of @var{SHIFT} greater than
7126 zero corresponds to a left shift, a value of zero corresponds to no
7127 shift, and a value less than zero corresponds to a right shift. If the
7128 absolute value of @var{SHIFT} is greater than @code{BIT_SIZE(I)}, the
7129 value is undefined. Bits shifted out from the left end or right end are
7130 lost; zeros are shifted in from the opposite end.
7132 @item @emph{Standard}:
7133 Fortran 95 and later
7138 @item @emph{Syntax}:
7139 @code{RESULT = ISHFT(I, SHIFT)}
7141 @item @emph{Arguments}:
7142 @multitable @columnfractions .15 .70
7143 @item @var{I} @tab The type shall be @code{INTEGER}.
7144 @item @var{SHIFT} @tab The type shall be @code{INTEGER}.
7147 @item @emph{Return value}:
7148 The return value is of type @code{INTEGER} and of the same kind as
7151 @item @emph{See also}:
7158 @section @code{ISHFTC} --- Shift bits circularly
7160 @cindex bits, shift circular
7163 @item @emph{Description}:
7164 @code{ISHFTC} returns a value corresponding to @var{I} with the
7165 rightmost @var{SIZE} bits shifted circularly @var{SHIFT} places; that
7166 is, bits shifted out one end are shifted into the opposite end. A value
7167 of @var{SHIFT} greater than zero corresponds to a left shift, a value of
7168 zero corresponds to no shift, and a value less than zero corresponds to
7169 a right shift. The absolute value of @var{SHIFT} must be less than
7170 @var{SIZE}. If the @var{SIZE} argument is omitted, it is taken to be
7171 equivalent to @code{BIT_SIZE(I)}.
7173 @item @emph{Standard}:
7174 Fortran 95 and later
7179 @item @emph{Syntax}:
7180 @code{RESULT = ISHFTC(I, SHIFT [, SIZE])}
7182 @item @emph{Arguments}:
7183 @multitable @columnfractions .15 .70
7184 @item @var{I} @tab The type shall be @code{INTEGER}.
7185 @item @var{SHIFT} @tab The type shall be @code{INTEGER}.
7186 @item @var{SIZE} @tab (Optional) The type shall be @code{INTEGER};
7187 the value must be greater than zero and less than or equal to
7191 @item @emph{Return value}:
7192 The return value is of type @code{INTEGER} and of the same kind as
7195 @item @emph{See also}:
7202 @section @code{ISNAN} --- Test for a NaN
7207 @item @emph{Description}:
7208 @code{ISNAN} tests whether a floating-point value is an IEEE
7210 @item @emph{Standard}:
7216 @item @emph{Syntax}:
7219 @item @emph{Arguments}:
7220 @multitable @columnfractions .15 .70
7221 @item @var{X} @tab Variable of the type @code{REAL}.
7225 @item @emph{Return value}:
7226 Returns a default-kind @code{LOGICAL}. The returned value is @code{TRUE}
7227 if @var{X} is a NaN and @code{FALSE} otherwise.
7229 @item @emph{Example}:
7236 if (isnan(x)) stop '"x" is a NaN'
7237 end program test_nan
7244 @section @code{ITIME} --- Get current local time subroutine (hour/minutes/seconds)
7246 @cindex time, current
7247 @cindex current time
7250 @item @emph{Description}:
7251 @code{IDATE(VALUES)} Fills @var{VALUES} with the numerical values at the
7252 current local time. The hour (in the range 1-24), minute (in the range 1-60),
7253 and seconds (in the range 1-60) appear in elements 1, 2, and 3 of @var{VALUES},
7256 @item @emph{Standard}:
7262 @item @emph{Syntax}:
7263 @code{CALL ITIME(VALUES)}
7265 @item @emph{Arguments}:
7266 @multitable @columnfractions .15 .70
7267 @item @var{VALUES} @tab The type shall be @code{INTEGER, DIMENSION(3)}
7268 and the kind shall be the default integer kind.
7271 @item @emph{Return value}:
7272 Does not return anything.
7275 @item @emph{Example}:
7278 integer, dimension(3) :: tarray
7283 end program test_itime
7290 @section @code{KILL} --- Send a signal to a process
7294 @item @emph{Description}:
7295 @item @emph{Standard}:
7296 Sends the signal specified by @var{SIGNAL} to the process @var{PID}.
7299 This intrinsic is provided in both subroutine and function forms; however,
7300 only one form can be used in any given program unit.
7303 Subroutine, function
7305 @item @emph{Syntax}:
7306 @multitable @columnfractions .80
7307 @item @code{CALL KILL(C, VALUE [, STATUS])}
7308 @item @code{STATUS = KILL(C, VALUE)}
7311 @item @emph{Arguments}:
7312 @multitable @columnfractions .15 .70
7313 @item @var{C} @tab Shall be a scalar @code{INTEGER}, with
7315 @item @var{VALUE} @tab Shall be a scalar @code{INTEGER}, with
7317 @item @var{STATUS} @tab (Optional) status flag of type @code{INTEGER(4)} or
7318 @code{INTEGER(8)}. Returns 0 on success, or a system-specific error code
7322 @item @emph{See also}:
7323 @ref{ABORT}, @ref{EXIT}
7329 @section @code{KIND} --- Kind of an entity
7334 @item @emph{Description}:
7335 @code{KIND(X)} returns the kind value of the entity @var{X}.
7337 @item @emph{Standard}:
7338 Fortran 95 and later
7343 @item @emph{Syntax}:
7346 @item @emph{Arguments}:
7347 @multitable @columnfractions .15 .70
7348 @item @var{X} @tab Shall be of type @code{LOGICAL}, @code{INTEGER},
7349 @code{REAL}, @code{COMPLEX} or @code{CHARACTER}.
7352 @item @emph{Return value}:
7353 The return value is a scalar of type @code{INTEGER} and of the default
7356 @item @emph{Example}:
7359 integer,parameter :: kc = kind(' ')
7360 integer,parameter :: kl = kind(.true.)
7362 print *, "The default character kind is ", kc
7363 print *, "The default logical kind is ", kl
7364 end program test_kind
7372 @section @code{LBOUND} --- Lower dimension bounds of an array
7374 @cindex array, lower bound
7377 @item @emph{Description}:
7378 Returns the lower bounds of an array, or a single lower bound
7379 along the @var{DIM} dimension.
7380 @item @emph{Standard}:
7381 Fortran 95 and later, with @var{KIND} argument Fortran 2003 and later
7386 @item @emph{Syntax}:
7387 @code{RESULT = LBOUND(ARRAY [, DIM [, KIND]])}
7389 @item @emph{Arguments}:
7390 @multitable @columnfractions .15 .70
7391 @item @var{ARRAY} @tab Shall be an array, of any type.
7392 @item @var{DIM} @tab (Optional) Shall be a scalar @code{INTEGER}.
7393 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
7394 expression indicating the kind parameter of the result.
7397 @item @emph{Return value}:
7398 The return value is of type @code{INTEGER} and of kind @var{KIND}. If
7399 @var{KIND} is absent, the return value is of default integer kind.
7400 If @var{DIM} is absent, the result is an array of the lower bounds of
7401 @var{ARRAY}. If @var{DIM} is present, the result is a scalar
7402 corresponding to the lower bound of the array along that dimension. If
7403 @var{ARRAY} is an expression rather than a whole array or array
7404 structure component, or if it has a zero extent along the relevant
7405 dimension, the lower bound is taken to be 1.
7407 @item @emph{See also}:
7408 @ref{UBOUND}, @ref{LCOBOUND}
7414 @section @code{LCOBOUND} --- Lower codimension bounds of an array
7416 @cindex coarray, lower bound
7419 @item @emph{Description}:
7420 Returns the lower bounds of a coarray, or a single lower cobound
7421 along the @var{DIM} codimension.
7422 @item @emph{Standard}:
7423 Fortran 2008 and later
7428 @item @emph{Syntax}:
7429 @code{RESULT = LCOBOUND(COARRAY [, DIM [, KIND]])}
7431 @item @emph{Arguments}:
7432 @multitable @columnfractions .15 .70
7433 @item @var{ARRAY} @tab Shall be an coarray, of any type.
7434 @item @var{DIM} @tab (Optional) Shall be a scalar @code{INTEGER}.
7435 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
7436 expression indicating the kind parameter of the result.
7439 @item @emph{Return value}:
7440 The return value is of type @code{INTEGER} and of kind @var{KIND}. If
7441 @var{KIND} is absent, the return value is of default integer kind.
7442 If @var{DIM} is absent, the result is an array of the lower cobounds of
7443 @var{COARRAY}. If @var{DIM} is present, the result is a scalar
7444 corresponding to the lower cobound of the array along that codimension.
7446 @item @emph{See also}:
7447 @ref{UCOBOUND}, @ref{LBOUND}
7453 @section @code{LEADZ} --- Number of leading zero bits of an integer
7458 @item @emph{Description}:
7459 @code{LEADZ} returns the number of leading zero bits of an integer.
7461 @item @emph{Standard}:
7462 Fortran 2008 and later
7467 @item @emph{Syntax}:
7468 @code{RESULT = LEADZ(I)}
7470 @item @emph{Arguments}:
7471 @multitable @columnfractions .15 .70
7472 @item @var{I} @tab Shall be of type @code{INTEGER}.
7475 @item @emph{Return value}:
7476 The type of the return value is the default @code{INTEGER}.
7477 If all the bits of @code{I} are zero, the result value is @code{BIT_SIZE(I)}.
7479 @item @emph{Example}:
7482 WRITE (*,*) BIT_SIZE(1) ! prints 32
7483 WRITE (*,*) LEADZ(1) ! prints 31
7487 @item @emph{See also}:
7488 @ref{BIT_SIZE}, @ref{TRAILZ}, @ref{POPCNT}, @ref{POPPAR}
7494 @section @code{LEN} --- Length of a character entity
7496 @cindex string, length
7499 @item @emph{Description}:
7500 Returns the length of a character string. If @var{STRING} is an array,
7501 the length of an element of @var{STRING} is returned. Note that
7502 @var{STRING} need not be defined when this intrinsic is invoked, since
7503 only the length, not the content, of @var{STRING} is needed.
7505 @item @emph{Standard}:
7506 Fortran 77 and later, with @var{KIND} argument Fortran 2003 and later
7511 @item @emph{Syntax}:
7512 @code{L = LEN(STRING [, KIND])}
7514 @item @emph{Arguments}:
7515 @multitable @columnfractions .15 .70
7516 @item @var{STRING} @tab Shall be a scalar or array of type
7517 @code{CHARACTER}, with @code{INTENT(IN)}
7518 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
7519 expression indicating the kind parameter of the result.
7522 @item @emph{Return value}:
7523 The return value is of type @code{INTEGER} and of kind @var{KIND}. If
7524 @var{KIND} is absent, the return value is of default integer kind.
7527 @item @emph{Specific names}:
7528 @multitable @columnfractions .20 .20 .20 .25
7529 @item Name @tab Argument @tab Return type @tab Standard
7530 @item @code{LEN(STRING)} @tab @code{CHARACTER} @tab @code{INTEGER} @tab Fortran 77 and later
7534 @item @emph{See also}:
7535 @ref{LEN_TRIM}, @ref{ADJUSTL}, @ref{ADJUSTR}
7541 @section @code{LEN_TRIM} --- Length of a character entity without trailing blank characters
7543 @cindex string, length, without trailing whitespace
7546 @item @emph{Description}:
7547 Returns the length of a character string, ignoring any trailing blanks.
7549 @item @emph{Standard}:
7550 Fortran 95 and later, with @var{KIND} argument Fortran 2003 and later
7555 @item @emph{Syntax}:
7556 @code{RESULT = LEN_TRIM(STRING [, KIND])}
7558 @item @emph{Arguments}:
7559 @multitable @columnfractions .15 .70
7560 @item @var{STRING} @tab Shall be a scalar of type @code{CHARACTER},
7561 with @code{INTENT(IN)}
7562 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
7563 expression indicating the kind parameter of the result.
7566 @item @emph{Return value}:
7567 The return value is of type @code{INTEGER} and of kind @var{KIND}. If
7568 @var{KIND} is absent, the return value is of default integer kind.
7570 @item @emph{See also}:
7571 @ref{LEN}, @ref{ADJUSTL}, @ref{ADJUSTR}
7577 @section @code{LGE} --- Lexical greater than or equal
7579 @cindex lexical comparison of strings
7580 @cindex string, comparison
7583 @item @emph{Description}:
7584 Determines whether one string is lexically greater than or equal to
7585 another string, where the two strings are interpreted as containing
7586 ASCII character codes. If the String A and String B are not the same
7587 length, the shorter is compared as if spaces were appended to it to form
7588 a value that has the same length as the longer.
7590 In general, the lexical comparison intrinsics @code{LGE}, @code{LGT},
7591 @code{LLE}, and @code{LLT} differ from the corresponding intrinsic
7592 operators @code{.GE.}, @code{.GT.}, @code{.LE.}, and @code{.LT.}, in
7593 that the latter use the processor's character ordering (which is not
7594 ASCII on some targets), whereas the former always use the ASCII
7597 @item @emph{Standard}:
7598 Fortran 77 and later
7603 @item @emph{Syntax}:
7604 @code{RESULT = LGE(STRING_A, STRING_B)}
7606 @item @emph{Arguments}:
7607 @multitable @columnfractions .15 .70
7608 @item @var{STRING_A} @tab Shall be of default @code{CHARACTER} type.
7609 @item @var{STRING_B} @tab Shall be of default @code{CHARACTER} type.
7612 @item @emph{Return value}:
7613 Returns @code{.TRUE.} if @code{STRING_A >= STRING_B}, and @code{.FALSE.}
7614 otherwise, based on the ASCII ordering.
7616 @item @emph{Specific names}:
7617 @multitable @columnfractions .20 .20 .20 .25
7618 @item Name @tab Argument @tab Return type @tab Standard
7619 @item @code{LGE(STRING_A, STRING_B)} @tab @code{CHARACTER} @tab @code{LOGICAL} @tab Fortran 77 and later
7622 @item @emph{See also}:
7623 @ref{LGT}, @ref{LLE}, @ref{LLT}
7629 @section @code{LGT} --- Lexical greater than
7631 @cindex lexical comparison of strings
7632 @cindex string, comparison
7635 @item @emph{Description}:
7636 Determines whether one string is lexically greater than another string,
7637 where the two strings are interpreted as containing ASCII character
7638 codes. If the String A and String B are not the same length, the
7639 shorter is compared as if spaces were appended to it to form a value
7640 that has the same length as the longer.
7642 In general, the lexical comparison intrinsics @code{LGE}, @code{LGT},
7643 @code{LLE}, and @code{LLT} differ from the corresponding intrinsic
7644 operators @code{.GE.}, @code{.GT.}, @code{.LE.}, and @code{.LT.}, in
7645 that the latter use the processor's character ordering (which is not
7646 ASCII on some targets), whereas the former always use the ASCII
7649 @item @emph{Standard}:
7650 Fortran 77 and later
7655 @item @emph{Syntax}:
7656 @code{RESULT = LGT(STRING_A, STRING_B)}
7658 @item @emph{Arguments}:
7659 @multitable @columnfractions .15 .70
7660 @item @var{STRING_A} @tab Shall be of default @code{CHARACTER} type.
7661 @item @var{STRING_B} @tab Shall be of default @code{CHARACTER} type.
7664 @item @emph{Return value}:
7665 Returns @code{.TRUE.} if @code{STRING_A > STRING_B}, and @code{.FALSE.}
7666 otherwise, based on the ASCII ordering.
7668 @item @emph{Specific names}:
7669 @multitable @columnfractions .20 .20 .20 .25
7670 @item Name @tab Argument @tab Return type @tab Standard
7671 @item @code{LGT(STRING_A, STRING_B)} @tab @code{CHARACTER} @tab @code{LOGICAL} @tab Fortran 77 and later
7674 @item @emph{See also}:
7675 @ref{LGE}, @ref{LLE}, @ref{LLT}
7681 @section @code{LINK} --- Create a hard link
7683 @cindex file system, create link
7684 @cindex file system, hard link
7687 @item @emph{Description}:
7688 Makes a (hard) link from file @var{PATH1} to @var{PATH2}. A null
7689 character (@code{CHAR(0)}) can be used to mark the end of the names in
7690 @var{PATH1} and @var{PATH2}; otherwise, trailing blanks in the file
7691 names are ignored. If the @var{STATUS} argument is supplied, it
7692 contains 0 on success or a nonzero error code upon return; see
7695 This intrinsic is provided in both subroutine and function forms;
7696 however, only one form can be used in any given program unit.
7698 @item @emph{Standard}:
7702 Subroutine, function
7704 @item @emph{Syntax}:
7705 @multitable @columnfractions .80
7706 @item @code{CALL LINK(PATH1, PATH2 [, STATUS])}
7707 @item @code{STATUS = LINK(PATH1, PATH2)}
7710 @item @emph{Arguments}:
7711 @multitable @columnfractions .15 .70
7712 @item @var{PATH1} @tab Shall be of default @code{CHARACTER} type.
7713 @item @var{PATH2} @tab Shall be of default @code{CHARACTER} type.
7714 @item @var{STATUS} @tab (Optional) Shall be of default @code{INTEGER} type.
7717 @item @emph{See also}:
7718 @ref{SYMLNK}, @ref{UNLINK}
7724 @section @code{LLE} --- Lexical less than or equal
7726 @cindex lexical comparison of strings
7727 @cindex string, comparison
7730 @item @emph{Description}:
7731 Determines whether one string is lexically less than or equal to another
7732 string, where the two strings are interpreted as containing ASCII
7733 character codes. If the String A and String B are not the same length,
7734 the shorter is compared as if spaces were appended to it to form a value
7735 that has the same length as the longer.
7737 In general, the lexical comparison intrinsics @code{LGE}, @code{LGT},
7738 @code{LLE}, and @code{LLT} differ from the corresponding intrinsic
7739 operators @code{.GE.}, @code{.GT.}, @code{.LE.}, and @code{.LT.}, in
7740 that the latter use the processor's character ordering (which is not
7741 ASCII on some targets), whereas the former always use the ASCII
7744 @item @emph{Standard}:
7745 Fortran 77 and later
7750 @item @emph{Syntax}:
7751 @code{RESULT = LLE(STRING_A, STRING_B)}
7753 @item @emph{Arguments}:
7754 @multitable @columnfractions .15 .70
7755 @item @var{STRING_A} @tab Shall be of default @code{CHARACTER} type.
7756 @item @var{STRING_B} @tab Shall be of default @code{CHARACTER} type.
7759 @item @emph{Return value}:
7760 Returns @code{.TRUE.} if @code{STRING_A <= STRING_B}, and @code{.FALSE.}
7761 otherwise, based on the ASCII ordering.
7763 @item @emph{Specific names}:
7764 @multitable @columnfractions .20 .20 .20 .25
7765 @item Name @tab Argument @tab Return type @tab Standard
7766 @item @code{LLE(STRING_A, STRING_B)} @tab @code{CHARACTER} @tab @code{LOGICAL} @tab Fortran 77 and later
7769 @item @emph{See also}:
7770 @ref{LGE}, @ref{LGT}, @ref{LLT}
7776 @section @code{LLT} --- Lexical less than
7778 @cindex lexical comparison of strings
7779 @cindex string, comparison
7782 @item @emph{Description}:
7783 Determines whether one string is lexically less than another string,
7784 where the two strings are interpreted as containing ASCII character
7785 codes. If the String A and String B are not the same length, the
7786 shorter is compared as if spaces were appended to it to form a value
7787 that has the same length as the longer.
7789 In general, the lexical comparison intrinsics @code{LGE}, @code{LGT},
7790 @code{LLE}, and @code{LLT} differ from the corresponding intrinsic
7791 operators @code{.GE.}, @code{.GT.}, @code{.LE.}, and @code{.LT.}, in
7792 that the latter use the processor's character ordering (which is not
7793 ASCII on some targets), whereas the former always use the ASCII
7796 @item @emph{Standard}:
7797 Fortran 77 and later
7802 @item @emph{Syntax}:
7803 @code{RESULT = LLT(STRING_A, STRING_B)}
7805 @item @emph{Arguments}:
7806 @multitable @columnfractions .15 .70
7807 @item @var{STRING_A} @tab Shall be of default @code{CHARACTER} type.
7808 @item @var{STRING_B} @tab Shall be of default @code{CHARACTER} type.
7811 @item @emph{Return value}:
7812 Returns @code{.TRUE.} if @code{STRING_A < STRING_B}, and @code{.FALSE.}
7813 otherwise, based on the ASCII ordering.
7815 @item @emph{Specific names}:
7816 @multitable @columnfractions .20 .20 .20 .25
7817 @item Name @tab Argument @tab Return type @tab Standard
7818 @item @code{LLT(STRING_A, STRING_B)} @tab @code{CHARACTER} @tab @code{LOGICAL} @tab Fortran 77 and later
7821 @item @emph{See also}:
7822 @ref{LGE}, @ref{LGT}, @ref{LLE}
7828 @section @code{LNBLNK} --- Index of the last non-blank character in a string
7830 @cindex string, find non-blank character
7833 @item @emph{Description}:
7834 Returns the length of a character string, ignoring any trailing blanks.
7835 This is identical to the standard @code{LEN_TRIM} intrinsic, and is only
7836 included for backwards compatibility.
7838 @item @emph{Standard}:
7844 @item @emph{Syntax}:
7845 @code{RESULT = LNBLNK(STRING)}
7847 @item @emph{Arguments}:
7848 @multitable @columnfractions .15 .70
7849 @item @var{STRING} @tab Shall be a scalar of type @code{CHARACTER},
7850 with @code{INTENT(IN)}
7853 @item @emph{Return value}:
7854 The return value is of @code{INTEGER(kind=4)} type.
7856 @item @emph{See also}:
7857 @ref{INDEX intrinsic}, @ref{LEN_TRIM}
7863 @section @code{LOC} --- Returns the address of a variable
7865 @cindex location of a variable in memory
7868 @item @emph{Description}:
7869 @code{LOC(X)} returns the address of @var{X} as an integer.
7871 @item @emph{Standard}:
7877 @item @emph{Syntax}:
7878 @code{RESULT = LOC(X)}
7880 @item @emph{Arguments}:
7881 @multitable @columnfractions .15 .70
7882 @item @var{X} @tab Variable of any type.
7885 @item @emph{Return value}:
7886 The return value is of type @code{INTEGER}, with a @code{KIND}
7887 corresponding to the size (in bytes) of a memory address on the target
7890 @item @emph{Example}:
7897 end program test_loc
7904 @section @code{LOG} --- Natural logarithm function
7911 @cindex exponential function, inverse
7912 @cindex logarithm function
7913 @cindex natural logarithm function
7916 @item @emph{Description}:
7917 @code{LOG(X)} computes the natural logarithm of @var{X}, i.e. the
7918 logarithm to the base @math{e}.
7920 @item @emph{Standard}:
7921 Fortran 77 and later
7926 @item @emph{Syntax}:
7927 @code{RESULT = LOG(X)}
7929 @item @emph{Arguments}:
7930 @multitable @columnfractions .15 .70
7931 @item @var{X} @tab The type shall be @code{REAL} or
7935 @item @emph{Return value}:
7936 The return value is of type @code{REAL} or @code{COMPLEX}.
7937 The kind type parameter is the same as @var{X}.
7938 If @var{X} is @code{COMPLEX}, the imaginary part @math{\omega} is in the range
7939 @math{-\pi \leq \omega \leq \pi}.
7941 @item @emph{Example}:
7944 real(8) :: x = 2.7182818284590451_8
7945 complex :: z = (1.0, 2.0)
7946 x = log(x) ! will yield (approximately) 1
7948 end program test_log
7951 @item @emph{Specific names}:
7952 @multitable @columnfractions .20 .20 .20 .25
7953 @item Name @tab Argument @tab Return type @tab Standard
7954 @item @code{ALOG(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab f95, gnu
7955 @item @code{DLOG(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab f95, gnu
7956 @item @code{CLOG(X)} @tab @code{COMPLEX(4) X} @tab @code{COMPLEX(4)} @tab f95, gnu
7957 @item @code{ZLOG(X)} @tab @code{COMPLEX(8) X} @tab @code{COMPLEX(8)} @tab f95, gnu
7958 @item @code{CDLOG(X)} @tab @code{COMPLEX(8) X} @tab @code{COMPLEX(8)} @tab f95, gnu
7965 @section @code{LOG10} --- Base 10 logarithm function
7969 @cindex exponential function, inverse
7970 @cindex logarithm function with base 10
7971 @cindex base 10 logarithm function
7974 @item @emph{Description}:
7975 @code{LOG10(X)} computes the base 10 logarithm of @var{X}.
7977 @item @emph{Standard}:
7978 Fortran 77 and later
7983 @item @emph{Syntax}:
7984 @code{RESULT = LOG10(X)}
7986 @item @emph{Arguments}:
7987 @multitable @columnfractions .15 .70
7988 @item @var{X} @tab The type shall be @code{REAL}.
7991 @item @emph{Return value}:
7992 The return value is of type @code{REAL} or @code{COMPLEX}.
7993 The kind type parameter is the same as @var{X}.
7995 @item @emph{Example}:
7998 real(8) :: x = 10.0_8
8000 end program test_log10
8003 @item @emph{Specific names}:
8004 @multitable @columnfractions .20 .20 .20 .25
8005 @item Name @tab Argument @tab Return type @tab Standard
8006 @item @code{ALOG10(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab Fortran 95 and later
8007 @item @code{DLOG10(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab Fortran 95 and later
8014 @section @code{LOG_GAMMA} --- Logarithm of the Gamma function
8019 @cindex Gamma function, logarithm of
8022 @item @emph{Description}:
8023 @code{LOG_GAMMA(X)} computes the natural logarithm of the absolute value
8024 of the Gamma (@math{\Gamma}) function.
8026 @item @emph{Standard}:
8027 Fortran 2008 and later
8032 @item @emph{Syntax}:
8033 @code{X = LOG_GAMMA(X)}
8035 @item @emph{Arguments}:
8036 @multitable @columnfractions .15 .70
8037 @item @var{X} @tab Shall be of type @code{REAL} and neither zero
8038 nor a negative integer.
8041 @item @emph{Return value}:
8042 The return value is of type @code{REAL} of the same kind as @var{X}.
8044 @item @emph{Example}:
8046 program test_log_gamma
8048 x = lgamma(x) ! returns 0.0
8049 end program test_log_gamma
8052 @item @emph{Specific names}:
8053 @multitable @columnfractions .20 .20 .20 .25
8054 @item Name @tab Argument @tab Return type @tab Standard
8055 @item @code{LGAMMA(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab GNU Extension
8056 @item @code{ALGAMA(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab GNU Extension
8057 @item @code{DLGAMA(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU Extension
8060 @item @emph{See also}:
8061 Gamma function: @ref{GAMMA}
8068 @section @code{LOGICAL} --- Convert to logical type
8070 @cindex conversion, to logical
8073 @item @emph{Description}:
8074 Converts one kind of @code{LOGICAL} variable to another.
8076 @item @emph{Standard}:
8077 Fortran 95 and later
8082 @item @emph{Syntax}:
8083 @code{RESULT = LOGICAL(L [, KIND])}
8085 @item @emph{Arguments}:
8086 @multitable @columnfractions .15 .70
8087 @item @var{L} @tab The type shall be @code{LOGICAL}.
8088 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
8089 expression indicating the kind parameter of the result.
8092 @item @emph{Return value}:
8093 The return value is a @code{LOGICAL} value equal to @var{L}, with a
8094 kind corresponding to @var{KIND}, or of the default logical kind if
8095 @var{KIND} is not given.
8097 @item @emph{See also}:
8098 @ref{INT}, @ref{REAL}, @ref{CMPLX}
8104 @section @code{LONG} --- Convert to integer type
8106 @cindex conversion, to integer
8109 @item @emph{Description}:
8110 Convert to a @code{KIND=4} integer type, which is the same size as a C
8111 @code{long} integer. This is equivalent to the standard @code{INT}
8112 intrinsic with an optional argument of @code{KIND=4}, and is only
8113 included for backwards compatibility.
8115 @item @emph{Standard}:
8121 @item @emph{Syntax}:
8122 @code{RESULT = LONG(A)}
8124 @item @emph{Arguments}:
8125 @multitable @columnfractions .15 .70
8126 @item @var{A} @tab Shall be of type @code{INTEGER},
8127 @code{REAL}, or @code{COMPLEX}.
8130 @item @emph{Return value}:
8131 The return value is a @code{INTEGER(4)} variable.
8133 @item @emph{See also}:
8134 @ref{INT}, @ref{INT2}, @ref{INT8}
8140 @section @code{LSHIFT} --- Left shift bits
8142 @cindex bits, shift left
8145 @item @emph{Description}:
8146 @code{LSHIFT} returns a value corresponding to @var{I} with all of the
8147 bits shifted left by @var{SHIFT} places. If the absolute value of
8148 @var{SHIFT} is greater than @code{BIT_SIZE(I)}, the value is undefined.
8149 Bits shifted out from the left end are lost; zeros are shifted in from
8152 This function has been superseded by the @code{ISHFT} intrinsic, which
8153 is standard in Fortran 95 and later, and the @code{SHIFTL} intrinsic,
8154 which is standard in Fortran 2008 and later.
8156 @item @emph{Standard}:
8162 @item @emph{Syntax}:
8163 @code{RESULT = LSHIFT(I, SHIFT)}
8165 @item @emph{Arguments}:
8166 @multitable @columnfractions .15 .70
8167 @item @var{I} @tab The type shall be @code{INTEGER}.
8168 @item @var{SHIFT} @tab The type shall be @code{INTEGER}.
8171 @item @emph{Return value}:
8172 The return value is of type @code{INTEGER} and of the same kind as
8175 @item @emph{See also}:
8176 @ref{ISHFT}, @ref{ISHFTC}, @ref{RSHIFT}, @ref{SHIFTA}, @ref{SHIFTL},
8184 @section @code{LSTAT} --- Get file status
8186 @cindex file system, file status
8189 @item @emph{Description}:
8190 @code{LSTAT} is identical to @ref{STAT}, except that if path is a
8191 symbolic link, then the link itself is statted, not the file that it
8194 The elements in @code{VALUES} are the same as described by @ref{STAT}.
8196 This intrinsic is provided in both subroutine and function forms;
8197 however, only one form can be used in any given program unit.
8199 @item @emph{Standard}:
8203 Subroutine, function
8205 @item @emph{Syntax}:
8206 @multitable @columnfractions .80
8207 @item @code{CALL LSTAT(NAME, VALUES [, STATUS])}
8208 @item @code{STATUS = LSTAT(NAME, VALUES)}
8211 @item @emph{Arguments}:
8212 @multitable @columnfractions .15 .70
8213 @item @var{NAME} @tab The type shall be @code{CHARACTER} of the default
8214 kind, a valid path within the file system.
8215 @item @var{VALUES} @tab The type shall be @code{INTEGER(4), DIMENSION(13)}.
8216 @item @var{STATUS} @tab (Optional) status flag of type @code{INTEGER(4)}.
8217 Returns 0 on success and a system specific error code otherwise.
8220 @item @emph{Example}:
8221 See @ref{STAT} for an example.
8223 @item @emph{See also}:
8224 To stat an open file: @ref{FSTAT}, to stat a file: @ref{STAT}
8230 @section @code{LTIME} --- Convert time to local time info
8232 @cindex time, conversion to local time info
8235 @item @emph{Description}:
8236 Given a system time value @var{TIME} (as provided by the @code{TIME8}
8237 intrinsic), fills @var{VALUES} with values extracted from it appropriate
8238 to the local time zone using @code{localtime(3)}.
8240 @item @emph{Standard}:
8246 @item @emph{Syntax}:
8247 @code{CALL LTIME(TIME, VALUES)}
8249 @item @emph{Arguments}:
8250 @multitable @columnfractions .15 .70
8251 @item @var{TIME} @tab An @code{INTEGER} scalar expression
8252 corresponding to a system time, with @code{INTENT(IN)}.
8253 @item @var{VALUES} @tab A default @code{INTEGER} array with 9 elements,
8254 with @code{INTENT(OUT)}.
8257 @item @emph{Return value}:
8258 The elements of @var{VALUES} are assigned as follows:
8260 @item Seconds after the minute, range 0--59 or 0--61 to allow for leap
8262 @item Minutes after the hour, range 0--59
8263 @item Hours past midnight, range 0--23
8264 @item Day of month, range 0--31
8265 @item Number of months since January, range 0--12
8266 @item Years since 1900
8267 @item Number of days since Sunday, range 0--6
8268 @item Days since January 1
8269 @item Daylight savings indicator: positive if daylight savings is in
8270 effect, zero if not, and negative if the information is not available.
8273 @item @emph{See also}:
8274 @ref{CTIME}, @ref{GMTIME}, @ref{TIME}, @ref{TIME8}
8281 @section @code{MALLOC} --- Allocate dynamic memory
8283 @cindex pointer, cray
8286 @item @emph{Description}:
8287 @code{MALLOC(SIZE)} allocates @var{SIZE} bytes of dynamic memory and
8288 returns the address of the allocated memory. The @code{MALLOC} intrinsic
8289 is an extension intended to be used with Cray pointers, and is provided
8290 in GNU Fortran to allow the user to compile legacy code. For new code
8291 using Fortran 95 pointers, the memory allocation intrinsic is
8294 @item @emph{Standard}:
8300 @item @emph{Syntax}:
8301 @code{PTR = MALLOC(SIZE)}
8303 @item @emph{Arguments}:
8304 @multitable @columnfractions .15 .70
8305 @item @var{SIZE} @tab The type shall be @code{INTEGER}.
8308 @item @emph{Return value}:
8309 The return value is of type @code{INTEGER(K)}, with @var{K} such that
8310 variables of type @code{INTEGER(K)} have the same size as
8311 C pointers (@code{sizeof(void *)}).
8313 @item @emph{Example}:
8314 The following example demonstrates the use of @code{MALLOC} and
8315 @code{FREE} with Cray pointers.
8324 ptr_x = malloc(20*8)
8326 x(i) = sqrt(1.0d0 / i)
8334 end program test_malloc
8337 @item @emph{See also}:
8344 @section @code{MASKL} --- Left justified mask
8346 @cindex mask, left justified
8349 @item @emph{Description}:
8350 @code{MASKL(I[, KIND])} has its leftmost @var{I} bits set to 1, and the
8351 remaining bits set to 0.
8353 @item @emph{Standard}:
8354 Fortran 2008 and later
8359 @item @emph{Syntax}:
8360 @code{RESULT = MASKL(I[, KIND])}
8362 @item @emph{Arguments}:
8363 @multitable @columnfractions .15 .70
8364 @item @var{I} @tab Shall be of type @code{INTEGER}.
8365 @item @var{KIND} @tab Shall be a scalar constant expression of type
8369 @item @emph{Return value}:
8370 The return value is of type @code{INTEGER}. If @var{KIND} is present, it
8371 specifies the kind value of the return type; otherwise, it is of the
8372 default integer kind.
8374 @item @emph{See also}:
8381 @section @code{MASKR} --- Right justified mask
8383 @cindex mask, right justified
8386 @item @emph{Description}:
8387 @code{MASKL(I[, KIND])} has its rightmost @var{I} bits set to 1, and the
8388 remaining bits set to 0.
8390 @item @emph{Standard}:
8391 Fortran 2008 and later
8396 @item @emph{Syntax}:
8397 @code{RESULT = MASKR(I[, KIND])}
8399 @item @emph{Arguments}:
8400 @multitable @columnfractions .15 .70
8401 @item @var{I} @tab Shall be of type @code{INTEGER}.
8402 @item @var{KIND} @tab Shall be a scalar constant expression of type
8406 @item @emph{Return value}:
8407 The return value is of type @code{INTEGER}. If @var{KIND} is present, it
8408 specifies the kind value of the return type; otherwise, it is of the
8409 default integer kind.
8411 @item @emph{See also}:
8418 @section @code{MATMUL} --- matrix multiplication
8420 @cindex matrix multiplication
8421 @cindex product, matrix
8424 @item @emph{Description}:
8425 Performs a matrix multiplication on numeric or logical arguments.
8427 @item @emph{Standard}:
8428 Fortran 95 and later
8431 Transformational function
8433 @item @emph{Syntax}:
8434 @code{RESULT = MATMUL(MATRIX_A, MATRIX_B)}
8436 @item @emph{Arguments}:
8437 @multitable @columnfractions .15 .70
8438 @item @var{MATRIX_A} @tab An array of @code{INTEGER},
8439 @code{REAL}, @code{COMPLEX}, or @code{LOGICAL} type, with a rank of
8441 @item @var{MATRIX_B} @tab An array of @code{INTEGER},
8442 @code{REAL}, or @code{COMPLEX} type if @var{MATRIX_A} is of a numeric
8443 type; otherwise, an array of @code{LOGICAL} type. The rank shall be one
8444 or two, and the first (or only) dimension of @var{MATRIX_B} shall be
8445 equal to the last (or only) dimension of @var{MATRIX_A}.
8448 @item @emph{Return value}:
8449 The matrix product of @var{MATRIX_A} and @var{MATRIX_B}. The type and
8450 kind of the result follow the usual type and kind promotion rules, as
8451 for the @code{*} or @code{.AND.} operators.
8453 @item @emph{See also}:
8459 @section @code{MAX} --- Maximum value of an argument list
8466 @cindex maximum value
8469 @item @emph{Description}:
8470 Returns the argument with the largest (most positive) value.
8472 @item @emph{Standard}:
8473 Fortran 77 and later
8478 @item @emph{Syntax}:
8479 @code{RESULT = MAX(A1, A2 [, A3 [, ...]])}
8481 @item @emph{Arguments}:
8482 @multitable @columnfractions .15 .70
8483 @item @var{A1} @tab The type shall be @code{INTEGER} or
8485 @item @var{A2}, @var{A3}, ... @tab An expression of the same type and kind
8486 as @var{A1}. (As a GNU extension, arguments of different kinds are
8490 @item @emph{Return value}:
8491 The return value corresponds to the maximum value among the arguments,
8492 and has the same type and kind as the first argument.
8494 @item @emph{Specific names}:
8495 @multitable @columnfractions .20 .20 .20 .25
8496 @item Name @tab Argument @tab Return type @tab Standard
8497 @item @code{MAX0(A1)} @tab @code{INTEGER(4) A1} @tab @code{INTEGER(4)} @tab Fortran 77 and later
8498 @item @code{AMAX0(A1)} @tab @code{INTEGER(4) A1} @tab @code{REAL(MAX(X))} @tab Fortran 77 and later
8499 @item @code{MAX1(A1)} @tab @code{REAL A1} @tab @code{INT(MAX(X))} @tab Fortran 77 and later
8500 @item @code{AMAX1(A1)} @tab @code{REAL(4) A1} @tab @code{REAL(4)} @tab Fortran 77 and later
8501 @item @code{DMAX1(A1)} @tab @code{REAL(8) A1} @tab @code{REAL(8)} @tab Fortran 77 and later
8504 @item @emph{See also}:
8505 @ref{MAXLOC} @ref{MAXVAL}, @ref{MIN}
8512 @section @code{MAXEXPONENT} --- Maximum exponent of a real kind
8513 @fnindex MAXEXPONENT
8514 @cindex model representation, maximum exponent
8517 @item @emph{Description}:
8518 @code{MAXEXPONENT(X)} returns the maximum exponent in the model of the
8521 @item @emph{Standard}:
8522 Fortran 95 and later
8527 @item @emph{Syntax}:
8528 @code{RESULT = MAXEXPONENT(X)}
8530 @item @emph{Arguments}:
8531 @multitable @columnfractions .15 .70
8532 @item @var{X} @tab Shall be of type @code{REAL}.
8535 @item @emph{Return value}:
8536 The return value is of type @code{INTEGER} and of the default integer
8539 @item @emph{Example}:
8545 print *, minexponent(x), maxexponent(x)
8546 print *, minexponent(y), maxexponent(y)
8547 end program exponents
8554 @section @code{MAXLOC} --- Location of the maximum value within an array
8556 @cindex array, location of maximum element
8559 @item @emph{Description}:
8560 Determines the location of the element in the array with the maximum
8561 value, or, if the @var{DIM} argument is supplied, determines the
8562 locations of the maximum element along each row of the array in the
8563 @var{DIM} direction. If @var{MASK} is present, only the elements for
8564 which @var{MASK} is @code{.TRUE.} are considered. If more than one
8565 element in the array has the maximum value, the location returned is
8566 that of the first such element in array element order. If the array has
8567 zero size, or all of the elements of @var{MASK} are @code{.FALSE.}, then
8568 the result is an array of zeroes. Similarly, if @var{DIM} is supplied
8569 and all of the elements of @var{MASK} along a given row are zero, the
8570 result value for that row is zero.
8572 @item @emph{Standard}:
8573 Fortran 95 and later
8576 Transformational function
8578 @item @emph{Syntax}:
8579 @multitable @columnfractions .80
8580 @item @code{RESULT = MAXLOC(ARRAY, DIM [, MASK])}
8581 @item @code{RESULT = MAXLOC(ARRAY [, MASK])}
8584 @item @emph{Arguments}:
8585 @multitable @columnfractions .15 .70
8586 @item @var{ARRAY} @tab Shall be an array of type @code{INTEGER} or
8588 @item @var{DIM} @tab (Optional) Shall be a scalar of type
8589 @code{INTEGER}, with a value between one and the rank of @var{ARRAY},
8590 inclusive. It may not be an optional dummy argument.
8591 @item @var{MASK} @tab Shall be an array of type @code{LOGICAL},
8592 and conformable with @var{ARRAY}.
8595 @item @emph{Return value}:
8596 If @var{DIM} is absent, the result is a rank-one array with a length
8597 equal to the rank of @var{ARRAY}. If @var{DIM} is present, the result
8598 is an array with a rank one less than the rank of @var{ARRAY}, and a
8599 size corresponding to the size of @var{ARRAY} with the @var{DIM}
8600 dimension removed. If @var{DIM} is present and @var{ARRAY} has a rank
8601 of one, the result is a scalar. In all cases, the result is of default
8602 @code{INTEGER} type.
8604 @item @emph{See also}:
8605 @ref{MAX}, @ref{MAXVAL}
8612 @section @code{MAXVAL} --- Maximum value of an array
8614 @cindex array, maximum value
8615 @cindex maximum value
8618 @item @emph{Description}:
8619 Determines the maximum value of the elements in an array value, or, if
8620 the @var{DIM} argument is supplied, determines the maximum value along
8621 each row of the array in the @var{DIM} direction. If @var{MASK} is
8622 present, only the elements for which @var{MASK} is @code{.TRUE.} are
8623 considered. If the array has zero size, or all of the elements of
8624 @var{MASK} are @code{.FALSE.}, then the result is @code{-HUGE(ARRAY)}
8625 if @var{ARRAY} is numeric, or a string of nulls if @var{ARRAY} is of character
8628 @item @emph{Standard}:
8629 Fortran 95 and later
8632 Transformational function
8634 @item @emph{Syntax}:
8635 @multitable @columnfractions .80
8636 @item @code{RESULT = MAXVAL(ARRAY, DIM [, MASK])}
8637 @item @code{RESULT = MAXVAL(ARRAY [, MASK])}
8640 @item @emph{Arguments}:
8641 @multitable @columnfractions .15 .70
8642 @item @var{ARRAY} @tab Shall be an array of type @code{INTEGER} or
8644 @item @var{DIM} @tab (Optional) Shall be a scalar of type
8645 @code{INTEGER}, with a value between one and the rank of @var{ARRAY},
8646 inclusive. It may not be an optional dummy argument.
8647 @item @var{MASK} @tab Shall be an array of type @code{LOGICAL},
8648 and conformable with @var{ARRAY}.
8651 @item @emph{Return value}:
8652 If @var{DIM} is absent, or if @var{ARRAY} has a rank of one, the result
8653 is a scalar. If @var{DIM} is present, the result is an array with a
8654 rank one less than the rank of @var{ARRAY}, and a size corresponding to
8655 the size of @var{ARRAY} with the @var{DIM} dimension removed. In all
8656 cases, the result is of the same type and kind as @var{ARRAY}.
8658 @item @emph{See also}:
8659 @ref{MAX}, @ref{MAXLOC}
8665 @section @code{MCLOCK} --- Time function
8667 @cindex time, clock ticks
8671 @item @emph{Description}:
8672 Returns the number of clock ticks since the start of the process, based
8673 on the function @code{clock(3)} in the C standard library.
8675 This intrinsic is not fully portable, such as to systems with 32-bit
8676 @code{INTEGER} types but supporting times wider than 32 bits. Therefore,
8677 the values returned by this intrinsic might be, or become, negative, or
8678 numerically less than previous values, during a single run of the
8681 @item @emph{Standard}:
8687 @item @emph{Syntax}:
8688 @code{RESULT = MCLOCK()}
8690 @item @emph{Return value}:
8691 The return value is a scalar of type @code{INTEGER(4)}, equal to the
8692 number of clock ticks since the start of the process, or @code{-1} if
8693 the system does not support @code{clock(3)}.
8695 @item @emph{See also}:
8696 @ref{CTIME}, @ref{GMTIME}, @ref{LTIME}, @ref{MCLOCK}, @ref{TIME}
8703 @section @code{MCLOCK8} --- Time function (64-bit)
8705 @cindex time, clock ticks
8709 @item @emph{Description}:
8710 Returns the number of clock ticks since the start of the process, based
8711 on the function @code{clock(3)} in the C standard library.
8713 @emph{Warning:} this intrinsic does not increase the range of the timing
8714 values over that returned by @code{clock(3)}. On a system with a 32-bit
8715 @code{clock(3)}, @code{MCLOCK8} will return a 32-bit value, even though
8716 it is converted to a 64-bit @code{INTEGER(8)} value. That means
8717 overflows of the 32-bit value can still occur. Therefore, the values
8718 returned by this intrinsic might be or become negative or numerically
8719 less than previous values during a single run of the compiled program.
8721 @item @emph{Standard}:
8727 @item @emph{Syntax}:
8728 @code{RESULT = MCLOCK8()}
8730 @item @emph{Return value}:
8731 The return value is a scalar of type @code{INTEGER(8)}, equal to the
8732 number of clock ticks since the start of the process, or @code{-1} if
8733 the system does not support @code{clock(3)}.
8735 @item @emph{See also}:
8736 @ref{CTIME}, @ref{GMTIME}, @ref{LTIME}, @ref{MCLOCK}, @ref{TIME8}
8743 @section @code{MERGE} --- Merge variables
8745 @cindex array, merge arrays
8746 @cindex array, combine arrays
8749 @item @emph{Description}:
8750 Select values from two arrays according to a logical mask. The result
8751 is equal to @var{TSOURCE} if @var{MASK} is @code{.TRUE.}, or equal to
8752 @var{FSOURCE} if it is @code{.FALSE.}.
8754 @item @emph{Standard}:
8755 Fortran 95 and later
8760 @item @emph{Syntax}:
8761 @code{RESULT = MERGE(TSOURCE, FSOURCE, MASK)}
8763 @item @emph{Arguments}:
8764 @multitable @columnfractions .15 .70
8765 @item @var{TSOURCE} @tab May be of any type.
8766 @item @var{FSOURCE} @tab Shall be of the same type and type parameters
8768 @item @var{MASK} @tab Shall be of type @code{LOGICAL}.
8771 @item @emph{Return value}:
8772 The result is of the same type and type parameters as @var{TSOURCE}.
8779 @section @code{MERGE_BITS} --- Merge of bits under mask
8784 @item @emph{Description}:
8785 @code{MERGE_BITS(I, J, MASK)} merges the bits of @var{I} and @var{J}
8786 as determined by the mask. The i-th bit of the result is equal to the
8787 i-th bit of @var{I} if the i-th bit of @var{MASK} is 1; it is equal to
8788 the i-th bit of @var{J} otherwise.
8790 @item @emph{Standard}:
8791 Fortran 2008 and later
8796 @item @emph{Syntax}:
8797 @code{RESULT = MERGE_BITS(I, J, MASK)}
8799 @item @emph{Arguments}:
8800 @multitable @columnfractions .15 .70
8801 @item @var{I} @tab Shall be of type @code{INTEGER}.
8802 @item @var{J} @tab Shall be of type @code{INTEGER} and of the same
8804 @item @var{MASK} @tab Shall be of type @code{INTEGER} and of the same
8808 @item @emph{Return value}:
8809 The result is of the same type and kind as @var{I}.
8816 @section @code{MIN} --- Minimum value of an argument list
8823 @cindex minimum value
8826 @item @emph{Description}:
8827 Returns the argument with the smallest (most negative) value.
8829 @item @emph{Standard}:
8830 Fortran 77 and later
8835 @item @emph{Syntax}:
8836 @code{RESULT = MIN(A1, A2 [, A3, ...])}
8838 @item @emph{Arguments}:
8839 @multitable @columnfractions .15 .70
8840 @item @var{A1} @tab The type shall be @code{INTEGER} or
8842 @item @var{A2}, @var{A3}, ... @tab An expression of the same type and kind
8843 as @var{A1}. (As a GNU extension, arguments of different kinds are
8847 @item @emph{Return value}:
8848 The return value corresponds to the maximum value among the arguments,
8849 and has the same type and kind as the first argument.
8851 @item @emph{Specific names}:
8852 @multitable @columnfractions .20 .20 .20 .25
8853 @item Name @tab Argument @tab Return type @tab Standard
8854 @item @code{MIN0(A1)} @tab @code{INTEGER(4) A1} @tab @code{INTEGER(4)} @tab Fortran 77 and later
8855 @item @code{AMIN0(A1)} @tab @code{INTEGER(4) A1} @tab @code{REAL(4)} @tab Fortran 77 and later
8856 @item @code{MIN1(A1)} @tab @code{REAL A1} @tab @code{INTEGER(4)} @tab Fortran 77 and later
8857 @item @code{AMIN1(A1)} @tab @code{REAL(4) A1} @tab @code{REAL(4)} @tab Fortran 77 and later
8858 @item @code{DMIN1(A1)} @tab @code{REAL(8) A1} @tab @code{REAL(8)} @tab Fortran 77 and later
8861 @item @emph{See also}:
8862 @ref{MAX}, @ref{MINLOC}, @ref{MINVAL}
8868 @section @code{MINEXPONENT} --- Minimum exponent of a real kind
8869 @fnindex MINEXPONENT
8870 @cindex model representation, minimum exponent
8873 @item @emph{Description}:
8874 @code{MINEXPONENT(X)} returns the minimum exponent in the model of the
8877 @item @emph{Standard}:
8878 Fortran 95 and later
8883 @item @emph{Syntax}:
8884 @code{RESULT = MINEXPONENT(X)}
8886 @item @emph{Arguments}:
8887 @multitable @columnfractions .15 .70
8888 @item @var{X} @tab Shall be of type @code{REAL}.
8891 @item @emph{Return value}:
8892 The return value is of type @code{INTEGER} and of the default integer
8895 @item @emph{Example}:
8896 See @code{MAXEXPONENT} for an example.
8902 @section @code{MINLOC} --- Location of the minimum value within an array
8904 @cindex array, location of minimum element
8907 @item @emph{Description}:
8908 Determines the location of the element in the array with the minimum
8909 value, or, if the @var{DIM} argument is supplied, determines the
8910 locations of the minimum element along each row of the array in the
8911 @var{DIM} direction. If @var{MASK} is present, only the elements for
8912 which @var{MASK} is @code{.TRUE.} are considered. If more than one
8913 element in the array has the minimum value, the location returned is
8914 that of the first such element in array element order. If the array has
8915 zero size, or all of the elements of @var{MASK} are @code{.FALSE.}, then
8916 the result is an array of zeroes. Similarly, if @var{DIM} is supplied
8917 and all of the elements of @var{MASK} along a given row are zero, the
8918 result value for that row is zero.
8920 @item @emph{Standard}:
8921 Fortran 95 and later
8924 Transformational function
8926 @item @emph{Syntax}:
8927 @multitable @columnfractions .80
8928 @item @code{RESULT = MINLOC(ARRAY, DIM [, MASK])}
8929 @item @code{RESULT = MINLOC(ARRAY [, MASK])}
8932 @item @emph{Arguments}:
8933 @multitable @columnfractions .15 .70
8934 @item @var{ARRAY} @tab Shall be an array of type @code{INTEGER} or
8936 @item @var{DIM} @tab (Optional) Shall be a scalar of type
8937 @code{INTEGER}, with a value between one and the rank of @var{ARRAY},
8938 inclusive. It may not be an optional dummy argument.
8939 @item @var{MASK} @tab Shall be an array of type @code{LOGICAL},
8940 and conformable with @var{ARRAY}.
8943 @item @emph{Return value}:
8944 If @var{DIM} is absent, the result is a rank-one array with a length
8945 equal to the rank of @var{ARRAY}. If @var{DIM} is present, the result
8946 is an array with a rank one less than the rank of @var{ARRAY}, and a
8947 size corresponding to the size of @var{ARRAY} with the @var{DIM}
8948 dimension removed. If @var{DIM} is present and @var{ARRAY} has a rank
8949 of one, the result is a scalar. In all cases, the result is of default
8950 @code{INTEGER} type.
8952 @item @emph{See also}:
8953 @ref{MIN}, @ref{MINVAL}
8960 @section @code{MINVAL} --- Minimum value of an array
8962 @cindex array, minimum value
8963 @cindex minimum value
8966 @item @emph{Description}:
8967 Determines the minimum value of the elements in an array value, or, if
8968 the @var{DIM} argument is supplied, determines the minimum value along
8969 each row of the array in the @var{DIM} direction. If @var{MASK} is
8970 present, only the elements for which @var{MASK} is @code{.TRUE.} are
8971 considered. If the array has zero size, or all of the elements of
8972 @var{MASK} are @code{.FALSE.}, then the result is @code{HUGE(ARRAY)} if
8973 @var{ARRAY} is numeric, or a string of @code{CHAR(255)} characters if
8974 @var{ARRAY} is of character type.
8976 @item @emph{Standard}:
8977 Fortran 95 and later
8980 Transformational function
8982 @item @emph{Syntax}:
8983 @multitable @columnfractions .80
8984 @item @code{RESULT = MINVAL(ARRAY, DIM [, MASK])}
8985 @item @code{RESULT = MINVAL(ARRAY [, MASK])}
8988 @item @emph{Arguments}:
8989 @multitable @columnfractions .15 .70
8990 @item @var{ARRAY} @tab Shall be an array of type @code{INTEGER} or
8992 @item @var{DIM} @tab (Optional) Shall be a scalar of type
8993 @code{INTEGER}, with a value between one and the rank of @var{ARRAY},
8994 inclusive. It may not be an optional dummy argument.
8995 @item @var{MASK} @tab Shall be an array of type @code{LOGICAL},
8996 and conformable with @var{ARRAY}.
8999 @item @emph{Return value}:
9000 If @var{DIM} is absent, or if @var{ARRAY} has a rank of one, the result
9001 is a scalar. If @var{DIM} is present, the result is an array with a
9002 rank one less than the rank of @var{ARRAY}, and a size corresponding to
9003 the size of @var{ARRAY} with the @var{DIM} dimension removed. In all
9004 cases, the result is of the same type and kind as @var{ARRAY}.
9006 @item @emph{See also}:
9007 @ref{MIN}, @ref{MINLOC}
9014 @section @code{MOD} --- Remainder function
9019 @cindex division, remainder
9022 @item @emph{Description}:
9023 @code{MOD(A,P)} computes the remainder of the division of A by P@.
9025 @item @emph{Standard}:
9026 Fortran 77 and later
9031 @item @emph{Syntax}:
9032 @code{RESULT = MOD(A, P)}
9034 @item @emph{Arguments}:
9035 @multitable @columnfractions .15 .70
9036 @item @var{A} @tab Shall be a scalar of type @code{INTEGER} or @code{REAL}.
9037 @item @var{P} @tab Shall be a scalar of the same type and kind as @var{A}
9038 and not equal to zero.
9041 @item @emph{Return value}:
9042 The return value is the result of @code{A - (INT(A/P) * P)}. The type
9043 and kind of the return value is the same as that of the arguments. The
9044 returned value has the same sign as A and a magnitude less than the
9047 @item @emph{Example}:
9051 print *, mod(17.5,5.5)
9052 print *, mod(17.5d0,5.5)
9053 print *, mod(17.5,5.5d0)
9056 print *, mod(-17.5,5.5)
9057 print *, mod(-17.5d0,5.5)
9058 print *, mod(-17.5,5.5d0)
9061 print *, mod(17.5,-5.5)
9062 print *, mod(17.5d0,-5.5)
9063 print *, mod(17.5,-5.5d0)
9064 end program test_mod
9067 @item @emph{Specific names}:
9068 @multitable @columnfractions .20 .20 .20 .25
9069 @item Name @tab Arguments @tab Return type @tab Standard
9070 @item @code{MOD(A,P)} @tab @code{INTEGER A,P} @tab @code{INTEGER} @tab Fortran 95 and later
9071 @item @code{AMOD(A,P)} @tab @code{REAL(4) A,P} @tab @code{REAL(4)} @tab Fortran 95 and later
9072 @item @code{DMOD(A,P)} @tab @code{REAL(8) A,P} @tab @code{REAL(8)} @tab Fortran 95 and later
9075 @item @emph{See also}:
9083 @section @code{MODULO} --- Modulo function
9086 @cindex division, modulo
9089 @item @emph{Description}:
9090 @code{MODULO(A,P)} computes the @var{A} modulo @var{P}.
9092 @item @emph{Standard}:
9093 Fortran 95 and later
9098 @item @emph{Syntax}:
9099 @code{RESULT = MODULO(A, P)}
9101 @item @emph{Arguments}:
9102 @multitable @columnfractions .15 .70
9103 @item @var{A} @tab Shall be a scalar of type @code{INTEGER} or @code{REAL}.
9104 @item @var{P} @tab Shall be a scalar of the same type and kind as @var{A}.
9105 It shall not be zero.
9108 @item @emph{Return value}:
9109 The type and kind of the result are those of the arguments.
9111 @item If @var{A} and @var{P} are of type @code{INTEGER}:
9112 @code{MODULO(A,P)} has the value @var{R} such that @code{A=Q*P+R}, where
9113 @var{Q} is an integer and @var{R} is between 0 (inclusive) and @var{P}
9115 @item If @var{A} and @var{P} are of type @code{REAL}:
9116 @code{MODULO(A,P)} has the value of @code{A - FLOOR (A / P) * P}.
9118 The returned value has the same sign as P and a magnitude less than
9121 @item @emph{Example}:
9124 print *, modulo(17,3)
9125 print *, modulo(17.5,5.5)
9127 print *, modulo(-17,3)
9128 print *, modulo(-17.5,5.5)
9130 print *, modulo(17,-3)
9131 print *, modulo(17.5,-5.5)
9135 @item @emph{See also}:
9143 @section @code{MOVE_ALLOC} --- Move allocation from one object to another
9145 @cindex moving allocation
9146 @cindex allocation, moving
9149 @item @emph{Description}:
9150 @code{MOVE_ALLOC(FROM, TO)} moves the allocation from @var{FROM} to
9151 @var{TO}. @var{FROM} will become deallocated in the process.
9153 @item @emph{Standard}:
9154 Fortran 2003 and later
9159 @item @emph{Syntax}:
9160 @code{CALL MOVE_ALLOC(FROM, TO)}
9162 @item @emph{Arguments}:
9163 @multitable @columnfractions .15 .70
9164 @item @var{FROM} @tab @code{ALLOCATABLE}, @code{INTENT(INOUT)}, may be
9165 of any type and kind.
9166 @item @var{TO} @tab @code{ALLOCATABLE}, @code{INTENT(OUT)}, shall be
9167 of the same type, kind and rank as @var{FROM}.
9170 @item @emph{Return value}:
9173 @item @emph{Example}:
9175 program test_move_alloc
9176 integer, allocatable :: a(:), b(:)
9180 call move_alloc(a, b)
9181 print *, allocated(a), allocated(b)
9183 end program test_move_alloc
9190 @section @code{MVBITS} --- Move bits from one integer to another
9195 @item @emph{Description}:
9196 Moves @var{LEN} bits from positions @var{FROMPOS} through
9197 @code{FROMPOS+LEN-1} of @var{FROM} to positions @var{TOPOS} through
9198 @code{TOPOS+LEN-1} of @var{TO}. The portion of argument @var{TO} not
9199 affected by the movement of bits is unchanged. The values of
9200 @code{FROMPOS+LEN-1} and @code{TOPOS+LEN-1} must be less than
9201 @code{BIT_SIZE(FROM)}.
9203 @item @emph{Standard}:
9204 Fortran 95 and later
9207 Elemental subroutine
9209 @item @emph{Syntax}:
9210 @code{CALL MVBITS(FROM, FROMPOS, LEN, TO, TOPOS)}
9212 @item @emph{Arguments}:
9213 @multitable @columnfractions .15 .70
9214 @item @var{FROM} @tab The type shall be @code{INTEGER}.
9215 @item @var{FROMPOS} @tab The type shall be @code{INTEGER}.
9216 @item @var{LEN} @tab The type shall be @code{INTEGER}.
9217 @item @var{TO} @tab The type shall be @code{INTEGER}, of the
9218 same kind as @var{FROM}.
9219 @item @var{TOPOS} @tab The type shall be @code{INTEGER}.
9222 @item @emph{See also}:
9223 @ref{IBCLR}, @ref{IBSET}, @ref{IBITS}, @ref{IAND}, @ref{IOR}, @ref{IEOR}
9229 @section @code{NEAREST} --- Nearest representable number
9231 @cindex real number, nearest different
9232 @cindex floating point, nearest different
9235 @item @emph{Description}:
9236 @code{NEAREST(X, S)} returns the processor-representable number nearest
9237 to @code{X} in the direction indicated by the sign of @code{S}.
9239 @item @emph{Standard}:
9240 Fortran 95 and later
9245 @item @emph{Syntax}:
9246 @code{RESULT = NEAREST(X, S)}
9248 @item @emph{Arguments}:
9249 @multitable @columnfractions .15 .70
9250 @item @var{X} @tab Shall be of type @code{REAL}.
9251 @item @var{S} @tab (Optional) shall be of type @code{REAL} and
9255 @item @emph{Return value}:
9256 The return value is of the same type as @code{X}. If @code{S} is
9257 positive, @code{NEAREST} returns the processor-representable number
9258 greater than @code{X} and nearest to it. If @code{S} is negative,
9259 @code{NEAREST} returns the processor-representable number smaller than
9260 @code{X} and nearest to it.
9262 @item @emph{Example}:
9264 program test_nearest
9266 x = nearest(42.0, 1.0)
9267 y = nearest(42.0, -1.0)
9268 write (*,"(3(G20.15))") x, y, x - y
9269 end program test_nearest
9276 @section @code{NEW_LINE} --- New line character
9279 @cindex output, newline
9282 @item @emph{Description}:
9283 @code{NEW_LINE(C)} returns the new-line character.
9285 @item @emph{Standard}:
9286 Fortran 2003 and later
9291 @item @emph{Syntax}:
9292 @code{RESULT = NEW_LINE(C)}
9294 @item @emph{Arguments}:
9295 @multitable @columnfractions .15 .70
9296 @item @var{C} @tab The argument shall be a scalar or array of the
9297 type @code{CHARACTER}.
9300 @item @emph{Return value}:
9301 Returns a @var{CHARACTER} scalar of length one with the new-line character of
9302 the same kind as parameter @var{C}.
9304 @item @emph{Example}:
9308 write(*,'(A)') 'This is record 1.'//NEW_LINE('A')//'This is record 2.'
9316 @section @code{NINT} --- Nearest whole number
9319 @cindex rounding, nearest whole number
9322 @item @emph{Description}:
9323 @code{NINT(A)} rounds its argument to the nearest whole number.
9325 @item @emph{Standard}:
9326 Fortran 77 and later, with @var{KIND} argument Fortran 90 and later
9331 @item @emph{Syntax}:
9332 @code{RESULT = NINT(A [, KIND])}
9334 @item @emph{Arguments}:
9335 @multitable @columnfractions .15 .70
9336 @item @var{A} @tab The type of the argument shall be @code{REAL}.
9337 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
9338 expression indicating the kind parameter of the result.
9341 @item @emph{Return value}:
9342 Returns @var{A} with the fractional portion of its magnitude eliminated by
9343 rounding to the nearest whole number and with its sign preserved,
9344 converted to an @code{INTEGER} of the default kind.
9346 @item @emph{Example}:
9353 print *, nint(x4), idnint(x8)
9354 end program test_nint
9357 @item @emph{Specific names}:
9358 @multitable @columnfractions .20 .20 .20 .25
9359 @item Name @tab Argument @tab Return Type @tab Standard
9360 @item @code{NINT(A)} @tab @code{REAL(4) A} @tab @code{INTEGER} @tab Fortran 95 and later
9361 @item @code{IDNINT(A)} @tab @code{REAL(8) A} @tab @code{INTEGER} @tab Fortran 95 and later
9364 @item @emph{See also}:
9365 @ref{CEILING}, @ref{FLOOR}
9372 @section @code{NORM2} --- Euclidean vector norms
9374 @cindex Euclidean vector norm
9375 @cindex L2 vector norm
9376 @cindex norm, Euclidean
9379 @item @emph{Description}:
9380 Calculates the Euclidean vector norm (@math{L_2} norm) of
9381 of @var{ARRAY} along dimension @var{DIM}.
9383 @item @emph{Standard}:
9384 Fortran 2008 and later
9387 Transformational function
9389 @item @emph{Syntax}:
9390 @multitable @columnfractions .80
9391 @item @code{RESULT = NORM2(ARRAY[, DIM])}
9394 @item @emph{Arguments}:
9395 @multitable @columnfractions .15 .70
9396 @item @var{ARRAY} @tab Shall be an array of type @code{REAL}
9397 @item @var{DIM} @tab (Optional) shall be a scalar of type
9398 @code{INTEGER} with a value in the range from 1 to n, where n
9399 equals the rank of @var{ARRAY}.
9402 @item @emph{Return value}:
9403 The result is of the same type as @var{ARRAY}.
9405 If @var{DIM} is absent, a scalar with the square root of the sum of all
9406 elements in @var{ARRAY} squared is returned. Otherwise, an array of
9407 rank @math{n-1}, where @math{n} equals the rank of @var{ARRAY}, and a
9408 shape similar to that of @var{ARRAY} with dimension @var{DIM} dropped
9411 @item @emph{Example}:
9414 REAL :: x(5) = [ real :: 1, 2, 3, 4, 5 ]
9415 print *, NORM2(x) ! = sqrt(55.) ~ 7.416
9423 @section @code{NOT} --- Logical negation
9425 @cindex bits, negate
9426 @cindex bitwise logical not
9427 @cindex logical not, bitwise
9430 @item @emph{Description}:
9431 @code{NOT} returns the bitwise Boolean inverse of @var{I}.
9433 @item @emph{Standard}:
9434 Fortran 95 and later
9439 @item @emph{Syntax}:
9440 @code{RESULT = NOT(I)}
9442 @item @emph{Arguments}:
9443 @multitable @columnfractions .15 .70
9444 @item @var{I} @tab The type shall be @code{INTEGER}.
9447 @item @emph{Return value}:
9448 The return type is @code{INTEGER}, of the same kind as the
9451 @item @emph{See also}:
9452 @ref{IAND}, @ref{IEOR}, @ref{IOR}, @ref{IBITS}, @ref{IBSET}, @ref{IBCLR}
9459 @section @code{NULL} --- Function that returns an disassociated pointer
9461 @cindex pointer, status
9462 @cindex pointer, disassociated
9465 @item @emph{Description}:
9466 Returns a disassociated pointer.
9468 If @var{MOLD} is present, a disassociated pointer of the same type is
9469 returned, otherwise the type is determined by context.
9471 In Fortran 95, @var{MOLD} is optional. Please note that Fortran 2003
9472 includes cases where it is required.
9474 @item @emph{Standard}:
9475 Fortran 95 and later
9478 Transformational function
9480 @item @emph{Syntax}:
9481 @code{PTR => NULL([MOLD])}
9483 @item @emph{Arguments}:
9484 @multitable @columnfractions .15 .70
9485 @item @var{MOLD} @tab (Optional) shall be a pointer of any association
9486 status and of any type.
9489 @item @emph{Return value}:
9490 A disassociated pointer.
9492 @item @emph{Example}:
9494 REAL, POINTER, DIMENSION(:) :: VEC => NULL ()
9497 @item @emph{See also}:
9504 @section @code{NUM_IMAGES} --- Function that returns the number of images
9506 @cindex coarray, @code{NUM_IMAGES}
9507 @cindex images, number of
9510 @item @emph{Description}:
9511 Returns the number of images.
9513 @item @emph{Standard}:
9514 Fortran 2008 and later
9517 Transformational function
9519 @item @emph{Syntax}:
9520 @code{RESULT = NUM_IMAGES()}
9522 @item @emph{Arguments}: None.
9524 @item @emph{Return value}:
9525 Scalar default-kind integer.
9527 @item @emph{Example}:
9531 value = THIS_IMAGE()
9533 IF (THIS_IMAGE() == 1) THEN
9534 DO i = 1, NUM_IMAGES()
9535 WRITE(*,'(2(a,i0))') 'value[', i, '] is ', value[i]
9540 @item @emph{See also}:
9541 @ref{THIS_IMAGE}, @ref{IMAGE_INDEX}
9547 @section @code{OR} --- Bitwise logical OR
9549 @cindex bitwise logical or
9550 @cindex logical or, bitwise
9553 @item @emph{Description}:
9554 Bitwise logical @code{OR}.
9556 This intrinsic routine is provided for backwards compatibility with
9557 GNU Fortran 77. For integer arguments, programmers should consider
9558 the use of the @ref{IOR} intrinsic defined by the Fortran standard.
9560 @item @emph{Standard}:
9566 @item @emph{Syntax}:
9567 @code{RESULT = OR(I, J)}
9569 @item @emph{Arguments}:
9570 @multitable @columnfractions .15 .70
9571 @item @var{I} @tab The type shall be either a scalar @code{INTEGER}
9572 type or a scalar @code{LOGICAL} type.
9573 @item @var{J} @tab The type shall be the same as the type of @var{J}.
9576 @item @emph{Return value}:
9577 The return type is either a scalar @code{INTEGER} or a scalar
9578 @code{LOGICAL}. If the kind type parameters differ, then the
9579 smaller kind type is implicitly converted to larger kind, and the
9580 return has the larger kind.
9582 @item @emph{Example}:
9585 LOGICAL :: T = .TRUE., F = .FALSE.
9587 DATA a / Z'F' /, b / Z'3' /
9589 WRITE (*,*) OR(T, T), OR(T, F), OR(F, T), OR(F, F)
9590 WRITE (*,*) OR(a, b)
9594 @item @emph{See also}:
9595 Fortran 95 elemental function: @ref{IOR}
9601 @section @code{PACK} --- Pack an array into an array of rank one
9603 @cindex array, packing
9604 @cindex array, reduce dimension
9605 @cindex array, gather elements
9608 @item @emph{Description}:
9609 Stores the elements of @var{ARRAY} in an array of rank one.
9611 The beginning of the resulting array is made up of elements whose @var{MASK}
9612 equals @code{TRUE}. Afterwards, positions are filled with elements taken from
9615 @item @emph{Standard}:
9616 Fortran 95 and later
9619 Transformational function
9621 @item @emph{Syntax}:
9622 @code{RESULT = PACK(ARRAY, MASK[,VECTOR]}
9624 @item @emph{Arguments}:
9625 @multitable @columnfractions .15 .70
9626 @item @var{ARRAY} @tab Shall be an array of any type.
9627 @item @var{MASK} @tab Shall be an array of type @code{LOGICAL} and
9628 of the same size as @var{ARRAY}. Alternatively, it may be a @code{LOGICAL}
9630 @item @var{VECTOR} @tab (Optional) shall be an array of the same type
9631 as @var{ARRAY} and of rank one. If present, the number of elements in
9632 @var{VECTOR} shall be equal to or greater than the number of true elements
9633 in @var{MASK}. If @var{MASK} is scalar, the number of elements in
9634 @var{VECTOR} shall be equal to or greater than the number of elements in
9638 @item @emph{Return value}:
9639 The result is an array of rank one and the same type as that of @var{ARRAY}.
9640 If @var{VECTOR} is present, the result size is that of @var{VECTOR}, the
9641 number of @code{TRUE} values in @var{MASK} otherwise.
9643 @item @emph{Example}:
9644 Gathering nonzero elements from an array:
9648 m = (/ 1, 0, 0, 0, 5, 0 /)
9649 WRITE(*, FMT="(6(I0, ' '))") pack(m, m /= 0) ! "1 5"
9653 Gathering nonzero elements from an array and appending elements from @var{VECTOR}:
9657 m = (/ 1, 0, 0, 2 /)
9658 WRITE(*, FMT="(4(I0, ' '))") pack(m, m /= 0, (/ 0, 0, 3, 4 /)) ! "1 2 3 4"
9662 @item @emph{See also}:
9669 @section @code{PARITY} --- Reduction with exclusive OR
9672 @cindex Reduction, XOR
9673 @cindex XOR reduction
9676 @item @emph{Description}:
9677 Calculates the parity, i.e. the reduction using @code{.XOR.},
9678 of @var{MASK} along dimension @var{DIM}.
9680 @item @emph{Standard}:
9681 Fortran 2008 and later
9684 Transformational function
9686 @item @emph{Syntax}:
9687 @multitable @columnfractions .80
9688 @item @code{RESULT = PARITY(MASK[, DIM])}
9691 @item @emph{Arguments}:
9692 @multitable @columnfractions .15 .70
9693 @item @var{LOGICAL} @tab Shall be an array of type @code{LOGICAL}
9694 @item @var{DIM} @tab (Optional) shall be a scalar of type
9695 @code{INTEGER} with a value in the range from 1 to n, where n
9696 equals the rank of @var{MASK}.
9699 @item @emph{Return value}:
9700 The result is of the same type as @var{MASK}.
9702 If @var{DIM} is absent, a scalar with the parity of all elements in
9703 @var{MASK} is returned, i.e. true if an odd number of elements is
9704 @code{.true.} and false otherwise. If @var{DIM} is present, an array
9705 of rank @math{n-1}, where @math{n} equals the rank of @var{ARRAY},
9706 and a shape similar to that of @var{MASK} with dimension @var{DIM}
9707 dropped is returned.
9709 @item @emph{Example}:
9712 LOGICAL :: x(2) = [ .true., .false. ]
9713 print *, PARITY(x) ! prints "T" (true).
9721 @section @code{PERROR} --- Print system error message
9723 @cindex system, error handling
9726 @item @emph{Description}:
9727 Prints (on the C @code{stderr} stream) a newline-terminated error
9728 message corresponding to the last system error. This is prefixed by
9729 @var{STRING}, a colon and a space. See @code{perror(3)}.
9731 @item @emph{Standard}:
9737 @item @emph{Syntax}:
9738 @code{CALL PERROR(STRING)}
9740 @item @emph{Arguments}:
9741 @multitable @columnfractions .15 .70
9742 @item @var{STRING} @tab A scalar of type @code{CHARACTER} and of the
9746 @item @emph{See also}:
9753 @section @code{PRECISION} --- Decimal precision of a real kind
9755 @cindex model representation, precision
9758 @item @emph{Description}:
9759 @code{PRECISION(X)} returns the decimal precision in the model of the
9762 @item @emph{Standard}:
9763 Fortran 95 and later
9768 @item @emph{Syntax}:
9769 @code{RESULT = PRECISION(X)}
9771 @item @emph{Arguments}:
9772 @multitable @columnfractions .15 .70
9773 @item @var{X} @tab Shall be of type @code{REAL} or @code{COMPLEX}.
9776 @item @emph{Return value}:
9777 The return value is of type @code{INTEGER} and of the default integer
9780 @item @emph{See also}:
9781 @ref{SELECTED_REAL_KIND}, @ref{RANGE}
9783 @item @emph{Example}:
9785 program prec_and_range
9786 real(kind=4) :: x(2)
9787 complex(kind=8) :: y
9789 print *, precision(x), range(x)
9790 print *, precision(y), range(y)
9791 end program prec_and_range
9798 @section @code{POPCNT} --- Number of bits set
9800 @cindex binary representation
9804 @item @emph{Description}:
9805 @code{POPCNT(I)} returns the number of bits set ('1' bits) in the binary
9806 representation of @code{I}.
9808 @item @emph{Standard}:
9809 Fortran 2008 and later
9814 @item @emph{Syntax}:
9815 @code{RESULT = POPCNT(I)}
9817 @item @emph{Arguments}:
9818 @multitable @columnfractions .15 .70
9819 @item @var{I} @tab Shall be of type @code{INTEGER}.
9822 @item @emph{Return value}:
9823 The return value is of type @code{INTEGER} and of the default integer
9826 @item @emph{See also}:
9827 @ref{POPPAR}, @ref{LEADZ}, @ref{TRAILZ}
9829 @item @emph{Example}:
9831 program test_population
9832 print *, popcnt(127), poppar(127)
9833 print *, popcnt(huge(0_4)), poppar(huge(0_4))
9834 print *, popcnt(huge(0_8)), poppar(huge(0_8))
9835 end program test_population
9841 @section @code{POPPAR} --- Parity of the number of bits set
9843 @cindex binary representation
9847 @item @emph{Description}:
9848 @code{POPPAR(I)} returns parity of the integer @code{I}, i.e. the parity
9849 of the number of bits set ('1' bits) in the binary representation of
9850 @code{I}. It is equal to 0 if @code{I} has an even number of bits set,
9851 and 1 for an odd number of '1' bits.
9853 @item @emph{Standard}:
9854 Fortran 2008 and later
9859 @item @emph{Syntax}:
9860 @code{RESULT = POPPAR(I)}
9862 @item @emph{Arguments}:
9863 @multitable @columnfractions .15 .70
9864 @item @var{I} @tab Shall be of type @code{INTEGER}.
9867 @item @emph{Return value}:
9868 The return value is of type @code{INTEGER} and of the default integer
9871 @item @emph{See also}:
9872 @ref{POPCNT}, @ref{LEADZ}, @ref{TRAILZ}
9874 @item @emph{Example}:
9876 program test_population
9877 print *, popcnt(127), poppar(127)
9878 print *, popcnt(huge(0_4)), poppar(huge(0_4))
9879 print *, popcnt(huge(0_8)), poppar(huge(0_8))
9880 end program test_population
9887 @section @code{PRESENT} --- Determine whether an optional dummy argument is specified
9891 @item @emph{Description}:
9892 Determines whether an optional dummy argument is present.
9894 @item @emph{Standard}:
9895 Fortran 95 and later
9900 @item @emph{Syntax}:
9901 @code{RESULT = PRESENT(A)}
9903 @item @emph{Arguments}:
9904 @multitable @columnfractions .15 .70
9905 @item @var{A} @tab May be of any type and may be a pointer, scalar or array
9906 value, or a dummy procedure. It shall be the name of an optional dummy argument
9907 accessible within the current subroutine or function.
9910 @item @emph{Return value}:
9911 Returns either @code{TRUE} if the optional argument @var{A} is present, or
9912 @code{FALSE} otherwise.
9914 @item @emph{Example}:
9916 PROGRAM test_present
9917 WRITE(*,*) f(), f(42) ! "F T"
9919 LOGICAL FUNCTION f(x)
9920 INTEGER, INTENT(IN), OPTIONAL :: x
9930 @section @code{PRODUCT} --- Product of array elements
9932 @cindex array, product
9933 @cindex array, multiply elements
9934 @cindex array, conditionally multiply elements
9935 @cindex multiply array elements
9938 @item @emph{Description}:
9939 Multiplies the elements of @var{ARRAY} along dimension @var{DIM} if
9940 the corresponding element in @var{MASK} is @code{TRUE}.
9942 @item @emph{Standard}:
9943 Fortran 95 and later
9946 Transformational function
9948 @item @emph{Syntax}:
9949 @multitable @columnfractions .80
9950 @item @code{RESULT = PRODUCT(ARRAY[, MASK])}
9951 @item @code{RESULT = PRODUCT(ARRAY, DIM[, MASK])}
9954 @item @emph{Arguments}:
9955 @multitable @columnfractions .15 .70
9956 @item @var{ARRAY} @tab Shall be an array of type @code{INTEGER},
9957 @code{REAL} or @code{COMPLEX}.
9958 @item @var{DIM} @tab (Optional) shall be a scalar of type
9959 @code{INTEGER} with a value in the range from 1 to n, where n
9960 equals the rank of @var{ARRAY}.
9961 @item @var{MASK} @tab (Optional) shall be of type @code{LOGICAL}
9962 and either be a scalar or an array of the same shape as @var{ARRAY}.
9965 @item @emph{Return value}:
9966 The result is of the same type as @var{ARRAY}.
9968 If @var{DIM} is absent, a scalar with the product of all elements in
9969 @var{ARRAY} is returned. Otherwise, an array of rank n-1, where n equals
9970 the rank of @var{ARRAY}, and a shape similar to that of @var{ARRAY} with
9971 dimension @var{DIM} dropped is returned.
9974 @item @emph{Example}:
9976 PROGRAM test_product
9977 INTEGER :: x(5) = (/ 1, 2, 3, 4 ,5 /)
9978 print *, PRODUCT(x) ! all elements, product = 120
9979 print *, PRODUCT(x, MASK=MOD(x, 2)==1) ! odd elements, product = 15
9983 @item @emph{See also}:
9990 @section @code{RADIX} --- Base of a model number
9992 @cindex model representation, base
9993 @cindex model representation, radix
9996 @item @emph{Description}:
9997 @code{RADIX(X)} returns the base of the model representing the entity @var{X}.
9999 @item @emph{Standard}:
10000 Fortran 95 and later
10002 @item @emph{Class}:
10005 @item @emph{Syntax}:
10006 @code{RESULT = RADIX(X)}
10008 @item @emph{Arguments}:
10009 @multitable @columnfractions .15 .70
10010 @item @var{X} @tab Shall be of type @code{INTEGER} or @code{REAL}
10013 @item @emph{Return value}:
10014 The return value is a scalar of type @code{INTEGER} and of the default
10017 @item @emph{See also}:
10018 @ref{SELECTED_REAL_KIND}
10020 @item @emph{Example}:
10023 print *, "The radix for the default integer kind is", radix(0)
10024 print *, "The radix for the default real kind is", radix(0.0)
10025 end program test_radix
10033 @section @code{RAN} --- Real pseudo-random number
10035 @cindex random number generation
10038 @item @emph{Description}:
10039 For compatibility with HP FORTRAN 77/iX, the @code{RAN} intrinsic is
10040 provided as an alias for @code{RAND}. See @ref{RAND} for complete
10043 @item @emph{Standard}:
10046 @item @emph{Class}:
10049 @item @emph{See also}:
10050 @ref{RAND}, @ref{RANDOM_NUMBER}
10056 @section @code{RAND} --- Real pseudo-random number
10058 @cindex random number generation
10061 @item @emph{Description}:
10062 @code{RAND(FLAG)} returns a pseudo-random number from a uniform
10063 distribution between 0 and 1. If @var{FLAG} is 0, the next number
10064 in the current sequence is returned; if @var{FLAG} is 1, the generator
10065 is restarted by @code{CALL SRAND(0)}; if @var{FLAG} has any other value,
10066 it is used as a new seed with @code{SRAND}.
10068 This intrinsic routine is provided for backwards compatibility with
10069 GNU Fortran 77. It implements a simple modulo generator as provided
10070 by @command{g77}. For new code, one should consider the use of
10071 @ref{RANDOM_NUMBER} as it implements a superior algorithm.
10073 @item @emph{Standard}:
10076 @item @emph{Class}:
10079 @item @emph{Syntax}:
10080 @code{RESULT = RAND(I)}
10082 @item @emph{Arguments}:
10083 @multitable @columnfractions .15 .70
10084 @item @var{I} @tab Shall be a scalar @code{INTEGER} of kind 4.
10087 @item @emph{Return value}:
10088 The return value is of @code{REAL} type and the default kind.
10090 @item @emph{Example}:
10093 integer,parameter :: seed = 86456
10096 print *, rand(), rand(), rand(), rand()
10097 print *, rand(seed), rand(), rand(), rand()
10098 end program test_rand
10101 @item @emph{See also}:
10102 @ref{SRAND}, @ref{RANDOM_NUMBER}
10108 @node RANDOM_NUMBER
10109 @section @code{RANDOM_NUMBER} --- Pseudo-random number
10110 @fnindex RANDOM_NUMBER
10111 @cindex random number generation
10114 @item @emph{Description}:
10115 Returns a single pseudorandom number or an array of pseudorandom numbers
10116 from the uniform distribution over the range @math{ 0 \leq x < 1}.
10118 The runtime-library implements George Marsaglia's KISS (Keep It Simple
10119 Stupid) random number generator (RNG). This RNG combines:
10121 @item The congruential generator @math{x(n) = 69069 \cdot x(n-1) + 1327217885}
10122 with a period of @math{2^{32}},
10123 @item A 3-shift shift-register generator with a period of @math{2^{32} - 1},
10124 @item Two 16-bit multiply-with-carry generators with a period of
10125 @math{597273182964842497 > 2^{59}}.
10127 The overall period exceeds @math{2^{123}}.
10129 Please note, this RNG is thread safe if used within OpenMP directives,
10130 i.e., its state will be consistent while called from multiple threads.
10131 However, the KISS generator does not create random numbers in parallel
10132 from multiple sources, but in sequence from a single source. If an
10133 OpenMP-enabled application heavily relies on random numbers, one should
10134 consider employing a dedicated parallel random number generator instead.
10136 @item @emph{Standard}:
10137 Fortran 95 and later
10139 @item @emph{Class}:
10142 @item @emph{Syntax}:
10143 @code{RANDOM_NUMBER(HARVEST)}
10145 @item @emph{Arguments}:
10146 @multitable @columnfractions .15 .70
10147 @item @var{HARVEST} @tab Shall be a scalar or an array of type @code{REAL}.
10150 @item @emph{Example}:
10152 program test_random_number
10154 CALL init_random_seed() ! see example of RANDOM_SEED
10155 CALL RANDOM_NUMBER(r)
10159 @item @emph{See also}:
10166 @section @code{RANDOM_SEED} --- Initialize a pseudo-random number sequence
10167 @fnindex RANDOM_SEED
10168 @cindex random number generation, seeding
10169 @cindex seeding a random number generator
10172 @item @emph{Description}:
10173 Restarts or queries the state of the pseudorandom number generator used by
10174 @code{RANDOM_NUMBER}.
10176 If @code{RANDOM_SEED} is called without arguments, it is initialized to
10177 a default state. The example below shows how to initialize the random
10178 seed based on the system's time.
10180 @item @emph{Standard}:
10181 Fortran 95 and later
10183 @item @emph{Class}:
10186 @item @emph{Syntax}:
10187 @code{CALL RANDOM_SEED([SIZE, PUT, GET])}
10189 @item @emph{Arguments}:
10190 @multitable @columnfractions .15 .70
10191 @item @var{SIZE} @tab (Optional) Shall be a scalar and of type default
10192 @code{INTEGER}, with @code{INTENT(OUT)}. It specifies the minimum size
10193 of the arrays used with the @var{PUT} and @var{GET} arguments.
10194 @item @var{PUT} @tab (Optional) Shall be an array of type default
10195 @code{INTEGER} and rank one. It is @code{INTENT(IN)} and the size of
10196 the array must be larger than or equal to the number returned by the
10197 @var{SIZE} argument.
10198 @item @var{GET} @tab (Optional) Shall be an array of type default
10199 @code{INTEGER} and rank one. It is @code{INTENT(OUT)} and the size
10200 of the array must be larger than or equal to the number returned by
10201 the @var{SIZE} argument.
10204 @item @emph{Example}:
10206 SUBROUTINE init_random_seed()
10207 INTEGER :: i, n, clock
10208 INTEGER, DIMENSION(:), ALLOCATABLE :: seed
10210 CALL RANDOM_SEED(size = n)
10213 CALL SYSTEM_CLOCK(COUNT=clock)
10215 seed = clock + 37 * (/ (i - 1, i = 1, n) /)
10216 CALL RANDOM_SEED(PUT = seed)
10222 @item @emph{See also}:
10223 @ref{RANDOM_NUMBER}
10229 @section @code{RANGE} --- Decimal exponent range
10231 @cindex model representation, range
10234 @item @emph{Description}:
10235 @code{RANGE(X)} returns the decimal exponent range in the model of the
10238 @item @emph{Standard}:
10239 Fortran 95 and later
10241 @item @emph{Class}:
10244 @item @emph{Syntax}:
10245 @code{RESULT = RANGE(X)}
10247 @item @emph{Arguments}:
10248 @multitable @columnfractions .15 .70
10249 @item @var{X} @tab Shall be of type @code{INTEGER}, @code{REAL}
10253 @item @emph{Return value}:
10254 The return value is of type @code{INTEGER} and of the default integer
10257 @item @emph{See also}:
10258 @ref{SELECTED_REAL_KIND}, @ref{PRECISION}
10260 @item @emph{Example}:
10261 See @code{PRECISION} for an example.
10267 @section @code{RANK} --- Rank of a data object
10272 @item @emph{Description}:
10273 @code{RANK(A)} returns the rank of a scalar or array data object.
10275 @item @emph{Standard}:
10276 Technical Specification (TS) 29113
10278 @item @emph{Class}:
10281 @item @emph{Syntax}:
10282 @code{RESULT = RANGE(A)}
10284 @item @emph{Arguments}:
10285 @multitable @columnfractions .15 .70
10286 @item @var{A} @tab can be of any type
10289 @item @emph{Return value}:
10290 The return value is of type @code{INTEGER} and of the default integer
10291 kind. For arrays, their rank is returned; for scalars zero is returned.
10293 @item @emph{Example}:
10297 real, allocatable :: b(:,:)
10299 print *, rank(a), rank(b) ! Prints: 0 3
10300 end program test_rank
10308 @section @code{REAL} --- Convert to real type
10314 @cindex conversion, to real
10315 @cindex complex numbers, real part
10318 @item @emph{Description}:
10319 @code{REAL(A [, KIND])} converts its argument @var{A} to a real type. The
10320 @code{REALPART} function is provided for compatibility with @command{g77},
10321 and its use is strongly discouraged.
10323 @item @emph{Standard}:
10324 Fortran 77 and later
10326 @item @emph{Class}:
10329 @item @emph{Syntax}:
10330 @multitable @columnfractions .80
10331 @item @code{RESULT = REAL(A [, KIND])}
10332 @item @code{RESULT = REALPART(Z)}
10335 @item @emph{Arguments}:
10336 @multitable @columnfractions .15 .70
10337 @item @var{A} @tab Shall be @code{INTEGER}, @code{REAL}, or
10339 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
10340 expression indicating the kind parameter of the result.
10343 @item @emph{Return value}:
10344 These functions return a @code{REAL} variable or array under
10345 the following rules:
10349 @code{REAL(A)} is converted to a default real type if @var{A} is an
10350 integer or real variable.
10352 @code{REAL(A)} is converted to a real type with the kind type parameter
10353 of @var{A} if @var{A} is a complex variable.
10355 @code{REAL(A, KIND)} is converted to a real type with kind type
10356 parameter @var{KIND} if @var{A} is a complex, integer, or real
10360 @item @emph{Example}:
10363 complex :: x = (1.0, 2.0)
10364 print *, real(x), real(x,8), realpart(x)
10365 end program test_real
10368 @item @emph{Specific names}:
10369 @multitable @columnfractions .20 .20 .20 .25
10370 @item Name @tab Argument @tab Return type @tab Standard
10371 @item @code{FLOAT(A)} @tab @code{INTEGER(4)} @tab @code{REAL(4)} @tab Fortran 77 and later
10372 @item @code{DFLOAT(A)} @tab @code{INTEGER(4)} @tab @code{REAL(8)} @tab GNU extension
10373 @item @code{SNGL(A)} @tab @code{INTEGER(8)} @tab @code{REAL(4)} @tab Fortran 77 and later
10377 @item @emph{See also}:
10385 @section @code{RENAME} --- Rename a file
10387 @cindex file system, rename file
10390 @item @emph{Description}:
10391 Renames a file from file @var{PATH1} to @var{PATH2}. A null
10392 character (@code{CHAR(0)}) can be used to mark the end of the names in
10393 @var{PATH1} and @var{PATH2}; otherwise, trailing blanks in the file
10394 names are ignored. If the @var{STATUS} argument is supplied, it
10395 contains 0 on success or a nonzero error code upon return; see
10398 This intrinsic is provided in both subroutine and function forms;
10399 however, only one form can be used in any given program unit.
10401 @item @emph{Standard}:
10404 @item @emph{Class}:
10405 Subroutine, function
10407 @item @emph{Syntax}:
10408 @multitable @columnfractions .80
10409 @item @code{CALL RENAME(PATH1, PATH2 [, STATUS])}
10410 @item @code{STATUS = RENAME(PATH1, PATH2)}
10413 @item @emph{Arguments}:
10414 @multitable @columnfractions .15 .70
10415 @item @var{PATH1} @tab Shall be of default @code{CHARACTER} type.
10416 @item @var{PATH2} @tab Shall be of default @code{CHARACTER} type.
10417 @item @var{STATUS} @tab (Optional) Shall be of default @code{INTEGER} type.
10420 @item @emph{See also}:
10428 @section @code{REPEAT} --- Repeated string concatenation
10430 @cindex string, repeat
10431 @cindex string, concatenate
10434 @item @emph{Description}:
10435 Concatenates @var{NCOPIES} copies of a string.
10437 @item @emph{Standard}:
10438 Fortran 95 and later
10440 @item @emph{Class}:
10441 Transformational function
10443 @item @emph{Syntax}:
10444 @code{RESULT = REPEAT(STRING, NCOPIES)}
10446 @item @emph{Arguments}:
10447 @multitable @columnfractions .15 .70
10448 @item @var{STRING} @tab Shall be scalar and of type @code{CHARACTER}.
10449 @item @var{NCOPIES} @tab Shall be scalar and of type @code{INTEGER}.
10452 @item @emph{Return value}:
10453 A new scalar of type @code{CHARACTER} built up from @var{NCOPIES} copies
10456 @item @emph{Example}:
10458 program test_repeat
10459 write(*,*) repeat("x", 5) ! "xxxxx"
10467 @section @code{RESHAPE} --- Function to reshape an array
10469 @cindex array, change dimensions
10470 @cindex array, transmogrify
10473 @item @emph{Description}:
10474 Reshapes @var{SOURCE} to correspond to @var{SHAPE}. If necessary,
10475 the new array may be padded with elements from @var{PAD} or permuted
10476 as defined by @var{ORDER}.
10478 @item @emph{Standard}:
10479 Fortran 95 and later
10481 @item @emph{Class}:
10482 Transformational function
10484 @item @emph{Syntax}:
10485 @code{RESULT = RESHAPE(SOURCE, SHAPE[, PAD, ORDER])}
10487 @item @emph{Arguments}:
10488 @multitable @columnfractions .15 .70
10489 @item @var{SOURCE} @tab Shall be an array of any type.
10490 @item @var{SHAPE} @tab Shall be of type @code{INTEGER} and an
10491 array of rank one. Its values must be positive or zero.
10492 @item @var{PAD} @tab (Optional) shall be an array of the same
10493 type as @var{SOURCE}.
10494 @item @var{ORDER} @tab (Optional) shall be of type @code{INTEGER}
10495 and an array of the same shape as @var{SHAPE}. Its values shall
10496 be a permutation of the numbers from 1 to n, where n is the size of
10497 @var{SHAPE}. If @var{ORDER} is absent, the natural ordering shall
10501 @item @emph{Return value}:
10502 The result is an array of shape @var{SHAPE} with the same type as
10505 @item @emph{Example}:
10507 PROGRAM test_reshape
10508 INTEGER, DIMENSION(4) :: x
10509 WRITE(*,*) SHAPE(x) ! prints "4"
10510 WRITE(*,*) SHAPE(RESHAPE(x, (/2, 2/))) ! prints "2 2"
10514 @item @emph{See also}:
10521 @section @code{RRSPACING} --- Reciprocal of the relative spacing
10523 @cindex real number, relative spacing
10524 @cindex floating point, relative spacing
10528 @item @emph{Description}:
10529 @code{RRSPACING(X)} returns the reciprocal of the relative spacing of
10530 model numbers near @var{X}.
10532 @item @emph{Standard}:
10533 Fortran 95 and later
10535 @item @emph{Class}:
10538 @item @emph{Syntax}:
10539 @code{RESULT = RRSPACING(X)}
10541 @item @emph{Arguments}:
10542 @multitable @columnfractions .15 .70
10543 @item @var{X} @tab Shall be of type @code{REAL}.
10546 @item @emph{Return value}:
10547 The return value is of the same type and kind as @var{X}.
10548 The value returned is equal to
10549 @code{ABS(FRACTION(X)) * FLOAT(RADIX(X))**DIGITS(X)}.
10551 @item @emph{See also}:
10558 @section @code{RSHIFT} --- Right shift bits
10560 @cindex bits, shift right
10563 @item @emph{Description}:
10564 @code{RSHIFT} returns a value corresponding to @var{I} with all of the
10565 bits shifted right by @var{SHIFT} places. If the absolute value of
10566 @var{SHIFT} is greater than @code{BIT_SIZE(I)}, the value is undefined.
10567 Bits shifted out from the right end are lost. The fill is arithmetic: the
10568 bits shifted in from the left end are equal to the leftmost bit, which in
10569 two's complement representation is the sign bit.
10571 This function has been superseded by the @code{SHIFTA} intrinsic, which
10572 is standard in Fortran 2008 and later.
10574 @item @emph{Standard}:
10577 @item @emph{Class}:
10580 @item @emph{Syntax}:
10581 @code{RESULT = RSHIFT(I, SHIFT)}
10583 @item @emph{Arguments}:
10584 @multitable @columnfractions .15 .70
10585 @item @var{I} @tab The type shall be @code{INTEGER}.
10586 @item @var{SHIFT} @tab The type shall be @code{INTEGER}.
10589 @item @emph{Return value}:
10590 The return value is of type @code{INTEGER} and of the same kind as
10593 @item @emph{See also}:
10594 @ref{ISHFT}, @ref{ISHFTC}, @ref{LSHIFT}, @ref{SHIFTA}, @ref{SHIFTR},
10602 @section @code{SAME_TYPE_AS} --- Query dynamic types for equality
10603 @fnindex SAME_TYPE_AS
10606 @item @emph{Description}:
10607 Query dynamic types for equality.
10609 @item @emph{Standard}:
10610 Fortran 2003 and later
10612 @item @emph{Class}:
10615 @item @emph{Syntax}:
10616 @code{RESULT = SAME_TYPE_AS(A, B)}
10618 @item @emph{Arguments}:
10619 @multitable @columnfractions .15 .70
10620 @item @var{A} @tab Shall be an object of extensible declared type or
10621 unlimited polymorphic.
10622 @item @var{B} @tab Shall be an object of extensible declared type or
10623 unlimited polymorphic.
10626 @item @emph{Return value}:
10627 The return value is a scalar of type default logical. It is true if and
10628 only if the dynamic type of A is the same as the dynamic type of B.
10630 @item @emph{See also}:
10631 @ref{EXTENDS_TYPE_OF}
10638 @section @code{SCALE} --- Scale a real value
10640 @cindex real number, scale
10641 @cindex floating point, scale
10644 @item @emph{Description}:
10645 @code{SCALE(X,I)} returns @code{X * RADIX(X)**I}.
10647 @item @emph{Standard}:
10648 Fortran 95 and later
10650 @item @emph{Class}:
10653 @item @emph{Syntax}:
10654 @code{RESULT = SCALE(X, I)}
10656 @item @emph{Arguments}:
10657 @multitable @columnfractions .15 .70
10658 @item @var{X} @tab The type of the argument shall be a @code{REAL}.
10659 @item @var{I} @tab The type of the argument shall be a @code{INTEGER}.
10662 @item @emph{Return value}:
10663 The return value is of the same type and kind as @var{X}.
10664 Its value is @code{X * RADIX(X)**I}.
10666 @item @emph{Example}:
10669 real :: x = 178.1387e-4
10671 print *, scale(x,i), x*radix(x)**i
10672 end program test_scale
10680 @section @code{SCAN} --- Scan a string for the presence of a set of characters
10682 @cindex string, find subset
10685 @item @emph{Description}:
10686 Scans a @var{STRING} for any of the characters in a @var{SET}
10689 If @var{BACK} is either absent or equals @code{FALSE}, this function
10690 returns the position of the leftmost character of @var{STRING} that is
10691 in @var{SET}. If @var{BACK} equals @code{TRUE}, the rightmost position
10692 is returned. If no character of @var{SET} is found in @var{STRING}, the
10695 @item @emph{Standard}:
10696 Fortran 95 and later, with @var{KIND} argument Fortran 2003 and later
10698 @item @emph{Class}:
10701 @item @emph{Syntax}:
10702 @code{RESULT = SCAN(STRING, SET[, BACK [, KIND]])}
10704 @item @emph{Arguments}:
10705 @multitable @columnfractions .15 .70
10706 @item @var{STRING} @tab Shall be of type @code{CHARACTER}.
10707 @item @var{SET} @tab Shall be of type @code{CHARACTER}.
10708 @item @var{BACK} @tab (Optional) shall be of type @code{LOGICAL}.
10709 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
10710 expression indicating the kind parameter of the result.
10713 @item @emph{Return value}:
10714 The return value is of type @code{INTEGER} and of kind @var{KIND}. If
10715 @var{KIND} is absent, the return value is of default integer kind.
10717 @item @emph{Example}:
10720 WRITE(*,*) SCAN("FORTRAN", "AO") ! 2, found 'O'
10721 WRITE(*,*) SCAN("FORTRAN", "AO", .TRUE.) ! 6, found 'A'
10722 WRITE(*,*) SCAN("FORTRAN", "C++") ! 0, found none
10726 @item @emph{See also}:
10727 @ref{INDEX intrinsic}, @ref{VERIFY}
10733 @section @code{SECNDS} --- Time function
10735 @cindex time, elapsed
10736 @cindex elapsed time
10739 @item @emph{Description}:
10740 @code{SECNDS(X)} gets the time in seconds from the real-time system clock.
10741 @var{X} is a reference time, also in seconds. If this is zero, the time in
10742 seconds from midnight is returned. This function is non-standard and its
10743 use is discouraged.
10745 @item @emph{Standard}:
10748 @item @emph{Class}:
10751 @item @emph{Syntax}:
10752 @code{RESULT = SECNDS (X)}
10754 @item @emph{Arguments}:
10755 @multitable @columnfractions .15 .70
10756 @item @var{T} @tab Shall be of type @code{REAL(4)}.
10757 @item @var{X} @tab Shall be of type @code{REAL(4)}.
10760 @item @emph{Return value}:
10763 @item @emph{Example}:
10765 program test_secnds
10768 print *, secnds (0.0) ! seconds since midnight
10769 t1 = secnds (0.0) ! reference time
10770 do i = 1, 10000000 ! do something
10772 t2 = secnds (t1) ! elapsed time
10773 print *, "Something took ", t2, " seconds."
10774 end program test_secnds
10781 @section @code{SECOND} --- CPU time function
10783 @cindex time, elapsed
10784 @cindex elapsed time
10787 @item @emph{Description}:
10788 Returns a @code{REAL(4)} value representing the elapsed CPU time in
10789 seconds. This provides the same functionality as the standard
10790 @code{CPU_TIME} intrinsic, and is only included for backwards
10793 This intrinsic is provided in both subroutine and function forms;
10794 however, only one form can be used in any given program unit.
10796 @item @emph{Standard}:
10799 @item @emph{Class}:
10800 Subroutine, function
10802 @item @emph{Syntax}:
10803 @multitable @columnfractions .80
10804 @item @code{CALL SECOND(TIME)}
10805 @item @code{TIME = SECOND()}
10808 @item @emph{Arguments}:
10809 @multitable @columnfractions .15 .70
10810 @item @var{TIME} @tab Shall be of type @code{REAL(4)}.
10813 @item @emph{Return value}:
10814 In either syntax, @var{TIME} is set to the process's current runtime in
10817 @item @emph{See also}:
10824 @node SELECTED_CHAR_KIND
10825 @section @code{SELECTED_CHAR_KIND} --- Choose character kind
10826 @fnindex SELECTED_CHAR_KIND
10827 @cindex character kind
10828 @cindex kind, character
10831 @item @emph{Description}:
10833 @code{SELECTED_CHAR_KIND(NAME)} returns the kind value for the character
10834 set named @var{NAME}, if a character set with such a name is supported,
10835 or @math{-1} otherwise. Currently, supported character sets include
10836 ``ASCII'' and ``DEFAULT'', which are equivalent, and ``ISO_10646''
10837 (Universal Character Set, UCS-4) which is commonly known as Unicode.
10839 @item @emph{Standard}:
10840 Fortran 2003 and later
10842 @item @emph{Class}:
10843 Transformational function
10845 @item @emph{Syntax}:
10846 @code{RESULT = SELECTED_CHAR_KIND(NAME)}
10848 @item @emph{Arguments}:
10849 @multitable @columnfractions .15 .70
10850 @item @var{NAME} @tab Shall be a scalar and of the default character type.
10853 @item @emph{Example}:
10855 program character_kind
10856 use iso_fortran_env
10858 integer, parameter :: ascii = selected_char_kind ("ascii")
10859 integer, parameter :: ucs4 = selected_char_kind ('ISO_10646')
10861 character(kind=ascii, len=26) :: alphabet
10862 character(kind=ucs4, len=30) :: hello_world
10864 alphabet = ascii_"abcdefghijklmnopqrstuvwxyz"
10865 hello_world = ucs4_'Hello World and Ni Hao -- ' &
10866 // char (int (z'4F60'), ucs4) &
10867 // char (int (z'597D'), ucs4)
10869 write (*,*) alphabet
10871 open (output_unit, encoding='UTF-8')
10872 write (*,*) trim (hello_world)
10873 end program character_kind
10879 @node SELECTED_INT_KIND
10880 @section @code{SELECTED_INT_KIND} --- Choose integer kind
10881 @fnindex SELECTED_INT_KIND
10882 @cindex integer kind
10883 @cindex kind, integer
10886 @item @emph{Description}:
10887 @code{SELECTED_INT_KIND(R)} return the kind value of the smallest integer
10888 type that can represent all values ranging from @math{-10^R} (exclusive)
10889 to @math{10^R} (exclusive). If there is no integer kind that accommodates
10890 this range, @code{SELECTED_INT_KIND} returns @math{-1}.
10892 @item @emph{Standard}:
10893 Fortran 95 and later
10895 @item @emph{Class}:
10896 Transformational function
10898 @item @emph{Syntax}:
10899 @code{RESULT = SELECTED_INT_KIND(R)}
10901 @item @emph{Arguments}:
10902 @multitable @columnfractions .15 .70
10903 @item @var{R} @tab Shall be a scalar and of type @code{INTEGER}.
10906 @item @emph{Example}:
10908 program large_integers
10909 integer,parameter :: k5 = selected_int_kind(5)
10910 integer,parameter :: k15 = selected_int_kind(15)
10911 integer(kind=k5) :: i5
10912 integer(kind=k15) :: i15
10914 print *, huge(i5), huge(i15)
10916 ! The following inequalities are always true
10917 print *, huge(i5) >= 10_k5**5-1
10918 print *, huge(i15) >= 10_k15**15-1
10919 end program large_integers
10925 @node SELECTED_REAL_KIND
10926 @section @code{SELECTED_REAL_KIND} --- Choose real kind
10927 @fnindex SELECTED_REAL_KIND
10930 @cindex radix, real
10933 @item @emph{Description}:
10934 @code{SELECTED_REAL_KIND(P,R)} returns the kind value of a real data type
10935 with decimal precision of at least @code{P} digits, exponent range of
10936 at least @code{R}, and with a radix of @code{RADIX}.
10938 @item @emph{Standard}:
10939 Fortran 95 and later, with @code{RADIX} Fortran 2008 or later
10941 @item @emph{Class}:
10942 Transformational function
10944 @item @emph{Syntax}:
10945 @code{RESULT = SELECTED_REAL_KIND([P, R, RADIX])}
10947 @item @emph{Arguments}:
10948 @multitable @columnfractions .15 .70
10949 @item @var{P} @tab (Optional) shall be a scalar and of type @code{INTEGER}.
10950 @item @var{R} @tab (Optional) shall be a scalar and of type @code{INTEGER}.
10951 @item @var{RADIX} @tab (Optional) shall be a scalar and of type @code{INTEGER}.
10953 Before Fortran 2008, at least one of the arguments @var{R} or @var{P} shall
10954 be present; since Fortran 2008, they are assumed to be zero if absent.
10956 @item @emph{Return value}:
10958 @code{SELECTED_REAL_KIND} returns the value of the kind type parameter of
10959 a real data type with decimal precision of at least @code{P} digits, a
10960 decimal exponent range of at least @code{R}, and with the requested
10961 @code{RADIX}. If the @code{RADIX} parameter is absent, real kinds with
10962 any radix can be returned. If more than one real data type meet the
10963 criteria, the kind of the data type with the smallest decimal precision
10964 is returned. If no real data type matches the criteria, the result is
10966 @item -1 if the processor does not support a real data type with a
10967 precision greater than or equal to @code{P}, but the @code{R} and
10968 @code{RADIX} requirements can be fulfilled
10969 @item -2 if the processor does not support a real type with an exponent
10970 range greater than or equal to @code{R}, but @code{P} and @code{RADIX}
10972 @item -3 if @code{RADIX} but not @code{P} and @code{R} requirements
10974 @item -4 if @code{RADIX} and either @code{P} or @code{R} requirements
10976 @item -5 if there is no real type with the given @code{RADIX}
10979 @item @emph{See also}:
10980 @ref{PRECISION}, @ref{RANGE}, @ref{RADIX}
10982 @item @emph{Example}:
10985 integer,parameter :: p6 = selected_real_kind(6)
10986 integer,parameter :: p10r100 = selected_real_kind(10,100)
10987 integer,parameter :: r400 = selected_real_kind(r=400)
10989 real(kind=p10r100) :: y
10990 real(kind=r400) :: z
10992 print *, precision(x), range(x)
10993 print *, precision(y), range(y)
10994 print *, precision(z), range(z)
10995 end program real_kinds
11002 @section @code{SET_EXPONENT} --- Set the exponent of the model
11003 @fnindex SET_EXPONENT
11004 @cindex real number, set exponent
11005 @cindex floating point, set exponent
11008 @item @emph{Description}:
11009 @code{SET_EXPONENT(X, I)} returns the real number whose fractional part
11010 is that that of @var{X} and whose exponent part is @var{I}.
11012 @item @emph{Standard}:
11013 Fortran 95 and later
11015 @item @emph{Class}:
11018 @item @emph{Syntax}:
11019 @code{RESULT = SET_EXPONENT(X, I)}
11021 @item @emph{Arguments}:
11022 @multitable @columnfractions .15 .70
11023 @item @var{X} @tab Shall be of type @code{REAL}.
11024 @item @var{I} @tab Shall be of type @code{INTEGER}.
11027 @item @emph{Return value}:
11028 The return value is of the same type and kind as @var{X}.
11029 The real number whose fractional part
11030 is that that of @var{X} and whose exponent part if @var{I} is returned;
11031 it is @code{FRACTION(X) * RADIX(X)**I}.
11033 @item @emph{Example}:
11035 PROGRAM test_setexp
11036 REAL :: x = 178.1387e-4
11038 PRINT *, SET_EXPONENT(x, i), FRACTION(x) * RADIX(x)**i
11047 @section @code{SHAPE} --- Determine the shape of an array
11049 @cindex array, shape
11052 @item @emph{Description}:
11053 Determines the shape of an array.
11055 @item @emph{Standard}:
11056 Fortran 95 and later, with @var{KIND} argument Fortran 2003 and later
11058 @item @emph{Class}:
11061 @item @emph{Syntax}:
11062 @code{RESULT = SHAPE(SOURCE [, KIND])}
11064 @item @emph{Arguments}:
11065 @multitable @columnfractions .15 .70
11066 @item @var{SOURCE} @tab Shall be an array or scalar of any type.
11067 If @var{SOURCE} is a pointer it must be associated and allocatable
11068 arrays must be allocated.
11069 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
11070 expression indicating the kind parameter of the result.
11073 @item @emph{Return value}:
11074 An @code{INTEGER} array of rank one with as many elements as @var{SOURCE}
11075 has dimensions. The elements of the resulting array correspond to the extend
11076 of @var{SOURCE} along the respective dimensions. If @var{SOURCE} is a scalar,
11077 the result is the rank one array of size zero. If @var{KIND} is absent, the
11078 return value has the default integer kind otherwise the specified kind.
11080 @item @emph{Example}:
11083 INTEGER, DIMENSION(-1:1, -1:2) :: A
11084 WRITE(*,*) SHAPE(A) ! (/ 3, 4 /)
11085 WRITE(*,*) SIZE(SHAPE(42)) ! (/ /)
11089 @item @emph{See also}:
11090 @ref{RESHAPE}, @ref{SIZE}
11096 @section @code{SHIFTA} --- Right shift with fill
11098 @cindex bits, shift right
11099 @cindex shift, right with fill
11102 @item @emph{Description}:
11103 @code{SHIFTA} returns a value corresponding to @var{I} with all of the
11104 bits shifted right by @var{SHIFT} places. If the absolute value of
11105 @var{SHIFT} is greater than @code{BIT_SIZE(I)}, the value is undefined.
11106 Bits shifted out from the right end are lost. The fill is arithmetic: the
11107 bits shifted in from the left end are equal to the leftmost bit, which in
11108 two's complement representation is the sign bit.
11110 @item @emph{Standard}:
11111 Fortran 2008 and later
11113 @item @emph{Class}:
11116 @item @emph{Syntax}:
11117 @code{RESULT = SHIFTA(I, SHIFT)}
11119 @item @emph{Arguments}:
11120 @multitable @columnfractions .15 .70
11121 @item @var{I} @tab The type shall be @code{INTEGER}.
11122 @item @var{SHIFT} @tab The type shall be @code{INTEGER}.
11125 @item @emph{Return value}:
11126 The return value is of type @code{INTEGER} and of the same kind as
11129 @item @emph{See also}:
11130 @ref{SHIFTL}, @ref{SHIFTR}
11136 @section @code{SHIFTL} --- Left shift
11138 @cindex bits, shift left
11139 @cindex shift, left
11142 @item @emph{Description}:
11143 @code{SHIFTL} returns a value corresponding to @var{I} with all of the
11144 bits shifted left by @var{SHIFT} places. If the absolute value of
11145 @var{SHIFT} is greater than @code{BIT_SIZE(I)}, the value is undefined.
11146 Bits shifted out from the left end are lost, and bits shifted in from
11147 the right end are set to 0.
11149 @item @emph{Standard}:
11150 Fortran 2008 and later
11152 @item @emph{Class}:
11155 @item @emph{Syntax}:
11156 @code{RESULT = SHIFTL(I, SHIFT)}
11158 @item @emph{Arguments}:
11159 @multitable @columnfractions .15 .70
11160 @item @var{I} @tab The type shall be @code{INTEGER}.
11161 @item @var{SHIFT} @tab The type shall be @code{INTEGER}.
11164 @item @emph{Return value}:
11165 The return value is of type @code{INTEGER} and of the same kind as
11168 @item @emph{See also}:
11169 @ref{SHIFTA}, @ref{SHIFTR}
11175 @section @code{SHIFTR} --- Right shift
11177 @cindex bits, shift right
11178 @cindex shift, right
11181 @item @emph{Description}:
11182 @code{SHIFTR} returns a value corresponding to @var{I} with all of the
11183 bits shifted right by @var{SHIFT} places. If the absolute value of
11184 @var{SHIFT} is greater than @code{BIT_SIZE(I)}, the value is undefined.
11185 Bits shifted out from the right end are lost, and bits shifted in from
11186 the left end are set to 0.
11188 @item @emph{Standard}:
11189 Fortran 2008 and later
11191 @item @emph{Class}:
11194 @item @emph{Syntax}:
11195 @code{RESULT = SHIFTR(I, SHIFT)}
11197 @item @emph{Arguments}:
11198 @multitable @columnfractions .15 .70
11199 @item @var{I} @tab The type shall be @code{INTEGER}.
11200 @item @var{SHIFT} @tab The type shall be @code{INTEGER}.
11203 @item @emph{Return value}:
11204 The return value is of type @code{INTEGER} and of the same kind as
11207 @item @emph{See also}:
11208 @ref{SHIFTA}, @ref{SHIFTL}
11214 @section @code{SIGN} --- Sign copying function
11218 @cindex sign copying
11221 @item @emph{Description}:
11222 @code{SIGN(A,B)} returns the value of @var{A} with the sign of @var{B}.
11224 @item @emph{Standard}:
11225 Fortran 77 and later
11227 @item @emph{Class}:
11230 @item @emph{Syntax}:
11231 @code{RESULT = SIGN(A, B)}
11233 @item @emph{Arguments}:
11234 @multitable @columnfractions .15 .70
11235 @item @var{A} @tab Shall be of type @code{INTEGER} or @code{REAL}
11236 @item @var{B} @tab Shall be of the same type and kind as @var{A}
11239 @item @emph{Return value}:
11240 The kind of the return value is that of @var{A} and @var{B}.
11241 If @math{B\ge 0} then the result is @code{ABS(A)}, else
11242 it is @code{-ABS(A)}.
11244 @item @emph{Example}:
11247 print *, sign(-12,1)
11248 print *, sign(-12,0)
11249 print *, sign(-12,-1)
11251 print *, sign(-12.,1.)
11252 print *, sign(-12.,0.)
11253 print *, sign(-12.,-1.)
11254 end program test_sign
11257 @item @emph{Specific names}:
11258 @multitable @columnfractions .20 .20 .20 .25
11259 @item Name @tab Arguments @tab Return type @tab Standard
11260 @item @code{SIGN(A,B)} @tab @code{REAL(4) A, B} @tab @code{REAL(4)} @tab f77, gnu
11261 @item @code{ISIGN(A,B)} @tab @code{INTEGER(4) A, B} @tab @code{INTEGER(4)} @tab f77, gnu
11262 @item @code{DSIGN(A,B)} @tab @code{REAL(8) A, B} @tab @code{REAL(8)} @tab f77, gnu
11269 @section @code{SIGNAL} --- Signal handling subroutine (or function)
11271 @cindex system, signal handling
11274 @item @emph{Description}:
11275 @code{SIGNAL(NUMBER, HANDLER [, STATUS])} causes external subroutine
11276 @var{HANDLER} to be executed with a single integer argument when signal
11277 @var{NUMBER} occurs. If @var{HANDLER} is an integer, it can be used to
11278 turn off handling of signal @var{NUMBER} or revert to its default
11279 action. See @code{signal(2)}.
11281 If @code{SIGNAL} is called as a subroutine and the @var{STATUS} argument
11282 is supplied, it is set to the value returned by @code{signal(2)}.
11284 @item @emph{Standard}:
11287 @item @emph{Class}:
11288 Subroutine, function
11290 @item @emph{Syntax}:
11291 @multitable @columnfractions .80
11292 @item @code{CALL SIGNAL(NUMBER, HANDLER [, STATUS])}
11293 @item @code{STATUS = SIGNAL(NUMBER, HANDLER)}
11296 @item @emph{Arguments}:
11297 @multitable @columnfractions .15 .70
11298 @item @var{NUMBER} @tab Shall be a scalar integer, with @code{INTENT(IN)}
11299 @item @var{HANDLER}@tab Signal handler (@code{INTEGER FUNCTION} or
11300 @code{SUBROUTINE}) or dummy/global @code{INTEGER} scalar.
11301 @code{INTEGER}. It is @code{INTENT(IN)}.
11302 @item @var{STATUS} @tab (Optional) @var{STATUS} shall be a scalar
11303 integer. It has @code{INTENT(OUT)}.
11305 @c TODO: What should the interface of the handler be? Does it take arguments?
11307 @item @emph{Return value}:
11308 The @code{SIGNAL} function returns the value returned by @code{signal(2)}.
11310 @item @emph{Example}:
11312 program test_signal
11314 external handler_print
11316 call signal (12, handler_print)
11317 call signal (10, 1)
11320 end program test_signal
11327 @section @code{SIN} --- Sine function
11333 @cindex trigonometric function, sine
11337 @item @emph{Description}:
11338 @code{SIN(X)} computes the sine of @var{X}.
11340 @item @emph{Standard}:
11341 Fortran 77 and later
11343 @item @emph{Class}:
11346 @item @emph{Syntax}:
11347 @code{RESULT = SIN(X)}
11349 @item @emph{Arguments}:
11350 @multitable @columnfractions .15 .70
11351 @item @var{X} @tab The type shall be @code{REAL} or
11355 @item @emph{Return value}:
11356 The return value has same type and kind as @var{X}.
11358 @item @emph{Example}:
11363 end program test_sin
11366 @item @emph{Specific names}:
11367 @multitable @columnfractions .20 .20 .20 .25
11368 @item Name @tab Argument @tab Return type @tab Standard
11369 @item @code{SIN(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab f77, gnu
11370 @item @code{DSIN(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab f95, gnu
11371 @item @code{CSIN(X)} @tab @code{COMPLEX(4) X} @tab @code{COMPLEX(4)} @tab f95, gnu
11372 @item @code{ZSIN(X)} @tab @code{COMPLEX(8) X} @tab @code{COMPLEX(8)} @tab f95, gnu
11373 @item @code{CDSIN(X)} @tab @code{COMPLEX(8) X} @tab @code{COMPLEX(8)} @tab f95, gnu
11376 @item @emph{See also}:
11383 @section @code{SINH} --- Hyperbolic sine function
11386 @cindex hyperbolic sine
11387 @cindex hyperbolic function, sine
11388 @cindex sine, hyperbolic
11391 @item @emph{Description}:
11392 @code{SINH(X)} computes the hyperbolic sine of @var{X}.
11394 @item @emph{Standard}:
11395 Fortran 95 and later, for a complex argument Fortran 2008 or later
11397 @item @emph{Class}:
11400 @item @emph{Syntax}:
11401 @code{RESULT = SINH(X)}
11403 @item @emph{Arguments}:
11404 @multitable @columnfractions .15 .70
11405 @item @var{X} @tab The type shall be @code{REAL} or @code{COMPLEX}.
11408 @item @emph{Return value}:
11409 The return value has same type and kind as @var{X}.
11411 @item @emph{Example}:
11414 real(8) :: x = - 1.0_8
11416 end program test_sinh
11419 @item @emph{Specific names}:
11420 @multitable @columnfractions .20 .20 .20 .25
11421 @item Name @tab Argument @tab Return type @tab Standard
11422 @item @code{SINH(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab Fortran 95 and later
11423 @item @code{DSINH(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab Fortran 95 and later
11426 @item @emph{See also}:
11433 @section @code{SIZE} --- Determine the size of an array
11435 @cindex array, size
11436 @cindex array, number of elements
11437 @cindex array, count elements
11440 @item @emph{Description}:
11441 Determine the extent of @var{ARRAY} along a specified dimension @var{DIM},
11442 or the total number of elements in @var{ARRAY} if @var{DIM} is absent.
11444 @item @emph{Standard}:
11445 Fortran 95 and later, with @var{KIND} argument Fortran 2003 and later
11447 @item @emph{Class}:
11450 @item @emph{Syntax}:
11451 @code{RESULT = SIZE(ARRAY[, DIM [, KIND]])}
11453 @item @emph{Arguments}:
11454 @multitable @columnfractions .15 .70
11455 @item @var{ARRAY} @tab Shall be an array of any type. If @var{ARRAY} is
11456 a pointer it must be associated and allocatable arrays must be allocated.
11457 @item @var{DIM} @tab (Optional) shall be a scalar of type @code{INTEGER}
11458 and its value shall be in the range from 1 to n, where n equals the rank
11460 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
11461 expression indicating the kind parameter of the result.
11464 @item @emph{Return value}:
11465 The return value is of type @code{INTEGER} and of kind @var{KIND}. If
11466 @var{KIND} is absent, the return value is of default integer kind.
11468 @item @emph{Example}:
11471 WRITE(*,*) SIZE((/ 1, 2 /)) ! 2
11475 @item @emph{See also}:
11476 @ref{SHAPE}, @ref{RESHAPE}
11481 @section @code{SIZEOF} --- Size in bytes of an expression
11483 @cindex expression size
11484 @cindex size of an expression
11487 @item @emph{Description}:
11488 @code{SIZEOF(X)} calculates the number of bytes of storage the
11489 expression @code{X} occupies.
11491 @item @emph{Standard}:
11494 @item @emph{Class}:
11497 @item @emph{Syntax}:
11498 @code{N = SIZEOF(X)}
11500 @item @emph{Arguments}:
11501 @multitable @columnfractions .15 .70
11502 @item @var{X} @tab The argument shall be of any type, rank or shape.
11505 @item @emph{Return value}:
11506 The return value is of type integer and of the system-dependent kind
11507 @var{C_SIZE_T} (from the @var{ISO_C_BINDING} module). Its value is the
11508 number of bytes occupied by the argument. If the argument has the
11509 @code{POINTER} attribute, the number of bytes of the storage area pointed
11510 to is returned. If the argument is of a derived type with @code{POINTER}
11511 or @code{ALLOCATABLE} components, the return value does not account for
11512 the sizes of the data pointed to by these components. If the argument is
11513 polymorphic, the size according to the declared type is returned. The argument
11514 may not be a procedure or procedure pointer.
11516 @item @emph{Example}:
11520 print *, (sizeof(s)/sizeof(r) == 5)
11523 The example will print @code{.TRUE.} unless you are using a platform
11524 where default @code{REAL} variables are unusually padded.
11526 @item @emph{See also}:
11527 @ref{C_SIZEOF}, @ref{STORAGE_SIZE}
11532 @section @code{SLEEP} --- Sleep for the specified number of seconds
11534 @cindex delayed execution
11537 @item @emph{Description}:
11538 Calling this subroutine causes the process to pause for @var{SECONDS} seconds.
11540 @item @emph{Standard}:
11543 @item @emph{Class}:
11546 @item @emph{Syntax}:
11547 @code{CALL SLEEP(SECONDS)}
11549 @item @emph{Arguments}:
11550 @multitable @columnfractions .15 .70
11551 @item @var{SECONDS} @tab The type shall be of default @code{INTEGER}.
11554 @item @emph{Example}:
11565 @section @code{SPACING} --- Smallest distance between two numbers of a given type
11567 @cindex real number, relative spacing
11568 @cindex floating point, relative spacing
11571 @item @emph{Description}:
11572 Determines the distance between the argument @var{X} and the nearest
11573 adjacent number of the same type.
11575 @item @emph{Standard}:
11576 Fortran 95 and later
11578 @item @emph{Class}:
11581 @item @emph{Syntax}:
11582 @code{RESULT = SPACING(X)}
11584 @item @emph{Arguments}:
11585 @multitable @columnfractions .15 .70
11586 @item @var{X} @tab Shall be of type @code{REAL}.
11589 @item @emph{Return value}:
11590 The result is of the same type as the input argument @var{X}.
11592 @item @emph{Example}:
11594 PROGRAM test_spacing
11595 INTEGER, PARAMETER :: SGL = SELECTED_REAL_KIND(p=6, r=37)
11596 INTEGER, PARAMETER :: DBL = SELECTED_REAL_KIND(p=13, r=200)
11598 WRITE(*,*) spacing(1.0_SGL) ! "1.1920929E-07" on i686
11599 WRITE(*,*) spacing(1.0_DBL) ! "2.220446049250313E-016" on i686
11603 @item @emph{See also}:
11610 @section @code{SPREAD} --- Add a dimension to an array
11612 @cindex array, increase dimension
11613 @cindex array, duplicate elements
11614 @cindex array, duplicate dimensions
11617 @item @emph{Description}:
11618 Replicates a @var{SOURCE} array @var{NCOPIES} times along a specified
11619 dimension @var{DIM}.
11621 @item @emph{Standard}:
11622 Fortran 95 and later
11624 @item @emph{Class}:
11625 Transformational function
11627 @item @emph{Syntax}:
11628 @code{RESULT = SPREAD(SOURCE, DIM, NCOPIES)}
11630 @item @emph{Arguments}:
11631 @multitable @columnfractions .15 .70
11632 @item @var{SOURCE} @tab Shall be a scalar or an array of any type and
11633 a rank less than seven.
11634 @item @var{DIM} @tab Shall be a scalar of type @code{INTEGER} with a
11635 value in the range from 1 to n+1, where n equals the rank of @var{SOURCE}.
11636 @item @var{NCOPIES} @tab Shall be a scalar of type @code{INTEGER}.
11639 @item @emph{Return value}:
11640 The result is an array of the same type as @var{SOURCE} and has rank n+1
11641 where n equals the rank of @var{SOURCE}.
11643 @item @emph{Example}:
11645 PROGRAM test_spread
11646 INTEGER :: a = 1, b(2) = (/ 1, 2 /)
11647 WRITE(*,*) SPREAD(A, 1, 2) ! "1 1"
11648 WRITE(*,*) SPREAD(B, 1, 2) ! "1 1 2 2"
11652 @item @emph{See also}:
11659 @section @code{SQRT} --- Square-root function
11666 @cindex square-root
11669 @item @emph{Description}:
11670 @code{SQRT(X)} computes the square root of @var{X}.
11672 @item @emph{Standard}:
11673 Fortran 77 and later
11675 @item @emph{Class}:
11678 @item @emph{Syntax}:
11679 @code{RESULT = SQRT(X)}
11681 @item @emph{Arguments}:
11682 @multitable @columnfractions .15 .70
11683 @item @var{X} @tab The type shall be @code{REAL} or
11687 @item @emph{Return value}:
11688 The return value is of type @code{REAL} or @code{COMPLEX}.
11689 The kind type parameter is the same as @var{X}.
11691 @item @emph{Example}:
11694 real(8) :: x = 2.0_8
11695 complex :: z = (1.0, 2.0)
11698 end program test_sqrt
11701 @item @emph{Specific names}:
11702 @multitable @columnfractions .20 .20 .20 .25
11703 @item Name @tab Argument @tab Return type @tab Standard
11704 @item @code{SQRT(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab Fortran 95 and later
11705 @item @code{DSQRT(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab Fortran 95 and later
11706 @item @code{CSQRT(X)} @tab @code{COMPLEX(4) X} @tab @code{COMPLEX(4)} @tab Fortran 95 and later
11707 @item @code{ZSQRT(X)} @tab @code{COMPLEX(8) X} @tab @code{COMPLEX(8)} @tab GNU extension
11708 @item @code{CDSQRT(X)} @tab @code{COMPLEX(8) X} @tab @code{COMPLEX(8)} @tab GNU extension
11715 @section @code{SRAND} --- Reinitialize the random number generator
11717 @cindex random number generation, seeding
11718 @cindex seeding a random number generator
11721 @item @emph{Description}:
11722 @code{SRAND} reinitializes the pseudo-random number generator
11723 called by @code{RAND} and @code{IRAND}. The new seed used by the
11724 generator is specified by the required argument @var{SEED}.
11726 @item @emph{Standard}:
11729 @item @emph{Class}:
11732 @item @emph{Syntax}:
11733 @code{CALL SRAND(SEED)}
11735 @item @emph{Arguments}:
11736 @multitable @columnfractions .15 .70
11737 @item @var{SEED} @tab Shall be a scalar @code{INTEGER(kind=4)}.
11740 @item @emph{Return value}:
11741 Does not return anything.
11743 @item @emph{Example}:
11744 See @code{RAND} and @code{IRAND} for examples.
11746 @item @emph{Notes}:
11747 The Fortran 2003 standard specifies the intrinsic @code{RANDOM_SEED} to
11748 initialize the pseudo-random numbers generator and @code{RANDOM_NUMBER}
11749 to generate pseudo-random numbers. Please note that in
11750 GNU Fortran, these two sets of intrinsics (@code{RAND},
11751 @code{IRAND} and @code{SRAND} on the one hand, @code{RANDOM_NUMBER} and
11752 @code{RANDOM_SEED} on the other hand) access two independent
11753 pseudo-random number generators.
11755 @item @emph{See also}:
11756 @ref{RAND}, @ref{RANDOM_SEED}, @ref{RANDOM_NUMBER}
11763 @section @code{STAT} --- Get file status
11765 @cindex file system, file status
11768 @item @emph{Description}:
11769 This function returns information about a file. No permissions are required on
11770 the file itself, but execute (search) permission is required on all of the
11771 directories in path that lead to the file.
11773 The elements that are obtained and stored in the array @code{VALUES}:
11774 @multitable @columnfractions .15 .70
11775 @item @code{VALUES(1)} @tab Device ID
11776 @item @code{VALUES(2)} @tab Inode number
11777 @item @code{VALUES(3)} @tab File mode
11778 @item @code{VALUES(4)} @tab Number of links
11779 @item @code{VALUES(5)} @tab Owner's uid
11780 @item @code{VALUES(6)} @tab Owner's gid
11781 @item @code{VALUES(7)} @tab ID of device containing directory entry for file (0 if not available)
11782 @item @code{VALUES(8)} @tab File size (bytes)
11783 @item @code{VALUES(9)} @tab Last access time
11784 @item @code{VALUES(10)} @tab Last modification time
11785 @item @code{VALUES(11)} @tab Last file status change time
11786 @item @code{VALUES(12)} @tab Preferred I/O block size (-1 if not available)
11787 @item @code{VALUES(13)} @tab Number of blocks allocated (-1 if not available)
11790 Not all these elements are relevant on all systems.
11791 If an element is not relevant, it is returned as 0.
11793 This intrinsic is provided in both subroutine and function forms; however,
11794 only one form can be used in any given program unit.
11796 @item @emph{Standard}:
11799 @item @emph{Class}:
11800 Subroutine, function
11802 @item @emph{Syntax}:
11803 @multitable @columnfractions .80
11804 @item @code{CALL STAT(NAME, VALUES [, STATUS])}
11805 @item @code{STATUS = STAT(NAME, VALUES)}
11808 @item @emph{Arguments}:
11809 @multitable @columnfractions .15 .70
11810 @item @var{NAME} @tab The type shall be @code{CHARACTER}, of the
11811 default kind and a valid path within the file system.
11812 @item @var{VALUES} @tab The type shall be @code{INTEGER(4), DIMENSION(13)}.
11813 @item @var{STATUS} @tab (Optional) status flag of type @code{INTEGER(4)}. Returns 0
11814 on success and a system specific error code otherwise.
11817 @item @emph{Example}:
11820 INTEGER, DIMENSION(13) :: buff
11823 CALL STAT("/etc/passwd", buff, status)
11825 IF (status == 0) THEN
11826 WRITE (*, FMT="('Device ID:', T30, I19)") buff(1)
11827 WRITE (*, FMT="('Inode number:', T30, I19)") buff(2)
11828 WRITE (*, FMT="('File mode (octal):', T30, O19)") buff(3)
11829 WRITE (*, FMT="('Number of links:', T30, I19)") buff(4)
11830 WRITE (*, FMT="('Owner''s uid:', T30, I19)") buff(5)
11831 WRITE (*, FMT="('Owner''s gid:', T30, I19)") buff(6)
11832 WRITE (*, FMT="('Device where located:', T30, I19)") buff(7)
11833 WRITE (*, FMT="('File size:', T30, I19)") buff(8)
11834 WRITE (*, FMT="('Last access time:', T30, A19)") CTIME(buff(9))
11835 WRITE (*, FMT="('Last modification time', T30, A19)") CTIME(buff(10))
11836 WRITE (*, FMT="('Last status change time:', T30, A19)") CTIME(buff(11))
11837 WRITE (*, FMT="('Preferred block size:', T30, I19)") buff(12)
11838 WRITE (*, FMT="('No. of blocks allocated:', T30, I19)") buff(13)
11843 @item @emph{See also}:
11844 To stat an open file: @ref{FSTAT}, to stat a link: @ref{LSTAT}
11850 @section @code{STORAGE_SIZE} --- Storage size in bits
11851 @fnindex STORAGE_SIZE
11852 @cindex storage size
11855 @item @emph{Description}:
11856 Returns the storage size of argument @var{A} in bits.
11857 @item @emph{Standard}:
11858 Fortran 2008 and later
11859 @item @emph{Class}:
11861 @item @emph{Syntax}:
11862 @code{RESULT = STORAGE_SIZE(A [, KIND])}
11864 @item @emph{Arguments}:
11865 @multitable @columnfractions .15 .70
11866 @item @var{A} @tab Shall be a scalar or array of any type.
11867 @item @var{KIND} @tab (Optional) shall be a scalar integer constant expression.
11870 @item @emph{Return Value}:
11871 The result is a scalar integer with the kind type parameter specified by KIND
11872 (or default integer type if KIND is missing). The result value is the size
11873 expressed in bits for an element of an array that has the dynamic type and type
11876 @item @emph{See also}:
11877 @ref{C_SIZEOF}, @ref{SIZEOF}
11883 @section @code{SUM} --- Sum of array elements
11886 @cindex array, add elements
11887 @cindex array, conditionally add elements
11888 @cindex sum array elements
11891 @item @emph{Description}:
11892 Adds the elements of @var{ARRAY} along dimension @var{DIM} if
11893 the corresponding element in @var{MASK} is @code{TRUE}.
11895 @item @emph{Standard}:
11896 Fortran 95 and later
11898 @item @emph{Class}:
11899 Transformational function
11901 @item @emph{Syntax}:
11902 @multitable @columnfractions .80
11903 @item @code{RESULT = SUM(ARRAY[, MASK])}
11904 @item @code{RESULT = SUM(ARRAY, DIM[, MASK])}
11907 @item @emph{Arguments}:
11908 @multitable @columnfractions .15 .70
11909 @item @var{ARRAY} @tab Shall be an array of type @code{INTEGER},
11910 @code{REAL} or @code{COMPLEX}.
11911 @item @var{DIM} @tab (Optional) shall be a scalar of type
11912 @code{INTEGER} with a value in the range from 1 to n, where n
11913 equals the rank of @var{ARRAY}.
11914 @item @var{MASK} @tab (Optional) shall be of type @code{LOGICAL}
11915 and either be a scalar or an array of the same shape as @var{ARRAY}.
11918 @item @emph{Return value}:
11919 The result is of the same type as @var{ARRAY}.
11921 If @var{DIM} is absent, a scalar with the sum of all elements in @var{ARRAY}
11922 is returned. Otherwise, an array of rank n-1, where n equals the rank of
11923 @var{ARRAY}, and a shape similar to that of @var{ARRAY} with dimension @var{DIM}
11924 dropped is returned.
11926 @item @emph{Example}:
11929 INTEGER :: x(5) = (/ 1, 2, 3, 4 ,5 /)
11930 print *, SUM(x) ! all elements, sum = 15
11931 print *, SUM(x, MASK=MOD(x, 2)==1) ! odd elements, sum = 9
11935 @item @emph{See also}:
11942 @section @code{SYMLNK} --- Create a symbolic link
11944 @cindex file system, create link
11945 @cindex file system, soft link
11948 @item @emph{Description}:
11949 Makes a symbolic link from file @var{PATH1} to @var{PATH2}. A null
11950 character (@code{CHAR(0)}) can be used to mark the end of the names in
11951 @var{PATH1} and @var{PATH2}; otherwise, trailing blanks in the file
11952 names are ignored. If the @var{STATUS} argument is supplied, it
11953 contains 0 on success or a nonzero error code upon return; see
11954 @code{symlink(2)}. If the system does not supply @code{symlink(2)},
11955 @code{ENOSYS} is returned.
11957 This intrinsic is provided in both subroutine and function forms;
11958 however, only one form can be used in any given program unit.
11960 @item @emph{Standard}:
11963 @item @emph{Class}:
11964 Subroutine, function
11966 @item @emph{Syntax}:
11967 @multitable @columnfractions .80
11968 @item @code{CALL SYMLNK(PATH1, PATH2 [, STATUS])}
11969 @item @code{STATUS = SYMLNK(PATH1, PATH2)}
11972 @item @emph{Arguments}:
11973 @multitable @columnfractions .15 .70
11974 @item @var{PATH1} @tab Shall be of default @code{CHARACTER} type.
11975 @item @var{PATH2} @tab Shall be of default @code{CHARACTER} type.
11976 @item @var{STATUS} @tab (Optional) Shall be of default @code{INTEGER} type.
11979 @item @emph{See also}:
11980 @ref{LINK}, @ref{UNLINK}
11987 @section @code{SYSTEM} --- Execute a shell command
11989 @cindex system, system call
11992 @item @emph{Description}:
11993 Passes the command @var{COMMAND} to a shell (see @code{system(3)}). If
11994 argument @var{STATUS} is present, it contains the value returned by
11995 @code{system(3)}, which is presumably 0 if the shell command succeeded.
11996 Note that which shell is used to invoke the command is system-dependent
11997 and environment-dependent.
11999 This intrinsic is provided in both subroutine and function forms;
12000 however, only one form can be used in any given program unit.
12002 Note that the @code{system} function need not be thread-safe. It is
12003 the responsibility of the user to ensure that @code{system} is not
12004 called concurrently.
12006 @item @emph{Standard}:
12009 @item @emph{Class}:
12010 Subroutine, function
12012 @item @emph{Syntax}:
12013 @multitable @columnfractions .80
12014 @item @code{CALL SYSTEM(COMMAND [, STATUS])}
12015 @item @code{STATUS = SYSTEM(COMMAND)}
12018 @item @emph{Arguments}:
12019 @multitable @columnfractions .15 .70
12020 @item @var{COMMAND} @tab Shall be of default @code{CHARACTER} type.
12021 @item @var{STATUS} @tab (Optional) Shall be of default @code{INTEGER} type.
12024 @item @emph{See also}:
12025 @ref{EXECUTE_COMMAND_LINE}, which is part of the Fortran 2008 standard
12026 and should considered in new code for future portability.
12032 @section @code{SYSTEM_CLOCK} --- Time function
12033 @fnindex SYSTEM_CLOCK
12034 @cindex time, clock ticks
12035 @cindex clock ticks
12038 @item @emph{Description}:
12039 Determines the @var{COUNT} of a processor clock since an unspecified
12040 time in the past modulo @var{COUNT_MAX}, @var{COUNT_RATE} determines
12041 the number of clock ticks per second. If the platform supports a high
12042 resolution monotonic clock, that clock is used and can provide up to
12043 nanosecond resolution. If a high resolution monotonic clock is not
12044 available, the implementation falls back to a potentially lower
12045 resolution realtime clock.
12047 @var{COUNT_RATE} is system dependent and can vary depending on the kind of the
12048 arguments. For @var{kind=4} arguments, @var{COUNT} usually represents
12049 milliseconds, while for @var{kind=8} arguments, @var{COUNT} typically
12050 represents micro- or nanoseconds. @var{COUNT_MAX} usually equals
12051 @code{HUGE(COUNT_MAX)}.
12053 If there is no clock, @var{COUNT} is set to @code{-HUGE(COUNT)}, and
12054 @var{COUNT_RATE} and @var{COUNT_MAX} are set to zero.
12056 When running on a platform using the GNU C library (glibc), or a
12057 derivative thereof, the high resolution monotonic clock is available
12058 only when linking with the @var{rt} library. This can be done
12059 explicitly by adding the @code{-lrt} flag when linking the
12060 application, but is also done implicitly when using OpenMP.
12062 @item @emph{Standard}:
12063 Fortran 95 and later
12065 @item @emph{Class}:
12068 @item @emph{Syntax}:
12069 @code{CALL SYSTEM_CLOCK([COUNT, COUNT_RATE, COUNT_MAX])}
12071 @item @emph{Arguments}:
12072 @multitable @columnfractions .15 .70
12073 @item @var{COUNT} @tab (Optional) shall be a scalar of type
12074 @code{INTEGER} with @code{INTENT(OUT)}.
12075 @item @var{COUNT_RATE} @tab (Optional) shall be a scalar of type
12076 @code{INTEGER} with @code{INTENT(OUT)}.
12077 @item @var{COUNT_MAX} @tab (Optional) shall be a scalar of type
12078 @code{INTEGER} with @code{INTENT(OUT)}.
12081 @item @emph{Example}:
12083 PROGRAM test_system_clock
12084 INTEGER :: count, count_rate, count_max
12085 CALL SYSTEM_CLOCK(count, count_rate, count_max)
12086 WRITE(*,*) count, count_rate, count_max
12090 @item @emph{See also}:
12091 @ref{DATE_AND_TIME}, @ref{CPU_TIME}
12097 @section @code{TAN} --- Tangent function
12100 @cindex trigonometric function, tangent
12104 @item @emph{Description}:
12105 @code{TAN(X)} computes the tangent of @var{X}.
12107 @item @emph{Standard}:
12108 Fortran 77 and later, for a complex argument Fortran 2008 or later
12110 @item @emph{Class}:
12113 @item @emph{Syntax}:
12114 @code{RESULT = TAN(X)}
12116 @item @emph{Arguments}:
12117 @multitable @columnfractions .15 .70
12118 @item @var{X} @tab The type shall be @code{REAL} or @code{COMPLEX}.
12121 @item @emph{Return value}:
12122 The return value has same type and kind as @var{X}.
12124 @item @emph{Example}:
12127 real(8) :: x = 0.165_8
12129 end program test_tan
12132 @item @emph{Specific names}:
12133 @multitable @columnfractions .20 .20 .20 .25
12134 @item Name @tab Argument @tab Return type @tab Standard
12135 @item @code{TAN(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab Fortran 95 and later
12136 @item @code{DTAN(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab Fortran 95 and later
12139 @item @emph{See also}:
12146 @section @code{TANH} --- Hyperbolic tangent function
12149 @cindex hyperbolic tangent
12150 @cindex hyperbolic function, tangent
12151 @cindex tangent, hyperbolic
12154 @item @emph{Description}:
12155 @code{TANH(X)} computes the hyperbolic tangent of @var{X}.
12157 @item @emph{Standard}:
12158 Fortran 77 and later, for a complex argument Fortran 2008 or later
12160 @item @emph{Class}:
12163 @item @emph{Syntax}:
12166 @item @emph{Arguments}:
12167 @multitable @columnfractions .15 .70
12168 @item @var{X} @tab The type shall be @code{REAL} or @code{COMPLEX}.
12171 @item @emph{Return value}:
12172 The return value has same type and kind as @var{X}. If @var{X} is
12173 complex, the imaginary part of the result is in radians. If @var{X}
12174 is @code{REAL}, the return value lies in the range
12175 @math{ - 1 \leq tanh(x) \leq 1 }.
12177 @item @emph{Example}:
12180 real(8) :: x = 2.1_8
12182 end program test_tanh
12185 @item @emph{Specific names}:
12186 @multitable @columnfractions .20 .20 .20 .25
12187 @item Name @tab Argument @tab Return type @tab Standard
12188 @item @code{TANH(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab Fortran 95 and later
12189 @item @code{DTANH(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab Fortran 95 and later
12192 @item @emph{See also}:
12199 @section @code{THIS_IMAGE} --- Function that returns the cosubscript index of this image
12200 @fnindex THIS_IMAGE
12201 @cindex coarray, @code{THIS_IMAGE}
12202 @cindex images, index of this image
12205 @item @emph{Description}:
12206 Returns the cosubscript for this image.
12208 @item @emph{Standard}:
12209 Fortran 2008 and later
12211 @item @emph{Class}:
12212 Transformational function
12214 @item @emph{Syntax}:
12215 @multitable @columnfractions .80
12216 @item @code{RESULT = THIS_IMAGE()}
12217 @item @code{RESULT = THIS_IMAGE(COARRAY [, DIM])}
12220 @item @emph{Arguments}:
12221 @multitable @columnfractions .15 .70
12222 @item @var{COARRAY} @tab Coarray of any type (optional; if @var{DIM}
12223 present, required).
12224 @item @var{DIM} @tab default integer scalar (optional). If present,
12225 @var{DIM} shall be between one and the corank of @var{COARRAY}.
12229 @item @emph{Return value}:
12230 Default integer. If @var{COARRAY} is not present, it is scalar and its value
12231 is the index of the invoking image. Otherwise, if @var{DIM} is not present,
12232 a rank-1 array with corank elements is returned, containing the cosubscripts
12233 for @var{COARRAY} specifying the invoking image. If @var{DIM} is present,
12234 a scalar is returned, with the value of the @var{DIM} element of
12235 @code{THIS_IMAGE(COARRAY)}.
12237 @item @emph{Example}:
12239 INTEGER :: value[*]
12241 value = THIS_IMAGE()
12243 IF (THIS_IMAGE() == 1) THEN
12244 DO i = 1, NUM_IMAGES()
12245 WRITE(*,'(2(a,i0))') 'value[', i, '] is ', value[i]
12250 @item @emph{See also}:
12251 @ref{NUM_IMAGES}, @ref{IMAGE_INDEX}
12257 @section @code{TIME} --- Time function
12259 @cindex time, current
12260 @cindex current time
12263 @item @emph{Description}:
12264 Returns the current time encoded as an integer (in the manner of the
12265 function @code{time(3)} in the C standard library). This value is
12266 suitable for passing to @code{CTIME}, @code{GMTIME}, and @code{LTIME}.
12268 This intrinsic is not fully portable, such as to systems with 32-bit
12269 @code{INTEGER} types but supporting times wider than 32 bits. Therefore,
12270 the values returned by this intrinsic might be, or become, negative, or
12271 numerically less than previous values, during a single run of the
12274 See @ref{TIME8}, for information on a similar intrinsic that might be
12275 portable to more GNU Fortran implementations, though to fewer Fortran
12278 @item @emph{Standard}:
12281 @item @emph{Class}:
12284 @item @emph{Syntax}:
12285 @code{RESULT = TIME()}
12287 @item @emph{Return value}:
12288 The return value is a scalar of type @code{INTEGER(4)}.
12290 @item @emph{See also}:
12291 @ref{CTIME}, @ref{GMTIME}, @ref{LTIME}, @ref{MCLOCK}, @ref{TIME8}
12298 @section @code{TIME8} --- Time function (64-bit)
12300 @cindex time, current
12301 @cindex current time
12304 @item @emph{Description}:
12305 Returns the current time encoded as an integer (in the manner of the
12306 function @code{time(3)} in the C standard library). This value is
12307 suitable for passing to @code{CTIME}, @code{GMTIME}, and @code{LTIME}.
12309 @emph{Warning:} this intrinsic does not increase the range of the timing
12310 values over that returned by @code{time(3)}. On a system with a 32-bit
12311 @code{time(3)}, @code{TIME8} will return a 32-bit value, even though
12312 it is converted to a 64-bit @code{INTEGER(8)} value. That means
12313 overflows of the 32-bit value can still occur. Therefore, the values
12314 returned by this intrinsic might be or become negative or numerically
12315 less than previous values during a single run of the compiled program.
12317 @item @emph{Standard}:
12320 @item @emph{Class}:
12323 @item @emph{Syntax}:
12324 @code{RESULT = TIME8()}
12326 @item @emph{Return value}:
12327 The return value is a scalar of type @code{INTEGER(8)}.
12329 @item @emph{See also}:
12330 @ref{CTIME}, @ref{GMTIME}, @ref{LTIME}, @ref{MCLOCK8}, @ref{TIME}
12337 @section @code{TINY} --- Smallest positive number of a real kind
12339 @cindex limits, smallest number
12340 @cindex model representation, smallest number
12343 @item @emph{Description}:
12344 @code{TINY(X)} returns the smallest positive (non zero) number
12345 in the model of the type of @code{X}.
12347 @item @emph{Standard}:
12348 Fortran 95 and later
12350 @item @emph{Class}:
12353 @item @emph{Syntax}:
12354 @code{RESULT = TINY(X)}
12356 @item @emph{Arguments}:
12357 @multitable @columnfractions .15 .70
12358 @item @var{X} @tab Shall be of type @code{REAL}.
12361 @item @emph{Return value}:
12362 The return value is of the same type and kind as @var{X}
12364 @item @emph{Example}:
12365 See @code{HUGE} for an example.
12371 @section @code{TRAILZ} --- Number of trailing zero bits of an integer
12376 @item @emph{Description}:
12377 @code{TRAILZ} returns the number of trailing zero bits of an integer.
12379 @item @emph{Standard}:
12380 Fortran 2008 and later
12382 @item @emph{Class}:
12385 @item @emph{Syntax}:
12386 @code{RESULT = TRAILZ(I)}
12388 @item @emph{Arguments}:
12389 @multitable @columnfractions .15 .70
12390 @item @var{I} @tab Shall be of type @code{INTEGER}.
12393 @item @emph{Return value}:
12394 The type of the return value is the default @code{INTEGER}.
12395 If all the bits of @code{I} are zero, the result value is @code{BIT_SIZE(I)}.
12397 @item @emph{Example}:
12399 PROGRAM test_trailz
12400 WRITE (*,*) TRAILZ(8) ! prints 3
12404 @item @emph{See also}:
12405 @ref{BIT_SIZE}, @ref{LEADZ}, @ref{POPPAR}, @ref{POPCNT}
12411 @section @code{TRANSFER} --- Transfer bit patterns
12417 @item @emph{Description}:
12418 Interprets the bitwise representation of @var{SOURCE} in memory as if it
12419 is the representation of a variable or array of the same type and type
12420 parameters as @var{MOLD}.
12422 This is approximately equivalent to the C concept of @emph{casting} one
12425 @item @emph{Standard}:
12426 Fortran 95 and later
12428 @item @emph{Class}:
12429 Transformational function
12431 @item @emph{Syntax}:
12432 @code{RESULT = TRANSFER(SOURCE, MOLD[, SIZE])}
12434 @item @emph{Arguments}:
12435 @multitable @columnfractions .15 .70
12436 @item @var{SOURCE} @tab Shall be a scalar or an array of any type.
12437 @item @var{MOLD} @tab Shall be a scalar or an array of any type.
12438 @item @var{SIZE} @tab (Optional) shall be a scalar of type
12442 @item @emph{Return value}:
12443 The result has the same type as @var{MOLD}, with the bit level
12444 representation of @var{SOURCE}. If @var{SIZE} is present, the result is
12445 a one-dimensional array of length @var{SIZE}. If @var{SIZE} is absent
12446 but @var{MOLD} is an array (of any size or shape), the result is a one-
12447 dimensional array of the minimum length needed to contain the entirety
12448 of the bitwise representation of @var{SOURCE}. If @var{SIZE} is absent
12449 and @var{MOLD} is a scalar, the result is a scalar.
12451 If the bitwise representation of the result is longer than that of
12452 @var{SOURCE}, then the leading bits of the result correspond to those of
12453 @var{SOURCE} and any trailing bits are filled arbitrarily.
12455 When the resulting bit representation does not correspond to a valid
12456 representation of a variable of the same type as @var{MOLD}, the results
12457 are undefined, and subsequent operations on the result cannot be
12458 guaranteed to produce sensible behavior. For example, it is possible to
12459 create @code{LOGICAL} variables for which @code{@var{VAR}} and
12460 @code{.NOT.@var{VAR}} both appear to be true.
12462 @item @emph{Example}:
12464 PROGRAM test_transfer
12465 integer :: x = 2143289344
12466 print *, transfer(x, 1.0) ! prints "NaN" on i686
12474 @section @code{TRANSPOSE} --- Transpose an array of rank two
12476 @cindex array, transpose
12477 @cindex matrix, transpose
12481 @item @emph{Description}:
12482 Transpose an array of rank two. Element (i, j) of the result has the value
12483 @code{MATRIX(j, i)}, for all i, j.
12485 @item @emph{Standard}:
12486 Fortran 95 and later
12488 @item @emph{Class}:
12489 Transformational function
12491 @item @emph{Syntax}:
12492 @code{RESULT = TRANSPOSE(MATRIX)}
12494 @item @emph{Arguments}:
12495 @multitable @columnfractions .15 .70
12496 @item @var{MATRIX} @tab Shall be an array of any type and have a rank of two.
12499 @item @emph{Return value}:
12500 The result has the same type as @var{MATRIX}, and has shape
12501 @code{(/ m, n /)} if @var{MATRIX} has shape @code{(/ n, m /)}.
12507 @section @code{TRIM} --- Remove trailing blank characters of a string
12509 @cindex string, remove trailing whitespace
12512 @item @emph{Description}:
12513 Removes trailing blank characters of a string.
12515 @item @emph{Standard}:
12516 Fortran 95 and later
12518 @item @emph{Class}:
12519 Transformational function
12521 @item @emph{Syntax}:
12522 @code{RESULT = TRIM(STRING)}
12524 @item @emph{Arguments}:
12525 @multitable @columnfractions .15 .70
12526 @item @var{STRING} @tab Shall be a scalar of type @code{CHARACTER}.
12529 @item @emph{Return value}:
12530 A scalar of type @code{CHARACTER} which length is that of @var{STRING}
12531 less the number of trailing blanks.
12533 @item @emph{Example}:
12536 CHARACTER(len=10), PARAMETER :: s = "GFORTRAN "
12537 WRITE(*,*) LEN(s), LEN(TRIM(s)) ! "10 8", with/without trailing blanks
12541 @item @emph{See also}:
12542 @ref{ADJUSTL}, @ref{ADJUSTR}
12548 @section @code{TTYNAM} --- Get the name of a terminal device.
12550 @cindex system, terminal
12553 @item @emph{Description}:
12554 Get the name of a terminal device. For more information,
12555 see @code{ttyname(3)}.
12557 This intrinsic is provided in both subroutine and function forms;
12558 however, only one form can be used in any given program unit.
12560 @item @emph{Standard}:
12563 @item @emph{Class}:
12564 Subroutine, function
12566 @item @emph{Syntax}:
12567 @multitable @columnfractions .80
12568 @item @code{CALL TTYNAM(UNIT, NAME)}
12569 @item @code{NAME = TTYNAM(UNIT)}
12572 @item @emph{Arguments}:
12573 @multitable @columnfractions .15 .70
12574 @item @var{UNIT} @tab Shall be a scalar @code{INTEGER}.
12575 @item @var{NAME} @tab Shall be of type @code{CHARACTER}.
12578 @item @emph{Example}:
12580 PROGRAM test_ttynam
12583 IF (isatty(unit=unit)) write(*,*) ttynam(unit)
12588 @item @emph{See also}:
12595 @section @code{UBOUND} --- Upper dimension bounds of an array
12597 @cindex array, upper bound
12600 @item @emph{Description}:
12601 Returns the upper bounds of an array, or a single upper bound
12602 along the @var{DIM} dimension.
12603 @item @emph{Standard}:
12604 Fortran 95 and later, with @var{KIND} argument Fortran 2003 and later
12606 @item @emph{Class}:
12609 @item @emph{Syntax}:
12610 @code{RESULT = UBOUND(ARRAY [, DIM [, KIND]])}
12612 @item @emph{Arguments}:
12613 @multitable @columnfractions .15 .70
12614 @item @var{ARRAY} @tab Shall be an array, of any type.
12615 @item @var{DIM} @tab (Optional) Shall be a scalar @code{INTEGER}.
12616 @item @var{KIND}@tab (Optional) An @code{INTEGER} initialization
12617 expression indicating the kind parameter of the result.
12620 @item @emph{Return value}:
12621 The return value is of type @code{INTEGER} and of kind @var{KIND}. If
12622 @var{KIND} is absent, the return value is of default integer kind.
12623 If @var{DIM} is absent, the result is an array of the upper bounds of
12624 @var{ARRAY}. If @var{DIM} is present, the result is a scalar
12625 corresponding to the upper bound of the array along that dimension. If
12626 @var{ARRAY} is an expression rather than a whole array or array
12627 structure component, or if it has a zero extent along the relevant
12628 dimension, the upper bound is taken to be the number of elements along
12629 the relevant dimension.
12631 @item @emph{See also}:
12632 @ref{LBOUND}, @ref{LCOBOUND}
12638 @section @code{UCOBOUND} --- Upper codimension bounds of an array
12640 @cindex coarray, upper bound
12643 @item @emph{Description}:
12644 Returns the upper cobounds of a coarray, or a single upper cobound
12645 along the @var{DIM} codimension.
12646 @item @emph{Standard}:
12647 Fortran 2008 and later
12649 @item @emph{Class}:
12652 @item @emph{Syntax}:
12653 @code{RESULT = UCOBOUND(COARRAY [, DIM [, KIND]])}
12655 @item @emph{Arguments}:
12656 @multitable @columnfractions .15 .70
12657 @item @var{ARRAY} @tab Shall be an coarray, of any type.
12658 @item @var{DIM} @tab (Optional) Shall be a scalar @code{INTEGER}.
12659 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
12660 expression indicating the kind parameter of the result.
12663 @item @emph{Return value}:
12664 The return value is of type @code{INTEGER} and of kind @var{KIND}. If
12665 @var{KIND} is absent, the return value is of default integer kind.
12666 If @var{DIM} is absent, the result is an array of the lower cobounds of
12667 @var{COARRAY}. If @var{DIM} is present, the result is a scalar
12668 corresponding to the lower cobound of the array along that codimension.
12670 @item @emph{See also}:
12671 @ref{LCOBOUND}, @ref{LBOUND}
12677 @section @code{UMASK} --- Set the file creation mask
12679 @cindex file system, file creation mask
12682 @item @emph{Description}:
12683 Sets the file creation mask to @var{MASK}. If called as a function, it
12684 returns the old value. If called as a subroutine and argument @var{OLD}
12685 if it is supplied, it is set to the old value. See @code{umask(2)}.
12687 @item @emph{Standard}:
12690 @item @emph{Class}:
12691 Subroutine, function
12693 @item @emph{Syntax}:
12694 @multitable @columnfractions .80
12695 @item @code{CALL UMASK(MASK [, OLD])}
12696 @item @code{OLD = UMASK(MASK)}
12699 @item @emph{Arguments}:
12700 @multitable @columnfractions .15 .70
12701 @item @var{MASK} @tab Shall be a scalar of type @code{INTEGER}.
12702 @item @var{OLD} @tab (Optional) Shall be a scalar of type
12711 @section @code{UNLINK} --- Remove a file from the file system
12713 @cindex file system, remove file
12716 @item @emph{Description}:
12717 Unlinks the file @var{PATH}. A null character (@code{CHAR(0)}) can be
12718 used to mark the end of the name in @var{PATH}; otherwise, trailing
12719 blanks in the file name are ignored. If the @var{STATUS} argument is
12720 supplied, it contains 0 on success or a nonzero error code upon return;
12721 see @code{unlink(2)}.
12723 This intrinsic is provided in both subroutine and function forms;
12724 however, only one form can be used in any given program unit.
12726 @item @emph{Standard}:
12729 @item @emph{Class}:
12730 Subroutine, function
12732 @item @emph{Syntax}:
12733 @multitable @columnfractions .80
12734 @item @code{CALL UNLINK(PATH [, STATUS])}
12735 @item @code{STATUS = UNLINK(PATH)}
12738 @item @emph{Arguments}:
12739 @multitable @columnfractions .15 .70
12740 @item @var{PATH} @tab Shall be of default @code{CHARACTER} type.
12741 @item @var{STATUS} @tab (Optional) Shall be of default @code{INTEGER} type.
12744 @item @emph{See also}:
12745 @ref{LINK}, @ref{SYMLNK}
12751 @section @code{UNPACK} --- Unpack an array of rank one into an array
12753 @cindex array, unpacking
12754 @cindex array, increase dimension
12755 @cindex array, scatter elements
12758 @item @emph{Description}:
12759 Store the elements of @var{VECTOR} in an array of higher rank.
12761 @item @emph{Standard}:
12762 Fortran 95 and later
12764 @item @emph{Class}:
12765 Transformational function
12767 @item @emph{Syntax}:
12768 @code{RESULT = UNPACK(VECTOR, MASK, FIELD)}
12770 @item @emph{Arguments}:
12771 @multitable @columnfractions .15 .70
12772 @item @var{VECTOR} @tab Shall be an array of any type and rank one. It
12773 shall have at least as many elements as @var{MASK} has @code{TRUE} values.
12774 @item @var{MASK} @tab Shall be an array of type @code{LOGICAL}.
12775 @item @var{FIELD} @tab Shall be of the same type as @var{VECTOR} and have
12776 the same shape as @var{MASK}.
12779 @item @emph{Return value}:
12780 The resulting array corresponds to @var{FIELD} with @code{TRUE} elements
12781 of @var{MASK} replaced by values from @var{VECTOR} in array element order.
12783 @item @emph{Example}:
12785 PROGRAM test_unpack
12786 integer :: vector(2) = (/1,1/)
12787 logical :: mask(4) = (/ .TRUE., .FALSE., .FALSE., .TRUE. /)
12788 integer :: field(2,2) = 0, unity(2,2)
12790 ! result: unity matrix
12791 unity = unpack(vector, reshape(mask, (/2,2/)), field)
12795 @item @emph{See also}:
12796 @ref{PACK}, @ref{SPREAD}
12802 @section @code{VERIFY} --- Scan a string for characters not a given set
12804 @cindex string, find missing set
12807 @item @emph{Description}:
12808 Verifies that all the characters in @var{STRING} belong to the set of
12809 characters in @var{SET}.
12811 If @var{BACK} is either absent or equals @code{FALSE}, this function
12812 returns the position of the leftmost character of @var{STRING} that is
12813 not in @var{SET}. If @var{BACK} equals @code{TRUE}, the rightmost
12814 position is returned. If all characters of @var{STRING} are found in
12815 @var{SET}, the result is zero.
12817 @item @emph{Standard}:
12818 Fortran 95 and later, with @var{KIND} argument Fortran 2003 and later
12820 @item @emph{Class}:
12823 @item @emph{Syntax}:
12824 @code{RESULT = VERIFY(STRING, SET[, BACK [, KIND]])}
12826 @item @emph{Arguments}:
12827 @multitable @columnfractions .15 .70
12828 @item @var{STRING} @tab Shall be of type @code{CHARACTER}.
12829 @item @var{SET} @tab Shall be of type @code{CHARACTER}.
12830 @item @var{BACK} @tab (Optional) shall be of type @code{LOGICAL}.
12831 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
12832 expression indicating the kind parameter of the result.
12835 @item @emph{Return value}:
12836 The return value is of type @code{INTEGER} and of kind @var{KIND}. If
12837 @var{KIND} is absent, the return value is of default integer kind.
12839 @item @emph{Example}:
12841 PROGRAM test_verify
12842 WRITE(*,*) VERIFY("FORTRAN", "AO") ! 1, found 'F'
12843 WRITE(*,*) VERIFY("FORTRAN", "FOO") ! 3, found 'R'
12844 WRITE(*,*) VERIFY("FORTRAN", "C++") ! 1, found 'F'
12845 WRITE(*,*) VERIFY("FORTRAN", "C++", .TRUE.) ! 7, found 'N'
12846 WRITE(*,*) VERIFY("FORTRAN", "FORTRAN") ! 0' found none
12850 @item @emph{See also}:
12851 @ref{SCAN}, @ref{INDEX intrinsic}
12857 @section @code{XOR} --- Bitwise logical exclusive OR
12859 @cindex bitwise logical exclusive or
12860 @cindex logical exclusive or, bitwise
12863 @item @emph{Description}:
12864 Bitwise logical exclusive or.
12866 This intrinsic routine is provided for backwards compatibility with
12867 GNU Fortran 77. For integer arguments, programmers should consider
12868 the use of the @ref{IEOR} intrinsic and for logical arguments the
12869 @code{.NEQV.} operator, which are both defined by the Fortran standard.
12871 @item @emph{Standard}:
12874 @item @emph{Class}:
12877 @item @emph{Syntax}:
12878 @code{RESULT = XOR(I, J)}
12880 @item @emph{Arguments}:
12881 @multitable @columnfractions .15 .70
12882 @item @var{I} @tab The type shall be either a scalar @code{INTEGER}
12883 type or a scalar @code{LOGICAL} type.
12884 @item @var{J} @tab The type shall be the same as the type of @var{I}.
12887 @item @emph{Return value}:
12888 The return type is either a scalar @code{INTEGER} or a scalar
12889 @code{LOGICAL}. If the kind type parameters differ, then the
12890 smaller kind type is implicitly converted to larger kind, and the
12891 return has the larger kind.
12893 @item @emph{Example}:
12896 LOGICAL :: T = .TRUE., F = .FALSE.
12898 DATA a / Z'F' /, b / Z'3' /
12900 WRITE (*,*) XOR(T, T), XOR(T, F), XOR(F, T), XOR(F, F)
12901 WRITE (*,*) XOR(a, b)
12905 @item @emph{See also}:
12906 Fortran 95 elemental function: @ref{IEOR}
12911 @node Intrinsic Modules
12912 @chapter Intrinsic Modules
12913 @cindex intrinsic Modules
12916 * ISO_FORTRAN_ENV::
12918 * OpenMP Modules OMP_LIB and OMP_LIB_KINDS::
12921 @node ISO_FORTRAN_ENV
12922 @section @code{ISO_FORTRAN_ENV}
12924 @item @emph{Standard}:
12925 Fortran 2003 and later, except when otherwise noted
12928 The @code{ISO_FORTRAN_ENV} module provides the following scalar default-integer
12932 @item @code{ATOMIC_INT_KIND}:
12933 Default-kind integer constant to be used as kind parameter when defining
12934 integer variables used in atomic operations. (Fortran 2008 or later.)
12936 @item @code{ATOMIC_LOGICAL_KIND}:
12937 Default-kind integer constant to be used as kind parameter when defining
12938 logical variables used in atomic operations. (Fortran 2008 or later.)
12940 @item @code{CHARACTER_KINDS}:
12941 Default-kind integer constant array of rank one containing the supported kind
12942 parameters of the @code{CHARACTER} type. (Fortran 2008 or later.)
12944 @item @code{CHARACTER_STORAGE_SIZE}:
12945 Size in bits of the character storage unit.
12947 @item @code{ERROR_UNIT}:
12948 Identifies the preconnected unit used for error reporting.
12950 @item @code{FILE_STORAGE_SIZE}:
12951 Size in bits of the file-storage unit.
12953 @item @code{INPUT_UNIT}:
12954 Identifies the preconnected unit identified by the asterisk
12955 (@code{*}) in @code{READ} statement.
12957 @item @code{INT8}, @code{INT16}, @code{INT32}, @code{INT64}:
12958 Kind type parameters to specify an INTEGER type with a storage
12959 size of 16, 32, and 64 bits. It is negative if a target platform
12960 does not support the particular kind. (Fortran 2008 or later.)
12962 @item @code{INTEGER_KINDS}:
12963 Default-kind integer constant array of rank one containing the supported kind
12964 parameters of the @code{INTEGER} type. (Fortran 2008 or later.)
12966 @item @code{IOSTAT_END}:
12967 The value assigned to the variable passed to the @code{IOSTAT=} specifier of
12968 an input/output statement if an end-of-file condition occurred.
12970 @item @code{IOSTAT_EOR}:
12971 The value assigned to the variable passed to the @code{IOSTAT=} specifier of
12972 an input/output statement if an end-of-record condition occurred.
12974 @item @code{IOSTAT_INQUIRE_INTERNAL_UNIT}:
12975 Scalar default-integer constant, used by @code{INQUIRE} for the
12976 @code{IOSTAT=} specifier to denote an that a unit number identifies an
12977 internal unit. (Fortran 2008 or later.)
12979 @item @code{NUMERIC_STORAGE_SIZE}:
12980 The size in bits of the numeric storage unit.
12982 @item @code{LOGICAL_KINDS}:
12983 Default-kind integer constant array of rank one containing the supported kind
12984 parameters of the @code{LOGICAL} type. (Fortran 2008 or later.)
12986 @item @code{OUTPUT_UNIT}:
12987 Identifies the preconnected unit identified by the asterisk
12988 (@code{*}) in @code{WRITE} statement.
12990 @item @code{REAL32}, @code{REAL64}, @code{REAL128}:
12991 Kind type parameters to specify a REAL type with a storage
12992 size of 32, 64, and 128 bits. It is negative if a target platform
12993 does not support the particular kind. (Fortran 2008 or later.)
12995 @item @code{REAL_KINDS}:
12996 Default-kind integer constant array of rank one containing the supported kind
12997 parameters of the @code{REAL} type. (Fortran 2008 or later.)
12999 @item @code{STAT_LOCKED}:
13000 Scalar default-integer constant used as STAT= return value by @code{LOCK} to
13001 denote that the lock variable is locked by the executing image. (Fortran 2008
13004 @item @code{STAT_LOCKED_OTHER_IMAGE}:
13005 Scalar default-integer constant used as STAT= return value by @code{UNLOCK} to
13006 denote that the lock variable is locked by another image. (Fortran 2008 or
13009 @item @code{STAT_STOPPED_IMAGE}:
13010 Positive, scalar default-integer constant used as STAT= return value if the
13011 argument in the statement requires synchronisation with an image, which has
13012 initiated the termination of the execution. (Fortran 2008 or later.)
13014 @item @code{STAT_UNLOCKED}:
13015 Scalar default-integer constant used as STAT= return value by @code{UNLOCK} to
13016 denote that the lock variable is unlocked. (Fortran 2008 or later.)
13019 The module provides the following derived type:
13022 @item @code{LOCK_TYPE}:
13023 Derived type with private components to be use with the @code{LOCK} and
13024 @code{UNLOCK} statement. A variable of its type has to be always declared
13025 as coarray and may not appear in a variable-definition context.
13026 (Fortran 2008 or later.)
13029 The module also provides the following intrinsic procedures:
13030 @ref{COMPILER_OPTIONS} and @ref{COMPILER_VERSION}.
13034 @node ISO_C_BINDING
13035 @section @code{ISO_C_BINDING}
13037 @item @emph{Standard}:
13038 Fortran 2003 and later, GNU extensions
13041 The following intrinsic procedures are provided by the module; their
13042 definition can be found in the section Intrinsic Procedures of this
13046 @item @code{C_ASSOCIATED}
13047 @item @code{C_F_POINTER}
13048 @item @code{C_F_PROCPOINTER}
13049 @item @code{C_FUNLOC}
13051 @item @code{C_SIZEOF}
13053 @c TODO: Vertical spacing between C_FUNLOC and C_LOC wrong in PDF,
13054 @c don't really know why.
13056 The @code{ISO_C_BINDING} module provides the following named constants of
13057 type default integer, which can be used as KIND type parameters.
13059 In addition to the integer named constants required by the Fortran 2003
13060 standard and @code{C_PTRDIFF_T} of TS 29113, GNU Fortran provides as an
13061 extension named constants for the 128-bit integer types supported by the
13062 C compiler: @code{C_INT128_T, C_INT_LEAST128_T, C_INT_FAST128_T}.
13063 Furthermore, if @code{__float128} is supported in C, the named constants
13064 @code{C_FLOAT128, C_FLOAT128_COMPLEX} are defined.
13066 @multitable @columnfractions .15 .35 .35 .35
13067 @item Fortran Type @tab Named constant @tab C type @tab Extension
13068 @item @code{INTEGER}@tab @code{C_INT} @tab @code{int}
13069 @item @code{INTEGER}@tab @code{C_SHORT} @tab @code{short int}
13070 @item @code{INTEGER}@tab @code{C_LONG} @tab @code{long int}
13071 @item @code{INTEGER}@tab @code{C_LONG_LONG} @tab @code{long long int}
13072 @item @code{INTEGER}@tab @code{C_SIGNED_CHAR} @tab @code{signed char}/@code{unsigned char}
13073 @item @code{INTEGER}@tab @code{C_SIZE_T} @tab @code{size_t}
13074 @item @code{INTEGER}@tab @code{C_INT8_T} @tab @code{int8_t}
13075 @item @code{INTEGER}@tab @code{C_INT16_T} @tab @code{int16_t}
13076 @item @code{INTEGER}@tab @code{C_INT32_T} @tab @code{int32_t}
13077 @item @code{INTEGER}@tab @code{C_INT64_T} @tab @code{int64_t}
13078 @item @code{INTEGER}@tab @code{C_INT128_T} @tab @code{int128_t} @tab Ext.
13079 @item @code{INTEGER}@tab @code{C_INT_LEAST8_T} @tab @code{int_least8_t}
13080 @item @code{INTEGER}@tab @code{C_INT_LEAST16_T} @tab @code{int_least16_t}
13081 @item @code{INTEGER}@tab @code{C_INT_LEAST32_T} @tab @code{int_least32_t}
13082 @item @code{INTEGER}@tab @code{C_INT_LEAST64_T} @tab @code{int_least64_t}
13083 @item @code{INTEGER}@tab @code{C_INT_LEAST128_T}@tab @code{int_least128_t} @tab Ext.
13084 @item @code{INTEGER}@tab @code{C_INT_FAST8_T} @tab @code{int_fast8_t}
13085 @item @code{INTEGER}@tab @code{C_INT_FAST16_T} @tab @code{int_fast16_t}
13086 @item @code{INTEGER}@tab @code{C_INT_FAST32_T} @tab @code{int_fast32_t}
13087 @item @code{INTEGER}@tab @code{C_INT_FAST64_T} @tab @code{int_fast64_t}
13088 @item @code{INTEGER}@tab @code{C_INT_FAST128_T} @tab @code{int_fast128_t} @tab Ext.
13089 @item @code{INTEGER}@tab @code{C_INTMAX_T} @tab @code{intmax_t}
13090 @item @code{INTEGER}@tab @code{C_INTPTR_T} @tab @code{intptr_t}
13091 @item @code{INTEGER}@tab @code{C_PTRDIFF_T} @tab @code{intptr_t} @tab TS 29113
13092 @item @code{REAL} @tab @code{C_FLOAT} @tab @code{float}
13093 @item @code{REAL} @tab @code{C_DOUBLE} @tab @code{double}
13094 @item @code{REAL} @tab @code{C_LONG_DOUBLE} @tab @code{long double}
13095 @item @code{REAL} @tab @code{C_FLOAT128} @tab @code{__float128} @tab Ext.
13096 @item @code{COMPLEX}@tab @code{C_FLOAT_COMPLEX} @tab @code{float _Complex}
13097 @item @code{COMPLEX}@tab @code{C_DOUBLE_COMPLEX}@tab @code{double _Complex}
13098 @item @code{COMPLEX}@tab @code{C_LONG_DOUBLE_COMPLEX}@tab @code{long double _Complex}
13099 @item @code{REAL} @tab @code{C_FLOAT128_COMPLEX} @tab @code{__float128 _Complex} @tab Ext.
13100 @item @code{LOGICAL}@tab @code{C_BOOL} @tab @code{_Bool}
13101 @item @code{CHARACTER}@tab @code{C_CHAR} @tab @code{char}
13104 Additionally, the following parameters of type @code{CHARACTER(KIND=C_CHAR)}
13107 @multitable @columnfractions .20 .45 .15
13108 @item Name @tab C definition @tab Value
13109 @item @code{C_NULL_CHAR} @tab null character @tab @code{'\0'}
13110 @item @code{C_ALERT} @tab alert @tab @code{'\a'}
13111 @item @code{C_BACKSPACE} @tab backspace @tab @code{'\b'}
13112 @item @code{C_FORM_FEED} @tab form feed @tab @code{'\f'}
13113 @item @code{C_NEW_LINE} @tab new line @tab @code{'\n'}
13114 @item @code{C_CARRIAGE_RETURN} @tab carriage return @tab @code{'\r'}
13115 @item @code{C_HORIZONTAL_TAB} @tab horizontal tab @tab @code{'\t'}
13116 @item @code{C_VERTICAL_TAB} @tab vertical tab @tab @code{'\v'}
13119 Moreover, the following two named constants are defined:
13121 @multitable @columnfractions .20 .80
13122 @item Name @tab Type
13123 @item @code{C_NULL_PTR} @tab @code{C_PTR}
13124 @item @code{C_NULL_FUNPTR} @tab @code{C_FUNPTR}
13127 Both are equivalent to the value @code{NULL} in C.
13129 @node OpenMP Modules OMP_LIB and OMP_LIB_KINDS
13130 @section OpenMP Modules @code{OMP_LIB} and @code{OMP_LIB_KINDS}
13132 @item @emph{Standard}:
13133 OpenMP Application Program Interface v3.1
13137 The OpenMP Fortran runtime library routines are provided both in
13138 a form of two Fortran 90 modules, named @code{OMP_LIB} and
13139 @code{OMP_LIB_KINDS}, and in a form of a Fortran @code{include} file named
13140 @file{omp_lib.h}. The procedures provided by @code{OMP_LIB} can be found
13141 in the @ref{Top,,Introduction,libgomp,GNU OpenMP runtime library} manual,
13142 the named constants defined in the modules are listed
13145 For details refer to the actual
13146 @uref{http://www.openmp.org/mp-documents/spec31.pdf,
13147 OpenMP Application Program Interface v3.1}.
13149 @code{OMP_LIB_KINDS} provides the following scalar default-integer
13153 @item @code{omp_lock_kind}
13154 @item @code{omp_nest_lock_kind}
13155 @item @code{omp_sched_kind}
13158 @code{OMP_LIB} provides the scalar default-integer
13159 named constant @code{openmp_version} with a value of the form
13160 @var{yyyymm}, where @code{yyyy} is the year and @var{mm} the month
13161 of the OpenMP version; for OpenMP v3.1 the value is @code{201107}.
13163 And the following scalar integer named constants of the
13164 kind @code{omp_sched_kind}:
13167 @item @code{omp_sched_static}
13168 @item @code{omp_sched_dynamic}
13169 @item @code{omp_sched_guided}
13170 @item @code{omp_sched_auto}