2 Copyright (C) 2005, 2006, 2007, 2008, 2009, 2010
3 Free Software Foundation, Inc.
4 This is part of the GNU Fortran manual.
5 For copying conditions, see the file gfortran.texi.
7 Permission is granted to copy, distribute and/or modify this document
8 under the terms of the GNU Free Documentation License, Version 1.3 or
9 any later version published by the Free Software Foundation; with the
10 Invariant Sections being ``Funding Free Software'', the Front-Cover
11 Texts being (a) (see below), and with the Back-Cover Texts being (b)
12 (see below). A copy of the license is included in the gfdl(7) man page.
15 Some basic guidelines for editing this document:
17 (1) The intrinsic procedures are to be listed in alphabetical order.
18 (2) The generic name is to be used.
19 (3) The specific names are included in the function index and in a
20 table at the end of the node (See ABS entry).
21 (4) Try to maintain the same style for each entry.
27 \gdef\acos{\mathop{\rm acos}\nolimits}
28 \gdef\asin{\mathop{\rm asin}\nolimits}
29 \gdef\atan{\mathop{\rm atan}\nolimits}
30 \gdef\acosh{\mathop{\rm acosh}\nolimits}
31 \gdef\asinh{\mathop{\rm asinh}\nolimits}
32 \gdef\atanh{\mathop{\rm atanh}\nolimits}
36 @node Intrinsic Procedures
37 @chapter Intrinsic Procedures
38 @cindex intrinsic procedures
41 * Introduction: Introduction to Intrinsics
42 * @code{ABORT}: ABORT, Abort the program
43 * @code{ABS}: ABS, Absolute value
44 * @code{ACCESS}: ACCESS, Checks file access modes
45 * @code{ACHAR}: ACHAR, Character in @acronym{ASCII} collating sequence
46 * @code{ACOS}: ACOS, Arccosine function
47 * @code{ACOSH}: ACOSH, Inverse hyperbolic cosine function
48 * @code{ADJUSTL}: ADJUSTL, Left adjust a string
49 * @code{ADJUSTR}: ADJUSTR, Right adjust a string
50 * @code{AIMAG}: AIMAG, Imaginary part of complex number
51 * @code{AINT}: AINT, Truncate to a whole number
52 * @code{ALARM}: ALARM, Set an alarm clock
53 * @code{ALL}: ALL, Determine if all values are true
54 * @code{ALLOCATED}: ALLOCATED, Status of allocatable entity
55 * @code{AND}: AND, Bitwise logical AND
56 * @code{ANINT}: ANINT, Nearest whole number
57 * @code{ANY}: ANY, Determine if any values are true
58 * @code{ASIN}: ASIN, Arcsine function
59 * @code{ASINH}: ASINH, Inverse hyperbolic sine function
60 * @code{ASSOCIATED}: ASSOCIATED, Status of a pointer or pointer/target pair
61 * @code{ATAN}: ATAN, Arctangent function
62 * @code{ATAN2}: ATAN2, Arctangent function
63 * @code{ATANH}: ATANH, Inverse hyperbolic tangent function
64 * @code{BESSEL_J0}: BESSEL_J0, Bessel function of the first kind of order 0
65 * @code{BESSEL_J1}: BESSEL_J1, Bessel function of the first kind of order 1
66 * @code{BESSEL_JN}: BESSEL_JN, Bessel function of the first kind
67 * @code{BESSEL_Y0}: BESSEL_Y0, Bessel function of the second kind of order 0
68 * @code{BESSEL_Y1}: BESSEL_Y1, Bessel function of the second kind of order 1
69 * @code{BESSEL_YN}: BESSEL_YN, Bessel function of the second kind
70 * @code{BGE}: BGE, Bitwise greater than or equal to
71 * @code{BGT}: BGT, Bitwise greater than
72 * @code{BIT_SIZE}: BIT_SIZE, Bit size inquiry function
73 * @code{BLE}: BLE, Bitwise less than or equal to
74 * @code{BLT}: BLT, Bitwise less than
75 * @code{BTEST}: BTEST, Bit test function
76 * @code{C_ASSOCIATED}: C_ASSOCIATED, Status of a C pointer
77 * @code{C_F_POINTER}: C_F_POINTER, Convert C into Fortran pointer
78 * @code{C_F_PROCPOINTER}: C_F_PROCPOINTER, Convert C into Fortran procedure pointer
79 * @code{C_FUNLOC}: C_FUNLOC, Obtain the C address of a procedure
80 * @code{C_LOC}: C_LOC, Obtain the C address of an object
81 * @code{C_SIZEOF}: C_SIZEOF, Size in bytes of an expression
82 * @code{CEILING}: CEILING, Integer ceiling function
83 * @code{CHAR}: CHAR, Integer-to-character conversion function
84 * @code{CHDIR}: CHDIR, Change working directory
85 * @code{CHMOD}: CHMOD, Change access permissions of files
86 * @code{CMPLX}: CMPLX, Complex conversion function
87 * @code{COMMAND_ARGUMENT_COUNT}: COMMAND_ARGUMENT_COUNT, Get number of command line arguments
88 * @code{COMPLEX}: COMPLEX, Complex conversion function
89 * @code{COMPILER_VERSION}: COMPILER_VERSION, Compiler version string
90 * @code{COMPILER_OPTIONS}: COMPILER_OPTIONS, Options passed to the compiler
91 * @code{CONJG}: CONJG, Complex conjugate function
92 * @code{COS}: COS, Cosine function
93 * @code{COSH}: COSH, Hyperbolic cosine function
94 * @code{COUNT}: COUNT, Count occurrences of TRUE in an array
95 * @code{CPU_TIME}: CPU_TIME, CPU time subroutine
96 * @code{CSHIFT}: CSHIFT, Circular shift elements of an array
97 * @code{CTIME}: CTIME, Subroutine (or function) to convert a time into a string
98 * @code{DATE_AND_TIME}: DATE_AND_TIME, Date and time subroutine
99 * @code{DBLE}: DBLE, Double precision conversion function
100 * @code{DCMPLX}: DCMPLX, Double complex conversion function
101 * @code{DIGITS}: DIGITS, Significant digits function
102 * @code{DIM}: DIM, Positive difference
103 * @code{DOT_PRODUCT}: DOT_PRODUCT, Dot product function
104 * @code{DPROD}: DPROD, Double product function
105 * @code{DREAL}: DREAL, Double real part function
106 * @code{DSHIFTL}: DSHIFTL, Combined left shift
107 * @code{DSHIFTR}: DSHIFTR, Combined right shift
108 * @code{DTIME}: DTIME, Execution time subroutine (or function)
109 * @code{EOSHIFT}: EOSHIFT, End-off shift elements of an array
110 * @code{EPSILON}: EPSILON, Epsilon function
111 * @code{ERF}: ERF, Error function
112 * @code{ERFC}: ERFC, Complementary error function
113 * @code{ERFC_SCALED}: ERFC_SCALED, Exponentially-scaled complementary error function
114 * @code{ETIME}: ETIME, Execution time subroutine (or function)
115 * @code{EXECUTE_COMMAND_LINE}: EXECUTE_COMMAND_LINE, Execute a shell command
116 * @code{EXIT}: EXIT, Exit the program with status.
117 * @code{EXP}: EXP, Exponential function
118 * @code{EXPONENT}: EXPONENT, Exponent function
119 * @code{EXTENDS_TYPE_OF}: EXTENDS_TYPE_OF, Query dynamic type for extension
120 * @code{FDATE}: FDATE, Subroutine (or function) to get the current time as a string
121 * @code{FGET}: FGET, Read a single character in stream mode from stdin
122 * @code{FGETC}: FGETC, Read a single character in stream mode
123 * @code{FLOOR}: FLOOR, Integer floor function
124 * @code{FLUSH}: FLUSH, Flush I/O unit(s)
125 * @code{FNUM}: FNUM, File number function
126 * @code{FPUT}: FPUT, Write a single character in stream mode to stdout
127 * @code{FPUTC}: FPUTC, Write a single character in stream mode
128 * @code{FRACTION}: FRACTION, Fractional part of the model representation
129 * @code{FREE}: FREE, Memory de-allocation subroutine
130 * @code{FSEEK}: FSEEK, Low level file positioning subroutine
131 * @code{FSTAT}: FSTAT, Get file status
132 * @code{FTELL}: FTELL, Current stream position
133 * @code{GAMMA}: GAMMA, Gamma function
134 * @code{GERROR}: GERROR, Get last system error message
135 * @code{GETARG}: GETARG, Get command line arguments
136 * @code{GET_COMMAND}: GET_COMMAND, Get the entire command line
137 * @code{GET_COMMAND_ARGUMENT}: GET_COMMAND_ARGUMENT, Get command line arguments
138 * @code{GETCWD}: GETCWD, Get current working directory
139 * @code{GETENV}: GETENV, Get an environmental variable
140 * @code{GET_ENVIRONMENT_VARIABLE}: GET_ENVIRONMENT_VARIABLE, Get an environmental variable
141 * @code{GETGID}: GETGID, Group ID function
142 * @code{GETLOG}: GETLOG, Get login name
143 * @code{GETPID}: GETPID, Process ID function
144 * @code{GETUID}: GETUID, User ID function
145 * @code{GMTIME}: GMTIME, Convert time to GMT info
146 * @code{HOSTNM}: HOSTNM, Get system host name
147 * @code{HUGE}: HUGE, Largest number of a kind
148 * @code{HYPOT}: HYPOT, Euclidean distance function
149 * @code{IACHAR}: IACHAR, Code in @acronym{ASCII} collating sequence
150 * @code{IALL}: IALL, Bitwise AND of array elements
151 * @code{IAND}: IAND, Bitwise logical and
152 * @code{IANY}: IANY, Bitwise OR of array elements
153 * @code{IARGC}: IARGC, Get the number of command line arguments
154 * @code{IBCLR}: IBCLR, Clear bit
155 * @code{IBITS}: IBITS, Bit extraction
156 * @code{IBSET}: IBSET, Set bit
157 * @code{ICHAR}: ICHAR, Character-to-integer conversion function
158 * @code{IDATE}: IDATE, Current local time (day/month/year)
159 * @code{IEOR}: IEOR, Bitwise logical exclusive or
160 * @code{IERRNO}: IERRNO, Function to get the last system error number
161 * @code{IMAGE_INDEX}: IMAGE_INDEX, Cosubscript to image index conversion
162 * @code{INDEX}: INDEX intrinsic, Position of a substring within a string
163 * @code{INT}: INT, Convert to integer type
164 * @code{INT2}: INT2, Convert to 16-bit integer type
165 * @code{INT8}: INT8, Convert to 64-bit integer type
166 * @code{IOR}: IOR, Bitwise logical or
167 * @code{IPARITY}: IPARITY, Bitwise XOR of array elements
168 * @code{IRAND}: IRAND, Integer pseudo-random number
169 * @code{IS_IOSTAT_END}: IS_IOSTAT_END, Test for end-of-file value
170 * @code{IS_IOSTAT_EOR}: IS_IOSTAT_EOR, Test for end-of-record value
171 * @code{ISATTY}: ISATTY, Whether a unit is a terminal device
172 * @code{ISHFT}: ISHFT, Shift bits
173 * @code{ISHFTC}: ISHFTC, Shift bits circularly
174 * @code{ISNAN}: ISNAN, Tests for a NaN
175 * @code{ITIME}: ITIME, Current local time (hour/minutes/seconds)
176 * @code{KILL}: KILL, Send a signal to a process
177 * @code{KIND}: KIND, Kind of an entity
178 * @code{LBOUND}: LBOUND, Lower dimension bounds of an array
179 * @code{LCOBOUND}: LCOBOUND, Lower codimension bounds of an array
180 * @code{LEADZ}: LEADZ, Number of leading zero bits of an integer
181 * @code{LEN}: LEN, Length of a character entity
182 * @code{LEN_TRIM}: LEN_TRIM, Length of a character entity without trailing blank characters
183 * @code{LGE}: LGE, Lexical greater than or equal
184 * @code{LGT}: LGT, Lexical greater than
185 * @code{LINK}: LINK, Create a hard link
186 * @code{LLE}: LLE, Lexical less than or equal
187 * @code{LLT}: LLT, Lexical less than
188 * @code{LNBLNK}: LNBLNK, Index of the last non-blank character in a string
189 * @code{LOC}: LOC, Returns the address of a variable
190 * @code{LOG}: LOG, Logarithm function
191 * @code{LOG10}: LOG10, Base 10 logarithm function
192 * @code{LOG_GAMMA}: LOG_GAMMA, Logarithm of the Gamma function
193 * @code{LOGICAL}: LOGICAL, Convert to logical type
194 * @code{LONG}: LONG, Convert to integer type
195 * @code{LSHIFT}: LSHIFT, Left shift bits
196 * @code{LSTAT}: LSTAT, Get file status
197 * @code{LTIME}: LTIME, Convert time to local time info
198 * @code{MALLOC}: MALLOC, Dynamic memory allocation function
199 * @code{MASKL}: MASKL, Left justified mask
200 * @code{MASKR}: MASKR, Right justified mask
201 * @code{MATMUL}: MATMUL, matrix multiplication
202 * @code{MAX}: MAX, Maximum value of an argument list
203 * @code{MAXEXPONENT}: MAXEXPONENT, Maximum exponent of a real kind
204 * @code{MAXLOC}: MAXLOC, Location of the maximum value within an array
205 * @code{MAXVAL}: MAXVAL, Maximum value of an array
206 * @code{MCLOCK}: MCLOCK, Time function
207 * @code{MCLOCK8}: MCLOCK8, Time function (64-bit)
208 * @code{MERGE}: MERGE, Merge arrays
209 * @code{MERGE_BITS}: MERGE_BITS, Merge of bits under mask
210 * @code{MIN}: MIN, Minimum value of an argument list
211 * @code{MINEXPONENT}: MINEXPONENT, Minimum exponent of a real kind
212 * @code{MINLOC}: MINLOC, Location of the minimum value within an array
213 * @code{MINVAL}: MINVAL, Minimum value of an array
214 * @code{MOD}: MOD, Remainder function
215 * @code{MODULO}: MODULO, Modulo function
216 * @code{MOVE_ALLOC}: MOVE_ALLOC, Move allocation from one object to another
217 * @code{MVBITS}: MVBITS, Move bits from one integer to another
218 * @code{NEAREST}: NEAREST, Nearest representable number
219 * @code{NEW_LINE}: NEW_LINE, New line character
220 * @code{NINT}: NINT, Nearest whole number
221 * @code{NORM2}: NORM2, Euclidean vector norm
222 * @code{NOT}: NOT, Logical negation
223 * @code{NULL}: NULL, Function that returns an disassociated pointer
224 * @code{NUM_IMAGES}: NUM_IMAGES, Number of images
225 * @code{OR}: OR, Bitwise logical OR
226 * @code{PACK}: PACK, Pack an array into an array of rank one
227 * @code{PARITY}: PARITY, Reduction with exclusive OR
228 * @code{PERROR}: PERROR, Print system error message
229 * @code{POPCNT}: POPCNT, Number of bits set
230 * @code{POPPAR}: POPPAR, Parity of the number of bits set
231 * @code{PRECISION}: PRECISION, Decimal precision of a real kind
232 * @code{PRESENT}: PRESENT, Determine whether an optional dummy argument is specified
233 * @code{PRODUCT}: PRODUCT, Product of array elements
234 * @code{RADIX}: RADIX, Base of a data model
235 * @code{RANDOM_NUMBER}: RANDOM_NUMBER, Pseudo-random number
236 * @code{RANDOM_SEED}: RANDOM_SEED, Initialize a pseudo-random number sequence
237 * @code{RAND}: RAND, Real pseudo-random number
238 * @code{RANGE}: RANGE, Decimal exponent range
239 * @code{RAN}: RAN, Real pseudo-random number
240 * @code{REAL}: REAL, Convert to real type
241 * @code{RENAME}: RENAME, Rename a file
242 * @code{REPEAT}: REPEAT, Repeated string concatenation
243 * @code{RESHAPE}: RESHAPE, Function to reshape an array
244 * @code{RRSPACING}: RRSPACING, Reciprocal of the relative spacing
245 * @code{RSHIFT}: RSHIFT, Right shift bits
246 * @code{SAME_TYPE_AS}: SAME_TYPE_AS, Query dynamic types for equality
247 * @code{SCALE}: SCALE, Scale a real value
248 * @code{SCAN}: SCAN, Scan a string for the presence of a set of characters
249 * @code{SECNDS}: SECNDS, Time function
250 * @code{SECOND}: SECOND, CPU time function
251 * @code{SELECTED_CHAR_KIND}: SELECTED_CHAR_KIND, Choose character kind
252 * @code{SELECTED_INT_KIND}: SELECTED_INT_KIND, Choose integer kind
253 * @code{SELECTED_REAL_KIND}: SELECTED_REAL_KIND, Choose real kind
254 * @code{SET_EXPONENT}: SET_EXPONENT, Set the exponent of the model
255 * @code{SHAPE}: SHAPE, Determine the shape of an array
256 * @code{SHIFTA}: SHIFTA, Right shift with fill
257 * @code{SHIFTL}: SHIFTL, Left shift
258 * @code{SHIFTR}: SHIFTR, Right shift
259 * @code{SIGN}: SIGN, Sign copying function
260 * @code{SIGNAL}: SIGNAL, Signal handling subroutine (or function)
261 * @code{SIN}: SIN, Sine function
262 * @code{SINH}: SINH, Hyperbolic sine function
263 * @code{SIZE}: SIZE, Function to determine the size of an array
264 * @code{SIZEOF}: SIZEOF, Determine the size in bytes of an expression
265 * @code{SLEEP}: SLEEP, Sleep for the specified number of seconds
266 * @code{SPACING}: SPACING, Smallest distance between two numbers of a given type
267 * @code{SPREAD}: SPREAD, Add a dimension to an array
268 * @code{SQRT}: SQRT, Square-root function
269 * @code{SRAND}: SRAND, Reinitialize the random number generator
270 * @code{STAT}: STAT, Get file status
271 * @code{STORAGE_SIZE}: STORAGE_SIZE, Storage size in bits
272 * @code{SUM}: SUM, Sum of array elements
273 * @code{SYMLNK}: SYMLNK, Create a symbolic link
274 * @code{SYSTEM}: SYSTEM, Execute a shell command
275 * @code{SYSTEM_CLOCK}: SYSTEM_CLOCK, Time function
276 * @code{TAN}: TAN, Tangent function
277 * @code{TANH}: TANH, Hyperbolic tangent function
278 * @code{THIS_IMAGE}: THIS_IMAGE, Cosubscript index of this image
279 * @code{TIME}: TIME, Time function
280 * @code{TIME8}: TIME8, Time function (64-bit)
281 * @code{TINY}: TINY, Smallest positive number of a real kind
282 * @code{TRAILZ}: TRAILZ, Number of trailing zero bits of an integer
283 * @code{TRANSFER}: TRANSFER, Transfer bit patterns
284 * @code{TRANSPOSE}: TRANSPOSE, Transpose an array of rank two
285 * @code{TRIM}: TRIM, Remove trailing blank characters of a string
286 * @code{TTYNAM}: TTYNAM, Get the name of a terminal device.
287 * @code{UBOUND}: UBOUND, Upper dimension bounds of an array
288 * @code{UCOBOUND}: UCOBOUND, Upper codimension bounds of an array
289 * @code{UMASK}: UMASK, Set the file creation mask
290 * @code{UNLINK}: UNLINK, Remove a file from the file system
291 * @code{UNPACK}: UNPACK, Unpack an array of rank one into an array
292 * @code{VERIFY}: VERIFY, Scan a string for the absence of a set of characters
293 * @code{XOR}: XOR, Bitwise logical exclusive or
296 @node Introduction to Intrinsics
297 @section Introduction to intrinsic procedures
299 The intrinsic procedures provided by GNU Fortran include all of the
300 intrinsic procedures required by the Fortran 95 standard, a set of
301 intrinsic procedures for backwards compatibility with G77, and a
302 selection of intrinsic procedures from the Fortran 2003 and Fortran 2008
303 standards. Any conflict between a description here and a description in
304 either the Fortran 95 standard, the Fortran 2003 standard or the Fortran
305 2008 standard is unintentional, and the standard(s) should be considered
308 The enumeration of the @code{KIND} type parameter is processor defined in
309 the Fortran 95 standard. GNU Fortran defines the default integer type and
310 default real type by @code{INTEGER(KIND=4)} and @code{REAL(KIND=4)},
311 respectively. The standard mandates that both data types shall have
312 another kind, which have more precision. On typical target architectures
313 supported by @command{gfortran}, this kind type parameter is @code{KIND=8}.
314 Hence, @code{REAL(KIND=8)} and @code{DOUBLE PRECISION} are equivalent.
315 In the description of generic intrinsic procedures, the kind type parameter
316 will be specified by @code{KIND=*}, and in the description of specific
317 names for an intrinsic procedure the kind type parameter will be explicitly
318 given (e.g., @code{REAL(KIND=4)} or @code{REAL(KIND=8)}). Finally, for
319 brevity the optional @code{KIND=} syntax will be omitted.
321 Many of the intrinsic procedures take one or more optional arguments.
322 This document follows the convention used in the Fortran 95 standard,
323 and denotes such arguments by square brackets.
325 GNU Fortran offers the @option{-std=f95} and @option{-std=gnu} options,
326 which can be used to restrict the set of intrinsic procedures to a
327 given standard. By default, @command{gfortran} sets the @option{-std=gnu}
328 option, and so all intrinsic procedures described here are accepted. There
329 is one caveat. For a select group of intrinsic procedures, @command{g77}
330 implemented both a function and a subroutine. Both classes
331 have been implemented in @command{gfortran} for backwards compatibility
332 with @command{g77}. It is noted here that these functions and subroutines
333 cannot be intermixed in a given subprogram. In the descriptions that follow,
334 the applicable standard for each intrinsic procedure is noted.
339 @section @code{ABORT} --- Abort the program
341 @cindex program termination, with core dump
342 @cindex terminate program, with core dump
346 @item @emph{Description}:
347 @code{ABORT} causes immediate termination of the program. On operating
348 systems that support a core dump, @code{ABORT} will produce a core dump even if
349 the option @option{-fno-dump-core} is in effect, which is suitable for debugging
351 @c TODO: Check if this (with -fno-dump-core) is correct.
353 @item @emph{Standard}:
362 @item @emph{Return value}:
365 @item @emph{Example}:
368 integer :: i = 1, j = 2
369 if (i /= j) call abort
370 end program test_abort
373 @item @emph{See also}:
374 @ref{EXIT}, @ref{KILL}
381 @section @code{ABS} --- Absolute value
388 @cindex absolute value
391 @item @emph{Description}:
392 @code{ABS(A)} computes the absolute value of @code{A}.
394 @item @emph{Standard}:
395 Fortran 77 and later, has overloads that are GNU extensions
401 @code{RESULT = ABS(A)}
403 @item @emph{Arguments}:
404 @multitable @columnfractions .15 .70
405 @item @var{A} @tab The type of the argument shall be an @code{INTEGER},
406 @code{REAL}, or @code{COMPLEX}.
409 @item @emph{Return value}:
410 The return value is of the same type and
411 kind as the argument except the return value is @code{REAL} for a
412 @code{COMPLEX} argument.
414 @item @emph{Example}:
419 complex :: z = (-1.e0,0.e0)
426 @item @emph{Specific names}:
427 @multitable @columnfractions .20 .20 .20 .25
428 @item Name @tab Argument @tab Return type @tab Standard
429 @item @code{ABS(A)} @tab @code{REAL(4) A} @tab @code{REAL(4)} @tab Fortran 77 and later
430 @item @code{CABS(A)} @tab @code{COMPLEX(4) A} @tab @code{REAL(4)} @tab Fortran 77 and later
431 @item @code{DABS(A)} @tab @code{REAL(8) A} @tab @code{REAL(8)} @tab Fortran 77 and later
432 @item @code{IABS(A)} @tab @code{INTEGER(4) A} @tab @code{INTEGER(4)} @tab Fortran 77 and later
433 @item @code{ZABS(A)} @tab @code{COMPLEX(8) A} @tab @code{COMPLEX(8)} @tab GNU extension
434 @item @code{CDABS(A)} @tab @code{COMPLEX(8) A} @tab @code{COMPLEX(8)} @tab GNU extension
441 @section @code{ACCESS} --- Checks file access modes
443 @cindex file system, access mode
446 @item @emph{Description}:
447 @code{ACCESS(NAME, MODE)} checks whether the file @var{NAME}
448 exists, is readable, writable or executable. Except for the
449 executable check, @code{ACCESS} can be replaced by
450 Fortran 95's @code{INQUIRE}.
452 @item @emph{Standard}:
459 @code{RESULT = ACCESS(NAME, MODE)}
461 @item @emph{Arguments}:
462 @multitable @columnfractions .15 .70
463 @item @var{NAME} @tab Scalar @code{CHARACTER} of default kind with the
464 file name. Tailing blank are ignored unless the character @code{achar(0)}
465 is present, then all characters up to and excluding @code{achar(0)} are
467 @item @var{MODE} @tab Scalar @code{CHARACTER} of default kind with the
468 file access mode, may be any concatenation of @code{"r"} (readable),
469 @code{"w"} (writable) and @code{"x"} (executable), or @code{" "} to check
473 @item @emph{Return value}:
474 Returns a scalar @code{INTEGER}, which is @code{0} if the file is
475 accessible in the given mode; otherwise or if an invalid argument
476 has been given for @code{MODE} the value @code{1} is returned.
478 @item @emph{Example}:
482 character(len=*), parameter :: file = 'test.dat'
483 character(len=*), parameter :: file2 = 'test.dat '//achar(0)
484 if(access(file,' ') == 0) print *, trim(file),' is exists'
485 if(access(file,'r') == 0) print *, trim(file),' is readable'
486 if(access(file,'w') == 0) print *, trim(file),' is writable'
487 if(access(file,'x') == 0) print *, trim(file),' is executable'
488 if(access(file2,'rwx') == 0) &
489 print *, trim(file2),' is readable, writable and executable'
490 end program access_test
492 @item @emph{Specific names}:
493 @item @emph{See also}:
500 @section @code{ACHAR} --- Character in @acronym{ASCII} collating sequence
502 @cindex @acronym{ASCII} collating sequence
503 @cindex collating sequence, @acronym{ASCII}
506 @item @emph{Description}:
507 @code{ACHAR(I)} returns the character located at position @code{I}
508 in the @acronym{ASCII} collating sequence.
510 @item @emph{Standard}:
511 Fortran 77 and later, with @var{KIND} argument Fortran 2003 and later
517 @code{RESULT = ACHAR(I [, KIND])}
519 @item @emph{Arguments}:
520 @multitable @columnfractions .15 .70
521 @item @var{I} @tab The type shall be @code{INTEGER}.
522 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
523 expression indicating the kind parameter of the result.
526 @item @emph{Return value}:
527 The return value is of type @code{CHARACTER} with a length of one.
528 If the @var{KIND} argument is present, the return value is of the
529 specified kind and of the default kind otherwise.
531 @item @emph{Example}:
536 end program test_achar
540 See @ref{ICHAR} for a discussion of converting between numerical values
541 and formatted string representations.
543 @item @emph{See also}:
544 @ref{CHAR}, @ref{IACHAR}, @ref{ICHAR}
551 @section @code{ACOS} --- Arccosine function
554 @cindex trigonometric function, cosine, inverse
555 @cindex cosine, inverse
558 @item @emph{Description}:
559 @code{ACOS(X)} computes the arccosine of @var{X} (inverse of @code{COS(X)}).
561 @item @emph{Standard}:
562 Fortran 77 and later, for a complex argument Fortran 2008 or later
568 @code{RESULT = ACOS(X)}
570 @item @emph{Arguments}:
571 @multitable @columnfractions .15 .70
572 @item @var{X} @tab The type shall either be @code{REAL} with a magnitude that is
573 less than or equal to one - or the type shall be @code{COMPLEX}.
576 @item @emph{Return value}:
577 The return value is of the same type and kind as @var{X}.
578 The real part of the result is in radians and lies in the range
579 @math{0 \leq \Re \acos(x) \leq \pi}.
581 @item @emph{Example}:
584 real(8) :: x = 0.866_8
586 end program test_acos
589 @item @emph{Specific names}:
590 @multitable @columnfractions .20 .20 .20 .25
591 @item Name @tab Argument @tab Return type @tab Standard
592 @item @code{ACOS(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab Fortran 77 and later
593 @item @code{DACOS(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab Fortran 77 and later
596 @item @emph{See also}:
597 Inverse function: @ref{COS}
604 @section @code{ACOSH} --- Inverse hyperbolic cosine function
607 @cindex area hyperbolic cosine
608 @cindex inverse hyperbolic cosine
609 @cindex hyperbolic function, cosine, inverse
610 @cindex cosine, hyperbolic, inverse
613 @item @emph{Description}:
614 @code{ACOSH(X)} computes the inverse hyperbolic cosine of @var{X}.
616 @item @emph{Standard}:
617 Fortran 2008 and later
623 @code{RESULT = ACOSH(X)}
625 @item @emph{Arguments}:
626 @multitable @columnfractions .15 .70
627 @item @var{X} @tab The type shall be @code{REAL} or @code{COMPLEX}.
630 @item @emph{Return value}:
631 The return value has the same type and kind as @var{X}. If @var{X} is
632 complex, the imaginary part of the result is in radians and lies between
633 @math{ 0 \leq \Im \acosh(x) \leq \pi}.
635 @item @emph{Example}:
638 REAL(8), DIMENSION(3) :: x = (/ 1.0, 2.0, 3.0 /)
643 @item @emph{Specific names}:
644 @multitable @columnfractions .20 .20 .20 .25
645 @item Name @tab Argument @tab Return type @tab Standard
646 @item @code{DACOSH(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU extension
649 @item @emph{See also}:
650 Inverse function: @ref{COSH}
656 @section @code{ADJUSTL} --- Left adjust a string
658 @cindex string, adjust left
659 @cindex adjust string
662 @item @emph{Description}:
663 @code{ADJUSTL(STRING)} will left adjust a string by removing leading spaces.
664 Spaces are inserted at the end of the string as needed.
666 @item @emph{Standard}:
673 @code{RESULT = ADJUSTL(STRING)}
675 @item @emph{Arguments}:
676 @multitable @columnfractions .15 .70
677 @item @var{STRING} @tab The type shall be @code{CHARACTER}.
680 @item @emph{Return value}:
681 The return value is of type @code{CHARACTER} and of the same kind as
682 @var{STRING} where leading spaces are removed and the same number of
683 spaces are inserted on the end of @var{STRING}.
685 @item @emph{Example}:
688 character(len=20) :: str = ' gfortran'
691 end program test_adjustl
694 @item @emph{See also}:
695 @ref{ADJUSTR}, @ref{TRIM}
701 @section @code{ADJUSTR} --- Right adjust a string
703 @cindex string, adjust right
704 @cindex adjust string
707 @item @emph{Description}:
708 @code{ADJUSTR(STRING)} will right adjust a string by removing trailing spaces.
709 Spaces are inserted at the start of the string as needed.
711 @item @emph{Standard}:
718 @code{RESULT = ADJUSTR(STRING)}
720 @item @emph{Arguments}:
721 @multitable @columnfractions .15 .70
722 @item @var{STR} @tab The type shall be @code{CHARACTER}.
725 @item @emph{Return value}:
726 The return value is of type @code{CHARACTER} and of the same kind as
727 @var{STRING} where trailing spaces are removed and the same number of
728 spaces are inserted at the start of @var{STRING}.
730 @item @emph{Example}:
733 character(len=20) :: str = 'gfortran'
736 end program test_adjustr
739 @item @emph{See also}:
740 @ref{ADJUSTL}, @ref{TRIM}
746 @section @code{AIMAG} --- Imaginary part of complex number
751 @cindex complex numbers, imaginary part
754 @item @emph{Description}:
755 @code{AIMAG(Z)} yields the imaginary part of complex argument @code{Z}.
756 The @code{IMAG(Z)} and @code{IMAGPART(Z)} intrinsic functions are provided
757 for compatibility with @command{g77}, and their use in new code is
758 strongly discouraged.
760 @item @emph{Standard}:
761 Fortran 77 and later, has overloads that are GNU extensions
767 @code{RESULT = AIMAG(Z)}
769 @item @emph{Arguments}:
770 @multitable @columnfractions .15 .70
771 @item @var{Z} @tab The type of the argument shall be @code{COMPLEX}.
774 @item @emph{Return value}:
775 The return value is of type @code{REAL} with the
776 kind type parameter of the argument.
778 @item @emph{Example}:
783 z4 = cmplx(1.e0_4, 0.e0_4)
784 z8 = cmplx(0.e0_8, 1.e0_8)
785 print *, aimag(z4), dimag(z8)
786 end program test_aimag
789 @item @emph{Specific names}:
790 @multitable @columnfractions .20 .20 .20 .25
791 @item Name @tab Argument @tab Return type @tab Standard
792 @item @code{AIMAG(Z)} @tab @code{COMPLEX Z} @tab @code{REAL} @tab GNU extension
793 @item @code{DIMAG(Z)} @tab @code{COMPLEX(8) Z} @tab @code{REAL(8)} @tab GNU extension
794 @item @code{IMAG(Z)} @tab @code{COMPLEX Z} @tab @code{REAL} @tab GNU extension
795 @item @code{IMAGPART(Z)} @tab @code{COMPLEX Z} @tab @code{REAL} @tab GNU extension
802 @section @code{AINT} --- Truncate to a whole number
806 @cindex rounding, floor
809 @item @emph{Description}:
810 @code{AINT(A [, KIND])} truncates its argument to a whole number.
812 @item @emph{Standard}:
819 @code{RESULT = AINT(A [, KIND])}
821 @item @emph{Arguments}:
822 @multitable @columnfractions .15 .70
823 @item @var{A} @tab The type of the argument shall be @code{REAL}.
824 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
825 expression indicating the kind parameter of the result.
828 @item @emph{Return value}:
829 The return value is of type @code{REAL} with the kind type parameter of the
830 argument if the optional @var{KIND} is absent; otherwise, the kind
831 type parameter will be given by @var{KIND}. If the magnitude of
832 @var{X} is less than one, @code{AINT(X)} returns zero. If the
833 magnitude is equal to or greater than one then it returns the largest
834 whole number that does not exceed its magnitude. The sign is the same
835 as the sign of @var{X}.
837 @item @emph{Example}:
844 print *, aint(x4), dint(x8)
846 end program test_aint
849 @item @emph{Specific names}:
850 @multitable @columnfractions .20 .20 .20 .25
851 @item Name @tab Argument @tab Return type @tab Standard
852 @item @code{AINT(A)} @tab @code{REAL(4) A} @tab @code{REAL(4)} @tab Fortran 77 and later
853 @item @code{DINT(A)} @tab @code{REAL(8) A} @tab @code{REAL(8)} @tab Fortran 77 and later
860 @section @code{ALARM} --- Execute a routine after a given delay
862 @cindex delayed execution
865 @item @emph{Description}:
866 @code{ALARM(SECONDS, HANDLER [, STATUS])} causes external subroutine @var{HANDLER}
867 to be executed after a delay of @var{SECONDS} by using @code{alarm(2)} to
868 set up a signal and @code{signal(2)} to catch it. If @var{STATUS} is
869 supplied, it will be returned with the number of seconds remaining until
870 any previously scheduled alarm was due to be delivered, or zero if there
871 was no previously scheduled alarm.
873 @item @emph{Standard}:
880 @code{CALL ALARM(SECONDS, HANDLER [, STATUS])}
882 @item @emph{Arguments}:
883 @multitable @columnfractions .15 .70
884 @item @var{SECONDS} @tab The type of the argument shall be a scalar
885 @code{INTEGER}. It is @code{INTENT(IN)}.
886 @item @var{HANDLER} @tab Signal handler (@code{INTEGER FUNCTION} or
887 @code{SUBROUTINE}) or dummy/global @code{INTEGER} scalar. The scalar
888 values may be either @code{SIG_IGN=1} to ignore the alarm generated
889 or @code{SIG_DFL=0} to set the default action. It is @code{INTENT(IN)}.
890 @item @var{STATUS} @tab (Optional) @var{STATUS} shall be a scalar
891 variable of the default @code{INTEGER} kind. It is @code{INTENT(OUT)}.
894 @item @emph{Example}:
897 external handler_print
899 call alarm (3, handler_print, i)
902 end program test_alarm
904 This will cause the external routine @var{handler_print} to be called
911 @section @code{ALL} --- All values in @var{MASK} along @var{DIM} are true
913 @cindex array, apply condition
914 @cindex array, condition testing
917 @item @emph{Description}:
918 @code{ALL(MASK [, DIM])} determines if all the values are true in @var{MASK}
919 in the array along dimension @var{DIM}.
921 @item @emph{Standard}:
925 Transformational function
928 @code{RESULT = ALL(MASK [, DIM])}
930 @item @emph{Arguments}:
931 @multitable @columnfractions .15 .70
932 @item @var{MASK} @tab The type of the argument shall be @code{LOGICAL} and
933 it shall not be scalar.
934 @item @var{DIM} @tab (Optional) @var{DIM} shall be a scalar integer
935 with a value that lies between one and the rank of @var{MASK}.
938 @item @emph{Return value}:
939 @code{ALL(MASK)} returns a scalar value of type @code{LOGICAL} where
940 the kind type parameter is the same as the kind type parameter of
941 @var{MASK}. If @var{DIM} is present, then @code{ALL(MASK, DIM)} returns
942 an array with the rank of @var{MASK} minus 1. The shape is determined from
943 the shape of @var{MASK} where the @var{DIM} dimension is elided.
947 @code{ALL(MASK)} is true if all elements of @var{MASK} are true.
948 It also is true if @var{MASK} has zero size; otherwise, it is false.
950 If the rank of @var{MASK} is one, then @code{ALL(MASK,DIM)} is equivalent
951 to @code{ALL(MASK)}. If the rank is greater than one, then @code{ALL(MASK,DIM)}
952 is determined by applying @code{ALL} to the array sections.
955 @item @emph{Example}:
959 l = all((/.true., .true., .true./))
964 integer a(2,3), b(2,3)
968 print *, all(a .eq. b, 1)
969 print *, all(a .eq. b, 2)
970 end subroutine section
978 @section @code{ALLOCATED} --- Status of an allocatable entity
980 @cindex allocation, status
983 @item @emph{Description}:
984 @code{ALLOCATED(ARRAY)} and @code{ALLOCATED(SCALAR)} check the allocation
985 status of @var{ARRAY} and @var{SCALAR}, respectively.
987 @item @emph{Standard}:
988 Fortran 95 and later. Note, the @code{SCALAR=} keyword and allocatable
989 scalar entities are available in Fortran 2003 and later.
995 @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{BESSEL_J0} --- Bessel function of the first kind of order 0
1556 @cindex Bessel function, first kind
1559 @item @emph{Description}:
1560 @code{BESSEL_J0(X)} computes the Bessel function of the first kind of
1561 order 0 of @var{X}. This function is available under the name
1562 @code{BESJ0} as a GNU extension.
1564 @item @emph{Standard}:
1565 Fortran 2008 and later
1570 @item @emph{Syntax}:
1571 @code{RESULT = BESSEL_J0(X)}
1573 @item @emph{Arguments}:
1574 @multitable @columnfractions .15 .70
1575 @item @var{X} @tab The type shall be @code{REAL}, and it shall be scalar.
1578 @item @emph{Return value}:
1579 The return value is of type @code{REAL} and lies in the
1580 range @math{ - 0.4027... \leq Bessel (0,x) \leq 1}. It has the same
1583 @item @emph{Example}:
1586 real(8) :: x = 0.0_8
1588 end program test_besj0
1591 @item @emph{Specific names}:
1592 @multitable @columnfractions .20 .20 .20 .25
1593 @item Name @tab Argument @tab Return type @tab Standard
1594 @item @code{DBESJ0(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU extension
1601 @section @code{BESSEL_J1} --- Bessel function of the first kind of order 1
1605 @cindex Bessel function, first kind
1608 @item @emph{Description}:
1609 @code{BESSEL_J1(X)} computes the Bessel function of the first kind of
1610 order 1 of @var{X}. This function is available under the name
1611 @code{BESJ1} as a GNU extension.
1613 @item @emph{Standard}:
1619 @item @emph{Syntax}:
1620 @code{RESULT = BESSEL_J1(X)}
1622 @item @emph{Arguments}:
1623 @multitable @columnfractions .15 .70
1624 @item @var{X} @tab The type shall be @code{REAL}, and it shall be scalar.
1627 @item @emph{Return value}:
1628 The return value is of type @code{REAL} and it lies in the
1629 range @math{ - 0.5818... \leq Bessel (0,x) \leq 0.5818 }. It has the same
1632 @item @emph{Example}:
1635 real(8) :: x = 1.0_8
1637 end program test_besj1
1640 @item @emph{Specific names}:
1641 @multitable @columnfractions .20 .20 .20 .25
1642 @item Name @tab Argument @tab Return type @tab Standard
1643 @item @code{DBESJ1(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU extension
1650 @section @code{BESSEL_JN} --- Bessel function of the first kind
1654 @cindex Bessel function, first kind
1657 @item @emph{Description}:
1658 @code{BESSEL_JN(N, X)} computes the Bessel function of the first kind of
1659 order @var{N} of @var{X}. This function is available under the name
1660 @code{BESJN} as a GNU extension. If @var{N} and @var{X} are arrays,
1661 their ranks and shapes shall conform.
1663 @code{BESSEL_JN(N1, N2, X)} returns an array with the Bessel functions
1664 of the first kind of the orders @var{N1} to @var{N2}.
1666 @item @emph{Standard}:
1667 Fortran 2008 and later, negative @var{N} is allowed as GNU extension
1670 Elemental function, except for the transformational function
1671 @code{BESSEL_JN(N1, N2, X)}
1673 @item @emph{Syntax}:
1674 @multitable @columnfractions .80
1675 @item @code{RESULT = BESSEL_JN(N, X)}
1676 @item @code{RESULT = BESSEL_JN(N1, N2, X)}
1679 @item @emph{Arguments}:
1680 @multitable @columnfractions .15 .70
1681 @item @var{N} @tab Shall be a scalar or an array of type @code{INTEGER}.
1682 @item @var{N1} @tab Shall be a non-negative scalar of type @code{INTEGER}.
1683 @item @var{N2} @tab Shall be a non-negative scalar of type @code{INTEGER}.
1684 @item @var{X} @tab Shall be a scalar or an array of type @code{REAL};
1685 for @code{BESSEL_JN(N1, N2, X)} it shall be scalar.
1688 @item @emph{Return value}:
1689 The return value is a scalar of type @code{REAL}. It has the same
1693 The transformational function uses a recurrence algorithm which might,
1694 for some values of @var{X}, lead to different results than calls to
1695 the elemental function.
1697 @item @emph{Example}:
1700 real(8) :: x = 1.0_8
1702 end program test_besjn
1705 @item @emph{Specific names}:
1706 @multitable @columnfractions .20 .20 .20 .25
1707 @item Name @tab Argument @tab Return type @tab Standard
1708 @item @code{DBESJN(N, X)} @tab @code{INTEGER N} @tab @code{REAL(8)} @tab GNU extension
1709 @item @tab @code{REAL(8) X} @tab @tab
1716 @section @code{BESSEL_Y0} --- Bessel function of the second kind of order 0
1720 @cindex Bessel function, second kind
1723 @item @emph{Description}:
1724 @code{BESSEL_Y0(X)} computes the Bessel function of the second kind of
1725 order 0 of @var{X}. This function is available under the name
1726 @code{BESY0} as a GNU extension.
1728 @item @emph{Standard}:
1729 Fortran 2008 and later
1734 @item @emph{Syntax}:
1735 @code{RESULT = BESSEL_Y0(X)}
1737 @item @emph{Arguments}:
1738 @multitable @columnfractions .15 .70
1739 @item @var{X} @tab The type shall be @code{REAL}, and it shall be scalar.
1742 @item @emph{Return value}:
1743 The return value is a scalar of type @code{REAL}. It has the same
1746 @item @emph{Example}:
1749 real(8) :: x = 0.0_8
1751 end program test_besy0
1754 @item @emph{Specific names}:
1755 @multitable @columnfractions .20 .20 .20 .25
1756 @item Name @tab Argument @tab Return type @tab Standard
1757 @item @code{DBESY0(X)}@tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU extension
1764 @section @code{BESSEL_Y1} --- Bessel function of the second kind of order 1
1768 @cindex Bessel function, second kind
1771 @item @emph{Description}:
1772 @code{BESSEL_Y1(X)} computes the Bessel function of the second kind of
1773 order 1 of @var{X}. This function is available under the name
1774 @code{BESY1} as a GNU extension.
1776 @item @emph{Standard}:
1777 Fortran 2008 and later
1782 @item @emph{Syntax}:
1783 @code{RESULT = BESSEL_Y1(X)}
1785 @item @emph{Arguments}:
1786 @multitable @columnfractions .15 .70
1787 @item @var{X} @tab The type shall be @code{REAL}, and it shall be scalar.
1790 @item @emph{Return value}:
1791 The return value is a scalar of type @code{REAL}. It has the same
1794 @item @emph{Example}:
1797 real(8) :: x = 1.0_8
1799 end program test_besy1
1802 @item @emph{Specific names}:
1803 @multitable @columnfractions .20 .20 .20 .25
1804 @item Name @tab Argument @tab Return type @tab Standard
1805 @item @code{DBESY1(X)}@tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU extension
1812 @section @code{BESSEL_YN} --- Bessel function of the second kind
1816 @cindex Bessel function, second kind
1819 @item @emph{Description}:
1820 @code{BESSEL_YN(N, X)} computes the Bessel function of the second kind of
1821 order @var{N} of @var{X}. This function is available under the name
1822 @code{BESYN} as a GNU extension. If @var{N} and @var{X} are arrays,
1823 their ranks and shapes shall conform.
1825 @code{BESSEL_YN(N1, N2, X)} returns an array with the Bessel functions
1826 of the first kind of the orders @var{N1} to @var{N2}.
1828 @item @emph{Standard}:
1829 Fortran 2008 and later, negative @var{N} is allowed as GNU extension
1832 Elemental function, except for the transformational function
1833 @code{BESSEL_YN(N1, N2, X)}
1835 @item @emph{Syntax}:
1836 @multitable @columnfractions .80
1837 @item @code{RESULT = BESSEL_YN(N, X)}
1838 @item @code{RESULT = BESSEL_YN(N1, N2, X)}
1841 @item @emph{Arguments}:
1842 @multitable @columnfractions .15 .70
1843 @item @var{N} @tab Shall be a scalar or an array of type @code{INTEGER} .
1844 @item @var{N1} @tab Shall be a non-negative scalar of type @code{INTEGER}.
1845 @item @var{N2} @tab Shall be a non-negative scalar of type @code{INTEGER}.
1846 @item @var{X} @tab Shall be a scalar or an array of type @code{REAL};
1847 for @code{BESSEL_YN(N1, N2, X)} it shall be scalar.
1850 @item @emph{Return value}:
1851 The return value is a scalar of type @code{REAL}. It has the same
1855 The transformational function uses a recurrence algorithm which might,
1856 for some values of @var{X}, lead to different results than calls to
1857 the elemental function.
1859 @item @emph{Example}:
1862 real(8) :: x = 1.0_8
1864 end program test_besyn
1867 @item @emph{Specific names}:
1868 @multitable @columnfractions .20 .20 .20 .25
1869 @item Name @tab Argument @tab Return type @tab Standard
1870 @item @code{DBESYN(N,X)} @tab @code{INTEGER N} @tab @code{REAL(8)} @tab GNU extension
1871 @item @tab @code{REAL(8) X} @tab @tab
1878 @section @code{BGE} --- Bitwise greater than or equal to
1880 @cindex bitwise comparison
1883 @item @emph{Description}:
1884 Determines whether an integral is a bitwise greater than or equal to
1887 @item @emph{Standard}:
1888 Fortran 2008 and later
1893 @item @emph{Syntax}:
1894 @code{RESULT = BGE(I, J)}
1896 @item @emph{Arguments}:
1897 @multitable @columnfractions .15 .70
1898 @item @var{I} @tab Shall be of @code{INTEGER} type.
1899 @item @var{J} @tab Shall be of @code{INTEGER} type, and of the same kind
1903 @item @emph{Return value}:
1904 The return value is of type @code{LOGICAL} and of the default kind.
1906 @item @emph{See also}:
1907 @ref{BGT}, @ref{BLE}, @ref{BLT}
1913 @section @code{BGT} --- Bitwise greater than
1915 @cindex bitwise comparison
1918 @item @emph{Description}:
1919 Determines whether an integral is a bitwise greater than another.
1921 @item @emph{Standard}:
1922 Fortran 2008 and later
1927 @item @emph{Syntax}:
1928 @code{RESULT = BGT(I, J)}
1930 @item @emph{Arguments}:
1931 @multitable @columnfractions .15 .70
1932 @item @var{I} @tab Shall be of @code{INTEGER} type.
1933 @item @var{J} @tab Shall be of @code{INTEGER} type, and of the same kind
1937 @item @emph{Return value}:
1938 The return value is of type @code{LOGICAL} and of the default kind.
1940 @item @emph{See also}:
1941 @ref{BGE}, @ref{BLE}, @ref{BLT}
1947 @section @code{BIT_SIZE} --- Bit size inquiry function
1949 @cindex bits, number of
1950 @cindex size of a variable, in bits
1953 @item @emph{Description}:
1954 @code{BIT_SIZE(I)} returns the number of bits (integer precision plus sign bit)
1955 represented by the type of @var{I}. The result of @code{BIT_SIZE(I)} is
1956 independent of the actual value of @var{I}.
1958 @item @emph{Standard}:
1959 Fortran 95 and later
1964 @item @emph{Syntax}:
1965 @code{RESULT = BIT_SIZE(I)}
1967 @item @emph{Arguments}:
1968 @multitable @columnfractions .15 .70
1969 @item @var{I} @tab The type shall be @code{INTEGER}.
1972 @item @emph{Return value}:
1973 The return value is of type @code{INTEGER}
1975 @item @emph{Example}:
1977 program test_bit_size
1982 end program test_bit_size
1989 @section @code{BLE} --- Bitwise less than or equal to
1991 @cindex bitwise comparison
1994 @item @emph{Description}:
1995 Determines whether an integral is a bitwise less than or equal to
1998 @item @emph{Standard}:
1999 Fortran 2008 and later
2004 @item @emph{Syntax}:
2005 @code{RESULT = BLE(I, J)}
2007 @item @emph{Arguments}:
2008 @multitable @columnfractions .15 .70
2009 @item @var{I} @tab Shall be of @code{INTEGER} type.
2010 @item @var{J} @tab Shall be of @code{INTEGER} type, and of the same kind
2014 @item @emph{Return value}:
2015 The return value is of type @code{LOGICAL} and of the default kind.
2017 @item @emph{See also}:
2018 @ref{BGT}, @ref{BGE}, @ref{BLT}
2024 @section @code{BLT} --- Bitwise less than
2026 @cindex bitwise comparison
2029 @item @emph{Description}:
2030 Determines whether an integral is a bitwise less than another.
2032 @item @emph{Standard}:
2033 Fortran 2008 and later
2038 @item @emph{Syntax}:
2039 @code{RESULT = BLT(I, J)}
2041 @item @emph{Arguments}:
2042 @multitable @columnfractions .15 .70
2043 @item @var{I} @tab Shall be of @code{INTEGER} type.
2044 @item @var{J} @tab Shall be of @code{INTEGER} type, and of the same kind
2048 @item @emph{Return value}:
2049 The return value is of type @code{LOGICAL} and of the default kind.
2051 @item @emph{See also}:
2052 @ref{BGE}, @ref{BGT}, @ref{BLE}
2058 @section @code{BTEST} --- Bit test function
2060 @cindex bits, testing
2063 @item @emph{Description}:
2064 @code{BTEST(I,POS)} returns logical @code{.TRUE.} if the bit at @var{POS}
2065 in @var{I} is set. The counting of the bits starts at 0.
2067 @item @emph{Standard}:
2068 Fortran 95 and later
2073 @item @emph{Syntax}:
2074 @code{RESULT = BTEST(I, POS)}
2076 @item @emph{Arguments}:
2077 @multitable @columnfractions .15 .70
2078 @item @var{I} @tab The type shall be @code{INTEGER}.
2079 @item @var{POS} @tab The type shall be @code{INTEGER}.
2082 @item @emph{Return value}:
2083 The return value is of type @code{LOGICAL}
2085 @item @emph{Example}:
2088 integer :: i = 32768 + 1024 + 64
2092 bool = btest(i, pos)
2095 end program test_btest
2101 @section @code{C_ASSOCIATED} --- Status of a C pointer
2102 @fnindex C_ASSOCIATED
2103 @cindex association status, C pointer
2104 @cindex pointer, C association status
2107 @item @emph{Description}:
2108 @code{C_ASSOCIATED(c_prt_1[, c_ptr_2])} determines the status of the C pointer
2109 @var{c_ptr_1} or if @var{c_ptr_1} is associated with the target @var{c_ptr_2}.
2111 @item @emph{Standard}:
2112 Fortran 2003 and later
2117 @item @emph{Syntax}:
2118 @code{RESULT = C_ASSOCIATED(c_prt_1[, c_ptr_2])}
2120 @item @emph{Arguments}:
2121 @multitable @columnfractions .15 .70
2122 @item @var{c_ptr_1} @tab Scalar of the type @code{C_PTR} or @code{C_FUNPTR}.
2123 @item @var{c_ptr_2} @tab (Optional) Scalar of the same type as @var{c_ptr_1}.
2126 @item @emph{Return value}:
2127 The return value is of type @code{LOGICAL}; it is @code{.false.} if either
2128 @var{c_ptr_1} is a C NULL pointer or if @var{c_ptr1} and @var{c_ptr_2}
2129 point to different addresses.
2131 @item @emph{Example}:
2133 subroutine association_test(a,b)
2134 use iso_c_binding, only: c_associated, c_loc, c_ptr
2138 if(c_associated(b, c_loc(a))) &
2139 stop 'b and a do not point to same target'
2140 end subroutine association_test
2143 @item @emph{See also}:
2144 @ref{C_LOC}, @ref{C_FUNLOC}
2149 @section @code{C_FUNLOC} --- Obtain the C address of a procedure
2151 @cindex pointer, C address of procedures
2154 @item @emph{Description}:
2155 @code{C_FUNLOC(x)} determines the C address of the argument.
2157 @item @emph{Standard}:
2158 Fortran 2003 and later
2163 @item @emph{Syntax}:
2164 @code{RESULT = C_FUNLOC(x)}
2166 @item @emph{Arguments}:
2167 @multitable @columnfractions .15 .70
2168 @item @var{x} @tab Interoperable function or pointer to such function.
2171 @item @emph{Return value}:
2172 The return value is of type @code{C_FUNPTR} and contains the C address
2175 @item @emph{Example}:
2181 subroutine sub(a) bind(c)
2191 subroutine my_routine(p) bind(c,name='myC_func')
2193 type(c_funptr), intent(in) :: p
2196 call my_routine(c_funloc(sub))
2200 @item @emph{See also}:
2201 @ref{C_ASSOCIATED}, @ref{C_LOC}, @ref{C_F_POINTER}, @ref{C_F_PROCPOINTER}
2205 @node C_F_PROCPOINTER
2206 @section @code{C_F_PROCPOINTER} --- Convert C into Fortran procedure pointer
2207 @fnindex C_F_PROCPOINTER
2208 @cindex pointer, C address of pointers
2211 @item @emph{Description}:
2212 @code{C_F_PROCPOINTER(CPTR, FPTR)} Assign the target of the C function pointer
2213 @var{CPTR} to the Fortran procedure pointer @var{FPTR}.
2215 @item @emph{Standard}:
2216 Fortran 2003 and later
2221 @item @emph{Syntax}:
2222 @code{CALL C_F_PROCPOINTER(cptr, fptr)}
2224 @item @emph{Arguments}:
2225 @multitable @columnfractions .15 .70
2226 @item @var{CPTR} @tab scalar of the type @code{C_FUNPTR}. It is
2228 @item @var{FPTR} @tab procedure pointer interoperable with @var{cptr}. It is
2232 @item @emph{Example}:
2240 real(c_float), intent(in) :: a
2241 real(c_float) :: func
2245 function getIterFunc() bind(c,name="getIterFunc")
2247 type(c_funptr) :: getIterFunc
2250 type(c_funptr) :: cfunptr
2251 procedure(func), pointer :: myFunc
2252 cfunptr = getIterFunc()
2253 call c_f_procpointer(cfunptr, myFunc)
2257 @item @emph{See also}:
2258 @ref{C_LOC}, @ref{C_F_POINTER}
2263 @section @code{C_F_POINTER} --- Convert C into Fortran pointer
2264 @fnindex C_F_POINTER
2265 @cindex pointer, convert C to Fortran
2268 @item @emph{Description}:
2269 @code{C_F_POINTER(CPTR, FPTR[, SHAPE])} Assign the target the C pointer
2270 @var{CPTR} to the Fortran pointer @var{FPTR} and specify its
2273 @item @emph{Standard}:
2274 Fortran 2003 and later
2279 @item @emph{Syntax}:
2280 @code{CALL C_F_POINTER(CPTR, FPTR[, SHAPE])}
2282 @item @emph{Arguments}:
2283 @multitable @columnfractions .15 .70
2284 @item @var{CPTR} @tab scalar of the type @code{C_PTR}. It is
2286 @item @var{FPTR} @tab pointer interoperable with @var{cptr}. It is
2288 @item @var{SHAPE} @tab (Optional) Rank-one array of type @code{INTEGER}
2289 with @code{INTENT(IN)}. It shall be present
2290 if and only if @var{fptr} is an array. The size
2291 must be equal to the rank of @var{fptr}.
2294 @item @emph{Example}:
2300 subroutine my_routine(p) bind(c,name='myC_func')
2302 type(c_ptr), intent(out) :: p
2306 real,pointer :: a(:)
2307 call my_routine(cptr)
2308 call c_f_pointer(cptr, a, [12])
2312 @item @emph{See also}:
2313 @ref{C_LOC}, @ref{C_F_PROCPOINTER}
2318 @section @code{C_LOC} --- Obtain the C address of an object
2320 @cindex procedure pointer, convert C to Fortran
2323 @item @emph{Description}:
2324 @code{C_LOC(X)} determines the C address of the argument.
2326 @item @emph{Standard}:
2327 Fortran 2003 and later
2332 @item @emph{Syntax}:
2333 @code{RESULT = C_LOC(X)}
2335 @item @emph{Arguments}:
2336 @multitable @columnfractions .10 .75
2337 @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.
2341 @item @emph{Return value}:
2342 The return value is of type @code{C_PTR} and contains the C address
2345 @item @emph{Example}:
2347 subroutine association_test(a,b)
2348 use iso_c_binding, only: c_associated, c_loc, c_ptr
2352 if(c_associated(b, c_loc(a))) &
2353 stop 'b and a do not point to same target'
2354 end subroutine association_test
2357 @item @emph{See also}:
2358 @ref{C_ASSOCIATED}, @ref{C_FUNLOC}, @ref{C_F_POINTER}, @ref{C_F_PROCPOINTER}
2363 @section @code{C_SIZEOF} --- Size in bytes of an expression
2365 @cindex expression size
2366 @cindex size of an expression
2369 @item @emph{Description}:
2370 @code{C_SIZEOF(X)} calculates the number of bytes of storage the
2371 expression @code{X} occupies.
2373 @item @emph{Standard}:
2377 Inquiry function of the module @code{ISO_C_BINDING}
2379 @item @emph{Syntax}:
2380 @code{N = C_SIZEOF(X)}
2382 @item @emph{Arguments}:
2383 @multitable @columnfractions .15 .70
2384 @item @var{X} @tab The argument shall be an interoperable data entity.
2387 @item @emph{Return value}:
2388 The return value is of type integer and of the system-dependent kind
2389 @code{C_SIZE_T} (from the @code{ISO_C_BINDING} module). Its value is the
2390 number of bytes occupied by the argument. If the argument has the
2391 @code{POINTER} attribute, the number of bytes of the storage area pointed
2392 to is returned. If the argument is of a derived type with @code{POINTER}
2393 or @code{ALLOCATABLE} components, the return value doesn't account for
2394 the sizes of the data pointed to by these components.
2396 @item @emph{Example}:
2400 real(c_float) :: r, s(5)
2401 print *, (c_sizeof(s)/c_sizeof(r) == 5)
2404 The example will print @code{.TRUE.} unless you are using a platform
2405 where default @code{REAL} variables are unusually padded.
2407 @item @emph{See also}:
2408 @ref{SIZEOF}, @ref{STORAGE_SIZE}
2413 @section @code{CEILING} --- Integer ceiling function
2416 @cindex rounding, ceiling
2419 @item @emph{Description}:
2420 @code{CEILING(A)} returns the least integer greater than or equal to @var{A}.
2422 @item @emph{Standard}:
2423 Fortran 95 and later
2428 @item @emph{Syntax}:
2429 @code{RESULT = CEILING(A [, KIND])}
2431 @item @emph{Arguments}:
2432 @multitable @columnfractions .15 .70
2433 @item @var{A} @tab The type shall be @code{REAL}.
2434 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
2435 expression indicating the kind parameter of the result.
2438 @item @emph{Return value}:
2439 The return value is of type @code{INTEGER(KIND)} if @var{KIND} is present
2440 and a default-kind @code{INTEGER} otherwise.
2442 @item @emph{Example}:
2444 program test_ceiling
2447 print *, ceiling(x) ! returns 64
2448 print *, ceiling(y) ! returns -63
2449 end program test_ceiling
2452 @item @emph{See also}:
2453 @ref{FLOOR}, @ref{NINT}
2460 @section @code{CHAR} --- Character conversion function
2462 @cindex conversion, to character
2465 @item @emph{Description}:
2466 @code{CHAR(I [, KIND])} returns the character represented by the integer @var{I}.
2468 @item @emph{Standard}:
2469 Fortran 77 and later
2474 @item @emph{Syntax}:
2475 @code{RESULT = CHAR(I [, KIND])}
2477 @item @emph{Arguments}:
2478 @multitable @columnfractions .15 .70
2479 @item @var{I} @tab The type shall be @code{INTEGER}.
2480 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
2481 expression indicating the kind parameter of the result.
2484 @item @emph{Return value}:
2485 The return value is of type @code{CHARACTER(1)}
2487 @item @emph{Example}:
2493 print *, i, c ! returns 'J'
2494 end program test_char
2497 @item @emph{Specific names}:
2498 @multitable @columnfractions .20 .20 .20 .25
2499 @item Name @tab Argument @tab Return type @tab Standard
2500 @item @code{CHAR(I)} @tab @code{INTEGER I} @tab @code{CHARACTER(LEN=1)} @tab F77 and later
2504 See @ref{ICHAR} for a discussion of converting between numerical values
2505 and formatted string representations.
2507 @item @emph{See also}:
2508 @ref{ACHAR}, @ref{IACHAR}, @ref{ICHAR}
2515 @section @code{CHDIR} --- Change working directory
2517 @cindex system, working directory
2520 @item @emph{Description}:
2521 Change current working directory to a specified path.
2523 This intrinsic is provided in both subroutine and function forms; however,
2524 only one form can be used in any given program unit.
2526 @item @emph{Standard}:
2530 Subroutine, function
2532 @item @emph{Syntax}:
2533 @multitable @columnfractions .80
2534 @item @code{CALL CHDIR(NAME [, STATUS])}
2535 @item @code{STATUS = CHDIR(NAME)}
2538 @item @emph{Arguments}:
2539 @multitable @columnfractions .15 .70
2540 @item @var{NAME} @tab The type shall be @code{CHARACTER} of default
2541 kind and shall specify a valid path within the file system.
2542 @item @var{STATUS} @tab (Optional) @code{INTEGER} status flag of the default
2543 kind. Returns 0 on success, and a system specific and nonzero error code
2547 @item @emph{Example}:
2550 CHARACTER(len=255) :: path
2552 WRITE(*,*) TRIM(path)
2555 WRITE(*,*) TRIM(path)
2559 @item @emph{See also}:
2566 @section @code{CHMOD} --- Change access permissions of files
2568 @cindex file system, change access mode
2571 @item @emph{Description}:
2572 @code{CHMOD} changes the permissions of a file. This function invokes
2573 @code{/bin/chmod} and might therefore not work on all platforms.
2575 This intrinsic is provided in both subroutine and function forms; however,
2576 only one form can be used in any given program unit.
2578 @item @emph{Standard}:
2582 Subroutine, function
2584 @item @emph{Syntax}:
2585 @multitable @columnfractions .80
2586 @item @code{CALL CHMOD(NAME, MODE[, STATUS])}
2587 @item @code{STATUS = CHMOD(NAME, MODE)}
2590 @item @emph{Arguments}:
2591 @multitable @columnfractions .15 .70
2593 @item @var{NAME} @tab Scalar @code{CHARACTER} of default kind with the
2594 file name. Trailing blanks are ignored unless the character
2595 @code{achar(0)} is present, then all characters up to and excluding
2596 @code{achar(0)} are used as the file name.
2598 @item @var{MODE} @tab Scalar @code{CHARACTER} of default kind giving the
2599 file permission. @var{MODE} uses the same syntax as the @var{MODE}
2600 argument of @code{/bin/chmod}.
2602 @item @var{STATUS} @tab (optional) scalar @code{INTEGER}, which is
2603 @code{0} on success and nonzero otherwise.
2606 @item @emph{Return value}:
2607 In either syntax, @var{STATUS} is set to @code{0} on success and nonzero
2610 @item @emph{Example}:
2611 @code{CHMOD} as subroutine
2616 call chmod('test.dat','u+x',status)
2617 print *, 'Status: ', status
2618 end program chmod_test
2620 @code{CHMOD} as function:
2625 status = chmod('test.dat','u+x')
2626 print *, 'Status: ', status
2627 end program chmod_test
2635 @section @code{CMPLX} --- Complex conversion function
2637 @cindex complex numbers, conversion to
2638 @cindex conversion, to complex
2641 @item @emph{Description}:
2642 @code{CMPLX(X [, Y [, KIND]])} returns a complex number where @var{X} is converted to
2643 the real component. If @var{Y} is present it is converted to the imaginary
2644 component. If @var{Y} is not present then the imaginary component is set to
2645 0.0. If @var{X} is complex then @var{Y} must not be present.
2647 @item @emph{Standard}:
2648 Fortran 77 and later
2653 @item @emph{Syntax}:
2654 @code{RESULT = CMPLX(X [, Y [, KIND]])}
2656 @item @emph{Arguments}:
2657 @multitable @columnfractions .15 .70
2658 @item @var{X} @tab The type may be @code{INTEGER}, @code{REAL},
2660 @item @var{Y} @tab (Optional; only allowed if @var{X} is not
2661 @code{COMPLEX}.) May be @code{INTEGER} or @code{REAL}.
2662 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
2663 expression indicating the kind parameter of the result.
2666 @item @emph{Return value}:
2667 The return value is of @code{COMPLEX} type, with a kind equal to
2668 @var{KIND} if it is specified. If @var{KIND} is not specified, the
2669 result is of the default @code{COMPLEX} kind, regardless of the kinds of
2670 @var{X} and @var{Y}.
2672 @item @emph{Example}:
2679 print *, z, cmplx(x)
2680 end program test_cmplx
2683 @item @emph{See also}:
2689 @node COMMAND_ARGUMENT_COUNT
2690 @section @code{COMMAND_ARGUMENT_COUNT} --- Get number of command line arguments
2691 @fnindex COMMAND_ARGUMENT_COUNT
2692 @cindex command-line arguments
2693 @cindex command-line arguments, number of
2694 @cindex arguments, to program
2697 @item @emph{Description}:
2698 @code{COMMAND_ARGUMENT_COUNT} returns the number of arguments passed on the
2699 command line when the containing program was invoked.
2701 @item @emph{Standard}:
2702 Fortran 2003 and later
2707 @item @emph{Syntax}:
2708 @code{RESULT = COMMAND_ARGUMENT_COUNT()}
2710 @item @emph{Arguments}:
2711 @multitable @columnfractions .15 .70
2715 @item @emph{Return value}:
2716 The return value is an @code{INTEGER} of default kind.
2718 @item @emph{Example}:
2720 program test_command_argument_count
2722 count = command_argument_count()
2724 end program test_command_argument_count
2727 @item @emph{See also}:
2728 @ref{GET_COMMAND}, @ref{GET_COMMAND_ARGUMENT}
2733 @node COMPILER_OPTIONS
2734 @section @code{COMPILER_OPTIONS} --- Options passed to the compiler
2735 @fnindex COMPILER_OPTIONS
2736 @cindex flags inquiry function
2737 @cindex options inquiry function
2738 @cindex compiler flags inquiry function
2741 @item @emph{Description}:
2742 @code{COMPILER_OPTIONS} returns a string with the options used for
2745 @item @emph{Standard}:
2749 Inquiry function of the module @code{ISO_FORTRAN_ENV}
2751 @item @emph{Syntax}:
2752 @code{STR = COMPILER_OPTIONS()}
2754 @item @emph{Arguments}:
2757 @item @emph{Return value}:
2758 The return value is a default-kind string with system-dependent length.
2759 It contains the compiler flags used to compile the file, which called
2760 the @code{COMPILER_OPTIONS} intrinsic.
2762 @item @emph{Example}:
2765 print '(4a)', 'This file was compiled by ', &
2766 compiler_version(), ' using the options ', &
2771 @item @emph{See also}:
2772 @ref{COMPILER_VERSION}, @ref{ISO_FORTRAN_ENV}
2777 @node COMPILER_VERSION
2778 @section @code{COMPILER_VERSION} --- Compiler version string
2779 @fnindex COMPILER_VERSION
2780 @cindex compiler, name and version
2781 @cindex version of the compiler
2784 @item @emph{Description}:
2785 @code{COMPILER_VERSION} returns a string with the name and the
2786 version of the compiler.
2788 @item @emph{Standard}:
2792 Inquiry function of the module @code{ISO_FORTRAN_ENV}
2794 @item @emph{Syntax}:
2795 @code{STR = COMPILER_VERSION()}
2797 @item @emph{Arguments}:
2800 @item @emph{Return value}:
2801 The return value is a default-kind string with system-dependent length.
2802 It contains the name of the compiler and its version number.
2804 @item @emph{Example}:
2807 print '(4a)', 'This file was compiled by ', &
2808 compiler_version(), ' using the options ', &
2813 @item @emph{See also}:
2814 @ref{COMPILER_OPTIONS}, @ref{ISO_FORTRAN_ENV}
2820 @section @code{COMPLEX} --- Complex conversion function
2822 @cindex complex numbers, conversion to
2823 @cindex conversion, to complex
2826 @item @emph{Description}:
2827 @code{COMPLEX(X, Y)} returns a complex number where @var{X} is converted
2828 to the real component and @var{Y} is converted to the imaginary
2831 @item @emph{Standard}:
2837 @item @emph{Syntax}:
2838 @code{RESULT = COMPLEX(X, Y)}
2840 @item @emph{Arguments}:
2841 @multitable @columnfractions .15 .70
2842 @item @var{X} @tab The type may be @code{INTEGER} or @code{REAL}.
2843 @item @var{Y} @tab The type may be @code{INTEGER} or @code{REAL}.
2846 @item @emph{Return value}:
2847 If @var{X} and @var{Y} are both of @code{INTEGER} type, then the return
2848 value is of default @code{COMPLEX} type.
2850 If @var{X} and @var{Y} are of @code{REAL} type, or one is of @code{REAL}
2851 type and one is of @code{INTEGER} type, then the return value is of
2852 @code{COMPLEX} type with a kind equal to that of the @code{REAL}
2853 argument with the highest precision.
2855 @item @emph{Example}:
2857 program test_complex
2860 print *, complex(i, x)
2861 end program test_complex
2864 @item @emph{See also}:
2871 @section @code{CONJG} --- Complex conjugate function
2874 @cindex complex conjugate
2877 @item @emph{Description}:
2878 @code{CONJG(Z)} returns the conjugate of @var{Z}. If @var{Z} is @code{(x, y)}
2879 then the result is @code{(x, -y)}
2881 @item @emph{Standard}:
2882 Fortran 77 and later, has overloads that are GNU extensions
2887 @item @emph{Syntax}:
2890 @item @emph{Arguments}:
2891 @multitable @columnfractions .15 .70
2892 @item @var{Z} @tab The type shall be @code{COMPLEX}.
2895 @item @emph{Return value}:
2896 The return value is of type @code{COMPLEX}.
2898 @item @emph{Example}:
2901 complex :: z = (2.0, 3.0)
2902 complex(8) :: dz = (2.71_8, -3.14_8)
2907 end program test_conjg
2910 @item @emph{Specific names}:
2911 @multitable @columnfractions .20 .20 .20 .25
2912 @item Name @tab Argument @tab Return type @tab Standard
2913 @item @code{CONJG(Z)} @tab @code{COMPLEX Z} @tab @code{COMPLEX} @tab GNU extension
2914 @item @code{DCONJG(Z)} @tab @code{COMPLEX(8) Z} @tab @code{COMPLEX(8)} @tab GNU extension
2921 @section @code{COS} --- Cosine function
2927 @cindex trigonometric function, cosine
2931 @item @emph{Description}:
2932 @code{COS(X)} computes the cosine of @var{X}.
2934 @item @emph{Standard}:
2935 Fortran 77 and later, has overloads that are GNU extensions
2940 @item @emph{Syntax}:
2941 @code{RESULT = COS(X)}
2943 @item @emph{Arguments}:
2944 @multitable @columnfractions .15 .70
2945 @item @var{X} @tab The type shall be @code{REAL} or
2949 @item @emph{Return value}:
2950 The return value is of the same type and kind as @var{X}. The real part
2951 of the result is in radians. If @var{X} is of the type @code{REAL},
2952 the return value lies in the range @math{ -1 \leq \cos (x) \leq 1}.
2954 @item @emph{Example}:
2959 end program test_cos
2962 @item @emph{Specific names}:
2963 @multitable @columnfractions .20 .20 .20 .25
2964 @item Name @tab Argument @tab Return type @tab Standard
2965 @item @code{COS(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab Fortran 77 and later
2966 @item @code{DCOS(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab Fortran 77 and later
2967 @item @code{CCOS(X)} @tab @code{COMPLEX(4) X} @tab @code{COMPLEX(4)} @tab Fortran 77 and later
2968 @item @code{ZCOS(X)} @tab @code{COMPLEX(8) X} @tab @code{COMPLEX(8)} @tab GNU extension
2969 @item @code{CDCOS(X)} @tab @code{COMPLEX(8) X} @tab @code{COMPLEX(8)} @tab GNU extension
2972 @item @emph{See also}:
2973 Inverse function: @ref{ACOS}
2980 @section @code{COSH} --- Hyperbolic cosine function
2983 @cindex hyperbolic cosine
2984 @cindex hyperbolic function, cosine
2985 @cindex cosine, hyperbolic
2988 @item @emph{Description}:
2989 @code{COSH(X)} computes the hyperbolic cosine of @var{X}.
2991 @item @emph{Standard}:
2992 Fortran 77 and later, for a complex argument Fortran 2008 or later
2997 @item @emph{Syntax}:
3000 @item @emph{Arguments}:
3001 @multitable @columnfractions .15 .70
3002 @item @var{X} @tab The type shall be @code{REAL} or @code{COMPLEX}.
3005 @item @emph{Return value}:
3006 The return value has same type and kind as @var{X}. If @var{X} is
3007 complex, the imaginary part of the result is in radians. If @var{X}
3008 is @code{REAL}, the return value has a lower bound of one,
3009 @math{\cosh (x) \geq 1}.
3011 @item @emph{Example}:
3014 real(8) :: x = 1.0_8
3016 end program test_cosh
3019 @item @emph{Specific names}:
3020 @multitable @columnfractions .20 .20 .20 .25
3021 @item Name @tab Argument @tab Return type @tab Standard
3022 @item @code{COSH(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab Fortran 77 and later
3023 @item @code{DCOSH(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab Fortran 77 and later
3026 @item @emph{See also}:
3027 Inverse function: @ref{ACOSH}
3034 @section @code{COUNT} --- Count function
3036 @cindex array, conditionally count elements
3037 @cindex array, element counting
3038 @cindex array, number of elements
3041 @item @emph{Description}:
3043 Counts the number of @code{.TRUE.} elements in a logical @var{MASK},
3044 or, if the @var{DIM} argument is supplied, counts the number of
3045 elements along each row of the array in the @var{DIM} direction.
3046 If the array has zero size, or all of the elements of @var{MASK} are
3047 @code{.FALSE.}, then the result is @code{0}.
3049 @item @emph{Standard}:
3050 Fortran 95 and later, with @var{KIND} argument Fortran 2003 and later
3053 Transformational function
3055 @item @emph{Syntax}:
3056 @code{RESULT = COUNT(MASK [, DIM, KIND])}
3058 @item @emph{Arguments}:
3059 @multitable @columnfractions .15 .70
3060 @item @var{MASK} @tab The type shall be @code{LOGICAL}.
3061 @item @var{DIM} @tab (Optional) The type shall be @code{INTEGER}.
3062 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
3063 expression indicating the kind parameter of the result.
3066 @item @emph{Return value}:
3067 The return value is of type @code{INTEGER} and of kind @var{KIND}. If
3068 @var{KIND} is absent, the return value is of default integer kind.
3069 If @var{DIM} is present, the result is an array with a rank one less
3070 than the rank of @var{ARRAY}, and a size corresponding to the shape
3071 of @var{ARRAY} with the @var{DIM} dimension removed.
3073 @item @emph{Example}:
3076 integer, dimension(2,3) :: a, b
3077 logical, dimension(2,3) :: mask
3078 a = reshape( (/ 1, 2, 3, 4, 5, 6 /), (/ 2, 3 /))
3079 b = reshape( (/ 0, 7, 3, 4, 5, 8 /), (/ 2, 3 /))
3080 print '(3i3)', a(1,:)
3081 print '(3i3)', a(2,:)
3083 print '(3i3)', b(1,:)
3084 print '(3i3)', b(2,:)
3087 print '(3l3)', mask(1,:)
3088 print '(3l3)', mask(2,:)
3090 print '(3i3)', count(mask)
3092 print '(3i3)', count(mask, 1)
3094 print '(3i3)', count(mask, 2)
3095 end program test_count
3102 @section @code{CPU_TIME} --- CPU elapsed time in seconds
3104 @cindex time, elapsed
3107 @item @emph{Description}:
3108 Returns a @code{REAL} value representing the elapsed CPU time in
3109 seconds. This is useful for testing segments of code to determine
3112 If a time source is available, time will be reported with microsecond
3113 resolution. If no time source is available, @var{TIME} is set to
3116 Note that @var{TIME} may contain a, system dependent, arbitrary offset
3117 and may not start with @code{0.0}. For @code{CPU_TIME}, the absolute
3118 value is meaningless, only differences between subsequent calls to
3119 this subroutine, as shown in the example below, should be used.
3122 @item @emph{Standard}:
3123 Fortran 95 and later
3128 @item @emph{Syntax}:
3129 @code{CALL CPU_TIME(TIME)}
3131 @item @emph{Arguments}:
3132 @multitable @columnfractions .15 .70
3133 @item @var{TIME} @tab The type shall be @code{REAL} with @code{INTENT(OUT)}.
3136 @item @emph{Return value}:
3139 @item @emph{Example}:
3141 program test_cpu_time
3142 real :: start, finish
3143 call cpu_time(start)
3144 ! put code to test here
3145 call cpu_time(finish)
3146 print '("Time = ",f6.3," seconds.")',finish-start
3147 end program test_cpu_time
3150 @item @emph{See also}:
3151 @ref{SYSTEM_CLOCK}, @ref{DATE_AND_TIME}
3157 @section @code{CSHIFT} --- Circular shift elements of an array
3159 @cindex array, shift circularly
3160 @cindex array, permutation
3161 @cindex array, rotate
3164 @item @emph{Description}:
3165 @code{CSHIFT(ARRAY, SHIFT [, DIM])} performs a circular shift on elements of
3166 @var{ARRAY} along the dimension of @var{DIM}. If @var{DIM} is omitted it is
3167 taken to be @code{1}. @var{DIM} is a scalar of type @code{INTEGER} in the
3168 range of @math{1 \leq DIM \leq n)} where @math{n} is the rank of @var{ARRAY}.
3169 If the rank of @var{ARRAY} is one, then all elements of @var{ARRAY} are shifted
3170 by @var{SHIFT} places. If rank is greater than one, then all complete rank one
3171 sections of @var{ARRAY} along the given dimension are shifted. Elements
3172 shifted out one end of each rank one section are shifted back in the other end.
3174 @item @emph{Standard}:
3175 Fortran 95 and later
3178 Transformational function
3180 @item @emph{Syntax}:
3181 @code{RESULT = CSHIFT(ARRAY, SHIFT [, DIM])}
3183 @item @emph{Arguments}:
3184 @multitable @columnfractions .15 .70
3185 @item @var{ARRAY} @tab Shall be an array of any type.
3186 @item @var{SHIFT} @tab The type shall be @code{INTEGER}.
3187 @item @var{DIM} @tab The type shall be @code{INTEGER}.
3190 @item @emph{Return value}:
3191 Returns an array of same type and rank as the @var{ARRAY} argument.
3193 @item @emph{Example}:
3196 integer, dimension(3,3) :: a
3197 a = reshape( (/ 1, 2, 3, 4, 5, 6, 7, 8, 9 /), (/ 3, 3 /))
3198 print '(3i3)', a(1,:)
3199 print '(3i3)', a(2,:)
3200 print '(3i3)', a(3,:)
3201 a = cshift(a, SHIFT=(/1, 2, -1/), DIM=2)
3203 print '(3i3)', a(1,:)
3204 print '(3i3)', a(2,:)
3205 print '(3i3)', a(3,:)
3206 end program test_cshift
3213 @section @code{CTIME} --- Convert a time into a string
3215 @cindex time, conversion to string
3216 @cindex conversion, to string
3219 @item @emph{Description}:
3220 @code{CTIME} converts a system time value, such as returned by
3221 @code{TIME8}, to a string. Unless the application has called
3222 @code{setlocale}, the output will be in the default locale, of length
3223 24 and of the form @samp{Sat Aug 19 18:13:14 1995}. In other locales,
3224 a longer string may result.
3226 This intrinsic is provided in both subroutine and function forms; however,
3227 only one form can be used in any given program unit.
3229 @item @emph{Standard}:
3233 Subroutine, function
3235 @item @emph{Syntax}:
3236 @multitable @columnfractions .80
3237 @item @code{CALL CTIME(TIME, RESULT)}.
3238 @item @code{RESULT = CTIME(TIME)}.
3241 @item @emph{Arguments}:
3242 @multitable @columnfractions .15 .70
3243 @item @var{TIME} @tab The type shall be of type @code{INTEGER}.
3244 @item @var{RESULT} @tab The type shall be of type @code{CHARACTER} and
3245 of default kind. It is an @code{INTENT(OUT)} argument. If the length
3246 of this variable is too short for the time and date string to fit
3247 completely, it will be blank on procedure return.
3250 @item @emph{Return value}:
3251 The converted date and time as a string.
3253 @item @emph{Example}:
3257 character(len=30) :: date
3260 ! Do something, main part of the program
3263 print *, 'Program was started on ', date
3264 end program test_ctime
3267 @item @emph{See Also}:
3268 @ref{DATE_AND_TIME}, @ref{GMTIME}, @ref{LTIME}, @ref{TIME}, @ref{TIME8}
3274 @section @code{DATE_AND_TIME} --- Date and time subroutine
3275 @fnindex DATE_AND_TIME
3276 @cindex date, current
3277 @cindex current date
3278 @cindex time, current
3279 @cindex current time
3282 @item @emph{Description}:
3283 @code{DATE_AND_TIME(DATE, TIME, ZONE, VALUES)} gets the corresponding date and
3284 time information from the real-time system clock. @var{DATE} is
3285 @code{INTENT(OUT)} and has form ccyymmdd. @var{TIME} is @code{INTENT(OUT)} and
3286 has form hhmmss.sss. @var{ZONE} is @code{INTENT(OUT)} and has form (+-)hhmm,
3287 representing the difference with respect to Coordinated Universal Time (UTC).
3288 Unavailable time and date parameters return blanks.
3290 @var{VALUES} is @code{INTENT(OUT)} and provides the following:
3292 @multitable @columnfractions .15 .30 .40
3293 @item @tab @code{VALUE(1)}: @tab The year
3294 @item @tab @code{VALUE(2)}: @tab The month
3295 @item @tab @code{VALUE(3)}: @tab The day of the month
3296 @item @tab @code{VALUE(4)}: @tab Time difference with UTC in minutes
3297 @item @tab @code{VALUE(5)}: @tab The hour of the day
3298 @item @tab @code{VALUE(6)}: @tab The minutes of the hour
3299 @item @tab @code{VALUE(7)}: @tab The seconds of the minute
3300 @item @tab @code{VALUE(8)}: @tab The milliseconds of the second
3303 @item @emph{Standard}:
3304 Fortran 95 and later
3309 @item @emph{Syntax}:
3310 @code{CALL DATE_AND_TIME([DATE, TIME, ZONE, VALUES])}
3312 @item @emph{Arguments}:
3313 @multitable @columnfractions .15 .70
3314 @item @var{DATE} @tab (Optional) The type shall be @code{CHARACTER(LEN=8)}
3315 or larger, and of default kind.
3316 @item @var{TIME} @tab (Optional) The type shall be @code{CHARACTER(LEN=10)}
3317 or larger, and of default kind.
3318 @item @var{ZONE} @tab (Optional) The type shall be @code{CHARACTER(LEN=5)}
3319 or larger, and of default kind.
3320 @item @var{VALUES}@tab (Optional) The type shall be @code{INTEGER(8)}.
3323 @item @emph{Return value}:
3326 @item @emph{Example}:
3328 program test_time_and_date
3329 character(8) :: date
3330 character(10) :: time
3331 character(5) :: zone
3332 integer,dimension(8) :: values
3333 ! using keyword arguments
3334 call date_and_time(date,time,zone,values)
3335 call date_and_time(DATE=date,ZONE=zone)
3336 call date_and_time(TIME=time)
3337 call date_and_time(VALUES=values)
3338 print '(a,2x,a,2x,a)', date, time, zone
3339 print '(8i5))', values
3340 end program test_time_and_date
3343 @item @emph{See also}:
3344 @ref{CPU_TIME}, @ref{SYSTEM_CLOCK}
3350 @section @code{DBLE} --- Double conversion function
3352 @cindex conversion, to real
3355 @item @emph{Description}:
3356 @code{DBLE(A)} Converts @var{A} to double precision real type.
3358 @item @emph{Standard}:
3359 Fortran 77 and later
3364 @item @emph{Syntax}:
3365 @code{RESULT = DBLE(A)}
3367 @item @emph{Arguments}:
3368 @multitable @columnfractions .15 .70
3369 @item @var{A} @tab The type shall be @code{INTEGER}, @code{REAL},
3373 @item @emph{Return value}:
3374 The return value is of type double precision real.
3376 @item @emph{Example}:
3381 complex :: z = (2.3,1.14)
3382 print *, dble(x), dble(i), dble(z)
3383 end program test_dble
3386 @item @emph{See also}:
3393 @section @code{DCMPLX} --- Double complex conversion function
3395 @cindex complex numbers, conversion to
3396 @cindex conversion, to complex
3399 @item @emph{Description}:
3400 @code{DCMPLX(X [,Y])} returns a double complex number where @var{X} is
3401 converted to the real component. If @var{Y} is present it is converted to the
3402 imaginary component. If @var{Y} is not present then the imaginary component is
3403 set to 0.0. If @var{X} is complex then @var{Y} must not be present.
3405 @item @emph{Standard}:
3411 @item @emph{Syntax}:
3412 @code{RESULT = DCMPLX(X [, Y])}
3414 @item @emph{Arguments}:
3415 @multitable @columnfractions .15 .70
3416 @item @var{X} @tab The type may be @code{INTEGER}, @code{REAL},
3418 @item @var{Y} @tab (Optional if @var{X} is not @code{COMPLEX}.) May be
3419 @code{INTEGER} or @code{REAL}.
3422 @item @emph{Return value}:
3423 The return value is of type @code{COMPLEX(8)}
3425 @item @emph{Example}:
3435 print *, dcmplx(x,i)
3436 end program test_dcmplx
3442 @section @code{DIGITS} --- Significant binary digits function
3444 @cindex model representation, significant digits
3447 @item @emph{Description}:
3448 @code{DIGITS(X)} returns the number of significant binary digits of the internal
3449 model representation of @var{X}. For example, on a system using a 32-bit
3450 floating point representation, a default real number would likely return 24.
3452 @item @emph{Standard}:
3453 Fortran 95 and later
3458 @item @emph{Syntax}:
3459 @code{RESULT = DIGITS(X)}
3461 @item @emph{Arguments}:
3462 @multitable @columnfractions .15 .70
3463 @item @var{X} @tab The type may be @code{INTEGER} or @code{REAL}.
3466 @item @emph{Return value}:
3467 The return value is of type @code{INTEGER}.
3469 @item @emph{Example}:
3472 integer :: i = 12345
3478 end program test_digits
3485 @section @code{DIM} --- Positive difference
3489 @cindex positive difference
3492 @item @emph{Description}:
3493 @code{DIM(X,Y)} returns the difference @code{X-Y} if the result is positive;
3494 otherwise returns zero.
3496 @item @emph{Standard}:
3497 Fortran 77 and later
3502 @item @emph{Syntax}:
3503 @code{RESULT = DIM(X, Y)}
3505 @item @emph{Arguments}:
3506 @multitable @columnfractions .15 .70
3507 @item @var{X} @tab The type shall be @code{INTEGER} or @code{REAL}
3508 @item @var{Y} @tab The type shall be the same type and kind as @var{X}.
3511 @item @emph{Return value}:
3512 The return value is of type @code{INTEGER} or @code{REAL}.
3514 @item @emph{Example}:
3520 x = dim(4.345_8, 2.111_8)
3523 end program test_dim
3526 @item @emph{Specific names}:
3527 @multitable @columnfractions .20 .20 .20 .25
3528 @item Name @tab Argument @tab Return type @tab Standard
3529 @item @code{DIM(X,Y)} @tab @code{REAL(4) X, Y} @tab @code{REAL(4)} @tab Fortran 77 and later
3530 @item @code{IDIM(X,Y)} @tab @code{INTEGER(4) X, Y} @tab @code{INTEGER(4)} @tab Fortran 77 and later
3531 @item @code{DDIM(X,Y)} @tab @code{REAL(8) X, Y} @tab @code{REAL(8)} @tab Fortran 77 and later
3538 @section @code{DOT_PRODUCT} --- Dot product function
3539 @fnindex DOT_PRODUCT
3541 @cindex vector product
3542 @cindex product, vector
3545 @item @emph{Description}:
3546 @code{DOT_PRODUCT(VECTOR_A, VECTOR_B)} computes the dot product multiplication
3547 of two vectors @var{VECTOR_A} and @var{VECTOR_B}. The two vectors may be
3548 either numeric or logical and must be arrays of rank one and of equal size. If
3549 the vectors are @code{INTEGER} or @code{REAL}, the result is
3550 @code{SUM(VECTOR_A*VECTOR_B)}. If the vectors are @code{COMPLEX}, the result
3551 is @code{SUM(CONJG(VECTOR_A)*VECTOR_B)}. If the vectors are @code{LOGICAL},
3552 the result is @code{ANY(VECTOR_A .AND. VECTOR_B)}.
3554 @item @emph{Standard}:
3555 Fortran 95 and later
3558 Transformational function
3560 @item @emph{Syntax}:
3561 @code{RESULT = DOT_PRODUCT(VECTOR_A, VECTOR_B)}
3563 @item @emph{Arguments}:
3564 @multitable @columnfractions .15 .70
3565 @item @var{VECTOR_A} @tab The type shall be numeric or @code{LOGICAL}, rank 1.
3566 @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.
3569 @item @emph{Return value}:
3570 If the arguments are numeric, the return value is a scalar of numeric type,
3571 @code{INTEGER}, @code{REAL}, or @code{COMPLEX}. If the arguments are
3572 @code{LOGICAL}, the return value is @code{.TRUE.} or @code{.FALSE.}.
3574 @item @emph{Example}:
3576 program test_dot_prod
3577 integer, dimension(3) :: a, b
3584 print *, dot_product(a,b)
3585 end program test_dot_prod
3592 @section @code{DPROD} --- Double product function
3594 @cindex product, double-precision
3597 @item @emph{Description}:
3598 @code{DPROD(X,Y)} returns the product @code{X*Y}.
3600 @item @emph{Standard}:
3601 Fortran 77 and later
3606 @item @emph{Syntax}:
3607 @code{RESULT = DPROD(X, Y)}
3609 @item @emph{Arguments}:
3610 @multitable @columnfractions .15 .70
3611 @item @var{X} @tab The type shall be @code{REAL}.
3612 @item @var{Y} @tab The type shall be @code{REAL}.
3615 @item @emph{Return value}:
3616 The return value is of type @code{REAL(8)}.
3618 @item @emph{Example}:
3626 end program test_dprod
3629 @item @emph{Specific names}:
3630 @multitable @columnfractions .20 .20 .20 .25
3631 @item Name @tab Argument @tab Return type @tab Standard
3632 @item @code{DPROD(X,Y)} @tab @code{REAL(4) X, Y} @tab @code{REAL(4)} @tab Fortran 77 and later
3639 @section @code{DREAL} --- Double real part function
3641 @cindex complex numbers, real part
3644 @item @emph{Description}:
3645 @code{DREAL(Z)} returns the real part of complex variable @var{Z}.
3647 @item @emph{Standard}:
3653 @item @emph{Syntax}:
3654 @code{RESULT = DREAL(A)}
3656 @item @emph{Arguments}:
3657 @multitable @columnfractions .15 .70
3658 @item @var{A} @tab The type shall be @code{COMPLEX(8)}.
3661 @item @emph{Return value}:
3662 The return value is of type @code{REAL(8)}.
3664 @item @emph{Example}:
3667 complex(8) :: z = (1.3_8,7.2_8)
3669 end program test_dreal
3672 @item @emph{See also}:
3680 @section @code{DSHIFTL} --- Combined left shift
3682 @cindex left shift, combined
3686 @item @emph{Description}:
3687 @code{DSHIFTL(I, J, SHIFT)} combines bits of @var{I} and @var{J}. The
3688 rightmost @var{SHIFT} bits of the result are the leftmost @var{SHIFT}
3689 bits of @var{J}, and the remaining bits are the rightmost bits of
3692 @item @emph{Standard}:
3693 Fortran 2008 and later
3698 @item @emph{Syntax}:
3699 @code{RESULT = DSHIFTL(I, J, SHIFT)}
3701 @item @emph{Arguments}:
3702 @multitable @columnfractions .15 .70
3703 @item @var{I} @tab Shall be of type @code{INTEGER}.
3704 @item @var{J} @tab Shall be of type @code{INTEGER}, and of the same kind
3706 @item @var{SHIFT} @tab Shall be of type @code{INTEGER}.
3709 @item @emph{Return value}:
3710 The return value has same type and kind as @var{I}.
3712 @item @emph{See also}:
3720 @section @code{DSHIFTR} --- Combined right shift
3722 @cindex right shift, combined
3723 @cindex shift, right
3726 @item @emph{Description}:
3727 @code{DSHIFTR(I, J, SHIFT)} combines bits of @var{I} and @var{J}. The
3728 leftmost @var{SHIFT} bits of the result are the rightmost @var{SHIFT}
3729 bits of @var{I}, and the remaining bits are the leftmost bits of
3732 @item @emph{Standard}:
3733 Fortran 2008 and later
3738 @item @emph{Syntax}:
3739 @code{RESULT = DSHIFTR(I, J, SHIFT)}
3741 @item @emph{Arguments}:
3742 @multitable @columnfractions .15 .70
3743 @item @var{I} @tab Shall be of type @code{INTEGER}.
3744 @item @var{J} @tab Shall be of type @code{INTEGER}, and of the same kind
3746 @item @var{SHIFT} @tab Shall be of type @code{INTEGER}.
3749 @item @emph{Return value}:
3750 The return value has same type and kind as @var{I}.
3752 @item @emph{See also}:
3760 @section @code{DTIME} --- Execution time subroutine (or function)
3762 @cindex time, elapsed
3763 @cindex elapsed time
3766 @item @emph{Description}:
3767 @code{DTIME(VALUES, TIME)} initially returns the number of seconds of runtime
3768 since the start of the process's execution in @var{TIME}. @var{VALUES}
3769 returns the user and system components of this time in @code{VALUES(1)} and
3770 @code{VALUES(2)} respectively. @var{TIME} is equal to @code{VALUES(1) +
3773 Subsequent invocations of @code{DTIME} return values accumulated since the
3774 previous invocation.
3776 On some systems, the underlying timings are represented using types with
3777 sufficiently small limits that overflows (wrap around) are possible, such as
3778 32-bit types. Therefore, the values returned by this intrinsic might be, or
3779 become, negative, or numerically less than previous values, during a single
3780 run of the compiled program.
3782 Please note, that this implementation is thread safe if used within OpenMP
3783 directives, i.e., its state will be consistent while called from multiple
3784 threads. However, if @code{DTIME} is called from multiple threads, the result
3785 is still the time since the last invocation. This may not give the intended
3786 results. If possible, use @code{CPU_TIME} instead.
3788 This intrinsic is provided in both subroutine and function forms; however,
3789 only one form can be used in any given program unit.
3791 @var{VALUES} and @var{TIME} are @code{INTENT(OUT)} and provide the following:
3793 @multitable @columnfractions .15 .30 .40
3794 @item @tab @code{VALUES(1)}: @tab User time in seconds.
3795 @item @tab @code{VALUES(2)}: @tab System time in seconds.
3796 @item @tab @code{TIME}: @tab Run time since start in seconds.
3799 @item @emph{Standard}:
3803 Subroutine, function
3805 @item @emph{Syntax}:
3806 @multitable @columnfractions .80
3807 @item @code{CALL DTIME(VALUES, TIME)}.
3808 @item @code{TIME = DTIME(VALUES)}, (not recommended).
3811 @item @emph{Arguments}:
3812 @multitable @columnfractions .15 .70
3813 @item @var{VALUES}@tab The type shall be @code{REAL(4), DIMENSION(2)}.
3814 @item @var{TIME}@tab The type shall be @code{REAL(4)}.
3817 @item @emph{Return value}:
3818 Elapsed time in seconds since the last invocation or since the start of program
3819 execution if not called before.
3821 @item @emph{Example}:
3825 real, dimension(2) :: tarray
3827 call dtime(tarray, result)
3831 do i=1,100000000 ! Just a delay
3834 call dtime(tarray, result)
3838 end program test_dtime
3841 @item @emph{See also}:
3849 @section @code{EOSHIFT} --- End-off shift elements of an array
3851 @cindex array, shift
3854 @item @emph{Description}:
3855 @code{EOSHIFT(ARRAY, SHIFT[, BOUNDARY, DIM])} performs an end-off shift on
3856 elements of @var{ARRAY} along the dimension of @var{DIM}. If @var{DIM} is
3857 omitted it is taken to be @code{1}. @var{DIM} is a scalar of type
3858 @code{INTEGER} in the range of @math{1 \leq DIM \leq n)} where @math{n} is the
3859 rank of @var{ARRAY}. If the rank of @var{ARRAY} is one, then all elements of
3860 @var{ARRAY} are shifted by @var{SHIFT} places. If rank is greater than one,
3861 then all complete rank one sections of @var{ARRAY} along the given dimension are
3862 shifted. Elements shifted out one end of each rank one section are dropped. If
3863 @var{BOUNDARY} is present then the corresponding value of from @var{BOUNDARY}
3864 is copied back in the other end. If @var{BOUNDARY} is not present then the
3865 following are copied in depending on the type of @var{ARRAY}.
3867 @multitable @columnfractions .15 .80
3868 @item @emph{Array Type} @tab @emph{Boundary Value}
3869 @item Numeric @tab 0 of the type and kind of @var{ARRAY}.
3870 @item Logical @tab @code{.FALSE.}.
3871 @item Character(@var{len}) @tab @var{len} blanks.
3874 @item @emph{Standard}:
3875 Fortran 95 and later
3878 Transformational function
3880 @item @emph{Syntax}:
3881 @code{RESULT = EOSHIFT(ARRAY, SHIFT [, BOUNDARY, DIM])}
3883 @item @emph{Arguments}:
3884 @multitable @columnfractions .15 .70
3885 @item @var{ARRAY} @tab May be any type, not scalar.
3886 @item @var{SHIFT} @tab The type shall be @code{INTEGER}.
3887 @item @var{BOUNDARY} @tab Same type as @var{ARRAY}.
3888 @item @var{DIM} @tab The type shall be @code{INTEGER}.
3891 @item @emph{Return value}:
3892 Returns an array of same type and rank as the @var{ARRAY} argument.
3894 @item @emph{Example}:
3896 program test_eoshift
3897 integer, dimension(3,3) :: a
3898 a = reshape( (/ 1, 2, 3, 4, 5, 6, 7, 8, 9 /), (/ 3, 3 /))
3899 print '(3i3)', a(1,:)
3900 print '(3i3)', a(2,:)
3901 print '(3i3)', a(3,:)
3902 a = EOSHIFT(a, SHIFT=(/1, 2, 1/), BOUNDARY=-5, DIM=2)
3904 print '(3i3)', a(1,:)
3905 print '(3i3)', a(2,:)
3906 print '(3i3)', a(3,:)
3907 end program test_eoshift
3914 @section @code{EPSILON} --- Epsilon function
3916 @cindex model representation, epsilon
3919 @item @emph{Description}:
3920 @code{EPSILON(X)} returns the smallest number @var{E} of the same kind
3921 as @var{X} such that @math{1 + E > 1}.
3923 @item @emph{Standard}:
3924 Fortran 95 and later
3929 @item @emph{Syntax}:
3930 @code{RESULT = EPSILON(X)}
3932 @item @emph{Arguments}:
3933 @multitable @columnfractions .15 .70
3934 @item @var{X} @tab The type shall be @code{REAL}.
3937 @item @emph{Return value}:
3938 The return value is of same type as the argument.
3940 @item @emph{Example}:
3942 program test_epsilon
3947 end program test_epsilon
3954 @section @code{ERF} --- Error function
3956 @cindex error function
3959 @item @emph{Description}:
3960 @code{ERF(X)} computes the error function of @var{X}.
3962 @item @emph{Standard}:
3963 Fortran 2008 and later
3968 @item @emph{Syntax}:
3969 @code{RESULT = ERF(X)}
3971 @item @emph{Arguments}:
3972 @multitable @columnfractions .15 .70
3973 @item @var{X} @tab The type shall be @code{REAL}.
3976 @item @emph{Return value}:
3977 The return value is of type @code{REAL}, of the same kind as
3978 @var{X} and lies in the range @math{-1 \leq erf (x) \leq 1 }.
3980 @item @emph{Example}:
3983 real(8) :: x = 0.17_8
3985 end program test_erf
3988 @item @emph{Specific names}:
3989 @multitable @columnfractions .20 .20 .20 .25
3990 @item Name @tab Argument @tab Return type @tab Standard
3991 @item @code{DERF(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU extension
3998 @section @code{ERFC} --- Error function
4000 @cindex error function, complementary
4003 @item @emph{Description}:
4004 @code{ERFC(X)} computes the complementary error function of @var{X}.
4006 @item @emph{Standard}:
4007 Fortran 2008 and later
4012 @item @emph{Syntax}:
4013 @code{RESULT = ERFC(X)}
4015 @item @emph{Arguments}:
4016 @multitable @columnfractions .15 .70
4017 @item @var{X} @tab The type shall be @code{REAL}.
4020 @item @emph{Return value}:
4021 The return value is of type @code{REAL} and of the same kind as @var{X}.
4022 It lies in the range @math{ 0 \leq erfc (x) \leq 2 }.
4024 @item @emph{Example}:
4027 real(8) :: x = 0.17_8
4029 end program test_erfc
4032 @item @emph{Specific names}:
4033 @multitable @columnfractions .20 .20 .20 .25
4034 @item Name @tab Argument @tab Return type @tab Standard
4035 @item @code{DERFC(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU extension
4042 @section @code{ERFC_SCALED} --- Error function
4043 @fnindex ERFC_SCALED
4044 @cindex error function, complementary, exponentially-scaled
4047 @item @emph{Description}:
4048 @code{ERFC_SCALED(X)} computes the exponentially-scaled complementary
4049 error function of @var{X}.
4051 @item @emph{Standard}:
4052 Fortran 2008 and later
4057 @item @emph{Syntax}:
4058 @code{RESULT = ERFC_SCALED(X)}
4060 @item @emph{Arguments}:
4061 @multitable @columnfractions .15 .70
4062 @item @var{X} @tab The type shall be @code{REAL}.
4065 @item @emph{Return value}:
4066 The return value is of type @code{REAL} and of the same kind as @var{X}.
4068 @item @emph{Example}:
4070 program test_erfc_scaled
4071 real(8) :: x = 0.17_8
4073 end program test_erfc_scaled
4080 @section @code{ETIME} --- Execution time subroutine (or function)
4082 @cindex time, elapsed
4085 @item @emph{Description}:
4086 @code{ETIME(VALUES, TIME)} returns the number of seconds of runtime
4087 since the start of the process's execution in @var{TIME}. @var{VALUES}
4088 returns the user and system components of this time in @code{VALUES(1)} and
4089 @code{VALUES(2)} respectively. @var{TIME} is equal to @code{VALUES(1) + VALUES(2)}.
4091 On some systems, the underlying timings are represented using types with
4092 sufficiently small limits that overflows (wrap around) are possible, such as
4093 32-bit types. Therefore, the values returned by this intrinsic might be, or
4094 become, negative, or numerically less than previous values, during a single
4095 run of the compiled program.
4097 This intrinsic is provided in both subroutine and function forms; however,
4098 only one form can be used in any given program unit.
4100 @var{VALUES} and @var{TIME} are @code{INTENT(OUT)} and provide the following:
4102 @multitable @columnfractions .15 .30 .60
4103 @item @tab @code{VALUES(1)}: @tab User time in seconds.
4104 @item @tab @code{VALUES(2)}: @tab System time in seconds.
4105 @item @tab @code{TIME}: @tab Run time since start in seconds.
4108 @item @emph{Standard}:
4112 Subroutine, function
4114 @item @emph{Syntax}:
4115 @multitable @columnfractions .80
4116 @item @code{CALL ETIME(VALUES, TIME)}.
4117 @item @code{TIME = ETIME(VALUES)}, (not recommended).
4120 @item @emph{Arguments}:
4121 @multitable @columnfractions .15 .70
4122 @item @var{VALUES}@tab The type shall be @code{REAL(4), DIMENSION(2)}.
4123 @item @var{TIME}@tab The type shall be @code{REAL(4)}.
4126 @item @emph{Return value}:
4127 Elapsed time in seconds since the start of program execution.
4129 @item @emph{Example}:
4133 real, dimension(2) :: tarray
4135 call ETIME(tarray, result)
4139 do i=1,100000000 ! Just a delay
4142 call ETIME(tarray, result)
4146 end program test_etime
4149 @item @emph{See also}:
4156 @node EXECUTE_COMMAND_LINE
4157 @section @code{EXECUTE_COMMAND_LINE} --- Execute a shell command
4158 @fnindex EXECUTE_COMMAND_LINE
4159 @cindex system, system call
4160 @cindex command line
4163 @item @emph{Description}:
4164 @code{EXECUTE_COMMAND_LINE} runs a shell command, synchronously or
4167 The @code{COMMAND} argument is passed to the shell and executed, using
4168 the C library's @code{system} call. (The shell is @code{sh} on Unix
4169 systems, and @code{cmd.exe} on Windows.) If @code{WAIT} is present
4170 and has the value false, the execution of the command is asynchronous
4171 if the system supports it; otherwise, the command is executed
4174 The three last arguments allow the user to get status information. After
4175 synchronous execution, @code{EXITSTAT} contains the integer exit code of
4176 the command, as returned by @code{system}. @code{CMDSTAT} is set to zero
4177 if the command line was executed (whatever its exit status was).
4178 @code{CMDMSG} is assigned an error message if an error has occurred.
4180 Note that the @code{system} function need not be thread-safe. It is
4181 the responsibility of the user to ensure that @code{system} is not
4182 called concurrently.
4184 @item @emph{Standard}:
4185 Fortran 2008 and later
4190 @item @emph{Syntax}:
4191 @code{CALL EXECUTE_COMMAND_LINE(COMMAND [, WAIT, EXITSTAT, CMDSTAT, CMDMSG ])}
4193 @item @emph{Arguments}:
4194 @multitable @columnfractions .15 .70
4195 @item @var{COMMAND} @tab Shall be a default @code{CHARACTER} scalar.
4196 @item @var{WAIT} @tab (Optional) Shall be a default @code{LOGICAL} scalar.
4197 @item @var{EXITSTAT} @tab (Optional) Shall be an @code{INTEGER} of the
4199 @item @var{CMDSTAT} @tab (Optional) Shall be an @code{INTEGER} of the
4201 @item @var{CMDMSG} @tab (Optional) Shall be an @code{CHARACTER} scalar of the
4205 @item @emph{Example}:
4210 call execute_command_line ("external_prog.exe", exitstat=i)
4211 print *, "Exit status of external_prog.exe was ", i
4213 call execute_command_line ("reindex_files.exe", wait=.false.)
4214 print *, "Now reindexing files in the background"
4216 end program test_exec
4222 Because this intrinsic is implemented in terms of the @code{system}
4223 function call, its behavior with respect to signaling is processor
4224 dependent. In particular, on POSIX-compliant systems, the SIGINT and
4225 SIGQUIT signals will be ignored, and the SIGCHLD will be blocked. As
4226 such, if the parent process is terminated, the child process might not be
4227 terminated alongside.
4230 @item @emph{See also}:
4237 @section @code{EXIT} --- Exit the program with status.
4239 @cindex program termination
4240 @cindex terminate program
4243 @item @emph{Description}:
4244 @code{EXIT} causes immediate termination of the program with status. If status
4245 is omitted it returns the canonical @emph{success} for the system. All Fortran
4246 I/O units are closed.
4248 @item @emph{Standard}:
4254 @item @emph{Syntax}:
4255 @code{CALL EXIT([STATUS])}
4257 @item @emph{Arguments}:
4258 @multitable @columnfractions .15 .70
4259 @item @var{STATUS} @tab Shall be an @code{INTEGER} of the default kind.
4262 @item @emph{Return value}:
4263 @code{STATUS} is passed to the parent process on exit.
4265 @item @emph{Example}:
4268 integer :: STATUS = 0
4269 print *, 'This program is going to exit.'
4271 end program test_exit
4274 @item @emph{See also}:
4275 @ref{ABORT}, @ref{KILL}
4281 @section @code{EXP} --- Exponential function
4287 @cindex exponential function
4288 @cindex logarithm function, inverse
4291 @item @emph{Description}:
4292 @code{EXP(X)} computes the base @math{e} exponential of @var{X}.
4294 @item @emph{Standard}:
4295 Fortran 77 and later, has overloads that are GNU extensions
4300 @item @emph{Syntax}:
4301 @code{RESULT = EXP(X)}
4303 @item @emph{Arguments}:
4304 @multitable @columnfractions .15 .70
4305 @item @var{X} @tab The type shall be @code{REAL} or
4309 @item @emph{Return value}:
4310 The return value has same type and kind as @var{X}.
4312 @item @emph{Example}:
4317 end program test_exp
4320 @item @emph{Specific names}:
4321 @multitable @columnfractions .20 .20 .20 .25
4322 @item Name @tab Argument @tab Return type @tab Standard
4323 @item @code{EXP(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab Fortran 77 and later
4324 @item @code{DEXP(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab Fortran 77 and later
4325 @item @code{CEXP(X)} @tab @code{COMPLEX(4) X} @tab @code{COMPLEX(4)} @tab Fortran 77 and later
4326 @item @code{ZEXP(X)} @tab @code{COMPLEX(8) X} @tab @code{COMPLEX(8)} @tab GNU extension
4327 @item @code{CDEXP(X)} @tab @code{COMPLEX(8) X} @tab @code{COMPLEX(8)} @tab GNU extension
4334 @section @code{EXPONENT} --- Exponent function
4336 @cindex real number, exponent
4337 @cindex floating point, exponent
4340 @item @emph{Description}:
4341 @code{EXPONENT(X)} returns the value of the exponent part of @var{X}. If @var{X}
4342 is zero the value returned is zero.
4344 @item @emph{Standard}:
4345 Fortran 95 and later
4350 @item @emph{Syntax}:
4351 @code{RESULT = EXPONENT(X)}
4353 @item @emph{Arguments}:
4354 @multitable @columnfractions .15 .70
4355 @item @var{X} @tab The type shall be @code{REAL}.
4358 @item @emph{Return value}:
4359 The return value is of type default @code{INTEGER}.
4361 @item @emph{Example}:
4363 program test_exponent
4368 print *, exponent(0.0)
4369 end program test_exponent
4375 @node EXTENDS_TYPE_OF
4376 @section @code{EXTENDS_TYPE_OF} --- Query dynamic type for extension
4377 @fnindex EXTENDS_TYPE_OF
4380 @item @emph{Description}:
4381 Query dynamic type for extension.
4383 @item @emph{Standard}:
4384 Fortran 2003 and later
4389 @item @emph{Syntax}:
4390 @code{RESULT = EXTENDS_TYPE_OF(A, MOLD)}
4392 @item @emph{Arguments}:
4393 @multitable @columnfractions .15 .70
4394 @item @var{A} @tab Shall be an object of extensible declared type or
4395 unlimited polymorphic.
4396 @item @var{MOLD} @tab Shall be an object of extensible declared type or
4397 unlimited polymorphic.
4400 @item @emph{Return value}:
4401 The return value is a scalar of type default logical. It is true if and only if
4402 the dynamic type of A is an extension type of the dynamic type of MOLD.
4405 @item @emph{See also}:
4412 @section @code{FDATE} --- Get the current time as a string
4414 @cindex time, current
4415 @cindex current time
4416 @cindex date, current
4417 @cindex current date
4420 @item @emph{Description}:
4421 @code{FDATE(DATE)} returns the current date (using the same format as
4422 @code{CTIME}) in @var{DATE}. It is equivalent to @code{CALL CTIME(DATE,
4425 This intrinsic is provided in both subroutine and function forms; however,
4426 only one form can be used in any given program unit.
4428 @item @emph{Standard}:
4432 Subroutine, function
4434 @item @emph{Syntax}:
4435 @multitable @columnfractions .80
4436 @item @code{CALL FDATE(DATE)}.
4437 @item @code{DATE = FDATE()}.
4440 @item @emph{Arguments}:
4441 @multitable @columnfractions .15 .70
4442 @item @var{DATE}@tab The type shall be of type @code{CHARACTER} of the
4443 default kind. It is an @code{INTENT(OUT)} argument. If the length of
4444 this variable is too short for the date and time string to fit
4445 completely, it will be blank on procedure return.
4448 @item @emph{Return value}:
4449 The current date and time as a string.
4451 @item @emph{Example}:
4455 character(len=30) :: date
4457 print *, 'Program started on ', date
4458 do i = 1, 100000000 ! Just a delay
4462 print *, 'Program ended on ', date
4463 end program test_fdate
4466 @item @emph{See also}:
4467 @ref{DATE_AND_TIME}, @ref{CTIME}
4472 @section @code{FGET} --- Read a single character in stream mode from stdin
4474 @cindex read character, stream mode
4475 @cindex stream mode, read character
4476 @cindex file operation, read character
4479 @item @emph{Description}:
4480 Read a single character in stream mode from stdin by bypassing normal
4481 formatted output. Stream I/O should not be mixed with normal record-oriented
4482 (formatted or unformatted) I/O on the same unit; the results are unpredictable.
4484 This intrinsic is provided in both subroutine and function forms; however,
4485 only one form can be used in any given program unit.
4487 Note that the @code{FGET} intrinsic is provided for backwards compatibility with
4488 @command{g77}. GNU Fortran provides the Fortran 2003 Stream facility.
4489 Programmers should consider the use of new stream IO feature in new code
4490 for future portability. See also @ref{Fortran 2003 status}.
4492 @item @emph{Standard}:
4496 Subroutine, function
4498 @item @emph{Syntax}:
4499 @multitable @columnfractions .80
4500 @item @code{CALL FGET(C [, STATUS])}
4501 @item @code{STATUS = FGET(C)}
4504 @item @emph{Arguments}:
4505 @multitable @columnfractions .15 .70
4506 @item @var{C} @tab The type shall be @code{CHARACTER} and of default
4508 @item @var{STATUS} @tab (Optional) status flag of type @code{INTEGER}.
4509 Returns 0 on success, -1 on end-of-file, and a system specific positive
4510 error code otherwise.
4513 @item @emph{Example}:
4516 INTEGER, PARAMETER :: strlen = 100
4517 INTEGER :: status, i = 1
4518 CHARACTER(len=strlen) :: str = ""
4520 WRITE (*,*) 'Enter text:'
4522 CALL fget(str(i:i), status)
4523 if (status /= 0 .OR. i > strlen) exit
4526 WRITE (*,*) TRIM(str)
4530 @item @emph{See also}:
4531 @ref{FGETC}, @ref{FPUT}, @ref{FPUTC}
4537 @section @code{FGETC} --- Read a single character in stream mode
4539 @cindex read character, stream mode
4540 @cindex stream mode, read character
4541 @cindex file operation, read character
4544 @item @emph{Description}:
4545 Read a single character in stream mode by bypassing normal formatted output.
4546 Stream I/O should not be mixed with normal record-oriented (formatted or
4547 unformatted) I/O on the same unit; the results are unpredictable.
4549 This intrinsic is provided in both subroutine and function forms; however,
4550 only one form can be used in any given program unit.
4552 Note that the @code{FGET} intrinsic is provided for backwards compatibility
4553 with @command{g77}. GNU Fortran provides the Fortran 2003 Stream facility.
4554 Programmers should consider the use of new stream IO feature in new code
4555 for future portability. See also @ref{Fortran 2003 status}.
4557 @item @emph{Standard}:
4561 Subroutine, function
4563 @item @emph{Syntax}:
4564 @multitable @columnfractions .80
4565 @item @code{CALL FGETC(UNIT, C [, STATUS])}
4566 @item @code{STATUS = FGETC(UNIT, C)}
4569 @item @emph{Arguments}:
4570 @multitable @columnfractions .15 .70
4571 @item @var{UNIT} @tab The type shall be @code{INTEGER}.
4572 @item @var{C} @tab The type shall be @code{CHARACTER} and of default
4574 @item @var{STATUS} @tab (Optional) status flag of type @code{INTEGER}.
4575 Returns 0 on success, -1 on end-of-file and a system specific positive
4576 error code otherwise.
4579 @item @emph{Example}:
4582 INTEGER :: fd = 42, status
4585 OPEN(UNIT=fd, FILE="/etc/passwd", ACTION="READ", STATUS = "OLD")
4587 CALL fgetc(fd, c, status)
4588 IF (status /= 0) EXIT
4595 @item @emph{See also}:
4596 @ref{FGET}, @ref{FPUT}, @ref{FPUTC}
4602 @section @code{FLOOR} --- Integer floor function
4605 @cindex rounding, floor
4608 @item @emph{Description}:
4609 @code{FLOOR(A)} returns the greatest integer less than or equal to @var{X}.
4611 @item @emph{Standard}:
4612 Fortran 95 and later
4617 @item @emph{Syntax}:
4618 @code{RESULT = FLOOR(A [, KIND])}
4620 @item @emph{Arguments}:
4621 @multitable @columnfractions .15 .70
4622 @item @var{A} @tab The type shall be @code{REAL}.
4623 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
4624 expression indicating the kind parameter of the result.
4627 @item @emph{Return value}:
4628 The return value is of type @code{INTEGER(KIND)} if @var{KIND} is present
4629 and of default-kind @code{INTEGER} otherwise.
4631 @item @emph{Example}:
4636 print *, floor(x) ! returns 63
4637 print *, floor(y) ! returns -64
4638 end program test_floor
4641 @item @emph{See also}:
4642 @ref{CEILING}, @ref{NINT}
4649 @section @code{FLUSH} --- Flush I/O unit(s)
4651 @cindex file operation, flush
4654 @item @emph{Description}:
4655 Flushes Fortran unit(s) currently open for output. Without the optional
4656 argument, all units are flushed, otherwise just the unit specified.
4658 @item @emph{Standard}:
4664 @item @emph{Syntax}:
4665 @code{CALL FLUSH(UNIT)}
4667 @item @emph{Arguments}:
4668 @multitable @columnfractions .15 .70
4669 @item @var{UNIT} @tab (Optional) The type shall be @code{INTEGER}.
4673 Beginning with the Fortran 2003 standard, there is a @code{FLUSH}
4674 statement that should be preferred over the @code{FLUSH} intrinsic.
4676 The @code{FLUSH} intrinsic and the Fortran 2003 @code{FLUSH} statement
4677 have identical effect: they flush the runtime library's I/O buffer so
4678 that the data becomes visible to other processes. This does not guarantee
4679 that the data is committed to disk.
4681 On POSIX systems, you can request that all data is transferred to the
4682 storage device by calling the @code{fsync} function, with the POSIX file
4683 descriptor of the I/O unit as argument (retrieved with GNU intrinsic
4684 @code{FNUM}). The following example shows how:
4687 ! Declare the interface for POSIX fsync function
4689 function fsync (fd) bind(c,name="fsync")
4690 use iso_c_binding, only: c_int
4691 integer(c_int), value :: fd
4692 integer(c_int) :: fsync
4696 ! Variable declaration
4700 open (10,file="foo")
4703 ! Perform I/O on unit 10
4708 ret = fsync(fnum(10))
4710 ! Handle possible error
4711 if (ret /= 0) stop "Error calling FSYNC"
4719 @section @code{FNUM} --- File number function
4721 @cindex file operation, file number
4724 @item @emph{Description}:
4725 @code{FNUM(UNIT)} returns the POSIX file descriptor number corresponding to the
4726 open Fortran I/O unit @code{UNIT}.
4728 @item @emph{Standard}:
4734 @item @emph{Syntax}:
4735 @code{RESULT = FNUM(UNIT)}
4737 @item @emph{Arguments}:
4738 @multitable @columnfractions .15 .70
4739 @item @var{UNIT} @tab The type shall be @code{INTEGER}.
4742 @item @emph{Return value}:
4743 The return value is of type @code{INTEGER}
4745 @item @emph{Example}:
4749 open (unit=10, status = "scratch")
4753 end program test_fnum
4760 @section @code{FPUT} --- Write a single character in stream mode to stdout
4762 @cindex write character, stream mode
4763 @cindex stream mode, write character
4764 @cindex file operation, write character
4767 @item @emph{Description}:
4768 Write a single character in stream mode to stdout by bypassing normal
4769 formatted output. Stream I/O should not be mixed with normal record-oriented
4770 (formatted or unformatted) I/O on the same unit; the results are unpredictable.
4772 This intrinsic is provided in both subroutine and function forms; however,
4773 only one form can be used in any given program unit.
4775 Note that the @code{FGET} intrinsic is provided for backwards compatibility with
4776 @command{g77}. GNU Fortran provides the Fortran 2003 Stream facility.
4777 Programmers should consider the use of new stream IO feature in new code
4778 for future portability. See also @ref{Fortran 2003 status}.
4780 @item @emph{Standard}:
4784 Subroutine, function
4786 @item @emph{Syntax}:
4787 @multitable @columnfractions .80
4788 @item @code{CALL FPUT(C [, STATUS])}
4789 @item @code{STATUS = FPUT(C)}
4792 @item @emph{Arguments}:
4793 @multitable @columnfractions .15 .70
4794 @item @var{C} @tab The type shall be @code{CHARACTER} and of default
4796 @item @var{STATUS} @tab (Optional) status flag of type @code{INTEGER}.
4797 Returns 0 on success, -1 on end-of-file and a system specific positive
4798 error code otherwise.
4801 @item @emph{Example}:
4804 CHARACTER(len=10) :: str = "gfortran"
4806 DO i = 1, len_trim(str)
4812 @item @emph{See also}:
4813 @ref{FPUTC}, @ref{FGET}, @ref{FGETC}
4819 @section @code{FPUTC} --- Write a single character in stream mode
4821 @cindex write character, stream mode
4822 @cindex stream mode, write character
4823 @cindex file operation, write character
4826 @item @emph{Description}:
4827 Write a single character in stream mode by bypassing normal formatted
4828 output. Stream I/O should not be mixed with normal record-oriented
4829 (formatted or unformatted) I/O on the same unit; the results are unpredictable.
4831 This intrinsic is provided in both subroutine and function forms; however,
4832 only one form can be used in any given program unit.
4834 Note that the @code{FGET} intrinsic is provided for backwards compatibility with
4835 @command{g77}. GNU Fortran provides the Fortran 2003 Stream facility.
4836 Programmers should consider the use of new stream IO feature in new code
4837 for future portability. See also @ref{Fortran 2003 status}.
4839 @item @emph{Standard}:
4843 Subroutine, function
4845 @item @emph{Syntax}:
4846 @multitable @columnfractions .80
4847 @item @code{CALL FPUTC(UNIT, C [, STATUS])}
4848 @item @code{STATUS = FPUTC(UNIT, C)}
4851 @item @emph{Arguments}:
4852 @multitable @columnfractions .15 .70
4853 @item @var{UNIT} @tab The type shall be @code{INTEGER}.
4854 @item @var{C} @tab The type shall be @code{CHARACTER} and of default
4856 @item @var{STATUS} @tab (Optional) status flag of type @code{INTEGER}.
4857 Returns 0 on success, -1 on end-of-file and a system specific positive
4858 error code otherwise.
4861 @item @emph{Example}:
4864 CHARACTER(len=10) :: str = "gfortran"
4865 INTEGER :: fd = 42, i
4867 OPEN(UNIT = fd, FILE = "out", ACTION = "WRITE", STATUS="NEW")
4868 DO i = 1, len_trim(str)
4869 CALL fputc(fd, str(i:i))
4875 @item @emph{See also}:
4876 @ref{FPUT}, @ref{FGET}, @ref{FGETC}
4882 @section @code{FRACTION} --- Fractional part of the model representation
4884 @cindex real number, fraction
4885 @cindex floating point, fraction
4888 @item @emph{Description}:
4889 @code{FRACTION(X)} returns the fractional part of the model
4890 representation of @code{X}.
4892 @item @emph{Standard}:
4893 Fortran 95 and later
4898 @item @emph{Syntax}:
4899 @code{Y = FRACTION(X)}
4901 @item @emph{Arguments}:
4902 @multitable @columnfractions .15 .70
4903 @item @var{X} @tab The type of the argument shall be a @code{REAL}.
4906 @item @emph{Return value}:
4907 The return value is of the same type and kind as the argument.
4908 The fractional part of the model representation of @code{X} is returned;
4909 it is @code{X * RADIX(X)**(-EXPONENT(X))}.
4911 @item @emph{Example}:
4913 program test_fraction
4916 print *, fraction(x), x * radix(x)**(-exponent(x))
4917 end program test_fraction
4925 @section @code{FREE} --- Frees memory
4927 @cindex pointer, cray
4930 @item @emph{Description}:
4931 Frees memory previously allocated by @code{MALLOC}. The @code{FREE}
4932 intrinsic is an extension intended to be used with Cray pointers, and is
4933 provided in GNU Fortran to allow user to compile legacy code. For
4934 new code using Fortran 95 pointers, the memory de-allocation intrinsic is
4937 @item @emph{Standard}:
4943 @item @emph{Syntax}:
4944 @code{CALL FREE(PTR)}
4946 @item @emph{Arguments}:
4947 @multitable @columnfractions .15 .70
4948 @item @var{PTR} @tab The type shall be @code{INTEGER}. It represents the
4949 location of the memory that should be de-allocated.
4952 @item @emph{Return value}:
4955 @item @emph{Example}:
4956 See @code{MALLOC} for an example.
4958 @item @emph{See also}:
4965 @section @code{FSEEK} --- Low level file positioning subroutine
4967 @cindex file operation, seek
4968 @cindex file operation, position
4971 @item @emph{Description}:
4972 Moves @var{UNIT} to the specified @var{OFFSET}. If @var{WHENCE}
4973 is set to 0, the @var{OFFSET} is taken as an absolute value @code{SEEK_SET},
4974 if set to 1, @var{OFFSET} is taken to be relative to the current position
4975 @code{SEEK_CUR}, and if set to 2 relative to the end of the file @code{SEEK_END}.
4976 On error, @var{STATUS} is set to a nonzero value. If @var{STATUS} the seek
4979 This intrinsic routine is not fully backwards compatible with @command{g77}.
4980 In @command{g77}, the @code{FSEEK} takes a statement label instead of a
4981 @var{STATUS} variable. If FSEEK is used in old code, change
4983 CALL FSEEK(UNIT, OFFSET, WHENCE, *label)
4988 CALL FSEEK(UNIT, OFFSET, WHENCE, status)
4989 IF (status /= 0) GOTO label
4992 Please note that GNU Fortran provides the Fortran 2003 Stream facility.
4993 Programmers should consider the use of new stream IO feature in new code
4994 for future portability. See also @ref{Fortran 2003 status}.
4996 @item @emph{Standard}:
5002 @item @emph{Syntax}:
5003 @code{CALL FSEEK(UNIT, OFFSET, WHENCE[, STATUS])}
5005 @item @emph{Arguments}:
5006 @multitable @columnfractions .15 .70
5007 @item @var{UNIT} @tab Shall be a scalar of type @code{INTEGER}.
5008 @item @var{OFFSET} @tab Shall be a scalar of type @code{INTEGER}.
5009 @item @var{WHENCE} @tab Shall be a scalar of type @code{INTEGER}.
5010 Its value shall be either 0, 1 or 2.
5011 @item @var{STATUS} @tab (Optional) shall be a scalar of type
5015 @item @emph{Example}:
5018 INTEGER, PARAMETER :: SEEK_SET = 0, SEEK_CUR = 1, SEEK_END = 2
5019 INTEGER :: fd, offset, ierr
5025 OPEN(UNIT=fd, FILE="fseek.test")
5026 CALL FSEEK(fd, offset, SEEK_SET, ierr) ! move to OFFSET
5027 print *, FTELL(fd), ierr
5029 CALL FSEEK(fd, 0, SEEK_END, ierr) ! move to end
5030 print *, FTELL(fd), ierr
5032 CALL FSEEK(fd, 0, SEEK_SET, ierr) ! move to beginning
5033 print *, FTELL(fd), ierr
5039 @item @emph{See also}:
5046 @section @code{FSTAT} --- Get file status
5048 @cindex file system, file status
5051 @item @emph{Description}:
5052 @code{FSTAT} is identical to @ref{STAT}, except that information about an
5053 already opened file is obtained.
5055 The elements in @code{VALUES} are the same as described by @ref{STAT}.
5057 This intrinsic is provided in both subroutine and function forms; however,
5058 only one form can be used in any given program unit.
5060 @item @emph{Standard}:
5064 Subroutine, function
5066 @item @emph{Syntax}:
5067 @multitable @columnfractions .80
5068 @item @code{CALL FSTAT(UNIT, VALUES [, STATUS])}
5069 @item @code{STATUS = FSTAT(UNIT, VALUES)}
5072 @item @emph{Arguments}:
5073 @multitable @columnfractions .15 .70
5074 @item @var{UNIT} @tab An open I/O unit number of type @code{INTEGER}.
5075 @item @var{VALUES} @tab The type shall be @code{INTEGER(4), DIMENSION(13)}.
5076 @item @var{STATUS} @tab (Optional) status flag of type @code{INTEGER(4)}. Returns 0
5077 on success and a system specific error code otherwise.
5080 @item @emph{Example}:
5081 See @ref{STAT} for an example.
5083 @item @emph{See also}:
5084 To stat a link: @ref{LSTAT}, to stat a file: @ref{STAT}
5090 @section @code{FTELL} --- Current stream position
5092 @cindex file operation, position
5095 @item @emph{Description}:
5096 Retrieves the current position within an open file.
5098 This intrinsic is provided in both subroutine and function forms; however,
5099 only one form can be used in any given program unit.
5101 @item @emph{Standard}:
5105 Subroutine, function
5107 @item @emph{Syntax}:
5108 @multitable @columnfractions .80
5109 @item @code{CALL FTELL(UNIT, OFFSET)}
5110 @item @code{OFFSET = FTELL(UNIT)}
5113 @item @emph{Arguments}:
5114 @multitable @columnfractions .15 .70
5115 @item @var{OFFSET} @tab Shall of type @code{INTEGER}.
5116 @item @var{UNIT} @tab Shall of type @code{INTEGER}.
5119 @item @emph{Return value}:
5120 In either syntax, @var{OFFSET} is set to the current offset of unit
5121 number @var{UNIT}, or to @math{-1} if the unit is not currently open.
5123 @item @emph{Example}:
5127 OPEN(10, FILE="temp.dat")
5133 @item @emph{See also}:
5140 @section @code{GAMMA} --- Gamma function
5143 @cindex Gamma function
5144 @cindex Factorial function
5147 @item @emph{Description}:
5148 @code{GAMMA(X)} computes Gamma (@math{\Gamma}) of @var{X}. For positive,
5149 integer values of @var{X} the Gamma function simplifies to the factorial
5150 function @math{\Gamma(x)=(x-1)!}.
5154 \Gamma(x) = \int_0^\infty t^{x-1}{\rm e}^{-t}\,{\rm d}t
5158 @item @emph{Standard}:
5159 Fortran 2008 and later
5164 @item @emph{Syntax}:
5167 @item @emph{Arguments}:
5168 @multitable @columnfractions .15 .70
5169 @item @var{X} @tab Shall be of type @code{REAL} and neither zero
5170 nor a negative integer.
5173 @item @emph{Return value}:
5174 The return value is of type @code{REAL} of the same kind as @var{X}.
5176 @item @emph{Example}:
5180 x = gamma(x) ! returns 1.0
5181 end program test_gamma
5184 @item @emph{Specific names}:
5185 @multitable @columnfractions .20 .20 .20 .25
5186 @item Name @tab Argument @tab Return type @tab Standard
5187 @item @code{GAMMA(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab GNU Extension
5188 @item @code{DGAMMA(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU Extension
5191 @item @emph{See also}:
5192 Logarithm of the Gamma function: @ref{LOG_GAMMA}
5199 @section @code{GERROR} --- Get last system error message
5201 @cindex system, error handling
5204 @item @emph{Description}:
5205 Returns the system error message corresponding to the last system error.
5206 This resembles the functionality of @code{strerror(3)} in C.
5208 @item @emph{Standard}:
5214 @item @emph{Syntax}:
5215 @code{CALL GERROR(RESULT)}
5217 @item @emph{Arguments}:
5218 @multitable @columnfractions .15 .70
5219 @item @var{RESULT} @tab Shall of type @code{CHARACTER} and of default
5222 @item @emph{Example}:
5225 CHARACTER(len=100) :: msg
5231 @item @emph{See also}:
5232 @ref{IERRNO}, @ref{PERROR}
5238 @section @code{GETARG} --- Get command line arguments
5240 @cindex command-line arguments
5241 @cindex arguments, to program
5244 @item @emph{Description}:
5245 Retrieve the @var{POS}-th argument that was passed on the
5246 command line when the containing program was invoked.
5248 This intrinsic routine is provided for backwards compatibility with
5249 GNU Fortran 77. In new code, programmers should consider the use of
5250 the @ref{GET_COMMAND_ARGUMENT} intrinsic defined by the Fortran 2003
5253 @item @emph{Standard}:
5259 @item @emph{Syntax}:
5260 @code{CALL GETARG(POS, VALUE)}
5262 @item @emph{Arguments}:
5263 @multitable @columnfractions .15 .70
5264 @item @var{POS} @tab Shall be of type @code{INTEGER} and not wider than
5265 the default integer kind; @math{@var{POS} \geq 0}
5266 @item @var{VALUE} @tab Shall be of type @code{CHARACTER} and of default
5268 @item @var{VALUE} @tab Shall be of type @code{CHARACTER}.
5271 @item @emph{Return value}:
5272 After @code{GETARG} returns, the @var{VALUE} argument holds the
5273 @var{POS}th command line argument. If @var{VALUE} can not hold the
5274 argument, it is truncated to fit the length of @var{VALUE}. If there are
5275 less than @var{POS} arguments specified at the command line, @var{VALUE}
5276 will be filled with blanks. If @math{@var{POS} = 0}, @var{VALUE} is set
5277 to the name of the program (on systems that support this feature).
5279 @item @emph{Example}:
5283 CHARACTER(len=32) :: arg
5292 @item @emph{See also}:
5293 GNU Fortran 77 compatibility function: @ref{IARGC}
5295 Fortran 2003 functions and subroutines: @ref{GET_COMMAND},
5296 @ref{GET_COMMAND_ARGUMENT}, @ref{COMMAND_ARGUMENT_COUNT}
5302 @section @code{GET_COMMAND} --- Get the entire command line
5303 @fnindex GET_COMMAND
5304 @cindex command-line arguments
5305 @cindex arguments, to program
5308 @item @emph{Description}:
5309 Retrieve the entire command line that was used to invoke the program.
5311 @item @emph{Standard}:
5312 Fortran 2003 and later
5317 @item @emph{Syntax}:
5318 @code{CALL GET_COMMAND([COMMAND, LENGTH, STATUS])}
5320 @item @emph{Arguments}:
5321 @multitable @columnfractions .15 .70
5322 @item @var{COMMAND} @tab (Optional) shall be of type @code{CHARACTER} and
5324 @item @var{LENGTH} @tab (Optional) Shall be of type @code{INTEGER} and of
5326 @item @var{STATUS} @tab (Optional) Shall be of type @code{INTEGER} and of
5330 @item @emph{Return value}:
5331 If @var{COMMAND} is present, stores the entire command line that was used
5332 to invoke the program in @var{COMMAND}. If @var{LENGTH} is present, it is
5333 assigned the length of the command line. If @var{STATUS} is present, it
5334 is assigned 0 upon success of the command, -1 if @var{COMMAND} is too
5335 short to store the command line, or a positive value in case of an error.
5337 @item @emph{Example}:
5339 PROGRAM test_get_command
5340 CHARACTER(len=255) :: cmd
5341 CALL get_command(cmd)
5342 WRITE (*,*) TRIM(cmd)
5346 @item @emph{See also}:
5347 @ref{GET_COMMAND_ARGUMENT}, @ref{COMMAND_ARGUMENT_COUNT}
5352 @node GET_COMMAND_ARGUMENT
5353 @section @code{GET_COMMAND_ARGUMENT} --- Get command line arguments
5354 @fnindex GET_COMMAND_ARGUMENT
5355 @cindex command-line arguments
5356 @cindex arguments, to program
5359 @item @emph{Description}:
5360 Retrieve the @var{NUMBER}-th argument that was passed on the
5361 command line when the containing program was invoked.
5363 @item @emph{Standard}:
5364 Fortran 2003 and later
5369 @item @emph{Syntax}:
5370 @code{CALL GET_COMMAND_ARGUMENT(NUMBER [, VALUE, LENGTH, STATUS])}
5372 @item @emph{Arguments}:
5373 @multitable @columnfractions .15 .70
5374 @item @var{NUMBER} @tab Shall be a scalar of type @code{INTEGER} and of
5375 default kind, @math{@var{NUMBER} \geq 0}
5376 @item @var{VALUE} @tab (Optional) Shall be a scalar of type @code{CHARACTER}
5377 and of default kind.
5378 @item @var{LENGTH} @tab (Optional) Shall be a scalar of type @code{INTEGER}
5379 and of default kind.
5380 @item @var{STATUS} @tab (Optional) Shall be a scalar of type @code{INTEGER}
5381 and of default kind.
5384 @item @emph{Return value}:
5385 After @code{GET_COMMAND_ARGUMENT} returns, the @var{VALUE} argument holds the
5386 @var{NUMBER}-th command line argument. If @var{VALUE} can not hold the argument, it is
5387 truncated to fit the length of @var{VALUE}. If there are less than @var{NUMBER}
5388 arguments specified at the command line, @var{VALUE} will be filled with blanks.
5389 If @math{@var{NUMBER} = 0}, @var{VALUE} is set to the name of the program (on
5390 systems that support this feature). The @var{LENGTH} argument contains the
5391 length of the @var{NUMBER}-th command line argument. If the argument retrieval
5392 fails, @var{STATUS} is a positive number; if @var{VALUE} contains a truncated
5393 command line argument, @var{STATUS} is -1; and otherwise the @var{STATUS} is
5396 @item @emph{Example}:
5398 PROGRAM test_get_command_argument
5400 CHARACTER(len=32) :: arg
5404 CALL get_command_argument(i, arg)
5405 IF (LEN_TRIM(arg) == 0) EXIT
5407 WRITE (*,*) TRIM(arg)
5413 @item @emph{See also}:
5414 @ref{GET_COMMAND}, @ref{COMMAND_ARGUMENT_COUNT}
5420 @section @code{GETCWD} --- Get current working directory
5422 @cindex system, working directory
5425 @item @emph{Description}:
5426 Get current working directory.
5428 This intrinsic is provided in both subroutine and function forms; however,
5429 only one form can be used in any given program unit.
5431 @item @emph{Standard}:
5435 Subroutine, function
5437 @item @emph{Syntax}:
5438 @multitable @columnfractions .80
5439 @item @code{CALL GETCWD(C [, STATUS])}
5440 @item @code{STATUS = GETCWD(C)}
5443 @item @emph{Arguments}:
5444 @multitable @columnfractions .15 .70
5445 @item @var{C} @tab The type shall be @code{CHARACTER} and of default kind.
5446 @item @var{STATUS} @tab (Optional) status flag. Returns 0 on success,
5447 a system specific and nonzero error code otherwise.
5450 @item @emph{Example}:
5453 CHARACTER(len=255) :: cwd
5455 WRITE(*,*) TRIM(cwd)
5459 @item @emph{See also}:
5466 @section @code{GETENV} --- Get an environmental variable
5468 @cindex environment variable
5471 @item @emph{Description}:
5472 Get the @var{VALUE} of the environmental variable @var{NAME}.
5474 This intrinsic routine is provided for backwards compatibility with
5475 GNU Fortran 77. In new code, programmers should consider the use of
5476 the @ref{GET_ENVIRONMENT_VARIABLE} intrinsic defined by the Fortran
5479 Note that @code{GETENV} need not be thread-safe. It is the
5480 responsibility of the user to ensure that the environment is not being
5481 updated concurrently with a call to the @code{GETENV} intrinsic.
5483 @item @emph{Standard}:
5489 @item @emph{Syntax}:
5490 @code{CALL GETENV(NAME, VALUE)}
5492 @item @emph{Arguments}:
5493 @multitable @columnfractions .15 .70
5494 @item @var{NAME} @tab Shall be of type @code{CHARACTER} and of default kind.
5495 @item @var{VALUE} @tab Shall be of type @code{CHARACTER} and of default kind.
5498 @item @emph{Return value}:
5499 Stores the value of @var{NAME} in @var{VALUE}. If @var{VALUE} is
5500 not large enough to hold the data, it is truncated. If @var{NAME}
5501 is not set, @var{VALUE} will be filled with blanks.
5503 @item @emph{Example}:
5506 CHARACTER(len=255) :: homedir
5507 CALL getenv("HOME", homedir)
5508 WRITE (*,*) TRIM(homedir)
5512 @item @emph{See also}:
5513 @ref{GET_ENVIRONMENT_VARIABLE}
5518 @node GET_ENVIRONMENT_VARIABLE
5519 @section @code{GET_ENVIRONMENT_VARIABLE} --- Get an environmental variable
5520 @fnindex GET_ENVIRONMENT_VARIABLE
5521 @cindex environment variable
5524 @item @emph{Description}:
5525 Get the @var{VALUE} of the environmental variable @var{NAME}.
5527 Note that @code{GET_ENVIRONMENT_VARIABLE} need not be thread-safe. It
5528 is the responsibility of the user to ensure that the environment is
5529 not being updated concurrently with a call to the
5530 @code{GET_ENVIRONMENT_VARIABLE} intrinsic.
5532 @item @emph{Standard}:
5533 Fortran 2003 and later
5538 @item @emph{Syntax}:
5539 @code{CALL GET_ENVIRONMENT_VARIABLE(NAME[, VALUE, LENGTH, STATUS, TRIM_NAME)}
5541 @item @emph{Arguments}:
5542 @multitable @columnfractions .15 .70
5543 @item @var{NAME} @tab Shall be a scalar of type @code{CHARACTER}
5544 and of default kind.
5545 @item @var{VALUE} @tab (Optional) Shall be a scalar of type @code{CHARACTER}
5546 and of default kind.
5547 @item @var{LENGTH} @tab (Optional) Shall be a scalar of type @code{INTEGER}
5548 and of default kind.
5549 @item @var{STATUS} @tab (Optional) Shall be a scalar of type @code{INTEGER}
5550 and of default kind.
5551 @item @var{TRIM_NAME} @tab (Optional) Shall be a scalar of type @code{LOGICAL}
5552 and of default kind.
5555 @item @emph{Return value}:
5556 Stores the value of @var{NAME} in @var{VALUE}. If @var{VALUE} is
5557 not large enough to hold the data, it is truncated. If @var{NAME}
5558 is not set, @var{VALUE} will be filled with blanks. Argument @var{LENGTH}
5559 contains the length needed for storing the environment variable @var{NAME}
5560 or zero if it is not present. @var{STATUS} is -1 if @var{VALUE} is present
5561 but too short for the environment variable; it is 1 if the environment
5562 variable does not exist and 2 if the processor does not support environment
5563 variables; in all other cases @var{STATUS} is zero. If @var{TRIM_NAME} is
5564 present with the value @code{.FALSE.}, the trailing blanks in @var{NAME}
5565 are significant; otherwise they are not part of the environment variable
5568 @item @emph{Example}:
5571 CHARACTER(len=255) :: homedir
5572 CALL get_environment_variable("HOME", homedir)
5573 WRITE (*,*) TRIM(homedir)
5581 @section @code{GETGID} --- Group ID function
5583 @cindex system, group ID
5586 @item @emph{Description}:
5587 Returns the numerical group ID of the current process.
5589 @item @emph{Standard}:
5595 @item @emph{Syntax}:
5596 @code{RESULT = GETGID()}
5598 @item @emph{Return value}:
5599 The return value of @code{GETGID} is an @code{INTEGER} of the default
5603 @item @emph{Example}:
5604 See @code{GETPID} for an example.
5606 @item @emph{See also}:
5607 @ref{GETPID}, @ref{GETUID}
5613 @section @code{GETLOG} --- Get login name
5615 @cindex system, login name
5619 @item @emph{Description}:
5620 Gets the username under which the program is running.
5622 @item @emph{Standard}:
5628 @item @emph{Syntax}:
5629 @code{CALL GETLOG(C)}
5631 @item @emph{Arguments}:
5632 @multitable @columnfractions .15 .70
5633 @item @var{C} @tab Shall be of type @code{CHARACTER} and of default kind.
5636 @item @emph{Return value}:
5637 Stores the current user name in @var{LOGIN}. (On systems where POSIX
5638 functions @code{geteuid} and @code{getpwuid} are not available, and
5639 the @code{getlogin} function is not implemented either, this will
5640 return a blank string.)
5642 @item @emph{Example}:
5645 CHARACTER(32) :: login
5651 @item @emph{See also}:
5658 @section @code{GETPID} --- Process ID function
5660 @cindex system, process ID
5664 @item @emph{Description}:
5665 Returns the numerical process identifier of the current process.
5667 @item @emph{Standard}:
5673 @item @emph{Syntax}:
5674 @code{RESULT = GETPID()}
5676 @item @emph{Return value}:
5677 The return value of @code{GETPID} is an @code{INTEGER} of the default
5681 @item @emph{Example}:
5684 print *, "The current process ID is ", getpid()
5685 print *, "Your numerical user ID is ", getuid()
5686 print *, "Your numerical group ID is ", getgid()
5690 @item @emph{See also}:
5691 @ref{GETGID}, @ref{GETUID}
5697 @section @code{GETUID} --- User ID function
5699 @cindex system, user ID
5703 @item @emph{Description}:
5704 Returns the numerical user ID of the current process.
5706 @item @emph{Standard}:
5712 @item @emph{Syntax}:
5713 @code{RESULT = GETUID()}
5715 @item @emph{Return value}:
5716 The return value of @code{GETUID} is an @code{INTEGER} of the default
5720 @item @emph{Example}:
5721 See @code{GETPID} for an example.
5723 @item @emph{See also}:
5724 @ref{GETPID}, @ref{GETLOG}
5730 @section @code{GMTIME} --- Convert time to GMT info
5732 @cindex time, conversion to GMT info
5735 @item @emph{Description}:
5736 Given a system time value @var{TIME} (as provided by the @code{TIME8}
5737 intrinsic), fills @var{VALUES} with values extracted from it appropriate
5738 to the UTC time zone (Universal Coordinated Time, also known in some
5739 countries as GMT, Greenwich Mean Time), using @code{gmtime(3)}.
5741 @item @emph{Standard}:
5747 @item @emph{Syntax}:
5748 @code{CALL GMTIME(TIME, VALUES)}
5750 @item @emph{Arguments}:
5751 @multitable @columnfractions .15 .70
5752 @item @var{TIME} @tab An @code{INTEGER} scalar expression
5753 corresponding to a system time, with @code{INTENT(IN)}.
5754 @item @var{VALUES} @tab A default @code{INTEGER} array with 9 elements,
5755 with @code{INTENT(OUT)}.
5758 @item @emph{Return value}:
5759 The elements of @var{VALUES} are assigned as follows:
5761 @item Seconds after the minute, range 0--59 or 0--61 to allow for leap
5763 @item Minutes after the hour, range 0--59
5764 @item Hours past midnight, range 0--23
5765 @item Day of month, range 0--31
5766 @item Number of months since January, range 0--12
5767 @item Years since 1900
5768 @item Number of days since Sunday, range 0--6
5769 @item Days since January 1
5770 @item Daylight savings indicator: positive if daylight savings is in
5771 effect, zero if not, and negative if the information is not available.
5774 @item @emph{See also}:
5775 @ref{CTIME}, @ref{LTIME}, @ref{TIME}, @ref{TIME8}
5782 @section @code{HOSTNM} --- Get system host name
5784 @cindex system, host name
5787 @item @emph{Description}:
5788 Retrieves the host name of the system on which the program is running.
5790 This intrinsic is provided in both subroutine and function forms; however,
5791 only one form can be used in any given program unit.
5793 @item @emph{Standard}:
5797 Subroutine, function
5799 @item @emph{Syntax}:
5800 @multitable @columnfractions .80
5801 @item @code{CALL HOSTNM(C [, STATUS])}
5802 @item @code{STATUS = HOSTNM(NAME)}
5805 @item @emph{Arguments}:
5806 @multitable @columnfractions .15 .70
5807 @item @var{C} @tab Shall of type @code{CHARACTER} and of default kind.
5808 @item @var{STATUS} @tab (Optional) status flag of type @code{INTEGER}.
5809 Returns 0 on success, or a system specific error code otherwise.
5812 @item @emph{Return value}:
5813 In either syntax, @var{NAME} is set to the current hostname if it can
5814 be obtained, or to a blank string otherwise.
5821 @section @code{HUGE} --- Largest number of a kind
5823 @cindex limits, largest number
5824 @cindex model representation, largest number
5827 @item @emph{Description}:
5828 @code{HUGE(X)} returns the largest number that is not an infinity in
5829 the model of the type of @code{X}.
5831 @item @emph{Standard}:
5832 Fortran 95 and later
5837 @item @emph{Syntax}:
5838 @code{RESULT = HUGE(X)}
5840 @item @emph{Arguments}:
5841 @multitable @columnfractions .15 .70
5842 @item @var{X} @tab Shall be of type @code{REAL} or @code{INTEGER}.
5845 @item @emph{Return value}:
5846 The return value is of the same type and kind as @var{X}
5848 @item @emph{Example}:
5850 program test_huge_tiny
5851 print *, huge(0), huge(0.0), huge(0.0d0)
5852 print *, tiny(0.0), tiny(0.0d0)
5853 end program test_huge_tiny
5860 @section @code{HYPOT} --- Euclidean distance function
5862 @cindex Euclidean distance
5865 @item @emph{Description}:
5866 @code{HYPOT(X,Y)} is the Euclidean distance function. It is equal to
5867 @math{\sqrt{X^2 + Y^2}}, without undue underflow or overflow.
5869 @item @emph{Standard}:
5870 Fortran 2008 and later
5875 @item @emph{Syntax}:
5876 @code{RESULT = HYPOT(X, Y)}
5878 @item @emph{Arguments}:
5879 @multitable @columnfractions .15 .70
5880 @item @var{X} @tab The type shall be @code{REAL}.
5881 @item @var{Y} @tab The type and kind type parameter shall be the same as
5885 @item @emph{Return value}:
5886 The return value has the same type and kind type parameter as @var{X}.
5888 @item @emph{Example}:
5891 real(4) :: x = 1.e0_4, y = 0.5e0_4
5893 end program test_hypot
5900 @section @code{IACHAR} --- Code in @acronym{ASCII} collating sequence
5902 @cindex @acronym{ASCII} collating sequence
5903 @cindex collating sequence, @acronym{ASCII}
5904 @cindex conversion, to integer
5907 @item @emph{Description}:
5908 @code{IACHAR(C)} returns the code for the @acronym{ASCII} character
5909 in the first character position of @code{C}.
5911 @item @emph{Standard}:
5912 Fortran 95 and later, with @var{KIND} argument Fortran 2003 and later
5917 @item @emph{Syntax}:
5918 @code{RESULT = IACHAR(C [, KIND])}
5920 @item @emph{Arguments}:
5921 @multitable @columnfractions .15 .70
5922 @item @var{C} @tab Shall be a scalar @code{CHARACTER}, with @code{INTENT(IN)}
5923 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
5924 expression indicating the kind parameter of the result.
5927 @item @emph{Return value}:
5928 The return value is of type @code{INTEGER} and of kind @var{KIND}. If
5929 @var{KIND} is absent, the return value is of default integer kind.
5931 @item @emph{Example}:
5936 end program test_iachar
5940 See @ref{ICHAR} for a discussion of converting between numerical values
5941 and formatted string representations.
5943 @item @emph{See also}:
5944 @ref{ACHAR}, @ref{CHAR}, @ref{ICHAR}
5951 @section @code{IALL} --- Bitwise AND of array elements
5954 @cindex bits, AND of array elements
5957 @item @emph{Description}:
5958 Reduces with bitwise AND the elements of @var{ARRAY} along dimension @var{DIM}
5959 if the corresponding element in @var{MASK} is @code{TRUE}.
5961 @item @emph{Standard}:
5962 Fortran 2008 and later
5965 Transformational function
5967 @item @emph{Syntax}:
5968 @multitable @columnfractions .80
5969 @item @code{RESULT = IALL(ARRAY[, MASK])}
5970 @item @code{RESULT = IALL(ARRAY, DIM[, MASK])}
5973 @item @emph{Arguments}:
5974 @multitable @columnfractions .15 .70
5975 @item @var{ARRAY} @tab Shall be an array of type @code{INTEGER}
5976 @item @var{DIM} @tab (Optional) shall be a scalar of type
5977 @code{INTEGER} with a value in the range from 1 to n, where n
5978 equals the rank of @var{ARRAY}.
5979 @item @var{MASK} @tab (Optional) shall be of type @code{LOGICAL}
5980 and either be a scalar or an array of the same shape as @var{ARRAY}.
5983 @item @emph{Return value}:
5984 The result is of the same type as @var{ARRAY}.
5986 If @var{DIM} is absent, a scalar with the bitwise ALL of all elements in
5987 @var{ARRAY} is returned. Otherwise, an array of rank n-1, where n equals
5988 the rank of @var{ARRAY}, and a shape similar to that of @var{ARRAY} with
5989 dimension @var{DIM} dropped is returned.
5991 @item @emph{Example}:
6000 PRINT '(b8.8)', IALL(a)
6004 @item @emph{See also}:
6005 @ref{IANY}, @ref{IPARITY}, @ref{IAND}
6011 @section @code{IAND} --- Bitwise logical and
6013 @cindex bitwise logical and
6014 @cindex logical and, bitwise
6017 @item @emph{Description}:
6018 Bitwise logical @code{AND}.
6020 @item @emph{Standard}:
6021 Fortran 95 and later
6026 @item @emph{Syntax}:
6027 @code{RESULT = IAND(I, J)}
6029 @item @emph{Arguments}:
6030 @multitable @columnfractions .15 .70
6031 @item @var{I} @tab The type shall be @code{INTEGER}.
6032 @item @var{J} @tab The type shall be @code{INTEGER}, of the same
6033 kind as @var{I}. (As a GNU extension, different kinds are also
6037 @item @emph{Return value}:
6038 The return type is @code{INTEGER}, of the same kind as the
6039 arguments. (If the argument kinds differ, it is of the same kind as
6040 the larger argument.)
6042 @item @emph{Example}:
6046 DATA a / Z'F' /, b / Z'3' /
6047 WRITE (*,*) IAND(a, b)
6051 @item @emph{See also}:
6052 @ref{IOR}, @ref{IEOR}, @ref{IBITS}, @ref{IBSET}, @ref{IBCLR}, @ref{NOT}
6059 @section @code{IANY} --- Bitwise OR of array elements
6062 @cindex bits, OR of array elements
6065 @item @emph{Description}:
6066 Reduces with bitwise OR (inclusive or) the elements of @var{ARRAY} along
6067 dimension @var{DIM} if the corresponding element in @var{MASK} is @code{TRUE}.
6069 @item @emph{Standard}:
6070 Fortran 2008 and later
6073 Transformational function
6075 @item @emph{Syntax}:
6076 @multitable @columnfractions .80
6077 @item @code{RESULT = IANY(ARRAY[, MASK])}
6078 @item @code{RESULT = IANY(ARRAY, DIM[, MASK])}
6081 @item @emph{Arguments}:
6082 @multitable @columnfractions .15 .70
6083 @item @var{ARRAY} @tab Shall be an array of type @code{INTEGER}
6084 @item @var{DIM} @tab (Optional) shall be a scalar of type
6085 @code{INTEGER} with a value in the range from 1 to n, where n
6086 equals the rank of @var{ARRAY}.
6087 @item @var{MASK} @tab (Optional) shall be of type @code{LOGICAL}
6088 and either be a scalar or an array of the same shape as @var{ARRAY}.
6091 @item @emph{Return value}:
6092 The result is of the same type as @var{ARRAY}.
6094 If @var{DIM} is absent, a scalar with the bitwise OR of all elements in
6095 @var{ARRAY} is returned. Otherwise, an array of rank n-1, where n equals
6096 the rank of @var{ARRAY}, and a shape similar to that of @var{ARRAY} with
6097 dimension @var{DIM} dropped is returned.
6099 @item @emph{Example}:
6108 PRINT '(b8.8)', IANY(a)
6112 @item @emph{See also}:
6113 @ref{IPARITY}, @ref{IALL}, @ref{IOR}
6119 @section @code{IARGC} --- Get the number of command line arguments
6121 @cindex command-line arguments
6122 @cindex command-line arguments, number of
6123 @cindex arguments, to program
6126 @item @emph{Description}:
6127 @code{IARGC} returns the number of arguments passed on the
6128 command line when the containing program was invoked.
6130 This intrinsic routine is provided for backwards compatibility with
6131 GNU Fortran 77. In new code, programmers should consider the use of
6132 the @ref{COMMAND_ARGUMENT_COUNT} intrinsic defined by the Fortran 2003
6135 @item @emph{Standard}:
6141 @item @emph{Syntax}:
6142 @code{RESULT = IARGC()}
6144 @item @emph{Arguments}:
6147 @item @emph{Return value}:
6148 The number of command line arguments, type @code{INTEGER(4)}.
6150 @item @emph{Example}:
6153 @item @emph{See also}:
6154 GNU Fortran 77 compatibility subroutine: @ref{GETARG}
6156 Fortran 2003 functions and subroutines: @ref{GET_COMMAND},
6157 @ref{GET_COMMAND_ARGUMENT}, @ref{COMMAND_ARGUMENT_COUNT}
6163 @section @code{IBCLR} --- Clear bit
6169 @item @emph{Description}:
6170 @code{IBCLR} returns the value of @var{I} with the bit at position
6171 @var{POS} set to zero.
6173 @item @emph{Standard}:
6174 Fortran 95 and later
6179 @item @emph{Syntax}:
6180 @code{RESULT = IBCLR(I, POS)}
6182 @item @emph{Arguments}:
6183 @multitable @columnfractions .15 .70
6184 @item @var{I} @tab The type shall be @code{INTEGER}.
6185 @item @var{POS} @tab The type shall be @code{INTEGER}.
6188 @item @emph{Return value}:
6189 The return value is of type @code{INTEGER} and of the same kind as
6192 @item @emph{See also}:
6193 @ref{IBITS}, @ref{IBSET}, @ref{IAND}, @ref{IOR}, @ref{IEOR}, @ref{MVBITS}
6200 @section @code{IBITS} --- Bit extraction
6203 @cindex bits, extract
6206 @item @emph{Description}:
6207 @code{IBITS} extracts a field of length @var{LEN} from @var{I},
6208 starting from bit position @var{POS} and extending left for @var{LEN}
6209 bits. The result is right-justified and the remaining bits are
6210 zeroed. The value of @code{POS+LEN} must be less than or equal to the
6211 value @code{BIT_SIZE(I)}.
6213 @item @emph{Standard}:
6214 Fortran 95 and later
6219 @item @emph{Syntax}:
6220 @code{RESULT = IBITS(I, POS, LEN)}
6222 @item @emph{Arguments}:
6223 @multitable @columnfractions .15 .70
6224 @item @var{I} @tab The type shall be @code{INTEGER}.
6225 @item @var{POS} @tab The type shall be @code{INTEGER}.
6226 @item @var{LEN} @tab The type shall be @code{INTEGER}.
6229 @item @emph{Return value}:
6230 The return value is of type @code{INTEGER} and of the same kind as
6233 @item @emph{See also}:
6234 @ref{BIT_SIZE}, @ref{IBCLR}, @ref{IBSET}, @ref{IAND}, @ref{IOR}, @ref{IEOR}
6240 @section @code{IBSET} --- Set bit
6245 @item @emph{Description}:
6246 @code{IBSET} returns the value of @var{I} with the bit at position
6247 @var{POS} set to one.
6249 @item @emph{Standard}:
6250 Fortran 95 and later
6255 @item @emph{Syntax}:
6256 @code{RESULT = IBSET(I, POS)}
6258 @item @emph{Arguments}:
6259 @multitable @columnfractions .15 .70
6260 @item @var{I} @tab The type shall be @code{INTEGER}.
6261 @item @var{POS} @tab The type shall be @code{INTEGER}.
6264 @item @emph{Return value}:
6265 The return value is of type @code{INTEGER} and of the same kind as
6268 @item @emph{See also}:
6269 @ref{IBCLR}, @ref{IBITS}, @ref{IAND}, @ref{IOR}, @ref{IEOR}, @ref{MVBITS}
6276 @section @code{ICHAR} --- Character-to-integer conversion function
6278 @cindex conversion, to integer
6281 @item @emph{Description}:
6282 @code{ICHAR(C)} returns the code for the character in the first character
6283 position of @code{C} in the system's native character set.
6284 The correspondence between characters and their codes is not necessarily
6285 the same across different GNU Fortran implementations.
6287 @item @emph{Standard}:
6288 Fortran 95 and later, with @var{KIND} argument Fortran 2003 and later
6293 @item @emph{Syntax}:
6294 @code{RESULT = ICHAR(C [, KIND])}
6296 @item @emph{Arguments}:
6297 @multitable @columnfractions .15 .70
6298 @item @var{C} @tab Shall be a scalar @code{CHARACTER}, with @code{INTENT(IN)}
6299 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
6300 expression indicating the kind parameter of the result.
6303 @item @emph{Return value}:
6304 The return value is of type @code{INTEGER} and of kind @var{KIND}. If
6305 @var{KIND} is absent, the return value is of default integer kind.
6307 @item @emph{Example}:
6312 end program test_ichar
6315 @item @emph{Specific names}:
6316 @multitable @columnfractions .20 .20 .20 .25
6317 @item Name @tab Argument @tab Return type @tab Standard
6318 @item @code{ICHAR(C)} @tab @code{CHARACTER C} @tab @code{INTEGER(4)} @tab Fortran 77 and later
6322 No intrinsic exists to convert between a numeric value and a formatted
6323 character string representation -- for instance, given the
6324 @code{CHARACTER} value @code{'154'}, obtaining an @code{INTEGER} or
6325 @code{REAL} value with the value 154, or vice versa. Instead, this
6326 functionality is provided by internal-file I/O, as in the following
6331 character(len=10) string, string2
6334 ! Convert a string to a numeric value
6335 read (string,'(I10)') value
6338 ! Convert a value to a formatted string
6339 write (string2,'(I10)') value
6341 end program read_val
6344 @item @emph{See also}:
6345 @ref{ACHAR}, @ref{CHAR}, @ref{IACHAR}
6352 @section @code{IDATE} --- Get current local time subroutine (day/month/year)
6354 @cindex date, current
6355 @cindex current date
6358 @item @emph{Description}:
6359 @code{IDATE(VALUES)} Fills @var{VALUES} with the numerical values at the
6360 current local time. The day (in the range 1-31), month (in the range 1-12),
6361 and year appear in elements 1, 2, and 3 of @var{VALUES}, respectively.
6362 The year has four significant digits.
6364 @item @emph{Standard}:
6370 @item @emph{Syntax}:
6371 @code{CALL IDATE(VALUES)}
6373 @item @emph{Arguments}:
6374 @multitable @columnfractions .15 .70
6375 @item @var{VALUES} @tab The type shall be @code{INTEGER, DIMENSION(3)} and
6376 the kind shall be the default integer kind.
6379 @item @emph{Return value}:
6380 Does not return anything.
6382 @item @emph{Example}:
6385 integer, dimension(3) :: tarray
6390 end program test_idate
6397 @section @code{IEOR} --- Bitwise logical exclusive or
6399 @cindex bitwise logical exclusive or
6400 @cindex logical exclusive or, bitwise
6403 @item @emph{Description}:
6404 @code{IEOR} returns the bitwise Boolean exclusive-OR of @var{I} and
6407 @item @emph{Standard}:
6408 Fortran 95 and later
6413 @item @emph{Syntax}:
6414 @code{RESULT = IEOR(I, J)}
6416 @item @emph{Arguments}:
6417 @multitable @columnfractions .15 .70
6418 @item @var{I} @tab The type shall be @code{INTEGER}.
6419 @item @var{J} @tab The type shall be @code{INTEGER}, of the same
6420 kind as @var{I}. (As a GNU extension, different kinds are also
6424 @item @emph{Return value}:
6425 The return type is @code{INTEGER}, of the same kind as the
6426 arguments. (If the argument kinds differ, it is of the same kind as
6427 the larger argument.)
6429 @item @emph{See also}:
6430 @ref{IOR}, @ref{IAND}, @ref{IBITS}, @ref{IBSET}, @ref{IBCLR}, @ref{NOT}
6436 @section @code{IERRNO} --- Get the last system error number
6438 @cindex system, error handling
6441 @item @emph{Description}:
6442 Returns the last system error number, as given by the C @code{errno}
6445 @item @emph{Standard}:
6451 @item @emph{Syntax}:
6452 @code{RESULT = IERRNO()}
6454 @item @emph{Arguments}:
6457 @item @emph{Return value}:
6458 The return value is of type @code{INTEGER} and of the default integer
6461 @item @emph{See also}:
6468 @section @code{IMAGE_INDEX} --- Function that converts a cosubscript to an image index
6469 @fnindex IMAGE_INDEX
6470 @cindex coarray, @code{IMAGE_INDEX}
6471 @cindex images, cosubscript to image index conversion
6474 @item @emph{Description}:
6475 Returns the image index belonging to a cosubscript.
6477 @item @emph{Standard}:
6478 Fortran 2008 and later
6483 @item @emph{Syntax}:
6484 @code{RESULT = IMAGE_INDEX(COARRAY, SUB)}
6486 @item @emph{Arguments}: None.
6487 @multitable @columnfractions .15 .70
6488 @item @var{COARRAY} @tab Coarray of any type.
6489 @item @var{SUB} @tab default integer rank-1 array of a size equal to
6490 the corank of @var{COARRAY}.
6494 @item @emph{Return value}:
6495 Scalar default integer with the value of the image index which corresponds
6496 to the cosubscripts. For invalid cosubscripts the result is zero.
6498 @item @emph{Example}:
6500 INTEGER :: array[2,-1:4,8,*]
6501 ! Writes 28 (or 0 if there are fewer than 28 images)
6502 WRITE (*,*) IMAGE_INDEX (array, [2,0,3,1])
6505 @item @emph{See also}:
6506 @ref{THIS_IMAGE}, @ref{NUM_IMAGES}
6511 @node INDEX intrinsic
6512 @section @code{INDEX} --- Position of a substring within a string
6514 @cindex substring position
6515 @cindex string, find substring
6518 @item @emph{Description}:
6519 Returns the position of the start of the first occurrence of string
6520 @var{SUBSTRING} as a substring in @var{STRING}, counting from one. If
6521 @var{SUBSTRING} is not present in @var{STRING}, zero is returned. If
6522 the @var{BACK} argument is present and true, the return value is the
6523 start of the last occurrence rather than the first.
6525 @item @emph{Standard}:
6526 Fortran 77 and later, with @var{KIND} argument Fortran 2003 and later
6531 @item @emph{Syntax}:
6532 @code{RESULT = INDEX(STRING, SUBSTRING [, BACK [, KIND]])}
6534 @item @emph{Arguments}:
6535 @multitable @columnfractions .15 .70
6536 @item @var{STRING} @tab Shall be a scalar @code{CHARACTER}, with
6538 @item @var{SUBSTRING} @tab Shall be a scalar @code{CHARACTER}, with
6540 @item @var{BACK} @tab (Optional) Shall be a scalar @code{LOGICAL}, with
6542 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
6543 expression indicating the kind parameter of the result.
6546 @item @emph{Return value}:
6547 The return value is of type @code{INTEGER} and of kind @var{KIND}. If
6548 @var{KIND} is absent, the return value is of default integer kind.
6550 @item @emph{Specific names}:
6551 @multitable @columnfractions .20 .20 .20 .25
6552 @item Name @tab Argument @tab Return type @tab Standard
6553 @item @code{INDEX(STRING, SUBSTRING)} @tab @code{CHARACTER} @tab @code{INTEGER(4)} @tab Fortran 77 and later
6556 @item @emph{See also}:
6557 @ref{SCAN}, @ref{VERIFY}
6563 @section @code{INT} --- Convert to integer type
6567 @cindex conversion, to integer
6570 @item @emph{Description}:
6571 Convert to integer type
6573 @item @emph{Standard}:
6574 Fortran 77 and later
6579 @item @emph{Syntax}:
6580 @code{RESULT = INT(A [, KIND))}
6582 @item @emph{Arguments}:
6583 @multitable @columnfractions .15 .70
6584 @item @var{A} @tab Shall be of type @code{INTEGER},
6585 @code{REAL}, or @code{COMPLEX}.
6586 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
6587 expression indicating the kind parameter of the result.
6590 @item @emph{Return value}:
6591 These functions return a @code{INTEGER} variable or array under
6592 the following rules:
6596 If @var{A} is of type @code{INTEGER}, @code{INT(A) = A}
6598 If @var{A} is of type @code{REAL} and @math{|A| < 1}, @code{INT(A)} equals @code{0}.
6599 If @math{|A| \geq 1}, then @code{INT(A)} equals the largest integer that does not exceed
6600 the range of @var{A} and whose sign is the same as the sign of @var{A}.
6602 If @var{A} is of type @code{COMPLEX}, rule B is applied to the real part of @var{A}.
6605 @item @emph{Example}:
6609 complex :: z = (-3.7, 1.0)
6611 print *, int(z), int(z,8)
6615 @item @emph{Specific names}:
6616 @multitable @columnfractions .20 .20 .20 .25
6617 @item Name @tab Argument @tab Return type @tab Standard
6618 @item @code{INT(A)} @tab @code{REAL(4) A} @tab @code{INTEGER} @tab Fortran 77 and later
6619 @item @code{IFIX(A)} @tab @code{REAL(4) A} @tab @code{INTEGER} @tab Fortran 77 and later
6620 @item @code{IDINT(A)} @tab @code{REAL(8) A} @tab @code{INTEGER} @tab Fortran 77 and later
6627 @section @code{INT2} --- Convert to 16-bit integer type
6630 @cindex conversion, to integer
6633 @item @emph{Description}:
6634 Convert to a @code{KIND=2} integer type. This is equivalent to the
6635 standard @code{INT} intrinsic with an optional argument of
6636 @code{KIND=2}, and is only included for backwards compatibility.
6638 The @code{SHORT} intrinsic is equivalent to @code{INT2}.
6640 @item @emph{Standard}:
6646 @item @emph{Syntax}:
6647 @code{RESULT = INT2(A)}
6649 @item @emph{Arguments}:
6650 @multitable @columnfractions .15 .70
6651 @item @var{A} @tab Shall be of type @code{INTEGER},
6652 @code{REAL}, or @code{COMPLEX}.
6655 @item @emph{Return value}:
6656 The return value is a @code{INTEGER(2)} variable.
6658 @item @emph{See also}:
6659 @ref{INT}, @ref{INT8}, @ref{LONG}
6665 @section @code{INT8} --- Convert to 64-bit integer type
6667 @cindex conversion, to integer
6670 @item @emph{Description}:
6671 Convert to a @code{KIND=8} integer type. This is equivalent to the
6672 standard @code{INT} intrinsic with an optional argument of
6673 @code{KIND=8}, and is only included for backwards compatibility.
6675 @item @emph{Standard}:
6681 @item @emph{Syntax}:
6682 @code{RESULT = INT8(A)}
6684 @item @emph{Arguments}:
6685 @multitable @columnfractions .15 .70
6686 @item @var{A} @tab Shall be of type @code{INTEGER},
6687 @code{REAL}, or @code{COMPLEX}.
6690 @item @emph{Return value}:
6691 The return value is a @code{INTEGER(8)} variable.
6693 @item @emph{See also}:
6694 @ref{INT}, @ref{INT2}, @ref{LONG}
6700 @section @code{IOR} --- Bitwise logical or
6702 @cindex bitwise logical or
6703 @cindex logical or, bitwise
6706 @item @emph{Description}:
6707 @code{IOR} returns the bitwise Boolean inclusive-OR of @var{I} and
6710 @item @emph{Standard}:
6711 Fortran 95 and later
6716 @item @emph{Syntax}:
6717 @code{RESULT = IOR(I, J)}
6719 @item @emph{Arguments}:
6720 @multitable @columnfractions .15 .70
6721 @item @var{I} @tab The type shall be @code{INTEGER}.
6722 @item @var{J} @tab The type shall be @code{INTEGER}, of the same
6723 kind as @var{I}. (As a GNU extension, different kinds are also
6727 @item @emph{Return value}:
6728 The return type is @code{INTEGER}, of the same kind as the
6729 arguments. (If the argument kinds differ, it is of the same kind as
6730 the larger argument.)
6732 @item @emph{See also}:
6733 @ref{IEOR}, @ref{IAND}, @ref{IBITS}, @ref{IBSET}, @ref{IBCLR}, @ref{NOT}
6739 @section @code{IPARITY} --- Bitwise XOR of array elements
6741 @cindex array, parity
6743 @cindex bits, XOR of array elements
6746 @item @emph{Description}:
6747 Reduces with bitwise XOR (exclusive or) the elements of @var{ARRAY} along
6748 dimension @var{DIM} if the corresponding element in @var{MASK} is @code{TRUE}.
6750 @item @emph{Standard}:
6751 Fortran 2008 and later
6754 Transformational function
6756 @item @emph{Syntax}:
6757 @multitable @columnfractions .80
6758 @item @code{RESULT = IPARITY(ARRAY[, MASK])}
6759 @item @code{RESULT = IPARITY(ARRAY, DIM[, MASK])}
6762 @item @emph{Arguments}:
6763 @multitable @columnfractions .15 .70
6764 @item @var{ARRAY} @tab Shall be an array of type @code{INTEGER}
6765 @item @var{DIM} @tab (Optional) shall be a scalar of type
6766 @code{INTEGER} with a value in the range from 1 to n, where n
6767 equals the rank of @var{ARRAY}.
6768 @item @var{MASK} @tab (Optional) shall be of type @code{LOGICAL}
6769 and either be a scalar or an array of the same shape as @var{ARRAY}.
6772 @item @emph{Return value}:
6773 The result is of the same type as @var{ARRAY}.
6775 If @var{DIM} is absent, a scalar with the bitwise XOR of all elements in
6776 @var{ARRAY} is returned. Otherwise, an array of rank n-1, where n equals
6777 the rank of @var{ARRAY}, and a shape similar to that of @var{ARRAY} with
6778 dimension @var{DIM} dropped is returned.
6780 @item @emph{Example}:
6782 PROGRAM test_iparity
6789 PRINT '(b8.8)', IPARITY(a)
6793 @item @emph{See also}:
6794 @ref{IANY}, @ref{IALL}, @ref{IEOR}, @ref{PARITY}
6800 @section @code{IRAND} --- Integer pseudo-random number
6802 @cindex random number generation
6805 @item @emph{Description}:
6806 @code{IRAND(FLAG)} returns a pseudo-random number from a uniform
6807 distribution between 0 and a system-dependent limit (which is in most
6808 cases 2147483647). If @var{FLAG} is 0, the next number
6809 in the current sequence is returned; if @var{FLAG} is 1, the generator
6810 is restarted by @code{CALL SRAND(0)}; if @var{FLAG} has any other value,
6811 it is used as a new seed with @code{SRAND}.
6813 This intrinsic routine is provided for backwards compatibility with
6814 GNU Fortran 77. It implements a simple modulo generator as provided
6815 by @command{g77}. For new code, one should consider the use of
6816 @ref{RANDOM_NUMBER} as it implements a superior algorithm.
6818 @item @emph{Standard}:
6824 @item @emph{Syntax}:
6825 @code{RESULT = IRAND(I)}
6827 @item @emph{Arguments}:
6828 @multitable @columnfractions .15 .70
6829 @item @var{I} @tab Shall be a scalar @code{INTEGER} of kind 4.
6832 @item @emph{Return value}:
6833 The return value is of @code{INTEGER(kind=4)} type.
6835 @item @emph{Example}:
6838 integer,parameter :: seed = 86456
6841 print *, irand(), irand(), irand(), irand()
6842 print *, irand(seed), irand(), irand(), irand()
6843 end program test_irand
6851 @section @code{IS_IOSTAT_END} --- Test for end-of-file value
6852 @fnindex IS_IOSTAT_END
6853 @cindex @code{IOSTAT}, end of file
6856 @item @emph{Description}:
6857 @code{IS_IOSTAT_END} tests whether an variable has the value of the I/O
6858 status ``end of file''. The function is equivalent to comparing the variable
6859 with the @code{IOSTAT_END} parameter of the intrinsic module
6860 @code{ISO_FORTRAN_ENV}.
6862 @item @emph{Standard}:
6863 Fortran 2003 and later
6868 @item @emph{Syntax}:
6869 @code{RESULT = IS_IOSTAT_END(I)}
6871 @item @emph{Arguments}:
6872 @multitable @columnfractions .15 .70
6873 @item @var{I} @tab Shall be of the type @code{INTEGER}.
6876 @item @emph{Return value}:
6877 Returns a @code{LOGICAL} of the default kind, which @code{.TRUE.} if
6878 @var{I} has the value which indicates an end of file condition for
6879 @code{IOSTAT=} specifiers, and is @code{.FALSE.} otherwise.
6881 @item @emph{Example}:
6886 OPEN(88, FILE='test.dat')
6887 READ(88, *, IOSTAT=stat) i
6888 IF(IS_IOSTAT_END(stat)) STOP 'END OF FILE'
6896 @section @code{IS_IOSTAT_EOR} --- Test for end-of-record value
6897 @fnindex IS_IOSTAT_EOR
6898 @cindex @code{IOSTAT}, end of record
6901 @item @emph{Description}:
6902 @code{IS_IOSTAT_EOR} tests whether an variable has the value of the I/O
6903 status ``end of record''. The function is equivalent to comparing the
6904 variable with the @code{IOSTAT_EOR} parameter of the intrinsic module
6905 @code{ISO_FORTRAN_ENV}.
6907 @item @emph{Standard}:
6908 Fortran 2003 and later
6913 @item @emph{Syntax}:
6914 @code{RESULT = IS_IOSTAT_EOR(I)}
6916 @item @emph{Arguments}:
6917 @multitable @columnfractions .15 .70
6918 @item @var{I} @tab Shall be of the type @code{INTEGER}.
6921 @item @emph{Return value}:
6922 Returns a @code{LOGICAL} of the default kind, which @code{.TRUE.} if
6923 @var{I} has the value which indicates an end of file condition for
6924 @code{IOSTAT=} specifiers, and is @code{.FALSE.} otherwise.
6926 @item @emph{Example}:
6930 INTEGER :: stat, i(50)
6931 OPEN(88, FILE='test.dat', FORM='UNFORMATTED')
6932 READ(88, IOSTAT=stat) i
6933 IF(IS_IOSTAT_EOR(stat)) STOP 'END OF RECORD'
6941 @section @code{ISATTY} --- Whether a unit is a terminal device.
6943 @cindex system, terminal
6946 @item @emph{Description}:
6947 Determine whether a unit is connected to a terminal device.
6949 @item @emph{Standard}:
6955 @item @emph{Syntax}:
6956 @code{RESULT = ISATTY(UNIT)}
6958 @item @emph{Arguments}:
6959 @multitable @columnfractions .15 .70
6960 @item @var{UNIT} @tab Shall be a scalar @code{INTEGER}.
6963 @item @emph{Return value}:
6964 Returns @code{.TRUE.} if the @var{UNIT} is connected to a terminal
6965 device, @code{.FALSE.} otherwise.
6967 @item @emph{Example}:
6970 INTEGER(kind=1) :: unit
6972 write(*,*) isatty(unit=unit)
6976 @item @emph{See also}:
6983 @section @code{ISHFT} --- Shift bits
6988 @item @emph{Description}:
6989 @code{ISHFT} returns a value corresponding to @var{I} with all of the
6990 bits shifted @var{SHIFT} places. A value of @var{SHIFT} greater than
6991 zero corresponds to a left shift, a value of zero corresponds to no
6992 shift, and a value less than zero corresponds to a right shift. If the
6993 absolute value of @var{SHIFT} is greater than @code{BIT_SIZE(I)}, the
6994 value is undefined. Bits shifted out from the left end or right end are
6995 lost; zeros are shifted in from the opposite end.
6997 @item @emph{Standard}:
6998 Fortran 95 and later
7003 @item @emph{Syntax}:
7004 @code{RESULT = ISHFT(I, SHIFT)}
7006 @item @emph{Arguments}:
7007 @multitable @columnfractions .15 .70
7008 @item @var{I} @tab The type shall be @code{INTEGER}.
7009 @item @var{SHIFT} @tab The type shall be @code{INTEGER}.
7012 @item @emph{Return value}:
7013 The return value is of type @code{INTEGER} and of the same kind as
7016 @item @emph{See also}:
7023 @section @code{ISHFTC} --- Shift bits circularly
7025 @cindex bits, shift circular
7028 @item @emph{Description}:
7029 @code{ISHFTC} returns a value corresponding to @var{I} with the
7030 rightmost @var{SIZE} bits shifted circularly @var{SHIFT} places; that
7031 is, bits shifted out one end are shifted into the opposite end. A value
7032 of @var{SHIFT} greater than zero corresponds to a left shift, a value of
7033 zero corresponds to no shift, and a value less than zero corresponds to
7034 a right shift. The absolute value of @var{SHIFT} must be less than
7035 @var{SIZE}. If the @var{SIZE} argument is omitted, it is taken to be
7036 equivalent to @code{BIT_SIZE(I)}.
7038 @item @emph{Standard}:
7039 Fortran 95 and later
7044 @item @emph{Syntax}:
7045 @code{RESULT = ISHFTC(I, SHIFT [, SIZE])}
7047 @item @emph{Arguments}:
7048 @multitable @columnfractions .15 .70
7049 @item @var{I} @tab The type shall be @code{INTEGER}.
7050 @item @var{SHIFT} @tab The type shall be @code{INTEGER}.
7051 @item @var{SIZE} @tab (Optional) The type shall be @code{INTEGER};
7052 the value must be greater than zero and less than or equal to
7056 @item @emph{Return value}:
7057 The return value is of type @code{INTEGER} and of the same kind as
7060 @item @emph{See also}:
7067 @section @code{ISNAN} --- Test for a NaN
7072 @item @emph{Description}:
7073 @code{ISNAN} tests whether a floating-point value is an IEEE
7075 @item @emph{Standard}:
7081 @item @emph{Syntax}:
7084 @item @emph{Arguments}:
7085 @multitable @columnfractions .15 .70
7086 @item @var{X} @tab Variable of the type @code{REAL}.
7090 @item @emph{Return value}:
7091 Returns a default-kind @code{LOGICAL}. The returned value is @code{TRUE}
7092 if @var{X} is a NaN and @code{FALSE} otherwise.
7094 @item @emph{Example}:
7101 if (isnan(x)) stop '"x" is a NaN'
7102 end program test_nan
7109 @section @code{ITIME} --- Get current local time subroutine (hour/minutes/seconds)
7111 @cindex time, current
7112 @cindex current time
7115 @item @emph{Description}:
7116 @code{IDATE(VALUES)} Fills @var{VALUES} with the numerical values at the
7117 current local time. The hour (in the range 1-24), minute (in the range 1-60),
7118 and seconds (in the range 1-60) appear in elements 1, 2, and 3 of @var{VALUES},
7121 @item @emph{Standard}:
7127 @item @emph{Syntax}:
7128 @code{CALL ITIME(VALUES)}
7130 @item @emph{Arguments}:
7131 @multitable @columnfractions .15 .70
7132 @item @var{VALUES} @tab The type shall be @code{INTEGER, DIMENSION(3)}
7133 and the kind shall be the default integer kind.
7136 @item @emph{Return value}:
7137 Does not return anything.
7140 @item @emph{Example}:
7143 integer, dimension(3) :: tarray
7148 end program test_itime
7155 @section @code{KILL} --- Send a signal to a process
7159 @item @emph{Description}:
7160 @item @emph{Standard}:
7161 Sends the signal specified by @var{SIGNAL} to the process @var{PID}.
7164 This intrinsic is provided in both subroutine and function forms; however,
7165 only one form can be used in any given program unit.
7168 Subroutine, function
7170 @item @emph{Syntax}:
7171 @multitable @columnfractions .80
7172 @item @code{CALL KILL(C, VALUE [, STATUS])}
7173 @item @code{STATUS = KILL(C, VALUE)}
7176 @item @emph{Arguments}:
7177 @multitable @columnfractions .15 .70
7178 @item @var{C} @tab Shall be a scalar @code{INTEGER}, with
7180 @item @var{VALUE} @tab Shall be a scalar @code{INTEGER}, with
7182 @item @var{STATUS} @tab (Optional) status flag of type @code{INTEGER(4)} or
7183 @code{INTEGER(8)}. Returns 0 on success, or a system-specific error code
7187 @item @emph{See also}:
7188 @ref{ABORT}, @ref{EXIT}
7194 @section @code{KIND} --- Kind of an entity
7199 @item @emph{Description}:
7200 @code{KIND(X)} returns the kind value of the entity @var{X}.
7202 @item @emph{Standard}:
7203 Fortran 95 and later
7208 @item @emph{Syntax}:
7211 @item @emph{Arguments}:
7212 @multitable @columnfractions .15 .70
7213 @item @var{X} @tab Shall be of type @code{LOGICAL}, @code{INTEGER},
7214 @code{REAL}, @code{COMPLEX} or @code{CHARACTER}.
7217 @item @emph{Return value}:
7218 The return value is a scalar of type @code{INTEGER} and of the default
7221 @item @emph{Example}:
7224 integer,parameter :: kc = kind(' ')
7225 integer,parameter :: kl = kind(.true.)
7227 print *, "The default character kind is ", kc
7228 print *, "The default logical kind is ", kl
7229 end program test_kind
7237 @section @code{LBOUND} --- Lower dimension bounds of an array
7239 @cindex array, lower bound
7242 @item @emph{Description}:
7243 Returns the lower bounds of an array, or a single lower bound
7244 along the @var{DIM} dimension.
7245 @item @emph{Standard}:
7246 Fortran 95 and later, with @var{KIND} argument Fortran 2003 and later
7251 @item @emph{Syntax}:
7252 @code{RESULT = LBOUND(ARRAY [, DIM [, KIND]])}
7254 @item @emph{Arguments}:
7255 @multitable @columnfractions .15 .70
7256 @item @var{ARRAY} @tab Shall be an array, of any type.
7257 @item @var{DIM} @tab (Optional) Shall be a scalar @code{INTEGER}.
7258 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
7259 expression indicating the kind parameter of the result.
7262 @item @emph{Return value}:
7263 The return value is of type @code{INTEGER} and of kind @var{KIND}. If
7264 @var{KIND} is absent, the return value is of default integer kind.
7265 If @var{DIM} is absent, the result is an array of the lower bounds of
7266 @var{ARRAY}. If @var{DIM} is present, the result is a scalar
7267 corresponding to the lower bound of the array along that dimension. If
7268 @var{ARRAY} is an expression rather than a whole array or array
7269 structure component, or if it has a zero extent along the relevant
7270 dimension, the lower bound is taken to be 1.
7272 @item @emph{See also}:
7273 @ref{UBOUND}, @ref{LCOBOUND}
7279 @section @code{LCOBOUND} --- Lower codimension bounds of an array
7281 @cindex coarray, lower bound
7284 @item @emph{Description}:
7285 Returns the lower bounds of a coarray, or a single lower cobound
7286 along the @var{DIM} codimension.
7287 @item @emph{Standard}:
7288 Fortran 2008 and later
7293 @item @emph{Syntax}:
7294 @code{RESULT = LCOBOUND(COARRAY [, DIM [, KIND]])}
7296 @item @emph{Arguments}:
7297 @multitable @columnfractions .15 .70
7298 @item @var{ARRAY} @tab Shall be an coarray, of any type.
7299 @item @var{DIM} @tab (Optional) Shall be a scalar @code{INTEGER}.
7300 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
7301 expression indicating the kind parameter of the result.
7304 @item @emph{Return value}:
7305 The return value is of type @code{INTEGER} and of kind @var{KIND}. If
7306 @var{KIND} is absent, the return value is of default integer kind.
7307 If @var{DIM} is absent, the result is an array of the lower cobounds of
7308 @var{COARRAY}. If @var{DIM} is present, the result is a scalar
7309 corresponding to the lower cobound of the array along that codimension.
7311 @item @emph{See also}:
7312 @ref{UCOBOUND}, @ref{LBOUND}
7318 @section @code{LEADZ} --- Number of leading zero bits of an integer
7323 @item @emph{Description}:
7324 @code{LEADZ} returns the number of leading zero bits of an integer.
7326 @item @emph{Standard}:
7327 Fortran 2008 and later
7332 @item @emph{Syntax}:
7333 @code{RESULT = LEADZ(I)}
7335 @item @emph{Arguments}:
7336 @multitable @columnfractions .15 .70
7337 @item @var{I} @tab Shall be of type @code{INTEGER}.
7340 @item @emph{Return value}:
7341 The type of the return value is the default @code{INTEGER}.
7342 If all the bits of @code{I} are zero, the result value is @code{BIT_SIZE(I)}.
7344 @item @emph{Example}:
7347 WRITE (*,*) BIT_SIZE(1) ! prints 32
7348 WRITE (*,*) LEADZ(1) ! prints 31
7352 @item @emph{See also}:
7353 @ref{BIT_SIZE}, @ref{TRAILZ}, @ref{POPCNT}, @ref{POPPAR}
7359 @section @code{LEN} --- Length of a character entity
7361 @cindex string, length
7364 @item @emph{Description}:
7365 Returns the length of a character string. If @var{STRING} is an array,
7366 the length of an element of @var{STRING} is returned. Note that
7367 @var{STRING} need not be defined when this intrinsic is invoked, since
7368 only the length, not the content, of @var{STRING} is needed.
7370 @item @emph{Standard}:
7371 Fortran 77 and later, with @var{KIND} argument Fortran 2003 and later
7376 @item @emph{Syntax}:
7377 @code{L = LEN(STRING [, KIND])}
7379 @item @emph{Arguments}:
7380 @multitable @columnfractions .15 .70
7381 @item @var{STRING} @tab Shall be a scalar or array of type
7382 @code{CHARACTER}, with @code{INTENT(IN)}
7383 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
7384 expression indicating the kind parameter of the result.
7387 @item @emph{Return value}:
7388 The return value is of type @code{INTEGER} and of kind @var{KIND}. If
7389 @var{KIND} is absent, the return value is of default integer kind.
7392 @item @emph{Specific names}:
7393 @multitable @columnfractions .20 .20 .20 .25
7394 @item Name @tab Argument @tab Return type @tab Standard
7395 @item @code{LEN(STRING)} @tab @code{CHARACTER} @tab @code{INTEGER} @tab Fortran 77 and later
7399 @item @emph{See also}:
7400 @ref{LEN_TRIM}, @ref{ADJUSTL}, @ref{ADJUSTR}
7406 @section @code{LEN_TRIM} --- Length of a character entity without trailing blank characters
7408 @cindex string, length, without trailing whitespace
7411 @item @emph{Description}:
7412 Returns the length of a character string, ignoring any trailing blanks.
7414 @item @emph{Standard}:
7415 Fortran 95 and later, with @var{KIND} argument Fortran 2003 and later
7420 @item @emph{Syntax}:
7421 @code{RESULT = LEN_TRIM(STRING [, KIND])}
7423 @item @emph{Arguments}:
7424 @multitable @columnfractions .15 .70
7425 @item @var{STRING} @tab Shall be a scalar of type @code{CHARACTER},
7426 with @code{INTENT(IN)}
7427 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
7428 expression indicating the kind parameter of the result.
7431 @item @emph{Return value}:
7432 The return value is of type @code{INTEGER} and of kind @var{KIND}. If
7433 @var{KIND} is absent, the return value is of default integer kind.
7435 @item @emph{See also}:
7436 @ref{LEN}, @ref{ADJUSTL}, @ref{ADJUSTR}
7442 @section @code{LGE} --- Lexical greater than or equal
7444 @cindex lexical comparison of strings
7445 @cindex string, comparison
7448 @item @emph{Description}:
7449 Determines whether one string is lexically greater than or equal to
7450 another string, where the two strings are interpreted as containing
7451 ASCII character codes. If the String A and String B are not the same
7452 length, the shorter is compared as if spaces were appended to it to form
7453 a value that has the same length as the longer.
7455 In general, the lexical comparison intrinsics @code{LGE}, @code{LGT},
7456 @code{LLE}, and @code{LLT} differ from the corresponding intrinsic
7457 operators @code{.GE.}, @code{.GT.}, @code{.LE.}, and @code{.LT.}, in
7458 that the latter use the processor's character ordering (which is not
7459 ASCII on some targets), whereas the former always use the ASCII
7462 @item @emph{Standard}:
7463 Fortran 77 and later
7468 @item @emph{Syntax}:
7469 @code{RESULT = LGE(STRING_A, STRING_B)}
7471 @item @emph{Arguments}:
7472 @multitable @columnfractions .15 .70
7473 @item @var{STRING_A} @tab Shall be of default @code{CHARACTER} type.
7474 @item @var{STRING_B} @tab Shall be of default @code{CHARACTER} type.
7477 @item @emph{Return value}:
7478 Returns @code{.TRUE.} if @code{STRING_A >= STRING_B}, and @code{.FALSE.}
7479 otherwise, based on the ASCII ordering.
7481 @item @emph{Specific names}:
7482 @multitable @columnfractions .20 .20 .20 .25
7483 @item Name @tab Argument @tab Return type @tab Standard
7484 @item @code{LGE(STRING_A, STRING_B)} @tab @code{CHARACTER} @tab @code{LOGICAL} @tab Fortran 77 and later
7487 @item @emph{See also}:
7488 @ref{LGT}, @ref{LLE}, @ref{LLT}
7494 @section @code{LGT} --- Lexical greater than
7496 @cindex lexical comparison of strings
7497 @cindex string, comparison
7500 @item @emph{Description}:
7501 Determines whether one string is lexically greater than another string,
7502 where the two strings are interpreted as containing ASCII character
7503 codes. If the String A and String B are not the same length, the
7504 shorter is compared as if spaces were appended to it to form a value
7505 that has the same length as the longer.
7507 In general, the lexical comparison intrinsics @code{LGE}, @code{LGT},
7508 @code{LLE}, and @code{LLT} differ from the corresponding intrinsic
7509 operators @code{.GE.}, @code{.GT.}, @code{.LE.}, and @code{.LT.}, in
7510 that the latter use the processor's character ordering (which is not
7511 ASCII on some targets), whereas the former always use the ASCII
7514 @item @emph{Standard}:
7515 Fortran 77 and later
7520 @item @emph{Syntax}:
7521 @code{RESULT = LGT(STRING_A, STRING_B)}
7523 @item @emph{Arguments}:
7524 @multitable @columnfractions .15 .70
7525 @item @var{STRING_A} @tab Shall be of default @code{CHARACTER} type.
7526 @item @var{STRING_B} @tab Shall be of default @code{CHARACTER} type.
7529 @item @emph{Return value}:
7530 Returns @code{.TRUE.} if @code{STRING_A > STRING_B}, and @code{.FALSE.}
7531 otherwise, based on the ASCII ordering.
7533 @item @emph{Specific names}:
7534 @multitable @columnfractions .20 .20 .20 .25
7535 @item Name @tab Argument @tab Return type @tab Standard
7536 @item @code{LGT(STRING_A, STRING_B)} @tab @code{CHARACTER} @tab @code{LOGICAL} @tab Fortran 77 and later
7539 @item @emph{See also}:
7540 @ref{LGE}, @ref{LLE}, @ref{LLT}
7546 @section @code{LINK} --- Create a hard link
7548 @cindex file system, create link
7549 @cindex file system, hard link
7552 @item @emph{Description}:
7553 Makes a (hard) link from file @var{PATH1} to @var{PATH2}. A null
7554 character (@code{CHAR(0)}) can be used to mark the end of the names in
7555 @var{PATH1} and @var{PATH2}; otherwise, trailing blanks in the file
7556 names are ignored. If the @var{STATUS} argument is supplied, it
7557 contains 0 on success or a nonzero error code upon return; see
7560 This intrinsic is provided in both subroutine and function forms;
7561 however, only one form can be used in any given program unit.
7563 @item @emph{Standard}:
7567 Subroutine, function
7569 @item @emph{Syntax}:
7570 @multitable @columnfractions .80
7571 @item @code{CALL LINK(PATH1, PATH2 [, STATUS])}
7572 @item @code{STATUS = LINK(PATH1, PATH2)}
7575 @item @emph{Arguments}:
7576 @multitable @columnfractions .15 .70
7577 @item @var{PATH1} @tab Shall be of default @code{CHARACTER} type.
7578 @item @var{PATH2} @tab Shall be of default @code{CHARACTER} type.
7579 @item @var{STATUS} @tab (Optional) Shall be of default @code{INTEGER} type.
7582 @item @emph{See also}:
7583 @ref{SYMLNK}, @ref{UNLINK}
7589 @section @code{LLE} --- Lexical less than or equal
7591 @cindex lexical comparison of strings
7592 @cindex string, comparison
7595 @item @emph{Description}:
7596 Determines whether one string is lexically less than or equal to another
7597 string, where the two strings are interpreted as containing ASCII
7598 character codes. If the String A and String B are not the same length,
7599 the shorter is compared as if spaces were appended to it to form a value
7600 that has the same length as the longer.
7602 In general, the lexical comparison intrinsics @code{LGE}, @code{LGT},
7603 @code{LLE}, and @code{LLT} differ from the corresponding intrinsic
7604 operators @code{.GE.}, @code{.GT.}, @code{.LE.}, and @code{.LT.}, in
7605 that the latter use the processor's character ordering (which is not
7606 ASCII on some targets), whereas the former always use the ASCII
7609 @item @emph{Standard}:
7610 Fortran 77 and later
7615 @item @emph{Syntax}:
7616 @code{RESULT = LLE(STRING_A, STRING_B)}
7618 @item @emph{Arguments}:
7619 @multitable @columnfractions .15 .70
7620 @item @var{STRING_A} @tab Shall be of default @code{CHARACTER} type.
7621 @item @var{STRING_B} @tab Shall be of default @code{CHARACTER} type.
7624 @item @emph{Return value}:
7625 Returns @code{.TRUE.} if @code{STRING_A <= STRING_B}, and @code{.FALSE.}
7626 otherwise, based on the ASCII ordering.
7628 @item @emph{Specific names}:
7629 @multitable @columnfractions .20 .20 .20 .25
7630 @item Name @tab Argument @tab Return type @tab Standard
7631 @item @code{LLE(STRING_A, STRING_B)} @tab @code{CHARACTER} @tab @code{LOGICAL} @tab Fortran 77 and later
7634 @item @emph{See also}:
7635 @ref{LGE}, @ref{LGT}, @ref{LLT}
7641 @section @code{LLT} --- Lexical less than
7643 @cindex lexical comparison of strings
7644 @cindex string, comparison
7647 @item @emph{Description}:
7648 Determines whether one string is lexically less than another string,
7649 where the two strings are interpreted as containing ASCII character
7650 codes. If the String A and String B are not the same length, the
7651 shorter is compared as if spaces were appended to it to form a value
7652 that has the same length as the longer.
7654 In general, the lexical comparison intrinsics @code{LGE}, @code{LGT},
7655 @code{LLE}, and @code{LLT} differ from the corresponding intrinsic
7656 operators @code{.GE.}, @code{.GT.}, @code{.LE.}, and @code{.LT.}, in
7657 that the latter use the processor's character ordering (which is not
7658 ASCII on some targets), whereas the former always use the ASCII
7661 @item @emph{Standard}:
7662 Fortran 77 and later
7667 @item @emph{Syntax}:
7668 @code{RESULT = LLT(STRING_A, STRING_B)}
7670 @item @emph{Arguments}:
7671 @multitable @columnfractions .15 .70
7672 @item @var{STRING_A} @tab Shall be of default @code{CHARACTER} type.
7673 @item @var{STRING_B} @tab Shall be of default @code{CHARACTER} type.
7676 @item @emph{Return value}:
7677 Returns @code{.TRUE.} if @code{STRING_A < STRING_B}, and @code{.FALSE.}
7678 otherwise, based on the ASCII ordering.
7680 @item @emph{Specific names}:
7681 @multitable @columnfractions .20 .20 .20 .25
7682 @item Name @tab Argument @tab Return type @tab Standard
7683 @item @code{LLT(STRING_A, STRING_B)} @tab @code{CHARACTER} @tab @code{LOGICAL} @tab Fortran 77 and later
7686 @item @emph{See also}:
7687 @ref{LGE}, @ref{LGT}, @ref{LLE}
7693 @section @code{LNBLNK} --- Index of the last non-blank character in a string
7695 @cindex string, find non-blank character
7698 @item @emph{Description}:
7699 Returns the length of a character string, ignoring any trailing blanks.
7700 This is identical to the standard @code{LEN_TRIM} intrinsic, and is only
7701 included for backwards compatibility.
7703 @item @emph{Standard}:
7709 @item @emph{Syntax}:
7710 @code{RESULT = LNBLNK(STRING)}
7712 @item @emph{Arguments}:
7713 @multitable @columnfractions .15 .70
7714 @item @var{STRING} @tab Shall be a scalar of type @code{CHARACTER},
7715 with @code{INTENT(IN)}
7718 @item @emph{Return value}:
7719 The return value is of @code{INTEGER(kind=4)} type.
7721 @item @emph{See also}:
7722 @ref{INDEX intrinsic}, @ref{LEN_TRIM}
7728 @section @code{LOC} --- Returns the address of a variable
7730 @cindex location of a variable in memory
7733 @item @emph{Description}:
7734 @code{LOC(X)} returns the address of @var{X} as an integer.
7736 @item @emph{Standard}:
7742 @item @emph{Syntax}:
7743 @code{RESULT = LOC(X)}
7745 @item @emph{Arguments}:
7746 @multitable @columnfractions .15 .70
7747 @item @var{X} @tab Variable of any type.
7750 @item @emph{Return value}:
7751 The return value is of type @code{INTEGER}, with a @code{KIND}
7752 corresponding to the size (in bytes) of a memory address on the target
7755 @item @emph{Example}:
7762 end program test_loc
7769 @section @code{LOG} --- Natural logarithm function
7776 @cindex exponential function, inverse
7777 @cindex logarithm function
7778 @cindex natural logarithm function
7781 @item @emph{Description}:
7782 @code{LOG(X)} computes the natural logarithm of @var{X}, i.e. the
7783 logarithm to the base @math{e}.
7785 @item @emph{Standard}:
7786 Fortran 77 and later
7791 @item @emph{Syntax}:
7792 @code{RESULT = LOG(X)}
7794 @item @emph{Arguments}:
7795 @multitable @columnfractions .15 .70
7796 @item @var{X} @tab The type shall be @code{REAL} or
7800 @item @emph{Return value}:
7801 The return value is of type @code{REAL} or @code{COMPLEX}.
7802 The kind type parameter is the same as @var{X}.
7803 If @var{X} is @code{COMPLEX}, the imaginary part @math{\omega} is in the range
7804 @math{-\pi \leq \omega \leq \pi}.
7806 @item @emph{Example}:
7809 real(8) :: x = 2.7182818284590451_8
7810 complex :: z = (1.0, 2.0)
7811 x = log(x) ! will yield (approximately) 1
7813 end program test_log
7816 @item @emph{Specific names}:
7817 @multitable @columnfractions .20 .20 .20 .25
7818 @item Name @tab Argument @tab Return type @tab Standard
7819 @item @code{ALOG(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab f95, gnu
7820 @item @code{DLOG(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab f95, gnu
7821 @item @code{CLOG(X)} @tab @code{COMPLEX(4) X} @tab @code{COMPLEX(4)} @tab f95, gnu
7822 @item @code{ZLOG(X)} @tab @code{COMPLEX(8) X} @tab @code{COMPLEX(8)} @tab f95, gnu
7823 @item @code{CDLOG(X)} @tab @code{COMPLEX(8) X} @tab @code{COMPLEX(8)} @tab f95, gnu
7830 @section @code{LOG10} --- Base 10 logarithm function
7834 @cindex exponential function, inverse
7835 @cindex logarithm function with base 10
7836 @cindex base 10 logarithm function
7839 @item @emph{Description}:
7840 @code{LOG10(X)} computes the base 10 logarithm of @var{X}.
7842 @item @emph{Standard}:
7843 Fortran 77 and later
7848 @item @emph{Syntax}:
7849 @code{RESULT = LOG10(X)}
7851 @item @emph{Arguments}:
7852 @multitable @columnfractions .15 .70
7853 @item @var{X} @tab The type shall be @code{REAL}.
7856 @item @emph{Return value}:
7857 The return value is of type @code{REAL} or @code{COMPLEX}.
7858 The kind type parameter is the same as @var{X}.
7860 @item @emph{Example}:
7863 real(8) :: x = 10.0_8
7865 end program test_log10
7868 @item @emph{Specific names}:
7869 @multitable @columnfractions .20 .20 .20 .25
7870 @item Name @tab Argument @tab Return type @tab Standard
7871 @item @code{ALOG10(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab Fortran 95 and later
7872 @item @code{DLOG10(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab Fortran 95 and later
7879 @section @code{LOG_GAMMA} --- Logarithm of the Gamma function
7884 @cindex Gamma function, logarithm of
7887 @item @emph{Description}:
7888 @code{LOG_GAMMA(X)} computes the natural logarithm of the absolute value
7889 of the Gamma (@math{\Gamma}) function.
7891 @item @emph{Standard}:
7892 Fortran 2008 and later
7897 @item @emph{Syntax}:
7898 @code{X = LOG_GAMMA(X)}
7900 @item @emph{Arguments}:
7901 @multitable @columnfractions .15 .70
7902 @item @var{X} @tab Shall be of type @code{REAL} and neither zero
7903 nor a negative integer.
7906 @item @emph{Return value}:
7907 The return value is of type @code{REAL} of the same kind as @var{X}.
7909 @item @emph{Example}:
7911 program test_log_gamma
7913 x = lgamma(x) ! returns 0.0
7914 end program test_log_gamma
7917 @item @emph{Specific names}:
7918 @multitable @columnfractions .20 .20 .20 .25
7919 @item Name @tab Argument @tab Return type @tab Standard
7920 @item @code{LGAMMA(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab GNU Extension
7921 @item @code{ALGAMA(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab GNU Extension
7922 @item @code{DLGAMA(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU Extension
7925 @item @emph{See also}:
7926 Gamma function: @ref{GAMMA}
7933 @section @code{LOGICAL} --- Convert to logical type
7935 @cindex conversion, to logical
7938 @item @emph{Description}:
7939 Converts one kind of @code{LOGICAL} variable to another.
7941 @item @emph{Standard}:
7942 Fortran 95 and later
7947 @item @emph{Syntax}:
7948 @code{RESULT = LOGICAL(L [, KIND])}
7950 @item @emph{Arguments}:
7951 @multitable @columnfractions .15 .70
7952 @item @var{L} @tab The type shall be @code{LOGICAL}.
7953 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
7954 expression indicating the kind parameter of the result.
7957 @item @emph{Return value}:
7958 The return value is a @code{LOGICAL} value equal to @var{L}, with a
7959 kind corresponding to @var{KIND}, or of the default logical kind if
7960 @var{KIND} is not given.
7962 @item @emph{See also}:
7963 @ref{INT}, @ref{REAL}, @ref{CMPLX}
7969 @section @code{LONG} --- Convert to integer type
7971 @cindex conversion, to integer
7974 @item @emph{Description}:
7975 Convert to a @code{KIND=4} integer type, which is the same size as a C
7976 @code{long} integer. This is equivalent to the standard @code{INT}
7977 intrinsic with an optional argument of @code{KIND=4}, and is only
7978 included for backwards compatibility.
7980 @item @emph{Standard}:
7986 @item @emph{Syntax}:
7987 @code{RESULT = LONG(A)}
7989 @item @emph{Arguments}:
7990 @multitable @columnfractions .15 .70
7991 @item @var{A} @tab Shall be of type @code{INTEGER},
7992 @code{REAL}, or @code{COMPLEX}.
7995 @item @emph{Return value}:
7996 The return value is a @code{INTEGER(4)} variable.
7998 @item @emph{See also}:
7999 @ref{INT}, @ref{INT2}, @ref{INT8}
8005 @section @code{LSHIFT} --- Left shift bits
8007 @cindex bits, shift left
8010 @item @emph{Description}:
8011 @code{LSHIFT} returns a value corresponding to @var{I} with all of the
8012 bits shifted left by @var{SHIFT} places. If the absolute value of
8013 @var{SHIFT} is greater than @code{BIT_SIZE(I)}, the value is undefined.
8014 Bits shifted out from the left end are lost; zeros are shifted in from
8017 This function has been superseded by the @code{ISHFT} intrinsic, which
8018 is standard in Fortran 95 and later, and the @code{SHIFTL} intrinsic,
8019 which is standard in Fortran 2008 and later.
8021 @item @emph{Standard}:
8027 @item @emph{Syntax}:
8028 @code{RESULT = LSHIFT(I, SHIFT)}
8030 @item @emph{Arguments}:
8031 @multitable @columnfractions .15 .70
8032 @item @var{I} @tab The type shall be @code{INTEGER}.
8033 @item @var{SHIFT} @tab The type shall be @code{INTEGER}.
8036 @item @emph{Return value}:
8037 The return value is of type @code{INTEGER} and of the same kind as
8040 @item @emph{See also}:
8041 @ref{ISHFT}, @ref{ISHFTC}, @ref{RSHIFT}, @ref{SHIFTA}, @ref{SHIFTL},
8049 @section @code{LSTAT} --- Get file status
8051 @cindex file system, file status
8054 @item @emph{Description}:
8055 @code{LSTAT} is identical to @ref{STAT}, except that if path is a
8056 symbolic link, then the link itself is statted, not the file that it
8059 The elements in @code{VALUES} are the same as described by @ref{STAT}.
8061 This intrinsic is provided in both subroutine and function forms;
8062 however, only one form can be used in any given program unit.
8064 @item @emph{Standard}:
8068 Subroutine, function
8070 @item @emph{Syntax}:
8071 @multitable @columnfractions .80
8072 @item @code{CALL LSTAT(NAME, VALUES [, STATUS])}
8073 @item @code{STATUS = LSTAT(NAME, VALUES)}
8076 @item @emph{Arguments}:
8077 @multitable @columnfractions .15 .70
8078 @item @var{NAME} @tab The type shall be @code{CHARACTER} of the default
8079 kind, a valid path within the file system.
8080 @item @var{VALUES} @tab The type shall be @code{INTEGER(4), DIMENSION(13)}.
8081 @item @var{STATUS} @tab (Optional) status flag of type @code{INTEGER(4)}.
8082 Returns 0 on success and a system specific error code otherwise.
8085 @item @emph{Example}:
8086 See @ref{STAT} for an example.
8088 @item @emph{See also}:
8089 To stat an open file: @ref{FSTAT}, to stat a file: @ref{STAT}
8095 @section @code{LTIME} --- Convert time to local time info
8097 @cindex time, conversion to local time info
8100 @item @emph{Description}:
8101 Given a system time value @var{TIME} (as provided by the @code{TIME8}
8102 intrinsic), fills @var{VALUES} with values extracted from it appropriate
8103 to the local time zone using @code{localtime(3)}.
8105 @item @emph{Standard}:
8111 @item @emph{Syntax}:
8112 @code{CALL LTIME(TIME, VALUES)}
8114 @item @emph{Arguments}:
8115 @multitable @columnfractions .15 .70
8116 @item @var{TIME} @tab An @code{INTEGER} scalar expression
8117 corresponding to a system time, with @code{INTENT(IN)}.
8118 @item @var{VALUES} @tab A default @code{INTEGER} array with 9 elements,
8119 with @code{INTENT(OUT)}.
8122 @item @emph{Return value}:
8123 The elements of @var{VALUES} are assigned as follows:
8125 @item Seconds after the minute, range 0--59 or 0--61 to allow for leap
8127 @item Minutes after the hour, range 0--59
8128 @item Hours past midnight, range 0--23
8129 @item Day of month, range 0--31
8130 @item Number of months since January, range 0--12
8131 @item Years since 1900
8132 @item Number of days since Sunday, range 0--6
8133 @item Days since January 1
8134 @item Daylight savings indicator: positive if daylight savings is in
8135 effect, zero if not, and negative if the information is not available.
8138 @item @emph{See also}:
8139 @ref{CTIME}, @ref{GMTIME}, @ref{TIME}, @ref{TIME8}
8146 @section @code{MALLOC} --- Allocate dynamic memory
8148 @cindex pointer, cray
8151 @item @emph{Description}:
8152 @code{MALLOC(SIZE)} allocates @var{SIZE} bytes of dynamic memory and
8153 returns the address of the allocated memory. The @code{MALLOC} intrinsic
8154 is an extension intended to be used with Cray pointers, and is provided
8155 in GNU Fortran to allow the user to compile legacy code. For new code
8156 using Fortran 95 pointers, the memory allocation intrinsic is
8159 @item @emph{Standard}:
8165 @item @emph{Syntax}:
8166 @code{PTR = MALLOC(SIZE)}
8168 @item @emph{Arguments}:
8169 @multitable @columnfractions .15 .70
8170 @item @var{SIZE} @tab The type shall be @code{INTEGER}.
8173 @item @emph{Return value}:
8174 The return value is of type @code{INTEGER(K)}, with @var{K} such that
8175 variables of type @code{INTEGER(K)} have the same size as
8176 C pointers (@code{sizeof(void *)}).
8178 @item @emph{Example}:
8179 The following example demonstrates the use of @code{MALLOC} and
8180 @code{FREE} with Cray pointers.
8189 ptr_x = malloc(20*8)
8191 x(i) = sqrt(1.0d0 / i)
8199 end program test_malloc
8202 @item @emph{See also}:
8209 @section @code{MASKL} --- Left justified mask
8211 @cindex mask, left justified
8214 @item @emph{Description}:
8215 @code{MASKL(I[, KIND])} has its leftmost @var{I} bits set to 1, and the
8216 remaining bits set to 0.
8218 @item @emph{Standard}:
8219 Fortran 2008 and later
8224 @item @emph{Syntax}:
8225 @code{RESULT = MASKL(I[, KIND])}
8227 @item @emph{Arguments}:
8228 @multitable @columnfractions .15 .70
8229 @item @var{I} @tab Shall be of type @code{INTEGER}.
8230 @item @var{KIND} @tab Shall be a scalar constant expression of type
8234 @item @emph{Return value}:
8235 The return value is of type @code{INTEGER}. If @var{KIND} is present, it
8236 specifies the kind value of the return type; otherwise, it is of the
8237 default integer kind.
8239 @item @emph{See also}:
8246 @section @code{MASKR} --- Right justified mask
8248 @cindex mask, right justified
8251 @item @emph{Description}:
8252 @code{MASKL(I[, KIND])} has its rightmost @var{I} bits set to 1, and the
8253 remaining bits set to 0.
8255 @item @emph{Standard}:
8256 Fortran 2008 and later
8261 @item @emph{Syntax}:
8262 @code{RESULT = MASKR(I[, KIND])}
8264 @item @emph{Arguments}:
8265 @multitable @columnfractions .15 .70
8266 @item @var{I} @tab Shall be of type @code{INTEGER}.
8267 @item @var{KIND} @tab Shall be a scalar constant expression of type
8271 @item @emph{Return value}:
8272 The return value is of type @code{INTEGER}. If @var{KIND} is present, it
8273 specifies the kind value of the return type; otherwise, it is of the
8274 default integer kind.
8276 @item @emph{See also}:
8283 @section @code{MATMUL} --- matrix multiplication
8285 @cindex matrix multiplication
8286 @cindex product, matrix
8289 @item @emph{Description}:
8290 Performs a matrix multiplication on numeric or logical arguments.
8292 @item @emph{Standard}:
8293 Fortran 95 and later
8296 Transformational function
8298 @item @emph{Syntax}:
8299 @code{RESULT = MATMUL(MATRIX_A, MATRIX_B)}
8301 @item @emph{Arguments}:
8302 @multitable @columnfractions .15 .70
8303 @item @var{MATRIX_A} @tab An array of @code{INTEGER},
8304 @code{REAL}, @code{COMPLEX}, or @code{LOGICAL} type, with a rank of
8306 @item @var{MATRIX_B} @tab An array of @code{INTEGER},
8307 @code{REAL}, or @code{COMPLEX} type if @var{MATRIX_A} is of a numeric
8308 type; otherwise, an array of @code{LOGICAL} type. The rank shall be one
8309 or two, and the first (or only) dimension of @var{MATRIX_B} shall be
8310 equal to the last (or only) dimension of @var{MATRIX_A}.
8313 @item @emph{Return value}:
8314 The matrix product of @var{MATRIX_A} and @var{MATRIX_B}. The type and
8315 kind of the result follow the usual type and kind promotion rules, as
8316 for the @code{*} or @code{.AND.} operators.
8318 @item @emph{See also}:
8324 @section @code{MAX} --- Maximum value of an argument list
8331 @cindex maximum value
8334 @item @emph{Description}:
8335 Returns the argument with the largest (most positive) value.
8337 @item @emph{Standard}:
8338 Fortran 77 and later
8343 @item @emph{Syntax}:
8344 @code{RESULT = MAX(A1, A2 [, A3 [, ...]])}
8346 @item @emph{Arguments}:
8347 @multitable @columnfractions .15 .70
8348 @item @var{A1} @tab The type shall be @code{INTEGER} or
8350 @item @var{A2}, @var{A3}, ... @tab An expression of the same type and kind
8351 as @var{A1}. (As a GNU extension, arguments of different kinds are
8355 @item @emph{Return value}:
8356 The return value corresponds to the maximum value among the arguments,
8357 and has the same type and kind as the first argument.
8359 @item @emph{Specific names}:
8360 @multitable @columnfractions .20 .20 .20 .25
8361 @item Name @tab Argument @tab Return type @tab Standard
8362 @item @code{MAX0(A1)} @tab @code{INTEGER(4) A1} @tab @code{INTEGER(4)} @tab Fortran 77 and later
8363 @item @code{AMAX0(A1)} @tab @code{INTEGER(4) A1} @tab @code{REAL(MAX(X))} @tab Fortran 77 and later
8364 @item @code{MAX1(A1)} @tab @code{REAL A1} @tab @code{INT(MAX(X))} @tab Fortran 77 and later
8365 @item @code{AMAX1(A1)} @tab @code{REAL(4) A1} @tab @code{REAL(4)} @tab Fortran 77 and later
8366 @item @code{DMAX1(A1)} @tab @code{REAL(8) A1} @tab @code{REAL(8)} @tab Fortran 77 and later
8369 @item @emph{See also}:
8370 @ref{MAXLOC} @ref{MAXVAL}, @ref{MIN}
8377 @section @code{MAXEXPONENT} --- Maximum exponent of a real kind
8378 @fnindex MAXEXPONENT
8379 @cindex model representation, maximum exponent
8382 @item @emph{Description}:
8383 @code{MAXEXPONENT(X)} returns the maximum exponent in the model of the
8386 @item @emph{Standard}:
8387 Fortran 95 and later
8392 @item @emph{Syntax}:
8393 @code{RESULT = MAXEXPONENT(X)}
8395 @item @emph{Arguments}:
8396 @multitable @columnfractions .15 .70
8397 @item @var{X} @tab Shall be of type @code{REAL}.
8400 @item @emph{Return value}:
8401 The return value is of type @code{INTEGER} and of the default integer
8404 @item @emph{Example}:
8410 print *, minexponent(x), maxexponent(x)
8411 print *, minexponent(y), maxexponent(y)
8412 end program exponents
8419 @section @code{MAXLOC} --- Location of the maximum value within an array
8421 @cindex array, location of maximum element
8424 @item @emph{Description}:
8425 Determines the location of the element in the array with the maximum
8426 value, or, if the @var{DIM} argument is supplied, determines the
8427 locations of the maximum element along each row of the array in the
8428 @var{DIM} direction. If @var{MASK} is present, only the elements for
8429 which @var{MASK} is @code{.TRUE.} are considered. If more than one
8430 element in the array has the maximum value, the location returned is
8431 that of the first such element in array element order. If the array has
8432 zero size, or all of the elements of @var{MASK} are @code{.FALSE.}, then
8433 the result is an array of zeroes. Similarly, if @var{DIM} is supplied
8434 and all of the elements of @var{MASK} along a given row are zero, the
8435 result value for that row is zero.
8437 @item @emph{Standard}:
8438 Fortran 95 and later
8441 Transformational function
8443 @item @emph{Syntax}:
8444 @multitable @columnfractions .80
8445 @item @code{RESULT = MAXLOC(ARRAY, DIM [, MASK])}
8446 @item @code{RESULT = MAXLOC(ARRAY [, MASK])}
8449 @item @emph{Arguments}:
8450 @multitable @columnfractions .15 .70
8451 @item @var{ARRAY} @tab Shall be an array of type @code{INTEGER} or
8453 @item @var{DIM} @tab (Optional) Shall be a scalar of type
8454 @code{INTEGER}, with a value between one and the rank of @var{ARRAY},
8455 inclusive. It may not be an optional dummy argument.
8456 @item @var{MASK} @tab Shall be an array of type @code{LOGICAL},
8457 and conformable with @var{ARRAY}.
8460 @item @emph{Return value}:
8461 If @var{DIM} is absent, the result is a rank-one array with a length
8462 equal to the rank of @var{ARRAY}. If @var{DIM} is present, the result
8463 is an array with a rank one less than the rank of @var{ARRAY}, and a
8464 size corresponding to the size of @var{ARRAY} with the @var{DIM}
8465 dimension removed. If @var{DIM} is present and @var{ARRAY} has a rank
8466 of one, the result is a scalar. In all cases, the result is of default
8467 @code{INTEGER} type.
8469 @item @emph{See also}:
8470 @ref{MAX}, @ref{MAXVAL}
8477 @section @code{MAXVAL} --- Maximum value of an array
8479 @cindex array, maximum value
8480 @cindex maximum value
8483 @item @emph{Description}:
8484 Determines the maximum value of the elements in an array value, or, if
8485 the @var{DIM} argument is supplied, determines the maximum value along
8486 each row of the array in the @var{DIM} direction. If @var{MASK} is
8487 present, only the elements for which @var{MASK} is @code{.TRUE.} are
8488 considered. If the array has zero size, or all of the elements of
8489 @var{MASK} are @code{.FALSE.}, then the result is @code{-HUGE(ARRAY)}
8490 if @var{ARRAY} is numeric, or a string of nulls if @var{ARRAY} is of character
8493 @item @emph{Standard}:
8494 Fortran 95 and later
8497 Transformational function
8499 @item @emph{Syntax}:
8500 @multitable @columnfractions .80
8501 @item @code{RESULT = MAXVAL(ARRAY, DIM [, MASK])}
8502 @item @code{RESULT = MAXVAL(ARRAY [, MASK])}
8505 @item @emph{Arguments}:
8506 @multitable @columnfractions .15 .70
8507 @item @var{ARRAY} @tab Shall be an array of type @code{INTEGER} or
8509 @item @var{DIM} @tab (Optional) Shall be a scalar of type
8510 @code{INTEGER}, with a value between one and the rank of @var{ARRAY},
8511 inclusive. It may not be an optional dummy argument.
8512 @item @var{MASK} @tab Shall be an array of type @code{LOGICAL},
8513 and conformable with @var{ARRAY}.
8516 @item @emph{Return value}:
8517 If @var{DIM} is absent, or if @var{ARRAY} has a rank of one, the result
8518 is a scalar. If @var{DIM} is present, the result is an array with a
8519 rank one less than the rank of @var{ARRAY}, and a size corresponding to
8520 the size of @var{ARRAY} with the @var{DIM} dimension removed. In all
8521 cases, the result is of the same type and kind as @var{ARRAY}.
8523 @item @emph{See also}:
8524 @ref{MAX}, @ref{MAXLOC}
8530 @section @code{MCLOCK} --- Time function
8532 @cindex time, clock ticks
8536 @item @emph{Description}:
8537 Returns the number of clock ticks since the start of the process, based
8538 on the UNIX function @code{clock(3)}.
8540 This intrinsic is not fully portable, such as to systems with 32-bit
8541 @code{INTEGER} types but supporting times wider than 32 bits. Therefore,
8542 the values returned by this intrinsic might be, or become, negative, or
8543 numerically less than previous values, during a single run of the
8546 @item @emph{Standard}:
8552 @item @emph{Syntax}:
8553 @code{RESULT = MCLOCK()}
8555 @item @emph{Return value}:
8556 The return value is a scalar of type @code{INTEGER(4)}, equal to the
8557 number of clock ticks since the start of the process, or @code{-1} if
8558 the system does not support @code{clock(3)}.
8560 @item @emph{See also}:
8561 @ref{CTIME}, @ref{GMTIME}, @ref{LTIME}, @ref{MCLOCK}, @ref{TIME}
8568 @section @code{MCLOCK8} --- Time function (64-bit)
8570 @cindex time, clock ticks
8574 @item @emph{Description}:
8575 Returns the number of clock ticks since the start of the process, based
8576 on the UNIX function @code{clock(3)}.
8578 @emph{Warning:} this intrinsic does not increase the range of the timing
8579 values over that returned by @code{clock(3)}. On a system with a 32-bit
8580 @code{clock(3)}, @code{MCLOCK8} will return a 32-bit value, even though
8581 it is converted to a 64-bit @code{INTEGER(8)} value. That means
8582 overflows of the 32-bit value can still occur. Therefore, the values
8583 returned by this intrinsic might be or become negative or numerically
8584 less than previous values during a single run of the compiled program.
8586 @item @emph{Standard}:
8592 @item @emph{Syntax}:
8593 @code{RESULT = MCLOCK8()}
8595 @item @emph{Return value}:
8596 The return value is a scalar of type @code{INTEGER(8)}, equal to the
8597 number of clock ticks since the start of the process, or @code{-1} if
8598 the system does not support @code{clock(3)}.
8600 @item @emph{See also}:
8601 @ref{CTIME}, @ref{GMTIME}, @ref{LTIME}, @ref{MCLOCK}, @ref{TIME8}
8608 @section @code{MERGE} --- Merge variables
8610 @cindex array, merge arrays
8611 @cindex array, combine arrays
8614 @item @emph{Description}:
8615 Select values from two arrays according to a logical mask. The result
8616 is equal to @var{TSOURCE} if @var{MASK} is @code{.TRUE.}, or equal to
8617 @var{FSOURCE} if it is @code{.FALSE.}.
8619 @item @emph{Standard}:
8620 Fortran 95 and later
8625 @item @emph{Syntax}:
8626 @code{RESULT = MERGE(TSOURCE, FSOURCE, MASK)}
8628 @item @emph{Arguments}:
8629 @multitable @columnfractions .15 .70
8630 @item @var{TSOURCE} @tab May be of any type.
8631 @item @var{FSOURCE} @tab Shall be of the same type and type parameters
8633 @item @var{MASK} @tab Shall be of type @code{LOGICAL}.
8636 @item @emph{Return value}:
8637 The result is of the same type and type parameters as @var{TSOURCE}.
8644 @section @code{MERGE_BITS} --- Merge of bits under mask
8649 @item @emph{Description}:
8650 @code{MERGE_BITS(I, J, MASK)} merges the bits of @var{I} and @var{J}
8651 as determined by the mask. The i-th bit of the result is equal to the
8652 i-th bit of @var{I} if the i-th bit of @var{MASK} is 1; it is equal to
8653 the i-th bit of @var{J} otherwise.
8655 @item @emph{Standard}:
8656 Fortran 2008 and later
8661 @item @emph{Syntax}:
8662 @code{RESULT = MERGE_BITS(I, J, MASK)}
8664 @item @emph{Arguments}:
8665 @multitable @columnfractions .15 .70
8666 @item @var{I} @tab Shall be of type @code{INTEGER}.
8667 @item @var{J} @tab Shall be of type @code{INTEGER} and of the same
8669 @item @var{MASK} @tab Shall be of type @code{INTEGER} and of the same
8673 @item @emph{Return value}:
8674 The result is of the same type and kind as @var{I}.
8681 @section @code{MIN} --- Minimum value of an argument list
8688 @cindex minimum value
8691 @item @emph{Description}:
8692 Returns the argument with the smallest (most negative) value.
8694 @item @emph{Standard}:
8695 Fortran 77 and later
8700 @item @emph{Syntax}:
8701 @code{RESULT = MIN(A1, A2 [, A3, ...])}
8703 @item @emph{Arguments}:
8704 @multitable @columnfractions .15 .70
8705 @item @var{A1} @tab The type shall be @code{INTEGER} or
8707 @item @var{A2}, @var{A3}, ... @tab An expression of the same type and kind
8708 as @var{A1}. (As a GNU extension, arguments of different kinds are
8712 @item @emph{Return value}:
8713 The return value corresponds to the maximum value among the arguments,
8714 and has the same type and kind as the first argument.
8716 @item @emph{Specific names}:
8717 @multitable @columnfractions .20 .20 .20 .25
8718 @item Name @tab Argument @tab Return type @tab Standard
8719 @item @code{MIN0(A1)} @tab @code{INTEGER(4) A1} @tab @code{INTEGER(4)} @tab Fortran 77 and later
8720 @item @code{AMIN0(A1)} @tab @code{INTEGER(4) A1} @tab @code{REAL(4)} @tab Fortran 77 and later
8721 @item @code{MIN1(A1)} @tab @code{REAL A1} @tab @code{INTEGER(4)} @tab Fortran 77 and later
8722 @item @code{AMIN1(A1)} @tab @code{REAL(4) A1} @tab @code{REAL(4)} @tab Fortran 77 and later
8723 @item @code{DMIN1(A1)} @tab @code{REAL(8) A1} @tab @code{REAL(8)} @tab Fortran 77 and later
8726 @item @emph{See also}:
8727 @ref{MAX}, @ref{MINLOC}, @ref{MINVAL}
8733 @section @code{MINEXPONENT} --- Minimum exponent of a real kind
8734 @fnindex MINEXPONENT
8735 @cindex model representation, minimum exponent
8738 @item @emph{Description}:
8739 @code{MINEXPONENT(X)} returns the minimum exponent in the model of the
8742 @item @emph{Standard}:
8743 Fortran 95 and later
8748 @item @emph{Syntax}:
8749 @code{RESULT = MINEXPONENT(X)}
8751 @item @emph{Arguments}:
8752 @multitable @columnfractions .15 .70
8753 @item @var{X} @tab Shall be of type @code{REAL}.
8756 @item @emph{Return value}:
8757 The return value is of type @code{INTEGER} and of the default integer
8760 @item @emph{Example}:
8761 See @code{MAXEXPONENT} for an example.
8767 @section @code{MINLOC} --- Location of the minimum value within an array
8769 @cindex array, location of minimum element
8772 @item @emph{Description}:
8773 Determines the location of the element in the array with the minimum
8774 value, or, if the @var{DIM} argument is supplied, determines the
8775 locations of the minimum element along each row of the array in the
8776 @var{DIM} direction. If @var{MASK} is present, only the elements for
8777 which @var{MASK} is @code{.TRUE.} are considered. If more than one
8778 element in the array has the minimum value, the location returned is
8779 that of the first such element in array element order. If the array has
8780 zero size, or all of the elements of @var{MASK} are @code{.FALSE.}, then
8781 the result is an array of zeroes. Similarly, if @var{DIM} is supplied
8782 and all of the elements of @var{MASK} along a given row are zero, the
8783 result value for that row is zero.
8785 @item @emph{Standard}:
8786 Fortran 95 and later
8789 Transformational function
8791 @item @emph{Syntax}:
8792 @multitable @columnfractions .80
8793 @item @code{RESULT = MINLOC(ARRAY, DIM [, MASK])}
8794 @item @code{RESULT = MINLOC(ARRAY [, MASK])}
8797 @item @emph{Arguments}:
8798 @multitable @columnfractions .15 .70
8799 @item @var{ARRAY} @tab Shall be an array of type @code{INTEGER} or
8801 @item @var{DIM} @tab (Optional) Shall be a scalar of type
8802 @code{INTEGER}, with a value between one and the rank of @var{ARRAY},
8803 inclusive. It may not be an optional dummy argument.
8804 @item @var{MASK} @tab Shall be an array of type @code{LOGICAL},
8805 and conformable with @var{ARRAY}.
8808 @item @emph{Return value}:
8809 If @var{DIM} is absent, the result is a rank-one array with a length
8810 equal to the rank of @var{ARRAY}. If @var{DIM} is present, the result
8811 is an array with a rank one less than the rank of @var{ARRAY}, and a
8812 size corresponding to the size of @var{ARRAY} with the @var{DIM}
8813 dimension removed. If @var{DIM} is present and @var{ARRAY} has a rank
8814 of one, the result is a scalar. In all cases, the result is of default
8815 @code{INTEGER} type.
8817 @item @emph{See also}:
8818 @ref{MIN}, @ref{MINVAL}
8825 @section @code{MINVAL} --- Minimum value of an array
8827 @cindex array, minimum value
8828 @cindex minimum value
8831 @item @emph{Description}:
8832 Determines the minimum value of the elements in an array value, or, if
8833 the @var{DIM} argument is supplied, determines the minimum value along
8834 each row of the array in the @var{DIM} direction. If @var{MASK} is
8835 present, only the elements for which @var{MASK} is @code{.TRUE.} are
8836 considered. If the array has zero size, or all of the elements of
8837 @var{MASK} are @code{.FALSE.}, then the result is @code{HUGE(ARRAY)} if
8838 @var{ARRAY} is numeric, or a string of @code{CHAR(255)} characters if
8839 @var{ARRAY} is of character type.
8841 @item @emph{Standard}:
8842 Fortran 95 and later
8845 Transformational function
8847 @item @emph{Syntax}:
8848 @multitable @columnfractions .80
8849 @item @code{RESULT = MINVAL(ARRAY, DIM [, MASK])}
8850 @item @code{RESULT = MINVAL(ARRAY [, MASK])}
8853 @item @emph{Arguments}:
8854 @multitable @columnfractions .15 .70
8855 @item @var{ARRAY} @tab Shall be an array of type @code{INTEGER} or
8857 @item @var{DIM} @tab (Optional) Shall be a scalar of type
8858 @code{INTEGER}, with a value between one and the rank of @var{ARRAY},
8859 inclusive. It may not be an optional dummy argument.
8860 @item @var{MASK} @tab Shall be an array of type @code{LOGICAL},
8861 and conformable with @var{ARRAY}.
8864 @item @emph{Return value}:
8865 If @var{DIM} is absent, or if @var{ARRAY} has a rank of one, the result
8866 is a scalar. If @var{DIM} is present, the result is an array with a
8867 rank one less than the rank of @var{ARRAY}, and a size corresponding to
8868 the size of @var{ARRAY} with the @var{DIM} dimension removed. In all
8869 cases, the result is of the same type and kind as @var{ARRAY}.
8871 @item @emph{See also}:
8872 @ref{MIN}, @ref{MINLOC}
8879 @section @code{MOD} --- Remainder function
8884 @cindex division, remainder
8887 @item @emph{Description}:
8888 @code{MOD(A,P)} computes the remainder of the division of A by P@. It is
8889 calculated as @code{A - (INT(A/P) * P)}.
8891 @item @emph{Standard}:
8892 Fortran 77 and later
8897 @item @emph{Syntax}:
8898 @code{RESULT = MOD(A, P)}
8900 @item @emph{Arguments}:
8901 @multitable @columnfractions .15 .70
8902 @item @var{A} @tab Shall be a scalar of type @code{INTEGER} or @code{REAL}
8903 @item @var{P} @tab Shall be a scalar of the same type as @var{A} and not
8907 @item @emph{Return value}:
8908 The kind of the return value is the result of cross-promoting
8909 the kinds of the arguments.
8911 @item @emph{Example}:
8915 print *, mod(17.5,5.5)
8916 print *, mod(17.5d0,5.5)
8917 print *, mod(17.5,5.5d0)
8920 print *, mod(-17.5,5.5)
8921 print *, mod(-17.5d0,5.5)
8922 print *, mod(-17.5,5.5d0)
8925 print *, mod(17.5,-5.5)
8926 print *, mod(17.5d0,-5.5)
8927 print *, mod(17.5,-5.5d0)
8928 end program test_mod
8931 @item @emph{Specific names}:
8932 @multitable @columnfractions .20 .20 .20 .25
8933 @item Name @tab Arguments @tab Return type @tab Standard
8934 @item @code{MOD(A,P)} @tab @code{INTEGER A,P} @tab @code{INTEGER} @tab Fortran 95 and later
8935 @item @code{AMOD(A,P)} @tab @code{REAL(4) A,P} @tab @code{REAL(4)} @tab Fortran 95 and later
8936 @item @code{DMOD(A,P)} @tab @code{REAL(8) A,P} @tab @code{REAL(8)} @tab Fortran 95 and later
8943 @section @code{MODULO} --- Modulo function
8946 @cindex division, modulo
8949 @item @emph{Description}:
8950 @code{MODULO(A,P)} computes the @var{A} modulo @var{P}.
8952 @item @emph{Standard}:
8953 Fortran 95 and later
8958 @item @emph{Syntax}:
8959 @code{RESULT = MODULO(A, P)}
8961 @item @emph{Arguments}:
8962 @multitable @columnfractions .15 .70
8963 @item @var{A} @tab Shall be a scalar of type @code{INTEGER} or @code{REAL}
8964 @item @var{P} @tab Shall be a scalar of the same type and kind as @var{A}
8967 @item @emph{Return value}:
8968 The type and kind of the result are those of the arguments.
8970 @item If @var{A} and @var{P} are of type @code{INTEGER}:
8971 @code{MODULO(A,P)} has the value @var{R} such that @code{A=Q*P+R}, where
8972 @var{Q} is an integer and @var{R} is between 0 (inclusive) and @var{P}
8974 @item If @var{A} and @var{P} are of type @code{REAL}:
8975 @code{MODULO(A,P)} has the value of @code{A - FLOOR (A / P) * P}.
8977 In all cases, if @var{P} is zero the result is processor-dependent.
8979 @item @emph{Example}:
8982 print *, modulo(17,3)
8983 print *, modulo(17.5,5.5)
8985 print *, modulo(-17,3)
8986 print *, modulo(-17.5,5.5)
8988 print *, modulo(17,-3)
8989 print *, modulo(17.5,-5.5)
8998 @section @code{MOVE_ALLOC} --- Move allocation from one object to another
9000 @cindex moving allocation
9001 @cindex allocation, moving
9004 @item @emph{Description}:
9005 @code{MOVE_ALLOC(FROM, TO)} moves the allocation from @var{FROM} to
9006 @var{TO}. @var{FROM} will become deallocated in the process.
9008 @item @emph{Standard}:
9009 Fortran 2003 and later
9014 @item @emph{Syntax}:
9015 @code{CALL MOVE_ALLOC(FROM, TO)}
9017 @item @emph{Arguments}:
9018 @multitable @columnfractions .15 .70
9019 @item @var{FROM} @tab @code{ALLOCATABLE}, @code{INTENT(INOUT)}, may be
9020 of any type and kind.
9021 @item @var{TO} @tab @code{ALLOCATABLE}, @code{INTENT(OUT)}, shall be
9022 of the same type, kind and rank as @var{FROM}.
9025 @item @emph{Return value}:
9028 @item @emph{Example}:
9030 program test_move_alloc
9031 integer, allocatable :: a(:), b(:)
9035 call move_alloc(a, b)
9036 print *, allocated(a), allocated(b)
9038 end program test_move_alloc
9045 @section @code{MVBITS} --- Move bits from one integer to another
9050 @item @emph{Description}:
9051 Moves @var{LEN} bits from positions @var{FROMPOS} through
9052 @code{FROMPOS+LEN-1} of @var{FROM} to positions @var{TOPOS} through
9053 @code{TOPOS+LEN-1} of @var{TO}. The portion of argument @var{TO} not
9054 affected by the movement of bits is unchanged. The values of
9055 @code{FROMPOS+LEN-1} and @code{TOPOS+LEN-1} must be less than
9056 @code{BIT_SIZE(FROM)}.
9058 @item @emph{Standard}:
9059 Fortran 95 and later
9062 Elemental subroutine
9064 @item @emph{Syntax}:
9065 @code{CALL MVBITS(FROM, FROMPOS, LEN, TO, TOPOS)}
9067 @item @emph{Arguments}:
9068 @multitable @columnfractions .15 .70
9069 @item @var{FROM} @tab The type shall be @code{INTEGER}.
9070 @item @var{FROMPOS} @tab The type shall be @code{INTEGER}.
9071 @item @var{LEN} @tab The type shall be @code{INTEGER}.
9072 @item @var{TO} @tab The type shall be @code{INTEGER}, of the
9073 same kind as @var{FROM}.
9074 @item @var{TOPOS} @tab The type shall be @code{INTEGER}.
9077 @item @emph{See also}:
9078 @ref{IBCLR}, @ref{IBSET}, @ref{IBITS}, @ref{IAND}, @ref{IOR}, @ref{IEOR}
9084 @section @code{NEAREST} --- Nearest representable number
9086 @cindex real number, nearest different
9087 @cindex floating point, nearest different
9090 @item @emph{Description}:
9091 @code{NEAREST(X, S)} returns the processor-representable number nearest
9092 to @code{X} in the direction indicated by the sign of @code{S}.
9094 @item @emph{Standard}:
9095 Fortran 95 and later
9100 @item @emph{Syntax}:
9101 @code{RESULT = NEAREST(X, S)}
9103 @item @emph{Arguments}:
9104 @multitable @columnfractions .15 .70
9105 @item @var{X} @tab Shall be of type @code{REAL}.
9106 @item @var{S} @tab (Optional) shall be of type @code{REAL} and
9110 @item @emph{Return value}:
9111 The return value is of the same type as @code{X}. If @code{S} is
9112 positive, @code{NEAREST} returns the processor-representable number
9113 greater than @code{X} and nearest to it. If @code{S} is negative,
9114 @code{NEAREST} returns the processor-representable number smaller than
9115 @code{X} and nearest to it.
9117 @item @emph{Example}:
9119 program test_nearest
9121 x = nearest(42.0, 1.0)
9122 y = nearest(42.0, -1.0)
9123 write (*,"(3(G20.15))") x, y, x - y
9124 end program test_nearest
9131 @section @code{NEW_LINE} --- New line character
9134 @cindex output, newline
9137 @item @emph{Description}:
9138 @code{NEW_LINE(C)} returns the new-line character.
9140 @item @emph{Standard}:
9141 Fortran 2003 and later
9146 @item @emph{Syntax}:
9147 @code{RESULT = NEW_LINE(C)}
9149 @item @emph{Arguments}:
9150 @multitable @columnfractions .15 .70
9151 @item @var{C} @tab The argument shall be a scalar or array of the
9152 type @code{CHARACTER}.
9155 @item @emph{Return value}:
9156 Returns a @var{CHARACTER} scalar of length one with the new-line character of
9157 the same kind as parameter @var{C}.
9159 @item @emph{Example}:
9163 write(*,'(A)') 'This is record 1.'//NEW_LINE('A')//'This is record 2.'
9171 @section @code{NINT} --- Nearest whole number
9174 @cindex rounding, nearest whole number
9177 @item @emph{Description}:
9178 @code{NINT(A)} rounds its argument to the nearest whole number.
9180 @item @emph{Standard}:
9181 Fortran 77 and later, with @var{KIND} argument Fortran 90 and later
9186 @item @emph{Syntax}:
9187 @code{RESULT = NINT(A [, KIND])}
9189 @item @emph{Arguments}:
9190 @multitable @columnfractions .15 .70
9191 @item @var{A} @tab The type of the argument shall be @code{REAL}.
9192 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
9193 expression indicating the kind parameter of the result.
9196 @item @emph{Return value}:
9197 Returns @var{A} with the fractional portion of its magnitude eliminated by
9198 rounding to the nearest whole number and with its sign preserved,
9199 converted to an @code{INTEGER} of the default kind.
9201 @item @emph{Example}:
9208 print *, nint(x4), idnint(x8)
9209 end program test_nint
9212 @item @emph{Specific names}:
9213 @multitable @columnfractions .20 .20 .20 .25
9214 @item Name @tab Argument @tab Return Type @tab Standard
9215 @item @code{NINT(A)} @tab @code{REAL(4) A} @tab @code{INTEGER} @tab Fortran 95 and later
9216 @item @code{IDNINT(A)} @tab @code{REAL(8) A} @tab @code{INTEGER} @tab Fortran 95 and later
9219 @item @emph{See also}:
9220 @ref{CEILING}, @ref{FLOOR}
9227 @section @code{NORM2} --- Euclidean vector norms
9229 @cindex Euclidean vector norm
9230 @cindex L2 vector norm
9231 @cindex norm, Euclidean
9234 @item @emph{Description}:
9235 Calculates the Euclidean vector norm (@math{L_2} norm) of
9236 of @var{ARRAY} along dimension @var{DIM}.
9238 @item @emph{Standard}:
9239 Fortran 2008 and later
9242 Transformational function
9244 @item @emph{Syntax}:
9245 @multitable @columnfractions .80
9246 @item @code{RESULT = NORM2(ARRAY[, DIM])}
9249 @item @emph{Arguments}:
9250 @multitable @columnfractions .15 .70
9251 @item @var{ARRAY} @tab Shall be an array of type @code{REAL}
9252 @item @var{DIM} @tab (Optional) shall be a scalar of type
9253 @code{INTEGER} with a value in the range from 1 to n, where n
9254 equals the rank of @var{ARRAY}.
9257 @item @emph{Return value}:
9258 The result is of the same type as @var{ARRAY}.
9260 If @var{DIM} is absent, a scalar with the square root of the sum of all
9261 elements in @var{ARRAY} squared is returned. Otherwise, an array of
9262 rank @math{n-1}, where @math{n} equals the rank of @var{ARRAY}, and a
9263 shape similar to that of @var{ARRAY} with dimension @var{DIM} dropped
9266 @item @emph{Example}:
9269 REAL :: x(5) = [ real :: 1, 2, 3, 4, 5 ]
9270 print *, NORM2(x) ! = sqrt(55.) ~ 7.416
9278 @section @code{NOT} --- Logical negation
9280 @cindex bits, negate
9281 @cindex bitwise logical not
9282 @cindex logical not, bitwise
9285 @item @emph{Description}:
9286 @code{NOT} returns the bitwise Boolean inverse of @var{I}.
9288 @item @emph{Standard}:
9289 Fortran 95 and later
9294 @item @emph{Syntax}:
9295 @code{RESULT = NOT(I)}
9297 @item @emph{Arguments}:
9298 @multitable @columnfractions .15 .70
9299 @item @var{I} @tab The type shall be @code{INTEGER}.
9302 @item @emph{Return value}:
9303 The return type is @code{INTEGER}, of the same kind as the
9306 @item @emph{See also}:
9307 @ref{IAND}, @ref{IEOR}, @ref{IOR}, @ref{IBITS}, @ref{IBSET}, @ref{IBCLR}
9314 @section @code{NULL} --- Function that returns an disassociated pointer
9316 @cindex pointer, status
9317 @cindex pointer, disassociated
9320 @item @emph{Description}:
9321 Returns a disassociated pointer.
9323 If @var{MOLD} is present, a disassociated pointer of the same type is
9324 returned, otherwise the type is determined by context.
9326 In Fortran 95, @var{MOLD} is optional. Please note that Fortran 2003
9327 includes cases where it is required.
9329 @item @emph{Standard}:
9330 Fortran 95 and later
9333 Transformational function
9335 @item @emph{Syntax}:
9336 @code{PTR => NULL([MOLD])}
9338 @item @emph{Arguments}:
9339 @multitable @columnfractions .15 .70
9340 @item @var{MOLD} @tab (Optional) shall be a pointer of any association
9341 status and of any type.
9344 @item @emph{Return value}:
9345 A disassociated pointer.
9347 @item @emph{Example}:
9349 REAL, POINTER, DIMENSION(:) :: VEC => NULL ()
9352 @item @emph{See also}:
9359 @section @code{NUM_IMAGES} --- Function that returns the number of images
9361 @cindex coarray, @code{NUM_IMAGES}
9362 @cindex images, number of
9365 @item @emph{Description}:
9366 Returns the number of images.
9368 @item @emph{Standard}:
9369 Fortran 2008 and later
9372 Transformational function
9374 @item @emph{Syntax}:
9375 @code{RESULT = NUM_IMAGES()}
9377 @item @emph{Arguments}: None.
9379 @item @emph{Return value}:
9380 Scalar default-kind integer.
9382 @item @emph{Example}:
9386 value = THIS_IMAGE()
9388 IF (THIS_IMAGE() == 1) THEN
9389 DO i = 1, NUM_IMAGES()
9390 WRITE(*,'(2(a,i0))') 'value[', i, '] is ', value[i]
9395 @item @emph{See also}:
9396 @ref{THIS_IMAGE}, @ref{IMAGE_INDEX}
9402 @section @code{OR} --- Bitwise logical OR
9404 @cindex bitwise logical or
9405 @cindex logical or, bitwise
9408 @item @emph{Description}:
9409 Bitwise logical @code{OR}.
9411 This intrinsic routine is provided for backwards compatibility with
9412 GNU Fortran 77. For integer arguments, programmers should consider
9413 the use of the @ref{IOR} intrinsic defined by the Fortran standard.
9415 @item @emph{Standard}:
9421 @item @emph{Syntax}:
9422 @code{RESULT = OR(I, J)}
9424 @item @emph{Arguments}:
9425 @multitable @columnfractions .15 .70
9426 @item @var{I} @tab The type shall be either a scalar @code{INTEGER}
9427 type or a scalar @code{LOGICAL} type.
9428 @item @var{J} @tab The type shall be the same as the type of @var{J}.
9431 @item @emph{Return value}:
9432 The return type is either a scalar @code{INTEGER} or a scalar
9433 @code{LOGICAL}. If the kind type parameters differ, then the
9434 smaller kind type is implicitly converted to larger kind, and the
9435 return has the larger kind.
9437 @item @emph{Example}:
9440 LOGICAL :: T = .TRUE., F = .FALSE.
9442 DATA a / Z'F' /, b / Z'3' /
9444 WRITE (*,*) OR(T, T), OR(T, F), OR(F, T), OR(F, F)
9445 WRITE (*,*) OR(a, b)
9449 @item @emph{See also}:
9450 Fortran 95 elemental function: @ref{IOR}
9456 @section @code{PACK} --- Pack an array into an array of rank one
9458 @cindex array, packing
9459 @cindex array, reduce dimension
9460 @cindex array, gather elements
9463 @item @emph{Description}:
9464 Stores the elements of @var{ARRAY} in an array of rank one.
9466 The beginning of the resulting array is made up of elements whose @var{MASK}
9467 equals @code{TRUE}. Afterwards, positions are filled with elements taken from
9470 @item @emph{Standard}:
9471 Fortran 95 and later
9474 Transformational function
9476 @item @emph{Syntax}:
9477 @code{RESULT = PACK(ARRAY, MASK[,VECTOR]}
9479 @item @emph{Arguments}:
9480 @multitable @columnfractions .15 .70
9481 @item @var{ARRAY} @tab Shall be an array of any type.
9482 @item @var{MASK} @tab Shall be an array of type @code{LOGICAL} and
9483 of the same size as @var{ARRAY}. Alternatively, it may be a @code{LOGICAL}
9485 @item @var{VECTOR} @tab (Optional) shall be an array of the same type
9486 as @var{ARRAY} and of rank one. If present, the number of elements in
9487 @var{VECTOR} shall be equal to or greater than the number of true elements
9488 in @var{MASK}. If @var{MASK} is scalar, the number of elements in
9489 @var{VECTOR} shall be equal to or greater than the number of elements in
9493 @item @emph{Return value}:
9494 The result is an array of rank one and the same type as that of @var{ARRAY}.
9495 If @var{VECTOR} is present, the result size is that of @var{VECTOR}, the
9496 number of @code{TRUE} values in @var{MASK} otherwise.
9498 @item @emph{Example}:
9499 Gathering nonzero elements from an array:
9503 m = (/ 1, 0, 0, 0, 5, 0 /)
9504 WRITE(*, FMT="(6(I0, ' '))") pack(m, m /= 0) ! "1 5"
9508 Gathering nonzero elements from an array and appending elements from @var{VECTOR}:
9512 m = (/ 1, 0, 0, 2 /)
9513 WRITE(*, FMT="(4(I0, ' '))") pack(m, m /= 0, (/ 0, 0, 3, 4 /)) ! "1 2 3 4"
9517 @item @emph{See also}:
9524 @section @code{PARITY} --- Reduction with exclusive OR
9527 @cindex Reduction, XOR
9528 @cindex XOR reduction
9531 @item @emph{Description}:
9532 Calculates the parity, i.e. the reduction using @code{.XOR.},
9533 of @var{MASK} along dimension @var{DIM}.
9535 @item @emph{Standard}:
9536 Fortran 2008 and later
9539 Transformational function
9541 @item @emph{Syntax}:
9542 @multitable @columnfractions .80
9543 @item @code{RESULT = PARITY(MASK[, DIM])}
9546 @item @emph{Arguments}:
9547 @multitable @columnfractions .15 .70
9548 @item @var{LOGICAL} @tab Shall be an array of type @code{LOGICAL}
9549 @item @var{DIM} @tab (Optional) shall be a scalar of type
9550 @code{INTEGER} with a value in the range from 1 to n, where n
9551 equals the rank of @var{MASK}.
9554 @item @emph{Return value}:
9555 The result is of the same type as @var{MASK}.
9557 If @var{DIM} is absent, a scalar with the parity of all elements in
9558 @var{MASK} is returned, i.e. true if an odd number of elements is
9559 @code{.true.} and false otherwise. If @var{DIM} is present, an array
9560 of rank @math{n-1}, where @math{n} equals the rank of @var{ARRAY},
9561 and a shape similar to that of @var{MASK} with dimension @var{DIM}
9562 dropped is returned.
9564 @item @emph{Example}:
9567 LOGICAL :: x(2) = [ .true., .false. ]
9568 print *, PARITY(x) ! prints "T" (true).
9576 @section @code{PERROR} --- Print system error message
9578 @cindex system, error handling
9581 @item @emph{Description}:
9582 Prints (on the C @code{stderr} stream) a newline-terminated error
9583 message corresponding to the last system error. This is prefixed by
9584 @var{STRING}, a colon and a space. See @code{perror(3)}.
9586 @item @emph{Standard}:
9592 @item @emph{Syntax}:
9593 @code{CALL PERROR(STRING)}
9595 @item @emph{Arguments}:
9596 @multitable @columnfractions .15 .70
9597 @item @var{STRING} @tab A scalar of type @code{CHARACTER} and of the
9601 @item @emph{See also}:
9608 @section @code{PRECISION} --- Decimal precision of a real kind
9610 @cindex model representation, precision
9613 @item @emph{Description}:
9614 @code{PRECISION(X)} returns the decimal precision in the model of the
9617 @item @emph{Standard}:
9618 Fortran 95 and later
9623 @item @emph{Syntax}:
9624 @code{RESULT = PRECISION(X)}
9626 @item @emph{Arguments}:
9627 @multitable @columnfractions .15 .70
9628 @item @var{X} @tab Shall be of type @code{REAL} or @code{COMPLEX}.
9631 @item @emph{Return value}:
9632 The return value is of type @code{INTEGER} and of the default integer
9635 @item @emph{See also}:
9636 @ref{SELECTED_REAL_KIND}, @ref{RANGE}
9638 @item @emph{Example}:
9640 program prec_and_range
9641 real(kind=4) :: x(2)
9642 complex(kind=8) :: y
9644 print *, precision(x), range(x)
9645 print *, precision(y), range(y)
9646 end program prec_and_range
9653 @section @code{POPCNT} --- Number of bits set
9655 @cindex binary representation
9659 @item @emph{Description}:
9660 @code{POPCNT(I)} returns the number of bits set ('1' bits) in the binary
9661 representation of @code{I}.
9663 @item @emph{Standard}:
9664 Fortran 2008 and later
9669 @item @emph{Syntax}:
9670 @code{RESULT = POPCNT(I)}
9672 @item @emph{Arguments}:
9673 @multitable @columnfractions .15 .70
9674 @item @var{I} @tab Shall be of type @code{INTEGER}.
9677 @item @emph{Return value}:
9678 The return value is of type @code{INTEGER} and of the default integer
9681 @item @emph{See also}:
9682 @ref{POPPAR}, @ref{LEADZ}, @ref{TRAILZ}
9684 @item @emph{Example}:
9686 program test_population
9687 print *, popcnt(127), poppar(127)
9688 print *, popcnt(huge(0_4)), poppar(huge(0_4))
9689 print *, popcnt(huge(0_8)), poppar(huge(0_8))
9690 end program test_population
9696 @section @code{POPPAR} --- Parity of the number of bits set
9698 @cindex binary representation
9702 @item @emph{Description}:
9703 @code{POPPAR(I)} returns parity of the integer @code{I}, i.e. the parity
9704 of the number of bits set ('1' bits) in the binary representation of
9705 @code{I}. It is equal to 0 if @code{I} has an even number of bits set,
9706 and 1 for an odd number of '1' bits.
9708 @item @emph{Standard}:
9709 Fortran 2008 and later
9714 @item @emph{Syntax}:
9715 @code{RESULT = POPPAR(I)}
9717 @item @emph{Arguments}:
9718 @multitable @columnfractions .15 .70
9719 @item @var{I} @tab Shall be of type @code{INTEGER}.
9722 @item @emph{Return value}:
9723 The return value is of type @code{INTEGER} and of the default integer
9726 @item @emph{See also}:
9727 @ref{POPCNT}, @ref{LEADZ}, @ref{TRAILZ}
9729 @item @emph{Example}:
9731 program test_population
9732 print *, popcnt(127), poppar(127)
9733 print *, popcnt(huge(0_4)), poppar(huge(0_4))
9734 print *, popcnt(huge(0_8)), poppar(huge(0_8))
9735 end program test_population
9742 @section @code{PRESENT} --- Determine whether an optional dummy argument is specified
9746 @item @emph{Description}:
9747 Determines whether an optional dummy argument is present.
9749 @item @emph{Standard}:
9750 Fortran 95 and later
9755 @item @emph{Syntax}:
9756 @code{RESULT = PRESENT(A)}
9758 @item @emph{Arguments}:
9759 @multitable @columnfractions .15 .70
9760 @item @var{A} @tab May be of any type and may be a pointer, scalar or array
9761 value, or a dummy procedure. It shall be the name of an optional dummy argument
9762 accessible within the current subroutine or function.
9765 @item @emph{Return value}:
9766 Returns either @code{TRUE} if the optional argument @var{A} is present, or
9767 @code{FALSE} otherwise.
9769 @item @emph{Example}:
9771 PROGRAM test_present
9772 WRITE(*,*) f(), f(42) ! "F T"
9774 LOGICAL FUNCTION f(x)
9775 INTEGER, INTENT(IN), OPTIONAL :: x
9785 @section @code{PRODUCT} --- Product of array elements
9787 @cindex array, product
9788 @cindex array, multiply elements
9789 @cindex array, conditionally multiply elements
9790 @cindex multiply array elements
9793 @item @emph{Description}:
9794 Multiplies the elements of @var{ARRAY} along dimension @var{DIM} if
9795 the corresponding element in @var{MASK} is @code{TRUE}.
9797 @item @emph{Standard}:
9798 Fortran 95 and later
9801 Transformational function
9803 @item @emph{Syntax}:
9804 @multitable @columnfractions .80
9805 @item @code{RESULT = PRODUCT(ARRAY[, MASK])}
9806 @item @code{RESULT = PRODUCT(ARRAY, DIM[, MASK])}
9809 @item @emph{Arguments}:
9810 @multitable @columnfractions .15 .70
9811 @item @var{ARRAY} @tab Shall be an array of type @code{INTEGER},
9812 @code{REAL} or @code{COMPLEX}.
9813 @item @var{DIM} @tab (Optional) shall be a scalar of type
9814 @code{INTEGER} with a value in the range from 1 to n, where n
9815 equals the rank of @var{ARRAY}.
9816 @item @var{MASK} @tab (Optional) shall be of type @code{LOGICAL}
9817 and either be a scalar or an array of the same shape as @var{ARRAY}.
9820 @item @emph{Return value}:
9821 The result is of the same type as @var{ARRAY}.
9823 If @var{DIM} is absent, a scalar with the product of all elements in
9824 @var{ARRAY} is returned. Otherwise, an array of rank n-1, where n equals
9825 the rank of @var{ARRAY}, and a shape similar to that of @var{ARRAY} with
9826 dimension @var{DIM} dropped is returned.
9829 @item @emph{Example}:
9831 PROGRAM test_product
9832 INTEGER :: x(5) = (/ 1, 2, 3, 4 ,5 /)
9833 print *, PRODUCT(x) ! all elements, product = 120
9834 print *, PRODUCT(x, MASK=MOD(x, 2)==1) ! odd elements, product = 15
9838 @item @emph{See also}:
9845 @section @code{RADIX} --- Base of a model number
9847 @cindex model representation, base
9848 @cindex model representation, radix
9851 @item @emph{Description}:
9852 @code{RADIX(X)} returns the base of the model representing the entity @var{X}.
9854 @item @emph{Standard}:
9855 Fortran 95 and later
9860 @item @emph{Syntax}:
9861 @code{RESULT = RADIX(X)}
9863 @item @emph{Arguments}:
9864 @multitable @columnfractions .15 .70
9865 @item @var{X} @tab Shall be of type @code{INTEGER} or @code{REAL}
9868 @item @emph{Return value}:
9869 The return value is a scalar of type @code{INTEGER} and of the default
9872 @item @emph{See also}:
9873 @ref{SELECTED_REAL_KIND}
9875 @item @emph{Example}:
9878 print *, "The radix for the default integer kind is", radix(0)
9879 print *, "The radix for the default real kind is", radix(0.0)
9880 end program test_radix
9888 @section @code{RAN} --- Real pseudo-random number
9890 @cindex random number generation
9893 @item @emph{Description}:
9894 For compatibility with HP FORTRAN 77/iX, the @code{RAN} intrinsic is
9895 provided as an alias for @code{RAND}. See @ref{RAND} for complete
9898 @item @emph{Standard}:
9904 @item @emph{See also}:
9905 @ref{RAND}, @ref{RANDOM_NUMBER}
9911 @section @code{RAND} --- Real pseudo-random number
9913 @cindex random number generation
9916 @item @emph{Description}:
9917 @code{RAND(FLAG)} returns a pseudo-random number from a uniform
9918 distribution between 0 and 1. If @var{FLAG} is 0, the next number
9919 in the current sequence is returned; if @var{FLAG} is 1, the generator
9920 is restarted by @code{CALL SRAND(0)}; if @var{FLAG} has any other value,
9921 it is used as a new seed with @code{SRAND}.
9923 This intrinsic routine is provided for backwards compatibility with
9924 GNU Fortran 77. It implements a simple modulo generator as provided
9925 by @command{g77}. For new code, one should consider the use of
9926 @ref{RANDOM_NUMBER} as it implements a superior algorithm.
9928 @item @emph{Standard}:
9934 @item @emph{Syntax}:
9935 @code{RESULT = RAND(I)}
9937 @item @emph{Arguments}:
9938 @multitable @columnfractions .15 .70
9939 @item @var{I} @tab Shall be a scalar @code{INTEGER} of kind 4.
9942 @item @emph{Return value}:
9943 The return value is of @code{REAL} type and the default kind.
9945 @item @emph{Example}:
9948 integer,parameter :: seed = 86456
9951 print *, rand(), rand(), rand(), rand()
9952 print *, rand(seed), rand(), rand(), rand()
9953 end program test_rand
9956 @item @emph{See also}:
9957 @ref{SRAND}, @ref{RANDOM_NUMBER}
9964 @section @code{RANDOM_NUMBER} --- Pseudo-random number
9965 @fnindex RANDOM_NUMBER
9966 @cindex random number generation
9969 @item @emph{Description}:
9970 Returns a single pseudorandom number or an array of pseudorandom numbers
9971 from the uniform distribution over the range @math{ 0 \leq x < 1}.
9973 The runtime-library implements George Marsaglia's KISS (Keep It Simple
9974 Stupid) random number generator (RNG). This RNG combines:
9976 @item The congruential generator @math{x(n) = 69069 \cdot x(n-1) + 1327217885}
9977 with a period of @math{2^{32}},
9978 @item A 3-shift shift-register generator with a period of @math{2^{32} - 1},
9979 @item Two 16-bit multiply-with-carry generators with a period of
9980 @math{597273182964842497 > 2^{59}}.
9982 The overall period exceeds @math{2^{123}}.
9984 Please note, this RNG is thread safe if used within OpenMP directives,
9985 i.e., its state will be consistent while called from multiple threads.
9986 However, the KISS generator does not create random numbers in parallel
9987 from multiple sources, but in sequence from a single source. If an
9988 OpenMP-enabled application heavily relies on random numbers, one should
9989 consider employing a dedicated parallel random number generator instead.
9991 @item @emph{Standard}:
9992 Fortran 95 and later
9997 @item @emph{Syntax}:
9998 @code{RANDOM_NUMBER(HARVEST)}
10000 @item @emph{Arguments}:
10001 @multitable @columnfractions .15 .70
10002 @item @var{HARVEST} @tab Shall be a scalar or an array of type @code{REAL}.
10005 @item @emph{Example}:
10007 program test_random_number
10009 CALL init_random_seed() ! see example of RANDOM_SEED
10010 CALL RANDOM_NUMBER(r)
10014 @item @emph{See also}:
10021 @section @code{RANDOM_SEED} --- Initialize a pseudo-random number sequence
10022 @fnindex RANDOM_SEED
10023 @cindex random number generation, seeding
10024 @cindex seeding a random number generator
10027 @item @emph{Description}:
10028 Restarts or queries the state of the pseudorandom number generator used by
10029 @code{RANDOM_NUMBER}.
10031 If @code{RANDOM_SEED} is called without arguments, it is initialized to
10032 a default state. The example below shows how to initialize the random
10033 seed based on the system's time.
10035 @item @emph{Standard}:
10036 Fortran 95 and later
10038 @item @emph{Class}:
10041 @item @emph{Syntax}:
10042 @code{CALL RANDOM_SEED([SIZE, PUT, GET])}
10044 @item @emph{Arguments}:
10045 @multitable @columnfractions .15 .70
10046 @item @var{SIZE} @tab (Optional) Shall be a scalar and of type default
10047 @code{INTEGER}, with @code{INTENT(OUT)}. It specifies the minimum size
10048 of the arrays used with the @var{PUT} and @var{GET} arguments.
10049 @item @var{PUT} @tab (Optional) Shall be an array of type default
10050 @code{INTEGER} and rank one. It is @code{INTENT(IN)} and the size of
10051 the array must be larger than or equal to the number returned by the
10052 @var{SIZE} argument.
10053 @item @var{GET} @tab (Optional) Shall be an array of type default
10054 @code{INTEGER} and rank one. It is @code{INTENT(OUT)} and the size
10055 of the array must be larger than or equal to the number returned by
10056 the @var{SIZE} argument.
10059 @item @emph{Example}:
10061 SUBROUTINE init_random_seed()
10062 INTEGER :: i, n, clock
10063 INTEGER, DIMENSION(:), ALLOCATABLE :: seed
10065 CALL RANDOM_SEED(size = n)
10068 CALL SYSTEM_CLOCK(COUNT=clock)
10070 seed = clock + 37 * (/ (i - 1, i = 1, n) /)
10071 CALL RANDOM_SEED(PUT = seed)
10077 @item @emph{See also}:
10078 @ref{RANDOM_NUMBER}
10084 @section @code{RANGE} --- Decimal exponent range
10086 @cindex model representation, range
10089 @item @emph{Description}:
10090 @code{RANGE(X)} returns the decimal exponent range in the model of the
10093 @item @emph{Standard}:
10094 Fortran 95 and later
10096 @item @emph{Class}:
10099 @item @emph{Syntax}:
10100 @code{RESULT = RANGE(X)}
10102 @item @emph{Arguments}:
10103 @multitable @columnfractions .15 .70
10104 @item @var{X} @tab Shall be of type @code{INTEGER}, @code{REAL}
10108 @item @emph{Return value}:
10109 The return value is of type @code{INTEGER} and of the default integer
10112 @item @emph{See also}:
10113 @ref{SELECTED_REAL_KIND}, @ref{PRECISION}
10115 @item @emph{Example}:
10116 See @code{PRECISION} for an example.
10122 @section @code{REAL} --- Convert to real type
10128 @cindex conversion, to real
10129 @cindex complex numbers, real part
10132 @item @emph{Description}:
10133 @code{REAL(A [, KIND])} converts its argument @var{A} to a real type. The
10134 @code{REALPART} function is provided for compatibility with @command{g77},
10135 and its use is strongly discouraged.
10137 @item @emph{Standard}:
10138 Fortran 77 and later
10140 @item @emph{Class}:
10143 @item @emph{Syntax}:
10144 @multitable @columnfractions .80
10145 @item @code{RESULT = REAL(A [, KIND])}
10146 @item @code{RESULT = REALPART(Z)}
10149 @item @emph{Arguments}:
10150 @multitable @columnfractions .15 .70
10151 @item @var{A} @tab Shall be @code{INTEGER}, @code{REAL}, or
10153 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
10154 expression indicating the kind parameter of the result.
10157 @item @emph{Return value}:
10158 These functions return a @code{REAL} variable or array under
10159 the following rules:
10163 @code{REAL(A)} is converted to a default real type if @var{A} is an
10164 integer or real variable.
10166 @code{REAL(A)} is converted to a real type with the kind type parameter
10167 of @var{A} if @var{A} is a complex variable.
10169 @code{REAL(A, KIND)} is converted to a real type with kind type
10170 parameter @var{KIND} if @var{A} is a complex, integer, or real
10174 @item @emph{Example}:
10177 complex :: x = (1.0, 2.0)
10178 print *, real(x), real(x,8), realpart(x)
10179 end program test_real
10182 @item @emph{Specific names}:
10183 @multitable @columnfractions .20 .20 .20 .25
10184 @item Name @tab Argument @tab Return type @tab Standard
10185 @item @code{FLOAT(A)} @tab @code{INTEGER(4)} @tab @code{REAL(4)} @tab Fortran 77 and later
10186 @item @code{DFLOAT(A)} @tab @code{INTEGER(4)} @tab @code{REAL(8)} @tab GNU extension
10187 @item @code{SNGL(A)} @tab @code{INTEGER(8)} @tab @code{REAL(4)} @tab Fortran 77 and later
10191 @item @emph{See also}:
10199 @section @code{RENAME} --- Rename a file
10201 @cindex file system, rename file
10204 @item @emph{Description}:
10205 Renames a file from file @var{PATH1} to @var{PATH2}. A null
10206 character (@code{CHAR(0)}) can be used to mark the end of the names in
10207 @var{PATH1} and @var{PATH2}; otherwise, trailing blanks in the file
10208 names are ignored. If the @var{STATUS} argument is supplied, it
10209 contains 0 on success or a nonzero error code upon return; see
10212 This intrinsic is provided in both subroutine and function forms;
10213 however, only one form can be used in any given program unit.
10215 @item @emph{Standard}:
10218 @item @emph{Class}:
10219 Subroutine, function
10221 @item @emph{Syntax}:
10222 @multitable @columnfractions .80
10223 @item @code{CALL RENAME(PATH1, PATH2 [, STATUS])}
10224 @item @code{STATUS = RENAME(PATH1, PATH2)}
10227 @item @emph{Arguments}:
10228 @multitable @columnfractions .15 .70
10229 @item @var{PATH1} @tab Shall be of default @code{CHARACTER} type.
10230 @item @var{PATH2} @tab Shall be of default @code{CHARACTER} type.
10231 @item @var{STATUS} @tab (Optional) Shall be of default @code{INTEGER} type.
10234 @item @emph{See also}:
10242 @section @code{REPEAT} --- Repeated string concatenation
10244 @cindex string, repeat
10245 @cindex string, concatenate
10248 @item @emph{Description}:
10249 Concatenates @var{NCOPIES} copies of a string.
10251 @item @emph{Standard}:
10252 Fortran 95 and later
10254 @item @emph{Class}:
10255 Transformational function
10257 @item @emph{Syntax}:
10258 @code{RESULT = REPEAT(STRING, NCOPIES)}
10260 @item @emph{Arguments}:
10261 @multitable @columnfractions .15 .70
10262 @item @var{STRING} @tab Shall be scalar and of type @code{CHARACTER}.
10263 @item @var{NCOPIES} @tab Shall be scalar and of type @code{INTEGER}.
10266 @item @emph{Return value}:
10267 A new scalar of type @code{CHARACTER} built up from @var{NCOPIES} copies
10270 @item @emph{Example}:
10272 program test_repeat
10273 write(*,*) repeat("x", 5) ! "xxxxx"
10281 @section @code{RESHAPE} --- Function to reshape an array
10283 @cindex array, change dimensions
10284 @cindex array, transmogrify
10287 @item @emph{Description}:
10288 Reshapes @var{SOURCE} to correspond to @var{SHAPE}. If necessary,
10289 the new array may be padded with elements from @var{PAD} or permuted
10290 as defined by @var{ORDER}.
10292 @item @emph{Standard}:
10293 Fortran 95 and later
10295 @item @emph{Class}:
10296 Transformational function
10298 @item @emph{Syntax}:
10299 @code{RESULT = RESHAPE(SOURCE, SHAPE[, PAD, ORDER])}
10301 @item @emph{Arguments}:
10302 @multitable @columnfractions .15 .70
10303 @item @var{SOURCE} @tab Shall be an array of any type.
10304 @item @var{SHAPE} @tab Shall be of type @code{INTEGER} and an
10305 array of rank one. Its values must be positive or zero.
10306 @item @var{PAD} @tab (Optional) shall be an array of the same
10307 type as @var{SOURCE}.
10308 @item @var{ORDER} @tab (Optional) shall be of type @code{INTEGER}
10309 and an array of the same shape as @var{SHAPE}. Its values shall
10310 be a permutation of the numbers from 1 to n, where n is the size of
10311 @var{SHAPE}. If @var{ORDER} is absent, the natural ordering shall
10315 @item @emph{Return value}:
10316 The result is an array of shape @var{SHAPE} with the same type as
10319 @item @emph{Example}:
10321 PROGRAM test_reshape
10322 INTEGER, DIMENSION(4) :: x
10323 WRITE(*,*) SHAPE(x) ! prints "4"
10324 WRITE(*,*) SHAPE(RESHAPE(x, (/2, 2/))) ! prints "2 2"
10328 @item @emph{See also}:
10335 @section @code{RRSPACING} --- Reciprocal of the relative spacing
10337 @cindex real number, relative spacing
10338 @cindex floating point, relative spacing
10342 @item @emph{Description}:
10343 @code{RRSPACING(X)} returns the reciprocal of the relative spacing of
10344 model numbers near @var{X}.
10346 @item @emph{Standard}:
10347 Fortran 95 and later
10349 @item @emph{Class}:
10352 @item @emph{Syntax}:
10353 @code{RESULT = RRSPACING(X)}
10355 @item @emph{Arguments}:
10356 @multitable @columnfractions .15 .70
10357 @item @var{X} @tab Shall be of type @code{REAL}.
10360 @item @emph{Return value}:
10361 The return value is of the same type and kind as @var{X}.
10362 The value returned is equal to
10363 @code{ABS(FRACTION(X)) * FLOAT(RADIX(X))**DIGITS(X)}.
10365 @item @emph{See also}:
10372 @section @code{RSHIFT} --- Right shift bits
10374 @cindex bits, shift right
10377 @item @emph{Description}:
10378 @code{RSHIFT} returns a value corresponding to @var{I} with all of the
10379 bits shifted right by @var{SHIFT} places. If the absolute value of
10380 @var{SHIFT} is greater than @code{BIT_SIZE(I)}, the value is undefined.
10381 Bits shifted out from the right end are lost. The fill is arithmetic: the
10382 bits shifted in from the left end are equal to the leftmost bit, which in
10383 two's complement representation is the sign bit.
10385 This function has been superseded by the @code{SHIFTA} intrinsic, which
10386 is standard in Fortran 2008 and later.
10388 @item @emph{Standard}:
10391 @item @emph{Class}:
10394 @item @emph{Syntax}:
10395 @code{RESULT = RSHIFT(I, SHIFT)}
10397 @item @emph{Arguments}:
10398 @multitable @columnfractions .15 .70
10399 @item @var{I} @tab The type shall be @code{INTEGER}.
10400 @item @var{SHIFT} @tab The type shall be @code{INTEGER}.
10403 @item @emph{Return value}:
10404 The return value is of type @code{INTEGER} and of the same kind as
10407 @item @emph{See also}:
10408 @ref{ISHFT}, @ref{ISHFTC}, @ref{LSHIFT}, @ref{SHIFTA}, @ref{SHIFTR},
10416 @section @code{SAME_TYPE_AS} --- Query dynamic types for equality
10417 @fnindex SAME_TYPE_AS
10420 @item @emph{Description}:
10421 Query dynamic types for equality.
10423 @item @emph{Standard}:
10424 Fortran 2003 and later
10426 @item @emph{Class}:
10429 @item @emph{Syntax}:
10430 @code{RESULT = SAME_TYPE_AS(A, B)}
10432 @item @emph{Arguments}:
10433 @multitable @columnfractions .15 .70
10434 @item @var{A} @tab Shall be an object of extensible declared type or
10435 unlimited polymorphic.
10436 @item @var{B} @tab Shall be an object of extensible declared type or
10437 unlimited polymorphic.
10440 @item @emph{Return value}:
10441 The return value is a scalar of type default logical. It is true if and
10442 only if the dynamic type of A is the same as the dynamic type of B.
10444 @item @emph{See also}:
10445 @ref{EXTENDS_TYPE_OF}
10452 @section @code{SCALE} --- Scale a real value
10454 @cindex real number, scale
10455 @cindex floating point, scale
10458 @item @emph{Description}:
10459 @code{SCALE(X,I)} returns @code{X * RADIX(X)**I}.
10461 @item @emph{Standard}:
10462 Fortran 95 and later
10464 @item @emph{Class}:
10467 @item @emph{Syntax}:
10468 @code{RESULT = SCALE(X, I)}
10470 @item @emph{Arguments}:
10471 @multitable @columnfractions .15 .70
10472 @item @var{X} @tab The type of the argument shall be a @code{REAL}.
10473 @item @var{I} @tab The type of the argument shall be a @code{INTEGER}.
10476 @item @emph{Return value}:
10477 The return value is of the same type and kind as @var{X}.
10478 Its value is @code{X * RADIX(X)**I}.
10480 @item @emph{Example}:
10483 real :: x = 178.1387e-4
10485 print *, scale(x,i), x*radix(x)**i
10486 end program test_scale
10494 @section @code{SCAN} --- Scan a string for the presence of a set of characters
10496 @cindex string, find subset
10499 @item @emph{Description}:
10500 Scans a @var{STRING} for any of the characters in a @var{SET}
10503 If @var{BACK} is either absent or equals @code{FALSE}, this function
10504 returns the position of the leftmost character of @var{STRING} that is
10505 in @var{SET}. If @var{BACK} equals @code{TRUE}, the rightmost position
10506 is returned. If no character of @var{SET} is found in @var{STRING}, the
10509 @item @emph{Standard}:
10510 Fortran 95 and later, with @var{KIND} argument Fortran 2003 and later
10512 @item @emph{Class}:
10515 @item @emph{Syntax}:
10516 @code{RESULT = SCAN(STRING, SET[, BACK [, KIND]])}
10518 @item @emph{Arguments}:
10519 @multitable @columnfractions .15 .70
10520 @item @var{STRING} @tab Shall be of type @code{CHARACTER}.
10521 @item @var{SET} @tab Shall be of type @code{CHARACTER}.
10522 @item @var{BACK} @tab (Optional) shall be of type @code{LOGICAL}.
10523 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
10524 expression indicating the kind parameter of the result.
10527 @item @emph{Return value}:
10528 The return value is of type @code{INTEGER} and of kind @var{KIND}. If
10529 @var{KIND} is absent, the return value is of default integer kind.
10531 @item @emph{Example}:
10534 WRITE(*,*) SCAN("FORTRAN", "AO") ! 2, found 'O'
10535 WRITE(*,*) SCAN("FORTRAN", "AO", .TRUE.) ! 6, found 'A'
10536 WRITE(*,*) SCAN("FORTRAN", "C++") ! 0, found none
10540 @item @emph{See also}:
10541 @ref{INDEX intrinsic}, @ref{VERIFY}
10547 @section @code{SECNDS} --- Time function
10549 @cindex time, elapsed
10550 @cindex elapsed time
10553 @item @emph{Description}:
10554 @code{SECNDS(X)} gets the time in seconds from the real-time system clock.
10555 @var{X} is a reference time, also in seconds. If this is zero, the time in
10556 seconds from midnight is returned. This function is non-standard and its
10557 use is discouraged.
10559 @item @emph{Standard}:
10562 @item @emph{Class}:
10565 @item @emph{Syntax}:
10566 @code{RESULT = SECNDS (X)}
10568 @item @emph{Arguments}:
10569 @multitable @columnfractions .15 .70
10570 @item @var{T} @tab Shall be of type @code{REAL(4)}.
10571 @item @var{X} @tab Shall be of type @code{REAL(4)}.
10574 @item @emph{Return value}:
10577 @item @emph{Example}:
10579 program test_secnds
10582 print *, secnds (0.0) ! seconds since midnight
10583 t1 = secnds (0.0) ! reference time
10584 do i = 1, 10000000 ! do something
10586 t2 = secnds (t1) ! elapsed time
10587 print *, "Something took ", t2, " seconds."
10588 end program test_secnds
10595 @section @code{SECOND} --- CPU time function
10597 @cindex time, elapsed
10598 @cindex elapsed time
10601 @item @emph{Description}:
10602 Returns a @code{REAL(4)} value representing the elapsed CPU time in
10603 seconds. This provides the same functionality as the standard
10604 @code{CPU_TIME} intrinsic, and is only included for backwards
10607 This intrinsic is provided in both subroutine and function forms;
10608 however, only one form can be used in any given program unit.
10610 @item @emph{Standard}:
10613 @item @emph{Class}:
10614 Subroutine, function
10616 @item @emph{Syntax}:
10617 @multitable @columnfractions .80
10618 @item @code{CALL SECOND(TIME)}
10619 @item @code{TIME = SECOND()}
10622 @item @emph{Arguments}:
10623 @multitable @columnfractions .15 .70
10624 @item @var{TIME} @tab Shall be of type @code{REAL(4)}.
10627 @item @emph{Return value}:
10628 In either syntax, @var{TIME} is set to the process's current runtime in
10631 @item @emph{See also}:
10638 @node SELECTED_CHAR_KIND
10639 @section @code{SELECTED_CHAR_KIND} --- Choose character kind
10640 @fnindex SELECTED_CHAR_KIND
10641 @cindex character kind
10642 @cindex kind, character
10645 @item @emph{Description}:
10647 @code{SELECTED_CHAR_KIND(NAME)} returns the kind value for the character
10648 set named @var{NAME}, if a character set with such a name is supported,
10649 or @math{-1} otherwise. Currently, supported character sets include
10650 ``ASCII'' and ``DEFAULT'', which are equivalent, and ``ISO_10646''
10651 (Universal Character Set, UCS-4) which is commonly known as Unicode.
10653 @item @emph{Standard}:
10654 Fortran 2003 and later
10656 @item @emph{Class}:
10657 Transformational function
10659 @item @emph{Syntax}:
10660 @code{RESULT = SELECTED_CHAR_KIND(NAME)}
10662 @item @emph{Arguments}:
10663 @multitable @columnfractions .15 .70
10664 @item @var{NAME} @tab Shall be a scalar and of the default character type.
10667 @item @emph{Example}:
10669 program character_kind
10670 use iso_fortran_env
10672 integer, parameter :: ascii = selected_char_kind ("ascii")
10673 integer, parameter :: ucs4 = selected_char_kind ('ISO_10646')
10675 character(kind=ascii, len=26) :: alphabet
10676 character(kind=ucs4, len=30) :: hello_world
10678 alphabet = ascii_"abcdefghijklmnopqrstuvwxyz"
10679 hello_world = ucs4_'Hello World and Ni Hao -- ' &
10680 // char (int (z'4F60'), ucs4) &
10681 // char (int (z'597D'), ucs4)
10683 write (*,*) alphabet
10685 open (output_unit, encoding='UTF-8')
10686 write (*,*) trim (hello_world)
10687 end program character_kind
10693 @node SELECTED_INT_KIND
10694 @section @code{SELECTED_INT_KIND} --- Choose integer kind
10695 @fnindex SELECTED_INT_KIND
10696 @cindex integer kind
10697 @cindex kind, integer
10700 @item @emph{Description}:
10701 @code{SELECTED_INT_KIND(R)} return the kind value of the smallest integer
10702 type that can represent all values ranging from @math{-10^R} (exclusive)
10703 to @math{10^R} (exclusive). If there is no integer kind that accommodates
10704 this range, @code{SELECTED_INT_KIND} returns @math{-1}.
10706 @item @emph{Standard}:
10707 Fortran 95 and later
10709 @item @emph{Class}:
10710 Transformational function
10712 @item @emph{Syntax}:
10713 @code{RESULT = SELECTED_INT_KIND(R)}
10715 @item @emph{Arguments}:
10716 @multitable @columnfractions .15 .70
10717 @item @var{R} @tab Shall be a scalar and of type @code{INTEGER}.
10720 @item @emph{Example}:
10722 program large_integers
10723 integer,parameter :: k5 = selected_int_kind(5)
10724 integer,parameter :: k15 = selected_int_kind(15)
10725 integer(kind=k5) :: i5
10726 integer(kind=k15) :: i15
10728 print *, huge(i5), huge(i15)
10730 ! The following inequalities are always true
10731 print *, huge(i5) >= 10_k5**5-1
10732 print *, huge(i15) >= 10_k15**15-1
10733 end program large_integers
10739 @node SELECTED_REAL_KIND
10740 @section @code{SELECTED_REAL_KIND} --- Choose real kind
10741 @fnindex SELECTED_REAL_KIND
10744 @cindex radix, real
10747 @item @emph{Description}:
10748 @code{SELECTED_REAL_KIND(P,R)} returns the kind value of a real data type
10749 with decimal precision of at least @code{P} digits, exponent range of
10750 at least @code{R}, and with a radix of @code{RADIX}.
10752 @item @emph{Standard}:
10753 Fortran 95 and later, with @code{RADIX} Fortran 2008 or later
10755 @item @emph{Class}:
10756 Transformational function
10758 @item @emph{Syntax}:
10759 @code{RESULT = SELECTED_REAL_KIND([P, R, RADIX])}
10761 @item @emph{Arguments}:
10762 @multitable @columnfractions .15 .70
10763 @item @var{P} @tab (Optional) shall be a scalar and of type @code{INTEGER}.
10764 @item @var{R} @tab (Optional) shall be a scalar and of type @code{INTEGER}.
10765 @item @var{RADIX} @tab (Optional) shall be a scalar and of type @code{INTEGER}.
10767 Before Fortran 2008, at least one of the arguments @var{R} or @var{P} shall
10768 be present; since Fortran 2008, they are assumed to be zero if absent.
10770 @item @emph{Return value}:
10772 @code{SELECTED_REAL_KIND} returns the value of the kind type parameter of
10773 a real data type with decimal precision of at least @code{P} digits, a
10774 decimal exponent range of at least @code{R}, and with the requested
10775 @code{RADIX}. If the @code{RADIX} parameter is absent, real kinds with
10776 any radix can be returned. If more than one real data type meet the
10777 criteria, the kind of the data type with the smallest decimal precision
10778 is returned. If no real data type matches the criteria, the result is
10780 @item -1 if the processor does not support a real data type with a
10781 precision greater than or equal to @code{P}, but the @code{R} and
10782 @code{RADIX} requirements can be fulfilled
10783 @item -2 if the processor does not support a real type with an exponent
10784 range greater than or equal to @code{R}, but @code{P} and @code{RADIX}
10786 @item -3 if @code{RADIX} but not @code{P} and @code{R} requirements
10788 @item -4 if @code{RADIX} and either @code{P} or @code{R} requirements
10790 @item -5 if there is no real type with the given @code{RADIX}
10793 @item @emph{See also}:
10794 @ref{PRECISION}, @ref{RANGE}, @ref{RADIX}
10796 @item @emph{Example}:
10799 integer,parameter :: p6 = selected_real_kind(6)
10800 integer,parameter :: p10r100 = selected_real_kind(10,100)
10801 integer,parameter :: r400 = selected_real_kind(r=400)
10803 real(kind=p10r100) :: y
10804 real(kind=r400) :: z
10806 print *, precision(x), range(x)
10807 print *, precision(y), range(y)
10808 print *, precision(z), range(z)
10809 end program real_kinds
10816 @section @code{SET_EXPONENT} --- Set the exponent of the model
10817 @fnindex SET_EXPONENT
10818 @cindex real number, set exponent
10819 @cindex floating point, set exponent
10822 @item @emph{Description}:
10823 @code{SET_EXPONENT(X, I)} returns the real number whose fractional part
10824 is that that of @var{X} and whose exponent part is @var{I}.
10826 @item @emph{Standard}:
10827 Fortran 95 and later
10829 @item @emph{Class}:
10832 @item @emph{Syntax}:
10833 @code{RESULT = SET_EXPONENT(X, I)}
10835 @item @emph{Arguments}:
10836 @multitable @columnfractions .15 .70
10837 @item @var{X} @tab Shall be of type @code{REAL}.
10838 @item @var{I} @tab Shall be of type @code{INTEGER}.
10841 @item @emph{Return value}:
10842 The return value is of the same type and kind as @var{X}.
10843 The real number whose fractional part
10844 is that that of @var{X} and whose exponent part if @var{I} is returned;
10845 it is @code{FRACTION(X) * RADIX(X)**I}.
10847 @item @emph{Example}:
10849 PROGRAM test_setexp
10850 REAL :: x = 178.1387e-4
10852 PRINT *, SET_EXPONENT(x, i), FRACTION(x) * RADIX(x)**i
10861 @section @code{SHAPE} --- Determine the shape of an array
10863 @cindex array, shape
10866 @item @emph{Description}:
10867 Determines the shape of an array.
10869 @item @emph{Standard}:
10870 Fortran 95 and later, with @var{KIND} argument Fortran 2003 and later
10872 @item @emph{Class}:
10875 @item @emph{Syntax}:
10876 @code{RESULT = SHAPE(SOURCE [, KIND])}
10878 @item @emph{Arguments}:
10879 @multitable @columnfractions .15 .70
10880 @item @var{SOURCE} @tab Shall be an array or scalar of any type.
10881 If @var{SOURCE} is a pointer it must be associated and allocatable
10882 arrays must be allocated.
10883 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
10884 expression indicating the kind parameter of the result.
10887 @item @emph{Return value}:
10888 An @code{INTEGER} array of rank one with as many elements as @var{SOURCE}
10889 has dimensions. The elements of the resulting array correspond to the extend
10890 of @var{SOURCE} along the respective dimensions. If @var{SOURCE} is a scalar,
10891 the result is the rank one array of size zero. If @var{KIND} is absent, the
10892 return value has the default integer kind otherwise the specified kind.
10894 @item @emph{Example}:
10897 INTEGER, DIMENSION(-1:1, -1:2) :: A
10898 WRITE(*,*) SHAPE(A) ! (/ 3, 4 /)
10899 WRITE(*,*) SIZE(SHAPE(42)) ! (/ /)
10903 @item @emph{See also}:
10904 @ref{RESHAPE}, @ref{SIZE}
10910 @section @code{SHIFTA} --- Right shift with fill
10912 @cindex bits, shift right
10913 @cindex shift, right with fill
10916 @item @emph{Description}:
10917 @code{SHIFTA} returns a value corresponding to @var{I} with all of the
10918 bits shifted right by @var{SHIFT} places. If the absolute value of
10919 @var{SHIFT} is greater than @code{BIT_SIZE(I)}, the value is undefined.
10920 Bits shifted out from the right end are lost. The fill is arithmetic: the
10921 bits shifted in from the left end are equal to the leftmost bit, which in
10922 two's complement representation is the sign bit.
10924 @item @emph{Standard}:
10925 Fortran 2008 and later
10927 @item @emph{Class}:
10930 @item @emph{Syntax}:
10931 @code{RESULT = SHIFTA(I, SHIFT)}
10933 @item @emph{Arguments}:
10934 @multitable @columnfractions .15 .70
10935 @item @var{I} @tab The type shall be @code{INTEGER}.
10936 @item @var{SHIFT} @tab The type shall be @code{INTEGER}.
10939 @item @emph{Return value}:
10940 The return value is of type @code{INTEGER} and of the same kind as
10943 @item @emph{See also}:
10944 @ref{SHIFTL}, @ref{SHIFTR}
10950 @section @code{SHIFTL} --- Left shift
10952 @cindex bits, shift left
10953 @cindex shift, left
10956 @item @emph{Description}:
10957 @code{SHIFTL} returns a value corresponding to @var{I} with all of the
10958 bits shifted left by @var{SHIFT} places. If the absolute value of
10959 @var{SHIFT} is greater than @code{BIT_SIZE(I)}, the value is undefined.
10960 Bits shifted out from the left end are lost, and bits shifted in from
10961 the right end are set to 0.
10963 @item @emph{Standard}:
10964 Fortran 2008 and later
10966 @item @emph{Class}:
10969 @item @emph{Syntax}:
10970 @code{RESULT = SHIFTL(I, SHIFT)}
10972 @item @emph{Arguments}:
10973 @multitable @columnfractions .15 .70
10974 @item @var{I} @tab The type shall be @code{INTEGER}.
10975 @item @var{SHIFT} @tab The type shall be @code{INTEGER}.
10978 @item @emph{Return value}:
10979 The return value is of type @code{INTEGER} and of the same kind as
10982 @item @emph{See also}:
10983 @ref{SHIFTA}, @ref{SHIFTR}
10989 @section @code{SHIFTR} --- Right shift
10991 @cindex bits, shift right
10992 @cindex shift, right
10995 @item @emph{Description}:
10996 @code{SHIFTR} returns a value corresponding to @var{I} with all of the
10997 bits shifted right by @var{SHIFT} places. If the absolute value of
10998 @var{SHIFT} is greater than @code{BIT_SIZE(I)}, the value is undefined.
10999 Bits shifted out from the right end are lost, and bits shifted in from
11000 the left end are set to 0.
11002 @item @emph{Standard}:
11003 Fortran 2008 and later
11005 @item @emph{Class}:
11008 @item @emph{Syntax}:
11009 @code{RESULT = SHIFTR(I, SHIFT)}
11011 @item @emph{Arguments}:
11012 @multitable @columnfractions .15 .70
11013 @item @var{I} @tab The type shall be @code{INTEGER}.
11014 @item @var{SHIFT} @tab The type shall be @code{INTEGER}.
11017 @item @emph{Return value}:
11018 The return value is of type @code{INTEGER} and of the same kind as
11021 @item @emph{See also}:
11022 @ref{SHIFTA}, @ref{SHIFTL}
11028 @section @code{SIGN} --- Sign copying function
11032 @cindex sign copying
11035 @item @emph{Description}:
11036 @code{SIGN(A,B)} returns the value of @var{A} with the sign of @var{B}.
11038 @item @emph{Standard}:
11039 Fortran 77 and later
11041 @item @emph{Class}:
11044 @item @emph{Syntax}:
11045 @code{RESULT = SIGN(A, B)}
11047 @item @emph{Arguments}:
11048 @multitable @columnfractions .15 .70
11049 @item @var{A} @tab Shall be of type @code{INTEGER} or @code{REAL}
11050 @item @var{B} @tab Shall be of the same type and kind as @var{A}
11053 @item @emph{Return value}:
11054 The kind of the return value is that of @var{A} and @var{B}.
11055 If @math{B\ge 0} then the result is @code{ABS(A)}, else
11056 it is @code{-ABS(A)}.
11058 @item @emph{Example}:
11061 print *, sign(-12,1)
11062 print *, sign(-12,0)
11063 print *, sign(-12,-1)
11065 print *, sign(-12.,1.)
11066 print *, sign(-12.,0.)
11067 print *, sign(-12.,-1.)
11068 end program test_sign
11071 @item @emph{Specific names}:
11072 @multitable @columnfractions .20 .20 .20 .25
11073 @item Name @tab Arguments @tab Return type @tab Standard
11074 @item @code{SIGN(A,B)} @tab @code{REAL(4) A, B} @tab @code{REAL(4)} @tab f77, gnu
11075 @item @code{ISIGN(A,B)} @tab @code{INTEGER(4) A, B} @tab @code{INTEGER(4)} @tab f77, gnu
11076 @item @code{DSIGN(A,B)} @tab @code{REAL(8) A, B} @tab @code{REAL(8)} @tab f77, gnu
11083 @section @code{SIGNAL} --- Signal handling subroutine (or function)
11085 @cindex system, signal handling
11088 @item @emph{Description}:
11089 @code{SIGNAL(NUMBER, HANDLER [, STATUS])} causes external subroutine
11090 @var{HANDLER} to be executed with a single integer argument when signal
11091 @var{NUMBER} occurs. If @var{HANDLER} is an integer, it can be used to
11092 turn off handling of signal @var{NUMBER} or revert to its default
11093 action. See @code{signal(2)}.
11095 If @code{SIGNAL} is called as a subroutine and the @var{STATUS} argument
11096 is supplied, it is set to the value returned by @code{signal(2)}.
11098 @item @emph{Standard}:
11101 @item @emph{Class}:
11102 Subroutine, function
11104 @item @emph{Syntax}:
11105 @multitable @columnfractions .80
11106 @item @code{CALL SIGNAL(NUMBER, HANDLER [, STATUS])}
11107 @item @code{STATUS = SIGNAL(NUMBER, HANDLER)}
11110 @item @emph{Arguments}:
11111 @multitable @columnfractions .15 .70
11112 @item @var{NUMBER} @tab Shall be a scalar integer, with @code{INTENT(IN)}
11113 @item @var{HANDLER}@tab Signal handler (@code{INTEGER FUNCTION} or
11114 @code{SUBROUTINE}) or dummy/global @code{INTEGER} scalar.
11115 @code{INTEGER}. It is @code{INTENT(IN)}.
11116 @item @var{STATUS} @tab (Optional) @var{STATUS} shall be a scalar
11117 integer. It has @code{INTENT(OUT)}.
11119 @c TODO: What should the interface of the handler be? Does it take arguments?
11121 @item @emph{Return value}:
11122 The @code{SIGNAL} function returns the value returned by @code{signal(2)}.
11124 @item @emph{Example}:
11126 program test_signal
11128 external handler_print
11130 call signal (12, handler_print)
11131 call signal (10, 1)
11134 end program test_signal
11141 @section @code{SIN} --- Sine function
11147 @cindex trigonometric function, sine
11151 @item @emph{Description}:
11152 @code{SIN(X)} computes the sine of @var{X}.
11154 @item @emph{Standard}:
11155 Fortran 77 and later
11157 @item @emph{Class}:
11160 @item @emph{Syntax}:
11161 @code{RESULT = SIN(X)}
11163 @item @emph{Arguments}:
11164 @multitable @columnfractions .15 .70
11165 @item @var{X} @tab The type shall be @code{REAL} or
11169 @item @emph{Return value}:
11170 The return value has same type and kind as @var{X}.
11172 @item @emph{Example}:
11177 end program test_sin
11180 @item @emph{Specific names}:
11181 @multitable @columnfractions .20 .20 .20 .25
11182 @item Name @tab Argument @tab Return type @tab Standard
11183 @item @code{SIN(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab f77, gnu
11184 @item @code{DSIN(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab f95, gnu
11185 @item @code{CSIN(X)} @tab @code{COMPLEX(4) X} @tab @code{COMPLEX(4)} @tab f95, gnu
11186 @item @code{ZSIN(X)} @tab @code{COMPLEX(8) X} @tab @code{COMPLEX(8)} @tab f95, gnu
11187 @item @code{CDSIN(X)} @tab @code{COMPLEX(8) X} @tab @code{COMPLEX(8)} @tab f95, gnu
11190 @item @emph{See also}:
11197 @section @code{SINH} --- Hyperbolic sine function
11200 @cindex hyperbolic sine
11201 @cindex hyperbolic function, sine
11202 @cindex sine, hyperbolic
11205 @item @emph{Description}:
11206 @code{SINH(X)} computes the hyperbolic sine of @var{X}.
11208 @item @emph{Standard}:
11209 Fortran 95 and later, for a complex argument Fortran 2008 or later
11211 @item @emph{Class}:
11214 @item @emph{Syntax}:
11215 @code{RESULT = SINH(X)}
11217 @item @emph{Arguments}:
11218 @multitable @columnfractions .15 .70
11219 @item @var{X} @tab The type shall be @code{REAL} or @code{COMPLEX}.
11222 @item @emph{Return value}:
11223 The return value has same type and kind as @var{X}.
11225 @item @emph{Example}:
11228 real(8) :: x = - 1.0_8
11230 end program test_sinh
11233 @item @emph{Specific names}:
11234 @multitable @columnfractions .20 .20 .20 .25
11235 @item Name @tab Argument @tab Return type @tab Standard
11236 @item @code{SINH(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab Fortran 95 and later
11237 @item @code{DSINH(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab Fortran 95 and later
11240 @item @emph{See also}:
11247 @section @code{SIZE} --- Determine the size of an array
11249 @cindex array, size
11250 @cindex array, number of elements
11251 @cindex array, count elements
11254 @item @emph{Description}:
11255 Determine the extent of @var{ARRAY} along a specified dimension @var{DIM},
11256 or the total number of elements in @var{ARRAY} if @var{DIM} is absent.
11258 @item @emph{Standard}:
11259 Fortran 95 and later, with @var{KIND} argument Fortran 2003 and later
11261 @item @emph{Class}:
11264 @item @emph{Syntax}:
11265 @code{RESULT = SIZE(ARRAY[, DIM [, KIND]])}
11267 @item @emph{Arguments}:
11268 @multitable @columnfractions .15 .70
11269 @item @var{ARRAY} @tab Shall be an array of any type. If @var{ARRAY} is
11270 a pointer it must be associated and allocatable arrays must be allocated.
11271 @item @var{DIM} @tab (Optional) shall be a scalar of type @code{INTEGER}
11272 and its value shall be in the range from 1 to n, where n equals the rank
11274 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
11275 expression indicating the kind parameter of the result.
11278 @item @emph{Return value}:
11279 The return value is of type @code{INTEGER} and of kind @var{KIND}. If
11280 @var{KIND} is absent, the return value is of default integer kind.
11282 @item @emph{Example}:
11285 WRITE(*,*) SIZE((/ 1, 2 /)) ! 2
11289 @item @emph{See also}:
11290 @ref{SHAPE}, @ref{RESHAPE}
11295 @section @code{SIZEOF} --- Size in bytes of an expression
11297 @cindex expression size
11298 @cindex size of an expression
11301 @item @emph{Description}:
11302 @code{SIZEOF(X)} calculates the number of bytes of storage the
11303 expression @code{X} occupies.
11305 @item @emph{Standard}:
11308 @item @emph{Class}:
11311 @item @emph{Syntax}:
11312 @code{N = SIZEOF(X)}
11314 @item @emph{Arguments}:
11315 @multitable @columnfractions .15 .70
11316 @item @var{X} @tab The argument shall be of any type, rank or shape.
11319 @item @emph{Return value}:
11320 The return value is of type integer and of the system-dependent kind
11321 @var{C_SIZE_T} (from the @var{ISO_C_BINDING} module). Its value is the
11322 number of bytes occupied by the argument. If the argument has the
11323 @code{POINTER} attribute, the number of bytes of the storage area pointed
11324 to is returned. If the argument is of a derived type with @code{POINTER}
11325 or @code{ALLOCATABLE} components, the return value doesn't account for
11326 the sizes of the data pointed to by these components. If the argument is
11327 polymorphic, the size according to the declared type is returned.
11329 @item @emph{Example}:
11333 print *, (sizeof(s)/sizeof(r) == 5)
11336 The example will print @code{.TRUE.} unless you are using a platform
11337 where default @code{REAL} variables are unusually padded.
11339 @item @emph{See also}:
11340 @ref{C_SIZEOF}, @ref{STORAGE_SIZE}
11345 @section @code{SLEEP} --- Sleep for the specified number of seconds
11347 @cindex delayed execution
11350 @item @emph{Description}:
11351 Calling this subroutine causes the process to pause for @var{SECONDS} seconds.
11353 @item @emph{Standard}:
11356 @item @emph{Class}:
11359 @item @emph{Syntax}:
11360 @code{CALL SLEEP(SECONDS)}
11362 @item @emph{Arguments}:
11363 @multitable @columnfractions .15 .70
11364 @item @var{SECONDS} @tab The type shall be of default @code{INTEGER}.
11367 @item @emph{Example}:
11378 @section @code{SPACING} --- Smallest distance between two numbers of a given type
11380 @cindex real number, relative spacing
11381 @cindex floating point, relative spacing
11384 @item @emph{Description}:
11385 Determines the distance between the argument @var{X} and the nearest
11386 adjacent number of the same type.
11388 @item @emph{Standard}:
11389 Fortran 95 and later
11391 @item @emph{Class}:
11394 @item @emph{Syntax}:
11395 @code{RESULT = SPACING(X)}
11397 @item @emph{Arguments}:
11398 @multitable @columnfractions .15 .70
11399 @item @var{X} @tab Shall be of type @code{REAL}.
11402 @item @emph{Return value}:
11403 The result is of the same type as the input argument @var{X}.
11405 @item @emph{Example}:
11407 PROGRAM test_spacing
11408 INTEGER, PARAMETER :: SGL = SELECTED_REAL_KIND(p=6, r=37)
11409 INTEGER, PARAMETER :: DBL = SELECTED_REAL_KIND(p=13, r=200)
11411 WRITE(*,*) spacing(1.0_SGL) ! "1.1920929E-07" on i686
11412 WRITE(*,*) spacing(1.0_DBL) ! "2.220446049250313E-016" on i686
11416 @item @emph{See also}:
11423 @section @code{SPREAD} --- Add a dimension to an array
11425 @cindex array, increase dimension
11426 @cindex array, duplicate elements
11427 @cindex array, duplicate dimensions
11430 @item @emph{Description}:
11431 Replicates a @var{SOURCE} array @var{NCOPIES} times along a specified
11432 dimension @var{DIM}.
11434 @item @emph{Standard}:
11435 Fortran 95 and later
11437 @item @emph{Class}:
11438 Transformational function
11440 @item @emph{Syntax}:
11441 @code{RESULT = SPREAD(SOURCE, DIM, NCOPIES)}
11443 @item @emph{Arguments}:
11444 @multitable @columnfractions .15 .70
11445 @item @var{SOURCE} @tab Shall be a scalar or an array of any type and
11446 a rank less than seven.
11447 @item @var{DIM} @tab Shall be a scalar of type @code{INTEGER} with a
11448 value in the range from 1 to n+1, where n equals the rank of @var{SOURCE}.
11449 @item @var{NCOPIES} @tab Shall be a scalar of type @code{INTEGER}.
11452 @item @emph{Return value}:
11453 The result is an array of the same type as @var{SOURCE} and has rank n+1
11454 where n equals the rank of @var{SOURCE}.
11456 @item @emph{Example}:
11458 PROGRAM test_spread
11459 INTEGER :: a = 1, b(2) = (/ 1, 2 /)
11460 WRITE(*,*) SPREAD(A, 1, 2) ! "1 1"
11461 WRITE(*,*) SPREAD(B, 1, 2) ! "1 1 2 2"
11465 @item @emph{See also}:
11472 @section @code{SQRT} --- Square-root function
11479 @cindex square-root
11482 @item @emph{Description}:
11483 @code{SQRT(X)} computes the square root of @var{X}.
11485 @item @emph{Standard}:
11486 Fortran 77 and later
11488 @item @emph{Class}:
11491 @item @emph{Syntax}:
11492 @code{RESULT = SQRT(X)}
11494 @item @emph{Arguments}:
11495 @multitable @columnfractions .15 .70
11496 @item @var{X} @tab The type shall be @code{REAL} or
11500 @item @emph{Return value}:
11501 The return value is of type @code{REAL} or @code{COMPLEX}.
11502 The kind type parameter is the same as @var{X}.
11504 @item @emph{Example}:
11507 real(8) :: x = 2.0_8
11508 complex :: z = (1.0, 2.0)
11511 end program test_sqrt
11514 @item @emph{Specific names}:
11515 @multitable @columnfractions .20 .20 .20 .25
11516 @item Name @tab Argument @tab Return type @tab Standard
11517 @item @code{SQRT(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab Fortran 95 and later
11518 @item @code{DSQRT(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab Fortran 95 and later
11519 @item @code{CSQRT(X)} @tab @code{COMPLEX(4) X} @tab @code{COMPLEX(4)} @tab Fortran 95 and later
11520 @item @code{ZSQRT(X)} @tab @code{COMPLEX(8) X} @tab @code{COMPLEX(8)} @tab GNU extension
11521 @item @code{CDSQRT(X)} @tab @code{COMPLEX(8) X} @tab @code{COMPLEX(8)} @tab GNU extension
11528 @section @code{SRAND} --- Reinitialize the random number generator
11530 @cindex random number generation, seeding
11531 @cindex seeding a random number generator
11534 @item @emph{Description}:
11535 @code{SRAND} reinitializes the pseudo-random number generator
11536 called by @code{RAND} and @code{IRAND}. The new seed used by the
11537 generator is specified by the required argument @var{SEED}.
11539 @item @emph{Standard}:
11542 @item @emph{Class}:
11545 @item @emph{Syntax}:
11546 @code{CALL SRAND(SEED)}
11548 @item @emph{Arguments}:
11549 @multitable @columnfractions .15 .70
11550 @item @var{SEED} @tab Shall be a scalar @code{INTEGER(kind=4)}.
11553 @item @emph{Return value}:
11554 Does not return anything.
11556 @item @emph{Example}:
11557 See @code{RAND} and @code{IRAND} for examples.
11559 @item @emph{Notes}:
11560 The Fortran 2003 standard specifies the intrinsic @code{RANDOM_SEED} to
11561 initialize the pseudo-random numbers generator and @code{RANDOM_NUMBER}
11562 to generate pseudo-random numbers. Please note that in
11563 GNU Fortran, these two sets of intrinsics (@code{RAND},
11564 @code{IRAND} and @code{SRAND} on the one hand, @code{RANDOM_NUMBER} and
11565 @code{RANDOM_SEED} on the other hand) access two independent
11566 pseudo-random number generators.
11568 @item @emph{See also}:
11569 @ref{RAND}, @ref{RANDOM_SEED}, @ref{RANDOM_NUMBER}
11576 @section @code{STAT} --- Get file status
11578 @cindex file system, file status
11581 @item @emph{Description}:
11582 This function returns information about a file. No permissions are required on
11583 the file itself, but execute (search) permission is required on all of the
11584 directories in path that lead to the file.
11586 The elements that are obtained and stored in the array @code{VALUES}:
11587 @multitable @columnfractions .15 .70
11588 @item @code{VALUES(1)} @tab Device ID
11589 @item @code{VALUES(2)} @tab Inode number
11590 @item @code{VALUES(3)} @tab File mode
11591 @item @code{VALUES(4)} @tab Number of links
11592 @item @code{VALUES(5)} @tab Owner's uid
11593 @item @code{VALUES(6)} @tab Owner's gid
11594 @item @code{VALUES(7)} @tab ID of device containing directory entry for file (0 if not available)
11595 @item @code{VALUES(8)} @tab File size (bytes)
11596 @item @code{VALUES(9)} @tab Last access time
11597 @item @code{VALUES(10)} @tab Last modification time
11598 @item @code{VALUES(11)} @tab Last file status change time
11599 @item @code{VALUES(12)} @tab Preferred I/O block size (-1 if not available)
11600 @item @code{VALUES(13)} @tab Number of blocks allocated (-1 if not available)
11603 Not all these elements are relevant on all systems.
11604 If an element is not relevant, it is returned as 0.
11606 This intrinsic is provided in both subroutine and function forms; however,
11607 only one form can be used in any given program unit.
11609 @item @emph{Standard}:
11612 @item @emph{Class}:
11613 Subroutine, function
11615 @item @emph{Syntax}:
11616 @multitable @columnfractions .80
11617 @item @code{CALL STAT(NAME, VALUES [, STATUS])}
11618 @item @code{STATUS = STAT(NAME, VALUES)}
11621 @item @emph{Arguments}:
11622 @multitable @columnfractions .15 .70
11623 @item @var{NAME} @tab The type shall be @code{CHARACTER}, of the
11624 default kind and a valid path within the file system.
11625 @item @var{VALUES} @tab The type shall be @code{INTEGER(4), DIMENSION(13)}.
11626 @item @var{STATUS} @tab (Optional) status flag of type @code{INTEGER(4)}. Returns 0
11627 on success and a system specific error code otherwise.
11630 @item @emph{Example}:
11633 INTEGER, DIMENSION(13) :: buff
11636 CALL STAT("/etc/passwd", buff, status)
11638 IF (status == 0) THEN
11639 WRITE (*, FMT="('Device ID:', T30, I19)") buff(1)
11640 WRITE (*, FMT="('Inode number:', T30, I19)") buff(2)
11641 WRITE (*, FMT="('File mode (octal):', T30, O19)") buff(3)
11642 WRITE (*, FMT="('Number of links:', T30, I19)") buff(4)
11643 WRITE (*, FMT="('Owner''s uid:', T30, I19)") buff(5)
11644 WRITE (*, FMT="('Owner''s gid:', T30, I19)") buff(6)
11645 WRITE (*, FMT="('Device where located:', T30, I19)") buff(7)
11646 WRITE (*, FMT="('File size:', T30, I19)") buff(8)
11647 WRITE (*, FMT="('Last access time:', T30, A19)") CTIME(buff(9))
11648 WRITE (*, FMT="('Last modification time', T30, A19)") CTIME(buff(10))
11649 WRITE (*, FMT="('Last status change time:', T30, A19)") CTIME(buff(11))
11650 WRITE (*, FMT="('Preferred block size:', T30, I19)") buff(12)
11651 WRITE (*, FMT="('No. of blocks allocated:', T30, I19)") buff(13)
11656 @item @emph{See also}:
11657 To stat an open file: @ref{FSTAT}, to stat a link: @ref{LSTAT}
11663 @section @code{STORAGE_SIZE} --- Storage size in bits
11664 @fnindex STORAGE_SIZE
11665 @cindex storage size
11668 @item @emph{Description}:
11669 Returns the storage size of argument @var{A} in bits.
11670 @item @emph{Standard}:
11671 Fortran 2008 and later
11672 @item @emph{Class}:
11674 @item @emph{Syntax}:
11675 @code{RESULT = STORAGE_SIZE(A [, KIND])}
11677 @item @emph{Arguments}:
11678 @multitable @columnfractions .15 .70
11679 @item @var{A} @tab Shall be a scalar or array of any type.
11680 @item @var{KIND} @tab (Optional) shall be a scalar integer constant expression.
11683 @item @emph{Return Value}:
11684 The result is a scalar integer with the kind type parameter specified by KIND (or default integer type if KIND is missing). The result value is the size expressed in bits for an element of an array that
11685 has the dynamic type and type parameters of A.
11687 @item @emph{See also}:
11688 @ref{C_SIZEOF}, @ref{SIZEOF}
11694 @section @code{SUM} --- Sum of array elements
11697 @cindex array, add elements
11698 @cindex array, conditionally add elements
11699 @cindex sum array elements
11702 @item @emph{Description}:
11703 Adds the elements of @var{ARRAY} along dimension @var{DIM} if
11704 the corresponding element in @var{MASK} is @code{TRUE}.
11706 @item @emph{Standard}:
11707 Fortran 95 and later
11709 @item @emph{Class}:
11710 Transformational function
11712 @item @emph{Syntax}:
11713 @multitable @columnfractions .80
11714 @item @code{RESULT = SUM(ARRAY[, MASK])}
11715 @item @code{RESULT = SUM(ARRAY, DIM[, MASK])}
11718 @item @emph{Arguments}:
11719 @multitable @columnfractions .15 .70
11720 @item @var{ARRAY} @tab Shall be an array of type @code{INTEGER},
11721 @code{REAL} or @code{COMPLEX}.
11722 @item @var{DIM} @tab (Optional) shall be a scalar of type
11723 @code{INTEGER} with a value in the range from 1 to n, where n
11724 equals the rank of @var{ARRAY}.
11725 @item @var{MASK} @tab (Optional) shall be of type @code{LOGICAL}
11726 and either be a scalar or an array of the same shape as @var{ARRAY}.
11729 @item @emph{Return value}:
11730 The result is of the same type as @var{ARRAY}.
11732 If @var{DIM} is absent, a scalar with the sum of all elements in @var{ARRAY}
11733 is returned. Otherwise, an array of rank n-1, where n equals the rank of
11734 @var{ARRAY}, and a shape similar to that of @var{ARRAY} with dimension @var{DIM}
11735 dropped is returned.
11737 @item @emph{Example}:
11740 INTEGER :: x(5) = (/ 1, 2, 3, 4 ,5 /)
11741 print *, SUM(x) ! all elements, sum = 15
11742 print *, SUM(x, MASK=MOD(x, 2)==1) ! odd elements, sum = 9
11746 @item @emph{See also}:
11753 @section @code{SYMLNK} --- Create a symbolic link
11755 @cindex file system, create link
11756 @cindex file system, soft link
11759 @item @emph{Description}:
11760 Makes a symbolic link from file @var{PATH1} to @var{PATH2}. A null
11761 character (@code{CHAR(0)}) can be used to mark the end of the names in
11762 @var{PATH1} and @var{PATH2}; otherwise, trailing blanks in the file
11763 names are ignored. If the @var{STATUS} argument is supplied, it
11764 contains 0 on success or a nonzero error code upon return; see
11765 @code{symlink(2)}. If the system does not supply @code{symlink(2)},
11766 @code{ENOSYS} is returned.
11768 This intrinsic is provided in both subroutine and function forms;
11769 however, only one form can be used in any given program unit.
11771 @item @emph{Standard}:
11774 @item @emph{Class}:
11775 Subroutine, function
11777 @item @emph{Syntax}:
11778 @multitable @columnfractions .80
11779 @item @code{CALL SYMLNK(PATH1, PATH2 [, STATUS])}
11780 @item @code{STATUS = SYMLNK(PATH1, PATH2)}
11783 @item @emph{Arguments}:
11784 @multitable @columnfractions .15 .70
11785 @item @var{PATH1} @tab Shall be of default @code{CHARACTER} type.
11786 @item @var{PATH2} @tab Shall be of default @code{CHARACTER} type.
11787 @item @var{STATUS} @tab (Optional) Shall be of default @code{INTEGER} type.
11790 @item @emph{See also}:
11791 @ref{LINK}, @ref{UNLINK}
11798 @section @code{SYSTEM} --- Execute a shell command
11800 @cindex system, system call
11803 @item @emph{Description}:
11804 Passes the command @var{COMMAND} to a shell (see @code{system(3)}). If
11805 argument @var{STATUS} is present, it contains the value returned by
11806 @code{system(3)}, which is presumably 0 if the shell command succeeded.
11807 Note that which shell is used to invoke the command is system-dependent
11808 and environment-dependent.
11810 This intrinsic is provided in both subroutine and function forms;
11811 however, only one form can be used in any given program unit.
11813 Note that the @code{system} function need not be thread-safe. It is
11814 the responsibility of the user to ensure that @code{system} is not
11815 called concurrently.
11817 @item @emph{Standard}:
11820 @item @emph{Class}:
11821 Subroutine, function
11823 @item @emph{Syntax}:
11824 @multitable @columnfractions .80
11825 @item @code{CALL SYSTEM(COMMAND [, STATUS])}
11826 @item @code{STATUS = SYSTEM(COMMAND)}
11829 @item @emph{Arguments}:
11830 @multitable @columnfractions .15 .70
11831 @item @var{COMMAND} @tab Shall be of default @code{CHARACTER} type.
11832 @item @var{STATUS} @tab (Optional) Shall be of default @code{INTEGER} type.
11835 @item @emph{See also}:
11836 @ref{EXECUTE_COMMAND_LINE}, which is part of the Fortran 2008 standard
11837 and should considered in new code for future portability.
11843 @section @code{SYSTEM_CLOCK} --- Time function
11844 @fnindex SYSTEM_CLOCK
11845 @cindex time, clock ticks
11846 @cindex clock ticks
11849 @item @emph{Description}:
11850 Determines the @var{COUNT} of a processor clock since an unspecified
11851 time in the past modulo @var{COUNT_MAX}, @var{COUNT_RATE} determines
11852 the number of clock ticks per second. If the platform supports a high
11853 resolution monotonic clock, that clock is used and can provide up to
11854 nanosecond resolution. If a high resolution monotonic clock is not
11855 available, the implementation falls back to a potentially lower
11856 resolution realtime clock.
11858 @var{COUNT_RATE} and @var{COUNT_MAX} vary depending on the kind of the
11859 arguments. For @var{kind=8} arguments, @var{COUNT} represents
11860 nanoseconds, and for @var{kind=4} arguments, @var{COUNT} represents
11861 milliseconds. Other than the kind dependency, @var{COUNT_RATE} and
11862 @var{COUNT_MAX} are constant, however the particular values are
11863 specific to @command{gfortran}.
11865 If there is no clock, @var{COUNT} is set to @code{-HUGE(COUNT)}, and
11866 @var{COUNT_RATE} and @var{COUNT_MAX} are set to zero.
11868 When running on a platform using the GNU C library (glibc), or a
11869 derivative thereof, the high resolution monotonic clock is available
11870 only when linking with the @var{rt} library. This can be done
11871 explicitly by adding the @code{-lrt} flag when linking the
11872 application, but is also done implicitly when using OpenMP.
11874 @item @emph{Standard}:
11875 Fortran 95 and later
11877 @item @emph{Class}:
11880 @item @emph{Syntax}:
11881 @code{CALL SYSTEM_CLOCK([COUNT, COUNT_RATE, COUNT_MAX])}
11883 @item @emph{Arguments}:
11884 @multitable @columnfractions .15 .70
11885 @item @var{COUNT} @tab (Optional) shall be a scalar of type
11886 @code{INTEGER} with @code{INTENT(OUT)}.
11887 @item @var{COUNT_RATE} @tab (Optional) shall be a scalar of type
11888 @code{INTEGER} with @code{INTENT(OUT)}.
11889 @item @var{COUNT_MAX} @tab (Optional) shall be a scalar of type
11890 @code{INTEGER} with @code{INTENT(OUT)}.
11893 @item @emph{Example}:
11895 PROGRAM test_system_clock
11896 INTEGER :: count, count_rate, count_max
11897 CALL SYSTEM_CLOCK(count, count_rate, count_max)
11898 WRITE(*,*) count, count_rate, count_max
11902 @item @emph{See also}:
11903 @ref{DATE_AND_TIME}, @ref{CPU_TIME}
11909 @section @code{TAN} --- Tangent function
11912 @cindex trigonometric function, tangent
11916 @item @emph{Description}:
11917 @code{TAN(X)} computes the tangent of @var{X}.
11919 @item @emph{Standard}:
11920 Fortran 77 and later, for a complex argument Fortran 2008 or later
11922 @item @emph{Class}:
11925 @item @emph{Syntax}:
11926 @code{RESULT = TAN(X)}
11928 @item @emph{Arguments}:
11929 @multitable @columnfractions .15 .70
11930 @item @var{X} @tab The type shall be @code{REAL} or @code{COMPLEX}.
11933 @item @emph{Return value}:
11934 The return value has same type and kind as @var{X}.
11936 @item @emph{Example}:
11939 real(8) :: x = 0.165_8
11941 end program test_tan
11944 @item @emph{Specific names}:
11945 @multitable @columnfractions .20 .20 .20 .25
11946 @item Name @tab Argument @tab Return type @tab Standard
11947 @item @code{TAN(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab Fortran 95 and later
11948 @item @code{DTAN(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab Fortran 95 and later
11951 @item @emph{See also}:
11958 @section @code{TANH} --- Hyperbolic tangent function
11961 @cindex hyperbolic tangent
11962 @cindex hyperbolic function, tangent
11963 @cindex tangent, hyperbolic
11966 @item @emph{Description}:
11967 @code{TANH(X)} computes the hyperbolic tangent of @var{X}.
11969 @item @emph{Standard}:
11970 Fortran 77 and later, for a complex argument Fortran 2008 or later
11972 @item @emph{Class}:
11975 @item @emph{Syntax}:
11978 @item @emph{Arguments}:
11979 @multitable @columnfractions .15 .70
11980 @item @var{X} @tab The type shall be @code{REAL} or @code{COMPLEX}.
11983 @item @emph{Return value}:
11984 The return value has same type and kind as @var{X}. If @var{X} is
11985 complex, the imaginary part of the result is in radians. If @var{X}
11986 is @code{REAL}, the return value lies in the range
11987 @math{ - 1 \leq tanh(x) \leq 1 }.
11989 @item @emph{Example}:
11992 real(8) :: x = 2.1_8
11994 end program test_tanh
11997 @item @emph{Specific names}:
11998 @multitable @columnfractions .20 .20 .20 .25
11999 @item Name @tab Argument @tab Return type @tab Standard
12000 @item @code{TANH(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab Fortran 95 and later
12001 @item @code{DTANH(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab Fortran 95 and later
12004 @item @emph{See also}:
12011 @section @code{THIS_IMAGE} --- Function that returns the cosubscript index of this image
12012 @fnindex THIS_IMAGE
12013 @cindex coarray, @code{THIS_IMAGE}
12014 @cindex images, index of this image
12017 @item @emph{Description}:
12018 Returns the cosubscript for this image.
12020 @item @emph{Standard}:
12021 Fortran 2008 and later
12023 @item @emph{Class}:
12024 Transformational function
12026 @item @emph{Syntax}:
12027 @multitable @columnfractions .80
12028 @item @code{RESULT = THIS_IMAGE()}
12029 @item @code{RESULT = THIS_IMAGE(COARRAY [, DIM])}
12032 @item @emph{Arguments}:
12033 @multitable @columnfractions .15 .70
12034 @item @var{COARRAY} @tab Coarray of any type (optional; if @var{DIM}
12035 present, required).
12036 @item @var{DIM} @tab default integer scalar (optional). If present,
12037 @var{DIM} shall be between one and the corank of @var{COARRAY}.
12041 @item @emph{Return value}:
12042 Default integer. If @var{COARRAY} is not present, it is scalar and its value
12043 is the index of the invoking image. Otherwise, if @var{DIM} is not present,
12044 a rank-1 array with corank elements is returned, containing the cosubscripts
12045 for @var{COARRAY} specifying the invoking image. If @var{DIM} is present,
12046 a scalar is returned, with the value of the @var{DIM} element of
12047 @code{THIS_IMAGE(COARRAY)}.
12049 @item @emph{Example}:
12051 INTEGER :: value[*]
12053 value = THIS_IMAGE()
12055 IF (THIS_IMAGE() == 1) THEN
12056 DO i = 1, NUM_IMAGES()
12057 WRITE(*,'(2(a,i0))') 'value[', i, '] is ', value[i]
12062 @item @emph{See also}:
12063 @ref{NUM_IMAGES}, @ref{IMAGE_INDEX}
12069 @section @code{TIME} --- Time function
12071 @cindex time, current
12072 @cindex current time
12075 @item @emph{Description}:
12076 Returns the current time encoded as an integer (in the manner of the
12077 UNIX function @code{time(3)}). This value is suitable for passing to
12078 @code{CTIME}, @code{GMTIME}, and @code{LTIME}.
12080 This intrinsic is not fully portable, such as to systems with 32-bit
12081 @code{INTEGER} types but supporting times wider than 32 bits. Therefore,
12082 the values returned by this intrinsic might be, or become, negative, or
12083 numerically less than previous values, during a single run of the
12086 See @ref{TIME8}, for information on a similar intrinsic that might be
12087 portable to more GNU Fortran implementations, though to fewer Fortran
12090 @item @emph{Standard}:
12093 @item @emph{Class}:
12096 @item @emph{Syntax}:
12097 @code{RESULT = TIME()}
12099 @item @emph{Return value}:
12100 The return value is a scalar of type @code{INTEGER(4)}.
12102 @item @emph{See also}:
12103 @ref{CTIME}, @ref{GMTIME}, @ref{LTIME}, @ref{MCLOCK}, @ref{TIME8}
12110 @section @code{TIME8} --- Time function (64-bit)
12112 @cindex time, current
12113 @cindex current time
12116 @item @emph{Description}:
12117 Returns the current time encoded as an integer (in the manner of the
12118 UNIX function @code{time(3)}). This value is suitable for passing to
12119 @code{CTIME}, @code{GMTIME}, and @code{LTIME}.
12121 @emph{Warning:} this intrinsic does not increase the range of the timing
12122 values over that returned by @code{time(3)}. On a system with a 32-bit
12123 @code{time(3)}, @code{TIME8} will return a 32-bit value, even though
12124 it is converted to a 64-bit @code{INTEGER(8)} value. That means
12125 overflows of the 32-bit value can still occur. Therefore, the values
12126 returned by this intrinsic might be or become negative or numerically
12127 less than previous values during a single run of the compiled program.
12129 @item @emph{Standard}:
12132 @item @emph{Class}:
12135 @item @emph{Syntax}:
12136 @code{RESULT = TIME8()}
12138 @item @emph{Return value}:
12139 The return value is a scalar of type @code{INTEGER(8)}.
12141 @item @emph{See also}:
12142 @ref{CTIME}, @ref{GMTIME}, @ref{LTIME}, @ref{MCLOCK8}, @ref{TIME}
12149 @section @code{TINY} --- Smallest positive number of a real kind
12151 @cindex limits, smallest number
12152 @cindex model representation, smallest number
12155 @item @emph{Description}:
12156 @code{TINY(X)} returns the smallest positive (non zero) number
12157 in the model of the type of @code{X}.
12159 @item @emph{Standard}:
12160 Fortran 95 and later
12162 @item @emph{Class}:
12165 @item @emph{Syntax}:
12166 @code{RESULT = TINY(X)}
12168 @item @emph{Arguments}:
12169 @multitable @columnfractions .15 .70
12170 @item @var{X} @tab Shall be of type @code{REAL}.
12173 @item @emph{Return value}:
12174 The return value is of the same type and kind as @var{X}
12176 @item @emph{Example}:
12177 See @code{HUGE} for an example.
12183 @section @code{TRAILZ} --- Number of trailing zero bits of an integer
12188 @item @emph{Description}:
12189 @code{TRAILZ} returns the number of trailing zero bits of an integer.
12191 @item @emph{Standard}:
12192 Fortran 2008 and later
12194 @item @emph{Class}:
12197 @item @emph{Syntax}:
12198 @code{RESULT = TRAILZ(I)}
12200 @item @emph{Arguments}:
12201 @multitable @columnfractions .15 .70
12202 @item @var{I} @tab Shall be of type @code{INTEGER}.
12205 @item @emph{Return value}:
12206 The type of the return value is the default @code{INTEGER}.
12207 If all the bits of @code{I} are zero, the result value is @code{BIT_SIZE(I)}.
12209 @item @emph{Example}:
12211 PROGRAM test_trailz
12212 WRITE (*,*) TRAILZ(8) ! prints 3
12216 @item @emph{See also}:
12217 @ref{BIT_SIZE}, @ref{LEADZ}, @ref{POPPAR}, @ref{POPCNT}
12223 @section @code{TRANSFER} --- Transfer bit patterns
12229 @item @emph{Description}:
12230 Interprets the bitwise representation of @var{SOURCE} in memory as if it
12231 is the representation of a variable or array of the same type and type
12232 parameters as @var{MOLD}.
12234 This is approximately equivalent to the C concept of @emph{casting} one
12237 @item @emph{Standard}:
12238 Fortran 95 and later
12240 @item @emph{Class}:
12241 Transformational function
12243 @item @emph{Syntax}:
12244 @code{RESULT = TRANSFER(SOURCE, MOLD[, SIZE])}
12246 @item @emph{Arguments}:
12247 @multitable @columnfractions .15 .70
12248 @item @var{SOURCE} @tab Shall be a scalar or an array of any type.
12249 @item @var{MOLD} @tab Shall be a scalar or an array of any type.
12250 @item @var{SIZE} @tab (Optional) shall be a scalar of type
12254 @item @emph{Return value}:
12255 The result has the same type as @var{MOLD}, with the bit level
12256 representation of @var{SOURCE}. If @var{SIZE} is present, the result is
12257 a one-dimensional array of length @var{SIZE}. If @var{SIZE} is absent
12258 but @var{MOLD} is an array (of any size or shape), the result is a one-
12259 dimensional array of the minimum length needed to contain the entirety
12260 of the bitwise representation of @var{SOURCE}. If @var{SIZE} is absent
12261 and @var{MOLD} is a scalar, the result is a scalar.
12263 If the bitwise representation of the result is longer than that of
12264 @var{SOURCE}, then the leading bits of the result correspond to those of
12265 @var{SOURCE} and any trailing bits are filled arbitrarily.
12267 When the resulting bit representation does not correspond to a valid
12268 representation of a variable of the same type as @var{MOLD}, the results
12269 are undefined, and subsequent operations on the result cannot be
12270 guaranteed to produce sensible behavior. For example, it is possible to
12271 create @code{LOGICAL} variables for which @code{@var{VAR}} and
12272 @code{.NOT.@var{VAR}} both appear to be true.
12274 @item @emph{Example}:
12276 PROGRAM test_transfer
12277 integer :: x = 2143289344
12278 print *, transfer(x, 1.0) ! prints "NaN" on i686
12286 @section @code{TRANSPOSE} --- Transpose an array of rank two
12288 @cindex array, transpose
12289 @cindex matrix, transpose
12293 @item @emph{Description}:
12294 Transpose an array of rank two. Element (i, j) of the result has the value
12295 @code{MATRIX(j, i)}, for all i, j.
12297 @item @emph{Standard}:
12298 Fortran 95 and later
12300 @item @emph{Class}:
12301 Transformational function
12303 @item @emph{Syntax}:
12304 @code{RESULT = TRANSPOSE(MATRIX)}
12306 @item @emph{Arguments}:
12307 @multitable @columnfractions .15 .70
12308 @item @var{MATRIX} @tab Shall be an array of any type and have a rank of two.
12311 @item @emph{Return value}:
12312 The result has the same type as @var{MATRIX}, and has shape
12313 @code{(/ m, n /)} if @var{MATRIX} has shape @code{(/ n, m /)}.
12319 @section @code{TRIM} --- Remove trailing blank characters of a string
12321 @cindex string, remove trailing whitespace
12324 @item @emph{Description}:
12325 Removes trailing blank characters of a string.
12327 @item @emph{Standard}:
12328 Fortran 95 and later
12330 @item @emph{Class}:
12331 Transformational function
12333 @item @emph{Syntax}:
12334 @code{RESULT = TRIM(STRING)}
12336 @item @emph{Arguments}:
12337 @multitable @columnfractions .15 .70
12338 @item @var{STRING} @tab Shall be a scalar of type @code{CHARACTER}.
12341 @item @emph{Return value}:
12342 A scalar of type @code{CHARACTER} which length is that of @var{STRING}
12343 less the number of trailing blanks.
12345 @item @emph{Example}:
12348 CHARACTER(len=10), PARAMETER :: s = "GFORTRAN "
12349 WRITE(*,*) LEN(s), LEN(TRIM(s)) ! "10 8", with/without trailing blanks
12353 @item @emph{See also}:
12354 @ref{ADJUSTL}, @ref{ADJUSTR}
12360 @section @code{TTYNAM} --- Get the name of a terminal device.
12362 @cindex system, terminal
12365 @item @emph{Description}:
12366 Get the name of a terminal device. For more information,
12367 see @code{ttyname(3)}.
12369 This intrinsic is provided in both subroutine and function forms;
12370 however, only one form can be used in any given program unit.
12372 @item @emph{Standard}:
12375 @item @emph{Class}:
12376 Subroutine, function
12378 @item @emph{Syntax}:
12379 @multitable @columnfractions .80
12380 @item @code{CALL TTYNAM(UNIT, NAME)}
12381 @item @code{NAME = TTYNAM(UNIT)}
12384 @item @emph{Arguments}:
12385 @multitable @columnfractions .15 .70
12386 @item @var{UNIT} @tab Shall be a scalar @code{INTEGER}.
12387 @item @var{NAME} @tab Shall be of type @code{CHARACTER}.
12390 @item @emph{Example}:
12392 PROGRAM test_ttynam
12395 IF (isatty(unit=unit)) write(*,*) ttynam(unit)
12400 @item @emph{See also}:
12407 @section @code{UBOUND} --- Upper dimension bounds of an array
12409 @cindex array, upper bound
12412 @item @emph{Description}:
12413 Returns the upper bounds of an array, or a single upper bound
12414 along the @var{DIM} dimension.
12415 @item @emph{Standard}:
12416 Fortran 95 and later, with @var{KIND} argument Fortran 2003 and later
12418 @item @emph{Class}:
12421 @item @emph{Syntax}:
12422 @code{RESULT = UBOUND(ARRAY [, DIM [, KIND]])}
12424 @item @emph{Arguments}:
12425 @multitable @columnfractions .15 .70
12426 @item @var{ARRAY} @tab Shall be an array, of any type.
12427 @item @var{DIM} @tab (Optional) Shall be a scalar @code{INTEGER}.
12428 @item @var{KIND}@tab (Optional) An @code{INTEGER} initialization
12429 expression indicating the kind parameter of the result.
12432 @item @emph{Return value}:
12433 The return value is of type @code{INTEGER} and of kind @var{KIND}. If
12434 @var{KIND} is absent, the return value is of default integer kind.
12435 If @var{DIM} is absent, the result is an array of the upper bounds of
12436 @var{ARRAY}. If @var{DIM} is present, the result is a scalar
12437 corresponding to the upper bound of the array along that dimension. If
12438 @var{ARRAY} is an expression rather than a whole array or array
12439 structure component, or if it has a zero extent along the relevant
12440 dimension, the upper bound is taken to be the number of elements along
12441 the relevant dimension.
12443 @item @emph{See also}:
12444 @ref{LBOUND}, @ref{LCOBOUND}
12450 @section @code{UCOBOUND} --- Upper codimension bounds of an array
12452 @cindex coarray, upper bound
12455 @item @emph{Description}:
12456 Returns the upper cobounds of a coarray, or a single upper cobound
12457 along the @var{DIM} codimension.
12458 @item @emph{Standard}:
12459 Fortran 2008 and later
12461 @item @emph{Class}:
12464 @item @emph{Syntax}:
12465 @code{RESULT = UCOBOUND(COARRAY [, DIM [, KIND]])}
12467 @item @emph{Arguments}:
12468 @multitable @columnfractions .15 .70
12469 @item @var{ARRAY} @tab Shall be an coarray, of any type.
12470 @item @var{DIM} @tab (Optional) Shall be a scalar @code{INTEGER}.
12471 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
12472 expression indicating the kind parameter of the result.
12475 @item @emph{Return value}:
12476 The return value is of type @code{INTEGER} and of kind @var{KIND}. If
12477 @var{KIND} is absent, the return value is of default integer kind.
12478 If @var{DIM} is absent, the result is an array of the lower cobounds of
12479 @var{COARRAY}. If @var{DIM} is present, the result is a scalar
12480 corresponding to the lower cobound of the array along that codimension.
12482 @item @emph{See also}:
12483 @ref{LCOBOUND}, @ref{LBOUND}
12489 @section @code{UMASK} --- Set the file creation mask
12491 @cindex file system, file creation mask
12494 @item @emph{Description}:
12495 Sets the file creation mask to @var{MASK}. If called as a function, it
12496 returns the old value. If called as a subroutine and argument @var{OLD}
12497 if it is supplied, it is set to the old value. See @code{umask(2)}.
12499 @item @emph{Standard}:
12502 @item @emph{Class}:
12503 Subroutine, function
12505 @item @emph{Syntax}:
12506 @multitable @columnfractions .80
12507 @item @code{CALL UMASK(MASK [, OLD])}
12508 @item @code{OLD = UMASK(MASK)}
12511 @item @emph{Arguments}:
12512 @multitable @columnfractions .15 .70
12513 @item @var{MASK} @tab Shall be a scalar of type @code{INTEGER}.
12514 @item @var{OLD} @tab (Optional) Shall be a scalar of type
12523 @section @code{UNLINK} --- Remove a file from the file system
12525 @cindex file system, remove file
12528 @item @emph{Description}:
12529 Unlinks the file @var{PATH}. A null character (@code{CHAR(0)}) can be
12530 used to mark the end of the name in @var{PATH}; otherwise, trailing
12531 blanks in the file name are ignored. If the @var{STATUS} argument is
12532 supplied, it contains 0 on success or a nonzero error code upon return;
12533 see @code{unlink(2)}.
12535 This intrinsic is provided in both subroutine and function forms;
12536 however, only one form can be used in any given program unit.
12538 @item @emph{Standard}:
12541 @item @emph{Class}:
12542 Subroutine, function
12544 @item @emph{Syntax}:
12545 @multitable @columnfractions .80
12546 @item @code{CALL UNLINK(PATH [, STATUS])}
12547 @item @code{STATUS = UNLINK(PATH)}
12550 @item @emph{Arguments}:
12551 @multitable @columnfractions .15 .70
12552 @item @var{PATH} @tab Shall be of default @code{CHARACTER} type.
12553 @item @var{STATUS} @tab (Optional) Shall be of default @code{INTEGER} type.
12556 @item @emph{See also}:
12557 @ref{LINK}, @ref{SYMLNK}
12563 @section @code{UNPACK} --- Unpack an array of rank one into an array
12565 @cindex array, unpacking
12566 @cindex array, increase dimension
12567 @cindex array, scatter elements
12570 @item @emph{Description}:
12571 Store the elements of @var{VECTOR} in an array of higher rank.
12573 @item @emph{Standard}:
12574 Fortran 95 and later
12576 @item @emph{Class}:
12577 Transformational function
12579 @item @emph{Syntax}:
12580 @code{RESULT = UNPACK(VECTOR, MASK, FIELD)}
12582 @item @emph{Arguments}:
12583 @multitable @columnfractions .15 .70
12584 @item @var{VECTOR} @tab Shall be an array of any type and rank one. It
12585 shall have at least as many elements as @var{MASK} has @code{TRUE} values.
12586 @item @var{MASK} @tab Shall be an array of type @code{LOGICAL}.
12587 @item @var{FIELD} @tab Shall be of the same type as @var{VECTOR} and have
12588 the same shape as @var{MASK}.
12591 @item @emph{Return value}:
12592 The resulting array corresponds to @var{FIELD} with @code{TRUE} elements
12593 of @var{MASK} replaced by values from @var{VECTOR} in array element order.
12595 @item @emph{Example}:
12597 PROGRAM test_unpack
12598 integer :: vector(2) = (/1,1/)
12599 logical :: mask(4) = (/ .TRUE., .FALSE., .FALSE., .TRUE. /)
12600 integer :: field(2,2) = 0, unity(2,2)
12602 ! result: unity matrix
12603 unity = unpack(vector, reshape(mask, (/2,2/)), field)
12607 @item @emph{See also}:
12608 @ref{PACK}, @ref{SPREAD}
12614 @section @code{VERIFY} --- Scan a string for characters not a given set
12616 @cindex string, find missing set
12619 @item @emph{Description}:
12620 Verifies that all the characters in @var{STRING} belong to the set of
12621 characters in @var{SET}.
12623 If @var{BACK} is either absent or equals @code{FALSE}, this function
12624 returns the position of the leftmost character of @var{STRING} that is
12625 not in @var{SET}. If @var{BACK} equals @code{TRUE}, the rightmost
12626 position is returned. If all characters of @var{STRING} are found in
12627 @var{SET}, the result is zero.
12629 @item @emph{Standard}:
12630 Fortran 95 and later, with @var{KIND} argument Fortran 2003 and later
12632 @item @emph{Class}:
12635 @item @emph{Syntax}:
12636 @code{RESULT = VERIFY(STRING, SET[, BACK [, KIND]])}
12638 @item @emph{Arguments}:
12639 @multitable @columnfractions .15 .70
12640 @item @var{STRING} @tab Shall be of type @code{CHARACTER}.
12641 @item @var{SET} @tab Shall be of type @code{CHARACTER}.
12642 @item @var{BACK} @tab (Optional) shall be of type @code{LOGICAL}.
12643 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
12644 expression indicating the kind parameter of the result.
12647 @item @emph{Return value}:
12648 The return value is of type @code{INTEGER} and of kind @var{KIND}. If
12649 @var{KIND} is absent, the return value is of default integer kind.
12651 @item @emph{Example}:
12653 PROGRAM test_verify
12654 WRITE(*,*) VERIFY("FORTRAN", "AO") ! 1, found 'F'
12655 WRITE(*,*) VERIFY("FORTRAN", "FOO") ! 3, found 'R'
12656 WRITE(*,*) VERIFY("FORTRAN", "C++") ! 1, found 'F'
12657 WRITE(*,*) VERIFY("FORTRAN", "C++", .TRUE.) ! 7, found 'N'
12658 WRITE(*,*) VERIFY("FORTRAN", "FORTRAN") ! 0' found none
12662 @item @emph{See also}:
12663 @ref{SCAN}, @ref{INDEX intrinsic}
12669 @section @code{XOR} --- Bitwise logical exclusive OR
12671 @cindex bitwise logical exclusive or
12672 @cindex logical exclusive or, bitwise
12675 @item @emph{Description}:
12676 Bitwise logical exclusive or.
12678 This intrinsic routine is provided for backwards compatibility with
12679 GNU Fortran 77. For integer arguments, programmers should consider
12680 the use of the @ref{IEOR} intrinsic and for logical arguments the
12681 @code{.NEQV.} operator, which are both defined by the Fortran standard.
12683 @item @emph{Standard}:
12686 @item @emph{Class}:
12689 @item @emph{Syntax}:
12690 @code{RESULT = XOR(I, J)}
12692 @item @emph{Arguments}:
12693 @multitable @columnfractions .15 .70
12694 @item @var{I} @tab The type shall be either a scalar @code{INTEGER}
12695 type or a scalar @code{LOGICAL} type.
12696 @item @var{J} @tab The type shall be the same as the type of @var{I}.
12699 @item @emph{Return value}:
12700 The return type is either a scalar @code{INTEGER} or a scalar
12701 @code{LOGICAL}. If the kind type parameters differ, then the
12702 smaller kind type is implicitly converted to larger kind, and the
12703 return has the larger kind.
12705 @item @emph{Example}:
12708 LOGICAL :: T = .TRUE., F = .FALSE.
12710 DATA a / Z'F' /, b / Z'3' /
12712 WRITE (*,*) XOR(T, T), XOR(T, F), XOR(F, T), XOR(F, F)
12713 WRITE (*,*) XOR(a, b)
12717 @item @emph{See also}:
12718 Fortran 95 elemental function: @ref{IEOR}
12723 @node Intrinsic Modules
12724 @chapter Intrinsic Modules
12725 @cindex intrinsic Modules
12728 * ISO_FORTRAN_ENV::
12730 * OpenMP Modules OMP_LIB and OMP_LIB_KINDS::
12733 @node ISO_FORTRAN_ENV
12734 @section @code{ISO_FORTRAN_ENV}
12736 @item @emph{Standard}:
12737 Fortran 2003 and later, except when otherwise noted
12740 The @code{ISO_FORTRAN_ENV} module provides the following scalar default-integer
12744 @item @code{ATOMIC_INT_KIND}:
12745 Default-kind integer constant to be used as kind parameter when defining
12746 integer variables used in atomic operations. (Fortran 2008 or later.)
12748 @item @code{ATOMIC_LOGICAL_KIND}:
12749 Default-kind integer constant to be used as kind parameter when defining
12750 logical variables used in atomic operations. (Fortran 2008 or later.)
12752 @item @code{CHARACTER_KINDS}:
12753 Default-kind integer constant array of rank one containing the supported kind
12754 parameters of the @code{CHARACTER} type. (Fortran 2008 or later.)
12756 @item @code{CHARACTER_STORAGE_SIZE}:
12757 Size in bits of the character storage unit.
12759 @item @code{ERROR_UNIT}:
12760 Identifies the preconnected unit used for error reporting.
12762 @item @code{FILE_STORAGE_SIZE}:
12763 Size in bits of the file-storage unit.
12765 @item @code{INPUT_UNIT}:
12766 Identifies the preconnected unit identified by the asterisk
12767 (@code{*}) in @code{READ} statement.
12769 @item @code{INT8}, @code{INT16}, @code{INT32}, @code{INT64}:
12770 Kind type parameters to specify an INTEGER type with a storage
12771 size of 16, 32, and 64 bits. It is negative if a target platform
12772 does not support the particular kind. (Fortran 2008 or later.)
12774 @item @code{INTEGER_KINDS}:
12775 Default-kind integer constant array of rank one containing the supported kind
12776 parameters of the @code{INTEGER} type. (Fortran 2008 or later.)
12778 @item @code{IOSTAT_END}:
12779 The value assigned to the variable passed to the @code{IOSTAT=} specifier of
12780 an input/output statement if an end-of-file condition occurred.
12782 @item @code{IOSTAT_EOR}:
12783 The value assigned to the variable passed to the @code{IOSTAT=} specifier of
12784 an input/output statement if an end-of-record condition occurred.
12786 @item @code{IOSTAT_INQUIRE_INTERNAL_UNIT}:
12787 Scalar default-integer constant, used by @code{INQUIRE} for the
12788 @code{IOSTAT=} specifier to denote an that a unit number identifies an
12789 internal unit. (Fortran 2008 or later.)
12791 @item @code{NUMERIC_STORAGE_SIZE}:
12792 The size in bits of the numeric storage unit.
12794 @item @code{LOGICAL_KINDS}:
12795 Default-kind integer constant array of rank one containing the supported kind
12796 parameters of the @code{LOGICAL} type. (Fortran 2008 or later.)
12798 @item @code{OUTPUT_UNIT}:
12799 Identifies the preconnected unit identified by the asterisk
12800 (@code{*}) in @code{WRITE} statement.
12802 @item @code{REAL32}, @code{REAL64}, @code{REAL128}:
12803 Kind type parameters to specify a REAL type with a storage
12804 size of 32, 64, and 128 bits. It is negative if a target platform
12805 does not support the particular kind. (Fortran 2008 or later.)
12807 @item @code{REAL_KINDS}:
12808 Default-kind integer constant array of rank one containing the supported kind
12809 parameters of the @code{REAL} type. (Fortran 2008 or later.)
12811 @item @code{STAT_LOCKED}:
12812 Scalar default-integer constant used as STAT= return value by @code{LOCK} to
12813 denote that the lock variable is locked by the executing image. (Fortran 2008
12816 @item @code{STAT_LOCKED_OTHER_IMAGE}:
12817 Scalar default-integer constant used as STAT= return value by @code{UNLOCK} to
12818 denote that the lock variable is locked by another image. (Fortran 2008 or
12821 @item @code{STAT_STOPPED_IMAGE}:
12822 Positive, scalar default-integer constant used as STAT= return value if the
12823 argument in the statement requires synchronisation with an image, which has
12824 initiated the termination of the execution. (Fortran 2008 or later.)
12826 @item @code{STAT_UNLOCKED}:
12827 Scalar default-integer constant used as STAT= return value by @code{UNLOCK} to
12828 denote that the lock variable is unlocked. (Fortran 2008 or later.)
12831 The module also provides the following intrinsic procedures:
12832 @ref{COMPILER_OPTIONS} and @ref{COMPILER_VERSION}.
12836 @node ISO_C_BINDING
12837 @section @code{ISO_C_BINDING}
12839 @item @emph{Standard}:
12840 Fortran 2003 and later, GNU extensions
12843 The following intrinsic procedures are provided by the module; their
12844 definition can be found in the section Intrinsic Procedures of this
12848 @item @code{C_ASSOCIATED}
12849 @item @code{C_F_POINTER}
12850 @item @code{C_F_PROCPOINTER}
12851 @item @code{C_FUNLOC}
12853 @item @code{C_SIZEOF}
12855 @c TODO: Vertical spacing between C_FUNLOC and C_LOC wrong in PDF,
12856 @c don't really know why.
12858 The @code{ISO_C_BINDING} module provides the following named constants of
12859 type default integer, which can be used as KIND type parameters.
12861 In addition to the integer named constants required by the Fortran 2003
12862 standard, GNU Fortran provides as an extension named constants for the
12863 128-bit integer types supported by the C compiler: @code{C_INT128_T,
12864 C_INT_LEAST128_T, C_INT_FAST128_T}.
12866 @multitable @columnfractions .15 .35 .35 .35
12867 @item Fortran Type @tab Named constant @tab C type @tab Extension
12868 @item @code{INTEGER}@tab @code{C_INT} @tab @code{int}
12869 @item @code{INTEGER}@tab @code{C_SHORT} @tab @code{short int}
12870 @item @code{INTEGER}@tab @code{C_LONG} @tab @code{long int}
12871 @item @code{INTEGER}@tab @code{C_LONG_LONG} @tab @code{long long int}
12872 @item @code{INTEGER}@tab @code{C_SIGNED_CHAR} @tab @code{signed char}/@code{unsigned char}
12873 @item @code{INTEGER}@tab @code{C_SIZE_T} @tab @code{size_t}
12874 @item @code{INTEGER}@tab @code{C_INT8_T} @tab @code{int8_t}
12875 @item @code{INTEGER}@tab @code{C_INT16_T} @tab @code{int16_t}
12876 @item @code{INTEGER}@tab @code{C_INT32_T} @tab @code{int32_t}
12877 @item @code{INTEGER}@tab @code{C_INT64_T} @tab @code{int64_t}
12878 @item @code{INTEGER}@tab @code{C_INT128_T} @tab @code{int128_t} @tab Ext.
12879 @item @code{INTEGER}@tab @code{C_INT_LEAST8_T} @tab @code{int_least8_t}
12880 @item @code{INTEGER}@tab @code{C_INT_LEAST16_T} @tab @code{int_least16_t}
12881 @item @code{INTEGER}@tab @code{C_INT_LEAST32_T} @tab @code{int_least32_t}
12882 @item @code{INTEGER}@tab @code{C_INT_LEAST64_T} @tab @code{int_least64_t}
12883 @item @code{INTEGER}@tab @code{C_INT_LEAST128_T}@tab @code{int_least128_t} @tab Ext.
12884 @item @code{INTEGER}@tab @code{C_INT_FAST8_T} @tab @code{int_fast8_t}
12885 @item @code{INTEGER}@tab @code{C_INT_FAST16_T} @tab @code{int_fast16_t}
12886 @item @code{INTEGER}@tab @code{C_INT_FAST32_T} @tab @code{int_fast32_t}
12887 @item @code{INTEGER}@tab @code{C_INT_FAST64_T} @tab @code{int_fast64_t}
12888 @item @code{INTEGER}@tab @code{C_INT_FAST128_T} @tab @code{int_fast128_t} @tab Ext.
12889 @item @code{INTEGER}@tab @code{C_INTMAX_T} @tab @code{intmax_t}
12890 @item @code{INTEGER}@tab @code{C_INTPTR_T} @tab @code{intptr_t}
12891 @item @code{REAL} @tab @code{C_FLOAT} @tab @code{float}
12892 @item @code{REAL} @tab @code{C_DOUBLE} @tab @code{double}
12893 @item @code{REAL} @tab @code{C_LONG_DOUBLE} @tab @code{long double}
12894 @item @code{COMPLEX}@tab @code{C_FLOAT_COMPLEX} @tab @code{float _Complex}
12895 @item @code{COMPLEX}@tab @code{C_DOUBLE_COMPLEX}@tab @code{double _Complex}
12896 @item @code{COMPLEX}@tab @code{C_LONG_DOUBLE_COMPLEX}@tab @code{long double _Complex}
12897 @item @code{LOGICAL}@tab @code{C_BOOL} @tab @code{_Bool}
12898 @item @code{CHARACTER}@tab @code{C_CHAR} @tab @code{char}
12901 Additionally, the following parameters of type @code{CHARACTER(KIND=C_CHAR)}
12904 @multitable @columnfractions .20 .45 .15
12905 @item Name @tab C definition @tab Value
12906 @item @code{C_NULL_CHAR} @tab null character @tab @code{'\0'}
12907 @item @code{C_ALERT} @tab alert @tab @code{'\a'}
12908 @item @code{C_BACKSPACE} @tab backspace @tab @code{'\b'}
12909 @item @code{C_FORM_FEED} @tab form feed @tab @code{'\f'}
12910 @item @code{C_NEW_LINE} @tab new line @tab @code{'\n'}
12911 @item @code{C_CARRIAGE_RETURN} @tab carriage return @tab @code{'\r'}
12912 @item @code{C_HORIZONTAL_TAB} @tab horizontal tab @tab @code{'\t'}
12913 @item @code{C_VERTICAL_TAB} @tab vertical tab @tab @code{'\v'}
12916 Moreover, the following two named constants are defined:
12918 @multitable @columnfractions .20 .80
12919 @item Name @tab Type
12920 @item @code{C_NULL_PTR} @tab @code{C_PTR}
12921 @item @code{C_NULL_FUNPTR} @tab @code{C_FUNPTR}
12924 Both are equivalent to the value @code{NULL} in C.
12926 @node OpenMP Modules OMP_LIB and OMP_LIB_KINDS
12927 @section OpenMP Modules @code{OMP_LIB} and @code{OMP_LIB_KINDS}
12929 @item @emph{Standard}:
12930 OpenMP Application Program Interface v3.0
12934 The OpenMP Fortran runtime library routines are provided both in
12935 a form of two Fortran 90 modules, named @code{OMP_LIB} and
12936 @code{OMP_LIB_KINDS}, and in a form of a Fortran @code{include} file named
12937 @file{omp_lib.h}. The procedures provided by @code{OMP_LIB} can be found
12938 in the @ref{Top,,Introduction,libgomp,GNU OpenMP runtime library} manual,
12939 the named constants defined in the modules are listed
12942 For details refer to the actual
12943 @uref{http://www.openmp.org/mp-documents/spec30.pdf,
12944 OpenMP Application Program Interface v3.0}.
12946 @code{OMP_LIB_KINDS} provides the following scalar default-integer
12950 @item @code{omp_integer_kind}
12951 @item @code{omp_logical_kind}
12952 @item @code{omp_lock_kind}
12953 @item @code{omp_nest_lock_kind}
12954 @item @code{omp_sched_kind}
12957 @code{OMP_LIB} provides the scalar default-integer
12958 named constant @code{openmp_version} with a value of the form
12959 @var{yyyymm}, where @code{yyyy} is the year and @var{mm} the month
12960 of the OpenMP version; for OpenMP v3.0 the value is @code{200805}.
12962 And the following scalar integer named constants of the
12963 kind @code{omp_sched_kind}:
12966 @item @code{omp_sched_static}
12967 @item @code{omp_sched_dynamic}
12968 @item @code{omp_sched_guided}
12969 @item @code{omp_sched_auto}