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.
350 @item @emph{Standard}:
359 @item @emph{Return value}:
362 @item @emph{Example}:
365 integer :: i = 1, j = 2
366 if (i /= j) call abort
367 end program test_abort
370 @item @emph{See also}:
371 @ref{EXIT}, @ref{KILL}
378 @section @code{ABS} --- Absolute value
385 @cindex absolute value
388 @item @emph{Description}:
389 @code{ABS(A)} computes the absolute value of @code{A}.
391 @item @emph{Standard}:
392 Fortran 77 and later, has overloads that are GNU extensions
398 @code{RESULT = ABS(A)}
400 @item @emph{Arguments}:
401 @multitable @columnfractions .15 .70
402 @item @var{A} @tab The type of the argument shall be an @code{INTEGER},
403 @code{REAL}, or @code{COMPLEX}.
406 @item @emph{Return value}:
407 The return value is of the same type and
408 kind as the argument except the return value is @code{REAL} for a
409 @code{COMPLEX} argument.
411 @item @emph{Example}:
416 complex :: z = (-1.e0,0.e0)
423 @item @emph{Specific names}:
424 @multitable @columnfractions .20 .20 .20 .25
425 @item Name @tab Argument @tab Return type @tab Standard
426 @item @code{ABS(A)} @tab @code{REAL(4) A} @tab @code{REAL(4)} @tab Fortran 77 and later
427 @item @code{CABS(A)} @tab @code{COMPLEX(4) A} @tab @code{REAL(4)} @tab Fortran 77 and later
428 @item @code{DABS(A)} @tab @code{REAL(8) A} @tab @code{REAL(8)} @tab Fortran 77 and later
429 @item @code{IABS(A)} @tab @code{INTEGER(4) A} @tab @code{INTEGER(4)} @tab Fortran 77 and later
430 @item @code{ZABS(A)} @tab @code{COMPLEX(8) A} @tab @code{COMPLEX(8)} @tab GNU extension
431 @item @code{CDABS(A)} @tab @code{COMPLEX(8) A} @tab @code{COMPLEX(8)} @tab GNU extension
438 @section @code{ACCESS} --- Checks file access modes
440 @cindex file system, access mode
443 @item @emph{Description}:
444 @code{ACCESS(NAME, MODE)} checks whether the file @var{NAME}
445 exists, is readable, writable or executable. Except for the
446 executable check, @code{ACCESS} can be replaced by
447 Fortran 95's @code{INQUIRE}.
449 @item @emph{Standard}:
456 @code{RESULT = ACCESS(NAME, MODE)}
458 @item @emph{Arguments}:
459 @multitable @columnfractions .15 .70
460 @item @var{NAME} @tab Scalar @code{CHARACTER} of default kind with the
461 file name. Tailing blank are ignored unless the character @code{achar(0)}
462 is present, then all characters up to and excluding @code{achar(0)} are
464 @item @var{MODE} @tab Scalar @code{CHARACTER} of default kind with the
465 file access mode, may be any concatenation of @code{"r"} (readable),
466 @code{"w"} (writable) and @code{"x"} (executable), or @code{" "} to check
470 @item @emph{Return value}:
471 Returns a scalar @code{INTEGER}, which is @code{0} if the file is
472 accessible in the given mode; otherwise or if an invalid argument
473 has been given for @code{MODE} the value @code{1} is returned.
475 @item @emph{Example}:
479 character(len=*), parameter :: file = 'test.dat'
480 character(len=*), parameter :: file2 = 'test.dat '//achar(0)
481 if(access(file,' ') == 0) print *, trim(file),' is exists'
482 if(access(file,'r') == 0) print *, trim(file),' is readable'
483 if(access(file,'w') == 0) print *, trim(file),' is writable'
484 if(access(file,'x') == 0) print *, trim(file),' is executable'
485 if(access(file2,'rwx') == 0) &
486 print *, trim(file2),' is readable, writable and executable'
487 end program access_test
489 @item @emph{Specific names}:
490 @item @emph{See also}:
497 @section @code{ACHAR} --- Character in @acronym{ASCII} collating sequence
499 @cindex @acronym{ASCII} collating sequence
500 @cindex collating sequence, @acronym{ASCII}
503 @item @emph{Description}:
504 @code{ACHAR(I)} returns the character located at position @code{I}
505 in the @acronym{ASCII} collating sequence.
507 @item @emph{Standard}:
508 Fortran 77 and later, with @var{KIND} argument Fortran 2003 and later
514 @code{RESULT = ACHAR(I [, KIND])}
516 @item @emph{Arguments}:
517 @multitable @columnfractions .15 .70
518 @item @var{I} @tab The type shall be @code{INTEGER}.
519 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
520 expression indicating the kind parameter of the result.
523 @item @emph{Return value}:
524 The return value is of type @code{CHARACTER} with a length of one.
525 If the @var{KIND} argument is present, the return value is of the
526 specified kind and of the default kind otherwise.
528 @item @emph{Example}:
533 end program test_achar
537 See @ref{ICHAR} for a discussion of converting between numerical values
538 and formatted string representations.
540 @item @emph{See also}:
541 @ref{CHAR}, @ref{IACHAR}, @ref{ICHAR}
548 @section @code{ACOS} --- Arccosine function
551 @cindex trigonometric function, cosine, inverse
552 @cindex cosine, inverse
555 @item @emph{Description}:
556 @code{ACOS(X)} computes the arccosine of @var{X} (inverse of @code{COS(X)}).
558 @item @emph{Standard}:
559 Fortran 77 and later, for a complex argument Fortran 2008 or later
565 @code{RESULT = ACOS(X)}
567 @item @emph{Arguments}:
568 @multitable @columnfractions .15 .70
569 @item @var{X} @tab The type shall either be @code{REAL} with a magnitude that is
570 less than or equal to one - or the type shall be @code{COMPLEX}.
573 @item @emph{Return value}:
574 The return value is of the same type and kind as @var{X}.
575 The real part of the result is in radians and lies in the range
576 @math{0 \leq \Re \acos(x) \leq \pi}.
578 @item @emph{Example}:
581 real(8) :: x = 0.866_8
583 end program test_acos
586 @item @emph{Specific names}:
587 @multitable @columnfractions .20 .20 .20 .25
588 @item Name @tab Argument @tab Return type @tab Standard
589 @item @code{ACOS(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab Fortran 77 and later
590 @item @code{DACOS(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab Fortran 77 and later
593 @item @emph{See also}:
594 Inverse function: @ref{COS}
601 @section @code{ACOSH} --- Inverse hyperbolic cosine function
604 @cindex area hyperbolic cosine
605 @cindex inverse hyperbolic cosine
606 @cindex hyperbolic function, cosine, inverse
607 @cindex cosine, hyperbolic, inverse
610 @item @emph{Description}:
611 @code{ACOSH(X)} computes the inverse hyperbolic cosine of @var{X}.
613 @item @emph{Standard}:
614 Fortran 2008 and later
620 @code{RESULT = ACOSH(X)}
622 @item @emph{Arguments}:
623 @multitable @columnfractions .15 .70
624 @item @var{X} @tab The type shall be @code{REAL} or @code{COMPLEX}.
627 @item @emph{Return value}:
628 The return value has the same type and kind as @var{X}. If @var{X} is
629 complex, the imaginary part of the result is in radians and lies between
630 @math{ 0 \leq \Im \acosh(x) \leq \pi}.
632 @item @emph{Example}:
635 REAL(8), DIMENSION(3) :: x = (/ 1.0, 2.0, 3.0 /)
640 @item @emph{Specific names}:
641 @multitable @columnfractions .20 .20 .20 .25
642 @item Name @tab Argument @tab Return type @tab Standard
643 @item @code{DACOSH(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU extension
646 @item @emph{See also}:
647 Inverse function: @ref{COSH}
653 @section @code{ADJUSTL} --- Left adjust a string
655 @cindex string, adjust left
656 @cindex adjust string
659 @item @emph{Description}:
660 @code{ADJUSTL(STRING)} will left adjust a string by removing leading spaces.
661 Spaces are inserted at the end of the string as needed.
663 @item @emph{Standard}:
670 @code{RESULT = ADJUSTL(STRING)}
672 @item @emph{Arguments}:
673 @multitable @columnfractions .15 .70
674 @item @var{STRING} @tab The type shall be @code{CHARACTER}.
677 @item @emph{Return value}:
678 The return value is of type @code{CHARACTER} and of the same kind as
679 @var{STRING} where leading spaces are removed and the same number of
680 spaces are inserted on the end of @var{STRING}.
682 @item @emph{Example}:
685 character(len=20) :: str = ' gfortran'
688 end program test_adjustl
691 @item @emph{See also}:
692 @ref{ADJUSTR}, @ref{TRIM}
698 @section @code{ADJUSTR} --- Right adjust a string
700 @cindex string, adjust right
701 @cindex adjust string
704 @item @emph{Description}:
705 @code{ADJUSTR(STRING)} will right adjust a string by removing trailing spaces.
706 Spaces are inserted at the start of the string as needed.
708 @item @emph{Standard}:
715 @code{RESULT = ADJUSTR(STRING)}
717 @item @emph{Arguments}:
718 @multitable @columnfractions .15 .70
719 @item @var{STR} @tab The type shall be @code{CHARACTER}.
722 @item @emph{Return value}:
723 The return value is of type @code{CHARACTER} and of the same kind as
724 @var{STRING} where trailing spaces are removed and the same number of
725 spaces are inserted at the start of @var{STRING}.
727 @item @emph{Example}:
730 character(len=20) :: str = 'gfortran'
733 end program test_adjustr
736 @item @emph{See also}:
737 @ref{ADJUSTL}, @ref{TRIM}
743 @section @code{AIMAG} --- Imaginary part of complex number
748 @cindex complex numbers, imaginary part
751 @item @emph{Description}:
752 @code{AIMAG(Z)} yields the imaginary part of complex argument @code{Z}.
753 The @code{IMAG(Z)} and @code{IMAGPART(Z)} intrinsic functions are provided
754 for compatibility with @command{g77}, and their use in new code is
755 strongly discouraged.
757 @item @emph{Standard}:
758 Fortran 77 and later, has overloads that are GNU extensions
764 @code{RESULT = AIMAG(Z)}
766 @item @emph{Arguments}:
767 @multitable @columnfractions .15 .70
768 @item @var{Z} @tab The type of the argument shall be @code{COMPLEX}.
771 @item @emph{Return value}:
772 The return value is of type @code{REAL} with the
773 kind type parameter of the argument.
775 @item @emph{Example}:
780 z4 = cmplx(1.e0_4, 0.e0_4)
781 z8 = cmplx(0.e0_8, 1.e0_8)
782 print *, aimag(z4), dimag(z8)
783 end program test_aimag
786 @item @emph{Specific names}:
787 @multitable @columnfractions .20 .20 .20 .25
788 @item Name @tab Argument @tab Return type @tab Standard
789 @item @code{AIMAG(Z)} @tab @code{COMPLEX Z} @tab @code{REAL} @tab GNU extension
790 @item @code{DIMAG(Z)} @tab @code{COMPLEX(8) Z} @tab @code{REAL(8)} @tab GNU extension
791 @item @code{IMAG(Z)} @tab @code{COMPLEX Z} @tab @code{REAL} @tab GNU extension
792 @item @code{IMAGPART(Z)} @tab @code{COMPLEX Z} @tab @code{REAL} @tab GNU extension
799 @section @code{AINT} --- Truncate to a whole number
803 @cindex rounding, floor
806 @item @emph{Description}:
807 @code{AINT(A [, KIND])} truncates its argument to a whole number.
809 @item @emph{Standard}:
816 @code{RESULT = AINT(A [, KIND])}
818 @item @emph{Arguments}:
819 @multitable @columnfractions .15 .70
820 @item @var{A} @tab The type of the argument shall be @code{REAL}.
821 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
822 expression indicating the kind parameter of the result.
825 @item @emph{Return value}:
826 The return value is of type @code{REAL} with the kind type parameter of the
827 argument if the optional @var{KIND} is absent; otherwise, the kind
828 type parameter will be given by @var{KIND}. If the magnitude of
829 @var{X} is less than one, @code{AINT(X)} returns zero. If the
830 magnitude is equal to or greater than one then it returns the largest
831 whole number that does not exceed its magnitude. The sign is the same
832 as the sign of @var{X}.
834 @item @emph{Example}:
841 print *, aint(x4), dint(x8)
843 end program test_aint
846 @item @emph{Specific names}:
847 @multitable @columnfractions .20 .20 .20 .25
848 @item Name @tab Argument @tab Return type @tab Standard
849 @item @code{AINT(A)} @tab @code{REAL(4) A} @tab @code{REAL(4)} @tab Fortran 77 and later
850 @item @code{DINT(A)} @tab @code{REAL(8) A} @tab @code{REAL(8)} @tab Fortran 77 and later
857 @section @code{ALARM} --- Execute a routine after a given delay
859 @cindex delayed execution
862 @item @emph{Description}:
863 @code{ALARM(SECONDS, HANDLER [, STATUS])} causes external subroutine @var{HANDLER}
864 to be executed after a delay of @var{SECONDS} by using @code{alarm(2)} to
865 set up a signal and @code{signal(2)} to catch it. If @var{STATUS} is
866 supplied, it will be returned with the number of seconds remaining until
867 any previously scheduled alarm was due to be delivered, or zero if there
868 was no previously scheduled alarm.
870 @item @emph{Standard}:
877 @code{CALL ALARM(SECONDS, HANDLER [, STATUS])}
879 @item @emph{Arguments}:
880 @multitable @columnfractions .15 .70
881 @item @var{SECONDS} @tab The type of the argument shall be a scalar
882 @code{INTEGER}. It is @code{INTENT(IN)}.
883 @item @var{HANDLER} @tab Signal handler (@code{INTEGER FUNCTION} or
884 @code{SUBROUTINE}) or dummy/global @code{INTEGER} scalar. The scalar
885 values may be either @code{SIG_IGN=1} to ignore the alarm generated
886 or @code{SIG_DFL=0} to set the default action. It is @code{INTENT(IN)}.
887 @item @var{STATUS} @tab (Optional) @var{STATUS} shall be a scalar
888 variable of the default @code{INTEGER} kind. It is @code{INTENT(OUT)}.
891 @item @emph{Example}:
894 external handler_print
896 call alarm (3, handler_print, i)
899 end program test_alarm
901 This will cause the external routine @var{handler_print} to be called
908 @section @code{ALL} --- All values in @var{MASK} along @var{DIM} are true
910 @cindex array, apply condition
911 @cindex array, condition testing
914 @item @emph{Description}:
915 @code{ALL(MASK [, DIM])} determines if all the values are true in @var{MASK}
916 in the array along dimension @var{DIM}.
918 @item @emph{Standard}:
922 Transformational function
925 @code{RESULT = ALL(MASK [, DIM])}
927 @item @emph{Arguments}:
928 @multitable @columnfractions .15 .70
929 @item @var{MASK} @tab The type of the argument shall be @code{LOGICAL} and
930 it shall not be scalar.
931 @item @var{DIM} @tab (Optional) @var{DIM} shall be a scalar integer
932 with a value that lies between one and the rank of @var{MASK}.
935 @item @emph{Return value}:
936 @code{ALL(MASK)} returns a scalar value of type @code{LOGICAL} where
937 the kind type parameter is the same as the kind type parameter of
938 @var{MASK}. If @var{DIM} is present, then @code{ALL(MASK, DIM)} returns
939 an array with the rank of @var{MASK} minus 1. The shape is determined from
940 the shape of @var{MASK} where the @var{DIM} dimension is elided.
944 @code{ALL(MASK)} is true if all elements of @var{MASK} are true.
945 It also is true if @var{MASK} has zero size; otherwise, it is false.
947 If the rank of @var{MASK} is one, then @code{ALL(MASK,DIM)} is equivalent
948 to @code{ALL(MASK)}. If the rank is greater than one, then @code{ALL(MASK,DIM)}
949 is determined by applying @code{ALL} to the array sections.
952 @item @emph{Example}:
956 l = all((/.true., .true., .true./))
961 integer a(2,3), b(2,3)
965 print *, all(a .eq. b, 1)
966 print *, all(a .eq. b, 2)
967 end subroutine section
975 @section @code{ALLOCATED} --- Status of an allocatable entity
977 @cindex allocation, status
980 @item @emph{Description}:
981 @code{ALLOCATED(ARRAY)} and @code{ALLOCATED(SCALAR)} check the allocation
982 status of @var{ARRAY} and @var{SCALAR}, respectively.
984 @item @emph{Standard}:
985 Fortran 95 and later. Note, the @code{SCALAR=} keyword and allocatable
986 scalar entities are available in Fortran 2003 and later.
992 @multitable @columnfractions .80
993 @item @code{RESULT = ALLOCATED(ARRAY)}
994 @item @code{RESULT = ALLOCATED(SCALAR)}
997 @item @emph{Arguments}:
998 @multitable @columnfractions .15 .70
999 @item @var{ARRAY} @tab The argument shall be an @code{ALLOCATABLE} array.
1000 @item @var{SCALAR} @tab The argument shall be an @code{ALLOCATABLE} scalar.
1003 @item @emph{Return value}:
1004 The return value is a scalar @code{LOGICAL} with the default logical
1005 kind type parameter. If the argument is allocated, then the result is
1006 @code{.TRUE.}; otherwise, it returns @code{.FALSE.}
1008 @item @emph{Example}:
1010 program test_allocated
1012 real(4), allocatable :: x(:)
1013 if (.not. allocated(x)) allocate(x(i))
1014 end program test_allocated
1021 @section @code{AND} --- Bitwise logical AND
1023 @cindex bitwise logical and
1024 @cindex logical and, bitwise
1027 @item @emph{Description}:
1028 Bitwise logical @code{AND}.
1030 This intrinsic routine is provided for backwards compatibility with
1031 GNU Fortran 77. For integer arguments, programmers should consider
1032 the use of the @ref{IAND} intrinsic defined by the Fortran standard.
1034 @item @emph{Standard}:
1040 @item @emph{Syntax}:
1041 @code{RESULT = AND(I, J)}
1043 @item @emph{Arguments}:
1044 @multitable @columnfractions .15 .70
1045 @item @var{I} @tab The type shall be either a scalar @code{INTEGER}
1046 type or a scalar @code{LOGICAL} type.
1047 @item @var{J} @tab The type shall be the same as the type of @var{I}.
1050 @item @emph{Return value}:
1051 The return type is either a scalar @code{INTEGER} or a scalar
1052 @code{LOGICAL}. If the kind type parameters differ, then the
1053 smaller kind type is implicitly converted to larger kind, and the
1054 return has the larger kind.
1056 @item @emph{Example}:
1059 LOGICAL :: T = .TRUE., F = .FALSE.
1061 DATA a / Z'F' /, b / Z'3' /
1063 WRITE (*,*) AND(T, T), AND(T, F), AND(F, T), AND(F, F)
1064 WRITE (*,*) AND(a, b)
1068 @item @emph{See also}:
1069 Fortran 95 elemental function: @ref{IAND}
1075 @section @code{ANINT} --- Nearest whole number
1079 @cindex rounding, ceiling
1082 @item @emph{Description}:
1083 @code{ANINT(A [, KIND])} rounds its argument to the nearest whole number.
1085 @item @emph{Standard}:
1086 Fortran 77 and later
1091 @item @emph{Syntax}:
1092 @code{RESULT = ANINT(A [, KIND])}
1094 @item @emph{Arguments}:
1095 @multitable @columnfractions .15 .70
1096 @item @var{A} @tab The type of the argument shall be @code{REAL}.
1097 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
1098 expression indicating the kind parameter of the result.
1101 @item @emph{Return value}:
1102 The return value is of type real with the kind type parameter of the
1103 argument if the optional @var{KIND} is absent; otherwise, the kind
1104 type parameter will be given by @var{KIND}. If @var{A} is greater than
1105 zero, @code{ANINT(A)} returns @code{AINT(X+0.5)}. If @var{A} is
1106 less than or equal to zero then it returns @code{AINT(X-0.5)}.
1108 @item @emph{Example}:
1115 print *, anint(x4), dnint(x8)
1117 end program test_anint
1120 @item @emph{Specific names}:
1121 @multitable @columnfractions .20 .20 .20 .25
1122 @item Name @tab Argument @tab Return type @tab Standard
1123 @item @code{AINT(A)} @tab @code{REAL(4) A} @tab @code{REAL(4)} @tab Fortran 77 and later
1124 @item @code{DNINT(A)} @tab @code{REAL(8) A} @tab @code{REAL(8)} @tab Fortran 77 and later
1131 @section @code{ANY} --- Any value in @var{MASK} along @var{DIM} is true
1133 @cindex array, apply condition
1134 @cindex array, condition testing
1137 @item @emph{Description}:
1138 @code{ANY(MASK [, DIM])} determines if any of the values in the logical array
1139 @var{MASK} along dimension @var{DIM} are @code{.TRUE.}.
1141 @item @emph{Standard}:
1142 Fortran 95 and later
1145 Transformational function
1147 @item @emph{Syntax}:
1148 @code{RESULT = ANY(MASK [, DIM])}
1150 @item @emph{Arguments}:
1151 @multitable @columnfractions .15 .70
1152 @item @var{MASK} @tab The type of the argument shall be @code{LOGICAL} and
1153 it shall not be scalar.
1154 @item @var{DIM} @tab (Optional) @var{DIM} shall be a scalar integer
1155 with a value that lies between one and the rank of @var{MASK}.
1158 @item @emph{Return value}:
1159 @code{ANY(MASK)} returns a scalar value of type @code{LOGICAL} where
1160 the kind type parameter is the same as the kind type parameter of
1161 @var{MASK}. If @var{DIM} is present, then @code{ANY(MASK, DIM)} returns
1162 an array with the rank of @var{MASK} minus 1. The shape is determined from
1163 the shape of @var{MASK} where the @var{DIM} dimension is elided.
1167 @code{ANY(MASK)} is true if any element of @var{MASK} is true;
1168 otherwise, it is false. It also is false if @var{MASK} has zero size.
1170 If the rank of @var{MASK} is one, then @code{ANY(MASK,DIM)} is equivalent
1171 to @code{ANY(MASK)}. If the rank is greater than one, then @code{ANY(MASK,DIM)}
1172 is determined by applying @code{ANY} to the array sections.
1175 @item @emph{Example}:
1179 l = any((/.true., .true., .true./))
1184 integer a(2,3), b(2,3)
1188 print *, any(a .eq. b, 1)
1189 print *, any(a .eq. b, 2)
1190 end subroutine section
1191 end program test_any
1198 @section @code{ASIN} --- Arcsine function
1201 @cindex trigonometric function, sine, inverse
1202 @cindex sine, inverse
1205 @item @emph{Description}:
1206 @code{ASIN(X)} computes the arcsine of its @var{X} (inverse of @code{SIN(X)}).
1208 @item @emph{Standard}:
1209 Fortran 77 and later, for a complex argument Fortran 2008 or later
1214 @item @emph{Syntax}:
1215 @code{RESULT = ASIN(X)}
1217 @item @emph{Arguments}:
1218 @multitable @columnfractions .15 .70
1219 @item @var{X} @tab The type shall be either @code{REAL} and a magnitude that is
1220 less than or equal to one - or be @code{COMPLEX}.
1223 @item @emph{Return value}:
1224 The return value is of the same type and kind as @var{X}.
1225 The real part of the result is in radians and lies in the range
1226 @math{-\pi/2 \leq \Re \asin(x) \leq \pi/2}.
1228 @item @emph{Example}:
1231 real(8) :: x = 0.866_8
1233 end program test_asin
1236 @item @emph{Specific names}:
1237 @multitable @columnfractions .20 .20 .20 .25
1238 @item Name @tab Argument @tab Return type @tab Standard
1239 @item @code{ASIN(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab Fortran 77 and later
1240 @item @code{DASIN(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab Fortran 77 and later
1243 @item @emph{See also}:
1244 Inverse function: @ref{SIN}
1251 @section @code{ASINH} --- Inverse hyperbolic sine function
1254 @cindex area hyperbolic sine
1255 @cindex inverse hyperbolic sine
1256 @cindex hyperbolic function, sine, inverse
1257 @cindex sine, hyperbolic, inverse
1260 @item @emph{Description}:
1261 @code{ASINH(X)} computes the inverse hyperbolic sine of @var{X}.
1263 @item @emph{Standard}:
1264 Fortran 2008 and later
1269 @item @emph{Syntax}:
1270 @code{RESULT = ASINH(X)}
1272 @item @emph{Arguments}:
1273 @multitable @columnfractions .15 .70
1274 @item @var{X} @tab The type shall be @code{REAL} or @code{COMPLEX}.
1277 @item @emph{Return value}:
1278 The return value is of the same type and kind as @var{X}. If @var{X} is
1279 complex, the imaginary part of the result is in radians and lies between
1280 @math{-\pi/2 \leq \Im \asinh(x) \leq \pi/2}.
1282 @item @emph{Example}:
1285 REAL(8), DIMENSION(3) :: x = (/ -1.0, 0.0, 1.0 /)
1286 WRITE (*,*) ASINH(x)
1290 @item @emph{Specific names}:
1291 @multitable @columnfractions .20 .20 .20 .25
1292 @item Name @tab Argument @tab Return type @tab Standard
1293 @item @code{DASINH(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU extension.
1296 @item @emph{See also}:
1297 Inverse function: @ref{SINH}
1303 @section @code{ASSOCIATED} --- Status of a pointer or pointer/target pair
1305 @cindex pointer, status
1306 @cindex association status
1309 @item @emph{Description}:
1310 @code{ASSOCIATED(POINTER [, TARGET])} determines the status of the pointer
1311 @var{POINTER} or if @var{POINTER} is associated with the target @var{TARGET}.
1313 @item @emph{Standard}:
1314 Fortran 95 and later
1319 @item @emph{Syntax}:
1320 @code{RESULT = ASSOCIATED(POINTER [, TARGET])}
1322 @item @emph{Arguments}:
1323 @multitable @columnfractions .15 .70
1324 @item @var{POINTER} @tab @var{POINTER} shall have the @code{POINTER} attribute
1325 and it can be of any type.
1326 @item @var{TARGET} @tab (Optional) @var{TARGET} shall be a pointer or
1327 a target. It must have the same type, kind type parameter, and
1328 array rank as @var{POINTER}.
1330 The association status of neither @var{POINTER} nor @var{TARGET} shall be
1333 @item @emph{Return value}:
1334 @code{ASSOCIATED(POINTER)} returns a scalar value of type @code{LOGICAL(4)}.
1335 There are several cases:
1337 @item (A) When the optional @var{TARGET} is not present then
1338 @code{ASSOCIATED(POINTER)} is true if @var{POINTER} is associated with a target; otherwise, it returns false.
1339 @item (B) If @var{TARGET} is present and a scalar target, the result is true if
1340 @var{TARGET} is not a zero-sized storage sequence and the target associated with @var{POINTER} occupies the same storage units. If @var{POINTER} is
1341 disassociated, the result is false.
1342 @item (C) If @var{TARGET} is present and an array target, the result is true if
1343 @var{TARGET} and @var{POINTER} have the same shape, are not zero-sized arrays,
1344 are arrays whose elements are not zero-sized storage sequences, and
1345 @var{TARGET} and @var{POINTER} occupy the same storage units in array element
1347 As in case(B), the result is false, if @var{POINTER} is disassociated.
1348 @item (D) If @var{TARGET} is present and an scalar pointer, the result is true
1349 if @var{TARGET} is associated with @var{POINTER}, the target associated with
1350 @var{TARGET} are not zero-sized storage sequences and occupy the same storage
1352 The result is false, if either @var{TARGET} or @var{POINTER} is disassociated.
1353 @item (E) If @var{TARGET} is present and an array pointer, the result is true if
1354 target associated with @var{POINTER} and the target associated with @var{TARGET}
1355 have the same shape, are not zero-sized arrays, are arrays whose elements are
1356 not zero-sized storage sequences, and @var{TARGET} and @var{POINTER} occupy
1357 the same storage units in array element order.
1358 The result is false, if either @var{TARGET} or @var{POINTER} is disassociated.
1361 @item @emph{Example}:
1363 program test_associated
1365 real, target :: tgt(2) = (/1., 2./)
1366 real, pointer :: ptr(:)
1368 if (associated(ptr) .eqv. .false.) call abort
1369 if (associated(ptr,tgt) .eqv. .false.) call abort
1370 end program test_associated
1373 @item @emph{See also}:
1380 @section @code{ATAN} --- Arctangent function
1383 @cindex trigonometric function, tangent, inverse
1384 @cindex tangent, inverse
1387 @item @emph{Description}:
1388 @code{ATAN(X)} computes the arctangent of @var{X}.
1390 @item @emph{Standard}:
1391 Fortran 77 and later, for a complex argument and for two arguments
1392 Fortran 2008 or later
1397 @item @emph{Syntax}:
1398 @multitable @columnfractions .80
1399 @item @code{RESULT = ATAN(X)}
1400 @item @code{RESULT = ATAN(Y, X)}
1403 @item @emph{Arguments}:
1404 @multitable @columnfractions .15 .70
1405 @item @var{X} @tab The type shall be @code{REAL} or @code{COMPLEX};
1406 if @var{Y} is present, @var{X} shall be REAL.
1407 @item @var{Y} shall be of the same type and kind as @var{X}.
1410 @item @emph{Return value}:
1411 The return value is of the same type and kind as @var{X}.
1412 If @var{Y} is present, the result is identical to @code{ATAN2(Y,X)}.
1413 Otherwise, it the arcus tangent of @var{X}, where the real part of
1414 the result is in radians and lies in the range
1415 @math{-\pi/2 \leq \Re \atan(x) \leq \pi/2}.
1417 @item @emph{Example}:
1420 real(8) :: x = 2.866_8
1422 end program test_atan
1425 @item @emph{Specific names}:
1426 @multitable @columnfractions .20 .20 .20 .25
1427 @item Name @tab Argument @tab Return type @tab Standard
1428 @item @code{ATAN(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab Fortran 77 and later
1429 @item @code{DATAN(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab Fortran 77 and later
1432 @item @emph{See also}:
1433 Inverse function: @ref{TAN}
1440 @section @code{ATAN2} --- Arctangent function
1443 @cindex trigonometric function, tangent, inverse
1444 @cindex tangent, inverse
1447 @item @emph{Description}:
1448 @code{ATAN2(Y, X)} computes the principal value of the argument
1449 function of the complex number @math{X + i Y}. This function can
1450 be used to transform from Cartesian into polar coordinates and
1451 allows to determine the angle in the correct quadrant.
1453 @item @emph{Standard}:
1454 Fortran 77 and later
1459 @item @emph{Syntax}:
1460 @code{RESULT = ATAN2(Y, X)}
1462 @item @emph{Arguments}:
1463 @multitable @columnfractions .15 .70
1464 @item @var{Y} @tab The type shall be @code{REAL}.
1465 @item @var{X} @tab The type and kind type parameter shall be the same as @var{Y}.
1466 If @var{Y} is zero, then @var{X} must be nonzero.
1469 @item @emph{Return value}:
1470 The return value has the same type and kind type parameter as @var{Y}.
1471 It is the principal value of the complex number @math{X + i Y}. If
1472 @var{X} is nonzero, then it lies in the range @math{-\pi \le \atan (x) \leq \pi}.
1473 The sign is positive if @var{Y} is positive. If @var{Y} is zero, then
1474 the return value is zero if @var{X} is positive and @math{\pi} if @var{X}
1475 is negative. Finally, if @var{X} is zero, then the magnitude of the result
1478 @item @emph{Example}:
1481 real(4) :: x = 1.e0_4, y = 0.5e0_4
1483 end program test_atan2
1486 @item @emph{Specific names}:
1487 @multitable @columnfractions .20 .20 .20 .25
1488 @item Name @tab Argument @tab Return type @tab Standard
1489 @item @code{ATAN2(X, Y)} @tab @code{REAL(4) X, Y} @tab @code{REAL(4)} @tab Fortran 77 and later
1490 @item @code{DATAN2(X, Y)} @tab @code{REAL(8) X, Y} @tab @code{REAL(8)} @tab Fortran 77 and later
1497 @section @code{ATANH} --- Inverse hyperbolic tangent function
1500 @cindex area hyperbolic tangent
1501 @cindex inverse hyperbolic tangent
1502 @cindex hyperbolic function, tangent, inverse
1503 @cindex tangent, hyperbolic, inverse
1506 @item @emph{Description}:
1507 @code{ATANH(X)} computes the inverse hyperbolic tangent of @var{X}.
1509 @item @emph{Standard}:
1510 Fortran 2008 and later
1515 @item @emph{Syntax}:
1516 @code{RESULT = ATANH(X)}
1518 @item @emph{Arguments}:
1519 @multitable @columnfractions .15 .70
1520 @item @var{X} @tab The type shall be @code{REAL} or @code{COMPLEX}.
1523 @item @emph{Return value}:
1524 The return value has same type and kind as @var{X}. If @var{X} is
1525 complex, the imaginary part of the result is in radians and lies between
1526 @math{-\pi/2 \leq \Im \atanh(x) \leq \pi/2}.
1528 @item @emph{Example}:
1531 REAL, DIMENSION(3) :: x = (/ -1.0, 0.0, 1.0 /)
1532 WRITE (*,*) ATANH(x)
1536 @item @emph{Specific names}:
1537 @multitable @columnfractions .20 .20 .20 .25
1538 @item Name @tab Argument @tab Return type @tab Standard
1539 @item @code{DATANH(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU extension
1542 @item @emph{See also}:
1543 Inverse function: @ref{TANH}
1549 @section @code{BESSEL_J0} --- Bessel function of the first kind of order 0
1553 @cindex Bessel function, first kind
1556 @item @emph{Description}:
1557 @code{BESSEL_J0(X)} computes the Bessel function of the first kind of
1558 order 0 of @var{X}. This function is available under the name
1559 @code{BESJ0} as a GNU extension.
1561 @item @emph{Standard}:
1562 Fortran 2008 and later
1567 @item @emph{Syntax}:
1568 @code{RESULT = BESSEL_J0(X)}
1570 @item @emph{Arguments}:
1571 @multitable @columnfractions .15 .70
1572 @item @var{X} @tab The type shall be @code{REAL}, and it shall be scalar.
1575 @item @emph{Return value}:
1576 The return value is of type @code{REAL} and lies in the
1577 range @math{ - 0.4027... \leq Bessel (0,x) \leq 1}. It has the same
1580 @item @emph{Example}:
1583 real(8) :: x = 0.0_8
1585 end program test_besj0
1588 @item @emph{Specific names}:
1589 @multitable @columnfractions .20 .20 .20 .25
1590 @item Name @tab Argument @tab Return type @tab Standard
1591 @item @code{DBESJ0(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU extension
1598 @section @code{BESSEL_J1} --- Bessel function of the first kind of order 1
1602 @cindex Bessel function, first kind
1605 @item @emph{Description}:
1606 @code{BESSEL_J1(X)} computes the Bessel function of the first kind of
1607 order 1 of @var{X}. This function is available under the name
1608 @code{BESJ1} as a GNU extension.
1610 @item @emph{Standard}:
1616 @item @emph{Syntax}:
1617 @code{RESULT = BESSEL_J1(X)}
1619 @item @emph{Arguments}:
1620 @multitable @columnfractions .15 .70
1621 @item @var{X} @tab The type shall be @code{REAL}, and it shall be scalar.
1624 @item @emph{Return value}:
1625 The return value is of type @code{REAL} and it lies in the
1626 range @math{ - 0.5818... \leq Bessel (0,x) \leq 0.5818 }. It has the same
1629 @item @emph{Example}:
1632 real(8) :: x = 1.0_8
1634 end program test_besj1
1637 @item @emph{Specific names}:
1638 @multitable @columnfractions .20 .20 .20 .25
1639 @item Name @tab Argument @tab Return type @tab Standard
1640 @item @code{DBESJ1(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU extension
1647 @section @code{BESSEL_JN} --- Bessel function of the first kind
1651 @cindex Bessel function, first kind
1654 @item @emph{Description}:
1655 @code{BESSEL_JN(N, X)} computes the Bessel function of the first kind of
1656 order @var{N} of @var{X}. This function is available under the name
1657 @code{BESJN} as a GNU extension. If @var{N} and @var{X} are arrays,
1658 their ranks and shapes shall conform.
1660 @code{BESSEL_JN(N1, N2, X)} returns an array with the Bessel functions
1661 of the first kind of the orders @var{N1} to @var{N2}.
1663 @item @emph{Standard}:
1664 Fortran 2008 and later, negative @var{N} is allowed as GNU extension
1667 Elemental function, except for the transformational function
1668 @code{BESSEL_JN(N1, N2, X)}
1670 @item @emph{Syntax}:
1671 @multitable @columnfractions .80
1672 @item @code{RESULT = BESSEL_JN(N, X)}
1673 @item @code{RESULT = BESSEL_JN(N1, N2, X)}
1676 @item @emph{Arguments}:
1677 @multitable @columnfractions .15 .70
1678 @item @var{N} @tab Shall be a scalar or an array of type @code{INTEGER}.
1679 @item @var{N1} @tab Shall be a non-negative scalar of type @code{INTEGER}.
1680 @item @var{N2} @tab Shall be a non-negative scalar of type @code{INTEGER}.
1681 @item @var{X} @tab Shall be a scalar or an array of type @code{REAL};
1682 for @code{BESSEL_JN(N1, N2, X)} it shall be scalar.
1685 @item @emph{Return value}:
1686 The return value is a scalar of type @code{REAL}. It has the same
1690 The transformational function uses a recurrence algorithm which might,
1691 for some values of @var{X}, lead to different results than calls to
1692 the elemental function.
1694 @item @emph{Example}:
1697 real(8) :: x = 1.0_8
1699 end program test_besjn
1702 @item @emph{Specific names}:
1703 @multitable @columnfractions .20 .20 .20 .25
1704 @item Name @tab Argument @tab Return type @tab Standard
1705 @item @code{DBESJN(N, X)} @tab @code{INTEGER N} @tab @code{REAL(8)} @tab GNU extension
1706 @item @tab @code{REAL(8) X} @tab @tab
1713 @section @code{BESSEL_Y0} --- Bessel function of the second kind of order 0
1717 @cindex Bessel function, second kind
1720 @item @emph{Description}:
1721 @code{BESSEL_Y0(X)} computes the Bessel function of the second kind of
1722 order 0 of @var{X}. This function is available under the name
1723 @code{BESY0} as a GNU extension.
1725 @item @emph{Standard}:
1726 Fortran 2008 and later
1731 @item @emph{Syntax}:
1732 @code{RESULT = BESSEL_Y0(X)}
1734 @item @emph{Arguments}:
1735 @multitable @columnfractions .15 .70
1736 @item @var{X} @tab The type shall be @code{REAL}, and it shall be scalar.
1739 @item @emph{Return value}:
1740 The return value is a scalar of type @code{REAL}. It has the same
1743 @item @emph{Example}:
1746 real(8) :: x = 0.0_8
1748 end program test_besy0
1751 @item @emph{Specific names}:
1752 @multitable @columnfractions .20 .20 .20 .25
1753 @item Name @tab Argument @tab Return type @tab Standard
1754 @item @code{DBESY0(X)}@tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU extension
1761 @section @code{BESSEL_Y1} --- Bessel function of the second kind of order 1
1765 @cindex Bessel function, second kind
1768 @item @emph{Description}:
1769 @code{BESSEL_Y1(X)} computes the Bessel function of the second kind of
1770 order 1 of @var{X}. This function is available under the name
1771 @code{BESY1} as a GNU extension.
1773 @item @emph{Standard}:
1774 Fortran 2008 and later
1779 @item @emph{Syntax}:
1780 @code{RESULT = BESSEL_Y1(X)}
1782 @item @emph{Arguments}:
1783 @multitable @columnfractions .15 .70
1784 @item @var{X} @tab The type shall be @code{REAL}, and it shall be scalar.
1787 @item @emph{Return value}:
1788 The return value is a scalar of type @code{REAL}. It has the same
1791 @item @emph{Example}:
1794 real(8) :: x = 1.0_8
1796 end program test_besy1
1799 @item @emph{Specific names}:
1800 @multitable @columnfractions .20 .20 .20 .25
1801 @item Name @tab Argument @tab Return type @tab Standard
1802 @item @code{DBESY1(X)}@tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU extension
1809 @section @code{BESSEL_YN} --- Bessel function of the second kind
1813 @cindex Bessel function, second kind
1816 @item @emph{Description}:
1817 @code{BESSEL_YN(N, X)} computes the Bessel function of the second kind of
1818 order @var{N} of @var{X}. This function is available under the name
1819 @code{BESYN} as a GNU extension. If @var{N} and @var{X} are arrays,
1820 their ranks and shapes shall conform.
1822 @code{BESSEL_YN(N1, N2, X)} returns an array with the Bessel functions
1823 of the first kind of the orders @var{N1} to @var{N2}.
1825 @item @emph{Standard}:
1826 Fortran 2008 and later, negative @var{N} is allowed as GNU extension
1829 Elemental function, except for the transformational function
1830 @code{BESSEL_YN(N1, N2, X)}
1832 @item @emph{Syntax}:
1833 @multitable @columnfractions .80
1834 @item @code{RESULT = BESSEL_YN(N, X)}
1835 @item @code{RESULT = BESSEL_YN(N1, N2, X)}
1838 @item @emph{Arguments}:
1839 @multitable @columnfractions .15 .70
1840 @item @var{N} @tab Shall be a scalar or an array of type @code{INTEGER} .
1841 @item @var{N1} @tab Shall be a non-negative scalar of type @code{INTEGER}.
1842 @item @var{N2} @tab Shall be a non-negative scalar of type @code{INTEGER}.
1843 @item @var{X} @tab Shall be a scalar or an array of type @code{REAL};
1844 for @code{BESSEL_YN(N1, N2, X)} it shall be scalar.
1847 @item @emph{Return value}:
1848 The return value is a scalar of type @code{REAL}. It has the same
1852 The transformational function uses a recurrence algorithm which might,
1853 for some values of @var{X}, lead to different results than calls to
1854 the elemental function.
1856 @item @emph{Example}:
1859 real(8) :: x = 1.0_8
1861 end program test_besyn
1864 @item @emph{Specific names}:
1865 @multitable @columnfractions .20 .20 .20 .25
1866 @item Name @tab Argument @tab Return type @tab Standard
1867 @item @code{DBESYN(N,X)} @tab @code{INTEGER N} @tab @code{REAL(8)} @tab GNU extension
1868 @item @tab @code{REAL(8) X} @tab @tab
1875 @section @code{BGE} --- Bitwise greater than or equal to
1877 @cindex bitwise comparison
1880 @item @emph{Description}:
1881 Determines whether an integral is a bitwise greater than or equal to
1884 @item @emph{Standard}:
1885 Fortran 2008 and later
1890 @item @emph{Syntax}:
1891 @code{RESULT = BGE(I, J)}
1893 @item @emph{Arguments}:
1894 @multitable @columnfractions .15 .70
1895 @item @var{I} @tab Shall be of @code{INTEGER} type.
1896 @item @var{J} @tab Shall be of @code{INTEGER} type, and of the same kind
1900 @item @emph{Return value}:
1901 The return value is of type @code{LOGICAL} and of the default kind.
1903 @item @emph{See also}:
1904 @ref{BGT}, @ref{BLE}, @ref{BLT}
1910 @section @code{BGT} --- Bitwise greater than
1912 @cindex bitwise comparison
1915 @item @emph{Description}:
1916 Determines whether an integral is a bitwise greater than another.
1918 @item @emph{Standard}:
1919 Fortran 2008 and later
1924 @item @emph{Syntax}:
1925 @code{RESULT = BGT(I, J)}
1927 @item @emph{Arguments}:
1928 @multitable @columnfractions .15 .70
1929 @item @var{I} @tab Shall be of @code{INTEGER} type.
1930 @item @var{J} @tab Shall be of @code{INTEGER} type, and of the same kind
1934 @item @emph{Return value}:
1935 The return value is of type @code{LOGICAL} and of the default kind.
1937 @item @emph{See also}:
1938 @ref{BGE}, @ref{BLE}, @ref{BLT}
1944 @section @code{BIT_SIZE} --- Bit size inquiry function
1946 @cindex bits, number of
1947 @cindex size of a variable, in bits
1950 @item @emph{Description}:
1951 @code{BIT_SIZE(I)} returns the number of bits (integer precision plus sign bit)
1952 represented by the type of @var{I}. The result of @code{BIT_SIZE(I)} is
1953 independent of the actual value of @var{I}.
1955 @item @emph{Standard}:
1956 Fortran 95 and later
1961 @item @emph{Syntax}:
1962 @code{RESULT = BIT_SIZE(I)}
1964 @item @emph{Arguments}:
1965 @multitable @columnfractions .15 .70
1966 @item @var{I} @tab The type shall be @code{INTEGER}.
1969 @item @emph{Return value}:
1970 The return value is of type @code{INTEGER}
1972 @item @emph{Example}:
1974 program test_bit_size
1979 end program test_bit_size
1986 @section @code{BLE} --- Bitwise less than or equal to
1988 @cindex bitwise comparison
1991 @item @emph{Description}:
1992 Determines whether an integral is a bitwise less than or equal to
1995 @item @emph{Standard}:
1996 Fortran 2008 and later
2001 @item @emph{Syntax}:
2002 @code{RESULT = BLE(I, J)}
2004 @item @emph{Arguments}:
2005 @multitable @columnfractions .15 .70
2006 @item @var{I} @tab Shall be of @code{INTEGER} type.
2007 @item @var{J} @tab Shall be of @code{INTEGER} type, and of the same kind
2011 @item @emph{Return value}:
2012 The return value is of type @code{LOGICAL} and of the default kind.
2014 @item @emph{See also}:
2015 @ref{BGT}, @ref{BGE}, @ref{BLT}
2021 @section @code{BLT} --- Bitwise less than
2023 @cindex bitwise comparison
2026 @item @emph{Description}:
2027 Determines whether an integral is a bitwise less than another.
2029 @item @emph{Standard}:
2030 Fortran 2008 and later
2035 @item @emph{Syntax}:
2036 @code{RESULT = BLT(I, J)}
2038 @item @emph{Arguments}:
2039 @multitable @columnfractions .15 .70
2040 @item @var{I} @tab Shall be of @code{INTEGER} type.
2041 @item @var{J} @tab Shall be of @code{INTEGER} type, and of the same kind
2045 @item @emph{Return value}:
2046 The return value is of type @code{LOGICAL} and of the default kind.
2048 @item @emph{See also}:
2049 @ref{BGE}, @ref{BGT}, @ref{BLE}
2055 @section @code{BTEST} --- Bit test function
2057 @cindex bits, testing
2060 @item @emph{Description}:
2061 @code{BTEST(I,POS)} returns logical @code{.TRUE.} if the bit at @var{POS}
2062 in @var{I} is set. The counting of the bits starts at 0.
2064 @item @emph{Standard}:
2065 Fortran 95 and later
2070 @item @emph{Syntax}:
2071 @code{RESULT = BTEST(I, POS)}
2073 @item @emph{Arguments}:
2074 @multitable @columnfractions .15 .70
2075 @item @var{I} @tab The type shall be @code{INTEGER}.
2076 @item @var{POS} @tab The type shall be @code{INTEGER}.
2079 @item @emph{Return value}:
2080 The return value is of type @code{LOGICAL}
2082 @item @emph{Example}:
2085 integer :: i = 32768 + 1024 + 64
2089 bool = btest(i, pos)
2092 end program test_btest
2098 @section @code{C_ASSOCIATED} --- Status of a C pointer
2099 @fnindex C_ASSOCIATED
2100 @cindex association status, C pointer
2101 @cindex pointer, C association status
2104 @item @emph{Description}:
2105 @code{C_ASSOCIATED(c_prt_1[, c_ptr_2])} determines the status of the C pointer
2106 @var{c_ptr_1} or if @var{c_ptr_1} is associated with the target @var{c_ptr_2}.
2108 @item @emph{Standard}:
2109 Fortran 2003 and later
2114 @item @emph{Syntax}:
2115 @code{RESULT = C_ASSOCIATED(c_prt_1[, c_ptr_2])}
2117 @item @emph{Arguments}:
2118 @multitable @columnfractions .15 .70
2119 @item @var{c_ptr_1} @tab Scalar of the type @code{C_PTR} or @code{C_FUNPTR}.
2120 @item @var{c_ptr_2} @tab (Optional) Scalar of the same type as @var{c_ptr_1}.
2123 @item @emph{Return value}:
2124 The return value is of type @code{LOGICAL}; it is @code{.false.} if either
2125 @var{c_ptr_1} is a C NULL pointer or if @var{c_ptr1} and @var{c_ptr_2}
2126 point to different addresses.
2128 @item @emph{Example}:
2130 subroutine association_test(a,b)
2131 use iso_c_binding, only: c_associated, c_loc, c_ptr
2135 if(c_associated(b, c_loc(a))) &
2136 stop 'b and a do not point to same target'
2137 end subroutine association_test
2140 @item @emph{See also}:
2141 @ref{C_LOC}, @ref{C_FUNLOC}
2146 @section @code{C_FUNLOC} --- Obtain the C address of a procedure
2148 @cindex pointer, C address of procedures
2151 @item @emph{Description}:
2152 @code{C_FUNLOC(x)} determines the C address of the argument.
2154 @item @emph{Standard}:
2155 Fortran 2003 and later
2160 @item @emph{Syntax}:
2161 @code{RESULT = C_FUNLOC(x)}
2163 @item @emph{Arguments}:
2164 @multitable @columnfractions .15 .70
2165 @item @var{x} @tab Interoperable function or pointer to such function.
2168 @item @emph{Return value}:
2169 The return value is of type @code{C_FUNPTR} and contains the C address
2172 @item @emph{Example}:
2178 subroutine sub(a) bind(c)
2188 subroutine my_routine(p) bind(c,name='myC_func')
2190 type(c_funptr), intent(in) :: p
2193 call my_routine(c_funloc(sub))
2197 @item @emph{See also}:
2198 @ref{C_ASSOCIATED}, @ref{C_LOC}, @ref{C_F_POINTER}, @ref{C_F_PROCPOINTER}
2202 @node C_F_PROCPOINTER
2203 @section @code{C_F_PROCPOINTER} --- Convert C into Fortran procedure pointer
2204 @fnindex C_F_PROCPOINTER
2205 @cindex pointer, C address of pointers
2208 @item @emph{Description}:
2209 @code{C_F_PROCPOINTER(CPTR, FPTR)} Assign the target of the C function pointer
2210 @var{CPTR} to the Fortran procedure pointer @var{FPTR}.
2212 @item @emph{Standard}:
2213 Fortran 2003 and later
2218 @item @emph{Syntax}:
2219 @code{CALL C_F_PROCPOINTER(cptr, fptr)}
2221 @item @emph{Arguments}:
2222 @multitable @columnfractions .15 .70
2223 @item @var{CPTR} @tab scalar of the type @code{C_FUNPTR}. It is
2225 @item @var{FPTR} @tab procedure pointer interoperable with @var{cptr}. It is
2229 @item @emph{Example}:
2237 real(c_float), intent(in) :: a
2238 real(c_float) :: func
2242 function getIterFunc() bind(c,name="getIterFunc")
2244 type(c_funptr) :: getIterFunc
2247 type(c_funptr) :: cfunptr
2248 procedure(func), pointer :: myFunc
2249 cfunptr = getIterFunc()
2250 call c_f_procpointer(cfunptr, myFunc)
2254 @item @emph{See also}:
2255 @ref{C_LOC}, @ref{C_F_POINTER}
2260 @section @code{C_F_POINTER} --- Convert C into Fortran pointer
2261 @fnindex C_F_POINTER
2262 @cindex pointer, convert C to Fortran
2265 @item @emph{Description}:
2266 @code{C_F_POINTER(CPTR, FPTR[, SHAPE])} Assign the target the C pointer
2267 @var{CPTR} to the Fortran pointer @var{FPTR} and specify its
2270 @item @emph{Standard}:
2271 Fortran 2003 and later
2276 @item @emph{Syntax}:
2277 @code{CALL C_F_POINTER(CPTR, FPTR[, SHAPE])}
2279 @item @emph{Arguments}:
2280 @multitable @columnfractions .15 .70
2281 @item @var{CPTR} @tab scalar of the type @code{C_PTR}. It is
2283 @item @var{FPTR} @tab pointer interoperable with @var{cptr}. It is
2285 @item @var{SHAPE} @tab (Optional) Rank-one array of type @code{INTEGER}
2286 with @code{INTENT(IN)}. It shall be present
2287 if and only if @var{fptr} is an array. The size
2288 must be equal to the rank of @var{fptr}.
2291 @item @emph{Example}:
2297 subroutine my_routine(p) bind(c,name='myC_func')
2299 type(c_ptr), intent(out) :: p
2303 real,pointer :: a(:)
2304 call my_routine(cptr)
2305 call c_f_pointer(cptr, a, [12])
2309 @item @emph{See also}:
2310 @ref{C_LOC}, @ref{C_F_PROCPOINTER}
2315 @section @code{C_LOC} --- Obtain the C address of an object
2317 @cindex procedure pointer, convert C to Fortran
2320 @item @emph{Description}:
2321 @code{C_LOC(X)} determines the C address of the argument.
2323 @item @emph{Standard}:
2324 Fortran 2003 and later
2329 @item @emph{Syntax}:
2330 @code{RESULT = C_LOC(X)}
2332 @item @emph{Arguments}:
2333 @multitable @columnfractions .10 .75
2334 @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.
2338 @item @emph{Return value}:
2339 The return value is of type @code{C_PTR} and contains the C address
2342 @item @emph{Example}:
2344 subroutine association_test(a,b)
2345 use iso_c_binding, only: c_associated, c_loc, c_ptr
2349 if(c_associated(b, c_loc(a))) &
2350 stop 'b and a do not point to same target'
2351 end subroutine association_test
2354 @item @emph{See also}:
2355 @ref{C_ASSOCIATED}, @ref{C_FUNLOC}, @ref{C_F_POINTER}, @ref{C_F_PROCPOINTER}
2360 @section @code{C_SIZEOF} --- Size in bytes of an expression
2362 @cindex expression size
2363 @cindex size of an expression
2366 @item @emph{Description}:
2367 @code{C_SIZEOF(X)} calculates the number of bytes of storage the
2368 expression @code{X} occupies.
2370 @item @emph{Standard}:
2374 Inquiry function of the module @code{ISO_C_BINDING}
2376 @item @emph{Syntax}:
2377 @code{N = C_SIZEOF(X)}
2379 @item @emph{Arguments}:
2380 @multitable @columnfractions .15 .70
2381 @item @var{X} @tab The argument shall be an interoperable data entity.
2384 @item @emph{Return value}:
2385 The return value is of type integer and of the system-dependent kind
2386 @code{C_SIZE_T} (from the @code{ISO_C_BINDING} module). Its value is the
2387 number of bytes occupied by the argument. If the argument has the
2388 @code{POINTER} attribute, the number of bytes of the storage area pointed
2389 to is returned. If the argument is of a derived type with @code{POINTER}
2390 or @code{ALLOCATABLE} components, the return value doesn't account for
2391 the sizes of the data pointed to by these components.
2393 @item @emph{Example}:
2397 real(c_float) :: r, s(5)
2398 print *, (c_sizeof(s)/c_sizeof(r) == 5)
2401 The example will print @code{.TRUE.} unless you are using a platform
2402 where default @code{REAL} variables are unusually padded.
2404 @item @emph{See also}:
2405 @ref{SIZEOF}, @ref{STORAGE_SIZE}
2410 @section @code{CEILING} --- Integer ceiling function
2413 @cindex rounding, ceiling
2416 @item @emph{Description}:
2417 @code{CEILING(A)} returns the least integer greater than or equal to @var{A}.
2419 @item @emph{Standard}:
2420 Fortran 95 and later
2425 @item @emph{Syntax}:
2426 @code{RESULT = CEILING(A [, KIND])}
2428 @item @emph{Arguments}:
2429 @multitable @columnfractions .15 .70
2430 @item @var{A} @tab The type shall be @code{REAL}.
2431 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
2432 expression indicating the kind parameter of the result.
2435 @item @emph{Return value}:
2436 The return value is of type @code{INTEGER(KIND)} if @var{KIND} is present
2437 and a default-kind @code{INTEGER} otherwise.
2439 @item @emph{Example}:
2441 program test_ceiling
2444 print *, ceiling(x) ! returns 64
2445 print *, ceiling(y) ! returns -63
2446 end program test_ceiling
2449 @item @emph{See also}:
2450 @ref{FLOOR}, @ref{NINT}
2457 @section @code{CHAR} --- Character conversion function
2459 @cindex conversion, to character
2462 @item @emph{Description}:
2463 @code{CHAR(I [, KIND])} returns the character represented by the integer @var{I}.
2465 @item @emph{Standard}:
2466 Fortran 77 and later
2471 @item @emph{Syntax}:
2472 @code{RESULT = CHAR(I [, KIND])}
2474 @item @emph{Arguments}:
2475 @multitable @columnfractions .15 .70
2476 @item @var{I} @tab The type shall be @code{INTEGER}.
2477 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
2478 expression indicating the kind parameter of the result.
2481 @item @emph{Return value}:
2482 The return value is of type @code{CHARACTER(1)}
2484 @item @emph{Example}:
2490 print *, i, c ! returns 'J'
2491 end program test_char
2494 @item @emph{Specific names}:
2495 @multitable @columnfractions .20 .20 .20 .25
2496 @item Name @tab Argument @tab Return type @tab Standard
2497 @item @code{CHAR(I)} @tab @code{INTEGER I} @tab @code{CHARACTER(LEN=1)} @tab F77 and later
2501 See @ref{ICHAR} for a discussion of converting between numerical values
2502 and formatted string representations.
2504 @item @emph{See also}:
2505 @ref{ACHAR}, @ref{IACHAR}, @ref{ICHAR}
2512 @section @code{CHDIR} --- Change working directory
2514 @cindex system, working directory
2517 @item @emph{Description}:
2518 Change current working directory to a specified path.
2520 This intrinsic is provided in both subroutine and function forms; however,
2521 only one form can be used in any given program unit.
2523 @item @emph{Standard}:
2527 Subroutine, function
2529 @item @emph{Syntax}:
2530 @multitable @columnfractions .80
2531 @item @code{CALL CHDIR(NAME [, STATUS])}
2532 @item @code{STATUS = CHDIR(NAME)}
2535 @item @emph{Arguments}:
2536 @multitable @columnfractions .15 .70
2537 @item @var{NAME} @tab The type shall be @code{CHARACTER} of default
2538 kind and shall specify a valid path within the file system.
2539 @item @var{STATUS} @tab (Optional) @code{INTEGER} status flag of the default
2540 kind. Returns 0 on success, and a system specific and nonzero error code
2544 @item @emph{Example}:
2547 CHARACTER(len=255) :: path
2549 WRITE(*,*) TRIM(path)
2552 WRITE(*,*) TRIM(path)
2556 @item @emph{See also}:
2563 @section @code{CHMOD} --- Change access permissions of files
2565 @cindex file system, change access mode
2568 @item @emph{Description}:
2569 @code{CHMOD} changes the permissions of a file. This function invokes
2570 @code{/bin/chmod} and might therefore not work on all platforms.
2572 This intrinsic is provided in both subroutine and function forms; however,
2573 only one form can be used in any given program unit.
2575 @item @emph{Standard}:
2579 Subroutine, function
2581 @item @emph{Syntax}:
2582 @multitable @columnfractions .80
2583 @item @code{CALL CHMOD(NAME, MODE[, STATUS])}
2584 @item @code{STATUS = CHMOD(NAME, MODE)}
2587 @item @emph{Arguments}:
2588 @multitable @columnfractions .15 .70
2590 @item @var{NAME} @tab Scalar @code{CHARACTER} of default kind with the
2591 file name. Trailing blanks are ignored unless the character
2592 @code{achar(0)} is present, then all characters up to and excluding
2593 @code{achar(0)} are used as the file name.
2595 @item @var{MODE} @tab Scalar @code{CHARACTER} of default kind giving the
2596 file permission. @var{MODE} uses the same syntax as the @var{MODE}
2597 argument of @code{/bin/chmod}.
2599 @item @var{STATUS} @tab (optional) scalar @code{INTEGER}, which is
2600 @code{0} on success and nonzero otherwise.
2603 @item @emph{Return value}:
2604 In either syntax, @var{STATUS} is set to @code{0} on success and nonzero
2607 @item @emph{Example}:
2608 @code{CHMOD} as subroutine
2613 call chmod('test.dat','u+x',status)
2614 print *, 'Status: ', status
2615 end program chmod_test
2617 @code{CHMOD} as function:
2622 status = chmod('test.dat','u+x')
2623 print *, 'Status: ', status
2624 end program chmod_test
2632 @section @code{CMPLX} --- Complex conversion function
2634 @cindex complex numbers, conversion to
2635 @cindex conversion, to complex
2638 @item @emph{Description}:
2639 @code{CMPLX(X [, Y [, KIND]])} returns a complex number where @var{X} is converted to
2640 the real component. If @var{Y} is present it is converted to the imaginary
2641 component. If @var{Y} is not present then the imaginary component is set to
2642 0.0. If @var{X} is complex then @var{Y} must not be present.
2644 @item @emph{Standard}:
2645 Fortran 77 and later
2650 @item @emph{Syntax}:
2651 @code{RESULT = CMPLX(X [, Y [, KIND]])}
2653 @item @emph{Arguments}:
2654 @multitable @columnfractions .15 .70
2655 @item @var{X} @tab The type may be @code{INTEGER}, @code{REAL},
2657 @item @var{Y} @tab (Optional; only allowed if @var{X} is not
2658 @code{COMPLEX}.) May be @code{INTEGER} or @code{REAL}.
2659 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
2660 expression indicating the kind parameter of the result.
2663 @item @emph{Return value}:
2664 The return value is of @code{COMPLEX} type, with a kind equal to
2665 @var{KIND} if it is specified. If @var{KIND} is not specified, the
2666 result is of the default @code{COMPLEX} kind, regardless of the kinds of
2667 @var{X} and @var{Y}.
2669 @item @emph{Example}:
2676 print *, z, cmplx(x)
2677 end program test_cmplx
2680 @item @emph{See also}:
2686 @node COMMAND_ARGUMENT_COUNT
2687 @section @code{COMMAND_ARGUMENT_COUNT} --- Get number of command line arguments
2688 @fnindex COMMAND_ARGUMENT_COUNT
2689 @cindex command-line arguments
2690 @cindex command-line arguments, number of
2691 @cindex arguments, to program
2694 @item @emph{Description}:
2695 @code{COMMAND_ARGUMENT_COUNT} returns the number of arguments passed on the
2696 command line when the containing program was invoked.
2698 @item @emph{Standard}:
2699 Fortran 2003 and later
2704 @item @emph{Syntax}:
2705 @code{RESULT = COMMAND_ARGUMENT_COUNT()}
2707 @item @emph{Arguments}:
2708 @multitable @columnfractions .15 .70
2712 @item @emph{Return value}:
2713 The return value is an @code{INTEGER} of default kind.
2715 @item @emph{Example}:
2717 program test_command_argument_count
2719 count = command_argument_count()
2721 end program test_command_argument_count
2724 @item @emph{See also}:
2725 @ref{GET_COMMAND}, @ref{GET_COMMAND_ARGUMENT}
2730 @node COMPILER_OPTIONS
2731 @section @code{COMPILER_OPTIONS} --- Options passed to the compiler
2732 @fnindex COMPILER_OPTIONS
2733 @cindex flags inquiry function
2734 @cindex options inquiry function
2735 @cindex compiler flags inquiry function
2738 @item @emph{Description}:
2739 @code{COMPILER_OPTIONS} returns a string with the options used for
2742 @item @emph{Standard}:
2746 Inquiry function of the module @code{ISO_FORTRAN_ENV}
2748 @item @emph{Syntax}:
2749 @code{STR = COMPILER_OPTIONS()}
2751 @item @emph{Arguments}:
2754 @item @emph{Return value}:
2755 The return value is a default-kind string with system-dependent length.
2756 It contains the compiler flags used to compile the file, which called
2757 the @code{COMPILER_OPTIONS} intrinsic.
2759 @item @emph{Example}:
2762 print '(4a)', 'This file was compiled by ', &
2763 compiler_version(), ' using the options ', &
2768 @item @emph{See also}:
2769 @ref{COMPILER_VERSION}, @ref{ISO_FORTRAN_ENV}
2774 @node COMPILER_VERSION
2775 @section @code{COMPILER_VERSION} --- Compiler version string
2776 @fnindex COMPILER_VERSION
2777 @cindex compiler, name and version
2778 @cindex version of the compiler
2781 @item @emph{Description}:
2782 @code{COMPILER_VERSION} returns a string with the name and the
2783 version of the compiler.
2785 @item @emph{Standard}:
2789 Inquiry function of the module @code{ISO_FORTRAN_ENV}
2791 @item @emph{Syntax}:
2792 @code{STR = COMPILER_VERSION()}
2794 @item @emph{Arguments}:
2797 @item @emph{Return value}:
2798 The return value is a default-kind string with system-dependent length.
2799 It contains the name of the compiler and its version number.
2801 @item @emph{Example}:
2804 print '(4a)', 'This file was compiled by ', &
2805 compiler_version(), ' using the options ', &
2810 @item @emph{See also}:
2811 @ref{COMPILER_OPTIONS}, @ref{ISO_FORTRAN_ENV}
2817 @section @code{COMPLEX} --- Complex conversion function
2819 @cindex complex numbers, conversion to
2820 @cindex conversion, to complex
2823 @item @emph{Description}:
2824 @code{COMPLEX(X, Y)} returns a complex number where @var{X} is converted
2825 to the real component and @var{Y} is converted to the imaginary
2828 @item @emph{Standard}:
2834 @item @emph{Syntax}:
2835 @code{RESULT = COMPLEX(X, Y)}
2837 @item @emph{Arguments}:
2838 @multitable @columnfractions .15 .70
2839 @item @var{X} @tab The type may be @code{INTEGER} or @code{REAL}.
2840 @item @var{Y} @tab The type may be @code{INTEGER} or @code{REAL}.
2843 @item @emph{Return value}:
2844 If @var{X} and @var{Y} are both of @code{INTEGER} type, then the return
2845 value is of default @code{COMPLEX} type.
2847 If @var{X} and @var{Y} are of @code{REAL} type, or one is of @code{REAL}
2848 type and one is of @code{INTEGER} type, then the return value is of
2849 @code{COMPLEX} type with a kind equal to that of the @code{REAL}
2850 argument with the highest precision.
2852 @item @emph{Example}:
2854 program test_complex
2857 print *, complex(i, x)
2858 end program test_complex
2861 @item @emph{See also}:
2868 @section @code{CONJG} --- Complex conjugate function
2871 @cindex complex conjugate
2874 @item @emph{Description}:
2875 @code{CONJG(Z)} returns the conjugate of @var{Z}. If @var{Z} is @code{(x, y)}
2876 then the result is @code{(x, -y)}
2878 @item @emph{Standard}:
2879 Fortran 77 and later, has overloads that are GNU extensions
2884 @item @emph{Syntax}:
2887 @item @emph{Arguments}:
2888 @multitable @columnfractions .15 .70
2889 @item @var{Z} @tab The type shall be @code{COMPLEX}.
2892 @item @emph{Return value}:
2893 The return value is of type @code{COMPLEX}.
2895 @item @emph{Example}:
2898 complex :: z = (2.0, 3.0)
2899 complex(8) :: dz = (2.71_8, -3.14_8)
2904 end program test_conjg
2907 @item @emph{Specific names}:
2908 @multitable @columnfractions .20 .20 .20 .25
2909 @item Name @tab Argument @tab Return type @tab Standard
2910 @item @code{CONJG(Z)} @tab @code{COMPLEX Z} @tab @code{COMPLEX} @tab GNU extension
2911 @item @code{DCONJG(Z)} @tab @code{COMPLEX(8) Z} @tab @code{COMPLEX(8)} @tab GNU extension
2918 @section @code{COS} --- Cosine function
2924 @cindex trigonometric function, cosine
2928 @item @emph{Description}:
2929 @code{COS(X)} computes the cosine of @var{X}.
2931 @item @emph{Standard}:
2932 Fortran 77 and later, has overloads that are GNU extensions
2937 @item @emph{Syntax}:
2938 @code{RESULT = COS(X)}
2940 @item @emph{Arguments}:
2941 @multitable @columnfractions .15 .70
2942 @item @var{X} @tab The type shall be @code{REAL} or
2946 @item @emph{Return value}:
2947 The return value is of the same type and kind as @var{X}. The real part
2948 of the result is in radians. If @var{X} is of the type @code{REAL},
2949 the return value lies in the range @math{ -1 \leq \cos (x) \leq 1}.
2951 @item @emph{Example}:
2956 end program test_cos
2959 @item @emph{Specific names}:
2960 @multitable @columnfractions .20 .20 .20 .25
2961 @item Name @tab Argument @tab Return type @tab Standard
2962 @item @code{COS(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab Fortran 77 and later
2963 @item @code{DCOS(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab Fortran 77 and later
2964 @item @code{CCOS(X)} @tab @code{COMPLEX(4) X} @tab @code{COMPLEX(4)} @tab Fortran 77 and later
2965 @item @code{ZCOS(X)} @tab @code{COMPLEX(8) X} @tab @code{COMPLEX(8)} @tab GNU extension
2966 @item @code{CDCOS(X)} @tab @code{COMPLEX(8) X} @tab @code{COMPLEX(8)} @tab GNU extension
2969 @item @emph{See also}:
2970 Inverse function: @ref{ACOS}
2977 @section @code{COSH} --- Hyperbolic cosine function
2980 @cindex hyperbolic cosine
2981 @cindex hyperbolic function, cosine
2982 @cindex cosine, hyperbolic
2985 @item @emph{Description}:
2986 @code{COSH(X)} computes the hyperbolic cosine of @var{X}.
2988 @item @emph{Standard}:
2989 Fortran 77 and later, for a complex argument Fortran 2008 or later
2994 @item @emph{Syntax}:
2997 @item @emph{Arguments}:
2998 @multitable @columnfractions .15 .70
2999 @item @var{X} @tab The type shall be @code{REAL} or @code{COMPLEX}.
3002 @item @emph{Return value}:
3003 The return value has same type and kind as @var{X}. If @var{X} is
3004 complex, the imaginary part of the result is in radians. If @var{X}
3005 is @code{REAL}, the return value has a lower bound of one,
3006 @math{\cosh (x) \geq 1}.
3008 @item @emph{Example}:
3011 real(8) :: x = 1.0_8
3013 end program test_cosh
3016 @item @emph{Specific names}:
3017 @multitable @columnfractions .20 .20 .20 .25
3018 @item Name @tab Argument @tab Return type @tab Standard
3019 @item @code{COSH(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab Fortran 77 and later
3020 @item @code{DCOSH(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab Fortran 77 and later
3023 @item @emph{See also}:
3024 Inverse function: @ref{ACOSH}
3031 @section @code{COUNT} --- Count function
3033 @cindex array, conditionally count elements
3034 @cindex array, element counting
3035 @cindex array, number of elements
3038 @item @emph{Description}:
3040 Counts the number of @code{.TRUE.} elements in a logical @var{MASK},
3041 or, if the @var{DIM} argument is supplied, counts the number of
3042 elements along each row of the array in the @var{DIM} direction.
3043 If the array has zero size, or all of the elements of @var{MASK} are
3044 @code{.FALSE.}, then the result is @code{0}.
3046 @item @emph{Standard}:
3047 Fortran 95 and later, with @var{KIND} argument Fortran 2003 and later
3050 Transformational function
3052 @item @emph{Syntax}:
3053 @code{RESULT = COUNT(MASK [, DIM, KIND])}
3055 @item @emph{Arguments}:
3056 @multitable @columnfractions .15 .70
3057 @item @var{MASK} @tab The type shall be @code{LOGICAL}.
3058 @item @var{DIM} @tab (Optional) The type shall be @code{INTEGER}.
3059 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
3060 expression indicating the kind parameter of the result.
3063 @item @emph{Return value}:
3064 The return value is of type @code{INTEGER} and of kind @var{KIND}. If
3065 @var{KIND} is absent, the return value is of default integer kind.
3066 If @var{DIM} is present, the result is an array with a rank one less
3067 than the rank of @var{ARRAY}, and a size corresponding to the shape
3068 of @var{ARRAY} with the @var{DIM} dimension removed.
3070 @item @emph{Example}:
3073 integer, dimension(2,3) :: a, b
3074 logical, dimension(2,3) :: mask
3075 a = reshape( (/ 1, 2, 3, 4, 5, 6 /), (/ 2, 3 /))
3076 b = reshape( (/ 0, 7, 3, 4, 5, 8 /), (/ 2, 3 /))
3077 print '(3i3)', a(1,:)
3078 print '(3i3)', a(2,:)
3080 print '(3i3)', b(1,:)
3081 print '(3i3)', b(2,:)
3084 print '(3l3)', mask(1,:)
3085 print '(3l3)', mask(2,:)
3087 print '(3i3)', count(mask)
3089 print '(3i3)', count(mask, 1)
3091 print '(3i3)', count(mask, 2)
3092 end program test_count
3099 @section @code{CPU_TIME} --- CPU elapsed time in seconds
3101 @cindex time, elapsed
3104 @item @emph{Description}:
3105 Returns a @code{REAL} value representing the elapsed CPU time in
3106 seconds. This is useful for testing segments of code to determine
3109 If a time source is available, time will be reported with microsecond
3110 resolution. If no time source is available, @var{TIME} is set to
3113 Note that @var{TIME} may contain a, system dependent, arbitrary offset
3114 and may not start with @code{0.0}. For @code{CPU_TIME}, the absolute
3115 value is meaningless, only differences between subsequent calls to
3116 this subroutine, as shown in the example below, should be used.
3119 @item @emph{Standard}:
3120 Fortran 95 and later
3125 @item @emph{Syntax}:
3126 @code{CALL CPU_TIME(TIME)}
3128 @item @emph{Arguments}:
3129 @multitable @columnfractions .15 .70
3130 @item @var{TIME} @tab The type shall be @code{REAL} with @code{INTENT(OUT)}.
3133 @item @emph{Return value}:
3136 @item @emph{Example}:
3138 program test_cpu_time
3139 real :: start, finish
3140 call cpu_time(start)
3141 ! put code to test here
3142 call cpu_time(finish)
3143 print '("Time = ",f6.3," seconds.")',finish-start
3144 end program test_cpu_time
3147 @item @emph{See also}:
3148 @ref{SYSTEM_CLOCK}, @ref{DATE_AND_TIME}
3154 @section @code{CSHIFT} --- Circular shift elements of an array
3156 @cindex array, shift circularly
3157 @cindex array, permutation
3158 @cindex array, rotate
3161 @item @emph{Description}:
3162 @code{CSHIFT(ARRAY, SHIFT [, DIM])} performs a circular shift on elements of
3163 @var{ARRAY} along the dimension of @var{DIM}. If @var{DIM} is omitted it is
3164 taken to be @code{1}. @var{DIM} is a scalar of type @code{INTEGER} in the
3165 range of @math{1 \leq DIM \leq n)} where @math{n} is the rank of @var{ARRAY}.
3166 If the rank of @var{ARRAY} is one, then all elements of @var{ARRAY} are shifted
3167 by @var{SHIFT} places. If rank is greater than one, then all complete rank one
3168 sections of @var{ARRAY} along the given dimension are shifted. Elements
3169 shifted out one end of each rank one section are shifted back in the other end.
3171 @item @emph{Standard}:
3172 Fortran 95 and later
3175 Transformational function
3177 @item @emph{Syntax}:
3178 @code{RESULT = CSHIFT(ARRAY, SHIFT [, DIM])}
3180 @item @emph{Arguments}:
3181 @multitable @columnfractions .15 .70
3182 @item @var{ARRAY} @tab Shall be an array of any type.
3183 @item @var{SHIFT} @tab The type shall be @code{INTEGER}.
3184 @item @var{DIM} @tab The type shall be @code{INTEGER}.
3187 @item @emph{Return value}:
3188 Returns an array of same type and rank as the @var{ARRAY} argument.
3190 @item @emph{Example}:
3193 integer, dimension(3,3) :: a
3194 a = reshape( (/ 1, 2, 3, 4, 5, 6, 7, 8, 9 /), (/ 3, 3 /))
3195 print '(3i3)', a(1,:)
3196 print '(3i3)', a(2,:)
3197 print '(3i3)', a(3,:)
3198 a = cshift(a, SHIFT=(/1, 2, -1/), DIM=2)
3200 print '(3i3)', a(1,:)
3201 print '(3i3)', a(2,:)
3202 print '(3i3)', a(3,:)
3203 end program test_cshift
3210 @section @code{CTIME} --- Convert a time into a string
3212 @cindex time, conversion to string
3213 @cindex conversion, to string
3216 @item @emph{Description}:
3217 @code{CTIME} converts a system time value, such as returned by
3218 @code{TIME8}, to a string. Unless the application has called
3219 @code{setlocale}, the output will be in the default locale, of length
3220 24 and of the form @samp{Sat Aug 19 18:13:14 1995}. In other locales,
3221 a longer string may result.
3223 This intrinsic is provided in both subroutine and function forms; however,
3224 only one form can be used in any given program unit.
3226 @item @emph{Standard}:
3230 Subroutine, function
3232 @item @emph{Syntax}:
3233 @multitable @columnfractions .80
3234 @item @code{CALL CTIME(TIME, RESULT)}.
3235 @item @code{RESULT = CTIME(TIME)}.
3238 @item @emph{Arguments}:
3239 @multitable @columnfractions .15 .70
3240 @item @var{TIME} @tab The type shall be of type @code{INTEGER}.
3241 @item @var{RESULT} @tab The type shall be of type @code{CHARACTER} and
3242 of default kind. It is an @code{INTENT(OUT)} argument. If the length
3243 of this variable is too short for the time and date string to fit
3244 completely, it will be blank on procedure return.
3247 @item @emph{Return value}:
3248 The converted date and time as a string.
3250 @item @emph{Example}:
3254 character(len=30) :: date
3257 ! Do something, main part of the program
3260 print *, 'Program was started on ', date
3261 end program test_ctime
3264 @item @emph{See Also}:
3265 @ref{DATE_AND_TIME}, @ref{GMTIME}, @ref{LTIME}, @ref{TIME}, @ref{TIME8}
3271 @section @code{DATE_AND_TIME} --- Date and time subroutine
3272 @fnindex DATE_AND_TIME
3273 @cindex date, current
3274 @cindex current date
3275 @cindex time, current
3276 @cindex current time
3279 @item @emph{Description}:
3280 @code{DATE_AND_TIME(DATE, TIME, ZONE, VALUES)} gets the corresponding date and
3281 time information from the real-time system clock. @var{DATE} is
3282 @code{INTENT(OUT)} and has form ccyymmdd. @var{TIME} is @code{INTENT(OUT)} and
3283 has form hhmmss.sss. @var{ZONE} is @code{INTENT(OUT)} and has form (+-)hhmm,
3284 representing the difference with respect to Coordinated Universal Time (UTC).
3285 Unavailable time and date parameters return blanks.
3287 @var{VALUES} is @code{INTENT(OUT)} and provides the following:
3289 @multitable @columnfractions .15 .30 .40
3290 @item @tab @code{VALUE(1)}: @tab The year
3291 @item @tab @code{VALUE(2)}: @tab The month
3292 @item @tab @code{VALUE(3)}: @tab The day of the month
3293 @item @tab @code{VALUE(4)}: @tab Time difference with UTC in minutes
3294 @item @tab @code{VALUE(5)}: @tab The hour of the day
3295 @item @tab @code{VALUE(6)}: @tab The minutes of the hour
3296 @item @tab @code{VALUE(7)}: @tab The seconds of the minute
3297 @item @tab @code{VALUE(8)}: @tab The milliseconds of the second
3300 @item @emph{Standard}:
3301 Fortran 95 and later
3306 @item @emph{Syntax}:
3307 @code{CALL DATE_AND_TIME([DATE, TIME, ZONE, VALUES])}
3309 @item @emph{Arguments}:
3310 @multitable @columnfractions .15 .70
3311 @item @var{DATE} @tab (Optional) The type shall be @code{CHARACTER(LEN=8)}
3312 or larger, and of default kind.
3313 @item @var{TIME} @tab (Optional) The type shall be @code{CHARACTER(LEN=10)}
3314 or larger, and of default kind.
3315 @item @var{ZONE} @tab (Optional) The type shall be @code{CHARACTER(LEN=5)}
3316 or larger, and of default kind.
3317 @item @var{VALUES}@tab (Optional) The type shall be @code{INTEGER(8)}.
3320 @item @emph{Return value}:
3323 @item @emph{Example}:
3325 program test_time_and_date
3326 character(8) :: date
3327 character(10) :: time
3328 character(5) :: zone
3329 integer,dimension(8) :: values
3330 ! using keyword arguments
3331 call date_and_time(date,time,zone,values)
3332 call date_and_time(DATE=date,ZONE=zone)
3333 call date_and_time(TIME=time)
3334 call date_and_time(VALUES=values)
3335 print '(a,2x,a,2x,a)', date, time, zone
3336 print '(8i5))', values
3337 end program test_time_and_date
3340 @item @emph{See also}:
3341 @ref{CPU_TIME}, @ref{SYSTEM_CLOCK}
3347 @section @code{DBLE} --- Double conversion function
3349 @cindex conversion, to real
3352 @item @emph{Description}:
3353 @code{DBLE(A)} Converts @var{A} to double precision real type.
3355 @item @emph{Standard}:
3356 Fortran 77 and later
3361 @item @emph{Syntax}:
3362 @code{RESULT = DBLE(A)}
3364 @item @emph{Arguments}:
3365 @multitable @columnfractions .15 .70
3366 @item @var{A} @tab The type shall be @code{INTEGER}, @code{REAL},
3370 @item @emph{Return value}:
3371 The return value is of type double precision real.
3373 @item @emph{Example}:
3378 complex :: z = (2.3,1.14)
3379 print *, dble(x), dble(i), dble(z)
3380 end program test_dble
3383 @item @emph{See also}:
3390 @section @code{DCMPLX} --- Double complex conversion function
3392 @cindex complex numbers, conversion to
3393 @cindex conversion, to complex
3396 @item @emph{Description}:
3397 @code{DCMPLX(X [,Y])} returns a double complex number where @var{X} is
3398 converted to the real component. If @var{Y} is present it is converted to the
3399 imaginary component. If @var{Y} is not present then the imaginary component is
3400 set to 0.0. If @var{X} is complex then @var{Y} must not be present.
3402 @item @emph{Standard}:
3408 @item @emph{Syntax}:
3409 @code{RESULT = DCMPLX(X [, Y])}
3411 @item @emph{Arguments}:
3412 @multitable @columnfractions .15 .70
3413 @item @var{X} @tab The type may be @code{INTEGER}, @code{REAL},
3415 @item @var{Y} @tab (Optional if @var{X} is not @code{COMPLEX}.) May be
3416 @code{INTEGER} or @code{REAL}.
3419 @item @emph{Return value}:
3420 The return value is of type @code{COMPLEX(8)}
3422 @item @emph{Example}:
3432 print *, dcmplx(x,i)
3433 end program test_dcmplx
3439 @section @code{DIGITS} --- Significant binary digits function
3441 @cindex model representation, significant digits
3444 @item @emph{Description}:
3445 @code{DIGITS(X)} returns the number of significant binary digits of the internal
3446 model representation of @var{X}. For example, on a system using a 32-bit
3447 floating point representation, a default real number would likely return 24.
3449 @item @emph{Standard}:
3450 Fortran 95 and later
3455 @item @emph{Syntax}:
3456 @code{RESULT = DIGITS(X)}
3458 @item @emph{Arguments}:
3459 @multitable @columnfractions .15 .70
3460 @item @var{X} @tab The type may be @code{INTEGER} or @code{REAL}.
3463 @item @emph{Return value}:
3464 The return value is of type @code{INTEGER}.
3466 @item @emph{Example}:
3469 integer :: i = 12345
3475 end program test_digits
3482 @section @code{DIM} --- Positive difference
3486 @cindex positive difference
3489 @item @emph{Description}:
3490 @code{DIM(X,Y)} returns the difference @code{X-Y} if the result is positive;
3491 otherwise returns zero.
3493 @item @emph{Standard}:
3494 Fortran 77 and later
3499 @item @emph{Syntax}:
3500 @code{RESULT = DIM(X, Y)}
3502 @item @emph{Arguments}:
3503 @multitable @columnfractions .15 .70
3504 @item @var{X} @tab The type shall be @code{INTEGER} or @code{REAL}
3505 @item @var{Y} @tab The type shall be the same type and kind as @var{X}.
3508 @item @emph{Return value}:
3509 The return value is of type @code{INTEGER} or @code{REAL}.
3511 @item @emph{Example}:
3517 x = dim(4.345_8, 2.111_8)
3520 end program test_dim
3523 @item @emph{Specific names}:
3524 @multitable @columnfractions .20 .20 .20 .25
3525 @item Name @tab Argument @tab Return type @tab Standard
3526 @item @code{DIM(X,Y)} @tab @code{REAL(4) X, Y} @tab @code{REAL(4)} @tab Fortran 77 and later
3527 @item @code{IDIM(X,Y)} @tab @code{INTEGER(4) X, Y} @tab @code{INTEGER(4)} @tab Fortran 77 and later
3528 @item @code{DDIM(X,Y)} @tab @code{REAL(8) X, Y} @tab @code{REAL(8)} @tab Fortran 77 and later
3535 @section @code{DOT_PRODUCT} --- Dot product function
3536 @fnindex DOT_PRODUCT
3538 @cindex vector product
3539 @cindex product, vector
3542 @item @emph{Description}:
3543 @code{DOT_PRODUCT(VECTOR_A, VECTOR_B)} computes the dot product multiplication
3544 of two vectors @var{VECTOR_A} and @var{VECTOR_B}. The two vectors may be
3545 either numeric or logical and must be arrays of rank one and of equal size. If
3546 the vectors are @code{INTEGER} or @code{REAL}, the result is
3547 @code{SUM(VECTOR_A*VECTOR_B)}. If the vectors are @code{COMPLEX}, the result
3548 is @code{SUM(CONJG(VECTOR_A)*VECTOR_B)}. If the vectors are @code{LOGICAL},
3549 the result is @code{ANY(VECTOR_A .AND. VECTOR_B)}.
3551 @item @emph{Standard}:
3552 Fortran 95 and later
3555 Transformational function
3557 @item @emph{Syntax}:
3558 @code{RESULT = DOT_PRODUCT(VECTOR_A, VECTOR_B)}
3560 @item @emph{Arguments}:
3561 @multitable @columnfractions .15 .70
3562 @item @var{VECTOR_A} @tab The type shall be numeric or @code{LOGICAL}, rank 1.
3563 @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.
3566 @item @emph{Return value}:
3567 If the arguments are numeric, the return value is a scalar of numeric type,
3568 @code{INTEGER}, @code{REAL}, or @code{COMPLEX}. If the arguments are
3569 @code{LOGICAL}, the return value is @code{.TRUE.} or @code{.FALSE.}.
3571 @item @emph{Example}:
3573 program test_dot_prod
3574 integer, dimension(3) :: a, b
3581 print *, dot_product(a,b)
3582 end program test_dot_prod
3589 @section @code{DPROD} --- Double product function
3591 @cindex product, double-precision
3594 @item @emph{Description}:
3595 @code{DPROD(X,Y)} returns the product @code{X*Y}.
3597 @item @emph{Standard}:
3598 Fortran 77 and later
3603 @item @emph{Syntax}:
3604 @code{RESULT = DPROD(X, Y)}
3606 @item @emph{Arguments}:
3607 @multitable @columnfractions .15 .70
3608 @item @var{X} @tab The type shall be @code{REAL}.
3609 @item @var{Y} @tab The type shall be @code{REAL}.
3612 @item @emph{Return value}:
3613 The return value is of type @code{REAL(8)}.
3615 @item @emph{Example}:
3623 end program test_dprod
3626 @item @emph{Specific names}:
3627 @multitable @columnfractions .20 .20 .20 .25
3628 @item Name @tab Argument @tab Return type @tab Standard
3629 @item @code{DPROD(X,Y)} @tab @code{REAL(4) X, Y} @tab @code{REAL(4)} @tab Fortran 77 and later
3636 @section @code{DREAL} --- Double real part function
3638 @cindex complex numbers, real part
3641 @item @emph{Description}:
3642 @code{DREAL(Z)} returns the real part of complex variable @var{Z}.
3644 @item @emph{Standard}:
3650 @item @emph{Syntax}:
3651 @code{RESULT = DREAL(A)}
3653 @item @emph{Arguments}:
3654 @multitable @columnfractions .15 .70
3655 @item @var{A} @tab The type shall be @code{COMPLEX(8)}.
3658 @item @emph{Return value}:
3659 The return value is of type @code{REAL(8)}.
3661 @item @emph{Example}:
3664 complex(8) :: z = (1.3_8,7.2_8)
3666 end program test_dreal
3669 @item @emph{See also}:
3677 @section @code{DSHIFTL} --- Combined left shift
3679 @cindex left shift, combined
3683 @item @emph{Description}:
3684 @code{DSHIFTL(I, J, SHIFT)} combines bits of @var{I} and @var{J}. The
3685 rightmost @var{SHIFT} bits of the result are the leftmost @var{SHIFT}
3686 bits of @var{J}, and the remaining bits are the rightmost bits of
3689 @item @emph{Standard}:
3690 Fortran 2008 and later
3695 @item @emph{Syntax}:
3696 @code{RESULT = DSHIFTL(I, J, SHIFT)}
3698 @item @emph{Arguments}:
3699 @multitable @columnfractions .15 .70
3700 @item @var{I} @tab Shall be of type @code{INTEGER}.
3701 @item @var{J} @tab Shall be of type @code{INTEGER}, and of the same kind
3703 @item @var{SHIFT} @tab Shall be of type @code{INTEGER}.
3706 @item @emph{Return value}:
3707 The return value has same type and kind as @var{I}.
3709 @item @emph{See also}:
3717 @section @code{DSHIFTR} --- Combined right shift
3719 @cindex right shift, combined
3720 @cindex shift, right
3723 @item @emph{Description}:
3724 @code{DSHIFTR(I, J, SHIFT)} combines bits of @var{I} and @var{J}. The
3725 leftmost @var{SHIFT} bits of the result are the rightmost @var{SHIFT}
3726 bits of @var{I}, and the remaining bits are the leftmost bits of
3729 @item @emph{Standard}:
3730 Fortran 2008 and later
3735 @item @emph{Syntax}:
3736 @code{RESULT = DSHIFTR(I, J, SHIFT)}
3738 @item @emph{Arguments}:
3739 @multitable @columnfractions .15 .70
3740 @item @var{I} @tab Shall be of type @code{INTEGER}.
3741 @item @var{J} @tab Shall be of type @code{INTEGER}, and of the same kind
3743 @item @var{SHIFT} @tab Shall be of type @code{INTEGER}.
3746 @item @emph{Return value}:
3747 The return value has same type and kind as @var{I}.
3749 @item @emph{See also}:
3757 @section @code{DTIME} --- Execution time subroutine (or function)
3759 @cindex time, elapsed
3760 @cindex elapsed time
3763 @item @emph{Description}:
3764 @code{DTIME(VALUES, TIME)} initially returns the number of seconds of runtime
3765 since the start of the process's execution in @var{TIME}. @var{VALUES}
3766 returns the user and system components of this time in @code{VALUES(1)} and
3767 @code{VALUES(2)} respectively. @var{TIME} is equal to @code{VALUES(1) +
3770 Subsequent invocations of @code{DTIME} return values accumulated since the
3771 previous invocation.
3773 On some systems, the underlying timings are represented using types with
3774 sufficiently small limits that overflows (wrap around) are possible, such as
3775 32-bit types. Therefore, the values returned by this intrinsic might be, or
3776 become, negative, or numerically less than previous values, during a single
3777 run of the compiled program.
3779 Please note, that this implementation is thread safe if used within OpenMP
3780 directives, i.e., its state will be consistent while called from multiple
3781 threads. However, if @code{DTIME} is called from multiple threads, the result
3782 is still the time since the last invocation. This may not give the intended
3783 results. If possible, use @code{CPU_TIME} instead.
3785 This intrinsic is provided in both subroutine and function forms; however,
3786 only one form can be used in any given program unit.
3788 @var{VALUES} and @var{TIME} are @code{INTENT(OUT)} and provide the following:
3790 @multitable @columnfractions .15 .30 .40
3791 @item @tab @code{VALUES(1)}: @tab User time in seconds.
3792 @item @tab @code{VALUES(2)}: @tab System time in seconds.
3793 @item @tab @code{TIME}: @tab Run time since start in seconds.
3796 @item @emph{Standard}:
3800 Subroutine, function
3802 @item @emph{Syntax}:
3803 @multitable @columnfractions .80
3804 @item @code{CALL DTIME(VALUES, TIME)}.
3805 @item @code{TIME = DTIME(VALUES)}, (not recommended).
3808 @item @emph{Arguments}:
3809 @multitable @columnfractions .15 .70
3810 @item @var{VALUES}@tab The type shall be @code{REAL(4), DIMENSION(2)}.
3811 @item @var{TIME}@tab The type shall be @code{REAL(4)}.
3814 @item @emph{Return value}:
3815 Elapsed time in seconds since the last invocation or since the start of program
3816 execution if not called before.
3818 @item @emph{Example}:
3822 real, dimension(2) :: tarray
3824 call dtime(tarray, result)
3828 do i=1,100000000 ! Just a delay
3831 call dtime(tarray, result)
3835 end program test_dtime
3838 @item @emph{See also}:
3846 @section @code{EOSHIFT} --- End-off shift elements of an array
3848 @cindex array, shift
3851 @item @emph{Description}:
3852 @code{EOSHIFT(ARRAY, SHIFT[, BOUNDARY, DIM])} performs an end-off shift on
3853 elements of @var{ARRAY} along the dimension of @var{DIM}. If @var{DIM} is
3854 omitted it is taken to be @code{1}. @var{DIM} is a scalar of type
3855 @code{INTEGER} in the range of @math{1 \leq DIM \leq n)} where @math{n} is the
3856 rank of @var{ARRAY}. If the rank of @var{ARRAY} is one, then all elements of
3857 @var{ARRAY} are shifted by @var{SHIFT} places. If rank is greater than one,
3858 then all complete rank one sections of @var{ARRAY} along the given dimension are
3859 shifted. Elements shifted out one end of each rank one section are dropped. If
3860 @var{BOUNDARY} is present then the corresponding value of from @var{BOUNDARY}
3861 is copied back in the other end. If @var{BOUNDARY} is not present then the
3862 following are copied in depending on the type of @var{ARRAY}.
3864 @multitable @columnfractions .15 .80
3865 @item @emph{Array Type} @tab @emph{Boundary Value}
3866 @item Numeric @tab 0 of the type and kind of @var{ARRAY}.
3867 @item Logical @tab @code{.FALSE.}.
3868 @item Character(@var{len}) @tab @var{len} blanks.
3871 @item @emph{Standard}:
3872 Fortran 95 and later
3875 Transformational function
3877 @item @emph{Syntax}:
3878 @code{RESULT = EOSHIFT(ARRAY, SHIFT [, BOUNDARY, DIM])}
3880 @item @emph{Arguments}:
3881 @multitable @columnfractions .15 .70
3882 @item @var{ARRAY} @tab May be any type, not scalar.
3883 @item @var{SHIFT} @tab The type shall be @code{INTEGER}.
3884 @item @var{BOUNDARY} @tab Same type as @var{ARRAY}.
3885 @item @var{DIM} @tab The type shall be @code{INTEGER}.
3888 @item @emph{Return value}:
3889 Returns an array of same type and rank as the @var{ARRAY} argument.
3891 @item @emph{Example}:
3893 program test_eoshift
3894 integer, dimension(3,3) :: a
3895 a = reshape( (/ 1, 2, 3, 4, 5, 6, 7, 8, 9 /), (/ 3, 3 /))
3896 print '(3i3)', a(1,:)
3897 print '(3i3)', a(2,:)
3898 print '(3i3)', a(3,:)
3899 a = EOSHIFT(a, SHIFT=(/1, 2, 1/), BOUNDARY=-5, DIM=2)
3901 print '(3i3)', a(1,:)
3902 print '(3i3)', a(2,:)
3903 print '(3i3)', a(3,:)
3904 end program test_eoshift
3911 @section @code{EPSILON} --- Epsilon function
3913 @cindex model representation, epsilon
3916 @item @emph{Description}:
3917 @code{EPSILON(X)} returns the smallest number @var{E} of the same kind
3918 as @var{X} such that @math{1 + E > 1}.
3920 @item @emph{Standard}:
3921 Fortran 95 and later
3926 @item @emph{Syntax}:
3927 @code{RESULT = EPSILON(X)}
3929 @item @emph{Arguments}:
3930 @multitable @columnfractions .15 .70
3931 @item @var{X} @tab The type shall be @code{REAL}.
3934 @item @emph{Return value}:
3935 The return value is of same type as the argument.
3937 @item @emph{Example}:
3939 program test_epsilon
3944 end program test_epsilon
3951 @section @code{ERF} --- Error function
3953 @cindex error function
3956 @item @emph{Description}:
3957 @code{ERF(X)} computes the error function of @var{X}.
3959 @item @emph{Standard}:
3960 Fortran 2008 and later
3965 @item @emph{Syntax}:
3966 @code{RESULT = ERF(X)}
3968 @item @emph{Arguments}:
3969 @multitable @columnfractions .15 .70
3970 @item @var{X} @tab The type shall be @code{REAL}.
3973 @item @emph{Return value}:
3974 The return value is of type @code{REAL}, of the same kind as
3975 @var{X} and lies in the range @math{-1 \leq erf (x) \leq 1 }.
3977 @item @emph{Example}:
3980 real(8) :: x = 0.17_8
3982 end program test_erf
3985 @item @emph{Specific names}:
3986 @multitable @columnfractions .20 .20 .20 .25
3987 @item Name @tab Argument @tab Return type @tab Standard
3988 @item @code{DERF(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU extension
3995 @section @code{ERFC} --- Error function
3997 @cindex error function, complementary
4000 @item @emph{Description}:
4001 @code{ERFC(X)} computes the complementary error function of @var{X}.
4003 @item @emph{Standard}:
4004 Fortran 2008 and later
4009 @item @emph{Syntax}:
4010 @code{RESULT = ERFC(X)}
4012 @item @emph{Arguments}:
4013 @multitable @columnfractions .15 .70
4014 @item @var{X} @tab The type shall be @code{REAL}.
4017 @item @emph{Return value}:
4018 The return value is of type @code{REAL} and of the same kind as @var{X}.
4019 It lies in the range @math{ 0 \leq erfc (x) \leq 2 }.
4021 @item @emph{Example}:
4024 real(8) :: x = 0.17_8
4026 end program test_erfc
4029 @item @emph{Specific names}:
4030 @multitable @columnfractions .20 .20 .20 .25
4031 @item Name @tab Argument @tab Return type @tab Standard
4032 @item @code{DERFC(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU extension
4039 @section @code{ERFC_SCALED} --- Error function
4040 @fnindex ERFC_SCALED
4041 @cindex error function, complementary, exponentially-scaled
4044 @item @emph{Description}:
4045 @code{ERFC_SCALED(X)} computes the exponentially-scaled complementary
4046 error function of @var{X}.
4048 @item @emph{Standard}:
4049 Fortran 2008 and later
4054 @item @emph{Syntax}:
4055 @code{RESULT = ERFC_SCALED(X)}
4057 @item @emph{Arguments}:
4058 @multitable @columnfractions .15 .70
4059 @item @var{X} @tab The type shall be @code{REAL}.
4062 @item @emph{Return value}:
4063 The return value is of type @code{REAL} and of the same kind as @var{X}.
4065 @item @emph{Example}:
4067 program test_erfc_scaled
4068 real(8) :: x = 0.17_8
4070 end program test_erfc_scaled
4077 @section @code{ETIME} --- Execution time subroutine (or function)
4079 @cindex time, elapsed
4082 @item @emph{Description}:
4083 @code{ETIME(VALUES, TIME)} returns the number of seconds of runtime
4084 since the start of the process's execution in @var{TIME}. @var{VALUES}
4085 returns the user and system components of this time in @code{VALUES(1)} and
4086 @code{VALUES(2)} respectively. @var{TIME} is equal to @code{VALUES(1) + VALUES(2)}.
4088 On some systems, the underlying timings are represented using types with
4089 sufficiently small limits that overflows (wrap around) are possible, such as
4090 32-bit types. Therefore, the values returned by this intrinsic might be, or
4091 become, negative, or numerically less than previous values, during a single
4092 run of the compiled program.
4094 This intrinsic is provided in both subroutine and function forms; however,
4095 only one form can be used in any given program unit.
4097 @var{VALUES} and @var{TIME} are @code{INTENT(OUT)} and provide the following:
4099 @multitable @columnfractions .15 .30 .60
4100 @item @tab @code{VALUES(1)}: @tab User time in seconds.
4101 @item @tab @code{VALUES(2)}: @tab System time in seconds.
4102 @item @tab @code{TIME}: @tab Run time since start in seconds.
4105 @item @emph{Standard}:
4109 Subroutine, function
4111 @item @emph{Syntax}:
4112 @multitable @columnfractions .80
4113 @item @code{CALL ETIME(VALUES, TIME)}.
4114 @item @code{TIME = ETIME(VALUES)}, (not recommended).
4117 @item @emph{Arguments}:
4118 @multitable @columnfractions .15 .70
4119 @item @var{VALUES}@tab The type shall be @code{REAL(4), DIMENSION(2)}.
4120 @item @var{TIME}@tab The type shall be @code{REAL(4)}.
4123 @item @emph{Return value}:
4124 Elapsed time in seconds since the start of program execution.
4126 @item @emph{Example}:
4130 real, dimension(2) :: tarray
4132 call ETIME(tarray, result)
4136 do i=1,100000000 ! Just a delay
4139 call ETIME(tarray, result)
4143 end program test_etime
4146 @item @emph{See also}:
4153 @node EXECUTE_COMMAND_LINE
4154 @section @code{EXECUTE_COMMAND_LINE} --- Execute a shell command
4155 @fnindex EXECUTE_COMMAND_LINE
4156 @cindex system, system call
4157 @cindex command line
4160 @item @emph{Description}:
4161 @code{EXECUTE_COMMAND_LINE} runs a shell command, synchronously or
4164 The @code{COMMAND} argument is passed to the shell and executed, using
4165 the C library's @code{system} call. (The shell is @code{sh} on Unix
4166 systems, and @code{cmd.exe} on Windows.) If @code{WAIT} is present
4167 and has the value false, the execution of the command is asynchronous
4168 if the system supports it; otherwise, the command is executed
4171 The three last arguments allow the user to get status information. After
4172 synchronous execution, @code{EXITSTAT} contains the integer exit code of
4173 the command, as returned by @code{system}. @code{CMDSTAT} is set to zero
4174 if the command line was executed (whatever its exit status was).
4175 @code{CMDMSG} is assigned an error message if an error has occurred.
4177 Note that the @code{system} function need not be thread-safe. It is
4178 the responsibility of the user to ensure that @code{system} is not
4179 called concurrently.
4181 @item @emph{Standard}:
4182 Fortran 2008 and later
4187 @item @emph{Syntax}:
4188 @code{CALL EXECUTE_COMMAND_LINE(COMMAND [, WAIT, EXITSTAT, CMDSTAT, CMDMSG ])}
4190 @item @emph{Arguments}:
4191 @multitable @columnfractions .15 .70
4192 @item @var{COMMAND} @tab Shall be a default @code{CHARACTER} scalar.
4193 @item @var{WAIT} @tab (Optional) Shall be a default @code{LOGICAL} scalar.
4194 @item @var{EXITSTAT} @tab (Optional) Shall be an @code{INTEGER} of the
4196 @item @var{CMDSTAT} @tab (Optional) Shall be an @code{INTEGER} of the
4198 @item @var{CMDMSG} @tab (Optional) Shall be an @code{CHARACTER} scalar of the
4202 @item @emph{Example}:
4207 call execute_command_line ("external_prog.exe", exitstat=i)
4208 print *, "Exit status of external_prog.exe was ", i
4210 call execute_command_line ("reindex_files.exe", wait=.false.)
4211 print *, "Now reindexing files in the background"
4213 end program test_exec
4219 Because this intrinsic is implemented in terms of the @code{system}
4220 function call, its behavior with respect to signaling is processor
4221 dependent. In particular, on POSIX-compliant systems, the SIGINT and
4222 SIGQUIT signals will be ignored, and the SIGCHLD will be blocked. As
4223 such, if the parent process is terminated, the child process might not be
4224 terminated alongside.
4227 @item @emph{See also}:
4234 @section @code{EXIT} --- Exit the program with status.
4236 @cindex program termination
4237 @cindex terminate program
4240 @item @emph{Description}:
4241 @code{EXIT} causes immediate termination of the program with status. If status
4242 is omitted it returns the canonical @emph{success} for the system. All Fortran
4243 I/O units are closed.
4245 @item @emph{Standard}:
4251 @item @emph{Syntax}:
4252 @code{CALL EXIT([STATUS])}
4254 @item @emph{Arguments}:
4255 @multitable @columnfractions .15 .70
4256 @item @var{STATUS} @tab Shall be an @code{INTEGER} of the default kind.
4259 @item @emph{Return value}:
4260 @code{STATUS} is passed to the parent process on exit.
4262 @item @emph{Example}:
4265 integer :: STATUS = 0
4266 print *, 'This program is going to exit.'
4268 end program test_exit
4271 @item @emph{See also}:
4272 @ref{ABORT}, @ref{KILL}
4278 @section @code{EXP} --- Exponential function
4284 @cindex exponential function
4285 @cindex logarithm function, inverse
4288 @item @emph{Description}:
4289 @code{EXP(X)} computes the base @math{e} exponential of @var{X}.
4291 @item @emph{Standard}:
4292 Fortran 77 and later, has overloads that are GNU extensions
4297 @item @emph{Syntax}:
4298 @code{RESULT = EXP(X)}
4300 @item @emph{Arguments}:
4301 @multitable @columnfractions .15 .70
4302 @item @var{X} @tab The type shall be @code{REAL} or
4306 @item @emph{Return value}:
4307 The return value has same type and kind as @var{X}.
4309 @item @emph{Example}:
4314 end program test_exp
4317 @item @emph{Specific names}:
4318 @multitable @columnfractions .20 .20 .20 .25
4319 @item Name @tab Argument @tab Return type @tab Standard
4320 @item @code{EXP(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab Fortran 77 and later
4321 @item @code{DEXP(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab Fortran 77 and later
4322 @item @code{CEXP(X)} @tab @code{COMPLEX(4) X} @tab @code{COMPLEX(4)} @tab Fortran 77 and later
4323 @item @code{ZEXP(X)} @tab @code{COMPLEX(8) X} @tab @code{COMPLEX(8)} @tab GNU extension
4324 @item @code{CDEXP(X)} @tab @code{COMPLEX(8) X} @tab @code{COMPLEX(8)} @tab GNU extension
4331 @section @code{EXPONENT} --- Exponent function
4333 @cindex real number, exponent
4334 @cindex floating point, exponent
4337 @item @emph{Description}:
4338 @code{EXPONENT(X)} returns the value of the exponent part of @var{X}. If @var{X}
4339 is zero the value returned is zero.
4341 @item @emph{Standard}:
4342 Fortran 95 and later
4347 @item @emph{Syntax}:
4348 @code{RESULT = EXPONENT(X)}
4350 @item @emph{Arguments}:
4351 @multitable @columnfractions .15 .70
4352 @item @var{X} @tab The type shall be @code{REAL}.
4355 @item @emph{Return value}:
4356 The return value is of type default @code{INTEGER}.
4358 @item @emph{Example}:
4360 program test_exponent
4365 print *, exponent(0.0)
4366 end program test_exponent
4372 @node EXTENDS_TYPE_OF
4373 @section @code{EXTENDS_TYPE_OF} --- Query dynamic type for extension
4374 @fnindex EXTENDS_TYPE_OF
4377 @item @emph{Description}:
4378 Query dynamic type for extension.
4380 @item @emph{Standard}:
4381 Fortran 2003 and later
4386 @item @emph{Syntax}:
4387 @code{RESULT = EXTENDS_TYPE_OF(A, MOLD)}
4389 @item @emph{Arguments}:
4390 @multitable @columnfractions .15 .70
4391 @item @var{A} @tab Shall be an object of extensible declared type or
4392 unlimited polymorphic.
4393 @item @var{MOLD} @tab Shall be an object of extensible declared type or
4394 unlimited polymorphic.
4397 @item @emph{Return value}:
4398 The return value is a scalar of type default logical. It is true if and only if
4399 the dynamic type of A is an extension type of the dynamic type of MOLD.
4402 @item @emph{See also}:
4409 @section @code{FDATE} --- Get the current time as a string
4411 @cindex time, current
4412 @cindex current time
4413 @cindex date, current
4414 @cindex current date
4417 @item @emph{Description}:
4418 @code{FDATE(DATE)} returns the current date (using the same format as
4419 @code{CTIME}) in @var{DATE}. It is equivalent to @code{CALL CTIME(DATE,
4422 This intrinsic is provided in both subroutine and function forms; however,
4423 only one form can be used in any given program unit.
4425 @item @emph{Standard}:
4429 Subroutine, function
4431 @item @emph{Syntax}:
4432 @multitable @columnfractions .80
4433 @item @code{CALL FDATE(DATE)}.
4434 @item @code{DATE = FDATE()}.
4437 @item @emph{Arguments}:
4438 @multitable @columnfractions .15 .70
4439 @item @var{DATE}@tab The type shall be of type @code{CHARACTER} of the
4440 default kind. It is an @code{INTENT(OUT)} argument. If the length of
4441 this variable is too short for the date and time string to fit
4442 completely, it will be blank on procedure return.
4445 @item @emph{Return value}:
4446 The current date and time as a string.
4448 @item @emph{Example}:
4452 character(len=30) :: date
4454 print *, 'Program started on ', date
4455 do i = 1, 100000000 ! Just a delay
4459 print *, 'Program ended on ', date
4460 end program test_fdate
4463 @item @emph{See also}:
4464 @ref{DATE_AND_TIME}, @ref{CTIME}
4469 @section @code{FGET} --- Read a single character in stream mode from stdin
4471 @cindex read character, stream mode
4472 @cindex stream mode, read character
4473 @cindex file operation, read character
4476 @item @emph{Description}:
4477 Read a single character in stream mode from stdin by bypassing normal
4478 formatted output. Stream I/O should not be mixed with normal record-oriented
4479 (formatted or unformatted) I/O on the same unit; the results are unpredictable.
4481 This intrinsic is provided in both subroutine and function forms; however,
4482 only one form can be used in any given program unit.
4484 Note that the @code{FGET} intrinsic is provided for backwards compatibility with
4485 @command{g77}. GNU Fortran provides the Fortran 2003 Stream facility.
4486 Programmers should consider the use of new stream IO feature in new code
4487 for future portability. See also @ref{Fortran 2003 status}.
4489 @item @emph{Standard}:
4493 Subroutine, function
4495 @item @emph{Syntax}:
4496 @multitable @columnfractions .80
4497 @item @code{CALL FGET(C [, STATUS])}
4498 @item @code{STATUS = FGET(C)}
4501 @item @emph{Arguments}:
4502 @multitable @columnfractions .15 .70
4503 @item @var{C} @tab The type shall be @code{CHARACTER} and of default
4505 @item @var{STATUS} @tab (Optional) status flag of type @code{INTEGER}.
4506 Returns 0 on success, -1 on end-of-file, and a system specific positive
4507 error code otherwise.
4510 @item @emph{Example}:
4513 INTEGER, PARAMETER :: strlen = 100
4514 INTEGER :: status, i = 1
4515 CHARACTER(len=strlen) :: str = ""
4517 WRITE (*,*) 'Enter text:'
4519 CALL fget(str(i:i), status)
4520 if (status /= 0 .OR. i > strlen) exit
4523 WRITE (*,*) TRIM(str)
4527 @item @emph{See also}:
4528 @ref{FGETC}, @ref{FPUT}, @ref{FPUTC}
4534 @section @code{FGETC} --- Read a single character in stream mode
4536 @cindex read character, stream mode
4537 @cindex stream mode, read character
4538 @cindex file operation, read character
4541 @item @emph{Description}:
4542 Read a single character in stream mode by bypassing normal formatted output.
4543 Stream I/O should not be mixed with normal record-oriented (formatted or
4544 unformatted) I/O on the same unit; the results are unpredictable.
4546 This intrinsic is provided in both subroutine and function forms; however,
4547 only one form can be used in any given program unit.
4549 Note that the @code{FGET} intrinsic is provided for backwards compatibility
4550 with @command{g77}. GNU Fortran provides the Fortran 2003 Stream facility.
4551 Programmers should consider the use of new stream IO feature in new code
4552 for future portability. See also @ref{Fortran 2003 status}.
4554 @item @emph{Standard}:
4558 Subroutine, function
4560 @item @emph{Syntax}:
4561 @multitable @columnfractions .80
4562 @item @code{CALL FGETC(UNIT, C [, STATUS])}
4563 @item @code{STATUS = FGETC(UNIT, C)}
4566 @item @emph{Arguments}:
4567 @multitable @columnfractions .15 .70
4568 @item @var{UNIT} @tab The type shall be @code{INTEGER}.
4569 @item @var{C} @tab The type shall be @code{CHARACTER} and of default
4571 @item @var{STATUS} @tab (Optional) status flag of type @code{INTEGER}.
4572 Returns 0 on success, -1 on end-of-file and a system specific positive
4573 error code otherwise.
4576 @item @emph{Example}:
4579 INTEGER :: fd = 42, status
4582 OPEN(UNIT=fd, FILE="/etc/passwd", ACTION="READ", STATUS = "OLD")
4584 CALL fgetc(fd, c, status)
4585 IF (status /= 0) EXIT
4592 @item @emph{See also}:
4593 @ref{FGET}, @ref{FPUT}, @ref{FPUTC}
4599 @section @code{FLOOR} --- Integer floor function
4602 @cindex rounding, floor
4605 @item @emph{Description}:
4606 @code{FLOOR(A)} returns the greatest integer less than or equal to @var{X}.
4608 @item @emph{Standard}:
4609 Fortran 95 and later
4614 @item @emph{Syntax}:
4615 @code{RESULT = FLOOR(A [, KIND])}
4617 @item @emph{Arguments}:
4618 @multitable @columnfractions .15 .70
4619 @item @var{A} @tab The type shall be @code{REAL}.
4620 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
4621 expression indicating the kind parameter of the result.
4624 @item @emph{Return value}:
4625 The return value is of type @code{INTEGER(KIND)} if @var{KIND} is present
4626 and of default-kind @code{INTEGER} otherwise.
4628 @item @emph{Example}:
4633 print *, floor(x) ! returns 63
4634 print *, floor(y) ! returns -64
4635 end program test_floor
4638 @item @emph{See also}:
4639 @ref{CEILING}, @ref{NINT}
4646 @section @code{FLUSH} --- Flush I/O unit(s)
4648 @cindex file operation, flush
4651 @item @emph{Description}:
4652 Flushes Fortran unit(s) currently open for output. Without the optional
4653 argument, all units are flushed, otherwise just the unit specified.
4655 @item @emph{Standard}:
4661 @item @emph{Syntax}:
4662 @code{CALL FLUSH(UNIT)}
4664 @item @emph{Arguments}:
4665 @multitable @columnfractions .15 .70
4666 @item @var{UNIT} @tab (Optional) The type shall be @code{INTEGER}.
4670 Beginning with the Fortran 2003 standard, there is a @code{FLUSH}
4671 statement that should be preferred over the @code{FLUSH} intrinsic.
4673 The @code{FLUSH} intrinsic and the Fortran 2003 @code{FLUSH} statement
4674 have identical effect: they flush the runtime library's I/O buffer so
4675 that the data becomes visible to other processes. This does not guarantee
4676 that the data is committed to disk.
4678 On POSIX systems, you can request that all data is transferred to the
4679 storage device by calling the @code{fsync} function, with the POSIX file
4680 descriptor of the I/O unit as argument (retrieved with GNU intrinsic
4681 @code{FNUM}). The following example shows how:
4684 ! Declare the interface for POSIX fsync function
4686 function fsync (fd) bind(c,name="fsync")
4687 use iso_c_binding, only: c_int
4688 integer(c_int), value :: fd
4689 integer(c_int) :: fsync
4693 ! Variable declaration
4697 open (10,file="foo")
4700 ! Perform I/O on unit 10
4705 ret = fsync(fnum(10))
4707 ! Handle possible error
4708 if (ret /= 0) stop "Error calling FSYNC"
4716 @section @code{FNUM} --- File number function
4718 @cindex file operation, file number
4721 @item @emph{Description}:
4722 @code{FNUM(UNIT)} returns the POSIX file descriptor number corresponding to the
4723 open Fortran I/O unit @code{UNIT}.
4725 @item @emph{Standard}:
4731 @item @emph{Syntax}:
4732 @code{RESULT = FNUM(UNIT)}
4734 @item @emph{Arguments}:
4735 @multitable @columnfractions .15 .70
4736 @item @var{UNIT} @tab The type shall be @code{INTEGER}.
4739 @item @emph{Return value}:
4740 The return value is of type @code{INTEGER}
4742 @item @emph{Example}:
4746 open (unit=10, status = "scratch")
4750 end program test_fnum
4757 @section @code{FPUT} --- Write a single character in stream mode to stdout
4759 @cindex write character, stream mode
4760 @cindex stream mode, write character
4761 @cindex file operation, write character
4764 @item @emph{Description}:
4765 Write a single character in stream mode to stdout by bypassing normal
4766 formatted output. Stream I/O should not be mixed with normal record-oriented
4767 (formatted or unformatted) I/O on the same unit; the results are unpredictable.
4769 This intrinsic is provided in both subroutine and function forms; however,
4770 only one form can be used in any given program unit.
4772 Note that the @code{FGET} intrinsic is provided for backwards compatibility with
4773 @command{g77}. GNU Fortran provides the Fortran 2003 Stream facility.
4774 Programmers should consider the use of new stream IO feature in new code
4775 for future portability. See also @ref{Fortran 2003 status}.
4777 @item @emph{Standard}:
4781 Subroutine, function
4783 @item @emph{Syntax}:
4784 @multitable @columnfractions .80
4785 @item @code{CALL FPUT(C [, STATUS])}
4786 @item @code{STATUS = FPUT(C)}
4789 @item @emph{Arguments}:
4790 @multitable @columnfractions .15 .70
4791 @item @var{C} @tab The type shall be @code{CHARACTER} and of default
4793 @item @var{STATUS} @tab (Optional) status flag of type @code{INTEGER}.
4794 Returns 0 on success, -1 on end-of-file and a system specific positive
4795 error code otherwise.
4798 @item @emph{Example}:
4801 CHARACTER(len=10) :: str = "gfortran"
4803 DO i = 1, len_trim(str)
4809 @item @emph{See also}:
4810 @ref{FPUTC}, @ref{FGET}, @ref{FGETC}
4816 @section @code{FPUTC} --- Write a single character in stream mode
4818 @cindex write character, stream mode
4819 @cindex stream mode, write character
4820 @cindex file operation, write character
4823 @item @emph{Description}:
4824 Write a single character in stream mode by bypassing normal formatted
4825 output. Stream I/O should not be mixed with normal record-oriented
4826 (formatted or unformatted) I/O on the same unit; the results are unpredictable.
4828 This intrinsic is provided in both subroutine and function forms; however,
4829 only one form can be used in any given program unit.
4831 Note that the @code{FGET} intrinsic is provided for backwards compatibility with
4832 @command{g77}. GNU Fortran provides the Fortran 2003 Stream facility.
4833 Programmers should consider the use of new stream IO feature in new code
4834 for future portability. See also @ref{Fortran 2003 status}.
4836 @item @emph{Standard}:
4840 Subroutine, function
4842 @item @emph{Syntax}:
4843 @multitable @columnfractions .80
4844 @item @code{CALL FPUTC(UNIT, C [, STATUS])}
4845 @item @code{STATUS = FPUTC(UNIT, C)}
4848 @item @emph{Arguments}:
4849 @multitable @columnfractions .15 .70
4850 @item @var{UNIT} @tab The type shall be @code{INTEGER}.
4851 @item @var{C} @tab The type shall be @code{CHARACTER} and of default
4853 @item @var{STATUS} @tab (Optional) status flag of type @code{INTEGER}.
4854 Returns 0 on success, -1 on end-of-file and a system specific positive
4855 error code otherwise.
4858 @item @emph{Example}:
4861 CHARACTER(len=10) :: str = "gfortran"
4862 INTEGER :: fd = 42, i
4864 OPEN(UNIT = fd, FILE = "out", ACTION = "WRITE", STATUS="NEW")
4865 DO i = 1, len_trim(str)
4866 CALL fputc(fd, str(i:i))
4872 @item @emph{See also}:
4873 @ref{FPUT}, @ref{FGET}, @ref{FGETC}
4879 @section @code{FRACTION} --- Fractional part of the model representation
4881 @cindex real number, fraction
4882 @cindex floating point, fraction
4885 @item @emph{Description}:
4886 @code{FRACTION(X)} returns the fractional part of the model
4887 representation of @code{X}.
4889 @item @emph{Standard}:
4890 Fortran 95 and later
4895 @item @emph{Syntax}:
4896 @code{Y = FRACTION(X)}
4898 @item @emph{Arguments}:
4899 @multitable @columnfractions .15 .70
4900 @item @var{X} @tab The type of the argument shall be a @code{REAL}.
4903 @item @emph{Return value}:
4904 The return value is of the same type and kind as the argument.
4905 The fractional part of the model representation of @code{X} is returned;
4906 it is @code{X * RADIX(X)**(-EXPONENT(X))}.
4908 @item @emph{Example}:
4910 program test_fraction
4913 print *, fraction(x), x * radix(x)**(-exponent(x))
4914 end program test_fraction
4922 @section @code{FREE} --- Frees memory
4924 @cindex pointer, cray
4927 @item @emph{Description}:
4928 Frees memory previously allocated by @code{MALLOC}. The @code{FREE}
4929 intrinsic is an extension intended to be used with Cray pointers, and is
4930 provided in GNU Fortran to allow user to compile legacy code. For
4931 new code using Fortran 95 pointers, the memory de-allocation intrinsic is
4934 @item @emph{Standard}:
4940 @item @emph{Syntax}:
4941 @code{CALL FREE(PTR)}
4943 @item @emph{Arguments}:
4944 @multitable @columnfractions .15 .70
4945 @item @var{PTR} @tab The type shall be @code{INTEGER}. It represents the
4946 location of the memory that should be de-allocated.
4949 @item @emph{Return value}:
4952 @item @emph{Example}:
4953 See @code{MALLOC} for an example.
4955 @item @emph{See also}:
4962 @section @code{FSEEK} --- Low level file positioning subroutine
4964 @cindex file operation, seek
4965 @cindex file operation, position
4968 @item @emph{Description}:
4969 Moves @var{UNIT} to the specified @var{OFFSET}. If @var{WHENCE}
4970 is set to 0, the @var{OFFSET} is taken as an absolute value @code{SEEK_SET},
4971 if set to 1, @var{OFFSET} is taken to be relative to the current position
4972 @code{SEEK_CUR}, and if set to 2 relative to the end of the file @code{SEEK_END}.
4973 On error, @var{STATUS} is set to a nonzero value. If @var{STATUS} the seek
4976 This intrinsic routine is not fully backwards compatible with @command{g77}.
4977 In @command{g77}, the @code{FSEEK} takes a statement label instead of a
4978 @var{STATUS} variable. If FSEEK is used in old code, change
4980 CALL FSEEK(UNIT, OFFSET, WHENCE, *label)
4985 CALL FSEEK(UNIT, OFFSET, WHENCE, status)
4986 IF (status /= 0) GOTO label
4989 Please note that GNU Fortran provides the Fortran 2003 Stream facility.
4990 Programmers should consider the use of new stream IO feature in new code
4991 for future portability. See also @ref{Fortran 2003 status}.
4993 @item @emph{Standard}:
4999 @item @emph{Syntax}:
5000 @code{CALL FSEEK(UNIT, OFFSET, WHENCE[, STATUS])}
5002 @item @emph{Arguments}:
5003 @multitable @columnfractions .15 .70
5004 @item @var{UNIT} @tab Shall be a scalar of type @code{INTEGER}.
5005 @item @var{OFFSET} @tab Shall be a scalar of type @code{INTEGER}.
5006 @item @var{WHENCE} @tab Shall be a scalar of type @code{INTEGER}.
5007 Its value shall be either 0, 1 or 2.
5008 @item @var{STATUS} @tab (Optional) shall be a scalar of type
5012 @item @emph{Example}:
5015 INTEGER, PARAMETER :: SEEK_SET = 0, SEEK_CUR = 1, SEEK_END = 2
5016 INTEGER :: fd, offset, ierr
5022 OPEN(UNIT=fd, FILE="fseek.test")
5023 CALL FSEEK(fd, offset, SEEK_SET, ierr) ! move to OFFSET
5024 print *, FTELL(fd), ierr
5026 CALL FSEEK(fd, 0, SEEK_END, ierr) ! move to end
5027 print *, FTELL(fd), ierr
5029 CALL FSEEK(fd, 0, SEEK_SET, ierr) ! move to beginning
5030 print *, FTELL(fd), ierr
5036 @item @emph{See also}:
5043 @section @code{FSTAT} --- Get file status
5045 @cindex file system, file status
5048 @item @emph{Description}:
5049 @code{FSTAT} is identical to @ref{STAT}, except that information about an
5050 already opened file is obtained.
5052 The elements in @code{VALUES} are the same as described by @ref{STAT}.
5054 This intrinsic is provided in both subroutine and function forms; however,
5055 only one form can be used in any given program unit.
5057 @item @emph{Standard}:
5061 Subroutine, function
5063 @item @emph{Syntax}:
5064 @multitable @columnfractions .80
5065 @item @code{CALL FSTAT(UNIT, VALUES [, STATUS])}
5066 @item @code{STATUS = FSTAT(UNIT, VALUES)}
5069 @item @emph{Arguments}:
5070 @multitable @columnfractions .15 .70
5071 @item @var{UNIT} @tab An open I/O unit number of type @code{INTEGER}.
5072 @item @var{VALUES} @tab The type shall be @code{INTEGER(4), DIMENSION(13)}.
5073 @item @var{STATUS} @tab (Optional) status flag of type @code{INTEGER(4)}. Returns 0
5074 on success and a system specific error code otherwise.
5077 @item @emph{Example}:
5078 See @ref{STAT} for an example.
5080 @item @emph{See also}:
5081 To stat a link: @ref{LSTAT}, to stat a file: @ref{STAT}
5087 @section @code{FTELL} --- Current stream position
5089 @cindex file operation, position
5092 @item @emph{Description}:
5093 Retrieves the current position within an open file.
5095 This intrinsic is provided in both subroutine and function forms; however,
5096 only one form can be used in any given program unit.
5098 @item @emph{Standard}:
5102 Subroutine, function
5104 @item @emph{Syntax}:
5105 @multitable @columnfractions .80
5106 @item @code{CALL FTELL(UNIT, OFFSET)}
5107 @item @code{OFFSET = FTELL(UNIT)}
5110 @item @emph{Arguments}:
5111 @multitable @columnfractions .15 .70
5112 @item @var{OFFSET} @tab Shall of type @code{INTEGER}.
5113 @item @var{UNIT} @tab Shall of type @code{INTEGER}.
5116 @item @emph{Return value}:
5117 In either syntax, @var{OFFSET} is set to the current offset of unit
5118 number @var{UNIT}, or to @math{-1} if the unit is not currently open.
5120 @item @emph{Example}:
5124 OPEN(10, FILE="temp.dat")
5130 @item @emph{See also}:
5137 @section @code{GAMMA} --- Gamma function
5140 @cindex Gamma function
5141 @cindex Factorial function
5144 @item @emph{Description}:
5145 @code{GAMMA(X)} computes Gamma (@math{\Gamma}) of @var{X}. For positive,
5146 integer values of @var{X} the Gamma function simplifies to the factorial
5147 function @math{\Gamma(x)=(x-1)!}.
5151 \Gamma(x) = \int_0^\infty t^{x-1}{\rm e}^{-t}\,{\rm d}t
5155 @item @emph{Standard}:
5156 Fortran 2008 and later
5161 @item @emph{Syntax}:
5164 @item @emph{Arguments}:
5165 @multitable @columnfractions .15 .70
5166 @item @var{X} @tab Shall be of type @code{REAL} and neither zero
5167 nor a negative integer.
5170 @item @emph{Return value}:
5171 The return value is of type @code{REAL} of the same kind as @var{X}.
5173 @item @emph{Example}:
5177 x = gamma(x) ! returns 1.0
5178 end program test_gamma
5181 @item @emph{Specific names}:
5182 @multitable @columnfractions .20 .20 .20 .25
5183 @item Name @tab Argument @tab Return type @tab Standard
5184 @item @code{GAMMA(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab GNU Extension
5185 @item @code{DGAMMA(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU Extension
5188 @item @emph{See also}:
5189 Logarithm of the Gamma function: @ref{LOG_GAMMA}
5196 @section @code{GERROR} --- Get last system error message
5198 @cindex system, error handling
5201 @item @emph{Description}:
5202 Returns the system error message corresponding to the last system error.
5203 This resembles the functionality of @code{strerror(3)} in C.
5205 @item @emph{Standard}:
5211 @item @emph{Syntax}:
5212 @code{CALL GERROR(RESULT)}
5214 @item @emph{Arguments}:
5215 @multitable @columnfractions .15 .70
5216 @item @var{RESULT} @tab Shall of type @code{CHARACTER} and of default
5219 @item @emph{Example}:
5222 CHARACTER(len=100) :: msg
5228 @item @emph{See also}:
5229 @ref{IERRNO}, @ref{PERROR}
5235 @section @code{GETARG} --- Get command line arguments
5237 @cindex command-line arguments
5238 @cindex arguments, to program
5241 @item @emph{Description}:
5242 Retrieve the @var{POS}-th argument that was passed on the
5243 command line when the containing program was invoked.
5245 This intrinsic routine is provided for backwards compatibility with
5246 GNU Fortran 77. In new code, programmers should consider the use of
5247 the @ref{GET_COMMAND_ARGUMENT} intrinsic defined by the Fortran 2003
5250 @item @emph{Standard}:
5256 @item @emph{Syntax}:
5257 @code{CALL GETARG(POS, VALUE)}
5259 @item @emph{Arguments}:
5260 @multitable @columnfractions .15 .70
5261 @item @var{POS} @tab Shall be of type @code{INTEGER} and not wider than
5262 the default integer kind; @math{@var{POS} \geq 0}
5263 @item @var{VALUE} @tab Shall be of type @code{CHARACTER} and of default
5265 @item @var{VALUE} @tab Shall be of type @code{CHARACTER}.
5268 @item @emph{Return value}:
5269 After @code{GETARG} returns, the @var{VALUE} argument holds the
5270 @var{POS}th command line argument. If @var{VALUE} can not hold the
5271 argument, it is truncated to fit the length of @var{VALUE}. If there are
5272 less than @var{POS} arguments specified at the command line, @var{VALUE}
5273 will be filled with blanks. If @math{@var{POS} = 0}, @var{VALUE} is set
5274 to the name of the program (on systems that support this feature).
5276 @item @emph{Example}:
5280 CHARACTER(len=32) :: arg
5289 @item @emph{See also}:
5290 GNU Fortran 77 compatibility function: @ref{IARGC}
5292 Fortran 2003 functions and subroutines: @ref{GET_COMMAND},
5293 @ref{GET_COMMAND_ARGUMENT}, @ref{COMMAND_ARGUMENT_COUNT}
5299 @section @code{GET_COMMAND} --- Get the entire command line
5300 @fnindex GET_COMMAND
5301 @cindex command-line arguments
5302 @cindex arguments, to program
5305 @item @emph{Description}:
5306 Retrieve the entire command line that was used to invoke the program.
5308 @item @emph{Standard}:
5309 Fortran 2003 and later
5314 @item @emph{Syntax}:
5315 @code{CALL GET_COMMAND([COMMAND, LENGTH, STATUS])}
5317 @item @emph{Arguments}:
5318 @multitable @columnfractions .15 .70
5319 @item @var{COMMAND} @tab (Optional) shall be of type @code{CHARACTER} and
5321 @item @var{LENGTH} @tab (Optional) Shall be of type @code{INTEGER} and of
5323 @item @var{STATUS} @tab (Optional) Shall be of type @code{INTEGER} and of
5327 @item @emph{Return value}:
5328 If @var{COMMAND} is present, stores the entire command line that was used
5329 to invoke the program in @var{COMMAND}. If @var{LENGTH} is present, it is
5330 assigned the length of the command line. If @var{STATUS} is present, it
5331 is assigned 0 upon success of the command, -1 if @var{COMMAND} is too
5332 short to store the command line, or a positive value in case of an error.
5334 @item @emph{Example}:
5336 PROGRAM test_get_command
5337 CHARACTER(len=255) :: cmd
5338 CALL get_command(cmd)
5339 WRITE (*,*) TRIM(cmd)
5343 @item @emph{See also}:
5344 @ref{GET_COMMAND_ARGUMENT}, @ref{COMMAND_ARGUMENT_COUNT}
5349 @node GET_COMMAND_ARGUMENT
5350 @section @code{GET_COMMAND_ARGUMENT} --- Get command line arguments
5351 @fnindex GET_COMMAND_ARGUMENT
5352 @cindex command-line arguments
5353 @cindex arguments, to program
5356 @item @emph{Description}:
5357 Retrieve the @var{NUMBER}-th argument that was passed on the
5358 command line when the containing program was invoked.
5360 @item @emph{Standard}:
5361 Fortran 2003 and later
5366 @item @emph{Syntax}:
5367 @code{CALL GET_COMMAND_ARGUMENT(NUMBER [, VALUE, LENGTH, STATUS])}
5369 @item @emph{Arguments}:
5370 @multitable @columnfractions .15 .70
5371 @item @var{NUMBER} @tab Shall be a scalar of type @code{INTEGER} and of
5372 default kind, @math{@var{NUMBER} \geq 0}
5373 @item @var{VALUE} @tab (Optional) Shall be a scalar of type @code{CHARACTER}
5374 and of default kind.
5375 @item @var{LENGTH} @tab (Optional) Shall be a scalar of type @code{INTEGER}
5376 and of default kind.
5377 @item @var{STATUS} @tab (Optional) Shall be a scalar of type @code{INTEGER}
5378 and of default kind.
5381 @item @emph{Return value}:
5382 After @code{GET_COMMAND_ARGUMENT} returns, the @var{VALUE} argument holds the
5383 @var{NUMBER}-th command line argument. If @var{VALUE} can not hold the argument, it is
5384 truncated to fit the length of @var{VALUE}. If there are less than @var{NUMBER}
5385 arguments specified at the command line, @var{VALUE} will be filled with blanks.
5386 If @math{@var{NUMBER} = 0}, @var{VALUE} is set to the name of the program (on
5387 systems that support this feature). The @var{LENGTH} argument contains the
5388 length of the @var{NUMBER}-th command line argument. If the argument retrieval
5389 fails, @var{STATUS} is a positive number; if @var{VALUE} contains a truncated
5390 command line argument, @var{STATUS} is -1; and otherwise the @var{STATUS} is
5393 @item @emph{Example}:
5395 PROGRAM test_get_command_argument
5397 CHARACTER(len=32) :: arg
5401 CALL get_command_argument(i, arg)
5402 IF (LEN_TRIM(arg) == 0) EXIT
5404 WRITE (*,*) TRIM(arg)
5410 @item @emph{See also}:
5411 @ref{GET_COMMAND}, @ref{COMMAND_ARGUMENT_COUNT}
5417 @section @code{GETCWD} --- Get current working directory
5419 @cindex system, working directory
5422 @item @emph{Description}:
5423 Get current working directory.
5425 This intrinsic is provided in both subroutine and function forms; however,
5426 only one form can be used in any given program unit.
5428 @item @emph{Standard}:
5432 Subroutine, function
5434 @item @emph{Syntax}:
5435 @multitable @columnfractions .80
5436 @item @code{CALL GETCWD(C [, STATUS])}
5437 @item @code{STATUS = GETCWD(C)}
5440 @item @emph{Arguments}:
5441 @multitable @columnfractions .15 .70
5442 @item @var{C} @tab The type shall be @code{CHARACTER} and of default kind.
5443 @item @var{STATUS} @tab (Optional) status flag. Returns 0 on success,
5444 a system specific and nonzero error code otherwise.
5447 @item @emph{Example}:
5450 CHARACTER(len=255) :: cwd
5452 WRITE(*,*) TRIM(cwd)
5456 @item @emph{See also}:
5463 @section @code{GETENV} --- Get an environmental variable
5465 @cindex environment variable
5468 @item @emph{Description}:
5469 Get the @var{VALUE} of the environmental variable @var{NAME}.
5471 This intrinsic routine is provided for backwards compatibility with
5472 GNU Fortran 77. In new code, programmers should consider the use of
5473 the @ref{GET_ENVIRONMENT_VARIABLE} intrinsic defined by the Fortran
5476 Note that @code{GETENV} need not be thread-safe. It is the
5477 responsibility of the user to ensure that the environment is not being
5478 updated concurrently with a call to the @code{GETENV} intrinsic.
5480 @item @emph{Standard}:
5486 @item @emph{Syntax}:
5487 @code{CALL GETENV(NAME, VALUE)}
5489 @item @emph{Arguments}:
5490 @multitable @columnfractions .15 .70
5491 @item @var{NAME} @tab Shall be of type @code{CHARACTER} and of default kind.
5492 @item @var{VALUE} @tab Shall be of type @code{CHARACTER} and of default kind.
5495 @item @emph{Return value}:
5496 Stores the value of @var{NAME} in @var{VALUE}. If @var{VALUE} is
5497 not large enough to hold the data, it is truncated. If @var{NAME}
5498 is not set, @var{VALUE} will be filled with blanks.
5500 @item @emph{Example}:
5503 CHARACTER(len=255) :: homedir
5504 CALL getenv("HOME", homedir)
5505 WRITE (*,*) TRIM(homedir)
5509 @item @emph{See also}:
5510 @ref{GET_ENVIRONMENT_VARIABLE}
5515 @node GET_ENVIRONMENT_VARIABLE
5516 @section @code{GET_ENVIRONMENT_VARIABLE} --- Get an environmental variable
5517 @fnindex GET_ENVIRONMENT_VARIABLE
5518 @cindex environment variable
5521 @item @emph{Description}:
5522 Get the @var{VALUE} of the environmental variable @var{NAME}.
5524 Note that @code{GET_ENVIRONMENT_VARIABLE} need not be thread-safe. It
5525 is the responsibility of the user to ensure that the environment is
5526 not being updated concurrently with a call to the
5527 @code{GET_ENVIRONMENT_VARIABLE} intrinsic.
5529 @item @emph{Standard}:
5530 Fortran 2003 and later
5535 @item @emph{Syntax}:
5536 @code{CALL GET_ENVIRONMENT_VARIABLE(NAME[, VALUE, LENGTH, STATUS, TRIM_NAME)}
5538 @item @emph{Arguments}:
5539 @multitable @columnfractions .15 .70
5540 @item @var{NAME} @tab Shall be a scalar of type @code{CHARACTER}
5541 and of default kind.
5542 @item @var{VALUE} @tab (Optional) Shall be a scalar of type @code{CHARACTER}
5543 and of default kind.
5544 @item @var{LENGTH} @tab (Optional) Shall be a scalar of type @code{INTEGER}
5545 and of default kind.
5546 @item @var{STATUS} @tab (Optional) Shall be a scalar of type @code{INTEGER}
5547 and of default kind.
5548 @item @var{TRIM_NAME} @tab (Optional) Shall be a scalar of type @code{LOGICAL}
5549 and of default kind.
5552 @item @emph{Return value}:
5553 Stores the value of @var{NAME} in @var{VALUE}. If @var{VALUE} is
5554 not large enough to hold the data, it is truncated. If @var{NAME}
5555 is not set, @var{VALUE} will be filled with blanks. Argument @var{LENGTH}
5556 contains the length needed for storing the environment variable @var{NAME}
5557 or zero if it is not present. @var{STATUS} is -1 if @var{VALUE} is present
5558 but too short for the environment variable; it is 1 if the environment
5559 variable does not exist and 2 if the processor does not support environment
5560 variables; in all other cases @var{STATUS} is zero. If @var{TRIM_NAME} is
5561 present with the value @code{.FALSE.}, the trailing blanks in @var{NAME}
5562 are significant; otherwise they are not part of the environment variable
5565 @item @emph{Example}:
5568 CHARACTER(len=255) :: homedir
5569 CALL get_environment_variable("HOME", homedir)
5570 WRITE (*,*) TRIM(homedir)
5578 @section @code{GETGID} --- Group ID function
5580 @cindex system, group ID
5583 @item @emph{Description}:
5584 Returns the numerical group ID of the current process.
5586 @item @emph{Standard}:
5592 @item @emph{Syntax}:
5593 @code{RESULT = GETGID()}
5595 @item @emph{Return value}:
5596 The return value of @code{GETGID} is an @code{INTEGER} of the default
5600 @item @emph{Example}:
5601 See @code{GETPID} for an example.
5603 @item @emph{See also}:
5604 @ref{GETPID}, @ref{GETUID}
5610 @section @code{GETLOG} --- Get login name
5612 @cindex system, login name
5616 @item @emph{Description}:
5617 Gets the username under which the program is running.
5619 @item @emph{Standard}:
5625 @item @emph{Syntax}:
5626 @code{CALL GETLOG(C)}
5628 @item @emph{Arguments}:
5629 @multitable @columnfractions .15 .70
5630 @item @var{C} @tab Shall be of type @code{CHARACTER} and of default kind.
5633 @item @emph{Return value}:
5634 Stores the current user name in @var{LOGIN}. (On systems where POSIX
5635 functions @code{geteuid} and @code{getpwuid} are not available, and
5636 the @code{getlogin} function is not implemented either, this will
5637 return a blank string.)
5639 @item @emph{Example}:
5642 CHARACTER(32) :: login
5648 @item @emph{See also}:
5655 @section @code{GETPID} --- Process ID function
5657 @cindex system, process ID
5661 @item @emph{Description}:
5662 Returns the numerical process identifier of the current process.
5664 @item @emph{Standard}:
5670 @item @emph{Syntax}:
5671 @code{RESULT = GETPID()}
5673 @item @emph{Return value}:
5674 The return value of @code{GETPID} is an @code{INTEGER} of the default
5678 @item @emph{Example}:
5681 print *, "The current process ID is ", getpid()
5682 print *, "Your numerical user ID is ", getuid()
5683 print *, "Your numerical group ID is ", getgid()
5687 @item @emph{See also}:
5688 @ref{GETGID}, @ref{GETUID}
5694 @section @code{GETUID} --- User ID function
5696 @cindex system, user ID
5700 @item @emph{Description}:
5701 Returns the numerical user ID of the current process.
5703 @item @emph{Standard}:
5709 @item @emph{Syntax}:
5710 @code{RESULT = GETUID()}
5712 @item @emph{Return value}:
5713 The return value of @code{GETUID} is an @code{INTEGER} of the default
5717 @item @emph{Example}:
5718 See @code{GETPID} for an example.
5720 @item @emph{See also}:
5721 @ref{GETPID}, @ref{GETLOG}
5727 @section @code{GMTIME} --- Convert time to GMT info
5729 @cindex time, conversion to GMT info
5732 @item @emph{Description}:
5733 Given a system time value @var{TIME} (as provided by the @code{TIME8}
5734 intrinsic), fills @var{VALUES} with values extracted from it appropriate
5735 to the UTC time zone (Universal Coordinated Time, also known in some
5736 countries as GMT, Greenwich Mean Time), using @code{gmtime(3)}.
5738 @item @emph{Standard}:
5744 @item @emph{Syntax}:
5745 @code{CALL GMTIME(TIME, VALUES)}
5747 @item @emph{Arguments}:
5748 @multitable @columnfractions .15 .70
5749 @item @var{TIME} @tab An @code{INTEGER} scalar expression
5750 corresponding to a system time, with @code{INTENT(IN)}.
5751 @item @var{VALUES} @tab A default @code{INTEGER} array with 9 elements,
5752 with @code{INTENT(OUT)}.
5755 @item @emph{Return value}:
5756 The elements of @var{VALUES} are assigned as follows:
5758 @item Seconds after the minute, range 0--59 or 0--61 to allow for leap
5760 @item Minutes after the hour, range 0--59
5761 @item Hours past midnight, range 0--23
5762 @item Day of month, range 0--31
5763 @item Number of months since January, range 0--12
5764 @item Years since 1900
5765 @item Number of days since Sunday, range 0--6
5766 @item Days since January 1
5767 @item Daylight savings indicator: positive if daylight savings is in
5768 effect, zero if not, and negative if the information is not available.
5771 @item @emph{See also}:
5772 @ref{CTIME}, @ref{LTIME}, @ref{TIME}, @ref{TIME8}
5779 @section @code{HOSTNM} --- Get system host name
5781 @cindex system, host name
5784 @item @emph{Description}:
5785 Retrieves the host name of the system on which the program is running.
5787 This intrinsic is provided in both subroutine and function forms; however,
5788 only one form can be used in any given program unit.
5790 @item @emph{Standard}:
5794 Subroutine, function
5796 @item @emph{Syntax}:
5797 @multitable @columnfractions .80
5798 @item @code{CALL HOSTNM(C [, STATUS])}
5799 @item @code{STATUS = HOSTNM(NAME)}
5802 @item @emph{Arguments}:
5803 @multitable @columnfractions .15 .70
5804 @item @var{C} @tab Shall of type @code{CHARACTER} and of default kind.
5805 @item @var{STATUS} @tab (Optional) status flag of type @code{INTEGER}.
5806 Returns 0 on success, or a system specific error code otherwise.
5809 @item @emph{Return value}:
5810 In either syntax, @var{NAME} is set to the current hostname if it can
5811 be obtained, or to a blank string otherwise.
5818 @section @code{HUGE} --- Largest number of a kind
5820 @cindex limits, largest number
5821 @cindex model representation, largest number
5824 @item @emph{Description}:
5825 @code{HUGE(X)} returns the largest number that is not an infinity in
5826 the model of the type of @code{X}.
5828 @item @emph{Standard}:
5829 Fortran 95 and later
5834 @item @emph{Syntax}:
5835 @code{RESULT = HUGE(X)}
5837 @item @emph{Arguments}:
5838 @multitable @columnfractions .15 .70
5839 @item @var{X} @tab Shall be of type @code{REAL} or @code{INTEGER}.
5842 @item @emph{Return value}:
5843 The return value is of the same type and kind as @var{X}
5845 @item @emph{Example}:
5847 program test_huge_tiny
5848 print *, huge(0), huge(0.0), huge(0.0d0)
5849 print *, tiny(0.0), tiny(0.0d0)
5850 end program test_huge_tiny
5857 @section @code{HYPOT} --- Euclidean distance function
5859 @cindex Euclidean distance
5862 @item @emph{Description}:
5863 @code{HYPOT(X,Y)} is the Euclidean distance function. It is equal to
5864 @math{\sqrt{X^2 + Y^2}}, without undue underflow or overflow.
5866 @item @emph{Standard}:
5867 Fortran 2008 and later
5872 @item @emph{Syntax}:
5873 @code{RESULT = HYPOT(X, Y)}
5875 @item @emph{Arguments}:
5876 @multitable @columnfractions .15 .70
5877 @item @var{X} @tab The type shall be @code{REAL}.
5878 @item @var{Y} @tab The type and kind type parameter shall be the same as
5882 @item @emph{Return value}:
5883 The return value has the same type and kind type parameter as @var{X}.
5885 @item @emph{Example}:
5888 real(4) :: x = 1.e0_4, y = 0.5e0_4
5890 end program test_hypot
5897 @section @code{IACHAR} --- Code in @acronym{ASCII} collating sequence
5899 @cindex @acronym{ASCII} collating sequence
5900 @cindex collating sequence, @acronym{ASCII}
5901 @cindex conversion, to integer
5904 @item @emph{Description}:
5905 @code{IACHAR(C)} returns the code for the @acronym{ASCII} character
5906 in the first character position of @code{C}.
5908 @item @emph{Standard}:
5909 Fortran 95 and later, with @var{KIND} argument Fortran 2003 and later
5914 @item @emph{Syntax}:
5915 @code{RESULT = IACHAR(C [, KIND])}
5917 @item @emph{Arguments}:
5918 @multitable @columnfractions .15 .70
5919 @item @var{C} @tab Shall be a scalar @code{CHARACTER}, with @code{INTENT(IN)}
5920 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
5921 expression indicating the kind parameter of the result.
5924 @item @emph{Return value}:
5925 The return value is of type @code{INTEGER} and of kind @var{KIND}. If
5926 @var{KIND} is absent, the return value is of default integer kind.
5928 @item @emph{Example}:
5933 end program test_iachar
5937 See @ref{ICHAR} for a discussion of converting between numerical values
5938 and formatted string representations.
5940 @item @emph{See also}:
5941 @ref{ACHAR}, @ref{CHAR}, @ref{ICHAR}
5948 @section @code{IALL} --- Bitwise AND of array elements
5951 @cindex bits, AND of array elements
5954 @item @emph{Description}:
5955 Reduces with bitwise AND the elements of @var{ARRAY} along dimension @var{DIM}
5956 if the corresponding element in @var{MASK} is @code{TRUE}.
5958 @item @emph{Standard}:
5959 Fortran 2008 and later
5962 Transformational function
5964 @item @emph{Syntax}:
5965 @multitable @columnfractions .80
5966 @item @code{RESULT = IALL(ARRAY[, MASK])}
5967 @item @code{RESULT = IALL(ARRAY, DIM[, MASK])}
5970 @item @emph{Arguments}:
5971 @multitable @columnfractions .15 .70
5972 @item @var{ARRAY} @tab Shall be an array of type @code{INTEGER}
5973 @item @var{DIM} @tab (Optional) shall be a scalar of type
5974 @code{INTEGER} with a value in the range from 1 to n, where n
5975 equals the rank of @var{ARRAY}.
5976 @item @var{MASK} @tab (Optional) shall be of type @code{LOGICAL}
5977 and either be a scalar or an array of the same shape as @var{ARRAY}.
5980 @item @emph{Return value}:
5981 The result is of the same type as @var{ARRAY}.
5983 If @var{DIM} is absent, a scalar with the bitwise ALL of all elements in
5984 @var{ARRAY} is returned. Otherwise, an array of rank n-1, where n equals
5985 the rank of @var{ARRAY}, and a shape similar to that of @var{ARRAY} with
5986 dimension @var{DIM} dropped is returned.
5988 @item @emph{Example}:
5997 PRINT '(b8.8)', IALL(a)
6001 @item @emph{See also}:
6002 @ref{IANY}, @ref{IPARITY}, @ref{IAND}
6008 @section @code{IAND} --- Bitwise logical and
6010 @cindex bitwise logical and
6011 @cindex logical and, bitwise
6014 @item @emph{Description}:
6015 Bitwise logical @code{AND}.
6017 @item @emph{Standard}:
6018 Fortran 95 and later
6023 @item @emph{Syntax}:
6024 @code{RESULT = IAND(I, J)}
6026 @item @emph{Arguments}:
6027 @multitable @columnfractions .15 .70
6028 @item @var{I} @tab The type shall be @code{INTEGER}.
6029 @item @var{J} @tab The type shall be @code{INTEGER}, of the same
6030 kind as @var{I}. (As a GNU extension, different kinds are also
6034 @item @emph{Return value}:
6035 The return type is @code{INTEGER}, of the same kind as the
6036 arguments. (If the argument kinds differ, it is of the same kind as
6037 the larger argument.)
6039 @item @emph{Example}:
6043 DATA a / Z'F' /, b / Z'3' /
6044 WRITE (*,*) IAND(a, b)
6048 @item @emph{See also}:
6049 @ref{IOR}, @ref{IEOR}, @ref{IBITS}, @ref{IBSET}, @ref{IBCLR}, @ref{NOT}
6056 @section @code{IANY} --- Bitwise OR of array elements
6059 @cindex bits, OR of array elements
6062 @item @emph{Description}:
6063 Reduces with bitwise OR (inclusive or) the elements of @var{ARRAY} along
6064 dimension @var{DIM} if the corresponding element in @var{MASK} is @code{TRUE}.
6066 @item @emph{Standard}:
6067 Fortran 2008 and later
6070 Transformational function
6072 @item @emph{Syntax}:
6073 @multitable @columnfractions .80
6074 @item @code{RESULT = IANY(ARRAY[, MASK])}
6075 @item @code{RESULT = IANY(ARRAY, DIM[, MASK])}
6078 @item @emph{Arguments}:
6079 @multitable @columnfractions .15 .70
6080 @item @var{ARRAY} @tab Shall be an array of type @code{INTEGER}
6081 @item @var{DIM} @tab (Optional) shall be a scalar of type
6082 @code{INTEGER} with a value in the range from 1 to n, where n
6083 equals the rank of @var{ARRAY}.
6084 @item @var{MASK} @tab (Optional) shall be of type @code{LOGICAL}
6085 and either be a scalar or an array of the same shape as @var{ARRAY}.
6088 @item @emph{Return value}:
6089 The result is of the same type as @var{ARRAY}.
6091 If @var{DIM} is absent, a scalar with the bitwise OR of all elements in
6092 @var{ARRAY} is returned. Otherwise, an array of rank n-1, where n equals
6093 the rank of @var{ARRAY}, and a shape similar to that of @var{ARRAY} with
6094 dimension @var{DIM} dropped is returned.
6096 @item @emph{Example}:
6105 PRINT '(b8.8)', IANY(a)
6109 @item @emph{See also}:
6110 @ref{IPARITY}, @ref{IALL}, @ref{IOR}
6116 @section @code{IARGC} --- Get the number of command line arguments
6118 @cindex command-line arguments
6119 @cindex command-line arguments, number of
6120 @cindex arguments, to program
6123 @item @emph{Description}:
6124 @code{IARGC} returns the number of arguments passed on the
6125 command line when the containing program was invoked.
6127 This intrinsic routine is provided for backwards compatibility with
6128 GNU Fortran 77. In new code, programmers should consider the use of
6129 the @ref{COMMAND_ARGUMENT_COUNT} intrinsic defined by the Fortran 2003
6132 @item @emph{Standard}:
6138 @item @emph{Syntax}:
6139 @code{RESULT = IARGC()}
6141 @item @emph{Arguments}:
6144 @item @emph{Return value}:
6145 The number of command line arguments, type @code{INTEGER(4)}.
6147 @item @emph{Example}:
6150 @item @emph{See also}:
6151 GNU Fortran 77 compatibility subroutine: @ref{GETARG}
6153 Fortran 2003 functions and subroutines: @ref{GET_COMMAND},
6154 @ref{GET_COMMAND_ARGUMENT}, @ref{COMMAND_ARGUMENT_COUNT}
6160 @section @code{IBCLR} --- Clear bit
6166 @item @emph{Description}:
6167 @code{IBCLR} returns the value of @var{I} with the bit at position
6168 @var{POS} set to zero.
6170 @item @emph{Standard}:
6171 Fortran 95 and later
6176 @item @emph{Syntax}:
6177 @code{RESULT = IBCLR(I, POS)}
6179 @item @emph{Arguments}:
6180 @multitable @columnfractions .15 .70
6181 @item @var{I} @tab The type shall be @code{INTEGER}.
6182 @item @var{POS} @tab The type shall be @code{INTEGER}.
6185 @item @emph{Return value}:
6186 The return value is of type @code{INTEGER} and of the same kind as
6189 @item @emph{See also}:
6190 @ref{IBITS}, @ref{IBSET}, @ref{IAND}, @ref{IOR}, @ref{IEOR}, @ref{MVBITS}
6197 @section @code{IBITS} --- Bit extraction
6200 @cindex bits, extract
6203 @item @emph{Description}:
6204 @code{IBITS} extracts a field of length @var{LEN} from @var{I},
6205 starting from bit position @var{POS} and extending left for @var{LEN}
6206 bits. The result is right-justified and the remaining bits are
6207 zeroed. The value of @code{POS+LEN} must be less than or equal to the
6208 value @code{BIT_SIZE(I)}.
6210 @item @emph{Standard}:
6211 Fortran 95 and later
6216 @item @emph{Syntax}:
6217 @code{RESULT = IBITS(I, POS, LEN)}
6219 @item @emph{Arguments}:
6220 @multitable @columnfractions .15 .70
6221 @item @var{I} @tab The type shall be @code{INTEGER}.
6222 @item @var{POS} @tab The type shall be @code{INTEGER}.
6223 @item @var{LEN} @tab The type shall be @code{INTEGER}.
6226 @item @emph{Return value}:
6227 The return value is of type @code{INTEGER} and of the same kind as
6230 @item @emph{See also}:
6231 @ref{BIT_SIZE}, @ref{IBCLR}, @ref{IBSET}, @ref{IAND}, @ref{IOR}, @ref{IEOR}
6237 @section @code{IBSET} --- Set bit
6242 @item @emph{Description}:
6243 @code{IBSET} returns the value of @var{I} with the bit at position
6244 @var{POS} set to one.
6246 @item @emph{Standard}:
6247 Fortran 95 and later
6252 @item @emph{Syntax}:
6253 @code{RESULT = IBSET(I, POS)}
6255 @item @emph{Arguments}:
6256 @multitable @columnfractions .15 .70
6257 @item @var{I} @tab The type shall be @code{INTEGER}.
6258 @item @var{POS} @tab The type shall be @code{INTEGER}.
6261 @item @emph{Return value}:
6262 The return value is of type @code{INTEGER} and of the same kind as
6265 @item @emph{See also}:
6266 @ref{IBCLR}, @ref{IBITS}, @ref{IAND}, @ref{IOR}, @ref{IEOR}, @ref{MVBITS}
6273 @section @code{ICHAR} --- Character-to-integer conversion function
6275 @cindex conversion, to integer
6278 @item @emph{Description}:
6279 @code{ICHAR(C)} returns the code for the character in the first character
6280 position of @code{C} in the system's native character set.
6281 The correspondence between characters and their codes is not necessarily
6282 the same across different GNU Fortran implementations.
6284 @item @emph{Standard}:
6285 Fortran 95 and later, with @var{KIND} argument Fortran 2003 and later
6290 @item @emph{Syntax}:
6291 @code{RESULT = ICHAR(C [, KIND])}
6293 @item @emph{Arguments}:
6294 @multitable @columnfractions .15 .70
6295 @item @var{C} @tab Shall be a scalar @code{CHARACTER}, with @code{INTENT(IN)}
6296 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
6297 expression indicating the kind parameter of the result.
6300 @item @emph{Return value}:
6301 The return value is of type @code{INTEGER} and of kind @var{KIND}. If
6302 @var{KIND} is absent, the return value is of default integer kind.
6304 @item @emph{Example}:
6309 end program test_ichar
6312 @item @emph{Specific names}:
6313 @multitable @columnfractions .20 .20 .20 .25
6314 @item Name @tab Argument @tab Return type @tab Standard
6315 @item @code{ICHAR(C)} @tab @code{CHARACTER C} @tab @code{INTEGER(4)} @tab Fortran 77 and later
6319 No intrinsic exists to convert between a numeric value and a formatted
6320 character string representation -- for instance, given the
6321 @code{CHARACTER} value @code{'154'}, obtaining an @code{INTEGER} or
6322 @code{REAL} value with the value 154, or vice versa. Instead, this
6323 functionality is provided by internal-file I/O, as in the following
6328 character(len=10) string, string2
6331 ! Convert a string to a numeric value
6332 read (string,'(I10)') value
6335 ! Convert a value to a formatted string
6336 write (string2,'(I10)') value
6338 end program read_val
6341 @item @emph{See also}:
6342 @ref{ACHAR}, @ref{CHAR}, @ref{IACHAR}
6349 @section @code{IDATE} --- Get current local time subroutine (day/month/year)
6351 @cindex date, current
6352 @cindex current date
6355 @item @emph{Description}:
6356 @code{IDATE(VALUES)} Fills @var{VALUES} with the numerical values at the
6357 current local time. The day (in the range 1-31), month (in the range 1-12),
6358 and year appear in elements 1, 2, and 3 of @var{VALUES}, respectively.
6359 The year has four significant digits.
6361 @item @emph{Standard}:
6367 @item @emph{Syntax}:
6368 @code{CALL IDATE(VALUES)}
6370 @item @emph{Arguments}:
6371 @multitable @columnfractions .15 .70
6372 @item @var{VALUES} @tab The type shall be @code{INTEGER, DIMENSION(3)} and
6373 the kind shall be the default integer kind.
6376 @item @emph{Return value}:
6377 Does not return anything.
6379 @item @emph{Example}:
6382 integer, dimension(3) :: tarray
6387 end program test_idate
6394 @section @code{IEOR} --- Bitwise logical exclusive or
6396 @cindex bitwise logical exclusive or
6397 @cindex logical exclusive or, bitwise
6400 @item @emph{Description}:
6401 @code{IEOR} returns the bitwise Boolean exclusive-OR of @var{I} and
6404 @item @emph{Standard}:
6405 Fortran 95 and later
6410 @item @emph{Syntax}:
6411 @code{RESULT = IEOR(I, J)}
6413 @item @emph{Arguments}:
6414 @multitable @columnfractions .15 .70
6415 @item @var{I} @tab The type shall be @code{INTEGER}.
6416 @item @var{J} @tab The type shall be @code{INTEGER}, of the same
6417 kind as @var{I}. (As a GNU extension, different kinds are also
6421 @item @emph{Return value}:
6422 The return type is @code{INTEGER}, of the same kind as the
6423 arguments. (If the argument kinds differ, it is of the same kind as
6424 the larger argument.)
6426 @item @emph{See also}:
6427 @ref{IOR}, @ref{IAND}, @ref{IBITS}, @ref{IBSET}, @ref{IBCLR}, @ref{NOT}
6433 @section @code{IERRNO} --- Get the last system error number
6435 @cindex system, error handling
6438 @item @emph{Description}:
6439 Returns the last system error number, as given by the C @code{errno}
6442 @item @emph{Standard}:
6448 @item @emph{Syntax}:
6449 @code{RESULT = IERRNO()}
6451 @item @emph{Arguments}:
6454 @item @emph{Return value}:
6455 The return value is of type @code{INTEGER} and of the default integer
6458 @item @emph{See also}:
6465 @section @code{IMAGE_INDEX} --- Function that converts a cosubscript to an image index
6466 @fnindex IMAGE_INDEX
6467 @cindex coarray, @code{IMAGE_INDEX}
6468 @cindex images, cosubscript to image index conversion
6471 @item @emph{Description}:
6472 Returns the image index belonging to a cosubscript.
6474 @item @emph{Standard}:
6475 Fortran 2008 and later
6480 @item @emph{Syntax}:
6481 @code{RESULT = IMAGE_INDEX(COARRAY, SUB)}
6483 @item @emph{Arguments}: None.
6484 @multitable @columnfractions .15 .70
6485 @item @var{COARRAY} @tab Coarray of any type.
6486 @item @var{SUB} @tab default integer rank-1 array of a size equal to
6487 the corank of @var{COARRAY}.
6491 @item @emph{Return value}:
6492 Scalar default integer with the value of the image index which corresponds
6493 to the cosubscripts. For invalid cosubscripts the result is zero.
6495 @item @emph{Example}:
6497 INTEGER :: array[2,-1:4,8,*]
6498 ! Writes 28 (or 0 if there are fewer than 28 images)
6499 WRITE (*,*) IMAGE_INDEX (array, [2,0,3,1])
6502 @item @emph{See also}:
6503 @ref{THIS_IMAGE}, @ref{NUM_IMAGES}
6508 @node INDEX intrinsic
6509 @section @code{INDEX} --- Position of a substring within a string
6511 @cindex substring position
6512 @cindex string, find substring
6515 @item @emph{Description}:
6516 Returns the position of the start of the first occurrence of string
6517 @var{SUBSTRING} as a substring in @var{STRING}, counting from one. If
6518 @var{SUBSTRING} is not present in @var{STRING}, zero is returned. If
6519 the @var{BACK} argument is present and true, the return value is the
6520 start of the last occurrence rather than the first.
6522 @item @emph{Standard}:
6523 Fortran 77 and later, with @var{KIND} argument Fortran 2003 and later
6528 @item @emph{Syntax}:
6529 @code{RESULT = INDEX(STRING, SUBSTRING [, BACK [, KIND]])}
6531 @item @emph{Arguments}:
6532 @multitable @columnfractions .15 .70
6533 @item @var{STRING} @tab Shall be a scalar @code{CHARACTER}, with
6535 @item @var{SUBSTRING} @tab Shall be a scalar @code{CHARACTER}, with
6537 @item @var{BACK} @tab (Optional) Shall be a scalar @code{LOGICAL}, with
6539 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
6540 expression indicating the kind parameter of the result.
6543 @item @emph{Return value}:
6544 The return value is of type @code{INTEGER} and of kind @var{KIND}. If
6545 @var{KIND} is absent, the return value is of default integer kind.
6547 @item @emph{Specific names}:
6548 @multitable @columnfractions .20 .20 .20 .25
6549 @item Name @tab Argument @tab Return type @tab Standard
6550 @item @code{INDEX(STRING, SUBSTRING)} @tab @code{CHARACTER} @tab @code{INTEGER(4)} @tab Fortran 77 and later
6553 @item @emph{See also}:
6554 @ref{SCAN}, @ref{VERIFY}
6560 @section @code{INT} --- Convert to integer type
6564 @cindex conversion, to integer
6567 @item @emph{Description}:
6568 Convert to integer type
6570 @item @emph{Standard}:
6571 Fortran 77 and later
6576 @item @emph{Syntax}:
6577 @code{RESULT = INT(A [, KIND))}
6579 @item @emph{Arguments}:
6580 @multitable @columnfractions .15 .70
6581 @item @var{A} @tab Shall be of type @code{INTEGER},
6582 @code{REAL}, or @code{COMPLEX}.
6583 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
6584 expression indicating the kind parameter of the result.
6587 @item @emph{Return value}:
6588 These functions return a @code{INTEGER} variable or array under
6589 the following rules:
6593 If @var{A} is of type @code{INTEGER}, @code{INT(A) = A}
6595 If @var{A} is of type @code{REAL} and @math{|A| < 1}, @code{INT(A)} equals @code{0}.
6596 If @math{|A| \geq 1}, then @code{INT(A)} equals the largest integer that does not exceed
6597 the range of @var{A} and whose sign is the same as the sign of @var{A}.
6599 If @var{A} is of type @code{COMPLEX}, rule B is applied to the real part of @var{A}.
6602 @item @emph{Example}:
6606 complex :: z = (-3.7, 1.0)
6608 print *, int(z), int(z,8)
6612 @item @emph{Specific names}:
6613 @multitable @columnfractions .20 .20 .20 .25
6614 @item Name @tab Argument @tab Return type @tab Standard
6615 @item @code{INT(A)} @tab @code{REAL(4) A} @tab @code{INTEGER} @tab Fortran 77 and later
6616 @item @code{IFIX(A)} @tab @code{REAL(4) A} @tab @code{INTEGER} @tab Fortran 77 and later
6617 @item @code{IDINT(A)} @tab @code{REAL(8) A} @tab @code{INTEGER} @tab Fortran 77 and later
6624 @section @code{INT2} --- Convert to 16-bit integer type
6627 @cindex conversion, to integer
6630 @item @emph{Description}:
6631 Convert to a @code{KIND=2} integer type. This is equivalent to the
6632 standard @code{INT} intrinsic with an optional argument of
6633 @code{KIND=2}, and is only included for backwards compatibility.
6635 The @code{SHORT} intrinsic is equivalent to @code{INT2}.
6637 @item @emph{Standard}:
6643 @item @emph{Syntax}:
6644 @code{RESULT = INT2(A)}
6646 @item @emph{Arguments}:
6647 @multitable @columnfractions .15 .70
6648 @item @var{A} @tab Shall be of type @code{INTEGER},
6649 @code{REAL}, or @code{COMPLEX}.
6652 @item @emph{Return value}:
6653 The return value is a @code{INTEGER(2)} variable.
6655 @item @emph{See also}:
6656 @ref{INT}, @ref{INT8}, @ref{LONG}
6662 @section @code{INT8} --- Convert to 64-bit integer type
6664 @cindex conversion, to integer
6667 @item @emph{Description}:
6668 Convert to a @code{KIND=8} integer type. This is equivalent to the
6669 standard @code{INT} intrinsic with an optional argument of
6670 @code{KIND=8}, and is only included for backwards compatibility.
6672 @item @emph{Standard}:
6678 @item @emph{Syntax}:
6679 @code{RESULT = INT8(A)}
6681 @item @emph{Arguments}:
6682 @multitable @columnfractions .15 .70
6683 @item @var{A} @tab Shall be of type @code{INTEGER},
6684 @code{REAL}, or @code{COMPLEX}.
6687 @item @emph{Return value}:
6688 The return value is a @code{INTEGER(8)} variable.
6690 @item @emph{See also}:
6691 @ref{INT}, @ref{INT2}, @ref{LONG}
6697 @section @code{IOR} --- Bitwise logical or
6699 @cindex bitwise logical or
6700 @cindex logical or, bitwise
6703 @item @emph{Description}:
6704 @code{IOR} returns the bitwise Boolean inclusive-OR of @var{I} and
6707 @item @emph{Standard}:
6708 Fortran 95 and later
6713 @item @emph{Syntax}:
6714 @code{RESULT = IOR(I, J)}
6716 @item @emph{Arguments}:
6717 @multitable @columnfractions .15 .70
6718 @item @var{I} @tab The type shall be @code{INTEGER}.
6719 @item @var{J} @tab The type shall be @code{INTEGER}, of the same
6720 kind as @var{I}. (As a GNU extension, different kinds are also
6724 @item @emph{Return value}:
6725 The return type is @code{INTEGER}, of the same kind as the
6726 arguments. (If the argument kinds differ, it is of the same kind as
6727 the larger argument.)
6729 @item @emph{See also}:
6730 @ref{IEOR}, @ref{IAND}, @ref{IBITS}, @ref{IBSET}, @ref{IBCLR}, @ref{NOT}
6736 @section @code{IPARITY} --- Bitwise XOR of array elements
6738 @cindex array, parity
6740 @cindex bits, XOR of array elements
6743 @item @emph{Description}:
6744 Reduces with bitwise XOR (exclusive or) the elements of @var{ARRAY} along
6745 dimension @var{DIM} if the corresponding element in @var{MASK} is @code{TRUE}.
6747 @item @emph{Standard}:
6748 Fortran 2008 and later
6751 Transformational function
6753 @item @emph{Syntax}:
6754 @multitable @columnfractions .80
6755 @item @code{RESULT = IPARITY(ARRAY[, MASK])}
6756 @item @code{RESULT = IPARITY(ARRAY, DIM[, MASK])}
6759 @item @emph{Arguments}:
6760 @multitable @columnfractions .15 .70
6761 @item @var{ARRAY} @tab Shall be an array of type @code{INTEGER}
6762 @item @var{DIM} @tab (Optional) shall be a scalar of type
6763 @code{INTEGER} with a value in the range from 1 to n, where n
6764 equals the rank of @var{ARRAY}.
6765 @item @var{MASK} @tab (Optional) shall be of type @code{LOGICAL}
6766 and either be a scalar or an array of the same shape as @var{ARRAY}.
6769 @item @emph{Return value}:
6770 The result is of the same type as @var{ARRAY}.
6772 If @var{DIM} is absent, a scalar with the bitwise XOR of all elements in
6773 @var{ARRAY} is returned. Otherwise, an array of rank n-1, where n equals
6774 the rank of @var{ARRAY}, and a shape similar to that of @var{ARRAY} with
6775 dimension @var{DIM} dropped is returned.
6777 @item @emph{Example}:
6779 PROGRAM test_iparity
6786 PRINT '(b8.8)', IPARITY(a)
6790 @item @emph{See also}:
6791 @ref{IANY}, @ref{IALL}, @ref{IEOR}, @ref{PARITY}
6797 @section @code{IRAND} --- Integer pseudo-random number
6799 @cindex random number generation
6802 @item @emph{Description}:
6803 @code{IRAND(FLAG)} returns a pseudo-random number from a uniform
6804 distribution between 0 and a system-dependent limit (which is in most
6805 cases 2147483647). If @var{FLAG} is 0, the next number
6806 in the current sequence is returned; if @var{FLAG} is 1, the generator
6807 is restarted by @code{CALL SRAND(0)}; if @var{FLAG} has any other value,
6808 it is used as a new seed with @code{SRAND}.
6810 This intrinsic routine is provided for backwards compatibility with
6811 GNU Fortran 77. It implements a simple modulo generator as provided
6812 by @command{g77}. For new code, one should consider the use of
6813 @ref{RANDOM_NUMBER} as it implements a superior algorithm.
6815 @item @emph{Standard}:
6821 @item @emph{Syntax}:
6822 @code{RESULT = IRAND(I)}
6824 @item @emph{Arguments}:
6825 @multitable @columnfractions .15 .70
6826 @item @var{I} @tab Shall be a scalar @code{INTEGER} of kind 4.
6829 @item @emph{Return value}:
6830 The return value is of @code{INTEGER(kind=4)} type.
6832 @item @emph{Example}:
6835 integer,parameter :: seed = 86456
6838 print *, irand(), irand(), irand(), irand()
6839 print *, irand(seed), irand(), irand(), irand()
6840 end program test_irand
6848 @section @code{IS_IOSTAT_END} --- Test for end-of-file value
6849 @fnindex IS_IOSTAT_END
6850 @cindex @code{IOSTAT}, end of file
6853 @item @emph{Description}:
6854 @code{IS_IOSTAT_END} tests whether an variable has the value of the I/O
6855 status ``end of file''. The function is equivalent to comparing the variable
6856 with the @code{IOSTAT_END} parameter of the intrinsic module
6857 @code{ISO_FORTRAN_ENV}.
6859 @item @emph{Standard}:
6860 Fortran 2003 and later
6865 @item @emph{Syntax}:
6866 @code{RESULT = IS_IOSTAT_END(I)}
6868 @item @emph{Arguments}:
6869 @multitable @columnfractions .15 .70
6870 @item @var{I} @tab Shall be of the type @code{INTEGER}.
6873 @item @emph{Return value}:
6874 Returns a @code{LOGICAL} of the default kind, which @code{.TRUE.} if
6875 @var{I} has the value which indicates an end of file condition for
6876 @code{IOSTAT=} specifiers, and is @code{.FALSE.} otherwise.
6878 @item @emph{Example}:
6883 OPEN(88, FILE='test.dat')
6884 READ(88, *, IOSTAT=stat) i
6885 IF(IS_IOSTAT_END(stat)) STOP 'END OF FILE'
6893 @section @code{IS_IOSTAT_EOR} --- Test for end-of-record value
6894 @fnindex IS_IOSTAT_EOR
6895 @cindex @code{IOSTAT}, end of record
6898 @item @emph{Description}:
6899 @code{IS_IOSTAT_EOR} tests whether an variable has the value of the I/O
6900 status ``end of record''. The function is equivalent to comparing the
6901 variable with the @code{IOSTAT_EOR} parameter of the intrinsic module
6902 @code{ISO_FORTRAN_ENV}.
6904 @item @emph{Standard}:
6905 Fortran 2003 and later
6910 @item @emph{Syntax}:
6911 @code{RESULT = IS_IOSTAT_EOR(I)}
6913 @item @emph{Arguments}:
6914 @multitable @columnfractions .15 .70
6915 @item @var{I} @tab Shall be of the type @code{INTEGER}.
6918 @item @emph{Return value}:
6919 Returns a @code{LOGICAL} of the default kind, which @code{.TRUE.} if
6920 @var{I} has the value which indicates an end of file condition for
6921 @code{IOSTAT=} specifiers, and is @code{.FALSE.} otherwise.
6923 @item @emph{Example}:
6927 INTEGER :: stat, i(50)
6928 OPEN(88, FILE='test.dat', FORM='UNFORMATTED')
6929 READ(88, IOSTAT=stat) i
6930 IF(IS_IOSTAT_EOR(stat)) STOP 'END OF RECORD'
6938 @section @code{ISATTY} --- Whether a unit is a terminal device.
6940 @cindex system, terminal
6943 @item @emph{Description}:
6944 Determine whether a unit is connected to a terminal device.
6946 @item @emph{Standard}:
6952 @item @emph{Syntax}:
6953 @code{RESULT = ISATTY(UNIT)}
6955 @item @emph{Arguments}:
6956 @multitable @columnfractions .15 .70
6957 @item @var{UNIT} @tab Shall be a scalar @code{INTEGER}.
6960 @item @emph{Return value}:
6961 Returns @code{.TRUE.} if the @var{UNIT} is connected to a terminal
6962 device, @code{.FALSE.} otherwise.
6964 @item @emph{Example}:
6967 INTEGER(kind=1) :: unit
6969 write(*,*) isatty(unit=unit)
6973 @item @emph{See also}:
6980 @section @code{ISHFT} --- Shift bits
6985 @item @emph{Description}:
6986 @code{ISHFT} returns a value corresponding to @var{I} with all of the
6987 bits shifted @var{SHIFT} places. A value of @var{SHIFT} greater than
6988 zero corresponds to a left shift, a value of zero corresponds to no
6989 shift, and a value less than zero corresponds to a right shift. If the
6990 absolute value of @var{SHIFT} is greater than @code{BIT_SIZE(I)}, the
6991 value is undefined. Bits shifted out from the left end or right end are
6992 lost; zeros are shifted in from the opposite end.
6994 @item @emph{Standard}:
6995 Fortran 95 and later
7000 @item @emph{Syntax}:
7001 @code{RESULT = ISHFT(I, SHIFT)}
7003 @item @emph{Arguments}:
7004 @multitable @columnfractions .15 .70
7005 @item @var{I} @tab The type shall be @code{INTEGER}.
7006 @item @var{SHIFT} @tab The type shall be @code{INTEGER}.
7009 @item @emph{Return value}:
7010 The return value is of type @code{INTEGER} and of the same kind as
7013 @item @emph{See also}:
7020 @section @code{ISHFTC} --- Shift bits circularly
7022 @cindex bits, shift circular
7025 @item @emph{Description}:
7026 @code{ISHFTC} returns a value corresponding to @var{I} with the
7027 rightmost @var{SIZE} bits shifted circularly @var{SHIFT} places; that
7028 is, bits shifted out one end are shifted into the opposite end. A value
7029 of @var{SHIFT} greater than zero corresponds to a left shift, a value of
7030 zero corresponds to no shift, and a value less than zero corresponds to
7031 a right shift. The absolute value of @var{SHIFT} must be less than
7032 @var{SIZE}. If the @var{SIZE} argument is omitted, it is taken to be
7033 equivalent to @code{BIT_SIZE(I)}.
7035 @item @emph{Standard}:
7036 Fortran 95 and later
7041 @item @emph{Syntax}:
7042 @code{RESULT = ISHFTC(I, SHIFT [, SIZE])}
7044 @item @emph{Arguments}:
7045 @multitable @columnfractions .15 .70
7046 @item @var{I} @tab The type shall be @code{INTEGER}.
7047 @item @var{SHIFT} @tab The type shall be @code{INTEGER}.
7048 @item @var{SIZE} @tab (Optional) The type shall be @code{INTEGER};
7049 the value must be greater than zero and less than or equal to
7053 @item @emph{Return value}:
7054 The return value is of type @code{INTEGER} and of the same kind as
7057 @item @emph{See also}:
7064 @section @code{ISNAN} --- Test for a NaN
7069 @item @emph{Description}:
7070 @code{ISNAN} tests whether a floating-point value is an IEEE
7072 @item @emph{Standard}:
7078 @item @emph{Syntax}:
7081 @item @emph{Arguments}:
7082 @multitable @columnfractions .15 .70
7083 @item @var{X} @tab Variable of the type @code{REAL}.
7087 @item @emph{Return value}:
7088 Returns a default-kind @code{LOGICAL}. The returned value is @code{TRUE}
7089 if @var{X} is a NaN and @code{FALSE} otherwise.
7091 @item @emph{Example}:
7098 if (isnan(x)) stop '"x" is a NaN'
7099 end program test_nan
7106 @section @code{ITIME} --- Get current local time subroutine (hour/minutes/seconds)
7108 @cindex time, current
7109 @cindex current time
7112 @item @emph{Description}:
7113 @code{IDATE(VALUES)} Fills @var{VALUES} with the numerical values at the
7114 current local time. The hour (in the range 1-24), minute (in the range 1-60),
7115 and seconds (in the range 1-60) appear in elements 1, 2, and 3 of @var{VALUES},
7118 @item @emph{Standard}:
7124 @item @emph{Syntax}:
7125 @code{CALL ITIME(VALUES)}
7127 @item @emph{Arguments}:
7128 @multitable @columnfractions .15 .70
7129 @item @var{VALUES} @tab The type shall be @code{INTEGER, DIMENSION(3)}
7130 and the kind shall be the default integer kind.
7133 @item @emph{Return value}:
7134 Does not return anything.
7137 @item @emph{Example}:
7140 integer, dimension(3) :: tarray
7145 end program test_itime
7152 @section @code{KILL} --- Send a signal to a process
7156 @item @emph{Description}:
7157 @item @emph{Standard}:
7158 Sends the signal specified by @var{SIGNAL} to the process @var{PID}.
7161 This intrinsic is provided in both subroutine and function forms; however,
7162 only one form can be used in any given program unit.
7165 Subroutine, function
7167 @item @emph{Syntax}:
7168 @multitable @columnfractions .80
7169 @item @code{CALL KILL(C, VALUE [, STATUS])}
7170 @item @code{STATUS = KILL(C, VALUE)}
7173 @item @emph{Arguments}:
7174 @multitable @columnfractions .15 .70
7175 @item @var{C} @tab Shall be a scalar @code{INTEGER}, with
7177 @item @var{VALUE} @tab Shall be a scalar @code{INTEGER}, with
7179 @item @var{STATUS} @tab (Optional) status flag of type @code{INTEGER(4)} or
7180 @code{INTEGER(8)}. Returns 0 on success, or a system-specific error code
7184 @item @emph{See also}:
7185 @ref{ABORT}, @ref{EXIT}
7191 @section @code{KIND} --- Kind of an entity
7196 @item @emph{Description}:
7197 @code{KIND(X)} returns the kind value of the entity @var{X}.
7199 @item @emph{Standard}:
7200 Fortran 95 and later
7205 @item @emph{Syntax}:
7208 @item @emph{Arguments}:
7209 @multitable @columnfractions .15 .70
7210 @item @var{X} @tab Shall be of type @code{LOGICAL}, @code{INTEGER},
7211 @code{REAL}, @code{COMPLEX} or @code{CHARACTER}.
7214 @item @emph{Return value}:
7215 The return value is a scalar of type @code{INTEGER} and of the default
7218 @item @emph{Example}:
7221 integer,parameter :: kc = kind(' ')
7222 integer,parameter :: kl = kind(.true.)
7224 print *, "The default character kind is ", kc
7225 print *, "The default logical kind is ", kl
7226 end program test_kind
7234 @section @code{LBOUND} --- Lower dimension bounds of an array
7236 @cindex array, lower bound
7239 @item @emph{Description}:
7240 Returns the lower bounds of an array, or a single lower bound
7241 along the @var{DIM} dimension.
7242 @item @emph{Standard}:
7243 Fortran 95 and later, with @var{KIND} argument Fortran 2003 and later
7248 @item @emph{Syntax}:
7249 @code{RESULT = LBOUND(ARRAY [, DIM [, KIND]])}
7251 @item @emph{Arguments}:
7252 @multitable @columnfractions .15 .70
7253 @item @var{ARRAY} @tab Shall be an array, of any type.
7254 @item @var{DIM} @tab (Optional) Shall be a scalar @code{INTEGER}.
7255 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
7256 expression indicating the kind parameter of the result.
7259 @item @emph{Return value}:
7260 The return value is of type @code{INTEGER} and of kind @var{KIND}. If
7261 @var{KIND} is absent, the return value is of default integer kind.
7262 If @var{DIM} is absent, the result is an array of the lower bounds of
7263 @var{ARRAY}. If @var{DIM} is present, the result is a scalar
7264 corresponding to the lower bound of the array along that dimension. If
7265 @var{ARRAY} is an expression rather than a whole array or array
7266 structure component, or if it has a zero extent along the relevant
7267 dimension, the lower bound is taken to be 1.
7269 @item @emph{See also}:
7270 @ref{UBOUND}, @ref{LCOBOUND}
7276 @section @code{LCOBOUND} --- Lower codimension bounds of an array
7278 @cindex coarray, lower bound
7281 @item @emph{Description}:
7282 Returns the lower bounds of a coarray, or a single lower cobound
7283 along the @var{DIM} codimension.
7284 @item @emph{Standard}:
7285 Fortran 2008 and later
7290 @item @emph{Syntax}:
7291 @code{RESULT = LCOBOUND(COARRAY [, DIM [, KIND]])}
7293 @item @emph{Arguments}:
7294 @multitable @columnfractions .15 .70
7295 @item @var{ARRAY} @tab Shall be an coarray, of any type.
7296 @item @var{DIM} @tab (Optional) Shall be a scalar @code{INTEGER}.
7297 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
7298 expression indicating the kind parameter of the result.
7301 @item @emph{Return value}:
7302 The return value is of type @code{INTEGER} and of kind @var{KIND}. If
7303 @var{KIND} is absent, the return value is of default integer kind.
7304 If @var{DIM} is absent, the result is an array of the lower cobounds of
7305 @var{COARRAY}. If @var{DIM} is present, the result is a scalar
7306 corresponding to the lower cobound of the array along that codimension.
7308 @item @emph{See also}:
7309 @ref{UCOBOUND}, @ref{LBOUND}
7315 @section @code{LEADZ} --- Number of leading zero bits of an integer
7320 @item @emph{Description}:
7321 @code{LEADZ} returns the number of leading zero bits of an integer.
7323 @item @emph{Standard}:
7324 Fortran 2008 and later
7329 @item @emph{Syntax}:
7330 @code{RESULT = LEADZ(I)}
7332 @item @emph{Arguments}:
7333 @multitable @columnfractions .15 .70
7334 @item @var{I} @tab Shall be of type @code{INTEGER}.
7337 @item @emph{Return value}:
7338 The type of the return value is the default @code{INTEGER}.
7339 If all the bits of @code{I} are zero, the result value is @code{BIT_SIZE(I)}.
7341 @item @emph{Example}:
7344 WRITE (*,*) BIT_SIZE(1) ! prints 32
7345 WRITE (*,*) LEADZ(1) ! prints 31
7349 @item @emph{See also}:
7350 @ref{BIT_SIZE}, @ref{TRAILZ}, @ref{POPCNT}, @ref{POPPAR}
7356 @section @code{LEN} --- Length of a character entity
7358 @cindex string, length
7361 @item @emph{Description}:
7362 Returns the length of a character string. If @var{STRING} is an array,
7363 the length of an element of @var{STRING} is returned. Note that
7364 @var{STRING} need not be defined when this intrinsic is invoked, since
7365 only the length, not the content, of @var{STRING} is needed.
7367 @item @emph{Standard}:
7368 Fortran 77 and later, with @var{KIND} argument Fortran 2003 and later
7373 @item @emph{Syntax}:
7374 @code{L = LEN(STRING [, KIND])}
7376 @item @emph{Arguments}:
7377 @multitable @columnfractions .15 .70
7378 @item @var{STRING} @tab Shall be a scalar or array of type
7379 @code{CHARACTER}, with @code{INTENT(IN)}
7380 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
7381 expression indicating the kind parameter of the result.
7384 @item @emph{Return value}:
7385 The return value is of type @code{INTEGER} and of kind @var{KIND}. If
7386 @var{KIND} is absent, the return value is of default integer kind.
7389 @item @emph{Specific names}:
7390 @multitable @columnfractions .20 .20 .20 .25
7391 @item Name @tab Argument @tab Return type @tab Standard
7392 @item @code{LEN(STRING)} @tab @code{CHARACTER} @tab @code{INTEGER} @tab Fortran 77 and later
7396 @item @emph{See also}:
7397 @ref{LEN_TRIM}, @ref{ADJUSTL}, @ref{ADJUSTR}
7403 @section @code{LEN_TRIM} --- Length of a character entity without trailing blank characters
7405 @cindex string, length, without trailing whitespace
7408 @item @emph{Description}:
7409 Returns the length of a character string, ignoring any trailing blanks.
7411 @item @emph{Standard}:
7412 Fortran 95 and later, with @var{KIND} argument Fortran 2003 and later
7417 @item @emph{Syntax}:
7418 @code{RESULT = LEN_TRIM(STRING [, KIND])}
7420 @item @emph{Arguments}:
7421 @multitable @columnfractions .15 .70
7422 @item @var{STRING} @tab Shall be a scalar of type @code{CHARACTER},
7423 with @code{INTENT(IN)}
7424 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
7425 expression indicating the kind parameter of the result.
7428 @item @emph{Return value}:
7429 The return value is of type @code{INTEGER} and of kind @var{KIND}. If
7430 @var{KIND} is absent, the return value is of default integer kind.
7432 @item @emph{See also}:
7433 @ref{LEN}, @ref{ADJUSTL}, @ref{ADJUSTR}
7439 @section @code{LGE} --- Lexical greater than or equal
7441 @cindex lexical comparison of strings
7442 @cindex string, comparison
7445 @item @emph{Description}:
7446 Determines whether one string is lexically greater than or equal to
7447 another string, where the two strings are interpreted as containing
7448 ASCII character codes. If the String A and String B are not the same
7449 length, the shorter is compared as if spaces were appended to it to form
7450 a value that has the same length as the longer.
7452 In general, the lexical comparison intrinsics @code{LGE}, @code{LGT},
7453 @code{LLE}, and @code{LLT} differ from the corresponding intrinsic
7454 operators @code{.GE.}, @code{.GT.}, @code{.LE.}, and @code{.LT.}, in
7455 that the latter use the processor's character ordering (which is not
7456 ASCII on some targets), whereas the former always use the ASCII
7459 @item @emph{Standard}:
7460 Fortran 77 and later
7465 @item @emph{Syntax}:
7466 @code{RESULT = LGE(STRING_A, STRING_B)}
7468 @item @emph{Arguments}:
7469 @multitable @columnfractions .15 .70
7470 @item @var{STRING_A} @tab Shall be of default @code{CHARACTER} type.
7471 @item @var{STRING_B} @tab Shall be of default @code{CHARACTER} type.
7474 @item @emph{Return value}:
7475 Returns @code{.TRUE.} if @code{STRING_A >= STRING_B}, and @code{.FALSE.}
7476 otherwise, based on the ASCII ordering.
7478 @item @emph{Specific names}:
7479 @multitable @columnfractions .20 .20 .20 .25
7480 @item Name @tab Argument @tab Return type @tab Standard
7481 @item @code{LGE(STRING_A, STRING_B)} @tab @code{CHARACTER} @tab @code{LOGICAL} @tab Fortran 77 and later
7484 @item @emph{See also}:
7485 @ref{LGT}, @ref{LLE}, @ref{LLT}
7491 @section @code{LGT} --- Lexical greater than
7493 @cindex lexical comparison of strings
7494 @cindex string, comparison
7497 @item @emph{Description}:
7498 Determines whether one string is lexically greater than another string,
7499 where the two strings are interpreted as containing ASCII character
7500 codes. If the String A and String B are not the same length, the
7501 shorter is compared as if spaces were appended to it to form a value
7502 that has the same length as the longer.
7504 In general, the lexical comparison intrinsics @code{LGE}, @code{LGT},
7505 @code{LLE}, and @code{LLT} differ from the corresponding intrinsic
7506 operators @code{.GE.}, @code{.GT.}, @code{.LE.}, and @code{.LT.}, in
7507 that the latter use the processor's character ordering (which is not
7508 ASCII on some targets), whereas the former always use the ASCII
7511 @item @emph{Standard}:
7512 Fortran 77 and later
7517 @item @emph{Syntax}:
7518 @code{RESULT = LGT(STRING_A, STRING_B)}
7520 @item @emph{Arguments}:
7521 @multitable @columnfractions .15 .70
7522 @item @var{STRING_A} @tab Shall be of default @code{CHARACTER} type.
7523 @item @var{STRING_B} @tab Shall be of default @code{CHARACTER} type.
7526 @item @emph{Return value}:
7527 Returns @code{.TRUE.} if @code{STRING_A > STRING_B}, and @code{.FALSE.}
7528 otherwise, based on the ASCII ordering.
7530 @item @emph{Specific names}:
7531 @multitable @columnfractions .20 .20 .20 .25
7532 @item Name @tab Argument @tab Return type @tab Standard
7533 @item @code{LGT(STRING_A, STRING_B)} @tab @code{CHARACTER} @tab @code{LOGICAL} @tab Fortran 77 and later
7536 @item @emph{See also}:
7537 @ref{LGE}, @ref{LLE}, @ref{LLT}
7543 @section @code{LINK} --- Create a hard link
7545 @cindex file system, create link
7546 @cindex file system, hard link
7549 @item @emph{Description}:
7550 Makes a (hard) link from file @var{PATH1} to @var{PATH2}. A null
7551 character (@code{CHAR(0)}) can be used to mark the end of the names in
7552 @var{PATH1} and @var{PATH2}; otherwise, trailing blanks in the file
7553 names are ignored. If the @var{STATUS} argument is supplied, it
7554 contains 0 on success or a nonzero error code upon return; see
7557 This intrinsic is provided in both subroutine and function forms;
7558 however, only one form can be used in any given program unit.
7560 @item @emph{Standard}:
7564 Subroutine, function
7566 @item @emph{Syntax}:
7567 @multitable @columnfractions .80
7568 @item @code{CALL LINK(PATH1, PATH2 [, STATUS])}
7569 @item @code{STATUS = LINK(PATH1, PATH2)}
7572 @item @emph{Arguments}:
7573 @multitable @columnfractions .15 .70
7574 @item @var{PATH1} @tab Shall be of default @code{CHARACTER} type.
7575 @item @var{PATH2} @tab Shall be of default @code{CHARACTER} type.
7576 @item @var{STATUS} @tab (Optional) Shall be of default @code{INTEGER} type.
7579 @item @emph{See also}:
7580 @ref{SYMLNK}, @ref{UNLINK}
7586 @section @code{LLE} --- Lexical less than or equal
7588 @cindex lexical comparison of strings
7589 @cindex string, comparison
7592 @item @emph{Description}:
7593 Determines whether one string is lexically less than or equal to another
7594 string, where the two strings are interpreted as containing ASCII
7595 character codes. If the String A and String B are not the same length,
7596 the shorter is compared as if spaces were appended to it to form a value
7597 that has the same length as the longer.
7599 In general, the lexical comparison intrinsics @code{LGE}, @code{LGT},
7600 @code{LLE}, and @code{LLT} differ from the corresponding intrinsic
7601 operators @code{.GE.}, @code{.GT.}, @code{.LE.}, and @code{.LT.}, in
7602 that the latter use the processor's character ordering (which is not
7603 ASCII on some targets), whereas the former always use the ASCII
7606 @item @emph{Standard}:
7607 Fortran 77 and later
7612 @item @emph{Syntax}:
7613 @code{RESULT = LLE(STRING_A, STRING_B)}
7615 @item @emph{Arguments}:
7616 @multitable @columnfractions .15 .70
7617 @item @var{STRING_A} @tab Shall be of default @code{CHARACTER} type.
7618 @item @var{STRING_B} @tab Shall be of default @code{CHARACTER} type.
7621 @item @emph{Return value}:
7622 Returns @code{.TRUE.} if @code{STRING_A <= STRING_B}, and @code{.FALSE.}
7623 otherwise, based on the ASCII ordering.
7625 @item @emph{Specific names}:
7626 @multitable @columnfractions .20 .20 .20 .25
7627 @item Name @tab Argument @tab Return type @tab Standard
7628 @item @code{LLE(STRING_A, STRING_B)} @tab @code{CHARACTER} @tab @code{LOGICAL} @tab Fortran 77 and later
7631 @item @emph{See also}:
7632 @ref{LGE}, @ref{LGT}, @ref{LLT}
7638 @section @code{LLT} --- Lexical less than
7640 @cindex lexical comparison of strings
7641 @cindex string, comparison
7644 @item @emph{Description}:
7645 Determines whether one string is lexically less than another string,
7646 where the two strings are interpreted as containing ASCII character
7647 codes. If the String A and String B are not the same length, the
7648 shorter is compared as if spaces were appended to it to form a value
7649 that has the same length as the longer.
7651 In general, the lexical comparison intrinsics @code{LGE}, @code{LGT},
7652 @code{LLE}, and @code{LLT} differ from the corresponding intrinsic
7653 operators @code{.GE.}, @code{.GT.}, @code{.LE.}, and @code{.LT.}, in
7654 that the latter use the processor's character ordering (which is not
7655 ASCII on some targets), whereas the former always use the ASCII
7658 @item @emph{Standard}:
7659 Fortran 77 and later
7664 @item @emph{Syntax}:
7665 @code{RESULT = LLT(STRING_A, STRING_B)}
7667 @item @emph{Arguments}:
7668 @multitable @columnfractions .15 .70
7669 @item @var{STRING_A} @tab Shall be of default @code{CHARACTER} type.
7670 @item @var{STRING_B} @tab Shall be of default @code{CHARACTER} type.
7673 @item @emph{Return value}:
7674 Returns @code{.TRUE.} if @code{STRING_A < STRING_B}, and @code{.FALSE.}
7675 otherwise, based on the ASCII ordering.
7677 @item @emph{Specific names}:
7678 @multitable @columnfractions .20 .20 .20 .25
7679 @item Name @tab Argument @tab Return type @tab Standard
7680 @item @code{LLT(STRING_A, STRING_B)} @tab @code{CHARACTER} @tab @code{LOGICAL} @tab Fortran 77 and later
7683 @item @emph{See also}:
7684 @ref{LGE}, @ref{LGT}, @ref{LLE}
7690 @section @code{LNBLNK} --- Index of the last non-blank character in a string
7692 @cindex string, find non-blank character
7695 @item @emph{Description}:
7696 Returns the length of a character string, ignoring any trailing blanks.
7697 This is identical to the standard @code{LEN_TRIM} intrinsic, and is only
7698 included for backwards compatibility.
7700 @item @emph{Standard}:
7706 @item @emph{Syntax}:
7707 @code{RESULT = LNBLNK(STRING)}
7709 @item @emph{Arguments}:
7710 @multitable @columnfractions .15 .70
7711 @item @var{STRING} @tab Shall be a scalar of type @code{CHARACTER},
7712 with @code{INTENT(IN)}
7715 @item @emph{Return value}:
7716 The return value is of @code{INTEGER(kind=4)} type.
7718 @item @emph{See also}:
7719 @ref{INDEX intrinsic}, @ref{LEN_TRIM}
7725 @section @code{LOC} --- Returns the address of a variable
7727 @cindex location of a variable in memory
7730 @item @emph{Description}:
7731 @code{LOC(X)} returns the address of @var{X} as an integer.
7733 @item @emph{Standard}:
7739 @item @emph{Syntax}:
7740 @code{RESULT = LOC(X)}
7742 @item @emph{Arguments}:
7743 @multitable @columnfractions .15 .70
7744 @item @var{X} @tab Variable of any type.
7747 @item @emph{Return value}:
7748 The return value is of type @code{INTEGER}, with a @code{KIND}
7749 corresponding to the size (in bytes) of a memory address on the target
7752 @item @emph{Example}:
7759 end program test_loc
7766 @section @code{LOG} --- Natural logarithm function
7773 @cindex exponential function, inverse
7774 @cindex logarithm function
7775 @cindex natural logarithm function
7778 @item @emph{Description}:
7779 @code{LOG(X)} computes the natural logarithm of @var{X}, i.e. the
7780 logarithm to the base @math{e}.
7782 @item @emph{Standard}:
7783 Fortran 77 and later
7788 @item @emph{Syntax}:
7789 @code{RESULT = LOG(X)}
7791 @item @emph{Arguments}:
7792 @multitable @columnfractions .15 .70
7793 @item @var{X} @tab The type shall be @code{REAL} or
7797 @item @emph{Return value}:
7798 The return value is of type @code{REAL} or @code{COMPLEX}.
7799 The kind type parameter is the same as @var{X}.
7800 If @var{X} is @code{COMPLEX}, the imaginary part @math{\omega} is in the range
7801 @math{-\pi \leq \omega \leq \pi}.
7803 @item @emph{Example}:
7806 real(8) :: x = 2.7182818284590451_8
7807 complex :: z = (1.0, 2.0)
7808 x = log(x) ! will yield (approximately) 1
7810 end program test_log
7813 @item @emph{Specific names}:
7814 @multitable @columnfractions .20 .20 .20 .25
7815 @item Name @tab Argument @tab Return type @tab Standard
7816 @item @code{ALOG(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab f95, gnu
7817 @item @code{DLOG(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab f95, gnu
7818 @item @code{CLOG(X)} @tab @code{COMPLEX(4) X} @tab @code{COMPLEX(4)} @tab f95, gnu
7819 @item @code{ZLOG(X)} @tab @code{COMPLEX(8) X} @tab @code{COMPLEX(8)} @tab f95, gnu
7820 @item @code{CDLOG(X)} @tab @code{COMPLEX(8) X} @tab @code{COMPLEX(8)} @tab f95, gnu
7827 @section @code{LOG10} --- Base 10 logarithm function
7831 @cindex exponential function, inverse
7832 @cindex logarithm function with base 10
7833 @cindex base 10 logarithm function
7836 @item @emph{Description}:
7837 @code{LOG10(X)} computes the base 10 logarithm of @var{X}.
7839 @item @emph{Standard}:
7840 Fortran 77 and later
7845 @item @emph{Syntax}:
7846 @code{RESULT = LOG10(X)}
7848 @item @emph{Arguments}:
7849 @multitable @columnfractions .15 .70
7850 @item @var{X} @tab The type shall be @code{REAL}.
7853 @item @emph{Return value}:
7854 The return value is of type @code{REAL} or @code{COMPLEX}.
7855 The kind type parameter is the same as @var{X}.
7857 @item @emph{Example}:
7860 real(8) :: x = 10.0_8
7862 end program test_log10
7865 @item @emph{Specific names}:
7866 @multitable @columnfractions .20 .20 .20 .25
7867 @item Name @tab Argument @tab Return type @tab Standard
7868 @item @code{ALOG10(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab Fortran 95 and later
7869 @item @code{DLOG10(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab Fortran 95 and later
7876 @section @code{LOG_GAMMA} --- Logarithm of the Gamma function
7881 @cindex Gamma function, logarithm of
7884 @item @emph{Description}:
7885 @code{LOG_GAMMA(X)} computes the natural logarithm of the absolute value
7886 of the Gamma (@math{\Gamma}) function.
7888 @item @emph{Standard}:
7889 Fortran 2008 and later
7894 @item @emph{Syntax}:
7895 @code{X = LOG_GAMMA(X)}
7897 @item @emph{Arguments}:
7898 @multitable @columnfractions .15 .70
7899 @item @var{X} @tab Shall be of type @code{REAL} and neither zero
7900 nor a negative integer.
7903 @item @emph{Return value}:
7904 The return value is of type @code{REAL} of the same kind as @var{X}.
7906 @item @emph{Example}:
7908 program test_log_gamma
7910 x = lgamma(x) ! returns 0.0
7911 end program test_log_gamma
7914 @item @emph{Specific names}:
7915 @multitable @columnfractions .20 .20 .20 .25
7916 @item Name @tab Argument @tab Return type @tab Standard
7917 @item @code{LGAMMA(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab GNU Extension
7918 @item @code{ALGAMA(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab GNU Extension
7919 @item @code{DLGAMA(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU Extension
7922 @item @emph{See also}:
7923 Gamma function: @ref{GAMMA}
7930 @section @code{LOGICAL} --- Convert to logical type
7932 @cindex conversion, to logical
7935 @item @emph{Description}:
7936 Converts one kind of @code{LOGICAL} variable to another.
7938 @item @emph{Standard}:
7939 Fortran 95 and later
7944 @item @emph{Syntax}:
7945 @code{RESULT = LOGICAL(L [, KIND])}
7947 @item @emph{Arguments}:
7948 @multitable @columnfractions .15 .70
7949 @item @var{L} @tab The type shall be @code{LOGICAL}.
7950 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
7951 expression indicating the kind parameter of the result.
7954 @item @emph{Return value}:
7955 The return value is a @code{LOGICAL} value equal to @var{L}, with a
7956 kind corresponding to @var{KIND}, or of the default logical kind if
7957 @var{KIND} is not given.
7959 @item @emph{See also}:
7960 @ref{INT}, @ref{REAL}, @ref{CMPLX}
7966 @section @code{LONG} --- Convert to integer type
7968 @cindex conversion, to integer
7971 @item @emph{Description}:
7972 Convert to a @code{KIND=4} integer type, which is the same size as a C
7973 @code{long} integer. This is equivalent to the standard @code{INT}
7974 intrinsic with an optional argument of @code{KIND=4}, and is only
7975 included for backwards compatibility.
7977 @item @emph{Standard}:
7983 @item @emph{Syntax}:
7984 @code{RESULT = LONG(A)}
7986 @item @emph{Arguments}:
7987 @multitable @columnfractions .15 .70
7988 @item @var{A} @tab Shall be of type @code{INTEGER},
7989 @code{REAL}, or @code{COMPLEX}.
7992 @item @emph{Return value}:
7993 The return value is a @code{INTEGER(4)} variable.
7995 @item @emph{See also}:
7996 @ref{INT}, @ref{INT2}, @ref{INT8}
8002 @section @code{LSHIFT} --- Left shift bits
8004 @cindex bits, shift left
8007 @item @emph{Description}:
8008 @code{LSHIFT} returns a value corresponding to @var{I} with all of the
8009 bits shifted left by @var{SHIFT} places. If the absolute value of
8010 @var{SHIFT} is greater than @code{BIT_SIZE(I)}, the value is undefined.
8011 Bits shifted out from the left end are lost; zeros are shifted in from
8014 This function has been superseded by the @code{ISHFT} intrinsic, which
8015 is standard in Fortran 95 and later, and the @code{SHIFTL} intrinsic,
8016 which is standard in Fortran 2008 and later.
8018 @item @emph{Standard}:
8024 @item @emph{Syntax}:
8025 @code{RESULT = LSHIFT(I, SHIFT)}
8027 @item @emph{Arguments}:
8028 @multitable @columnfractions .15 .70
8029 @item @var{I} @tab The type shall be @code{INTEGER}.
8030 @item @var{SHIFT} @tab The type shall be @code{INTEGER}.
8033 @item @emph{Return value}:
8034 The return value is of type @code{INTEGER} and of the same kind as
8037 @item @emph{See also}:
8038 @ref{ISHFT}, @ref{ISHFTC}, @ref{RSHIFT}, @ref{SHIFTA}, @ref{SHIFTL},
8046 @section @code{LSTAT} --- Get file status
8048 @cindex file system, file status
8051 @item @emph{Description}:
8052 @code{LSTAT} is identical to @ref{STAT}, except that if path is a
8053 symbolic link, then the link itself is statted, not the file that it
8056 The elements in @code{VALUES} are the same as described by @ref{STAT}.
8058 This intrinsic is provided in both subroutine and function forms;
8059 however, only one form can be used in any given program unit.
8061 @item @emph{Standard}:
8065 Subroutine, function
8067 @item @emph{Syntax}:
8068 @multitable @columnfractions .80
8069 @item @code{CALL LSTAT(NAME, VALUES [, STATUS])}
8070 @item @code{STATUS = LSTAT(NAME, VALUES)}
8073 @item @emph{Arguments}:
8074 @multitable @columnfractions .15 .70
8075 @item @var{NAME} @tab The type shall be @code{CHARACTER} of the default
8076 kind, a valid path within the file system.
8077 @item @var{VALUES} @tab The type shall be @code{INTEGER(4), DIMENSION(13)}.
8078 @item @var{STATUS} @tab (Optional) status flag of type @code{INTEGER(4)}.
8079 Returns 0 on success and a system specific error code otherwise.
8082 @item @emph{Example}:
8083 See @ref{STAT} for an example.
8085 @item @emph{See also}:
8086 To stat an open file: @ref{FSTAT}, to stat a file: @ref{STAT}
8092 @section @code{LTIME} --- Convert time to local time info
8094 @cindex time, conversion to local time info
8097 @item @emph{Description}:
8098 Given a system time value @var{TIME} (as provided by the @code{TIME8}
8099 intrinsic), fills @var{VALUES} with values extracted from it appropriate
8100 to the local time zone using @code{localtime(3)}.
8102 @item @emph{Standard}:
8108 @item @emph{Syntax}:
8109 @code{CALL LTIME(TIME, VALUES)}
8111 @item @emph{Arguments}:
8112 @multitable @columnfractions .15 .70
8113 @item @var{TIME} @tab An @code{INTEGER} scalar expression
8114 corresponding to a system time, with @code{INTENT(IN)}.
8115 @item @var{VALUES} @tab A default @code{INTEGER} array with 9 elements,
8116 with @code{INTENT(OUT)}.
8119 @item @emph{Return value}:
8120 The elements of @var{VALUES} are assigned as follows:
8122 @item Seconds after the minute, range 0--59 or 0--61 to allow for leap
8124 @item Minutes after the hour, range 0--59
8125 @item Hours past midnight, range 0--23
8126 @item Day of month, range 0--31
8127 @item Number of months since January, range 0--12
8128 @item Years since 1900
8129 @item Number of days since Sunday, range 0--6
8130 @item Days since January 1
8131 @item Daylight savings indicator: positive if daylight savings is in
8132 effect, zero if not, and negative if the information is not available.
8135 @item @emph{See also}:
8136 @ref{CTIME}, @ref{GMTIME}, @ref{TIME}, @ref{TIME8}
8143 @section @code{MALLOC} --- Allocate dynamic memory
8145 @cindex pointer, cray
8148 @item @emph{Description}:
8149 @code{MALLOC(SIZE)} allocates @var{SIZE} bytes of dynamic memory and
8150 returns the address of the allocated memory. The @code{MALLOC} intrinsic
8151 is an extension intended to be used with Cray pointers, and is provided
8152 in GNU Fortran to allow the user to compile legacy code. For new code
8153 using Fortran 95 pointers, the memory allocation intrinsic is
8156 @item @emph{Standard}:
8162 @item @emph{Syntax}:
8163 @code{PTR = MALLOC(SIZE)}
8165 @item @emph{Arguments}:
8166 @multitable @columnfractions .15 .70
8167 @item @var{SIZE} @tab The type shall be @code{INTEGER}.
8170 @item @emph{Return value}:
8171 The return value is of type @code{INTEGER(K)}, with @var{K} such that
8172 variables of type @code{INTEGER(K)} have the same size as
8173 C pointers (@code{sizeof(void *)}).
8175 @item @emph{Example}:
8176 The following example demonstrates the use of @code{MALLOC} and
8177 @code{FREE} with Cray pointers.
8186 ptr_x = malloc(20*8)
8188 x(i) = sqrt(1.0d0 / i)
8196 end program test_malloc
8199 @item @emph{See also}:
8206 @section @code{MASKL} --- Left justified mask
8208 @cindex mask, left justified
8211 @item @emph{Description}:
8212 @code{MASKL(I[, KIND])} has its leftmost @var{I} bits set to 1, and the
8213 remaining bits set to 0.
8215 @item @emph{Standard}:
8216 Fortran 2008 and later
8221 @item @emph{Syntax}:
8222 @code{RESULT = MASKL(I[, KIND])}
8224 @item @emph{Arguments}:
8225 @multitable @columnfractions .15 .70
8226 @item @var{I} @tab Shall be of type @code{INTEGER}.
8227 @item @var{KIND} @tab Shall be a scalar constant expression of type
8231 @item @emph{Return value}:
8232 The return value is of type @code{INTEGER}. If @var{KIND} is present, it
8233 specifies the kind value of the return type; otherwise, it is of the
8234 default integer kind.
8236 @item @emph{See also}:
8243 @section @code{MASKR} --- Right justified mask
8245 @cindex mask, right justified
8248 @item @emph{Description}:
8249 @code{MASKL(I[, KIND])} has its rightmost @var{I} bits set to 1, and the
8250 remaining bits set to 0.
8252 @item @emph{Standard}:
8253 Fortran 2008 and later
8258 @item @emph{Syntax}:
8259 @code{RESULT = MASKR(I[, KIND])}
8261 @item @emph{Arguments}:
8262 @multitable @columnfractions .15 .70
8263 @item @var{I} @tab Shall be of type @code{INTEGER}.
8264 @item @var{KIND} @tab Shall be a scalar constant expression of type
8268 @item @emph{Return value}:
8269 The return value is of type @code{INTEGER}. If @var{KIND} is present, it
8270 specifies the kind value of the return type; otherwise, it is of the
8271 default integer kind.
8273 @item @emph{See also}:
8280 @section @code{MATMUL} --- matrix multiplication
8282 @cindex matrix multiplication
8283 @cindex product, matrix
8286 @item @emph{Description}:
8287 Performs a matrix multiplication on numeric or logical arguments.
8289 @item @emph{Standard}:
8290 Fortran 95 and later
8293 Transformational function
8295 @item @emph{Syntax}:
8296 @code{RESULT = MATMUL(MATRIX_A, MATRIX_B)}
8298 @item @emph{Arguments}:
8299 @multitable @columnfractions .15 .70
8300 @item @var{MATRIX_A} @tab An array of @code{INTEGER},
8301 @code{REAL}, @code{COMPLEX}, or @code{LOGICAL} type, with a rank of
8303 @item @var{MATRIX_B} @tab An array of @code{INTEGER},
8304 @code{REAL}, or @code{COMPLEX} type if @var{MATRIX_A} is of a numeric
8305 type; otherwise, an array of @code{LOGICAL} type. The rank shall be one
8306 or two, and the first (or only) dimension of @var{MATRIX_B} shall be
8307 equal to the last (or only) dimension of @var{MATRIX_A}.
8310 @item @emph{Return value}:
8311 The matrix product of @var{MATRIX_A} and @var{MATRIX_B}. The type and
8312 kind of the result follow the usual type and kind promotion rules, as
8313 for the @code{*} or @code{.AND.} operators.
8315 @item @emph{See also}:
8321 @section @code{MAX} --- Maximum value of an argument list
8328 @cindex maximum value
8331 @item @emph{Description}:
8332 Returns the argument with the largest (most positive) value.
8334 @item @emph{Standard}:
8335 Fortran 77 and later
8340 @item @emph{Syntax}:
8341 @code{RESULT = MAX(A1, A2 [, A3 [, ...]])}
8343 @item @emph{Arguments}:
8344 @multitable @columnfractions .15 .70
8345 @item @var{A1} @tab The type shall be @code{INTEGER} or
8347 @item @var{A2}, @var{A3}, ... @tab An expression of the same type and kind
8348 as @var{A1}. (As a GNU extension, arguments of different kinds are
8352 @item @emph{Return value}:
8353 The return value corresponds to the maximum value among the arguments,
8354 and has the same type and kind as the first argument.
8356 @item @emph{Specific names}:
8357 @multitable @columnfractions .20 .20 .20 .25
8358 @item Name @tab Argument @tab Return type @tab Standard
8359 @item @code{MAX0(A1)} @tab @code{INTEGER(4) A1} @tab @code{INTEGER(4)} @tab Fortran 77 and later
8360 @item @code{AMAX0(A1)} @tab @code{INTEGER(4) A1} @tab @code{REAL(MAX(X))} @tab Fortran 77 and later
8361 @item @code{MAX1(A1)} @tab @code{REAL A1} @tab @code{INT(MAX(X))} @tab Fortran 77 and later
8362 @item @code{AMAX1(A1)} @tab @code{REAL(4) A1} @tab @code{REAL(4)} @tab Fortran 77 and later
8363 @item @code{DMAX1(A1)} @tab @code{REAL(8) A1} @tab @code{REAL(8)} @tab Fortran 77 and later
8366 @item @emph{See also}:
8367 @ref{MAXLOC} @ref{MAXVAL}, @ref{MIN}
8374 @section @code{MAXEXPONENT} --- Maximum exponent of a real kind
8375 @fnindex MAXEXPONENT
8376 @cindex model representation, maximum exponent
8379 @item @emph{Description}:
8380 @code{MAXEXPONENT(X)} returns the maximum exponent in the model of the
8383 @item @emph{Standard}:
8384 Fortran 95 and later
8389 @item @emph{Syntax}:
8390 @code{RESULT = MAXEXPONENT(X)}
8392 @item @emph{Arguments}:
8393 @multitable @columnfractions .15 .70
8394 @item @var{X} @tab Shall be of type @code{REAL}.
8397 @item @emph{Return value}:
8398 The return value is of type @code{INTEGER} and of the default integer
8401 @item @emph{Example}:
8407 print *, minexponent(x), maxexponent(x)
8408 print *, minexponent(y), maxexponent(y)
8409 end program exponents
8416 @section @code{MAXLOC} --- Location of the maximum value within an array
8418 @cindex array, location of maximum element
8421 @item @emph{Description}:
8422 Determines the location of the element in the array with the maximum
8423 value, or, if the @var{DIM} argument is supplied, determines the
8424 locations of the maximum element along each row of the array in the
8425 @var{DIM} direction. If @var{MASK} is present, only the elements for
8426 which @var{MASK} is @code{.TRUE.} are considered. If more than one
8427 element in the array has the maximum value, the location returned is
8428 that of the first such element in array element order. If the array has
8429 zero size, or all of the elements of @var{MASK} are @code{.FALSE.}, then
8430 the result is an array of zeroes. Similarly, if @var{DIM} is supplied
8431 and all of the elements of @var{MASK} along a given row are zero, the
8432 result value for that row is zero.
8434 @item @emph{Standard}:
8435 Fortran 95 and later
8438 Transformational function
8440 @item @emph{Syntax}:
8441 @multitable @columnfractions .80
8442 @item @code{RESULT = MAXLOC(ARRAY, DIM [, MASK])}
8443 @item @code{RESULT = MAXLOC(ARRAY [, MASK])}
8446 @item @emph{Arguments}:
8447 @multitable @columnfractions .15 .70
8448 @item @var{ARRAY} @tab Shall be an array of type @code{INTEGER} or
8450 @item @var{DIM} @tab (Optional) Shall be a scalar of type
8451 @code{INTEGER}, with a value between one and the rank of @var{ARRAY},
8452 inclusive. It may not be an optional dummy argument.
8453 @item @var{MASK} @tab Shall be an array of type @code{LOGICAL},
8454 and conformable with @var{ARRAY}.
8457 @item @emph{Return value}:
8458 If @var{DIM} is absent, the result is a rank-one array with a length
8459 equal to the rank of @var{ARRAY}. If @var{DIM} is present, the result
8460 is an array with a rank one less than the rank of @var{ARRAY}, and a
8461 size corresponding to the size of @var{ARRAY} with the @var{DIM}
8462 dimension removed. If @var{DIM} is present and @var{ARRAY} has a rank
8463 of one, the result is a scalar. In all cases, the result is of default
8464 @code{INTEGER} type.
8466 @item @emph{See also}:
8467 @ref{MAX}, @ref{MAXVAL}
8474 @section @code{MAXVAL} --- Maximum value of an array
8476 @cindex array, maximum value
8477 @cindex maximum value
8480 @item @emph{Description}:
8481 Determines the maximum value of the elements in an array value, or, if
8482 the @var{DIM} argument is supplied, determines the maximum value along
8483 each row of the array in the @var{DIM} direction. If @var{MASK} is
8484 present, only the elements for which @var{MASK} is @code{.TRUE.} are
8485 considered. If the array has zero size, or all of the elements of
8486 @var{MASK} are @code{.FALSE.}, then the result is @code{-HUGE(ARRAY)}
8487 if @var{ARRAY} is numeric, or a string of nulls if @var{ARRAY} is of character
8490 @item @emph{Standard}:
8491 Fortran 95 and later
8494 Transformational function
8496 @item @emph{Syntax}:
8497 @multitable @columnfractions .80
8498 @item @code{RESULT = MAXVAL(ARRAY, DIM [, MASK])}
8499 @item @code{RESULT = MAXVAL(ARRAY [, MASK])}
8502 @item @emph{Arguments}:
8503 @multitable @columnfractions .15 .70
8504 @item @var{ARRAY} @tab Shall be an array of type @code{INTEGER} or
8506 @item @var{DIM} @tab (Optional) Shall be a scalar of type
8507 @code{INTEGER}, with a value between one and the rank of @var{ARRAY},
8508 inclusive. It may not be an optional dummy argument.
8509 @item @var{MASK} @tab Shall be an array of type @code{LOGICAL},
8510 and conformable with @var{ARRAY}.
8513 @item @emph{Return value}:
8514 If @var{DIM} is absent, or if @var{ARRAY} has a rank of one, the result
8515 is a scalar. If @var{DIM} is present, the result is an array with a
8516 rank one less than the rank of @var{ARRAY}, and a size corresponding to
8517 the size of @var{ARRAY} with the @var{DIM} dimension removed. In all
8518 cases, the result is of the same type and kind as @var{ARRAY}.
8520 @item @emph{See also}:
8521 @ref{MAX}, @ref{MAXLOC}
8527 @section @code{MCLOCK} --- Time function
8529 @cindex time, clock ticks
8533 @item @emph{Description}:
8534 Returns the number of clock ticks since the start of the process, based
8535 on the UNIX function @code{clock(3)}.
8537 This intrinsic is not fully portable, such as to systems with 32-bit
8538 @code{INTEGER} types but supporting times wider than 32 bits. Therefore,
8539 the values returned by this intrinsic might be, or become, negative, or
8540 numerically less than previous values, during a single run of the
8543 @item @emph{Standard}:
8549 @item @emph{Syntax}:
8550 @code{RESULT = MCLOCK()}
8552 @item @emph{Return value}:
8553 The return value is a scalar of type @code{INTEGER(4)}, equal to the
8554 number of clock ticks since the start of the process, or @code{-1} if
8555 the system does not support @code{clock(3)}.
8557 @item @emph{See also}:
8558 @ref{CTIME}, @ref{GMTIME}, @ref{LTIME}, @ref{MCLOCK}, @ref{TIME}
8565 @section @code{MCLOCK8} --- Time function (64-bit)
8567 @cindex time, clock ticks
8571 @item @emph{Description}:
8572 Returns the number of clock ticks since the start of the process, based
8573 on the UNIX function @code{clock(3)}.
8575 @emph{Warning:} this intrinsic does not increase the range of the timing
8576 values over that returned by @code{clock(3)}. On a system with a 32-bit
8577 @code{clock(3)}, @code{MCLOCK8} will return a 32-bit value, even though
8578 it is converted to a 64-bit @code{INTEGER(8)} value. That means
8579 overflows of the 32-bit value can still occur. Therefore, the values
8580 returned by this intrinsic might be or become negative or numerically
8581 less than previous values during a single run of the compiled program.
8583 @item @emph{Standard}:
8589 @item @emph{Syntax}:
8590 @code{RESULT = MCLOCK8()}
8592 @item @emph{Return value}:
8593 The return value is a scalar of type @code{INTEGER(8)}, equal to the
8594 number of clock ticks since the start of the process, or @code{-1} if
8595 the system does not support @code{clock(3)}.
8597 @item @emph{See also}:
8598 @ref{CTIME}, @ref{GMTIME}, @ref{LTIME}, @ref{MCLOCK}, @ref{TIME8}
8605 @section @code{MERGE} --- Merge variables
8607 @cindex array, merge arrays
8608 @cindex array, combine arrays
8611 @item @emph{Description}:
8612 Select values from two arrays according to a logical mask. The result
8613 is equal to @var{TSOURCE} if @var{MASK} is @code{.TRUE.}, or equal to
8614 @var{FSOURCE} if it is @code{.FALSE.}.
8616 @item @emph{Standard}:
8617 Fortran 95 and later
8622 @item @emph{Syntax}:
8623 @code{RESULT = MERGE(TSOURCE, FSOURCE, MASK)}
8625 @item @emph{Arguments}:
8626 @multitable @columnfractions .15 .70
8627 @item @var{TSOURCE} @tab May be of any type.
8628 @item @var{FSOURCE} @tab Shall be of the same type and type parameters
8630 @item @var{MASK} @tab Shall be of type @code{LOGICAL}.
8633 @item @emph{Return value}:
8634 The result is of the same type and type parameters as @var{TSOURCE}.
8641 @section @code{MERGE_BITS} --- Merge of bits under mask
8646 @item @emph{Description}:
8647 @code{MERGE_BITS(I, J, MASK)} merges the bits of @var{I} and @var{J}
8648 as determined by the mask. The i-th bit of the result is equal to the
8649 i-th bit of @var{I} if the i-th bit of @var{MASK} is 1; it is equal to
8650 the i-th bit of @var{J} otherwise.
8652 @item @emph{Standard}:
8653 Fortran 2008 and later
8658 @item @emph{Syntax}:
8659 @code{RESULT = MERGE_BITS(I, J, MASK)}
8661 @item @emph{Arguments}:
8662 @multitable @columnfractions .15 .70
8663 @item @var{I} @tab Shall be of type @code{INTEGER}.
8664 @item @var{J} @tab Shall be of type @code{INTEGER} and of the same
8666 @item @var{MASK} @tab Shall be of type @code{INTEGER} and of the same
8670 @item @emph{Return value}:
8671 The result is of the same type and kind as @var{I}.
8678 @section @code{MIN} --- Minimum value of an argument list
8685 @cindex minimum value
8688 @item @emph{Description}:
8689 Returns the argument with the smallest (most negative) value.
8691 @item @emph{Standard}:
8692 Fortran 77 and later
8697 @item @emph{Syntax}:
8698 @code{RESULT = MIN(A1, A2 [, A3, ...])}
8700 @item @emph{Arguments}:
8701 @multitable @columnfractions .15 .70
8702 @item @var{A1} @tab The type shall be @code{INTEGER} or
8704 @item @var{A2}, @var{A3}, ... @tab An expression of the same type and kind
8705 as @var{A1}. (As a GNU extension, arguments of different kinds are
8709 @item @emph{Return value}:
8710 The return value corresponds to the maximum value among the arguments,
8711 and has the same type and kind as the first argument.
8713 @item @emph{Specific names}:
8714 @multitable @columnfractions .20 .20 .20 .25
8715 @item Name @tab Argument @tab Return type @tab Standard
8716 @item @code{MIN0(A1)} @tab @code{INTEGER(4) A1} @tab @code{INTEGER(4)} @tab Fortran 77 and later
8717 @item @code{AMIN0(A1)} @tab @code{INTEGER(4) A1} @tab @code{REAL(4)} @tab Fortran 77 and later
8718 @item @code{MIN1(A1)} @tab @code{REAL A1} @tab @code{INTEGER(4)} @tab Fortran 77 and later
8719 @item @code{AMIN1(A1)} @tab @code{REAL(4) A1} @tab @code{REAL(4)} @tab Fortran 77 and later
8720 @item @code{DMIN1(A1)} @tab @code{REAL(8) A1} @tab @code{REAL(8)} @tab Fortran 77 and later
8723 @item @emph{See also}:
8724 @ref{MAX}, @ref{MINLOC}, @ref{MINVAL}
8730 @section @code{MINEXPONENT} --- Minimum exponent of a real kind
8731 @fnindex MINEXPONENT
8732 @cindex model representation, minimum exponent
8735 @item @emph{Description}:
8736 @code{MINEXPONENT(X)} returns the minimum exponent in the model of the
8739 @item @emph{Standard}:
8740 Fortran 95 and later
8745 @item @emph{Syntax}:
8746 @code{RESULT = MINEXPONENT(X)}
8748 @item @emph{Arguments}:
8749 @multitable @columnfractions .15 .70
8750 @item @var{X} @tab Shall be of type @code{REAL}.
8753 @item @emph{Return value}:
8754 The return value is of type @code{INTEGER} and of the default integer
8757 @item @emph{Example}:
8758 See @code{MAXEXPONENT} for an example.
8764 @section @code{MINLOC} --- Location of the minimum value within an array
8766 @cindex array, location of minimum element
8769 @item @emph{Description}:
8770 Determines the location of the element in the array with the minimum
8771 value, or, if the @var{DIM} argument is supplied, determines the
8772 locations of the minimum element along each row of the array in the
8773 @var{DIM} direction. If @var{MASK} is present, only the elements for
8774 which @var{MASK} is @code{.TRUE.} are considered. If more than one
8775 element in the array has the minimum value, the location returned is
8776 that of the first such element in array element order. If the array has
8777 zero size, or all of the elements of @var{MASK} are @code{.FALSE.}, then
8778 the result is an array of zeroes. Similarly, if @var{DIM} is supplied
8779 and all of the elements of @var{MASK} along a given row are zero, the
8780 result value for that row is zero.
8782 @item @emph{Standard}:
8783 Fortran 95 and later
8786 Transformational function
8788 @item @emph{Syntax}:
8789 @multitable @columnfractions .80
8790 @item @code{RESULT = MINLOC(ARRAY, DIM [, MASK])}
8791 @item @code{RESULT = MINLOC(ARRAY [, MASK])}
8794 @item @emph{Arguments}:
8795 @multitable @columnfractions .15 .70
8796 @item @var{ARRAY} @tab Shall be an array of type @code{INTEGER} or
8798 @item @var{DIM} @tab (Optional) Shall be a scalar of type
8799 @code{INTEGER}, with a value between one and the rank of @var{ARRAY},
8800 inclusive. It may not be an optional dummy argument.
8801 @item @var{MASK} @tab Shall be an array of type @code{LOGICAL},
8802 and conformable with @var{ARRAY}.
8805 @item @emph{Return value}:
8806 If @var{DIM} is absent, the result is a rank-one array with a length
8807 equal to the rank of @var{ARRAY}. If @var{DIM} is present, the result
8808 is an array with a rank one less than the rank of @var{ARRAY}, and a
8809 size corresponding to the size of @var{ARRAY} with the @var{DIM}
8810 dimension removed. If @var{DIM} is present and @var{ARRAY} has a rank
8811 of one, the result is a scalar. In all cases, the result is of default
8812 @code{INTEGER} type.
8814 @item @emph{See also}:
8815 @ref{MIN}, @ref{MINVAL}
8822 @section @code{MINVAL} --- Minimum value of an array
8824 @cindex array, minimum value
8825 @cindex minimum value
8828 @item @emph{Description}:
8829 Determines the minimum value of the elements in an array value, or, if
8830 the @var{DIM} argument is supplied, determines the minimum value along
8831 each row of the array in the @var{DIM} direction. If @var{MASK} is
8832 present, only the elements for which @var{MASK} is @code{.TRUE.} are
8833 considered. If the array has zero size, or all of the elements of
8834 @var{MASK} are @code{.FALSE.}, then the result is @code{HUGE(ARRAY)} if
8835 @var{ARRAY} is numeric, or a string of @code{CHAR(255)} characters if
8836 @var{ARRAY} is of character type.
8838 @item @emph{Standard}:
8839 Fortran 95 and later
8842 Transformational function
8844 @item @emph{Syntax}:
8845 @multitable @columnfractions .80
8846 @item @code{RESULT = MINVAL(ARRAY, DIM [, MASK])}
8847 @item @code{RESULT = MINVAL(ARRAY [, MASK])}
8850 @item @emph{Arguments}:
8851 @multitable @columnfractions .15 .70
8852 @item @var{ARRAY} @tab Shall be an array of type @code{INTEGER} or
8854 @item @var{DIM} @tab (Optional) Shall be a scalar of type
8855 @code{INTEGER}, with a value between one and the rank of @var{ARRAY},
8856 inclusive. It may not be an optional dummy argument.
8857 @item @var{MASK} @tab Shall be an array of type @code{LOGICAL},
8858 and conformable with @var{ARRAY}.
8861 @item @emph{Return value}:
8862 If @var{DIM} is absent, or if @var{ARRAY} has a rank of one, the result
8863 is a scalar. If @var{DIM} is present, the result is an array with a
8864 rank one less than the rank of @var{ARRAY}, and a size corresponding to
8865 the size of @var{ARRAY} with the @var{DIM} dimension removed. In all
8866 cases, the result is of the same type and kind as @var{ARRAY}.
8868 @item @emph{See also}:
8869 @ref{MIN}, @ref{MINLOC}
8876 @section @code{MOD} --- Remainder function
8881 @cindex division, remainder
8884 @item @emph{Description}:
8885 @code{MOD(A,P)} computes the remainder of the division of A by P@. It is
8886 calculated as @code{A - (INT(A/P) * P)}.
8888 @item @emph{Standard}:
8889 Fortran 77 and later
8894 @item @emph{Syntax}:
8895 @code{RESULT = MOD(A, P)}
8897 @item @emph{Arguments}:
8898 @multitable @columnfractions .15 .70
8899 @item @var{A} @tab Shall be a scalar of type @code{INTEGER} or @code{REAL}
8900 @item @var{P} @tab Shall be a scalar of the same type as @var{A} and not
8904 @item @emph{Return value}:
8905 The kind of the return value is the result of cross-promoting
8906 the kinds of the arguments.
8908 @item @emph{Example}:
8912 print *, mod(17.5,5.5)
8913 print *, mod(17.5d0,5.5)
8914 print *, mod(17.5,5.5d0)
8917 print *, mod(-17.5,5.5)
8918 print *, mod(-17.5d0,5.5)
8919 print *, mod(-17.5,5.5d0)
8922 print *, mod(17.5,-5.5)
8923 print *, mod(17.5d0,-5.5)
8924 print *, mod(17.5,-5.5d0)
8925 end program test_mod
8928 @item @emph{Specific names}:
8929 @multitable @columnfractions .20 .20 .20 .25
8930 @item Name @tab Arguments @tab Return type @tab Standard
8931 @item @code{MOD(A,P)} @tab @code{INTEGER A,P} @tab @code{INTEGER} @tab Fortran 95 and later
8932 @item @code{AMOD(A,P)} @tab @code{REAL(4) A,P} @tab @code{REAL(4)} @tab Fortran 95 and later
8933 @item @code{DMOD(A,P)} @tab @code{REAL(8) A,P} @tab @code{REAL(8)} @tab Fortran 95 and later
8940 @section @code{MODULO} --- Modulo function
8943 @cindex division, modulo
8946 @item @emph{Description}:
8947 @code{MODULO(A,P)} computes the @var{A} modulo @var{P}.
8949 @item @emph{Standard}:
8950 Fortran 95 and later
8955 @item @emph{Syntax}:
8956 @code{RESULT = MODULO(A, P)}
8958 @item @emph{Arguments}:
8959 @multitable @columnfractions .15 .70
8960 @item @var{A} @tab Shall be a scalar of type @code{INTEGER} or @code{REAL}
8961 @item @var{P} @tab Shall be a scalar of the same type and kind as @var{A}
8964 @item @emph{Return value}:
8965 The type and kind of the result are those of the arguments.
8967 @item If @var{A} and @var{P} are of type @code{INTEGER}:
8968 @code{MODULO(A,P)} has the value @var{R} such that @code{A=Q*P+R}, where
8969 @var{Q} is an integer and @var{R} is between 0 (inclusive) and @var{P}
8971 @item If @var{A} and @var{P} are of type @code{REAL}:
8972 @code{MODULO(A,P)} has the value of @code{A - FLOOR (A / P) * P}.
8974 In all cases, if @var{P} is zero the result is processor-dependent.
8976 @item @emph{Example}:
8979 print *, modulo(17,3)
8980 print *, modulo(17.5,5.5)
8982 print *, modulo(-17,3)
8983 print *, modulo(-17.5,5.5)
8985 print *, modulo(17,-3)
8986 print *, modulo(17.5,-5.5)
8995 @section @code{MOVE_ALLOC} --- Move allocation from one object to another
8997 @cindex moving allocation
8998 @cindex allocation, moving
9001 @item @emph{Description}:
9002 @code{MOVE_ALLOC(FROM, TO)} moves the allocation from @var{FROM} to
9003 @var{TO}. @var{FROM} will become deallocated in the process.
9005 @item @emph{Standard}:
9006 Fortran 2003 and later
9011 @item @emph{Syntax}:
9012 @code{CALL MOVE_ALLOC(FROM, TO)}
9014 @item @emph{Arguments}:
9015 @multitable @columnfractions .15 .70
9016 @item @var{FROM} @tab @code{ALLOCATABLE}, @code{INTENT(INOUT)}, may be
9017 of any type and kind.
9018 @item @var{TO} @tab @code{ALLOCATABLE}, @code{INTENT(OUT)}, shall be
9019 of the same type, kind and rank as @var{FROM}.
9022 @item @emph{Return value}:
9025 @item @emph{Example}:
9027 program test_move_alloc
9028 integer, allocatable :: a(:), b(:)
9032 call move_alloc(a, b)
9033 print *, allocated(a), allocated(b)
9035 end program test_move_alloc
9042 @section @code{MVBITS} --- Move bits from one integer to another
9047 @item @emph{Description}:
9048 Moves @var{LEN} bits from positions @var{FROMPOS} through
9049 @code{FROMPOS+LEN-1} of @var{FROM} to positions @var{TOPOS} through
9050 @code{TOPOS+LEN-1} of @var{TO}. The portion of argument @var{TO} not
9051 affected by the movement of bits is unchanged. The values of
9052 @code{FROMPOS+LEN-1} and @code{TOPOS+LEN-1} must be less than
9053 @code{BIT_SIZE(FROM)}.
9055 @item @emph{Standard}:
9056 Fortran 95 and later
9059 Elemental subroutine
9061 @item @emph{Syntax}:
9062 @code{CALL MVBITS(FROM, FROMPOS, LEN, TO, TOPOS)}
9064 @item @emph{Arguments}:
9065 @multitable @columnfractions .15 .70
9066 @item @var{FROM} @tab The type shall be @code{INTEGER}.
9067 @item @var{FROMPOS} @tab The type shall be @code{INTEGER}.
9068 @item @var{LEN} @tab The type shall be @code{INTEGER}.
9069 @item @var{TO} @tab The type shall be @code{INTEGER}, of the
9070 same kind as @var{FROM}.
9071 @item @var{TOPOS} @tab The type shall be @code{INTEGER}.
9074 @item @emph{See also}:
9075 @ref{IBCLR}, @ref{IBSET}, @ref{IBITS}, @ref{IAND}, @ref{IOR}, @ref{IEOR}
9081 @section @code{NEAREST} --- Nearest representable number
9083 @cindex real number, nearest different
9084 @cindex floating point, nearest different
9087 @item @emph{Description}:
9088 @code{NEAREST(X, S)} returns the processor-representable number nearest
9089 to @code{X} in the direction indicated by the sign of @code{S}.
9091 @item @emph{Standard}:
9092 Fortran 95 and later
9097 @item @emph{Syntax}:
9098 @code{RESULT = NEAREST(X, S)}
9100 @item @emph{Arguments}:
9101 @multitable @columnfractions .15 .70
9102 @item @var{X} @tab Shall be of type @code{REAL}.
9103 @item @var{S} @tab (Optional) shall be of type @code{REAL} and
9107 @item @emph{Return value}:
9108 The return value is of the same type as @code{X}. If @code{S} is
9109 positive, @code{NEAREST} returns the processor-representable number
9110 greater than @code{X} and nearest to it. If @code{S} is negative,
9111 @code{NEAREST} returns the processor-representable number smaller than
9112 @code{X} and nearest to it.
9114 @item @emph{Example}:
9116 program test_nearest
9118 x = nearest(42.0, 1.0)
9119 y = nearest(42.0, -1.0)
9120 write (*,"(3(G20.15))") x, y, x - y
9121 end program test_nearest
9128 @section @code{NEW_LINE} --- New line character
9131 @cindex output, newline
9134 @item @emph{Description}:
9135 @code{NEW_LINE(C)} returns the new-line character.
9137 @item @emph{Standard}:
9138 Fortran 2003 and later
9143 @item @emph{Syntax}:
9144 @code{RESULT = NEW_LINE(C)}
9146 @item @emph{Arguments}:
9147 @multitable @columnfractions .15 .70
9148 @item @var{C} @tab The argument shall be a scalar or array of the
9149 type @code{CHARACTER}.
9152 @item @emph{Return value}:
9153 Returns a @var{CHARACTER} scalar of length one with the new-line character of
9154 the same kind as parameter @var{C}.
9156 @item @emph{Example}:
9160 write(*,'(A)') 'This is record 1.'//NEW_LINE('A')//'This is record 2.'
9168 @section @code{NINT} --- Nearest whole number
9171 @cindex rounding, nearest whole number
9174 @item @emph{Description}:
9175 @code{NINT(A)} rounds its argument to the nearest whole number.
9177 @item @emph{Standard}:
9178 Fortran 77 and later, with @var{KIND} argument Fortran 90 and later
9183 @item @emph{Syntax}:
9184 @code{RESULT = NINT(A [, KIND])}
9186 @item @emph{Arguments}:
9187 @multitable @columnfractions .15 .70
9188 @item @var{A} @tab The type of the argument shall be @code{REAL}.
9189 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
9190 expression indicating the kind parameter of the result.
9193 @item @emph{Return value}:
9194 Returns @var{A} with the fractional portion of its magnitude eliminated by
9195 rounding to the nearest whole number and with its sign preserved,
9196 converted to an @code{INTEGER} of the default kind.
9198 @item @emph{Example}:
9205 print *, nint(x4), idnint(x8)
9206 end program test_nint
9209 @item @emph{Specific names}:
9210 @multitable @columnfractions .20 .20 .20 .25
9211 @item Name @tab Argument @tab Return Type @tab Standard
9212 @item @code{NINT(A)} @tab @code{REAL(4) A} @tab @code{INTEGER} @tab Fortran 95 and later
9213 @item @code{IDNINT(A)} @tab @code{REAL(8) A} @tab @code{INTEGER} @tab Fortran 95 and later
9216 @item @emph{See also}:
9217 @ref{CEILING}, @ref{FLOOR}
9224 @section @code{NORM2} --- Euclidean vector norms
9226 @cindex Euclidean vector norm
9227 @cindex L2 vector norm
9228 @cindex norm, Euclidean
9231 @item @emph{Description}:
9232 Calculates the Euclidean vector norm (@math{L_2} norm) of
9233 of @var{ARRAY} along dimension @var{DIM}.
9235 @item @emph{Standard}:
9236 Fortran 2008 and later
9239 Transformational function
9241 @item @emph{Syntax}:
9242 @multitable @columnfractions .80
9243 @item @code{RESULT = NORM2(ARRAY[, DIM])}
9246 @item @emph{Arguments}:
9247 @multitable @columnfractions .15 .70
9248 @item @var{ARRAY} @tab Shall be an array of type @code{REAL}
9249 @item @var{DIM} @tab (Optional) shall be a scalar of type
9250 @code{INTEGER} with a value in the range from 1 to n, where n
9251 equals the rank of @var{ARRAY}.
9254 @item @emph{Return value}:
9255 The result is of the same type as @var{ARRAY}.
9257 If @var{DIM} is absent, a scalar with the square root of the sum of all
9258 elements in @var{ARRAY} squared is returned. Otherwise, an array of
9259 rank @math{n-1}, where @math{n} equals the rank of @var{ARRAY}, and a
9260 shape similar to that of @var{ARRAY} with dimension @var{DIM} dropped
9263 @item @emph{Example}:
9266 REAL :: x(5) = [ real :: 1, 2, 3, 4, 5 ]
9267 print *, NORM2(x) ! = sqrt(55.) ~ 7.416
9275 @section @code{NOT} --- Logical negation
9277 @cindex bits, negate
9278 @cindex bitwise logical not
9279 @cindex logical not, bitwise
9282 @item @emph{Description}:
9283 @code{NOT} returns the bitwise Boolean inverse of @var{I}.
9285 @item @emph{Standard}:
9286 Fortran 95 and later
9291 @item @emph{Syntax}:
9292 @code{RESULT = NOT(I)}
9294 @item @emph{Arguments}:
9295 @multitable @columnfractions .15 .70
9296 @item @var{I} @tab The type shall be @code{INTEGER}.
9299 @item @emph{Return value}:
9300 The return type is @code{INTEGER}, of the same kind as the
9303 @item @emph{See also}:
9304 @ref{IAND}, @ref{IEOR}, @ref{IOR}, @ref{IBITS}, @ref{IBSET}, @ref{IBCLR}
9311 @section @code{NULL} --- Function that returns an disassociated pointer
9313 @cindex pointer, status
9314 @cindex pointer, disassociated
9317 @item @emph{Description}:
9318 Returns a disassociated pointer.
9320 If @var{MOLD} is present, a disassociated pointer of the same type is
9321 returned, otherwise the type is determined by context.
9323 In Fortran 95, @var{MOLD} is optional. Please note that Fortran 2003
9324 includes cases where it is required.
9326 @item @emph{Standard}:
9327 Fortran 95 and later
9330 Transformational function
9332 @item @emph{Syntax}:
9333 @code{PTR => NULL([MOLD])}
9335 @item @emph{Arguments}:
9336 @multitable @columnfractions .15 .70
9337 @item @var{MOLD} @tab (Optional) shall be a pointer of any association
9338 status and of any type.
9341 @item @emph{Return value}:
9342 A disassociated pointer.
9344 @item @emph{Example}:
9346 REAL, POINTER, DIMENSION(:) :: VEC => NULL ()
9349 @item @emph{See also}:
9356 @section @code{NUM_IMAGES} --- Function that returns the number of images
9358 @cindex coarray, @code{NUM_IMAGES}
9359 @cindex images, number of
9362 @item @emph{Description}:
9363 Returns the number of images.
9365 @item @emph{Standard}:
9366 Fortran 2008 and later
9369 Transformational function
9371 @item @emph{Syntax}:
9372 @code{RESULT = NUM_IMAGES()}
9374 @item @emph{Arguments}: None.
9376 @item @emph{Return value}:
9377 Scalar default-kind integer.
9379 @item @emph{Example}:
9383 value = THIS_IMAGE()
9385 IF (THIS_IMAGE() == 1) THEN
9386 DO i = 1, NUM_IMAGES()
9387 WRITE(*,'(2(a,i0))') 'value[', i, '] is ', value[i]
9392 @item @emph{See also}:
9393 @ref{THIS_IMAGE}, @ref{IMAGE_INDEX}
9399 @section @code{OR} --- Bitwise logical OR
9401 @cindex bitwise logical or
9402 @cindex logical or, bitwise
9405 @item @emph{Description}:
9406 Bitwise logical @code{OR}.
9408 This intrinsic routine is provided for backwards compatibility with
9409 GNU Fortran 77. For integer arguments, programmers should consider
9410 the use of the @ref{IOR} intrinsic defined by the Fortran standard.
9412 @item @emph{Standard}:
9418 @item @emph{Syntax}:
9419 @code{RESULT = OR(I, J)}
9421 @item @emph{Arguments}:
9422 @multitable @columnfractions .15 .70
9423 @item @var{I} @tab The type shall be either a scalar @code{INTEGER}
9424 type or a scalar @code{LOGICAL} type.
9425 @item @var{J} @tab The type shall be the same as the type of @var{J}.
9428 @item @emph{Return value}:
9429 The return type is either a scalar @code{INTEGER} or a scalar
9430 @code{LOGICAL}. If the kind type parameters differ, then the
9431 smaller kind type is implicitly converted to larger kind, and the
9432 return has the larger kind.
9434 @item @emph{Example}:
9437 LOGICAL :: T = .TRUE., F = .FALSE.
9439 DATA a / Z'F' /, b / Z'3' /
9441 WRITE (*,*) OR(T, T), OR(T, F), OR(F, T), OR(F, F)
9442 WRITE (*,*) OR(a, b)
9446 @item @emph{See also}:
9447 Fortran 95 elemental function: @ref{IOR}
9453 @section @code{PACK} --- Pack an array into an array of rank one
9455 @cindex array, packing
9456 @cindex array, reduce dimension
9457 @cindex array, gather elements
9460 @item @emph{Description}:
9461 Stores the elements of @var{ARRAY} in an array of rank one.
9463 The beginning of the resulting array is made up of elements whose @var{MASK}
9464 equals @code{TRUE}. Afterwards, positions are filled with elements taken from
9467 @item @emph{Standard}:
9468 Fortran 95 and later
9471 Transformational function
9473 @item @emph{Syntax}:
9474 @code{RESULT = PACK(ARRAY, MASK[,VECTOR]}
9476 @item @emph{Arguments}:
9477 @multitable @columnfractions .15 .70
9478 @item @var{ARRAY} @tab Shall be an array of any type.
9479 @item @var{MASK} @tab Shall be an array of type @code{LOGICAL} and
9480 of the same size as @var{ARRAY}. Alternatively, it may be a @code{LOGICAL}
9482 @item @var{VECTOR} @tab (Optional) shall be an array of the same type
9483 as @var{ARRAY} and of rank one. If present, the number of elements in
9484 @var{VECTOR} shall be equal to or greater than the number of true elements
9485 in @var{MASK}. If @var{MASK} is scalar, the number of elements in
9486 @var{VECTOR} shall be equal to or greater than the number of elements in
9490 @item @emph{Return value}:
9491 The result is an array of rank one and the same type as that of @var{ARRAY}.
9492 If @var{VECTOR} is present, the result size is that of @var{VECTOR}, the
9493 number of @code{TRUE} values in @var{MASK} otherwise.
9495 @item @emph{Example}:
9496 Gathering nonzero elements from an array:
9500 m = (/ 1, 0, 0, 0, 5, 0 /)
9501 WRITE(*, FMT="(6(I0, ' '))") pack(m, m /= 0) ! "1 5"
9505 Gathering nonzero elements from an array and appending elements from @var{VECTOR}:
9509 m = (/ 1, 0, 0, 2 /)
9510 WRITE(*, FMT="(4(I0, ' '))") pack(m, m /= 0, (/ 0, 0, 3, 4 /)) ! "1 2 3 4"
9514 @item @emph{See also}:
9521 @section @code{PARITY} --- Reduction with exclusive OR
9524 @cindex Reduction, XOR
9525 @cindex XOR reduction
9528 @item @emph{Description}:
9529 Calculates the parity, i.e. the reduction using @code{.XOR.},
9530 of @var{MASK} along dimension @var{DIM}.
9532 @item @emph{Standard}:
9533 Fortran 2008 and later
9536 Transformational function
9538 @item @emph{Syntax}:
9539 @multitable @columnfractions .80
9540 @item @code{RESULT = PARITY(MASK[, DIM])}
9543 @item @emph{Arguments}:
9544 @multitable @columnfractions .15 .70
9545 @item @var{LOGICAL} @tab Shall be an array of type @code{LOGICAL}
9546 @item @var{DIM} @tab (Optional) shall be a scalar of type
9547 @code{INTEGER} with a value in the range from 1 to n, where n
9548 equals the rank of @var{MASK}.
9551 @item @emph{Return value}:
9552 The result is of the same type as @var{MASK}.
9554 If @var{DIM} is absent, a scalar with the parity of all elements in
9555 @var{MASK} is returned, i.e. true if an odd number of elements is
9556 @code{.true.} and false otherwise. If @var{DIM} is present, an array
9557 of rank @math{n-1}, where @math{n} equals the rank of @var{ARRAY},
9558 and a shape similar to that of @var{MASK} with dimension @var{DIM}
9559 dropped is returned.
9561 @item @emph{Example}:
9564 LOGICAL :: x(2) = [ .true., .false. ]
9565 print *, PARITY(x) ! prints "T" (true).
9573 @section @code{PERROR} --- Print system error message
9575 @cindex system, error handling
9578 @item @emph{Description}:
9579 Prints (on the C @code{stderr} stream) a newline-terminated error
9580 message corresponding to the last system error. This is prefixed by
9581 @var{STRING}, a colon and a space. See @code{perror(3)}.
9583 @item @emph{Standard}:
9589 @item @emph{Syntax}:
9590 @code{CALL PERROR(STRING)}
9592 @item @emph{Arguments}:
9593 @multitable @columnfractions .15 .70
9594 @item @var{STRING} @tab A scalar of type @code{CHARACTER} and of the
9598 @item @emph{See also}:
9605 @section @code{PRECISION} --- Decimal precision of a real kind
9607 @cindex model representation, precision
9610 @item @emph{Description}:
9611 @code{PRECISION(X)} returns the decimal precision in the model of the
9614 @item @emph{Standard}:
9615 Fortran 95 and later
9620 @item @emph{Syntax}:
9621 @code{RESULT = PRECISION(X)}
9623 @item @emph{Arguments}:
9624 @multitable @columnfractions .15 .70
9625 @item @var{X} @tab Shall be of type @code{REAL} or @code{COMPLEX}.
9628 @item @emph{Return value}:
9629 The return value is of type @code{INTEGER} and of the default integer
9632 @item @emph{See also}:
9633 @ref{SELECTED_REAL_KIND}, @ref{RANGE}
9635 @item @emph{Example}:
9637 program prec_and_range
9638 real(kind=4) :: x(2)
9639 complex(kind=8) :: y
9641 print *, precision(x), range(x)
9642 print *, precision(y), range(y)
9643 end program prec_and_range
9650 @section @code{POPCNT} --- Number of bits set
9652 @cindex binary representation
9656 @item @emph{Description}:
9657 @code{POPCNT(I)} returns the number of bits set ('1' bits) in the binary
9658 representation of @code{I}.
9660 @item @emph{Standard}:
9661 Fortran 2008 and later
9666 @item @emph{Syntax}:
9667 @code{RESULT = POPCNT(I)}
9669 @item @emph{Arguments}:
9670 @multitable @columnfractions .15 .70
9671 @item @var{I} @tab Shall be of type @code{INTEGER}.
9674 @item @emph{Return value}:
9675 The return value is of type @code{INTEGER} and of the default integer
9678 @item @emph{See also}:
9679 @ref{POPPAR}, @ref{LEADZ}, @ref{TRAILZ}
9681 @item @emph{Example}:
9683 program test_population
9684 print *, popcnt(127), poppar(127)
9685 print *, popcnt(huge(0_4)), poppar(huge(0_4))
9686 print *, popcnt(huge(0_8)), poppar(huge(0_8))
9687 end program test_population
9693 @section @code{POPPAR} --- Parity of the number of bits set
9695 @cindex binary representation
9699 @item @emph{Description}:
9700 @code{POPPAR(I)} returns parity of the integer @code{I}, i.e. the parity
9701 of the number of bits set ('1' bits) in the binary representation of
9702 @code{I}. It is equal to 0 if @code{I} has an even number of bits set,
9703 and 1 for an odd number of '1' bits.
9705 @item @emph{Standard}:
9706 Fortran 2008 and later
9711 @item @emph{Syntax}:
9712 @code{RESULT = POPPAR(I)}
9714 @item @emph{Arguments}:
9715 @multitable @columnfractions .15 .70
9716 @item @var{I} @tab Shall be of type @code{INTEGER}.
9719 @item @emph{Return value}:
9720 The return value is of type @code{INTEGER} and of the default integer
9723 @item @emph{See also}:
9724 @ref{POPCNT}, @ref{LEADZ}, @ref{TRAILZ}
9726 @item @emph{Example}:
9728 program test_population
9729 print *, popcnt(127), poppar(127)
9730 print *, popcnt(huge(0_4)), poppar(huge(0_4))
9731 print *, popcnt(huge(0_8)), poppar(huge(0_8))
9732 end program test_population
9739 @section @code{PRESENT} --- Determine whether an optional dummy argument is specified
9743 @item @emph{Description}:
9744 Determines whether an optional dummy argument is present.
9746 @item @emph{Standard}:
9747 Fortran 95 and later
9752 @item @emph{Syntax}:
9753 @code{RESULT = PRESENT(A)}
9755 @item @emph{Arguments}:
9756 @multitable @columnfractions .15 .70
9757 @item @var{A} @tab May be of any type and may be a pointer, scalar or array
9758 value, or a dummy procedure. It shall be the name of an optional dummy argument
9759 accessible within the current subroutine or function.
9762 @item @emph{Return value}:
9763 Returns either @code{TRUE} if the optional argument @var{A} is present, or
9764 @code{FALSE} otherwise.
9766 @item @emph{Example}:
9768 PROGRAM test_present
9769 WRITE(*,*) f(), f(42) ! "F T"
9771 LOGICAL FUNCTION f(x)
9772 INTEGER, INTENT(IN), OPTIONAL :: x
9782 @section @code{PRODUCT} --- Product of array elements
9784 @cindex array, product
9785 @cindex array, multiply elements
9786 @cindex array, conditionally multiply elements
9787 @cindex multiply array elements
9790 @item @emph{Description}:
9791 Multiplies the elements of @var{ARRAY} along dimension @var{DIM} if
9792 the corresponding element in @var{MASK} is @code{TRUE}.
9794 @item @emph{Standard}:
9795 Fortran 95 and later
9798 Transformational function
9800 @item @emph{Syntax}:
9801 @multitable @columnfractions .80
9802 @item @code{RESULT = PRODUCT(ARRAY[, MASK])}
9803 @item @code{RESULT = PRODUCT(ARRAY, DIM[, MASK])}
9806 @item @emph{Arguments}:
9807 @multitable @columnfractions .15 .70
9808 @item @var{ARRAY} @tab Shall be an array of type @code{INTEGER},
9809 @code{REAL} or @code{COMPLEX}.
9810 @item @var{DIM} @tab (Optional) shall be a scalar of type
9811 @code{INTEGER} with a value in the range from 1 to n, where n
9812 equals the rank of @var{ARRAY}.
9813 @item @var{MASK} @tab (Optional) shall be of type @code{LOGICAL}
9814 and either be a scalar or an array of the same shape as @var{ARRAY}.
9817 @item @emph{Return value}:
9818 The result is of the same type as @var{ARRAY}.
9820 If @var{DIM} is absent, a scalar with the product of all elements in
9821 @var{ARRAY} is returned. Otherwise, an array of rank n-1, where n equals
9822 the rank of @var{ARRAY}, and a shape similar to that of @var{ARRAY} with
9823 dimension @var{DIM} dropped is returned.
9826 @item @emph{Example}:
9828 PROGRAM test_product
9829 INTEGER :: x(5) = (/ 1, 2, 3, 4 ,5 /)
9830 print *, PRODUCT(x) ! all elements, product = 120
9831 print *, PRODUCT(x, MASK=MOD(x, 2)==1) ! odd elements, product = 15
9835 @item @emph{See also}:
9842 @section @code{RADIX} --- Base of a model number
9844 @cindex model representation, base
9845 @cindex model representation, radix
9848 @item @emph{Description}:
9849 @code{RADIX(X)} returns the base of the model representing the entity @var{X}.
9851 @item @emph{Standard}:
9852 Fortran 95 and later
9857 @item @emph{Syntax}:
9858 @code{RESULT = RADIX(X)}
9860 @item @emph{Arguments}:
9861 @multitable @columnfractions .15 .70
9862 @item @var{X} @tab Shall be of type @code{INTEGER} or @code{REAL}
9865 @item @emph{Return value}:
9866 The return value is a scalar of type @code{INTEGER} and of the default
9869 @item @emph{See also}:
9870 @ref{SELECTED_REAL_KIND}
9872 @item @emph{Example}:
9875 print *, "The radix for the default integer kind is", radix(0)
9876 print *, "The radix for the default real kind is", radix(0.0)
9877 end program test_radix
9885 @section @code{RAN} --- Real pseudo-random number
9887 @cindex random number generation
9890 @item @emph{Description}:
9891 For compatibility with HP FORTRAN 77/iX, the @code{RAN} intrinsic is
9892 provided as an alias for @code{RAND}. See @ref{RAND} for complete
9895 @item @emph{Standard}:
9901 @item @emph{See also}:
9902 @ref{RAND}, @ref{RANDOM_NUMBER}
9908 @section @code{RAND} --- Real pseudo-random number
9910 @cindex random number generation
9913 @item @emph{Description}:
9914 @code{RAND(FLAG)} returns a pseudo-random number from a uniform
9915 distribution between 0 and 1. If @var{FLAG} is 0, the next number
9916 in the current sequence is returned; if @var{FLAG} is 1, the generator
9917 is restarted by @code{CALL SRAND(0)}; if @var{FLAG} has any other value,
9918 it is used as a new seed with @code{SRAND}.
9920 This intrinsic routine is provided for backwards compatibility with
9921 GNU Fortran 77. It implements a simple modulo generator as provided
9922 by @command{g77}. For new code, one should consider the use of
9923 @ref{RANDOM_NUMBER} as it implements a superior algorithm.
9925 @item @emph{Standard}:
9931 @item @emph{Syntax}:
9932 @code{RESULT = RAND(I)}
9934 @item @emph{Arguments}:
9935 @multitable @columnfractions .15 .70
9936 @item @var{I} @tab Shall be a scalar @code{INTEGER} of kind 4.
9939 @item @emph{Return value}:
9940 The return value is of @code{REAL} type and the default kind.
9942 @item @emph{Example}:
9945 integer,parameter :: seed = 86456
9948 print *, rand(), rand(), rand(), rand()
9949 print *, rand(seed), rand(), rand(), rand()
9950 end program test_rand
9953 @item @emph{See also}:
9954 @ref{SRAND}, @ref{RANDOM_NUMBER}
9961 @section @code{RANDOM_NUMBER} --- Pseudo-random number
9962 @fnindex RANDOM_NUMBER
9963 @cindex random number generation
9966 @item @emph{Description}:
9967 Returns a single pseudorandom number or an array of pseudorandom numbers
9968 from the uniform distribution over the range @math{ 0 \leq x < 1}.
9970 The runtime-library implements George Marsaglia's KISS (Keep It Simple
9971 Stupid) random number generator (RNG). This RNG combines:
9973 @item The congruential generator @math{x(n) = 69069 \cdot x(n-1) + 1327217885}
9974 with a period of @math{2^{32}},
9975 @item A 3-shift shift-register generator with a period of @math{2^{32} - 1},
9976 @item Two 16-bit multiply-with-carry generators with a period of
9977 @math{597273182964842497 > 2^{59}}.
9979 The overall period exceeds @math{2^{123}}.
9981 Please note, this RNG is thread safe if used within OpenMP directives,
9982 i.e., its state will be consistent while called from multiple threads.
9983 However, the KISS generator does not create random numbers in parallel
9984 from multiple sources, but in sequence from a single source. If an
9985 OpenMP-enabled application heavily relies on random numbers, one should
9986 consider employing a dedicated parallel random number generator instead.
9988 @item @emph{Standard}:
9989 Fortran 95 and later
9994 @item @emph{Syntax}:
9995 @code{RANDOM_NUMBER(HARVEST)}
9997 @item @emph{Arguments}:
9998 @multitable @columnfractions .15 .70
9999 @item @var{HARVEST} @tab Shall be a scalar or an array of type @code{REAL}.
10002 @item @emph{Example}:
10004 program test_random_number
10006 CALL init_random_seed() ! see example of RANDOM_SEED
10007 CALL RANDOM_NUMBER(r)
10011 @item @emph{See also}:
10018 @section @code{RANDOM_SEED} --- Initialize a pseudo-random number sequence
10019 @fnindex RANDOM_SEED
10020 @cindex random number generation, seeding
10021 @cindex seeding a random number generator
10024 @item @emph{Description}:
10025 Restarts or queries the state of the pseudorandom number generator used by
10026 @code{RANDOM_NUMBER}.
10028 If @code{RANDOM_SEED} is called without arguments, it is initialized to
10029 a default state. The example below shows how to initialize the random
10030 seed based on the system's time.
10032 @item @emph{Standard}:
10033 Fortran 95 and later
10035 @item @emph{Class}:
10038 @item @emph{Syntax}:
10039 @code{CALL RANDOM_SEED([SIZE, PUT, GET])}
10041 @item @emph{Arguments}:
10042 @multitable @columnfractions .15 .70
10043 @item @var{SIZE} @tab (Optional) Shall be a scalar and of type default
10044 @code{INTEGER}, with @code{INTENT(OUT)}. It specifies the minimum size
10045 of the arrays used with the @var{PUT} and @var{GET} arguments.
10046 @item @var{PUT} @tab (Optional) Shall be an array of type default
10047 @code{INTEGER} and rank one. It is @code{INTENT(IN)} and the size of
10048 the array must be larger than or equal to the number returned by the
10049 @var{SIZE} argument.
10050 @item @var{GET} @tab (Optional) Shall be an array of type default
10051 @code{INTEGER} and rank one. It is @code{INTENT(OUT)} and the size
10052 of the array must be larger than or equal to the number returned by
10053 the @var{SIZE} argument.
10056 @item @emph{Example}:
10058 SUBROUTINE init_random_seed()
10059 INTEGER :: i, n, clock
10060 INTEGER, DIMENSION(:), ALLOCATABLE :: seed
10062 CALL RANDOM_SEED(size = n)
10065 CALL SYSTEM_CLOCK(COUNT=clock)
10067 seed = clock + 37 * (/ (i - 1, i = 1, n) /)
10068 CALL RANDOM_SEED(PUT = seed)
10074 @item @emph{See also}:
10075 @ref{RANDOM_NUMBER}
10081 @section @code{RANGE} --- Decimal exponent range
10083 @cindex model representation, range
10086 @item @emph{Description}:
10087 @code{RANGE(X)} returns the decimal exponent range in the model of the
10090 @item @emph{Standard}:
10091 Fortran 95 and later
10093 @item @emph{Class}:
10096 @item @emph{Syntax}:
10097 @code{RESULT = RANGE(X)}
10099 @item @emph{Arguments}:
10100 @multitable @columnfractions .15 .70
10101 @item @var{X} @tab Shall be of type @code{INTEGER}, @code{REAL}
10105 @item @emph{Return value}:
10106 The return value is of type @code{INTEGER} and of the default integer
10109 @item @emph{See also}:
10110 @ref{SELECTED_REAL_KIND}, @ref{PRECISION}
10112 @item @emph{Example}:
10113 See @code{PRECISION} for an example.
10119 @section @code{REAL} --- Convert to real type
10125 @cindex conversion, to real
10126 @cindex complex numbers, real part
10129 @item @emph{Description}:
10130 @code{REAL(A [, KIND])} converts its argument @var{A} to a real type. The
10131 @code{REALPART} function is provided for compatibility with @command{g77},
10132 and its use is strongly discouraged.
10134 @item @emph{Standard}:
10135 Fortran 77 and later
10137 @item @emph{Class}:
10140 @item @emph{Syntax}:
10141 @multitable @columnfractions .80
10142 @item @code{RESULT = REAL(A [, KIND])}
10143 @item @code{RESULT = REALPART(Z)}
10146 @item @emph{Arguments}:
10147 @multitable @columnfractions .15 .70
10148 @item @var{A} @tab Shall be @code{INTEGER}, @code{REAL}, or
10150 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
10151 expression indicating the kind parameter of the result.
10154 @item @emph{Return value}:
10155 These functions return a @code{REAL} variable or array under
10156 the following rules:
10160 @code{REAL(A)} is converted to a default real type if @var{A} is an
10161 integer or real variable.
10163 @code{REAL(A)} is converted to a real type with the kind type parameter
10164 of @var{A} if @var{A} is a complex variable.
10166 @code{REAL(A, KIND)} is converted to a real type with kind type
10167 parameter @var{KIND} if @var{A} is a complex, integer, or real
10171 @item @emph{Example}:
10174 complex :: x = (1.0, 2.0)
10175 print *, real(x), real(x,8), realpart(x)
10176 end program test_real
10179 @item @emph{Specific names}:
10180 @multitable @columnfractions .20 .20 .20 .25
10181 @item Name @tab Argument @tab Return type @tab Standard
10182 @item @code{FLOAT(A)} @tab @code{INTEGER(4)} @tab @code{REAL(4)} @tab Fortran 77 and later
10183 @item @code{DFLOAT(A)} @tab @code{INTEGER(4)} @tab @code{REAL(8)} @tab GNU extension
10184 @item @code{SNGL(A)} @tab @code{INTEGER(8)} @tab @code{REAL(4)} @tab Fortran 77 and later
10188 @item @emph{See also}:
10196 @section @code{RENAME} --- Rename a file
10198 @cindex file system, rename file
10201 @item @emph{Description}:
10202 Renames a file from file @var{PATH1} to @var{PATH2}. A null
10203 character (@code{CHAR(0)}) can be used to mark the end of the names in
10204 @var{PATH1} and @var{PATH2}; otherwise, trailing blanks in the file
10205 names are ignored. If the @var{STATUS} argument is supplied, it
10206 contains 0 on success or a nonzero error code upon return; see
10209 This intrinsic is provided in both subroutine and function forms;
10210 however, only one form can be used in any given program unit.
10212 @item @emph{Standard}:
10215 @item @emph{Class}:
10216 Subroutine, function
10218 @item @emph{Syntax}:
10219 @multitable @columnfractions .80
10220 @item @code{CALL RENAME(PATH1, PATH2 [, STATUS])}
10221 @item @code{STATUS = RENAME(PATH1, PATH2)}
10224 @item @emph{Arguments}:
10225 @multitable @columnfractions .15 .70
10226 @item @var{PATH1} @tab Shall be of default @code{CHARACTER} type.
10227 @item @var{PATH2} @tab Shall be of default @code{CHARACTER} type.
10228 @item @var{STATUS} @tab (Optional) Shall be of default @code{INTEGER} type.
10231 @item @emph{See also}:
10239 @section @code{REPEAT} --- Repeated string concatenation
10241 @cindex string, repeat
10242 @cindex string, concatenate
10245 @item @emph{Description}:
10246 Concatenates @var{NCOPIES} copies of a string.
10248 @item @emph{Standard}:
10249 Fortran 95 and later
10251 @item @emph{Class}:
10252 Transformational function
10254 @item @emph{Syntax}:
10255 @code{RESULT = REPEAT(STRING, NCOPIES)}
10257 @item @emph{Arguments}:
10258 @multitable @columnfractions .15 .70
10259 @item @var{STRING} @tab Shall be scalar and of type @code{CHARACTER}.
10260 @item @var{NCOPIES} @tab Shall be scalar and of type @code{INTEGER}.
10263 @item @emph{Return value}:
10264 A new scalar of type @code{CHARACTER} built up from @var{NCOPIES} copies
10267 @item @emph{Example}:
10269 program test_repeat
10270 write(*,*) repeat("x", 5) ! "xxxxx"
10278 @section @code{RESHAPE} --- Function to reshape an array
10280 @cindex array, change dimensions
10281 @cindex array, transmogrify
10284 @item @emph{Description}:
10285 Reshapes @var{SOURCE} to correspond to @var{SHAPE}. If necessary,
10286 the new array may be padded with elements from @var{PAD} or permuted
10287 as defined by @var{ORDER}.
10289 @item @emph{Standard}:
10290 Fortran 95 and later
10292 @item @emph{Class}:
10293 Transformational function
10295 @item @emph{Syntax}:
10296 @code{RESULT = RESHAPE(SOURCE, SHAPE[, PAD, ORDER])}
10298 @item @emph{Arguments}:
10299 @multitable @columnfractions .15 .70
10300 @item @var{SOURCE} @tab Shall be an array of any type.
10301 @item @var{SHAPE} @tab Shall be of type @code{INTEGER} and an
10302 array of rank one. Its values must be positive or zero.
10303 @item @var{PAD} @tab (Optional) shall be an array of the same
10304 type as @var{SOURCE}.
10305 @item @var{ORDER} @tab (Optional) shall be of type @code{INTEGER}
10306 and an array of the same shape as @var{SHAPE}. Its values shall
10307 be a permutation of the numbers from 1 to n, where n is the size of
10308 @var{SHAPE}. If @var{ORDER} is absent, the natural ordering shall
10312 @item @emph{Return value}:
10313 The result is an array of shape @var{SHAPE} with the same type as
10316 @item @emph{Example}:
10318 PROGRAM test_reshape
10319 INTEGER, DIMENSION(4) :: x
10320 WRITE(*,*) SHAPE(x) ! prints "4"
10321 WRITE(*,*) SHAPE(RESHAPE(x, (/2, 2/))) ! prints "2 2"
10325 @item @emph{See also}:
10332 @section @code{RRSPACING} --- Reciprocal of the relative spacing
10334 @cindex real number, relative spacing
10335 @cindex floating point, relative spacing
10339 @item @emph{Description}:
10340 @code{RRSPACING(X)} returns the reciprocal of the relative spacing of
10341 model numbers near @var{X}.
10343 @item @emph{Standard}:
10344 Fortran 95 and later
10346 @item @emph{Class}:
10349 @item @emph{Syntax}:
10350 @code{RESULT = RRSPACING(X)}
10352 @item @emph{Arguments}:
10353 @multitable @columnfractions .15 .70
10354 @item @var{X} @tab Shall be of type @code{REAL}.
10357 @item @emph{Return value}:
10358 The return value is of the same type and kind as @var{X}.
10359 The value returned is equal to
10360 @code{ABS(FRACTION(X)) * FLOAT(RADIX(X))**DIGITS(X)}.
10362 @item @emph{See also}:
10369 @section @code{RSHIFT} --- Right shift bits
10371 @cindex bits, shift right
10374 @item @emph{Description}:
10375 @code{RSHIFT} returns a value corresponding to @var{I} with all of the
10376 bits shifted right by @var{SHIFT} places. If the absolute value of
10377 @var{SHIFT} is greater than @code{BIT_SIZE(I)}, the value is undefined.
10378 Bits shifted out from the right end are lost. The fill is arithmetic: the
10379 bits shifted in from the left end are equal to the leftmost bit, which in
10380 two's complement representation is the sign bit.
10382 This function has been superseded by the @code{SHIFTA} intrinsic, which
10383 is standard in Fortran 2008 and later.
10385 @item @emph{Standard}:
10388 @item @emph{Class}:
10391 @item @emph{Syntax}:
10392 @code{RESULT = RSHIFT(I, SHIFT)}
10394 @item @emph{Arguments}:
10395 @multitable @columnfractions .15 .70
10396 @item @var{I} @tab The type shall be @code{INTEGER}.
10397 @item @var{SHIFT} @tab The type shall be @code{INTEGER}.
10400 @item @emph{Return value}:
10401 The return value is of type @code{INTEGER} and of the same kind as
10404 @item @emph{See also}:
10405 @ref{ISHFT}, @ref{ISHFTC}, @ref{LSHIFT}, @ref{SHIFTA}, @ref{SHIFTR},
10413 @section @code{SAME_TYPE_AS} --- Query dynamic types for equality
10414 @fnindex SAME_TYPE_AS
10417 @item @emph{Description}:
10418 Query dynamic types for equality.
10420 @item @emph{Standard}:
10421 Fortran 2003 and later
10423 @item @emph{Class}:
10426 @item @emph{Syntax}:
10427 @code{RESULT = SAME_TYPE_AS(A, B)}
10429 @item @emph{Arguments}:
10430 @multitable @columnfractions .15 .70
10431 @item @var{A} @tab Shall be an object of extensible declared type or
10432 unlimited polymorphic.
10433 @item @var{B} @tab Shall be an object of extensible declared type or
10434 unlimited polymorphic.
10437 @item @emph{Return value}:
10438 The return value is a scalar of type default logical. It is true if and
10439 only if the dynamic type of A is the same as the dynamic type of B.
10441 @item @emph{See also}:
10442 @ref{EXTENDS_TYPE_OF}
10449 @section @code{SCALE} --- Scale a real value
10451 @cindex real number, scale
10452 @cindex floating point, scale
10455 @item @emph{Description}:
10456 @code{SCALE(X,I)} returns @code{X * RADIX(X)**I}.
10458 @item @emph{Standard}:
10459 Fortran 95 and later
10461 @item @emph{Class}:
10464 @item @emph{Syntax}:
10465 @code{RESULT = SCALE(X, I)}
10467 @item @emph{Arguments}:
10468 @multitable @columnfractions .15 .70
10469 @item @var{X} @tab The type of the argument shall be a @code{REAL}.
10470 @item @var{I} @tab The type of the argument shall be a @code{INTEGER}.
10473 @item @emph{Return value}:
10474 The return value is of the same type and kind as @var{X}.
10475 Its value is @code{X * RADIX(X)**I}.
10477 @item @emph{Example}:
10480 real :: x = 178.1387e-4
10482 print *, scale(x,i), x*radix(x)**i
10483 end program test_scale
10491 @section @code{SCAN} --- Scan a string for the presence of a set of characters
10493 @cindex string, find subset
10496 @item @emph{Description}:
10497 Scans a @var{STRING} for any of the characters in a @var{SET}
10500 If @var{BACK} is either absent or equals @code{FALSE}, this function
10501 returns the position of the leftmost character of @var{STRING} that is
10502 in @var{SET}. If @var{BACK} equals @code{TRUE}, the rightmost position
10503 is returned. If no character of @var{SET} is found in @var{STRING}, the
10506 @item @emph{Standard}:
10507 Fortran 95 and later, with @var{KIND} argument Fortran 2003 and later
10509 @item @emph{Class}:
10512 @item @emph{Syntax}:
10513 @code{RESULT = SCAN(STRING, SET[, BACK [, KIND]])}
10515 @item @emph{Arguments}:
10516 @multitable @columnfractions .15 .70
10517 @item @var{STRING} @tab Shall be of type @code{CHARACTER}.
10518 @item @var{SET} @tab Shall be of type @code{CHARACTER}.
10519 @item @var{BACK} @tab (Optional) shall be of type @code{LOGICAL}.
10520 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
10521 expression indicating the kind parameter of the result.
10524 @item @emph{Return value}:
10525 The return value is of type @code{INTEGER} and of kind @var{KIND}. If
10526 @var{KIND} is absent, the return value is of default integer kind.
10528 @item @emph{Example}:
10531 WRITE(*,*) SCAN("FORTRAN", "AO") ! 2, found 'O'
10532 WRITE(*,*) SCAN("FORTRAN", "AO", .TRUE.) ! 6, found 'A'
10533 WRITE(*,*) SCAN("FORTRAN", "C++") ! 0, found none
10537 @item @emph{See also}:
10538 @ref{INDEX intrinsic}, @ref{VERIFY}
10544 @section @code{SECNDS} --- Time function
10546 @cindex time, elapsed
10547 @cindex elapsed time
10550 @item @emph{Description}:
10551 @code{SECNDS(X)} gets the time in seconds from the real-time system clock.
10552 @var{X} is a reference time, also in seconds. If this is zero, the time in
10553 seconds from midnight is returned. This function is non-standard and its
10554 use is discouraged.
10556 @item @emph{Standard}:
10559 @item @emph{Class}:
10562 @item @emph{Syntax}:
10563 @code{RESULT = SECNDS (X)}
10565 @item @emph{Arguments}:
10566 @multitable @columnfractions .15 .70
10567 @item @var{T} @tab Shall be of type @code{REAL(4)}.
10568 @item @var{X} @tab Shall be of type @code{REAL(4)}.
10571 @item @emph{Return value}:
10574 @item @emph{Example}:
10576 program test_secnds
10579 print *, secnds (0.0) ! seconds since midnight
10580 t1 = secnds (0.0) ! reference time
10581 do i = 1, 10000000 ! do something
10583 t2 = secnds (t1) ! elapsed time
10584 print *, "Something took ", t2, " seconds."
10585 end program test_secnds
10592 @section @code{SECOND} --- CPU time function
10594 @cindex time, elapsed
10595 @cindex elapsed time
10598 @item @emph{Description}:
10599 Returns a @code{REAL(4)} value representing the elapsed CPU time in
10600 seconds. This provides the same functionality as the standard
10601 @code{CPU_TIME} intrinsic, and is only included for backwards
10604 This intrinsic is provided in both subroutine and function forms;
10605 however, only one form can be used in any given program unit.
10607 @item @emph{Standard}:
10610 @item @emph{Class}:
10611 Subroutine, function
10613 @item @emph{Syntax}:
10614 @multitable @columnfractions .80
10615 @item @code{CALL SECOND(TIME)}
10616 @item @code{TIME = SECOND()}
10619 @item @emph{Arguments}:
10620 @multitable @columnfractions .15 .70
10621 @item @var{TIME} @tab Shall be of type @code{REAL(4)}.
10624 @item @emph{Return value}:
10625 In either syntax, @var{TIME} is set to the process's current runtime in
10628 @item @emph{See also}:
10635 @node SELECTED_CHAR_KIND
10636 @section @code{SELECTED_CHAR_KIND} --- Choose character kind
10637 @fnindex SELECTED_CHAR_KIND
10638 @cindex character kind
10639 @cindex kind, character
10642 @item @emph{Description}:
10644 @code{SELECTED_CHAR_KIND(NAME)} returns the kind value for the character
10645 set named @var{NAME}, if a character set with such a name is supported,
10646 or @math{-1} otherwise. Currently, supported character sets include
10647 ``ASCII'' and ``DEFAULT'', which are equivalent, and ``ISO_10646''
10648 (Universal Character Set, UCS-4) which is commonly known as Unicode.
10650 @item @emph{Standard}:
10651 Fortran 2003 and later
10653 @item @emph{Class}:
10654 Transformational function
10656 @item @emph{Syntax}:
10657 @code{RESULT = SELECTED_CHAR_KIND(NAME)}
10659 @item @emph{Arguments}:
10660 @multitable @columnfractions .15 .70
10661 @item @var{NAME} @tab Shall be a scalar and of the default character type.
10664 @item @emph{Example}:
10666 program character_kind
10667 use iso_fortran_env
10669 integer, parameter :: ascii = selected_char_kind ("ascii")
10670 integer, parameter :: ucs4 = selected_char_kind ('ISO_10646')
10672 character(kind=ascii, len=26) :: alphabet
10673 character(kind=ucs4, len=30) :: hello_world
10675 alphabet = ascii_"abcdefghijklmnopqrstuvwxyz"
10676 hello_world = ucs4_'Hello World and Ni Hao -- ' &
10677 // char (int (z'4F60'), ucs4) &
10678 // char (int (z'597D'), ucs4)
10680 write (*,*) alphabet
10682 open (output_unit, encoding='UTF-8')
10683 write (*,*) trim (hello_world)
10684 end program character_kind
10690 @node SELECTED_INT_KIND
10691 @section @code{SELECTED_INT_KIND} --- Choose integer kind
10692 @fnindex SELECTED_INT_KIND
10693 @cindex integer kind
10694 @cindex kind, integer
10697 @item @emph{Description}:
10698 @code{SELECTED_INT_KIND(R)} return the kind value of the smallest integer
10699 type that can represent all values ranging from @math{-10^R} (exclusive)
10700 to @math{10^R} (exclusive). If there is no integer kind that accommodates
10701 this range, @code{SELECTED_INT_KIND} returns @math{-1}.
10703 @item @emph{Standard}:
10704 Fortran 95 and later
10706 @item @emph{Class}:
10707 Transformational function
10709 @item @emph{Syntax}:
10710 @code{RESULT = SELECTED_INT_KIND(R)}
10712 @item @emph{Arguments}:
10713 @multitable @columnfractions .15 .70
10714 @item @var{R} @tab Shall be a scalar and of type @code{INTEGER}.
10717 @item @emph{Example}:
10719 program large_integers
10720 integer,parameter :: k5 = selected_int_kind(5)
10721 integer,parameter :: k15 = selected_int_kind(15)
10722 integer(kind=k5) :: i5
10723 integer(kind=k15) :: i15
10725 print *, huge(i5), huge(i15)
10727 ! The following inequalities are always true
10728 print *, huge(i5) >= 10_k5**5-1
10729 print *, huge(i15) >= 10_k15**15-1
10730 end program large_integers
10736 @node SELECTED_REAL_KIND
10737 @section @code{SELECTED_REAL_KIND} --- Choose real kind
10738 @fnindex SELECTED_REAL_KIND
10741 @cindex radix, real
10744 @item @emph{Description}:
10745 @code{SELECTED_REAL_KIND(P,R)} returns the kind value of a real data type
10746 with decimal precision of at least @code{P} digits, exponent range of
10747 at least @code{R}, and with a radix of @code{RADIX}.
10749 @item @emph{Standard}:
10750 Fortran 95 and later, with @code{RADIX} Fortran 2008 or later
10752 @item @emph{Class}:
10753 Transformational function
10755 @item @emph{Syntax}:
10756 @code{RESULT = SELECTED_REAL_KIND([P, R, RADIX])}
10758 @item @emph{Arguments}:
10759 @multitable @columnfractions .15 .70
10760 @item @var{P} @tab (Optional) shall be a scalar and of type @code{INTEGER}.
10761 @item @var{R} @tab (Optional) shall be a scalar and of type @code{INTEGER}.
10762 @item @var{RADIX} @tab (Optional) shall be a scalar and of type @code{INTEGER}.
10764 Before Fortran 2008, at least one of the arguments @var{R} or @var{P} shall
10765 be present; since Fortran 2008, they are assumed to be zero if absent.
10767 @item @emph{Return value}:
10769 @code{SELECTED_REAL_KIND} returns the value of the kind type parameter of
10770 a real data type with decimal precision of at least @code{P} digits, a
10771 decimal exponent range of at least @code{R}, and with the requested
10772 @code{RADIX}. If the @code{RADIX} parameter is absent, real kinds with
10773 any radix can be returned. If more than one real data type meet the
10774 criteria, the kind of the data type with the smallest decimal precision
10775 is returned. If no real data type matches the criteria, the result is
10777 @item -1 if the processor does not support a real data type with a
10778 precision greater than or equal to @code{P}, but the @code{R} and
10779 @code{RADIX} requirements can be fulfilled
10780 @item -2 if the processor does not support a real type with an exponent
10781 range greater than or equal to @code{R}, but @code{P} and @code{RADIX}
10783 @item -3 if @code{RADIX} but not @code{P} and @code{R} requirements
10785 @item -4 if @code{RADIX} and either @code{P} or @code{R} requirements
10787 @item -5 if there is no real type with the given @code{RADIX}
10790 @item @emph{See also}:
10791 @ref{PRECISION}, @ref{RANGE}, @ref{RADIX}
10793 @item @emph{Example}:
10796 integer,parameter :: p6 = selected_real_kind(6)
10797 integer,parameter :: p10r100 = selected_real_kind(10,100)
10798 integer,parameter :: r400 = selected_real_kind(r=400)
10800 real(kind=p10r100) :: y
10801 real(kind=r400) :: z
10803 print *, precision(x), range(x)
10804 print *, precision(y), range(y)
10805 print *, precision(z), range(z)
10806 end program real_kinds
10813 @section @code{SET_EXPONENT} --- Set the exponent of the model
10814 @fnindex SET_EXPONENT
10815 @cindex real number, set exponent
10816 @cindex floating point, set exponent
10819 @item @emph{Description}:
10820 @code{SET_EXPONENT(X, I)} returns the real number whose fractional part
10821 is that that of @var{X} and whose exponent part is @var{I}.
10823 @item @emph{Standard}:
10824 Fortran 95 and later
10826 @item @emph{Class}:
10829 @item @emph{Syntax}:
10830 @code{RESULT = SET_EXPONENT(X, I)}
10832 @item @emph{Arguments}:
10833 @multitable @columnfractions .15 .70
10834 @item @var{X} @tab Shall be of type @code{REAL}.
10835 @item @var{I} @tab Shall be of type @code{INTEGER}.
10838 @item @emph{Return value}:
10839 The return value is of the same type and kind as @var{X}.
10840 The real number whose fractional part
10841 is that that of @var{X} and whose exponent part if @var{I} is returned;
10842 it is @code{FRACTION(X) * RADIX(X)**I}.
10844 @item @emph{Example}:
10846 PROGRAM test_setexp
10847 REAL :: x = 178.1387e-4
10849 PRINT *, SET_EXPONENT(x, i), FRACTION(x) * RADIX(x)**i
10858 @section @code{SHAPE} --- Determine the shape of an array
10860 @cindex array, shape
10863 @item @emph{Description}:
10864 Determines the shape of an array.
10866 @item @emph{Standard}:
10867 Fortran 95 and later, with @var{KIND} argument Fortran 2003 and later
10869 @item @emph{Class}:
10872 @item @emph{Syntax}:
10873 @code{RESULT = SHAPE(SOURCE [, KIND])}
10875 @item @emph{Arguments}:
10876 @multitable @columnfractions .15 .70
10877 @item @var{SOURCE} @tab Shall be an array or scalar of any type.
10878 If @var{SOURCE} is a pointer it must be associated and allocatable
10879 arrays must be allocated.
10880 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
10881 expression indicating the kind parameter of the result.
10884 @item @emph{Return value}:
10885 An @code{INTEGER} array of rank one with as many elements as @var{SOURCE}
10886 has dimensions. The elements of the resulting array correspond to the extend
10887 of @var{SOURCE} along the respective dimensions. If @var{SOURCE} is a scalar,
10888 the result is the rank one array of size zero. If @var{KIND} is absent, the
10889 return value has the default integer kind otherwise the specified kind.
10891 @item @emph{Example}:
10894 INTEGER, DIMENSION(-1:1, -1:2) :: A
10895 WRITE(*,*) SHAPE(A) ! (/ 3, 4 /)
10896 WRITE(*,*) SIZE(SHAPE(42)) ! (/ /)
10900 @item @emph{See also}:
10901 @ref{RESHAPE}, @ref{SIZE}
10907 @section @code{SHIFTA} --- Right shift with fill
10909 @cindex bits, shift right
10910 @cindex shift, right with fill
10913 @item @emph{Description}:
10914 @code{SHIFTA} returns a value corresponding to @var{I} with all of the
10915 bits shifted right by @var{SHIFT} places. If the absolute value of
10916 @var{SHIFT} is greater than @code{BIT_SIZE(I)}, the value is undefined.
10917 Bits shifted out from the right end are lost. The fill is arithmetic: the
10918 bits shifted in from the left end are equal to the leftmost bit, which in
10919 two's complement representation is the sign bit.
10921 @item @emph{Standard}:
10922 Fortran 2008 and later
10924 @item @emph{Class}:
10927 @item @emph{Syntax}:
10928 @code{RESULT = SHIFTA(I, SHIFT)}
10930 @item @emph{Arguments}:
10931 @multitable @columnfractions .15 .70
10932 @item @var{I} @tab The type shall be @code{INTEGER}.
10933 @item @var{SHIFT} @tab The type shall be @code{INTEGER}.
10936 @item @emph{Return value}:
10937 The return value is of type @code{INTEGER} and of the same kind as
10940 @item @emph{See also}:
10941 @ref{SHIFTL}, @ref{SHIFTR}
10947 @section @code{SHIFTL} --- Left shift
10949 @cindex bits, shift left
10950 @cindex shift, left
10953 @item @emph{Description}:
10954 @code{SHIFTL} returns a value corresponding to @var{I} with all of the
10955 bits shifted left by @var{SHIFT} places. If the absolute value of
10956 @var{SHIFT} is greater than @code{BIT_SIZE(I)}, the value is undefined.
10957 Bits shifted out from the left end are lost, and bits shifted in from
10958 the right end are set to 0.
10960 @item @emph{Standard}:
10961 Fortran 2008 and later
10963 @item @emph{Class}:
10966 @item @emph{Syntax}:
10967 @code{RESULT = SHIFTL(I, SHIFT)}
10969 @item @emph{Arguments}:
10970 @multitable @columnfractions .15 .70
10971 @item @var{I} @tab The type shall be @code{INTEGER}.
10972 @item @var{SHIFT} @tab The type shall be @code{INTEGER}.
10975 @item @emph{Return value}:
10976 The return value is of type @code{INTEGER} and of the same kind as
10979 @item @emph{See also}:
10980 @ref{SHIFTA}, @ref{SHIFTR}
10986 @section @code{SHIFTR} --- Right shift
10988 @cindex bits, shift right
10989 @cindex shift, right
10992 @item @emph{Description}:
10993 @code{SHIFTR} returns a value corresponding to @var{I} with all of the
10994 bits shifted right by @var{SHIFT} places. If the absolute value of
10995 @var{SHIFT} is greater than @code{BIT_SIZE(I)}, the value is undefined.
10996 Bits shifted out from the right end are lost, and bits shifted in from
10997 the left end are set to 0.
10999 @item @emph{Standard}:
11000 Fortran 2008 and later
11002 @item @emph{Class}:
11005 @item @emph{Syntax}:
11006 @code{RESULT = SHIFTR(I, SHIFT)}
11008 @item @emph{Arguments}:
11009 @multitable @columnfractions .15 .70
11010 @item @var{I} @tab The type shall be @code{INTEGER}.
11011 @item @var{SHIFT} @tab The type shall be @code{INTEGER}.
11014 @item @emph{Return value}:
11015 The return value is of type @code{INTEGER} and of the same kind as
11018 @item @emph{See also}:
11019 @ref{SHIFTA}, @ref{SHIFTL}
11025 @section @code{SIGN} --- Sign copying function
11029 @cindex sign copying
11032 @item @emph{Description}:
11033 @code{SIGN(A,B)} returns the value of @var{A} with the sign of @var{B}.
11035 @item @emph{Standard}:
11036 Fortran 77 and later
11038 @item @emph{Class}:
11041 @item @emph{Syntax}:
11042 @code{RESULT = SIGN(A, B)}
11044 @item @emph{Arguments}:
11045 @multitable @columnfractions .15 .70
11046 @item @var{A} @tab Shall be of type @code{INTEGER} or @code{REAL}
11047 @item @var{B} @tab Shall be of the same type and kind as @var{A}
11050 @item @emph{Return value}:
11051 The kind of the return value is that of @var{A} and @var{B}.
11052 If @math{B\ge 0} then the result is @code{ABS(A)}, else
11053 it is @code{-ABS(A)}.
11055 @item @emph{Example}:
11058 print *, sign(-12,1)
11059 print *, sign(-12,0)
11060 print *, sign(-12,-1)
11062 print *, sign(-12.,1.)
11063 print *, sign(-12.,0.)
11064 print *, sign(-12.,-1.)
11065 end program test_sign
11068 @item @emph{Specific names}:
11069 @multitable @columnfractions .20 .20 .20 .25
11070 @item Name @tab Arguments @tab Return type @tab Standard
11071 @item @code{SIGN(A,B)} @tab @code{REAL(4) A, B} @tab @code{REAL(4)} @tab f77, gnu
11072 @item @code{ISIGN(A,B)} @tab @code{INTEGER(4) A, B} @tab @code{INTEGER(4)} @tab f77, gnu
11073 @item @code{DSIGN(A,B)} @tab @code{REAL(8) A, B} @tab @code{REAL(8)} @tab f77, gnu
11080 @section @code{SIGNAL} --- Signal handling subroutine (or function)
11082 @cindex system, signal handling
11085 @item @emph{Description}:
11086 @code{SIGNAL(NUMBER, HANDLER [, STATUS])} causes external subroutine
11087 @var{HANDLER} to be executed with a single integer argument when signal
11088 @var{NUMBER} occurs. If @var{HANDLER} is an integer, it can be used to
11089 turn off handling of signal @var{NUMBER} or revert to its default
11090 action. See @code{signal(2)}.
11092 If @code{SIGNAL} is called as a subroutine and the @var{STATUS} argument
11093 is supplied, it is set to the value returned by @code{signal(2)}.
11095 @item @emph{Standard}:
11098 @item @emph{Class}:
11099 Subroutine, function
11101 @item @emph{Syntax}:
11102 @multitable @columnfractions .80
11103 @item @code{CALL SIGNAL(NUMBER, HANDLER [, STATUS])}
11104 @item @code{STATUS = SIGNAL(NUMBER, HANDLER)}
11107 @item @emph{Arguments}:
11108 @multitable @columnfractions .15 .70
11109 @item @var{NUMBER} @tab Shall be a scalar integer, with @code{INTENT(IN)}
11110 @item @var{HANDLER}@tab Signal handler (@code{INTEGER FUNCTION} or
11111 @code{SUBROUTINE}) or dummy/global @code{INTEGER} scalar.
11112 @code{INTEGER}. It is @code{INTENT(IN)}.
11113 @item @var{STATUS} @tab (Optional) @var{STATUS} shall be a scalar
11114 integer. It has @code{INTENT(OUT)}.
11116 @c TODO: What should the interface of the handler be? Does it take arguments?
11118 @item @emph{Return value}:
11119 The @code{SIGNAL} function returns the value returned by @code{signal(2)}.
11121 @item @emph{Example}:
11123 program test_signal
11125 external handler_print
11127 call signal (12, handler_print)
11128 call signal (10, 1)
11131 end program test_signal
11138 @section @code{SIN} --- Sine function
11144 @cindex trigonometric function, sine
11148 @item @emph{Description}:
11149 @code{SIN(X)} computes the sine of @var{X}.
11151 @item @emph{Standard}:
11152 Fortran 77 and later
11154 @item @emph{Class}:
11157 @item @emph{Syntax}:
11158 @code{RESULT = SIN(X)}
11160 @item @emph{Arguments}:
11161 @multitable @columnfractions .15 .70
11162 @item @var{X} @tab The type shall be @code{REAL} or
11166 @item @emph{Return value}:
11167 The return value has same type and kind as @var{X}.
11169 @item @emph{Example}:
11174 end program test_sin
11177 @item @emph{Specific names}:
11178 @multitable @columnfractions .20 .20 .20 .25
11179 @item Name @tab Argument @tab Return type @tab Standard
11180 @item @code{SIN(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab f77, gnu
11181 @item @code{DSIN(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab f95, gnu
11182 @item @code{CSIN(X)} @tab @code{COMPLEX(4) X} @tab @code{COMPLEX(4)} @tab f95, gnu
11183 @item @code{ZSIN(X)} @tab @code{COMPLEX(8) X} @tab @code{COMPLEX(8)} @tab f95, gnu
11184 @item @code{CDSIN(X)} @tab @code{COMPLEX(8) X} @tab @code{COMPLEX(8)} @tab f95, gnu
11187 @item @emph{See also}:
11194 @section @code{SINH} --- Hyperbolic sine function
11197 @cindex hyperbolic sine
11198 @cindex hyperbolic function, sine
11199 @cindex sine, hyperbolic
11202 @item @emph{Description}:
11203 @code{SINH(X)} computes the hyperbolic sine of @var{X}.
11205 @item @emph{Standard}:
11206 Fortran 95 and later, for a complex argument Fortran 2008 or later
11208 @item @emph{Class}:
11211 @item @emph{Syntax}:
11212 @code{RESULT = SINH(X)}
11214 @item @emph{Arguments}:
11215 @multitable @columnfractions .15 .70
11216 @item @var{X} @tab The type shall be @code{REAL} or @code{COMPLEX}.
11219 @item @emph{Return value}:
11220 The return value has same type and kind as @var{X}.
11222 @item @emph{Example}:
11225 real(8) :: x = - 1.0_8
11227 end program test_sinh
11230 @item @emph{Specific names}:
11231 @multitable @columnfractions .20 .20 .20 .25
11232 @item Name @tab Argument @tab Return type @tab Standard
11233 @item @code{SINH(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab Fortran 95 and later
11234 @item @code{DSINH(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab Fortran 95 and later
11237 @item @emph{See also}:
11244 @section @code{SIZE} --- Determine the size of an array
11246 @cindex array, size
11247 @cindex array, number of elements
11248 @cindex array, count elements
11251 @item @emph{Description}:
11252 Determine the extent of @var{ARRAY} along a specified dimension @var{DIM},
11253 or the total number of elements in @var{ARRAY} if @var{DIM} is absent.
11255 @item @emph{Standard}:
11256 Fortran 95 and later, with @var{KIND} argument Fortran 2003 and later
11258 @item @emph{Class}:
11261 @item @emph{Syntax}:
11262 @code{RESULT = SIZE(ARRAY[, DIM [, KIND]])}
11264 @item @emph{Arguments}:
11265 @multitable @columnfractions .15 .70
11266 @item @var{ARRAY} @tab Shall be an array of any type. If @var{ARRAY} is
11267 a pointer it must be associated and allocatable arrays must be allocated.
11268 @item @var{DIM} @tab (Optional) shall be a scalar of type @code{INTEGER}
11269 and its value shall be in the range from 1 to n, where n equals the rank
11271 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
11272 expression indicating the kind parameter of the result.
11275 @item @emph{Return value}:
11276 The return value is of type @code{INTEGER} and of kind @var{KIND}. If
11277 @var{KIND} is absent, the return value is of default integer kind.
11279 @item @emph{Example}:
11282 WRITE(*,*) SIZE((/ 1, 2 /)) ! 2
11286 @item @emph{See also}:
11287 @ref{SHAPE}, @ref{RESHAPE}
11292 @section @code{SIZEOF} --- Size in bytes of an expression
11294 @cindex expression size
11295 @cindex size of an expression
11298 @item @emph{Description}:
11299 @code{SIZEOF(X)} calculates the number of bytes of storage the
11300 expression @code{X} occupies.
11302 @item @emph{Standard}:
11305 @item @emph{Class}:
11308 @item @emph{Syntax}:
11309 @code{N = SIZEOF(X)}
11311 @item @emph{Arguments}:
11312 @multitable @columnfractions .15 .70
11313 @item @var{X} @tab The argument shall be of any type, rank or shape.
11316 @item @emph{Return value}:
11317 The return value is of type integer and of the system-dependent kind
11318 @var{C_SIZE_T} (from the @var{ISO_C_BINDING} module). Its value is the
11319 number of bytes occupied by the argument. If the argument has the
11320 @code{POINTER} attribute, the number of bytes of the storage area pointed
11321 to is returned. If the argument is of a derived type with @code{POINTER}
11322 or @code{ALLOCATABLE} components, the return value doesn't account for
11323 the sizes of the data pointed to by these components. If the argument is
11324 polymorphic, the size according to the declared type is returned.
11326 @item @emph{Example}:
11330 print *, (sizeof(s)/sizeof(r) == 5)
11333 The example will print @code{.TRUE.} unless you are using a platform
11334 where default @code{REAL} variables are unusually padded.
11336 @item @emph{See also}:
11337 @ref{C_SIZEOF}, @ref{STORAGE_SIZE}
11342 @section @code{SLEEP} --- Sleep for the specified number of seconds
11344 @cindex delayed execution
11347 @item @emph{Description}:
11348 Calling this subroutine causes the process to pause for @var{SECONDS} seconds.
11350 @item @emph{Standard}:
11353 @item @emph{Class}:
11356 @item @emph{Syntax}:
11357 @code{CALL SLEEP(SECONDS)}
11359 @item @emph{Arguments}:
11360 @multitable @columnfractions .15 .70
11361 @item @var{SECONDS} @tab The type shall be of default @code{INTEGER}.
11364 @item @emph{Example}:
11375 @section @code{SPACING} --- Smallest distance between two numbers of a given type
11377 @cindex real number, relative spacing
11378 @cindex floating point, relative spacing
11381 @item @emph{Description}:
11382 Determines the distance between the argument @var{X} and the nearest
11383 adjacent number of the same type.
11385 @item @emph{Standard}:
11386 Fortran 95 and later
11388 @item @emph{Class}:
11391 @item @emph{Syntax}:
11392 @code{RESULT = SPACING(X)}
11394 @item @emph{Arguments}:
11395 @multitable @columnfractions .15 .70
11396 @item @var{X} @tab Shall be of type @code{REAL}.
11399 @item @emph{Return value}:
11400 The result is of the same type as the input argument @var{X}.
11402 @item @emph{Example}:
11404 PROGRAM test_spacing
11405 INTEGER, PARAMETER :: SGL = SELECTED_REAL_KIND(p=6, r=37)
11406 INTEGER, PARAMETER :: DBL = SELECTED_REAL_KIND(p=13, r=200)
11408 WRITE(*,*) spacing(1.0_SGL) ! "1.1920929E-07" on i686
11409 WRITE(*,*) spacing(1.0_DBL) ! "2.220446049250313E-016" on i686
11413 @item @emph{See also}:
11420 @section @code{SPREAD} --- Add a dimension to an array
11422 @cindex array, increase dimension
11423 @cindex array, duplicate elements
11424 @cindex array, duplicate dimensions
11427 @item @emph{Description}:
11428 Replicates a @var{SOURCE} array @var{NCOPIES} times along a specified
11429 dimension @var{DIM}.
11431 @item @emph{Standard}:
11432 Fortran 95 and later
11434 @item @emph{Class}:
11435 Transformational function
11437 @item @emph{Syntax}:
11438 @code{RESULT = SPREAD(SOURCE, DIM, NCOPIES)}
11440 @item @emph{Arguments}:
11441 @multitable @columnfractions .15 .70
11442 @item @var{SOURCE} @tab Shall be a scalar or an array of any type and
11443 a rank less than seven.
11444 @item @var{DIM} @tab Shall be a scalar of type @code{INTEGER} with a
11445 value in the range from 1 to n+1, where n equals the rank of @var{SOURCE}.
11446 @item @var{NCOPIES} @tab Shall be a scalar of type @code{INTEGER}.
11449 @item @emph{Return value}:
11450 The result is an array of the same type as @var{SOURCE} and has rank n+1
11451 where n equals the rank of @var{SOURCE}.
11453 @item @emph{Example}:
11455 PROGRAM test_spread
11456 INTEGER :: a = 1, b(2) = (/ 1, 2 /)
11457 WRITE(*,*) SPREAD(A, 1, 2) ! "1 1"
11458 WRITE(*,*) SPREAD(B, 1, 2) ! "1 1 2 2"
11462 @item @emph{See also}:
11469 @section @code{SQRT} --- Square-root function
11476 @cindex square-root
11479 @item @emph{Description}:
11480 @code{SQRT(X)} computes the square root of @var{X}.
11482 @item @emph{Standard}:
11483 Fortran 77 and later
11485 @item @emph{Class}:
11488 @item @emph{Syntax}:
11489 @code{RESULT = SQRT(X)}
11491 @item @emph{Arguments}:
11492 @multitable @columnfractions .15 .70
11493 @item @var{X} @tab The type shall be @code{REAL} or
11497 @item @emph{Return value}:
11498 The return value is of type @code{REAL} or @code{COMPLEX}.
11499 The kind type parameter is the same as @var{X}.
11501 @item @emph{Example}:
11504 real(8) :: x = 2.0_8
11505 complex :: z = (1.0, 2.0)
11508 end program test_sqrt
11511 @item @emph{Specific names}:
11512 @multitable @columnfractions .20 .20 .20 .25
11513 @item Name @tab Argument @tab Return type @tab Standard
11514 @item @code{SQRT(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab Fortran 95 and later
11515 @item @code{DSQRT(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab Fortran 95 and later
11516 @item @code{CSQRT(X)} @tab @code{COMPLEX(4) X} @tab @code{COMPLEX(4)} @tab Fortran 95 and later
11517 @item @code{ZSQRT(X)} @tab @code{COMPLEX(8) X} @tab @code{COMPLEX(8)} @tab GNU extension
11518 @item @code{CDSQRT(X)} @tab @code{COMPLEX(8) X} @tab @code{COMPLEX(8)} @tab GNU extension
11525 @section @code{SRAND} --- Reinitialize the random number generator
11527 @cindex random number generation, seeding
11528 @cindex seeding a random number generator
11531 @item @emph{Description}:
11532 @code{SRAND} reinitializes the pseudo-random number generator
11533 called by @code{RAND} and @code{IRAND}. The new seed used by the
11534 generator is specified by the required argument @var{SEED}.
11536 @item @emph{Standard}:
11539 @item @emph{Class}:
11542 @item @emph{Syntax}:
11543 @code{CALL SRAND(SEED)}
11545 @item @emph{Arguments}:
11546 @multitable @columnfractions .15 .70
11547 @item @var{SEED} @tab Shall be a scalar @code{INTEGER(kind=4)}.
11550 @item @emph{Return value}:
11551 Does not return anything.
11553 @item @emph{Example}:
11554 See @code{RAND} and @code{IRAND} for examples.
11556 @item @emph{Notes}:
11557 The Fortran 2003 standard specifies the intrinsic @code{RANDOM_SEED} to
11558 initialize the pseudo-random numbers generator and @code{RANDOM_NUMBER}
11559 to generate pseudo-random numbers. Please note that in
11560 GNU Fortran, these two sets of intrinsics (@code{RAND},
11561 @code{IRAND} and @code{SRAND} on the one hand, @code{RANDOM_NUMBER} and
11562 @code{RANDOM_SEED} on the other hand) access two independent
11563 pseudo-random number generators.
11565 @item @emph{See also}:
11566 @ref{RAND}, @ref{RANDOM_SEED}, @ref{RANDOM_NUMBER}
11573 @section @code{STAT} --- Get file status
11575 @cindex file system, file status
11578 @item @emph{Description}:
11579 This function returns information about a file. No permissions are required on
11580 the file itself, but execute (search) permission is required on all of the
11581 directories in path that lead to the file.
11583 The elements that are obtained and stored in the array @code{VALUES}:
11584 @multitable @columnfractions .15 .70
11585 @item @code{VALUES(1)} @tab Device ID
11586 @item @code{VALUES(2)} @tab Inode number
11587 @item @code{VALUES(3)} @tab File mode
11588 @item @code{VALUES(4)} @tab Number of links
11589 @item @code{VALUES(5)} @tab Owner's uid
11590 @item @code{VALUES(6)} @tab Owner's gid
11591 @item @code{VALUES(7)} @tab ID of device containing directory entry for file (0 if not available)
11592 @item @code{VALUES(8)} @tab File size (bytes)
11593 @item @code{VALUES(9)} @tab Last access time
11594 @item @code{VALUES(10)} @tab Last modification time
11595 @item @code{VALUES(11)} @tab Last file status change time
11596 @item @code{VALUES(12)} @tab Preferred I/O block size (-1 if not available)
11597 @item @code{VALUES(13)} @tab Number of blocks allocated (-1 if not available)
11600 Not all these elements are relevant on all systems.
11601 If an element is not relevant, it is returned as 0.
11603 This intrinsic is provided in both subroutine and function forms; however,
11604 only one form can be used in any given program unit.
11606 @item @emph{Standard}:
11609 @item @emph{Class}:
11610 Subroutine, function
11612 @item @emph{Syntax}:
11613 @multitable @columnfractions .80
11614 @item @code{CALL STAT(NAME, VALUES [, STATUS])}
11615 @item @code{STATUS = STAT(NAME, VALUES)}
11618 @item @emph{Arguments}:
11619 @multitable @columnfractions .15 .70
11620 @item @var{NAME} @tab The type shall be @code{CHARACTER}, of the
11621 default kind and a valid path within the file system.
11622 @item @var{VALUES} @tab The type shall be @code{INTEGER(4), DIMENSION(13)}.
11623 @item @var{STATUS} @tab (Optional) status flag of type @code{INTEGER(4)}. Returns 0
11624 on success and a system specific error code otherwise.
11627 @item @emph{Example}:
11630 INTEGER, DIMENSION(13) :: buff
11633 CALL STAT("/etc/passwd", buff, status)
11635 IF (status == 0) THEN
11636 WRITE (*, FMT="('Device ID:', T30, I19)") buff(1)
11637 WRITE (*, FMT="('Inode number:', T30, I19)") buff(2)
11638 WRITE (*, FMT="('File mode (octal):', T30, O19)") buff(3)
11639 WRITE (*, FMT="('Number of links:', T30, I19)") buff(4)
11640 WRITE (*, FMT="('Owner''s uid:', T30, I19)") buff(5)
11641 WRITE (*, FMT="('Owner''s gid:', T30, I19)") buff(6)
11642 WRITE (*, FMT="('Device where located:', T30, I19)") buff(7)
11643 WRITE (*, FMT="('File size:', T30, I19)") buff(8)
11644 WRITE (*, FMT="('Last access time:', T30, A19)") CTIME(buff(9))
11645 WRITE (*, FMT="('Last modification time', T30, A19)") CTIME(buff(10))
11646 WRITE (*, FMT="('Last status change time:', T30, A19)") CTIME(buff(11))
11647 WRITE (*, FMT="('Preferred block size:', T30, I19)") buff(12)
11648 WRITE (*, FMT="('No. of blocks allocated:', T30, I19)") buff(13)
11653 @item @emph{See also}:
11654 To stat an open file: @ref{FSTAT}, to stat a link: @ref{LSTAT}
11660 @section @code{STORAGE_SIZE} --- Storage size in bits
11661 @fnindex STORAGE_SIZE
11662 @cindex storage size
11665 @item @emph{Description}:
11666 Returns the storage size of argument @var{A} in bits.
11667 @item @emph{Standard}:
11668 Fortran 2008 and later
11669 @item @emph{Class}:
11671 @item @emph{Syntax}:
11672 @code{RESULT = STORAGE_SIZE(A [, KIND])}
11674 @item @emph{Arguments}:
11675 @multitable @columnfractions .15 .70
11676 @item @var{A} @tab Shall be a scalar or array of any type.
11677 @item @var{KIND} @tab (Optional) shall be a scalar integer constant expression.
11680 @item @emph{Return Value}:
11681 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
11682 has the dynamic type and type parameters of A.
11684 @item @emph{See also}:
11685 @ref{C_SIZEOF}, @ref{SIZEOF}
11691 @section @code{SUM} --- Sum of array elements
11694 @cindex array, add elements
11695 @cindex array, conditionally add elements
11696 @cindex sum array elements
11699 @item @emph{Description}:
11700 Adds the elements of @var{ARRAY} along dimension @var{DIM} if
11701 the corresponding element in @var{MASK} is @code{TRUE}.
11703 @item @emph{Standard}:
11704 Fortran 95 and later
11706 @item @emph{Class}:
11707 Transformational function
11709 @item @emph{Syntax}:
11710 @multitable @columnfractions .80
11711 @item @code{RESULT = SUM(ARRAY[, MASK])}
11712 @item @code{RESULT = SUM(ARRAY, DIM[, MASK])}
11715 @item @emph{Arguments}:
11716 @multitable @columnfractions .15 .70
11717 @item @var{ARRAY} @tab Shall be an array of type @code{INTEGER},
11718 @code{REAL} or @code{COMPLEX}.
11719 @item @var{DIM} @tab (Optional) shall be a scalar of type
11720 @code{INTEGER} with a value in the range from 1 to n, where n
11721 equals the rank of @var{ARRAY}.
11722 @item @var{MASK} @tab (Optional) shall be of type @code{LOGICAL}
11723 and either be a scalar or an array of the same shape as @var{ARRAY}.
11726 @item @emph{Return value}:
11727 The result is of the same type as @var{ARRAY}.
11729 If @var{DIM} is absent, a scalar with the sum of all elements in @var{ARRAY}
11730 is returned. Otherwise, an array of rank n-1, where n equals the rank of
11731 @var{ARRAY}, and a shape similar to that of @var{ARRAY} with dimension @var{DIM}
11732 dropped is returned.
11734 @item @emph{Example}:
11737 INTEGER :: x(5) = (/ 1, 2, 3, 4 ,5 /)
11738 print *, SUM(x) ! all elements, sum = 15
11739 print *, SUM(x, MASK=MOD(x, 2)==1) ! odd elements, sum = 9
11743 @item @emph{See also}:
11750 @section @code{SYMLNK} --- Create a symbolic link
11752 @cindex file system, create link
11753 @cindex file system, soft link
11756 @item @emph{Description}:
11757 Makes a symbolic link from file @var{PATH1} to @var{PATH2}. A null
11758 character (@code{CHAR(0)}) can be used to mark the end of the names in
11759 @var{PATH1} and @var{PATH2}; otherwise, trailing blanks in the file
11760 names are ignored. If the @var{STATUS} argument is supplied, it
11761 contains 0 on success or a nonzero error code upon return; see
11762 @code{symlink(2)}. If the system does not supply @code{symlink(2)},
11763 @code{ENOSYS} is returned.
11765 This intrinsic is provided in both subroutine and function forms;
11766 however, only one form can be used in any given program unit.
11768 @item @emph{Standard}:
11771 @item @emph{Class}:
11772 Subroutine, function
11774 @item @emph{Syntax}:
11775 @multitable @columnfractions .80
11776 @item @code{CALL SYMLNK(PATH1, PATH2 [, STATUS])}
11777 @item @code{STATUS = SYMLNK(PATH1, PATH2)}
11780 @item @emph{Arguments}:
11781 @multitable @columnfractions .15 .70
11782 @item @var{PATH1} @tab Shall be of default @code{CHARACTER} type.
11783 @item @var{PATH2} @tab Shall be of default @code{CHARACTER} type.
11784 @item @var{STATUS} @tab (Optional) Shall be of default @code{INTEGER} type.
11787 @item @emph{See also}:
11788 @ref{LINK}, @ref{UNLINK}
11795 @section @code{SYSTEM} --- Execute a shell command
11797 @cindex system, system call
11800 @item @emph{Description}:
11801 Passes the command @var{COMMAND} to a shell (see @code{system(3)}). If
11802 argument @var{STATUS} is present, it contains the value returned by
11803 @code{system(3)}, which is presumably 0 if the shell command succeeded.
11804 Note that which shell is used to invoke the command is system-dependent
11805 and environment-dependent.
11807 This intrinsic is provided in both subroutine and function forms;
11808 however, only one form can be used in any given program unit.
11810 Note that the @code{system} function need not be thread-safe. It is
11811 the responsibility of the user to ensure that @code{system} is not
11812 called concurrently.
11814 @item @emph{Standard}:
11817 @item @emph{Class}:
11818 Subroutine, function
11820 @item @emph{Syntax}:
11821 @multitable @columnfractions .80
11822 @item @code{CALL SYSTEM(COMMAND [, STATUS])}
11823 @item @code{STATUS = SYSTEM(COMMAND)}
11826 @item @emph{Arguments}:
11827 @multitable @columnfractions .15 .70
11828 @item @var{COMMAND} @tab Shall be of default @code{CHARACTER} type.
11829 @item @var{STATUS} @tab (Optional) Shall be of default @code{INTEGER} type.
11832 @item @emph{See also}:
11833 @ref{EXECUTE_COMMAND_LINE}, which is part of the Fortran 2008 standard
11834 and should considered in new code for future portability.
11840 @section @code{SYSTEM_CLOCK} --- Time function
11841 @fnindex SYSTEM_CLOCK
11842 @cindex time, clock ticks
11843 @cindex clock ticks
11846 @item @emph{Description}:
11847 Determines the @var{COUNT} of a processor clock since an unspecified
11848 time in the past modulo @var{COUNT_MAX}, @var{COUNT_RATE} determines
11849 the number of clock ticks per second. If the platform supports a high
11850 resolution monotonic clock, that clock is used and can provide up to
11851 nanosecond resolution. If a high resolution monotonic clock is not
11852 available, the implementation falls back to a potentially lower
11853 resolution realtime clock.
11855 @var{COUNT_RATE} and @var{COUNT_MAX} vary depending on the kind of the
11856 arguments. For @var{kind=8} arguments, @var{COUNT} represents
11857 nanoseconds, and for @var{kind=4} arguments, @var{COUNT} represents
11858 milliseconds. Other than the kind dependency, @var{COUNT_RATE} and
11859 @var{COUNT_MAX} are constant, however the particular values are
11860 specific to @command{gfortran}.
11862 If there is no clock, @var{COUNT} is set to @code{-HUGE(COUNT)}, and
11863 @var{COUNT_RATE} and @var{COUNT_MAX} are set to zero.
11865 When running on a platform using the GNU C library (glibc), or a
11866 derivative thereof, the high resolution monotonic clock is available
11867 only when linking with the @var{rt} library. This can be done
11868 explicitly by adding the @code{-lrt} flag when linking the
11869 application, but is also done implicitly when using OpenMP.
11871 @item @emph{Standard}:
11872 Fortran 95 and later
11874 @item @emph{Class}:
11877 @item @emph{Syntax}:
11878 @code{CALL SYSTEM_CLOCK([COUNT, COUNT_RATE, COUNT_MAX])}
11880 @item @emph{Arguments}:
11881 @multitable @columnfractions .15 .70
11882 @item @var{COUNT} @tab (Optional) shall be a scalar of type
11883 @code{INTEGER} with @code{INTENT(OUT)}.
11884 @item @var{COUNT_RATE} @tab (Optional) shall be a scalar of type
11885 @code{INTEGER} with @code{INTENT(OUT)}.
11886 @item @var{COUNT_MAX} @tab (Optional) shall be a scalar of type
11887 @code{INTEGER} with @code{INTENT(OUT)}.
11890 @item @emph{Example}:
11892 PROGRAM test_system_clock
11893 INTEGER :: count, count_rate, count_max
11894 CALL SYSTEM_CLOCK(count, count_rate, count_max)
11895 WRITE(*,*) count, count_rate, count_max
11899 @item @emph{See also}:
11900 @ref{DATE_AND_TIME}, @ref{CPU_TIME}
11906 @section @code{TAN} --- Tangent function
11909 @cindex trigonometric function, tangent
11913 @item @emph{Description}:
11914 @code{TAN(X)} computes the tangent of @var{X}.
11916 @item @emph{Standard}:
11917 Fortran 77 and later, for a complex argument Fortran 2008 or later
11919 @item @emph{Class}:
11922 @item @emph{Syntax}:
11923 @code{RESULT = TAN(X)}
11925 @item @emph{Arguments}:
11926 @multitable @columnfractions .15 .70
11927 @item @var{X} @tab The type shall be @code{REAL} or @code{COMPLEX}.
11930 @item @emph{Return value}:
11931 The return value has same type and kind as @var{X}.
11933 @item @emph{Example}:
11936 real(8) :: x = 0.165_8
11938 end program test_tan
11941 @item @emph{Specific names}:
11942 @multitable @columnfractions .20 .20 .20 .25
11943 @item Name @tab Argument @tab Return type @tab Standard
11944 @item @code{TAN(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab Fortran 95 and later
11945 @item @code{DTAN(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab Fortran 95 and later
11948 @item @emph{See also}:
11955 @section @code{TANH} --- Hyperbolic tangent function
11958 @cindex hyperbolic tangent
11959 @cindex hyperbolic function, tangent
11960 @cindex tangent, hyperbolic
11963 @item @emph{Description}:
11964 @code{TANH(X)} computes the hyperbolic tangent of @var{X}.
11966 @item @emph{Standard}:
11967 Fortran 77 and later, for a complex argument Fortran 2008 or later
11969 @item @emph{Class}:
11972 @item @emph{Syntax}:
11975 @item @emph{Arguments}:
11976 @multitable @columnfractions .15 .70
11977 @item @var{X} @tab The type shall be @code{REAL} or @code{COMPLEX}.
11980 @item @emph{Return value}:
11981 The return value has same type and kind as @var{X}. If @var{X} is
11982 complex, the imaginary part of the result is in radians. If @var{X}
11983 is @code{REAL}, the return value lies in the range
11984 @math{ - 1 \leq tanh(x) \leq 1 }.
11986 @item @emph{Example}:
11989 real(8) :: x = 2.1_8
11991 end program test_tanh
11994 @item @emph{Specific names}:
11995 @multitable @columnfractions .20 .20 .20 .25
11996 @item Name @tab Argument @tab Return type @tab Standard
11997 @item @code{TANH(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab Fortran 95 and later
11998 @item @code{DTANH(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab Fortran 95 and later
12001 @item @emph{See also}:
12008 @section @code{THIS_IMAGE} --- Function that returns the cosubscript index of this image
12009 @fnindex THIS_IMAGE
12010 @cindex coarray, @code{THIS_IMAGE}
12011 @cindex images, index of this image
12014 @item @emph{Description}:
12015 Returns the cosubscript for this image.
12017 @item @emph{Standard}:
12018 Fortran 2008 and later
12020 @item @emph{Class}:
12021 Transformational function
12023 @item @emph{Syntax}:
12024 @multitable @columnfractions .80
12025 @item @code{RESULT = THIS_IMAGE()}
12026 @item @code{RESULT = THIS_IMAGE(COARRAY [, DIM])}
12029 @item @emph{Arguments}:
12030 @multitable @columnfractions .15 .70
12031 @item @var{COARRAY} @tab Coarray of any type (optional; if @var{DIM}
12032 present, required).
12033 @item @var{DIM} @tab default integer scalar (optional). If present,
12034 @var{DIM} shall be between one and the corank of @var{COARRAY}.
12038 @item @emph{Return value}:
12039 Default integer. If @var{COARRAY} is not present, it is scalar and its value
12040 is the index of the invoking image. Otherwise, if @var{DIM} is not present,
12041 a rank-1 array with corank elements is returned, containing the cosubscripts
12042 for @var{COARRAY} specifying the invoking image. If @var{DIM} is present,
12043 a scalar is returned, with the value of the @var{DIM} element of
12044 @code{THIS_IMAGE(COARRAY)}.
12046 @item @emph{Example}:
12048 INTEGER :: value[*]
12050 value = THIS_IMAGE()
12052 IF (THIS_IMAGE() == 1) THEN
12053 DO i = 1, NUM_IMAGES()
12054 WRITE(*,'(2(a,i0))') 'value[', i, '] is ', value[i]
12059 @item @emph{See also}:
12060 @ref{NUM_IMAGES}, @ref{IMAGE_INDEX}
12066 @section @code{TIME} --- Time function
12068 @cindex time, current
12069 @cindex current time
12072 @item @emph{Description}:
12073 Returns the current time encoded as an integer (in the manner of the
12074 UNIX function @code{time(3)}). This value is suitable for passing to
12075 @code{CTIME}, @code{GMTIME}, and @code{LTIME}.
12077 This intrinsic is not fully portable, such as to systems with 32-bit
12078 @code{INTEGER} types but supporting times wider than 32 bits. Therefore,
12079 the values returned by this intrinsic might be, or become, negative, or
12080 numerically less than previous values, during a single run of the
12083 See @ref{TIME8}, for information on a similar intrinsic that might be
12084 portable to more GNU Fortran implementations, though to fewer Fortran
12087 @item @emph{Standard}:
12090 @item @emph{Class}:
12093 @item @emph{Syntax}:
12094 @code{RESULT = TIME()}
12096 @item @emph{Return value}:
12097 The return value is a scalar of type @code{INTEGER(4)}.
12099 @item @emph{See also}:
12100 @ref{CTIME}, @ref{GMTIME}, @ref{LTIME}, @ref{MCLOCK}, @ref{TIME8}
12107 @section @code{TIME8} --- Time function (64-bit)
12109 @cindex time, current
12110 @cindex current time
12113 @item @emph{Description}:
12114 Returns the current time encoded as an integer (in the manner of the
12115 UNIX function @code{time(3)}). This value is suitable for passing to
12116 @code{CTIME}, @code{GMTIME}, and @code{LTIME}.
12118 @emph{Warning:} this intrinsic does not increase the range of the timing
12119 values over that returned by @code{time(3)}. On a system with a 32-bit
12120 @code{time(3)}, @code{TIME8} will return a 32-bit value, even though
12121 it is converted to a 64-bit @code{INTEGER(8)} value. That means
12122 overflows of the 32-bit value can still occur. Therefore, the values
12123 returned by this intrinsic might be or become negative or numerically
12124 less than previous values during a single run of the compiled program.
12126 @item @emph{Standard}:
12129 @item @emph{Class}:
12132 @item @emph{Syntax}:
12133 @code{RESULT = TIME8()}
12135 @item @emph{Return value}:
12136 The return value is a scalar of type @code{INTEGER(8)}.
12138 @item @emph{See also}:
12139 @ref{CTIME}, @ref{GMTIME}, @ref{LTIME}, @ref{MCLOCK8}, @ref{TIME}
12146 @section @code{TINY} --- Smallest positive number of a real kind
12148 @cindex limits, smallest number
12149 @cindex model representation, smallest number
12152 @item @emph{Description}:
12153 @code{TINY(X)} returns the smallest positive (non zero) number
12154 in the model of the type of @code{X}.
12156 @item @emph{Standard}:
12157 Fortran 95 and later
12159 @item @emph{Class}:
12162 @item @emph{Syntax}:
12163 @code{RESULT = TINY(X)}
12165 @item @emph{Arguments}:
12166 @multitable @columnfractions .15 .70
12167 @item @var{X} @tab Shall be of type @code{REAL}.
12170 @item @emph{Return value}:
12171 The return value is of the same type and kind as @var{X}
12173 @item @emph{Example}:
12174 See @code{HUGE} for an example.
12180 @section @code{TRAILZ} --- Number of trailing zero bits of an integer
12185 @item @emph{Description}:
12186 @code{TRAILZ} returns the number of trailing zero bits of an integer.
12188 @item @emph{Standard}:
12189 Fortran 2008 and later
12191 @item @emph{Class}:
12194 @item @emph{Syntax}:
12195 @code{RESULT = TRAILZ(I)}
12197 @item @emph{Arguments}:
12198 @multitable @columnfractions .15 .70
12199 @item @var{I} @tab Shall be of type @code{INTEGER}.
12202 @item @emph{Return value}:
12203 The type of the return value is the default @code{INTEGER}.
12204 If all the bits of @code{I} are zero, the result value is @code{BIT_SIZE(I)}.
12206 @item @emph{Example}:
12208 PROGRAM test_trailz
12209 WRITE (*,*) TRAILZ(8) ! prints 3
12213 @item @emph{See also}:
12214 @ref{BIT_SIZE}, @ref{LEADZ}, @ref{POPPAR}, @ref{POPCNT}
12220 @section @code{TRANSFER} --- Transfer bit patterns
12226 @item @emph{Description}:
12227 Interprets the bitwise representation of @var{SOURCE} in memory as if it
12228 is the representation of a variable or array of the same type and type
12229 parameters as @var{MOLD}.
12231 This is approximately equivalent to the C concept of @emph{casting} one
12234 @item @emph{Standard}:
12235 Fortran 95 and later
12237 @item @emph{Class}:
12238 Transformational function
12240 @item @emph{Syntax}:
12241 @code{RESULT = TRANSFER(SOURCE, MOLD[, SIZE])}
12243 @item @emph{Arguments}:
12244 @multitable @columnfractions .15 .70
12245 @item @var{SOURCE} @tab Shall be a scalar or an array of any type.
12246 @item @var{MOLD} @tab Shall be a scalar or an array of any type.
12247 @item @var{SIZE} @tab (Optional) shall be a scalar of type
12251 @item @emph{Return value}:
12252 The result has the same type as @var{MOLD}, with the bit level
12253 representation of @var{SOURCE}. If @var{SIZE} is present, the result is
12254 a one-dimensional array of length @var{SIZE}. If @var{SIZE} is absent
12255 but @var{MOLD} is an array (of any size or shape), the result is a one-
12256 dimensional array of the minimum length needed to contain the entirety
12257 of the bitwise representation of @var{SOURCE}. If @var{SIZE} is absent
12258 and @var{MOLD} is a scalar, the result is a scalar.
12260 If the bitwise representation of the result is longer than that of
12261 @var{SOURCE}, then the leading bits of the result correspond to those of
12262 @var{SOURCE} and any trailing bits are filled arbitrarily.
12264 When the resulting bit representation does not correspond to a valid
12265 representation of a variable of the same type as @var{MOLD}, the results
12266 are undefined, and subsequent operations on the result cannot be
12267 guaranteed to produce sensible behavior. For example, it is possible to
12268 create @code{LOGICAL} variables for which @code{@var{VAR}} and
12269 @code{.NOT.@var{VAR}} both appear to be true.
12271 @item @emph{Example}:
12273 PROGRAM test_transfer
12274 integer :: x = 2143289344
12275 print *, transfer(x, 1.0) ! prints "NaN" on i686
12283 @section @code{TRANSPOSE} --- Transpose an array of rank two
12285 @cindex array, transpose
12286 @cindex matrix, transpose
12290 @item @emph{Description}:
12291 Transpose an array of rank two. Element (i, j) of the result has the value
12292 @code{MATRIX(j, i)}, for all i, j.
12294 @item @emph{Standard}:
12295 Fortran 95 and later
12297 @item @emph{Class}:
12298 Transformational function
12300 @item @emph{Syntax}:
12301 @code{RESULT = TRANSPOSE(MATRIX)}
12303 @item @emph{Arguments}:
12304 @multitable @columnfractions .15 .70
12305 @item @var{MATRIX} @tab Shall be an array of any type and have a rank of two.
12308 @item @emph{Return value}:
12309 The result has the same type as @var{MATRIX}, and has shape
12310 @code{(/ m, n /)} if @var{MATRIX} has shape @code{(/ n, m /)}.
12316 @section @code{TRIM} --- Remove trailing blank characters of a string
12318 @cindex string, remove trailing whitespace
12321 @item @emph{Description}:
12322 Removes trailing blank characters of a string.
12324 @item @emph{Standard}:
12325 Fortran 95 and later
12327 @item @emph{Class}:
12328 Transformational function
12330 @item @emph{Syntax}:
12331 @code{RESULT = TRIM(STRING)}
12333 @item @emph{Arguments}:
12334 @multitable @columnfractions .15 .70
12335 @item @var{STRING} @tab Shall be a scalar of type @code{CHARACTER}.
12338 @item @emph{Return value}:
12339 A scalar of type @code{CHARACTER} which length is that of @var{STRING}
12340 less the number of trailing blanks.
12342 @item @emph{Example}:
12345 CHARACTER(len=10), PARAMETER :: s = "GFORTRAN "
12346 WRITE(*,*) LEN(s), LEN(TRIM(s)) ! "10 8", with/without trailing blanks
12350 @item @emph{See also}:
12351 @ref{ADJUSTL}, @ref{ADJUSTR}
12357 @section @code{TTYNAM} --- Get the name of a terminal device.
12359 @cindex system, terminal
12362 @item @emph{Description}:
12363 Get the name of a terminal device. For more information,
12364 see @code{ttyname(3)}.
12366 This intrinsic is provided in both subroutine and function forms;
12367 however, only one form can be used in any given program unit.
12369 @item @emph{Standard}:
12372 @item @emph{Class}:
12373 Subroutine, function
12375 @item @emph{Syntax}:
12376 @multitable @columnfractions .80
12377 @item @code{CALL TTYNAM(UNIT, NAME)}
12378 @item @code{NAME = TTYNAM(UNIT)}
12381 @item @emph{Arguments}:
12382 @multitable @columnfractions .15 .70
12383 @item @var{UNIT} @tab Shall be a scalar @code{INTEGER}.
12384 @item @var{NAME} @tab Shall be of type @code{CHARACTER}.
12387 @item @emph{Example}:
12389 PROGRAM test_ttynam
12392 IF (isatty(unit=unit)) write(*,*) ttynam(unit)
12397 @item @emph{See also}:
12404 @section @code{UBOUND} --- Upper dimension bounds of an array
12406 @cindex array, upper bound
12409 @item @emph{Description}:
12410 Returns the upper bounds of an array, or a single upper bound
12411 along the @var{DIM} dimension.
12412 @item @emph{Standard}:
12413 Fortran 95 and later, with @var{KIND} argument Fortran 2003 and later
12415 @item @emph{Class}:
12418 @item @emph{Syntax}:
12419 @code{RESULT = UBOUND(ARRAY [, DIM [, KIND]])}
12421 @item @emph{Arguments}:
12422 @multitable @columnfractions .15 .70
12423 @item @var{ARRAY} @tab Shall be an array, of any type.
12424 @item @var{DIM} @tab (Optional) Shall be a scalar @code{INTEGER}.
12425 @item @var{KIND}@tab (Optional) An @code{INTEGER} initialization
12426 expression indicating the kind parameter of the result.
12429 @item @emph{Return value}:
12430 The return value is of type @code{INTEGER} and of kind @var{KIND}. If
12431 @var{KIND} is absent, the return value is of default integer kind.
12432 If @var{DIM} is absent, the result is an array of the upper bounds of
12433 @var{ARRAY}. If @var{DIM} is present, the result is a scalar
12434 corresponding to the upper bound of the array along that dimension. If
12435 @var{ARRAY} is an expression rather than a whole array or array
12436 structure component, or if it has a zero extent along the relevant
12437 dimension, the upper bound is taken to be the number of elements along
12438 the relevant dimension.
12440 @item @emph{See also}:
12441 @ref{LBOUND}, @ref{LCOBOUND}
12447 @section @code{UCOBOUND} --- Upper codimension bounds of an array
12449 @cindex coarray, upper bound
12452 @item @emph{Description}:
12453 Returns the upper cobounds of a coarray, or a single upper cobound
12454 along the @var{DIM} codimension.
12455 @item @emph{Standard}:
12456 Fortran 2008 and later
12458 @item @emph{Class}:
12461 @item @emph{Syntax}:
12462 @code{RESULT = UCOBOUND(COARRAY [, DIM [, KIND]])}
12464 @item @emph{Arguments}:
12465 @multitable @columnfractions .15 .70
12466 @item @var{ARRAY} @tab Shall be an coarray, of any type.
12467 @item @var{DIM} @tab (Optional) Shall be a scalar @code{INTEGER}.
12468 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
12469 expression indicating the kind parameter of the result.
12472 @item @emph{Return value}:
12473 The return value is of type @code{INTEGER} and of kind @var{KIND}. If
12474 @var{KIND} is absent, the return value is of default integer kind.
12475 If @var{DIM} is absent, the result is an array of the lower cobounds of
12476 @var{COARRAY}. If @var{DIM} is present, the result is a scalar
12477 corresponding to the lower cobound of the array along that codimension.
12479 @item @emph{See also}:
12480 @ref{LCOBOUND}, @ref{LBOUND}
12486 @section @code{UMASK} --- Set the file creation mask
12488 @cindex file system, file creation mask
12491 @item @emph{Description}:
12492 Sets the file creation mask to @var{MASK}. If called as a function, it
12493 returns the old value. If called as a subroutine and argument @var{OLD}
12494 if it is supplied, it is set to the old value. See @code{umask(2)}.
12496 @item @emph{Standard}:
12499 @item @emph{Class}:
12500 Subroutine, function
12502 @item @emph{Syntax}:
12503 @multitable @columnfractions .80
12504 @item @code{CALL UMASK(MASK [, OLD])}
12505 @item @code{OLD = UMASK(MASK)}
12508 @item @emph{Arguments}:
12509 @multitable @columnfractions .15 .70
12510 @item @var{MASK} @tab Shall be a scalar of type @code{INTEGER}.
12511 @item @var{OLD} @tab (Optional) Shall be a scalar of type
12520 @section @code{UNLINK} --- Remove a file from the file system
12522 @cindex file system, remove file
12525 @item @emph{Description}:
12526 Unlinks the file @var{PATH}. A null character (@code{CHAR(0)}) can be
12527 used to mark the end of the name in @var{PATH}; otherwise, trailing
12528 blanks in the file name are ignored. If the @var{STATUS} argument is
12529 supplied, it contains 0 on success or a nonzero error code upon return;
12530 see @code{unlink(2)}.
12532 This intrinsic is provided in both subroutine and function forms;
12533 however, only one form can be used in any given program unit.
12535 @item @emph{Standard}:
12538 @item @emph{Class}:
12539 Subroutine, function
12541 @item @emph{Syntax}:
12542 @multitable @columnfractions .80
12543 @item @code{CALL UNLINK(PATH [, STATUS])}
12544 @item @code{STATUS = UNLINK(PATH)}
12547 @item @emph{Arguments}:
12548 @multitable @columnfractions .15 .70
12549 @item @var{PATH} @tab Shall be of default @code{CHARACTER} type.
12550 @item @var{STATUS} @tab (Optional) Shall be of default @code{INTEGER} type.
12553 @item @emph{See also}:
12554 @ref{LINK}, @ref{SYMLNK}
12560 @section @code{UNPACK} --- Unpack an array of rank one into an array
12562 @cindex array, unpacking
12563 @cindex array, increase dimension
12564 @cindex array, scatter elements
12567 @item @emph{Description}:
12568 Store the elements of @var{VECTOR} in an array of higher rank.
12570 @item @emph{Standard}:
12571 Fortran 95 and later
12573 @item @emph{Class}:
12574 Transformational function
12576 @item @emph{Syntax}:
12577 @code{RESULT = UNPACK(VECTOR, MASK, FIELD)}
12579 @item @emph{Arguments}:
12580 @multitable @columnfractions .15 .70
12581 @item @var{VECTOR} @tab Shall be an array of any type and rank one. It
12582 shall have at least as many elements as @var{MASK} has @code{TRUE} values.
12583 @item @var{MASK} @tab Shall be an array of type @code{LOGICAL}.
12584 @item @var{FIELD} @tab Shall be of the same type as @var{VECTOR} and have
12585 the same shape as @var{MASK}.
12588 @item @emph{Return value}:
12589 The resulting array corresponds to @var{FIELD} with @code{TRUE} elements
12590 of @var{MASK} replaced by values from @var{VECTOR} in array element order.
12592 @item @emph{Example}:
12594 PROGRAM test_unpack
12595 integer :: vector(2) = (/1,1/)
12596 logical :: mask(4) = (/ .TRUE., .FALSE., .FALSE., .TRUE. /)
12597 integer :: field(2,2) = 0, unity(2,2)
12599 ! result: unity matrix
12600 unity = unpack(vector, reshape(mask, (/2,2/)), field)
12604 @item @emph{See also}:
12605 @ref{PACK}, @ref{SPREAD}
12611 @section @code{VERIFY} --- Scan a string for characters not a given set
12613 @cindex string, find missing set
12616 @item @emph{Description}:
12617 Verifies that all the characters in @var{STRING} belong to the set of
12618 characters in @var{SET}.
12620 If @var{BACK} is either absent or equals @code{FALSE}, this function
12621 returns the position of the leftmost character of @var{STRING} that is
12622 not in @var{SET}. If @var{BACK} equals @code{TRUE}, the rightmost
12623 position is returned. If all characters of @var{STRING} are found in
12624 @var{SET}, the result is zero.
12626 @item @emph{Standard}:
12627 Fortran 95 and later, with @var{KIND} argument Fortran 2003 and later
12629 @item @emph{Class}:
12632 @item @emph{Syntax}:
12633 @code{RESULT = VERIFY(STRING, SET[, BACK [, KIND]])}
12635 @item @emph{Arguments}:
12636 @multitable @columnfractions .15 .70
12637 @item @var{STRING} @tab Shall be of type @code{CHARACTER}.
12638 @item @var{SET} @tab Shall be of type @code{CHARACTER}.
12639 @item @var{BACK} @tab (Optional) shall be of type @code{LOGICAL}.
12640 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
12641 expression indicating the kind parameter of the result.
12644 @item @emph{Return value}:
12645 The return value is of type @code{INTEGER} and of kind @var{KIND}. If
12646 @var{KIND} is absent, the return value is of default integer kind.
12648 @item @emph{Example}:
12650 PROGRAM test_verify
12651 WRITE(*,*) VERIFY("FORTRAN", "AO") ! 1, found 'F'
12652 WRITE(*,*) VERIFY("FORTRAN", "FOO") ! 3, found 'R'
12653 WRITE(*,*) VERIFY("FORTRAN", "C++") ! 1, found 'F'
12654 WRITE(*,*) VERIFY("FORTRAN", "C++", .TRUE.) ! 7, found 'N'
12655 WRITE(*,*) VERIFY("FORTRAN", "FORTRAN") ! 0' found none
12659 @item @emph{See also}:
12660 @ref{SCAN}, @ref{INDEX intrinsic}
12666 @section @code{XOR} --- Bitwise logical exclusive OR
12668 @cindex bitwise logical exclusive or
12669 @cindex logical exclusive or, bitwise
12672 @item @emph{Description}:
12673 Bitwise logical exclusive or.
12675 This intrinsic routine is provided for backwards compatibility with
12676 GNU Fortran 77. For integer arguments, programmers should consider
12677 the use of the @ref{IEOR} intrinsic and for logical arguments the
12678 @code{.NEQV.} operator, which are both defined by the Fortran standard.
12680 @item @emph{Standard}:
12683 @item @emph{Class}:
12686 @item @emph{Syntax}:
12687 @code{RESULT = XOR(I, J)}
12689 @item @emph{Arguments}:
12690 @multitable @columnfractions .15 .70
12691 @item @var{I} @tab The type shall be either a scalar @code{INTEGER}
12692 type or a scalar @code{LOGICAL} type.
12693 @item @var{J} @tab The type shall be the same as the type of @var{I}.
12696 @item @emph{Return value}:
12697 The return type is either a scalar @code{INTEGER} or a scalar
12698 @code{LOGICAL}. If the kind type parameters differ, then the
12699 smaller kind type is implicitly converted to larger kind, and the
12700 return has the larger kind.
12702 @item @emph{Example}:
12705 LOGICAL :: T = .TRUE., F = .FALSE.
12707 DATA a / Z'F' /, b / Z'3' /
12709 WRITE (*,*) XOR(T, T), XOR(T, F), XOR(F, T), XOR(F, F)
12710 WRITE (*,*) XOR(a, b)
12714 @item @emph{See also}:
12715 Fortran 95 elemental function: @ref{IEOR}
12720 @node Intrinsic Modules
12721 @chapter Intrinsic Modules
12722 @cindex intrinsic Modules
12725 * ISO_FORTRAN_ENV::
12727 * OpenMP Modules OMP_LIB and OMP_LIB_KINDS::
12730 @node ISO_FORTRAN_ENV
12731 @section @code{ISO_FORTRAN_ENV}
12733 @item @emph{Standard}:
12734 Fortran 2003 and later, except when otherwise noted
12737 The @code{ISO_FORTRAN_ENV} module provides the following scalar default-integer
12741 @item @code{ATOMIC_INT_KIND}:
12742 Default-kind integer constant to be used as kind parameter when defining
12743 integer variables used in atomic operations. (Fortran 2008 or later.)
12745 @item @code{ATOMIC_LOGICAL_KIND}:
12746 Default-kind integer constant to be used as kind parameter when defining
12747 logical variables used in atomic operations. (Fortran 2008 or later.)
12749 @item @code{CHARACTER_KINDS}:
12750 Default-kind integer constant array of rank one containing the supported kind
12751 parameters of the @code{CHARACTER} type. (Fortran 2008 or later.)
12753 @item @code{CHARACTER_STORAGE_SIZE}:
12754 Size in bits of the character storage unit.
12756 @item @code{ERROR_UNIT}:
12757 Identifies the preconnected unit used for error reporting.
12759 @item @code{FILE_STORAGE_SIZE}:
12760 Size in bits of the file-storage unit.
12762 @item @code{INPUT_UNIT}:
12763 Identifies the preconnected unit identified by the asterisk
12764 (@code{*}) in @code{READ} statement.
12766 @item @code{INT8}, @code{INT16}, @code{INT32}, @code{INT64}:
12767 Kind type parameters to specify an INTEGER type with a storage
12768 size of 16, 32, and 64 bits. It is negative if a target platform
12769 does not support the particular kind. (Fortran 2008 or later.)
12771 @item @code{INTEGER_KINDS}:
12772 Default-kind integer constant array of rank one containing the supported kind
12773 parameters of the @code{INTEGER} type. (Fortran 2008 or later.)
12775 @item @code{IOSTAT_END}:
12776 The value assigned to the variable passed to the @code{IOSTAT=} specifier of
12777 an input/output statement if an end-of-file condition occurred.
12779 @item @code{IOSTAT_EOR}:
12780 The value assigned to the variable passed to the @code{IOSTAT=} specifier of
12781 an input/output statement if an end-of-record condition occurred.
12783 @item @code{IOSTAT_INQUIRE_INTERNAL_UNIT}:
12784 Scalar default-integer constant, used by @code{INQUIRE} for the
12785 @code{IOSTAT=} specifier to denote an that a unit number identifies an
12786 internal unit. (Fortran 2008 or later.)
12788 @item @code{NUMERIC_STORAGE_SIZE}:
12789 The size in bits of the numeric storage unit.
12791 @item @code{LOGICAL_KINDS}:
12792 Default-kind integer constant array of rank one containing the supported kind
12793 parameters of the @code{LOGICAL} type. (Fortran 2008 or later.)
12795 @item @code{OUTPUT_UNIT}:
12796 Identifies the preconnected unit identified by the asterisk
12797 (@code{*}) in @code{WRITE} statement.
12799 @item @code{REAL32}, @code{REAL64}, @code{REAL128}:
12800 Kind type parameters to specify a REAL type with a storage
12801 size of 32, 64, and 128 bits. It is negative if a target platform
12802 does not support the particular kind. (Fortran 2008 or later.)
12804 @item @code{REAL_KINDS}:
12805 Default-kind integer constant array of rank one containing the supported kind
12806 parameters of the @code{REAL} type. (Fortran 2008 or later.)
12808 @item @code{STAT_LOCKED}:
12809 Scalar default-integer constant used as STAT= return value by @code{LOCK} to
12810 denote that the lock variable is locked by the executing image. (Fortran 2008
12813 @item @code{STAT_LOCKED_OTHER_IMAGE}:
12814 Scalar default-integer constant used as STAT= return value by @code{UNLOCK} to
12815 denote that the lock variable is locked by another image. (Fortran 2008 or
12818 @item @code{STAT_STOPPED_IMAGE}:
12819 Positive, scalar default-integer constant used as STAT= return value if the
12820 argument in the statement requires synchronisation with an image, which has
12821 initiated the termination of the execution. (Fortran 2008 or later.)
12823 @item @code{STAT_UNLOCKED}:
12824 Scalar default-integer constant used as STAT= return value by @code{UNLOCK} to
12825 denote that the lock variable is unlocked. (Fortran 2008 or later.)
12828 The module also provides the following intrinsic procedures:
12829 @ref{COMPILER_OPTIONS} and @ref{COMPILER_VERSION}.
12833 @node ISO_C_BINDING
12834 @section @code{ISO_C_BINDING}
12836 @item @emph{Standard}:
12837 Fortran 2003 and later, GNU extensions
12840 The following intrinsic procedures are provided by the module; their
12841 definition can be found in the section Intrinsic Procedures of this
12845 @item @code{C_ASSOCIATED}
12846 @item @code{C_F_POINTER}
12847 @item @code{C_F_PROCPOINTER}
12848 @item @code{C_FUNLOC}
12850 @item @code{C_SIZEOF}
12852 @c TODO: Vertical spacing between C_FUNLOC and C_LOC wrong in PDF,
12853 @c don't really know why.
12855 The @code{ISO_C_BINDING} module provides the following named constants of
12856 type default integer, which can be used as KIND type parameters.
12858 In addition to the integer named constants required by the Fortran 2003
12859 standard, GNU Fortran provides as an extension named constants for the
12860 128-bit integer types supported by the C compiler: @code{C_INT128_T,
12861 C_INT_LEAST128_T, C_INT_FAST128_T}.
12863 @multitable @columnfractions .15 .35 .35 .35
12864 @item Fortran Type @tab Named constant @tab C type @tab Extension
12865 @item @code{INTEGER}@tab @code{C_INT} @tab @code{int}
12866 @item @code{INTEGER}@tab @code{C_SHORT} @tab @code{short int}
12867 @item @code{INTEGER}@tab @code{C_LONG} @tab @code{long int}
12868 @item @code{INTEGER}@tab @code{C_LONG_LONG} @tab @code{long long int}
12869 @item @code{INTEGER}@tab @code{C_SIGNED_CHAR} @tab @code{signed char}/@code{unsigned char}
12870 @item @code{INTEGER}@tab @code{C_SIZE_T} @tab @code{size_t}
12871 @item @code{INTEGER}@tab @code{C_INT8_T} @tab @code{int8_t}
12872 @item @code{INTEGER}@tab @code{C_INT16_T} @tab @code{int16_t}
12873 @item @code{INTEGER}@tab @code{C_INT32_T} @tab @code{int32_t}
12874 @item @code{INTEGER}@tab @code{C_INT64_T} @tab @code{int64_t}
12875 @item @code{INTEGER}@tab @code{C_INT128_T} @tab @code{int128_t} @tab Ext.
12876 @item @code{INTEGER}@tab @code{C_INT_LEAST8_T} @tab @code{int_least8_t}
12877 @item @code{INTEGER}@tab @code{C_INT_LEAST16_T} @tab @code{int_least16_t}
12878 @item @code{INTEGER}@tab @code{C_INT_LEAST32_T} @tab @code{int_least32_t}
12879 @item @code{INTEGER}@tab @code{C_INT_LEAST64_T} @tab @code{int_least64_t}
12880 @item @code{INTEGER}@tab @code{C_INT_LEAST128_T}@tab @code{int_least128_t} @tab Ext.
12881 @item @code{INTEGER}@tab @code{C_INT_FAST8_T} @tab @code{int_fast8_t}
12882 @item @code{INTEGER}@tab @code{C_INT_FAST16_T} @tab @code{int_fast16_t}
12883 @item @code{INTEGER}@tab @code{C_INT_FAST32_T} @tab @code{int_fast32_t}
12884 @item @code{INTEGER}@tab @code{C_INT_FAST64_T} @tab @code{int_fast64_t}
12885 @item @code{INTEGER}@tab @code{C_INT_FAST128_T} @tab @code{int_fast128_t} @tab Ext.
12886 @item @code{INTEGER}@tab @code{C_INTMAX_T} @tab @code{intmax_t}
12887 @item @code{INTEGER}@tab @code{C_INTPTR_T} @tab @code{intptr_t}
12888 @item @code{REAL} @tab @code{C_FLOAT} @tab @code{float}
12889 @item @code{REAL} @tab @code{C_DOUBLE} @tab @code{double}
12890 @item @code{REAL} @tab @code{C_LONG_DOUBLE} @tab @code{long double}
12891 @item @code{COMPLEX}@tab @code{C_FLOAT_COMPLEX} @tab @code{float _Complex}
12892 @item @code{COMPLEX}@tab @code{C_DOUBLE_COMPLEX}@tab @code{double _Complex}
12893 @item @code{COMPLEX}@tab @code{C_LONG_DOUBLE_COMPLEX}@tab @code{long double _Complex}
12894 @item @code{LOGICAL}@tab @code{C_BOOL} @tab @code{_Bool}
12895 @item @code{CHARACTER}@tab @code{C_CHAR} @tab @code{char}
12898 Additionally, the following parameters of type @code{CHARACTER(KIND=C_CHAR)}
12901 @multitable @columnfractions .20 .45 .15
12902 @item Name @tab C definition @tab Value
12903 @item @code{C_NULL_CHAR} @tab null character @tab @code{'\0'}
12904 @item @code{C_ALERT} @tab alert @tab @code{'\a'}
12905 @item @code{C_BACKSPACE} @tab backspace @tab @code{'\b'}
12906 @item @code{C_FORM_FEED} @tab form feed @tab @code{'\f'}
12907 @item @code{C_NEW_LINE} @tab new line @tab @code{'\n'}
12908 @item @code{C_CARRIAGE_RETURN} @tab carriage return @tab @code{'\r'}
12909 @item @code{C_HORIZONTAL_TAB} @tab horizontal tab @tab @code{'\t'}
12910 @item @code{C_VERTICAL_TAB} @tab vertical tab @tab @code{'\v'}
12913 Moreover, the following two named constants are defined:
12915 @multitable @columnfractions .20 .80
12916 @item Name @tab Type
12917 @item @code{C_NULL_PTR} @tab @code{C_PTR}
12918 @item @code{C_NULL_FUNPTR} @tab @code{C_FUNPTR}
12921 Both are equivalent to the value @code{NULL} in C.
12923 @node OpenMP Modules OMP_LIB and OMP_LIB_KINDS
12924 @section OpenMP Modules @code{OMP_LIB} and @code{OMP_LIB_KINDS}
12926 @item @emph{Standard}:
12927 OpenMP Application Program Interface v3.0
12931 The OpenMP Fortran runtime library routines are provided both in
12932 a form of two Fortran 90 modules, named @code{OMP_LIB} and
12933 @code{OMP_LIB_KINDS}, and in a form of a Fortran @code{include} file named
12934 @file{omp_lib.h}. The procedures provided by @code{OMP_LIB} can be found
12935 in the @ref{Top,,Introduction,libgomp,GNU OpenMP runtime library} manual,
12936 the named constants defined in the modules are listed
12939 For details refer to the actual
12940 @uref{http://www.openmp.org/mp-documents/spec30.pdf,
12941 OpenMP Application Program Interface v3.0}.
12943 @code{OMP_LIB_KINDS} provides the following scalar default-integer
12947 @item @code{omp_integer_kind}
12948 @item @code{omp_logical_kind}
12949 @item @code{omp_lock_kind}
12950 @item @code{omp_nest_lock_kind}
12951 @item @code{omp_sched_kind}
12954 @code{OMP_LIB} provides the scalar default-integer
12955 named constant @code{openmp_version} with a value of the form
12956 @var{yyyymm}, where @code{yyyy} is the year and @var{mm} the month
12957 of the OpenMP version; for OpenMP v3.0 the value is @code{200805}.
12959 And the following scalar integer named constants of the
12960 kind @code{omp_sched_kind}:
12963 @item @code{omp_sched_static}
12964 @item @code{omp_sched_dynamic}
12965 @item @code{omp_sched_guided}
12966 @item @code{omp_sched_auto}