2 Copyright (C) 2005, 2006, 2007, 2008, 2009, 2010
3 Free Software Foundation, Inc.
4 This is part of the GNU Fortran manual.
5 For copying conditions, see the file gfortran.texi.
7 Permission is granted to copy, distribute and/or modify this document
8 under the terms of the GNU Free Documentation License, Version 1.3 or
9 any later version published by the Free Software Foundation; with the
10 Invariant Sections being ``Funding Free Software'', the Front-Cover
11 Texts being (a) (see below), and with the Back-Cover Texts being (b)
12 (see below). A copy of the license is included in the gfdl(7) man page.
15 Some basic guidelines for editing this document:
17 (1) The intrinsic procedures are to be listed in alphabetical order.
18 (2) The generic name is to be used.
19 (3) The specific names are included in the function index and in a
20 table at the end of the node (See ABS entry).
21 (4) Try to maintain the same style for each entry.
27 \gdef\acos{\mathop{\rm acos}\nolimits}
28 \gdef\asin{\mathop{\rm asin}\nolimits}
29 \gdef\atan{\mathop{\rm atan}\nolimits}
30 \gdef\acosh{\mathop{\rm acosh}\nolimits}
31 \gdef\asinh{\mathop{\rm asinh}\nolimits}
32 \gdef\atanh{\mathop{\rm atanh}\nolimits}
36 @node Intrinsic Procedures
37 @chapter Intrinsic Procedures
38 @cindex intrinsic procedures
41 * Introduction: Introduction to Intrinsics
42 * @code{ABORT}: ABORT, Abort the program
43 * @code{ABS}: ABS, Absolute value
44 * @code{ACCESS}: ACCESS, Checks file access modes
45 * @code{ACHAR}: ACHAR, Character in @acronym{ASCII} collating sequence
46 * @code{ACOS}: ACOS, Arccosine function
47 * @code{ACOSH}: ACOSH, Inverse hyperbolic cosine function
48 * @code{ADJUSTL}: ADJUSTL, Left adjust a string
49 * @code{ADJUSTR}: ADJUSTR, Right adjust a string
50 * @code{AIMAG}: AIMAG, Imaginary part of complex number
51 * @code{AINT}: AINT, Truncate to a whole number
52 * @code{ALARM}: ALARM, Set an alarm clock
53 * @code{ALL}: ALL, Determine if all values are true
54 * @code{ALLOCATED}: ALLOCATED, Status of allocatable entity
55 * @code{AND}: AND, Bitwise logical AND
56 * @code{ANINT}: ANINT, Nearest whole number
57 * @code{ANY}: ANY, Determine if any values are true
58 * @code{ASIN}: ASIN, Arcsine function
59 * @code{ASINH}: ASINH, Inverse hyperbolic sine function
60 * @code{ASSOCIATED}: ASSOCIATED, Status of a pointer or pointer/target pair
61 * @code{ATAN}: ATAN, Arctangent function
62 * @code{ATAN2}: ATAN2, Arctangent function
63 * @code{ATANH}: ATANH, Inverse hyperbolic tangent function
64 * @code{ATOMIC_DEFINE}: ATOMIC_DEFINE, Setting a variable atomically
65 * @code{ATOMIC_REF}: ATOMIC_REF, Obtaining the value of a variable atomically
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.
353 @item @emph{Standard}:
362 @item @emph{Return value}:
365 @item @emph{Example}:
368 integer :: i = 1, j = 2
369 if (i /= j) call abort
370 end program test_abort
373 @item @emph{See also}:
374 @ref{EXIT}, @ref{KILL}
381 @section @code{ABS} --- Absolute value
388 @cindex absolute value
391 @item @emph{Description}:
392 @code{ABS(A)} computes the absolute value of @code{A}.
394 @item @emph{Standard}:
395 Fortran 77 and later, has overloads that are GNU extensions
401 @code{RESULT = ABS(A)}
403 @item @emph{Arguments}:
404 @multitable @columnfractions .15 .70
405 @item @var{A} @tab The type of the argument shall be an @code{INTEGER},
406 @code{REAL}, or @code{COMPLEX}.
409 @item @emph{Return value}:
410 The return value is of the same type and
411 kind as the argument except the return value is @code{REAL} for a
412 @code{COMPLEX} argument.
414 @item @emph{Example}:
419 complex :: z = (-1.e0,0.e0)
426 @item @emph{Specific names}:
427 @multitable @columnfractions .20 .20 .20 .25
428 @item Name @tab Argument @tab Return type @tab Standard
429 @item @code{ABS(A)} @tab @code{REAL(4) A} @tab @code{REAL(4)} @tab Fortran 77 and later
430 @item @code{CABS(A)} @tab @code{COMPLEX(4) A} @tab @code{REAL(4)} @tab Fortran 77 and later
431 @item @code{DABS(A)} @tab @code{REAL(8) A} @tab @code{REAL(8)} @tab Fortran 77 and later
432 @item @code{IABS(A)} @tab @code{INTEGER(4) A} @tab @code{INTEGER(4)} @tab Fortran 77 and later
433 @item @code{ZABS(A)} @tab @code{COMPLEX(8) A} @tab @code{COMPLEX(8)} @tab GNU extension
434 @item @code{CDABS(A)} @tab @code{COMPLEX(8) A} @tab @code{COMPLEX(8)} @tab GNU extension
441 @section @code{ACCESS} --- Checks file access modes
443 @cindex file system, access mode
446 @item @emph{Description}:
447 @code{ACCESS(NAME, MODE)} checks whether the file @var{NAME}
448 exists, is readable, writable or executable. Except for the
449 executable check, @code{ACCESS} can be replaced by
450 Fortran 95's @code{INQUIRE}.
452 @item @emph{Standard}:
459 @code{RESULT = ACCESS(NAME, MODE)}
461 @item @emph{Arguments}:
462 @multitable @columnfractions .15 .70
463 @item @var{NAME} @tab Scalar @code{CHARACTER} of default kind with the
464 file name. Tailing blank are ignored unless the character @code{achar(0)}
465 is present, then all characters up to and excluding @code{achar(0)} are
467 @item @var{MODE} @tab Scalar @code{CHARACTER} of default kind with the
468 file access mode, may be any concatenation of @code{"r"} (readable),
469 @code{"w"} (writable) and @code{"x"} (executable), or @code{" "} to check
473 @item @emph{Return value}:
474 Returns a scalar @code{INTEGER}, which is @code{0} if the file is
475 accessible in the given mode; otherwise or if an invalid argument
476 has been given for @code{MODE} the value @code{1} is returned.
478 @item @emph{Example}:
482 character(len=*), parameter :: file = 'test.dat'
483 character(len=*), parameter :: file2 = 'test.dat '//achar(0)
484 if(access(file,' ') == 0) print *, trim(file),' is exists'
485 if(access(file,'r') == 0) print *, trim(file),' is readable'
486 if(access(file,'w') == 0) print *, trim(file),' is writable'
487 if(access(file,'x') == 0) print *, trim(file),' is executable'
488 if(access(file2,'rwx') == 0) &
489 print *, trim(file2),' is readable, writable and executable'
490 end program access_test
492 @item @emph{Specific names}:
493 @item @emph{See also}:
500 @section @code{ACHAR} --- Character in @acronym{ASCII} collating sequence
502 @cindex @acronym{ASCII} collating sequence
503 @cindex collating sequence, @acronym{ASCII}
506 @item @emph{Description}:
507 @code{ACHAR(I)} returns the character located at position @code{I}
508 in the @acronym{ASCII} collating sequence.
510 @item @emph{Standard}:
511 Fortran 77 and later, with @var{KIND} argument Fortran 2003 and later
517 @code{RESULT = ACHAR(I [, KIND])}
519 @item @emph{Arguments}:
520 @multitable @columnfractions .15 .70
521 @item @var{I} @tab The type shall be @code{INTEGER}.
522 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
523 expression indicating the kind parameter of the result.
526 @item @emph{Return value}:
527 The return value is of type @code{CHARACTER} with a length of one.
528 If the @var{KIND} argument is present, the return value is of the
529 specified kind and of the default kind otherwise.
531 @item @emph{Example}:
536 end program test_achar
540 See @ref{ICHAR} for a discussion of converting between numerical values
541 and formatted string representations.
543 @item @emph{See also}:
544 @ref{CHAR}, @ref{IACHAR}, @ref{ICHAR}
551 @section @code{ACOS} --- Arccosine function
554 @cindex trigonometric function, cosine, inverse
555 @cindex cosine, inverse
558 @item @emph{Description}:
559 @code{ACOS(X)} computes the arccosine of @var{X} (inverse of @code{COS(X)}).
561 @item @emph{Standard}:
562 Fortran 77 and later, for a complex argument Fortran 2008 or later
568 @code{RESULT = ACOS(X)}
570 @item @emph{Arguments}:
571 @multitable @columnfractions .15 .70
572 @item @var{X} @tab The type shall either be @code{REAL} with a magnitude that is
573 less than or equal to one - or the type shall be @code{COMPLEX}.
576 @item @emph{Return value}:
577 The return value is of the same type and kind as @var{X}.
578 The real part of the result is in radians and lies in the range
579 @math{0 \leq \Re \acos(x) \leq \pi}.
581 @item @emph{Example}:
584 real(8) :: x = 0.866_8
586 end program test_acos
589 @item @emph{Specific names}:
590 @multitable @columnfractions .20 .20 .20 .25
591 @item Name @tab Argument @tab Return type @tab Standard
592 @item @code{ACOS(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab Fortran 77 and later
593 @item @code{DACOS(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab Fortran 77 and later
596 @item @emph{See also}:
597 Inverse function: @ref{COS}
604 @section @code{ACOSH} --- Inverse hyperbolic cosine function
607 @cindex area hyperbolic cosine
608 @cindex inverse hyperbolic cosine
609 @cindex hyperbolic function, cosine, inverse
610 @cindex cosine, hyperbolic, inverse
613 @item @emph{Description}:
614 @code{ACOSH(X)} computes the inverse hyperbolic cosine of @var{X}.
616 @item @emph{Standard}:
617 Fortran 2008 and later
623 @code{RESULT = ACOSH(X)}
625 @item @emph{Arguments}:
626 @multitable @columnfractions .15 .70
627 @item @var{X} @tab The type shall be @code{REAL} or @code{COMPLEX}.
630 @item @emph{Return value}:
631 The return value has the same type and kind as @var{X}. If @var{X} is
632 complex, the imaginary part of the result is in radians and lies between
633 @math{ 0 \leq \Im \acosh(x) \leq \pi}.
635 @item @emph{Example}:
638 REAL(8), DIMENSION(3) :: x = (/ 1.0, 2.0, 3.0 /)
643 @item @emph{Specific names}:
644 @multitable @columnfractions .20 .20 .20 .25
645 @item Name @tab Argument @tab Return type @tab Standard
646 @item @code{DACOSH(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU extension
649 @item @emph{See also}:
650 Inverse function: @ref{COSH}
656 @section @code{ADJUSTL} --- Left adjust a string
658 @cindex string, adjust left
659 @cindex adjust string
662 @item @emph{Description}:
663 @code{ADJUSTL(STRING)} will left adjust a string by removing leading spaces.
664 Spaces are inserted at the end of the string as needed.
666 @item @emph{Standard}:
673 @code{RESULT = ADJUSTL(STRING)}
675 @item @emph{Arguments}:
676 @multitable @columnfractions .15 .70
677 @item @var{STRING} @tab The type shall be @code{CHARACTER}.
680 @item @emph{Return value}:
681 The return value is of type @code{CHARACTER} and of the same kind as
682 @var{STRING} where leading spaces are removed and the same number of
683 spaces are inserted on the end of @var{STRING}.
685 @item @emph{Example}:
688 character(len=20) :: str = ' gfortran'
691 end program test_adjustl
694 @item @emph{See also}:
695 @ref{ADJUSTR}, @ref{TRIM}
701 @section @code{ADJUSTR} --- Right adjust a string
703 @cindex string, adjust right
704 @cindex adjust string
707 @item @emph{Description}:
708 @code{ADJUSTR(STRING)} will right adjust a string by removing trailing spaces.
709 Spaces are inserted at the start of the string as needed.
711 @item @emph{Standard}:
718 @code{RESULT = ADJUSTR(STRING)}
720 @item @emph{Arguments}:
721 @multitable @columnfractions .15 .70
722 @item @var{STR} @tab The type shall be @code{CHARACTER}.
725 @item @emph{Return value}:
726 The return value is of type @code{CHARACTER} and of the same kind as
727 @var{STRING} where trailing spaces are removed and the same number of
728 spaces are inserted at the start of @var{STRING}.
730 @item @emph{Example}:
733 character(len=20) :: str = 'gfortran'
736 end program test_adjustr
739 @item @emph{See also}:
740 @ref{ADJUSTL}, @ref{TRIM}
746 @section @code{AIMAG} --- Imaginary part of complex number
751 @cindex complex numbers, imaginary part
754 @item @emph{Description}:
755 @code{AIMAG(Z)} yields the imaginary part of complex argument @code{Z}.
756 The @code{IMAG(Z)} and @code{IMAGPART(Z)} intrinsic functions are provided
757 for compatibility with @command{g77}, and their use in new code is
758 strongly discouraged.
760 @item @emph{Standard}:
761 Fortran 77 and later, has overloads that are GNU extensions
767 @code{RESULT = AIMAG(Z)}
769 @item @emph{Arguments}:
770 @multitable @columnfractions .15 .70
771 @item @var{Z} @tab The type of the argument shall be @code{COMPLEX}.
774 @item @emph{Return value}:
775 The return value is of type @code{REAL} with the
776 kind type parameter of the argument.
778 @item @emph{Example}:
783 z4 = cmplx(1.e0_4, 0.e0_4)
784 z8 = cmplx(0.e0_8, 1.e0_8)
785 print *, aimag(z4), dimag(z8)
786 end program test_aimag
789 @item @emph{Specific names}:
790 @multitable @columnfractions .20 .20 .20 .25
791 @item Name @tab Argument @tab Return type @tab Standard
792 @item @code{AIMAG(Z)} @tab @code{COMPLEX Z} @tab @code{REAL} @tab GNU extension
793 @item @code{DIMAG(Z)} @tab @code{COMPLEX(8) Z} @tab @code{REAL(8)} @tab GNU extension
794 @item @code{IMAG(Z)} @tab @code{COMPLEX Z} @tab @code{REAL} @tab GNU extension
795 @item @code{IMAGPART(Z)} @tab @code{COMPLEX Z} @tab @code{REAL} @tab GNU extension
802 @section @code{AINT} --- Truncate to a whole number
806 @cindex rounding, floor
809 @item @emph{Description}:
810 @code{AINT(A [, KIND])} truncates its argument to a whole number.
812 @item @emph{Standard}:
819 @code{RESULT = AINT(A [, KIND])}
821 @item @emph{Arguments}:
822 @multitable @columnfractions .15 .70
823 @item @var{A} @tab The type of the argument shall be @code{REAL}.
824 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
825 expression indicating the kind parameter of the result.
828 @item @emph{Return value}:
829 The return value is of type @code{REAL} with the kind type parameter of the
830 argument if the optional @var{KIND} is absent; otherwise, the kind
831 type parameter will be given by @var{KIND}. If the magnitude of
832 @var{X} is less than one, @code{AINT(X)} returns zero. If the
833 magnitude is equal to or greater than one then it returns the largest
834 whole number that does not exceed its magnitude. The sign is the same
835 as the sign of @var{X}.
837 @item @emph{Example}:
844 print *, aint(x4), dint(x8)
846 end program test_aint
849 @item @emph{Specific names}:
850 @multitable @columnfractions .20 .20 .20 .25
851 @item Name @tab Argument @tab Return type @tab Standard
852 @item @code{AINT(A)} @tab @code{REAL(4) A} @tab @code{REAL(4)} @tab Fortran 77 and later
853 @item @code{DINT(A)} @tab @code{REAL(8) A} @tab @code{REAL(8)} @tab Fortran 77 and later
860 @section @code{ALARM} --- Execute a routine after a given delay
862 @cindex delayed execution
865 @item @emph{Description}:
866 @code{ALARM(SECONDS, HANDLER [, STATUS])} causes external subroutine @var{HANDLER}
867 to be executed after a delay of @var{SECONDS} by using @code{alarm(2)} to
868 set up a signal and @code{signal(2)} to catch it. If @var{STATUS} is
869 supplied, it will be returned with the number of seconds remaining until
870 any previously scheduled alarm was due to be delivered, or zero if there
871 was no previously scheduled alarm.
873 @item @emph{Standard}:
880 @code{CALL ALARM(SECONDS, HANDLER [, STATUS])}
882 @item @emph{Arguments}:
883 @multitable @columnfractions .15 .70
884 @item @var{SECONDS} @tab The type of the argument shall be a scalar
885 @code{INTEGER}. It is @code{INTENT(IN)}.
886 @item @var{HANDLER} @tab Signal handler (@code{INTEGER FUNCTION} or
887 @code{SUBROUTINE}) or dummy/global @code{INTEGER} scalar. The scalar
888 values may be either @code{SIG_IGN=1} to ignore the alarm generated
889 or @code{SIG_DFL=0} to set the default action. It is @code{INTENT(IN)}.
890 @item @var{STATUS} @tab (Optional) @var{STATUS} shall be a scalar
891 variable of the default @code{INTEGER} kind. It is @code{INTENT(OUT)}.
894 @item @emph{Example}:
897 external handler_print
899 call alarm (3, handler_print, i)
902 end program test_alarm
904 This will cause the external routine @var{handler_print} to be called
911 @section @code{ALL} --- All values in @var{MASK} along @var{DIM} are true
913 @cindex array, apply condition
914 @cindex array, condition testing
917 @item @emph{Description}:
918 @code{ALL(MASK [, DIM])} determines if all the values are true in @var{MASK}
919 in the array along dimension @var{DIM}.
921 @item @emph{Standard}:
925 Transformational function
928 @code{RESULT = ALL(MASK [, DIM])}
930 @item @emph{Arguments}:
931 @multitable @columnfractions .15 .70
932 @item @var{MASK} @tab The type of the argument shall be @code{LOGICAL} and
933 it shall not be scalar.
934 @item @var{DIM} @tab (Optional) @var{DIM} shall be a scalar integer
935 with a value that lies between one and the rank of @var{MASK}.
938 @item @emph{Return value}:
939 @code{ALL(MASK)} returns a scalar value of type @code{LOGICAL} where
940 the kind type parameter is the same as the kind type parameter of
941 @var{MASK}. If @var{DIM} is present, then @code{ALL(MASK, DIM)} returns
942 an array with the rank of @var{MASK} minus 1. The shape is determined from
943 the shape of @var{MASK} where the @var{DIM} dimension is elided.
947 @code{ALL(MASK)} is true if all elements of @var{MASK} are true.
948 It also is true if @var{MASK} has zero size; otherwise, it is false.
950 If the rank of @var{MASK} is one, then @code{ALL(MASK,DIM)} is equivalent
951 to @code{ALL(MASK)}. If the rank is greater than one, then @code{ALL(MASK,DIM)}
952 is determined by applying @code{ALL} to the array sections.
955 @item @emph{Example}:
959 l = all((/.true., .true., .true./))
964 integer a(2,3), b(2,3)
968 print *, all(a .eq. b, 1)
969 print *, all(a .eq. b, 2)
970 end subroutine section
978 @section @code{ALLOCATED} --- Status of an allocatable entity
980 @cindex allocation, status
983 @item @emph{Description}:
984 @code{ALLOCATED(ARRAY)} and @code{ALLOCATED(SCALAR)} check the allocation
985 status of @var{ARRAY} and @var{SCALAR}, respectively.
987 @item @emph{Standard}:
988 Fortran 95 and later. Note, the @code{SCALAR=} keyword and allocatable
989 scalar entities are available in Fortran 2003 and later.
995 @multitable @columnfractions .80
996 @item @code{RESULT = ALLOCATED(ARRAY)}
997 @item @code{RESULT = ALLOCATED(SCALAR)}
1000 @item @emph{Arguments}:
1001 @multitable @columnfractions .15 .70
1002 @item @var{ARRAY} @tab The argument shall be an @code{ALLOCATABLE} array.
1003 @item @var{SCALAR} @tab The argument shall be an @code{ALLOCATABLE} scalar.
1006 @item @emph{Return value}:
1007 The return value is a scalar @code{LOGICAL} with the default logical
1008 kind type parameter. If the argument is allocated, then the result is
1009 @code{.TRUE.}; otherwise, it returns @code{.FALSE.}
1011 @item @emph{Example}:
1013 program test_allocated
1015 real(4), allocatable :: x(:)
1016 if (.not. allocated(x)) allocate(x(i))
1017 end program test_allocated
1024 @section @code{AND} --- Bitwise logical AND
1026 @cindex bitwise logical and
1027 @cindex logical and, bitwise
1030 @item @emph{Description}:
1031 Bitwise logical @code{AND}.
1033 This intrinsic routine is provided for backwards compatibility with
1034 GNU Fortran 77. For integer arguments, programmers should consider
1035 the use of the @ref{IAND} intrinsic defined by the Fortran standard.
1037 @item @emph{Standard}:
1043 @item @emph{Syntax}:
1044 @code{RESULT = AND(I, J)}
1046 @item @emph{Arguments}:
1047 @multitable @columnfractions .15 .70
1048 @item @var{I} @tab The type shall be either a scalar @code{INTEGER}
1049 type or a scalar @code{LOGICAL} type.
1050 @item @var{J} @tab The type shall be the same as the type of @var{I}.
1053 @item @emph{Return value}:
1054 The return type is either a scalar @code{INTEGER} or a scalar
1055 @code{LOGICAL}. If the kind type parameters differ, then the
1056 smaller kind type is implicitly converted to larger kind, and the
1057 return has the larger kind.
1059 @item @emph{Example}:
1062 LOGICAL :: T = .TRUE., F = .FALSE.
1064 DATA a / Z'F' /, b / Z'3' /
1066 WRITE (*,*) AND(T, T), AND(T, F), AND(F, T), AND(F, F)
1067 WRITE (*,*) AND(a, b)
1071 @item @emph{See also}:
1072 Fortran 95 elemental function: @ref{IAND}
1078 @section @code{ANINT} --- Nearest whole number
1082 @cindex rounding, ceiling
1085 @item @emph{Description}:
1086 @code{ANINT(A [, KIND])} rounds its argument to the nearest whole number.
1088 @item @emph{Standard}:
1089 Fortran 77 and later
1094 @item @emph{Syntax}:
1095 @code{RESULT = ANINT(A [, KIND])}
1097 @item @emph{Arguments}:
1098 @multitable @columnfractions .15 .70
1099 @item @var{A} @tab The type of the argument shall be @code{REAL}.
1100 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
1101 expression indicating the kind parameter of the result.
1104 @item @emph{Return value}:
1105 The return value is of type real with the kind type parameter of the
1106 argument if the optional @var{KIND} is absent; otherwise, the kind
1107 type parameter will be given by @var{KIND}. If @var{A} is greater than
1108 zero, @code{ANINT(A)} returns @code{AINT(X+0.5)}. If @var{A} is
1109 less than or equal to zero then it returns @code{AINT(X-0.5)}.
1111 @item @emph{Example}:
1118 print *, anint(x4), dnint(x8)
1120 end program test_anint
1123 @item @emph{Specific names}:
1124 @multitable @columnfractions .20 .20 .20 .25
1125 @item Name @tab Argument @tab Return type @tab Standard
1126 @item @code{AINT(A)} @tab @code{REAL(4) A} @tab @code{REAL(4)} @tab Fortran 77 and later
1127 @item @code{DNINT(A)} @tab @code{REAL(8) A} @tab @code{REAL(8)} @tab Fortran 77 and later
1134 @section @code{ANY} --- Any value in @var{MASK} along @var{DIM} is true
1136 @cindex array, apply condition
1137 @cindex array, condition testing
1140 @item @emph{Description}:
1141 @code{ANY(MASK [, DIM])} determines if any of the values in the logical array
1142 @var{MASK} along dimension @var{DIM} are @code{.TRUE.}.
1144 @item @emph{Standard}:
1145 Fortran 95 and later
1148 Transformational function
1150 @item @emph{Syntax}:
1151 @code{RESULT = ANY(MASK [, DIM])}
1153 @item @emph{Arguments}:
1154 @multitable @columnfractions .15 .70
1155 @item @var{MASK} @tab The type of the argument shall be @code{LOGICAL} and
1156 it shall not be scalar.
1157 @item @var{DIM} @tab (Optional) @var{DIM} shall be a scalar integer
1158 with a value that lies between one and the rank of @var{MASK}.
1161 @item @emph{Return value}:
1162 @code{ANY(MASK)} returns a scalar value of type @code{LOGICAL} where
1163 the kind type parameter is the same as the kind type parameter of
1164 @var{MASK}. If @var{DIM} is present, then @code{ANY(MASK, DIM)} returns
1165 an array with the rank of @var{MASK} minus 1. The shape is determined from
1166 the shape of @var{MASK} where the @var{DIM} dimension is elided.
1170 @code{ANY(MASK)} is true if any element of @var{MASK} is true;
1171 otherwise, it is false. It also is false if @var{MASK} has zero size.
1173 If the rank of @var{MASK} is one, then @code{ANY(MASK,DIM)} is equivalent
1174 to @code{ANY(MASK)}. If the rank is greater than one, then @code{ANY(MASK,DIM)}
1175 is determined by applying @code{ANY} to the array sections.
1178 @item @emph{Example}:
1182 l = any((/.true., .true., .true./))
1187 integer a(2,3), b(2,3)
1191 print *, any(a .eq. b, 1)
1192 print *, any(a .eq. b, 2)
1193 end subroutine section
1194 end program test_any
1201 @section @code{ASIN} --- Arcsine function
1204 @cindex trigonometric function, sine, inverse
1205 @cindex sine, inverse
1208 @item @emph{Description}:
1209 @code{ASIN(X)} computes the arcsine of its @var{X} (inverse of @code{SIN(X)}).
1211 @item @emph{Standard}:
1212 Fortran 77 and later, for a complex argument Fortran 2008 or later
1217 @item @emph{Syntax}:
1218 @code{RESULT = ASIN(X)}
1220 @item @emph{Arguments}:
1221 @multitable @columnfractions .15 .70
1222 @item @var{X} @tab The type shall be either @code{REAL} and a magnitude that is
1223 less than or equal to one - or be @code{COMPLEX}.
1226 @item @emph{Return value}:
1227 The return value is of the same type and kind as @var{X}.
1228 The real part of the result is in radians and lies in the range
1229 @math{-\pi/2 \leq \Re \asin(x) \leq \pi/2}.
1231 @item @emph{Example}:
1234 real(8) :: x = 0.866_8
1236 end program test_asin
1239 @item @emph{Specific names}:
1240 @multitable @columnfractions .20 .20 .20 .25
1241 @item Name @tab Argument @tab Return type @tab Standard
1242 @item @code{ASIN(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab Fortran 77 and later
1243 @item @code{DASIN(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab Fortran 77 and later
1246 @item @emph{See also}:
1247 Inverse function: @ref{SIN}
1254 @section @code{ASINH} --- Inverse hyperbolic sine function
1257 @cindex area hyperbolic sine
1258 @cindex inverse hyperbolic sine
1259 @cindex hyperbolic function, sine, inverse
1260 @cindex sine, hyperbolic, inverse
1263 @item @emph{Description}:
1264 @code{ASINH(X)} computes the inverse hyperbolic sine of @var{X}.
1266 @item @emph{Standard}:
1267 Fortran 2008 and later
1272 @item @emph{Syntax}:
1273 @code{RESULT = ASINH(X)}
1275 @item @emph{Arguments}:
1276 @multitable @columnfractions .15 .70
1277 @item @var{X} @tab The type shall be @code{REAL} or @code{COMPLEX}.
1280 @item @emph{Return value}:
1281 The return value is of the same type and kind as @var{X}. If @var{X} is
1282 complex, the imaginary part of the result is in radians and lies between
1283 @math{-\pi/2 \leq \Im \asinh(x) \leq \pi/2}.
1285 @item @emph{Example}:
1288 REAL(8), DIMENSION(3) :: x = (/ -1.0, 0.0, 1.0 /)
1289 WRITE (*,*) ASINH(x)
1293 @item @emph{Specific names}:
1294 @multitable @columnfractions .20 .20 .20 .25
1295 @item Name @tab Argument @tab Return type @tab Standard
1296 @item @code{DASINH(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU extension.
1299 @item @emph{See also}:
1300 Inverse function: @ref{SINH}
1306 @section @code{ASSOCIATED} --- Status of a pointer or pointer/target pair
1308 @cindex pointer, status
1309 @cindex association status
1312 @item @emph{Description}:
1313 @code{ASSOCIATED(POINTER [, TARGET])} determines the status of the pointer
1314 @var{POINTER} or if @var{POINTER} is associated with the target @var{TARGET}.
1316 @item @emph{Standard}:
1317 Fortran 95 and later
1322 @item @emph{Syntax}:
1323 @code{RESULT = ASSOCIATED(POINTER [, TARGET])}
1325 @item @emph{Arguments}:
1326 @multitable @columnfractions .15 .70
1327 @item @var{POINTER} @tab @var{POINTER} shall have the @code{POINTER} attribute
1328 and it can be of any type.
1329 @item @var{TARGET} @tab (Optional) @var{TARGET} shall be a pointer or
1330 a target. It must have the same type, kind type parameter, and
1331 array rank as @var{POINTER}.
1333 The association status of neither @var{POINTER} nor @var{TARGET} shall be
1336 @item @emph{Return value}:
1337 @code{ASSOCIATED(POINTER)} returns a scalar value of type @code{LOGICAL(4)}.
1338 There are several cases:
1340 @item (A) When the optional @var{TARGET} is not present then
1341 @code{ASSOCIATED(POINTER)} is true if @var{POINTER} is associated with a target; otherwise, it returns false.
1342 @item (B) If @var{TARGET} is present and a scalar target, the result is true if
1343 @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
1344 disassociated, the result is false.
1345 @item (C) If @var{TARGET} is present and an array target, the result is true if
1346 @var{TARGET} and @var{POINTER} have the same shape, are not zero-sized arrays,
1347 are arrays whose elements are not zero-sized storage sequences, and
1348 @var{TARGET} and @var{POINTER} occupy the same storage units in array element
1350 As in case(B), the result is false, if @var{POINTER} is disassociated.
1351 @item (D) If @var{TARGET} is present and an scalar pointer, the result is true
1352 if @var{TARGET} is associated with @var{POINTER}, the target associated with
1353 @var{TARGET} are not zero-sized storage sequences and occupy the same storage
1355 The result is false, if either @var{TARGET} or @var{POINTER} is disassociated.
1356 @item (E) If @var{TARGET} is present and an array pointer, the result is true if
1357 target associated with @var{POINTER} and the target associated with @var{TARGET}
1358 have the same shape, are not zero-sized arrays, are arrays whose elements are
1359 not zero-sized storage sequences, and @var{TARGET} and @var{POINTER} occupy
1360 the same storage units in array element order.
1361 The result is false, if either @var{TARGET} or @var{POINTER} is disassociated.
1364 @item @emph{Example}:
1366 program test_associated
1368 real, target :: tgt(2) = (/1., 2./)
1369 real, pointer :: ptr(:)
1371 if (associated(ptr) .eqv. .false.) call abort
1372 if (associated(ptr,tgt) .eqv. .false.) call abort
1373 end program test_associated
1376 @item @emph{See also}:
1383 @section @code{ATAN} --- Arctangent function
1386 @cindex trigonometric function, tangent, inverse
1387 @cindex tangent, inverse
1390 @item @emph{Description}:
1391 @code{ATAN(X)} computes the arctangent of @var{X}.
1393 @item @emph{Standard}:
1394 Fortran 77 and later, for a complex argument and for two arguments
1395 Fortran 2008 or later
1400 @item @emph{Syntax}:
1401 @multitable @columnfractions .80
1402 @item @code{RESULT = ATAN(X)}
1403 @item @code{RESULT = ATAN(Y, X)}
1406 @item @emph{Arguments}:
1407 @multitable @columnfractions .15 .70
1408 @item @var{X} @tab The type shall be @code{REAL} or @code{COMPLEX};
1409 if @var{Y} is present, @var{X} shall be REAL.
1410 @item @var{Y} shall be of the same type and kind as @var{X}.
1413 @item @emph{Return value}:
1414 The return value is of the same type and kind as @var{X}.
1415 If @var{Y} is present, the result is identical to @code{ATAN2(Y,X)}.
1416 Otherwise, it the arcus tangent of @var{X}, where the real part of
1417 the result is in radians and lies in the range
1418 @math{-\pi/2 \leq \Re \atan(x) \leq \pi/2}.
1420 @item @emph{Example}:
1423 real(8) :: x = 2.866_8
1425 end program test_atan
1428 @item @emph{Specific names}:
1429 @multitable @columnfractions .20 .20 .20 .25
1430 @item Name @tab Argument @tab Return type @tab Standard
1431 @item @code{ATAN(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab Fortran 77 and later
1432 @item @code{DATAN(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab Fortran 77 and later
1435 @item @emph{See also}:
1436 Inverse function: @ref{TAN}
1443 @section @code{ATAN2} --- Arctangent function
1446 @cindex trigonometric function, tangent, inverse
1447 @cindex tangent, inverse
1450 @item @emph{Description}:
1451 @code{ATAN2(Y, X)} computes the principal value of the argument
1452 function of the complex number @math{X + i Y}. This function can
1453 be used to transform from Cartesian into polar coordinates and
1454 allows to determine the angle in the correct quadrant.
1456 @item @emph{Standard}:
1457 Fortran 77 and later
1462 @item @emph{Syntax}:
1463 @code{RESULT = ATAN2(Y, X)}
1465 @item @emph{Arguments}:
1466 @multitable @columnfractions .15 .70
1467 @item @var{Y} @tab The type shall be @code{REAL}.
1468 @item @var{X} @tab The type and kind type parameter shall be the same as @var{Y}.
1469 If @var{Y} is zero, then @var{X} must be nonzero.
1472 @item @emph{Return value}:
1473 The return value has the same type and kind type parameter as @var{Y}.
1474 It is the principal value of the complex number @math{X + i Y}. If
1475 @var{X} is nonzero, then it lies in the range @math{-\pi \le \atan (x) \leq \pi}.
1476 The sign is positive if @var{Y} is positive. If @var{Y} is zero, then
1477 the return value is zero if @var{X} is positive and @math{\pi} if @var{X}
1478 is negative. Finally, if @var{X} is zero, then the magnitude of the result
1481 @item @emph{Example}:
1484 real(4) :: x = 1.e0_4, y = 0.5e0_4
1486 end program test_atan2
1489 @item @emph{Specific names}:
1490 @multitable @columnfractions .20 .20 .20 .25
1491 @item Name @tab Argument @tab Return type @tab Standard
1492 @item @code{ATAN2(X, Y)} @tab @code{REAL(4) X, Y} @tab @code{REAL(4)} @tab Fortran 77 and later
1493 @item @code{DATAN2(X, Y)} @tab @code{REAL(8) X, Y} @tab @code{REAL(8)} @tab Fortran 77 and later
1500 @section @code{ATANH} --- Inverse hyperbolic tangent function
1503 @cindex area hyperbolic tangent
1504 @cindex inverse hyperbolic tangent
1505 @cindex hyperbolic function, tangent, inverse
1506 @cindex tangent, hyperbolic, inverse
1509 @item @emph{Description}:
1510 @code{ATANH(X)} computes the inverse hyperbolic tangent of @var{X}.
1512 @item @emph{Standard}:
1513 Fortran 2008 and later
1518 @item @emph{Syntax}:
1519 @code{RESULT = ATANH(X)}
1521 @item @emph{Arguments}:
1522 @multitable @columnfractions .15 .70
1523 @item @var{X} @tab The type shall be @code{REAL} or @code{COMPLEX}.
1526 @item @emph{Return value}:
1527 The return value has same type and kind as @var{X}. If @var{X} is
1528 complex, the imaginary part of the result is in radians and lies between
1529 @math{-\pi/2 \leq \Im \atanh(x) \leq \pi/2}.
1531 @item @emph{Example}:
1534 REAL, DIMENSION(3) :: x = (/ -1.0, 0.0, 1.0 /)
1535 WRITE (*,*) ATANH(x)
1539 @item @emph{Specific names}:
1540 @multitable @columnfractions .20 .20 .20 .25
1541 @item Name @tab Argument @tab Return type @tab Standard
1542 @item @code{DATANH(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU extension
1545 @item @emph{See also}:
1546 Inverse function: @ref{TANH}
1552 @section @code{ATOMIC_DEFINE} --- Setting a variable atomically
1553 @fnindex ATOMIC_DEFINE
1554 @cindex Atomic subroutine, define
1557 @item @emph{Description}:
1558 @code{ATOMIC_DEFINE(ATOM, VALUE)} defines the variable @var{ATOM} with the value
1559 @var{VALUE} atomically.
1561 @item @emph{Standard}:
1562 Fortran 2008 and later
1567 @item @emph{Syntax}:
1568 @code{CALL ATOMIC_DEFINE(ATOM, VALUE)}
1570 @item @emph{Arguments}:
1571 @multitable @columnfractions .15 .70
1572 @item @var{ATOM} @tab Scalar coarray or coindexed variable of either integer
1573 type with @code{ATOMIC_INT_KIND} kind or logical type
1574 with @code{ATOMIC_LOGICAL_KIND} kind.
1575 @item @var{VALURE} @tab Scalar and of the same type as @var{ATOM}. If the kind
1576 is different, the value is converted to the kind of
1580 @item @emph{Example}:
1584 integer(atomic_int_kind) :: atom[*]
1585 call atomic_define (atom[1], this_image())
1589 @item @emph{See also}:
1590 @ref{ATOMIC_REF}, @ref{ISO_FORTRAN_ENV}
1596 @section @code{ATOMIC_REF} --- Obtaining the value of a variable atomically
1598 @cindex Atomic subroutine, reference
1601 @item @emph{Description}:
1602 @code{ATOMIC_DEFINE(ATOM, VALUE)} atomically assigns the value of the
1603 variable @var{ATOM} to @var{VALUE}.
1605 @item @emph{Standard}:
1606 Fortran 2008 and later
1611 @item @emph{Syntax}:
1612 @code{CALL ATOMIC_REF(VALUE, ATOM)}
1614 @item @emph{Arguments}:
1615 @multitable @columnfractions .15 .70
1616 @item @var{VALURE} @tab Scalar and of the same type as @var{ATOM}. If the kind
1617 is different, the value is converted to the kind of
1619 @item @var{ATOM} @tab Scalar coarray or coindexed variable of either integer
1620 type with @code{ATOMIC_INT_KIND} kind or logical type
1621 with @code{ATOMIC_LOGICAL_KIND} kind.
1624 @item @emph{Example}:
1628 logical(atomic_logical_kind) :: atom[*]
1630 call atomic_ref (atom, .false.)
1632 call atomic_ref (atom, val)
1639 @item @emph{See also}:
1640 @ref{ATOMIC_DEFINE}, @ref{ISO_FORTRAN_ENV}
1646 @section @code{BESSEL_J0} --- Bessel function of the first kind of order 0
1650 @cindex Bessel function, first kind
1653 @item @emph{Description}:
1654 @code{BESSEL_J0(X)} computes the Bessel function of the first kind of
1655 order 0 of @var{X}. This function is available under the name
1656 @code{BESJ0} as a GNU extension.
1658 @item @emph{Standard}:
1659 Fortran 2008 and later
1664 @item @emph{Syntax}:
1665 @code{RESULT = BESSEL_J0(X)}
1667 @item @emph{Arguments}:
1668 @multitable @columnfractions .15 .70
1669 @item @var{X} @tab The type shall be @code{REAL}, and it shall be scalar.
1672 @item @emph{Return value}:
1673 The return value is of type @code{REAL} and lies in the
1674 range @math{ - 0.4027... \leq Bessel (0,x) \leq 1}. It has the same
1677 @item @emph{Example}:
1680 real(8) :: x = 0.0_8
1682 end program test_besj0
1685 @item @emph{Specific names}:
1686 @multitable @columnfractions .20 .20 .20 .25
1687 @item Name @tab Argument @tab Return type @tab Standard
1688 @item @code{DBESJ0(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU extension
1695 @section @code{BESSEL_J1} --- Bessel function of the first kind of order 1
1699 @cindex Bessel function, first kind
1702 @item @emph{Description}:
1703 @code{BESSEL_J1(X)} computes the Bessel function of the first kind of
1704 order 1 of @var{X}. This function is available under the name
1705 @code{BESJ1} as a GNU extension.
1707 @item @emph{Standard}:
1713 @item @emph{Syntax}:
1714 @code{RESULT = BESSEL_J1(X)}
1716 @item @emph{Arguments}:
1717 @multitable @columnfractions .15 .70
1718 @item @var{X} @tab The type shall be @code{REAL}, and it shall be scalar.
1721 @item @emph{Return value}:
1722 The return value is of type @code{REAL} and it lies in the
1723 range @math{ - 0.5818... \leq Bessel (0,x) \leq 0.5818 }. It has the same
1726 @item @emph{Example}:
1729 real(8) :: x = 1.0_8
1731 end program test_besj1
1734 @item @emph{Specific names}:
1735 @multitable @columnfractions .20 .20 .20 .25
1736 @item Name @tab Argument @tab Return type @tab Standard
1737 @item @code{DBESJ1(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU extension
1744 @section @code{BESSEL_JN} --- Bessel function of the first kind
1748 @cindex Bessel function, first kind
1751 @item @emph{Description}:
1752 @code{BESSEL_JN(N, X)} computes the Bessel function of the first kind of
1753 order @var{N} of @var{X}. This function is available under the name
1754 @code{BESJN} as a GNU extension. If @var{N} and @var{X} are arrays,
1755 their ranks and shapes shall conform.
1757 @code{BESSEL_JN(N1, N2, X)} returns an array with the Bessel functions
1758 of the first kind of the orders @var{N1} to @var{N2}.
1760 @item @emph{Standard}:
1761 Fortran 2008 and later, negative @var{N} is allowed as GNU extension
1764 Elemental function, except for the transformational function
1765 @code{BESSEL_JN(N1, N2, X)}
1767 @item @emph{Syntax}:
1768 @multitable @columnfractions .80
1769 @item @code{RESULT = BESSEL_JN(N, X)}
1770 @item @code{RESULT = BESSEL_JN(N1, N2, X)}
1773 @item @emph{Arguments}:
1774 @multitable @columnfractions .15 .70
1775 @item @var{N} @tab Shall be a scalar or an array of type @code{INTEGER}.
1776 @item @var{N1} @tab Shall be a non-negative scalar of type @code{INTEGER}.
1777 @item @var{N2} @tab Shall be a non-negative scalar of type @code{INTEGER}.
1778 @item @var{X} @tab Shall be a scalar or an array of type @code{REAL};
1779 for @code{BESSEL_JN(N1, N2, X)} it shall be scalar.
1782 @item @emph{Return value}:
1783 The return value is a scalar of type @code{REAL}. It has the same
1787 The transformational function uses a recurrence algorithm which might,
1788 for some values of @var{X}, lead to different results than calls to
1789 the elemental function.
1791 @item @emph{Example}:
1794 real(8) :: x = 1.0_8
1796 end program test_besjn
1799 @item @emph{Specific names}:
1800 @multitable @columnfractions .20 .20 .20 .25
1801 @item Name @tab Argument @tab Return type @tab Standard
1802 @item @code{DBESJN(N, X)} @tab @code{INTEGER N} @tab @code{REAL(8)} @tab GNU extension
1803 @item @tab @code{REAL(8) X} @tab @tab
1810 @section @code{BESSEL_Y0} --- Bessel function of the second kind of order 0
1814 @cindex Bessel function, second kind
1817 @item @emph{Description}:
1818 @code{BESSEL_Y0(X)} computes the Bessel function of the second kind of
1819 order 0 of @var{X}. This function is available under the name
1820 @code{BESY0} as a GNU extension.
1822 @item @emph{Standard}:
1823 Fortran 2008 and later
1828 @item @emph{Syntax}:
1829 @code{RESULT = BESSEL_Y0(X)}
1831 @item @emph{Arguments}:
1832 @multitable @columnfractions .15 .70
1833 @item @var{X} @tab The type shall be @code{REAL}, and it shall be scalar.
1836 @item @emph{Return value}:
1837 The return value is a scalar of type @code{REAL}. It has the same
1840 @item @emph{Example}:
1843 real(8) :: x = 0.0_8
1845 end program test_besy0
1848 @item @emph{Specific names}:
1849 @multitable @columnfractions .20 .20 .20 .25
1850 @item Name @tab Argument @tab Return type @tab Standard
1851 @item @code{DBESY0(X)}@tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU extension
1858 @section @code{BESSEL_Y1} --- Bessel function of the second kind of order 1
1862 @cindex Bessel function, second kind
1865 @item @emph{Description}:
1866 @code{BESSEL_Y1(X)} computes the Bessel function of the second kind of
1867 order 1 of @var{X}. This function is available under the name
1868 @code{BESY1} as a GNU extension.
1870 @item @emph{Standard}:
1871 Fortran 2008 and later
1876 @item @emph{Syntax}:
1877 @code{RESULT = BESSEL_Y1(X)}
1879 @item @emph{Arguments}:
1880 @multitable @columnfractions .15 .70
1881 @item @var{X} @tab The type shall be @code{REAL}, and it shall be scalar.
1884 @item @emph{Return value}:
1885 The return value is a scalar of type @code{REAL}. It has the same
1888 @item @emph{Example}:
1891 real(8) :: x = 1.0_8
1893 end program test_besy1
1896 @item @emph{Specific names}:
1897 @multitable @columnfractions .20 .20 .20 .25
1898 @item Name @tab Argument @tab Return type @tab Standard
1899 @item @code{DBESY1(X)}@tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU extension
1906 @section @code{BESSEL_YN} --- Bessel function of the second kind
1910 @cindex Bessel function, second kind
1913 @item @emph{Description}:
1914 @code{BESSEL_YN(N, X)} computes the Bessel function of the second kind of
1915 order @var{N} of @var{X}. This function is available under the name
1916 @code{BESYN} as a GNU extension. If @var{N} and @var{X} are arrays,
1917 their ranks and shapes shall conform.
1919 @code{BESSEL_YN(N1, N2, X)} returns an array with the Bessel functions
1920 of the first kind of the orders @var{N1} to @var{N2}.
1922 @item @emph{Standard}:
1923 Fortran 2008 and later, negative @var{N} is allowed as GNU extension
1926 Elemental function, except for the transformational function
1927 @code{BESSEL_YN(N1, N2, X)}
1929 @item @emph{Syntax}:
1930 @multitable @columnfractions .80
1931 @item @code{RESULT = BESSEL_YN(N, X)}
1932 @item @code{RESULT = BESSEL_YN(N1, N2, X)}
1935 @item @emph{Arguments}:
1936 @multitable @columnfractions .15 .70
1937 @item @var{N} @tab Shall be a scalar or an array of type @code{INTEGER} .
1938 @item @var{N1} @tab Shall be a non-negative scalar of type @code{INTEGER}.
1939 @item @var{N2} @tab Shall be a non-negative scalar of type @code{INTEGER}.
1940 @item @var{X} @tab Shall be a scalar or an array of type @code{REAL};
1941 for @code{BESSEL_YN(N1, N2, X)} it shall be scalar.
1944 @item @emph{Return value}:
1945 The return value is a scalar of type @code{REAL}. It has the same
1949 The transformational function uses a recurrence algorithm which might,
1950 for some values of @var{X}, lead to different results than calls to
1951 the elemental function.
1953 @item @emph{Example}:
1956 real(8) :: x = 1.0_8
1958 end program test_besyn
1961 @item @emph{Specific names}:
1962 @multitable @columnfractions .20 .20 .20 .25
1963 @item Name @tab Argument @tab Return type @tab Standard
1964 @item @code{DBESYN(N,X)} @tab @code{INTEGER N} @tab @code{REAL(8)} @tab GNU extension
1965 @item @tab @code{REAL(8) X} @tab @tab
1972 @section @code{BGE} --- Bitwise greater than or equal to
1974 @cindex bitwise comparison
1977 @item @emph{Description}:
1978 Determines whether an integral is a bitwise greater than or equal to
1981 @item @emph{Standard}:
1982 Fortran 2008 and later
1987 @item @emph{Syntax}:
1988 @code{RESULT = BGE(I, J)}
1990 @item @emph{Arguments}:
1991 @multitable @columnfractions .15 .70
1992 @item @var{I} @tab Shall be of @code{INTEGER} type.
1993 @item @var{J} @tab Shall be of @code{INTEGER} type, and of the same kind
1997 @item @emph{Return value}:
1998 The return value is of type @code{LOGICAL} and of the default kind.
2000 @item @emph{See also}:
2001 @ref{BGT}, @ref{BLE}, @ref{BLT}
2007 @section @code{BGT} --- Bitwise greater than
2009 @cindex bitwise comparison
2012 @item @emph{Description}:
2013 Determines whether an integral is a bitwise greater than another.
2015 @item @emph{Standard}:
2016 Fortran 2008 and later
2021 @item @emph{Syntax}:
2022 @code{RESULT = BGT(I, J)}
2024 @item @emph{Arguments}:
2025 @multitable @columnfractions .15 .70
2026 @item @var{I} @tab Shall be of @code{INTEGER} type.
2027 @item @var{J} @tab Shall be of @code{INTEGER} type, and of the same kind
2031 @item @emph{Return value}:
2032 The return value is of type @code{LOGICAL} and of the default kind.
2034 @item @emph{See also}:
2035 @ref{BGE}, @ref{BLE}, @ref{BLT}
2041 @section @code{BIT_SIZE} --- Bit size inquiry function
2043 @cindex bits, number of
2044 @cindex size of a variable, in bits
2047 @item @emph{Description}:
2048 @code{BIT_SIZE(I)} returns the number of bits (integer precision plus sign bit)
2049 represented by the type of @var{I}. The result of @code{BIT_SIZE(I)} is
2050 independent of the actual value of @var{I}.
2052 @item @emph{Standard}:
2053 Fortran 95 and later
2058 @item @emph{Syntax}:
2059 @code{RESULT = BIT_SIZE(I)}
2061 @item @emph{Arguments}:
2062 @multitable @columnfractions .15 .70
2063 @item @var{I} @tab The type shall be @code{INTEGER}.
2066 @item @emph{Return value}:
2067 The return value is of type @code{INTEGER}
2069 @item @emph{Example}:
2071 program test_bit_size
2076 end program test_bit_size
2083 @section @code{BLE} --- Bitwise less than or equal to
2085 @cindex bitwise comparison
2088 @item @emph{Description}:
2089 Determines whether an integral is a bitwise less than or equal to
2092 @item @emph{Standard}:
2093 Fortran 2008 and later
2098 @item @emph{Syntax}:
2099 @code{RESULT = BLE(I, J)}
2101 @item @emph{Arguments}:
2102 @multitable @columnfractions .15 .70
2103 @item @var{I} @tab Shall be of @code{INTEGER} type.
2104 @item @var{J} @tab Shall be of @code{INTEGER} type, and of the same kind
2108 @item @emph{Return value}:
2109 The return value is of type @code{LOGICAL} and of the default kind.
2111 @item @emph{See also}:
2112 @ref{BGT}, @ref{BGE}, @ref{BLT}
2118 @section @code{BLT} --- Bitwise less than
2120 @cindex bitwise comparison
2123 @item @emph{Description}:
2124 Determines whether an integral is a bitwise less than another.
2126 @item @emph{Standard}:
2127 Fortran 2008 and later
2132 @item @emph{Syntax}:
2133 @code{RESULT = BLT(I, J)}
2135 @item @emph{Arguments}:
2136 @multitable @columnfractions .15 .70
2137 @item @var{I} @tab Shall be of @code{INTEGER} type.
2138 @item @var{J} @tab Shall be of @code{INTEGER} type, and of the same kind
2142 @item @emph{Return value}:
2143 The return value is of type @code{LOGICAL} and of the default kind.
2145 @item @emph{See also}:
2146 @ref{BGE}, @ref{BGT}, @ref{BLE}
2152 @section @code{BTEST} --- Bit test function
2154 @cindex bits, testing
2157 @item @emph{Description}:
2158 @code{BTEST(I,POS)} returns logical @code{.TRUE.} if the bit at @var{POS}
2159 in @var{I} is set. The counting of the bits starts at 0.
2161 @item @emph{Standard}:
2162 Fortran 95 and later
2167 @item @emph{Syntax}:
2168 @code{RESULT = BTEST(I, POS)}
2170 @item @emph{Arguments}:
2171 @multitable @columnfractions .15 .70
2172 @item @var{I} @tab The type shall be @code{INTEGER}.
2173 @item @var{POS} @tab The type shall be @code{INTEGER}.
2176 @item @emph{Return value}:
2177 The return value is of type @code{LOGICAL}
2179 @item @emph{Example}:
2182 integer :: i = 32768 + 1024 + 64
2186 bool = btest(i, pos)
2189 end program test_btest
2195 @section @code{C_ASSOCIATED} --- Status of a C pointer
2196 @fnindex C_ASSOCIATED
2197 @cindex association status, C pointer
2198 @cindex pointer, C association status
2201 @item @emph{Description}:
2202 @code{C_ASSOCIATED(c_prt_1[, c_ptr_2])} determines the status of the C pointer
2203 @var{c_ptr_1} or if @var{c_ptr_1} is associated with the target @var{c_ptr_2}.
2205 @item @emph{Standard}:
2206 Fortran 2003 and later
2211 @item @emph{Syntax}:
2212 @code{RESULT = C_ASSOCIATED(c_prt_1[, c_ptr_2])}
2214 @item @emph{Arguments}:
2215 @multitable @columnfractions .15 .70
2216 @item @var{c_ptr_1} @tab Scalar of the type @code{C_PTR} or @code{C_FUNPTR}.
2217 @item @var{c_ptr_2} @tab (Optional) Scalar of the same type as @var{c_ptr_1}.
2220 @item @emph{Return value}:
2221 The return value is of type @code{LOGICAL}; it is @code{.false.} if either
2222 @var{c_ptr_1} is a C NULL pointer or if @var{c_ptr1} and @var{c_ptr_2}
2223 point to different addresses.
2225 @item @emph{Example}:
2227 subroutine association_test(a,b)
2228 use iso_c_binding, only: c_associated, c_loc, c_ptr
2232 if(c_associated(b, c_loc(a))) &
2233 stop 'b and a do not point to same target'
2234 end subroutine association_test
2237 @item @emph{See also}:
2238 @ref{C_LOC}, @ref{C_FUNLOC}
2243 @section @code{C_FUNLOC} --- Obtain the C address of a procedure
2245 @cindex pointer, C address of procedures
2248 @item @emph{Description}:
2249 @code{C_FUNLOC(x)} determines the C address of the argument.
2251 @item @emph{Standard}:
2252 Fortran 2003 and later
2257 @item @emph{Syntax}:
2258 @code{RESULT = C_FUNLOC(x)}
2260 @item @emph{Arguments}:
2261 @multitable @columnfractions .15 .70
2262 @item @var{x} @tab Interoperable function or pointer to such function.
2265 @item @emph{Return value}:
2266 The return value is of type @code{C_FUNPTR} and contains the C address
2269 @item @emph{Example}:
2275 subroutine sub(a) bind(c)
2285 subroutine my_routine(p) bind(c,name='myC_func')
2287 type(c_funptr), intent(in) :: p
2290 call my_routine(c_funloc(sub))
2294 @item @emph{See also}:
2295 @ref{C_ASSOCIATED}, @ref{C_LOC}, @ref{C_F_POINTER}, @ref{C_F_PROCPOINTER}
2299 @node C_F_PROCPOINTER
2300 @section @code{C_F_PROCPOINTER} --- Convert C into Fortran procedure pointer
2301 @fnindex C_F_PROCPOINTER
2302 @cindex pointer, C address of pointers
2305 @item @emph{Description}:
2306 @code{C_F_PROCPOINTER(CPTR, FPTR)} Assign the target of the C function pointer
2307 @var{CPTR} to the Fortran procedure pointer @var{FPTR}.
2309 @item @emph{Standard}:
2310 Fortran 2003 and later
2315 @item @emph{Syntax}:
2316 @code{CALL C_F_PROCPOINTER(cptr, fptr)}
2318 @item @emph{Arguments}:
2319 @multitable @columnfractions .15 .70
2320 @item @var{CPTR} @tab scalar of the type @code{C_FUNPTR}. It is
2322 @item @var{FPTR} @tab procedure pointer interoperable with @var{cptr}. It is
2326 @item @emph{Example}:
2334 real(c_float), intent(in) :: a
2335 real(c_float) :: func
2339 function getIterFunc() bind(c,name="getIterFunc")
2341 type(c_funptr) :: getIterFunc
2344 type(c_funptr) :: cfunptr
2345 procedure(func), pointer :: myFunc
2346 cfunptr = getIterFunc()
2347 call c_f_procpointer(cfunptr, myFunc)
2351 @item @emph{See also}:
2352 @ref{C_LOC}, @ref{C_F_POINTER}
2357 @section @code{C_F_POINTER} --- Convert C into Fortran pointer
2358 @fnindex C_F_POINTER
2359 @cindex pointer, convert C to Fortran
2362 @item @emph{Description}:
2363 @code{C_F_POINTER(CPTR, FPTR[, SHAPE])} Assign the target the C pointer
2364 @var{CPTR} to the Fortran pointer @var{FPTR} and specify its
2367 @item @emph{Standard}:
2368 Fortran 2003 and later
2373 @item @emph{Syntax}:
2374 @code{CALL C_F_POINTER(CPTR, FPTR[, SHAPE])}
2376 @item @emph{Arguments}:
2377 @multitable @columnfractions .15 .70
2378 @item @var{CPTR} @tab scalar of the type @code{C_PTR}. It is
2380 @item @var{FPTR} @tab pointer interoperable with @var{cptr}. It is
2382 @item @var{SHAPE} @tab (Optional) Rank-one array of type @code{INTEGER}
2383 with @code{INTENT(IN)}. It shall be present
2384 if and only if @var{fptr} is an array. The size
2385 must be equal to the rank of @var{fptr}.
2388 @item @emph{Example}:
2394 subroutine my_routine(p) bind(c,name='myC_func')
2396 type(c_ptr), intent(out) :: p
2400 real,pointer :: a(:)
2401 call my_routine(cptr)
2402 call c_f_pointer(cptr, a, [12])
2406 @item @emph{See also}:
2407 @ref{C_LOC}, @ref{C_F_PROCPOINTER}
2412 @section @code{C_LOC} --- Obtain the C address of an object
2414 @cindex procedure pointer, convert C to Fortran
2417 @item @emph{Description}:
2418 @code{C_LOC(X)} determines the C address of the argument.
2420 @item @emph{Standard}:
2421 Fortran 2003 and later
2426 @item @emph{Syntax}:
2427 @code{RESULT = C_LOC(X)}
2429 @item @emph{Arguments}:
2430 @multitable @columnfractions .10 .75
2431 @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.
2435 @item @emph{Return value}:
2436 The return value is of type @code{C_PTR} and contains the C address
2439 @item @emph{Example}:
2441 subroutine association_test(a,b)
2442 use iso_c_binding, only: c_associated, c_loc, c_ptr
2446 if(c_associated(b, c_loc(a))) &
2447 stop 'b and a do not point to same target'
2448 end subroutine association_test
2451 @item @emph{See also}:
2452 @ref{C_ASSOCIATED}, @ref{C_FUNLOC}, @ref{C_F_POINTER}, @ref{C_F_PROCPOINTER}
2457 @section @code{C_SIZEOF} --- Size in bytes of an expression
2459 @cindex expression size
2460 @cindex size of an expression
2463 @item @emph{Description}:
2464 @code{C_SIZEOF(X)} calculates the number of bytes of storage the
2465 expression @code{X} occupies.
2467 @item @emph{Standard}:
2471 Inquiry function of the module @code{ISO_C_BINDING}
2473 @item @emph{Syntax}:
2474 @code{N = C_SIZEOF(X)}
2476 @item @emph{Arguments}:
2477 @multitable @columnfractions .15 .70
2478 @item @var{X} @tab The argument shall be an interoperable data entity.
2481 @item @emph{Return value}:
2482 The return value is of type integer and of the system-dependent kind
2483 @code{C_SIZE_T} (from the @code{ISO_C_BINDING} module). Its value is the
2484 number of bytes occupied by the argument. If the argument has the
2485 @code{POINTER} attribute, the number of bytes of the storage area pointed
2486 to is returned. If the argument is of a derived type with @code{POINTER}
2487 or @code{ALLOCATABLE} components, the return value doesn't account for
2488 the sizes of the data pointed to by these components.
2490 @item @emph{Example}:
2494 real(c_float) :: r, s(5)
2495 print *, (c_sizeof(s)/c_sizeof(r) == 5)
2498 The example will print @code{.TRUE.} unless you are using a platform
2499 where default @code{REAL} variables are unusually padded.
2501 @item @emph{See also}:
2502 @ref{SIZEOF}, @ref{STORAGE_SIZE}
2507 @section @code{CEILING} --- Integer ceiling function
2510 @cindex rounding, ceiling
2513 @item @emph{Description}:
2514 @code{CEILING(A)} returns the least integer greater than or equal to @var{A}.
2516 @item @emph{Standard}:
2517 Fortran 95 and later
2522 @item @emph{Syntax}:
2523 @code{RESULT = CEILING(A [, KIND])}
2525 @item @emph{Arguments}:
2526 @multitable @columnfractions .15 .70
2527 @item @var{A} @tab The type shall be @code{REAL}.
2528 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
2529 expression indicating the kind parameter of the result.
2532 @item @emph{Return value}:
2533 The return value is of type @code{INTEGER(KIND)} if @var{KIND} is present
2534 and a default-kind @code{INTEGER} otherwise.
2536 @item @emph{Example}:
2538 program test_ceiling
2541 print *, ceiling(x) ! returns 64
2542 print *, ceiling(y) ! returns -63
2543 end program test_ceiling
2546 @item @emph{See also}:
2547 @ref{FLOOR}, @ref{NINT}
2554 @section @code{CHAR} --- Character conversion function
2556 @cindex conversion, to character
2559 @item @emph{Description}:
2560 @code{CHAR(I [, KIND])} returns the character represented by the integer @var{I}.
2562 @item @emph{Standard}:
2563 Fortran 77 and later
2568 @item @emph{Syntax}:
2569 @code{RESULT = CHAR(I [, KIND])}
2571 @item @emph{Arguments}:
2572 @multitable @columnfractions .15 .70
2573 @item @var{I} @tab The type shall be @code{INTEGER}.
2574 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
2575 expression indicating the kind parameter of the result.
2578 @item @emph{Return value}:
2579 The return value is of type @code{CHARACTER(1)}
2581 @item @emph{Example}:
2587 print *, i, c ! returns 'J'
2588 end program test_char
2591 @item @emph{Specific names}:
2592 @multitable @columnfractions .20 .20 .20 .25
2593 @item Name @tab Argument @tab Return type @tab Standard
2594 @item @code{CHAR(I)} @tab @code{INTEGER I} @tab @code{CHARACTER(LEN=1)} @tab F77 and later
2598 See @ref{ICHAR} for a discussion of converting between numerical values
2599 and formatted string representations.
2601 @item @emph{See also}:
2602 @ref{ACHAR}, @ref{IACHAR}, @ref{ICHAR}
2609 @section @code{CHDIR} --- Change working directory
2611 @cindex system, working directory
2614 @item @emph{Description}:
2615 Change current working directory to a specified path.
2617 This intrinsic is provided in both subroutine and function forms; however,
2618 only one form can be used in any given program unit.
2620 @item @emph{Standard}:
2624 Subroutine, function
2626 @item @emph{Syntax}:
2627 @multitable @columnfractions .80
2628 @item @code{CALL CHDIR(NAME [, STATUS])}
2629 @item @code{STATUS = CHDIR(NAME)}
2632 @item @emph{Arguments}:
2633 @multitable @columnfractions .15 .70
2634 @item @var{NAME} @tab The type shall be @code{CHARACTER} of default
2635 kind and shall specify a valid path within the file system.
2636 @item @var{STATUS} @tab (Optional) @code{INTEGER} status flag of the default
2637 kind. Returns 0 on success, and a system specific and nonzero error code
2641 @item @emph{Example}:
2644 CHARACTER(len=255) :: path
2646 WRITE(*,*) TRIM(path)
2649 WRITE(*,*) TRIM(path)
2653 @item @emph{See also}:
2660 @section @code{CHMOD} --- Change access permissions of files
2662 @cindex file system, change access mode
2665 @item @emph{Description}:
2666 @code{CHMOD} changes the permissions of a file. This function invokes
2667 @code{/bin/chmod} and might therefore not work on all platforms.
2669 This intrinsic is provided in both subroutine and function forms; however,
2670 only one form can be used in any given program unit.
2672 @item @emph{Standard}:
2676 Subroutine, function
2678 @item @emph{Syntax}:
2679 @multitable @columnfractions .80
2680 @item @code{CALL CHMOD(NAME, MODE[, STATUS])}
2681 @item @code{STATUS = CHMOD(NAME, MODE)}
2684 @item @emph{Arguments}:
2685 @multitable @columnfractions .15 .70
2687 @item @var{NAME} @tab Scalar @code{CHARACTER} of default kind with the
2688 file name. Trailing blanks are ignored unless the character
2689 @code{achar(0)} is present, then all characters up to and excluding
2690 @code{achar(0)} are used as the file name.
2692 @item @var{MODE} @tab Scalar @code{CHARACTER} of default kind giving the
2693 file permission. @var{MODE} uses the same syntax as the @var{MODE}
2694 argument of @code{/bin/chmod}.
2696 @item @var{STATUS} @tab (optional) scalar @code{INTEGER}, which is
2697 @code{0} on success and nonzero otherwise.
2700 @item @emph{Return value}:
2701 In either syntax, @var{STATUS} is set to @code{0} on success and nonzero
2704 @item @emph{Example}:
2705 @code{CHMOD} as subroutine
2710 call chmod('test.dat','u+x',status)
2711 print *, 'Status: ', status
2712 end program chmod_test
2714 @code{CHMOD} as function:
2719 status = chmod('test.dat','u+x')
2720 print *, 'Status: ', status
2721 end program chmod_test
2729 @section @code{CMPLX} --- Complex conversion function
2731 @cindex complex numbers, conversion to
2732 @cindex conversion, to complex
2735 @item @emph{Description}:
2736 @code{CMPLX(X [, Y [, KIND]])} returns a complex number where @var{X} is converted to
2737 the real component. If @var{Y} is present it is converted to the imaginary
2738 component. If @var{Y} is not present then the imaginary component is set to
2739 0.0. If @var{X} is complex then @var{Y} must not be present.
2741 @item @emph{Standard}:
2742 Fortran 77 and later
2747 @item @emph{Syntax}:
2748 @code{RESULT = CMPLX(X [, Y [, KIND]])}
2750 @item @emph{Arguments}:
2751 @multitable @columnfractions .15 .70
2752 @item @var{X} @tab The type may be @code{INTEGER}, @code{REAL},
2754 @item @var{Y} @tab (Optional; only allowed if @var{X} is not
2755 @code{COMPLEX}.) May be @code{INTEGER} or @code{REAL}.
2756 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
2757 expression indicating the kind parameter of the result.
2760 @item @emph{Return value}:
2761 The return value is of @code{COMPLEX} type, with a kind equal to
2762 @var{KIND} if it is specified. If @var{KIND} is not specified, the
2763 result is of the default @code{COMPLEX} kind, regardless of the kinds of
2764 @var{X} and @var{Y}.
2766 @item @emph{Example}:
2773 print *, z, cmplx(x)
2774 end program test_cmplx
2777 @item @emph{See also}:
2783 @node COMMAND_ARGUMENT_COUNT
2784 @section @code{COMMAND_ARGUMENT_COUNT} --- Get number of command line arguments
2785 @fnindex COMMAND_ARGUMENT_COUNT
2786 @cindex command-line arguments
2787 @cindex command-line arguments, number of
2788 @cindex arguments, to program
2791 @item @emph{Description}:
2792 @code{COMMAND_ARGUMENT_COUNT} returns the number of arguments passed on the
2793 command line when the containing program was invoked.
2795 @item @emph{Standard}:
2796 Fortran 2003 and later
2801 @item @emph{Syntax}:
2802 @code{RESULT = COMMAND_ARGUMENT_COUNT()}
2804 @item @emph{Arguments}:
2805 @multitable @columnfractions .15 .70
2809 @item @emph{Return value}:
2810 The return value is an @code{INTEGER} of default kind.
2812 @item @emph{Example}:
2814 program test_command_argument_count
2816 count = command_argument_count()
2818 end program test_command_argument_count
2821 @item @emph{See also}:
2822 @ref{GET_COMMAND}, @ref{GET_COMMAND_ARGUMENT}
2827 @node COMPILER_OPTIONS
2828 @section @code{COMPILER_OPTIONS} --- Options passed to the compiler
2829 @fnindex COMPILER_OPTIONS
2830 @cindex flags inquiry function
2831 @cindex options inquiry function
2832 @cindex compiler flags inquiry function
2835 @item @emph{Description}:
2836 @code{COMPILER_OPTIONS} returns a string with the options used for
2839 @item @emph{Standard}:
2843 Inquiry function of the module @code{ISO_FORTRAN_ENV}
2845 @item @emph{Syntax}:
2846 @code{STR = COMPILER_OPTIONS()}
2848 @item @emph{Arguments}:
2851 @item @emph{Return value}:
2852 The return value is a default-kind string with system-dependent length.
2853 It contains the compiler flags used to compile the file, which called
2854 the @code{COMPILER_OPTIONS} intrinsic.
2856 @item @emph{Example}:
2859 print '(4a)', 'This file was compiled by ', &
2860 compiler_version(), ' using the options ', &
2865 @item @emph{See also}:
2866 @ref{COMPILER_VERSION}, @ref{ISO_FORTRAN_ENV}
2871 @node COMPILER_VERSION
2872 @section @code{COMPILER_VERSION} --- Compiler version string
2873 @fnindex COMPILER_VERSION
2874 @cindex compiler, name and version
2875 @cindex version of the compiler
2878 @item @emph{Description}:
2879 @code{COMPILER_VERSION} returns a string with the name and the
2880 version of the compiler.
2882 @item @emph{Standard}:
2886 Inquiry function of the module @code{ISO_FORTRAN_ENV}
2888 @item @emph{Syntax}:
2889 @code{STR = COMPILER_VERSION()}
2891 @item @emph{Arguments}:
2894 @item @emph{Return value}:
2895 The return value is a default-kind string with system-dependent length.
2896 It contains the name of the compiler and its version number.
2898 @item @emph{Example}:
2901 print '(4a)', 'This file was compiled by ', &
2902 compiler_version(), ' using the options ', &
2907 @item @emph{See also}:
2908 @ref{COMPILER_OPTIONS}, @ref{ISO_FORTRAN_ENV}
2914 @section @code{COMPLEX} --- Complex conversion function
2916 @cindex complex numbers, conversion to
2917 @cindex conversion, to complex
2920 @item @emph{Description}:
2921 @code{COMPLEX(X, Y)} returns a complex number where @var{X} is converted
2922 to the real component and @var{Y} is converted to the imaginary
2925 @item @emph{Standard}:
2931 @item @emph{Syntax}:
2932 @code{RESULT = COMPLEX(X, Y)}
2934 @item @emph{Arguments}:
2935 @multitable @columnfractions .15 .70
2936 @item @var{X} @tab The type may be @code{INTEGER} or @code{REAL}.
2937 @item @var{Y} @tab The type may be @code{INTEGER} or @code{REAL}.
2940 @item @emph{Return value}:
2941 If @var{X} and @var{Y} are both of @code{INTEGER} type, then the return
2942 value is of default @code{COMPLEX} type.
2944 If @var{X} and @var{Y} are of @code{REAL} type, or one is of @code{REAL}
2945 type and one is of @code{INTEGER} type, then the return value is of
2946 @code{COMPLEX} type with a kind equal to that of the @code{REAL}
2947 argument with the highest precision.
2949 @item @emph{Example}:
2951 program test_complex
2954 print *, complex(i, x)
2955 end program test_complex
2958 @item @emph{See also}:
2965 @section @code{CONJG} --- Complex conjugate function
2968 @cindex complex conjugate
2971 @item @emph{Description}:
2972 @code{CONJG(Z)} returns the conjugate of @var{Z}. If @var{Z} is @code{(x, y)}
2973 then the result is @code{(x, -y)}
2975 @item @emph{Standard}:
2976 Fortran 77 and later, has overloads that are GNU extensions
2981 @item @emph{Syntax}:
2984 @item @emph{Arguments}:
2985 @multitable @columnfractions .15 .70
2986 @item @var{Z} @tab The type shall be @code{COMPLEX}.
2989 @item @emph{Return value}:
2990 The return value is of type @code{COMPLEX}.
2992 @item @emph{Example}:
2995 complex :: z = (2.0, 3.0)
2996 complex(8) :: dz = (2.71_8, -3.14_8)
3001 end program test_conjg
3004 @item @emph{Specific names}:
3005 @multitable @columnfractions .20 .20 .20 .25
3006 @item Name @tab Argument @tab Return type @tab Standard
3007 @item @code{CONJG(Z)} @tab @code{COMPLEX Z} @tab @code{COMPLEX} @tab GNU extension
3008 @item @code{DCONJG(Z)} @tab @code{COMPLEX(8) Z} @tab @code{COMPLEX(8)} @tab GNU extension
3015 @section @code{COS} --- Cosine function
3021 @cindex trigonometric function, cosine
3025 @item @emph{Description}:
3026 @code{COS(X)} computes the cosine of @var{X}.
3028 @item @emph{Standard}:
3029 Fortran 77 and later, has overloads that are GNU extensions
3034 @item @emph{Syntax}:
3035 @code{RESULT = COS(X)}
3037 @item @emph{Arguments}:
3038 @multitable @columnfractions .15 .70
3039 @item @var{X} @tab The type shall be @code{REAL} or
3043 @item @emph{Return value}:
3044 The return value is of the same type and kind as @var{X}. The real part
3045 of the result is in radians. If @var{X} is of the type @code{REAL},
3046 the return value lies in the range @math{ -1 \leq \cos (x) \leq 1}.
3048 @item @emph{Example}:
3053 end program test_cos
3056 @item @emph{Specific names}:
3057 @multitable @columnfractions .20 .20 .20 .25
3058 @item Name @tab Argument @tab Return type @tab Standard
3059 @item @code{COS(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab Fortran 77 and later
3060 @item @code{DCOS(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab Fortran 77 and later
3061 @item @code{CCOS(X)} @tab @code{COMPLEX(4) X} @tab @code{COMPLEX(4)} @tab Fortran 77 and later
3062 @item @code{ZCOS(X)} @tab @code{COMPLEX(8) X} @tab @code{COMPLEX(8)} @tab GNU extension
3063 @item @code{CDCOS(X)} @tab @code{COMPLEX(8) X} @tab @code{COMPLEX(8)} @tab GNU extension
3066 @item @emph{See also}:
3067 Inverse function: @ref{ACOS}
3074 @section @code{COSH} --- Hyperbolic cosine function
3077 @cindex hyperbolic cosine
3078 @cindex hyperbolic function, cosine
3079 @cindex cosine, hyperbolic
3082 @item @emph{Description}:
3083 @code{COSH(X)} computes the hyperbolic cosine of @var{X}.
3085 @item @emph{Standard}:
3086 Fortran 77 and later, for a complex argument Fortran 2008 or later
3091 @item @emph{Syntax}:
3094 @item @emph{Arguments}:
3095 @multitable @columnfractions .15 .70
3096 @item @var{X} @tab The type shall be @code{REAL} or @code{COMPLEX}.
3099 @item @emph{Return value}:
3100 The return value has same type and kind as @var{X}. If @var{X} is
3101 complex, the imaginary part of the result is in radians. If @var{X}
3102 is @code{REAL}, the return value has a lower bound of one,
3103 @math{\cosh (x) \geq 1}.
3105 @item @emph{Example}:
3108 real(8) :: x = 1.0_8
3110 end program test_cosh
3113 @item @emph{Specific names}:
3114 @multitable @columnfractions .20 .20 .20 .25
3115 @item Name @tab Argument @tab Return type @tab Standard
3116 @item @code{COSH(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab Fortran 77 and later
3117 @item @code{DCOSH(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab Fortran 77 and later
3120 @item @emph{See also}:
3121 Inverse function: @ref{ACOSH}
3128 @section @code{COUNT} --- Count function
3130 @cindex array, conditionally count elements
3131 @cindex array, element counting
3132 @cindex array, number of elements
3135 @item @emph{Description}:
3137 Counts the number of @code{.TRUE.} elements in a logical @var{MASK},
3138 or, if the @var{DIM} argument is supplied, counts the number of
3139 elements along each row of the array in the @var{DIM} direction.
3140 If the array has zero size, or all of the elements of @var{MASK} are
3141 @code{.FALSE.}, then the result is @code{0}.
3143 @item @emph{Standard}:
3144 Fortran 95 and later, with @var{KIND} argument Fortran 2003 and later
3147 Transformational function
3149 @item @emph{Syntax}:
3150 @code{RESULT = COUNT(MASK [, DIM, KIND])}
3152 @item @emph{Arguments}:
3153 @multitable @columnfractions .15 .70
3154 @item @var{MASK} @tab The type shall be @code{LOGICAL}.
3155 @item @var{DIM} @tab (Optional) The type shall be @code{INTEGER}.
3156 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
3157 expression indicating the kind parameter of the result.
3160 @item @emph{Return value}:
3161 The return value is of type @code{INTEGER} and of kind @var{KIND}. If
3162 @var{KIND} is absent, the return value is of default integer kind.
3163 If @var{DIM} is present, the result is an array with a rank one less
3164 than the rank of @var{ARRAY}, and a size corresponding to the shape
3165 of @var{ARRAY} with the @var{DIM} dimension removed.
3167 @item @emph{Example}:
3170 integer, dimension(2,3) :: a, b
3171 logical, dimension(2,3) :: mask
3172 a = reshape( (/ 1, 2, 3, 4, 5, 6 /), (/ 2, 3 /))
3173 b = reshape( (/ 0, 7, 3, 4, 5, 8 /), (/ 2, 3 /))
3174 print '(3i3)', a(1,:)
3175 print '(3i3)', a(2,:)
3177 print '(3i3)', b(1,:)
3178 print '(3i3)', b(2,:)
3181 print '(3l3)', mask(1,:)
3182 print '(3l3)', mask(2,:)
3184 print '(3i3)', count(mask)
3186 print '(3i3)', count(mask, 1)
3188 print '(3i3)', count(mask, 2)
3189 end program test_count
3196 @section @code{CPU_TIME} --- CPU elapsed time in seconds
3198 @cindex time, elapsed
3201 @item @emph{Description}:
3202 Returns a @code{REAL} value representing the elapsed CPU time in
3203 seconds. This is useful for testing segments of code to determine
3206 If a time source is available, time will be reported with microsecond
3207 resolution. If no time source is available, @var{TIME} is set to
3210 Note that @var{TIME} may contain a, system dependent, arbitrary offset
3211 and may not start with @code{0.0}. For @code{CPU_TIME}, the absolute
3212 value is meaningless, only differences between subsequent calls to
3213 this subroutine, as shown in the example below, should be used.
3216 @item @emph{Standard}:
3217 Fortran 95 and later
3222 @item @emph{Syntax}:
3223 @code{CALL CPU_TIME(TIME)}
3225 @item @emph{Arguments}:
3226 @multitable @columnfractions .15 .70
3227 @item @var{TIME} @tab The type shall be @code{REAL} with @code{INTENT(OUT)}.
3230 @item @emph{Return value}:
3233 @item @emph{Example}:
3235 program test_cpu_time
3236 real :: start, finish
3237 call cpu_time(start)
3238 ! put code to test here
3239 call cpu_time(finish)
3240 print '("Time = ",f6.3," seconds.")',finish-start
3241 end program test_cpu_time
3244 @item @emph{See also}:
3245 @ref{SYSTEM_CLOCK}, @ref{DATE_AND_TIME}
3251 @section @code{CSHIFT} --- Circular shift elements of an array
3253 @cindex array, shift circularly
3254 @cindex array, permutation
3255 @cindex array, rotate
3258 @item @emph{Description}:
3259 @code{CSHIFT(ARRAY, SHIFT [, DIM])} performs a circular shift on elements of
3260 @var{ARRAY} along the dimension of @var{DIM}. If @var{DIM} is omitted it is
3261 taken to be @code{1}. @var{DIM} is a scalar of type @code{INTEGER} in the
3262 range of @math{1 \leq DIM \leq n)} where @math{n} is the rank of @var{ARRAY}.
3263 If the rank of @var{ARRAY} is one, then all elements of @var{ARRAY} are shifted
3264 by @var{SHIFT} places. If rank is greater than one, then all complete rank one
3265 sections of @var{ARRAY} along the given dimension are shifted. Elements
3266 shifted out one end of each rank one section are shifted back in the other end.
3268 @item @emph{Standard}:
3269 Fortran 95 and later
3272 Transformational function
3274 @item @emph{Syntax}:
3275 @code{RESULT = CSHIFT(ARRAY, SHIFT [, DIM])}
3277 @item @emph{Arguments}:
3278 @multitable @columnfractions .15 .70
3279 @item @var{ARRAY} @tab Shall be an array of any type.
3280 @item @var{SHIFT} @tab The type shall be @code{INTEGER}.
3281 @item @var{DIM} @tab The type shall be @code{INTEGER}.
3284 @item @emph{Return value}:
3285 Returns an array of same type and rank as the @var{ARRAY} argument.
3287 @item @emph{Example}:
3290 integer, dimension(3,3) :: a
3291 a = reshape( (/ 1, 2, 3, 4, 5, 6, 7, 8, 9 /), (/ 3, 3 /))
3292 print '(3i3)', a(1,:)
3293 print '(3i3)', a(2,:)
3294 print '(3i3)', a(3,:)
3295 a = cshift(a, SHIFT=(/1, 2, -1/), DIM=2)
3297 print '(3i3)', a(1,:)
3298 print '(3i3)', a(2,:)
3299 print '(3i3)', a(3,:)
3300 end program test_cshift
3307 @section @code{CTIME} --- Convert a time into a string
3309 @cindex time, conversion to string
3310 @cindex conversion, to string
3313 @item @emph{Description}:
3314 @code{CTIME} converts a system time value, such as returned by
3315 @code{TIME8}, to a string. Unless the application has called
3316 @code{setlocale}, the output will be in the default locale, of length
3317 24 and of the form @samp{Sat Aug 19 18:13:14 1995}. In other locales,
3318 a longer string may result.
3320 This intrinsic is provided in both subroutine and function forms; however,
3321 only one form can be used in any given program unit.
3323 @item @emph{Standard}:
3327 Subroutine, function
3329 @item @emph{Syntax}:
3330 @multitable @columnfractions .80
3331 @item @code{CALL CTIME(TIME, RESULT)}.
3332 @item @code{RESULT = CTIME(TIME)}.
3335 @item @emph{Arguments}:
3336 @multitable @columnfractions .15 .70
3337 @item @var{TIME} @tab The type shall be of type @code{INTEGER}.
3338 @item @var{RESULT} @tab The type shall be of type @code{CHARACTER} and
3339 of default kind. It is an @code{INTENT(OUT)} argument. If the length
3340 of this variable is too short for the time and date string to fit
3341 completely, it will be blank on procedure return.
3344 @item @emph{Return value}:
3345 The converted date and time as a string.
3347 @item @emph{Example}:
3351 character(len=30) :: date
3354 ! Do something, main part of the program
3357 print *, 'Program was started on ', date
3358 end program test_ctime
3361 @item @emph{See Also}:
3362 @ref{DATE_AND_TIME}, @ref{GMTIME}, @ref{LTIME}, @ref{TIME}, @ref{TIME8}
3368 @section @code{DATE_AND_TIME} --- Date and time subroutine
3369 @fnindex DATE_AND_TIME
3370 @cindex date, current
3371 @cindex current date
3372 @cindex time, current
3373 @cindex current time
3376 @item @emph{Description}:
3377 @code{DATE_AND_TIME(DATE, TIME, ZONE, VALUES)} gets the corresponding date and
3378 time information from the real-time system clock. @var{DATE} is
3379 @code{INTENT(OUT)} and has form ccyymmdd. @var{TIME} is @code{INTENT(OUT)} and
3380 has form hhmmss.sss. @var{ZONE} is @code{INTENT(OUT)} and has form (+-)hhmm,
3381 representing the difference with respect to Coordinated Universal Time (UTC).
3382 Unavailable time and date parameters return blanks.
3384 @var{VALUES} is @code{INTENT(OUT)} and provides the following:
3386 @multitable @columnfractions .15 .30 .40
3387 @item @tab @code{VALUE(1)}: @tab The year
3388 @item @tab @code{VALUE(2)}: @tab The month
3389 @item @tab @code{VALUE(3)}: @tab The day of the month
3390 @item @tab @code{VALUE(4)}: @tab Time difference with UTC in minutes
3391 @item @tab @code{VALUE(5)}: @tab The hour of the day
3392 @item @tab @code{VALUE(6)}: @tab The minutes of the hour
3393 @item @tab @code{VALUE(7)}: @tab The seconds of the minute
3394 @item @tab @code{VALUE(8)}: @tab The milliseconds of the second
3397 @item @emph{Standard}:
3398 Fortran 95 and later
3403 @item @emph{Syntax}:
3404 @code{CALL DATE_AND_TIME([DATE, TIME, ZONE, VALUES])}
3406 @item @emph{Arguments}:
3407 @multitable @columnfractions .15 .70
3408 @item @var{DATE} @tab (Optional) The type shall be @code{CHARACTER(LEN=8)}
3409 or larger, and of default kind.
3410 @item @var{TIME} @tab (Optional) The type shall be @code{CHARACTER(LEN=10)}
3411 or larger, and of default kind.
3412 @item @var{ZONE} @tab (Optional) The type shall be @code{CHARACTER(LEN=5)}
3413 or larger, and of default kind.
3414 @item @var{VALUES}@tab (Optional) The type shall be @code{INTEGER(8)}.
3417 @item @emph{Return value}:
3420 @item @emph{Example}:
3422 program test_time_and_date
3423 character(8) :: date
3424 character(10) :: time
3425 character(5) :: zone
3426 integer,dimension(8) :: values
3427 ! using keyword arguments
3428 call date_and_time(date,time,zone,values)
3429 call date_and_time(DATE=date,ZONE=zone)
3430 call date_and_time(TIME=time)
3431 call date_and_time(VALUES=values)
3432 print '(a,2x,a,2x,a)', date, time, zone
3433 print '(8i5))', values
3434 end program test_time_and_date
3437 @item @emph{See also}:
3438 @ref{CPU_TIME}, @ref{SYSTEM_CLOCK}
3444 @section @code{DBLE} --- Double conversion function
3446 @cindex conversion, to real
3449 @item @emph{Description}:
3450 @code{DBLE(A)} Converts @var{A} to double precision real type.
3452 @item @emph{Standard}:
3453 Fortran 77 and later
3458 @item @emph{Syntax}:
3459 @code{RESULT = DBLE(A)}
3461 @item @emph{Arguments}:
3462 @multitable @columnfractions .15 .70
3463 @item @var{A} @tab The type shall be @code{INTEGER}, @code{REAL},
3467 @item @emph{Return value}:
3468 The return value is of type double precision real.
3470 @item @emph{Example}:
3475 complex :: z = (2.3,1.14)
3476 print *, dble(x), dble(i), dble(z)
3477 end program test_dble
3480 @item @emph{See also}:
3487 @section @code{DCMPLX} --- Double complex conversion function
3489 @cindex complex numbers, conversion to
3490 @cindex conversion, to complex
3493 @item @emph{Description}:
3494 @code{DCMPLX(X [,Y])} returns a double complex number where @var{X} is
3495 converted to the real component. If @var{Y} is present it is converted to the
3496 imaginary component. If @var{Y} is not present then the imaginary component is
3497 set to 0.0. If @var{X} is complex then @var{Y} must not be present.
3499 @item @emph{Standard}:
3505 @item @emph{Syntax}:
3506 @code{RESULT = DCMPLX(X [, Y])}
3508 @item @emph{Arguments}:
3509 @multitable @columnfractions .15 .70
3510 @item @var{X} @tab The type may be @code{INTEGER}, @code{REAL},
3512 @item @var{Y} @tab (Optional if @var{X} is not @code{COMPLEX}.) May be
3513 @code{INTEGER} or @code{REAL}.
3516 @item @emph{Return value}:
3517 The return value is of type @code{COMPLEX(8)}
3519 @item @emph{Example}:
3529 print *, dcmplx(x,i)
3530 end program test_dcmplx
3536 @section @code{DIGITS} --- Significant binary digits function
3538 @cindex model representation, significant digits
3541 @item @emph{Description}:
3542 @code{DIGITS(X)} returns the number of significant binary digits of the internal
3543 model representation of @var{X}. For example, on a system using a 32-bit
3544 floating point representation, a default real number would likely return 24.
3546 @item @emph{Standard}:
3547 Fortran 95 and later
3552 @item @emph{Syntax}:
3553 @code{RESULT = DIGITS(X)}
3555 @item @emph{Arguments}:
3556 @multitable @columnfractions .15 .70
3557 @item @var{X} @tab The type may be @code{INTEGER} or @code{REAL}.
3560 @item @emph{Return value}:
3561 The return value is of type @code{INTEGER}.
3563 @item @emph{Example}:
3566 integer :: i = 12345
3572 end program test_digits
3579 @section @code{DIM} --- Positive difference
3583 @cindex positive difference
3586 @item @emph{Description}:
3587 @code{DIM(X,Y)} returns the difference @code{X-Y} if the result is positive;
3588 otherwise returns zero.
3590 @item @emph{Standard}:
3591 Fortran 77 and later
3596 @item @emph{Syntax}:
3597 @code{RESULT = DIM(X, Y)}
3599 @item @emph{Arguments}:
3600 @multitable @columnfractions .15 .70
3601 @item @var{X} @tab The type shall be @code{INTEGER} or @code{REAL}
3602 @item @var{Y} @tab The type shall be the same type and kind as @var{X}.
3605 @item @emph{Return value}:
3606 The return value is of type @code{INTEGER} or @code{REAL}.
3608 @item @emph{Example}:
3614 x = dim(4.345_8, 2.111_8)
3617 end program test_dim
3620 @item @emph{Specific names}:
3621 @multitable @columnfractions .20 .20 .20 .25
3622 @item Name @tab Argument @tab Return type @tab Standard
3623 @item @code{DIM(X,Y)} @tab @code{REAL(4) X, Y} @tab @code{REAL(4)} @tab Fortran 77 and later
3624 @item @code{IDIM(X,Y)} @tab @code{INTEGER(4) X, Y} @tab @code{INTEGER(4)} @tab Fortran 77 and later
3625 @item @code{DDIM(X,Y)} @tab @code{REAL(8) X, Y} @tab @code{REAL(8)} @tab Fortran 77 and later
3632 @section @code{DOT_PRODUCT} --- Dot product function
3633 @fnindex DOT_PRODUCT
3635 @cindex vector product
3636 @cindex product, vector
3639 @item @emph{Description}:
3640 @code{DOT_PRODUCT(VECTOR_A, VECTOR_B)} computes the dot product multiplication
3641 of two vectors @var{VECTOR_A} and @var{VECTOR_B}. The two vectors may be
3642 either numeric or logical and must be arrays of rank one and of equal size. If
3643 the vectors are @code{INTEGER} or @code{REAL}, the result is
3644 @code{SUM(VECTOR_A*VECTOR_B)}. If the vectors are @code{COMPLEX}, the result
3645 is @code{SUM(CONJG(VECTOR_A)*VECTOR_B)}. If the vectors are @code{LOGICAL},
3646 the result is @code{ANY(VECTOR_A .AND. VECTOR_B)}.
3648 @item @emph{Standard}:
3649 Fortran 95 and later
3652 Transformational function
3654 @item @emph{Syntax}:
3655 @code{RESULT = DOT_PRODUCT(VECTOR_A, VECTOR_B)}
3657 @item @emph{Arguments}:
3658 @multitable @columnfractions .15 .70
3659 @item @var{VECTOR_A} @tab The type shall be numeric or @code{LOGICAL}, rank 1.
3660 @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.
3663 @item @emph{Return value}:
3664 If the arguments are numeric, the return value is a scalar of numeric type,
3665 @code{INTEGER}, @code{REAL}, or @code{COMPLEX}. If the arguments are
3666 @code{LOGICAL}, the return value is @code{.TRUE.} or @code{.FALSE.}.
3668 @item @emph{Example}:
3670 program test_dot_prod
3671 integer, dimension(3) :: a, b
3678 print *, dot_product(a,b)
3679 end program test_dot_prod
3686 @section @code{DPROD} --- Double product function
3688 @cindex product, double-precision
3691 @item @emph{Description}:
3692 @code{DPROD(X,Y)} returns the product @code{X*Y}.
3694 @item @emph{Standard}:
3695 Fortran 77 and later
3700 @item @emph{Syntax}:
3701 @code{RESULT = DPROD(X, Y)}
3703 @item @emph{Arguments}:
3704 @multitable @columnfractions .15 .70
3705 @item @var{X} @tab The type shall be @code{REAL}.
3706 @item @var{Y} @tab The type shall be @code{REAL}.
3709 @item @emph{Return value}:
3710 The return value is of type @code{REAL(8)}.
3712 @item @emph{Example}:
3720 end program test_dprod
3723 @item @emph{Specific names}:
3724 @multitable @columnfractions .20 .20 .20 .25
3725 @item Name @tab Argument @tab Return type @tab Standard
3726 @item @code{DPROD(X,Y)} @tab @code{REAL(4) X, Y} @tab @code{REAL(4)} @tab Fortran 77 and later
3733 @section @code{DREAL} --- Double real part function
3735 @cindex complex numbers, real part
3738 @item @emph{Description}:
3739 @code{DREAL(Z)} returns the real part of complex variable @var{Z}.
3741 @item @emph{Standard}:
3747 @item @emph{Syntax}:
3748 @code{RESULT = DREAL(A)}
3750 @item @emph{Arguments}:
3751 @multitable @columnfractions .15 .70
3752 @item @var{A} @tab The type shall be @code{COMPLEX(8)}.
3755 @item @emph{Return value}:
3756 The return value is of type @code{REAL(8)}.
3758 @item @emph{Example}:
3761 complex(8) :: z = (1.3_8,7.2_8)
3763 end program test_dreal
3766 @item @emph{See also}:
3774 @section @code{DSHIFTL} --- Combined left shift
3776 @cindex left shift, combined
3780 @item @emph{Description}:
3781 @code{DSHIFTL(I, J, SHIFT)} combines bits of @var{I} and @var{J}. The
3782 rightmost @var{SHIFT} bits of the result are the leftmost @var{SHIFT}
3783 bits of @var{J}, and the remaining bits are the rightmost bits of
3786 @item @emph{Standard}:
3787 Fortran 2008 and later
3792 @item @emph{Syntax}:
3793 @code{RESULT = DSHIFTL(I, J, SHIFT)}
3795 @item @emph{Arguments}:
3796 @multitable @columnfractions .15 .70
3797 @item @var{I} @tab Shall be of type @code{INTEGER} or a BOZ constant.
3798 @item @var{J} @tab Shall be of type @code{INTEGER} or a BOZ constant.
3799 If both @var{I} and @var{J} have integer type, then they shall have
3800 the same kind type parameter. @var{I} and @var{J} shall not both be
3802 @item @var{SHIFT} @tab Shall be of type @code{INTEGER}. It shall
3803 be nonnegative. If @var{I} is not a BOZ constant, then @var{SHIFT}
3804 shall be less than or equal to @code{BIT_SIZE(I)}; otherwise,
3805 @var{SHIFT} shall be less than or equal to @code{BIT_SIZE(J)}.
3808 @item @emph{Return value}:
3809 If either @var{I} or @var{J} is a BOZ constant, it is first converted
3810 as if by the intrinsic function @code{INT} to an integer type with the
3811 kind type parameter of the other.
3813 @item @emph{See also}:
3819 @section @code{DSHIFTR} --- Combined right shift
3821 @cindex right shift, combined
3822 @cindex shift, right
3825 @item @emph{Description}:
3826 @code{DSHIFTR(I, J, SHIFT)} combines bits of @var{I} and @var{J}. The
3827 leftmost @var{SHIFT} bits of the result are the rightmost @var{SHIFT}
3828 bits of @var{I}, and the remaining bits are the leftmost bits of
3831 @item @emph{Standard}:
3832 Fortran 2008 and later
3837 @item @emph{Syntax}:
3838 @code{RESULT = DSHIFTR(I, J, SHIFT)}
3840 @item @emph{Arguments}:
3841 @multitable @columnfractions .15 .70
3842 @item @var{I} @tab Shall be of type @code{INTEGER} or a BOZ constant.
3843 @item @var{J} @tab Shall be of type @code{INTEGER} or a BOZ constant.
3844 If both @var{I} and @var{J} have integer type, then they shall have
3845 the same kind type parameter. @var{I} and @var{J} shall not both be
3847 @item @var{SHIFT} @tab Shall be of type @code{INTEGER}. It shall
3848 be nonnegative. If @var{I} is not a BOZ constant, then @var{SHIFT}
3849 shall be less than or equal to @code{BIT_SIZE(I)}; otherwise,
3850 @var{SHIFT} shall be less than or equal to @code{BIT_SIZE(J)}.
3853 @item @emph{Return value}:
3854 If either @var{I} or @var{J} is a BOZ constant, it is first converted
3855 as if by the intrinsic function @code{INT} to an integer type with the
3856 kind type parameter of the other.
3858 @item @emph{See also}:
3864 @section @code{DTIME} --- Execution time subroutine (or function)
3866 @cindex time, elapsed
3867 @cindex elapsed time
3870 @item @emph{Description}:
3871 @code{DTIME(VALUES, TIME)} initially returns the number of seconds of runtime
3872 since the start of the process's execution in @var{TIME}. @var{VALUES}
3873 returns the user and system components of this time in @code{VALUES(1)} and
3874 @code{VALUES(2)} respectively. @var{TIME} is equal to @code{VALUES(1) +
3877 Subsequent invocations of @code{DTIME} return values accumulated since the
3878 previous invocation.
3880 On some systems, the underlying timings are represented using types with
3881 sufficiently small limits that overflows (wrap around) are possible, such as
3882 32-bit types. Therefore, the values returned by this intrinsic might be, or
3883 become, negative, or numerically less than previous values, during a single
3884 run of the compiled program.
3886 Please note, that this implementation is thread safe if used within OpenMP
3887 directives, i.e., its state will be consistent while called from multiple
3888 threads. However, if @code{DTIME} is called from multiple threads, the result
3889 is still the time since the last invocation. This may not give the intended
3890 results. If possible, use @code{CPU_TIME} instead.
3892 This intrinsic is provided in both subroutine and function forms; however,
3893 only one form can be used in any given program unit.
3895 @var{VALUES} and @var{TIME} are @code{INTENT(OUT)} and provide the following:
3897 @multitable @columnfractions .15 .30 .40
3898 @item @tab @code{VALUES(1)}: @tab User time in seconds.
3899 @item @tab @code{VALUES(2)}: @tab System time in seconds.
3900 @item @tab @code{TIME}: @tab Run time since start in seconds.
3903 @item @emph{Standard}:
3907 Subroutine, function
3909 @item @emph{Syntax}:
3910 @multitable @columnfractions .80
3911 @item @code{CALL DTIME(VALUES, TIME)}.
3912 @item @code{TIME = DTIME(VALUES)}, (not recommended).
3915 @item @emph{Arguments}:
3916 @multitable @columnfractions .15 .70
3917 @item @var{VALUES}@tab The type shall be @code{REAL(4), DIMENSION(2)}.
3918 @item @var{TIME}@tab The type shall be @code{REAL(4)}.
3921 @item @emph{Return value}:
3922 Elapsed time in seconds since the last invocation or since the start of program
3923 execution if not called before.
3925 @item @emph{Example}:
3929 real, dimension(2) :: tarray
3931 call dtime(tarray, result)
3935 do i=1,100000000 ! Just a delay
3938 call dtime(tarray, result)
3942 end program test_dtime
3945 @item @emph{See also}:
3953 @section @code{EOSHIFT} --- End-off shift elements of an array
3955 @cindex array, shift
3958 @item @emph{Description}:
3959 @code{EOSHIFT(ARRAY, SHIFT[, BOUNDARY, DIM])} performs an end-off shift on
3960 elements of @var{ARRAY} along the dimension of @var{DIM}. If @var{DIM} is
3961 omitted it is taken to be @code{1}. @var{DIM} is a scalar of type
3962 @code{INTEGER} in the range of @math{1 \leq DIM \leq n)} where @math{n} is the
3963 rank of @var{ARRAY}. If the rank of @var{ARRAY} is one, then all elements of
3964 @var{ARRAY} are shifted by @var{SHIFT} places. If rank is greater than one,
3965 then all complete rank one sections of @var{ARRAY} along the given dimension are
3966 shifted. Elements shifted out one end of each rank one section are dropped. If
3967 @var{BOUNDARY} is present then the corresponding value of from @var{BOUNDARY}
3968 is copied back in the other end. If @var{BOUNDARY} is not present then the
3969 following are copied in depending on the type of @var{ARRAY}.
3971 @multitable @columnfractions .15 .80
3972 @item @emph{Array Type} @tab @emph{Boundary Value}
3973 @item Numeric @tab 0 of the type and kind of @var{ARRAY}.
3974 @item Logical @tab @code{.FALSE.}.
3975 @item Character(@var{len}) @tab @var{len} blanks.
3978 @item @emph{Standard}:
3979 Fortran 95 and later
3982 Transformational function
3984 @item @emph{Syntax}:
3985 @code{RESULT = EOSHIFT(ARRAY, SHIFT [, BOUNDARY, DIM])}
3987 @item @emph{Arguments}:
3988 @multitable @columnfractions .15 .70
3989 @item @var{ARRAY} @tab May be any type, not scalar.
3990 @item @var{SHIFT} @tab The type shall be @code{INTEGER}.
3991 @item @var{BOUNDARY} @tab Same type as @var{ARRAY}.
3992 @item @var{DIM} @tab The type shall be @code{INTEGER}.
3995 @item @emph{Return value}:
3996 Returns an array of same type and rank as the @var{ARRAY} argument.
3998 @item @emph{Example}:
4000 program test_eoshift
4001 integer, dimension(3,3) :: a
4002 a = reshape( (/ 1, 2, 3, 4, 5, 6, 7, 8, 9 /), (/ 3, 3 /))
4003 print '(3i3)', a(1,:)
4004 print '(3i3)', a(2,:)
4005 print '(3i3)', a(3,:)
4006 a = EOSHIFT(a, SHIFT=(/1, 2, 1/), BOUNDARY=-5, DIM=2)
4008 print '(3i3)', a(1,:)
4009 print '(3i3)', a(2,:)
4010 print '(3i3)', a(3,:)
4011 end program test_eoshift
4018 @section @code{EPSILON} --- Epsilon function
4020 @cindex model representation, epsilon
4023 @item @emph{Description}:
4024 @code{EPSILON(X)} returns the smallest number @var{E} of the same kind
4025 as @var{X} such that @math{1 + E > 1}.
4027 @item @emph{Standard}:
4028 Fortran 95 and later
4033 @item @emph{Syntax}:
4034 @code{RESULT = EPSILON(X)}
4036 @item @emph{Arguments}:
4037 @multitable @columnfractions .15 .70
4038 @item @var{X} @tab The type shall be @code{REAL}.
4041 @item @emph{Return value}:
4042 The return value is of same type as the argument.
4044 @item @emph{Example}:
4046 program test_epsilon
4051 end program test_epsilon
4058 @section @code{ERF} --- Error function
4060 @cindex error function
4063 @item @emph{Description}:
4064 @code{ERF(X)} computes the error function of @var{X}.
4066 @item @emph{Standard}:
4067 Fortran 2008 and later
4072 @item @emph{Syntax}:
4073 @code{RESULT = ERF(X)}
4075 @item @emph{Arguments}:
4076 @multitable @columnfractions .15 .70
4077 @item @var{X} @tab The type shall be @code{REAL}.
4080 @item @emph{Return value}:
4081 The return value is of type @code{REAL}, of the same kind as
4082 @var{X} and lies in the range @math{-1 \leq erf (x) \leq 1 }.
4084 @item @emph{Example}:
4087 real(8) :: x = 0.17_8
4089 end program test_erf
4092 @item @emph{Specific names}:
4093 @multitable @columnfractions .20 .20 .20 .25
4094 @item Name @tab Argument @tab Return type @tab Standard
4095 @item @code{DERF(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU extension
4102 @section @code{ERFC} --- Error function
4104 @cindex error function, complementary
4107 @item @emph{Description}:
4108 @code{ERFC(X)} computes the complementary error function of @var{X}.
4110 @item @emph{Standard}:
4111 Fortran 2008 and later
4116 @item @emph{Syntax}:
4117 @code{RESULT = ERFC(X)}
4119 @item @emph{Arguments}:
4120 @multitable @columnfractions .15 .70
4121 @item @var{X} @tab The type shall be @code{REAL}.
4124 @item @emph{Return value}:
4125 The return value is of type @code{REAL} and of the same kind as @var{X}.
4126 It lies in the range @math{ 0 \leq erfc (x) \leq 2 }.
4128 @item @emph{Example}:
4131 real(8) :: x = 0.17_8
4133 end program test_erfc
4136 @item @emph{Specific names}:
4137 @multitable @columnfractions .20 .20 .20 .25
4138 @item Name @tab Argument @tab Return type @tab Standard
4139 @item @code{DERFC(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU extension
4146 @section @code{ERFC_SCALED} --- Error function
4147 @fnindex ERFC_SCALED
4148 @cindex error function, complementary, exponentially-scaled
4151 @item @emph{Description}:
4152 @code{ERFC_SCALED(X)} computes the exponentially-scaled complementary
4153 error function of @var{X}.
4155 @item @emph{Standard}:
4156 Fortran 2008 and later
4161 @item @emph{Syntax}:
4162 @code{RESULT = ERFC_SCALED(X)}
4164 @item @emph{Arguments}:
4165 @multitable @columnfractions .15 .70
4166 @item @var{X} @tab The type shall be @code{REAL}.
4169 @item @emph{Return value}:
4170 The return value is of type @code{REAL} and of the same kind as @var{X}.
4172 @item @emph{Example}:
4174 program test_erfc_scaled
4175 real(8) :: x = 0.17_8
4177 end program test_erfc_scaled
4184 @section @code{ETIME} --- Execution time subroutine (or function)
4186 @cindex time, elapsed
4189 @item @emph{Description}:
4190 @code{ETIME(VALUES, TIME)} returns the number of seconds of runtime
4191 since the start of the process's execution in @var{TIME}. @var{VALUES}
4192 returns the user and system components of this time in @code{VALUES(1)} and
4193 @code{VALUES(2)} respectively. @var{TIME} is equal to @code{VALUES(1) + VALUES(2)}.
4195 On some systems, the underlying timings are represented using types with
4196 sufficiently small limits that overflows (wrap around) are possible, such as
4197 32-bit types. Therefore, the values returned by this intrinsic might be, or
4198 become, negative, or numerically less than previous values, during a single
4199 run of the compiled program.
4201 This intrinsic is provided in both subroutine and function forms; however,
4202 only one form can be used in any given program unit.
4204 @var{VALUES} and @var{TIME} are @code{INTENT(OUT)} and provide the following:
4206 @multitable @columnfractions .15 .30 .60
4207 @item @tab @code{VALUES(1)}: @tab User time in seconds.
4208 @item @tab @code{VALUES(2)}: @tab System time in seconds.
4209 @item @tab @code{TIME}: @tab Run time since start in seconds.
4212 @item @emph{Standard}:
4216 Subroutine, function
4218 @item @emph{Syntax}:
4219 @multitable @columnfractions .80
4220 @item @code{CALL ETIME(VALUES, TIME)}.
4221 @item @code{TIME = ETIME(VALUES)}, (not recommended).
4224 @item @emph{Arguments}:
4225 @multitable @columnfractions .15 .70
4226 @item @var{VALUES}@tab The type shall be @code{REAL(4), DIMENSION(2)}.
4227 @item @var{TIME}@tab The type shall be @code{REAL(4)}.
4230 @item @emph{Return value}:
4231 Elapsed time in seconds since the start of program execution.
4233 @item @emph{Example}:
4237 real, dimension(2) :: tarray
4239 call ETIME(tarray, result)
4243 do i=1,100000000 ! Just a delay
4246 call ETIME(tarray, result)
4250 end program test_etime
4253 @item @emph{See also}:
4260 @node EXECUTE_COMMAND_LINE
4261 @section @code{EXECUTE_COMMAND_LINE} --- Execute a shell command
4262 @fnindex EXECUTE_COMMAND_LINE
4263 @cindex system, system call
4264 @cindex command line
4267 @item @emph{Description}:
4268 @code{EXECUTE_COMMAND_LINE} runs a shell command, synchronously or
4271 The @code{COMMAND} argument is passed to the shell and executed, using
4272 the C library's @code{system} call. (The shell is @code{sh} on Unix
4273 systems, and @code{cmd.exe} on Windows.) If @code{WAIT} is present
4274 and has the value false, the execution of the command is asynchronous
4275 if the system supports it; otherwise, the command is executed
4278 The three last arguments allow the user to get status information. After
4279 synchronous execution, @code{EXITSTAT} contains the integer exit code of
4280 the command, as returned by @code{system}. @code{CMDSTAT} is set to zero
4281 if the command line was executed (whatever its exit status was).
4282 @code{CMDMSG} is assigned an error message if an error has occurred.
4284 Note that the @code{system} function need not be thread-safe. It is
4285 the responsibility of the user to ensure that @code{system} is not
4286 called concurrently.
4288 @item @emph{Standard}:
4289 Fortran 2008 and later
4294 @item @emph{Syntax}:
4295 @code{CALL EXECUTE_COMMAND_LINE(COMMAND [, WAIT, EXITSTAT, CMDSTAT, CMDMSG ])}
4297 @item @emph{Arguments}:
4298 @multitable @columnfractions .15 .70
4299 @item @var{COMMAND} @tab Shall be a default @code{CHARACTER} scalar.
4300 @item @var{WAIT} @tab (Optional) Shall be a default @code{LOGICAL} scalar.
4301 @item @var{EXITSTAT} @tab (Optional) Shall be an @code{INTEGER} of the
4303 @item @var{CMDSTAT} @tab (Optional) Shall be an @code{INTEGER} of the
4305 @item @var{CMDMSG} @tab (Optional) Shall be an @code{CHARACTER} scalar of the
4309 @item @emph{Example}:
4314 call execute_command_line ("external_prog.exe", exitstat=i)
4315 print *, "Exit status of external_prog.exe was ", i
4317 call execute_command_line ("reindex_files.exe", wait=.false.)
4318 print *, "Now reindexing files in the background"
4320 end program test_exec
4326 Because this intrinsic is implemented in terms of the @code{system}
4327 function call, its behavior with respect to signaling is processor
4328 dependent. In particular, on POSIX-compliant systems, the SIGINT and
4329 SIGQUIT signals will be ignored, and the SIGCHLD will be blocked. As
4330 such, if the parent process is terminated, the child process might not be
4331 terminated alongside.
4334 @item @emph{See also}:
4341 @section @code{EXIT} --- Exit the program with status.
4343 @cindex program termination
4344 @cindex terminate program
4347 @item @emph{Description}:
4348 @code{EXIT} causes immediate termination of the program with status. If status
4349 is omitted it returns the canonical @emph{success} for the system. All Fortran
4350 I/O units are closed.
4352 @item @emph{Standard}:
4358 @item @emph{Syntax}:
4359 @code{CALL EXIT([STATUS])}
4361 @item @emph{Arguments}:
4362 @multitable @columnfractions .15 .70
4363 @item @var{STATUS} @tab Shall be an @code{INTEGER} of the default kind.
4366 @item @emph{Return value}:
4367 @code{STATUS} is passed to the parent process on exit.
4369 @item @emph{Example}:
4372 integer :: STATUS = 0
4373 print *, 'This program is going to exit.'
4375 end program test_exit
4378 @item @emph{See also}:
4379 @ref{ABORT}, @ref{KILL}
4385 @section @code{EXP} --- Exponential function
4391 @cindex exponential function
4392 @cindex logarithm function, inverse
4395 @item @emph{Description}:
4396 @code{EXP(X)} computes the base @math{e} exponential of @var{X}.
4398 @item @emph{Standard}:
4399 Fortran 77 and later, has overloads that are GNU extensions
4404 @item @emph{Syntax}:
4405 @code{RESULT = EXP(X)}
4407 @item @emph{Arguments}:
4408 @multitable @columnfractions .15 .70
4409 @item @var{X} @tab The type shall be @code{REAL} or
4413 @item @emph{Return value}:
4414 The return value has same type and kind as @var{X}.
4416 @item @emph{Example}:
4421 end program test_exp
4424 @item @emph{Specific names}:
4425 @multitable @columnfractions .20 .20 .20 .25
4426 @item Name @tab Argument @tab Return type @tab Standard
4427 @item @code{EXP(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab Fortran 77 and later
4428 @item @code{DEXP(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab Fortran 77 and later
4429 @item @code{CEXP(X)} @tab @code{COMPLEX(4) X} @tab @code{COMPLEX(4)} @tab Fortran 77 and later
4430 @item @code{ZEXP(X)} @tab @code{COMPLEX(8) X} @tab @code{COMPLEX(8)} @tab GNU extension
4431 @item @code{CDEXP(X)} @tab @code{COMPLEX(8) X} @tab @code{COMPLEX(8)} @tab GNU extension
4438 @section @code{EXPONENT} --- Exponent function
4440 @cindex real number, exponent
4441 @cindex floating point, exponent
4444 @item @emph{Description}:
4445 @code{EXPONENT(X)} returns the value of the exponent part of @var{X}. If @var{X}
4446 is zero the value returned is zero.
4448 @item @emph{Standard}:
4449 Fortran 95 and later
4454 @item @emph{Syntax}:
4455 @code{RESULT = EXPONENT(X)}
4457 @item @emph{Arguments}:
4458 @multitable @columnfractions .15 .70
4459 @item @var{X} @tab The type shall be @code{REAL}.
4462 @item @emph{Return value}:
4463 The return value is of type default @code{INTEGER}.
4465 @item @emph{Example}:
4467 program test_exponent
4472 print *, exponent(0.0)
4473 end program test_exponent
4479 @node EXTENDS_TYPE_OF
4480 @section @code{EXTENDS_TYPE_OF} --- Query dynamic type for extension
4481 @fnindex EXTENDS_TYPE_OF
4484 @item @emph{Description}:
4485 Query dynamic type for extension.
4487 @item @emph{Standard}:
4488 Fortran 2003 and later
4493 @item @emph{Syntax}:
4494 @code{RESULT = EXTENDS_TYPE_OF(A, MOLD)}
4496 @item @emph{Arguments}:
4497 @multitable @columnfractions .15 .70
4498 @item @var{A} @tab Shall be an object of extensible declared type or
4499 unlimited polymorphic.
4500 @item @var{MOLD} @tab Shall be an object of extensible declared type or
4501 unlimited polymorphic.
4504 @item @emph{Return value}:
4505 The return value is a scalar of type default logical. It is true if and only if
4506 the dynamic type of A is an extension type of the dynamic type of MOLD.
4509 @item @emph{See also}:
4516 @section @code{FDATE} --- Get the current time as a string
4518 @cindex time, current
4519 @cindex current time
4520 @cindex date, current
4521 @cindex current date
4524 @item @emph{Description}:
4525 @code{FDATE(DATE)} returns the current date (using the same format as
4526 @code{CTIME}) in @var{DATE}. It is equivalent to @code{CALL CTIME(DATE,
4529 This intrinsic is provided in both subroutine and function forms; however,
4530 only one form can be used in any given program unit.
4532 @item @emph{Standard}:
4536 Subroutine, function
4538 @item @emph{Syntax}:
4539 @multitable @columnfractions .80
4540 @item @code{CALL FDATE(DATE)}.
4541 @item @code{DATE = FDATE()}.
4544 @item @emph{Arguments}:
4545 @multitable @columnfractions .15 .70
4546 @item @var{DATE}@tab The type shall be of type @code{CHARACTER} of the
4547 default kind. It is an @code{INTENT(OUT)} argument. If the length of
4548 this variable is too short for the date and time string to fit
4549 completely, it will be blank on procedure return.
4552 @item @emph{Return value}:
4553 The current date and time as a string.
4555 @item @emph{Example}:
4559 character(len=30) :: date
4561 print *, 'Program started on ', date
4562 do i = 1, 100000000 ! Just a delay
4566 print *, 'Program ended on ', date
4567 end program test_fdate
4570 @item @emph{See also}:
4571 @ref{DATE_AND_TIME}, @ref{CTIME}
4576 @section @code{FGET} --- Read a single character in stream mode from stdin
4578 @cindex read character, stream mode
4579 @cindex stream mode, read character
4580 @cindex file operation, read character
4583 @item @emph{Description}:
4584 Read a single character in stream mode from stdin by bypassing normal
4585 formatted output. Stream I/O should not be mixed with normal record-oriented
4586 (formatted or unformatted) I/O on the same unit; the results are unpredictable.
4588 This intrinsic is provided in both subroutine and function forms; however,
4589 only one form can be used in any given program unit.
4591 Note that the @code{FGET} intrinsic is provided for backwards compatibility with
4592 @command{g77}. GNU Fortran provides the Fortran 2003 Stream facility.
4593 Programmers should consider the use of new stream IO feature in new code
4594 for future portability. See also @ref{Fortran 2003 status}.
4596 @item @emph{Standard}:
4600 Subroutine, function
4602 @item @emph{Syntax}:
4603 @multitable @columnfractions .80
4604 @item @code{CALL FGET(C [, STATUS])}
4605 @item @code{STATUS = FGET(C)}
4608 @item @emph{Arguments}:
4609 @multitable @columnfractions .15 .70
4610 @item @var{C} @tab The type shall be @code{CHARACTER} and of default
4612 @item @var{STATUS} @tab (Optional) status flag of type @code{INTEGER}.
4613 Returns 0 on success, -1 on end-of-file, and a system specific positive
4614 error code otherwise.
4617 @item @emph{Example}:
4620 INTEGER, PARAMETER :: strlen = 100
4621 INTEGER :: status, i = 1
4622 CHARACTER(len=strlen) :: str = ""
4624 WRITE (*,*) 'Enter text:'
4626 CALL fget(str(i:i), status)
4627 if (status /= 0 .OR. i > strlen) exit
4630 WRITE (*,*) TRIM(str)
4634 @item @emph{See also}:
4635 @ref{FGETC}, @ref{FPUT}, @ref{FPUTC}
4641 @section @code{FGETC} --- Read a single character in stream mode
4643 @cindex read character, stream mode
4644 @cindex stream mode, read character
4645 @cindex file operation, read character
4648 @item @emph{Description}:
4649 Read a single character in stream mode by bypassing normal formatted output.
4650 Stream I/O should not be mixed with normal record-oriented (formatted or
4651 unformatted) I/O on the same unit; the results are unpredictable.
4653 This intrinsic is provided in both subroutine and function forms; however,
4654 only one form can be used in any given program unit.
4656 Note that the @code{FGET} intrinsic is provided for backwards compatibility
4657 with @command{g77}. GNU Fortran provides the Fortran 2003 Stream facility.
4658 Programmers should consider the use of new stream IO feature in new code
4659 for future portability. See also @ref{Fortran 2003 status}.
4661 @item @emph{Standard}:
4665 Subroutine, function
4667 @item @emph{Syntax}:
4668 @multitable @columnfractions .80
4669 @item @code{CALL FGETC(UNIT, C [, STATUS])}
4670 @item @code{STATUS = FGETC(UNIT, C)}
4673 @item @emph{Arguments}:
4674 @multitable @columnfractions .15 .70
4675 @item @var{UNIT} @tab The type shall be @code{INTEGER}.
4676 @item @var{C} @tab The type shall be @code{CHARACTER} and of default
4678 @item @var{STATUS} @tab (Optional) status flag of type @code{INTEGER}.
4679 Returns 0 on success, -1 on end-of-file and a system specific positive
4680 error code otherwise.
4683 @item @emph{Example}:
4686 INTEGER :: fd = 42, status
4689 OPEN(UNIT=fd, FILE="/etc/passwd", ACTION="READ", STATUS = "OLD")
4691 CALL fgetc(fd, c, status)
4692 IF (status /= 0) EXIT
4699 @item @emph{See also}:
4700 @ref{FGET}, @ref{FPUT}, @ref{FPUTC}
4706 @section @code{FLOOR} --- Integer floor function
4709 @cindex rounding, floor
4712 @item @emph{Description}:
4713 @code{FLOOR(A)} returns the greatest integer less than or equal to @var{X}.
4715 @item @emph{Standard}:
4716 Fortran 95 and later
4721 @item @emph{Syntax}:
4722 @code{RESULT = FLOOR(A [, KIND])}
4724 @item @emph{Arguments}:
4725 @multitable @columnfractions .15 .70
4726 @item @var{A} @tab The type shall be @code{REAL}.
4727 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
4728 expression indicating the kind parameter of the result.
4731 @item @emph{Return value}:
4732 The return value is of type @code{INTEGER(KIND)} if @var{KIND} is present
4733 and of default-kind @code{INTEGER} otherwise.
4735 @item @emph{Example}:
4740 print *, floor(x) ! returns 63
4741 print *, floor(y) ! returns -64
4742 end program test_floor
4745 @item @emph{See also}:
4746 @ref{CEILING}, @ref{NINT}
4753 @section @code{FLUSH} --- Flush I/O unit(s)
4755 @cindex file operation, flush
4758 @item @emph{Description}:
4759 Flushes Fortran unit(s) currently open for output. Without the optional
4760 argument, all units are flushed, otherwise just the unit specified.
4762 @item @emph{Standard}:
4768 @item @emph{Syntax}:
4769 @code{CALL FLUSH(UNIT)}
4771 @item @emph{Arguments}:
4772 @multitable @columnfractions .15 .70
4773 @item @var{UNIT} @tab (Optional) The type shall be @code{INTEGER}.
4777 Beginning with the Fortran 2003 standard, there is a @code{FLUSH}
4778 statement that should be preferred over the @code{FLUSH} intrinsic.
4780 The @code{FLUSH} intrinsic and the Fortran 2003 @code{FLUSH} statement
4781 have identical effect: they flush the runtime library's I/O buffer so
4782 that the data becomes visible to other processes. This does not guarantee
4783 that the data is committed to disk.
4785 On POSIX systems, you can request that all data is transferred to the
4786 storage device by calling the @code{fsync} function, with the POSIX file
4787 descriptor of the I/O unit as argument (retrieved with GNU intrinsic
4788 @code{FNUM}). The following example shows how:
4791 ! Declare the interface for POSIX fsync function
4793 function fsync (fd) bind(c,name="fsync")
4794 use iso_c_binding, only: c_int
4795 integer(c_int), value :: fd
4796 integer(c_int) :: fsync
4800 ! Variable declaration
4804 open (10,file="foo")
4807 ! Perform I/O on unit 10
4812 ret = fsync(fnum(10))
4814 ! Handle possible error
4815 if (ret /= 0) stop "Error calling FSYNC"
4823 @section @code{FNUM} --- File number function
4825 @cindex file operation, file number
4828 @item @emph{Description}:
4829 @code{FNUM(UNIT)} returns the POSIX file descriptor number corresponding to the
4830 open Fortran I/O unit @code{UNIT}.
4832 @item @emph{Standard}:
4838 @item @emph{Syntax}:
4839 @code{RESULT = FNUM(UNIT)}
4841 @item @emph{Arguments}:
4842 @multitable @columnfractions .15 .70
4843 @item @var{UNIT} @tab The type shall be @code{INTEGER}.
4846 @item @emph{Return value}:
4847 The return value is of type @code{INTEGER}
4849 @item @emph{Example}:
4853 open (unit=10, status = "scratch")
4857 end program test_fnum
4864 @section @code{FPUT} --- Write a single character in stream mode to stdout
4866 @cindex write character, stream mode
4867 @cindex stream mode, write character
4868 @cindex file operation, write character
4871 @item @emph{Description}:
4872 Write a single character in stream mode to stdout by bypassing normal
4873 formatted output. Stream I/O should not be mixed with normal record-oriented
4874 (formatted or unformatted) I/O on the same unit; the results are unpredictable.
4876 This intrinsic is provided in both subroutine and function forms; however,
4877 only one form can be used in any given program unit.
4879 Note that the @code{FGET} intrinsic is provided for backwards compatibility with
4880 @command{g77}. GNU Fortran provides the Fortran 2003 Stream facility.
4881 Programmers should consider the use of new stream IO feature in new code
4882 for future portability. See also @ref{Fortran 2003 status}.
4884 @item @emph{Standard}:
4888 Subroutine, function
4890 @item @emph{Syntax}:
4891 @multitable @columnfractions .80
4892 @item @code{CALL FPUT(C [, STATUS])}
4893 @item @code{STATUS = FPUT(C)}
4896 @item @emph{Arguments}:
4897 @multitable @columnfractions .15 .70
4898 @item @var{C} @tab The type shall be @code{CHARACTER} and of default
4900 @item @var{STATUS} @tab (Optional) status flag of type @code{INTEGER}.
4901 Returns 0 on success, -1 on end-of-file and a system specific positive
4902 error code otherwise.
4905 @item @emph{Example}:
4908 CHARACTER(len=10) :: str = "gfortran"
4910 DO i = 1, len_trim(str)
4916 @item @emph{See also}:
4917 @ref{FPUTC}, @ref{FGET}, @ref{FGETC}
4923 @section @code{FPUTC} --- Write a single character in stream mode
4925 @cindex write character, stream mode
4926 @cindex stream mode, write character
4927 @cindex file operation, write character
4930 @item @emph{Description}:
4931 Write a single character in stream mode by bypassing normal formatted
4932 output. Stream I/O should not be mixed with normal record-oriented
4933 (formatted or unformatted) I/O on the same unit; the results are unpredictable.
4935 This intrinsic is provided in both subroutine and function forms; however,
4936 only one form can be used in any given program unit.
4938 Note that the @code{FGET} intrinsic is provided for backwards compatibility with
4939 @command{g77}. GNU Fortran provides the Fortran 2003 Stream facility.
4940 Programmers should consider the use of new stream IO feature in new code
4941 for future portability. See also @ref{Fortran 2003 status}.
4943 @item @emph{Standard}:
4947 Subroutine, function
4949 @item @emph{Syntax}:
4950 @multitable @columnfractions .80
4951 @item @code{CALL FPUTC(UNIT, C [, STATUS])}
4952 @item @code{STATUS = FPUTC(UNIT, C)}
4955 @item @emph{Arguments}:
4956 @multitable @columnfractions .15 .70
4957 @item @var{UNIT} @tab The type shall be @code{INTEGER}.
4958 @item @var{C} @tab The type shall be @code{CHARACTER} and of default
4960 @item @var{STATUS} @tab (Optional) status flag of type @code{INTEGER}.
4961 Returns 0 on success, -1 on end-of-file and a system specific positive
4962 error code otherwise.
4965 @item @emph{Example}:
4968 CHARACTER(len=10) :: str = "gfortran"
4969 INTEGER :: fd = 42, i
4971 OPEN(UNIT = fd, FILE = "out", ACTION = "WRITE", STATUS="NEW")
4972 DO i = 1, len_trim(str)
4973 CALL fputc(fd, str(i:i))
4979 @item @emph{See also}:
4980 @ref{FPUT}, @ref{FGET}, @ref{FGETC}
4986 @section @code{FRACTION} --- Fractional part of the model representation
4988 @cindex real number, fraction
4989 @cindex floating point, fraction
4992 @item @emph{Description}:
4993 @code{FRACTION(X)} returns the fractional part of the model
4994 representation of @code{X}.
4996 @item @emph{Standard}:
4997 Fortran 95 and later
5002 @item @emph{Syntax}:
5003 @code{Y = FRACTION(X)}
5005 @item @emph{Arguments}:
5006 @multitable @columnfractions .15 .70
5007 @item @var{X} @tab The type of the argument shall be a @code{REAL}.
5010 @item @emph{Return value}:
5011 The return value is of the same type and kind as the argument.
5012 The fractional part of the model representation of @code{X} is returned;
5013 it is @code{X * RADIX(X)**(-EXPONENT(X))}.
5015 @item @emph{Example}:
5017 program test_fraction
5020 print *, fraction(x), x * radix(x)**(-exponent(x))
5021 end program test_fraction
5029 @section @code{FREE} --- Frees memory
5031 @cindex pointer, cray
5034 @item @emph{Description}:
5035 Frees memory previously allocated by @code{MALLOC}. The @code{FREE}
5036 intrinsic is an extension intended to be used with Cray pointers, and is
5037 provided in GNU Fortran to allow user to compile legacy code. For
5038 new code using Fortran 95 pointers, the memory de-allocation intrinsic is
5041 @item @emph{Standard}:
5047 @item @emph{Syntax}:
5048 @code{CALL FREE(PTR)}
5050 @item @emph{Arguments}:
5051 @multitable @columnfractions .15 .70
5052 @item @var{PTR} @tab The type shall be @code{INTEGER}. It represents the
5053 location of the memory that should be de-allocated.
5056 @item @emph{Return value}:
5059 @item @emph{Example}:
5060 See @code{MALLOC} for an example.
5062 @item @emph{See also}:
5069 @section @code{FSEEK} --- Low level file positioning subroutine
5071 @cindex file operation, seek
5072 @cindex file operation, position
5075 @item @emph{Description}:
5076 Moves @var{UNIT} to the specified @var{OFFSET}. If @var{WHENCE}
5077 is set to 0, the @var{OFFSET} is taken as an absolute value @code{SEEK_SET},
5078 if set to 1, @var{OFFSET} is taken to be relative to the current position
5079 @code{SEEK_CUR}, and if set to 2 relative to the end of the file @code{SEEK_END}.
5080 On error, @var{STATUS} is set to a nonzero value. If @var{STATUS} the seek
5083 This intrinsic routine is not fully backwards compatible with @command{g77}.
5084 In @command{g77}, the @code{FSEEK} takes a statement label instead of a
5085 @var{STATUS} variable. If FSEEK is used in old code, change
5087 CALL FSEEK(UNIT, OFFSET, WHENCE, *label)
5092 CALL FSEEK(UNIT, OFFSET, WHENCE, status)
5093 IF (status /= 0) GOTO label
5096 Please note that GNU Fortran provides the Fortran 2003 Stream facility.
5097 Programmers should consider the use of new stream IO feature in new code
5098 for future portability. See also @ref{Fortran 2003 status}.
5100 @item @emph{Standard}:
5106 @item @emph{Syntax}:
5107 @code{CALL FSEEK(UNIT, OFFSET, WHENCE[, STATUS])}
5109 @item @emph{Arguments}:
5110 @multitable @columnfractions .15 .70
5111 @item @var{UNIT} @tab Shall be a scalar of type @code{INTEGER}.
5112 @item @var{OFFSET} @tab Shall be a scalar of type @code{INTEGER}.
5113 @item @var{WHENCE} @tab Shall be a scalar of type @code{INTEGER}.
5114 Its value shall be either 0, 1 or 2.
5115 @item @var{STATUS} @tab (Optional) shall be a scalar of type
5119 @item @emph{Example}:
5122 INTEGER, PARAMETER :: SEEK_SET = 0, SEEK_CUR = 1, SEEK_END = 2
5123 INTEGER :: fd, offset, ierr
5129 OPEN(UNIT=fd, FILE="fseek.test")
5130 CALL FSEEK(fd, offset, SEEK_SET, ierr) ! move to OFFSET
5131 print *, FTELL(fd), ierr
5133 CALL FSEEK(fd, 0, SEEK_END, ierr) ! move to end
5134 print *, FTELL(fd), ierr
5136 CALL FSEEK(fd, 0, SEEK_SET, ierr) ! move to beginning
5137 print *, FTELL(fd), ierr
5143 @item @emph{See also}:
5150 @section @code{FSTAT} --- Get file status
5152 @cindex file system, file status
5155 @item @emph{Description}:
5156 @code{FSTAT} is identical to @ref{STAT}, except that information about an
5157 already opened file is obtained.
5159 The elements in @code{VALUES} are the same as described by @ref{STAT}.
5161 This intrinsic is provided in both subroutine and function forms; however,
5162 only one form can be used in any given program unit.
5164 @item @emph{Standard}:
5168 Subroutine, function
5170 @item @emph{Syntax}:
5171 @multitable @columnfractions .80
5172 @item @code{CALL FSTAT(UNIT, VALUES [, STATUS])}
5173 @item @code{STATUS = FSTAT(UNIT, VALUES)}
5176 @item @emph{Arguments}:
5177 @multitable @columnfractions .15 .70
5178 @item @var{UNIT} @tab An open I/O unit number of type @code{INTEGER}.
5179 @item @var{VALUES} @tab The type shall be @code{INTEGER(4), DIMENSION(13)}.
5180 @item @var{STATUS} @tab (Optional) status flag of type @code{INTEGER(4)}. Returns 0
5181 on success and a system specific error code otherwise.
5184 @item @emph{Example}:
5185 See @ref{STAT} for an example.
5187 @item @emph{See also}:
5188 To stat a link: @ref{LSTAT}, to stat a file: @ref{STAT}
5194 @section @code{FTELL} --- Current stream position
5196 @cindex file operation, position
5199 @item @emph{Description}:
5200 Retrieves the current position within an open file.
5202 This intrinsic is provided in both subroutine and function forms; however,
5203 only one form can be used in any given program unit.
5205 @item @emph{Standard}:
5209 Subroutine, function
5211 @item @emph{Syntax}:
5212 @multitable @columnfractions .80
5213 @item @code{CALL FTELL(UNIT, OFFSET)}
5214 @item @code{OFFSET = FTELL(UNIT)}
5217 @item @emph{Arguments}:
5218 @multitable @columnfractions .15 .70
5219 @item @var{OFFSET} @tab Shall of type @code{INTEGER}.
5220 @item @var{UNIT} @tab Shall of type @code{INTEGER}.
5223 @item @emph{Return value}:
5224 In either syntax, @var{OFFSET} is set to the current offset of unit
5225 number @var{UNIT}, or to @math{-1} if the unit is not currently open.
5227 @item @emph{Example}:
5231 OPEN(10, FILE="temp.dat")
5237 @item @emph{See also}:
5244 @section @code{GAMMA} --- Gamma function
5247 @cindex Gamma function
5248 @cindex Factorial function
5251 @item @emph{Description}:
5252 @code{GAMMA(X)} computes Gamma (@math{\Gamma}) of @var{X}. For positive,
5253 integer values of @var{X} the Gamma function simplifies to the factorial
5254 function @math{\Gamma(x)=(x-1)!}.
5258 \Gamma(x) = \int_0^\infty t^{x-1}{\rm e}^{-t}\,{\rm d}t
5262 @item @emph{Standard}:
5263 Fortran 2008 and later
5268 @item @emph{Syntax}:
5271 @item @emph{Arguments}:
5272 @multitable @columnfractions .15 .70
5273 @item @var{X} @tab Shall be of type @code{REAL} and neither zero
5274 nor a negative integer.
5277 @item @emph{Return value}:
5278 The return value is of type @code{REAL} of the same kind as @var{X}.
5280 @item @emph{Example}:
5284 x = gamma(x) ! returns 1.0
5285 end program test_gamma
5288 @item @emph{Specific names}:
5289 @multitable @columnfractions .20 .20 .20 .25
5290 @item Name @tab Argument @tab Return type @tab Standard
5291 @item @code{GAMMA(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab GNU Extension
5292 @item @code{DGAMMA(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU Extension
5295 @item @emph{See also}:
5296 Logarithm of the Gamma function: @ref{LOG_GAMMA}
5303 @section @code{GERROR} --- Get last system error message
5305 @cindex system, error handling
5308 @item @emph{Description}:
5309 Returns the system error message corresponding to the last system error.
5310 This resembles the functionality of @code{strerror(3)} in C.
5312 @item @emph{Standard}:
5318 @item @emph{Syntax}:
5319 @code{CALL GERROR(RESULT)}
5321 @item @emph{Arguments}:
5322 @multitable @columnfractions .15 .70
5323 @item @var{RESULT} @tab Shall of type @code{CHARACTER} and of default
5326 @item @emph{Example}:
5329 CHARACTER(len=100) :: msg
5335 @item @emph{See also}:
5336 @ref{IERRNO}, @ref{PERROR}
5342 @section @code{GETARG} --- Get command line arguments
5344 @cindex command-line arguments
5345 @cindex arguments, to program
5348 @item @emph{Description}:
5349 Retrieve the @var{POS}-th argument that was passed on the
5350 command line when the containing program was invoked.
5352 This intrinsic routine is provided for backwards compatibility with
5353 GNU Fortran 77. In new code, programmers should consider the use of
5354 the @ref{GET_COMMAND_ARGUMENT} intrinsic defined by the Fortran 2003
5357 @item @emph{Standard}:
5363 @item @emph{Syntax}:
5364 @code{CALL GETARG(POS, VALUE)}
5366 @item @emph{Arguments}:
5367 @multitable @columnfractions .15 .70
5368 @item @var{POS} @tab Shall be of type @code{INTEGER} and not wider than
5369 the default integer kind; @math{@var{POS} \geq 0}
5370 @item @var{VALUE} @tab Shall be of type @code{CHARACTER} and of default
5372 @item @var{VALUE} @tab Shall be of type @code{CHARACTER}.
5375 @item @emph{Return value}:
5376 After @code{GETARG} returns, the @var{VALUE} argument holds the
5377 @var{POS}th command line argument. If @var{VALUE} can not hold the
5378 argument, it is truncated to fit the length of @var{VALUE}. If there are
5379 less than @var{POS} arguments specified at the command line, @var{VALUE}
5380 will be filled with blanks. If @math{@var{POS} = 0}, @var{VALUE} is set
5381 to the name of the program (on systems that support this feature).
5383 @item @emph{Example}:
5387 CHARACTER(len=32) :: arg
5396 @item @emph{See also}:
5397 GNU Fortran 77 compatibility function: @ref{IARGC}
5399 Fortran 2003 functions and subroutines: @ref{GET_COMMAND},
5400 @ref{GET_COMMAND_ARGUMENT}, @ref{COMMAND_ARGUMENT_COUNT}
5406 @section @code{GET_COMMAND} --- Get the entire command line
5407 @fnindex GET_COMMAND
5408 @cindex command-line arguments
5409 @cindex arguments, to program
5412 @item @emph{Description}:
5413 Retrieve the entire command line that was used to invoke the program.
5415 @item @emph{Standard}:
5416 Fortran 2003 and later
5421 @item @emph{Syntax}:
5422 @code{CALL GET_COMMAND([COMMAND, LENGTH, STATUS])}
5424 @item @emph{Arguments}:
5425 @multitable @columnfractions .15 .70
5426 @item @var{COMMAND} @tab (Optional) shall be of type @code{CHARACTER} and
5428 @item @var{LENGTH} @tab (Optional) Shall be of type @code{INTEGER} and of
5430 @item @var{STATUS} @tab (Optional) Shall be of type @code{INTEGER} and of
5434 @item @emph{Return value}:
5435 If @var{COMMAND} is present, stores the entire command line that was used
5436 to invoke the program in @var{COMMAND}. If @var{LENGTH} is present, it is
5437 assigned the length of the command line. If @var{STATUS} is present, it
5438 is assigned 0 upon success of the command, -1 if @var{COMMAND} is too
5439 short to store the command line, or a positive value in case of an error.
5441 @item @emph{Example}:
5443 PROGRAM test_get_command
5444 CHARACTER(len=255) :: cmd
5445 CALL get_command(cmd)
5446 WRITE (*,*) TRIM(cmd)
5450 @item @emph{See also}:
5451 @ref{GET_COMMAND_ARGUMENT}, @ref{COMMAND_ARGUMENT_COUNT}
5456 @node GET_COMMAND_ARGUMENT
5457 @section @code{GET_COMMAND_ARGUMENT} --- Get command line arguments
5458 @fnindex GET_COMMAND_ARGUMENT
5459 @cindex command-line arguments
5460 @cindex arguments, to program
5463 @item @emph{Description}:
5464 Retrieve the @var{NUMBER}-th argument that was passed on the
5465 command line when the containing program was invoked.
5467 @item @emph{Standard}:
5468 Fortran 2003 and later
5473 @item @emph{Syntax}:
5474 @code{CALL GET_COMMAND_ARGUMENT(NUMBER [, VALUE, LENGTH, STATUS])}
5476 @item @emph{Arguments}:
5477 @multitable @columnfractions .15 .70
5478 @item @var{NUMBER} @tab Shall be a scalar of type @code{INTEGER} and of
5479 default kind, @math{@var{NUMBER} \geq 0}
5480 @item @var{VALUE} @tab (Optional) Shall be a scalar of type @code{CHARACTER}
5481 and of default kind.
5482 @item @var{LENGTH} @tab (Optional) Shall be a scalar of type @code{INTEGER}
5483 and of default kind.
5484 @item @var{STATUS} @tab (Optional) Shall be a scalar of type @code{INTEGER}
5485 and of default kind.
5488 @item @emph{Return value}:
5489 After @code{GET_COMMAND_ARGUMENT} returns, the @var{VALUE} argument holds the
5490 @var{NUMBER}-th command line argument. If @var{VALUE} can not hold the argument, it is
5491 truncated to fit the length of @var{VALUE}. If there are less than @var{NUMBER}
5492 arguments specified at the command line, @var{VALUE} will be filled with blanks.
5493 If @math{@var{NUMBER} = 0}, @var{VALUE} is set to the name of the program (on
5494 systems that support this feature). The @var{LENGTH} argument contains the
5495 length of the @var{NUMBER}-th command line argument. If the argument retrieval
5496 fails, @var{STATUS} is a positive number; if @var{VALUE} contains a truncated
5497 command line argument, @var{STATUS} is -1; and otherwise the @var{STATUS} is
5500 @item @emph{Example}:
5502 PROGRAM test_get_command_argument
5504 CHARACTER(len=32) :: arg
5508 CALL get_command_argument(i, arg)
5509 IF (LEN_TRIM(arg) == 0) EXIT
5511 WRITE (*,*) TRIM(arg)
5517 @item @emph{See also}:
5518 @ref{GET_COMMAND}, @ref{COMMAND_ARGUMENT_COUNT}
5524 @section @code{GETCWD} --- Get current working directory
5526 @cindex system, working directory
5529 @item @emph{Description}:
5530 Get current working directory.
5532 This intrinsic is provided in both subroutine and function forms; however,
5533 only one form can be used in any given program unit.
5535 @item @emph{Standard}:
5539 Subroutine, function
5541 @item @emph{Syntax}:
5542 @multitable @columnfractions .80
5543 @item @code{CALL GETCWD(C [, STATUS])}
5544 @item @code{STATUS = GETCWD(C)}
5547 @item @emph{Arguments}:
5548 @multitable @columnfractions .15 .70
5549 @item @var{C} @tab The type shall be @code{CHARACTER} and of default kind.
5550 @item @var{STATUS} @tab (Optional) status flag. Returns 0 on success,
5551 a system specific and nonzero error code otherwise.
5554 @item @emph{Example}:
5557 CHARACTER(len=255) :: cwd
5559 WRITE(*,*) TRIM(cwd)
5563 @item @emph{See also}:
5570 @section @code{GETENV} --- Get an environmental variable
5572 @cindex environment variable
5575 @item @emph{Description}:
5576 Get the @var{VALUE} of the environmental variable @var{NAME}.
5578 This intrinsic routine is provided for backwards compatibility with
5579 GNU Fortran 77. In new code, programmers should consider the use of
5580 the @ref{GET_ENVIRONMENT_VARIABLE} intrinsic defined by the Fortran
5583 Note that @code{GETENV} need not be thread-safe. It is the
5584 responsibility of the user to ensure that the environment is not being
5585 updated concurrently with a call to the @code{GETENV} intrinsic.
5587 @item @emph{Standard}:
5593 @item @emph{Syntax}:
5594 @code{CALL GETENV(NAME, VALUE)}
5596 @item @emph{Arguments}:
5597 @multitable @columnfractions .15 .70
5598 @item @var{NAME} @tab Shall be of type @code{CHARACTER} and of default kind.
5599 @item @var{VALUE} @tab Shall be of type @code{CHARACTER} and of default kind.
5602 @item @emph{Return value}:
5603 Stores the value of @var{NAME} in @var{VALUE}. If @var{VALUE} is
5604 not large enough to hold the data, it is truncated. If @var{NAME}
5605 is not set, @var{VALUE} will be filled with blanks.
5607 @item @emph{Example}:
5610 CHARACTER(len=255) :: homedir
5611 CALL getenv("HOME", homedir)
5612 WRITE (*,*) TRIM(homedir)
5616 @item @emph{See also}:
5617 @ref{GET_ENVIRONMENT_VARIABLE}
5622 @node GET_ENVIRONMENT_VARIABLE
5623 @section @code{GET_ENVIRONMENT_VARIABLE} --- Get an environmental variable
5624 @fnindex GET_ENVIRONMENT_VARIABLE
5625 @cindex environment variable
5628 @item @emph{Description}:
5629 Get the @var{VALUE} of the environmental variable @var{NAME}.
5631 Note that @code{GET_ENVIRONMENT_VARIABLE} need not be thread-safe. It
5632 is the responsibility of the user to ensure that the environment is
5633 not being updated concurrently with a call to the
5634 @code{GET_ENVIRONMENT_VARIABLE} intrinsic.
5636 @item @emph{Standard}:
5637 Fortran 2003 and later
5642 @item @emph{Syntax}:
5643 @code{CALL GET_ENVIRONMENT_VARIABLE(NAME[, VALUE, LENGTH, STATUS, TRIM_NAME)}
5645 @item @emph{Arguments}:
5646 @multitable @columnfractions .15 .70
5647 @item @var{NAME} @tab Shall be a scalar of type @code{CHARACTER}
5648 and of default kind.
5649 @item @var{VALUE} @tab (Optional) Shall be a scalar of type @code{CHARACTER}
5650 and of default kind.
5651 @item @var{LENGTH} @tab (Optional) Shall be a scalar of type @code{INTEGER}
5652 and of default kind.
5653 @item @var{STATUS} @tab (Optional) Shall be a scalar of type @code{INTEGER}
5654 and of default kind.
5655 @item @var{TRIM_NAME} @tab (Optional) Shall be a scalar of type @code{LOGICAL}
5656 and of default kind.
5659 @item @emph{Return value}:
5660 Stores the value of @var{NAME} in @var{VALUE}. If @var{VALUE} is
5661 not large enough to hold the data, it is truncated. If @var{NAME}
5662 is not set, @var{VALUE} will be filled with blanks. Argument @var{LENGTH}
5663 contains the length needed for storing the environment variable @var{NAME}
5664 or zero if it is not present. @var{STATUS} is -1 if @var{VALUE} is present
5665 but too short for the environment variable; it is 1 if the environment
5666 variable does not exist and 2 if the processor does not support environment
5667 variables; in all other cases @var{STATUS} is zero. If @var{TRIM_NAME} is
5668 present with the value @code{.FALSE.}, the trailing blanks in @var{NAME}
5669 are significant; otherwise they are not part of the environment variable
5672 @item @emph{Example}:
5675 CHARACTER(len=255) :: homedir
5676 CALL get_environment_variable("HOME", homedir)
5677 WRITE (*,*) TRIM(homedir)
5685 @section @code{GETGID} --- Group ID function
5687 @cindex system, group ID
5690 @item @emph{Description}:
5691 Returns the numerical group ID of the current process.
5693 @item @emph{Standard}:
5699 @item @emph{Syntax}:
5700 @code{RESULT = GETGID()}
5702 @item @emph{Return value}:
5703 The return value of @code{GETGID} is an @code{INTEGER} of the default
5707 @item @emph{Example}:
5708 See @code{GETPID} for an example.
5710 @item @emph{See also}:
5711 @ref{GETPID}, @ref{GETUID}
5717 @section @code{GETLOG} --- Get login name
5719 @cindex system, login name
5723 @item @emph{Description}:
5724 Gets the username under which the program is running.
5726 @item @emph{Standard}:
5732 @item @emph{Syntax}:
5733 @code{CALL GETLOG(C)}
5735 @item @emph{Arguments}:
5736 @multitable @columnfractions .15 .70
5737 @item @var{C} @tab Shall be of type @code{CHARACTER} and of default kind.
5740 @item @emph{Return value}:
5741 Stores the current user name in @var{LOGIN}. (On systems where POSIX
5742 functions @code{geteuid} and @code{getpwuid} are not available, and
5743 the @code{getlogin} function is not implemented either, this will
5744 return a blank string.)
5746 @item @emph{Example}:
5749 CHARACTER(32) :: login
5755 @item @emph{See also}:
5762 @section @code{GETPID} --- Process ID function
5764 @cindex system, process ID
5768 @item @emph{Description}:
5769 Returns the numerical process identifier of the current process.
5771 @item @emph{Standard}:
5777 @item @emph{Syntax}:
5778 @code{RESULT = GETPID()}
5780 @item @emph{Return value}:
5781 The return value of @code{GETPID} is an @code{INTEGER} of the default
5785 @item @emph{Example}:
5788 print *, "The current process ID is ", getpid()
5789 print *, "Your numerical user ID is ", getuid()
5790 print *, "Your numerical group ID is ", getgid()
5794 @item @emph{See also}:
5795 @ref{GETGID}, @ref{GETUID}
5801 @section @code{GETUID} --- User ID function
5803 @cindex system, user ID
5807 @item @emph{Description}:
5808 Returns the numerical user ID of the current process.
5810 @item @emph{Standard}:
5816 @item @emph{Syntax}:
5817 @code{RESULT = GETUID()}
5819 @item @emph{Return value}:
5820 The return value of @code{GETUID} is an @code{INTEGER} of the default
5824 @item @emph{Example}:
5825 See @code{GETPID} for an example.
5827 @item @emph{See also}:
5828 @ref{GETPID}, @ref{GETLOG}
5834 @section @code{GMTIME} --- Convert time to GMT info
5836 @cindex time, conversion to GMT info
5839 @item @emph{Description}:
5840 Given a system time value @var{TIME} (as provided by the @code{TIME8}
5841 intrinsic), fills @var{VALUES} with values extracted from it appropriate
5842 to the UTC time zone (Universal Coordinated Time, also known in some
5843 countries as GMT, Greenwich Mean Time), using @code{gmtime(3)}.
5845 @item @emph{Standard}:
5851 @item @emph{Syntax}:
5852 @code{CALL GMTIME(TIME, VALUES)}
5854 @item @emph{Arguments}:
5855 @multitable @columnfractions .15 .70
5856 @item @var{TIME} @tab An @code{INTEGER} scalar expression
5857 corresponding to a system time, with @code{INTENT(IN)}.
5858 @item @var{VALUES} @tab A default @code{INTEGER} array with 9 elements,
5859 with @code{INTENT(OUT)}.
5862 @item @emph{Return value}:
5863 The elements of @var{VALUES} are assigned as follows:
5865 @item Seconds after the minute, range 0--59 or 0--61 to allow for leap
5867 @item Minutes after the hour, range 0--59
5868 @item Hours past midnight, range 0--23
5869 @item Day of month, range 0--31
5870 @item Number of months since January, range 0--12
5871 @item Years since 1900
5872 @item Number of days since Sunday, range 0--6
5873 @item Days since January 1
5874 @item Daylight savings indicator: positive if daylight savings is in
5875 effect, zero if not, and negative if the information is not available.
5878 @item @emph{See also}:
5879 @ref{CTIME}, @ref{LTIME}, @ref{TIME}, @ref{TIME8}
5886 @section @code{HOSTNM} --- Get system host name
5888 @cindex system, host name
5891 @item @emph{Description}:
5892 Retrieves the host name of the system on which the program is running.
5894 This intrinsic is provided in both subroutine and function forms; however,
5895 only one form can be used in any given program unit.
5897 @item @emph{Standard}:
5901 Subroutine, function
5903 @item @emph{Syntax}:
5904 @multitable @columnfractions .80
5905 @item @code{CALL HOSTNM(C [, STATUS])}
5906 @item @code{STATUS = HOSTNM(NAME)}
5909 @item @emph{Arguments}:
5910 @multitable @columnfractions .15 .70
5911 @item @var{C} @tab Shall of type @code{CHARACTER} and of default kind.
5912 @item @var{STATUS} @tab (Optional) status flag of type @code{INTEGER}.
5913 Returns 0 on success, or a system specific error code otherwise.
5916 @item @emph{Return value}:
5917 In either syntax, @var{NAME} is set to the current hostname if it can
5918 be obtained, or to a blank string otherwise.
5925 @section @code{HUGE} --- Largest number of a kind
5927 @cindex limits, largest number
5928 @cindex model representation, largest number
5931 @item @emph{Description}:
5932 @code{HUGE(X)} returns the largest number that is not an infinity in
5933 the model of the type of @code{X}.
5935 @item @emph{Standard}:
5936 Fortran 95 and later
5941 @item @emph{Syntax}:
5942 @code{RESULT = HUGE(X)}
5944 @item @emph{Arguments}:
5945 @multitable @columnfractions .15 .70
5946 @item @var{X} @tab Shall be of type @code{REAL} or @code{INTEGER}.
5949 @item @emph{Return value}:
5950 The return value is of the same type and kind as @var{X}
5952 @item @emph{Example}:
5954 program test_huge_tiny
5955 print *, huge(0), huge(0.0), huge(0.0d0)
5956 print *, tiny(0.0), tiny(0.0d0)
5957 end program test_huge_tiny
5964 @section @code{HYPOT} --- Euclidean distance function
5966 @cindex Euclidean distance
5969 @item @emph{Description}:
5970 @code{HYPOT(X,Y)} is the Euclidean distance function. It is equal to
5971 @math{\sqrt{X^2 + Y^2}}, without undue underflow or overflow.
5973 @item @emph{Standard}:
5974 Fortran 2008 and later
5979 @item @emph{Syntax}:
5980 @code{RESULT = HYPOT(X, Y)}
5982 @item @emph{Arguments}:
5983 @multitable @columnfractions .15 .70
5984 @item @var{X} @tab The type shall be @code{REAL}.
5985 @item @var{Y} @tab The type and kind type parameter shall be the same as
5989 @item @emph{Return value}:
5990 The return value has the same type and kind type parameter as @var{X}.
5992 @item @emph{Example}:
5995 real(4) :: x = 1.e0_4, y = 0.5e0_4
5997 end program test_hypot
6004 @section @code{IACHAR} --- Code in @acronym{ASCII} collating sequence
6006 @cindex @acronym{ASCII} collating sequence
6007 @cindex collating sequence, @acronym{ASCII}
6008 @cindex conversion, to integer
6011 @item @emph{Description}:
6012 @code{IACHAR(C)} returns the code for the @acronym{ASCII} character
6013 in the first character position of @code{C}.
6015 @item @emph{Standard}:
6016 Fortran 95 and later, with @var{KIND} argument Fortran 2003 and later
6021 @item @emph{Syntax}:
6022 @code{RESULT = IACHAR(C [, KIND])}
6024 @item @emph{Arguments}:
6025 @multitable @columnfractions .15 .70
6026 @item @var{C} @tab Shall be a scalar @code{CHARACTER}, with @code{INTENT(IN)}
6027 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
6028 expression indicating the kind parameter of the result.
6031 @item @emph{Return value}:
6032 The return value is of type @code{INTEGER} and of kind @var{KIND}. If
6033 @var{KIND} is absent, the return value is of default integer kind.
6035 @item @emph{Example}:
6040 end program test_iachar
6044 See @ref{ICHAR} for a discussion of converting between numerical values
6045 and formatted string representations.
6047 @item @emph{See also}:
6048 @ref{ACHAR}, @ref{CHAR}, @ref{ICHAR}
6055 @section @code{IALL} --- Bitwise AND of array elements
6058 @cindex bits, AND of array elements
6061 @item @emph{Description}:
6062 Reduces with bitwise AND the elements of @var{ARRAY} along dimension @var{DIM}
6063 if the corresponding element in @var{MASK} is @code{TRUE}.
6065 @item @emph{Standard}:
6066 Fortran 2008 and later
6069 Transformational function
6071 @item @emph{Syntax}:
6072 @multitable @columnfractions .80
6073 @item @code{RESULT = IALL(ARRAY[, MASK])}
6074 @item @code{RESULT = IALL(ARRAY, DIM[, MASK])}
6077 @item @emph{Arguments}:
6078 @multitable @columnfractions .15 .70
6079 @item @var{ARRAY} @tab Shall be an array of type @code{INTEGER}
6080 @item @var{DIM} @tab (Optional) shall be a scalar of type
6081 @code{INTEGER} with a value in the range from 1 to n, where n
6082 equals the rank of @var{ARRAY}.
6083 @item @var{MASK} @tab (Optional) shall be of type @code{LOGICAL}
6084 and either be a scalar or an array of the same shape as @var{ARRAY}.
6087 @item @emph{Return value}:
6088 The result is of the same type as @var{ARRAY}.
6090 If @var{DIM} is absent, a scalar with the bitwise ALL of all elements in
6091 @var{ARRAY} is returned. Otherwise, an array of rank n-1, where n equals
6092 the rank of @var{ARRAY}, and a shape similar to that of @var{ARRAY} with
6093 dimension @var{DIM} dropped is returned.
6095 @item @emph{Example}:
6104 PRINT '(b8.8)', IALL(a)
6108 @item @emph{See also}:
6109 @ref{IANY}, @ref{IPARITY}, @ref{IAND}
6115 @section @code{IAND} --- Bitwise logical and
6117 @cindex bitwise logical and
6118 @cindex logical and, bitwise
6121 @item @emph{Description}:
6122 Bitwise logical @code{AND}.
6124 @item @emph{Standard}:
6125 Fortran 95 and later
6130 @item @emph{Syntax}:
6131 @code{RESULT = IAND(I, J)}
6133 @item @emph{Arguments}:
6134 @multitable @columnfractions .15 .70
6135 @item @var{I} @tab The type shall be @code{INTEGER}.
6136 @item @var{J} @tab The type shall be @code{INTEGER}, of the same
6137 kind as @var{I}. (As a GNU extension, different kinds are also
6141 @item @emph{Return value}:
6142 The return type is @code{INTEGER}, of the same kind as the
6143 arguments. (If the argument kinds differ, it is of the same kind as
6144 the larger argument.)
6146 @item @emph{Example}:
6150 DATA a / Z'F' /, b / Z'3' /
6151 WRITE (*,*) IAND(a, b)
6155 @item @emph{See also}:
6156 @ref{IOR}, @ref{IEOR}, @ref{IBITS}, @ref{IBSET}, @ref{IBCLR}, @ref{NOT}
6163 @section @code{IANY} --- Bitwise OR of array elements
6166 @cindex bits, OR of array elements
6169 @item @emph{Description}:
6170 Reduces with bitwise OR (inclusive or) the elements of @var{ARRAY} along
6171 dimension @var{DIM} if the corresponding element in @var{MASK} is @code{TRUE}.
6173 @item @emph{Standard}:
6174 Fortran 2008 and later
6177 Transformational function
6179 @item @emph{Syntax}:
6180 @multitable @columnfractions .80
6181 @item @code{RESULT = IANY(ARRAY[, MASK])}
6182 @item @code{RESULT = IANY(ARRAY, DIM[, MASK])}
6185 @item @emph{Arguments}:
6186 @multitable @columnfractions .15 .70
6187 @item @var{ARRAY} @tab Shall be an array of type @code{INTEGER}
6188 @item @var{DIM} @tab (Optional) shall be a scalar of type
6189 @code{INTEGER} with a value in the range from 1 to n, where n
6190 equals the rank of @var{ARRAY}.
6191 @item @var{MASK} @tab (Optional) shall be of type @code{LOGICAL}
6192 and either be a scalar or an array of the same shape as @var{ARRAY}.
6195 @item @emph{Return value}:
6196 The result is of the same type as @var{ARRAY}.
6198 If @var{DIM} is absent, a scalar with the bitwise OR of all elements in
6199 @var{ARRAY} is returned. Otherwise, an array of rank n-1, where n equals
6200 the rank of @var{ARRAY}, and a shape similar to that of @var{ARRAY} with
6201 dimension @var{DIM} dropped is returned.
6203 @item @emph{Example}:
6212 PRINT '(b8.8)', IANY(a)
6216 @item @emph{See also}:
6217 @ref{IPARITY}, @ref{IALL}, @ref{IOR}
6223 @section @code{IARGC} --- Get the number of command line arguments
6225 @cindex command-line arguments
6226 @cindex command-line arguments, number of
6227 @cindex arguments, to program
6230 @item @emph{Description}:
6231 @code{IARGC} returns the number of arguments passed on the
6232 command line when the containing program was invoked.
6234 This intrinsic routine is provided for backwards compatibility with
6235 GNU Fortran 77. In new code, programmers should consider the use of
6236 the @ref{COMMAND_ARGUMENT_COUNT} intrinsic defined by the Fortran 2003
6239 @item @emph{Standard}:
6245 @item @emph{Syntax}:
6246 @code{RESULT = IARGC()}
6248 @item @emph{Arguments}:
6251 @item @emph{Return value}:
6252 The number of command line arguments, type @code{INTEGER(4)}.
6254 @item @emph{Example}:
6257 @item @emph{See also}:
6258 GNU Fortran 77 compatibility subroutine: @ref{GETARG}
6260 Fortran 2003 functions and subroutines: @ref{GET_COMMAND},
6261 @ref{GET_COMMAND_ARGUMENT}, @ref{COMMAND_ARGUMENT_COUNT}
6267 @section @code{IBCLR} --- Clear bit
6273 @item @emph{Description}:
6274 @code{IBCLR} returns the value of @var{I} with the bit at position
6275 @var{POS} set to zero.
6277 @item @emph{Standard}:
6278 Fortran 95 and later
6283 @item @emph{Syntax}:
6284 @code{RESULT = IBCLR(I, POS)}
6286 @item @emph{Arguments}:
6287 @multitable @columnfractions .15 .70
6288 @item @var{I} @tab The type shall be @code{INTEGER}.
6289 @item @var{POS} @tab The type shall be @code{INTEGER}.
6292 @item @emph{Return value}:
6293 The return value is of type @code{INTEGER} and of the same kind as
6296 @item @emph{See also}:
6297 @ref{IBITS}, @ref{IBSET}, @ref{IAND}, @ref{IOR}, @ref{IEOR}, @ref{MVBITS}
6304 @section @code{IBITS} --- Bit extraction
6307 @cindex bits, extract
6310 @item @emph{Description}:
6311 @code{IBITS} extracts a field of length @var{LEN} from @var{I},
6312 starting from bit position @var{POS} and extending left for @var{LEN}
6313 bits. The result is right-justified and the remaining bits are
6314 zeroed. The value of @code{POS+LEN} must be less than or equal to the
6315 value @code{BIT_SIZE(I)}.
6317 @item @emph{Standard}:
6318 Fortran 95 and later
6323 @item @emph{Syntax}:
6324 @code{RESULT = IBITS(I, POS, LEN)}
6326 @item @emph{Arguments}:
6327 @multitable @columnfractions .15 .70
6328 @item @var{I} @tab The type shall be @code{INTEGER}.
6329 @item @var{POS} @tab The type shall be @code{INTEGER}.
6330 @item @var{LEN} @tab The type shall be @code{INTEGER}.
6333 @item @emph{Return value}:
6334 The return value is of type @code{INTEGER} and of the same kind as
6337 @item @emph{See also}:
6338 @ref{BIT_SIZE}, @ref{IBCLR}, @ref{IBSET}, @ref{IAND}, @ref{IOR}, @ref{IEOR}
6344 @section @code{IBSET} --- Set bit
6349 @item @emph{Description}:
6350 @code{IBSET} returns the value of @var{I} with the bit at position
6351 @var{POS} set to one.
6353 @item @emph{Standard}:
6354 Fortran 95 and later
6359 @item @emph{Syntax}:
6360 @code{RESULT = IBSET(I, POS)}
6362 @item @emph{Arguments}:
6363 @multitable @columnfractions .15 .70
6364 @item @var{I} @tab The type shall be @code{INTEGER}.
6365 @item @var{POS} @tab The type shall be @code{INTEGER}.
6368 @item @emph{Return value}:
6369 The return value is of type @code{INTEGER} and of the same kind as
6372 @item @emph{See also}:
6373 @ref{IBCLR}, @ref{IBITS}, @ref{IAND}, @ref{IOR}, @ref{IEOR}, @ref{MVBITS}
6380 @section @code{ICHAR} --- Character-to-integer conversion function
6382 @cindex conversion, to integer
6385 @item @emph{Description}:
6386 @code{ICHAR(C)} returns the code for the character in the first character
6387 position of @code{C} in the system's native character set.
6388 The correspondence between characters and their codes is not necessarily
6389 the same across different GNU Fortran implementations.
6391 @item @emph{Standard}:
6392 Fortran 95 and later, with @var{KIND} argument Fortran 2003 and later
6397 @item @emph{Syntax}:
6398 @code{RESULT = ICHAR(C [, KIND])}
6400 @item @emph{Arguments}:
6401 @multitable @columnfractions .15 .70
6402 @item @var{C} @tab Shall be a scalar @code{CHARACTER}, with @code{INTENT(IN)}
6403 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
6404 expression indicating the kind parameter of the result.
6407 @item @emph{Return value}:
6408 The return value is of type @code{INTEGER} and of kind @var{KIND}. If
6409 @var{KIND} is absent, the return value is of default integer kind.
6411 @item @emph{Example}:
6416 end program test_ichar
6419 @item @emph{Specific names}:
6420 @multitable @columnfractions .20 .20 .20 .25
6421 @item Name @tab Argument @tab Return type @tab Standard
6422 @item @code{ICHAR(C)} @tab @code{CHARACTER C} @tab @code{INTEGER(4)} @tab Fortran 77 and later
6426 No intrinsic exists to convert between a numeric value and a formatted
6427 character string representation -- for instance, given the
6428 @code{CHARACTER} value @code{'154'}, obtaining an @code{INTEGER} or
6429 @code{REAL} value with the value 154, or vice versa. Instead, this
6430 functionality is provided by internal-file I/O, as in the following
6435 character(len=10) string, string2
6438 ! Convert a string to a numeric value
6439 read (string,'(I10)') value
6442 ! Convert a value to a formatted string
6443 write (string2,'(I10)') value
6445 end program read_val
6448 @item @emph{See also}:
6449 @ref{ACHAR}, @ref{CHAR}, @ref{IACHAR}
6456 @section @code{IDATE} --- Get current local time subroutine (day/month/year)
6458 @cindex date, current
6459 @cindex current date
6462 @item @emph{Description}:
6463 @code{IDATE(VALUES)} Fills @var{VALUES} with the numerical values at the
6464 current local time. The day (in the range 1-31), month (in the range 1-12),
6465 and year appear in elements 1, 2, and 3 of @var{VALUES}, respectively.
6466 The year has four significant digits.
6468 @item @emph{Standard}:
6474 @item @emph{Syntax}:
6475 @code{CALL IDATE(VALUES)}
6477 @item @emph{Arguments}:
6478 @multitable @columnfractions .15 .70
6479 @item @var{VALUES} @tab The type shall be @code{INTEGER, DIMENSION(3)} and
6480 the kind shall be the default integer kind.
6483 @item @emph{Return value}:
6484 Does not return anything.
6486 @item @emph{Example}:
6489 integer, dimension(3) :: tarray
6494 end program test_idate
6501 @section @code{IEOR} --- Bitwise logical exclusive or
6503 @cindex bitwise logical exclusive or
6504 @cindex logical exclusive or, bitwise
6507 @item @emph{Description}:
6508 @code{IEOR} returns the bitwise Boolean exclusive-OR of @var{I} and
6511 @item @emph{Standard}:
6512 Fortran 95 and later
6517 @item @emph{Syntax}:
6518 @code{RESULT = IEOR(I, J)}
6520 @item @emph{Arguments}:
6521 @multitable @columnfractions .15 .70
6522 @item @var{I} @tab The type shall be @code{INTEGER}.
6523 @item @var{J} @tab The type shall be @code{INTEGER}, of the same
6524 kind as @var{I}. (As a GNU extension, different kinds are also
6528 @item @emph{Return value}:
6529 The return type is @code{INTEGER}, of the same kind as the
6530 arguments. (If the argument kinds differ, it is of the same kind as
6531 the larger argument.)
6533 @item @emph{See also}:
6534 @ref{IOR}, @ref{IAND}, @ref{IBITS}, @ref{IBSET}, @ref{IBCLR}, @ref{NOT}
6540 @section @code{IERRNO} --- Get the last system error number
6542 @cindex system, error handling
6545 @item @emph{Description}:
6546 Returns the last system error number, as given by the C @code{errno}
6549 @item @emph{Standard}:
6555 @item @emph{Syntax}:
6556 @code{RESULT = IERRNO()}
6558 @item @emph{Arguments}:
6561 @item @emph{Return value}:
6562 The return value is of type @code{INTEGER} and of the default integer
6565 @item @emph{See also}:
6572 @section @code{IMAGE_INDEX} --- Function that converts a cosubscript to an image index
6573 @fnindex IMAGE_INDEX
6574 @cindex coarray, @code{IMAGE_INDEX}
6575 @cindex images, cosubscript to image index conversion
6578 @item @emph{Description}:
6579 Returns the image index belonging to a cosubscript.
6581 @item @emph{Standard}:
6582 Fortran 2008 and later
6587 @item @emph{Syntax}:
6588 @code{RESULT = IMAGE_INDEX(COARRAY, SUB)}
6590 @item @emph{Arguments}: None.
6591 @multitable @columnfractions .15 .70
6592 @item @var{COARRAY} @tab Coarray of any type.
6593 @item @var{SUB} @tab default integer rank-1 array of a size equal to
6594 the corank of @var{COARRAY}.
6598 @item @emph{Return value}:
6599 Scalar default integer with the value of the image index which corresponds
6600 to the cosubscripts. For invalid cosubscripts the result is zero.
6602 @item @emph{Example}:
6604 INTEGER :: array[2,-1:4,8,*]
6605 ! Writes 28 (or 0 if there are fewer than 28 images)
6606 WRITE (*,*) IMAGE_INDEX (array, [2,0,3,1])
6609 @item @emph{See also}:
6610 @ref{THIS_IMAGE}, @ref{NUM_IMAGES}
6615 @node INDEX intrinsic
6616 @section @code{INDEX} --- Position of a substring within a string
6618 @cindex substring position
6619 @cindex string, find substring
6622 @item @emph{Description}:
6623 Returns the position of the start of the first occurrence of string
6624 @var{SUBSTRING} as a substring in @var{STRING}, counting from one. If
6625 @var{SUBSTRING} is not present in @var{STRING}, zero is returned. If
6626 the @var{BACK} argument is present and true, the return value is the
6627 start of the last occurrence rather than the first.
6629 @item @emph{Standard}:
6630 Fortran 77 and later, with @var{KIND} argument Fortran 2003 and later
6635 @item @emph{Syntax}:
6636 @code{RESULT = INDEX(STRING, SUBSTRING [, BACK [, KIND]])}
6638 @item @emph{Arguments}:
6639 @multitable @columnfractions .15 .70
6640 @item @var{STRING} @tab Shall be a scalar @code{CHARACTER}, with
6642 @item @var{SUBSTRING} @tab Shall be a scalar @code{CHARACTER}, with
6644 @item @var{BACK} @tab (Optional) Shall be a scalar @code{LOGICAL}, with
6646 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
6647 expression indicating the kind parameter of the result.
6650 @item @emph{Return value}:
6651 The return value is of type @code{INTEGER} and of kind @var{KIND}. If
6652 @var{KIND} is absent, the return value is of default integer kind.
6654 @item @emph{Specific names}:
6655 @multitable @columnfractions .20 .20 .20 .25
6656 @item Name @tab Argument @tab Return type @tab Standard
6657 @item @code{INDEX(STRING, SUBSTRING)} @tab @code{CHARACTER} @tab @code{INTEGER(4)} @tab Fortran 77 and later
6660 @item @emph{See also}:
6661 @ref{SCAN}, @ref{VERIFY}
6667 @section @code{INT} --- Convert to integer type
6671 @cindex conversion, to integer
6674 @item @emph{Description}:
6675 Convert to integer type
6677 @item @emph{Standard}:
6678 Fortran 77 and later
6683 @item @emph{Syntax}:
6684 @code{RESULT = INT(A [, KIND))}
6686 @item @emph{Arguments}:
6687 @multitable @columnfractions .15 .70
6688 @item @var{A} @tab Shall be of type @code{INTEGER},
6689 @code{REAL}, or @code{COMPLEX}.
6690 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
6691 expression indicating the kind parameter of the result.
6694 @item @emph{Return value}:
6695 These functions return a @code{INTEGER} variable or array under
6696 the following rules:
6700 If @var{A} is of type @code{INTEGER}, @code{INT(A) = A}
6702 If @var{A} is of type @code{REAL} and @math{|A| < 1}, @code{INT(A)} equals @code{0}.
6703 If @math{|A| \geq 1}, then @code{INT(A)} equals the largest integer that does not exceed
6704 the range of @var{A} and whose sign is the same as the sign of @var{A}.
6706 If @var{A} is of type @code{COMPLEX}, rule B is applied to the real part of @var{A}.
6709 @item @emph{Example}:
6713 complex :: z = (-3.7, 1.0)
6715 print *, int(z), int(z,8)
6719 @item @emph{Specific names}:
6720 @multitable @columnfractions .20 .20 .20 .25
6721 @item Name @tab Argument @tab Return type @tab Standard
6722 @item @code{INT(A)} @tab @code{REAL(4) A} @tab @code{INTEGER} @tab Fortran 77 and later
6723 @item @code{IFIX(A)} @tab @code{REAL(4) A} @tab @code{INTEGER} @tab Fortran 77 and later
6724 @item @code{IDINT(A)} @tab @code{REAL(8) A} @tab @code{INTEGER} @tab Fortran 77 and later
6731 @section @code{INT2} --- Convert to 16-bit integer type
6734 @cindex conversion, to integer
6737 @item @emph{Description}:
6738 Convert to a @code{KIND=2} integer type. This is equivalent to the
6739 standard @code{INT} intrinsic with an optional argument of
6740 @code{KIND=2}, and is only included for backwards compatibility.
6742 The @code{SHORT} intrinsic is equivalent to @code{INT2}.
6744 @item @emph{Standard}:
6750 @item @emph{Syntax}:
6751 @code{RESULT = INT2(A)}
6753 @item @emph{Arguments}:
6754 @multitable @columnfractions .15 .70
6755 @item @var{A} @tab Shall be of type @code{INTEGER},
6756 @code{REAL}, or @code{COMPLEX}.
6759 @item @emph{Return value}:
6760 The return value is a @code{INTEGER(2)} variable.
6762 @item @emph{See also}:
6763 @ref{INT}, @ref{INT8}, @ref{LONG}
6769 @section @code{INT8} --- Convert to 64-bit integer type
6771 @cindex conversion, to integer
6774 @item @emph{Description}:
6775 Convert to a @code{KIND=8} integer type. This is equivalent to the
6776 standard @code{INT} intrinsic with an optional argument of
6777 @code{KIND=8}, and is only included for backwards compatibility.
6779 @item @emph{Standard}:
6785 @item @emph{Syntax}:
6786 @code{RESULT = INT8(A)}
6788 @item @emph{Arguments}:
6789 @multitable @columnfractions .15 .70
6790 @item @var{A} @tab Shall be of type @code{INTEGER},
6791 @code{REAL}, or @code{COMPLEX}.
6794 @item @emph{Return value}:
6795 The return value is a @code{INTEGER(8)} variable.
6797 @item @emph{See also}:
6798 @ref{INT}, @ref{INT2}, @ref{LONG}
6804 @section @code{IOR} --- Bitwise logical or
6806 @cindex bitwise logical or
6807 @cindex logical or, bitwise
6810 @item @emph{Description}:
6811 @code{IOR} returns the bitwise Boolean inclusive-OR of @var{I} and
6814 @item @emph{Standard}:
6815 Fortran 95 and later
6820 @item @emph{Syntax}:
6821 @code{RESULT = IOR(I, J)}
6823 @item @emph{Arguments}:
6824 @multitable @columnfractions .15 .70
6825 @item @var{I} @tab The type shall be @code{INTEGER}.
6826 @item @var{J} @tab The type shall be @code{INTEGER}, of the same
6827 kind as @var{I}. (As a GNU extension, different kinds are also
6831 @item @emph{Return value}:
6832 The return type is @code{INTEGER}, of the same kind as the
6833 arguments. (If the argument kinds differ, it is of the same kind as
6834 the larger argument.)
6836 @item @emph{See also}:
6837 @ref{IEOR}, @ref{IAND}, @ref{IBITS}, @ref{IBSET}, @ref{IBCLR}, @ref{NOT}
6843 @section @code{IPARITY} --- Bitwise XOR of array elements
6845 @cindex array, parity
6847 @cindex bits, XOR of array elements
6850 @item @emph{Description}:
6851 Reduces with bitwise XOR (exclusive or) the elements of @var{ARRAY} along
6852 dimension @var{DIM} if the corresponding element in @var{MASK} is @code{TRUE}.
6854 @item @emph{Standard}:
6855 Fortran 2008 and later
6858 Transformational function
6860 @item @emph{Syntax}:
6861 @multitable @columnfractions .80
6862 @item @code{RESULT = IPARITY(ARRAY[, MASK])}
6863 @item @code{RESULT = IPARITY(ARRAY, DIM[, MASK])}
6866 @item @emph{Arguments}:
6867 @multitable @columnfractions .15 .70
6868 @item @var{ARRAY} @tab Shall be an array of type @code{INTEGER}
6869 @item @var{DIM} @tab (Optional) shall be a scalar of type
6870 @code{INTEGER} with a value in the range from 1 to n, where n
6871 equals the rank of @var{ARRAY}.
6872 @item @var{MASK} @tab (Optional) shall be of type @code{LOGICAL}
6873 and either be a scalar or an array of the same shape as @var{ARRAY}.
6876 @item @emph{Return value}:
6877 The result is of the same type as @var{ARRAY}.
6879 If @var{DIM} is absent, a scalar with the bitwise XOR of all elements in
6880 @var{ARRAY} is returned. Otherwise, an array of rank n-1, where n equals
6881 the rank of @var{ARRAY}, and a shape similar to that of @var{ARRAY} with
6882 dimension @var{DIM} dropped is returned.
6884 @item @emph{Example}:
6886 PROGRAM test_iparity
6893 PRINT '(b8.8)', IPARITY(a)
6897 @item @emph{See also}:
6898 @ref{IANY}, @ref{IALL}, @ref{IEOR}, @ref{PARITY}
6904 @section @code{IRAND} --- Integer pseudo-random number
6906 @cindex random number generation
6909 @item @emph{Description}:
6910 @code{IRAND(FLAG)} returns a pseudo-random number from a uniform
6911 distribution between 0 and a system-dependent limit (which is in most
6912 cases 2147483647). If @var{FLAG} is 0, the next number
6913 in the current sequence is returned; if @var{FLAG} is 1, the generator
6914 is restarted by @code{CALL SRAND(0)}; if @var{FLAG} has any other value,
6915 it is used as a new seed with @code{SRAND}.
6917 This intrinsic routine is provided for backwards compatibility with
6918 GNU Fortran 77. It implements a simple modulo generator as provided
6919 by @command{g77}. For new code, one should consider the use of
6920 @ref{RANDOM_NUMBER} as it implements a superior algorithm.
6922 @item @emph{Standard}:
6928 @item @emph{Syntax}:
6929 @code{RESULT = IRAND(I)}
6931 @item @emph{Arguments}:
6932 @multitable @columnfractions .15 .70
6933 @item @var{I} @tab Shall be a scalar @code{INTEGER} of kind 4.
6936 @item @emph{Return value}:
6937 The return value is of @code{INTEGER(kind=4)} type.
6939 @item @emph{Example}:
6942 integer,parameter :: seed = 86456
6945 print *, irand(), irand(), irand(), irand()
6946 print *, irand(seed), irand(), irand(), irand()
6947 end program test_irand
6955 @section @code{IS_IOSTAT_END} --- Test for end-of-file value
6956 @fnindex IS_IOSTAT_END
6957 @cindex @code{IOSTAT}, end of file
6960 @item @emph{Description}:
6961 @code{IS_IOSTAT_END} tests whether an variable has the value of the I/O
6962 status ``end of file''. The function is equivalent to comparing the variable
6963 with the @code{IOSTAT_END} parameter of the intrinsic module
6964 @code{ISO_FORTRAN_ENV}.
6966 @item @emph{Standard}:
6967 Fortran 2003 and later
6972 @item @emph{Syntax}:
6973 @code{RESULT = IS_IOSTAT_END(I)}
6975 @item @emph{Arguments}:
6976 @multitable @columnfractions .15 .70
6977 @item @var{I} @tab Shall be of the type @code{INTEGER}.
6980 @item @emph{Return value}:
6981 Returns a @code{LOGICAL} of the default kind, which @code{.TRUE.} if
6982 @var{I} has the value which indicates an end of file condition for
6983 @code{IOSTAT=} specifiers, and is @code{.FALSE.} otherwise.
6985 @item @emph{Example}:
6990 OPEN(88, FILE='test.dat')
6991 READ(88, *, IOSTAT=stat) i
6992 IF(IS_IOSTAT_END(stat)) STOP 'END OF FILE'
7000 @section @code{IS_IOSTAT_EOR} --- Test for end-of-record value
7001 @fnindex IS_IOSTAT_EOR
7002 @cindex @code{IOSTAT}, end of record
7005 @item @emph{Description}:
7006 @code{IS_IOSTAT_EOR} tests whether an variable has the value of the I/O
7007 status ``end of record''. The function is equivalent to comparing the
7008 variable with the @code{IOSTAT_EOR} parameter of the intrinsic module
7009 @code{ISO_FORTRAN_ENV}.
7011 @item @emph{Standard}:
7012 Fortran 2003 and later
7017 @item @emph{Syntax}:
7018 @code{RESULT = IS_IOSTAT_EOR(I)}
7020 @item @emph{Arguments}:
7021 @multitable @columnfractions .15 .70
7022 @item @var{I} @tab Shall be of the type @code{INTEGER}.
7025 @item @emph{Return value}:
7026 Returns a @code{LOGICAL} of the default kind, which @code{.TRUE.} if
7027 @var{I} has the value which indicates an end of file condition for
7028 @code{IOSTAT=} specifiers, and is @code{.FALSE.} otherwise.
7030 @item @emph{Example}:
7034 INTEGER :: stat, i(50)
7035 OPEN(88, FILE='test.dat', FORM='UNFORMATTED')
7036 READ(88, IOSTAT=stat) i
7037 IF(IS_IOSTAT_EOR(stat)) STOP 'END OF RECORD'
7045 @section @code{ISATTY} --- Whether a unit is a terminal device.
7047 @cindex system, terminal
7050 @item @emph{Description}:
7051 Determine whether a unit is connected to a terminal device.
7053 @item @emph{Standard}:
7059 @item @emph{Syntax}:
7060 @code{RESULT = ISATTY(UNIT)}
7062 @item @emph{Arguments}:
7063 @multitable @columnfractions .15 .70
7064 @item @var{UNIT} @tab Shall be a scalar @code{INTEGER}.
7067 @item @emph{Return value}:
7068 Returns @code{.TRUE.} if the @var{UNIT} is connected to a terminal
7069 device, @code{.FALSE.} otherwise.
7071 @item @emph{Example}:
7074 INTEGER(kind=1) :: unit
7076 write(*,*) isatty(unit=unit)
7080 @item @emph{See also}:
7087 @section @code{ISHFT} --- Shift bits
7092 @item @emph{Description}:
7093 @code{ISHFT} returns a value corresponding to @var{I} with all of the
7094 bits shifted @var{SHIFT} places. A value of @var{SHIFT} greater than
7095 zero corresponds to a left shift, a value of zero corresponds to no
7096 shift, and a value less than zero corresponds to a right shift. If the
7097 absolute value of @var{SHIFT} is greater than @code{BIT_SIZE(I)}, the
7098 value is undefined. Bits shifted out from the left end or right end are
7099 lost; zeros are shifted in from the opposite end.
7101 @item @emph{Standard}:
7102 Fortran 95 and later
7107 @item @emph{Syntax}:
7108 @code{RESULT = ISHFT(I, SHIFT)}
7110 @item @emph{Arguments}:
7111 @multitable @columnfractions .15 .70
7112 @item @var{I} @tab The type shall be @code{INTEGER}.
7113 @item @var{SHIFT} @tab The type shall be @code{INTEGER}.
7116 @item @emph{Return value}:
7117 The return value is of type @code{INTEGER} and of the same kind as
7120 @item @emph{See also}:
7127 @section @code{ISHFTC} --- Shift bits circularly
7129 @cindex bits, shift circular
7132 @item @emph{Description}:
7133 @code{ISHFTC} returns a value corresponding to @var{I} with the
7134 rightmost @var{SIZE} bits shifted circularly @var{SHIFT} places; that
7135 is, bits shifted out one end are shifted into the opposite end. A value
7136 of @var{SHIFT} greater than zero corresponds to a left shift, a value of
7137 zero corresponds to no shift, and a value less than zero corresponds to
7138 a right shift. The absolute value of @var{SHIFT} must be less than
7139 @var{SIZE}. If the @var{SIZE} argument is omitted, it is taken to be
7140 equivalent to @code{BIT_SIZE(I)}.
7142 @item @emph{Standard}:
7143 Fortran 95 and later
7148 @item @emph{Syntax}:
7149 @code{RESULT = ISHFTC(I, SHIFT [, SIZE])}
7151 @item @emph{Arguments}:
7152 @multitable @columnfractions .15 .70
7153 @item @var{I} @tab The type shall be @code{INTEGER}.
7154 @item @var{SHIFT} @tab The type shall be @code{INTEGER}.
7155 @item @var{SIZE} @tab (Optional) The type shall be @code{INTEGER};
7156 the value must be greater than zero and less than or equal to
7160 @item @emph{Return value}:
7161 The return value is of type @code{INTEGER} and of the same kind as
7164 @item @emph{See also}:
7171 @section @code{ISNAN} --- Test for a NaN
7176 @item @emph{Description}:
7177 @code{ISNAN} tests whether a floating-point value is an IEEE
7179 @item @emph{Standard}:
7185 @item @emph{Syntax}:
7188 @item @emph{Arguments}:
7189 @multitable @columnfractions .15 .70
7190 @item @var{X} @tab Variable of the type @code{REAL}.
7194 @item @emph{Return value}:
7195 Returns a default-kind @code{LOGICAL}. The returned value is @code{TRUE}
7196 if @var{X} is a NaN and @code{FALSE} otherwise.
7198 @item @emph{Example}:
7205 if (isnan(x)) stop '"x" is a NaN'
7206 end program test_nan
7213 @section @code{ITIME} --- Get current local time subroutine (hour/minutes/seconds)
7215 @cindex time, current
7216 @cindex current time
7219 @item @emph{Description}:
7220 @code{IDATE(VALUES)} Fills @var{VALUES} with the numerical values at the
7221 current local time. The hour (in the range 1-24), minute (in the range 1-60),
7222 and seconds (in the range 1-60) appear in elements 1, 2, and 3 of @var{VALUES},
7225 @item @emph{Standard}:
7231 @item @emph{Syntax}:
7232 @code{CALL ITIME(VALUES)}
7234 @item @emph{Arguments}:
7235 @multitable @columnfractions .15 .70
7236 @item @var{VALUES} @tab The type shall be @code{INTEGER, DIMENSION(3)}
7237 and the kind shall be the default integer kind.
7240 @item @emph{Return value}:
7241 Does not return anything.
7244 @item @emph{Example}:
7247 integer, dimension(3) :: tarray
7252 end program test_itime
7259 @section @code{KILL} --- Send a signal to a process
7263 @item @emph{Description}:
7264 @item @emph{Standard}:
7265 Sends the signal specified by @var{SIGNAL} to the process @var{PID}.
7268 This intrinsic is provided in both subroutine and function forms; however,
7269 only one form can be used in any given program unit.
7272 Subroutine, function
7274 @item @emph{Syntax}:
7275 @multitable @columnfractions .80
7276 @item @code{CALL KILL(C, VALUE [, STATUS])}
7277 @item @code{STATUS = KILL(C, VALUE)}
7280 @item @emph{Arguments}:
7281 @multitable @columnfractions .15 .70
7282 @item @var{C} @tab Shall be a scalar @code{INTEGER}, with
7284 @item @var{VALUE} @tab Shall be a scalar @code{INTEGER}, with
7286 @item @var{STATUS} @tab (Optional) status flag of type @code{INTEGER(4)} or
7287 @code{INTEGER(8)}. Returns 0 on success, or a system-specific error code
7291 @item @emph{See also}:
7292 @ref{ABORT}, @ref{EXIT}
7298 @section @code{KIND} --- Kind of an entity
7303 @item @emph{Description}:
7304 @code{KIND(X)} returns the kind value of the entity @var{X}.
7306 @item @emph{Standard}:
7307 Fortran 95 and later
7312 @item @emph{Syntax}:
7315 @item @emph{Arguments}:
7316 @multitable @columnfractions .15 .70
7317 @item @var{X} @tab Shall be of type @code{LOGICAL}, @code{INTEGER},
7318 @code{REAL}, @code{COMPLEX} or @code{CHARACTER}.
7321 @item @emph{Return value}:
7322 The return value is a scalar of type @code{INTEGER} and of the default
7325 @item @emph{Example}:
7328 integer,parameter :: kc = kind(' ')
7329 integer,parameter :: kl = kind(.true.)
7331 print *, "The default character kind is ", kc
7332 print *, "The default logical kind is ", kl
7333 end program test_kind
7341 @section @code{LBOUND} --- Lower dimension bounds of an array
7343 @cindex array, lower bound
7346 @item @emph{Description}:
7347 Returns the lower bounds of an array, or a single lower bound
7348 along the @var{DIM} dimension.
7349 @item @emph{Standard}:
7350 Fortran 95 and later, with @var{KIND} argument Fortran 2003 and later
7355 @item @emph{Syntax}:
7356 @code{RESULT = LBOUND(ARRAY [, DIM [, KIND]])}
7358 @item @emph{Arguments}:
7359 @multitable @columnfractions .15 .70
7360 @item @var{ARRAY} @tab Shall be an array, of any type.
7361 @item @var{DIM} @tab (Optional) Shall be a scalar @code{INTEGER}.
7362 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
7363 expression indicating the kind parameter of the result.
7366 @item @emph{Return value}:
7367 The return value is of type @code{INTEGER} and of kind @var{KIND}. If
7368 @var{KIND} is absent, the return value is of default integer kind.
7369 If @var{DIM} is absent, the result is an array of the lower bounds of
7370 @var{ARRAY}. If @var{DIM} is present, the result is a scalar
7371 corresponding to the lower bound of the array along that dimension. If
7372 @var{ARRAY} is an expression rather than a whole array or array
7373 structure component, or if it has a zero extent along the relevant
7374 dimension, the lower bound is taken to be 1.
7376 @item @emph{See also}:
7377 @ref{UBOUND}, @ref{LCOBOUND}
7383 @section @code{LCOBOUND} --- Lower codimension bounds of an array
7385 @cindex coarray, lower bound
7388 @item @emph{Description}:
7389 Returns the lower bounds of a coarray, or a single lower cobound
7390 along the @var{DIM} codimension.
7391 @item @emph{Standard}:
7392 Fortran 2008 and later
7397 @item @emph{Syntax}:
7398 @code{RESULT = LCOBOUND(COARRAY [, DIM [, KIND]])}
7400 @item @emph{Arguments}:
7401 @multitable @columnfractions .15 .70
7402 @item @var{ARRAY} @tab Shall be an coarray, of any type.
7403 @item @var{DIM} @tab (Optional) Shall be a scalar @code{INTEGER}.
7404 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
7405 expression indicating the kind parameter of the result.
7408 @item @emph{Return value}:
7409 The return value is of type @code{INTEGER} and of kind @var{KIND}. If
7410 @var{KIND} is absent, the return value is of default integer kind.
7411 If @var{DIM} is absent, the result is an array of the lower cobounds of
7412 @var{COARRAY}. If @var{DIM} is present, the result is a scalar
7413 corresponding to the lower cobound of the array along that codimension.
7415 @item @emph{See also}:
7416 @ref{UCOBOUND}, @ref{LBOUND}
7422 @section @code{LEADZ} --- Number of leading zero bits of an integer
7427 @item @emph{Description}:
7428 @code{LEADZ} returns the number of leading zero bits of an integer.
7430 @item @emph{Standard}:
7431 Fortran 2008 and later
7436 @item @emph{Syntax}:
7437 @code{RESULT = LEADZ(I)}
7439 @item @emph{Arguments}:
7440 @multitable @columnfractions .15 .70
7441 @item @var{I} @tab Shall be of type @code{INTEGER}.
7444 @item @emph{Return value}:
7445 The type of the return value is the default @code{INTEGER}.
7446 If all the bits of @code{I} are zero, the result value is @code{BIT_SIZE(I)}.
7448 @item @emph{Example}:
7451 WRITE (*,*) BIT_SIZE(1) ! prints 32
7452 WRITE (*,*) LEADZ(1) ! prints 31
7456 @item @emph{See also}:
7457 @ref{BIT_SIZE}, @ref{TRAILZ}, @ref{POPCNT}, @ref{POPPAR}
7463 @section @code{LEN} --- Length of a character entity
7465 @cindex string, length
7468 @item @emph{Description}:
7469 Returns the length of a character string. If @var{STRING} is an array,
7470 the length of an element of @var{STRING} is returned. Note that
7471 @var{STRING} need not be defined when this intrinsic is invoked, since
7472 only the length, not the content, of @var{STRING} is needed.
7474 @item @emph{Standard}:
7475 Fortran 77 and later, with @var{KIND} argument Fortran 2003 and later
7480 @item @emph{Syntax}:
7481 @code{L = LEN(STRING [, KIND])}
7483 @item @emph{Arguments}:
7484 @multitable @columnfractions .15 .70
7485 @item @var{STRING} @tab Shall be a scalar or array of type
7486 @code{CHARACTER}, with @code{INTENT(IN)}
7487 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
7488 expression indicating the kind parameter of the result.
7491 @item @emph{Return value}:
7492 The return value is of type @code{INTEGER} and of kind @var{KIND}. If
7493 @var{KIND} is absent, the return value is of default integer kind.
7496 @item @emph{Specific names}:
7497 @multitable @columnfractions .20 .20 .20 .25
7498 @item Name @tab Argument @tab Return type @tab Standard
7499 @item @code{LEN(STRING)} @tab @code{CHARACTER} @tab @code{INTEGER} @tab Fortran 77 and later
7503 @item @emph{See also}:
7504 @ref{LEN_TRIM}, @ref{ADJUSTL}, @ref{ADJUSTR}
7510 @section @code{LEN_TRIM} --- Length of a character entity without trailing blank characters
7512 @cindex string, length, without trailing whitespace
7515 @item @emph{Description}:
7516 Returns the length of a character string, ignoring any trailing blanks.
7518 @item @emph{Standard}:
7519 Fortran 95 and later, with @var{KIND} argument Fortran 2003 and later
7524 @item @emph{Syntax}:
7525 @code{RESULT = LEN_TRIM(STRING [, KIND])}
7527 @item @emph{Arguments}:
7528 @multitable @columnfractions .15 .70
7529 @item @var{STRING} @tab Shall be a scalar of type @code{CHARACTER},
7530 with @code{INTENT(IN)}
7531 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
7532 expression indicating the kind parameter of the result.
7535 @item @emph{Return value}:
7536 The return value is of type @code{INTEGER} and of kind @var{KIND}. If
7537 @var{KIND} is absent, the return value is of default integer kind.
7539 @item @emph{See also}:
7540 @ref{LEN}, @ref{ADJUSTL}, @ref{ADJUSTR}
7546 @section @code{LGE} --- Lexical greater than or equal
7548 @cindex lexical comparison of strings
7549 @cindex string, comparison
7552 @item @emph{Description}:
7553 Determines whether one string is lexically greater than or equal to
7554 another string, where the two strings are interpreted as containing
7555 ASCII character codes. If the String A and String B are not the same
7556 length, the shorter is compared as if spaces were appended to it to form
7557 a value that has the same length as the longer.
7559 In general, the lexical comparison intrinsics @code{LGE}, @code{LGT},
7560 @code{LLE}, and @code{LLT} differ from the corresponding intrinsic
7561 operators @code{.GE.}, @code{.GT.}, @code{.LE.}, and @code{.LT.}, in
7562 that the latter use the processor's character ordering (which is not
7563 ASCII on some targets), whereas the former always use the ASCII
7566 @item @emph{Standard}:
7567 Fortran 77 and later
7572 @item @emph{Syntax}:
7573 @code{RESULT = LGE(STRING_A, STRING_B)}
7575 @item @emph{Arguments}:
7576 @multitable @columnfractions .15 .70
7577 @item @var{STRING_A} @tab Shall be of default @code{CHARACTER} type.
7578 @item @var{STRING_B} @tab Shall be of default @code{CHARACTER} type.
7581 @item @emph{Return value}:
7582 Returns @code{.TRUE.} if @code{STRING_A >= STRING_B}, and @code{.FALSE.}
7583 otherwise, based on the ASCII ordering.
7585 @item @emph{Specific names}:
7586 @multitable @columnfractions .20 .20 .20 .25
7587 @item Name @tab Argument @tab Return type @tab Standard
7588 @item @code{LGE(STRING_A, STRING_B)} @tab @code{CHARACTER} @tab @code{LOGICAL} @tab Fortran 77 and later
7591 @item @emph{See also}:
7592 @ref{LGT}, @ref{LLE}, @ref{LLT}
7598 @section @code{LGT} --- Lexical greater than
7600 @cindex lexical comparison of strings
7601 @cindex string, comparison
7604 @item @emph{Description}:
7605 Determines whether one string is lexically greater than another string,
7606 where the two strings are interpreted as containing ASCII character
7607 codes. If the String A and String B are not the same length, the
7608 shorter is compared as if spaces were appended to it to form a value
7609 that has the same length as the longer.
7611 In general, the lexical comparison intrinsics @code{LGE}, @code{LGT},
7612 @code{LLE}, and @code{LLT} differ from the corresponding intrinsic
7613 operators @code{.GE.}, @code{.GT.}, @code{.LE.}, and @code{.LT.}, in
7614 that the latter use the processor's character ordering (which is not
7615 ASCII on some targets), whereas the former always use the ASCII
7618 @item @emph{Standard}:
7619 Fortran 77 and later
7624 @item @emph{Syntax}:
7625 @code{RESULT = LGT(STRING_A, STRING_B)}
7627 @item @emph{Arguments}:
7628 @multitable @columnfractions .15 .70
7629 @item @var{STRING_A} @tab Shall be of default @code{CHARACTER} type.
7630 @item @var{STRING_B} @tab Shall be of default @code{CHARACTER} type.
7633 @item @emph{Return value}:
7634 Returns @code{.TRUE.} if @code{STRING_A > STRING_B}, and @code{.FALSE.}
7635 otherwise, based on the ASCII ordering.
7637 @item @emph{Specific names}:
7638 @multitable @columnfractions .20 .20 .20 .25
7639 @item Name @tab Argument @tab Return type @tab Standard
7640 @item @code{LGT(STRING_A, STRING_B)} @tab @code{CHARACTER} @tab @code{LOGICAL} @tab Fortran 77 and later
7643 @item @emph{See also}:
7644 @ref{LGE}, @ref{LLE}, @ref{LLT}
7650 @section @code{LINK} --- Create a hard link
7652 @cindex file system, create link
7653 @cindex file system, hard link
7656 @item @emph{Description}:
7657 Makes a (hard) link from file @var{PATH1} to @var{PATH2}. A null
7658 character (@code{CHAR(0)}) can be used to mark the end of the names in
7659 @var{PATH1} and @var{PATH2}; otherwise, trailing blanks in the file
7660 names are ignored. If the @var{STATUS} argument is supplied, it
7661 contains 0 on success or a nonzero error code upon return; see
7664 This intrinsic is provided in both subroutine and function forms;
7665 however, only one form can be used in any given program unit.
7667 @item @emph{Standard}:
7671 Subroutine, function
7673 @item @emph{Syntax}:
7674 @multitable @columnfractions .80
7675 @item @code{CALL LINK(PATH1, PATH2 [, STATUS])}
7676 @item @code{STATUS = LINK(PATH1, PATH2)}
7679 @item @emph{Arguments}:
7680 @multitable @columnfractions .15 .70
7681 @item @var{PATH1} @tab Shall be of default @code{CHARACTER} type.
7682 @item @var{PATH2} @tab Shall be of default @code{CHARACTER} type.
7683 @item @var{STATUS} @tab (Optional) Shall be of default @code{INTEGER} type.
7686 @item @emph{See also}:
7687 @ref{SYMLNK}, @ref{UNLINK}
7693 @section @code{LLE} --- Lexical less than or equal
7695 @cindex lexical comparison of strings
7696 @cindex string, comparison
7699 @item @emph{Description}:
7700 Determines whether one string is lexically less than or equal to another
7701 string, where the two strings are interpreted as containing ASCII
7702 character codes. If the String A and String B are not the same length,
7703 the shorter is compared as if spaces were appended to it to form a value
7704 that has the same length as the longer.
7706 In general, the lexical comparison intrinsics @code{LGE}, @code{LGT},
7707 @code{LLE}, and @code{LLT} differ from the corresponding intrinsic
7708 operators @code{.GE.}, @code{.GT.}, @code{.LE.}, and @code{.LT.}, in
7709 that the latter use the processor's character ordering (which is not
7710 ASCII on some targets), whereas the former always use the ASCII
7713 @item @emph{Standard}:
7714 Fortran 77 and later
7719 @item @emph{Syntax}:
7720 @code{RESULT = LLE(STRING_A, STRING_B)}
7722 @item @emph{Arguments}:
7723 @multitable @columnfractions .15 .70
7724 @item @var{STRING_A} @tab Shall be of default @code{CHARACTER} type.
7725 @item @var{STRING_B} @tab Shall be of default @code{CHARACTER} type.
7728 @item @emph{Return value}:
7729 Returns @code{.TRUE.} if @code{STRING_A <= STRING_B}, and @code{.FALSE.}
7730 otherwise, based on the ASCII ordering.
7732 @item @emph{Specific names}:
7733 @multitable @columnfractions .20 .20 .20 .25
7734 @item Name @tab Argument @tab Return type @tab Standard
7735 @item @code{LLE(STRING_A, STRING_B)} @tab @code{CHARACTER} @tab @code{LOGICAL} @tab Fortran 77 and later
7738 @item @emph{See also}:
7739 @ref{LGE}, @ref{LGT}, @ref{LLT}
7745 @section @code{LLT} --- Lexical less than
7747 @cindex lexical comparison of strings
7748 @cindex string, comparison
7751 @item @emph{Description}:
7752 Determines whether one string is lexically less than another string,
7753 where the two strings are interpreted as containing ASCII character
7754 codes. If the String A and String B are not the same length, the
7755 shorter is compared as if spaces were appended to it to form a value
7756 that has the same length as the longer.
7758 In general, the lexical comparison intrinsics @code{LGE}, @code{LGT},
7759 @code{LLE}, and @code{LLT} differ from the corresponding intrinsic
7760 operators @code{.GE.}, @code{.GT.}, @code{.LE.}, and @code{.LT.}, in
7761 that the latter use the processor's character ordering (which is not
7762 ASCII on some targets), whereas the former always use the ASCII
7765 @item @emph{Standard}:
7766 Fortran 77 and later
7771 @item @emph{Syntax}:
7772 @code{RESULT = LLT(STRING_A, STRING_B)}
7774 @item @emph{Arguments}:
7775 @multitable @columnfractions .15 .70
7776 @item @var{STRING_A} @tab Shall be of default @code{CHARACTER} type.
7777 @item @var{STRING_B} @tab Shall be of default @code{CHARACTER} type.
7780 @item @emph{Return value}:
7781 Returns @code{.TRUE.} if @code{STRING_A < STRING_B}, and @code{.FALSE.}
7782 otherwise, based on the ASCII ordering.
7784 @item @emph{Specific names}:
7785 @multitable @columnfractions .20 .20 .20 .25
7786 @item Name @tab Argument @tab Return type @tab Standard
7787 @item @code{LLT(STRING_A, STRING_B)} @tab @code{CHARACTER} @tab @code{LOGICAL} @tab Fortran 77 and later
7790 @item @emph{See also}:
7791 @ref{LGE}, @ref{LGT}, @ref{LLE}
7797 @section @code{LNBLNK} --- Index of the last non-blank character in a string
7799 @cindex string, find non-blank character
7802 @item @emph{Description}:
7803 Returns the length of a character string, ignoring any trailing blanks.
7804 This is identical to the standard @code{LEN_TRIM} intrinsic, and is only
7805 included for backwards compatibility.
7807 @item @emph{Standard}:
7813 @item @emph{Syntax}:
7814 @code{RESULT = LNBLNK(STRING)}
7816 @item @emph{Arguments}:
7817 @multitable @columnfractions .15 .70
7818 @item @var{STRING} @tab Shall be a scalar of type @code{CHARACTER},
7819 with @code{INTENT(IN)}
7822 @item @emph{Return value}:
7823 The return value is of @code{INTEGER(kind=4)} type.
7825 @item @emph{See also}:
7826 @ref{INDEX intrinsic}, @ref{LEN_TRIM}
7832 @section @code{LOC} --- Returns the address of a variable
7834 @cindex location of a variable in memory
7837 @item @emph{Description}:
7838 @code{LOC(X)} returns the address of @var{X} as an integer.
7840 @item @emph{Standard}:
7846 @item @emph{Syntax}:
7847 @code{RESULT = LOC(X)}
7849 @item @emph{Arguments}:
7850 @multitable @columnfractions .15 .70
7851 @item @var{X} @tab Variable of any type.
7854 @item @emph{Return value}:
7855 The return value is of type @code{INTEGER}, with a @code{KIND}
7856 corresponding to the size (in bytes) of a memory address on the target
7859 @item @emph{Example}:
7866 end program test_loc
7873 @section @code{LOG} --- Natural logarithm function
7880 @cindex exponential function, inverse
7881 @cindex logarithm function
7882 @cindex natural logarithm function
7885 @item @emph{Description}:
7886 @code{LOG(X)} computes the natural logarithm of @var{X}, i.e. the
7887 logarithm to the base @math{e}.
7889 @item @emph{Standard}:
7890 Fortran 77 and later
7895 @item @emph{Syntax}:
7896 @code{RESULT = LOG(X)}
7898 @item @emph{Arguments}:
7899 @multitable @columnfractions .15 .70
7900 @item @var{X} @tab The type shall be @code{REAL} or
7904 @item @emph{Return value}:
7905 The return value is of type @code{REAL} or @code{COMPLEX}.
7906 The kind type parameter is the same as @var{X}.
7907 If @var{X} is @code{COMPLEX}, the imaginary part @math{\omega} is in the range
7908 @math{-\pi \leq \omega \leq \pi}.
7910 @item @emph{Example}:
7913 real(8) :: x = 2.7182818284590451_8
7914 complex :: z = (1.0, 2.0)
7915 x = log(x) ! will yield (approximately) 1
7917 end program test_log
7920 @item @emph{Specific names}:
7921 @multitable @columnfractions .20 .20 .20 .25
7922 @item Name @tab Argument @tab Return type @tab Standard
7923 @item @code{ALOG(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab f95, gnu
7924 @item @code{DLOG(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab f95, gnu
7925 @item @code{CLOG(X)} @tab @code{COMPLEX(4) X} @tab @code{COMPLEX(4)} @tab f95, gnu
7926 @item @code{ZLOG(X)} @tab @code{COMPLEX(8) X} @tab @code{COMPLEX(8)} @tab f95, gnu
7927 @item @code{CDLOG(X)} @tab @code{COMPLEX(8) X} @tab @code{COMPLEX(8)} @tab f95, gnu
7934 @section @code{LOG10} --- Base 10 logarithm function
7938 @cindex exponential function, inverse
7939 @cindex logarithm function with base 10
7940 @cindex base 10 logarithm function
7943 @item @emph{Description}:
7944 @code{LOG10(X)} computes the base 10 logarithm of @var{X}.
7946 @item @emph{Standard}:
7947 Fortran 77 and later
7952 @item @emph{Syntax}:
7953 @code{RESULT = LOG10(X)}
7955 @item @emph{Arguments}:
7956 @multitable @columnfractions .15 .70
7957 @item @var{X} @tab The type shall be @code{REAL}.
7960 @item @emph{Return value}:
7961 The return value is of type @code{REAL} or @code{COMPLEX}.
7962 The kind type parameter is the same as @var{X}.
7964 @item @emph{Example}:
7967 real(8) :: x = 10.0_8
7969 end program test_log10
7972 @item @emph{Specific names}:
7973 @multitable @columnfractions .20 .20 .20 .25
7974 @item Name @tab Argument @tab Return type @tab Standard
7975 @item @code{ALOG10(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab Fortran 95 and later
7976 @item @code{DLOG10(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab Fortran 95 and later
7983 @section @code{LOG_GAMMA} --- Logarithm of the Gamma function
7988 @cindex Gamma function, logarithm of
7991 @item @emph{Description}:
7992 @code{LOG_GAMMA(X)} computes the natural logarithm of the absolute value
7993 of the Gamma (@math{\Gamma}) function.
7995 @item @emph{Standard}:
7996 Fortran 2008 and later
8001 @item @emph{Syntax}:
8002 @code{X = LOG_GAMMA(X)}
8004 @item @emph{Arguments}:
8005 @multitable @columnfractions .15 .70
8006 @item @var{X} @tab Shall be of type @code{REAL} and neither zero
8007 nor a negative integer.
8010 @item @emph{Return value}:
8011 The return value is of type @code{REAL} of the same kind as @var{X}.
8013 @item @emph{Example}:
8015 program test_log_gamma
8017 x = lgamma(x) ! returns 0.0
8018 end program test_log_gamma
8021 @item @emph{Specific names}:
8022 @multitable @columnfractions .20 .20 .20 .25
8023 @item Name @tab Argument @tab Return type @tab Standard
8024 @item @code{LGAMMA(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab GNU Extension
8025 @item @code{ALGAMA(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab GNU Extension
8026 @item @code{DLGAMA(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU Extension
8029 @item @emph{See also}:
8030 Gamma function: @ref{GAMMA}
8037 @section @code{LOGICAL} --- Convert to logical type
8039 @cindex conversion, to logical
8042 @item @emph{Description}:
8043 Converts one kind of @code{LOGICAL} variable to another.
8045 @item @emph{Standard}:
8046 Fortran 95 and later
8051 @item @emph{Syntax}:
8052 @code{RESULT = LOGICAL(L [, KIND])}
8054 @item @emph{Arguments}:
8055 @multitable @columnfractions .15 .70
8056 @item @var{L} @tab The type shall be @code{LOGICAL}.
8057 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
8058 expression indicating the kind parameter of the result.
8061 @item @emph{Return value}:
8062 The return value is a @code{LOGICAL} value equal to @var{L}, with a
8063 kind corresponding to @var{KIND}, or of the default logical kind if
8064 @var{KIND} is not given.
8066 @item @emph{See also}:
8067 @ref{INT}, @ref{REAL}, @ref{CMPLX}
8073 @section @code{LONG} --- Convert to integer type
8075 @cindex conversion, to integer
8078 @item @emph{Description}:
8079 Convert to a @code{KIND=4} integer type, which is the same size as a C
8080 @code{long} integer. This is equivalent to the standard @code{INT}
8081 intrinsic with an optional argument of @code{KIND=4}, and is only
8082 included for backwards compatibility.
8084 @item @emph{Standard}:
8090 @item @emph{Syntax}:
8091 @code{RESULT = LONG(A)}
8093 @item @emph{Arguments}:
8094 @multitable @columnfractions .15 .70
8095 @item @var{A} @tab Shall be of type @code{INTEGER},
8096 @code{REAL}, or @code{COMPLEX}.
8099 @item @emph{Return value}:
8100 The return value is a @code{INTEGER(4)} variable.
8102 @item @emph{See also}:
8103 @ref{INT}, @ref{INT2}, @ref{INT8}
8109 @section @code{LSHIFT} --- Left shift bits
8111 @cindex bits, shift left
8114 @item @emph{Description}:
8115 @code{LSHIFT} returns a value corresponding to @var{I} with all of the
8116 bits shifted left by @var{SHIFT} places. If the absolute value of
8117 @var{SHIFT} is greater than @code{BIT_SIZE(I)}, the value is undefined.
8118 Bits shifted out from the left end are lost; zeros are shifted in from
8121 This function has been superseded by the @code{ISHFT} intrinsic, which
8122 is standard in Fortran 95 and later, and the @code{SHIFTL} intrinsic,
8123 which is standard in Fortran 2008 and later.
8125 @item @emph{Standard}:
8131 @item @emph{Syntax}:
8132 @code{RESULT = LSHIFT(I, SHIFT)}
8134 @item @emph{Arguments}:
8135 @multitable @columnfractions .15 .70
8136 @item @var{I} @tab The type shall be @code{INTEGER}.
8137 @item @var{SHIFT} @tab The type shall be @code{INTEGER}.
8140 @item @emph{Return value}:
8141 The return value is of type @code{INTEGER} and of the same kind as
8144 @item @emph{See also}:
8145 @ref{ISHFT}, @ref{ISHFTC}, @ref{RSHIFT}, @ref{SHIFTA}, @ref{SHIFTL},
8153 @section @code{LSTAT} --- Get file status
8155 @cindex file system, file status
8158 @item @emph{Description}:
8159 @code{LSTAT} is identical to @ref{STAT}, except that if path is a
8160 symbolic link, then the link itself is statted, not the file that it
8163 The elements in @code{VALUES} are the same as described by @ref{STAT}.
8165 This intrinsic is provided in both subroutine and function forms;
8166 however, only one form can be used in any given program unit.
8168 @item @emph{Standard}:
8172 Subroutine, function
8174 @item @emph{Syntax}:
8175 @multitable @columnfractions .80
8176 @item @code{CALL LSTAT(NAME, VALUES [, STATUS])}
8177 @item @code{STATUS = LSTAT(NAME, VALUES)}
8180 @item @emph{Arguments}:
8181 @multitable @columnfractions .15 .70
8182 @item @var{NAME} @tab The type shall be @code{CHARACTER} of the default
8183 kind, a valid path within the file system.
8184 @item @var{VALUES} @tab The type shall be @code{INTEGER(4), DIMENSION(13)}.
8185 @item @var{STATUS} @tab (Optional) status flag of type @code{INTEGER(4)}.
8186 Returns 0 on success and a system specific error code otherwise.
8189 @item @emph{Example}:
8190 See @ref{STAT} for an example.
8192 @item @emph{See also}:
8193 To stat an open file: @ref{FSTAT}, to stat a file: @ref{STAT}
8199 @section @code{LTIME} --- Convert time to local time info
8201 @cindex time, conversion to local time info
8204 @item @emph{Description}:
8205 Given a system time value @var{TIME} (as provided by the @code{TIME8}
8206 intrinsic), fills @var{VALUES} with values extracted from it appropriate
8207 to the local time zone using @code{localtime(3)}.
8209 @item @emph{Standard}:
8215 @item @emph{Syntax}:
8216 @code{CALL LTIME(TIME, VALUES)}
8218 @item @emph{Arguments}:
8219 @multitable @columnfractions .15 .70
8220 @item @var{TIME} @tab An @code{INTEGER} scalar expression
8221 corresponding to a system time, with @code{INTENT(IN)}.
8222 @item @var{VALUES} @tab A default @code{INTEGER} array with 9 elements,
8223 with @code{INTENT(OUT)}.
8226 @item @emph{Return value}:
8227 The elements of @var{VALUES} are assigned as follows:
8229 @item Seconds after the minute, range 0--59 or 0--61 to allow for leap
8231 @item Minutes after the hour, range 0--59
8232 @item Hours past midnight, range 0--23
8233 @item Day of month, range 0--31
8234 @item Number of months since January, range 0--12
8235 @item Years since 1900
8236 @item Number of days since Sunday, range 0--6
8237 @item Days since January 1
8238 @item Daylight savings indicator: positive if daylight savings is in
8239 effect, zero if not, and negative if the information is not available.
8242 @item @emph{See also}:
8243 @ref{CTIME}, @ref{GMTIME}, @ref{TIME}, @ref{TIME8}
8250 @section @code{MALLOC} --- Allocate dynamic memory
8252 @cindex pointer, cray
8255 @item @emph{Description}:
8256 @code{MALLOC(SIZE)} allocates @var{SIZE} bytes of dynamic memory and
8257 returns the address of the allocated memory. The @code{MALLOC} intrinsic
8258 is an extension intended to be used with Cray pointers, and is provided
8259 in GNU Fortran to allow the user to compile legacy code. For new code
8260 using Fortran 95 pointers, the memory allocation intrinsic is
8263 @item @emph{Standard}:
8269 @item @emph{Syntax}:
8270 @code{PTR = MALLOC(SIZE)}
8272 @item @emph{Arguments}:
8273 @multitable @columnfractions .15 .70
8274 @item @var{SIZE} @tab The type shall be @code{INTEGER}.
8277 @item @emph{Return value}:
8278 The return value is of type @code{INTEGER(K)}, with @var{K} such that
8279 variables of type @code{INTEGER(K)} have the same size as
8280 C pointers (@code{sizeof(void *)}).
8282 @item @emph{Example}:
8283 The following example demonstrates the use of @code{MALLOC} and
8284 @code{FREE} with Cray pointers.
8293 ptr_x = malloc(20*8)
8295 x(i) = sqrt(1.0d0 / i)
8303 end program test_malloc
8306 @item @emph{See also}:
8313 @section @code{MASKL} --- Left justified mask
8315 @cindex mask, left justified
8318 @item @emph{Description}:
8319 @code{MASKL(I[, KIND])} has its leftmost @var{I} bits set to 1, and the
8320 remaining bits set to 0.
8322 @item @emph{Standard}:
8323 Fortran 2008 and later
8328 @item @emph{Syntax}:
8329 @code{RESULT = MASKL(I[, KIND])}
8331 @item @emph{Arguments}:
8332 @multitable @columnfractions .15 .70
8333 @item @var{I} @tab Shall be of type @code{INTEGER}.
8334 @item @var{KIND} @tab Shall be a scalar constant expression of type
8338 @item @emph{Return value}:
8339 The return value is of type @code{INTEGER}. If @var{KIND} is present, it
8340 specifies the kind value of the return type; otherwise, it is of the
8341 default integer kind.
8343 @item @emph{See also}:
8350 @section @code{MASKR} --- Right justified mask
8352 @cindex mask, right justified
8355 @item @emph{Description}:
8356 @code{MASKL(I[, KIND])} has its rightmost @var{I} bits set to 1, and the
8357 remaining bits set to 0.
8359 @item @emph{Standard}:
8360 Fortran 2008 and later
8365 @item @emph{Syntax}:
8366 @code{RESULT = MASKR(I[, KIND])}
8368 @item @emph{Arguments}:
8369 @multitable @columnfractions .15 .70
8370 @item @var{I} @tab Shall be of type @code{INTEGER}.
8371 @item @var{KIND} @tab Shall be a scalar constant expression of type
8375 @item @emph{Return value}:
8376 The return value is of type @code{INTEGER}. If @var{KIND} is present, it
8377 specifies the kind value of the return type; otherwise, it is of the
8378 default integer kind.
8380 @item @emph{See also}:
8387 @section @code{MATMUL} --- matrix multiplication
8389 @cindex matrix multiplication
8390 @cindex product, matrix
8393 @item @emph{Description}:
8394 Performs a matrix multiplication on numeric or logical arguments.
8396 @item @emph{Standard}:
8397 Fortran 95 and later
8400 Transformational function
8402 @item @emph{Syntax}:
8403 @code{RESULT = MATMUL(MATRIX_A, MATRIX_B)}
8405 @item @emph{Arguments}:
8406 @multitable @columnfractions .15 .70
8407 @item @var{MATRIX_A} @tab An array of @code{INTEGER},
8408 @code{REAL}, @code{COMPLEX}, or @code{LOGICAL} type, with a rank of
8410 @item @var{MATRIX_B} @tab An array of @code{INTEGER},
8411 @code{REAL}, or @code{COMPLEX} type if @var{MATRIX_A} is of a numeric
8412 type; otherwise, an array of @code{LOGICAL} type. The rank shall be one
8413 or two, and the first (or only) dimension of @var{MATRIX_B} shall be
8414 equal to the last (or only) dimension of @var{MATRIX_A}.
8417 @item @emph{Return value}:
8418 The matrix product of @var{MATRIX_A} and @var{MATRIX_B}. The type and
8419 kind of the result follow the usual type and kind promotion rules, as
8420 for the @code{*} or @code{.AND.} operators.
8422 @item @emph{See also}:
8428 @section @code{MAX} --- Maximum value of an argument list
8435 @cindex maximum value
8438 @item @emph{Description}:
8439 Returns the argument with the largest (most positive) value.
8441 @item @emph{Standard}:
8442 Fortran 77 and later
8447 @item @emph{Syntax}:
8448 @code{RESULT = MAX(A1, A2 [, A3 [, ...]])}
8450 @item @emph{Arguments}:
8451 @multitable @columnfractions .15 .70
8452 @item @var{A1} @tab The type shall be @code{INTEGER} or
8454 @item @var{A2}, @var{A3}, ... @tab An expression of the same type and kind
8455 as @var{A1}. (As a GNU extension, arguments of different kinds are
8459 @item @emph{Return value}:
8460 The return value corresponds to the maximum value among the arguments,
8461 and has the same type and kind as the first argument.
8463 @item @emph{Specific names}:
8464 @multitable @columnfractions .20 .20 .20 .25
8465 @item Name @tab Argument @tab Return type @tab Standard
8466 @item @code{MAX0(A1)} @tab @code{INTEGER(4) A1} @tab @code{INTEGER(4)} @tab Fortran 77 and later
8467 @item @code{AMAX0(A1)} @tab @code{INTEGER(4) A1} @tab @code{REAL(MAX(X))} @tab Fortran 77 and later
8468 @item @code{MAX1(A1)} @tab @code{REAL A1} @tab @code{INT(MAX(X))} @tab Fortran 77 and later
8469 @item @code{AMAX1(A1)} @tab @code{REAL(4) A1} @tab @code{REAL(4)} @tab Fortran 77 and later
8470 @item @code{DMAX1(A1)} @tab @code{REAL(8) A1} @tab @code{REAL(8)} @tab Fortran 77 and later
8473 @item @emph{See also}:
8474 @ref{MAXLOC} @ref{MAXVAL}, @ref{MIN}
8481 @section @code{MAXEXPONENT} --- Maximum exponent of a real kind
8482 @fnindex MAXEXPONENT
8483 @cindex model representation, maximum exponent
8486 @item @emph{Description}:
8487 @code{MAXEXPONENT(X)} returns the maximum exponent in the model of the
8490 @item @emph{Standard}:
8491 Fortran 95 and later
8496 @item @emph{Syntax}:
8497 @code{RESULT = MAXEXPONENT(X)}
8499 @item @emph{Arguments}:
8500 @multitable @columnfractions .15 .70
8501 @item @var{X} @tab Shall be of type @code{REAL}.
8504 @item @emph{Return value}:
8505 The return value is of type @code{INTEGER} and of the default integer
8508 @item @emph{Example}:
8514 print *, minexponent(x), maxexponent(x)
8515 print *, minexponent(y), maxexponent(y)
8516 end program exponents
8523 @section @code{MAXLOC} --- Location of the maximum value within an array
8525 @cindex array, location of maximum element
8528 @item @emph{Description}:
8529 Determines the location of the element in the array with the maximum
8530 value, or, if the @var{DIM} argument is supplied, determines the
8531 locations of the maximum element along each row of the array in the
8532 @var{DIM} direction. If @var{MASK} is present, only the elements for
8533 which @var{MASK} is @code{.TRUE.} are considered. If more than one
8534 element in the array has the maximum value, the location returned is
8535 that of the first such element in array element order. If the array has
8536 zero size, or all of the elements of @var{MASK} are @code{.FALSE.}, then
8537 the result is an array of zeroes. Similarly, if @var{DIM} is supplied
8538 and all of the elements of @var{MASK} along a given row are zero, the
8539 result value for that row is zero.
8541 @item @emph{Standard}:
8542 Fortran 95 and later
8545 Transformational function
8547 @item @emph{Syntax}:
8548 @multitable @columnfractions .80
8549 @item @code{RESULT = MAXLOC(ARRAY, DIM [, MASK])}
8550 @item @code{RESULT = MAXLOC(ARRAY [, MASK])}
8553 @item @emph{Arguments}:
8554 @multitable @columnfractions .15 .70
8555 @item @var{ARRAY} @tab Shall be an array of type @code{INTEGER} or
8557 @item @var{DIM} @tab (Optional) Shall be a scalar of type
8558 @code{INTEGER}, with a value between one and the rank of @var{ARRAY},
8559 inclusive. It may not be an optional dummy argument.
8560 @item @var{MASK} @tab Shall be an array of type @code{LOGICAL},
8561 and conformable with @var{ARRAY}.
8564 @item @emph{Return value}:
8565 If @var{DIM} is absent, the result is a rank-one array with a length
8566 equal to the rank of @var{ARRAY}. If @var{DIM} is present, the result
8567 is an array with a rank one less than the rank of @var{ARRAY}, and a
8568 size corresponding to the size of @var{ARRAY} with the @var{DIM}
8569 dimension removed. If @var{DIM} is present and @var{ARRAY} has a rank
8570 of one, the result is a scalar. In all cases, the result is of default
8571 @code{INTEGER} type.
8573 @item @emph{See also}:
8574 @ref{MAX}, @ref{MAXVAL}
8581 @section @code{MAXVAL} --- Maximum value of an array
8583 @cindex array, maximum value
8584 @cindex maximum value
8587 @item @emph{Description}:
8588 Determines the maximum value of the elements in an array value, or, if
8589 the @var{DIM} argument is supplied, determines the maximum value along
8590 each row of the array in the @var{DIM} direction. If @var{MASK} is
8591 present, only the elements for which @var{MASK} is @code{.TRUE.} are
8592 considered. If the array has zero size, or all of the elements of
8593 @var{MASK} are @code{.FALSE.}, then the result is @code{-HUGE(ARRAY)}
8594 if @var{ARRAY} is numeric, or a string of nulls if @var{ARRAY} is of character
8597 @item @emph{Standard}:
8598 Fortran 95 and later
8601 Transformational function
8603 @item @emph{Syntax}:
8604 @multitable @columnfractions .80
8605 @item @code{RESULT = MAXVAL(ARRAY, DIM [, MASK])}
8606 @item @code{RESULT = MAXVAL(ARRAY [, MASK])}
8609 @item @emph{Arguments}:
8610 @multitable @columnfractions .15 .70
8611 @item @var{ARRAY} @tab Shall be an array of type @code{INTEGER} or
8613 @item @var{DIM} @tab (Optional) Shall be a scalar of type
8614 @code{INTEGER}, with a value between one and the rank of @var{ARRAY},
8615 inclusive. It may not be an optional dummy argument.
8616 @item @var{MASK} @tab Shall be an array of type @code{LOGICAL},
8617 and conformable with @var{ARRAY}.
8620 @item @emph{Return value}:
8621 If @var{DIM} is absent, or if @var{ARRAY} has a rank of one, the result
8622 is a scalar. If @var{DIM} is present, the result is an array with a
8623 rank one less than the rank of @var{ARRAY}, and a size corresponding to
8624 the size of @var{ARRAY} with the @var{DIM} dimension removed. In all
8625 cases, the result is of the same type and kind as @var{ARRAY}.
8627 @item @emph{See also}:
8628 @ref{MAX}, @ref{MAXLOC}
8634 @section @code{MCLOCK} --- Time function
8636 @cindex time, clock ticks
8640 @item @emph{Description}:
8641 Returns the number of clock ticks since the start of the process, based
8642 on the UNIX function @code{clock(3)}.
8644 This intrinsic is not fully portable, such as to systems with 32-bit
8645 @code{INTEGER} types but supporting times wider than 32 bits. Therefore,
8646 the values returned by this intrinsic might be, or become, negative, or
8647 numerically less than previous values, during a single run of the
8650 @item @emph{Standard}:
8656 @item @emph{Syntax}:
8657 @code{RESULT = MCLOCK()}
8659 @item @emph{Return value}:
8660 The return value is a scalar of type @code{INTEGER(4)}, equal to the
8661 number of clock ticks since the start of the process, or @code{-1} if
8662 the system does not support @code{clock(3)}.
8664 @item @emph{See also}:
8665 @ref{CTIME}, @ref{GMTIME}, @ref{LTIME}, @ref{MCLOCK}, @ref{TIME}
8672 @section @code{MCLOCK8} --- Time function (64-bit)
8674 @cindex time, clock ticks
8678 @item @emph{Description}:
8679 Returns the number of clock ticks since the start of the process, based
8680 on the UNIX function @code{clock(3)}.
8682 @emph{Warning:} this intrinsic does not increase the range of the timing
8683 values over that returned by @code{clock(3)}. On a system with a 32-bit
8684 @code{clock(3)}, @code{MCLOCK8} will return a 32-bit value, even though
8685 it is converted to a 64-bit @code{INTEGER(8)} value. That means
8686 overflows of the 32-bit value can still occur. Therefore, the values
8687 returned by this intrinsic might be or become negative or numerically
8688 less than previous values during a single run of the compiled program.
8690 @item @emph{Standard}:
8696 @item @emph{Syntax}:
8697 @code{RESULT = MCLOCK8()}
8699 @item @emph{Return value}:
8700 The return value is a scalar of type @code{INTEGER(8)}, equal to the
8701 number of clock ticks since the start of the process, or @code{-1} if
8702 the system does not support @code{clock(3)}.
8704 @item @emph{See also}:
8705 @ref{CTIME}, @ref{GMTIME}, @ref{LTIME}, @ref{MCLOCK}, @ref{TIME8}
8712 @section @code{MERGE} --- Merge variables
8714 @cindex array, merge arrays
8715 @cindex array, combine arrays
8718 @item @emph{Description}:
8719 Select values from two arrays according to a logical mask. The result
8720 is equal to @var{TSOURCE} if @var{MASK} is @code{.TRUE.}, or equal to
8721 @var{FSOURCE} if it is @code{.FALSE.}.
8723 @item @emph{Standard}:
8724 Fortran 95 and later
8729 @item @emph{Syntax}:
8730 @code{RESULT = MERGE(TSOURCE, FSOURCE, MASK)}
8732 @item @emph{Arguments}:
8733 @multitable @columnfractions .15 .70
8734 @item @var{TSOURCE} @tab May be of any type.
8735 @item @var{FSOURCE} @tab Shall be of the same type and type parameters
8737 @item @var{MASK} @tab Shall be of type @code{LOGICAL}.
8740 @item @emph{Return value}:
8741 The result is of the same type and type parameters as @var{TSOURCE}.
8748 @section @code{MERGE_BITS} --- Merge of bits under mask
8753 @item @emph{Description}:
8754 @code{MERGE_BITS(I, J, MASK)} merges the bits of @var{I} and @var{J}
8755 as determined by the mask. The i-th bit of the result is equal to the
8756 i-th bit of @var{I} if the i-th bit of @var{MASK} is 1; it is equal to
8757 the i-th bit of @var{J} otherwise.
8759 @item @emph{Standard}:
8760 Fortran 2008 and later
8765 @item @emph{Syntax}:
8766 @code{RESULT = MERGE_BITS(I, J, MASK)}
8768 @item @emph{Arguments}:
8769 @multitable @columnfractions .15 .70
8770 @item @var{I} @tab Shall be of type @code{INTEGER}.
8771 @item @var{J} @tab Shall be of type @code{INTEGER} and of the same
8773 @item @var{MASK} @tab Shall be of type @code{INTEGER} and of the same
8777 @item @emph{Return value}:
8778 The result is of the same type and kind as @var{I}.
8785 @section @code{MIN} --- Minimum value of an argument list
8792 @cindex minimum value
8795 @item @emph{Description}:
8796 Returns the argument with the smallest (most negative) value.
8798 @item @emph{Standard}:
8799 Fortran 77 and later
8804 @item @emph{Syntax}:
8805 @code{RESULT = MIN(A1, A2 [, A3, ...])}
8807 @item @emph{Arguments}:
8808 @multitable @columnfractions .15 .70
8809 @item @var{A1} @tab The type shall be @code{INTEGER} or
8811 @item @var{A2}, @var{A3}, ... @tab An expression of the same type and kind
8812 as @var{A1}. (As a GNU extension, arguments of different kinds are
8816 @item @emph{Return value}:
8817 The return value corresponds to the maximum value among the arguments,
8818 and has the same type and kind as the first argument.
8820 @item @emph{Specific names}:
8821 @multitable @columnfractions .20 .20 .20 .25
8822 @item Name @tab Argument @tab Return type @tab Standard
8823 @item @code{MIN0(A1)} @tab @code{INTEGER(4) A1} @tab @code{INTEGER(4)} @tab Fortran 77 and later
8824 @item @code{AMIN0(A1)} @tab @code{INTEGER(4) A1} @tab @code{REAL(4)} @tab Fortran 77 and later
8825 @item @code{MIN1(A1)} @tab @code{REAL A1} @tab @code{INTEGER(4)} @tab Fortran 77 and later
8826 @item @code{AMIN1(A1)} @tab @code{REAL(4) A1} @tab @code{REAL(4)} @tab Fortran 77 and later
8827 @item @code{DMIN1(A1)} @tab @code{REAL(8) A1} @tab @code{REAL(8)} @tab Fortran 77 and later
8830 @item @emph{See also}:
8831 @ref{MAX}, @ref{MINLOC}, @ref{MINVAL}
8837 @section @code{MINEXPONENT} --- Minimum exponent of a real kind
8838 @fnindex MINEXPONENT
8839 @cindex model representation, minimum exponent
8842 @item @emph{Description}:
8843 @code{MINEXPONENT(X)} returns the minimum exponent in the model of the
8846 @item @emph{Standard}:
8847 Fortran 95 and later
8852 @item @emph{Syntax}:
8853 @code{RESULT = MINEXPONENT(X)}
8855 @item @emph{Arguments}:
8856 @multitable @columnfractions .15 .70
8857 @item @var{X} @tab Shall be of type @code{REAL}.
8860 @item @emph{Return value}:
8861 The return value is of type @code{INTEGER} and of the default integer
8864 @item @emph{Example}:
8865 See @code{MAXEXPONENT} for an example.
8871 @section @code{MINLOC} --- Location of the minimum value within an array
8873 @cindex array, location of minimum element
8876 @item @emph{Description}:
8877 Determines the location of the element in the array with the minimum
8878 value, or, if the @var{DIM} argument is supplied, determines the
8879 locations of the minimum element along each row of the array in the
8880 @var{DIM} direction. If @var{MASK} is present, only the elements for
8881 which @var{MASK} is @code{.TRUE.} are considered. If more than one
8882 element in the array has the minimum value, the location returned is
8883 that of the first such element in array element order. If the array has
8884 zero size, or all of the elements of @var{MASK} are @code{.FALSE.}, then
8885 the result is an array of zeroes. Similarly, if @var{DIM} is supplied
8886 and all of the elements of @var{MASK} along a given row are zero, the
8887 result value for that row is zero.
8889 @item @emph{Standard}:
8890 Fortran 95 and later
8893 Transformational function
8895 @item @emph{Syntax}:
8896 @multitable @columnfractions .80
8897 @item @code{RESULT = MINLOC(ARRAY, DIM [, MASK])}
8898 @item @code{RESULT = MINLOC(ARRAY [, MASK])}
8901 @item @emph{Arguments}:
8902 @multitable @columnfractions .15 .70
8903 @item @var{ARRAY} @tab Shall be an array of type @code{INTEGER} or
8905 @item @var{DIM} @tab (Optional) Shall be a scalar of type
8906 @code{INTEGER}, with a value between one and the rank of @var{ARRAY},
8907 inclusive. It may not be an optional dummy argument.
8908 @item @var{MASK} @tab Shall be an array of type @code{LOGICAL},
8909 and conformable with @var{ARRAY}.
8912 @item @emph{Return value}:
8913 If @var{DIM} is absent, the result is a rank-one array with a length
8914 equal to the rank of @var{ARRAY}. If @var{DIM} is present, the result
8915 is an array with a rank one less than the rank of @var{ARRAY}, and a
8916 size corresponding to the size of @var{ARRAY} with the @var{DIM}
8917 dimension removed. If @var{DIM} is present and @var{ARRAY} has a rank
8918 of one, the result is a scalar. In all cases, the result is of default
8919 @code{INTEGER} type.
8921 @item @emph{See also}:
8922 @ref{MIN}, @ref{MINVAL}
8929 @section @code{MINVAL} --- Minimum value of an array
8931 @cindex array, minimum value
8932 @cindex minimum value
8935 @item @emph{Description}:
8936 Determines the minimum value of the elements in an array value, or, if
8937 the @var{DIM} argument is supplied, determines the minimum value along
8938 each row of the array in the @var{DIM} direction. If @var{MASK} is
8939 present, only the elements for which @var{MASK} is @code{.TRUE.} are
8940 considered. If the array has zero size, or all of the elements of
8941 @var{MASK} are @code{.FALSE.}, then the result is @code{HUGE(ARRAY)} if
8942 @var{ARRAY} is numeric, or a string of @code{CHAR(255)} characters if
8943 @var{ARRAY} is of character type.
8945 @item @emph{Standard}:
8946 Fortran 95 and later
8949 Transformational function
8951 @item @emph{Syntax}:
8952 @multitable @columnfractions .80
8953 @item @code{RESULT = MINVAL(ARRAY, DIM [, MASK])}
8954 @item @code{RESULT = MINVAL(ARRAY [, MASK])}
8957 @item @emph{Arguments}:
8958 @multitable @columnfractions .15 .70
8959 @item @var{ARRAY} @tab Shall be an array of type @code{INTEGER} or
8961 @item @var{DIM} @tab (Optional) Shall be a scalar of type
8962 @code{INTEGER}, with a value between one and the rank of @var{ARRAY},
8963 inclusive. It may not be an optional dummy argument.
8964 @item @var{MASK} @tab Shall be an array of type @code{LOGICAL},
8965 and conformable with @var{ARRAY}.
8968 @item @emph{Return value}:
8969 If @var{DIM} is absent, or if @var{ARRAY} has a rank of one, the result
8970 is a scalar. If @var{DIM} is present, the result is an array with a
8971 rank one less than the rank of @var{ARRAY}, and a size corresponding to
8972 the size of @var{ARRAY} with the @var{DIM} dimension removed. In all
8973 cases, the result is of the same type and kind as @var{ARRAY}.
8975 @item @emph{See also}:
8976 @ref{MIN}, @ref{MINLOC}
8983 @section @code{MOD} --- Remainder function
8988 @cindex division, remainder
8991 @item @emph{Description}:
8992 @code{MOD(A,P)} computes the remainder of the division of A by P@. It is
8993 calculated as @code{A - (INT(A/P) * P)}.
8995 @item @emph{Standard}:
8996 Fortran 77 and later
9001 @item @emph{Syntax}:
9002 @code{RESULT = MOD(A, P)}
9004 @item @emph{Arguments}:
9005 @multitable @columnfractions .15 .70
9006 @item @var{A} @tab Shall be a scalar of type @code{INTEGER} or @code{REAL}
9007 @item @var{P} @tab Shall be a scalar of the same type as @var{A} and not
9011 @item @emph{Return value}:
9012 The kind of the return value is the result of cross-promoting
9013 the kinds of the arguments.
9015 @item @emph{Example}:
9019 print *, mod(17.5,5.5)
9020 print *, mod(17.5d0,5.5)
9021 print *, mod(17.5,5.5d0)
9024 print *, mod(-17.5,5.5)
9025 print *, mod(-17.5d0,5.5)
9026 print *, mod(-17.5,5.5d0)
9029 print *, mod(17.5,-5.5)
9030 print *, mod(17.5d0,-5.5)
9031 print *, mod(17.5,-5.5d0)
9032 end program test_mod
9035 @item @emph{Specific names}:
9036 @multitable @columnfractions .20 .20 .20 .25
9037 @item Name @tab Arguments @tab Return type @tab Standard
9038 @item @code{MOD(A,P)} @tab @code{INTEGER A,P} @tab @code{INTEGER} @tab Fortran 95 and later
9039 @item @code{AMOD(A,P)} @tab @code{REAL(4) A,P} @tab @code{REAL(4)} @tab Fortran 95 and later
9040 @item @code{DMOD(A,P)} @tab @code{REAL(8) A,P} @tab @code{REAL(8)} @tab Fortran 95 and later
9047 @section @code{MODULO} --- Modulo function
9050 @cindex division, modulo
9053 @item @emph{Description}:
9054 @code{MODULO(A,P)} computes the @var{A} modulo @var{P}.
9056 @item @emph{Standard}:
9057 Fortran 95 and later
9062 @item @emph{Syntax}:
9063 @code{RESULT = MODULO(A, P)}
9065 @item @emph{Arguments}:
9066 @multitable @columnfractions .15 .70
9067 @item @var{A} @tab Shall be a scalar of type @code{INTEGER} or @code{REAL}
9068 @item @var{P} @tab Shall be a scalar of the same type and kind as @var{A}
9071 @item @emph{Return value}:
9072 The type and kind of the result are those of the arguments.
9074 @item If @var{A} and @var{P} are of type @code{INTEGER}:
9075 @code{MODULO(A,P)} has the value @var{R} such that @code{A=Q*P+R}, where
9076 @var{Q} is an integer and @var{R} is between 0 (inclusive) and @var{P}
9078 @item If @var{A} and @var{P} are of type @code{REAL}:
9079 @code{MODULO(A,P)} has the value of @code{A - FLOOR (A / P) * P}.
9081 In all cases, if @var{P} is zero the result is processor-dependent.
9083 @item @emph{Example}:
9086 print *, modulo(17,3)
9087 print *, modulo(17.5,5.5)
9089 print *, modulo(-17,3)
9090 print *, modulo(-17.5,5.5)
9092 print *, modulo(17,-3)
9093 print *, modulo(17.5,-5.5)
9102 @section @code{MOVE_ALLOC} --- Move allocation from one object to another
9104 @cindex moving allocation
9105 @cindex allocation, moving
9108 @item @emph{Description}:
9109 @code{MOVE_ALLOC(FROM, TO)} moves the allocation from @var{FROM} to
9110 @var{TO}. @var{FROM} will become deallocated in the process.
9112 @item @emph{Standard}:
9113 Fortran 2003 and later
9118 @item @emph{Syntax}:
9119 @code{CALL MOVE_ALLOC(FROM, TO)}
9121 @item @emph{Arguments}:
9122 @multitable @columnfractions .15 .70
9123 @item @var{FROM} @tab @code{ALLOCATABLE}, @code{INTENT(INOUT)}, may be
9124 of any type and kind.
9125 @item @var{TO} @tab @code{ALLOCATABLE}, @code{INTENT(OUT)}, shall be
9126 of the same type, kind and rank as @var{FROM}.
9129 @item @emph{Return value}:
9132 @item @emph{Example}:
9134 program test_move_alloc
9135 integer, allocatable :: a(:), b(:)
9139 call move_alloc(a, b)
9140 print *, allocated(a), allocated(b)
9142 end program test_move_alloc
9149 @section @code{MVBITS} --- Move bits from one integer to another
9154 @item @emph{Description}:
9155 Moves @var{LEN} bits from positions @var{FROMPOS} through
9156 @code{FROMPOS+LEN-1} of @var{FROM} to positions @var{TOPOS} through
9157 @code{TOPOS+LEN-1} of @var{TO}. The portion of argument @var{TO} not
9158 affected by the movement of bits is unchanged. The values of
9159 @code{FROMPOS+LEN-1} and @code{TOPOS+LEN-1} must be less than
9160 @code{BIT_SIZE(FROM)}.
9162 @item @emph{Standard}:
9163 Fortran 95 and later
9166 Elemental subroutine
9168 @item @emph{Syntax}:
9169 @code{CALL MVBITS(FROM, FROMPOS, LEN, TO, TOPOS)}
9171 @item @emph{Arguments}:
9172 @multitable @columnfractions .15 .70
9173 @item @var{FROM} @tab The type shall be @code{INTEGER}.
9174 @item @var{FROMPOS} @tab The type shall be @code{INTEGER}.
9175 @item @var{LEN} @tab The type shall be @code{INTEGER}.
9176 @item @var{TO} @tab The type shall be @code{INTEGER}, of the
9177 same kind as @var{FROM}.
9178 @item @var{TOPOS} @tab The type shall be @code{INTEGER}.
9181 @item @emph{See also}:
9182 @ref{IBCLR}, @ref{IBSET}, @ref{IBITS}, @ref{IAND}, @ref{IOR}, @ref{IEOR}
9188 @section @code{NEAREST} --- Nearest representable number
9190 @cindex real number, nearest different
9191 @cindex floating point, nearest different
9194 @item @emph{Description}:
9195 @code{NEAREST(X, S)} returns the processor-representable number nearest
9196 to @code{X} in the direction indicated by the sign of @code{S}.
9198 @item @emph{Standard}:
9199 Fortran 95 and later
9204 @item @emph{Syntax}:
9205 @code{RESULT = NEAREST(X, S)}
9207 @item @emph{Arguments}:
9208 @multitable @columnfractions .15 .70
9209 @item @var{X} @tab Shall be of type @code{REAL}.
9210 @item @var{S} @tab (Optional) shall be of type @code{REAL} and
9214 @item @emph{Return value}:
9215 The return value is of the same type as @code{X}. If @code{S} is
9216 positive, @code{NEAREST} returns the processor-representable number
9217 greater than @code{X} and nearest to it. If @code{S} is negative,
9218 @code{NEAREST} returns the processor-representable number smaller than
9219 @code{X} and nearest to it.
9221 @item @emph{Example}:
9223 program test_nearest
9225 x = nearest(42.0, 1.0)
9226 y = nearest(42.0, -1.0)
9227 write (*,"(3(G20.15))") x, y, x - y
9228 end program test_nearest
9235 @section @code{NEW_LINE} --- New line character
9238 @cindex output, newline
9241 @item @emph{Description}:
9242 @code{NEW_LINE(C)} returns the new-line character.
9244 @item @emph{Standard}:
9245 Fortran 2003 and later
9250 @item @emph{Syntax}:
9251 @code{RESULT = NEW_LINE(C)}
9253 @item @emph{Arguments}:
9254 @multitable @columnfractions .15 .70
9255 @item @var{C} @tab The argument shall be a scalar or array of the
9256 type @code{CHARACTER}.
9259 @item @emph{Return value}:
9260 Returns a @var{CHARACTER} scalar of length one with the new-line character of
9261 the same kind as parameter @var{C}.
9263 @item @emph{Example}:
9267 write(*,'(A)') 'This is record 1.'//NEW_LINE('A')//'This is record 2.'
9275 @section @code{NINT} --- Nearest whole number
9278 @cindex rounding, nearest whole number
9281 @item @emph{Description}:
9282 @code{NINT(A)} rounds its argument to the nearest whole number.
9284 @item @emph{Standard}:
9285 Fortran 77 and later, with @var{KIND} argument Fortran 90 and later
9290 @item @emph{Syntax}:
9291 @code{RESULT = NINT(A [, KIND])}
9293 @item @emph{Arguments}:
9294 @multitable @columnfractions .15 .70
9295 @item @var{A} @tab The type of the argument shall be @code{REAL}.
9296 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
9297 expression indicating the kind parameter of the result.
9300 @item @emph{Return value}:
9301 Returns @var{A} with the fractional portion of its magnitude eliminated by
9302 rounding to the nearest whole number and with its sign preserved,
9303 converted to an @code{INTEGER} of the default kind.
9305 @item @emph{Example}:
9312 print *, nint(x4), idnint(x8)
9313 end program test_nint
9316 @item @emph{Specific names}:
9317 @multitable @columnfractions .20 .20 .20 .25
9318 @item Name @tab Argument @tab Return Type @tab Standard
9319 @item @code{NINT(A)} @tab @code{REAL(4) A} @tab @code{INTEGER} @tab Fortran 95 and later
9320 @item @code{IDNINT(A)} @tab @code{REAL(8) A} @tab @code{INTEGER} @tab Fortran 95 and later
9323 @item @emph{See also}:
9324 @ref{CEILING}, @ref{FLOOR}
9331 @section @code{NORM2} --- Euclidean vector norms
9333 @cindex Euclidean vector norm
9334 @cindex L2 vector norm
9335 @cindex norm, Euclidean
9338 @item @emph{Description}:
9339 Calculates the Euclidean vector norm (@math{L_2} norm) of
9340 of @var{ARRAY} along dimension @var{DIM}.
9342 @item @emph{Standard}:
9343 Fortran 2008 and later
9346 Transformational function
9348 @item @emph{Syntax}:
9349 @multitable @columnfractions .80
9350 @item @code{RESULT = NORM2(ARRAY[, DIM])}
9353 @item @emph{Arguments}:
9354 @multitable @columnfractions .15 .70
9355 @item @var{ARRAY} @tab Shall be an array of type @code{REAL}
9356 @item @var{DIM} @tab (Optional) shall be a scalar of type
9357 @code{INTEGER} with a value in the range from 1 to n, where n
9358 equals the rank of @var{ARRAY}.
9361 @item @emph{Return value}:
9362 The result is of the same type as @var{ARRAY}.
9364 If @var{DIM} is absent, a scalar with the square root of the sum of all
9365 elements in @var{ARRAY} squared is returned. Otherwise, an array of
9366 rank @math{n-1}, where @math{n} equals the rank of @var{ARRAY}, and a
9367 shape similar to that of @var{ARRAY} with dimension @var{DIM} dropped
9370 @item @emph{Example}:
9373 REAL :: x(5) = [ real :: 1, 2, 3, 4, 5 ]
9374 print *, NORM2(x) ! = sqrt(55.) ~ 7.416
9382 @section @code{NOT} --- Logical negation
9384 @cindex bits, negate
9385 @cindex bitwise logical not
9386 @cindex logical not, bitwise
9389 @item @emph{Description}:
9390 @code{NOT} returns the bitwise Boolean inverse of @var{I}.
9392 @item @emph{Standard}:
9393 Fortran 95 and later
9398 @item @emph{Syntax}:
9399 @code{RESULT = NOT(I)}
9401 @item @emph{Arguments}:
9402 @multitable @columnfractions .15 .70
9403 @item @var{I} @tab The type shall be @code{INTEGER}.
9406 @item @emph{Return value}:
9407 The return type is @code{INTEGER}, of the same kind as the
9410 @item @emph{See also}:
9411 @ref{IAND}, @ref{IEOR}, @ref{IOR}, @ref{IBITS}, @ref{IBSET}, @ref{IBCLR}
9418 @section @code{NULL} --- Function that returns an disassociated pointer
9420 @cindex pointer, status
9421 @cindex pointer, disassociated
9424 @item @emph{Description}:
9425 Returns a disassociated pointer.
9427 If @var{MOLD} is present, a disassociated pointer of the same type is
9428 returned, otherwise the type is determined by context.
9430 In Fortran 95, @var{MOLD} is optional. Please note that Fortran 2003
9431 includes cases where it is required.
9433 @item @emph{Standard}:
9434 Fortran 95 and later
9437 Transformational function
9439 @item @emph{Syntax}:
9440 @code{PTR => NULL([MOLD])}
9442 @item @emph{Arguments}:
9443 @multitable @columnfractions .15 .70
9444 @item @var{MOLD} @tab (Optional) shall be a pointer of any association
9445 status and of any type.
9448 @item @emph{Return value}:
9449 A disassociated pointer.
9451 @item @emph{Example}:
9453 REAL, POINTER, DIMENSION(:) :: VEC => NULL ()
9456 @item @emph{See also}:
9463 @section @code{NUM_IMAGES} --- Function that returns the number of images
9465 @cindex coarray, @code{NUM_IMAGES}
9466 @cindex images, number of
9469 @item @emph{Description}:
9470 Returns the number of images.
9472 @item @emph{Standard}:
9473 Fortran 2008 and later
9476 Transformational function
9478 @item @emph{Syntax}:
9479 @code{RESULT = NUM_IMAGES()}
9481 @item @emph{Arguments}: None.
9483 @item @emph{Return value}:
9484 Scalar default-kind integer.
9486 @item @emph{Example}:
9490 value = THIS_IMAGE()
9492 IF (THIS_IMAGE() == 1) THEN
9493 DO i = 1, NUM_IMAGES()
9494 WRITE(*,'(2(a,i0))') 'value[', i, '] is ', value[i]
9499 @item @emph{See also}:
9500 @ref{THIS_IMAGE}, @ref{IMAGE_INDEX}
9506 @section @code{OR} --- Bitwise logical OR
9508 @cindex bitwise logical or
9509 @cindex logical or, bitwise
9512 @item @emph{Description}:
9513 Bitwise logical @code{OR}.
9515 This intrinsic routine is provided for backwards compatibility with
9516 GNU Fortran 77. For integer arguments, programmers should consider
9517 the use of the @ref{IOR} intrinsic defined by the Fortran standard.
9519 @item @emph{Standard}:
9525 @item @emph{Syntax}:
9526 @code{RESULT = OR(I, J)}
9528 @item @emph{Arguments}:
9529 @multitable @columnfractions .15 .70
9530 @item @var{I} @tab The type shall be either a scalar @code{INTEGER}
9531 type or a scalar @code{LOGICAL} type.
9532 @item @var{J} @tab The type shall be the same as the type of @var{J}.
9535 @item @emph{Return value}:
9536 The return type is either a scalar @code{INTEGER} or a scalar
9537 @code{LOGICAL}. If the kind type parameters differ, then the
9538 smaller kind type is implicitly converted to larger kind, and the
9539 return has the larger kind.
9541 @item @emph{Example}:
9544 LOGICAL :: T = .TRUE., F = .FALSE.
9546 DATA a / Z'F' /, b / Z'3' /
9548 WRITE (*,*) OR(T, T), OR(T, F), OR(F, T), OR(F, F)
9549 WRITE (*,*) OR(a, b)
9553 @item @emph{See also}:
9554 Fortran 95 elemental function: @ref{IOR}
9560 @section @code{PACK} --- Pack an array into an array of rank one
9562 @cindex array, packing
9563 @cindex array, reduce dimension
9564 @cindex array, gather elements
9567 @item @emph{Description}:
9568 Stores the elements of @var{ARRAY} in an array of rank one.
9570 The beginning of the resulting array is made up of elements whose @var{MASK}
9571 equals @code{TRUE}. Afterwards, positions are filled with elements taken from
9574 @item @emph{Standard}:
9575 Fortran 95 and later
9578 Transformational function
9580 @item @emph{Syntax}:
9581 @code{RESULT = PACK(ARRAY, MASK[,VECTOR]}
9583 @item @emph{Arguments}:
9584 @multitable @columnfractions .15 .70
9585 @item @var{ARRAY} @tab Shall be an array of any type.
9586 @item @var{MASK} @tab Shall be an array of type @code{LOGICAL} and
9587 of the same size as @var{ARRAY}. Alternatively, it may be a @code{LOGICAL}
9589 @item @var{VECTOR} @tab (Optional) shall be an array of the same type
9590 as @var{ARRAY} and of rank one. If present, the number of elements in
9591 @var{VECTOR} shall be equal to or greater than the number of true elements
9592 in @var{MASK}. If @var{MASK} is scalar, the number of elements in
9593 @var{VECTOR} shall be equal to or greater than the number of elements in
9597 @item @emph{Return value}:
9598 The result is an array of rank one and the same type as that of @var{ARRAY}.
9599 If @var{VECTOR} is present, the result size is that of @var{VECTOR}, the
9600 number of @code{TRUE} values in @var{MASK} otherwise.
9602 @item @emph{Example}:
9603 Gathering nonzero elements from an array:
9607 m = (/ 1, 0, 0, 0, 5, 0 /)
9608 WRITE(*, FMT="(6(I0, ' '))") pack(m, m /= 0) ! "1 5"
9612 Gathering nonzero elements from an array and appending elements from @var{VECTOR}:
9616 m = (/ 1, 0, 0, 2 /)
9617 WRITE(*, FMT="(4(I0, ' '))") pack(m, m /= 0, (/ 0, 0, 3, 4 /)) ! "1 2 3 4"
9621 @item @emph{See also}:
9628 @section @code{PARITY} --- Reduction with exclusive OR
9631 @cindex Reduction, XOR
9632 @cindex XOR reduction
9635 @item @emph{Description}:
9636 Calculates the parity, i.e. the reduction using @code{.XOR.},
9637 of @var{MASK} along dimension @var{DIM}.
9639 @item @emph{Standard}:
9640 Fortran 2008 and later
9643 Transformational function
9645 @item @emph{Syntax}:
9646 @multitable @columnfractions .80
9647 @item @code{RESULT = PARITY(MASK[, DIM])}
9650 @item @emph{Arguments}:
9651 @multitable @columnfractions .15 .70
9652 @item @var{LOGICAL} @tab Shall be an array of type @code{LOGICAL}
9653 @item @var{DIM} @tab (Optional) shall be a scalar of type
9654 @code{INTEGER} with a value in the range from 1 to n, where n
9655 equals the rank of @var{MASK}.
9658 @item @emph{Return value}:
9659 The result is of the same type as @var{MASK}.
9661 If @var{DIM} is absent, a scalar with the parity of all elements in
9662 @var{MASK} is returned, i.e. true if an odd number of elements is
9663 @code{.true.} and false otherwise. If @var{DIM} is present, an array
9664 of rank @math{n-1}, where @math{n} equals the rank of @var{ARRAY},
9665 and a shape similar to that of @var{MASK} with dimension @var{DIM}
9666 dropped is returned.
9668 @item @emph{Example}:
9671 LOGICAL :: x(2) = [ .true., .false. ]
9672 print *, PARITY(x) ! prints "T" (true).
9680 @section @code{PERROR} --- Print system error message
9682 @cindex system, error handling
9685 @item @emph{Description}:
9686 Prints (on the C @code{stderr} stream) a newline-terminated error
9687 message corresponding to the last system error. This is prefixed by
9688 @var{STRING}, a colon and a space. See @code{perror(3)}.
9690 @item @emph{Standard}:
9696 @item @emph{Syntax}:
9697 @code{CALL PERROR(STRING)}
9699 @item @emph{Arguments}:
9700 @multitable @columnfractions .15 .70
9701 @item @var{STRING} @tab A scalar of type @code{CHARACTER} and of the
9705 @item @emph{See also}:
9712 @section @code{PRECISION} --- Decimal precision of a real kind
9714 @cindex model representation, precision
9717 @item @emph{Description}:
9718 @code{PRECISION(X)} returns the decimal precision in the model of the
9721 @item @emph{Standard}:
9722 Fortran 95 and later
9727 @item @emph{Syntax}:
9728 @code{RESULT = PRECISION(X)}
9730 @item @emph{Arguments}:
9731 @multitable @columnfractions .15 .70
9732 @item @var{X} @tab Shall be of type @code{REAL} or @code{COMPLEX}.
9735 @item @emph{Return value}:
9736 The return value is of type @code{INTEGER} and of the default integer
9739 @item @emph{See also}:
9740 @ref{SELECTED_REAL_KIND}, @ref{RANGE}
9742 @item @emph{Example}:
9744 program prec_and_range
9745 real(kind=4) :: x(2)
9746 complex(kind=8) :: y
9748 print *, precision(x), range(x)
9749 print *, precision(y), range(y)
9750 end program prec_and_range
9757 @section @code{POPCNT} --- Number of bits set
9759 @cindex binary representation
9763 @item @emph{Description}:
9764 @code{POPCNT(I)} returns the number of bits set ('1' bits) in the binary
9765 representation of @code{I}.
9767 @item @emph{Standard}:
9768 Fortran 2008 and later
9773 @item @emph{Syntax}:
9774 @code{RESULT = POPCNT(I)}
9776 @item @emph{Arguments}:
9777 @multitable @columnfractions .15 .70
9778 @item @var{I} @tab Shall be of type @code{INTEGER}.
9781 @item @emph{Return value}:
9782 The return value is of type @code{INTEGER} and of the default integer
9785 @item @emph{See also}:
9786 @ref{POPPAR}, @ref{LEADZ}, @ref{TRAILZ}
9788 @item @emph{Example}:
9790 program test_population
9791 print *, popcnt(127), poppar(127)
9792 print *, popcnt(huge(0_4)), poppar(huge(0_4))
9793 print *, popcnt(huge(0_8)), poppar(huge(0_8))
9794 end program test_population
9800 @section @code{POPPAR} --- Parity of the number of bits set
9802 @cindex binary representation
9806 @item @emph{Description}:
9807 @code{POPPAR(I)} returns parity of the integer @code{I}, i.e. the parity
9808 of the number of bits set ('1' bits) in the binary representation of
9809 @code{I}. It is equal to 0 if @code{I} has an even number of bits set,
9810 and 1 for an odd number of '1' bits.
9812 @item @emph{Standard}:
9813 Fortran 2008 and later
9818 @item @emph{Syntax}:
9819 @code{RESULT = POPPAR(I)}
9821 @item @emph{Arguments}:
9822 @multitable @columnfractions .15 .70
9823 @item @var{I} @tab Shall be of type @code{INTEGER}.
9826 @item @emph{Return value}:
9827 The return value is of type @code{INTEGER} and of the default integer
9830 @item @emph{See also}:
9831 @ref{POPCNT}, @ref{LEADZ}, @ref{TRAILZ}
9833 @item @emph{Example}:
9835 program test_population
9836 print *, popcnt(127), poppar(127)
9837 print *, popcnt(huge(0_4)), poppar(huge(0_4))
9838 print *, popcnt(huge(0_8)), poppar(huge(0_8))
9839 end program test_population
9846 @section @code{PRESENT} --- Determine whether an optional dummy argument is specified
9850 @item @emph{Description}:
9851 Determines whether an optional dummy argument is present.
9853 @item @emph{Standard}:
9854 Fortran 95 and later
9859 @item @emph{Syntax}:
9860 @code{RESULT = PRESENT(A)}
9862 @item @emph{Arguments}:
9863 @multitable @columnfractions .15 .70
9864 @item @var{A} @tab May be of any type and may be a pointer, scalar or array
9865 value, or a dummy procedure. It shall be the name of an optional dummy argument
9866 accessible within the current subroutine or function.
9869 @item @emph{Return value}:
9870 Returns either @code{TRUE} if the optional argument @var{A} is present, or
9871 @code{FALSE} otherwise.
9873 @item @emph{Example}:
9875 PROGRAM test_present
9876 WRITE(*,*) f(), f(42) ! "F T"
9878 LOGICAL FUNCTION f(x)
9879 INTEGER, INTENT(IN), OPTIONAL :: x
9889 @section @code{PRODUCT} --- Product of array elements
9891 @cindex array, product
9892 @cindex array, multiply elements
9893 @cindex array, conditionally multiply elements
9894 @cindex multiply array elements
9897 @item @emph{Description}:
9898 Multiplies the elements of @var{ARRAY} along dimension @var{DIM} if
9899 the corresponding element in @var{MASK} is @code{TRUE}.
9901 @item @emph{Standard}:
9902 Fortran 95 and later
9905 Transformational function
9907 @item @emph{Syntax}:
9908 @multitable @columnfractions .80
9909 @item @code{RESULT = PRODUCT(ARRAY[, MASK])}
9910 @item @code{RESULT = PRODUCT(ARRAY, DIM[, MASK])}
9913 @item @emph{Arguments}:
9914 @multitable @columnfractions .15 .70
9915 @item @var{ARRAY} @tab Shall be an array of type @code{INTEGER},
9916 @code{REAL} or @code{COMPLEX}.
9917 @item @var{DIM} @tab (Optional) shall be a scalar of type
9918 @code{INTEGER} with a value in the range from 1 to n, where n
9919 equals the rank of @var{ARRAY}.
9920 @item @var{MASK} @tab (Optional) shall be of type @code{LOGICAL}
9921 and either be a scalar or an array of the same shape as @var{ARRAY}.
9924 @item @emph{Return value}:
9925 The result is of the same type as @var{ARRAY}.
9927 If @var{DIM} is absent, a scalar with the product of all elements in
9928 @var{ARRAY} is returned. Otherwise, an array of rank n-1, where n equals
9929 the rank of @var{ARRAY}, and a shape similar to that of @var{ARRAY} with
9930 dimension @var{DIM} dropped is returned.
9933 @item @emph{Example}:
9935 PROGRAM test_product
9936 INTEGER :: x(5) = (/ 1, 2, 3, 4 ,5 /)
9937 print *, PRODUCT(x) ! all elements, product = 120
9938 print *, PRODUCT(x, MASK=MOD(x, 2)==1) ! odd elements, product = 15
9942 @item @emph{See also}:
9949 @section @code{RADIX} --- Base of a model number
9951 @cindex model representation, base
9952 @cindex model representation, radix
9955 @item @emph{Description}:
9956 @code{RADIX(X)} returns the base of the model representing the entity @var{X}.
9958 @item @emph{Standard}:
9959 Fortran 95 and later
9964 @item @emph{Syntax}:
9965 @code{RESULT = RADIX(X)}
9967 @item @emph{Arguments}:
9968 @multitable @columnfractions .15 .70
9969 @item @var{X} @tab Shall be of type @code{INTEGER} or @code{REAL}
9972 @item @emph{Return value}:
9973 The return value is a scalar of type @code{INTEGER} and of the default
9976 @item @emph{See also}:
9977 @ref{SELECTED_REAL_KIND}
9979 @item @emph{Example}:
9982 print *, "The radix for the default integer kind is", radix(0)
9983 print *, "The radix for the default real kind is", radix(0.0)
9984 end program test_radix
9992 @section @code{RAN} --- Real pseudo-random number
9994 @cindex random number generation
9997 @item @emph{Description}:
9998 For compatibility with HP FORTRAN 77/iX, the @code{RAN} intrinsic is
9999 provided as an alias for @code{RAND}. See @ref{RAND} for complete
10002 @item @emph{Standard}:
10005 @item @emph{Class}:
10008 @item @emph{See also}:
10009 @ref{RAND}, @ref{RANDOM_NUMBER}
10015 @section @code{RAND} --- Real pseudo-random number
10017 @cindex random number generation
10020 @item @emph{Description}:
10021 @code{RAND(FLAG)} returns a pseudo-random number from a uniform
10022 distribution between 0 and 1. If @var{FLAG} is 0, the next number
10023 in the current sequence is returned; if @var{FLAG} is 1, the generator
10024 is restarted by @code{CALL SRAND(0)}; if @var{FLAG} has any other value,
10025 it is used as a new seed with @code{SRAND}.
10027 This intrinsic routine is provided for backwards compatibility with
10028 GNU Fortran 77. It implements a simple modulo generator as provided
10029 by @command{g77}. For new code, one should consider the use of
10030 @ref{RANDOM_NUMBER} as it implements a superior algorithm.
10032 @item @emph{Standard}:
10035 @item @emph{Class}:
10038 @item @emph{Syntax}:
10039 @code{RESULT = RAND(I)}
10041 @item @emph{Arguments}:
10042 @multitable @columnfractions .15 .70
10043 @item @var{I} @tab Shall be a scalar @code{INTEGER} of kind 4.
10046 @item @emph{Return value}:
10047 The return value is of @code{REAL} type and the default kind.
10049 @item @emph{Example}:
10052 integer,parameter :: seed = 86456
10055 print *, rand(), rand(), rand(), rand()
10056 print *, rand(seed), rand(), rand(), rand()
10057 end program test_rand
10060 @item @emph{See also}:
10061 @ref{SRAND}, @ref{RANDOM_NUMBER}
10067 @node RANDOM_NUMBER
10068 @section @code{RANDOM_NUMBER} --- Pseudo-random number
10069 @fnindex RANDOM_NUMBER
10070 @cindex random number generation
10073 @item @emph{Description}:
10074 Returns a single pseudorandom number or an array of pseudorandom numbers
10075 from the uniform distribution over the range @math{ 0 \leq x < 1}.
10077 The runtime-library implements George Marsaglia's KISS (Keep It Simple
10078 Stupid) random number generator (RNG). This RNG combines:
10080 @item The congruential generator @math{x(n) = 69069 \cdot x(n-1) + 1327217885}
10081 with a period of @math{2^{32}},
10082 @item A 3-shift shift-register generator with a period of @math{2^{32} - 1},
10083 @item Two 16-bit multiply-with-carry generators with a period of
10084 @math{597273182964842497 > 2^{59}}.
10086 The overall period exceeds @math{2^{123}}.
10088 Please note, this RNG is thread safe if used within OpenMP directives,
10089 i.e., its state will be consistent while called from multiple threads.
10090 However, the KISS generator does not create random numbers in parallel
10091 from multiple sources, but in sequence from a single source. If an
10092 OpenMP-enabled application heavily relies on random numbers, one should
10093 consider employing a dedicated parallel random number generator instead.
10095 @item @emph{Standard}:
10096 Fortran 95 and later
10098 @item @emph{Class}:
10101 @item @emph{Syntax}:
10102 @code{RANDOM_NUMBER(HARVEST)}
10104 @item @emph{Arguments}:
10105 @multitable @columnfractions .15 .70
10106 @item @var{HARVEST} @tab Shall be a scalar or an array of type @code{REAL}.
10109 @item @emph{Example}:
10111 program test_random_number
10113 CALL init_random_seed() ! see example of RANDOM_SEED
10114 CALL RANDOM_NUMBER(r)
10118 @item @emph{See also}:
10125 @section @code{RANDOM_SEED} --- Initialize a pseudo-random number sequence
10126 @fnindex RANDOM_SEED
10127 @cindex random number generation, seeding
10128 @cindex seeding a random number generator
10131 @item @emph{Description}:
10132 Restarts or queries the state of the pseudorandom number generator used by
10133 @code{RANDOM_NUMBER}.
10135 If @code{RANDOM_SEED} is called without arguments, it is initialized to
10136 a default state. The example below shows how to initialize the random
10137 seed based on the system's time.
10139 @item @emph{Standard}:
10140 Fortran 95 and later
10142 @item @emph{Class}:
10145 @item @emph{Syntax}:
10146 @code{CALL RANDOM_SEED([SIZE, PUT, GET])}
10148 @item @emph{Arguments}:
10149 @multitable @columnfractions .15 .70
10150 @item @var{SIZE} @tab (Optional) Shall be a scalar and of type default
10151 @code{INTEGER}, with @code{INTENT(OUT)}. It specifies the minimum size
10152 of the arrays used with the @var{PUT} and @var{GET} arguments.
10153 @item @var{PUT} @tab (Optional) Shall be an array of type default
10154 @code{INTEGER} and rank one. It is @code{INTENT(IN)} and the size of
10155 the array must be larger than or equal to the number returned by the
10156 @var{SIZE} argument.
10157 @item @var{GET} @tab (Optional) Shall be an array of type default
10158 @code{INTEGER} and rank one. It is @code{INTENT(OUT)} and the size
10159 of the array must be larger than or equal to the number returned by
10160 the @var{SIZE} argument.
10163 @item @emph{Example}:
10165 SUBROUTINE init_random_seed()
10166 INTEGER :: i, n, clock
10167 INTEGER, DIMENSION(:), ALLOCATABLE :: seed
10169 CALL RANDOM_SEED(size = n)
10172 CALL SYSTEM_CLOCK(COUNT=clock)
10174 seed = clock + 37 * (/ (i - 1, i = 1, n) /)
10175 CALL RANDOM_SEED(PUT = seed)
10181 @item @emph{See also}:
10182 @ref{RANDOM_NUMBER}
10188 @section @code{RANGE} --- Decimal exponent range
10190 @cindex model representation, range
10193 @item @emph{Description}:
10194 @code{RANGE(X)} returns the decimal exponent range in the model of the
10197 @item @emph{Standard}:
10198 Fortran 95 and later
10200 @item @emph{Class}:
10203 @item @emph{Syntax}:
10204 @code{RESULT = RANGE(X)}
10206 @item @emph{Arguments}:
10207 @multitable @columnfractions .15 .70
10208 @item @var{X} @tab Shall be of type @code{INTEGER}, @code{REAL}
10212 @item @emph{Return value}:
10213 The return value is of type @code{INTEGER} and of the default integer
10216 @item @emph{See also}:
10217 @ref{SELECTED_REAL_KIND}, @ref{PRECISION}
10219 @item @emph{Example}:
10220 See @code{PRECISION} for an example.
10226 @section @code{RANK} --- Rank of a data object
10231 @item @emph{Description}:
10232 @code{RANK(A)} returns the rank of a scalar or array data object.
10234 @item @emph{Standard}:
10235 Technical Specification (TS) 29113
10237 @item @emph{Class}:
10240 @item @emph{Syntax}:
10241 @code{RESULT = RANGE(A)}
10243 @item @emph{Arguments}:
10244 @multitable @columnfractions .15 .70
10245 @item @var{A} @tab can be of any type
10248 @item @emph{Return value}:
10249 The return value is of type @code{INTEGER} and of the default integer
10250 kind. For arrays, their rank is returned; for scalars zero is returned.
10252 @item @emph{Example}:
10256 real, allocatable :: b(:,:)
10258 print *, rank(a), rank(b) ! Prints: 0 3
10259 end program test_rank
10267 @section @code{REAL} --- Convert to real type
10273 @cindex conversion, to real
10274 @cindex complex numbers, real part
10277 @item @emph{Description}:
10278 @code{REAL(A [, KIND])} converts its argument @var{A} to a real type. The
10279 @code{REALPART} function is provided for compatibility with @command{g77},
10280 and its use is strongly discouraged.
10282 @item @emph{Standard}:
10283 Fortran 77 and later
10285 @item @emph{Class}:
10288 @item @emph{Syntax}:
10289 @multitable @columnfractions .80
10290 @item @code{RESULT = REAL(A [, KIND])}
10291 @item @code{RESULT = REALPART(Z)}
10294 @item @emph{Arguments}:
10295 @multitable @columnfractions .15 .70
10296 @item @var{A} @tab Shall be @code{INTEGER}, @code{REAL}, or
10298 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
10299 expression indicating the kind parameter of the result.
10302 @item @emph{Return value}:
10303 These functions return a @code{REAL} variable or array under
10304 the following rules:
10308 @code{REAL(A)} is converted to a default real type if @var{A} is an
10309 integer or real variable.
10311 @code{REAL(A)} is converted to a real type with the kind type parameter
10312 of @var{A} if @var{A} is a complex variable.
10314 @code{REAL(A, KIND)} is converted to a real type with kind type
10315 parameter @var{KIND} if @var{A} is a complex, integer, or real
10319 @item @emph{Example}:
10322 complex :: x = (1.0, 2.0)
10323 print *, real(x), real(x,8), realpart(x)
10324 end program test_real
10327 @item @emph{Specific names}:
10328 @multitable @columnfractions .20 .20 .20 .25
10329 @item Name @tab Argument @tab Return type @tab Standard
10330 @item @code{FLOAT(A)} @tab @code{INTEGER(4)} @tab @code{REAL(4)} @tab Fortran 77 and later
10331 @item @code{DFLOAT(A)} @tab @code{INTEGER(4)} @tab @code{REAL(8)} @tab GNU extension
10332 @item @code{SNGL(A)} @tab @code{INTEGER(8)} @tab @code{REAL(4)} @tab Fortran 77 and later
10336 @item @emph{See also}:
10344 @section @code{RENAME} --- Rename a file
10346 @cindex file system, rename file
10349 @item @emph{Description}:
10350 Renames a file from file @var{PATH1} to @var{PATH2}. A null
10351 character (@code{CHAR(0)}) can be used to mark the end of the names in
10352 @var{PATH1} and @var{PATH2}; otherwise, trailing blanks in the file
10353 names are ignored. If the @var{STATUS} argument is supplied, it
10354 contains 0 on success or a nonzero error code upon return; see
10357 This intrinsic is provided in both subroutine and function forms;
10358 however, only one form can be used in any given program unit.
10360 @item @emph{Standard}:
10363 @item @emph{Class}:
10364 Subroutine, function
10366 @item @emph{Syntax}:
10367 @multitable @columnfractions .80
10368 @item @code{CALL RENAME(PATH1, PATH2 [, STATUS])}
10369 @item @code{STATUS = RENAME(PATH1, PATH2)}
10372 @item @emph{Arguments}:
10373 @multitable @columnfractions .15 .70
10374 @item @var{PATH1} @tab Shall be of default @code{CHARACTER} type.
10375 @item @var{PATH2} @tab Shall be of default @code{CHARACTER} type.
10376 @item @var{STATUS} @tab (Optional) Shall be of default @code{INTEGER} type.
10379 @item @emph{See also}:
10387 @section @code{REPEAT} --- Repeated string concatenation
10389 @cindex string, repeat
10390 @cindex string, concatenate
10393 @item @emph{Description}:
10394 Concatenates @var{NCOPIES} copies of a string.
10396 @item @emph{Standard}:
10397 Fortran 95 and later
10399 @item @emph{Class}:
10400 Transformational function
10402 @item @emph{Syntax}:
10403 @code{RESULT = REPEAT(STRING, NCOPIES)}
10405 @item @emph{Arguments}:
10406 @multitable @columnfractions .15 .70
10407 @item @var{STRING} @tab Shall be scalar and of type @code{CHARACTER}.
10408 @item @var{NCOPIES} @tab Shall be scalar and of type @code{INTEGER}.
10411 @item @emph{Return value}:
10412 A new scalar of type @code{CHARACTER} built up from @var{NCOPIES} copies
10415 @item @emph{Example}:
10417 program test_repeat
10418 write(*,*) repeat("x", 5) ! "xxxxx"
10426 @section @code{RESHAPE} --- Function to reshape an array
10428 @cindex array, change dimensions
10429 @cindex array, transmogrify
10432 @item @emph{Description}:
10433 Reshapes @var{SOURCE} to correspond to @var{SHAPE}. If necessary,
10434 the new array may be padded with elements from @var{PAD} or permuted
10435 as defined by @var{ORDER}.
10437 @item @emph{Standard}:
10438 Fortran 95 and later
10440 @item @emph{Class}:
10441 Transformational function
10443 @item @emph{Syntax}:
10444 @code{RESULT = RESHAPE(SOURCE, SHAPE[, PAD, ORDER])}
10446 @item @emph{Arguments}:
10447 @multitable @columnfractions .15 .70
10448 @item @var{SOURCE} @tab Shall be an array of any type.
10449 @item @var{SHAPE} @tab Shall be of type @code{INTEGER} and an
10450 array of rank one. Its values must be positive or zero.
10451 @item @var{PAD} @tab (Optional) shall be an array of the same
10452 type as @var{SOURCE}.
10453 @item @var{ORDER} @tab (Optional) shall be of type @code{INTEGER}
10454 and an array of the same shape as @var{SHAPE}. Its values shall
10455 be a permutation of the numbers from 1 to n, where n is the size of
10456 @var{SHAPE}. If @var{ORDER} is absent, the natural ordering shall
10460 @item @emph{Return value}:
10461 The result is an array of shape @var{SHAPE} with the same type as
10464 @item @emph{Example}:
10466 PROGRAM test_reshape
10467 INTEGER, DIMENSION(4) :: x
10468 WRITE(*,*) SHAPE(x) ! prints "4"
10469 WRITE(*,*) SHAPE(RESHAPE(x, (/2, 2/))) ! prints "2 2"
10473 @item @emph{See also}:
10480 @section @code{RRSPACING} --- Reciprocal of the relative spacing
10482 @cindex real number, relative spacing
10483 @cindex floating point, relative spacing
10487 @item @emph{Description}:
10488 @code{RRSPACING(X)} returns the reciprocal of the relative spacing of
10489 model numbers near @var{X}.
10491 @item @emph{Standard}:
10492 Fortran 95 and later
10494 @item @emph{Class}:
10497 @item @emph{Syntax}:
10498 @code{RESULT = RRSPACING(X)}
10500 @item @emph{Arguments}:
10501 @multitable @columnfractions .15 .70
10502 @item @var{X} @tab Shall be of type @code{REAL}.
10505 @item @emph{Return value}:
10506 The return value is of the same type and kind as @var{X}.
10507 The value returned is equal to
10508 @code{ABS(FRACTION(X)) * FLOAT(RADIX(X))**DIGITS(X)}.
10510 @item @emph{See also}:
10517 @section @code{RSHIFT} --- Right shift bits
10519 @cindex bits, shift right
10522 @item @emph{Description}:
10523 @code{RSHIFT} returns a value corresponding to @var{I} with all of the
10524 bits shifted right by @var{SHIFT} places. If the absolute value of
10525 @var{SHIFT} is greater than @code{BIT_SIZE(I)}, the value is undefined.
10526 Bits shifted out from the right end are lost. The fill is arithmetic: the
10527 bits shifted in from the left end are equal to the leftmost bit, which in
10528 two's complement representation is the sign bit.
10530 This function has been superseded by the @code{SHIFTA} intrinsic, which
10531 is standard in Fortran 2008 and later.
10533 @item @emph{Standard}:
10536 @item @emph{Class}:
10539 @item @emph{Syntax}:
10540 @code{RESULT = RSHIFT(I, SHIFT)}
10542 @item @emph{Arguments}:
10543 @multitable @columnfractions .15 .70
10544 @item @var{I} @tab The type shall be @code{INTEGER}.
10545 @item @var{SHIFT} @tab The type shall be @code{INTEGER}.
10548 @item @emph{Return value}:
10549 The return value is of type @code{INTEGER} and of the same kind as
10552 @item @emph{See also}:
10553 @ref{ISHFT}, @ref{ISHFTC}, @ref{LSHIFT}, @ref{SHIFTA}, @ref{SHIFTR},
10561 @section @code{SAME_TYPE_AS} --- Query dynamic types for equality
10562 @fnindex SAME_TYPE_AS
10565 @item @emph{Description}:
10566 Query dynamic types for equality.
10568 @item @emph{Standard}:
10569 Fortran 2003 and later
10571 @item @emph{Class}:
10574 @item @emph{Syntax}:
10575 @code{RESULT = SAME_TYPE_AS(A, B)}
10577 @item @emph{Arguments}:
10578 @multitable @columnfractions .15 .70
10579 @item @var{A} @tab Shall be an object of extensible declared type or
10580 unlimited polymorphic.
10581 @item @var{B} @tab Shall be an object of extensible declared type or
10582 unlimited polymorphic.
10585 @item @emph{Return value}:
10586 The return value is a scalar of type default logical. It is true if and
10587 only if the dynamic type of A is the same as the dynamic type of B.
10589 @item @emph{See also}:
10590 @ref{EXTENDS_TYPE_OF}
10597 @section @code{SCALE} --- Scale a real value
10599 @cindex real number, scale
10600 @cindex floating point, scale
10603 @item @emph{Description}:
10604 @code{SCALE(X,I)} returns @code{X * RADIX(X)**I}.
10606 @item @emph{Standard}:
10607 Fortran 95 and later
10609 @item @emph{Class}:
10612 @item @emph{Syntax}:
10613 @code{RESULT = SCALE(X, I)}
10615 @item @emph{Arguments}:
10616 @multitable @columnfractions .15 .70
10617 @item @var{X} @tab The type of the argument shall be a @code{REAL}.
10618 @item @var{I} @tab The type of the argument shall be a @code{INTEGER}.
10621 @item @emph{Return value}:
10622 The return value is of the same type and kind as @var{X}.
10623 Its value is @code{X * RADIX(X)**I}.
10625 @item @emph{Example}:
10628 real :: x = 178.1387e-4
10630 print *, scale(x,i), x*radix(x)**i
10631 end program test_scale
10639 @section @code{SCAN} --- Scan a string for the presence of a set of characters
10641 @cindex string, find subset
10644 @item @emph{Description}:
10645 Scans a @var{STRING} for any of the characters in a @var{SET}
10648 If @var{BACK} is either absent or equals @code{FALSE}, this function
10649 returns the position of the leftmost character of @var{STRING} that is
10650 in @var{SET}. If @var{BACK} equals @code{TRUE}, the rightmost position
10651 is returned. If no character of @var{SET} is found in @var{STRING}, the
10654 @item @emph{Standard}:
10655 Fortran 95 and later, with @var{KIND} argument Fortran 2003 and later
10657 @item @emph{Class}:
10660 @item @emph{Syntax}:
10661 @code{RESULT = SCAN(STRING, SET[, BACK [, KIND]])}
10663 @item @emph{Arguments}:
10664 @multitable @columnfractions .15 .70
10665 @item @var{STRING} @tab Shall be of type @code{CHARACTER}.
10666 @item @var{SET} @tab Shall be of type @code{CHARACTER}.
10667 @item @var{BACK} @tab (Optional) shall be of type @code{LOGICAL}.
10668 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
10669 expression indicating the kind parameter of the result.
10672 @item @emph{Return value}:
10673 The return value is of type @code{INTEGER} and of kind @var{KIND}. If
10674 @var{KIND} is absent, the return value is of default integer kind.
10676 @item @emph{Example}:
10679 WRITE(*,*) SCAN("FORTRAN", "AO") ! 2, found 'O'
10680 WRITE(*,*) SCAN("FORTRAN", "AO", .TRUE.) ! 6, found 'A'
10681 WRITE(*,*) SCAN("FORTRAN", "C++") ! 0, found none
10685 @item @emph{See also}:
10686 @ref{INDEX intrinsic}, @ref{VERIFY}
10692 @section @code{SECNDS} --- Time function
10694 @cindex time, elapsed
10695 @cindex elapsed time
10698 @item @emph{Description}:
10699 @code{SECNDS(X)} gets the time in seconds from the real-time system clock.
10700 @var{X} is a reference time, also in seconds. If this is zero, the time in
10701 seconds from midnight is returned. This function is non-standard and its
10702 use is discouraged.
10704 @item @emph{Standard}:
10707 @item @emph{Class}:
10710 @item @emph{Syntax}:
10711 @code{RESULT = SECNDS (X)}
10713 @item @emph{Arguments}:
10714 @multitable @columnfractions .15 .70
10715 @item @var{T} @tab Shall be of type @code{REAL(4)}.
10716 @item @var{X} @tab Shall be of type @code{REAL(4)}.
10719 @item @emph{Return value}:
10722 @item @emph{Example}:
10724 program test_secnds
10727 print *, secnds (0.0) ! seconds since midnight
10728 t1 = secnds (0.0) ! reference time
10729 do i = 1, 10000000 ! do something
10731 t2 = secnds (t1) ! elapsed time
10732 print *, "Something took ", t2, " seconds."
10733 end program test_secnds
10740 @section @code{SECOND} --- CPU time function
10742 @cindex time, elapsed
10743 @cindex elapsed time
10746 @item @emph{Description}:
10747 Returns a @code{REAL(4)} value representing the elapsed CPU time in
10748 seconds. This provides the same functionality as the standard
10749 @code{CPU_TIME} intrinsic, and is only included for backwards
10752 This intrinsic is provided in both subroutine and function forms;
10753 however, only one form can be used in any given program unit.
10755 @item @emph{Standard}:
10758 @item @emph{Class}:
10759 Subroutine, function
10761 @item @emph{Syntax}:
10762 @multitable @columnfractions .80
10763 @item @code{CALL SECOND(TIME)}
10764 @item @code{TIME = SECOND()}
10767 @item @emph{Arguments}:
10768 @multitable @columnfractions .15 .70
10769 @item @var{TIME} @tab Shall be of type @code{REAL(4)}.
10772 @item @emph{Return value}:
10773 In either syntax, @var{TIME} is set to the process's current runtime in
10776 @item @emph{See also}:
10783 @node SELECTED_CHAR_KIND
10784 @section @code{SELECTED_CHAR_KIND} --- Choose character kind
10785 @fnindex SELECTED_CHAR_KIND
10786 @cindex character kind
10787 @cindex kind, character
10790 @item @emph{Description}:
10792 @code{SELECTED_CHAR_KIND(NAME)} returns the kind value for the character
10793 set named @var{NAME}, if a character set with such a name is supported,
10794 or @math{-1} otherwise. Currently, supported character sets include
10795 ``ASCII'' and ``DEFAULT'', which are equivalent, and ``ISO_10646''
10796 (Universal Character Set, UCS-4) which is commonly known as Unicode.
10798 @item @emph{Standard}:
10799 Fortran 2003 and later
10801 @item @emph{Class}:
10802 Transformational function
10804 @item @emph{Syntax}:
10805 @code{RESULT = SELECTED_CHAR_KIND(NAME)}
10807 @item @emph{Arguments}:
10808 @multitable @columnfractions .15 .70
10809 @item @var{NAME} @tab Shall be a scalar and of the default character type.
10812 @item @emph{Example}:
10814 program character_kind
10815 use iso_fortran_env
10817 integer, parameter :: ascii = selected_char_kind ("ascii")
10818 integer, parameter :: ucs4 = selected_char_kind ('ISO_10646')
10820 character(kind=ascii, len=26) :: alphabet
10821 character(kind=ucs4, len=30) :: hello_world
10823 alphabet = ascii_"abcdefghijklmnopqrstuvwxyz"
10824 hello_world = ucs4_'Hello World and Ni Hao -- ' &
10825 // char (int (z'4F60'), ucs4) &
10826 // char (int (z'597D'), ucs4)
10828 write (*,*) alphabet
10830 open (output_unit, encoding='UTF-8')
10831 write (*,*) trim (hello_world)
10832 end program character_kind
10838 @node SELECTED_INT_KIND
10839 @section @code{SELECTED_INT_KIND} --- Choose integer kind
10840 @fnindex SELECTED_INT_KIND
10841 @cindex integer kind
10842 @cindex kind, integer
10845 @item @emph{Description}:
10846 @code{SELECTED_INT_KIND(R)} return the kind value of the smallest integer
10847 type that can represent all values ranging from @math{-10^R} (exclusive)
10848 to @math{10^R} (exclusive). If there is no integer kind that accommodates
10849 this range, @code{SELECTED_INT_KIND} returns @math{-1}.
10851 @item @emph{Standard}:
10852 Fortran 95 and later
10854 @item @emph{Class}:
10855 Transformational function
10857 @item @emph{Syntax}:
10858 @code{RESULT = SELECTED_INT_KIND(R)}
10860 @item @emph{Arguments}:
10861 @multitable @columnfractions .15 .70
10862 @item @var{R} @tab Shall be a scalar and of type @code{INTEGER}.
10865 @item @emph{Example}:
10867 program large_integers
10868 integer,parameter :: k5 = selected_int_kind(5)
10869 integer,parameter :: k15 = selected_int_kind(15)
10870 integer(kind=k5) :: i5
10871 integer(kind=k15) :: i15
10873 print *, huge(i5), huge(i15)
10875 ! The following inequalities are always true
10876 print *, huge(i5) >= 10_k5**5-1
10877 print *, huge(i15) >= 10_k15**15-1
10878 end program large_integers
10884 @node SELECTED_REAL_KIND
10885 @section @code{SELECTED_REAL_KIND} --- Choose real kind
10886 @fnindex SELECTED_REAL_KIND
10889 @cindex radix, real
10892 @item @emph{Description}:
10893 @code{SELECTED_REAL_KIND(P,R)} returns the kind value of a real data type
10894 with decimal precision of at least @code{P} digits, exponent range of
10895 at least @code{R}, and with a radix of @code{RADIX}.
10897 @item @emph{Standard}:
10898 Fortran 95 and later, with @code{RADIX} Fortran 2008 or later
10900 @item @emph{Class}:
10901 Transformational function
10903 @item @emph{Syntax}:
10904 @code{RESULT = SELECTED_REAL_KIND([P, R, RADIX])}
10906 @item @emph{Arguments}:
10907 @multitable @columnfractions .15 .70
10908 @item @var{P} @tab (Optional) shall be a scalar and of type @code{INTEGER}.
10909 @item @var{R} @tab (Optional) shall be a scalar and of type @code{INTEGER}.
10910 @item @var{RADIX} @tab (Optional) shall be a scalar and of type @code{INTEGER}.
10912 Before Fortran 2008, at least one of the arguments @var{R} or @var{P} shall
10913 be present; since Fortran 2008, they are assumed to be zero if absent.
10915 @item @emph{Return value}:
10917 @code{SELECTED_REAL_KIND} returns the value of the kind type parameter of
10918 a real data type with decimal precision of at least @code{P} digits, a
10919 decimal exponent range of at least @code{R}, and with the requested
10920 @code{RADIX}. If the @code{RADIX} parameter is absent, real kinds with
10921 any radix can be returned. If more than one real data type meet the
10922 criteria, the kind of the data type with the smallest decimal precision
10923 is returned. If no real data type matches the criteria, the result is
10925 @item -1 if the processor does not support a real data type with a
10926 precision greater than or equal to @code{P}, but the @code{R} and
10927 @code{RADIX} requirements can be fulfilled
10928 @item -2 if the processor does not support a real type with an exponent
10929 range greater than or equal to @code{R}, but @code{P} and @code{RADIX}
10931 @item -3 if @code{RADIX} but not @code{P} and @code{R} requirements
10933 @item -4 if @code{RADIX} and either @code{P} or @code{R} requirements
10935 @item -5 if there is no real type with the given @code{RADIX}
10938 @item @emph{See also}:
10939 @ref{PRECISION}, @ref{RANGE}, @ref{RADIX}
10941 @item @emph{Example}:
10944 integer,parameter :: p6 = selected_real_kind(6)
10945 integer,parameter :: p10r100 = selected_real_kind(10,100)
10946 integer,parameter :: r400 = selected_real_kind(r=400)
10948 real(kind=p10r100) :: y
10949 real(kind=r400) :: z
10951 print *, precision(x), range(x)
10952 print *, precision(y), range(y)
10953 print *, precision(z), range(z)
10954 end program real_kinds
10961 @section @code{SET_EXPONENT} --- Set the exponent of the model
10962 @fnindex SET_EXPONENT
10963 @cindex real number, set exponent
10964 @cindex floating point, set exponent
10967 @item @emph{Description}:
10968 @code{SET_EXPONENT(X, I)} returns the real number whose fractional part
10969 is that that of @var{X} and whose exponent part is @var{I}.
10971 @item @emph{Standard}:
10972 Fortran 95 and later
10974 @item @emph{Class}:
10977 @item @emph{Syntax}:
10978 @code{RESULT = SET_EXPONENT(X, I)}
10980 @item @emph{Arguments}:
10981 @multitable @columnfractions .15 .70
10982 @item @var{X} @tab Shall be of type @code{REAL}.
10983 @item @var{I} @tab Shall be of type @code{INTEGER}.
10986 @item @emph{Return value}:
10987 The return value is of the same type and kind as @var{X}.
10988 The real number whose fractional part
10989 is that that of @var{X} and whose exponent part if @var{I} is returned;
10990 it is @code{FRACTION(X) * RADIX(X)**I}.
10992 @item @emph{Example}:
10994 PROGRAM test_setexp
10995 REAL :: x = 178.1387e-4
10997 PRINT *, SET_EXPONENT(x, i), FRACTION(x) * RADIX(x)**i
11006 @section @code{SHAPE} --- Determine the shape of an array
11008 @cindex array, shape
11011 @item @emph{Description}:
11012 Determines the shape of an array.
11014 @item @emph{Standard}:
11015 Fortran 95 and later, with @var{KIND} argument Fortran 2003 and later
11017 @item @emph{Class}:
11020 @item @emph{Syntax}:
11021 @code{RESULT = SHAPE(SOURCE [, KIND])}
11023 @item @emph{Arguments}:
11024 @multitable @columnfractions .15 .70
11025 @item @var{SOURCE} @tab Shall be an array or scalar of any type.
11026 If @var{SOURCE} is a pointer it must be associated and allocatable
11027 arrays must be allocated.
11028 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
11029 expression indicating the kind parameter of the result.
11032 @item @emph{Return value}:
11033 An @code{INTEGER} array of rank one with as many elements as @var{SOURCE}
11034 has dimensions. The elements of the resulting array correspond to the extend
11035 of @var{SOURCE} along the respective dimensions. If @var{SOURCE} is a scalar,
11036 the result is the rank one array of size zero. If @var{KIND} is absent, the
11037 return value has the default integer kind otherwise the specified kind.
11039 @item @emph{Example}:
11042 INTEGER, DIMENSION(-1:1, -1:2) :: A
11043 WRITE(*,*) SHAPE(A) ! (/ 3, 4 /)
11044 WRITE(*,*) SIZE(SHAPE(42)) ! (/ /)
11048 @item @emph{See also}:
11049 @ref{RESHAPE}, @ref{SIZE}
11055 @section @code{SHIFTA} --- Right shift with fill
11057 @cindex bits, shift right
11058 @cindex shift, right with fill
11061 @item @emph{Description}:
11062 @code{SHIFTA} returns a value corresponding to @var{I} with all of the
11063 bits shifted right by @var{SHIFT} places. If the absolute value of
11064 @var{SHIFT} is greater than @code{BIT_SIZE(I)}, the value is undefined.
11065 Bits shifted out from the right end are lost. The fill is arithmetic: the
11066 bits shifted in from the left end are equal to the leftmost bit, which in
11067 two's complement representation is the sign bit.
11069 @item @emph{Standard}:
11070 Fortran 2008 and later
11072 @item @emph{Class}:
11075 @item @emph{Syntax}:
11076 @code{RESULT = SHIFTA(I, SHIFT)}
11078 @item @emph{Arguments}:
11079 @multitable @columnfractions .15 .70
11080 @item @var{I} @tab The type shall be @code{INTEGER}.
11081 @item @var{SHIFT} @tab The type shall be @code{INTEGER}.
11084 @item @emph{Return value}:
11085 The return value is of type @code{INTEGER} and of the same kind as
11088 @item @emph{See also}:
11089 @ref{SHIFTL}, @ref{SHIFTR}
11095 @section @code{SHIFTL} --- Left shift
11097 @cindex bits, shift left
11098 @cindex shift, left
11101 @item @emph{Description}:
11102 @code{SHIFTL} returns a value corresponding to @var{I} with all of the
11103 bits shifted left by @var{SHIFT} places. If the absolute value of
11104 @var{SHIFT} is greater than @code{BIT_SIZE(I)}, the value is undefined.
11105 Bits shifted out from the left end are lost, and bits shifted in from
11106 the right end are set to 0.
11108 @item @emph{Standard}:
11109 Fortran 2008 and later
11111 @item @emph{Class}:
11114 @item @emph{Syntax}:
11115 @code{RESULT = SHIFTL(I, SHIFT)}
11117 @item @emph{Arguments}:
11118 @multitable @columnfractions .15 .70
11119 @item @var{I} @tab The type shall be @code{INTEGER}.
11120 @item @var{SHIFT} @tab The type shall be @code{INTEGER}.
11123 @item @emph{Return value}:
11124 The return value is of type @code{INTEGER} and of the same kind as
11127 @item @emph{See also}:
11128 @ref{SHIFTA}, @ref{SHIFTR}
11134 @section @code{SHIFTR} --- Right shift
11136 @cindex bits, shift right
11137 @cindex shift, right
11140 @item @emph{Description}:
11141 @code{SHIFTR} returns a value corresponding to @var{I} with all of the
11142 bits shifted right by @var{SHIFT} places. If the absolute value of
11143 @var{SHIFT} is greater than @code{BIT_SIZE(I)}, the value is undefined.
11144 Bits shifted out from the right end are lost, and bits shifted in from
11145 the left end are set to 0.
11147 @item @emph{Standard}:
11148 Fortran 2008 and later
11150 @item @emph{Class}:
11153 @item @emph{Syntax}:
11154 @code{RESULT = SHIFTR(I, SHIFT)}
11156 @item @emph{Arguments}:
11157 @multitable @columnfractions .15 .70
11158 @item @var{I} @tab The type shall be @code{INTEGER}.
11159 @item @var{SHIFT} @tab The type shall be @code{INTEGER}.
11162 @item @emph{Return value}:
11163 The return value is of type @code{INTEGER} and of the same kind as
11166 @item @emph{See also}:
11167 @ref{SHIFTA}, @ref{SHIFTL}
11173 @section @code{SIGN} --- Sign copying function
11177 @cindex sign copying
11180 @item @emph{Description}:
11181 @code{SIGN(A,B)} returns the value of @var{A} with the sign of @var{B}.
11183 @item @emph{Standard}:
11184 Fortran 77 and later
11186 @item @emph{Class}:
11189 @item @emph{Syntax}:
11190 @code{RESULT = SIGN(A, B)}
11192 @item @emph{Arguments}:
11193 @multitable @columnfractions .15 .70
11194 @item @var{A} @tab Shall be of type @code{INTEGER} or @code{REAL}
11195 @item @var{B} @tab Shall be of the same type and kind as @var{A}
11198 @item @emph{Return value}:
11199 The kind of the return value is that of @var{A} and @var{B}.
11200 If @math{B\ge 0} then the result is @code{ABS(A)}, else
11201 it is @code{-ABS(A)}.
11203 @item @emph{Example}:
11206 print *, sign(-12,1)
11207 print *, sign(-12,0)
11208 print *, sign(-12,-1)
11210 print *, sign(-12.,1.)
11211 print *, sign(-12.,0.)
11212 print *, sign(-12.,-1.)
11213 end program test_sign
11216 @item @emph{Specific names}:
11217 @multitable @columnfractions .20 .20 .20 .25
11218 @item Name @tab Arguments @tab Return type @tab Standard
11219 @item @code{SIGN(A,B)} @tab @code{REAL(4) A, B} @tab @code{REAL(4)} @tab f77, gnu
11220 @item @code{ISIGN(A,B)} @tab @code{INTEGER(4) A, B} @tab @code{INTEGER(4)} @tab f77, gnu
11221 @item @code{DSIGN(A,B)} @tab @code{REAL(8) A, B} @tab @code{REAL(8)} @tab f77, gnu
11228 @section @code{SIGNAL} --- Signal handling subroutine (or function)
11230 @cindex system, signal handling
11233 @item @emph{Description}:
11234 @code{SIGNAL(NUMBER, HANDLER [, STATUS])} causes external subroutine
11235 @var{HANDLER} to be executed with a single integer argument when signal
11236 @var{NUMBER} occurs. If @var{HANDLER} is an integer, it can be used to
11237 turn off handling of signal @var{NUMBER} or revert to its default
11238 action. See @code{signal(2)}.
11240 If @code{SIGNAL} is called as a subroutine and the @var{STATUS} argument
11241 is supplied, it is set to the value returned by @code{signal(2)}.
11243 @item @emph{Standard}:
11246 @item @emph{Class}:
11247 Subroutine, function
11249 @item @emph{Syntax}:
11250 @multitable @columnfractions .80
11251 @item @code{CALL SIGNAL(NUMBER, HANDLER [, STATUS])}
11252 @item @code{STATUS = SIGNAL(NUMBER, HANDLER)}
11255 @item @emph{Arguments}:
11256 @multitable @columnfractions .15 .70
11257 @item @var{NUMBER} @tab Shall be a scalar integer, with @code{INTENT(IN)}
11258 @item @var{HANDLER}@tab Signal handler (@code{INTEGER FUNCTION} or
11259 @code{SUBROUTINE}) or dummy/global @code{INTEGER} scalar.
11260 @code{INTEGER}. It is @code{INTENT(IN)}.
11261 @item @var{STATUS} @tab (Optional) @var{STATUS} shall be a scalar
11262 integer. It has @code{INTENT(OUT)}.
11264 @c TODO: What should the interface of the handler be? Does it take arguments?
11266 @item @emph{Return value}:
11267 The @code{SIGNAL} function returns the value returned by @code{signal(2)}.
11269 @item @emph{Example}:
11271 program test_signal
11273 external handler_print
11275 call signal (12, handler_print)
11276 call signal (10, 1)
11279 end program test_signal
11286 @section @code{SIN} --- Sine function
11292 @cindex trigonometric function, sine
11296 @item @emph{Description}:
11297 @code{SIN(X)} computes the sine of @var{X}.
11299 @item @emph{Standard}:
11300 Fortran 77 and later
11302 @item @emph{Class}:
11305 @item @emph{Syntax}:
11306 @code{RESULT = SIN(X)}
11308 @item @emph{Arguments}:
11309 @multitable @columnfractions .15 .70
11310 @item @var{X} @tab The type shall be @code{REAL} or
11314 @item @emph{Return value}:
11315 The return value has same type and kind as @var{X}.
11317 @item @emph{Example}:
11322 end program test_sin
11325 @item @emph{Specific names}:
11326 @multitable @columnfractions .20 .20 .20 .25
11327 @item Name @tab Argument @tab Return type @tab Standard
11328 @item @code{SIN(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab f77, gnu
11329 @item @code{DSIN(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab f95, gnu
11330 @item @code{CSIN(X)} @tab @code{COMPLEX(4) X} @tab @code{COMPLEX(4)} @tab f95, gnu
11331 @item @code{ZSIN(X)} @tab @code{COMPLEX(8) X} @tab @code{COMPLEX(8)} @tab f95, gnu
11332 @item @code{CDSIN(X)} @tab @code{COMPLEX(8) X} @tab @code{COMPLEX(8)} @tab f95, gnu
11335 @item @emph{See also}:
11342 @section @code{SINH} --- Hyperbolic sine function
11345 @cindex hyperbolic sine
11346 @cindex hyperbolic function, sine
11347 @cindex sine, hyperbolic
11350 @item @emph{Description}:
11351 @code{SINH(X)} computes the hyperbolic sine of @var{X}.
11353 @item @emph{Standard}:
11354 Fortran 95 and later, for a complex argument Fortran 2008 or later
11356 @item @emph{Class}:
11359 @item @emph{Syntax}:
11360 @code{RESULT = SINH(X)}
11362 @item @emph{Arguments}:
11363 @multitable @columnfractions .15 .70
11364 @item @var{X} @tab The type shall be @code{REAL} or @code{COMPLEX}.
11367 @item @emph{Return value}:
11368 The return value has same type and kind as @var{X}.
11370 @item @emph{Example}:
11373 real(8) :: x = - 1.0_8
11375 end program test_sinh
11378 @item @emph{Specific names}:
11379 @multitable @columnfractions .20 .20 .20 .25
11380 @item Name @tab Argument @tab Return type @tab Standard
11381 @item @code{SINH(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab Fortran 95 and later
11382 @item @code{DSINH(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab Fortran 95 and later
11385 @item @emph{See also}:
11392 @section @code{SIZE} --- Determine the size of an array
11394 @cindex array, size
11395 @cindex array, number of elements
11396 @cindex array, count elements
11399 @item @emph{Description}:
11400 Determine the extent of @var{ARRAY} along a specified dimension @var{DIM},
11401 or the total number of elements in @var{ARRAY} if @var{DIM} is absent.
11403 @item @emph{Standard}:
11404 Fortran 95 and later, with @var{KIND} argument Fortran 2003 and later
11406 @item @emph{Class}:
11409 @item @emph{Syntax}:
11410 @code{RESULT = SIZE(ARRAY[, DIM [, KIND]])}
11412 @item @emph{Arguments}:
11413 @multitable @columnfractions .15 .70
11414 @item @var{ARRAY} @tab Shall be an array of any type. If @var{ARRAY} is
11415 a pointer it must be associated and allocatable arrays must be allocated.
11416 @item @var{DIM} @tab (Optional) shall be a scalar of type @code{INTEGER}
11417 and its value shall be in the range from 1 to n, where n equals the rank
11419 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
11420 expression indicating the kind parameter of the result.
11423 @item @emph{Return value}:
11424 The return value is of type @code{INTEGER} and of kind @var{KIND}. If
11425 @var{KIND} is absent, the return value is of default integer kind.
11427 @item @emph{Example}:
11430 WRITE(*,*) SIZE((/ 1, 2 /)) ! 2
11434 @item @emph{See also}:
11435 @ref{SHAPE}, @ref{RESHAPE}
11440 @section @code{SIZEOF} --- Size in bytes of an expression
11442 @cindex expression size
11443 @cindex size of an expression
11446 @item @emph{Description}:
11447 @code{SIZEOF(X)} calculates the number of bytes of storage the
11448 expression @code{X} occupies.
11450 @item @emph{Standard}:
11453 @item @emph{Class}:
11456 @item @emph{Syntax}:
11457 @code{N = SIZEOF(X)}
11459 @item @emph{Arguments}:
11460 @multitable @columnfractions .15 .70
11461 @item @var{X} @tab The argument shall be of any type, rank or shape.
11464 @item @emph{Return value}:
11465 The return value is of type integer and of the system-dependent kind
11466 @var{C_SIZE_T} (from the @var{ISO_C_BINDING} module). Its value is the
11467 number of bytes occupied by the argument. If the argument has the
11468 @code{POINTER} attribute, the number of bytes of the storage area pointed
11469 to is returned. If the argument is of a derived type with @code{POINTER}
11470 or @code{ALLOCATABLE} components, the return value doesn't account for
11471 the sizes of the data pointed to by these components. If the argument is
11472 polymorphic, the size according to the declared type is returned. The argument
11473 may not be a procedure or procedure pointer.
11475 @item @emph{Example}:
11479 print *, (sizeof(s)/sizeof(r) == 5)
11482 The example will print @code{.TRUE.} unless you are using a platform
11483 where default @code{REAL} variables are unusually padded.
11485 @item @emph{See also}:
11486 @ref{C_SIZEOF}, @ref{STORAGE_SIZE}
11491 @section @code{SLEEP} --- Sleep for the specified number of seconds
11493 @cindex delayed execution
11496 @item @emph{Description}:
11497 Calling this subroutine causes the process to pause for @var{SECONDS} seconds.
11499 @item @emph{Standard}:
11502 @item @emph{Class}:
11505 @item @emph{Syntax}:
11506 @code{CALL SLEEP(SECONDS)}
11508 @item @emph{Arguments}:
11509 @multitable @columnfractions .15 .70
11510 @item @var{SECONDS} @tab The type shall be of default @code{INTEGER}.
11513 @item @emph{Example}:
11524 @section @code{SPACING} --- Smallest distance between two numbers of a given type
11526 @cindex real number, relative spacing
11527 @cindex floating point, relative spacing
11530 @item @emph{Description}:
11531 Determines the distance between the argument @var{X} and the nearest
11532 adjacent number of the same type.
11534 @item @emph{Standard}:
11535 Fortran 95 and later
11537 @item @emph{Class}:
11540 @item @emph{Syntax}:
11541 @code{RESULT = SPACING(X)}
11543 @item @emph{Arguments}:
11544 @multitable @columnfractions .15 .70
11545 @item @var{X} @tab Shall be of type @code{REAL}.
11548 @item @emph{Return value}:
11549 The result is of the same type as the input argument @var{X}.
11551 @item @emph{Example}:
11553 PROGRAM test_spacing
11554 INTEGER, PARAMETER :: SGL = SELECTED_REAL_KIND(p=6, r=37)
11555 INTEGER, PARAMETER :: DBL = SELECTED_REAL_KIND(p=13, r=200)
11557 WRITE(*,*) spacing(1.0_SGL) ! "1.1920929E-07" on i686
11558 WRITE(*,*) spacing(1.0_DBL) ! "2.220446049250313E-016" on i686
11562 @item @emph{See also}:
11569 @section @code{SPREAD} --- Add a dimension to an array
11571 @cindex array, increase dimension
11572 @cindex array, duplicate elements
11573 @cindex array, duplicate dimensions
11576 @item @emph{Description}:
11577 Replicates a @var{SOURCE} array @var{NCOPIES} times along a specified
11578 dimension @var{DIM}.
11580 @item @emph{Standard}:
11581 Fortran 95 and later
11583 @item @emph{Class}:
11584 Transformational function
11586 @item @emph{Syntax}:
11587 @code{RESULT = SPREAD(SOURCE, DIM, NCOPIES)}
11589 @item @emph{Arguments}:
11590 @multitable @columnfractions .15 .70
11591 @item @var{SOURCE} @tab Shall be a scalar or an array of any type and
11592 a rank less than seven.
11593 @item @var{DIM} @tab Shall be a scalar of type @code{INTEGER} with a
11594 value in the range from 1 to n+1, where n equals the rank of @var{SOURCE}.
11595 @item @var{NCOPIES} @tab Shall be a scalar of type @code{INTEGER}.
11598 @item @emph{Return value}:
11599 The result is an array of the same type as @var{SOURCE} and has rank n+1
11600 where n equals the rank of @var{SOURCE}.
11602 @item @emph{Example}:
11604 PROGRAM test_spread
11605 INTEGER :: a = 1, b(2) = (/ 1, 2 /)
11606 WRITE(*,*) SPREAD(A, 1, 2) ! "1 1"
11607 WRITE(*,*) SPREAD(B, 1, 2) ! "1 1 2 2"
11611 @item @emph{See also}:
11618 @section @code{SQRT} --- Square-root function
11625 @cindex square-root
11628 @item @emph{Description}:
11629 @code{SQRT(X)} computes the square root of @var{X}.
11631 @item @emph{Standard}:
11632 Fortran 77 and later
11634 @item @emph{Class}:
11637 @item @emph{Syntax}:
11638 @code{RESULT = SQRT(X)}
11640 @item @emph{Arguments}:
11641 @multitable @columnfractions .15 .70
11642 @item @var{X} @tab The type shall be @code{REAL} or
11646 @item @emph{Return value}:
11647 The return value is of type @code{REAL} or @code{COMPLEX}.
11648 The kind type parameter is the same as @var{X}.
11650 @item @emph{Example}:
11653 real(8) :: x = 2.0_8
11654 complex :: z = (1.0, 2.0)
11657 end program test_sqrt
11660 @item @emph{Specific names}:
11661 @multitable @columnfractions .20 .20 .20 .25
11662 @item Name @tab Argument @tab Return type @tab Standard
11663 @item @code{SQRT(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab Fortran 95 and later
11664 @item @code{DSQRT(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab Fortran 95 and later
11665 @item @code{CSQRT(X)} @tab @code{COMPLEX(4) X} @tab @code{COMPLEX(4)} @tab Fortran 95 and later
11666 @item @code{ZSQRT(X)} @tab @code{COMPLEX(8) X} @tab @code{COMPLEX(8)} @tab GNU extension
11667 @item @code{CDSQRT(X)} @tab @code{COMPLEX(8) X} @tab @code{COMPLEX(8)} @tab GNU extension
11674 @section @code{SRAND} --- Reinitialize the random number generator
11676 @cindex random number generation, seeding
11677 @cindex seeding a random number generator
11680 @item @emph{Description}:
11681 @code{SRAND} reinitializes the pseudo-random number generator
11682 called by @code{RAND} and @code{IRAND}. The new seed used by the
11683 generator is specified by the required argument @var{SEED}.
11685 @item @emph{Standard}:
11688 @item @emph{Class}:
11691 @item @emph{Syntax}:
11692 @code{CALL SRAND(SEED)}
11694 @item @emph{Arguments}:
11695 @multitable @columnfractions .15 .70
11696 @item @var{SEED} @tab Shall be a scalar @code{INTEGER(kind=4)}.
11699 @item @emph{Return value}:
11700 Does not return anything.
11702 @item @emph{Example}:
11703 See @code{RAND} and @code{IRAND} for examples.
11705 @item @emph{Notes}:
11706 The Fortran 2003 standard specifies the intrinsic @code{RANDOM_SEED} to
11707 initialize the pseudo-random numbers generator and @code{RANDOM_NUMBER}
11708 to generate pseudo-random numbers. Please note that in
11709 GNU Fortran, these two sets of intrinsics (@code{RAND},
11710 @code{IRAND} and @code{SRAND} on the one hand, @code{RANDOM_NUMBER} and
11711 @code{RANDOM_SEED} on the other hand) access two independent
11712 pseudo-random number generators.
11714 @item @emph{See also}:
11715 @ref{RAND}, @ref{RANDOM_SEED}, @ref{RANDOM_NUMBER}
11722 @section @code{STAT} --- Get file status
11724 @cindex file system, file status
11727 @item @emph{Description}:
11728 This function returns information about a file. No permissions are required on
11729 the file itself, but execute (search) permission is required on all of the
11730 directories in path that lead to the file.
11732 The elements that are obtained and stored in the array @code{VALUES}:
11733 @multitable @columnfractions .15 .70
11734 @item @code{VALUES(1)} @tab Device ID
11735 @item @code{VALUES(2)} @tab Inode number
11736 @item @code{VALUES(3)} @tab File mode
11737 @item @code{VALUES(4)} @tab Number of links
11738 @item @code{VALUES(5)} @tab Owner's uid
11739 @item @code{VALUES(6)} @tab Owner's gid
11740 @item @code{VALUES(7)} @tab ID of device containing directory entry for file (0 if not available)
11741 @item @code{VALUES(8)} @tab File size (bytes)
11742 @item @code{VALUES(9)} @tab Last access time
11743 @item @code{VALUES(10)} @tab Last modification time
11744 @item @code{VALUES(11)} @tab Last file status change time
11745 @item @code{VALUES(12)} @tab Preferred I/O block size (-1 if not available)
11746 @item @code{VALUES(13)} @tab Number of blocks allocated (-1 if not available)
11749 Not all these elements are relevant on all systems.
11750 If an element is not relevant, it is returned as 0.
11752 This intrinsic is provided in both subroutine and function forms; however,
11753 only one form can be used in any given program unit.
11755 @item @emph{Standard}:
11758 @item @emph{Class}:
11759 Subroutine, function
11761 @item @emph{Syntax}:
11762 @multitable @columnfractions .80
11763 @item @code{CALL STAT(NAME, VALUES [, STATUS])}
11764 @item @code{STATUS = STAT(NAME, VALUES)}
11767 @item @emph{Arguments}:
11768 @multitable @columnfractions .15 .70
11769 @item @var{NAME} @tab The type shall be @code{CHARACTER}, of the
11770 default kind and a valid path within the file system.
11771 @item @var{VALUES} @tab The type shall be @code{INTEGER(4), DIMENSION(13)}.
11772 @item @var{STATUS} @tab (Optional) status flag of type @code{INTEGER(4)}. Returns 0
11773 on success and a system specific error code otherwise.
11776 @item @emph{Example}:
11779 INTEGER, DIMENSION(13) :: buff
11782 CALL STAT("/etc/passwd", buff, status)
11784 IF (status == 0) THEN
11785 WRITE (*, FMT="('Device ID:', T30, I19)") buff(1)
11786 WRITE (*, FMT="('Inode number:', T30, I19)") buff(2)
11787 WRITE (*, FMT="('File mode (octal):', T30, O19)") buff(3)
11788 WRITE (*, FMT="('Number of links:', T30, I19)") buff(4)
11789 WRITE (*, FMT="('Owner''s uid:', T30, I19)") buff(5)
11790 WRITE (*, FMT="('Owner''s gid:', T30, I19)") buff(6)
11791 WRITE (*, FMT="('Device where located:', T30, I19)") buff(7)
11792 WRITE (*, FMT="('File size:', T30, I19)") buff(8)
11793 WRITE (*, FMT="('Last access time:', T30, A19)") CTIME(buff(9))
11794 WRITE (*, FMT="('Last modification time', T30, A19)") CTIME(buff(10))
11795 WRITE (*, FMT="('Last status change time:', T30, A19)") CTIME(buff(11))
11796 WRITE (*, FMT="('Preferred block size:', T30, I19)") buff(12)
11797 WRITE (*, FMT="('No. of blocks allocated:', T30, I19)") buff(13)
11802 @item @emph{See also}:
11803 To stat an open file: @ref{FSTAT}, to stat a link: @ref{LSTAT}
11809 @section @code{STORAGE_SIZE} --- Storage size in bits
11810 @fnindex STORAGE_SIZE
11811 @cindex storage size
11814 @item @emph{Description}:
11815 Returns the storage size of argument @var{A} in bits.
11816 @item @emph{Standard}:
11817 Fortran 2008 and later
11818 @item @emph{Class}:
11820 @item @emph{Syntax}:
11821 @code{RESULT = STORAGE_SIZE(A [, KIND])}
11823 @item @emph{Arguments}:
11824 @multitable @columnfractions .15 .70
11825 @item @var{A} @tab Shall be a scalar or array of any type.
11826 @item @var{KIND} @tab (Optional) shall be a scalar integer constant expression.
11829 @item @emph{Return Value}:
11830 The result is a scalar integer with the kind type parameter specified by KIND
11831 (or default integer type if KIND is missing). The result value is the size
11832 expressed in bits for an element of an array that has the dynamic type and type
11835 @item @emph{See also}:
11836 @ref{C_SIZEOF}, @ref{SIZEOF}
11842 @section @code{SUM} --- Sum of array elements
11845 @cindex array, add elements
11846 @cindex array, conditionally add elements
11847 @cindex sum array elements
11850 @item @emph{Description}:
11851 Adds the elements of @var{ARRAY} along dimension @var{DIM} if
11852 the corresponding element in @var{MASK} is @code{TRUE}.
11854 @item @emph{Standard}:
11855 Fortran 95 and later
11857 @item @emph{Class}:
11858 Transformational function
11860 @item @emph{Syntax}:
11861 @multitable @columnfractions .80
11862 @item @code{RESULT = SUM(ARRAY[, MASK])}
11863 @item @code{RESULT = SUM(ARRAY, DIM[, MASK])}
11866 @item @emph{Arguments}:
11867 @multitable @columnfractions .15 .70
11868 @item @var{ARRAY} @tab Shall be an array of type @code{INTEGER},
11869 @code{REAL} or @code{COMPLEX}.
11870 @item @var{DIM} @tab (Optional) shall be a scalar of type
11871 @code{INTEGER} with a value in the range from 1 to n, where n
11872 equals the rank of @var{ARRAY}.
11873 @item @var{MASK} @tab (Optional) shall be of type @code{LOGICAL}
11874 and either be a scalar or an array of the same shape as @var{ARRAY}.
11877 @item @emph{Return value}:
11878 The result is of the same type as @var{ARRAY}.
11880 If @var{DIM} is absent, a scalar with the sum of all elements in @var{ARRAY}
11881 is returned. Otherwise, an array of rank n-1, where n equals the rank of
11882 @var{ARRAY}, and a shape similar to that of @var{ARRAY} with dimension @var{DIM}
11883 dropped is returned.
11885 @item @emph{Example}:
11888 INTEGER :: x(5) = (/ 1, 2, 3, 4 ,5 /)
11889 print *, SUM(x) ! all elements, sum = 15
11890 print *, SUM(x, MASK=MOD(x, 2)==1) ! odd elements, sum = 9
11894 @item @emph{See also}:
11901 @section @code{SYMLNK} --- Create a symbolic link
11903 @cindex file system, create link
11904 @cindex file system, soft link
11907 @item @emph{Description}:
11908 Makes a symbolic link from file @var{PATH1} to @var{PATH2}. A null
11909 character (@code{CHAR(0)}) can be used to mark the end of the names in
11910 @var{PATH1} and @var{PATH2}; otherwise, trailing blanks in the file
11911 names are ignored. If the @var{STATUS} argument is supplied, it
11912 contains 0 on success or a nonzero error code upon return; see
11913 @code{symlink(2)}. If the system does not supply @code{symlink(2)},
11914 @code{ENOSYS} is returned.
11916 This intrinsic is provided in both subroutine and function forms;
11917 however, only one form can be used in any given program unit.
11919 @item @emph{Standard}:
11922 @item @emph{Class}:
11923 Subroutine, function
11925 @item @emph{Syntax}:
11926 @multitable @columnfractions .80
11927 @item @code{CALL SYMLNK(PATH1, PATH2 [, STATUS])}
11928 @item @code{STATUS = SYMLNK(PATH1, PATH2)}
11931 @item @emph{Arguments}:
11932 @multitable @columnfractions .15 .70
11933 @item @var{PATH1} @tab Shall be of default @code{CHARACTER} type.
11934 @item @var{PATH2} @tab Shall be of default @code{CHARACTER} type.
11935 @item @var{STATUS} @tab (Optional) Shall be of default @code{INTEGER} type.
11938 @item @emph{See also}:
11939 @ref{LINK}, @ref{UNLINK}
11946 @section @code{SYSTEM} --- Execute a shell command
11948 @cindex system, system call
11951 @item @emph{Description}:
11952 Passes the command @var{COMMAND} to a shell (see @code{system(3)}). If
11953 argument @var{STATUS} is present, it contains the value returned by
11954 @code{system(3)}, which is presumably 0 if the shell command succeeded.
11955 Note that which shell is used to invoke the command is system-dependent
11956 and environment-dependent.
11958 This intrinsic is provided in both subroutine and function forms;
11959 however, only one form can be used in any given program unit.
11961 Note that the @code{system} function need not be thread-safe. It is
11962 the responsibility of the user to ensure that @code{system} is not
11963 called concurrently.
11965 @item @emph{Standard}:
11968 @item @emph{Class}:
11969 Subroutine, function
11971 @item @emph{Syntax}:
11972 @multitable @columnfractions .80
11973 @item @code{CALL SYSTEM(COMMAND [, STATUS])}
11974 @item @code{STATUS = SYSTEM(COMMAND)}
11977 @item @emph{Arguments}:
11978 @multitable @columnfractions .15 .70
11979 @item @var{COMMAND} @tab Shall be of default @code{CHARACTER} type.
11980 @item @var{STATUS} @tab (Optional) Shall be of default @code{INTEGER} type.
11983 @item @emph{See also}:
11984 @ref{EXECUTE_COMMAND_LINE}, which is part of the Fortran 2008 standard
11985 and should considered in new code for future portability.
11991 @section @code{SYSTEM_CLOCK} --- Time function
11992 @fnindex SYSTEM_CLOCK
11993 @cindex time, clock ticks
11994 @cindex clock ticks
11997 @item @emph{Description}:
11998 Determines the @var{COUNT} of a processor clock since an unspecified
11999 time in the past modulo @var{COUNT_MAX}, @var{COUNT_RATE} determines
12000 the number of clock ticks per second. If the platform supports a high
12001 resolution monotonic clock, that clock is used and can provide up to
12002 nanosecond resolution. If a high resolution monotonic clock is not
12003 available, the implementation falls back to a potentially lower
12004 resolution realtime clock.
12006 @var{COUNT_RATE} and @var{COUNT_MAX} vary depending on the kind of the
12007 arguments. For @var{kind=8} arguments, @var{COUNT} represents
12008 nanoseconds, and for @var{kind=4} arguments, @var{COUNT} represents
12009 milliseconds. Other than the kind dependency, @var{COUNT_RATE} and
12010 @var{COUNT_MAX} are constant, however the particular values are
12011 specific to @command{gfortran}.
12013 If there is no clock, @var{COUNT} is set to @code{-HUGE(COUNT)}, and
12014 @var{COUNT_RATE} and @var{COUNT_MAX} are set to zero.
12016 When running on a platform using the GNU C library (glibc), or a
12017 derivative thereof, the high resolution monotonic clock is available
12018 only when linking with the @var{rt} library. This can be done
12019 explicitly by adding the @code{-lrt} flag when linking the
12020 application, but is also done implicitly when using OpenMP.
12022 @item @emph{Standard}:
12023 Fortran 95 and later
12025 @item @emph{Class}:
12028 @item @emph{Syntax}:
12029 @code{CALL SYSTEM_CLOCK([COUNT, COUNT_RATE, COUNT_MAX])}
12031 @item @emph{Arguments}:
12032 @multitable @columnfractions .15 .70
12033 @item @var{COUNT} @tab (Optional) shall be a scalar of type
12034 @code{INTEGER} with @code{INTENT(OUT)}.
12035 @item @var{COUNT_RATE} @tab (Optional) shall be a scalar of type
12036 @code{INTEGER} with @code{INTENT(OUT)}.
12037 @item @var{COUNT_MAX} @tab (Optional) shall be a scalar of type
12038 @code{INTEGER} with @code{INTENT(OUT)}.
12041 @item @emph{Example}:
12043 PROGRAM test_system_clock
12044 INTEGER :: count, count_rate, count_max
12045 CALL SYSTEM_CLOCK(count, count_rate, count_max)
12046 WRITE(*,*) count, count_rate, count_max
12050 @item @emph{See also}:
12051 @ref{DATE_AND_TIME}, @ref{CPU_TIME}
12057 @section @code{TAN} --- Tangent function
12060 @cindex trigonometric function, tangent
12064 @item @emph{Description}:
12065 @code{TAN(X)} computes the tangent of @var{X}.
12067 @item @emph{Standard}:
12068 Fortran 77 and later, for a complex argument Fortran 2008 or later
12070 @item @emph{Class}:
12073 @item @emph{Syntax}:
12074 @code{RESULT = TAN(X)}
12076 @item @emph{Arguments}:
12077 @multitable @columnfractions .15 .70
12078 @item @var{X} @tab The type shall be @code{REAL} or @code{COMPLEX}.
12081 @item @emph{Return value}:
12082 The return value has same type and kind as @var{X}.
12084 @item @emph{Example}:
12087 real(8) :: x = 0.165_8
12089 end program test_tan
12092 @item @emph{Specific names}:
12093 @multitable @columnfractions .20 .20 .20 .25
12094 @item Name @tab Argument @tab Return type @tab Standard
12095 @item @code{TAN(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab Fortran 95 and later
12096 @item @code{DTAN(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab Fortran 95 and later
12099 @item @emph{See also}:
12106 @section @code{TANH} --- Hyperbolic tangent function
12109 @cindex hyperbolic tangent
12110 @cindex hyperbolic function, tangent
12111 @cindex tangent, hyperbolic
12114 @item @emph{Description}:
12115 @code{TANH(X)} computes the hyperbolic tangent of @var{X}.
12117 @item @emph{Standard}:
12118 Fortran 77 and later, for a complex argument Fortran 2008 or later
12120 @item @emph{Class}:
12123 @item @emph{Syntax}:
12126 @item @emph{Arguments}:
12127 @multitable @columnfractions .15 .70
12128 @item @var{X} @tab The type shall be @code{REAL} or @code{COMPLEX}.
12131 @item @emph{Return value}:
12132 The return value has same type and kind as @var{X}. If @var{X} is
12133 complex, the imaginary part of the result is in radians. If @var{X}
12134 is @code{REAL}, the return value lies in the range
12135 @math{ - 1 \leq tanh(x) \leq 1 }.
12137 @item @emph{Example}:
12140 real(8) :: x = 2.1_8
12142 end program test_tanh
12145 @item @emph{Specific names}:
12146 @multitable @columnfractions .20 .20 .20 .25
12147 @item Name @tab Argument @tab Return type @tab Standard
12148 @item @code{TANH(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab Fortran 95 and later
12149 @item @code{DTANH(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab Fortran 95 and later
12152 @item @emph{See also}:
12159 @section @code{THIS_IMAGE} --- Function that returns the cosubscript index of this image
12160 @fnindex THIS_IMAGE
12161 @cindex coarray, @code{THIS_IMAGE}
12162 @cindex images, index of this image
12165 @item @emph{Description}:
12166 Returns the cosubscript for this image.
12168 @item @emph{Standard}:
12169 Fortran 2008 and later
12171 @item @emph{Class}:
12172 Transformational function
12174 @item @emph{Syntax}:
12175 @multitable @columnfractions .80
12176 @item @code{RESULT = THIS_IMAGE()}
12177 @item @code{RESULT = THIS_IMAGE(COARRAY [, DIM])}
12180 @item @emph{Arguments}:
12181 @multitable @columnfractions .15 .70
12182 @item @var{COARRAY} @tab Coarray of any type (optional; if @var{DIM}
12183 present, required).
12184 @item @var{DIM} @tab default integer scalar (optional). If present,
12185 @var{DIM} shall be between one and the corank of @var{COARRAY}.
12189 @item @emph{Return value}:
12190 Default integer. If @var{COARRAY} is not present, it is scalar and its value
12191 is the index of the invoking image. Otherwise, if @var{DIM} is not present,
12192 a rank-1 array with corank elements is returned, containing the cosubscripts
12193 for @var{COARRAY} specifying the invoking image. If @var{DIM} is present,
12194 a scalar is returned, with the value of the @var{DIM} element of
12195 @code{THIS_IMAGE(COARRAY)}.
12197 @item @emph{Example}:
12199 INTEGER :: value[*]
12201 value = THIS_IMAGE()
12203 IF (THIS_IMAGE() == 1) THEN
12204 DO i = 1, NUM_IMAGES()
12205 WRITE(*,'(2(a,i0))') 'value[', i, '] is ', value[i]
12210 @item @emph{See also}:
12211 @ref{NUM_IMAGES}, @ref{IMAGE_INDEX}
12217 @section @code{TIME} --- Time function
12219 @cindex time, current
12220 @cindex current time
12223 @item @emph{Description}:
12224 Returns the current time encoded as an integer (in the manner of the
12225 UNIX function @code{time(3)}). This value is suitable for passing to
12226 @code{CTIME}, @code{GMTIME}, and @code{LTIME}.
12228 This intrinsic is not fully portable, such as to systems with 32-bit
12229 @code{INTEGER} types but supporting times wider than 32 bits. Therefore,
12230 the values returned by this intrinsic might be, or become, negative, or
12231 numerically less than previous values, during a single run of the
12234 See @ref{TIME8}, for information on a similar intrinsic that might be
12235 portable to more GNU Fortran implementations, though to fewer Fortran
12238 @item @emph{Standard}:
12241 @item @emph{Class}:
12244 @item @emph{Syntax}:
12245 @code{RESULT = TIME()}
12247 @item @emph{Return value}:
12248 The return value is a scalar of type @code{INTEGER(4)}.
12250 @item @emph{See also}:
12251 @ref{CTIME}, @ref{GMTIME}, @ref{LTIME}, @ref{MCLOCK}, @ref{TIME8}
12258 @section @code{TIME8} --- Time function (64-bit)
12260 @cindex time, current
12261 @cindex current time
12264 @item @emph{Description}:
12265 Returns the current time encoded as an integer (in the manner of the
12266 UNIX function @code{time(3)}). This value is suitable for passing to
12267 @code{CTIME}, @code{GMTIME}, and @code{LTIME}.
12269 @emph{Warning:} this intrinsic does not increase the range of the timing
12270 values over that returned by @code{time(3)}. On a system with a 32-bit
12271 @code{time(3)}, @code{TIME8} will return a 32-bit value, even though
12272 it is converted to a 64-bit @code{INTEGER(8)} value. That means
12273 overflows of the 32-bit value can still occur. Therefore, the values
12274 returned by this intrinsic might be or become negative or numerically
12275 less than previous values during a single run of the compiled program.
12277 @item @emph{Standard}:
12280 @item @emph{Class}:
12283 @item @emph{Syntax}:
12284 @code{RESULT = TIME8()}
12286 @item @emph{Return value}:
12287 The return value is a scalar of type @code{INTEGER(8)}.
12289 @item @emph{See also}:
12290 @ref{CTIME}, @ref{GMTIME}, @ref{LTIME}, @ref{MCLOCK8}, @ref{TIME}
12297 @section @code{TINY} --- Smallest positive number of a real kind
12299 @cindex limits, smallest number
12300 @cindex model representation, smallest number
12303 @item @emph{Description}:
12304 @code{TINY(X)} returns the smallest positive (non zero) number
12305 in the model of the type of @code{X}.
12307 @item @emph{Standard}:
12308 Fortran 95 and later
12310 @item @emph{Class}:
12313 @item @emph{Syntax}:
12314 @code{RESULT = TINY(X)}
12316 @item @emph{Arguments}:
12317 @multitable @columnfractions .15 .70
12318 @item @var{X} @tab Shall be of type @code{REAL}.
12321 @item @emph{Return value}:
12322 The return value is of the same type and kind as @var{X}
12324 @item @emph{Example}:
12325 See @code{HUGE} for an example.
12331 @section @code{TRAILZ} --- Number of trailing zero bits of an integer
12336 @item @emph{Description}:
12337 @code{TRAILZ} returns the number of trailing zero bits of an integer.
12339 @item @emph{Standard}:
12340 Fortran 2008 and later
12342 @item @emph{Class}:
12345 @item @emph{Syntax}:
12346 @code{RESULT = TRAILZ(I)}
12348 @item @emph{Arguments}:
12349 @multitable @columnfractions .15 .70
12350 @item @var{I} @tab Shall be of type @code{INTEGER}.
12353 @item @emph{Return value}:
12354 The type of the return value is the default @code{INTEGER}.
12355 If all the bits of @code{I} are zero, the result value is @code{BIT_SIZE(I)}.
12357 @item @emph{Example}:
12359 PROGRAM test_trailz
12360 WRITE (*,*) TRAILZ(8) ! prints 3
12364 @item @emph{See also}:
12365 @ref{BIT_SIZE}, @ref{LEADZ}, @ref{POPPAR}, @ref{POPCNT}
12371 @section @code{TRANSFER} --- Transfer bit patterns
12377 @item @emph{Description}:
12378 Interprets the bitwise representation of @var{SOURCE} in memory as if it
12379 is the representation of a variable or array of the same type and type
12380 parameters as @var{MOLD}.
12382 This is approximately equivalent to the C concept of @emph{casting} one
12385 @item @emph{Standard}:
12386 Fortran 95 and later
12388 @item @emph{Class}:
12389 Transformational function
12391 @item @emph{Syntax}:
12392 @code{RESULT = TRANSFER(SOURCE, MOLD[, SIZE])}
12394 @item @emph{Arguments}:
12395 @multitable @columnfractions .15 .70
12396 @item @var{SOURCE} @tab Shall be a scalar or an array of any type.
12397 @item @var{MOLD} @tab Shall be a scalar or an array of any type.
12398 @item @var{SIZE} @tab (Optional) shall be a scalar of type
12402 @item @emph{Return value}:
12403 The result has the same type as @var{MOLD}, with the bit level
12404 representation of @var{SOURCE}. If @var{SIZE} is present, the result is
12405 a one-dimensional array of length @var{SIZE}. If @var{SIZE} is absent
12406 but @var{MOLD} is an array (of any size or shape), the result is a one-
12407 dimensional array of the minimum length needed to contain the entirety
12408 of the bitwise representation of @var{SOURCE}. If @var{SIZE} is absent
12409 and @var{MOLD} is a scalar, the result is a scalar.
12411 If the bitwise representation of the result is longer than that of
12412 @var{SOURCE}, then the leading bits of the result correspond to those of
12413 @var{SOURCE} and any trailing bits are filled arbitrarily.
12415 When the resulting bit representation does not correspond to a valid
12416 representation of a variable of the same type as @var{MOLD}, the results
12417 are undefined, and subsequent operations on the result cannot be
12418 guaranteed to produce sensible behavior. For example, it is possible to
12419 create @code{LOGICAL} variables for which @code{@var{VAR}} and
12420 @code{.NOT.@var{VAR}} both appear to be true.
12422 @item @emph{Example}:
12424 PROGRAM test_transfer
12425 integer :: x = 2143289344
12426 print *, transfer(x, 1.0) ! prints "NaN" on i686
12434 @section @code{TRANSPOSE} --- Transpose an array of rank two
12436 @cindex array, transpose
12437 @cindex matrix, transpose
12441 @item @emph{Description}:
12442 Transpose an array of rank two. Element (i, j) of the result has the value
12443 @code{MATRIX(j, i)}, for all i, j.
12445 @item @emph{Standard}:
12446 Fortran 95 and later
12448 @item @emph{Class}:
12449 Transformational function
12451 @item @emph{Syntax}:
12452 @code{RESULT = TRANSPOSE(MATRIX)}
12454 @item @emph{Arguments}:
12455 @multitable @columnfractions .15 .70
12456 @item @var{MATRIX} @tab Shall be an array of any type and have a rank of two.
12459 @item @emph{Return value}:
12460 The result has the same type as @var{MATRIX}, and has shape
12461 @code{(/ m, n /)} if @var{MATRIX} has shape @code{(/ n, m /)}.
12467 @section @code{TRIM} --- Remove trailing blank characters of a string
12469 @cindex string, remove trailing whitespace
12472 @item @emph{Description}:
12473 Removes trailing blank characters of a string.
12475 @item @emph{Standard}:
12476 Fortran 95 and later
12478 @item @emph{Class}:
12479 Transformational function
12481 @item @emph{Syntax}:
12482 @code{RESULT = TRIM(STRING)}
12484 @item @emph{Arguments}:
12485 @multitable @columnfractions .15 .70
12486 @item @var{STRING} @tab Shall be a scalar of type @code{CHARACTER}.
12489 @item @emph{Return value}:
12490 A scalar of type @code{CHARACTER} which length is that of @var{STRING}
12491 less the number of trailing blanks.
12493 @item @emph{Example}:
12496 CHARACTER(len=10), PARAMETER :: s = "GFORTRAN "
12497 WRITE(*,*) LEN(s), LEN(TRIM(s)) ! "10 8", with/without trailing blanks
12501 @item @emph{See also}:
12502 @ref{ADJUSTL}, @ref{ADJUSTR}
12508 @section @code{TTYNAM} --- Get the name of a terminal device.
12510 @cindex system, terminal
12513 @item @emph{Description}:
12514 Get the name of a terminal device. For more information,
12515 see @code{ttyname(3)}.
12517 This intrinsic is provided in both subroutine and function forms;
12518 however, only one form can be used in any given program unit.
12520 @item @emph{Standard}:
12523 @item @emph{Class}:
12524 Subroutine, function
12526 @item @emph{Syntax}:
12527 @multitable @columnfractions .80
12528 @item @code{CALL TTYNAM(UNIT, NAME)}
12529 @item @code{NAME = TTYNAM(UNIT)}
12532 @item @emph{Arguments}:
12533 @multitable @columnfractions .15 .70
12534 @item @var{UNIT} @tab Shall be a scalar @code{INTEGER}.
12535 @item @var{NAME} @tab Shall be of type @code{CHARACTER}.
12538 @item @emph{Example}:
12540 PROGRAM test_ttynam
12543 IF (isatty(unit=unit)) write(*,*) ttynam(unit)
12548 @item @emph{See also}:
12555 @section @code{UBOUND} --- Upper dimension bounds of an array
12557 @cindex array, upper bound
12560 @item @emph{Description}:
12561 Returns the upper bounds of an array, or a single upper bound
12562 along the @var{DIM} dimension.
12563 @item @emph{Standard}:
12564 Fortran 95 and later, with @var{KIND} argument Fortran 2003 and later
12566 @item @emph{Class}:
12569 @item @emph{Syntax}:
12570 @code{RESULT = UBOUND(ARRAY [, DIM [, KIND]])}
12572 @item @emph{Arguments}:
12573 @multitable @columnfractions .15 .70
12574 @item @var{ARRAY} @tab Shall be an array, of any type.
12575 @item @var{DIM} @tab (Optional) Shall be a scalar @code{INTEGER}.
12576 @item @var{KIND}@tab (Optional) An @code{INTEGER} initialization
12577 expression indicating the kind parameter of the result.
12580 @item @emph{Return value}:
12581 The return value is of type @code{INTEGER} and of kind @var{KIND}. If
12582 @var{KIND} is absent, the return value is of default integer kind.
12583 If @var{DIM} is absent, the result is an array of the upper bounds of
12584 @var{ARRAY}. If @var{DIM} is present, the result is a scalar
12585 corresponding to the upper bound of the array along that dimension. If
12586 @var{ARRAY} is an expression rather than a whole array or array
12587 structure component, or if it has a zero extent along the relevant
12588 dimension, the upper bound is taken to be the number of elements along
12589 the relevant dimension.
12591 @item @emph{See also}:
12592 @ref{LBOUND}, @ref{LCOBOUND}
12598 @section @code{UCOBOUND} --- Upper codimension bounds of an array
12600 @cindex coarray, upper bound
12603 @item @emph{Description}:
12604 Returns the upper cobounds of a coarray, or a single upper cobound
12605 along the @var{DIM} codimension.
12606 @item @emph{Standard}:
12607 Fortran 2008 and later
12609 @item @emph{Class}:
12612 @item @emph{Syntax}:
12613 @code{RESULT = UCOBOUND(COARRAY [, DIM [, KIND]])}
12615 @item @emph{Arguments}:
12616 @multitable @columnfractions .15 .70
12617 @item @var{ARRAY} @tab Shall be an coarray, of any type.
12618 @item @var{DIM} @tab (Optional) Shall be a scalar @code{INTEGER}.
12619 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
12620 expression indicating the kind parameter of the result.
12623 @item @emph{Return value}:
12624 The return value is of type @code{INTEGER} and of kind @var{KIND}. If
12625 @var{KIND} is absent, the return value is of default integer kind.
12626 If @var{DIM} is absent, the result is an array of the lower cobounds of
12627 @var{COARRAY}. If @var{DIM} is present, the result is a scalar
12628 corresponding to the lower cobound of the array along that codimension.
12630 @item @emph{See also}:
12631 @ref{LCOBOUND}, @ref{LBOUND}
12637 @section @code{UMASK} --- Set the file creation mask
12639 @cindex file system, file creation mask
12642 @item @emph{Description}:
12643 Sets the file creation mask to @var{MASK}. If called as a function, it
12644 returns the old value. If called as a subroutine and argument @var{OLD}
12645 if it is supplied, it is set to the old value. See @code{umask(2)}.
12647 @item @emph{Standard}:
12650 @item @emph{Class}:
12651 Subroutine, function
12653 @item @emph{Syntax}:
12654 @multitable @columnfractions .80
12655 @item @code{CALL UMASK(MASK [, OLD])}
12656 @item @code{OLD = UMASK(MASK)}
12659 @item @emph{Arguments}:
12660 @multitable @columnfractions .15 .70
12661 @item @var{MASK} @tab Shall be a scalar of type @code{INTEGER}.
12662 @item @var{OLD} @tab (Optional) Shall be a scalar of type
12671 @section @code{UNLINK} --- Remove a file from the file system
12673 @cindex file system, remove file
12676 @item @emph{Description}:
12677 Unlinks the file @var{PATH}. A null character (@code{CHAR(0)}) can be
12678 used to mark the end of the name in @var{PATH}; otherwise, trailing
12679 blanks in the file name are ignored. If the @var{STATUS} argument is
12680 supplied, it contains 0 on success or a nonzero error code upon return;
12681 see @code{unlink(2)}.
12683 This intrinsic is provided in both subroutine and function forms;
12684 however, only one form can be used in any given program unit.
12686 @item @emph{Standard}:
12689 @item @emph{Class}:
12690 Subroutine, function
12692 @item @emph{Syntax}:
12693 @multitable @columnfractions .80
12694 @item @code{CALL UNLINK(PATH [, STATUS])}
12695 @item @code{STATUS = UNLINK(PATH)}
12698 @item @emph{Arguments}:
12699 @multitable @columnfractions .15 .70
12700 @item @var{PATH} @tab Shall be of default @code{CHARACTER} type.
12701 @item @var{STATUS} @tab (Optional) Shall be of default @code{INTEGER} type.
12704 @item @emph{See also}:
12705 @ref{LINK}, @ref{SYMLNK}
12711 @section @code{UNPACK} --- Unpack an array of rank one into an array
12713 @cindex array, unpacking
12714 @cindex array, increase dimension
12715 @cindex array, scatter elements
12718 @item @emph{Description}:
12719 Store the elements of @var{VECTOR} in an array of higher rank.
12721 @item @emph{Standard}:
12722 Fortran 95 and later
12724 @item @emph{Class}:
12725 Transformational function
12727 @item @emph{Syntax}:
12728 @code{RESULT = UNPACK(VECTOR, MASK, FIELD)}
12730 @item @emph{Arguments}:
12731 @multitable @columnfractions .15 .70
12732 @item @var{VECTOR} @tab Shall be an array of any type and rank one. It
12733 shall have at least as many elements as @var{MASK} has @code{TRUE} values.
12734 @item @var{MASK} @tab Shall be an array of type @code{LOGICAL}.
12735 @item @var{FIELD} @tab Shall be of the same type as @var{VECTOR} and have
12736 the same shape as @var{MASK}.
12739 @item @emph{Return value}:
12740 The resulting array corresponds to @var{FIELD} with @code{TRUE} elements
12741 of @var{MASK} replaced by values from @var{VECTOR} in array element order.
12743 @item @emph{Example}:
12745 PROGRAM test_unpack
12746 integer :: vector(2) = (/1,1/)
12747 logical :: mask(4) = (/ .TRUE., .FALSE., .FALSE., .TRUE. /)
12748 integer :: field(2,2) = 0, unity(2,2)
12750 ! result: unity matrix
12751 unity = unpack(vector, reshape(mask, (/2,2/)), field)
12755 @item @emph{See also}:
12756 @ref{PACK}, @ref{SPREAD}
12762 @section @code{VERIFY} --- Scan a string for characters not a given set
12764 @cindex string, find missing set
12767 @item @emph{Description}:
12768 Verifies that all the characters in @var{STRING} belong to the set of
12769 characters in @var{SET}.
12771 If @var{BACK} is either absent or equals @code{FALSE}, this function
12772 returns the position of the leftmost character of @var{STRING} that is
12773 not in @var{SET}. If @var{BACK} equals @code{TRUE}, the rightmost
12774 position is returned. If all characters of @var{STRING} are found in
12775 @var{SET}, the result is zero.
12777 @item @emph{Standard}:
12778 Fortran 95 and later, with @var{KIND} argument Fortran 2003 and later
12780 @item @emph{Class}:
12783 @item @emph{Syntax}:
12784 @code{RESULT = VERIFY(STRING, SET[, BACK [, KIND]])}
12786 @item @emph{Arguments}:
12787 @multitable @columnfractions .15 .70
12788 @item @var{STRING} @tab Shall be of type @code{CHARACTER}.
12789 @item @var{SET} @tab Shall be of type @code{CHARACTER}.
12790 @item @var{BACK} @tab (Optional) shall be of type @code{LOGICAL}.
12791 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
12792 expression indicating the kind parameter of the result.
12795 @item @emph{Return value}:
12796 The return value is of type @code{INTEGER} and of kind @var{KIND}. If
12797 @var{KIND} is absent, the return value is of default integer kind.
12799 @item @emph{Example}:
12801 PROGRAM test_verify
12802 WRITE(*,*) VERIFY("FORTRAN", "AO") ! 1, found 'F'
12803 WRITE(*,*) VERIFY("FORTRAN", "FOO") ! 3, found 'R'
12804 WRITE(*,*) VERIFY("FORTRAN", "C++") ! 1, found 'F'
12805 WRITE(*,*) VERIFY("FORTRAN", "C++", .TRUE.) ! 7, found 'N'
12806 WRITE(*,*) VERIFY("FORTRAN", "FORTRAN") ! 0' found none
12810 @item @emph{See also}:
12811 @ref{SCAN}, @ref{INDEX intrinsic}
12817 @section @code{XOR} --- Bitwise logical exclusive OR
12819 @cindex bitwise logical exclusive or
12820 @cindex logical exclusive or, bitwise
12823 @item @emph{Description}:
12824 Bitwise logical exclusive or.
12826 This intrinsic routine is provided for backwards compatibility with
12827 GNU Fortran 77. For integer arguments, programmers should consider
12828 the use of the @ref{IEOR} intrinsic and for logical arguments the
12829 @code{.NEQV.} operator, which are both defined by the Fortran standard.
12831 @item @emph{Standard}:
12834 @item @emph{Class}:
12837 @item @emph{Syntax}:
12838 @code{RESULT = XOR(I, J)}
12840 @item @emph{Arguments}:
12841 @multitable @columnfractions .15 .70
12842 @item @var{I} @tab The type shall be either a scalar @code{INTEGER}
12843 type or a scalar @code{LOGICAL} type.
12844 @item @var{J} @tab The type shall be the same as the type of @var{I}.
12847 @item @emph{Return value}:
12848 The return type is either a scalar @code{INTEGER} or a scalar
12849 @code{LOGICAL}. If the kind type parameters differ, then the
12850 smaller kind type is implicitly converted to larger kind, and the
12851 return has the larger kind.
12853 @item @emph{Example}:
12856 LOGICAL :: T = .TRUE., F = .FALSE.
12858 DATA a / Z'F' /, b / Z'3' /
12860 WRITE (*,*) XOR(T, T), XOR(T, F), XOR(F, T), XOR(F, F)
12861 WRITE (*,*) XOR(a, b)
12865 @item @emph{See also}:
12866 Fortran 95 elemental function: @ref{IEOR}
12871 @node Intrinsic Modules
12872 @chapter Intrinsic Modules
12873 @cindex intrinsic Modules
12876 * ISO_FORTRAN_ENV::
12878 * OpenMP Modules OMP_LIB and OMP_LIB_KINDS::
12881 @node ISO_FORTRAN_ENV
12882 @section @code{ISO_FORTRAN_ENV}
12884 @item @emph{Standard}:
12885 Fortran 2003 and later, except when otherwise noted
12888 The @code{ISO_FORTRAN_ENV} module provides the following scalar default-integer
12892 @item @code{ATOMIC_INT_KIND}:
12893 Default-kind integer constant to be used as kind parameter when defining
12894 integer variables used in atomic operations. (Fortran 2008 or later.)
12896 @item @code{ATOMIC_LOGICAL_KIND}:
12897 Default-kind integer constant to be used as kind parameter when defining
12898 logical variables used in atomic operations. (Fortran 2008 or later.)
12900 @item @code{CHARACTER_KINDS}:
12901 Default-kind integer constant array of rank one containing the supported kind
12902 parameters of the @code{CHARACTER} type. (Fortran 2008 or later.)
12904 @item @code{CHARACTER_STORAGE_SIZE}:
12905 Size in bits of the character storage unit.
12907 @item @code{ERROR_UNIT}:
12908 Identifies the preconnected unit used for error reporting.
12910 @item @code{FILE_STORAGE_SIZE}:
12911 Size in bits of the file-storage unit.
12913 @item @code{INPUT_UNIT}:
12914 Identifies the preconnected unit identified by the asterisk
12915 (@code{*}) in @code{READ} statement.
12917 @item @code{INT8}, @code{INT16}, @code{INT32}, @code{INT64}:
12918 Kind type parameters to specify an INTEGER type with a storage
12919 size of 16, 32, and 64 bits. It is negative if a target platform
12920 does not support the particular kind. (Fortran 2008 or later.)
12922 @item @code{INTEGER_KINDS}:
12923 Default-kind integer constant array of rank one containing the supported kind
12924 parameters of the @code{INTEGER} type. (Fortran 2008 or later.)
12926 @item @code{IOSTAT_END}:
12927 The value assigned to the variable passed to the @code{IOSTAT=} specifier of
12928 an input/output statement if an end-of-file condition occurred.
12930 @item @code{IOSTAT_EOR}:
12931 The value assigned to the variable passed to the @code{IOSTAT=} specifier of
12932 an input/output statement if an end-of-record condition occurred.
12934 @item @code{IOSTAT_INQUIRE_INTERNAL_UNIT}:
12935 Scalar default-integer constant, used by @code{INQUIRE} for the
12936 @code{IOSTAT=} specifier to denote an that a unit number identifies an
12937 internal unit. (Fortran 2008 or later.)
12939 @item @code{NUMERIC_STORAGE_SIZE}:
12940 The size in bits of the numeric storage unit.
12942 @item @code{LOGICAL_KINDS}:
12943 Default-kind integer constant array of rank one containing the supported kind
12944 parameters of the @code{LOGICAL} type. (Fortran 2008 or later.)
12946 @item @code{OUTPUT_UNIT}:
12947 Identifies the preconnected unit identified by the asterisk
12948 (@code{*}) in @code{WRITE} statement.
12950 @item @code{REAL32}, @code{REAL64}, @code{REAL128}:
12951 Kind type parameters to specify a REAL type with a storage
12952 size of 32, 64, and 128 bits. It is negative if a target platform
12953 does not support the particular kind. (Fortran 2008 or later.)
12955 @item @code{REAL_KINDS}:
12956 Default-kind integer constant array of rank one containing the supported kind
12957 parameters of the @code{REAL} type. (Fortran 2008 or later.)
12959 @item @code{STAT_LOCKED}:
12960 Scalar default-integer constant used as STAT= return value by @code{LOCK} to
12961 denote that the lock variable is locked by the executing image. (Fortran 2008
12964 @item @code{STAT_LOCKED_OTHER_IMAGE}:
12965 Scalar default-integer constant used as STAT= return value by @code{UNLOCK} to
12966 denote that the lock variable is locked by another image. (Fortran 2008 or
12969 @item @code{STAT_STOPPED_IMAGE}:
12970 Positive, scalar default-integer constant used as STAT= return value if the
12971 argument in the statement requires synchronisation with an image, which has
12972 initiated the termination of the execution. (Fortran 2008 or later.)
12974 @item @code{STAT_UNLOCKED}:
12975 Scalar default-integer constant used as STAT= return value by @code{UNLOCK} to
12976 denote that the lock variable is unlocked. (Fortran 2008 or later.)
12979 The module provides the following derived type:
12982 @item @code{LOCK_TYPE}:
12983 Derived type with private components to be use with the @code{LOCK} and
12984 @code{UNLOCK} statement. A variable of its type has to be always declared
12985 as coarray and may not appear in a variable-definition context.
12986 (Fortran 2008 or later.)
12989 The module also provides the following intrinsic procedures:
12990 @ref{COMPILER_OPTIONS} and @ref{COMPILER_VERSION}.
12994 @node ISO_C_BINDING
12995 @section @code{ISO_C_BINDING}
12997 @item @emph{Standard}:
12998 Fortran 2003 and later, GNU extensions
13001 The following intrinsic procedures are provided by the module; their
13002 definition can be found in the section Intrinsic Procedures of this
13006 @item @code{C_ASSOCIATED}
13007 @item @code{C_F_POINTER}
13008 @item @code{C_F_PROCPOINTER}
13009 @item @code{C_FUNLOC}
13011 @item @code{C_SIZEOF}
13013 @c TODO: Vertical spacing between C_FUNLOC and C_LOC wrong in PDF,
13014 @c don't really know why.
13016 The @code{ISO_C_BINDING} module provides the following named constants of
13017 type default integer, which can be used as KIND type parameters.
13019 In addition to the integer named constants required by the Fortran 2003
13020 standard, GNU Fortran provides as an extension named constants for the
13021 128-bit integer types supported by the C compiler: @code{C_INT128_T,
13022 C_INT_LEAST128_T, C_INT_FAST128_T}. Furthermore, if @code{__float} is
13023 supported in C, the named constants @code{C_FLOAT128, C_FLOAT128_COMPLEX}
13026 @multitable @columnfractions .15 .35 .35 .35
13027 @item Fortran Type @tab Named constant @tab C type @tab Extension
13028 @item @code{INTEGER}@tab @code{C_INT} @tab @code{int}
13029 @item @code{INTEGER}@tab @code{C_SHORT} @tab @code{short int}
13030 @item @code{INTEGER}@tab @code{C_LONG} @tab @code{long int}
13031 @item @code{INTEGER}@tab @code{C_LONG_LONG} @tab @code{long long int}
13032 @item @code{INTEGER}@tab @code{C_SIGNED_CHAR} @tab @code{signed char}/@code{unsigned char}
13033 @item @code{INTEGER}@tab @code{C_SIZE_T} @tab @code{size_t}
13034 @item @code{INTEGER}@tab @code{C_INT8_T} @tab @code{int8_t}
13035 @item @code{INTEGER}@tab @code{C_INT16_T} @tab @code{int16_t}
13036 @item @code{INTEGER}@tab @code{C_INT32_T} @tab @code{int32_t}
13037 @item @code{INTEGER}@tab @code{C_INT64_T} @tab @code{int64_t}
13038 @item @code{INTEGER}@tab @code{C_INT128_T} @tab @code{int128_t} @tab Ext.
13039 @item @code{INTEGER}@tab @code{C_INT_LEAST8_T} @tab @code{int_least8_t}
13040 @item @code{INTEGER}@tab @code{C_INT_LEAST16_T} @tab @code{int_least16_t}
13041 @item @code{INTEGER}@tab @code{C_INT_LEAST32_T} @tab @code{int_least32_t}
13042 @item @code{INTEGER}@tab @code{C_INT_LEAST64_T} @tab @code{int_least64_t}
13043 @item @code{INTEGER}@tab @code{C_INT_LEAST128_T}@tab @code{int_least128_t} @tab Ext.
13044 @item @code{INTEGER}@tab @code{C_INT_FAST8_T} @tab @code{int_fast8_t}
13045 @item @code{INTEGER}@tab @code{C_INT_FAST16_T} @tab @code{int_fast16_t}
13046 @item @code{INTEGER}@tab @code{C_INT_FAST32_T} @tab @code{int_fast32_t}
13047 @item @code{INTEGER}@tab @code{C_INT_FAST64_T} @tab @code{int_fast64_t}
13048 @item @code{INTEGER}@tab @code{C_INT_FAST128_T} @tab @code{int_fast128_t} @tab Ext.
13049 @item @code{INTEGER}@tab @code{C_INTMAX_T} @tab @code{intmax_t}
13050 @item @code{INTEGER}@tab @code{C_INTPTR_T} @tab @code{intptr_t}
13051 @item @code{REAL} @tab @code{C_FLOAT} @tab @code{float}
13052 @item @code{REAL} @tab @code{C_DOUBLE} @tab @code{double}
13053 @item @code{REAL} @tab @code{C_LONG_DOUBLE} @tab @code{long double}
13054 @item @code{REAL} @tab @code{C_FLOAT128} @tab @code{__float128} @tab Ext.
13055 @item @code{COMPLEX}@tab @code{C_FLOAT_COMPLEX} @tab @code{float _Complex}
13056 @item @code{COMPLEX}@tab @code{C_DOUBLE_COMPLEX}@tab @code{double _Complex}
13057 @item @code{COMPLEX}@tab @code{C_LONG_DOUBLE_COMPLEX}@tab @code{long double _Complex}
13058 @item @code{REAL} @tab @code{C_FLOAT128_COMPLEX} @tab @code{__float128 _Complex} @tab Ext.
13059 @item @code{LOGICAL}@tab @code{C_BOOL} @tab @code{_Bool}
13060 @item @code{CHARACTER}@tab @code{C_CHAR} @tab @code{char}
13063 Additionally, the following parameters of type @code{CHARACTER(KIND=C_CHAR)}
13066 @multitable @columnfractions .20 .45 .15
13067 @item Name @tab C definition @tab Value
13068 @item @code{C_NULL_CHAR} @tab null character @tab @code{'\0'}
13069 @item @code{C_ALERT} @tab alert @tab @code{'\a'}
13070 @item @code{C_BACKSPACE} @tab backspace @tab @code{'\b'}
13071 @item @code{C_FORM_FEED} @tab form feed @tab @code{'\f'}
13072 @item @code{C_NEW_LINE} @tab new line @tab @code{'\n'}
13073 @item @code{C_CARRIAGE_RETURN} @tab carriage return @tab @code{'\r'}
13074 @item @code{C_HORIZONTAL_TAB} @tab horizontal tab @tab @code{'\t'}
13075 @item @code{C_VERTICAL_TAB} @tab vertical tab @tab @code{'\v'}
13078 Moreover, the following two named constants are defined:
13080 @multitable @columnfractions .20 .80
13081 @item Name @tab Type
13082 @item @code{C_NULL_PTR} @tab @code{C_PTR}
13083 @item @code{C_NULL_FUNPTR} @tab @code{C_FUNPTR}
13086 Both are equivalent to the value @code{NULL} in C.
13088 @node OpenMP Modules OMP_LIB and OMP_LIB_KINDS
13089 @section OpenMP Modules @code{OMP_LIB} and @code{OMP_LIB_KINDS}
13091 @item @emph{Standard}:
13092 OpenMP Application Program Interface v3.1
13096 The OpenMP Fortran runtime library routines are provided both in
13097 a form of two Fortran 90 modules, named @code{OMP_LIB} and
13098 @code{OMP_LIB_KINDS}, and in a form of a Fortran @code{include} file named
13099 @file{omp_lib.h}. The procedures provided by @code{OMP_LIB} can be found
13100 in the @ref{Top,,Introduction,libgomp,GNU OpenMP runtime library} manual,
13101 the named constants defined in the modules are listed
13104 For details refer to the actual
13105 @uref{http://www.openmp.org/mp-documents/spec31.pdf,
13106 OpenMP Application Program Interface v3.1}.
13108 @code{OMP_LIB_KINDS} provides the following scalar default-integer
13112 @item @code{omp_lock_kind}
13113 @item @code{omp_nest_lock_kind}
13114 @item @code{omp_sched_kind}
13117 @code{OMP_LIB} provides the scalar default-integer
13118 named constant @code{openmp_version} with a value of the form
13119 @var{yyyymm}, where @code{yyyy} is the year and @var{mm} the month
13120 of the OpenMP version; for OpenMP v3.1 the value is @code{201107}.
13122 And the following scalar integer named constants of the
13123 kind @code{omp_sched_kind}:
13126 @item @code{omp_sched_static}
13127 @item @code{omp_sched_dynamic}
13128 @item @code{omp_sched_guided}
13129 @item @code{omp_sched_auto}