2 Copyright (C) 2005, 2006, 2007, 2008, 2009, 2010, 2012
3 Free Software Foundation, Inc.
4 This is part of the GNU Fortran manual.
5 For copying conditions, see the file gfortran.texi.
7 Permission is granted to copy, distribute and/or modify this document
8 under the terms of the GNU Free Documentation License, Version 1.3 or
9 any later version published by the Free Software Foundation; with the
10 Invariant Sections being ``Funding Free Software'', the Front-Cover
11 Texts being (a) (see below), and with the Back-Cover Texts being (b)
12 (see below). A copy of the license is included in the gfdl(7) man page.
15 Some basic guidelines for editing this document:
17 (1) The intrinsic procedures are to be listed in alphabetical order.
18 (2) The generic name is to be used.
19 (3) The specific names are included in the function index and in a
20 table at the end of the node (See ABS entry).
21 (4) Try to maintain the same style for each entry.
27 \gdef\acos{\mathop{\rm acos}\nolimits}
28 \gdef\asin{\mathop{\rm asin}\nolimits}
29 \gdef\atan{\mathop{\rm atan}\nolimits}
30 \gdef\acosh{\mathop{\rm acosh}\nolimits}
31 \gdef\asinh{\mathop{\rm asinh}\nolimits}
32 \gdef\atanh{\mathop{\rm atanh}\nolimits}
36 @node Intrinsic Procedures
37 @chapter Intrinsic Procedures
38 @cindex intrinsic procedures
41 * Introduction: Introduction to Intrinsics
42 * @code{ABORT}: ABORT, Abort the program
43 * @code{ABS}: ABS, Absolute value
44 * @code{ACCESS}: ACCESS, Checks file access modes
45 * @code{ACHAR}: ACHAR, Character in @acronym{ASCII} collating sequence
46 * @code{ACOS}: ACOS, Arccosine function
47 * @code{ACOSH}: ACOSH, Inverse hyperbolic cosine function
48 * @code{ADJUSTL}: ADJUSTL, Left adjust a string
49 * @code{ADJUSTR}: ADJUSTR, Right adjust a string
50 * @code{AIMAG}: AIMAG, Imaginary part of complex number
51 * @code{AINT}: AINT, Truncate to a whole number
52 * @code{ALARM}: ALARM, Set an alarm clock
53 * @code{ALL}: ALL, Determine if all values are true
54 * @code{ALLOCATED}: ALLOCATED, Status of allocatable entity
55 * @code{AND}: AND, Bitwise logical AND
56 * @code{ANINT}: ANINT, Nearest whole number
57 * @code{ANY}: ANY, Determine if any values are true
58 * @code{ASIN}: ASIN, Arcsine function
59 * @code{ASINH}: ASINH, Inverse hyperbolic sine function
60 * @code{ASSOCIATED}: ASSOCIATED, Status of a pointer or pointer/target pair
61 * @code{ATAN}: ATAN, Arctangent function
62 * @code{ATAN2}: ATAN2, Arctangent function
63 * @code{ATANH}: ATANH, Inverse hyperbolic tangent function
64 * @code{ATOMIC_DEFINE}: ATOMIC_DEFINE, Setting a variable atomically
65 * @code{ATOMIC_REF}: ATOMIC_REF, Obtaining the value of a variable atomically
66 * @code{BESSEL_J0}: BESSEL_J0, Bessel function of the first kind of order 0
67 * @code{BESSEL_J1}: BESSEL_J1, Bessel function of the first kind of order 1
68 * @code{BESSEL_JN}: BESSEL_JN, Bessel function of the first kind
69 * @code{BESSEL_Y0}: BESSEL_Y0, Bessel function of the second kind of order 0
70 * @code{BESSEL_Y1}: BESSEL_Y1, Bessel function of the second kind of order 1
71 * @code{BESSEL_YN}: BESSEL_YN, Bessel function of the second kind
72 * @code{BGE}: BGE, Bitwise greater than or equal to
73 * @code{BGT}: BGT, Bitwise greater than
74 * @code{BIT_SIZE}: BIT_SIZE, Bit size inquiry function
75 * @code{BLE}: BLE, Bitwise less than or equal to
76 * @code{BLT}: BLT, Bitwise less than
77 * @code{BTEST}: BTEST, Bit test function
78 * @code{C_ASSOCIATED}: C_ASSOCIATED, Status of a C pointer
79 * @code{C_F_POINTER}: C_F_POINTER, Convert C into Fortran pointer
80 * @code{C_F_PROCPOINTER}: C_F_PROCPOINTER, Convert C into Fortran procedure pointer
81 * @code{C_FUNLOC}: C_FUNLOC, Obtain the C address of a procedure
82 * @code{C_LOC}: C_LOC, Obtain the C address of an object
83 * @code{C_SIZEOF}: C_SIZEOF, Size in bytes of an expression
84 * @code{CEILING}: CEILING, Integer ceiling function
85 * @code{CHAR}: CHAR, Integer-to-character conversion function
86 * @code{CHDIR}: CHDIR, Change working directory
87 * @code{CHMOD}: CHMOD, Change access permissions of files
88 * @code{CMPLX}: CMPLX, Complex conversion function
89 * @code{COMMAND_ARGUMENT_COUNT}: COMMAND_ARGUMENT_COUNT, Get number of command line arguments
90 * @code{COMPLEX}: COMPLEX, Complex conversion function
91 * @code{COMPILER_VERSION}: COMPILER_VERSION, Compiler version string
92 * @code{COMPILER_OPTIONS}: COMPILER_OPTIONS, Options passed to the compiler
93 * @code{CONJG}: CONJG, Complex conjugate function
94 * @code{COS}: COS, Cosine function
95 * @code{COSH}: COSH, Hyperbolic cosine function
96 * @code{COUNT}: COUNT, Count occurrences of TRUE in an array
97 * @code{CPU_TIME}: CPU_TIME, CPU time subroutine
98 * @code{CSHIFT}: CSHIFT, Circular shift elements of an array
99 * @code{CTIME}: CTIME, Subroutine (or function) to convert a time into a string
100 * @code{DATE_AND_TIME}: DATE_AND_TIME, Date and time subroutine
101 * @code{DBLE}: DBLE, Double precision conversion function
102 * @code{DCMPLX}: DCMPLX, Double complex conversion function
103 * @code{DIGITS}: DIGITS, Significant digits function
104 * @code{DIM}: DIM, Positive difference
105 * @code{DOT_PRODUCT}: DOT_PRODUCT, Dot product function
106 * @code{DPROD}: DPROD, Double product function
107 * @code{DREAL}: DREAL, Double real part function
108 * @code{DSHIFTL}: DSHIFTL, Combined left shift
109 * @code{DSHIFTR}: DSHIFTR, Combined right shift
110 * @code{DTIME}: DTIME, Execution time subroutine (or function)
111 * @code{EOSHIFT}: EOSHIFT, End-off shift elements of an array
112 * @code{EPSILON}: EPSILON, Epsilon function
113 * @code{ERF}: ERF, Error function
114 * @code{ERFC}: ERFC, Complementary error function
115 * @code{ERFC_SCALED}: ERFC_SCALED, Exponentially-scaled complementary error function
116 * @code{ETIME}: ETIME, Execution time subroutine (or function)
117 * @code{EXECUTE_COMMAND_LINE}: EXECUTE_COMMAND_LINE, Execute a shell command
118 * @code{EXIT}: EXIT, Exit the program with status.
119 * @code{EXP}: EXP, Exponential function
120 * @code{EXPONENT}: EXPONENT, Exponent function
121 * @code{EXTENDS_TYPE_OF}: EXTENDS_TYPE_OF, Query dynamic type for extension
122 * @code{FDATE}: FDATE, Subroutine (or function) to get the current time as a string
123 * @code{FGET}: FGET, Read a single character in stream mode from stdin
124 * @code{FGETC}: FGETC, Read a single character in stream mode
125 * @code{FLOOR}: FLOOR, Integer floor function
126 * @code{FLUSH}: FLUSH, Flush I/O unit(s)
127 * @code{FNUM}: FNUM, File number function
128 * @code{FPUT}: FPUT, Write a single character in stream mode to stdout
129 * @code{FPUTC}: FPUTC, Write a single character in stream mode
130 * @code{FRACTION}: FRACTION, Fractional part of the model representation
131 * @code{FREE}: FREE, Memory de-allocation subroutine
132 * @code{FSEEK}: FSEEK, Low level file positioning subroutine
133 * @code{FSTAT}: FSTAT, Get file status
134 * @code{FTELL}: FTELL, Current stream position
135 * @code{GAMMA}: GAMMA, Gamma function
136 * @code{GERROR}: GERROR, Get last system error message
137 * @code{GETARG}: GETARG, Get command line arguments
138 * @code{GET_COMMAND}: GET_COMMAND, Get the entire command line
139 * @code{GET_COMMAND_ARGUMENT}: GET_COMMAND_ARGUMENT, Get command line arguments
140 * @code{GETCWD}: GETCWD, Get current working directory
141 * @code{GETENV}: GETENV, Get an environmental variable
142 * @code{GET_ENVIRONMENT_VARIABLE}: GET_ENVIRONMENT_VARIABLE, Get an environmental variable
143 * @code{GETGID}: GETGID, Group ID function
144 * @code{GETLOG}: GETLOG, Get login name
145 * @code{GETPID}: GETPID, Process ID function
146 * @code{GETUID}: GETUID, User ID function
147 * @code{GMTIME}: GMTIME, Convert time to GMT info
148 * @code{HOSTNM}: HOSTNM, Get system host name
149 * @code{HUGE}: HUGE, Largest number of a kind
150 * @code{HYPOT}: HYPOT, Euclidean distance function
151 * @code{IACHAR}: IACHAR, Code in @acronym{ASCII} collating sequence
152 * @code{IALL}: IALL, Bitwise AND of array elements
153 * @code{IAND}: IAND, Bitwise logical and
154 * @code{IANY}: IANY, Bitwise OR of array elements
155 * @code{IARGC}: IARGC, Get the number of command line arguments
156 * @code{IBCLR}: IBCLR, Clear bit
157 * @code{IBITS}: IBITS, Bit extraction
158 * @code{IBSET}: IBSET, Set bit
159 * @code{ICHAR}: ICHAR, Character-to-integer conversion function
160 * @code{IDATE}: IDATE, Current local time (day/month/year)
161 * @code{IEOR}: IEOR, Bitwise logical exclusive or
162 * @code{IERRNO}: IERRNO, Function to get the last system error number
163 * @code{IMAGE_INDEX}: IMAGE_INDEX, Cosubscript to image index conversion
164 * @code{INDEX}: INDEX intrinsic, Position of a substring within a string
165 * @code{INT}: INT, Convert to integer type
166 * @code{INT2}: INT2, Convert to 16-bit integer type
167 * @code{INT8}: INT8, Convert to 64-bit integer type
168 * @code{IOR}: IOR, Bitwise logical or
169 * @code{IPARITY}: IPARITY, Bitwise XOR of array elements
170 * @code{IRAND}: IRAND, Integer pseudo-random number
171 * @code{IS_IOSTAT_END}: IS_IOSTAT_END, Test for end-of-file value
172 * @code{IS_IOSTAT_EOR}: IS_IOSTAT_EOR, Test for end-of-record value
173 * @code{ISATTY}: ISATTY, Whether a unit is a terminal device
174 * @code{ISHFT}: ISHFT, Shift bits
175 * @code{ISHFTC}: ISHFTC, Shift bits circularly
176 * @code{ISNAN}: ISNAN, Tests for a NaN
177 * @code{ITIME}: ITIME, Current local time (hour/minutes/seconds)
178 * @code{KILL}: KILL, Send a signal to a process
179 * @code{KIND}: KIND, Kind of an entity
180 * @code{LBOUND}: LBOUND, Lower dimension bounds of an array
181 * @code{LCOBOUND}: LCOBOUND, Lower codimension bounds of an array
182 * @code{LEADZ}: LEADZ, Number of leading zero bits of an integer
183 * @code{LEN}: LEN, Length of a character entity
184 * @code{LEN_TRIM}: LEN_TRIM, Length of a character entity without trailing blank characters
185 * @code{LGE}: LGE, Lexical greater than or equal
186 * @code{LGT}: LGT, Lexical greater than
187 * @code{LINK}: LINK, Create a hard link
188 * @code{LLE}: LLE, Lexical less than or equal
189 * @code{LLT}: LLT, Lexical less than
190 * @code{LNBLNK}: LNBLNK, Index of the last non-blank character in a string
191 * @code{LOC}: LOC, Returns the address of a variable
192 * @code{LOG}: LOG, Logarithm function
193 * @code{LOG10}: LOG10, Base 10 logarithm function
194 * @code{LOG_GAMMA}: LOG_GAMMA, Logarithm of the Gamma function
195 * @code{LOGICAL}: LOGICAL, Convert to logical type
196 * @code{LONG}: LONG, Convert to integer type
197 * @code{LSHIFT}: LSHIFT, Left shift bits
198 * @code{LSTAT}: LSTAT, Get file status
199 * @code{LTIME}: LTIME, Convert time to local time info
200 * @code{MALLOC}: MALLOC, Dynamic memory allocation function
201 * @code{MASKL}: MASKL, Left justified mask
202 * @code{MASKR}: MASKR, Right justified mask
203 * @code{MATMUL}: MATMUL, matrix multiplication
204 * @code{MAX}: MAX, Maximum value of an argument list
205 * @code{MAXEXPONENT}: MAXEXPONENT, Maximum exponent of a real kind
206 * @code{MAXLOC}: MAXLOC, Location of the maximum value within an array
207 * @code{MAXVAL}: MAXVAL, Maximum value of an array
208 * @code{MCLOCK}: MCLOCK, Time function
209 * @code{MCLOCK8}: MCLOCK8, Time function (64-bit)
210 * @code{MERGE}: MERGE, Merge arrays
211 * @code{MERGE_BITS}: MERGE_BITS, Merge of bits under mask
212 * @code{MIN}: MIN, Minimum value of an argument list
213 * @code{MINEXPONENT}: MINEXPONENT, Minimum exponent of a real kind
214 * @code{MINLOC}: MINLOC, Location of the minimum value within an array
215 * @code{MINVAL}: MINVAL, Minimum value of an array
216 * @code{MOD}: MOD, Remainder function
217 * @code{MODULO}: MODULO, Modulo function
218 * @code{MOVE_ALLOC}: MOVE_ALLOC, Move allocation from one object to another
219 * @code{MVBITS}: MVBITS, Move bits from one integer to another
220 * @code{NEAREST}: NEAREST, Nearest representable number
221 * @code{NEW_LINE}: NEW_LINE, New line character
222 * @code{NINT}: NINT, Nearest whole number
223 * @code{NORM2}: NORM2, Euclidean vector norm
224 * @code{NOT}: NOT, Logical negation
225 * @code{NULL}: NULL, Function that returns an disassociated pointer
226 * @code{NUM_IMAGES}: NUM_IMAGES, Number of images
227 * @code{OR}: OR, Bitwise logical OR
228 * @code{PACK}: PACK, Pack an array into an array of rank one
229 * @code{PARITY}: PARITY, Reduction with exclusive OR
230 * @code{PERROR}: PERROR, Print system error message
231 * @code{POPCNT}: POPCNT, Number of bits set
232 * @code{POPPAR}: POPPAR, Parity of the number of bits set
233 * @code{PRECISION}: PRECISION, Decimal precision of a real kind
234 * @code{PRESENT}: PRESENT, Determine whether an optional dummy argument is specified
235 * @code{PRODUCT}: PRODUCT, Product of array elements
236 * @code{RADIX}: RADIX, Base of a data model
237 * @code{RANDOM_NUMBER}: RANDOM_NUMBER, Pseudo-random number
238 * @code{RANDOM_SEED}: RANDOM_SEED, Initialize a pseudo-random number sequence
239 * @code{RAND}: RAND, Real pseudo-random number
240 * @code{RANGE}: RANGE, Decimal exponent range
241 * @code{RANK} : RANK, Rank of a data object
242 * @code{RAN}: RAN, Real pseudo-random number
243 * @code{REAL}: REAL, Convert to real type
244 * @code{RENAME}: RENAME, Rename a file
245 * @code{REPEAT}: REPEAT, Repeated string concatenation
246 * @code{RESHAPE}: RESHAPE, Function to reshape an array
247 * @code{RRSPACING}: RRSPACING, Reciprocal of the relative spacing
248 * @code{RSHIFT}: RSHIFT, Right shift bits
249 * @code{SAME_TYPE_AS}: SAME_TYPE_AS, Query dynamic types for equality
250 * @code{SCALE}: SCALE, Scale a real value
251 * @code{SCAN}: SCAN, Scan a string for the presence of a set of characters
252 * @code{SECNDS}: SECNDS, Time function
253 * @code{SECOND}: SECOND, CPU time function
254 * @code{SELECTED_CHAR_KIND}: SELECTED_CHAR_KIND, Choose character kind
255 * @code{SELECTED_INT_KIND}: SELECTED_INT_KIND, Choose integer kind
256 * @code{SELECTED_REAL_KIND}: SELECTED_REAL_KIND, Choose real kind
257 * @code{SET_EXPONENT}: SET_EXPONENT, Set the exponent of the model
258 * @code{SHAPE}: SHAPE, Determine the shape of an array
259 * @code{SHIFTA}: SHIFTA, Right shift with fill
260 * @code{SHIFTL}: SHIFTL, Left shift
261 * @code{SHIFTR}: SHIFTR, Right shift
262 * @code{SIGN}: SIGN, Sign copying function
263 * @code{SIGNAL}: SIGNAL, Signal handling subroutine (or function)
264 * @code{SIN}: SIN, Sine function
265 * @code{SINH}: SINH, Hyperbolic sine function
266 * @code{SIZE}: SIZE, Function to determine the size of an array
267 * @code{SIZEOF}: SIZEOF, Determine the size in bytes of an expression
268 * @code{SLEEP}: SLEEP, Sleep for the specified number of seconds
269 * @code{SPACING}: SPACING, Smallest distance between two numbers of a given type
270 * @code{SPREAD}: SPREAD, Add a dimension to an array
271 * @code{SQRT}: SQRT, Square-root function
272 * @code{SRAND}: SRAND, Reinitialize the random number generator
273 * @code{STAT}: STAT, Get file status
274 * @code{STORAGE_SIZE}: STORAGE_SIZE, Storage size in bits
275 * @code{SUM}: SUM, Sum of array elements
276 * @code{SYMLNK}: SYMLNK, Create a symbolic link
277 * @code{SYSTEM}: SYSTEM, Execute a shell command
278 * @code{SYSTEM_CLOCK}: SYSTEM_CLOCK, Time function
279 * @code{TAN}: TAN, Tangent function
280 * @code{TANH}: TANH, Hyperbolic tangent function
281 * @code{THIS_IMAGE}: THIS_IMAGE, Cosubscript index of this image
282 * @code{TIME}: TIME, Time function
283 * @code{TIME8}: TIME8, Time function (64-bit)
284 * @code{TINY}: TINY, Smallest positive number of a real kind
285 * @code{TRAILZ}: TRAILZ, Number of trailing zero bits of an integer
286 * @code{TRANSFER}: TRANSFER, Transfer bit patterns
287 * @code{TRANSPOSE}: TRANSPOSE, Transpose an array of rank two
288 * @code{TRIM}: TRIM, Remove trailing blank characters of a string
289 * @code{TTYNAM}: TTYNAM, Get the name of a terminal device.
290 * @code{UBOUND}: UBOUND, Upper dimension bounds of an array
291 * @code{UCOBOUND}: UCOBOUND, Upper codimension bounds of an array
292 * @code{UMASK}: UMASK, Set the file creation mask
293 * @code{UNLINK}: UNLINK, Remove a file from the file system
294 * @code{UNPACK}: UNPACK, Unpack an array of rank one into an array
295 * @code{VERIFY}: VERIFY, Scan a string for the absence of a set of characters
296 * @code{XOR}: XOR, Bitwise logical exclusive or
299 @node Introduction to Intrinsics
300 @section Introduction to intrinsic procedures
302 The intrinsic procedures provided by GNU Fortran include all of the
303 intrinsic procedures required by the Fortran 95 standard, a set of
304 intrinsic procedures for backwards compatibility with G77, and a
305 selection of intrinsic procedures from the Fortran 2003 and Fortran 2008
306 standards. Any conflict between a description here and a description in
307 either the Fortran 95 standard, the Fortran 2003 standard or the Fortran
308 2008 standard is unintentional, and the standard(s) should be considered
311 The enumeration of the @code{KIND} type parameter is processor defined in
312 the Fortran 95 standard. GNU Fortran defines the default integer type and
313 default real type by @code{INTEGER(KIND=4)} and @code{REAL(KIND=4)},
314 respectively. The standard mandates that both data types shall have
315 another kind, which have more precision. On typical target architectures
316 supported by @command{gfortran}, this kind type parameter is @code{KIND=8}.
317 Hence, @code{REAL(KIND=8)} and @code{DOUBLE PRECISION} are equivalent.
318 In the description of generic intrinsic procedures, the kind type parameter
319 will be specified by @code{KIND=*}, and in the description of specific
320 names for an intrinsic procedure the kind type parameter will be explicitly
321 given (e.g., @code{REAL(KIND=4)} or @code{REAL(KIND=8)}). Finally, for
322 brevity the optional @code{KIND=} syntax will be omitted.
324 Many of the intrinsic procedures take one or more optional arguments.
325 This document follows the convention used in the Fortran 95 standard,
326 and denotes such arguments by square brackets.
328 GNU Fortran offers the @option{-std=f95} and @option{-std=gnu} options,
329 which can be used to restrict the set of intrinsic procedures to a
330 given standard. By default, @command{gfortran} sets the @option{-std=gnu}
331 option, and so all intrinsic procedures described here are accepted. There
332 is one caveat. For a select group of intrinsic procedures, @command{g77}
333 implemented both a function and a subroutine. Both classes
334 have been implemented in @command{gfortran} for backwards compatibility
335 with @command{g77}. It is noted here that these functions and subroutines
336 cannot be intermixed in a given subprogram. In the descriptions that follow,
337 the applicable standard for each intrinsic procedure is noted.
342 @section @code{ABORT} --- Abort the program
344 @cindex program termination, with core dump
345 @cindex terminate program, with core dump
349 @item @emph{Description}:
350 @code{ABORT} causes immediate termination of the program. On operating
351 systems that support a core dump, @code{ABORT} will produce a core dump.
353 @item @emph{Standard}:
362 @item @emph{Return value}:
365 @item @emph{Example}:
368 integer :: i = 1, j = 2
369 if (i /= j) call abort
370 end program test_abort
373 @item @emph{See also}:
374 @ref{EXIT}, @ref{KILL}
381 @section @code{ABS} --- Absolute value
388 @cindex absolute value
391 @item @emph{Description}:
392 @code{ABS(A)} computes the absolute value of @code{A}.
394 @item @emph{Standard}:
395 Fortran 77 and later, has overloads that are GNU extensions
401 @code{RESULT = ABS(A)}
403 @item @emph{Arguments}:
404 @multitable @columnfractions .15 .70
405 @item @var{A} @tab The type of the argument shall be an @code{INTEGER},
406 @code{REAL}, or @code{COMPLEX}.
409 @item @emph{Return value}:
410 The return value is of the same type and
411 kind as the argument except the return value is @code{REAL} for a
412 @code{COMPLEX} argument.
414 @item @emph{Example}:
419 complex :: z = (-1.e0,0.e0)
426 @item @emph{Specific names}:
427 @multitable @columnfractions .20 .20 .20 .25
428 @item Name @tab Argument @tab Return type @tab Standard
429 @item @code{ABS(A)} @tab @code{REAL(4) A} @tab @code{REAL(4)} @tab Fortran 77 and later
430 @item @code{CABS(A)} @tab @code{COMPLEX(4) A} @tab @code{REAL(4)} @tab Fortran 77 and later
431 @item @code{DABS(A)} @tab @code{REAL(8) A} @tab @code{REAL(8)} @tab Fortran 77 and later
432 @item @code{IABS(A)} @tab @code{INTEGER(4) A} @tab @code{INTEGER(4)} @tab Fortran 77 and later
433 @item @code{ZABS(A)} @tab @code{COMPLEX(8) A} @tab @code{COMPLEX(8)} @tab GNU extension
434 @item @code{CDABS(A)} @tab @code{COMPLEX(8) A} @tab @code{COMPLEX(8)} @tab GNU extension
441 @section @code{ACCESS} --- Checks file access modes
443 @cindex file system, access mode
446 @item @emph{Description}:
447 @code{ACCESS(NAME, MODE)} checks whether the file @var{NAME}
448 exists, is readable, writable or executable. Except for the
449 executable check, @code{ACCESS} can be replaced by
450 Fortran 95's @code{INQUIRE}.
452 @item @emph{Standard}:
459 @code{RESULT = ACCESS(NAME, MODE)}
461 @item @emph{Arguments}:
462 @multitable @columnfractions .15 .70
463 @item @var{NAME} @tab Scalar @code{CHARACTER} of default kind with the
464 file name. Tailing blank are ignored unless the character @code{achar(0)}
465 is present, then all characters up to and excluding @code{achar(0)} are
467 @item @var{MODE} @tab Scalar @code{CHARACTER} of default kind with the
468 file access mode, may be any concatenation of @code{"r"} (readable),
469 @code{"w"} (writable) and @code{"x"} (executable), or @code{" "} to check
473 @item @emph{Return value}:
474 Returns a scalar @code{INTEGER}, which is @code{0} if the file is
475 accessible in the given mode; otherwise or if an invalid argument
476 has been given for @code{MODE} the value @code{1} is returned.
478 @item @emph{Example}:
482 character(len=*), parameter :: file = 'test.dat'
483 character(len=*), parameter :: file2 = 'test.dat '//achar(0)
484 if(access(file,' ') == 0) print *, trim(file),' is exists'
485 if(access(file,'r') == 0) print *, trim(file),' is readable'
486 if(access(file,'w') == 0) print *, trim(file),' is writable'
487 if(access(file,'x') == 0) print *, trim(file),' is executable'
488 if(access(file2,'rwx') == 0) &
489 print *, trim(file2),' is readable, writable and executable'
490 end program access_test
492 @item @emph{Specific names}:
493 @item @emph{See also}:
500 @section @code{ACHAR} --- Character in @acronym{ASCII} collating sequence
502 @cindex @acronym{ASCII} collating sequence
503 @cindex collating sequence, @acronym{ASCII}
506 @item @emph{Description}:
507 @code{ACHAR(I)} returns the character located at position @code{I}
508 in the @acronym{ASCII} collating sequence.
510 @item @emph{Standard}:
511 Fortran 77 and later, with @var{KIND} argument Fortran 2003 and later
517 @code{RESULT = ACHAR(I [, KIND])}
519 @item @emph{Arguments}:
520 @multitable @columnfractions .15 .70
521 @item @var{I} @tab The type shall be @code{INTEGER}.
522 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
523 expression indicating the kind parameter of the result.
526 @item @emph{Return value}:
527 The return value is of type @code{CHARACTER} with a length of one.
528 If the @var{KIND} argument is present, the return value is of the
529 specified kind and of the default kind otherwise.
531 @item @emph{Example}:
536 end program test_achar
540 See @ref{ICHAR} for a discussion of converting between numerical values
541 and formatted string representations.
543 @item @emph{See also}:
544 @ref{CHAR}, @ref{IACHAR}, @ref{ICHAR}
551 @section @code{ACOS} --- Arccosine function
554 @cindex trigonometric function, cosine, inverse
555 @cindex cosine, inverse
558 @item @emph{Description}:
559 @code{ACOS(X)} computes the arccosine of @var{X} (inverse of @code{COS(X)}).
561 @item @emph{Standard}:
562 Fortran 77 and later, for a complex argument Fortran 2008 or later
568 @code{RESULT = ACOS(X)}
570 @item @emph{Arguments}:
571 @multitable @columnfractions .15 .70
572 @item @var{X} @tab The type shall either be @code{REAL} with a magnitude that is
573 less than or equal to one - or the type shall be @code{COMPLEX}.
576 @item @emph{Return value}:
577 The return value is of the same type and kind as @var{X}.
578 The real part of the result is in radians and lies in the range
579 @math{0 \leq \Re \acos(x) \leq \pi}.
581 @item @emph{Example}:
584 real(8) :: x = 0.866_8
586 end program test_acos
589 @item @emph{Specific names}:
590 @multitable @columnfractions .20 .20 .20 .25
591 @item Name @tab Argument @tab Return type @tab Standard
592 @item @code{ACOS(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab Fortran 77 and later
593 @item @code{DACOS(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab Fortran 77 and later
596 @item @emph{See also}:
597 Inverse function: @ref{COS}
604 @section @code{ACOSH} --- Inverse hyperbolic cosine function
607 @cindex area hyperbolic cosine
608 @cindex inverse hyperbolic cosine
609 @cindex hyperbolic function, cosine, inverse
610 @cindex cosine, hyperbolic, inverse
613 @item @emph{Description}:
614 @code{ACOSH(X)} computes the inverse hyperbolic cosine of @var{X}.
616 @item @emph{Standard}:
617 Fortran 2008 and later
623 @code{RESULT = ACOSH(X)}
625 @item @emph{Arguments}:
626 @multitable @columnfractions .15 .70
627 @item @var{X} @tab The type shall be @code{REAL} or @code{COMPLEX}.
630 @item @emph{Return value}:
631 The return value has the same type and kind as @var{X}. If @var{X} is
632 complex, the imaginary part of the result is in radians and lies between
633 @math{ 0 \leq \Im \acosh(x) \leq \pi}.
635 @item @emph{Example}:
638 REAL(8), DIMENSION(3) :: x = (/ 1.0, 2.0, 3.0 /)
643 @item @emph{Specific names}:
644 @multitable @columnfractions .20 .20 .20 .25
645 @item Name @tab Argument @tab Return type @tab Standard
646 @item @code{DACOSH(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU extension
649 @item @emph{See also}:
650 Inverse function: @ref{COSH}
656 @section @code{ADJUSTL} --- Left adjust a string
658 @cindex string, adjust left
659 @cindex adjust string
662 @item @emph{Description}:
663 @code{ADJUSTL(STRING)} will left adjust a string by removing leading spaces.
664 Spaces are inserted at the end of the string as needed.
666 @item @emph{Standard}:
673 @code{RESULT = ADJUSTL(STRING)}
675 @item @emph{Arguments}:
676 @multitable @columnfractions .15 .70
677 @item @var{STRING} @tab The type shall be @code{CHARACTER}.
680 @item @emph{Return value}:
681 The return value is of type @code{CHARACTER} and of the same kind as
682 @var{STRING} where leading spaces are removed and the same number of
683 spaces are inserted on the end of @var{STRING}.
685 @item @emph{Example}:
688 character(len=20) :: str = ' gfortran'
691 end program test_adjustl
694 @item @emph{See also}:
695 @ref{ADJUSTR}, @ref{TRIM}
701 @section @code{ADJUSTR} --- Right adjust a string
703 @cindex string, adjust right
704 @cindex adjust string
707 @item @emph{Description}:
708 @code{ADJUSTR(STRING)} will right adjust a string by removing trailing spaces.
709 Spaces are inserted at the start of the string as needed.
711 @item @emph{Standard}:
718 @code{RESULT = ADJUSTR(STRING)}
720 @item @emph{Arguments}:
721 @multitable @columnfractions .15 .70
722 @item @var{STR} @tab The type shall be @code{CHARACTER}.
725 @item @emph{Return value}:
726 The return value is of type @code{CHARACTER} and of the same kind as
727 @var{STRING} where trailing spaces are removed and the same number of
728 spaces are inserted at the start of @var{STRING}.
730 @item @emph{Example}:
733 character(len=20) :: str = 'gfortran'
736 end program test_adjustr
739 @item @emph{See also}:
740 @ref{ADJUSTL}, @ref{TRIM}
746 @section @code{AIMAG} --- Imaginary part of complex number
751 @cindex complex numbers, imaginary part
754 @item @emph{Description}:
755 @code{AIMAG(Z)} yields the imaginary part of complex argument @code{Z}.
756 The @code{IMAG(Z)} and @code{IMAGPART(Z)} intrinsic functions are provided
757 for compatibility with @command{g77}, and their use in new code is
758 strongly discouraged.
760 @item @emph{Standard}:
761 Fortran 77 and later, has overloads that are GNU extensions
767 @code{RESULT = AIMAG(Z)}
769 @item @emph{Arguments}:
770 @multitable @columnfractions .15 .70
771 @item @var{Z} @tab The type of the argument shall be @code{COMPLEX}.
774 @item @emph{Return value}:
775 The return value is of type @code{REAL} with the
776 kind type parameter of the argument.
778 @item @emph{Example}:
783 z4 = cmplx(1.e0_4, 0.e0_4)
784 z8 = cmplx(0.e0_8, 1.e0_8)
785 print *, aimag(z4), dimag(z8)
786 end program test_aimag
789 @item @emph{Specific names}:
790 @multitable @columnfractions .20 .20 .20 .25
791 @item Name @tab Argument @tab Return type @tab Standard
792 @item @code{AIMAG(Z)} @tab @code{COMPLEX Z} @tab @code{REAL} @tab GNU extension
793 @item @code{DIMAG(Z)} @tab @code{COMPLEX(8) Z} @tab @code{REAL(8)} @tab GNU extension
794 @item @code{IMAG(Z)} @tab @code{COMPLEX Z} @tab @code{REAL} @tab GNU extension
795 @item @code{IMAGPART(Z)} @tab @code{COMPLEX Z} @tab @code{REAL} @tab GNU extension
802 @section @code{AINT} --- Truncate to a whole number
806 @cindex rounding, floor
809 @item @emph{Description}:
810 @code{AINT(A [, KIND])} truncates its argument to a whole number.
812 @item @emph{Standard}:
819 @code{RESULT = AINT(A [, KIND])}
821 @item @emph{Arguments}:
822 @multitable @columnfractions .15 .70
823 @item @var{A} @tab The type of the argument shall be @code{REAL}.
824 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
825 expression indicating the kind parameter of the result.
828 @item @emph{Return value}:
829 The return value is of type @code{REAL} with the kind type parameter of the
830 argument if the optional @var{KIND} is absent; otherwise, the kind
831 type parameter will be given by @var{KIND}. If the magnitude of
832 @var{X} is less than one, @code{AINT(X)} returns zero. If the
833 magnitude is equal to or greater than one then it returns the largest
834 whole number that does not exceed its magnitude. The sign is the same
835 as the sign of @var{X}.
837 @item @emph{Example}:
844 print *, aint(x4), dint(x8)
846 end program test_aint
849 @item @emph{Specific names}:
850 @multitable @columnfractions .20 .20 .20 .25
851 @item Name @tab Argument @tab Return type @tab Standard
852 @item @code{AINT(A)} @tab @code{REAL(4) A} @tab @code{REAL(4)} @tab Fortran 77 and later
853 @item @code{DINT(A)} @tab @code{REAL(8) A} @tab @code{REAL(8)} @tab Fortran 77 and later
860 @section @code{ALARM} --- Execute a routine after a given delay
862 @cindex delayed execution
865 @item @emph{Description}:
866 @code{ALARM(SECONDS, HANDLER [, STATUS])} causes external subroutine @var{HANDLER}
867 to be executed after a delay of @var{SECONDS} by using @code{alarm(2)} to
868 set up a signal and @code{signal(2)} to catch it. If @var{STATUS} is
869 supplied, it will be returned with the number of seconds remaining until
870 any previously scheduled alarm was due to be delivered, or zero if there
871 was no previously scheduled alarm.
873 @item @emph{Standard}:
880 @code{CALL ALARM(SECONDS, HANDLER [, STATUS])}
882 @item @emph{Arguments}:
883 @multitable @columnfractions .15 .70
884 @item @var{SECONDS} @tab The type of the argument shall be a scalar
885 @code{INTEGER}. It is @code{INTENT(IN)}.
886 @item @var{HANDLER} @tab Signal handler (@code{INTEGER FUNCTION} or
887 @code{SUBROUTINE}) or dummy/global @code{INTEGER} scalar. The scalar
888 values may be either @code{SIG_IGN=1} to ignore the alarm generated
889 or @code{SIG_DFL=0} to set the default action. It is @code{INTENT(IN)}.
890 @item @var{STATUS} @tab (Optional) @var{STATUS} shall be a scalar
891 variable of the default @code{INTEGER} kind. It is @code{INTENT(OUT)}.
894 @item @emph{Example}:
897 external handler_print
899 call alarm (3, handler_print, i)
902 end program test_alarm
904 This will cause the external routine @var{handler_print} to be called
911 @section @code{ALL} --- All values in @var{MASK} along @var{DIM} are true
913 @cindex array, apply condition
914 @cindex array, condition testing
917 @item @emph{Description}:
918 @code{ALL(MASK [, DIM])} determines if all the values are true in @var{MASK}
919 in the array along dimension @var{DIM}.
921 @item @emph{Standard}:
925 Transformational function
928 @code{RESULT = ALL(MASK [, DIM])}
930 @item @emph{Arguments}:
931 @multitable @columnfractions .15 .70
932 @item @var{MASK} @tab The type of the argument shall be @code{LOGICAL} and
933 it shall not be scalar.
934 @item @var{DIM} @tab (Optional) @var{DIM} shall be a scalar integer
935 with a value that lies between one and the rank of @var{MASK}.
938 @item @emph{Return value}:
939 @code{ALL(MASK)} returns a scalar value of type @code{LOGICAL} where
940 the kind type parameter is the same as the kind type parameter of
941 @var{MASK}. If @var{DIM} is present, then @code{ALL(MASK, DIM)} returns
942 an array with the rank of @var{MASK} minus 1. The shape is determined from
943 the shape of @var{MASK} where the @var{DIM} dimension is elided.
947 @code{ALL(MASK)} is true if all elements of @var{MASK} are true.
948 It also is true if @var{MASK} has zero size; otherwise, it is false.
950 If the rank of @var{MASK} is one, then @code{ALL(MASK,DIM)} is equivalent
951 to @code{ALL(MASK)}. If the rank is greater than one, then @code{ALL(MASK,DIM)}
952 is determined by applying @code{ALL} to the array sections.
955 @item @emph{Example}:
959 l = all((/.true., .true., .true./))
964 integer a(2,3), b(2,3)
968 print *, all(a .eq. b, 1)
969 print *, all(a .eq. b, 2)
970 end subroutine section
978 @section @code{ALLOCATED} --- Status of an allocatable entity
980 @cindex allocation, status
983 @item @emph{Description}:
984 @code{ALLOCATED(ARRAY)} and @code{ALLOCATED(SCALAR)} check the allocation
985 status of @var{ARRAY} and @var{SCALAR}, respectively.
987 @item @emph{Standard}:
988 Fortran 95 and later. Note, the @code{SCALAR=} keyword and allocatable
989 scalar entities are available in Fortran 2003 and later.
995 @multitable @columnfractions .80
996 @item @code{RESULT = ALLOCATED(ARRAY)}
997 @item @code{RESULT = ALLOCATED(SCALAR)}
1000 @item @emph{Arguments}:
1001 @multitable @columnfractions .15 .70
1002 @item @var{ARRAY} @tab The argument shall be an @code{ALLOCATABLE} array.
1003 @item @var{SCALAR} @tab The argument shall be an @code{ALLOCATABLE} scalar.
1006 @item @emph{Return value}:
1007 The return value is a scalar @code{LOGICAL} with the default logical
1008 kind type parameter. If the argument is allocated, then the result is
1009 @code{.TRUE.}; otherwise, it returns @code{.FALSE.}
1011 @item @emph{Example}:
1013 program test_allocated
1015 real(4), allocatable :: x(:)
1016 if (.not. allocated(x)) allocate(x(i))
1017 end program test_allocated
1024 @section @code{AND} --- Bitwise logical AND
1026 @cindex bitwise logical and
1027 @cindex logical and, bitwise
1030 @item @emph{Description}:
1031 Bitwise logical @code{AND}.
1033 This intrinsic routine is provided for backwards compatibility with
1034 GNU Fortran 77. For integer arguments, programmers should consider
1035 the use of the @ref{IAND} intrinsic defined by the Fortran standard.
1037 @item @emph{Standard}:
1043 @item @emph{Syntax}:
1044 @code{RESULT = AND(I, J)}
1046 @item @emph{Arguments}:
1047 @multitable @columnfractions .15 .70
1048 @item @var{I} @tab The type shall be either a scalar @code{INTEGER}
1049 type or a scalar @code{LOGICAL} type.
1050 @item @var{J} @tab The type shall be the same as the type of @var{I}.
1053 @item @emph{Return value}:
1054 The return type is either a scalar @code{INTEGER} or a scalar
1055 @code{LOGICAL}. If the kind type parameters differ, then the
1056 smaller kind type is implicitly converted to larger kind, and the
1057 return has the larger kind.
1059 @item @emph{Example}:
1062 LOGICAL :: T = .TRUE., F = .FALSE.
1064 DATA a / Z'F' /, b / Z'3' /
1066 WRITE (*,*) AND(T, T), AND(T, F), AND(F, T), AND(F, F)
1067 WRITE (*,*) AND(a, b)
1071 @item @emph{See also}:
1072 Fortran 95 elemental function: @ref{IAND}
1078 @section @code{ANINT} --- Nearest whole number
1082 @cindex rounding, ceiling
1085 @item @emph{Description}:
1086 @code{ANINT(A [, KIND])} rounds its argument to the nearest whole number.
1088 @item @emph{Standard}:
1089 Fortran 77 and later
1094 @item @emph{Syntax}:
1095 @code{RESULT = ANINT(A [, KIND])}
1097 @item @emph{Arguments}:
1098 @multitable @columnfractions .15 .70
1099 @item @var{A} @tab The type of the argument shall be @code{REAL}.
1100 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
1101 expression indicating the kind parameter of the result.
1104 @item @emph{Return value}:
1105 The return value is of type real with the kind type parameter of the
1106 argument if the optional @var{KIND} is absent; otherwise, the kind
1107 type parameter will be given by @var{KIND}. If @var{A} is greater than
1108 zero, @code{ANINT(A)} returns @code{AINT(X+0.5)}. If @var{A} is
1109 less than or equal to zero then it returns @code{AINT(X-0.5)}.
1111 @item @emph{Example}:
1118 print *, anint(x4), dnint(x8)
1120 end program test_anint
1123 @item @emph{Specific names}:
1124 @multitable @columnfractions .20 .20 .20 .25
1125 @item Name @tab Argument @tab Return type @tab Standard
1126 @item @code{AINT(A)} @tab @code{REAL(4) A} @tab @code{REAL(4)} @tab Fortran 77 and later
1127 @item @code{DNINT(A)} @tab @code{REAL(8) A} @tab @code{REAL(8)} @tab Fortran 77 and later
1134 @section @code{ANY} --- Any value in @var{MASK} along @var{DIM} is true
1136 @cindex array, apply condition
1137 @cindex array, condition testing
1140 @item @emph{Description}:
1141 @code{ANY(MASK [, DIM])} determines if any of the values in the logical array
1142 @var{MASK} along dimension @var{DIM} are @code{.TRUE.}.
1144 @item @emph{Standard}:
1145 Fortran 95 and later
1148 Transformational function
1150 @item @emph{Syntax}:
1151 @code{RESULT = ANY(MASK [, DIM])}
1153 @item @emph{Arguments}:
1154 @multitable @columnfractions .15 .70
1155 @item @var{MASK} @tab The type of the argument shall be @code{LOGICAL} and
1156 it shall not be scalar.
1157 @item @var{DIM} @tab (Optional) @var{DIM} shall be a scalar integer
1158 with a value that lies between one and the rank of @var{MASK}.
1161 @item @emph{Return value}:
1162 @code{ANY(MASK)} returns a scalar value of type @code{LOGICAL} where
1163 the kind type parameter is the same as the kind type parameter of
1164 @var{MASK}. If @var{DIM} is present, then @code{ANY(MASK, DIM)} returns
1165 an array with the rank of @var{MASK} minus 1. The shape is determined from
1166 the shape of @var{MASK} where the @var{DIM} dimension is elided.
1170 @code{ANY(MASK)} is true if any element of @var{MASK} is true;
1171 otherwise, it is false. It also is false if @var{MASK} has zero size.
1173 If the rank of @var{MASK} is one, then @code{ANY(MASK,DIM)} is equivalent
1174 to @code{ANY(MASK)}. If the rank is greater than one, then @code{ANY(MASK,DIM)}
1175 is determined by applying @code{ANY} to the array sections.
1178 @item @emph{Example}:
1182 l = any((/.true., .true., .true./))
1187 integer a(2,3), b(2,3)
1191 print *, any(a .eq. b, 1)
1192 print *, any(a .eq. b, 2)
1193 end subroutine section
1194 end program test_any
1201 @section @code{ASIN} --- Arcsine function
1204 @cindex trigonometric function, sine, inverse
1205 @cindex sine, inverse
1208 @item @emph{Description}:
1209 @code{ASIN(X)} computes the arcsine of its @var{X} (inverse of @code{SIN(X)}).
1211 @item @emph{Standard}:
1212 Fortran 77 and later, for a complex argument Fortran 2008 or later
1217 @item @emph{Syntax}:
1218 @code{RESULT = ASIN(X)}
1220 @item @emph{Arguments}:
1221 @multitable @columnfractions .15 .70
1222 @item @var{X} @tab The type shall be either @code{REAL} and a magnitude that is
1223 less than or equal to one - or be @code{COMPLEX}.
1226 @item @emph{Return value}:
1227 The return value is of the same type and kind as @var{X}.
1228 The real part of the result is in radians and lies in the range
1229 @math{-\pi/2 \leq \Re \asin(x) \leq \pi/2}.
1231 @item @emph{Example}:
1234 real(8) :: x = 0.866_8
1236 end program test_asin
1239 @item @emph{Specific names}:
1240 @multitable @columnfractions .20 .20 .20 .25
1241 @item Name @tab Argument @tab Return type @tab Standard
1242 @item @code{ASIN(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab Fortran 77 and later
1243 @item @code{DASIN(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab Fortran 77 and later
1246 @item @emph{See also}:
1247 Inverse function: @ref{SIN}
1254 @section @code{ASINH} --- Inverse hyperbolic sine function
1257 @cindex area hyperbolic sine
1258 @cindex inverse hyperbolic sine
1259 @cindex hyperbolic function, sine, inverse
1260 @cindex sine, hyperbolic, inverse
1263 @item @emph{Description}:
1264 @code{ASINH(X)} computes the inverse hyperbolic sine of @var{X}.
1266 @item @emph{Standard}:
1267 Fortran 2008 and later
1272 @item @emph{Syntax}:
1273 @code{RESULT = ASINH(X)}
1275 @item @emph{Arguments}:
1276 @multitable @columnfractions .15 .70
1277 @item @var{X} @tab The type shall be @code{REAL} or @code{COMPLEX}.
1280 @item @emph{Return value}:
1281 The return value is of the same type and kind as @var{X}. If @var{X} is
1282 complex, the imaginary part of the result is in radians and lies between
1283 @math{-\pi/2 \leq \Im \asinh(x) \leq \pi/2}.
1285 @item @emph{Example}:
1288 REAL(8), DIMENSION(3) :: x = (/ -1.0, 0.0, 1.0 /)
1289 WRITE (*,*) ASINH(x)
1293 @item @emph{Specific names}:
1294 @multitable @columnfractions .20 .20 .20 .25
1295 @item Name @tab Argument @tab Return type @tab Standard
1296 @item @code{DASINH(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU extension.
1299 @item @emph{See also}:
1300 Inverse function: @ref{SINH}
1306 @section @code{ASSOCIATED} --- Status of a pointer or pointer/target pair
1308 @cindex pointer, status
1309 @cindex association status
1312 @item @emph{Description}:
1313 @code{ASSOCIATED(POINTER [, TARGET])} determines the status of the pointer
1314 @var{POINTER} or if @var{POINTER} is associated with the target @var{TARGET}.
1316 @item @emph{Standard}:
1317 Fortran 95 and later
1322 @item @emph{Syntax}:
1323 @code{RESULT = ASSOCIATED(POINTER [, TARGET])}
1325 @item @emph{Arguments}:
1326 @multitable @columnfractions .15 .70
1327 @item @var{POINTER} @tab @var{POINTER} shall have the @code{POINTER} attribute
1328 and it can be of any type.
1329 @item @var{TARGET} @tab (Optional) @var{TARGET} shall be a pointer or
1330 a target. It must have the same type, kind type parameter, and
1331 array rank as @var{POINTER}.
1333 The association status of neither @var{POINTER} nor @var{TARGET} shall be
1336 @item @emph{Return value}:
1337 @code{ASSOCIATED(POINTER)} returns a scalar value of type @code{LOGICAL(4)}.
1338 There are several cases:
1340 @item (A) When the optional @var{TARGET} is not present then
1341 @code{ASSOCIATED(POINTER)} is true if @var{POINTER} is associated with a target; otherwise, it returns false.
1342 @item (B) If @var{TARGET} is present and a scalar target, the result is true if
1343 @var{TARGET} is not a zero-sized storage sequence and the target associated with @var{POINTER} occupies the same storage units. If @var{POINTER} is
1344 disassociated, the result is false.
1345 @item (C) If @var{TARGET} is present and an array target, the result is true if
1346 @var{TARGET} and @var{POINTER} have the same shape, are not zero-sized arrays,
1347 are arrays whose elements are not zero-sized storage sequences, and
1348 @var{TARGET} and @var{POINTER} occupy the same storage units in array element
1350 As in case(B), the result is false, if @var{POINTER} is disassociated.
1351 @item (D) If @var{TARGET} is present and an scalar pointer, the result is true
1352 if @var{TARGET} is associated with @var{POINTER}, the target associated with
1353 @var{TARGET} are not zero-sized storage sequences and occupy the same storage
1355 The result is false, if either @var{TARGET} or @var{POINTER} is disassociated.
1356 @item (E) If @var{TARGET} is present and an array pointer, the result is true if
1357 target associated with @var{POINTER} and the target associated with @var{TARGET}
1358 have the same shape, are not zero-sized arrays, are arrays whose elements are
1359 not zero-sized storage sequences, and @var{TARGET} and @var{POINTER} occupy
1360 the same storage units in array element order.
1361 The result is false, if either @var{TARGET} or @var{POINTER} is disassociated.
1364 @item @emph{Example}:
1366 program test_associated
1368 real, target :: tgt(2) = (/1., 2./)
1369 real, pointer :: ptr(:)
1371 if (associated(ptr) .eqv. .false.) call abort
1372 if (associated(ptr,tgt) .eqv. .false.) call abort
1373 end program test_associated
1376 @item @emph{See also}:
1383 @section @code{ATAN} --- Arctangent function
1386 @cindex trigonometric function, tangent, inverse
1387 @cindex tangent, inverse
1390 @item @emph{Description}:
1391 @code{ATAN(X)} computes the arctangent of @var{X}.
1393 @item @emph{Standard}:
1394 Fortran 77 and later, for a complex argument and for two arguments
1395 Fortran 2008 or later
1400 @item @emph{Syntax}:
1401 @multitable @columnfractions .80
1402 @item @code{RESULT = ATAN(X)}
1403 @item @code{RESULT = ATAN(Y, X)}
1406 @item @emph{Arguments}:
1407 @multitable @columnfractions .15 .70
1408 @item @var{X} @tab The type shall be @code{REAL} or @code{COMPLEX};
1409 if @var{Y} is present, @var{X} shall be REAL.
1410 @item @var{Y} shall be of the same type and kind as @var{X}.
1413 @item @emph{Return value}:
1414 The return value is of the same type and kind as @var{X}.
1415 If @var{Y} is present, the result is identical to @code{ATAN2(Y,X)}.
1416 Otherwise, it the arcus tangent of @var{X}, where the real part of
1417 the result is in radians and lies in the range
1418 @math{-\pi/2 \leq \Re \atan(x) \leq \pi/2}.
1420 @item @emph{Example}:
1423 real(8) :: x = 2.866_8
1425 end program test_atan
1428 @item @emph{Specific names}:
1429 @multitable @columnfractions .20 .20 .20 .25
1430 @item Name @tab Argument @tab Return type @tab Standard
1431 @item @code{ATAN(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab Fortran 77 and later
1432 @item @code{DATAN(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab Fortran 77 and later
1435 @item @emph{See also}:
1436 Inverse function: @ref{TAN}
1443 @section @code{ATAN2} --- Arctangent function
1446 @cindex trigonometric function, tangent, inverse
1447 @cindex tangent, inverse
1450 @item @emph{Description}:
1451 @code{ATAN2(Y, X)} computes the principal value of the argument
1452 function of the complex number @math{X + i Y}. This function can
1453 be used to transform from Cartesian into polar coordinates and
1454 allows to determine the angle in the correct quadrant.
1456 @item @emph{Standard}:
1457 Fortran 77 and later
1462 @item @emph{Syntax}:
1463 @code{RESULT = ATAN2(Y, X)}
1465 @item @emph{Arguments}:
1466 @multitable @columnfractions .15 .70
1467 @item @var{Y} @tab The type shall be @code{REAL}.
1468 @item @var{X} @tab The type and kind type parameter shall be the same as @var{Y}.
1469 If @var{Y} is zero, then @var{X} must be nonzero.
1472 @item @emph{Return value}:
1473 The return value has the same type and kind type parameter as @var{Y}. It
1474 is the principal value of the complex number @math{X + i Y}. If @var{X}
1475 is nonzero, then it lies in the range @math{-\pi \le \atan (x) \leq \pi}.
1476 The sign is positive if @var{Y} is positive. If @var{Y} is zero, then
1477 the return value is zero if @var{X} is strictly positive, @math{\pi} if
1478 @var{X} is negative and @var{Y} is positive zero (or the processor does
1479 not handle signed zeros), and @math{-\pi} if @var{X} is negative and
1480 @var{Y} is negative zero. Finally, if @var{X} is zero, then the
1481 magnitude of the result is @math{\pi/2}.
1483 @item @emph{Example}:
1486 real(4) :: x = 1.e0_4, y = 0.5e0_4
1488 end program test_atan2
1491 @item @emph{Specific names}:
1492 @multitable @columnfractions .20 .20 .20 .25
1493 @item Name @tab Argument @tab Return type @tab Standard
1494 @item @code{ATAN2(X, Y)} @tab @code{REAL(4) X, Y} @tab @code{REAL(4)} @tab Fortran 77 and later
1495 @item @code{DATAN2(X, Y)} @tab @code{REAL(8) X, Y} @tab @code{REAL(8)} @tab Fortran 77 and later
1502 @section @code{ATANH} --- Inverse hyperbolic tangent function
1505 @cindex area hyperbolic tangent
1506 @cindex inverse hyperbolic tangent
1507 @cindex hyperbolic function, tangent, inverse
1508 @cindex tangent, hyperbolic, inverse
1511 @item @emph{Description}:
1512 @code{ATANH(X)} computes the inverse hyperbolic tangent of @var{X}.
1514 @item @emph{Standard}:
1515 Fortran 2008 and later
1520 @item @emph{Syntax}:
1521 @code{RESULT = ATANH(X)}
1523 @item @emph{Arguments}:
1524 @multitable @columnfractions .15 .70
1525 @item @var{X} @tab The type shall be @code{REAL} or @code{COMPLEX}.
1528 @item @emph{Return value}:
1529 The return value has same type and kind as @var{X}. If @var{X} is
1530 complex, the imaginary part of the result is in radians and lies between
1531 @math{-\pi/2 \leq \Im \atanh(x) \leq \pi/2}.
1533 @item @emph{Example}:
1536 REAL, DIMENSION(3) :: x = (/ -1.0, 0.0, 1.0 /)
1537 WRITE (*,*) ATANH(x)
1541 @item @emph{Specific names}:
1542 @multitable @columnfractions .20 .20 .20 .25
1543 @item Name @tab Argument @tab Return type @tab Standard
1544 @item @code{DATANH(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU extension
1547 @item @emph{See also}:
1548 Inverse function: @ref{TANH}
1554 @section @code{ATOMIC_DEFINE} --- Setting a variable atomically
1555 @fnindex ATOMIC_DEFINE
1556 @cindex Atomic subroutine, define
1559 @item @emph{Description}:
1560 @code{ATOMIC_DEFINE(ATOM, VALUE)} defines the variable @var{ATOM} with the value
1561 @var{VALUE} atomically.
1563 @item @emph{Standard}:
1564 Fortran 2008 and later
1569 @item @emph{Syntax}:
1570 @code{CALL ATOMIC_DEFINE(ATOM, VALUE)}
1572 @item @emph{Arguments}:
1573 @multitable @columnfractions .15 .70
1574 @item @var{ATOM} @tab Scalar coarray or coindexed variable of either integer
1575 type with @code{ATOMIC_INT_KIND} kind or logical type
1576 with @code{ATOMIC_LOGICAL_KIND} kind.
1577 @item @var{VALURE} @tab Scalar and of the same type as @var{ATOM}. If the kind
1578 is different, the value is converted to the kind of
1582 @item @emph{Example}:
1586 integer(atomic_int_kind) :: atom[*]
1587 call atomic_define (atom[1], this_image())
1591 @item @emph{See also}:
1592 @ref{ATOMIC_REF}, @ref{ISO_FORTRAN_ENV}
1598 @section @code{ATOMIC_REF} --- Obtaining the value of a variable atomically
1600 @cindex Atomic subroutine, reference
1603 @item @emph{Description}:
1604 @code{ATOMIC_DEFINE(ATOM, VALUE)} atomically assigns the value of the
1605 variable @var{ATOM} to @var{VALUE}.
1607 @item @emph{Standard}:
1608 Fortran 2008 and later
1613 @item @emph{Syntax}:
1614 @code{CALL ATOMIC_REF(VALUE, ATOM)}
1616 @item @emph{Arguments}:
1617 @multitable @columnfractions .15 .70
1618 @item @var{VALURE} @tab Scalar and of the same type as @var{ATOM}. If the kind
1619 is different, the value is converted to the kind of
1621 @item @var{ATOM} @tab Scalar coarray or coindexed variable of either integer
1622 type with @code{ATOMIC_INT_KIND} kind or logical type
1623 with @code{ATOMIC_LOGICAL_KIND} kind.
1626 @item @emph{Example}:
1630 logical(atomic_logical_kind) :: atom[*]
1632 call atomic_ref (atom, .false.)
1634 call atomic_ref (atom, val)
1641 @item @emph{See also}:
1642 @ref{ATOMIC_DEFINE}, @ref{ISO_FORTRAN_ENV}
1648 @section @code{BESSEL_J0} --- Bessel function of the first kind of order 0
1652 @cindex Bessel function, first kind
1655 @item @emph{Description}:
1656 @code{BESSEL_J0(X)} computes the Bessel function of the first kind of
1657 order 0 of @var{X}. This function is available under the name
1658 @code{BESJ0} as a GNU extension.
1660 @item @emph{Standard}:
1661 Fortran 2008 and later
1666 @item @emph{Syntax}:
1667 @code{RESULT = BESSEL_J0(X)}
1669 @item @emph{Arguments}:
1670 @multitable @columnfractions .15 .70
1671 @item @var{X} @tab The type shall be @code{REAL}, and it shall be scalar.
1674 @item @emph{Return value}:
1675 The return value is of type @code{REAL} and lies in the
1676 range @math{ - 0.4027... \leq Bessel (0,x) \leq 1}. It has the same
1679 @item @emph{Example}:
1682 real(8) :: x = 0.0_8
1684 end program test_besj0
1687 @item @emph{Specific names}:
1688 @multitable @columnfractions .20 .20 .20 .25
1689 @item Name @tab Argument @tab Return type @tab Standard
1690 @item @code{DBESJ0(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU extension
1697 @section @code{BESSEL_J1} --- Bessel function of the first kind of order 1
1701 @cindex Bessel function, first kind
1704 @item @emph{Description}:
1705 @code{BESSEL_J1(X)} computes the Bessel function of the first kind of
1706 order 1 of @var{X}. This function is available under the name
1707 @code{BESJ1} as a GNU extension.
1709 @item @emph{Standard}:
1715 @item @emph{Syntax}:
1716 @code{RESULT = BESSEL_J1(X)}
1718 @item @emph{Arguments}:
1719 @multitable @columnfractions .15 .70
1720 @item @var{X} @tab The type shall be @code{REAL}, and it shall be scalar.
1723 @item @emph{Return value}:
1724 The return value is of type @code{REAL} and it lies in the
1725 range @math{ - 0.5818... \leq Bessel (0,x) \leq 0.5818 }. It has the same
1728 @item @emph{Example}:
1731 real(8) :: x = 1.0_8
1733 end program test_besj1
1736 @item @emph{Specific names}:
1737 @multitable @columnfractions .20 .20 .20 .25
1738 @item Name @tab Argument @tab Return type @tab Standard
1739 @item @code{DBESJ1(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU extension
1746 @section @code{BESSEL_JN} --- Bessel function of the first kind
1750 @cindex Bessel function, first kind
1753 @item @emph{Description}:
1754 @code{BESSEL_JN(N, X)} computes the Bessel function of the first kind of
1755 order @var{N} of @var{X}. This function is available under the name
1756 @code{BESJN} as a GNU extension. If @var{N} and @var{X} are arrays,
1757 their ranks and shapes shall conform.
1759 @code{BESSEL_JN(N1, N2, X)} returns an array with the Bessel functions
1760 of the first kind of the orders @var{N1} to @var{N2}.
1762 @item @emph{Standard}:
1763 Fortran 2008 and later, negative @var{N} is allowed as GNU extension
1766 Elemental function, except for the transformational function
1767 @code{BESSEL_JN(N1, N2, X)}
1769 @item @emph{Syntax}:
1770 @multitable @columnfractions .80
1771 @item @code{RESULT = BESSEL_JN(N, X)}
1772 @item @code{RESULT = BESSEL_JN(N1, N2, X)}
1775 @item @emph{Arguments}:
1776 @multitable @columnfractions .15 .70
1777 @item @var{N} @tab Shall be a scalar or an array of type @code{INTEGER}.
1778 @item @var{N1} @tab Shall be a non-negative scalar of type @code{INTEGER}.
1779 @item @var{N2} @tab Shall be a non-negative scalar of type @code{INTEGER}.
1780 @item @var{X} @tab Shall be a scalar or an array of type @code{REAL};
1781 for @code{BESSEL_JN(N1, N2, X)} it shall be scalar.
1784 @item @emph{Return value}:
1785 The return value is a scalar of type @code{REAL}. It has the same
1789 The transformational function uses a recurrence algorithm which might,
1790 for some values of @var{X}, lead to different results than calls to
1791 the elemental function.
1793 @item @emph{Example}:
1796 real(8) :: x = 1.0_8
1798 end program test_besjn
1801 @item @emph{Specific names}:
1802 @multitable @columnfractions .20 .20 .20 .25
1803 @item Name @tab Argument @tab Return type @tab Standard
1804 @item @code{DBESJN(N, X)} @tab @code{INTEGER N} @tab @code{REAL(8)} @tab GNU extension
1805 @item @tab @code{REAL(8) X} @tab @tab
1812 @section @code{BESSEL_Y0} --- Bessel function of the second kind of order 0
1816 @cindex Bessel function, second kind
1819 @item @emph{Description}:
1820 @code{BESSEL_Y0(X)} computes the Bessel function of the second kind of
1821 order 0 of @var{X}. This function is available under the name
1822 @code{BESY0} as a GNU extension.
1824 @item @emph{Standard}:
1825 Fortran 2008 and later
1830 @item @emph{Syntax}:
1831 @code{RESULT = BESSEL_Y0(X)}
1833 @item @emph{Arguments}:
1834 @multitable @columnfractions .15 .70
1835 @item @var{X} @tab The type shall be @code{REAL}, and it shall be scalar.
1838 @item @emph{Return value}:
1839 The return value is a scalar of type @code{REAL}. It has the same
1842 @item @emph{Example}:
1845 real(8) :: x = 0.0_8
1847 end program test_besy0
1850 @item @emph{Specific names}:
1851 @multitable @columnfractions .20 .20 .20 .25
1852 @item Name @tab Argument @tab Return type @tab Standard
1853 @item @code{DBESY0(X)}@tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU extension
1860 @section @code{BESSEL_Y1} --- Bessel function of the second kind of order 1
1864 @cindex Bessel function, second kind
1867 @item @emph{Description}:
1868 @code{BESSEL_Y1(X)} computes the Bessel function of the second kind of
1869 order 1 of @var{X}. This function is available under the name
1870 @code{BESY1} as a GNU extension.
1872 @item @emph{Standard}:
1873 Fortran 2008 and later
1878 @item @emph{Syntax}:
1879 @code{RESULT = BESSEL_Y1(X)}
1881 @item @emph{Arguments}:
1882 @multitable @columnfractions .15 .70
1883 @item @var{X} @tab The type shall be @code{REAL}, and it shall be scalar.
1886 @item @emph{Return value}:
1887 The return value is a scalar of type @code{REAL}. It has the same
1890 @item @emph{Example}:
1893 real(8) :: x = 1.0_8
1895 end program test_besy1
1898 @item @emph{Specific names}:
1899 @multitable @columnfractions .20 .20 .20 .25
1900 @item Name @tab Argument @tab Return type @tab Standard
1901 @item @code{DBESY1(X)}@tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU extension
1908 @section @code{BESSEL_YN} --- Bessel function of the second kind
1912 @cindex Bessel function, second kind
1915 @item @emph{Description}:
1916 @code{BESSEL_YN(N, X)} computes the Bessel function of the second kind of
1917 order @var{N} of @var{X}. This function is available under the name
1918 @code{BESYN} as a GNU extension. If @var{N} and @var{X} are arrays,
1919 their ranks and shapes shall conform.
1921 @code{BESSEL_YN(N1, N2, X)} returns an array with the Bessel functions
1922 of the first kind of the orders @var{N1} to @var{N2}.
1924 @item @emph{Standard}:
1925 Fortran 2008 and later, negative @var{N} is allowed as GNU extension
1928 Elemental function, except for the transformational function
1929 @code{BESSEL_YN(N1, N2, X)}
1931 @item @emph{Syntax}:
1932 @multitable @columnfractions .80
1933 @item @code{RESULT = BESSEL_YN(N, X)}
1934 @item @code{RESULT = BESSEL_YN(N1, N2, X)}
1937 @item @emph{Arguments}:
1938 @multitable @columnfractions .15 .70
1939 @item @var{N} @tab Shall be a scalar or an array of type @code{INTEGER} .
1940 @item @var{N1} @tab Shall be a non-negative scalar of type @code{INTEGER}.
1941 @item @var{N2} @tab Shall be a non-negative scalar of type @code{INTEGER}.
1942 @item @var{X} @tab Shall be a scalar or an array of type @code{REAL};
1943 for @code{BESSEL_YN(N1, N2, X)} it shall be scalar.
1946 @item @emph{Return value}:
1947 The return value is a scalar of type @code{REAL}. It has the same
1951 The transformational function uses a recurrence algorithm which might,
1952 for some values of @var{X}, lead to different results than calls to
1953 the elemental function.
1955 @item @emph{Example}:
1958 real(8) :: x = 1.0_8
1960 end program test_besyn
1963 @item @emph{Specific names}:
1964 @multitable @columnfractions .20 .20 .20 .25
1965 @item Name @tab Argument @tab Return type @tab Standard
1966 @item @code{DBESYN(N,X)} @tab @code{INTEGER N} @tab @code{REAL(8)} @tab GNU extension
1967 @item @tab @code{REAL(8) X} @tab @tab
1974 @section @code{BGE} --- Bitwise greater than or equal to
1976 @cindex bitwise comparison
1979 @item @emph{Description}:
1980 Determines whether an integral is a bitwise greater than or equal to
1983 @item @emph{Standard}:
1984 Fortran 2008 and later
1989 @item @emph{Syntax}:
1990 @code{RESULT = BGE(I, J)}
1992 @item @emph{Arguments}:
1993 @multitable @columnfractions .15 .70
1994 @item @var{I} @tab Shall be of @code{INTEGER} type.
1995 @item @var{J} @tab Shall be of @code{INTEGER} type, and of the same kind
1999 @item @emph{Return value}:
2000 The return value is of type @code{LOGICAL} and of the default kind.
2002 @item @emph{See also}:
2003 @ref{BGT}, @ref{BLE}, @ref{BLT}
2009 @section @code{BGT} --- Bitwise greater than
2011 @cindex bitwise comparison
2014 @item @emph{Description}:
2015 Determines whether an integral is a bitwise greater than another.
2017 @item @emph{Standard}:
2018 Fortran 2008 and later
2023 @item @emph{Syntax}:
2024 @code{RESULT = BGT(I, J)}
2026 @item @emph{Arguments}:
2027 @multitable @columnfractions .15 .70
2028 @item @var{I} @tab Shall be of @code{INTEGER} type.
2029 @item @var{J} @tab Shall be of @code{INTEGER} type, and of the same kind
2033 @item @emph{Return value}:
2034 The return value is of type @code{LOGICAL} and of the default kind.
2036 @item @emph{See also}:
2037 @ref{BGE}, @ref{BLE}, @ref{BLT}
2043 @section @code{BIT_SIZE} --- Bit size inquiry function
2045 @cindex bits, number of
2046 @cindex size of a variable, in bits
2049 @item @emph{Description}:
2050 @code{BIT_SIZE(I)} returns the number of bits (integer precision plus sign bit)
2051 represented by the type of @var{I}. The result of @code{BIT_SIZE(I)} is
2052 independent of the actual value of @var{I}.
2054 @item @emph{Standard}:
2055 Fortran 95 and later
2060 @item @emph{Syntax}:
2061 @code{RESULT = BIT_SIZE(I)}
2063 @item @emph{Arguments}:
2064 @multitable @columnfractions .15 .70
2065 @item @var{I} @tab The type shall be @code{INTEGER}.
2068 @item @emph{Return value}:
2069 The return value is of type @code{INTEGER}
2071 @item @emph{Example}:
2073 program test_bit_size
2078 end program test_bit_size
2085 @section @code{BLE} --- Bitwise less than or equal to
2087 @cindex bitwise comparison
2090 @item @emph{Description}:
2091 Determines whether an integral is a bitwise less than or equal to
2094 @item @emph{Standard}:
2095 Fortran 2008 and later
2100 @item @emph{Syntax}:
2101 @code{RESULT = BLE(I, J)}
2103 @item @emph{Arguments}:
2104 @multitable @columnfractions .15 .70
2105 @item @var{I} @tab Shall be of @code{INTEGER} type.
2106 @item @var{J} @tab Shall be of @code{INTEGER} type, and of the same kind
2110 @item @emph{Return value}:
2111 The return value is of type @code{LOGICAL} and of the default kind.
2113 @item @emph{See also}:
2114 @ref{BGT}, @ref{BGE}, @ref{BLT}
2120 @section @code{BLT} --- Bitwise less than
2122 @cindex bitwise comparison
2125 @item @emph{Description}:
2126 Determines whether an integral is a bitwise less than another.
2128 @item @emph{Standard}:
2129 Fortran 2008 and later
2134 @item @emph{Syntax}:
2135 @code{RESULT = BLT(I, J)}
2137 @item @emph{Arguments}:
2138 @multitable @columnfractions .15 .70
2139 @item @var{I} @tab Shall be of @code{INTEGER} type.
2140 @item @var{J} @tab Shall be of @code{INTEGER} type, and of the same kind
2144 @item @emph{Return value}:
2145 The return value is of type @code{LOGICAL} and of the default kind.
2147 @item @emph{See also}:
2148 @ref{BGE}, @ref{BGT}, @ref{BLE}
2154 @section @code{BTEST} --- Bit test function
2156 @cindex bits, testing
2159 @item @emph{Description}:
2160 @code{BTEST(I,POS)} returns logical @code{.TRUE.} if the bit at @var{POS}
2161 in @var{I} is set. The counting of the bits starts at 0.
2163 @item @emph{Standard}:
2164 Fortran 95 and later
2169 @item @emph{Syntax}:
2170 @code{RESULT = BTEST(I, POS)}
2172 @item @emph{Arguments}:
2173 @multitable @columnfractions .15 .70
2174 @item @var{I} @tab The type shall be @code{INTEGER}.
2175 @item @var{POS} @tab The type shall be @code{INTEGER}.
2178 @item @emph{Return value}:
2179 The return value is of type @code{LOGICAL}
2181 @item @emph{Example}:
2184 integer :: i = 32768 + 1024 + 64
2188 bool = btest(i, pos)
2191 end program test_btest
2197 @section @code{C_ASSOCIATED} --- Status of a C pointer
2198 @fnindex C_ASSOCIATED
2199 @cindex association status, C pointer
2200 @cindex pointer, C association status
2203 @item @emph{Description}:
2204 @code{C_ASSOCIATED(c_prt_1[, c_ptr_2])} determines the status of the C pointer
2205 @var{c_ptr_1} or if @var{c_ptr_1} is associated with the target @var{c_ptr_2}.
2207 @item @emph{Standard}:
2208 Fortran 2003 and later
2213 @item @emph{Syntax}:
2214 @code{RESULT = C_ASSOCIATED(c_prt_1[, c_ptr_2])}
2216 @item @emph{Arguments}:
2217 @multitable @columnfractions .15 .70
2218 @item @var{c_ptr_1} @tab Scalar of the type @code{C_PTR} or @code{C_FUNPTR}.
2219 @item @var{c_ptr_2} @tab (Optional) Scalar of the same type as @var{c_ptr_1}.
2222 @item @emph{Return value}:
2223 The return value is of type @code{LOGICAL}; it is @code{.false.} if either
2224 @var{c_ptr_1} is a C NULL pointer or if @var{c_ptr1} and @var{c_ptr_2}
2225 point to different addresses.
2227 @item @emph{Example}:
2229 subroutine association_test(a,b)
2230 use iso_c_binding, only: c_associated, c_loc, c_ptr
2234 if(c_associated(b, c_loc(a))) &
2235 stop 'b and a do not point to same target'
2236 end subroutine association_test
2239 @item @emph{See also}:
2240 @ref{C_LOC}, @ref{C_FUNLOC}
2245 @section @code{C_FUNLOC} --- Obtain the C address of a procedure
2247 @cindex pointer, C address of procedures
2250 @item @emph{Description}:
2251 @code{C_FUNLOC(x)} determines the C address of the argument.
2253 @item @emph{Standard}:
2254 Fortran 2003 and later
2259 @item @emph{Syntax}:
2260 @code{RESULT = C_FUNLOC(x)}
2262 @item @emph{Arguments}:
2263 @multitable @columnfractions .15 .70
2264 @item @var{x} @tab Interoperable function or pointer to such function.
2267 @item @emph{Return value}:
2268 The return value is of type @code{C_FUNPTR} and contains the C address
2271 @item @emph{Example}:
2277 subroutine sub(a) bind(c)
2287 subroutine my_routine(p) bind(c,name='myC_func')
2289 type(c_funptr), intent(in) :: p
2292 call my_routine(c_funloc(sub))
2296 @item @emph{See also}:
2297 @ref{C_ASSOCIATED}, @ref{C_LOC}, @ref{C_F_POINTER}, @ref{C_F_PROCPOINTER}
2301 @node C_F_PROCPOINTER
2302 @section @code{C_F_PROCPOINTER} --- Convert C into Fortran procedure pointer
2303 @fnindex C_F_PROCPOINTER
2304 @cindex pointer, C address of pointers
2307 @item @emph{Description}:
2308 @code{C_F_PROCPOINTER(CPTR, FPTR)} Assign the target of the C function pointer
2309 @var{CPTR} to the Fortran procedure pointer @var{FPTR}.
2311 @item @emph{Standard}:
2312 Fortran 2003 and later
2317 @item @emph{Syntax}:
2318 @code{CALL C_F_PROCPOINTER(cptr, fptr)}
2320 @item @emph{Arguments}:
2321 @multitable @columnfractions .15 .70
2322 @item @var{CPTR} @tab scalar of the type @code{C_FUNPTR}. It is
2324 @item @var{FPTR} @tab procedure pointer interoperable with @var{cptr}. It is
2328 @item @emph{Example}:
2336 real(c_float), intent(in) :: a
2337 real(c_float) :: func
2341 function getIterFunc() bind(c,name="getIterFunc")
2343 type(c_funptr) :: getIterFunc
2346 type(c_funptr) :: cfunptr
2347 procedure(func), pointer :: myFunc
2348 cfunptr = getIterFunc()
2349 call c_f_procpointer(cfunptr, myFunc)
2353 @item @emph{See also}:
2354 @ref{C_LOC}, @ref{C_F_POINTER}
2359 @section @code{C_F_POINTER} --- Convert C into Fortran pointer
2360 @fnindex C_F_POINTER
2361 @cindex pointer, convert C to Fortran
2364 @item @emph{Description}:
2365 @code{C_F_POINTER(CPTR, FPTR[, SHAPE])} Assign the target the C pointer
2366 @var{CPTR} to the Fortran pointer @var{FPTR} and specify its
2369 @item @emph{Standard}:
2370 Fortran 2003 and later
2375 @item @emph{Syntax}:
2376 @code{CALL C_F_POINTER(CPTR, FPTR[, SHAPE])}
2378 @item @emph{Arguments}:
2379 @multitable @columnfractions .15 .70
2380 @item @var{CPTR} @tab scalar of the type @code{C_PTR}. It is
2382 @item @var{FPTR} @tab pointer interoperable with @var{cptr}. It is
2384 @item @var{SHAPE} @tab (Optional) Rank-one array of type @code{INTEGER}
2385 with @code{INTENT(IN)}. It shall be present
2386 if and only if @var{fptr} is an array. The size
2387 must be equal to the rank of @var{fptr}.
2390 @item @emph{Example}:
2396 subroutine my_routine(p) bind(c,name='myC_func')
2398 type(c_ptr), intent(out) :: p
2402 real,pointer :: a(:)
2403 call my_routine(cptr)
2404 call c_f_pointer(cptr, a, [12])
2408 @item @emph{See also}:
2409 @ref{C_LOC}, @ref{C_F_PROCPOINTER}
2414 @section @code{C_LOC} --- Obtain the C address of an object
2416 @cindex procedure pointer, convert C to Fortran
2419 @item @emph{Description}:
2420 @code{C_LOC(X)} determines the C address of the argument.
2422 @item @emph{Standard}:
2423 Fortran 2003 and later
2428 @item @emph{Syntax}:
2429 @code{RESULT = C_LOC(X)}
2431 @item @emph{Arguments}:
2432 @multitable @columnfractions .10 .75
2433 @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.
2437 @item @emph{Return value}:
2438 The return value is of type @code{C_PTR} and contains the C address
2441 @item @emph{Example}:
2443 subroutine association_test(a,b)
2444 use iso_c_binding, only: c_associated, c_loc, c_ptr
2448 if(c_associated(b, c_loc(a))) &
2449 stop 'b and a do not point to same target'
2450 end subroutine association_test
2453 @item @emph{See also}:
2454 @ref{C_ASSOCIATED}, @ref{C_FUNLOC}, @ref{C_F_POINTER}, @ref{C_F_PROCPOINTER}
2459 @section @code{C_SIZEOF} --- Size in bytes of an expression
2461 @cindex expression size
2462 @cindex size of an expression
2465 @item @emph{Description}:
2466 @code{C_SIZEOF(X)} calculates the number of bytes of storage the
2467 expression @code{X} occupies.
2469 @item @emph{Standard}:
2473 Inquiry function of the module @code{ISO_C_BINDING}
2475 @item @emph{Syntax}:
2476 @code{N = C_SIZEOF(X)}
2478 @item @emph{Arguments}:
2479 @multitable @columnfractions .15 .70
2480 @item @var{X} @tab The argument shall be an interoperable data entity.
2483 @item @emph{Return value}:
2484 The return value is of type integer and of the system-dependent kind
2485 @code{C_SIZE_T} (from the @code{ISO_C_BINDING} module). Its value is the
2486 number of bytes occupied by the argument. If the argument has the
2487 @code{POINTER} attribute, the number of bytes of the storage area pointed
2488 to is returned. If the argument is of a derived type with @code{POINTER}
2489 or @code{ALLOCATABLE} components, the return value does not account for
2490 the sizes of the data pointed to by these components.
2492 @item @emph{Example}:
2496 real(c_float) :: r, s(5)
2497 print *, (c_sizeof(s)/c_sizeof(r) == 5)
2500 The example will print @code{.TRUE.} unless you are using a platform
2501 where default @code{REAL} variables are unusually padded.
2503 @item @emph{See also}:
2504 @ref{SIZEOF}, @ref{STORAGE_SIZE}
2509 @section @code{CEILING} --- Integer ceiling function
2512 @cindex rounding, ceiling
2515 @item @emph{Description}:
2516 @code{CEILING(A)} returns the least integer greater than or equal to @var{A}.
2518 @item @emph{Standard}:
2519 Fortran 95 and later
2524 @item @emph{Syntax}:
2525 @code{RESULT = CEILING(A [, KIND])}
2527 @item @emph{Arguments}:
2528 @multitable @columnfractions .15 .70
2529 @item @var{A} @tab The type shall be @code{REAL}.
2530 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
2531 expression indicating the kind parameter of the result.
2534 @item @emph{Return value}:
2535 The return value is of type @code{INTEGER(KIND)} if @var{KIND} is present
2536 and a default-kind @code{INTEGER} otherwise.
2538 @item @emph{Example}:
2540 program test_ceiling
2543 print *, ceiling(x) ! returns 64
2544 print *, ceiling(y) ! returns -63
2545 end program test_ceiling
2548 @item @emph{See also}:
2549 @ref{FLOOR}, @ref{NINT}
2556 @section @code{CHAR} --- Character conversion function
2558 @cindex conversion, to character
2561 @item @emph{Description}:
2562 @code{CHAR(I [, KIND])} returns the character represented by the integer @var{I}.
2564 @item @emph{Standard}:
2565 Fortran 77 and later
2570 @item @emph{Syntax}:
2571 @code{RESULT = CHAR(I [, KIND])}
2573 @item @emph{Arguments}:
2574 @multitable @columnfractions .15 .70
2575 @item @var{I} @tab The type shall be @code{INTEGER}.
2576 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
2577 expression indicating the kind parameter of the result.
2580 @item @emph{Return value}:
2581 The return value is of type @code{CHARACTER(1)}
2583 @item @emph{Example}:
2589 print *, i, c ! returns 'J'
2590 end program test_char
2593 @item @emph{Specific names}:
2594 @multitable @columnfractions .20 .20 .20 .25
2595 @item Name @tab Argument @tab Return type @tab Standard
2596 @item @code{CHAR(I)} @tab @code{INTEGER I} @tab @code{CHARACTER(LEN=1)} @tab F77 and later
2600 See @ref{ICHAR} for a discussion of converting between numerical values
2601 and formatted string representations.
2603 @item @emph{See also}:
2604 @ref{ACHAR}, @ref{IACHAR}, @ref{ICHAR}
2611 @section @code{CHDIR} --- Change working directory
2613 @cindex system, working directory
2616 @item @emph{Description}:
2617 Change current working directory to a specified path.
2619 This intrinsic is provided in both subroutine and function forms; however,
2620 only one form can be used in any given program unit.
2622 @item @emph{Standard}:
2626 Subroutine, function
2628 @item @emph{Syntax}:
2629 @multitable @columnfractions .80
2630 @item @code{CALL CHDIR(NAME [, STATUS])}
2631 @item @code{STATUS = CHDIR(NAME)}
2634 @item @emph{Arguments}:
2635 @multitable @columnfractions .15 .70
2636 @item @var{NAME} @tab The type shall be @code{CHARACTER} of default
2637 kind and shall specify a valid path within the file system.
2638 @item @var{STATUS} @tab (Optional) @code{INTEGER} status flag of the default
2639 kind. Returns 0 on success, and a system specific and nonzero error code
2643 @item @emph{Example}:
2646 CHARACTER(len=255) :: path
2648 WRITE(*,*) TRIM(path)
2651 WRITE(*,*) TRIM(path)
2655 @item @emph{See also}:
2662 @section @code{CHMOD} --- Change access permissions of files
2664 @cindex file system, change access mode
2667 @item @emph{Description}:
2668 @code{CHMOD} changes the permissions of a file.
2670 This intrinsic is provided in both subroutine and function forms; however,
2671 only one form can be used in any given program unit.
2673 @item @emph{Standard}:
2677 Subroutine, function
2679 @item @emph{Syntax}:
2680 @multitable @columnfractions .80
2681 @item @code{CALL CHMOD(NAME, MODE[, STATUS])}
2682 @item @code{STATUS = CHMOD(NAME, MODE)}
2685 @item @emph{Arguments}:
2686 @multitable @columnfractions .15 .70
2688 @item @var{NAME} @tab Scalar @code{CHARACTER} of default kind with the
2689 file name. Trailing blanks are ignored unless the character
2690 @code{achar(0)} is present, then all characters up to and excluding
2691 @code{achar(0)} are used as the file name.
2693 @item @var{MODE} @tab Scalar @code{CHARACTER} of default kind giving the
2694 file permission. @var{MODE} uses the same syntax as the @code{chmod} utility
2695 as defined by the POSIX standard. The argument shall either be a string of
2696 a nonnegative octal number or a symbolic mode.
2698 @item @var{STATUS} @tab (optional) scalar @code{INTEGER}, which is
2699 @code{0} on success and nonzero otherwise.
2702 @item @emph{Return value}:
2703 In either syntax, @var{STATUS} is set to @code{0} on success and nonzero
2706 @item @emph{Example}:
2707 @code{CHMOD} as subroutine
2712 call chmod('test.dat','u+x',status)
2713 print *, 'Status: ', status
2714 end program chmod_test
2716 @code{CHMOD} as function:
2721 status = chmod('test.dat','u+x')
2722 print *, 'Status: ', status
2723 end program chmod_test
2731 @section @code{CMPLX} --- Complex conversion function
2733 @cindex complex numbers, conversion to
2734 @cindex conversion, to complex
2737 @item @emph{Description}:
2738 @code{CMPLX(X [, Y [, KIND]])} returns a complex number where @var{X} is converted to
2739 the real component. If @var{Y} is present it is converted to the imaginary
2740 component. If @var{Y} is not present then the imaginary component is set to
2741 0.0. If @var{X} is complex then @var{Y} must not be present.
2743 @item @emph{Standard}:
2744 Fortran 77 and later
2749 @item @emph{Syntax}:
2750 @code{RESULT = CMPLX(X [, Y [, KIND]])}
2752 @item @emph{Arguments}:
2753 @multitable @columnfractions .15 .70
2754 @item @var{X} @tab The type may be @code{INTEGER}, @code{REAL},
2756 @item @var{Y} @tab (Optional; only allowed if @var{X} is not
2757 @code{COMPLEX}.) May be @code{INTEGER} or @code{REAL}.
2758 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
2759 expression indicating the kind parameter of the result.
2762 @item @emph{Return value}:
2763 The return value is of @code{COMPLEX} type, with a kind equal to
2764 @var{KIND} if it is specified. If @var{KIND} is not specified, the
2765 result is of the default @code{COMPLEX} kind, regardless of the kinds of
2766 @var{X} and @var{Y}.
2768 @item @emph{Example}:
2775 print *, z, cmplx(x)
2776 end program test_cmplx
2779 @item @emph{See also}:
2785 @node COMMAND_ARGUMENT_COUNT
2786 @section @code{COMMAND_ARGUMENT_COUNT} --- Get number of command line arguments
2787 @fnindex COMMAND_ARGUMENT_COUNT
2788 @cindex command-line arguments
2789 @cindex command-line arguments, number of
2790 @cindex arguments, to program
2793 @item @emph{Description}:
2794 @code{COMMAND_ARGUMENT_COUNT} returns the number of arguments passed on the
2795 command line when the containing program was invoked.
2797 @item @emph{Standard}:
2798 Fortran 2003 and later
2803 @item @emph{Syntax}:
2804 @code{RESULT = COMMAND_ARGUMENT_COUNT()}
2806 @item @emph{Arguments}:
2807 @multitable @columnfractions .15 .70
2811 @item @emph{Return value}:
2812 The return value is an @code{INTEGER} of default kind.
2814 @item @emph{Example}:
2816 program test_command_argument_count
2818 count = command_argument_count()
2820 end program test_command_argument_count
2823 @item @emph{See also}:
2824 @ref{GET_COMMAND}, @ref{GET_COMMAND_ARGUMENT}
2829 @node COMPILER_OPTIONS
2830 @section @code{COMPILER_OPTIONS} --- Options passed to the compiler
2831 @fnindex COMPILER_OPTIONS
2832 @cindex flags inquiry function
2833 @cindex options inquiry function
2834 @cindex compiler flags inquiry function
2837 @item @emph{Description}:
2838 @code{COMPILER_OPTIONS} returns a string with the options used for
2841 @item @emph{Standard}:
2845 Inquiry function of the module @code{ISO_FORTRAN_ENV}
2847 @item @emph{Syntax}:
2848 @code{STR = COMPILER_OPTIONS()}
2850 @item @emph{Arguments}:
2853 @item @emph{Return value}:
2854 The return value is a default-kind string with system-dependent length.
2855 It contains the compiler flags used to compile the file, which called
2856 the @code{COMPILER_OPTIONS} intrinsic.
2858 @item @emph{Example}:
2861 print '(4a)', 'This file was compiled by ', &
2862 compiler_version(), ' using the options ', &
2867 @item @emph{See also}:
2868 @ref{COMPILER_VERSION}, @ref{ISO_FORTRAN_ENV}
2873 @node COMPILER_VERSION
2874 @section @code{COMPILER_VERSION} --- Compiler version string
2875 @fnindex COMPILER_VERSION
2876 @cindex compiler, name and version
2877 @cindex version of the compiler
2880 @item @emph{Description}:
2881 @code{COMPILER_VERSION} returns a string with the name and the
2882 version of the compiler.
2884 @item @emph{Standard}:
2888 Inquiry function of the module @code{ISO_FORTRAN_ENV}
2890 @item @emph{Syntax}:
2891 @code{STR = COMPILER_VERSION()}
2893 @item @emph{Arguments}:
2896 @item @emph{Return value}:
2897 The return value is a default-kind string with system-dependent length.
2898 It contains the name of the compiler and its version number.
2900 @item @emph{Example}:
2903 print '(4a)', 'This file was compiled by ', &
2904 compiler_version(), ' using the options ', &
2909 @item @emph{See also}:
2910 @ref{COMPILER_OPTIONS}, @ref{ISO_FORTRAN_ENV}
2916 @section @code{COMPLEX} --- Complex conversion function
2918 @cindex complex numbers, conversion to
2919 @cindex conversion, to complex
2922 @item @emph{Description}:
2923 @code{COMPLEX(X, Y)} returns a complex number where @var{X} is converted
2924 to the real component and @var{Y} is converted to the imaginary
2927 @item @emph{Standard}:
2933 @item @emph{Syntax}:
2934 @code{RESULT = COMPLEX(X, Y)}
2936 @item @emph{Arguments}:
2937 @multitable @columnfractions .15 .70
2938 @item @var{X} @tab The type may be @code{INTEGER} or @code{REAL}.
2939 @item @var{Y} @tab The type may be @code{INTEGER} or @code{REAL}.
2942 @item @emph{Return value}:
2943 If @var{X} and @var{Y} are both of @code{INTEGER} type, then the return
2944 value is of default @code{COMPLEX} type.
2946 If @var{X} and @var{Y} are of @code{REAL} type, or one is of @code{REAL}
2947 type and one is of @code{INTEGER} type, then the return value is of
2948 @code{COMPLEX} type with a kind equal to that of the @code{REAL}
2949 argument with the highest precision.
2951 @item @emph{Example}:
2953 program test_complex
2956 print *, complex(i, x)
2957 end program test_complex
2960 @item @emph{See also}:
2967 @section @code{CONJG} --- Complex conjugate function
2970 @cindex complex conjugate
2973 @item @emph{Description}:
2974 @code{CONJG(Z)} returns the conjugate of @var{Z}. If @var{Z} is @code{(x, y)}
2975 then the result is @code{(x, -y)}
2977 @item @emph{Standard}:
2978 Fortran 77 and later, has overloads that are GNU extensions
2983 @item @emph{Syntax}:
2986 @item @emph{Arguments}:
2987 @multitable @columnfractions .15 .70
2988 @item @var{Z} @tab The type shall be @code{COMPLEX}.
2991 @item @emph{Return value}:
2992 The return value is of type @code{COMPLEX}.
2994 @item @emph{Example}:
2997 complex :: z = (2.0, 3.0)
2998 complex(8) :: dz = (2.71_8, -3.14_8)
3003 end program test_conjg
3006 @item @emph{Specific names}:
3007 @multitable @columnfractions .20 .20 .20 .25
3008 @item Name @tab Argument @tab Return type @tab Standard
3009 @item @code{CONJG(Z)} @tab @code{COMPLEX Z} @tab @code{COMPLEX} @tab GNU extension
3010 @item @code{DCONJG(Z)} @tab @code{COMPLEX(8) Z} @tab @code{COMPLEX(8)} @tab GNU extension
3017 @section @code{COS} --- Cosine function
3023 @cindex trigonometric function, cosine
3027 @item @emph{Description}:
3028 @code{COS(X)} computes the cosine of @var{X}.
3030 @item @emph{Standard}:
3031 Fortran 77 and later, has overloads that are GNU extensions
3036 @item @emph{Syntax}:
3037 @code{RESULT = COS(X)}
3039 @item @emph{Arguments}:
3040 @multitable @columnfractions .15 .70
3041 @item @var{X} @tab The type shall be @code{REAL} or
3045 @item @emph{Return value}:
3046 The return value is of the same type and kind as @var{X}. The real part
3047 of the result is in radians. If @var{X} is of the type @code{REAL},
3048 the return value lies in the range @math{ -1 \leq \cos (x) \leq 1}.
3050 @item @emph{Example}:
3055 end program test_cos
3058 @item @emph{Specific names}:
3059 @multitable @columnfractions .20 .20 .20 .25
3060 @item Name @tab Argument @tab Return type @tab Standard
3061 @item @code{COS(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab Fortran 77 and later
3062 @item @code{DCOS(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab Fortran 77 and later
3063 @item @code{CCOS(X)} @tab @code{COMPLEX(4) X} @tab @code{COMPLEX(4)} @tab Fortran 77 and later
3064 @item @code{ZCOS(X)} @tab @code{COMPLEX(8) X} @tab @code{COMPLEX(8)} @tab GNU extension
3065 @item @code{CDCOS(X)} @tab @code{COMPLEX(8) X} @tab @code{COMPLEX(8)} @tab GNU extension
3068 @item @emph{See also}:
3069 Inverse function: @ref{ACOS}
3076 @section @code{COSH} --- Hyperbolic cosine function
3079 @cindex hyperbolic cosine
3080 @cindex hyperbolic function, cosine
3081 @cindex cosine, hyperbolic
3084 @item @emph{Description}:
3085 @code{COSH(X)} computes the hyperbolic cosine of @var{X}.
3087 @item @emph{Standard}:
3088 Fortran 77 and later, for a complex argument Fortran 2008 or later
3093 @item @emph{Syntax}:
3096 @item @emph{Arguments}:
3097 @multitable @columnfractions .15 .70
3098 @item @var{X} @tab The type shall be @code{REAL} or @code{COMPLEX}.
3101 @item @emph{Return value}:
3102 The return value has same type and kind as @var{X}. If @var{X} is
3103 complex, the imaginary part of the result is in radians. If @var{X}
3104 is @code{REAL}, the return value has a lower bound of one,
3105 @math{\cosh (x) \geq 1}.
3107 @item @emph{Example}:
3110 real(8) :: x = 1.0_8
3112 end program test_cosh
3115 @item @emph{Specific names}:
3116 @multitable @columnfractions .20 .20 .20 .25
3117 @item Name @tab Argument @tab Return type @tab Standard
3118 @item @code{COSH(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab Fortran 77 and later
3119 @item @code{DCOSH(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab Fortran 77 and later
3122 @item @emph{See also}:
3123 Inverse function: @ref{ACOSH}
3130 @section @code{COUNT} --- Count function
3132 @cindex array, conditionally count elements
3133 @cindex array, element counting
3134 @cindex array, number of elements
3137 @item @emph{Description}:
3139 Counts the number of @code{.TRUE.} elements in a logical @var{MASK},
3140 or, if the @var{DIM} argument is supplied, counts the number of
3141 elements along each row of the array in the @var{DIM} direction.
3142 If the array has zero size, or all of the elements of @var{MASK} are
3143 @code{.FALSE.}, then the result is @code{0}.
3145 @item @emph{Standard}:
3146 Fortran 95 and later, with @var{KIND} argument Fortran 2003 and later
3149 Transformational function
3151 @item @emph{Syntax}:
3152 @code{RESULT = COUNT(MASK [, DIM, KIND])}
3154 @item @emph{Arguments}:
3155 @multitable @columnfractions .15 .70
3156 @item @var{MASK} @tab The type shall be @code{LOGICAL}.
3157 @item @var{DIM} @tab (Optional) The type shall be @code{INTEGER}.
3158 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
3159 expression indicating the kind parameter of the result.
3162 @item @emph{Return value}:
3163 The return value is of type @code{INTEGER} and of kind @var{KIND}. If
3164 @var{KIND} is absent, the return value is of default integer kind.
3165 If @var{DIM} is present, the result is an array with a rank one less
3166 than the rank of @var{ARRAY}, and a size corresponding to the shape
3167 of @var{ARRAY} with the @var{DIM} dimension removed.
3169 @item @emph{Example}:
3172 integer, dimension(2,3) :: a, b
3173 logical, dimension(2,3) :: mask
3174 a = reshape( (/ 1, 2, 3, 4, 5, 6 /), (/ 2, 3 /))
3175 b = reshape( (/ 0, 7, 3, 4, 5, 8 /), (/ 2, 3 /))
3176 print '(3i3)', a(1,:)
3177 print '(3i3)', a(2,:)
3179 print '(3i3)', b(1,:)
3180 print '(3i3)', b(2,:)
3183 print '(3l3)', mask(1,:)
3184 print '(3l3)', mask(2,:)
3186 print '(3i3)', count(mask)
3188 print '(3i3)', count(mask, 1)
3190 print '(3i3)', count(mask, 2)
3191 end program test_count
3198 @section @code{CPU_TIME} --- CPU elapsed time in seconds
3200 @cindex time, elapsed
3203 @item @emph{Description}:
3204 Returns a @code{REAL} value representing the elapsed CPU time in
3205 seconds. This is useful for testing segments of code to determine
3208 If a time source is available, time will be reported with microsecond
3209 resolution. If no time source is available, @var{TIME} is set to
3212 Note that @var{TIME} may contain a, system dependent, arbitrary offset
3213 and may not start with @code{0.0}. For @code{CPU_TIME}, the absolute
3214 value is meaningless, only differences between subsequent calls to
3215 this subroutine, as shown in the example below, should be used.
3218 @item @emph{Standard}:
3219 Fortran 95 and later
3224 @item @emph{Syntax}:
3225 @code{CALL CPU_TIME(TIME)}
3227 @item @emph{Arguments}:
3228 @multitable @columnfractions .15 .70
3229 @item @var{TIME} @tab The type shall be @code{REAL} with @code{INTENT(OUT)}.
3232 @item @emph{Return value}:
3235 @item @emph{Example}:
3237 program test_cpu_time
3238 real :: start, finish
3239 call cpu_time(start)
3240 ! put code to test here
3241 call cpu_time(finish)
3242 print '("Time = ",f6.3," seconds.")',finish-start
3243 end program test_cpu_time
3246 @item @emph{See also}:
3247 @ref{SYSTEM_CLOCK}, @ref{DATE_AND_TIME}
3253 @section @code{CSHIFT} --- Circular shift elements of an array
3255 @cindex array, shift circularly
3256 @cindex array, permutation
3257 @cindex array, rotate
3260 @item @emph{Description}:
3261 @code{CSHIFT(ARRAY, SHIFT [, DIM])} performs a circular shift on elements of
3262 @var{ARRAY} along the dimension of @var{DIM}. If @var{DIM} is omitted it is
3263 taken to be @code{1}. @var{DIM} is a scalar of type @code{INTEGER} in the
3264 range of @math{1 \leq DIM \leq n)} where @math{n} is the rank of @var{ARRAY}.
3265 If the rank of @var{ARRAY} is one, then all elements of @var{ARRAY} are shifted
3266 by @var{SHIFT} places. If rank is greater than one, then all complete rank one
3267 sections of @var{ARRAY} along the given dimension are shifted. Elements
3268 shifted out one end of each rank one section are shifted back in the other end.
3270 @item @emph{Standard}:
3271 Fortran 95 and later
3274 Transformational function
3276 @item @emph{Syntax}:
3277 @code{RESULT = CSHIFT(ARRAY, SHIFT [, DIM])}
3279 @item @emph{Arguments}:
3280 @multitable @columnfractions .15 .70
3281 @item @var{ARRAY} @tab Shall be an array of any type.
3282 @item @var{SHIFT} @tab The type shall be @code{INTEGER}.
3283 @item @var{DIM} @tab The type shall be @code{INTEGER}.
3286 @item @emph{Return value}:
3287 Returns an array of same type and rank as the @var{ARRAY} argument.
3289 @item @emph{Example}:
3292 integer, dimension(3,3) :: a
3293 a = reshape( (/ 1, 2, 3, 4, 5, 6, 7, 8, 9 /), (/ 3, 3 /))
3294 print '(3i3)', a(1,:)
3295 print '(3i3)', a(2,:)
3296 print '(3i3)', a(3,:)
3297 a = cshift(a, SHIFT=(/1, 2, -1/), DIM=2)
3299 print '(3i3)', a(1,:)
3300 print '(3i3)', a(2,:)
3301 print '(3i3)', a(3,:)
3302 end program test_cshift
3309 @section @code{CTIME} --- Convert a time into a string
3311 @cindex time, conversion to string
3312 @cindex conversion, to string
3315 @item @emph{Description}:
3316 @code{CTIME} converts a system time value, such as returned by
3317 @code{TIME8}, to a string. Unless the application has called
3318 @code{setlocale}, the output will be in the default locale, of length
3319 24 and of the form @samp{Sat Aug 19 18:13:14 1995}. In other locales,
3320 a longer string may result.
3322 This intrinsic is provided in both subroutine and function forms; however,
3323 only one form can be used in any given program unit.
3325 @item @emph{Standard}:
3329 Subroutine, function
3331 @item @emph{Syntax}:
3332 @multitable @columnfractions .80
3333 @item @code{CALL CTIME(TIME, RESULT)}.
3334 @item @code{RESULT = CTIME(TIME)}.
3337 @item @emph{Arguments}:
3338 @multitable @columnfractions .15 .70
3339 @item @var{TIME} @tab The type shall be of type @code{INTEGER}.
3340 @item @var{RESULT} @tab The type shall be of type @code{CHARACTER} and
3341 of default kind. It is an @code{INTENT(OUT)} argument. If the length
3342 of this variable is too short for the time and date string to fit
3343 completely, it will be blank on procedure return.
3346 @item @emph{Return value}:
3347 The converted date and time as a string.
3349 @item @emph{Example}:
3353 character(len=30) :: date
3356 ! Do something, main part of the program
3359 print *, 'Program was started on ', date
3360 end program test_ctime
3363 @item @emph{See Also}:
3364 @ref{DATE_AND_TIME}, @ref{GMTIME}, @ref{LTIME}, @ref{TIME}, @ref{TIME8}
3370 @section @code{DATE_AND_TIME} --- Date and time subroutine
3371 @fnindex DATE_AND_TIME
3372 @cindex date, current
3373 @cindex current date
3374 @cindex time, current
3375 @cindex current time
3378 @item @emph{Description}:
3379 @code{DATE_AND_TIME(DATE, TIME, ZONE, VALUES)} gets the corresponding date and
3380 time information from the real-time system clock. @var{DATE} is
3381 @code{INTENT(OUT)} and has form ccyymmdd. @var{TIME} is @code{INTENT(OUT)} and
3382 has form hhmmss.sss. @var{ZONE} is @code{INTENT(OUT)} and has form (+-)hhmm,
3383 representing the difference with respect to Coordinated Universal Time (UTC).
3384 Unavailable time and date parameters return blanks.
3386 @var{VALUES} is @code{INTENT(OUT)} and provides the following:
3388 @multitable @columnfractions .15 .30 .40
3389 @item @tab @code{VALUE(1)}: @tab The year
3390 @item @tab @code{VALUE(2)}: @tab The month
3391 @item @tab @code{VALUE(3)}: @tab The day of the month
3392 @item @tab @code{VALUE(4)}: @tab Time difference with UTC in minutes
3393 @item @tab @code{VALUE(5)}: @tab The hour of the day
3394 @item @tab @code{VALUE(6)}: @tab The minutes of the hour
3395 @item @tab @code{VALUE(7)}: @tab The seconds of the minute
3396 @item @tab @code{VALUE(8)}: @tab The milliseconds of the second
3399 @item @emph{Standard}:
3400 Fortran 95 and later
3405 @item @emph{Syntax}:
3406 @code{CALL DATE_AND_TIME([DATE, TIME, ZONE, VALUES])}
3408 @item @emph{Arguments}:
3409 @multitable @columnfractions .15 .70
3410 @item @var{DATE} @tab (Optional) The type shall be @code{CHARACTER(LEN=8)}
3411 or larger, and of default kind.
3412 @item @var{TIME} @tab (Optional) The type shall be @code{CHARACTER(LEN=10)}
3413 or larger, and of default kind.
3414 @item @var{ZONE} @tab (Optional) The type shall be @code{CHARACTER(LEN=5)}
3415 or larger, and of default kind.
3416 @item @var{VALUES}@tab (Optional) The type shall be @code{INTEGER(8)}.
3419 @item @emph{Return value}:
3422 @item @emph{Example}:
3424 program test_time_and_date
3425 character(8) :: date
3426 character(10) :: time
3427 character(5) :: zone
3428 integer,dimension(8) :: values
3429 ! using keyword arguments
3430 call date_and_time(date,time,zone,values)
3431 call date_and_time(DATE=date,ZONE=zone)
3432 call date_and_time(TIME=time)
3433 call date_and_time(VALUES=values)
3434 print '(a,2x,a,2x,a)', date, time, zone
3435 print '(8i5))', values
3436 end program test_time_and_date
3439 @item @emph{See also}:
3440 @ref{CPU_TIME}, @ref{SYSTEM_CLOCK}
3446 @section @code{DBLE} --- Double conversion function
3448 @cindex conversion, to real
3451 @item @emph{Description}:
3452 @code{DBLE(A)} Converts @var{A} to double precision real type.
3454 @item @emph{Standard}:
3455 Fortran 77 and later
3460 @item @emph{Syntax}:
3461 @code{RESULT = DBLE(A)}
3463 @item @emph{Arguments}:
3464 @multitable @columnfractions .15 .70
3465 @item @var{A} @tab The type shall be @code{INTEGER}, @code{REAL},
3469 @item @emph{Return value}:
3470 The return value is of type double precision real.
3472 @item @emph{Example}:
3477 complex :: z = (2.3,1.14)
3478 print *, dble(x), dble(i), dble(z)
3479 end program test_dble
3482 @item @emph{See also}:
3489 @section @code{DCMPLX} --- Double complex conversion function
3491 @cindex complex numbers, conversion to
3492 @cindex conversion, to complex
3495 @item @emph{Description}:
3496 @code{DCMPLX(X [,Y])} returns a double complex number where @var{X} is
3497 converted to the real component. If @var{Y} is present it is converted to the
3498 imaginary component. If @var{Y} is not present then the imaginary component is
3499 set to 0.0. If @var{X} is complex then @var{Y} must not be present.
3501 @item @emph{Standard}:
3507 @item @emph{Syntax}:
3508 @code{RESULT = DCMPLX(X [, Y])}
3510 @item @emph{Arguments}:
3511 @multitable @columnfractions .15 .70
3512 @item @var{X} @tab The type may be @code{INTEGER}, @code{REAL},
3514 @item @var{Y} @tab (Optional if @var{X} is not @code{COMPLEX}.) May be
3515 @code{INTEGER} or @code{REAL}.
3518 @item @emph{Return value}:
3519 The return value is of type @code{COMPLEX(8)}
3521 @item @emph{Example}:
3531 print *, dcmplx(x,i)
3532 end program test_dcmplx
3538 @section @code{DIGITS} --- Significant binary digits function
3540 @cindex model representation, significant digits
3543 @item @emph{Description}:
3544 @code{DIGITS(X)} returns the number of significant binary digits of the internal
3545 model representation of @var{X}. For example, on a system using a 32-bit
3546 floating point representation, a default real number would likely return 24.
3548 @item @emph{Standard}:
3549 Fortran 95 and later
3554 @item @emph{Syntax}:
3555 @code{RESULT = DIGITS(X)}
3557 @item @emph{Arguments}:
3558 @multitable @columnfractions .15 .70
3559 @item @var{X} @tab The type may be @code{INTEGER} or @code{REAL}.
3562 @item @emph{Return value}:
3563 The return value is of type @code{INTEGER}.
3565 @item @emph{Example}:
3568 integer :: i = 12345
3574 end program test_digits
3581 @section @code{DIM} --- Positive difference
3585 @cindex positive difference
3588 @item @emph{Description}:
3589 @code{DIM(X,Y)} returns the difference @code{X-Y} if the result is positive;
3590 otherwise returns zero.
3592 @item @emph{Standard}:
3593 Fortran 77 and later
3598 @item @emph{Syntax}:
3599 @code{RESULT = DIM(X, Y)}
3601 @item @emph{Arguments}:
3602 @multitable @columnfractions .15 .70
3603 @item @var{X} @tab The type shall be @code{INTEGER} or @code{REAL}
3604 @item @var{Y} @tab The type shall be the same type and kind as @var{X}.
3607 @item @emph{Return value}:
3608 The return value is of type @code{INTEGER} or @code{REAL}.
3610 @item @emph{Example}:
3616 x = dim(4.345_8, 2.111_8)
3619 end program test_dim
3622 @item @emph{Specific names}:
3623 @multitable @columnfractions .20 .20 .20 .25
3624 @item Name @tab Argument @tab Return type @tab Standard
3625 @item @code{DIM(X,Y)} @tab @code{REAL(4) X, Y} @tab @code{REAL(4)} @tab Fortran 77 and later
3626 @item @code{IDIM(X,Y)} @tab @code{INTEGER(4) X, Y} @tab @code{INTEGER(4)} @tab Fortran 77 and later
3627 @item @code{DDIM(X,Y)} @tab @code{REAL(8) X, Y} @tab @code{REAL(8)} @tab Fortran 77 and later
3634 @section @code{DOT_PRODUCT} --- Dot product function
3635 @fnindex DOT_PRODUCT
3637 @cindex vector product
3638 @cindex product, vector
3641 @item @emph{Description}:
3642 @code{DOT_PRODUCT(VECTOR_A, VECTOR_B)} computes the dot product multiplication
3643 of two vectors @var{VECTOR_A} and @var{VECTOR_B}. The two vectors may be
3644 either numeric or logical and must be arrays of rank one and of equal size. If
3645 the vectors are @code{INTEGER} or @code{REAL}, the result is
3646 @code{SUM(VECTOR_A*VECTOR_B)}. If the vectors are @code{COMPLEX}, the result
3647 is @code{SUM(CONJG(VECTOR_A)*VECTOR_B)}. If the vectors are @code{LOGICAL},
3648 the result is @code{ANY(VECTOR_A .AND. VECTOR_B)}.
3650 @item @emph{Standard}:
3651 Fortran 95 and later
3654 Transformational function
3656 @item @emph{Syntax}:
3657 @code{RESULT = DOT_PRODUCT(VECTOR_A, VECTOR_B)}
3659 @item @emph{Arguments}:
3660 @multitable @columnfractions .15 .70
3661 @item @var{VECTOR_A} @tab The type shall be numeric or @code{LOGICAL}, rank 1.
3662 @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.
3665 @item @emph{Return value}:
3666 If the arguments are numeric, the return value is a scalar of numeric type,
3667 @code{INTEGER}, @code{REAL}, or @code{COMPLEX}. If the arguments are
3668 @code{LOGICAL}, the return value is @code{.TRUE.} or @code{.FALSE.}.
3670 @item @emph{Example}:
3672 program test_dot_prod
3673 integer, dimension(3) :: a, b
3680 print *, dot_product(a,b)
3681 end program test_dot_prod
3688 @section @code{DPROD} --- Double product function
3690 @cindex product, double-precision
3693 @item @emph{Description}:
3694 @code{DPROD(X,Y)} returns the product @code{X*Y}.
3696 @item @emph{Standard}:
3697 Fortran 77 and later
3702 @item @emph{Syntax}:
3703 @code{RESULT = DPROD(X, Y)}
3705 @item @emph{Arguments}:
3706 @multitable @columnfractions .15 .70
3707 @item @var{X} @tab The type shall be @code{REAL}.
3708 @item @var{Y} @tab The type shall be @code{REAL}.
3711 @item @emph{Return value}:
3712 The return value is of type @code{REAL(8)}.
3714 @item @emph{Example}:
3722 end program test_dprod
3725 @item @emph{Specific names}:
3726 @multitable @columnfractions .20 .20 .20 .25
3727 @item Name @tab Argument @tab Return type @tab Standard
3728 @item @code{DPROD(X,Y)} @tab @code{REAL(4) X, Y} @tab @code{REAL(4)} @tab Fortran 77 and later
3735 @section @code{DREAL} --- Double real part function
3737 @cindex complex numbers, real part
3740 @item @emph{Description}:
3741 @code{DREAL(Z)} returns the real part of complex variable @var{Z}.
3743 @item @emph{Standard}:
3749 @item @emph{Syntax}:
3750 @code{RESULT = DREAL(A)}
3752 @item @emph{Arguments}:
3753 @multitable @columnfractions .15 .70
3754 @item @var{A} @tab The type shall be @code{COMPLEX(8)}.
3757 @item @emph{Return value}:
3758 The return value is of type @code{REAL(8)}.
3760 @item @emph{Example}:
3763 complex(8) :: z = (1.3_8,7.2_8)
3765 end program test_dreal
3768 @item @emph{See also}:
3776 @section @code{DSHIFTL} --- Combined left shift
3778 @cindex left shift, combined
3782 @item @emph{Description}:
3783 @code{DSHIFTL(I, J, SHIFT)} combines bits of @var{I} and @var{J}. The
3784 rightmost @var{SHIFT} bits of the result are the leftmost @var{SHIFT}
3785 bits of @var{J}, and the remaining bits are the rightmost bits of
3788 @item @emph{Standard}:
3789 Fortran 2008 and later
3794 @item @emph{Syntax}:
3795 @code{RESULT = DSHIFTL(I, J, SHIFT)}
3797 @item @emph{Arguments}:
3798 @multitable @columnfractions .15 .70
3799 @item @var{I} @tab Shall be of type @code{INTEGER} or a BOZ constant.
3800 @item @var{J} @tab Shall be of type @code{INTEGER} or a BOZ constant.
3801 If both @var{I} and @var{J} have integer type, then they shall have
3802 the same kind type parameter. @var{I} and @var{J} shall not both be
3804 @item @var{SHIFT} @tab Shall be of type @code{INTEGER}. It shall
3805 be nonnegative. If @var{I} is not a BOZ constant, then @var{SHIFT}
3806 shall be less than or equal to @code{BIT_SIZE(I)}; otherwise,
3807 @var{SHIFT} shall be less than or equal to @code{BIT_SIZE(J)}.
3810 @item @emph{Return value}:
3811 If either @var{I} or @var{J} is a BOZ constant, it is first converted
3812 as if by the intrinsic function @code{INT} to an integer type with the
3813 kind type parameter of the other.
3815 @item @emph{See also}:
3821 @section @code{DSHIFTR} --- Combined right shift
3823 @cindex right shift, combined
3824 @cindex shift, right
3827 @item @emph{Description}:
3828 @code{DSHIFTR(I, J, SHIFT)} combines bits of @var{I} and @var{J}. The
3829 leftmost @var{SHIFT} bits of the result are the rightmost @var{SHIFT}
3830 bits of @var{I}, and the remaining bits are the leftmost bits of
3833 @item @emph{Standard}:
3834 Fortran 2008 and later
3839 @item @emph{Syntax}:
3840 @code{RESULT = DSHIFTR(I, J, SHIFT)}
3842 @item @emph{Arguments}:
3843 @multitable @columnfractions .15 .70
3844 @item @var{I} @tab Shall be of type @code{INTEGER} or a BOZ constant.
3845 @item @var{J} @tab Shall be of type @code{INTEGER} or a BOZ constant.
3846 If both @var{I} and @var{J} have integer type, then they shall have
3847 the same kind type parameter. @var{I} and @var{J} shall not both be
3849 @item @var{SHIFT} @tab Shall be of type @code{INTEGER}. It shall
3850 be nonnegative. If @var{I} is not a BOZ constant, then @var{SHIFT}
3851 shall be less than or equal to @code{BIT_SIZE(I)}; otherwise,
3852 @var{SHIFT} shall be less than or equal to @code{BIT_SIZE(J)}.
3855 @item @emph{Return value}:
3856 If either @var{I} or @var{J} is a BOZ constant, it is first converted
3857 as if by the intrinsic function @code{INT} to an integer type with the
3858 kind type parameter of the other.
3860 @item @emph{See also}:
3866 @section @code{DTIME} --- Execution time subroutine (or function)
3868 @cindex time, elapsed
3869 @cindex elapsed time
3872 @item @emph{Description}:
3873 @code{DTIME(VALUES, TIME)} initially returns the number of seconds of runtime
3874 since the start of the process's execution in @var{TIME}. @var{VALUES}
3875 returns the user and system components of this time in @code{VALUES(1)} and
3876 @code{VALUES(2)} respectively. @var{TIME} is equal to @code{VALUES(1) +
3879 Subsequent invocations of @code{DTIME} return values accumulated since the
3880 previous invocation.
3882 On some systems, the underlying timings are represented using types with
3883 sufficiently small limits that overflows (wrap around) are possible, such as
3884 32-bit types. Therefore, the values returned by this intrinsic might be, or
3885 become, negative, or numerically less than previous values, during a single
3886 run of the compiled program.
3888 Please note, that this implementation is thread safe if used within OpenMP
3889 directives, i.e., its state will be consistent while called from multiple
3890 threads. However, if @code{DTIME} is called from multiple threads, the result
3891 is still the time since the last invocation. This may not give the intended
3892 results. If possible, use @code{CPU_TIME} instead.
3894 This intrinsic is provided in both subroutine and function forms; however,
3895 only one form can be used in any given program unit.
3897 @var{VALUES} and @var{TIME} are @code{INTENT(OUT)} and provide the following:
3899 @multitable @columnfractions .15 .30 .40
3900 @item @tab @code{VALUES(1)}: @tab User time in seconds.
3901 @item @tab @code{VALUES(2)}: @tab System time in seconds.
3902 @item @tab @code{TIME}: @tab Run time since start in seconds.
3905 @item @emph{Standard}:
3909 Subroutine, function
3911 @item @emph{Syntax}:
3912 @multitable @columnfractions .80
3913 @item @code{CALL DTIME(VALUES, TIME)}.
3914 @item @code{TIME = DTIME(VALUES)}, (not recommended).
3917 @item @emph{Arguments}:
3918 @multitable @columnfractions .15 .70
3919 @item @var{VALUES}@tab The type shall be @code{REAL(4), DIMENSION(2)}.
3920 @item @var{TIME}@tab The type shall be @code{REAL(4)}.
3923 @item @emph{Return value}:
3924 Elapsed time in seconds since the last invocation or since the start of program
3925 execution if not called before.
3927 @item @emph{Example}:
3931 real, dimension(2) :: tarray
3933 call dtime(tarray, result)
3937 do i=1,100000000 ! Just a delay
3940 call dtime(tarray, result)
3944 end program test_dtime
3947 @item @emph{See also}:
3955 @section @code{EOSHIFT} --- End-off shift elements of an array
3957 @cindex array, shift
3960 @item @emph{Description}:
3961 @code{EOSHIFT(ARRAY, SHIFT[, BOUNDARY, DIM])} performs an end-off shift on
3962 elements of @var{ARRAY} along the dimension of @var{DIM}. If @var{DIM} is
3963 omitted it is taken to be @code{1}. @var{DIM} is a scalar of type
3964 @code{INTEGER} in the range of @math{1 \leq DIM \leq n)} where @math{n} is the
3965 rank of @var{ARRAY}. If the rank of @var{ARRAY} is one, then all elements of
3966 @var{ARRAY} are shifted by @var{SHIFT} places. If rank is greater than one,
3967 then all complete rank one sections of @var{ARRAY} along the given dimension are
3968 shifted. Elements shifted out one end of each rank one section are dropped. If
3969 @var{BOUNDARY} is present then the corresponding value of from @var{BOUNDARY}
3970 is copied back in the other end. If @var{BOUNDARY} is not present then the
3971 following are copied in depending on the type of @var{ARRAY}.
3973 @multitable @columnfractions .15 .80
3974 @item @emph{Array Type} @tab @emph{Boundary Value}
3975 @item Numeric @tab 0 of the type and kind of @var{ARRAY}.
3976 @item Logical @tab @code{.FALSE.}.
3977 @item Character(@var{len}) @tab @var{len} blanks.
3980 @item @emph{Standard}:
3981 Fortran 95 and later
3984 Transformational function
3986 @item @emph{Syntax}:
3987 @code{RESULT = EOSHIFT(ARRAY, SHIFT [, BOUNDARY, DIM])}
3989 @item @emph{Arguments}:
3990 @multitable @columnfractions .15 .70
3991 @item @var{ARRAY} @tab May be any type, not scalar.
3992 @item @var{SHIFT} @tab The type shall be @code{INTEGER}.
3993 @item @var{BOUNDARY} @tab Same type as @var{ARRAY}.
3994 @item @var{DIM} @tab The type shall be @code{INTEGER}.
3997 @item @emph{Return value}:
3998 Returns an array of same type and rank as the @var{ARRAY} argument.
4000 @item @emph{Example}:
4002 program test_eoshift
4003 integer, dimension(3,3) :: a
4004 a = reshape( (/ 1, 2, 3, 4, 5, 6, 7, 8, 9 /), (/ 3, 3 /))
4005 print '(3i3)', a(1,:)
4006 print '(3i3)', a(2,:)
4007 print '(3i3)', a(3,:)
4008 a = EOSHIFT(a, SHIFT=(/1, 2, 1/), BOUNDARY=-5, DIM=2)
4010 print '(3i3)', a(1,:)
4011 print '(3i3)', a(2,:)
4012 print '(3i3)', a(3,:)
4013 end program test_eoshift
4020 @section @code{EPSILON} --- Epsilon function
4022 @cindex model representation, epsilon
4025 @item @emph{Description}:
4026 @code{EPSILON(X)} returns the smallest number @var{E} of the same kind
4027 as @var{X} such that @math{1 + E > 1}.
4029 @item @emph{Standard}:
4030 Fortran 95 and later
4035 @item @emph{Syntax}:
4036 @code{RESULT = EPSILON(X)}
4038 @item @emph{Arguments}:
4039 @multitable @columnfractions .15 .70
4040 @item @var{X} @tab The type shall be @code{REAL}.
4043 @item @emph{Return value}:
4044 The return value is of same type as the argument.
4046 @item @emph{Example}:
4048 program test_epsilon
4053 end program test_epsilon
4060 @section @code{ERF} --- Error function
4062 @cindex error function
4065 @item @emph{Description}:
4066 @code{ERF(X)} computes the error function of @var{X}.
4068 @item @emph{Standard}:
4069 Fortran 2008 and later
4074 @item @emph{Syntax}:
4075 @code{RESULT = ERF(X)}
4077 @item @emph{Arguments}:
4078 @multitable @columnfractions .15 .70
4079 @item @var{X} @tab The type shall be @code{REAL}.
4082 @item @emph{Return value}:
4083 The return value is of type @code{REAL}, of the same kind as
4084 @var{X} and lies in the range @math{-1 \leq erf (x) \leq 1 }.
4086 @item @emph{Example}:
4089 real(8) :: x = 0.17_8
4091 end program test_erf
4094 @item @emph{Specific names}:
4095 @multitable @columnfractions .20 .20 .20 .25
4096 @item Name @tab Argument @tab Return type @tab Standard
4097 @item @code{DERF(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU extension
4104 @section @code{ERFC} --- Error function
4106 @cindex error function, complementary
4109 @item @emph{Description}:
4110 @code{ERFC(X)} computes the complementary error function of @var{X}.
4112 @item @emph{Standard}:
4113 Fortran 2008 and later
4118 @item @emph{Syntax}:
4119 @code{RESULT = ERFC(X)}
4121 @item @emph{Arguments}:
4122 @multitable @columnfractions .15 .70
4123 @item @var{X} @tab The type shall be @code{REAL}.
4126 @item @emph{Return value}:
4127 The return value is of type @code{REAL} and of the same kind as @var{X}.
4128 It lies in the range @math{ 0 \leq erfc (x) \leq 2 }.
4130 @item @emph{Example}:
4133 real(8) :: x = 0.17_8
4135 end program test_erfc
4138 @item @emph{Specific names}:
4139 @multitable @columnfractions .20 .20 .20 .25
4140 @item Name @tab Argument @tab Return type @tab Standard
4141 @item @code{DERFC(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU extension
4148 @section @code{ERFC_SCALED} --- Error function
4149 @fnindex ERFC_SCALED
4150 @cindex error function, complementary, exponentially-scaled
4153 @item @emph{Description}:
4154 @code{ERFC_SCALED(X)} computes the exponentially-scaled complementary
4155 error function of @var{X}.
4157 @item @emph{Standard}:
4158 Fortran 2008 and later
4163 @item @emph{Syntax}:
4164 @code{RESULT = ERFC_SCALED(X)}
4166 @item @emph{Arguments}:
4167 @multitable @columnfractions .15 .70
4168 @item @var{X} @tab The type shall be @code{REAL}.
4171 @item @emph{Return value}:
4172 The return value is of type @code{REAL} and of the same kind as @var{X}.
4174 @item @emph{Example}:
4176 program test_erfc_scaled
4177 real(8) :: x = 0.17_8
4179 end program test_erfc_scaled
4186 @section @code{ETIME} --- Execution time subroutine (or function)
4188 @cindex time, elapsed
4191 @item @emph{Description}:
4192 @code{ETIME(VALUES, TIME)} returns the number of seconds of runtime
4193 since the start of the process's execution in @var{TIME}. @var{VALUES}
4194 returns the user and system components of this time in @code{VALUES(1)} and
4195 @code{VALUES(2)} respectively. @var{TIME} is equal to @code{VALUES(1) + VALUES(2)}.
4197 On some systems, the underlying timings are represented using types with
4198 sufficiently small limits that overflows (wrap around) are possible, such as
4199 32-bit types. Therefore, the values returned by this intrinsic might be, or
4200 become, negative, or numerically less than previous values, during a single
4201 run of the compiled program.
4203 This intrinsic is provided in both subroutine and function forms; however,
4204 only one form can be used in any given program unit.
4206 @var{VALUES} and @var{TIME} are @code{INTENT(OUT)} and provide the following:
4208 @multitable @columnfractions .15 .30 .60
4209 @item @tab @code{VALUES(1)}: @tab User time in seconds.
4210 @item @tab @code{VALUES(2)}: @tab System time in seconds.
4211 @item @tab @code{TIME}: @tab Run time since start in seconds.
4214 @item @emph{Standard}:
4218 Subroutine, function
4220 @item @emph{Syntax}:
4221 @multitable @columnfractions .80
4222 @item @code{CALL ETIME(VALUES, TIME)}.
4223 @item @code{TIME = ETIME(VALUES)}, (not recommended).
4226 @item @emph{Arguments}:
4227 @multitable @columnfractions .15 .70
4228 @item @var{VALUES}@tab The type shall be @code{REAL(4), DIMENSION(2)}.
4229 @item @var{TIME}@tab The type shall be @code{REAL(4)}.
4232 @item @emph{Return value}:
4233 Elapsed time in seconds since the start of program execution.
4235 @item @emph{Example}:
4239 real, dimension(2) :: tarray
4241 call ETIME(tarray, result)
4245 do i=1,100000000 ! Just a delay
4248 call ETIME(tarray, result)
4252 end program test_etime
4255 @item @emph{See also}:
4262 @node EXECUTE_COMMAND_LINE
4263 @section @code{EXECUTE_COMMAND_LINE} --- Execute a shell command
4264 @fnindex EXECUTE_COMMAND_LINE
4265 @cindex system, system call
4266 @cindex command line
4269 @item @emph{Description}:
4270 @code{EXECUTE_COMMAND_LINE} runs a shell command, synchronously or
4273 The @code{COMMAND} argument is passed to the shell and executed, using
4274 the C library's @code{system} call. (The shell is @code{sh} on Unix
4275 systems, and @code{cmd.exe} on Windows.) If @code{WAIT} is present
4276 and has the value false, the execution of the command is asynchronous
4277 if the system supports it; otherwise, the command is executed
4280 The three last arguments allow the user to get status information. After
4281 synchronous execution, @code{EXITSTAT} contains the integer exit code of
4282 the command, as returned by @code{system}. @code{CMDSTAT} is set to zero
4283 if the command line was executed (whatever its exit status was).
4284 @code{CMDMSG} is assigned an error message if an error has occurred.
4286 Note that the @code{system} function need not be thread-safe. It is
4287 the responsibility of the user to ensure that @code{system} is not
4288 called concurrently.
4290 @item @emph{Standard}:
4291 Fortran 2008 and later
4296 @item @emph{Syntax}:
4297 @code{CALL EXECUTE_COMMAND_LINE(COMMAND [, WAIT, EXITSTAT, CMDSTAT, CMDMSG ])}
4299 @item @emph{Arguments}:
4300 @multitable @columnfractions .15 .70
4301 @item @var{COMMAND} @tab Shall be a default @code{CHARACTER} scalar.
4302 @item @var{WAIT} @tab (Optional) Shall be a default @code{LOGICAL} scalar.
4303 @item @var{EXITSTAT} @tab (Optional) Shall be an @code{INTEGER} of the
4305 @item @var{CMDSTAT} @tab (Optional) Shall be an @code{INTEGER} of the
4307 @item @var{CMDMSG} @tab (Optional) Shall be an @code{CHARACTER} scalar of the
4311 @item @emph{Example}:
4316 call execute_command_line ("external_prog.exe", exitstat=i)
4317 print *, "Exit status of external_prog.exe was ", i
4319 call execute_command_line ("reindex_files.exe", wait=.false.)
4320 print *, "Now reindexing files in the background"
4322 end program test_exec
4328 Because this intrinsic is implemented in terms of the @code{system}
4329 function call, its behavior with respect to signaling is processor
4330 dependent. In particular, on POSIX-compliant systems, the SIGINT and
4331 SIGQUIT signals will be ignored, and the SIGCHLD will be blocked. As
4332 such, if the parent process is terminated, the child process might not be
4333 terminated alongside.
4336 @item @emph{See also}:
4343 @section @code{EXIT} --- Exit the program with status.
4345 @cindex program termination
4346 @cindex terminate program
4349 @item @emph{Description}:
4350 @code{EXIT} causes immediate termination of the program with status. If status
4351 is omitted it returns the canonical @emph{success} for the system. All Fortran
4352 I/O units are closed.
4354 @item @emph{Standard}:
4360 @item @emph{Syntax}:
4361 @code{CALL EXIT([STATUS])}
4363 @item @emph{Arguments}:
4364 @multitable @columnfractions .15 .70
4365 @item @var{STATUS} @tab Shall be an @code{INTEGER} of the default kind.
4368 @item @emph{Return value}:
4369 @code{STATUS} is passed to the parent process on exit.
4371 @item @emph{Example}:
4374 integer :: STATUS = 0
4375 print *, 'This program is going to exit.'
4377 end program test_exit
4380 @item @emph{See also}:
4381 @ref{ABORT}, @ref{KILL}
4387 @section @code{EXP} --- Exponential function
4393 @cindex exponential function
4394 @cindex logarithm function, inverse
4397 @item @emph{Description}:
4398 @code{EXP(X)} computes the base @math{e} exponential of @var{X}.
4400 @item @emph{Standard}:
4401 Fortran 77 and later, has overloads that are GNU extensions
4406 @item @emph{Syntax}:
4407 @code{RESULT = EXP(X)}
4409 @item @emph{Arguments}:
4410 @multitable @columnfractions .15 .70
4411 @item @var{X} @tab The type shall be @code{REAL} or
4415 @item @emph{Return value}:
4416 The return value has same type and kind as @var{X}.
4418 @item @emph{Example}:
4423 end program test_exp
4426 @item @emph{Specific names}:
4427 @multitable @columnfractions .20 .20 .20 .25
4428 @item Name @tab Argument @tab Return type @tab Standard
4429 @item @code{EXP(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab Fortran 77 and later
4430 @item @code{DEXP(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab Fortran 77 and later
4431 @item @code{CEXP(X)} @tab @code{COMPLEX(4) X} @tab @code{COMPLEX(4)} @tab Fortran 77 and later
4432 @item @code{ZEXP(X)} @tab @code{COMPLEX(8) X} @tab @code{COMPLEX(8)} @tab GNU extension
4433 @item @code{CDEXP(X)} @tab @code{COMPLEX(8) X} @tab @code{COMPLEX(8)} @tab GNU extension
4440 @section @code{EXPONENT} --- Exponent function
4442 @cindex real number, exponent
4443 @cindex floating point, exponent
4446 @item @emph{Description}:
4447 @code{EXPONENT(X)} returns the value of the exponent part of @var{X}. If @var{X}
4448 is zero the value returned is zero.
4450 @item @emph{Standard}:
4451 Fortran 95 and later
4456 @item @emph{Syntax}:
4457 @code{RESULT = EXPONENT(X)}
4459 @item @emph{Arguments}:
4460 @multitable @columnfractions .15 .70
4461 @item @var{X} @tab The type shall be @code{REAL}.
4464 @item @emph{Return value}:
4465 The return value is of type default @code{INTEGER}.
4467 @item @emph{Example}:
4469 program test_exponent
4474 print *, exponent(0.0)
4475 end program test_exponent
4481 @node EXTENDS_TYPE_OF
4482 @section @code{EXTENDS_TYPE_OF} --- Query dynamic type for extension
4483 @fnindex EXTENDS_TYPE_OF
4486 @item @emph{Description}:
4487 Query dynamic type for extension.
4489 @item @emph{Standard}:
4490 Fortran 2003 and later
4495 @item @emph{Syntax}:
4496 @code{RESULT = EXTENDS_TYPE_OF(A, MOLD)}
4498 @item @emph{Arguments}:
4499 @multitable @columnfractions .15 .70
4500 @item @var{A} @tab Shall be an object of extensible declared type or
4501 unlimited polymorphic.
4502 @item @var{MOLD} @tab Shall be an object of extensible declared type or
4503 unlimited polymorphic.
4506 @item @emph{Return value}:
4507 The return value is a scalar of type default logical. It is true if and only if
4508 the dynamic type of A is an extension type of the dynamic type of MOLD.
4511 @item @emph{See also}:
4518 @section @code{FDATE} --- Get the current time as a string
4520 @cindex time, current
4521 @cindex current time
4522 @cindex date, current
4523 @cindex current date
4526 @item @emph{Description}:
4527 @code{FDATE(DATE)} returns the current date (using the same format as
4528 @code{CTIME}) in @var{DATE}. It is equivalent to @code{CALL CTIME(DATE,
4531 This intrinsic is provided in both subroutine and function forms; however,
4532 only one form can be used in any given program unit.
4534 @item @emph{Standard}:
4538 Subroutine, function
4540 @item @emph{Syntax}:
4541 @multitable @columnfractions .80
4542 @item @code{CALL FDATE(DATE)}.
4543 @item @code{DATE = FDATE()}.
4546 @item @emph{Arguments}:
4547 @multitable @columnfractions .15 .70
4548 @item @var{DATE}@tab The type shall be of type @code{CHARACTER} of the
4549 default kind. It is an @code{INTENT(OUT)} argument. If the length of
4550 this variable is too short for the date and time string to fit
4551 completely, it will be blank on procedure return.
4554 @item @emph{Return value}:
4555 The current date and time as a string.
4557 @item @emph{Example}:
4561 character(len=30) :: date
4563 print *, 'Program started on ', date
4564 do i = 1, 100000000 ! Just a delay
4568 print *, 'Program ended on ', date
4569 end program test_fdate
4572 @item @emph{See also}:
4573 @ref{DATE_AND_TIME}, @ref{CTIME}
4578 @section @code{FGET} --- Read a single character in stream mode from stdin
4580 @cindex read character, stream mode
4581 @cindex stream mode, read character
4582 @cindex file operation, read character
4585 @item @emph{Description}:
4586 Read a single character in stream mode from stdin by bypassing normal
4587 formatted output. Stream I/O should not be mixed with normal record-oriented
4588 (formatted or unformatted) I/O on the same unit; the results are unpredictable.
4590 This intrinsic is provided in both subroutine and function forms; however,
4591 only one form can be used in any given program unit.
4593 Note that the @code{FGET} intrinsic is provided for backwards compatibility with
4594 @command{g77}. GNU Fortran provides the Fortran 2003 Stream facility.
4595 Programmers should consider the use of new stream IO feature in new code
4596 for future portability. See also @ref{Fortran 2003 status}.
4598 @item @emph{Standard}:
4602 Subroutine, function
4604 @item @emph{Syntax}:
4605 @multitable @columnfractions .80
4606 @item @code{CALL FGET(C [, STATUS])}
4607 @item @code{STATUS = FGET(C)}
4610 @item @emph{Arguments}:
4611 @multitable @columnfractions .15 .70
4612 @item @var{C} @tab The type shall be @code{CHARACTER} and of default
4614 @item @var{STATUS} @tab (Optional) status flag of type @code{INTEGER}.
4615 Returns 0 on success, -1 on end-of-file, and a system specific positive
4616 error code otherwise.
4619 @item @emph{Example}:
4622 INTEGER, PARAMETER :: strlen = 100
4623 INTEGER :: status, i = 1
4624 CHARACTER(len=strlen) :: str = ""
4626 WRITE (*,*) 'Enter text:'
4628 CALL fget(str(i:i), status)
4629 if (status /= 0 .OR. i > strlen) exit
4632 WRITE (*,*) TRIM(str)
4636 @item @emph{See also}:
4637 @ref{FGETC}, @ref{FPUT}, @ref{FPUTC}
4643 @section @code{FGETC} --- Read a single character in stream mode
4645 @cindex read character, stream mode
4646 @cindex stream mode, read character
4647 @cindex file operation, read character
4650 @item @emph{Description}:
4651 Read a single character in stream mode by bypassing normal formatted output.
4652 Stream I/O should not be mixed with normal record-oriented (formatted or
4653 unformatted) I/O on the same unit; the results are unpredictable.
4655 This intrinsic is provided in both subroutine and function forms; however,
4656 only one form can be used in any given program unit.
4658 Note that the @code{FGET} intrinsic is provided for backwards compatibility
4659 with @command{g77}. GNU Fortran provides the Fortran 2003 Stream facility.
4660 Programmers should consider the use of new stream IO feature in new code
4661 for future portability. See also @ref{Fortran 2003 status}.
4663 @item @emph{Standard}:
4667 Subroutine, function
4669 @item @emph{Syntax}:
4670 @multitable @columnfractions .80
4671 @item @code{CALL FGETC(UNIT, C [, STATUS])}
4672 @item @code{STATUS = FGETC(UNIT, C)}
4675 @item @emph{Arguments}:
4676 @multitable @columnfractions .15 .70
4677 @item @var{UNIT} @tab The type shall be @code{INTEGER}.
4678 @item @var{C} @tab The type shall be @code{CHARACTER} and of default
4680 @item @var{STATUS} @tab (Optional) status flag of type @code{INTEGER}.
4681 Returns 0 on success, -1 on end-of-file and a system specific positive
4682 error code otherwise.
4685 @item @emph{Example}:
4688 INTEGER :: fd = 42, status
4691 OPEN(UNIT=fd, FILE="/etc/passwd", ACTION="READ", STATUS = "OLD")
4693 CALL fgetc(fd, c, status)
4694 IF (status /= 0) EXIT
4701 @item @emph{See also}:
4702 @ref{FGET}, @ref{FPUT}, @ref{FPUTC}
4708 @section @code{FLOOR} --- Integer floor function
4711 @cindex rounding, floor
4714 @item @emph{Description}:
4715 @code{FLOOR(A)} returns the greatest integer less than or equal to @var{X}.
4717 @item @emph{Standard}:
4718 Fortran 95 and later
4723 @item @emph{Syntax}:
4724 @code{RESULT = FLOOR(A [, KIND])}
4726 @item @emph{Arguments}:
4727 @multitable @columnfractions .15 .70
4728 @item @var{A} @tab The type shall be @code{REAL}.
4729 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
4730 expression indicating the kind parameter of the result.
4733 @item @emph{Return value}:
4734 The return value is of type @code{INTEGER(KIND)} if @var{KIND} is present
4735 and of default-kind @code{INTEGER} otherwise.
4737 @item @emph{Example}:
4742 print *, floor(x) ! returns 63
4743 print *, floor(y) ! returns -64
4744 end program test_floor
4747 @item @emph{See also}:
4748 @ref{CEILING}, @ref{NINT}
4755 @section @code{FLUSH} --- Flush I/O unit(s)
4757 @cindex file operation, flush
4760 @item @emph{Description}:
4761 Flushes Fortran unit(s) currently open for output. Without the optional
4762 argument, all units are flushed, otherwise just the unit specified.
4764 @item @emph{Standard}:
4770 @item @emph{Syntax}:
4771 @code{CALL FLUSH(UNIT)}
4773 @item @emph{Arguments}:
4774 @multitable @columnfractions .15 .70
4775 @item @var{UNIT} @tab (Optional) The type shall be @code{INTEGER}.
4779 Beginning with the Fortran 2003 standard, there is a @code{FLUSH}
4780 statement that should be preferred over the @code{FLUSH} intrinsic.
4782 The @code{FLUSH} intrinsic and the Fortran 2003 @code{FLUSH} statement
4783 have identical effect: they flush the runtime library's I/O buffer so
4784 that the data becomes visible to other processes. This does not guarantee
4785 that the data is committed to disk.
4787 On POSIX systems, you can request that all data is transferred to the
4788 storage device by calling the @code{fsync} function, with the POSIX file
4789 descriptor of the I/O unit as argument (retrieved with GNU intrinsic
4790 @code{FNUM}). The following example shows how:
4793 ! Declare the interface for POSIX fsync function
4795 function fsync (fd) bind(c,name="fsync")
4796 use iso_c_binding, only: c_int
4797 integer(c_int), value :: fd
4798 integer(c_int) :: fsync
4802 ! Variable declaration
4806 open (10,file="foo")
4809 ! Perform I/O on unit 10
4814 ret = fsync(fnum(10))
4816 ! Handle possible error
4817 if (ret /= 0) stop "Error calling FSYNC"
4825 @section @code{FNUM} --- File number function
4827 @cindex file operation, file number
4830 @item @emph{Description}:
4831 @code{FNUM(UNIT)} returns the POSIX file descriptor number corresponding to the
4832 open Fortran I/O unit @code{UNIT}.
4834 @item @emph{Standard}:
4840 @item @emph{Syntax}:
4841 @code{RESULT = FNUM(UNIT)}
4843 @item @emph{Arguments}:
4844 @multitable @columnfractions .15 .70
4845 @item @var{UNIT} @tab The type shall be @code{INTEGER}.
4848 @item @emph{Return value}:
4849 The return value is of type @code{INTEGER}
4851 @item @emph{Example}:
4855 open (unit=10, status = "scratch")
4859 end program test_fnum
4866 @section @code{FPUT} --- Write a single character in stream mode to stdout
4868 @cindex write character, stream mode
4869 @cindex stream mode, write character
4870 @cindex file operation, write character
4873 @item @emph{Description}:
4874 Write a single character in stream mode to stdout by bypassing normal
4875 formatted output. Stream I/O should not be mixed with normal record-oriented
4876 (formatted or unformatted) I/O on the same unit; the results are unpredictable.
4878 This intrinsic is provided in both subroutine and function forms; however,
4879 only one form can be used in any given program unit.
4881 Note that the @code{FGET} intrinsic is provided for backwards compatibility with
4882 @command{g77}. GNU Fortran provides the Fortran 2003 Stream facility.
4883 Programmers should consider the use of new stream IO feature in new code
4884 for future portability. See also @ref{Fortran 2003 status}.
4886 @item @emph{Standard}:
4890 Subroutine, function
4892 @item @emph{Syntax}:
4893 @multitable @columnfractions .80
4894 @item @code{CALL FPUT(C [, STATUS])}
4895 @item @code{STATUS = FPUT(C)}
4898 @item @emph{Arguments}:
4899 @multitable @columnfractions .15 .70
4900 @item @var{C} @tab The type shall be @code{CHARACTER} and of default
4902 @item @var{STATUS} @tab (Optional) status flag of type @code{INTEGER}.
4903 Returns 0 on success, -1 on end-of-file and a system specific positive
4904 error code otherwise.
4907 @item @emph{Example}:
4910 CHARACTER(len=10) :: str = "gfortran"
4912 DO i = 1, len_trim(str)
4918 @item @emph{See also}:
4919 @ref{FPUTC}, @ref{FGET}, @ref{FGETC}
4925 @section @code{FPUTC} --- Write a single character in stream mode
4927 @cindex write character, stream mode
4928 @cindex stream mode, write character
4929 @cindex file operation, write character
4932 @item @emph{Description}:
4933 Write a single character in stream mode by bypassing normal formatted
4934 output. Stream I/O should not be mixed with normal record-oriented
4935 (formatted or unformatted) I/O on the same unit; the results are unpredictable.
4937 This intrinsic is provided in both subroutine and function forms; however,
4938 only one form can be used in any given program unit.
4940 Note that the @code{FGET} intrinsic is provided for backwards compatibility with
4941 @command{g77}. GNU Fortran provides the Fortran 2003 Stream facility.
4942 Programmers should consider the use of new stream IO feature in new code
4943 for future portability. See also @ref{Fortran 2003 status}.
4945 @item @emph{Standard}:
4949 Subroutine, function
4951 @item @emph{Syntax}:
4952 @multitable @columnfractions .80
4953 @item @code{CALL FPUTC(UNIT, C [, STATUS])}
4954 @item @code{STATUS = FPUTC(UNIT, C)}
4957 @item @emph{Arguments}:
4958 @multitable @columnfractions .15 .70
4959 @item @var{UNIT} @tab The type shall be @code{INTEGER}.
4960 @item @var{C} @tab The type shall be @code{CHARACTER} and of default
4962 @item @var{STATUS} @tab (Optional) status flag of type @code{INTEGER}.
4963 Returns 0 on success, -1 on end-of-file and a system specific positive
4964 error code otherwise.
4967 @item @emph{Example}:
4970 CHARACTER(len=10) :: str = "gfortran"
4971 INTEGER :: fd = 42, i
4973 OPEN(UNIT = fd, FILE = "out", ACTION = "WRITE", STATUS="NEW")
4974 DO i = 1, len_trim(str)
4975 CALL fputc(fd, str(i:i))
4981 @item @emph{See also}:
4982 @ref{FPUT}, @ref{FGET}, @ref{FGETC}
4988 @section @code{FRACTION} --- Fractional part of the model representation
4990 @cindex real number, fraction
4991 @cindex floating point, fraction
4994 @item @emph{Description}:
4995 @code{FRACTION(X)} returns the fractional part of the model
4996 representation of @code{X}.
4998 @item @emph{Standard}:
4999 Fortran 95 and later
5004 @item @emph{Syntax}:
5005 @code{Y = FRACTION(X)}
5007 @item @emph{Arguments}:
5008 @multitable @columnfractions .15 .70
5009 @item @var{X} @tab The type of the argument shall be a @code{REAL}.
5012 @item @emph{Return value}:
5013 The return value is of the same type and kind as the argument.
5014 The fractional part of the model representation of @code{X} is returned;
5015 it is @code{X * RADIX(X)**(-EXPONENT(X))}.
5017 @item @emph{Example}:
5019 program test_fraction
5022 print *, fraction(x), x * radix(x)**(-exponent(x))
5023 end program test_fraction
5031 @section @code{FREE} --- Frees memory
5033 @cindex pointer, cray
5036 @item @emph{Description}:
5037 Frees memory previously allocated by @code{MALLOC}. The @code{FREE}
5038 intrinsic is an extension intended to be used with Cray pointers, and is
5039 provided in GNU Fortran to allow user to compile legacy code. For
5040 new code using Fortran 95 pointers, the memory de-allocation intrinsic is
5043 @item @emph{Standard}:
5049 @item @emph{Syntax}:
5050 @code{CALL FREE(PTR)}
5052 @item @emph{Arguments}:
5053 @multitable @columnfractions .15 .70
5054 @item @var{PTR} @tab The type shall be @code{INTEGER}. It represents the
5055 location of the memory that should be de-allocated.
5058 @item @emph{Return value}:
5061 @item @emph{Example}:
5062 See @code{MALLOC} for an example.
5064 @item @emph{See also}:
5071 @section @code{FSEEK} --- Low level file positioning subroutine
5073 @cindex file operation, seek
5074 @cindex file operation, position
5077 @item @emph{Description}:
5078 Moves @var{UNIT} to the specified @var{OFFSET}. If @var{WHENCE}
5079 is set to 0, the @var{OFFSET} is taken as an absolute value @code{SEEK_SET},
5080 if set to 1, @var{OFFSET} is taken to be relative to the current position
5081 @code{SEEK_CUR}, and if set to 2 relative to the end of the file @code{SEEK_END}.
5082 On error, @var{STATUS} is set to a nonzero value. If @var{STATUS} the seek
5085 This intrinsic routine is not fully backwards compatible with @command{g77}.
5086 In @command{g77}, the @code{FSEEK} takes a statement label instead of a
5087 @var{STATUS} variable. If FSEEK is used in old code, change
5089 CALL FSEEK(UNIT, OFFSET, WHENCE, *label)
5094 CALL FSEEK(UNIT, OFFSET, WHENCE, status)
5095 IF (status /= 0) GOTO label
5098 Please note that GNU Fortran provides the Fortran 2003 Stream facility.
5099 Programmers should consider the use of new stream IO feature in new code
5100 for future portability. See also @ref{Fortran 2003 status}.
5102 @item @emph{Standard}:
5108 @item @emph{Syntax}:
5109 @code{CALL FSEEK(UNIT, OFFSET, WHENCE[, STATUS])}
5111 @item @emph{Arguments}:
5112 @multitable @columnfractions .15 .70
5113 @item @var{UNIT} @tab Shall be a scalar of type @code{INTEGER}.
5114 @item @var{OFFSET} @tab Shall be a scalar of type @code{INTEGER}.
5115 @item @var{WHENCE} @tab Shall be a scalar of type @code{INTEGER}.
5116 Its value shall be either 0, 1 or 2.
5117 @item @var{STATUS} @tab (Optional) shall be a scalar of type
5121 @item @emph{Example}:
5124 INTEGER, PARAMETER :: SEEK_SET = 0, SEEK_CUR = 1, SEEK_END = 2
5125 INTEGER :: fd, offset, ierr
5131 OPEN(UNIT=fd, FILE="fseek.test")
5132 CALL FSEEK(fd, offset, SEEK_SET, ierr) ! move to OFFSET
5133 print *, FTELL(fd), ierr
5135 CALL FSEEK(fd, 0, SEEK_END, ierr) ! move to end
5136 print *, FTELL(fd), ierr
5138 CALL FSEEK(fd, 0, SEEK_SET, ierr) ! move to beginning
5139 print *, FTELL(fd), ierr
5145 @item @emph{See also}:
5152 @section @code{FSTAT} --- Get file status
5154 @cindex file system, file status
5157 @item @emph{Description}:
5158 @code{FSTAT} is identical to @ref{STAT}, except that information about an
5159 already opened file is obtained.
5161 The elements in @code{VALUES} are the same as described by @ref{STAT}.
5163 This intrinsic is provided in both subroutine and function forms; however,
5164 only one form can be used in any given program unit.
5166 @item @emph{Standard}:
5170 Subroutine, function
5172 @item @emph{Syntax}:
5173 @multitable @columnfractions .80
5174 @item @code{CALL FSTAT(UNIT, VALUES [, STATUS])}
5175 @item @code{STATUS = FSTAT(UNIT, VALUES)}
5178 @item @emph{Arguments}:
5179 @multitable @columnfractions .15 .70
5180 @item @var{UNIT} @tab An open I/O unit number of type @code{INTEGER}.
5181 @item @var{VALUES} @tab The type shall be @code{INTEGER(4), DIMENSION(13)}.
5182 @item @var{STATUS} @tab (Optional) status flag of type @code{INTEGER(4)}. Returns 0
5183 on success and a system specific error code otherwise.
5186 @item @emph{Example}:
5187 See @ref{STAT} for an example.
5189 @item @emph{See also}:
5190 To stat a link: @ref{LSTAT}, to stat a file: @ref{STAT}
5196 @section @code{FTELL} --- Current stream position
5198 @cindex file operation, position
5201 @item @emph{Description}:
5202 Retrieves the current position within an open file.
5204 This intrinsic is provided in both subroutine and function forms; however,
5205 only one form can be used in any given program unit.
5207 @item @emph{Standard}:
5211 Subroutine, function
5213 @item @emph{Syntax}:
5214 @multitable @columnfractions .80
5215 @item @code{CALL FTELL(UNIT, OFFSET)}
5216 @item @code{OFFSET = FTELL(UNIT)}
5219 @item @emph{Arguments}:
5220 @multitable @columnfractions .15 .70
5221 @item @var{OFFSET} @tab Shall of type @code{INTEGER}.
5222 @item @var{UNIT} @tab Shall of type @code{INTEGER}.
5225 @item @emph{Return value}:
5226 In either syntax, @var{OFFSET} is set to the current offset of unit
5227 number @var{UNIT}, or to @math{-1} if the unit is not currently open.
5229 @item @emph{Example}:
5233 OPEN(10, FILE="temp.dat")
5239 @item @emph{See also}:
5246 @section @code{GAMMA} --- Gamma function
5249 @cindex Gamma function
5250 @cindex Factorial function
5253 @item @emph{Description}:
5254 @code{GAMMA(X)} computes Gamma (@math{\Gamma}) of @var{X}. For positive,
5255 integer values of @var{X} the Gamma function simplifies to the factorial
5256 function @math{\Gamma(x)=(x-1)!}.
5260 \Gamma(x) = \int_0^\infty t^{x-1}{\rm e}^{-t}\,{\rm d}t
5264 @item @emph{Standard}:
5265 Fortran 2008 and later
5270 @item @emph{Syntax}:
5273 @item @emph{Arguments}:
5274 @multitable @columnfractions .15 .70
5275 @item @var{X} @tab Shall be of type @code{REAL} and neither zero
5276 nor a negative integer.
5279 @item @emph{Return value}:
5280 The return value is of type @code{REAL} of the same kind as @var{X}.
5282 @item @emph{Example}:
5286 x = gamma(x) ! returns 1.0
5287 end program test_gamma
5290 @item @emph{Specific names}:
5291 @multitable @columnfractions .20 .20 .20 .25
5292 @item Name @tab Argument @tab Return type @tab Standard
5293 @item @code{GAMMA(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab GNU Extension
5294 @item @code{DGAMMA(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU Extension
5297 @item @emph{See also}:
5298 Logarithm of the Gamma function: @ref{LOG_GAMMA}
5305 @section @code{GERROR} --- Get last system error message
5307 @cindex system, error handling
5310 @item @emph{Description}:
5311 Returns the system error message corresponding to the last system error.
5312 This resembles the functionality of @code{strerror(3)} in C.
5314 @item @emph{Standard}:
5320 @item @emph{Syntax}:
5321 @code{CALL GERROR(RESULT)}
5323 @item @emph{Arguments}:
5324 @multitable @columnfractions .15 .70
5325 @item @var{RESULT} @tab Shall of type @code{CHARACTER} and of default
5328 @item @emph{Example}:
5331 CHARACTER(len=100) :: msg
5337 @item @emph{See also}:
5338 @ref{IERRNO}, @ref{PERROR}
5344 @section @code{GETARG} --- Get command line arguments
5346 @cindex command-line arguments
5347 @cindex arguments, to program
5350 @item @emph{Description}:
5351 Retrieve the @var{POS}-th argument that was passed on the
5352 command line when the containing program was invoked.
5354 This intrinsic routine is provided for backwards compatibility with
5355 GNU Fortran 77. In new code, programmers should consider the use of
5356 the @ref{GET_COMMAND_ARGUMENT} intrinsic defined by the Fortran 2003
5359 @item @emph{Standard}:
5365 @item @emph{Syntax}:
5366 @code{CALL GETARG(POS, VALUE)}
5368 @item @emph{Arguments}:
5369 @multitable @columnfractions .15 .70
5370 @item @var{POS} @tab Shall be of type @code{INTEGER} and not wider than
5371 the default integer kind; @math{@var{POS} \geq 0}
5372 @item @var{VALUE} @tab Shall be of type @code{CHARACTER} and of default
5374 @item @var{VALUE} @tab Shall be of type @code{CHARACTER}.
5377 @item @emph{Return value}:
5378 After @code{GETARG} returns, the @var{VALUE} argument holds the
5379 @var{POS}th command line argument. If @var{VALUE} can not hold the
5380 argument, it is truncated to fit the length of @var{VALUE}. If there are
5381 less than @var{POS} arguments specified at the command line, @var{VALUE}
5382 will be filled with blanks. If @math{@var{POS} = 0}, @var{VALUE} is set
5383 to the name of the program (on systems that support this feature).
5385 @item @emph{Example}:
5389 CHARACTER(len=32) :: arg
5398 @item @emph{See also}:
5399 GNU Fortran 77 compatibility function: @ref{IARGC}
5401 Fortran 2003 functions and subroutines: @ref{GET_COMMAND},
5402 @ref{GET_COMMAND_ARGUMENT}, @ref{COMMAND_ARGUMENT_COUNT}
5408 @section @code{GET_COMMAND} --- Get the entire command line
5409 @fnindex GET_COMMAND
5410 @cindex command-line arguments
5411 @cindex arguments, to program
5414 @item @emph{Description}:
5415 Retrieve the entire command line that was used to invoke the program.
5417 @item @emph{Standard}:
5418 Fortran 2003 and later
5423 @item @emph{Syntax}:
5424 @code{CALL GET_COMMAND([COMMAND, LENGTH, STATUS])}
5426 @item @emph{Arguments}:
5427 @multitable @columnfractions .15 .70
5428 @item @var{COMMAND} @tab (Optional) shall be of type @code{CHARACTER} and
5430 @item @var{LENGTH} @tab (Optional) Shall be of type @code{INTEGER} and of
5432 @item @var{STATUS} @tab (Optional) Shall be of type @code{INTEGER} and of
5436 @item @emph{Return value}:
5437 If @var{COMMAND} is present, stores the entire command line that was used
5438 to invoke the program in @var{COMMAND}. If @var{LENGTH} is present, it is
5439 assigned the length of the command line. If @var{STATUS} is present, it
5440 is assigned 0 upon success of the command, -1 if @var{COMMAND} is too
5441 short to store the command line, or a positive value in case of an error.
5443 @item @emph{Example}:
5445 PROGRAM test_get_command
5446 CHARACTER(len=255) :: cmd
5447 CALL get_command(cmd)
5448 WRITE (*,*) TRIM(cmd)
5452 @item @emph{See also}:
5453 @ref{GET_COMMAND_ARGUMENT}, @ref{COMMAND_ARGUMENT_COUNT}
5458 @node GET_COMMAND_ARGUMENT
5459 @section @code{GET_COMMAND_ARGUMENT} --- Get command line arguments
5460 @fnindex GET_COMMAND_ARGUMENT
5461 @cindex command-line arguments
5462 @cindex arguments, to program
5465 @item @emph{Description}:
5466 Retrieve the @var{NUMBER}-th argument that was passed on the
5467 command line when the containing program was invoked.
5469 @item @emph{Standard}:
5470 Fortran 2003 and later
5475 @item @emph{Syntax}:
5476 @code{CALL GET_COMMAND_ARGUMENT(NUMBER [, VALUE, LENGTH, STATUS])}
5478 @item @emph{Arguments}:
5479 @multitable @columnfractions .15 .70
5480 @item @var{NUMBER} @tab Shall be a scalar of type @code{INTEGER} and of
5481 default kind, @math{@var{NUMBER} \geq 0}
5482 @item @var{VALUE} @tab (Optional) Shall be a scalar of type @code{CHARACTER}
5483 and of default kind.
5484 @item @var{LENGTH} @tab (Optional) Shall be a scalar of type @code{INTEGER}
5485 and of default kind.
5486 @item @var{STATUS} @tab (Optional) Shall be a scalar of type @code{INTEGER}
5487 and of default kind.
5490 @item @emph{Return value}:
5491 After @code{GET_COMMAND_ARGUMENT} returns, the @var{VALUE} argument holds the
5492 @var{NUMBER}-th command line argument. If @var{VALUE} can not hold the argument, it is
5493 truncated to fit the length of @var{VALUE}. If there are less than @var{NUMBER}
5494 arguments specified at the command line, @var{VALUE} will be filled with blanks.
5495 If @math{@var{NUMBER} = 0}, @var{VALUE} is set to the name of the program (on
5496 systems that support this feature). The @var{LENGTH} argument contains the
5497 length of the @var{NUMBER}-th command line argument. If the argument retrieval
5498 fails, @var{STATUS} is a positive number; if @var{VALUE} contains a truncated
5499 command line argument, @var{STATUS} is -1; and otherwise the @var{STATUS} is
5502 @item @emph{Example}:
5504 PROGRAM test_get_command_argument
5506 CHARACTER(len=32) :: arg
5510 CALL get_command_argument(i, arg)
5511 IF (LEN_TRIM(arg) == 0) EXIT
5513 WRITE (*,*) TRIM(arg)
5519 @item @emph{See also}:
5520 @ref{GET_COMMAND}, @ref{COMMAND_ARGUMENT_COUNT}
5526 @section @code{GETCWD} --- Get current working directory
5528 @cindex system, working directory
5531 @item @emph{Description}:
5532 Get current working directory.
5534 This intrinsic is provided in both subroutine and function forms; however,
5535 only one form can be used in any given program unit.
5537 @item @emph{Standard}:
5541 Subroutine, function
5543 @item @emph{Syntax}:
5544 @multitable @columnfractions .80
5545 @item @code{CALL GETCWD(C [, STATUS])}
5546 @item @code{STATUS = GETCWD(C)}
5549 @item @emph{Arguments}:
5550 @multitable @columnfractions .15 .70
5551 @item @var{C} @tab The type shall be @code{CHARACTER} and of default kind.
5552 @item @var{STATUS} @tab (Optional) status flag. Returns 0 on success,
5553 a system specific and nonzero error code otherwise.
5556 @item @emph{Example}:
5559 CHARACTER(len=255) :: cwd
5561 WRITE(*,*) TRIM(cwd)
5565 @item @emph{See also}:
5572 @section @code{GETENV} --- Get an environmental variable
5574 @cindex environment variable
5577 @item @emph{Description}:
5578 Get the @var{VALUE} of the environmental variable @var{NAME}.
5580 This intrinsic routine is provided for backwards compatibility with
5581 GNU Fortran 77. In new code, programmers should consider the use of
5582 the @ref{GET_ENVIRONMENT_VARIABLE} intrinsic defined by the Fortran
5585 Note that @code{GETENV} need not be thread-safe. It is the
5586 responsibility of the user to ensure that the environment is not being
5587 updated concurrently with a call to the @code{GETENV} intrinsic.
5589 @item @emph{Standard}:
5595 @item @emph{Syntax}:
5596 @code{CALL GETENV(NAME, VALUE)}
5598 @item @emph{Arguments}:
5599 @multitable @columnfractions .15 .70
5600 @item @var{NAME} @tab Shall be of type @code{CHARACTER} and of default kind.
5601 @item @var{VALUE} @tab Shall be of type @code{CHARACTER} and of default kind.
5604 @item @emph{Return value}:
5605 Stores the value of @var{NAME} in @var{VALUE}. If @var{VALUE} is
5606 not large enough to hold the data, it is truncated. If @var{NAME}
5607 is not set, @var{VALUE} will be filled with blanks.
5609 @item @emph{Example}:
5612 CHARACTER(len=255) :: homedir
5613 CALL getenv("HOME", homedir)
5614 WRITE (*,*) TRIM(homedir)
5618 @item @emph{See also}:
5619 @ref{GET_ENVIRONMENT_VARIABLE}
5624 @node GET_ENVIRONMENT_VARIABLE
5625 @section @code{GET_ENVIRONMENT_VARIABLE} --- Get an environmental variable
5626 @fnindex GET_ENVIRONMENT_VARIABLE
5627 @cindex environment variable
5630 @item @emph{Description}:
5631 Get the @var{VALUE} of the environmental variable @var{NAME}.
5633 Note that @code{GET_ENVIRONMENT_VARIABLE} need not be thread-safe. It
5634 is the responsibility of the user to ensure that the environment is
5635 not being updated concurrently with a call to the
5636 @code{GET_ENVIRONMENT_VARIABLE} intrinsic.
5638 @item @emph{Standard}:
5639 Fortran 2003 and later
5644 @item @emph{Syntax}:
5645 @code{CALL GET_ENVIRONMENT_VARIABLE(NAME[, VALUE, LENGTH, STATUS, TRIM_NAME)}
5647 @item @emph{Arguments}:
5648 @multitable @columnfractions .15 .70
5649 @item @var{NAME} @tab Shall be a scalar of type @code{CHARACTER}
5650 and of default kind.
5651 @item @var{VALUE} @tab (Optional) Shall be a scalar of type @code{CHARACTER}
5652 and of default kind.
5653 @item @var{LENGTH} @tab (Optional) Shall be a scalar of type @code{INTEGER}
5654 and of default kind.
5655 @item @var{STATUS} @tab (Optional) Shall be a scalar of type @code{INTEGER}
5656 and of default kind.
5657 @item @var{TRIM_NAME} @tab (Optional) Shall be a scalar of type @code{LOGICAL}
5658 and of default kind.
5661 @item @emph{Return value}:
5662 Stores the value of @var{NAME} in @var{VALUE}. If @var{VALUE} is
5663 not large enough to hold the data, it is truncated. If @var{NAME}
5664 is not set, @var{VALUE} will be filled with blanks. Argument @var{LENGTH}
5665 contains the length needed for storing the environment variable @var{NAME}
5666 or zero if it is not present. @var{STATUS} is -1 if @var{VALUE} is present
5667 but too short for the environment variable; it is 1 if the environment
5668 variable does not exist and 2 if the processor does not support environment
5669 variables; in all other cases @var{STATUS} is zero. If @var{TRIM_NAME} is
5670 present with the value @code{.FALSE.}, the trailing blanks in @var{NAME}
5671 are significant; otherwise they are not part of the environment variable
5674 @item @emph{Example}:
5677 CHARACTER(len=255) :: homedir
5678 CALL get_environment_variable("HOME", homedir)
5679 WRITE (*,*) TRIM(homedir)
5687 @section @code{GETGID} --- Group ID function
5689 @cindex system, group ID
5692 @item @emph{Description}:
5693 Returns the numerical group ID of the current process.
5695 @item @emph{Standard}:
5701 @item @emph{Syntax}:
5702 @code{RESULT = GETGID()}
5704 @item @emph{Return value}:
5705 The return value of @code{GETGID} is an @code{INTEGER} of the default
5709 @item @emph{Example}:
5710 See @code{GETPID} for an example.
5712 @item @emph{See also}:
5713 @ref{GETPID}, @ref{GETUID}
5719 @section @code{GETLOG} --- Get login name
5721 @cindex system, login name
5725 @item @emph{Description}:
5726 Gets the username under which the program is running.
5728 @item @emph{Standard}:
5734 @item @emph{Syntax}:
5735 @code{CALL GETLOG(C)}
5737 @item @emph{Arguments}:
5738 @multitable @columnfractions .15 .70
5739 @item @var{C} @tab Shall be of type @code{CHARACTER} and of default kind.
5742 @item @emph{Return value}:
5743 Stores the current user name in @var{LOGIN}. (On systems where POSIX
5744 functions @code{geteuid} and @code{getpwuid} are not available, and
5745 the @code{getlogin} function is not implemented either, this will
5746 return a blank string.)
5748 @item @emph{Example}:
5751 CHARACTER(32) :: login
5757 @item @emph{See also}:
5764 @section @code{GETPID} --- Process ID function
5766 @cindex system, process ID
5770 @item @emph{Description}:
5771 Returns the numerical process identifier of the current process.
5773 @item @emph{Standard}:
5779 @item @emph{Syntax}:
5780 @code{RESULT = GETPID()}
5782 @item @emph{Return value}:
5783 The return value of @code{GETPID} is an @code{INTEGER} of the default
5787 @item @emph{Example}:
5790 print *, "The current process ID is ", getpid()
5791 print *, "Your numerical user ID is ", getuid()
5792 print *, "Your numerical group ID is ", getgid()
5796 @item @emph{See also}:
5797 @ref{GETGID}, @ref{GETUID}
5803 @section @code{GETUID} --- User ID function
5805 @cindex system, user ID
5809 @item @emph{Description}:
5810 Returns the numerical user ID of the current process.
5812 @item @emph{Standard}:
5818 @item @emph{Syntax}:
5819 @code{RESULT = GETUID()}
5821 @item @emph{Return value}:
5822 The return value of @code{GETUID} is an @code{INTEGER} of the default
5826 @item @emph{Example}:
5827 See @code{GETPID} for an example.
5829 @item @emph{See also}:
5830 @ref{GETPID}, @ref{GETLOG}
5836 @section @code{GMTIME} --- Convert time to GMT info
5838 @cindex time, conversion to GMT info
5841 @item @emph{Description}:
5842 Given a system time value @var{TIME} (as provided by the @code{TIME8}
5843 intrinsic), fills @var{VALUES} with values extracted from it appropriate
5844 to the UTC time zone (Universal Coordinated Time, also known in some
5845 countries as GMT, Greenwich Mean Time), using @code{gmtime(3)}.
5847 @item @emph{Standard}:
5853 @item @emph{Syntax}:
5854 @code{CALL GMTIME(TIME, VALUES)}
5856 @item @emph{Arguments}:
5857 @multitable @columnfractions .15 .70
5858 @item @var{TIME} @tab An @code{INTEGER} scalar expression
5859 corresponding to a system time, with @code{INTENT(IN)}.
5860 @item @var{VALUES} @tab A default @code{INTEGER} array with 9 elements,
5861 with @code{INTENT(OUT)}.
5864 @item @emph{Return value}:
5865 The elements of @var{VALUES} are assigned as follows:
5867 @item Seconds after the minute, range 0--59 or 0--61 to allow for leap
5869 @item Minutes after the hour, range 0--59
5870 @item Hours past midnight, range 0--23
5871 @item Day of month, range 0--31
5872 @item Number of months since January, range 0--12
5873 @item Years since 1900
5874 @item Number of days since Sunday, range 0--6
5875 @item Days since January 1
5876 @item Daylight savings indicator: positive if daylight savings is in
5877 effect, zero if not, and negative if the information is not available.
5880 @item @emph{See also}:
5881 @ref{CTIME}, @ref{LTIME}, @ref{TIME}, @ref{TIME8}
5888 @section @code{HOSTNM} --- Get system host name
5890 @cindex system, host name
5893 @item @emph{Description}:
5894 Retrieves the host name of the system on which the program is running.
5896 This intrinsic is provided in both subroutine and function forms; however,
5897 only one form can be used in any given program unit.
5899 @item @emph{Standard}:
5903 Subroutine, function
5905 @item @emph{Syntax}:
5906 @multitable @columnfractions .80
5907 @item @code{CALL HOSTNM(C [, STATUS])}
5908 @item @code{STATUS = HOSTNM(NAME)}
5911 @item @emph{Arguments}:
5912 @multitable @columnfractions .15 .70
5913 @item @var{C} @tab Shall of type @code{CHARACTER} and of default kind.
5914 @item @var{STATUS} @tab (Optional) status flag of type @code{INTEGER}.
5915 Returns 0 on success, or a system specific error code otherwise.
5918 @item @emph{Return value}:
5919 In either syntax, @var{NAME} is set to the current hostname if it can
5920 be obtained, or to a blank string otherwise.
5927 @section @code{HUGE} --- Largest number of a kind
5929 @cindex limits, largest number
5930 @cindex model representation, largest number
5933 @item @emph{Description}:
5934 @code{HUGE(X)} returns the largest number that is not an infinity in
5935 the model of the type of @code{X}.
5937 @item @emph{Standard}:
5938 Fortran 95 and later
5943 @item @emph{Syntax}:
5944 @code{RESULT = HUGE(X)}
5946 @item @emph{Arguments}:
5947 @multitable @columnfractions .15 .70
5948 @item @var{X} @tab Shall be of type @code{REAL} or @code{INTEGER}.
5951 @item @emph{Return value}:
5952 The return value is of the same type and kind as @var{X}
5954 @item @emph{Example}:
5956 program test_huge_tiny
5957 print *, huge(0), huge(0.0), huge(0.0d0)
5958 print *, tiny(0.0), tiny(0.0d0)
5959 end program test_huge_tiny
5966 @section @code{HYPOT} --- Euclidean distance function
5968 @cindex Euclidean distance
5971 @item @emph{Description}:
5972 @code{HYPOT(X,Y)} is the Euclidean distance function. It is equal to
5973 @math{\sqrt{X^2 + Y^2}}, without undue underflow or overflow.
5975 @item @emph{Standard}:
5976 Fortran 2008 and later
5981 @item @emph{Syntax}:
5982 @code{RESULT = HYPOT(X, Y)}
5984 @item @emph{Arguments}:
5985 @multitable @columnfractions .15 .70
5986 @item @var{X} @tab The type shall be @code{REAL}.
5987 @item @var{Y} @tab The type and kind type parameter shall be the same as
5991 @item @emph{Return value}:
5992 The return value has the same type and kind type parameter as @var{X}.
5994 @item @emph{Example}:
5997 real(4) :: x = 1.e0_4, y = 0.5e0_4
5999 end program test_hypot
6006 @section @code{IACHAR} --- Code in @acronym{ASCII} collating sequence
6008 @cindex @acronym{ASCII} collating sequence
6009 @cindex collating sequence, @acronym{ASCII}
6010 @cindex conversion, to integer
6013 @item @emph{Description}:
6014 @code{IACHAR(C)} returns the code for the @acronym{ASCII} character
6015 in the first character position of @code{C}.
6017 @item @emph{Standard}:
6018 Fortran 95 and later, with @var{KIND} argument Fortran 2003 and later
6023 @item @emph{Syntax}:
6024 @code{RESULT = IACHAR(C [, KIND])}
6026 @item @emph{Arguments}:
6027 @multitable @columnfractions .15 .70
6028 @item @var{C} @tab Shall be a scalar @code{CHARACTER}, with @code{INTENT(IN)}
6029 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
6030 expression indicating the kind parameter of the result.
6033 @item @emph{Return value}:
6034 The return value is of type @code{INTEGER} and of kind @var{KIND}. If
6035 @var{KIND} is absent, the return value is of default integer kind.
6037 @item @emph{Example}:
6042 end program test_iachar
6046 See @ref{ICHAR} for a discussion of converting between numerical values
6047 and formatted string representations.
6049 @item @emph{See also}:
6050 @ref{ACHAR}, @ref{CHAR}, @ref{ICHAR}
6057 @section @code{IALL} --- Bitwise AND of array elements
6060 @cindex bits, AND of array elements
6063 @item @emph{Description}:
6064 Reduces with bitwise AND the elements of @var{ARRAY} along dimension @var{DIM}
6065 if the corresponding element in @var{MASK} is @code{TRUE}.
6067 @item @emph{Standard}:
6068 Fortran 2008 and later
6071 Transformational function
6073 @item @emph{Syntax}:
6074 @multitable @columnfractions .80
6075 @item @code{RESULT = IALL(ARRAY[, MASK])}
6076 @item @code{RESULT = IALL(ARRAY, DIM[, MASK])}
6079 @item @emph{Arguments}:
6080 @multitable @columnfractions .15 .70
6081 @item @var{ARRAY} @tab Shall be an array of type @code{INTEGER}
6082 @item @var{DIM} @tab (Optional) shall be a scalar of type
6083 @code{INTEGER} with a value in the range from 1 to n, where n
6084 equals the rank of @var{ARRAY}.
6085 @item @var{MASK} @tab (Optional) shall be of type @code{LOGICAL}
6086 and either be a scalar or an array of the same shape as @var{ARRAY}.
6089 @item @emph{Return value}:
6090 The result is of the same type as @var{ARRAY}.
6092 If @var{DIM} is absent, a scalar with the bitwise ALL of all elements in
6093 @var{ARRAY} is returned. Otherwise, an array of rank n-1, where n equals
6094 the rank of @var{ARRAY}, and a shape similar to that of @var{ARRAY} with
6095 dimension @var{DIM} dropped is returned.
6097 @item @emph{Example}:
6106 PRINT '(b8.8)', IALL(a)
6110 @item @emph{See also}:
6111 @ref{IANY}, @ref{IPARITY}, @ref{IAND}
6117 @section @code{IAND} --- Bitwise logical and
6119 @cindex bitwise logical and
6120 @cindex logical and, bitwise
6123 @item @emph{Description}:
6124 Bitwise logical @code{AND}.
6126 @item @emph{Standard}:
6127 Fortran 95 and later
6132 @item @emph{Syntax}:
6133 @code{RESULT = IAND(I, J)}
6135 @item @emph{Arguments}:
6136 @multitable @columnfractions .15 .70
6137 @item @var{I} @tab The type shall be @code{INTEGER}.
6138 @item @var{J} @tab The type shall be @code{INTEGER}, of the same
6139 kind as @var{I}. (As a GNU extension, different kinds are also
6143 @item @emph{Return value}:
6144 The return type is @code{INTEGER}, of the same kind as the
6145 arguments. (If the argument kinds differ, it is of the same kind as
6146 the larger argument.)
6148 @item @emph{Example}:
6152 DATA a / Z'F' /, b / Z'3' /
6153 WRITE (*,*) IAND(a, b)
6157 @item @emph{See also}:
6158 @ref{IOR}, @ref{IEOR}, @ref{IBITS}, @ref{IBSET}, @ref{IBCLR}, @ref{NOT}
6165 @section @code{IANY} --- Bitwise OR of array elements
6168 @cindex bits, OR of array elements
6171 @item @emph{Description}:
6172 Reduces with bitwise OR (inclusive or) the elements of @var{ARRAY} along
6173 dimension @var{DIM} if the corresponding element in @var{MASK} is @code{TRUE}.
6175 @item @emph{Standard}:
6176 Fortran 2008 and later
6179 Transformational function
6181 @item @emph{Syntax}:
6182 @multitable @columnfractions .80
6183 @item @code{RESULT = IANY(ARRAY[, MASK])}
6184 @item @code{RESULT = IANY(ARRAY, DIM[, MASK])}
6187 @item @emph{Arguments}:
6188 @multitable @columnfractions .15 .70
6189 @item @var{ARRAY} @tab Shall be an array of type @code{INTEGER}
6190 @item @var{DIM} @tab (Optional) shall be a scalar of type
6191 @code{INTEGER} with a value in the range from 1 to n, where n
6192 equals the rank of @var{ARRAY}.
6193 @item @var{MASK} @tab (Optional) shall be of type @code{LOGICAL}
6194 and either be a scalar or an array of the same shape as @var{ARRAY}.
6197 @item @emph{Return value}:
6198 The result is of the same type as @var{ARRAY}.
6200 If @var{DIM} is absent, a scalar with the bitwise OR of all elements in
6201 @var{ARRAY} is returned. Otherwise, an array of rank n-1, where n equals
6202 the rank of @var{ARRAY}, and a shape similar to that of @var{ARRAY} with
6203 dimension @var{DIM} dropped is returned.
6205 @item @emph{Example}:
6214 PRINT '(b8.8)', IANY(a)
6218 @item @emph{See also}:
6219 @ref{IPARITY}, @ref{IALL}, @ref{IOR}
6225 @section @code{IARGC} --- Get the number of command line arguments
6227 @cindex command-line arguments
6228 @cindex command-line arguments, number of
6229 @cindex arguments, to program
6232 @item @emph{Description}:
6233 @code{IARGC} returns the number of arguments passed on the
6234 command line when the containing program was invoked.
6236 This intrinsic routine is provided for backwards compatibility with
6237 GNU Fortran 77. In new code, programmers should consider the use of
6238 the @ref{COMMAND_ARGUMENT_COUNT} intrinsic defined by the Fortran 2003
6241 @item @emph{Standard}:
6247 @item @emph{Syntax}:
6248 @code{RESULT = IARGC()}
6250 @item @emph{Arguments}:
6253 @item @emph{Return value}:
6254 The number of command line arguments, type @code{INTEGER(4)}.
6256 @item @emph{Example}:
6259 @item @emph{See also}:
6260 GNU Fortran 77 compatibility subroutine: @ref{GETARG}
6262 Fortran 2003 functions and subroutines: @ref{GET_COMMAND},
6263 @ref{GET_COMMAND_ARGUMENT}, @ref{COMMAND_ARGUMENT_COUNT}
6269 @section @code{IBCLR} --- Clear bit
6275 @item @emph{Description}:
6276 @code{IBCLR} returns the value of @var{I} with the bit at position
6277 @var{POS} set to zero.
6279 @item @emph{Standard}:
6280 Fortran 95 and later
6285 @item @emph{Syntax}:
6286 @code{RESULT = IBCLR(I, POS)}
6288 @item @emph{Arguments}:
6289 @multitable @columnfractions .15 .70
6290 @item @var{I} @tab The type shall be @code{INTEGER}.
6291 @item @var{POS} @tab The type shall be @code{INTEGER}.
6294 @item @emph{Return value}:
6295 The return value is of type @code{INTEGER} and of the same kind as
6298 @item @emph{See also}:
6299 @ref{IBITS}, @ref{IBSET}, @ref{IAND}, @ref{IOR}, @ref{IEOR}, @ref{MVBITS}
6306 @section @code{IBITS} --- Bit extraction
6309 @cindex bits, extract
6312 @item @emph{Description}:
6313 @code{IBITS} extracts a field of length @var{LEN} from @var{I},
6314 starting from bit position @var{POS} and extending left for @var{LEN}
6315 bits. The result is right-justified and the remaining bits are
6316 zeroed. The value of @code{POS+LEN} must be less than or equal to the
6317 value @code{BIT_SIZE(I)}.
6319 @item @emph{Standard}:
6320 Fortran 95 and later
6325 @item @emph{Syntax}:
6326 @code{RESULT = IBITS(I, POS, LEN)}
6328 @item @emph{Arguments}:
6329 @multitable @columnfractions .15 .70
6330 @item @var{I} @tab The type shall be @code{INTEGER}.
6331 @item @var{POS} @tab The type shall be @code{INTEGER}.
6332 @item @var{LEN} @tab The type shall be @code{INTEGER}.
6335 @item @emph{Return value}:
6336 The return value is of type @code{INTEGER} and of the same kind as
6339 @item @emph{See also}:
6340 @ref{BIT_SIZE}, @ref{IBCLR}, @ref{IBSET}, @ref{IAND}, @ref{IOR}, @ref{IEOR}
6346 @section @code{IBSET} --- Set bit
6351 @item @emph{Description}:
6352 @code{IBSET} returns the value of @var{I} with the bit at position
6353 @var{POS} set to one.
6355 @item @emph{Standard}:
6356 Fortran 95 and later
6361 @item @emph{Syntax}:
6362 @code{RESULT = IBSET(I, POS)}
6364 @item @emph{Arguments}:
6365 @multitable @columnfractions .15 .70
6366 @item @var{I} @tab The type shall be @code{INTEGER}.
6367 @item @var{POS} @tab The type shall be @code{INTEGER}.
6370 @item @emph{Return value}:
6371 The return value is of type @code{INTEGER} and of the same kind as
6374 @item @emph{See also}:
6375 @ref{IBCLR}, @ref{IBITS}, @ref{IAND}, @ref{IOR}, @ref{IEOR}, @ref{MVBITS}
6382 @section @code{ICHAR} --- Character-to-integer conversion function
6384 @cindex conversion, to integer
6387 @item @emph{Description}:
6388 @code{ICHAR(C)} returns the code for the character in the first character
6389 position of @code{C} in the system's native character set.
6390 The correspondence between characters and their codes is not necessarily
6391 the same across different GNU Fortran implementations.
6393 @item @emph{Standard}:
6394 Fortran 95 and later, with @var{KIND} argument Fortran 2003 and later
6399 @item @emph{Syntax}:
6400 @code{RESULT = ICHAR(C [, KIND])}
6402 @item @emph{Arguments}:
6403 @multitable @columnfractions .15 .70
6404 @item @var{C} @tab Shall be a scalar @code{CHARACTER}, with @code{INTENT(IN)}
6405 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
6406 expression indicating the kind parameter of the result.
6409 @item @emph{Return value}:
6410 The return value is of type @code{INTEGER} and of kind @var{KIND}. If
6411 @var{KIND} is absent, the return value is of default integer kind.
6413 @item @emph{Example}:
6418 end program test_ichar
6421 @item @emph{Specific names}:
6422 @multitable @columnfractions .20 .20 .20 .25
6423 @item Name @tab Argument @tab Return type @tab Standard
6424 @item @code{ICHAR(C)} @tab @code{CHARACTER C} @tab @code{INTEGER(4)} @tab Fortran 77 and later
6428 No intrinsic exists to convert between a numeric value and a formatted
6429 character string representation -- for instance, given the
6430 @code{CHARACTER} value @code{'154'}, obtaining an @code{INTEGER} or
6431 @code{REAL} value with the value 154, or vice versa. Instead, this
6432 functionality is provided by internal-file I/O, as in the following
6437 character(len=10) string, string2
6440 ! Convert a string to a numeric value
6441 read (string,'(I10)') value
6444 ! Convert a value to a formatted string
6445 write (string2,'(I10)') value
6447 end program read_val
6450 @item @emph{See also}:
6451 @ref{ACHAR}, @ref{CHAR}, @ref{IACHAR}
6458 @section @code{IDATE} --- Get current local time subroutine (day/month/year)
6460 @cindex date, current
6461 @cindex current date
6464 @item @emph{Description}:
6465 @code{IDATE(VALUES)} Fills @var{VALUES} with the numerical values at the
6466 current local time. The day (in the range 1-31), month (in the range 1-12),
6467 and year appear in elements 1, 2, and 3 of @var{VALUES}, respectively.
6468 The year has four significant digits.
6470 @item @emph{Standard}:
6476 @item @emph{Syntax}:
6477 @code{CALL IDATE(VALUES)}
6479 @item @emph{Arguments}:
6480 @multitable @columnfractions .15 .70
6481 @item @var{VALUES} @tab The type shall be @code{INTEGER, DIMENSION(3)} and
6482 the kind shall be the default integer kind.
6485 @item @emph{Return value}:
6486 Does not return anything.
6488 @item @emph{Example}:
6491 integer, dimension(3) :: tarray
6496 end program test_idate
6503 @section @code{IEOR} --- Bitwise logical exclusive or
6505 @cindex bitwise logical exclusive or
6506 @cindex logical exclusive or, bitwise
6509 @item @emph{Description}:
6510 @code{IEOR} returns the bitwise Boolean exclusive-OR of @var{I} and
6513 @item @emph{Standard}:
6514 Fortran 95 and later
6519 @item @emph{Syntax}:
6520 @code{RESULT = IEOR(I, J)}
6522 @item @emph{Arguments}:
6523 @multitable @columnfractions .15 .70
6524 @item @var{I} @tab The type shall be @code{INTEGER}.
6525 @item @var{J} @tab The type shall be @code{INTEGER}, of the same
6526 kind as @var{I}. (As a GNU extension, different kinds are also
6530 @item @emph{Return value}:
6531 The return type is @code{INTEGER}, of the same kind as the
6532 arguments. (If the argument kinds differ, it is of the same kind as
6533 the larger argument.)
6535 @item @emph{See also}:
6536 @ref{IOR}, @ref{IAND}, @ref{IBITS}, @ref{IBSET}, @ref{IBCLR}, @ref{NOT}
6542 @section @code{IERRNO} --- Get the last system error number
6544 @cindex system, error handling
6547 @item @emph{Description}:
6548 Returns the last system error number, as given by the C @code{errno}
6551 @item @emph{Standard}:
6557 @item @emph{Syntax}:
6558 @code{RESULT = IERRNO()}
6560 @item @emph{Arguments}:
6563 @item @emph{Return value}:
6564 The return value is of type @code{INTEGER} and of the default integer
6567 @item @emph{See also}:
6574 @section @code{IMAGE_INDEX} --- Function that converts a cosubscript to an image index
6575 @fnindex IMAGE_INDEX
6576 @cindex coarray, @code{IMAGE_INDEX}
6577 @cindex images, cosubscript to image index conversion
6580 @item @emph{Description}:
6581 Returns the image index belonging to a cosubscript.
6583 @item @emph{Standard}:
6584 Fortran 2008 and later
6589 @item @emph{Syntax}:
6590 @code{RESULT = IMAGE_INDEX(COARRAY, SUB)}
6592 @item @emph{Arguments}: None.
6593 @multitable @columnfractions .15 .70
6594 @item @var{COARRAY} @tab Coarray of any type.
6595 @item @var{SUB} @tab default integer rank-1 array of a size equal to
6596 the corank of @var{COARRAY}.
6600 @item @emph{Return value}:
6601 Scalar default integer with the value of the image index which corresponds
6602 to the cosubscripts. For invalid cosubscripts the result is zero.
6604 @item @emph{Example}:
6606 INTEGER :: array[2,-1:4,8,*]
6607 ! Writes 28 (or 0 if there are fewer than 28 images)
6608 WRITE (*,*) IMAGE_INDEX (array, [2,0,3,1])
6611 @item @emph{See also}:
6612 @ref{THIS_IMAGE}, @ref{NUM_IMAGES}
6617 @node INDEX intrinsic
6618 @section @code{INDEX} --- Position of a substring within a string
6620 @cindex substring position
6621 @cindex string, find substring
6624 @item @emph{Description}:
6625 Returns the position of the start of the first occurrence of string
6626 @var{SUBSTRING} as a substring in @var{STRING}, counting from one. If
6627 @var{SUBSTRING} is not present in @var{STRING}, zero is returned. If
6628 the @var{BACK} argument is present and true, the return value is the
6629 start of the last occurrence rather than the first.
6631 @item @emph{Standard}:
6632 Fortran 77 and later, with @var{KIND} argument Fortran 2003 and later
6637 @item @emph{Syntax}:
6638 @code{RESULT = INDEX(STRING, SUBSTRING [, BACK [, KIND]])}
6640 @item @emph{Arguments}:
6641 @multitable @columnfractions .15 .70
6642 @item @var{STRING} @tab Shall be a scalar @code{CHARACTER}, with
6644 @item @var{SUBSTRING} @tab Shall be a scalar @code{CHARACTER}, with
6646 @item @var{BACK} @tab (Optional) Shall be a scalar @code{LOGICAL}, with
6648 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
6649 expression indicating the kind parameter of the result.
6652 @item @emph{Return value}:
6653 The return value is of type @code{INTEGER} and of kind @var{KIND}. If
6654 @var{KIND} is absent, the return value is of default integer kind.
6656 @item @emph{Specific names}:
6657 @multitable @columnfractions .20 .20 .20 .25
6658 @item Name @tab Argument @tab Return type @tab Standard
6659 @item @code{INDEX(STRING, SUBSTRING)} @tab @code{CHARACTER} @tab @code{INTEGER(4)} @tab Fortran 77 and later
6662 @item @emph{See also}:
6663 @ref{SCAN}, @ref{VERIFY}
6669 @section @code{INT} --- Convert to integer type
6673 @cindex conversion, to integer
6676 @item @emph{Description}:
6677 Convert to integer type
6679 @item @emph{Standard}:
6680 Fortran 77 and later
6685 @item @emph{Syntax}:
6686 @code{RESULT = INT(A [, KIND))}
6688 @item @emph{Arguments}:
6689 @multitable @columnfractions .15 .70
6690 @item @var{A} @tab Shall be of type @code{INTEGER},
6691 @code{REAL}, or @code{COMPLEX}.
6692 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
6693 expression indicating the kind parameter of the result.
6696 @item @emph{Return value}:
6697 These functions return a @code{INTEGER} variable or array under
6698 the following rules:
6702 If @var{A} is of type @code{INTEGER}, @code{INT(A) = A}
6704 If @var{A} is of type @code{REAL} and @math{|A| < 1}, @code{INT(A)} equals @code{0}.
6705 If @math{|A| \geq 1}, then @code{INT(A)} equals the largest integer that does not exceed
6706 the range of @var{A} and whose sign is the same as the sign of @var{A}.
6708 If @var{A} is of type @code{COMPLEX}, rule B is applied to the real part of @var{A}.
6711 @item @emph{Example}:
6715 complex :: z = (-3.7, 1.0)
6717 print *, int(z), int(z,8)
6721 @item @emph{Specific names}:
6722 @multitable @columnfractions .20 .20 .20 .25
6723 @item Name @tab Argument @tab Return type @tab Standard
6724 @item @code{INT(A)} @tab @code{REAL(4) A} @tab @code{INTEGER} @tab Fortran 77 and later
6725 @item @code{IFIX(A)} @tab @code{REAL(4) A} @tab @code{INTEGER} @tab Fortran 77 and later
6726 @item @code{IDINT(A)} @tab @code{REAL(8) A} @tab @code{INTEGER} @tab Fortran 77 and later
6733 @section @code{INT2} --- Convert to 16-bit integer type
6736 @cindex conversion, to integer
6739 @item @emph{Description}:
6740 Convert to a @code{KIND=2} integer type. This is equivalent to the
6741 standard @code{INT} intrinsic with an optional argument of
6742 @code{KIND=2}, and is only included for backwards compatibility.
6744 The @code{SHORT} intrinsic is equivalent to @code{INT2}.
6746 @item @emph{Standard}:
6752 @item @emph{Syntax}:
6753 @code{RESULT = INT2(A)}
6755 @item @emph{Arguments}:
6756 @multitable @columnfractions .15 .70
6757 @item @var{A} @tab Shall be of type @code{INTEGER},
6758 @code{REAL}, or @code{COMPLEX}.
6761 @item @emph{Return value}:
6762 The return value is a @code{INTEGER(2)} variable.
6764 @item @emph{See also}:
6765 @ref{INT}, @ref{INT8}, @ref{LONG}
6771 @section @code{INT8} --- Convert to 64-bit integer type
6773 @cindex conversion, to integer
6776 @item @emph{Description}:
6777 Convert to a @code{KIND=8} integer type. This is equivalent to the
6778 standard @code{INT} intrinsic with an optional argument of
6779 @code{KIND=8}, and is only included for backwards compatibility.
6781 @item @emph{Standard}:
6787 @item @emph{Syntax}:
6788 @code{RESULT = INT8(A)}
6790 @item @emph{Arguments}:
6791 @multitable @columnfractions .15 .70
6792 @item @var{A} @tab Shall be of type @code{INTEGER},
6793 @code{REAL}, or @code{COMPLEX}.
6796 @item @emph{Return value}:
6797 The return value is a @code{INTEGER(8)} variable.
6799 @item @emph{See also}:
6800 @ref{INT}, @ref{INT2}, @ref{LONG}
6806 @section @code{IOR} --- Bitwise logical or
6808 @cindex bitwise logical or
6809 @cindex logical or, bitwise
6812 @item @emph{Description}:
6813 @code{IOR} returns the bitwise Boolean inclusive-OR of @var{I} and
6816 @item @emph{Standard}:
6817 Fortran 95 and later
6822 @item @emph{Syntax}:
6823 @code{RESULT = IOR(I, J)}
6825 @item @emph{Arguments}:
6826 @multitable @columnfractions .15 .70
6827 @item @var{I} @tab The type shall be @code{INTEGER}.
6828 @item @var{J} @tab The type shall be @code{INTEGER}, of the same
6829 kind as @var{I}. (As a GNU extension, different kinds are also
6833 @item @emph{Return value}:
6834 The return type is @code{INTEGER}, of the same kind as the
6835 arguments. (If the argument kinds differ, it is of the same kind as
6836 the larger argument.)
6838 @item @emph{See also}:
6839 @ref{IEOR}, @ref{IAND}, @ref{IBITS}, @ref{IBSET}, @ref{IBCLR}, @ref{NOT}
6845 @section @code{IPARITY} --- Bitwise XOR of array elements
6847 @cindex array, parity
6849 @cindex bits, XOR of array elements
6852 @item @emph{Description}:
6853 Reduces with bitwise XOR (exclusive or) the elements of @var{ARRAY} along
6854 dimension @var{DIM} if the corresponding element in @var{MASK} is @code{TRUE}.
6856 @item @emph{Standard}:
6857 Fortran 2008 and later
6860 Transformational function
6862 @item @emph{Syntax}:
6863 @multitable @columnfractions .80
6864 @item @code{RESULT = IPARITY(ARRAY[, MASK])}
6865 @item @code{RESULT = IPARITY(ARRAY, DIM[, MASK])}
6868 @item @emph{Arguments}:
6869 @multitable @columnfractions .15 .70
6870 @item @var{ARRAY} @tab Shall be an array of type @code{INTEGER}
6871 @item @var{DIM} @tab (Optional) shall be a scalar of type
6872 @code{INTEGER} with a value in the range from 1 to n, where n
6873 equals the rank of @var{ARRAY}.
6874 @item @var{MASK} @tab (Optional) shall be of type @code{LOGICAL}
6875 and either be a scalar or an array of the same shape as @var{ARRAY}.
6878 @item @emph{Return value}:
6879 The result is of the same type as @var{ARRAY}.
6881 If @var{DIM} is absent, a scalar with the bitwise XOR of all elements in
6882 @var{ARRAY} is returned. Otherwise, an array of rank n-1, where n equals
6883 the rank of @var{ARRAY}, and a shape similar to that of @var{ARRAY} with
6884 dimension @var{DIM} dropped is returned.
6886 @item @emph{Example}:
6888 PROGRAM test_iparity
6895 PRINT '(b8.8)', IPARITY(a)
6899 @item @emph{See also}:
6900 @ref{IANY}, @ref{IALL}, @ref{IEOR}, @ref{PARITY}
6906 @section @code{IRAND} --- Integer pseudo-random number
6908 @cindex random number generation
6911 @item @emph{Description}:
6912 @code{IRAND(FLAG)} returns a pseudo-random number from a uniform
6913 distribution between 0 and a system-dependent limit (which is in most
6914 cases 2147483647). If @var{FLAG} is 0, the next number
6915 in the current sequence is returned; if @var{FLAG} is 1, the generator
6916 is restarted by @code{CALL SRAND(0)}; if @var{FLAG} has any other value,
6917 it is used as a new seed with @code{SRAND}.
6919 This intrinsic routine is provided for backwards compatibility with
6920 GNU Fortran 77. It implements a simple modulo generator as provided
6921 by @command{g77}. For new code, one should consider the use of
6922 @ref{RANDOM_NUMBER} as it implements a superior algorithm.
6924 @item @emph{Standard}:
6930 @item @emph{Syntax}:
6931 @code{RESULT = IRAND(I)}
6933 @item @emph{Arguments}:
6934 @multitable @columnfractions .15 .70
6935 @item @var{I} @tab Shall be a scalar @code{INTEGER} of kind 4.
6938 @item @emph{Return value}:
6939 The return value is of @code{INTEGER(kind=4)} type.
6941 @item @emph{Example}:
6944 integer,parameter :: seed = 86456
6947 print *, irand(), irand(), irand(), irand()
6948 print *, irand(seed), irand(), irand(), irand()
6949 end program test_irand
6957 @section @code{IS_IOSTAT_END} --- Test for end-of-file value
6958 @fnindex IS_IOSTAT_END
6959 @cindex @code{IOSTAT}, end of file
6962 @item @emph{Description}:
6963 @code{IS_IOSTAT_END} tests whether an variable has the value of the I/O
6964 status ``end of file''. The function is equivalent to comparing the variable
6965 with the @code{IOSTAT_END} parameter of the intrinsic module
6966 @code{ISO_FORTRAN_ENV}.
6968 @item @emph{Standard}:
6969 Fortran 2003 and later
6974 @item @emph{Syntax}:
6975 @code{RESULT = IS_IOSTAT_END(I)}
6977 @item @emph{Arguments}:
6978 @multitable @columnfractions .15 .70
6979 @item @var{I} @tab Shall be of the type @code{INTEGER}.
6982 @item @emph{Return value}:
6983 Returns a @code{LOGICAL} of the default kind, which @code{.TRUE.} if
6984 @var{I} has the value which indicates an end of file condition for
6985 @code{IOSTAT=} specifiers, and is @code{.FALSE.} otherwise.
6987 @item @emph{Example}:
6992 OPEN(88, FILE='test.dat')
6993 READ(88, *, IOSTAT=stat) i
6994 IF(IS_IOSTAT_END(stat)) STOP 'END OF FILE'
7002 @section @code{IS_IOSTAT_EOR} --- Test for end-of-record value
7003 @fnindex IS_IOSTAT_EOR
7004 @cindex @code{IOSTAT}, end of record
7007 @item @emph{Description}:
7008 @code{IS_IOSTAT_EOR} tests whether an variable has the value of the I/O
7009 status ``end of record''. The function is equivalent to comparing the
7010 variable with the @code{IOSTAT_EOR} parameter of the intrinsic module
7011 @code{ISO_FORTRAN_ENV}.
7013 @item @emph{Standard}:
7014 Fortran 2003 and later
7019 @item @emph{Syntax}:
7020 @code{RESULT = IS_IOSTAT_EOR(I)}
7022 @item @emph{Arguments}:
7023 @multitable @columnfractions .15 .70
7024 @item @var{I} @tab Shall be of the type @code{INTEGER}.
7027 @item @emph{Return value}:
7028 Returns a @code{LOGICAL} of the default kind, which @code{.TRUE.} if
7029 @var{I} has the value which indicates an end of file condition for
7030 @code{IOSTAT=} specifiers, and is @code{.FALSE.} otherwise.
7032 @item @emph{Example}:
7036 INTEGER :: stat, i(50)
7037 OPEN(88, FILE='test.dat', FORM='UNFORMATTED')
7038 READ(88, IOSTAT=stat) i
7039 IF(IS_IOSTAT_EOR(stat)) STOP 'END OF RECORD'
7047 @section @code{ISATTY} --- Whether a unit is a terminal device.
7049 @cindex system, terminal
7052 @item @emph{Description}:
7053 Determine whether a unit is connected to a terminal device.
7055 @item @emph{Standard}:
7061 @item @emph{Syntax}:
7062 @code{RESULT = ISATTY(UNIT)}
7064 @item @emph{Arguments}:
7065 @multitable @columnfractions .15 .70
7066 @item @var{UNIT} @tab Shall be a scalar @code{INTEGER}.
7069 @item @emph{Return value}:
7070 Returns @code{.TRUE.} if the @var{UNIT} is connected to a terminal
7071 device, @code{.FALSE.} otherwise.
7073 @item @emph{Example}:
7076 INTEGER(kind=1) :: unit
7078 write(*,*) isatty(unit=unit)
7082 @item @emph{See also}:
7089 @section @code{ISHFT} --- Shift bits
7094 @item @emph{Description}:
7095 @code{ISHFT} returns a value corresponding to @var{I} with all of the
7096 bits shifted @var{SHIFT} places. A value of @var{SHIFT} greater than
7097 zero corresponds to a left shift, a value of zero corresponds to no
7098 shift, and a value less than zero corresponds to a right shift. If the
7099 absolute value of @var{SHIFT} is greater than @code{BIT_SIZE(I)}, the
7100 value is undefined. Bits shifted out from the left end or right end are
7101 lost; zeros are shifted in from the opposite end.
7103 @item @emph{Standard}:
7104 Fortran 95 and later
7109 @item @emph{Syntax}:
7110 @code{RESULT = ISHFT(I, SHIFT)}
7112 @item @emph{Arguments}:
7113 @multitable @columnfractions .15 .70
7114 @item @var{I} @tab The type shall be @code{INTEGER}.
7115 @item @var{SHIFT} @tab The type shall be @code{INTEGER}.
7118 @item @emph{Return value}:
7119 The return value is of type @code{INTEGER} and of the same kind as
7122 @item @emph{See also}:
7129 @section @code{ISHFTC} --- Shift bits circularly
7131 @cindex bits, shift circular
7134 @item @emph{Description}:
7135 @code{ISHFTC} returns a value corresponding to @var{I} with the
7136 rightmost @var{SIZE} bits shifted circularly @var{SHIFT} places; that
7137 is, bits shifted out one end are shifted into the opposite end. A value
7138 of @var{SHIFT} greater than zero corresponds to a left shift, a value of
7139 zero corresponds to no shift, and a value less than zero corresponds to
7140 a right shift. The absolute value of @var{SHIFT} must be less than
7141 @var{SIZE}. If the @var{SIZE} argument is omitted, it is taken to be
7142 equivalent to @code{BIT_SIZE(I)}.
7144 @item @emph{Standard}:
7145 Fortran 95 and later
7150 @item @emph{Syntax}:
7151 @code{RESULT = ISHFTC(I, SHIFT [, SIZE])}
7153 @item @emph{Arguments}:
7154 @multitable @columnfractions .15 .70
7155 @item @var{I} @tab The type shall be @code{INTEGER}.
7156 @item @var{SHIFT} @tab The type shall be @code{INTEGER}.
7157 @item @var{SIZE} @tab (Optional) The type shall be @code{INTEGER};
7158 the value must be greater than zero and less than or equal to
7162 @item @emph{Return value}:
7163 The return value is of type @code{INTEGER} and of the same kind as
7166 @item @emph{See also}:
7173 @section @code{ISNAN} --- Test for a NaN
7178 @item @emph{Description}:
7179 @code{ISNAN} tests whether a floating-point value is an IEEE
7181 @item @emph{Standard}:
7187 @item @emph{Syntax}:
7190 @item @emph{Arguments}:
7191 @multitable @columnfractions .15 .70
7192 @item @var{X} @tab Variable of the type @code{REAL}.
7196 @item @emph{Return value}:
7197 Returns a default-kind @code{LOGICAL}. The returned value is @code{TRUE}
7198 if @var{X} is a NaN and @code{FALSE} otherwise.
7200 @item @emph{Example}:
7207 if (isnan(x)) stop '"x" is a NaN'
7208 end program test_nan
7215 @section @code{ITIME} --- Get current local time subroutine (hour/minutes/seconds)
7217 @cindex time, current
7218 @cindex current time
7221 @item @emph{Description}:
7222 @code{IDATE(VALUES)} Fills @var{VALUES} with the numerical values at the
7223 current local time. The hour (in the range 1-24), minute (in the range 1-60),
7224 and seconds (in the range 1-60) appear in elements 1, 2, and 3 of @var{VALUES},
7227 @item @emph{Standard}:
7233 @item @emph{Syntax}:
7234 @code{CALL ITIME(VALUES)}
7236 @item @emph{Arguments}:
7237 @multitable @columnfractions .15 .70
7238 @item @var{VALUES} @tab The type shall be @code{INTEGER, DIMENSION(3)}
7239 and the kind shall be the default integer kind.
7242 @item @emph{Return value}:
7243 Does not return anything.
7246 @item @emph{Example}:
7249 integer, dimension(3) :: tarray
7254 end program test_itime
7261 @section @code{KILL} --- Send a signal to a process
7265 @item @emph{Description}:
7266 @item @emph{Standard}:
7267 Sends the signal specified by @var{SIGNAL} to the process @var{PID}.
7270 This intrinsic is provided in both subroutine and function forms; however,
7271 only one form can be used in any given program unit.
7274 Subroutine, function
7276 @item @emph{Syntax}:
7277 @multitable @columnfractions .80
7278 @item @code{CALL KILL(C, VALUE [, STATUS])}
7279 @item @code{STATUS = KILL(C, VALUE)}
7282 @item @emph{Arguments}:
7283 @multitable @columnfractions .15 .70
7284 @item @var{C} @tab Shall be a scalar @code{INTEGER}, with
7286 @item @var{VALUE} @tab Shall be a scalar @code{INTEGER}, with
7288 @item @var{STATUS} @tab (Optional) status flag of type @code{INTEGER(4)} or
7289 @code{INTEGER(8)}. Returns 0 on success, or a system-specific error code
7293 @item @emph{See also}:
7294 @ref{ABORT}, @ref{EXIT}
7300 @section @code{KIND} --- Kind of an entity
7305 @item @emph{Description}:
7306 @code{KIND(X)} returns the kind value of the entity @var{X}.
7308 @item @emph{Standard}:
7309 Fortran 95 and later
7314 @item @emph{Syntax}:
7317 @item @emph{Arguments}:
7318 @multitable @columnfractions .15 .70
7319 @item @var{X} @tab Shall be of type @code{LOGICAL}, @code{INTEGER},
7320 @code{REAL}, @code{COMPLEX} or @code{CHARACTER}.
7323 @item @emph{Return value}:
7324 The return value is a scalar of type @code{INTEGER} and of the default
7327 @item @emph{Example}:
7330 integer,parameter :: kc = kind(' ')
7331 integer,parameter :: kl = kind(.true.)
7333 print *, "The default character kind is ", kc
7334 print *, "The default logical kind is ", kl
7335 end program test_kind
7343 @section @code{LBOUND} --- Lower dimension bounds of an array
7345 @cindex array, lower bound
7348 @item @emph{Description}:
7349 Returns the lower bounds of an array, or a single lower bound
7350 along the @var{DIM} dimension.
7351 @item @emph{Standard}:
7352 Fortran 95 and later, with @var{KIND} argument Fortran 2003 and later
7357 @item @emph{Syntax}:
7358 @code{RESULT = LBOUND(ARRAY [, DIM [, KIND]])}
7360 @item @emph{Arguments}:
7361 @multitable @columnfractions .15 .70
7362 @item @var{ARRAY} @tab Shall be an array, of any type.
7363 @item @var{DIM} @tab (Optional) Shall be a scalar @code{INTEGER}.
7364 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
7365 expression indicating the kind parameter of the result.
7368 @item @emph{Return value}:
7369 The return value is of type @code{INTEGER} and of kind @var{KIND}. If
7370 @var{KIND} is absent, the return value is of default integer kind.
7371 If @var{DIM} is absent, the result is an array of the lower bounds of
7372 @var{ARRAY}. If @var{DIM} is present, the result is a scalar
7373 corresponding to the lower bound of the array along that dimension. If
7374 @var{ARRAY} is an expression rather than a whole array or array
7375 structure component, or if it has a zero extent along the relevant
7376 dimension, the lower bound is taken to be 1.
7378 @item @emph{See also}:
7379 @ref{UBOUND}, @ref{LCOBOUND}
7385 @section @code{LCOBOUND} --- Lower codimension bounds of an array
7387 @cindex coarray, lower bound
7390 @item @emph{Description}:
7391 Returns the lower bounds of a coarray, or a single lower cobound
7392 along the @var{DIM} codimension.
7393 @item @emph{Standard}:
7394 Fortran 2008 and later
7399 @item @emph{Syntax}:
7400 @code{RESULT = LCOBOUND(COARRAY [, DIM [, KIND]])}
7402 @item @emph{Arguments}:
7403 @multitable @columnfractions .15 .70
7404 @item @var{ARRAY} @tab Shall be an coarray, of any type.
7405 @item @var{DIM} @tab (Optional) Shall be a scalar @code{INTEGER}.
7406 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
7407 expression indicating the kind parameter of the result.
7410 @item @emph{Return value}:
7411 The return value is of type @code{INTEGER} and of kind @var{KIND}. If
7412 @var{KIND} is absent, the return value is of default integer kind.
7413 If @var{DIM} is absent, the result is an array of the lower cobounds of
7414 @var{COARRAY}. If @var{DIM} is present, the result is a scalar
7415 corresponding to the lower cobound of the array along that codimension.
7417 @item @emph{See also}:
7418 @ref{UCOBOUND}, @ref{LBOUND}
7424 @section @code{LEADZ} --- Number of leading zero bits of an integer
7429 @item @emph{Description}:
7430 @code{LEADZ} returns the number of leading zero bits of an integer.
7432 @item @emph{Standard}:
7433 Fortran 2008 and later
7438 @item @emph{Syntax}:
7439 @code{RESULT = LEADZ(I)}
7441 @item @emph{Arguments}:
7442 @multitable @columnfractions .15 .70
7443 @item @var{I} @tab Shall be of type @code{INTEGER}.
7446 @item @emph{Return value}:
7447 The type of the return value is the default @code{INTEGER}.
7448 If all the bits of @code{I} are zero, the result value is @code{BIT_SIZE(I)}.
7450 @item @emph{Example}:
7453 WRITE (*,*) BIT_SIZE(1) ! prints 32
7454 WRITE (*,*) LEADZ(1) ! prints 31
7458 @item @emph{See also}:
7459 @ref{BIT_SIZE}, @ref{TRAILZ}, @ref{POPCNT}, @ref{POPPAR}
7465 @section @code{LEN} --- Length of a character entity
7467 @cindex string, length
7470 @item @emph{Description}:
7471 Returns the length of a character string. If @var{STRING} is an array,
7472 the length of an element of @var{STRING} is returned. Note that
7473 @var{STRING} need not be defined when this intrinsic is invoked, since
7474 only the length, not the content, of @var{STRING} is needed.
7476 @item @emph{Standard}:
7477 Fortran 77 and later, with @var{KIND} argument Fortran 2003 and later
7482 @item @emph{Syntax}:
7483 @code{L = LEN(STRING [, KIND])}
7485 @item @emph{Arguments}:
7486 @multitable @columnfractions .15 .70
7487 @item @var{STRING} @tab Shall be a scalar or array of type
7488 @code{CHARACTER}, with @code{INTENT(IN)}
7489 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
7490 expression indicating the kind parameter of the result.
7493 @item @emph{Return value}:
7494 The return value is of type @code{INTEGER} and of kind @var{KIND}. If
7495 @var{KIND} is absent, the return value is of default integer kind.
7498 @item @emph{Specific names}:
7499 @multitable @columnfractions .20 .20 .20 .25
7500 @item Name @tab Argument @tab Return type @tab Standard
7501 @item @code{LEN(STRING)} @tab @code{CHARACTER} @tab @code{INTEGER} @tab Fortran 77 and later
7505 @item @emph{See also}:
7506 @ref{LEN_TRIM}, @ref{ADJUSTL}, @ref{ADJUSTR}
7512 @section @code{LEN_TRIM} --- Length of a character entity without trailing blank characters
7514 @cindex string, length, without trailing whitespace
7517 @item @emph{Description}:
7518 Returns the length of a character string, ignoring any trailing blanks.
7520 @item @emph{Standard}:
7521 Fortran 95 and later, with @var{KIND} argument Fortran 2003 and later
7526 @item @emph{Syntax}:
7527 @code{RESULT = LEN_TRIM(STRING [, KIND])}
7529 @item @emph{Arguments}:
7530 @multitable @columnfractions .15 .70
7531 @item @var{STRING} @tab Shall be a scalar of type @code{CHARACTER},
7532 with @code{INTENT(IN)}
7533 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
7534 expression indicating the kind parameter of the result.
7537 @item @emph{Return value}:
7538 The return value is of type @code{INTEGER} and of kind @var{KIND}. If
7539 @var{KIND} is absent, the return value is of default integer kind.
7541 @item @emph{See also}:
7542 @ref{LEN}, @ref{ADJUSTL}, @ref{ADJUSTR}
7548 @section @code{LGE} --- Lexical greater than or equal
7550 @cindex lexical comparison of strings
7551 @cindex string, comparison
7554 @item @emph{Description}:
7555 Determines whether one string is lexically greater than or equal to
7556 another string, where the two strings are interpreted as containing
7557 ASCII character codes. If the String A and String B are not the same
7558 length, the shorter is compared as if spaces were appended to it to form
7559 a value that has the same length as the longer.
7561 In general, the lexical comparison intrinsics @code{LGE}, @code{LGT},
7562 @code{LLE}, and @code{LLT} differ from the corresponding intrinsic
7563 operators @code{.GE.}, @code{.GT.}, @code{.LE.}, and @code{.LT.}, in
7564 that the latter use the processor's character ordering (which is not
7565 ASCII on some targets), whereas the former always use the ASCII
7568 @item @emph{Standard}:
7569 Fortran 77 and later
7574 @item @emph{Syntax}:
7575 @code{RESULT = LGE(STRING_A, STRING_B)}
7577 @item @emph{Arguments}:
7578 @multitable @columnfractions .15 .70
7579 @item @var{STRING_A} @tab Shall be of default @code{CHARACTER} type.
7580 @item @var{STRING_B} @tab Shall be of default @code{CHARACTER} type.
7583 @item @emph{Return value}:
7584 Returns @code{.TRUE.} if @code{STRING_A >= STRING_B}, and @code{.FALSE.}
7585 otherwise, based on the ASCII ordering.
7587 @item @emph{Specific names}:
7588 @multitable @columnfractions .20 .20 .20 .25
7589 @item Name @tab Argument @tab Return type @tab Standard
7590 @item @code{LGE(STRING_A, STRING_B)} @tab @code{CHARACTER} @tab @code{LOGICAL} @tab Fortran 77 and later
7593 @item @emph{See also}:
7594 @ref{LGT}, @ref{LLE}, @ref{LLT}
7600 @section @code{LGT} --- Lexical greater than
7602 @cindex lexical comparison of strings
7603 @cindex string, comparison
7606 @item @emph{Description}:
7607 Determines whether one string is lexically greater than another string,
7608 where the two strings are interpreted as containing ASCII character
7609 codes. If the String A and String B are not the same length, the
7610 shorter is compared as if spaces were appended to it to form a value
7611 that has the same length as the longer.
7613 In general, the lexical comparison intrinsics @code{LGE}, @code{LGT},
7614 @code{LLE}, and @code{LLT} differ from the corresponding intrinsic
7615 operators @code{.GE.}, @code{.GT.}, @code{.LE.}, and @code{.LT.}, in
7616 that the latter use the processor's character ordering (which is not
7617 ASCII on some targets), whereas the former always use the ASCII
7620 @item @emph{Standard}:
7621 Fortran 77 and later
7626 @item @emph{Syntax}:
7627 @code{RESULT = LGT(STRING_A, STRING_B)}
7629 @item @emph{Arguments}:
7630 @multitable @columnfractions .15 .70
7631 @item @var{STRING_A} @tab Shall be of default @code{CHARACTER} type.
7632 @item @var{STRING_B} @tab Shall be of default @code{CHARACTER} type.
7635 @item @emph{Return value}:
7636 Returns @code{.TRUE.} if @code{STRING_A > STRING_B}, and @code{.FALSE.}
7637 otherwise, based on the ASCII ordering.
7639 @item @emph{Specific names}:
7640 @multitable @columnfractions .20 .20 .20 .25
7641 @item Name @tab Argument @tab Return type @tab Standard
7642 @item @code{LGT(STRING_A, STRING_B)} @tab @code{CHARACTER} @tab @code{LOGICAL} @tab Fortran 77 and later
7645 @item @emph{See also}:
7646 @ref{LGE}, @ref{LLE}, @ref{LLT}
7652 @section @code{LINK} --- Create a hard link
7654 @cindex file system, create link
7655 @cindex file system, hard link
7658 @item @emph{Description}:
7659 Makes a (hard) link from file @var{PATH1} to @var{PATH2}. A null
7660 character (@code{CHAR(0)}) can be used to mark the end of the names in
7661 @var{PATH1} and @var{PATH2}; otherwise, trailing blanks in the file
7662 names are ignored. If the @var{STATUS} argument is supplied, it
7663 contains 0 on success or a nonzero error code upon return; see
7666 This intrinsic is provided in both subroutine and function forms;
7667 however, only one form can be used in any given program unit.
7669 @item @emph{Standard}:
7673 Subroutine, function
7675 @item @emph{Syntax}:
7676 @multitable @columnfractions .80
7677 @item @code{CALL LINK(PATH1, PATH2 [, STATUS])}
7678 @item @code{STATUS = LINK(PATH1, PATH2)}
7681 @item @emph{Arguments}:
7682 @multitable @columnfractions .15 .70
7683 @item @var{PATH1} @tab Shall be of default @code{CHARACTER} type.
7684 @item @var{PATH2} @tab Shall be of default @code{CHARACTER} type.
7685 @item @var{STATUS} @tab (Optional) Shall be of default @code{INTEGER} type.
7688 @item @emph{See also}:
7689 @ref{SYMLNK}, @ref{UNLINK}
7695 @section @code{LLE} --- Lexical less than or equal
7697 @cindex lexical comparison of strings
7698 @cindex string, comparison
7701 @item @emph{Description}:
7702 Determines whether one string is lexically less than or equal to another
7703 string, where the two strings are interpreted as containing ASCII
7704 character codes. If the String A and String B are not the same length,
7705 the shorter is compared as if spaces were appended to it to form a value
7706 that has the same length as the longer.
7708 In general, the lexical comparison intrinsics @code{LGE}, @code{LGT},
7709 @code{LLE}, and @code{LLT} differ from the corresponding intrinsic
7710 operators @code{.GE.}, @code{.GT.}, @code{.LE.}, and @code{.LT.}, in
7711 that the latter use the processor's character ordering (which is not
7712 ASCII on some targets), whereas the former always use the ASCII
7715 @item @emph{Standard}:
7716 Fortran 77 and later
7721 @item @emph{Syntax}:
7722 @code{RESULT = LLE(STRING_A, STRING_B)}
7724 @item @emph{Arguments}:
7725 @multitable @columnfractions .15 .70
7726 @item @var{STRING_A} @tab Shall be of default @code{CHARACTER} type.
7727 @item @var{STRING_B} @tab Shall be of default @code{CHARACTER} type.
7730 @item @emph{Return value}:
7731 Returns @code{.TRUE.} if @code{STRING_A <= STRING_B}, and @code{.FALSE.}
7732 otherwise, based on the ASCII ordering.
7734 @item @emph{Specific names}:
7735 @multitable @columnfractions .20 .20 .20 .25
7736 @item Name @tab Argument @tab Return type @tab Standard
7737 @item @code{LLE(STRING_A, STRING_B)} @tab @code{CHARACTER} @tab @code{LOGICAL} @tab Fortran 77 and later
7740 @item @emph{See also}:
7741 @ref{LGE}, @ref{LGT}, @ref{LLT}
7747 @section @code{LLT} --- Lexical less than
7749 @cindex lexical comparison of strings
7750 @cindex string, comparison
7753 @item @emph{Description}:
7754 Determines whether one string is lexically less than another string,
7755 where the two strings are interpreted as containing ASCII character
7756 codes. If the String A and String B are not the same length, the
7757 shorter is compared as if spaces were appended to it to form a value
7758 that has the same length as the longer.
7760 In general, the lexical comparison intrinsics @code{LGE}, @code{LGT},
7761 @code{LLE}, and @code{LLT} differ from the corresponding intrinsic
7762 operators @code{.GE.}, @code{.GT.}, @code{.LE.}, and @code{.LT.}, in
7763 that the latter use the processor's character ordering (which is not
7764 ASCII on some targets), whereas the former always use the ASCII
7767 @item @emph{Standard}:
7768 Fortran 77 and later
7773 @item @emph{Syntax}:
7774 @code{RESULT = LLT(STRING_A, STRING_B)}
7776 @item @emph{Arguments}:
7777 @multitable @columnfractions .15 .70
7778 @item @var{STRING_A} @tab Shall be of default @code{CHARACTER} type.
7779 @item @var{STRING_B} @tab Shall be of default @code{CHARACTER} type.
7782 @item @emph{Return value}:
7783 Returns @code{.TRUE.} if @code{STRING_A < STRING_B}, and @code{.FALSE.}
7784 otherwise, based on the ASCII ordering.
7786 @item @emph{Specific names}:
7787 @multitable @columnfractions .20 .20 .20 .25
7788 @item Name @tab Argument @tab Return type @tab Standard
7789 @item @code{LLT(STRING_A, STRING_B)} @tab @code{CHARACTER} @tab @code{LOGICAL} @tab Fortran 77 and later
7792 @item @emph{See also}:
7793 @ref{LGE}, @ref{LGT}, @ref{LLE}
7799 @section @code{LNBLNK} --- Index of the last non-blank character in a string
7801 @cindex string, find non-blank character
7804 @item @emph{Description}:
7805 Returns the length of a character string, ignoring any trailing blanks.
7806 This is identical to the standard @code{LEN_TRIM} intrinsic, and is only
7807 included for backwards compatibility.
7809 @item @emph{Standard}:
7815 @item @emph{Syntax}:
7816 @code{RESULT = LNBLNK(STRING)}
7818 @item @emph{Arguments}:
7819 @multitable @columnfractions .15 .70
7820 @item @var{STRING} @tab Shall be a scalar of type @code{CHARACTER},
7821 with @code{INTENT(IN)}
7824 @item @emph{Return value}:
7825 The return value is of @code{INTEGER(kind=4)} type.
7827 @item @emph{See also}:
7828 @ref{INDEX intrinsic}, @ref{LEN_TRIM}
7834 @section @code{LOC} --- Returns the address of a variable
7836 @cindex location of a variable in memory
7839 @item @emph{Description}:
7840 @code{LOC(X)} returns the address of @var{X} as an integer.
7842 @item @emph{Standard}:
7848 @item @emph{Syntax}:
7849 @code{RESULT = LOC(X)}
7851 @item @emph{Arguments}:
7852 @multitable @columnfractions .15 .70
7853 @item @var{X} @tab Variable of any type.
7856 @item @emph{Return value}:
7857 The return value is of type @code{INTEGER}, with a @code{KIND}
7858 corresponding to the size (in bytes) of a memory address on the target
7861 @item @emph{Example}:
7868 end program test_loc
7875 @section @code{LOG} --- Natural logarithm function
7882 @cindex exponential function, inverse
7883 @cindex logarithm function
7884 @cindex natural logarithm function
7887 @item @emph{Description}:
7888 @code{LOG(X)} computes the natural logarithm of @var{X}, i.e. the
7889 logarithm to the base @math{e}.
7891 @item @emph{Standard}:
7892 Fortran 77 and later
7897 @item @emph{Syntax}:
7898 @code{RESULT = LOG(X)}
7900 @item @emph{Arguments}:
7901 @multitable @columnfractions .15 .70
7902 @item @var{X} @tab The type shall be @code{REAL} or
7906 @item @emph{Return value}:
7907 The return value is of type @code{REAL} or @code{COMPLEX}.
7908 The kind type parameter is the same as @var{X}.
7909 If @var{X} is @code{COMPLEX}, the imaginary part @math{\omega} is in the range
7910 @math{-\pi \leq \omega \leq \pi}.
7912 @item @emph{Example}:
7915 real(8) :: x = 2.7182818284590451_8
7916 complex :: z = (1.0, 2.0)
7917 x = log(x) ! will yield (approximately) 1
7919 end program test_log
7922 @item @emph{Specific names}:
7923 @multitable @columnfractions .20 .20 .20 .25
7924 @item Name @tab Argument @tab Return type @tab Standard
7925 @item @code{ALOG(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab f95, gnu
7926 @item @code{DLOG(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab f95, gnu
7927 @item @code{CLOG(X)} @tab @code{COMPLEX(4) X} @tab @code{COMPLEX(4)} @tab f95, gnu
7928 @item @code{ZLOG(X)} @tab @code{COMPLEX(8) X} @tab @code{COMPLEX(8)} @tab f95, gnu
7929 @item @code{CDLOG(X)} @tab @code{COMPLEX(8) X} @tab @code{COMPLEX(8)} @tab f95, gnu
7936 @section @code{LOG10} --- Base 10 logarithm function
7940 @cindex exponential function, inverse
7941 @cindex logarithm function with base 10
7942 @cindex base 10 logarithm function
7945 @item @emph{Description}:
7946 @code{LOG10(X)} computes the base 10 logarithm of @var{X}.
7948 @item @emph{Standard}:
7949 Fortran 77 and later
7954 @item @emph{Syntax}:
7955 @code{RESULT = LOG10(X)}
7957 @item @emph{Arguments}:
7958 @multitable @columnfractions .15 .70
7959 @item @var{X} @tab The type shall be @code{REAL}.
7962 @item @emph{Return value}:
7963 The return value is of type @code{REAL} or @code{COMPLEX}.
7964 The kind type parameter is the same as @var{X}.
7966 @item @emph{Example}:
7969 real(8) :: x = 10.0_8
7971 end program test_log10
7974 @item @emph{Specific names}:
7975 @multitable @columnfractions .20 .20 .20 .25
7976 @item Name @tab Argument @tab Return type @tab Standard
7977 @item @code{ALOG10(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab Fortran 95 and later
7978 @item @code{DLOG10(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab Fortran 95 and later
7985 @section @code{LOG_GAMMA} --- Logarithm of the Gamma function
7990 @cindex Gamma function, logarithm of
7993 @item @emph{Description}:
7994 @code{LOG_GAMMA(X)} computes the natural logarithm of the absolute value
7995 of the Gamma (@math{\Gamma}) function.
7997 @item @emph{Standard}:
7998 Fortran 2008 and later
8003 @item @emph{Syntax}:
8004 @code{X = LOG_GAMMA(X)}
8006 @item @emph{Arguments}:
8007 @multitable @columnfractions .15 .70
8008 @item @var{X} @tab Shall be of type @code{REAL} and neither zero
8009 nor a negative integer.
8012 @item @emph{Return value}:
8013 The return value is of type @code{REAL} of the same kind as @var{X}.
8015 @item @emph{Example}:
8017 program test_log_gamma
8019 x = lgamma(x) ! returns 0.0
8020 end program test_log_gamma
8023 @item @emph{Specific names}:
8024 @multitable @columnfractions .20 .20 .20 .25
8025 @item Name @tab Argument @tab Return type @tab Standard
8026 @item @code{LGAMMA(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab GNU Extension
8027 @item @code{ALGAMA(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab GNU Extension
8028 @item @code{DLGAMA(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU Extension
8031 @item @emph{See also}:
8032 Gamma function: @ref{GAMMA}
8039 @section @code{LOGICAL} --- Convert to logical type
8041 @cindex conversion, to logical
8044 @item @emph{Description}:
8045 Converts one kind of @code{LOGICAL} variable to another.
8047 @item @emph{Standard}:
8048 Fortran 95 and later
8053 @item @emph{Syntax}:
8054 @code{RESULT = LOGICAL(L [, KIND])}
8056 @item @emph{Arguments}:
8057 @multitable @columnfractions .15 .70
8058 @item @var{L} @tab The type shall be @code{LOGICAL}.
8059 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
8060 expression indicating the kind parameter of the result.
8063 @item @emph{Return value}:
8064 The return value is a @code{LOGICAL} value equal to @var{L}, with a
8065 kind corresponding to @var{KIND}, or of the default logical kind if
8066 @var{KIND} is not given.
8068 @item @emph{See also}:
8069 @ref{INT}, @ref{REAL}, @ref{CMPLX}
8075 @section @code{LONG} --- Convert to integer type
8077 @cindex conversion, to integer
8080 @item @emph{Description}:
8081 Convert to a @code{KIND=4} integer type, which is the same size as a C
8082 @code{long} integer. This is equivalent to the standard @code{INT}
8083 intrinsic with an optional argument of @code{KIND=4}, and is only
8084 included for backwards compatibility.
8086 @item @emph{Standard}:
8092 @item @emph{Syntax}:
8093 @code{RESULT = LONG(A)}
8095 @item @emph{Arguments}:
8096 @multitable @columnfractions .15 .70
8097 @item @var{A} @tab Shall be of type @code{INTEGER},
8098 @code{REAL}, or @code{COMPLEX}.
8101 @item @emph{Return value}:
8102 The return value is a @code{INTEGER(4)} variable.
8104 @item @emph{See also}:
8105 @ref{INT}, @ref{INT2}, @ref{INT8}
8111 @section @code{LSHIFT} --- Left shift bits
8113 @cindex bits, shift left
8116 @item @emph{Description}:
8117 @code{LSHIFT} returns a value corresponding to @var{I} with all of the
8118 bits shifted left by @var{SHIFT} places. If the absolute value of
8119 @var{SHIFT} is greater than @code{BIT_SIZE(I)}, the value is undefined.
8120 Bits shifted out from the left end are lost; zeros are shifted in from
8123 This function has been superseded by the @code{ISHFT} intrinsic, which
8124 is standard in Fortran 95 and later, and the @code{SHIFTL} intrinsic,
8125 which is standard in Fortran 2008 and later.
8127 @item @emph{Standard}:
8133 @item @emph{Syntax}:
8134 @code{RESULT = LSHIFT(I, SHIFT)}
8136 @item @emph{Arguments}:
8137 @multitable @columnfractions .15 .70
8138 @item @var{I} @tab The type shall be @code{INTEGER}.
8139 @item @var{SHIFT} @tab The type shall be @code{INTEGER}.
8142 @item @emph{Return value}:
8143 The return value is of type @code{INTEGER} and of the same kind as
8146 @item @emph{See also}:
8147 @ref{ISHFT}, @ref{ISHFTC}, @ref{RSHIFT}, @ref{SHIFTA}, @ref{SHIFTL},
8155 @section @code{LSTAT} --- Get file status
8157 @cindex file system, file status
8160 @item @emph{Description}:
8161 @code{LSTAT} is identical to @ref{STAT}, except that if path is a
8162 symbolic link, then the link itself is statted, not the file that it
8165 The elements in @code{VALUES} are the same as described by @ref{STAT}.
8167 This intrinsic is provided in both subroutine and function forms;
8168 however, only one form can be used in any given program unit.
8170 @item @emph{Standard}:
8174 Subroutine, function
8176 @item @emph{Syntax}:
8177 @multitable @columnfractions .80
8178 @item @code{CALL LSTAT(NAME, VALUES [, STATUS])}
8179 @item @code{STATUS = LSTAT(NAME, VALUES)}
8182 @item @emph{Arguments}:
8183 @multitable @columnfractions .15 .70
8184 @item @var{NAME} @tab The type shall be @code{CHARACTER} of the default
8185 kind, a valid path within the file system.
8186 @item @var{VALUES} @tab The type shall be @code{INTEGER(4), DIMENSION(13)}.
8187 @item @var{STATUS} @tab (Optional) status flag of type @code{INTEGER(4)}.
8188 Returns 0 on success and a system specific error code otherwise.
8191 @item @emph{Example}:
8192 See @ref{STAT} for an example.
8194 @item @emph{See also}:
8195 To stat an open file: @ref{FSTAT}, to stat a file: @ref{STAT}
8201 @section @code{LTIME} --- Convert time to local time info
8203 @cindex time, conversion to local time info
8206 @item @emph{Description}:
8207 Given a system time value @var{TIME} (as provided by the @code{TIME8}
8208 intrinsic), fills @var{VALUES} with values extracted from it appropriate
8209 to the local time zone using @code{localtime(3)}.
8211 @item @emph{Standard}:
8217 @item @emph{Syntax}:
8218 @code{CALL LTIME(TIME, VALUES)}
8220 @item @emph{Arguments}:
8221 @multitable @columnfractions .15 .70
8222 @item @var{TIME} @tab An @code{INTEGER} scalar expression
8223 corresponding to a system time, with @code{INTENT(IN)}.
8224 @item @var{VALUES} @tab A default @code{INTEGER} array with 9 elements,
8225 with @code{INTENT(OUT)}.
8228 @item @emph{Return value}:
8229 The elements of @var{VALUES} are assigned as follows:
8231 @item Seconds after the minute, range 0--59 or 0--61 to allow for leap
8233 @item Minutes after the hour, range 0--59
8234 @item Hours past midnight, range 0--23
8235 @item Day of month, range 0--31
8236 @item Number of months since January, range 0--12
8237 @item Years since 1900
8238 @item Number of days since Sunday, range 0--6
8239 @item Days since January 1
8240 @item Daylight savings indicator: positive if daylight savings is in
8241 effect, zero if not, and negative if the information is not available.
8244 @item @emph{See also}:
8245 @ref{CTIME}, @ref{GMTIME}, @ref{TIME}, @ref{TIME8}
8252 @section @code{MALLOC} --- Allocate dynamic memory
8254 @cindex pointer, cray
8257 @item @emph{Description}:
8258 @code{MALLOC(SIZE)} allocates @var{SIZE} bytes of dynamic memory and
8259 returns the address of the allocated memory. The @code{MALLOC} intrinsic
8260 is an extension intended to be used with Cray pointers, and is provided
8261 in GNU Fortran to allow the user to compile legacy code. For new code
8262 using Fortran 95 pointers, the memory allocation intrinsic is
8265 @item @emph{Standard}:
8271 @item @emph{Syntax}:
8272 @code{PTR = MALLOC(SIZE)}
8274 @item @emph{Arguments}:
8275 @multitable @columnfractions .15 .70
8276 @item @var{SIZE} @tab The type shall be @code{INTEGER}.
8279 @item @emph{Return value}:
8280 The return value is of type @code{INTEGER(K)}, with @var{K} such that
8281 variables of type @code{INTEGER(K)} have the same size as
8282 C pointers (@code{sizeof(void *)}).
8284 @item @emph{Example}:
8285 The following example demonstrates the use of @code{MALLOC} and
8286 @code{FREE} with Cray pointers.
8295 ptr_x = malloc(20*8)
8297 x(i) = sqrt(1.0d0 / i)
8305 end program test_malloc
8308 @item @emph{See also}:
8315 @section @code{MASKL} --- Left justified mask
8317 @cindex mask, left justified
8320 @item @emph{Description}:
8321 @code{MASKL(I[, KIND])} has its leftmost @var{I} bits set to 1, and the
8322 remaining bits set to 0.
8324 @item @emph{Standard}:
8325 Fortran 2008 and later
8330 @item @emph{Syntax}:
8331 @code{RESULT = MASKL(I[, KIND])}
8333 @item @emph{Arguments}:
8334 @multitable @columnfractions .15 .70
8335 @item @var{I} @tab Shall be of type @code{INTEGER}.
8336 @item @var{KIND} @tab Shall be a scalar constant expression of type
8340 @item @emph{Return value}:
8341 The return value is of type @code{INTEGER}. If @var{KIND} is present, it
8342 specifies the kind value of the return type; otherwise, it is of the
8343 default integer kind.
8345 @item @emph{See also}:
8352 @section @code{MASKR} --- Right justified mask
8354 @cindex mask, right justified
8357 @item @emph{Description}:
8358 @code{MASKL(I[, KIND])} has its rightmost @var{I} bits set to 1, and the
8359 remaining bits set to 0.
8361 @item @emph{Standard}:
8362 Fortran 2008 and later
8367 @item @emph{Syntax}:
8368 @code{RESULT = MASKR(I[, KIND])}
8370 @item @emph{Arguments}:
8371 @multitable @columnfractions .15 .70
8372 @item @var{I} @tab Shall be of type @code{INTEGER}.
8373 @item @var{KIND} @tab Shall be a scalar constant expression of type
8377 @item @emph{Return value}:
8378 The return value is of type @code{INTEGER}. If @var{KIND} is present, it
8379 specifies the kind value of the return type; otherwise, it is of the
8380 default integer kind.
8382 @item @emph{See also}:
8389 @section @code{MATMUL} --- matrix multiplication
8391 @cindex matrix multiplication
8392 @cindex product, matrix
8395 @item @emph{Description}:
8396 Performs a matrix multiplication on numeric or logical arguments.
8398 @item @emph{Standard}:
8399 Fortran 95 and later
8402 Transformational function
8404 @item @emph{Syntax}:
8405 @code{RESULT = MATMUL(MATRIX_A, MATRIX_B)}
8407 @item @emph{Arguments}:
8408 @multitable @columnfractions .15 .70
8409 @item @var{MATRIX_A} @tab An array of @code{INTEGER},
8410 @code{REAL}, @code{COMPLEX}, or @code{LOGICAL} type, with a rank of
8412 @item @var{MATRIX_B} @tab An array of @code{INTEGER},
8413 @code{REAL}, or @code{COMPLEX} type if @var{MATRIX_A} is of a numeric
8414 type; otherwise, an array of @code{LOGICAL} type. The rank shall be one
8415 or two, and the first (or only) dimension of @var{MATRIX_B} shall be
8416 equal to the last (or only) dimension of @var{MATRIX_A}.
8419 @item @emph{Return value}:
8420 The matrix product of @var{MATRIX_A} and @var{MATRIX_B}. The type and
8421 kind of the result follow the usual type and kind promotion rules, as
8422 for the @code{*} or @code{.AND.} operators.
8424 @item @emph{See also}:
8430 @section @code{MAX} --- Maximum value of an argument list
8437 @cindex maximum value
8440 @item @emph{Description}:
8441 Returns the argument with the largest (most positive) value.
8443 @item @emph{Standard}:
8444 Fortran 77 and later
8449 @item @emph{Syntax}:
8450 @code{RESULT = MAX(A1, A2 [, A3 [, ...]])}
8452 @item @emph{Arguments}:
8453 @multitable @columnfractions .15 .70
8454 @item @var{A1} @tab The type shall be @code{INTEGER} or
8456 @item @var{A2}, @var{A3}, ... @tab An expression of the same type and kind
8457 as @var{A1}. (As a GNU extension, arguments of different kinds are
8461 @item @emph{Return value}:
8462 The return value corresponds to the maximum value among the arguments,
8463 and has the same type and kind as the first argument.
8465 @item @emph{Specific names}:
8466 @multitable @columnfractions .20 .20 .20 .25
8467 @item Name @tab Argument @tab Return type @tab Standard
8468 @item @code{MAX0(A1)} @tab @code{INTEGER(4) A1} @tab @code{INTEGER(4)} @tab Fortran 77 and later
8469 @item @code{AMAX0(A1)} @tab @code{INTEGER(4) A1} @tab @code{REAL(MAX(X))} @tab Fortran 77 and later
8470 @item @code{MAX1(A1)} @tab @code{REAL A1} @tab @code{INT(MAX(X))} @tab Fortran 77 and later
8471 @item @code{AMAX1(A1)} @tab @code{REAL(4) A1} @tab @code{REAL(4)} @tab Fortran 77 and later
8472 @item @code{DMAX1(A1)} @tab @code{REAL(8) A1} @tab @code{REAL(8)} @tab Fortran 77 and later
8475 @item @emph{See also}:
8476 @ref{MAXLOC} @ref{MAXVAL}, @ref{MIN}
8483 @section @code{MAXEXPONENT} --- Maximum exponent of a real kind
8484 @fnindex MAXEXPONENT
8485 @cindex model representation, maximum exponent
8488 @item @emph{Description}:
8489 @code{MAXEXPONENT(X)} returns the maximum exponent in the model of the
8492 @item @emph{Standard}:
8493 Fortran 95 and later
8498 @item @emph{Syntax}:
8499 @code{RESULT = MAXEXPONENT(X)}
8501 @item @emph{Arguments}:
8502 @multitable @columnfractions .15 .70
8503 @item @var{X} @tab Shall be of type @code{REAL}.
8506 @item @emph{Return value}:
8507 The return value is of type @code{INTEGER} and of the default integer
8510 @item @emph{Example}:
8516 print *, minexponent(x), maxexponent(x)
8517 print *, minexponent(y), maxexponent(y)
8518 end program exponents
8525 @section @code{MAXLOC} --- Location of the maximum value within an array
8527 @cindex array, location of maximum element
8530 @item @emph{Description}:
8531 Determines the location of the element in the array with the maximum
8532 value, or, if the @var{DIM} argument is supplied, determines the
8533 locations of the maximum element along each row of the array in the
8534 @var{DIM} direction. If @var{MASK} is present, only the elements for
8535 which @var{MASK} is @code{.TRUE.} are considered. If more than one
8536 element in the array has the maximum value, the location returned is
8537 that of the first such element in array element order. If the array has
8538 zero size, or all of the elements of @var{MASK} are @code{.FALSE.}, then
8539 the result is an array of zeroes. Similarly, if @var{DIM} is supplied
8540 and all of the elements of @var{MASK} along a given row are zero, the
8541 result value for that row is zero.
8543 @item @emph{Standard}:
8544 Fortran 95 and later
8547 Transformational function
8549 @item @emph{Syntax}:
8550 @multitable @columnfractions .80
8551 @item @code{RESULT = MAXLOC(ARRAY, DIM [, MASK])}
8552 @item @code{RESULT = MAXLOC(ARRAY [, MASK])}
8555 @item @emph{Arguments}:
8556 @multitable @columnfractions .15 .70
8557 @item @var{ARRAY} @tab Shall be an array of type @code{INTEGER} or
8559 @item @var{DIM} @tab (Optional) Shall be a scalar of type
8560 @code{INTEGER}, with a value between one and the rank of @var{ARRAY},
8561 inclusive. It may not be an optional dummy argument.
8562 @item @var{MASK} @tab Shall be an array of type @code{LOGICAL},
8563 and conformable with @var{ARRAY}.
8566 @item @emph{Return value}:
8567 If @var{DIM} is absent, the result is a rank-one array with a length
8568 equal to the rank of @var{ARRAY}. If @var{DIM} is present, the result
8569 is an array with a rank one less than the rank of @var{ARRAY}, and a
8570 size corresponding to the size of @var{ARRAY} with the @var{DIM}
8571 dimension removed. If @var{DIM} is present and @var{ARRAY} has a rank
8572 of one, the result is a scalar. In all cases, the result is of default
8573 @code{INTEGER} type.
8575 @item @emph{See also}:
8576 @ref{MAX}, @ref{MAXVAL}
8583 @section @code{MAXVAL} --- Maximum value of an array
8585 @cindex array, maximum value
8586 @cindex maximum value
8589 @item @emph{Description}:
8590 Determines the maximum value of the elements in an array value, or, if
8591 the @var{DIM} argument is supplied, determines the maximum value along
8592 each row of the array in the @var{DIM} direction. If @var{MASK} is
8593 present, only the elements for which @var{MASK} is @code{.TRUE.} are
8594 considered. If the array has zero size, or all of the elements of
8595 @var{MASK} are @code{.FALSE.}, then the result is @code{-HUGE(ARRAY)}
8596 if @var{ARRAY} is numeric, or a string of nulls if @var{ARRAY} is of character
8599 @item @emph{Standard}:
8600 Fortran 95 and later
8603 Transformational function
8605 @item @emph{Syntax}:
8606 @multitable @columnfractions .80
8607 @item @code{RESULT = MAXVAL(ARRAY, DIM [, MASK])}
8608 @item @code{RESULT = MAXVAL(ARRAY [, MASK])}
8611 @item @emph{Arguments}:
8612 @multitable @columnfractions .15 .70
8613 @item @var{ARRAY} @tab Shall be an array of type @code{INTEGER} or
8615 @item @var{DIM} @tab (Optional) Shall be a scalar of type
8616 @code{INTEGER}, with a value between one and the rank of @var{ARRAY},
8617 inclusive. It may not be an optional dummy argument.
8618 @item @var{MASK} @tab Shall be an array of type @code{LOGICAL},
8619 and conformable with @var{ARRAY}.
8622 @item @emph{Return value}:
8623 If @var{DIM} is absent, or if @var{ARRAY} has a rank of one, the result
8624 is a scalar. If @var{DIM} is present, the result is an array with a
8625 rank one less than the rank of @var{ARRAY}, and a size corresponding to
8626 the size of @var{ARRAY} with the @var{DIM} dimension removed. In all
8627 cases, the result is of the same type and kind as @var{ARRAY}.
8629 @item @emph{See also}:
8630 @ref{MAX}, @ref{MAXLOC}
8636 @section @code{MCLOCK} --- Time function
8638 @cindex time, clock ticks
8642 @item @emph{Description}:
8643 Returns the number of clock ticks since the start of the process, based
8644 on the function @code{clock(3)} in the C standard library.
8646 This intrinsic is not fully portable, such as to systems with 32-bit
8647 @code{INTEGER} types but supporting times wider than 32 bits. Therefore,
8648 the values returned by this intrinsic might be, or become, negative, or
8649 numerically less than previous values, during a single run of the
8652 @item @emph{Standard}:
8658 @item @emph{Syntax}:
8659 @code{RESULT = MCLOCK()}
8661 @item @emph{Return value}:
8662 The return value is a scalar of type @code{INTEGER(4)}, equal to the
8663 number of clock ticks since the start of the process, or @code{-1} if
8664 the system does not support @code{clock(3)}.
8666 @item @emph{See also}:
8667 @ref{CTIME}, @ref{GMTIME}, @ref{LTIME}, @ref{MCLOCK}, @ref{TIME}
8674 @section @code{MCLOCK8} --- Time function (64-bit)
8676 @cindex time, clock ticks
8680 @item @emph{Description}:
8681 Returns the number of clock ticks since the start of the process, based
8682 on the function @code{clock(3)} in the C standard library.
8684 @emph{Warning:} this intrinsic does not increase the range of the timing
8685 values over that returned by @code{clock(3)}. On a system with a 32-bit
8686 @code{clock(3)}, @code{MCLOCK8} will return a 32-bit value, even though
8687 it is converted to a 64-bit @code{INTEGER(8)} value. That means
8688 overflows of the 32-bit value can still occur. Therefore, the values
8689 returned by this intrinsic might be or become negative or numerically
8690 less than previous values during a single run of the compiled program.
8692 @item @emph{Standard}:
8698 @item @emph{Syntax}:
8699 @code{RESULT = MCLOCK8()}
8701 @item @emph{Return value}:
8702 The return value is a scalar of type @code{INTEGER(8)}, equal to the
8703 number of clock ticks since the start of the process, or @code{-1} if
8704 the system does not support @code{clock(3)}.
8706 @item @emph{See also}:
8707 @ref{CTIME}, @ref{GMTIME}, @ref{LTIME}, @ref{MCLOCK}, @ref{TIME8}
8714 @section @code{MERGE} --- Merge variables
8716 @cindex array, merge arrays
8717 @cindex array, combine arrays
8720 @item @emph{Description}:
8721 Select values from two arrays according to a logical mask. The result
8722 is equal to @var{TSOURCE} if @var{MASK} is @code{.TRUE.}, or equal to
8723 @var{FSOURCE} if it is @code{.FALSE.}.
8725 @item @emph{Standard}:
8726 Fortran 95 and later
8731 @item @emph{Syntax}:
8732 @code{RESULT = MERGE(TSOURCE, FSOURCE, MASK)}
8734 @item @emph{Arguments}:
8735 @multitable @columnfractions .15 .70
8736 @item @var{TSOURCE} @tab May be of any type.
8737 @item @var{FSOURCE} @tab Shall be of the same type and type parameters
8739 @item @var{MASK} @tab Shall be of type @code{LOGICAL}.
8742 @item @emph{Return value}:
8743 The result is of the same type and type parameters as @var{TSOURCE}.
8750 @section @code{MERGE_BITS} --- Merge of bits under mask
8755 @item @emph{Description}:
8756 @code{MERGE_BITS(I, J, MASK)} merges the bits of @var{I} and @var{J}
8757 as determined by the mask. The i-th bit of the result is equal to the
8758 i-th bit of @var{I} if the i-th bit of @var{MASK} is 1; it is equal to
8759 the i-th bit of @var{J} otherwise.
8761 @item @emph{Standard}:
8762 Fortran 2008 and later
8767 @item @emph{Syntax}:
8768 @code{RESULT = MERGE_BITS(I, J, MASK)}
8770 @item @emph{Arguments}:
8771 @multitable @columnfractions .15 .70
8772 @item @var{I} @tab Shall be of type @code{INTEGER}.
8773 @item @var{J} @tab Shall be of type @code{INTEGER} and of the same
8775 @item @var{MASK} @tab Shall be of type @code{INTEGER} and of the same
8779 @item @emph{Return value}:
8780 The result is of the same type and kind as @var{I}.
8787 @section @code{MIN} --- Minimum value of an argument list
8794 @cindex minimum value
8797 @item @emph{Description}:
8798 Returns the argument with the smallest (most negative) value.
8800 @item @emph{Standard}:
8801 Fortran 77 and later
8806 @item @emph{Syntax}:
8807 @code{RESULT = MIN(A1, A2 [, A3, ...])}
8809 @item @emph{Arguments}:
8810 @multitable @columnfractions .15 .70
8811 @item @var{A1} @tab The type shall be @code{INTEGER} or
8813 @item @var{A2}, @var{A3}, ... @tab An expression of the same type and kind
8814 as @var{A1}. (As a GNU extension, arguments of different kinds are
8818 @item @emph{Return value}:
8819 The return value corresponds to the maximum value among the arguments,
8820 and has the same type and kind as the first argument.
8822 @item @emph{Specific names}:
8823 @multitable @columnfractions .20 .20 .20 .25
8824 @item Name @tab Argument @tab Return type @tab Standard
8825 @item @code{MIN0(A1)} @tab @code{INTEGER(4) A1} @tab @code{INTEGER(4)} @tab Fortran 77 and later
8826 @item @code{AMIN0(A1)} @tab @code{INTEGER(4) A1} @tab @code{REAL(4)} @tab Fortran 77 and later
8827 @item @code{MIN1(A1)} @tab @code{REAL A1} @tab @code{INTEGER(4)} @tab Fortran 77 and later
8828 @item @code{AMIN1(A1)} @tab @code{REAL(4) A1} @tab @code{REAL(4)} @tab Fortran 77 and later
8829 @item @code{DMIN1(A1)} @tab @code{REAL(8) A1} @tab @code{REAL(8)} @tab Fortran 77 and later
8832 @item @emph{See also}:
8833 @ref{MAX}, @ref{MINLOC}, @ref{MINVAL}
8839 @section @code{MINEXPONENT} --- Minimum exponent of a real kind
8840 @fnindex MINEXPONENT
8841 @cindex model representation, minimum exponent
8844 @item @emph{Description}:
8845 @code{MINEXPONENT(X)} returns the minimum exponent in the model of the
8848 @item @emph{Standard}:
8849 Fortran 95 and later
8854 @item @emph{Syntax}:
8855 @code{RESULT = MINEXPONENT(X)}
8857 @item @emph{Arguments}:
8858 @multitable @columnfractions .15 .70
8859 @item @var{X} @tab Shall be of type @code{REAL}.
8862 @item @emph{Return value}:
8863 The return value is of type @code{INTEGER} and of the default integer
8866 @item @emph{Example}:
8867 See @code{MAXEXPONENT} for an example.
8873 @section @code{MINLOC} --- Location of the minimum value within an array
8875 @cindex array, location of minimum element
8878 @item @emph{Description}:
8879 Determines the location of the element in the array with the minimum
8880 value, or, if the @var{DIM} argument is supplied, determines the
8881 locations of the minimum element along each row of the array in the
8882 @var{DIM} direction. If @var{MASK} is present, only the elements for
8883 which @var{MASK} is @code{.TRUE.} are considered. If more than one
8884 element in the array has the minimum value, the location returned is
8885 that of the first such element in array element order. If the array has
8886 zero size, or all of the elements of @var{MASK} are @code{.FALSE.}, then
8887 the result is an array of zeroes. Similarly, if @var{DIM} is supplied
8888 and all of the elements of @var{MASK} along a given row are zero, the
8889 result value for that row is zero.
8891 @item @emph{Standard}:
8892 Fortran 95 and later
8895 Transformational function
8897 @item @emph{Syntax}:
8898 @multitable @columnfractions .80
8899 @item @code{RESULT = MINLOC(ARRAY, DIM [, MASK])}
8900 @item @code{RESULT = MINLOC(ARRAY [, MASK])}
8903 @item @emph{Arguments}:
8904 @multitable @columnfractions .15 .70
8905 @item @var{ARRAY} @tab Shall be an array of type @code{INTEGER} or
8907 @item @var{DIM} @tab (Optional) Shall be a scalar of type
8908 @code{INTEGER}, with a value between one and the rank of @var{ARRAY},
8909 inclusive. It may not be an optional dummy argument.
8910 @item @var{MASK} @tab Shall be an array of type @code{LOGICAL},
8911 and conformable with @var{ARRAY}.
8914 @item @emph{Return value}:
8915 If @var{DIM} is absent, the result is a rank-one array with a length
8916 equal to the rank of @var{ARRAY}. If @var{DIM} is present, the result
8917 is an array with a rank one less than the rank of @var{ARRAY}, and a
8918 size corresponding to the size of @var{ARRAY} with the @var{DIM}
8919 dimension removed. If @var{DIM} is present and @var{ARRAY} has a rank
8920 of one, the result is a scalar. In all cases, the result is of default
8921 @code{INTEGER} type.
8923 @item @emph{See also}:
8924 @ref{MIN}, @ref{MINVAL}
8931 @section @code{MINVAL} --- Minimum value of an array
8933 @cindex array, minimum value
8934 @cindex minimum value
8937 @item @emph{Description}:
8938 Determines the minimum value of the elements in an array value, or, if
8939 the @var{DIM} argument is supplied, determines the minimum value along
8940 each row of the array in the @var{DIM} direction. If @var{MASK} is
8941 present, only the elements for which @var{MASK} is @code{.TRUE.} are
8942 considered. If the array has zero size, or all of the elements of
8943 @var{MASK} are @code{.FALSE.}, then the result is @code{HUGE(ARRAY)} if
8944 @var{ARRAY} is numeric, or a string of @code{CHAR(255)} characters if
8945 @var{ARRAY} is of character type.
8947 @item @emph{Standard}:
8948 Fortran 95 and later
8951 Transformational function
8953 @item @emph{Syntax}:
8954 @multitable @columnfractions .80
8955 @item @code{RESULT = MINVAL(ARRAY, DIM [, MASK])}
8956 @item @code{RESULT = MINVAL(ARRAY [, MASK])}
8959 @item @emph{Arguments}:
8960 @multitable @columnfractions .15 .70
8961 @item @var{ARRAY} @tab Shall be an array of type @code{INTEGER} or
8963 @item @var{DIM} @tab (Optional) Shall be a scalar of type
8964 @code{INTEGER}, with a value between one and the rank of @var{ARRAY},
8965 inclusive. It may not be an optional dummy argument.
8966 @item @var{MASK} @tab Shall be an array of type @code{LOGICAL},
8967 and conformable with @var{ARRAY}.
8970 @item @emph{Return value}:
8971 If @var{DIM} is absent, or if @var{ARRAY} has a rank of one, the result
8972 is a scalar. If @var{DIM} is present, the result is an array with a
8973 rank one less than the rank of @var{ARRAY}, and a size corresponding to
8974 the size of @var{ARRAY} with the @var{DIM} dimension removed. In all
8975 cases, the result is of the same type and kind as @var{ARRAY}.
8977 @item @emph{See also}:
8978 @ref{MIN}, @ref{MINLOC}
8985 @section @code{MOD} --- Remainder function
8990 @cindex division, remainder
8993 @item @emph{Description}:
8994 @code{MOD(A,P)} computes the remainder of the division of A by P@. It is
8995 calculated as @code{A - (INT(A/P) * P)}.
8997 @item @emph{Standard}:
8998 Fortran 77 and later
9003 @item @emph{Syntax}:
9004 @code{RESULT = MOD(A, P)}
9006 @item @emph{Arguments}:
9007 @multitable @columnfractions .15 .70
9008 @item @var{A} @tab Shall be a scalar of type @code{INTEGER} or @code{REAL}
9009 @item @var{P} @tab Shall be a scalar of the same type as @var{A} and not
9013 @item @emph{Return value}:
9014 The kind of the return value is the result of cross-promoting
9015 the kinds of the arguments.
9017 @item @emph{Example}:
9021 print *, mod(17.5,5.5)
9022 print *, mod(17.5d0,5.5)
9023 print *, mod(17.5,5.5d0)
9026 print *, mod(-17.5,5.5)
9027 print *, mod(-17.5d0,5.5)
9028 print *, mod(-17.5,5.5d0)
9031 print *, mod(17.5,-5.5)
9032 print *, mod(17.5d0,-5.5)
9033 print *, mod(17.5,-5.5d0)
9034 end program test_mod
9037 @item @emph{Specific names}:
9038 @multitable @columnfractions .20 .20 .20 .25
9039 @item Name @tab Arguments @tab Return type @tab Standard
9040 @item @code{MOD(A,P)} @tab @code{INTEGER A,P} @tab @code{INTEGER} @tab Fortran 95 and later
9041 @item @code{AMOD(A,P)} @tab @code{REAL(4) A,P} @tab @code{REAL(4)} @tab Fortran 95 and later
9042 @item @code{DMOD(A,P)} @tab @code{REAL(8) A,P} @tab @code{REAL(8)} @tab Fortran 95 and later
9049 @section @code{MODULO} --- Modulo function
9052 @cindex division, modulo
9055 @item @emph{Description}:
9056 @code{MODULO(A,P)} computes the @var{A} modulo @var{P}.
9058 @item @emph{Standard}:
9059 Fortran 95 and later
9064 @item @emph{Syntax}:
9065 @code{RESULT = MODULO(A, P)}
9067 @item @emph{Arguments}:
9068 @multitable @columnfractions .15 .70
9069 @item @var{A} @tab Shall be a scalar of type @code{INTEGER} or @code{REAL}
9070 @item @var{P} @tab Shall be a scalar of the same type and kind as @var{A}
9073 @item @emph{Return value}:
9074 The type and kind of the result are those of the arguments.
9076 @item If @var{A} and @var{P} are of type @code{INTEGER}:
9077 @code{MODULO(A,P)} has the value @var{R} such that @code{A=Q*P+R}, where
9078 @var{Q} is an integer and @var{R} is between 0 (inclusive) and @var{P}
9080 @item If @var{A} and @var{P} are of type @code{REAL}:
9081 @code{MODULO(A,P)} has the value of @code{A - FLOOR (A / P) * P}.
9083 In all cases, if @var{P} is zero the result is processor-dependent.
9085 @item @emph{Example}:
9088 print *, modulo(17,3)
9089 print *, modulo(17.5,5.5)
9091 print *, modulo(-17,3)
9092 print *, modulo(-17.5,5.5)
9094 print *, modulo(17,-3)
9095 print *, modulo(17.5,-5.5)
9104 @section @code{MOVE_ALLOC} --- Move allocation from one object to another
9106 @cindex moving allocation
9107 @cindex allocation, moving
9110 @item @emph{Description}:
9111 @code{MOVE_ALLOC(FROM, TO)} moves the allocation from @var{FROM} to
9112 @var{TO}. @var{FROM} will become deallocated in the process.
9114 @item @emph{Standard}:
9115 Fortran 2003 and later
9120 @item @emph{Syntax}:
9121 @code{CALL MOVE_ALLOC(FROM, TO)}
9123 @item @emph{Arguments}:
9124 @multitable @columnfractions .15 .70
9125 @item @var{FROM} @tab @code{ALLOCATABLE}, @code{INTENT(INOUT)}, may be
9126 of any type and kind.
9127 @item @var{TO} @tab @code{ALLOCATABLE}, @code{INTENT(OUT)}, shall be
9128 of the same type, kind and rank as @var{FROM}.
9131 @item @emph{Return value}:
9134 @item @emph{Example}:
9136 program test_move_alloc
9137 integer, allocatable :: a(:), b(:)
9141 call move_alloc(a, b)
9142 print *, allocated(a), allocated(b)
9144 end program test_move_alloc
9151 @section @code{MVBITS} --- Move bits from one integer to another
9156 @item @emph{Description}:
9157 Moves @var{LEN} bits from positions @var{FROMPOS} through
9158 @code{FROMPOS+LEN-1} of @var{FROM} to positions @var{TOPOS} through
9159 @code{TOPOS+LEN-1} of @var{TO}. The portion of argument @var{TO} not
9160 affected by the movement of bits is unchanged. The values of
9161 @code{FROMPOS+LEN-1} and @code{TOPOS+LEN-1} must be less than
9162 @code{BIT_SIZE(FROM)}.
9164 @item @emph{Standard}:
9165 Fortran 95 and later
9168 Elemental subroutine
9170 @item @emph{Syntax}:
9171 @code{CALL MVBITS(FROM, FROMPOS, LEN, TO, TOPOS)}
9173 @item @emph{Arguments}:
9174 @multitable @columnfractions .15 .70
9175 @item @var{FROM} @tab The type shall be @code{INTEGER}.
9176 @item @var{FROMPOS} @tab The type shall be @code{INTEGER}.
9177 @item @var{LEN} @tab The type shall be @code{INTEGER}.
9178 @item @var{TO} @tab The type shall be @code{INTEGER}, of the
9179 same kind as @var{FROM}.
9180 @item @var{TOPOS} @tab The type shall be @code{INTEGER}.
9183 @item @emph{See also}:
9184 @ref{IBCLR}, @ref{IBSET}, @ref{IBITS}, @ref{IAND}, @ref{IOR}, @ref{IEOR}
9190 @section @code{NEAREST} --- Nearest representable number
9192 @cindex real number, nearest different
9193 @cindex floating point, nearest different
9196 @item @emph{Description}:
9197 @code{NEAREST(X, S)} returns the processor-representable number nearest
9198 to @code{X} in the direction indicated by the sign of @code{S}.
9200 @item @emph{Standard}:
9201 Fortran 95 and later
9206 @item @emph{Syntax}:
9207 @code{RESULT = NEAREST(X, S)}
9209 @item @emph{Arguments}:
9210 @multitable @columnfractions .15 .70
9211 @item @var{X} @tab Shall be of type @code{REAL}.
9212 @item @var{S} @tab (Optional) shall be of type @code{REAL} and
9216 @item @emph{Return value}:
9217 The return value is of the same type as @code{X}. If @code{S} is
9218 positive, @code{NEAREST} returns the processor-representable number
9219 greater than @code{X} and nearest to it. If @code{S} is negative,
9220 @code{NEAREST} returns the processor-representable number smaller than
9221 @code{X} and nearest to it.
9223 @item @emph{Example}:
9225 program test_nearest
9227 x = nearest(42.0, 1.0)
9228 y = nearest(42.0, -1.0)
9229 write (*,"(3(G20.15))") x, y, x - y
9230 end program test_nearest
9237 @section @code{NEW_LINE} --- New line character
9240 @cindex output, newline
9243 @item @emph{Description}:
9244 @code{NEW_LINE(C)} returns the new-line character.
9246 @item @emph{Standard}:
9247 Fortran 2003 and later
9252 @item @emph{Syntax}:
9253 @code{RESULT = NEW_LINE(C)}
9255 @item @emph{Arguments}:
9256 @multitable @columnfractions .15 .70
9257 @item @var{C} @tab The argument shall be a scalar or array of the
9258 type @code{CHARACTER}.
9261 @item @emph{Return value}:
9262 Returns a @var{CHARACTER} scalar of length one with the new-line character of
9263 the same kind as parameter @var{C}.
9265 @item @emph{Example}:
9269 write(*,'(A)') 'This is record 1.'//NEW_LINE('A')//'This is record 2.'
9277 @section @code{NINT} --- Nearest whole number
9280 @cindex rounding, nearest whole number
9283 @item @emph{Description}:
9284 @code{NINT(A)} rounds its argument to the nearest whole number.
9286 @item @emph{Standard}:
9287 Fortran 77 and later, with @var{KIND} argument Fortran 90 and later
9292 @item @emph{Syntax}:
9293 @code{RESULT = NINT(A [, KIND])}
9295 @item @emph{Arguments}:
9296 @multitable @columnfractions .15 .70
9297 @item @var{A} @tab The type of the argument shall be @code{REAL}.
9298 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
9299 expression indicating the kind parameter of the result.
9302 @item @emph{Return value}:
9303 Returns @var{A} with the fractional portion of its magnitude eliminated by
9304 rounding to the nearest whole number and with its sign preserved,
9305 converted to an @code{INTEGER} of the default kind.
9307 @item @emph{Example}:
9314 print *, nint(x4), idnint(x8)
9315 end program test_nint
9318 @item @emph{Specific names}:
9319 @multitable @columnfractions .20 .20 .20 .25
9320 @item Name @tab Argument @tab Return Type @tab Standard
9321 @item @code{NINT(A)} @tab @code{REAL(4) A} @tab @code{INTEGER} @tab Fortran 95 and later
9322 @item @code{IDNINT(A)} @tab @code{REAL(8) A} @tab @code{INTEGER} @tab Fortran 95 and later
9325 @item @emph{See also}:
9326 @ref{CEILING}, @ref{FLOOR}
9333 @section @code{NORM2} --- Euclidean vector norms
9335 @cindex Euclidean vector norm
9336 @cindex L2 vector norm
9337 @cindex norm, Euclidean
9340 @item @emph{Description}:
9341 Calculates the Euclidean vector norm (@math{L_2} norm) of
9342 of @var{ARRAY} along dimension @var{DIM}.
9344 @item @emph{Standard}:
9345 Fortran 2008 and later
9348 Transformational function
9350 @item @emph{Syntax}:
9351 @multitable @columnfractions .80
9352 @item @code{RESULT = NORM2(ARRAY[, DIM])}
9355 @item @emph{Arguments}:
9356 @multitable @columnfractions .15 .70
9357 @item @var{ARRAY} @tab Shall be an array of type @code{REAL}
9358 @item @var{DIM} @tab (Optional) shall be a scalar of type
9359 @code{INTEGER} with a value in the range from 1 to n, where n
9360 equals the rank of @var{ARRAY}.
9363 @item @emph{Return value}:
9364 The result is of the same type as @var{ARRAY}.
9366 If @var{DIM} is absent, a scalar with the square root of the sum of all
9367 elements in @var{ARRAY} squared is returned. Otherwise, an array of
9368 rank @math{n-1}, where @math{n} equals the rank of @var{ARRAY}, and a
9369 shape similar to that of @var{ARRAY} with dimension @var{DIM} dropped
9372 @item @emph{Example}:
9375 REAL :: x(5) = [ real :: 1, 2, 3, 4, 5 ]
9376 print *, NORM2(x) ! = sqrt(55.) ~ 7.416
9384 @section @code{NOT} --- Logical negation
9386 @cindex bits, negate
9387 @cindex bitwise logical not
9388 @cindex logical not, bitwise
9391 @item @emph{Description}:
9392 @code{NOT} returns the bitwise Boolean inverse of @var{I}.
9394 @item @emph{Standard}:
9395 Fortran 95 and later
9400 @item @emph{Syntax}:
9401 @code{RESULT = NOT(I)}
9403 @item @emph{Arguments}:
9404 @multitable @columnfractions .15 .70
9405 @item @var{I} @tab The type shall be @code{INTEGER}.
9408 @item @emph{Return value}:
9409 The return type is @code{INTEGER}, of the same kind as the
9412 @item @emph{See also}:
9413 @ref{IAND}, @ref{IEOR}, @ref{IOR}, @ref{IBITS}, @ref{IBSET}, @ref{IBCLR}
9420 @section @code{NULL} --- Function that returns an disassociated pointer
9422 @cindex pointer, status
9423 @cindex pointer, disassociated
9426 @item @emph{Description}:
9427 Returns a disassociated pointer.
9429 If @var{MOLD} is present, a disassociated pointer of the same type is
9430 returned, otherwise the type is determined by context.
9432 In Fortran 95, @var{MOLD} is optional. Please note that Fortran 2003
9433 includes cases where it is required.
9435 @item @emph{Standard}:
9436 Fortran 95 and later
9439 Transformational function
9441 @item @emph{Syntax}:
9442 @code{PTR => NULL([MOLD])}
9444 @item @emph{Arguments}:
9445 @multitable @columnfractions .15 .70
9446 @item @var{MOLD} @tab (Optional) shall be a pointer of any association
9447 status and of any type.
9450 @item @emph{Return value}:
9451 A disassociated pointer.
9453 @item @emph{Example}:
9455 REAL, POINTER, DIMENSION(:) :: VEC => NULL ()
9458 @item @emph{See also}:
9465 @section @code{NUM_IMAGES} --- Function that returns the number of images
9467 @cindex coarray, @code{NUM_IMAGES}
9468 @cindex images, number of
9471 @item @emph{Description}:
9472 Returns the number of images.
9474 @item @emph{Standard}:
9475 Fortran 2008 and later
9478 Transformational function
9480 @item @emph{Syntax}:
9481 @code{RESULT = NUM_IMAGES()}
9483 @item @emph{Arguments}: None.
9485 @item @emph{Return value}:
9486 Scalar default-kind integer.
9488 @item @emph{Example}:
9492 value = THIS_IMAGE()
9494 IF (THIS_IMAGE() == 1) THEN
9495 DO i = 1, NUM_IMAGES()
9496 WRITE(*,'(2(a,i0))') 'value[', i, '] is ', value[i]
9501 @item @emph{See also}:
9502 @ref{THIS_IMAGE}, @ref{IMAGE_INDEX}
9508 @section @code{OR} --- Bitwise logical OR
9510 @cindex bitwise logical or
9511 @cindex logical or, bitwise
9514 @item @emph{Description}:
9515 Bitwise logical @code{OR}.
9517 This intrinsic routine is provided for backwards compatibility with
9518 GNU Fortran 77. For integer arguments, programmers should consider
9519 the use of the @ref{IOR} intrinsic defined by the Fortran standard.
9521 @item @emph{Standard}:
9527 @item @emph{Syntax}:
9528 @code{RESULT = OR(I, J)}
9530 @item @emph{Arguments}:
9531 @multitable @columnfractions .15 .70
9532 @item @var{I} @tab The type shall be either a scalar @code{INTEGER}
9533 type or a scalar @code{LOGICAL} type.
9534 @item @var{J} @tab The type shall be the same as the type of @var{J}.
9537 @item @emph{Return value}:
9538 The return type is either a scalar @code{INTEGER} or a scalar
9539 @code{LOGICAL}. If the kind type parameters differ, then the
9540 smaller kind type is implicitly converted to larger kind, and the
9541 return has the larger kind.
9543 @item @emph{Example}:
9546 LOGICAL :: T = .TRUE., F = .FALSE.
9548 DATA a / Z'F' /, b / Z'3' /
9550 WRITE (*,*) OR(T, T), OR(T, F), OR(F, T), OR(F, F)
9551 WRITE (*,*) OR(a, b)
9555 @item @emph{See also}:
9556 Fortran 95 elemental function: @ref{IOR}
9562 @section @code{PACK} --- Pack an array into an array of rank one
9564 @cindex array, packing
9565 @cindex array, reduce dimension
9566 @cindex array, gather elements
9569 @item @emph{Description}:
9570 Stores the elements of @var{ARRAY} in an array of rank one.
9572 The beginning of the resulting array is made up of elements whose @var{MASK}
9573 equals @code{TRUE}. Afterwards, positions are filled with elements taken from
9576 @item @emph{Standard}:
9577 Fortran 95 and later
9580 Transformational function
9582 @item @emph{Syntax}:
9583 @code{RESULT = PACK(ARRAY, MASK[,VECTOR]}
9585 @item @emph{Arguments}:
9586 @multitable @columnfractions .15 .70
9587 @item @var{ARRAY} @tab Shall be an array of any type.
9588 @item @var{MASK} @tab Shall be an array of type @code{LOGICAL} and
9589 of the same size as @var{ARRAY}. Alternatively, it may be a @code{LOGICAL}
9591 @item @var{VECTOR} @tab (Optional) shall be an array of the same type
9592 as @var{ARRAY} and of rank one. If present, the number of elements in
9593 @var{VECTOR} shall be equal to or greater than the number of true elements
9594 in @var{MASK}. If @var{MASK} is scalar, the number of elements in
9595 @var{VECTOR} shall be equal to or greater than the number of elements in
9599 @item @emph{Return value}:
9600 The result is an array of rank one and the same type as that of @var{ARRAY}.
9601 If @var{VECTOR} is present, the result size is that of @var{VECTOR}, the
9602 number of @code{TRUE} values in @var{MASK} otherwise.
9604 @item @emph{Example}:
9605 Gathering nonzero elements from an array:
9609 m = (/ 1, 0, 0, 0, 5, 0 /)
9610 WRITE(*, FMT="(6(I0, ' '))") pack(m, m /= 0) ! "1 5"
9614 Gathering nonzero elements from an array and appending elements from @var{VECTOR}:
9618 m = (/ 1, 0, 0, 2 /)
9619 WRITE(*, FMT="(4(I0, ' '))") pack(m, m /= 0, (/ 0, 0, 3, 4 /)) ! "1 2 3 4"
9623 @item @emph{See also}:
9630 @section @code{PARITY} --- Reduction with exclusive OR
9633 @cindex Reduction, XOR
9634 @cindex XOR reduction
9637 @item @emph{Description}:
9638 Calculates the parity, i.e. the reduction using @code{.XOR.},
9639 of @var{MASK} along dimension @var{DIM}.
9641 @item @emph{Standard}:
9642 Fortran 2008 and later
9645 Transformational function
9647 @item @emph{Syntax}:
9648 @multitable @columnfractions .80
9649 @item @code{RESULT = PARITY(MASK[, DIM])}
9652 @item @emph{Arguments}:
9653 @multitable @columnfractions .15 .70
9654 @item @var{LOGICAL} @tab Shall be an array of type @code{LOGICAL}
9655 @item @var{DIM} @tab (Optional) shall be a scalar of type
9656 @code{INTEGER} with a value in the range from 1 to n, where n
9657 equals the rank of @var{MASK}.
9660 @item @emph{Return value}:
9661 The result is of the same type as @var{MASK}.
9663 If @var{DIM} is absent, a scalar with the parity of all elements in
9664 @var{MASK} is returned, i.e. true if an odd number of elements is
9665 @code{.true.} and false otherwise. If @var{DIM} is present, an array
9666 of rank @math{n-1}, where @math{n} equals the rank of @var{ARRAY},
9667 and a shape similar to that of @var{MASK} with dimension @var{DIM}
9668 dropped is returned.
9670 @item @emph{Example}:
9673 LOGICAL :: x(2) = [ .true., .false. ]
9674 print *, PARITY(x) ! prints "T" (true).
9682 @section @code{PERROR} --- Print system error message
9684 @cindex system, error handling
9687 @item @emph{Description}:
9688 Prints (on the C @code{stderr} stream) a newline-terminated error
9689 message corresponding to the last system error. This is prefixed by
9690 @var{STRING}, a colon and a space. See @code{perror(3)}.
9692 @item @emph{Standard}:
9698 @item @emph{Syntax}:
9699 @code{CALL PERROR(STRING)}
9701 @item @emph{Arguments}:
9702 @multitable @columnfractions .15 .70
9703 @item @var{STRING} @tab A scalar of type @code{CHARACTER} and of the
9707 @item @emph{See also}:
9714 @section @code{PRECISION} --- Decimal precision of a real kind
9716 @cindex model representation, precision
9719 @item @emph{Description}:
9720 @code{PRECISION(X)} returns the decimal precision in the model of the
9723 @item @emph{Standard}:
9724 Fortran 95 and later
9729 @item @emph{Syntax}:
9730 @code{RESULT = PRECISION(X)}
9732 @item @emph{Arguments}:
9733 @multitable @columnfractions .15 .70
9734 @item @var{X} @tab Shall be of type @code{REAL} or @code{COMPLEX}.
9737 @item @emph{Return value}:
9738 The return value is of type @code{INTEGER} and of the default integer
9741 @item @emph{See also}:
9742 @ref{SELECTED_REAL_KIND}, @ref{RANGE}
9744 @item @emph{Example}:
9746 program prec_and_range
9747 real(kind=4) :: x(2)
9748 complex(kind=8) :: y
9750 print *, precision(x), range(x)
9751 print *, precision(y), range(y)
9752 end program prec_and_range
9759 @section @code{POPCNT} --- Number of bits set
9761 @cindex binary representation
9765 @item @emph{Description}:
9766 @code{POPCNT(I)} returns the number of bits set ('1' bits) in the binary
9767 representation of @code{I}.
9769 @item @emph{Standard}:
9770 Fortran 2008 and later
9775 @item @emph{Syntax}:
9776 @code{RESULT = POPCNT(I)}
9778 @item @emph{Arguments}:
9779 @multitable @columnfractions .15 .70
9780 @item @var{I} @tab Shall be of type @code{INTEGER}.
9783 @item @emph{Return value}:
9784 The return value is of type @code{INTEGER} and of the default integer
9787 @item @emph{See also}:
9788 @ref{POPPAR}, @ref{LEADZ}, @ref{TRAILZ}
9790 @item @emph{Example}:
9792 program test_population
9793 print *, popcnt(127), poppar(127)
9794 print *, popcnt(huge(0_4)), poppar(huge(0_4))
9795 print *, popcnt(huge(0_8)), poppar(huge(0_8))
9796 end program test_population
9802 @section @code{POPPAR} --- Parity of the number of bits set
9804 @cindex binary representation
9808 @item @emph{Description}:
9809 @code{POPPAR(I)} returns parity of the integer @code{I}, i.e. the parity
9810 of the number of bits set ('1' bits) in the binary representation of
9811 @code{I}. It is equal to 0 if @code{I} has an even number of bits set,
9812 and 1 for an odd number of '1' bits.
9814 @item @emph{Standard}:
9815 Fortran 2008 and later
9820 @item @emph{Syntax}:
9821 @code{RESULT = POPPAR(I)}
9823 @item @emph{Arguments}:
9824 @multitable @columnfractions .15 .70
9825 @item @var{I} @tab Shall be of type @code{INTEGER}.
9828 @item @emph{Return value}:
9829 The return value is of type @code{INTEGER} and of the default integer
9832 @item @emph{See also}:
9833 @ref{POPCNT}, @ref{LEADZ}, @ref{TRAILZ}
9835 @item @emph{Example}:
9837 program test_population
9838 print *, popcnt(127), poppar(127)
9839 print *, popcnt(huge(0_4)), poppar(huge(0_4))
9840 print *, popcnt(huge(0_8)), poppar(huge(0_8))
9841 end program test_population
9848 @section @code{PRESENT} --- Determine whether an optional dummy argument is specified
9852 @item @emph{Description}:
9853 Determines whether an optional dummy argument is present.
9855 @item @emph{Standard}:
9856 Fortran 95 and later
9861 @item @emph{Syntax}:
9862 @code{RESULT = PRESENT(A)}
9864 @item @emph{Arguments}:
9865 @multitable @columnfractions .15 .70
9866 @item @var{A} @tab May be of any type and may be a pointer, scalar or array
9867 value, or a dummy procedure. It shall be the name of an optional dummy argument
9868 accessible within the current subroutine or function.
9871 @item @emph{Return value}:
9872 Returns either @code{TRUE} if the optional argument @var{A} is present, or
9873 @code{FALSE} otherwise.
9875 @item @emph{Example}:
9877 PROGRAM test_present
9878 WRITE(*,*) f(), f(42) ! "F T"
9880 LOGICAL FUNCTION f(x)
9881 INTEGER, INTENT(IN), OPTIONAL :: x
9891 @section @code{PRODUCT} --- Product of array elements
9893 @cindex array, product
9894 @cindex array, multiply elements
9895 @cindex array, conditionally multiply elements
9896 @cindex multiply array elements
9899 @item @emph{Description}:
9900 Multiplies the elements of @var{ARRAY} along dimension @var{DIM} if
9901 the corresponding element in @var{MASK} is @code{TRUE}.
9903 @item @emph{Standard}:
9904 Fortran 95 and later
9907 Transformational function
9909 @item @emph{Syntax}:
9910 @multitable @columnfractions .80
9911 @item @code{RESULT = PRODUCT(ARRAY[, MASK])}
9912 @item @code{RESULT = PRODUCT(ARRAY, DIM[, MASK])}
9915 @item @emph{Arguments}:
9916 @multitable @columnfractions .15 .70
9917 @item @var{ARRAY} @tab Shall be an array of type @code{INTEGER},
9918 @code{REAL} or @code{COMPLEX}.
9919 @item @var{DIM} @tab (Optional) shall be a scalar of type
9920 @code{INTEGER} with a value in the range from 1 to n, where n
9921 equals the rank of @var{ARRAY}.
9922 @item @var{MASK} @tab (Optional) shall be of type @code{LOGICAL}
9923 and either be a scalar or an array of the same shape as @var{ARRAY}.
9926 @item @emph{Return value}:
9927 The result is of the same type as @var{ARRAY}.
9929 If @var{DIM} is absent, a scalar with the product of all elements in
9930 @var{ARRAY} is returned. Otherwise, an array of rank n-1, where n equals
9931 the rank of @var{ARRAY}, and a shape similar to that of @var{ARRAY} with
9932 dimension @var{DIM} dropped is returned.
9935 @item @emph{Example}:
9937 PROGRAM test_product
9938 INTEGER :: x(5) = (/ 1, 2, 3, 4 ,5 /)
9939 print *, PRODUCT(x) ! all elements, product = 120
9940 print *, PRODUCT(x, MASK=MOD(x, 2)==1) ! odd elements, product = 15
9944 @item @emph{See also}:
9951 @section @code{RADIX} --- Base of a model number
9953 @cindex model representation, base
9954 @cindex model representation, radix
9957 @item @emph{Description}:
9958 @code{RADIX(X)} returns the base of the model representing the entity @var{X}.
9960 @item @emph{Standard}:
9961 Fortran 95 and later
9966 @item @emph{Syntax}:
9967 @code{RESULT = RADIX(X)}
9969 @item @emph{Arguments}:
9970 @multitable @columnfractions .15 .70
9971 @item @var{X} @tab Shall be of type @code{INTEGER} or @code{REAL}
9974 @item @emph{Return value}:
9975 The return value is a scalar of type @code{INTEGER} and of the default
9978 @item @emph{See also}:
9979 @ref{SELECTED_REAL_KIND}
9981 @item @emph{Example}:
9984 print *, "The radix for the default integer kind is", radix(0)
9985 print *, "The radix for the default real kind is", radix(0.0)
9986 end program test_radix
9994 @section @code{RAN} --- Real pseudo-random number
9996 @cindex random number generation
9999 @item @emph{Description}:
10000 For compatibility with HP FORTRAN 77/iX, the @code{RAN} intrinsic is
10001 provided as an alias for @code{RAND}. See @ref{RAND} for complete
10004 @item @emph{Standard}:
10007 @item @emph{Class}:
10010 @item @emph{See also}:
10011 @ref{RAND}, @ref{RANDOM_NUMBER}
10017 @section @code{RAND} --- Real pseudo-random number
10019 @cindex random number generation
10022 @item @emph{Description}:
10023 @code{RAND(FLAG)} returns a pseudo-random number from a uniform
10024 distribution between 0 and 1. If @var{FLAG} is 0, the next number
10025 in the current sequence is returned; if @var{FLAG} is 1, the generator
10026 is restarted by @code{CALL SRAND(0)}; if @var{FLAG} has any other value,
10027 it is used as a new seed with @code{SRAND}.
10029 This intrinsic routine is provided for backwards compatibility with
10030 GNU Fortran 77. It implements a simple modulo generator as provided
10031 by @command{g77}. For new code, one should consider the use of
10032 @ref{RANDOM_NUMBER} as it implements a superior algorithm.
10034 @item @emph{Standard}:
10037 @item @emph{Class}:
10040 @item @emph{Syntax}:
10041 @code{RESULT = RAND(I)}
10043 @item @emph{Arguments}:
10044 @multitable @columnfractions .15 .70
10045 @item @var{I} @tab Shall be a scalar @code{INTEGER} of kind 4.
10048 @item @emph{Return value}:
10049 The return value is of @code{REAL} type and the default kind.
10051 @item @emph{Example}:
10054 integer,parameter :: seed = 86456
10057 print *, rand(), rand(), rand(), rand()
10058 print *, rand(seed), rand(), rand(), rand()
10059 end program test_rand
10062 @item @emph{See also}:
10063 @ref{SRAND}, @ref{RANDOM_NUMBER}
10069 @node RANDOM_NUMBER
10070 @section @code{RANDOM_NUMBER} --- Pseudo-random number
10071 @fnindex RANDOM_NUMBER
10072 @cindex random number generation
10075 @item @emph{Description}:
10076 Returns a single pseudorandom number or an array of pseudorandom numbers
10077 from the uniform distribution over the range @math{ 0 \leq x < 1}.
10079 The runtime-library implements George Marsaglia's KISS (Keep It Simple
10080 Stupid) random number generator (RNG). This RNG combines:
10082 @item The congruential generator @math{x(n) = 69069 \cdot x(n-1) + 1327217885}
10083 with a period of @math{2^{32}},
10084 @item A 3-shift shift-register generator with a period of @math{2^{32} - 1},
10085 @item Two 16-bit multiply-with-carry generators with a period of
10086 @math{597273182964842497 > 2^{59}}.
10088 The overall period exceeds @math{2^{123}}.
10090 Please note, this RNG is thread safe if used within OpenMP directives,
10091 i.e., its state will be consistent while called from multiple threads.
10092 However, the KISS generator does not create random numbers in parallel
10093 from multiple sources, but in sequence from a single source. If an
10094 OpenMP-enabled application heavily relies on random numbers, one should
10095 consider employing a dedicated parallel random number generator instead.
10097 @item @emph{Standard}:
10098 Fortran 95 and later
10100 @item @emph{Class}:
10103 @item @emph{Syntax}:
10104 @code{RANDOM_NUMBER(HARVEST)}
10106 @item @emph{Arguments}:
10107 @multitable @columnfractions .15 .70
10108 @item @var{HARVEST} @tab Shall be a scalar or an array of type @code{REAL}.
10111 @item @emph{Example}:
10113 program test_random_number
10115 CALL init_random_seed() ! see example of RANDOM_SEED
10116 CALL RANDOM_NUMBER(r)
10120 @item @emph{See also}:
10127 @section @code{RANDOM_SEED} --- Initialize a pseudo-random number sequence
10128 @fnindex RANDOM_SEED
10129 @cindex random number generation, seeding
10130 @cindex seeding a random number generator
10133 @item @emph{Description}:
10134 Restarts or queries the state of the pseudorandom number generator used by
10135 @code{RANDOM_NUMBER}.
10137 If @code{RANDOM_SEED} is called without arguments, it is initialized to
10138 a default state. The example below shows how to initialize the random
10139 seed based on the system's time.
10141 @item @emph{Standard}:
10142 Fortran 95 and later
10144 @item @emph{Class}:
10147 @item @emph{Syntax}:
10148 @code{CALL RANDOM_SEED([SIZE, PUT, GET])}
10150 @item @emph{Arguments}:
10151 @multitable @columnfractions .15 .70
10152 @item @var{SIZE} @tab (Optional) Shall be a scalar and of type default
10153 @code{INTEGER}, with @code{INTENT(OUT)}. It specifies the minimum size
10154 of the arrays used with the @var{PUT} and @var{GET} arguments.
10155 @item @var{PUT} @tab (Optional) Shall be an array of type default
10156 @code{INTEGER} and rank one. It is @code{INTENT(IN)} and the size of
10157 the array must be larger than or equal to the number returned by the
10158 @var{SIZE} argument.
10159 @item @var{GET} @tab (Optional) Shall be an array of type default
10160 @code{INTEGER} and rank one. It is @code{INTENT(OUT)} and the size
10161 of the array must be larger than or equal to the number returned by
10162 the @var{SIZE} argument.
10165 @item @emph{Example}:
10167 SUBROUTINE init_random_seed()
10168 INTEGER :: i, n, clock
10169 INTEGER, DIMENSION(:), ALLOCATABLE :: seed
10171 CALL RANDOM_SEED(size = n)
10174 CALL SYSTEM_CLOCK(COUNT=clock)
10176 seed = clock + 37 * (/ (i - 1, i = 1, n) /)
10177 CALL RANDOM_SEED(PUT = seed)
10183 @item @emph{See also}:
10184 @ref{RANDOM_NUMBER}
10190 @section @code{RANGE} --- Decimal exponent range
10192 @cindex model representation, range
10195 @item @emph{Description}:
10196 @code{RANGE(X)} returns the decimal exponent range in the model of the
10199 @item @emph{Standard}:
10200 Fortran 95 and later
10202 @item @emph{Class}:
10205 @item @emph{Syntax}:
10206 @code{RESULT = RANGE(X)}
10208 @item @emph{Arguments}:
10209 @multitable @columnfractions .15 .70
10210 @item @var{X} @tab Shall be of type @code{INTEGER}, @code{REAL}
10214 @item @emph{Return value}:
10215 The return value is of type @code{INTEGER} and of the default integer
10218 @item @emph{See also}:
10219 @ref{SELECTED_REAL_KIND}, @ref{PRECISION}
10221 @item @emph{Example}:
10222 See @code{PRECISION} for an example.
10228 @section @code{RANK} --- Rank of a data object
10233 @item @emph{Description}:
10234 @code{RANK(A)} returns the rank of a scalar or array data object.
10236 @item @emph{Standard}:
10237 Technical Specification (TS) 29113
10239 @item @emph{Class}:
10242 @item @emph{Syntax}:
10243 @code{RESULT = RANGE(A)}
10245 @item @emph{Arguments}:
10246 @multitable @columnfractions .15 .70
10247 @item @var{A} @tab can be of any type
10250 @item @emph{Return value}:
10251 The return value is of type @code{INTEGER} and of the default integer
10252 kind. For arrays, their rank is returned; for scalars zero is returned.
10254 @item @emph{Example}:
10258 real, allocatable :: b(:,:)
10260 print *, rank(a), rank(b) ! Prints: 0 3
10261 end program test_rank
10269 @section @code{REAL} --- Convert to real type
10275 @cindex conversion, to real
10276 @cindex complex numbers, real part
10279 @item @emph{Description}:
10280 @code{REAL(A [, KIND])} converts its argument @var{A} to a real type. The
10281 @code{REALPART} function is provided for compatibility with @command{g77},
10282 and its use is strongly discouraged.
10284 @item @emph{Standard}:
10285 Fortran 77 and later
10287 @item @emph{Class}:
10290 @item @emph{Syntax}:
10291 @multitable @columnfractions .80
10292 @item @code{RESULT = REAL(A [, KIND])}
10293 @item @code{RESULT = REALPART(Z)}
10296 @item @emph{Arguments}:
10297 @multitable @columnfractions .15 .70
10298 @item @var{A} @tab Shall be @code{INTEGER}, @code{REAL}, or
10300 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
10301 expression indicating the kind parameter of the result.
10304 @item @emph{Return value}:
10305 These functions return a @code{REAL} variable or array under
10306 the following rules:
10310 @code{REAL(A)} is converted to a default real type if @var{A} is an
10311 integer or real variable.
10313 @code{REAL(A)} is converted to a real type with the kind type parameter
10314 of @var{A} if @var{A} is a complex variable.
10316 @code{REAL(A, KIND)} is converted to a real type with kind type
10317 parameter @var{KIND} if @var{A} is a complex, integer, or real
10321 @item @emph{Example}:
10324 complex :: x = (1.0, 2.0)
10325 print *, real(x), real(x,8), realpart(x)
10326 end program test_real
10329 @item @emph{Specific names}:
10330 @multitable @columnfractions .20 .20 .20 .25
10331 @item Name @tab Argument @tab Return type @tab Standard
10332 @item @code{FLOAT(A)} @tab @code{INTEGER(4)} @tab @code{REAL(4)} @tab Fortran 77 and later
10333 @item @code{DFLOAT(A)} @tab @code{INTEGER(4)} @tab @code{REAL(8)} @tab GNU extension
10334 @item @code{SNGL(A)} @tab @code{INTEGER(8)} @tab @code{REAL(4)} @tab Fortran 77 and later
10338 @item @emph{See also}:
10346 @section @code{RENAME} --- Rename a file
10348 @cindex file system, rename file
10351 @item @emph{Description}:
10352 Renames a file from file @var{PATH1} to @var{PATH2}. A null
10353 character (@code{CHAR(0)}) can be used to mark the end of the names in
10354 @var{PATH1} and @var{PATH2}; otherwise, trailing blanks in the file
10355 names are ignored. If the @var{STATUS} argument is supplied, it
10356 contains 0 on success or a nonzero error code upon return; see
10359 This intrinsic is provided in both subroutine and function forms;
10360 however, only one form can be used in any given program unit.
10362 @item @emph{Standard}:
10365 @item @emph{Class}:
10366 Subroutine, function
10368 @item @emph{Syntax}:
10369 @multitable @columnfractions .80
10370 @item @code{CALL RENAME(PATH1, PATH2 [, STATUS])}
10371 @item @code{STATUS = RENAME(PATH1, PATH2)}
10374 @item @emph{Arguments}:
10375 @multitable @columnfractions .15 .70
10376 @item @var{PATH1} @tab Shall be of default @code{CHARACTER} type.
10377 @item @var{PATH2} @tab Shall be of default @code{CHARACTER} type.
10378 @item @var{STATUS} @tab (Optional) Shall be of default @code{INTEGER} type.
10381 @item @emph{See also}:
10389 @section @code{REPEAT} --- Repeated string concatenation
10391 @cindex string, repeat
10392 @cindex string, concatenate
10395 @item @emph{Description}:
10396 Concatenates @var{NCOPIES} copies of a string.
10398 @item @emph{Standard}:
10399 Fortran 95 and later
10401 @item @emph{Class}:
10402 Transformational function
10404 @item @emph{Syntax}:
10405 @code{RESULT = REPEAT(STRING, NCOPIES)}
10407 @item @emph{Arguments}:
10408 @multitable @columnfractions .15 .70
10409 @item @var{STRING} @tab Shall be scalar and of type @code{CHARACTER}.
10410 @item @var{NCOPIES} @tab Shall be scalar and of type @code{INTEGER}.
10413 @item @emph{Return value}:
10414 A new scalar of type @code{CHARACTER} built up from @var{NCOPIES} copies
10417 @item @emph{Example}:
10419 program test_repeat
10420 write(*,*) repeat("x", 5) ! "xxxxx"
10428 @section @code{RESHAPE} --- Function to reshape an array
10430 @cindex array, change dimensions
10431 @cindex array, transmogrify
10434 @item @emph{Description}:
10435 Reshapes @var{SOURCE} to correspond to @var{SHAPE}. If necessary,
10436 the new array may be padded with elements from @var{PAD} or permuted
10437 as defined by @var{ORDER}.
10439 @item @emph{Standard}:
10440 Fortran 95 and later
10442 @item @emph{Class}:
10443 Transformational function
10445 @item @emph{Syntax}:
10446 @code{RESULT = RESHAPE(SOURCE, SHAPE[, PAD, ORDER])}
10448 @item @emph{Arguments}:
10449 @multitable @columnfractions .15 .70
10450 @item @var{SOURCE} @tab Shall be an array of any type.
10451 @item @var{SHAPE} @tab Shall be of type @code{INTEGER} and an
10452 array of rank one. Its values must be positive or zero.
10453 @item @var{PAD} @tab (Optional) shall be an array of the same
10454 type as @var{SOURCE}.
10455 @item @var{ORDER} @tab (Optional) shall be of type @code{INTEGER}
10456 and an array of the same shape as @var{SHAPE}. Its values shall
10457 be a permutation of the numbers from 1 to n, where n is the size of
10458 @var{SHAPE}. If @var{ORDER} is absent, the natural ordering shall
10462 @item @emph{Return value}:
10463 The result is an array of shape @var{SHAPE} with the same type as
10466 @item @emph{Example}:
10468 PROGRAM test_reshape
10469 INTEGER, DIMENSION(4) :: x
10470 WRITE(*,*) SHAPE(x) ! prints "4"
10471 WRITE(*,*) SHAPE(RESHAPE(x, (/2, 2/))) ! prints "2 2"
10475 @item @emph{See also}:
10482 @section @code{RRSPACING} --- Reciprocal of the relative spacing
10484 @cindex real number, relative spacing
10485 @cindex floating point, relative spacing
10489 @item @emph{Description}:
10490 @code{RRSPACING(X)} returns the reciprocal of the relative spacing of
10491 model numbers near @var{X}.
10493 @item @emph{Standard}:
10494 Fortran 95 and later
10496 @item @emph{Class}:
10499 @item @emph{Syntax}:
10500 @code{RESULT = RRSPACING(X)}
10502 @item @emph{Arguments}:
10503 @multitable @columnfractions .15 .70
10504 @item @var{X} @tab Shall be of type @code{REAL}.
10507 @item @emph{Return value}:
10508 The return value is of the same type and kind as @var{X}.
10509 The value returned is equal to
10510 @code{ABS(FRACTION(X)) * FLOAT(RADIX(X))**DIGITS(X)}.
10512 @item @emph{See also}:
10519 @section @code{RSHIFT} --- Right shift bits
10521 @cindex bits, shift right
10524 @item @emph{Description}:
10525 @code{RSHIFT} returns a value corresponding to @var{I} with all of the
10526 bits shifted right by @var{SHIFT} places. If the absolute value of
10527 @var{SHIFT} is greater than @code{BIT_SIZE(I)}, the value is undefined.
10528 Bits shifted out from the right end are lost. The fill is arithmetic: the
10529 bits shifted in from the left end are equal to the leftmost bit, which in
10530 two's complement representation is the sign bit.
10532 This function has been superseded by the @code{SHIFTA} intrinsic, which
10533 is standard in Fortran 2008 and later.
10535 @item @emph{Standard}:
10538 @item @emph{Class}:
10541 @item @emph{Syntax}:
10542 @code{RESULT = RSHIFT(I, SHIFT)}
10544 @item @emph{Arguments}:
10545 @multitable @columnfractions .15 .70
10546 @item @var{I} @tab The type shall be @code{INTEGER}.
10547 @item @var{SHIFT} @tab The type shall be @code{INTEGER}.
10550 @item @emph{Return value}:
10551 The return value is of type @code{INTEGER} and of the same kind as
10554 @item @emph{See also}:
10555 @ref{ISHFT}, @ref{ISHFTC}, @ref{LSHIFT}, @ref{SHIFTA}, @ref{SHIFTR},
10563 @section @code{SAME_TYPE_AS} --- Query dynamic types for equality
10564 @fnindex SAME_TYPE_AS
10567 @item @emph{Description}:
10568 Query dynamic types for equality.
10570 @item @emph{Standard}:
10571 Fortran 2003 and later
10573 @item @emph{Class}:
10576 @item @emph{Syntax}:
10577 @code{RESULT = SAME_TYPE_AS(A, B)}
10579 @item @emph{Arguments}:
10580 @multitable @columnfractions .15 .70
10581 @item @var{A} @tab Shall be an object of extensible declared type or
10582 unlimited polymorphic.
10583 @item @var{B} @tab Shall be an object of extensible declared type or
10584 unlimited polymorphic.
10587 @item @emph{Return value}:
10588 The return value is a scalar of type default logical. It is true if and
10589 only if the dynamic type of A is the same as the dynamic type of B.
10591 @item @emph{See also}:
10592 @ref{EXTENDS_TYPE_OF}
10599 @section @code{SCALE} --- Scale a real value
10601 @cindex real number, scale
10602 @cindex floating point, scale
10605 @item @emph{Description}:
10606 @code{SCALE(X,I)} returns @code{X * RADIX(X)**I}.
10608 @item @emph{Standard}:
10609 Fortran 95 and later
10611 @item @emph{Class}:
10614 @item @emph{Syntax}:
10615 @code{RESULT = SCALE(X, I)}
10617 @item @emph{Arguments}:
10618 @multitable @columnfractions .15 .70
10619 @item @var{X} @tab The type of the argument shall be a @code{REAL}.
10620 @item @var{I} @tab The type of the argument shall be a @code{INTEGER}.
10623 @item @emph{Return value}:
10624 The return value is of the same type and kind as @var{X}.
10625 Its value is @code{X * RADIX(X)**I}.
10627 @item @emph{Example}:
10630 real :: x = 178.1387e-4
10632 print *, scale(x,i), x*radix(x)**i
10633 end program test_scale
10641 @section @code{SCAN} --- Scan a string for the presence of a set of characters
10643 @cindex string, find subset
10646 @item @emph{Description}:
10647 Scans a @var{STRING} for any of the characters in a @var{SET}
10650 If @var{BACK} is either absent or equals @code{FALSE}, this function
10651 returns the position of the leftmost character of @var{STRING} that is
10652 in @var{SET}. If @var{BACK} equals @code{TRUE}, the rightmost position
10653 is returned. If no character of @var{SET} is found in @var{STRING}, the
10656 @item @emph{Standard}:
10657 Fortran 95 and later, with @var{KIND} argument Fortran 2003 and later
10659 @item @emph{Class}:
10662 @item @emph{Syntax}:
10663 @code{RESULT = SCAN(STRING, SET[, BACK [, KIND]])}
10665 @item @emph{Arguments}:
10666 @multitable @columnfractions .15 .70
10667 @item @var{STRING} @tab Shall be of type @code{CHARACTER}.
10668 @item @var{SET} @tab Shall be of type @code{CHARACTER}.
10669 @item @var{BACK} @tab (Optional) shall be of type @code{LOGICAL}.
10670 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
10671 expression indicating the kind parameter of the result.
10674 @item @emph{Return value}:
10675 The return value is of type @code{INTEGER} and of kind @var{KIND}. If
10676 @var{KIND} is absent, the return value is of default integer kind.
10678 @item @emph{Example}:
10681 WRITE(*,*) SCAN("FORTRAN", "AO") ! 2, found 'O'
10682 WRITE(*,*) SCAN("FORTRAN", "AO", .TRUE.) ! 6, found 'A'
10683 WRITE(*,*) SCAN("FORTRAN", "C++") ! 0, found none
10687 @item @emph{See also}:
10688 @ref{INDEX intrinsic}, @ref{VERIFY}
10694 @section @code{SECNDS} --- Time function
10696 @cindex time, elapsed
10697 @cindex elapsed time
10700 @item @emph{Description}:
10701 @code{SECNDS(X)} gets the time in seconds from the real-time system clock.
10702 @var{X} is a reference time, also in seconds. If this is zero, the time in
10703 seconds from midnight is returned. This function is non-standard and its
10704 use is discouraged.
10706 @item @emph{Standard}:
10709 @item @emph{Class}:
10712 @item @emph{Syntax}:
10713 @code{RESULT = SECNDS (X)}
10715 @item @emph{Arguments}:
10716 @multitable @columnfractions .15 .70
10717 @item @var{T} @tab Shall be of type @code{REAL(4)}.
10718 @item @var{X} @tab Shall be of type @code{REAL(4)}.
10721 @item @emph{Return value}:
10724 @item @emph{Example}:
10726 program test_secnds
10729 print *, secnds (0.0) ! seconds since midnight
10730 t1 = secnds (0.0) ! reference time
10731 do i = 1, 10000000 ! do something
10733 t2 = secnds (t1) ! elapsed time
10734 print *, "Something took ", t2, " seconds."
10735 end program test_secnds
10742 @section @code{SECOND} --- CPU time function
10744 @cindex time, elapsed
10745 @cindex elapsed time
10748 @item @emph{Description}:
10749 Returns a @code{REAL(4)} value representing the elapsed CPU time in
10750 seconds. This provides the same functionality as the standard
10751 @code{CPU_TIME} intrinsic, and is only included for backwards
10754 This intrinsic is provided in both subroutine and function forms;
10755 however, only one form can be used in any given program unit.
10757 @item @emph{Standard}:
10760 @item @emph{Class}:
10761 Subroutine, function
10763 @item @emph{Syntax}:
10764 @multitable @columnfractions .80
10765 @item @code{CALL SECOND(TIME)}
10766 @item @code{TIME = SECOND()}
10769 @item @emph{Arguments}:
10770 @multitable @columnfractions .15 .70
10771 @item @var{TIME} @tab Shall be of type @code{REAL(4)}.
10774 @item @emph{Return value}:
10775 In either syntax, @var{TIME} is set to the process's current runtime in
10778 @item @emph{See also}:
10785 @node SELECTED_CHAR_KIND
10786 @section @code{SELECTED_CHAR_KIND} --- Choose character kind
10787 @fnindex SELECTED_CHAR_KIND
10788 @cindex character kind
10789 @cindex kind, character
10792 @item @emph{Description}:
10794 @code{SELECTED_CHAR_KIND(NAME)} returns the kind value for the character
10795 set named @var{NAME}, if a character set with such a name is supported,
10796 or @math{-1} otherwise. Currently, supported character sets include
10797 ``ASCII'' and ``DEFAULT'', which are equivalent, and ``ISO_10646''
10798 (Universal Character Set, UCS-4) which is commonly known as Unicode.
10800 @item @emph{Standard}:
10801 Fortran 2003 and later
10803 @item @emph{Class}:
10804 Transformational function
10806 @item @emph{Syntax}:
10807 @code{RESULT = SELECTED_CHAR_KIND(NAME)}
10809 @item @emph{Arguments}:
10810 @multitable @columnfractions .15 .70
10811 @item @var{NAME} @tab Shall be a scalar and of the default character type.
10814 @item @emph{Example}:
10816 program character_kind
10817 use iso_fortran_env
10819 integer, parameter :: ascii = selected_char_kind ("ascii")
10820 integer, parameter :: ucs4 = selected_char_kind ('ISO_10646')
10822 character(kind=ascii, len=26) :: alphabet
10823 character(kind=ucs4, len=30) :: hello_world
10825 alphabet = ascii_"abcdefghijklmnopqrstuvwxyz"
10826 hello_world = ucs4_'Hello World and Ni Hao -- ' &
10827 // char (int (z'4F60'), ucs4) &
10828 // char (int (z'597D'), ucs4)
10830 write (*,*) alphabet
10832 open (output_unit, encoding='UTF-8')
10833 write (*,*) trim (hello_world)
10834 end program character_kind
10840 @node SELECTED_INT_KIND
10841 @section @code{SELECTED_INT_KIND} --- Choose integer kind
10842 @fnindex SELECTED_INT_KIND
10843 @cindex integer kind
10844 @cindex kind, integer
10847 @item @emph{Description}:
10848 @code{SELECTED_INT_KIND(R)} return the kind value of the smallest integer
10849 type that can represent all values ranging from @math{-10^R} (exclusive)
10850 to @math{10^R} (exclusive). If there is no integer kind that accommodates
10851 this range, @code{SELECTED_INT_KIND} returns @math{-1}.
10853 @item @emph{Standard}:
10854 Fortran 95 and later
10856 @item @emph{Class}:
10857 Transformational function
10859 @item @emph{Syntax}:
10860 @code{RESULT = SELECTED_INT_KIND(R)}
10862 @item @emph{Arguments}:
10863 @multitable @columnfractions .15 .70
10864 @item @var{R} @tab Shall be a scalar and of type @code{INTEGER}.
10867 @item @emph{Example}:
10869 program large_integers
10870 integer,parameter :: k5 = selected_int_kind(5)
10871 integer,parameter :: k15 = selected_int_kind(15)
10872 integer(kind=k5) :: i5
10873 integer(kind=k15) :: i15
10875 print *, huge(i5), huge(i15)
10877 ! The following inequalities are always true
10878 print *, huge(i5) >= 10_k5**5-1
10879 print *, huge(i15) >= 10_k15**15-1
10880 end program large_integers
10886 @node SELECTED_REAL_KIND
10887 @section @code{SELECTED_REAL_KIND} --- Choose real kind
10888 @fnindex SELECTED_REAL_KIND
10891 @cindex radix, real
10894 @item @emph{Description}:
10895 @code{SELECTED_REAL_KIND(P,R)} returns the kind value of a real data type
10896 with decimal precision of at least @code{P} digits, exponent range of
10897 at least @code{R}, and with a radix of @code{RADIX}.
10899 @item @emph{Standard}:
10900 Fortran 95 and later, with @code{RADIX} Fortran 2008 or later
10902 @item @emph{Class}:
10903 Transformational function
10905 @item @emph{Syntax}:
10906 @code{RESULT = SELECTED_REAL_KIND([P, R, RADIX])}
10908 @item @emph{Arguments}:
10909 @multitable @columnfractions .15 .70
10910 @item @var{P} @tab (Optional) shall be a scalar and of type @code{INTEGER}.
10911 @item @var{R} @tab (Optional) shall be a scalar and of type @code{INTEGER}.
10912 @item @var{RADIX} @tab (Optional) shall be a scalar and of type @code{INTEGER}.
10914 Before Fortran 2008, at least one of the arguments @var{R} or @var{P} shall
10915 be present; since Fortran 2008, they are assumed to be zero if absent.
10917 @item @emph{Return value}:
10919 @code{SELECTED_REAL_KIND} returns the value of the kind type parameter of
10920 a real data type with decimal precision of at least @code{P} digits, a
10921 decimal exponent range of at least @code{R}, and with the requested
10922 @code{RADIX}. If the @code{RADIX} parameter is absent, real kinds with
10923 any radix can be returned. If more than one real data type meet the
10924 criteria, the kind of the data type with the smallest decimal precision
10925 is returned. If no real data type matches the criteria, the result is
10927 @item -1 if the processor does not support a real data type with a
10928 precision greater than or equal to @code{P}, but the @code{R} and
10929 @code{RADIX} requirements can be fulfilled
10930 @item -2 if the processor does not support a real type with an exponent
10931 range greater than or equal to @code{R}, but @code{P} and @code{RADIX}
10933 @item -3 if @code{RADIX} but not @code{P} and @code{R} requirements
10935 @item -4 if @code{RADIX} and either @code{P} or @code{R} requirements
10937 @item -5 if there is no real type with the given @code{RADIX}
10940 @item @emph{See also}:
10941 @ref{PRECISION}, @ref{RANGE}, @ref{RADIX}
10943 @item @emph{Example}:
10946 integer,parameter :: p6 = selected_real_kind(6)
10947 integer,parameter :: p10r100 = selected_real_kind(10,100)
10948 integer,parameter :: r400 = selected_real_kind(r=400)
10950 real(kind=p10r100) :: y
10951 real(kind=r400) :: z
10953 print *, precision(x), range(x)
10954 print *, precision(y), range(y)
10955 print *, precision(z), range(z)
10956 end program real_kinds
10963 @section @code{SET_EXPONENT} --- Set the exponent of the model
10964 @fnindex SET_EXPONENT
10965 @cindex real number, set exponent
10966 @cindex floating point, set exponent
10969 @item @emph{Description}:
10970 @code{SET_EXPONENT(X, I)} returns the real number whose fractional part
10971 is that that of @var{X} and whose exponent part is @var{I}.
10973 @item @emph{Standard}:
10974 Fortran 95 and later
10976 @item @emph{Class}:
10979 @item @emph{Syntax}:
10980 @code{RESULT = SET_EXPONENT(X, I)}
10982 @item @emph{Arguments}:
10983 @multitable @columnfractions .15 .70
10984 @item @var{X} @tab Shall be of type @code{REAL}.
10985 @item @var{I} @tab Shall be of type @code{INTEGER}.
10988 @item @emph{Return value}:
10989 The return value is of the same type and kind as @var{X}.
10990 The real number whose fractional part
10991 is that that of @var{X} and whose exponent part if @var{I} is returned;
10992 it is @code{FRACTION(X) * RADIX(X)**I}.
10994 @item @emph{Example}:
10996 PROGRAM test_setexp
10997 REAL :: x = 178.1387e-4
10999 PRINT *, SET_EXPONENT(x, i), FRACTION(x) * RADIX(x)**i
11008 @section @code{SHAPE} --- Determine the shape of an array
11010 @cindex array, shape
11013 @item @emph{Description}:
11014 Determines the shape of an array.
11016 @item @emph{Standard}:
11017 Fortran 95 and later, with @var{KIND} argument Fortran 2003 and later
11019 @item @emph{Class}:
11022 @item @emph{Syntax}:
11023 @code{RESULT = SHAPE(SOURCE [, KIND])}
11025 @item @emph{Arguments}:
11026 @multitable @columnfractions .15 .70
11027 @item @var{SOURCE} @tab Shall be an array or scalar of any type.
11028 If @var{SOURCE} is a pointer it must be associated and allocatable
11029 arrays must be allocated.
11030 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
11031 expression indicating the kind parameter of the result.
11034 @item @emph{Return value}:
11035 An @code{INTEGER} array of rank one with as many elements as @var{SOURCE}
11036 has dimensions. The elements of the resulting array correspond to the extend
11037 of @var{SOURCE} along the respective dimensions. If @var{SOURCE} is a scalar,
11038 the result is the rank one array of size zero. If @var{KIND} is absent, the
11039 return value has the default integer kind otherwise the specified kind.
11041 @item @emph{Example}:
11044 INTEGER, DIMENSION(-1:1, -1:2) :: A
11045 WRITE(*,*) SHAPE(A) ! (/ 3, 4 /)
11046 WRITE(*,*) SIZE(SHAPE(42)) ! (/ /)
11050 @item @emph{See also}:
11051 @ref{RESHAPE}, @ref{SIZE}
11057 @section @code{SHIFTA} --- Right shift with fill
11059 @cindex bits, shift right
11060 @cindex shift, right with fill
11063 @item @emph{Description}:
11064 @code{SHIFTA} returns a value corresponding to @var{I} with all of the
11065 bits shifted right by @var{SHIFT} places. If the absolute value of
11066 @var{SHIFT} is greater than @code{BIT_SIZE(I)}, the value is undefined.
11067 Bits shifted out from the right end are lost. The fill is arithmetic: the
11068 bits shifted in from the left end are equal to the leftmost bit, which in
11069 two's complement representation is the sign bit.
11071 @item @emph{Standard}:
11072 Fortran 2008 and later
11074 @item @emph{Class}:
11077 @item @emph{Syntax}:
11078 @code{RESULT = SHIFTA(I, SHIFT)}
11080 @item @emph{Arguments}:
11081 @multitable @columnfractions .15 .70
11082 @item @var{I} @tab The type shall be @code{INTEGER}.
11083 @item @var{SHIFT} @tab The type shall be @code{INTEGER}.
11086 @item @emph{Return value}:
11087 The return value is of type @code{INTEGER} and of the same kind as
11090 @item @emph{See also}:
11091 @ref{SHIFTL}, @ref{SHIFTR}
11097 @section @code{SHIFTL} --- Left shift
11099 @cindex bits, shift left
11100 @cindex shift, left
11103 @item @emph{Description}:
11104 @code{SHIFTL} returns a value corresponding to @var{I} with all of the
11105 bits shifted left by @var{SHIFT} places. If the absolute value of
11106 @var{SHIFT} is greater than @code{BIT_SIZE(I)}, the value is undefined.
11107 Bits shifted out from the left end are lost, and bits shifted in from
11108 the right end are set to 0.
11110 @item @emph{Standard}:
11111 Fortran 2008 and later
11113 @item @emph{Class}:
11116 @item @emph{Syntax}:
11117 @code{RESULT = SHIFTL(I, SHIFT)}
11119 @item @emph{Arguments}:
11120 @multitable @columnfractions .15 .70
11121 @item @var{I} @tab The type shall be @code{INTEGER}.
11122 @item @var{SHIFT} @tab The type shall be @code{INTEGER}.
11125 @item @emph{Return value}:
11126 The return value is of type @code{INTEGER} and of the same kind as
11129 @item @emph{See also}:
11130 @ref{SHIFTA}, @ref{SHIFTR}
11136 @section @code{SHIFTR} --- Right shift
11138 @cindex bits, shift right
11139 @cindex shift, right
11142 @item @emph{Description}:
11143 @code{SHIFTR} returns a value corresponding to @var{I} with all of the
11144 bits shifted right by @var{SHIFT} places. If the absolute value of
11145 @var{SHIFT} is greater than @code{BIT_SIZE(I)}, the value is undefined.
11146 Bits shifted out from the right end are lost, and bits shifted in from
11147 the left end are set to 0.
11149 @item @emph{Standard}:
11150 Fortran 2008 and later
11152 @item @emph{Class}:
11155 @item @emph{Syntax}:
11156 @code{RESULT = SHIFTR(I, SHIFT)}
11158 @item @emph{Arguments}:
11159 @multitable @columnfractions .15 .70
11160 @item @var{I} @tab The type shall be @code{INTEGER}.
11161 @item @var{SHIFT} @tab The type shall be @code{INTEGER}.
11164 @item @emph{Return value}:
11165 The return value is of type @code{INTEGER} and of the same kind as
11168 @item @emph{See also}:
11169 @ref{SHIFTA}, @ref{SHIFTL}
11175 @section @code{SIGN} --- Sign copying function
11179 @cindex sign copying
11182 @item @emph{Description}:
11183 @code{SIGN(A,B)} returns the value of @var{A} with the sign of @var{B}.
11185 @item @emph{Standard}:
11186 Fortran 77 and later
11188 @item @emph{Class}:
11191 @item @emph{Syntax}:
11192 @code{RESULT = SIGN(A, B)}
11194 @item @emph{Arguments}:
11195 @multitable @columnfractions .15 .70
11196 @item @var{A} @tab Shall be of type @code{INTEGER} or @code{REAL}
11197 @item @var{B} @tab Shall be of the same type and kind as @var{A}
11200 @item @emph{Return value}:
11201 The kind of the return value is that of @var{A} and @var{B}.
11202 If @math{B\ge 0} then the result is @code{ABS(A)}, else
11203 it is @code{-ABS(A)}.
11205 @item @emph{Example}:
11208 print *, sign(-12,1)
11209 print *, sign(-12,0)
11210 print *, sign(-12,-1)
11212 print *, sign(-12.,1.)
11213 print *, sign(-12.,0.)
11214 print *, sign(-12.,-1.)
11215 end program test_sign
11218 @item @emph{Specific names}:
11219 @multitable @columnfractions .20 .20 .20 .25
11220 @item Name @tab Arguments @tab Return type @tab Standard
11221 @item @code{SIGN(A,B)} @tab @code{REAL(4) A, B} @tab @code{REAL(4)} @tab f77, gnu
11222 @item @code{ISIGN(A,B)} @tab @code{INTEGER(4) A, B} @tab @code{INTEGER(4)} @tab f77, gnu
11223 @item @code{DSIGN(A,B)} @tab @code{REAL(8) A, B} @tab @code{REAL(8)} @tab f77, gnu
11230 @section @code{SIGNAL} --- Signal handling subroutine (or function)
11232 @cindex system, signal handling
11235 @item @emph{Description}:
11236 @code{SIGNAL(NUMBER, HANDLER [, STATUS])} causes external subroutine
11237 @var{HANDLER} to be executed with a single integer argument when signal
11238 @var{NUMBER} occurs. If @var{HANDLER} is an integer, it can be used to
11239 turn off handling of signal @var{NUMBER} or revert to its default
11240 action. See @code{signal(2)}.
11242 If @code{SIGNAL} is called as a subroutine and the @var{STATUS} argument
11243 is supplied, it is set to the value returned by @code{signal(2)}.
11245 @item @emph{Standard}:
11248 @item @emph{Class}:
11249 Subroutine, function
11251 @item @emph{Syntax}:
11252 @multitable @columnfractions .80
11253 @item @code{CALL SIGNAL(NUMBER, HANDLER [, STATUS])}
11254 @item @code{STATUS = SIGNAL(NUMBER, HANDLER)}
11257 @item @emph{Arguments}:
11258 @multitable @columnfractions .15 .70
11259 @item @var{NUMBER} @tab Shall be a scalar integer, with @code{INTENT(IN)}
11260 @item @var{HANDLER}@tab Signal handler (@code{INTEGER FUNCTION} or
11261 @code{SUBROUTINE}) or dummy/global @code{INTEGER} scalar.
11262 @code{INTEGER}. It is @code{INTENT(IN)}.
11263 @item @var{STATUS} @tab (Optional) @var{STATUS} shall be a scalar
11264 integer. It has @code{INTENT(OUT)}.
11266 @c TODO: What should the interface of the handler be? Does it take arguments?
11268 @item @emph{Return value}:
11269 The @code{SIGNAL} function returns the value returned by @code{signal(2)}.
11271 @item @emph{Example}:
11273 program test_signal
11275 external handler_print
11277 call signal (12, handler_print)
11278 call signal (10, 1)
11281 end program test_signal
11288 @section @code{SIN} --- Sine function
11294 @cindex trigonometric function, sine
11298 @item @emph{Description}:
11299 @code{SIN(X)} computes the sine of @var{X}.
11301 @item @emph{Standard}:
11302 Fortran 77 and later
11304 @item @emph{Class}:
11307 @item @emph{Syntax}:
11308 @code{RESULT = SIN(X)}
11310 @item @emph{Arguments}:
11311 @multitable @columnfractions .15 .70
11312 @item @var{X} @tab The type shall be @code{REAL} or
11316 @item @emph{Return value}:
11317 The return value has same type and kind as @var{X}.
11319 @item @emph{Example}:
11324 end program test_sin
11327 @item @emph{Specific names}:
11328 @multitable @columnfractions .20 .20 .20 .25
11329 @item Name @tab Argument @tab Return type @tab Standard
11330 @item @code{SIN(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab f77, gnu
11331 @item @code{DSIN(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab f95, gnu
11332 @item @code{CSIN(X)} @tab @code{COMPLEX(4) X} @tab @code{COMPLEX(4)} @tab f95, gnu
11333 @item @code{ZSIN(X)} @tab @code{COMPLEX(8) X} @tab @code{COMPLEX(8)} @tab f95, gnu
11334 @item @code{CDSIN(X)} @tab @code{COMPLEX(8) X} @tab @code{COMPLEX(8)} @tab f95, gnu
11337 @item @emph{See also}:
11344 @section @code{SINH} --- Hyperbolic sine function
11347 @cindex hyperbolic sine
11348 @cindex hyperbolic function, sine
11349 @cindex sine, hyperbolic
11352 @item @emph{Description}:
11353 @code{SINH(X)} computes the hyperbolic sine of @var{X}.
11355 @item @emph{Standard}:
11356 Fortran 95 and later, for a complex argument Fortran 2008 or later
11358 @item @emph{Class}:
11361 @item @emph{Syntax}:
11362 @code{RESULT = SINH(X)}
11364 @item @emph{Arguments}:
11365 @multitable @columnfractions .15 .70
11366 @item @var{X} @tab The type shall be @code{REAL} or @code{COMPLEX}.
11369 @item @emph{Return value}:
11370 The return value has same type and kind as @var{X}.
11372 @item @emph{Example}:
11375 real(8) :: x = - 1.0_8
11377 end program test_sinh
11380 @item @emph{Specific names}:
11381 @multitable @columnfractions .20 .20 .20 .25
11382 @item Name @tab Argument @tab Return type @tab Standard
11383 @item @code{SINH(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab Fortran 95 and later
11384 @item @code{DSINH(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab Fortran 95 and later
11387 @item @emph{See also}:
11394 @section @code{SIZE} --- Determine the size of an array
11396 @cindex array, size
11397 @cindex array, number of elements
11398 @cindex array, count elements
11401 @item @emph{Description}:
11402 Determine the extent of @var{ARRAY} along a specified dimension @var{DIM},
11403 or the total number of elements in @var{ARRAY} if @var{DIM} is absent.
11405 @item @emph{Standard}:
11406 Fortran 95 and later, with @var{KIND} argument Fortran 2003 and later
11408 @item @emph{Class}:
11411 @item @emph{Syntax}:
11412 @code{RESULT = SIZE(ARRAY[, DIM [, KIND]])}
11414 @item @emph{Arguments}:
11415 @multitable @columnfractions .15 .70
11416 @item @var{ARRAY} @tab Shall be an array of any type. If @var{ARRAY} is
11417 a pointer it must be associated and allocatable arrays must be allocated.
11418 @item @var{DIM} @tab (Optional) shall be a scalar of type @code{INTEGER}
11419 and its value shall be in the range from 1 to n, where n equals the rank
11421 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
11422 expression indicating the kind parameter of the result.
11425 @item @emph{Return value}:
11426 The return value is of type @code{INTEGER} and of kind @var{KIND}. If
11427 @var{KIND} is absent, the return value is of default integer kind.
11429 @item @emph{Example}:
11432 WRITE(*,*) SIZE((/ 1, 2 /)) ! 2
11436 @item @emph{See also}:
11437 @ref{SHAPE}, @ref{RESHAPE}
11442 @section @code{SIZEOF} --- Size in bytes of an expression
11444 @cindex expression size
11445 @cindex size of an expression
11448 @item @emph{Description}:
11449 @code{SIZEOF(X)} calculates the number of bytes of storage the
11450 expression @code{X} occupies.
11452 @item @emph{Standard}:
11455 @item @emph{Class}:
11458 @item @emph{Syntax}:
11459 @code{N = SIZEOF(X)}
11461 @item @emph{Arguments}:
11462 @multitable @columnfractions .15 .70
11463 @item @var{X} @tab The argument shall be of any type, rank or shape.
11466 @item @emph{Return value}:
11467 The return value is of type integer and of the system-dependent kind
11468 @var{C_SIZE_T} (from the @var{ISO_C_BINDING} module). Its value is the
11469 number of bytes occupied by the argument. If the argument has the
11470 @code{POINTER} attribute, the number of bytes of the storage area pointed
11471 to is returned. If the argument is of a derived type with @code{POINTER}
11472 or @code{ALLOCATABLE} components, the return value does not account for
11473 the sizes of the data pointed to by these components. If the argument is
11474 polymorphic, the size according to the declared type is returned. The argument
11475 may not be a procedure or procedure pointer.
11477 @item @emph{Example}:
11481 print *, (sizeof(s)/sizeof(r) == 5)
11484 The example will print @code{.TRUE.} unless you are using a platform
11485 where default @code{REAL} variables are unusually padded.
11487 @item @emph{See also}:
11488 @ref{C_SIZEOF}, @ref{STORAGE_SIZE}
11493 @section @code{SLEEP} --- Sleep for the specified number of seconds
11495 @cindex delayed execution
11498 @item @emph{Description}:
11499 Calling this subroutine causes the process to pause for @var{SECONDS} seconds.
11501 @item @emph{Standard}:
11504 @item @emph{Class}:
11507 @item @emph{Syntax}:
11508 @code{CALL SLEEP(SECONDS)}
11510 @item @emph{Arguments}:
11511 @multitable @columnfractions .15 .70
11512 @item @var{SECONDS} @tab The type shall be of default @code{INTEGER}.
11515 @item @emph{Example}:
11526 @section @code{SPACING} --- Smallest distance between two numbers of a given type
11528 @cindex real number, relative spacing
11529 @cindex floating point, relative spacing
11532 @item @emph{Description}:
11533 Determines the distance between the argument @var{X} and the nearest
11534 adjacent number of the same type.
11536 @item @emph{Standard}:
11537 Fortran 95 and later
11539 @item @emph{Class}:
11542 @item @emph{Syntax}:
11543 @code{RESULT = SPACING(X)}
11545 @item @emph{Arguments}:
11546 @multitable @columnfractions .15 .70
11547 @item @var{X} @tab Shall be of type @code{REAL}.
11550 @item @emph{Return value}:
11551 The result is of the same type as the input argument @var{X}.
11553 @item @emph{Example}:
11555 PROGRAM test_spacing
11556 INTEGER, PARAMETER :: SGL = SELECTED_REAL_KIND(p=6, r=37)
11557 INTEGER, PARAMETER :: DBL = SELECTED_REAL_KIND(p=13, r=200)
11559 WRITE(*,*) spacing(1.0_SGL) ! "1.1920929E-07" on i686
11560 WRITE(*,*) spacing(1.0_DBL) ! "2.220446049250313E-016" on i686
11564 @item @emph{See also}:
11571 @section @code{SPREAD} --- Add a dimension to an array
11573 @cindex array, increase dimension
11574 @cindex array, duplicate elements
11575 @cindex array, duplicate dimensions
11578 @item @emph{Description}:
11579 Replicates a @var{SOURCE} array @var{NCOPIES} times along a specified
11580 dimension @var{DIM}.
11582 @item @emph{Standard}:
11583 Fortran 95 and later
11585 @item @emph{Class}:
11586 Transformational function
11588 @item @emph{Syntax}:
11589 @code{RESULT = SPREAD(SOURCE, DIM, NCOPIES)}
11591 @item @emph{Arguments}:
11592 @multitable @columnfractions .15 .70
11593 @item @var{SOURCE} @tab Shall be a scalar or an array of any type and
11594 a rank less than seven.
11595 @item @var{DIM} @tab Shall be a scalar of type @code{INTEGER} with a
11596 value in the range from 1 to n+1, where n equals the rank of @var{SOURCE}.
11597 @item @var{NCOPIES} @tab Shall be a scalar of type @code{INTEGER}.
11600 @item @emph{Return value}:
11601 The result is an array of the same type as @var{SOURCE} and has rank n+1
11602 where n equals the rank of @var{SOURCE}.
11604 @item @emph{Example}:
11606 PROGRAM test_spread
11607 INTEGER :: a = 1, b(2) = (/ 1, 2 /)
11608 WRITE(*,*) SPREAD(A, 1, 2) ! "1 1"
11609 WRITE(*,*) SPREAD(B, 1, 2) ! "1 1 2 2"
11613 @item @emph{See also}:
11620 @section @code{SQRT} --- Square-root function
11627 @cindex square-root
11630 @item @emph{Description}:
11631 @code{SQRT(X)} computes the square root of @var{X}.
11633 @item @emph{Standard}:
11634 Fortran 77 and later
11636 @item @emph{Class}:
11639 @item @emph{Syntax}:
11640 @code{RESULT = SQRT(X)}
11642 @item @emph{Arguments}:
11643 @multitable @columnfractions .15 .70
11644 @item @var{X} @tab The type shall be @code{REAL} or
11648 @item @emph{Return value}:
11649 The return value is of type @code{REAL} or @code{COMPLEX}.
11650 The kind type parameter is the same as @var{X}.
11652 @item @emph{Example}:
11655 real(8) :: x = 2.0_8
11656 complex :: z = (1.0, 2.0)
11659 end program test_sqrt
11662 @item @emph{Specific names}:
11663 @multitable @columnfractions .20 .20 .20 .25
11664 @item Name @tab Argument @tab Return type @tab Standard
11665 @item @code{SQRT(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab Fortran 95 and later
11666 @item @code{DSQRT(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab Fortran 95 and later
11667 @item @code{CSQRT(X)} @tab @code{COMPLEX(4) X} @tab @code{COMPLEX(4)} @tab Fortran 95 and later
11668 @item @code{ZSQRT(X)} @tab @code{COMPLEX(8) X} @tab @code{COMPLEX(8)} @tab GNU extension
11669 @item @code{CDSQRT(X)} @tab @code{COMPLEX(8) X} @tab @code{COMPLEX(8)} @tab GNU extension
11676 @section @code{SRAND} --- Reinitialize the random number generator
11678 @cindex random number generation, seeding
11679 @cindex seeding a random number generator
11682 @item @emph{Description}:
11683 @code{SRAND} reinitializes the pseudo-random number generator
11684 called by @code{RAND} and @code{IRAND}. The new seed used by the
11685 generator is specified by the required argument @var{SEED}.
11687 @item @emph{Standard}:
11690 @item @emph{Class}:
11693 @item @emph{Syntax}:
11694 @code{CALL SRAND(SEED)}
11696 @item @emph{Arguments}:
11697 @multitable @columnfractions .15 .70
11698 @item @var{SEED} @tab Shall be a scalar @code{INTEGER(kind=4)}.
11701 @item @emph{Return value}:
11702 Does not return anything.
11704 @item @emph{Example}:
11705 See @code{RAND} and @code{IRAND} for examples.
11707 @item @emph{Notes}:
11708 The Fortran 2003 standard specifies the intrinsic @code{RANDOM_SEED} to
11709 initialize the pseudo-random numbers generator and @code{RANDOM_NUMBER}
11710 to generate pseudo-random numbers. Please note that in
11711 GNU Fortran, these two sets of intrinsics (@code{RAND},
11712 @code{IRAND} and @code{SRAND} on the one hand, @code{RANDOM_NUMBER} and
11713 @code{RANDOM_SEED} on the other hand) access two independent
11714 pseudo-random number generators.
11716 @item @emph{See also}:
11717 @ref{RAND}, @ref{RANDOM_SEED}, @ref{RANDOM_NUMBER}
11724 @section @code{STAT} --- Get file status
11726 @cindex file system, file status
11729 @item @emph{Description}:
11730 This function returns information about a file. No permissions are required on
11731 the file itself, but execute (search) permission is required on all of the
11732 directories in path that lead to the file.
11734 The elements that are obtained and stored in the array @code{VALUES}:
11735 @multitable @columnfractions .15 .70
11736 @item @code{VALUES(1)} @tab Device ID
11737 @item @code{VALUES(2)} @tab Inode number
11738 @item @code{VALUES(3)} @tab File mode
11739 @item @code{VALUES(4)} @tab Number of links
11740 @item @code{VALUES(5)} @tab Owner's uid
11741 @item @code{VALUES(6)} @tab Owner's gid
11742 @item @code{VALUES(7)} @tab ID of device containing directory entry for file (0 if not available)
11743 @item @code{VALUES(8)} @tab File size (bytes)
11744 @item @code{VALUES(9)} @tab Last access time
11745 @item @code{VALUES(10)} @tab Last modification time
11746 @item @code{VALUES(11)} @tab Last file status change time
11747 @item @code{VALUES(12)} @tab Preferred I/O block size (-1 if not available)
11748 @item @code{VALUES(13)} @tab Number of blocks allocated (-1 if not available)
11751 Not all these elements are relevant on all systems.
11752 If an element is not relevant, it is returned as 0.
11754 This intrinsic is provided in both subroutine and function forms; however,
11755 only one form can be used in any given program unit.
11757 @item @emph{Standard}:
11760 @item @emph{Class}:
11761 Subroutine, function
11763 @item @emph{Syntax}:
11764 @multitable @columnfractions .80
11765 @item @code{CALL STAT(NAME, VALUES [, STATUS])}
11766 @item @code{STATUS = STAT(NAME, VALUES)}
11769 @item @emph{Arguments}:
11770 @multitable @columnfractions .15 .70
11771 @item @var{NAME} @tab The type shall be @code{CHARACTER}, of the
11772 default kind and a valid path within the file system.
11773 @item @var{VALUES} @tab The type shall be @code{INTEGER(4), DIMENSION(13)}.
11774 @item @var{STATUS} @tab (Optional) status flag of type @code{INTEGER(4)}. Returns 0
11775 on success and a system specific error code otherwise.
11778 @item @emph{Example}:
11781 INTEGER, DIMENSION(13) :: buff
11784 CALL STAT("/etc/passwd", buff, status)
11786 IF (status == 0) THEN
11787 WRITE (*, FMT="('Device ID:', T30, I19)") buff(1)
11788 WRITE (*, FMT="('Inode number:', T30, I19)") buff(2)
11789 WRITE (*, FMT="('File mode (octal):', T30, O19)") buff(3)
11790 WRITE (*, FMT="('Number of links:', T30, I19)") buff(4)
11791 WRITE (*, FMT="('Owner''s uid:', T30, I19)") buff(5)
11792 WRITE (*, FMT="('Owner''s gid:', T30, I19)") buff(6)
11793 WRITE (*, FMT="('Device where located:', T30, I19)") buff(7)
11794 WRITE (*, FMT="('File size:', T30, I19)") buff(8)
11795 WRITE (*, FMT="('Last access time:', T30, A19)") CTIME(buff(9))
11796 WRITE (*, FMT="('Last modification time', T30, A19)") CTIME(buff(10))
11797 WRITE (*, FMT="('Last status change time:', T30, A19)") CTIME(buff(11))
11798 WRITE (*, FMT="('Preferred block size:', T30, I19)") buff(12)
11799 WRITE (*, FMT="('No. of blocks allocated:', T30, I19)") buff(13)
11804 @item @emph{See also}:
11805 To stat an open file: @ref{FSTAT}, to stat a link: @ref{LSTAT}
11811 @section @code{STORAGE_SIZE} --- Storage size in bits
11812 @fnindex STORAGE_SIZE
11813 @cindex storage size
11816 @item @emph{Description}:
11817 Returns the storage size of argument @var{A} in bits.
11818 @item @emph{Standard}:
11819 Fortran 2008 and later
11820 @item @emph{Class}:
11822 @item @emph{Syntax}:
11823 @code{RESULT = STORAGE_SIZE(A [, KIND])}
11825 @item @emph{Arguments}:
11826 @multitable @columnfractions .15 .70
11827 @item @var{A} @tab Shall be a scalar or array of any type.
11828 @item @var{KIND} @tab (Optional) shall be a scalar integer constant expression.
11831 @item @emph{Return Value}:
11832 The result is a scalar integer with the kind type parameter specified by KIND
11833 (or default integer type if KIND is missing). The result value is the size
11834 expressed in bits for an element of an array that has the dynamic type and type
11837 @item @emph{See also}:
11838 @ref{C_SIZEOF}, @ref{SIZEOF}
11844 @section @code{SUM} --- Sum of array elements
11847 @cindex array, add elements
11848 @cindex array, conditionally add elements
11849 @cindex sum array elements
11852 @item @emph{Description}:
11853 Adds the elements of @var{ARRAY} along dimension @var{DIM} if
11854 the corresponding element in @var{MASK} is @code{TRUE}.
11856 @item @emph{Standard}:
11857 Fortran 95 and later
11859 @item @emph{Class}:
11860 Transformational function
11862 @item @emph{Syntax}:
11863 @multitable @columnfractions .80
11864 @item @code{RESULT = SUM(ARRAY[, MASK])}
11865 @item @code{RESULT = SUM(ARRAY, DIM[, MASK])}
11868 @item @emph{Arguments}:
11869 @multitable @columnfractions .15 .70
11870 @item @var{ARRAY} @tab Shall be an array of type @code{INTEGER},
11871 @code{REAL} or @code{COMPLEX}.
11872 @item @var{DIM} @tab (Optional) shall be a scalar of type
11873 @code{INTEGER} with a value in the range from 1 to n, where n
11874 equals the rank of @var{ARRAY}.
11875 @item @var{MASK} @tab (Optional) shall be of type @code{LOGICAL}
11876 and either be a scalar or an array of the same shape as @var{ARRAY}.
11879 @item @emph{Return value}:
11880 The result is of the same type as @var{ARRAY}.
11882 If @var{DIM} is absent, a scalar with the sum of all elements in @var{ARRAY}
11883 is returned. Otherwise, an array of rank n-1, where n equals the rank of
11884 @var{ARRAY}, and a shape similar to that of @var{ARRAY} with dimension @var{DIM}
11885 dropped is returned.
11887 @item @emph{Example}:
11890 INTEGER :: x(5) = (/ 1, 2, 3, 4 ,5 /)
11891 print *, SUM(x) ! all elements, sum = 15
11892 print *, SUM(x, MASK=MOD(x, 2)==1) ! odd elements, sum = 9
11896 @item @emph{See also}:
11903 @section @code{SYMLNK} --- Create a symbolic link
11905 @cindex file system, create link
11906 @cindex file system, soft link
11909 @item @emph{Description}:
11910 Makes a symbolic link from file @var{PATH1} to @var{PATH2}. A null
11911 character (@code{CHAR(0)}) can be used to mark the end of the names in
11912 @var{PATH1} and @var{PATH2}; otherwise, trailing blanks in the file
11913 names are ignored. If the @var{STATUS} argument is supplied, it
11914 contains 0 on success or a nonzero error code upon return; see
11915 @code{symlink(2)}. If the system does not supply @code{symlink(2)},
11916 @code{ENOSYS} is returned.
11918 This intrinsic is provided in both subroutine and function forms;
11919 however, only one form can be used in any given program unit.
11921 @item @emph{Standard}:
11924 @item @emph{Class}:
11925 Subroutine, function
11927 @item @emph{Syntax}:
11928 @multitable @columnfractions .80
11929 @item @code{CALL SYMLNK(PATH1, PATH2 [, STATUS])}
11930 @item @code{STATUS = SYMLNK(PATH1, PATH2)}
11933 @item @emph{Arguments}:
11934 @multitable @columnfractions .15 .70
11935 @item @var{PATH1} @tab Shall be of default @code{CHARACTER} type.
11936 @item @var{PATH2} @tab Shall be of default @code{CHARACTER} type.
11937 @item @var{STATUS} @tab (Optional) Shall be of default @code{INTEGER} type.
11940 @item @emph{See also}:
11941 @ref{LINK}, @ref{UNLINK}
11948 @section @code{SYSTEM} --- Execute a shell command
11950 @cindex system, system call
11953 @item @emph{Description}:
11954 Passes the command @var{COMMAND} to a shell (see @code{system(3)}). If
11955 argument @var{STATUS} is present, it contains the value returned by
11956 @code{system(3)}, which is presumably 0 if the shell command succeeded.
11957 Note that which shell is used to invoke the command is system-dependent
11958 and environment-dependent.
11960 This intrinsic is provided in both subroutine and function forms;
11961 however, only one form can be used in any given program unit.
11963 Note that the @code{system} function need not be thread-safe. It is
11964 the responsibility of the user to ensure that @code{system} is not
11965 called concurrently.
11967 @item @emph{Standard}:
11970 @item @emph{Class}:
11971 Subroutine, function
11973 @item @emph{Syntax}:
11974 @multitable @columnfractions .80
11975 @item @code{CALL SYSTEM(COMMAND [, STATUS])}
11976 @item @code{STATUS = SYSTEM(COMMAND)}
11979 @item @emph{Arguments}:
11980 @multitable @columnfractions .15 .70
11981 @item @var{COMMAND} @tab Shall be of default @code{CHARACTER} type.
11982 @item @var{STATUS} @tab (Optional) Shall be of default @code{INTEGER} type.
11985 @item @emph{See also}:
11986 @ref{EXECUTE_COMMAND_LINE}, which is part of the Fortran 2008 standard
11987 and should considered in new code for future portability.
11993 @section @code{SYSTEM_CLOCK} --- Time function
11994 @fnindex SYSTEM_CLOCK
11995 @cindex time, clock ticks
11996 @cindex clock ticks
11999 @item @emph{Description}:
12000 Determines the @var{COUNT} of a processor clock since an unspecified
12001 time in the past modulo @var{COUNT_MAX}, @var{COUNT_RATE} determines
12002 the number of clock ticks per second. If the platform supports a high
12003 resolution monotonic clock, that clock is used and can provide up to
12004 nanosecond resolution. If a high resolution monotonic clock is not
12005 available, the implementation falls back to a potentially lower
12006 resolution realtime clock.
12008 @var{COUNT_RATE} and @var{COUNT_MAX} vary depending on the kind of the
12009 arguments. For @var{kind=8} arguments, @var{COUNT} represents
12010 nanoseconds, and for @var{kind=4} arguments, @var{COUNT} represents
12011 milliseconds. Other than the kind dependency, @var{COUNT_RATE} and
12012 @var{COUNT_MAX} are constant, however the particular values are
12013 specific to @command{gfortran}.
12015 If there is no clock, @var{COUNT} is set to @code{-HUGE(COUNT)}, and
12016 @var{COUNT_RATE} and @var{COUNT_MAX} are set to zero.
12018 When running on a platform using the GNU C library (glibc), or a
12019 derivative thereof, the high resolution monotonic clock is available
12020 only when linking with the @var{rt} library. This can be done
12021 explicitly by adding the @code{-lrt} flag when linking the
12022 application, but is also done implicitly when using OpenMP.
12024 @item @emph{Standard}:
12025 Fortran 95 and later
12027 @item @emph{Class}:
12030 @item @emph{Syntax}:
12031 @code{CALL SYSTEM_CLOCK([COUNT, COUNT_RATE, COUNT_MAX])}
12033 @item @emph{Arguments}:
12034 @multitable @columnfractions .15 .70
12035 @item @var{COUNT} @tab (Optional) shall be a scalar of type
12036 @code{INTEGER} with @code{INTENT(OUT)}.
12037 @item @var{COUNT_RATE} @tab (Optional) shall be a scalar of type
12038 @code{INTEGER} with @code{INTENT(OUT)}.
12039 @item @var{COUNT_MAX} @tab (Optional) shall be a scalar of type
12040 @code{INTEGER} with @code{INTENT(OUT)}.
12043 @item @emph{Example}:
12045 PROGRAM test_system_clock
12046 INTEGER :: count, count_rate, count_max
12047 CALL SYSTEM_CLOCK(count, count_rate, count_max)
12048 WRITE(*,*) count, count_rate, count_max
12052 @item @emph{See also}:
12053 @ref{DATE_AND_TIME}, @ref{CPU_TIME}
12059 @section @code{TAN} --- Tangent function
12062 @cindex trigonometric function, tangent
12066 @item @emph{Description}:
12067 @code{TAN(X)} computes the tangent of @var{X}.
12069 @item @emph{Standard}:
12070 Fortran 77 and later, for a complex argument Fortran 2008 or later
12072 @item @emph{Class}:
12075 @item @emph{Syntax}:
12076 @code{RESULT = TAN(X)}
12078 @item @emph{Arguments}:
12079 @multitable @columnfractions .15 .70
12080 @item @var{X} @tab The type shall be @code{REAL} or @code{COMPLEX}.
12083 @item @emph{Return value}:
12084 The return value has same type and kind as @var{X}.
12086 @item @emph{Example}:
12089 real(8) :: x = 0.165_8
12091 end program test_tan
12094 @item @emph{Specific names}:
12095 @multitable @columnfractions .20 .20 .20 .25
12096 @item Name @tab Argument @tab Return type @tab Standard
12097 @item @code{TAN(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab Fortran 95 and later
12098 @item @code{DTAN(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab Fortran 95 and later
12101 @item @emph{See also}:
12108 @section @code{TANH} --- Hyperbolic tangent function
12111 @cindex hyperbolic tangent
12112 @cindex hyperbolic function, tangent
12113 @cindex tangent, hyperbolic
12116 @item @emph{Description}:
12117 @code{TANH(X)} computes the hyperbolic tangent of @var{X}.
12119 @item @emph{Standard}:
12120 Fortran 77 and later, for a complex argument Fortran 2008 or later
12122 @item @emph{Class}:
12125 @item @emph{Syntax}:
12128 @item @emph{Arguments}:
12129 @multitable @columnfractions .15 .70
12130 @item @var{X} @tab The type shall be @code{REAL} or @code{COMPLEX}.
12133 @item @emph{Return value}:
12134 The return value has same type and kind as @var{X}. If @var{X} is
12135 complex, the imaginary part of the result is in radians. If @var{X}
12136 is @code{REAL}, the return value lies in the range
12137 @math{ - 1 \leq tanh(x) \leq 1 }.
12139 @item @emph{Example}:
12142 real(8) :: x = 2.1_8
12144 end program test_tanh
12147 @item @emph{Specific names}:
12148 @multitable @columnfractions .20 .20 .20 .25
12149 @item Name @tab Argument @tab Return type @tab Standard
12150 @item @code{TANH(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab Fortran 95 and later
12151 @item @code{DTANH(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab Fortran 95 and later
12154 @item @emph{See also}:
12161 @section @code{THIS_IMAGE} --- Function that returns the cosubscript index of this image
12162 @fnindex THIS_IMAGE
12163 @cindex coarray, @code{THIS_IMAGE}
12164 @cindex images, index of this image
12167 @item @emph{Description}:
12168 Returns the cosubscript for this image.
12170 @item @emph{Standard}:
12171 Fortran 2008 and later
12173 @item @emph{Class}:
12174 Transformational function
12176 @item @emph{Syntax}:
12177 @multitable @columnfractions .80
12178 @item @code{RESULT = THIS_IMAGE()}
12179 @item @code{RESULT = THIS_IMAGE(COARRAY [, DIM])}
12182 @item @emph{Arguments}:
12183 @multitable @columnfractions .15 .70
12184 @item @var{COARRAY} @tab Coarray of any type (optional; if @var{DIM}
12185 present, required).
12186 @item @var{DIM} @tab default integer scalar (optional). If present,
12187 @var{DIM} shall be between one and the corank of @var{COARRAY}.
12191 @item @emph{Return value}:
12192 Default integer. If @var{COARRAY} is not present, it is scalar and its value
12193 is the index of the invoking image. Otherwise, if @var{DIM} is not present,
12194 a rank-1 array with corank elements is returned, containing the cosubscripts
12195 for @var{COARRAY} specifying the invoking image. If @var{DIM} is present,
12196 a scalar is returned, with the value of the @var{DIM} element of
12197 @code{THIS_IMAGE(COARRAY)}.
12199 @item @emph{Example}:
12201 INTEGER :: value[*]
12203 value = THIS_IMAGE()
12205 IF (THIS_IMAGE() == 1) THEN
12206 DO i = 1, NUM_IMAGES()
12207 WRITE(*,'(2(a,i0))') 'value[', i, '] is ', value[i]
12212 @item @emph{See also}:
12213 @ref{NUM_IMAGES}, @ref{IMAGE_INDEX}
12219 @section @code{TIME} --- Time function
12221 @cindex time, current
12222 @cindex current time
12225 @item @emph{Description}:
12226 Returns the current time encoded as an integer (in the manner of the
12227 function @code{time(3)} in the C standard library). This value is
12228 suitable for passing to @code{CTIME}, @code{GMTIME}, and @code{LTIME}.
12230 This intrinsic is not fully portable, such as to systems with 32-bit
12231 @code{INTEGER} types but supporting times wider than 32 bits. Therefore,
12232 the values returned by this intrinsic might be, or become, negative, or
12233 numerically less than previous values, during a single run of the
12236 See @ref{TIME8}, for information on a similar intrinsic that might be
12237 portable to more GNU Fortran implementations, though to fewer Fortran
12240 @item @emph{Standard}:
12243 @item @emph{Class}:
12246 @item @emph{Syntax}:
12247 @code{RESULT = TIME()}
12249 @item @emph{Return value}:
12250 The return value is a scalar of type @code{INTEGER(4)}.
12252 @item @emph{See also}:
12253 @ref{CTIME}, @ref{GMTIME}, @ref{LTIME}, @ref{MCLOCK}, @ref{TIME8}
12260 @section @code{TIME8} --- Time function (64-bit)
12262 @cindex time, current
12263 @cindex current time
12266 @item @emph{Description}:
12267 Returns the current time encoded as an integer (in the manner of the
12268 function @code{time(3)} in the C standard library). This value is
12269 suitable for passing to @code{CTIME}, @code{GMTIME}, and @code{LTIME}.
12271 @emph{Warning:} this intrinsic does not increase the range of the timing
12272 values over that returned by @code{time(3)}. On a system with a 32-bit
12273 @code{time(3)}, @code{TIME8} will return a 32-bit value, even though
12274 it is converted to a 64-bit @code{INTEGER(8)} value. That means
12275 overflows of the 32-bit value can still occur. Therefore, the values
12276 returned by this intrinsic might be or become negative or numerically
12277 less than previous values during a single run of the compiled program.
12279 @item @emph{Standard}:
12282 @item @emph{Class}:
12285 @item @emph{Syntax}:
12286 @code{RESULT = TIME8()}
12288 @item @emph{Return value}:
12289 The return value is a scalar of type @code{INTEGER(8)}.
12291 @item @emph{See also}:
12292 @ref{CTIME}, @ref{GMTIME}, @ref{LTIME}, @ref{MCLOCK8}, @ref{TIME}
12299 @section @code{TINY} --- Smallest positive number of a real kind
12301 @cindex limits, smallest number
12302 @cindex model representation, smallest number
12305 @item @emph{Description}:
12306 @code{TINY(X)} returns the smallest positive (non zero) number
12307 in the model of the type of @code{X}.
12309 @item @emph{Standard}:
12310 Fortran 95 and later
12312 @item @emph{Class}:
12315 @item @emph{Syntax}:
12316 @code{RESULT = TINY(X)}
12318 @item @emph{Arguments}:
12319 @multitable @columnfractions .15 .70
12320 @item @var{X} @tab Shall be of type @code{REAL}.
12323 @item @emph{Return value}:
12324 The return value is of the same type and kind as @var{X}
12326 @item @emph{Example}:
12327 See @code{HUGE} for an example.
12333 @section @code{TRAILZ} --- Number of trailing zero bits of an integer
12338 @item @emph{Description}:
12339 @code{TRAILZ} returns the number of trailing zero bits of an integer.
12341 @item @emph{Standard}:
12342 Fortran 2008 and later
12344 @item @emph{Class}:
12347 @item @emph{Syntax}:
12348 @code{RESULT = TRAILZ(I)}
12350 @item @emph{Arguments}:
12351 @multitable @columnfractions .15 .70
12352 @item @var{I} @tab Shall be of type @code{INTEGER}.
12355 @item @emph{Return value}:
12356 The type of the return value is the default @code{INTEGER}.
12357 If all the bits of @code{I} are zero, the result value is @code{BIT_SIZE(I)}.
12359 @item @emph{Example}:
12361 PROGRAM test_trailz
12362 WRITE (*,*) TRAILZ(8) ! prints 3
12366 @item @emph{See also}:
12367 @ref{BIT_SIZE}, @ref{LEADZ}, @ref{POPPAR}, @ref{POPCNT}
12373 @section @code{TRANSFER} --- Transfer bit patterns
12379 @item @emph{Description}:
12380 Interprets the bitwise representation of @var{SOURCE} in memory as if it
12381 is the representation of a variable or array of the same type and type
12382 parameters as @var{MOLD}.
12384 This is approximately equivalent to the C concept of @emph{casting} one
12387 @item @emph{Standard}:
12388 Fortran 95 and later
12390 @item @emph{Class}:
12391 Transformational function
12393 @item @emph{Syntax}:
12394 @code{RESULT = TRANSFER(SOURCE, MOLD[, SIZE])}
12396 @item @emph{Arguments}:
12397 @multitable @columnfractions .15 .70
12398 @item @var{SOURCE} @tab Shall be a scalar or an array of any type.
12399 @item @var{MOLD} @tab Shall be a scalar or an array of any type.
12400 @item @var{SIZE} @tab (Optional) shall be a scalar of type
12404 @item @emph{Return value}:
12405 The result has the same type as @var{MOLD}, with the bit level
12406 representation of @var{SOURCE}. If @var{SIZE} is present, the result is
12407 a one-dimensional array of length @var{SIZE}. If @var{SIZE} is absent
12408 but @var{MOLD} is an array (of any size or shape), the result is a one-
12409 dimensional array of the minimum length needed to contain the entirety
12410 of the bitwise representation of @var{SOURCE}. If @var{SIZE} is absent
12411 and @var{MOLD} is a scalar, the result is a scalar.
12413 If the bitwise representation of the result is longer than that of
12414 @var{SOURCE}, then the leading bits of the result correspond to those of
12415 @var{SOURCE} and any trailing bits are filled arbitrarily.
12417 When the resulting bit representation does not correspond to a valid
12418 representation of a variable of the same type as @var{MOLD}, the results
12419 are undefined, and subsequent operations on the result cannot be
12420 guaranteed to produce sensible behavior. For example, it is possible to
12421 create @code{LOGICAL} variables for which @code{@var{VAR}} and
12422 @code{.NOT.@var{VAR}} both appear to be true.
12424 @item @emph{Example}:
12426 PROGRAM test_transfer
12427 integer :: x = 2143289344
12428 print *, transfer(x, 1.0) ! prints "NaN" on i686
12436 @section @code{TRANSPOSE} --- Transpose an array of rank two
12438 @cindex array, transpose
12439 @cindex matrix, transpose
12443 @item @emph{Description}:
12444 Transpose an array of rank two. Element (i, j) of the result has the value
12445 @code{MATRIX(j, i)}, for all i, j.
12447 @item @emph{Standard}:
12448 Fortran 95 and later
12450 @item @emph{Class}:
12451 Transformational function
12453 @item @emph{Syntax}:
12454 @code{RESULT = TRANSPOSE(MATRIX)}
12456 @item @emph{Arguments}:
12457 @multitable @columnfractions .15 .70
12458 @item @var{MATRIX} @tab Shall be an array of any type and have a rank of two.
12461 @item @emph{Return value}:
12462 The result has the same type as @var{MATRIX}, and has shape
12463 @code{(/ m, n /)} if @var{MATRIX} has shape @code{(/ n, m /)}.
12469 @section @code{TRIM} --- Remove trailing blank characters of a string
12471 @cindex string, remove trailing whitespace
12474 @item @emph{Description}:
12475 Removes trailing blank characters of a string.
12477 @item @emph{Standard}:
12478 Fortran 95 and later
12480 @item @emph{Class}:
12481 Transformational function
12483 @item @emph{Syntax}:
12484 @code{RESULT = TRIM(STRING)}
12486 @item @emph{Arguments}:
12487 @multitable @columnfractions .15 .70
12488 @item @var{STRING} @tab Shall be a scalar of type @code{CHARACTER}.
12491 @item @emph{Return value}:
12492 A scalar of type @code{CHARACTER} which length is that of @var{STRING}
12493 less the number of trailing blanks.
12495 @item @emph{Example}:
12498 CHARACTER(len=10), PARAMETER :: s = "GFORTRAN "
12499 WRITE(*,*) LEN(s), LEN(TRIM(s)) ! "10 8", with/without trailing blanks
12503 @item @emph{See also}:
12504 @ref{ADJUSTL}, @ref{ADJUSTR}
12510 @section @code{TTYNAM} --- Get the name of a terminal device.
12512 @cindex system, terminal
12515 @item @emph{Description}:
12516 Get the name of a terminal device. For more information,
12517 see @code{ttyname(3)}.
12519 This intrinsic is provided in both subroutine and function forms;
12520 however, only one form can be used in any given program unit.
12522 @item @emph{Standard}:
12525 @item @emph{Class}:
12526 Subroutine, function
12528 @item @emph{Syntax}:
12529 @multitable @columnfractions .80
12530 @item @code{CALL TTYNAM(UNIT, NAME)}
12531 @item @code{NAME = TTYNAM(UNIT)}
12534 @item @emph{Arguments}:
12535 @multitable @columnfractions .15 .70
12536 @item @var{UNIT} @tab Shall be a scalar @code{INTEGER}.
12537 @item @var{NAME} @tab Shall be of type @code{CHARACTER}.
12540 @item @emph{Example}:
12542 PROGRAM test_ttynam
12545 IF (isatty(unit=unit)) write(*,*) ttynam(unit)
12550 @item @emph{See also}:
12557 @section @code{UBOUND} --- Upper dimension bounds of an array
12559 @cindex array, upper bound
12562 @item @emph{Description}:
12563 Returns the upper bounds of an array, or a single upper bound
12564 along the @var{DIM} dimension.
12565 @item @emph{Standard}:
12566 Fortran 95 and later, with @var{KIND} argument Fortran 2003 and later
12568 @item @emph{Class}:
12571 @item @emph{Syntax}:
12572 @code{RESULT = UBOUND(ARRAY [, DIM [, KIND]])}
12574 @item @emph{Arguments}:
12575 @multitable @columnfractions .15 .70
12576 @item @var{ARRAY} @tab Shall be an array, of any type.
12577 @item @var{DIM} @tab (Optional) Shall be a scalar @code{INTEGER}.
12578 @item @var{KIND}@tab (Optional) An @code{INTEGER} initialization
12579 expression indicating the kind parameter of the result.
12582 @item @emph{Return value}:
12583 The return value is of type @code{INTEGER} and of kind @var{KIND}. If
12584 @var{KIND} is absent, the return value is of default integer kind.
12585 If @var{DIM} is absent, the result is an array of the upper bounds of
12586 @var{ARRAY}. If @var{DIM} is present, the result is a scalar
12587 corresponding to the upper bound of the array along that dimension. If
12588 @var{ARRAY} is an expression rather than a whole array or array
12589 structure component, or if it has a zero extent along the relevant
12590 dimension, the upper bound is taken to be the number of elements along
12591 the relevant dimension.
12593 @item @emph{See also}:
12594 @ref{LBOUND}, @ref{LCOBOUND}
12600 @section @code{UCOBOUND} --- Upper codimension bounds of an array
12602 @cindex coarray, upper bound
12605 @item @emph{Description}:
12606 Returns the upper cobounds of a coarray, or a single upper cobound
12607 along the @var{DIM} codimension.
12608 @item @emph{Standard}:
12609 Fortran 2008 and later
12611 @item @emph{Class}:
12614 @item @emph{Syntax}:
12615 @code{RESULT = UCOBOUND(COARRAY [, DIM [, KIND]])}
12617 @item @emph{Arguments}:
12618 @multitable @columnfractions .15 .70
12619 @item @var{ARRAY} @tab Shall be an coarray, of any type.
12620 @item @var{DIM} @tab (Optional) Shall be a scalar @code{INTEGER}.
12621 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
12622 expression indicating the kind parameter of the result.
12625 @item @emph{Return value}:
12626 The return value is of type @code{INTEGER} and of kind @var{KIND}. If
12627 @var{KIND} is absent, the return value is of default integer kind.
12628 If @var{DIM} is absent, the result is an array of the lower cobounds of
12629 @var{COARRAY}. If @var{DIM} is present, the result is a scalar
12630 corresponding to the lower cobound of the array along that codimension.
12632 @item @emph{See also}:
12633 @ref{LCOBOUND}, @ref{LBOUND}
12639 @section @code{UMASK} --- Set the file creation mask
12641 @cindex file system, file creation mask
12644 @item @emph{Description}:
12645 Sets the file creation mask to @var{MASK}. If called as a function, it
12646 returns the old value. If called as a subroutine and argument @var{OLD}
12647 if it is supplied, it is set to the old value. See @code{umask(2)}.
12649 @item @emph{Standard}:
12652 @item @emph{Class}:
12653 Subroutine, function
12655 @item @emph{Syntax}:
12656 @multitable @columnfractions .80
12657 @item @code{CALL UMASK(MASK [, OLD])}
12658 @item @code{OLD = UMASK(MASK)}
12661 @item @emph{Arguments}:
12662 @multitable @columnfractions .15 .70
12663 @item @var{MASK} @tab Shall be a scalar of type @code{INTEGER}.
12664 @item @var{OLD} @tab (Optional) Shall be a scalar of type
12673 @section @code{UNLINK} --- Remove a file from the file system
12675 @cindex file system, remove file
12678 @item @emph{Description}:
12679 Unlinks the file @var{PATH}. A null character (@code{CHAR(0)}) can be
12680 used to mark the end of the name in @var{PATH}; otherwise, trailing
12681 blanks in the file name are ignored. If the @var{STATUS} argument is
12682 supplied, it contains 0 on success or a nonzero error code upon return;
12683 see @code{unlink(2)}.
12685 This intrinsic is provided in both subroutine and function forms;
12686 however, only one form can be used in any given program unit.
12688 @item @emph{Standard}:
12691 @item @emph{Class}:
12692 Subroutine, function
12694 @item @emph{Syntax}:
12695 @multitable @columnfractions .80
12696 @item @code{CALL UNLINK(PATH [, STATUS])}
12697 @item @code{STATUS = UNLINK(PATH)}
12700 @item @emph{Arguments}:
12701 @multitable @columnfractions .15 .70
12702 @item @var{PATH} @tab Shall be of default @code{CHARACTER} type.
12703 @item @var{STATUS} @tab (Optional) Shall be of default @code{INTEGER} type.
12706 @item @emph{See also}:
12707 @ref{LINK}, @ref{SYMLNK}
12713 @section @code{UNPACK} --- Unpack an array of rank one into an array
12715 @cindex array, unpacking
12716 @cindex array, increase dimension
12717 @cindex array, scatter elements
12720 @item @emph{Description}:
12721 Store the elements of @var{VECTOR} in an array of higher rank.
12723 @item @emph{Standard}:
12724 Fortran 95 and later
12726 @item @emph{Class}:
12727 Transformational function
12729 @item @emph{Syntax}:
12730 @code{RESULT = UNPACK(VECTOR, MASK, FIELD)}
12732 @item @emph{Arguments}:
12733 @multitable @columnfractions .15 .70
12734 @item @var{VECTOR} @tab Shall be an array of any type and rank one. It
12735 shall have at least as many elements as @var{MASK} has @code{TRUE} values.
12736 @item @var{MASK} @tab Shall be an array of type @code{LOGICAL}.
12737 @item @var{FIELD} @tab Shall be of the same type as @var{VECTOR} and have
12738 the same shape as @var{MASK}.
12741 @item @emph{Return value}:
12742 The resulting array corresponds to @var{FIELD} with @code{TRUE} elements
12743 of @var{MASK} replaced by values from @var{VECTOR} in array element order.
12745 @item @emph{Example}:
12747 PROGRAM test_unpack
12748 integer :: vector(2) = (/1,1/)
12749 logical :: mask(4) = (/ .TRUE., .FALSE., .FALSE., .TRUE. /)
12750 integer :: field(2,2) = 0, unity(2,2)
12752 ! result: unity matrix
12753 unity = unpack(vector, reshape(mask, (/2,2/)), field)
12757 @item @emph{See also}:
12758 @ref{PACK}, @ref{SPREAD}
12764 @section @code{VERIFY} --- Scan a string for characters not a given set
12766 @cindex string, find missing set
12769 @item @emph{Description}:
12770 Verifies that all the characters in @var{STRING} belong to the set of
12771 characters in @var{SET}.
12773 If @var{BACK} is either absent or equals @code{FALSE}, this function
12774 returns the position of the leftmost character of @var{STRING} that is
12775 not in @var{SET}. If @var{BACK} equals @code{TRUE}, the rightmost
12776 position is returned. If all characters of @var{STRING} are found in
12777 @var{SET}, the result is zero.
12779 @item @emph{Standard}:
12780 Fortran 95 and later, with @var{KIND} argument Fortran 2003 and later
12782 @item @emph{Class}:
12785 @item @emph{Syntax}:
12786 @code{RESULT = VERIFY(STRING, SET[, BACK [, KIND]])}
12788 @item @emph{Arguments}:
12789 @multitable @columnfractions .15 .70
12790 @item @var{STRING} @tab Shall be of type @code{CHARACTER}.
12791 @item @var{SET} @tab Shall be of type @code{CHARACTER}.
12792 @item @var{BACK} @tab (Optional) shall be of type @code{LOGICAL}.
12793 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
12794 expression indicating the kind parameter of the result.
12797 @item @emph{Return value}:
12798 The return value is of type @code{INTEGER} and of kind @var{KIND}. If
12799 @var{KIND} is absent, the return value is of default integer kind.
12801 @item @emph{Example}:
12803 PROGRAM test_verify
12804 WRITE(*,*) VERIFY("FORTRAN", "AO") ! 1, found 'F'
12805 WRITE(*,*) VERIFY("FORTRAN", "FOO") ! 3, found 'R'
12806 WRITE(*,*) VERIFY("FORTRAN", "C++") ! 1, found 'F'
12807 WRITE(*,*) VERIFY("FORTRAN", "C++", .TRUE.) ! 7, found 'N'
12808 WRITE(*,*) VERIFY("FORTRAN", "FORTRAN") ! 0' found none
12812 @item @emph{See also}:
12813 @ref{SCAN}, @ref{INDEX intrinsic}
12819 @section @code{XOR} --- Bitwise logical exclusive OR
12821 @cindex bitwise logical exclusive or
12822 @cindex logical exclusive or, bitwise
12825 @item @emph{Description}:
12826 Bitwise logical exclusive or.
12828 This intrinsic routine is provided for backwards compatibility with
12829 GNU Fortran 77. For integer arguments, programmers should consider
12830 the use of the @ref{IEOR} intrinsic and for logical arguments the
12831 @code{.NEQV.} operator, which are both defined by the Fortran standard.
12833 @item @emph{Standard}:
12836 @item @emph{Class}:
12839 @item @emph{Syntax}:
12840 @code{RESULT = XOR(I, J)}
12842 @item @emph{Arguments}:
12843 @multitable @columnfractions .15 .70
12844 @item @var{I} @tab The type shall be either a scalar @code{INTEGER}
12845 type or a scalar @code{LOGICAL} type.
12846 @item @var{J} @tab The type shall be the same as the type of @var{I}.
12849 @item @emph{Return value}:
12850 The return type is either a scalar @code{INTEGER} or a scalar
12851 @code{LOGICAL}. If the kind type parameters differ, then the
12852 smaller kind type is implicitly converted to larger kind, and the
12853 return has the larger kind.
12855 @item @emph{Example}:
12858 LOGICAL :: T = .TRUE., F = .FALSE.
12860 DATA a / Z'F' /, b / Z'3' /
12862 WRITE (*,*) XOR(T, T), XOR(T, F), XOR(F, T), XOR(F, F)
12863 WRITE (*,*) XOR(a, b)
12867 @item @emph{See also}:
12868 Fortran 95 elemental function: @ref{IEOR}
12873 @node Intrinsic Modules
12874 @chapter Intrinsic Modules
12875 @cindex intrinsic Modules
12878 * ISO_FORTRAN_ENV::
12880 * OpenMP Modules OMP_LIB and OMP_LIB_KINDS::
12883 @node ISO_FORTRAN_ENV
12884 @section @code{ISO_FORTRAN_ENV}
12886 @item @emph{Standard}:
12887 Fortran 2003 and later, except when otherwise noted
12890 The @code{ISO_FORTRAN_ENV} module provides the following scalar default-integer
12894 @item @code{ATOMIC_INT_KIND}:
12895 Default-kind integer constant to be used as kind parameter when defining
12896 integer variables used in atomic operations. (Fortran 2008 or later.)
12898 @item @code{ATOMIC_LOGICAL_KIND}:
12899 Default-kind integer constant to be used as kind parameter when defining
12900 logical variables used in atomic operations. (Fortran 2008 or later.)
12902 @item @code{CHARACTER_KINDS}:
12903 Default-kind integer constant array of rank one containing the supported kind
12904 parameters of the @code{CHARACTER} type. (Fortran 2008 or later.)
12906 @item @code{CHARACTER_STORAGE_SIZE}:
12907 Size in bits of the character storage unit.
12909 @item @code{ERROR_UNIT}:
12910 Identifies the preconnected unit used for error reporting.
12912 @item @code{FILE_STORAGE_SIZE}:
12913 Size in bits of the file-storage unit.
12915 @item @code{INPUT_UNIT}:
12916 Identifies the preconnected unit identified by the asterisk
12917 (@code{*}) in @code{READ} statement.
12919 @item @code{INT8}, @code{INT16}, @code{INT32}, @code{INT64}:
12920 Kind type parameters to specify an INTEGER type with a storage
12921 size of 16, 32, and 64 bits. It is negative if a target platform
12922 does not support the particular kind. (Fortran 2008 or later.)
12924 @item @code{INTEGER_KINDS}:
12925 Default-kind integer constant array of rank one containing the supported kind
12926 parameters of the @code{INTEGER} type. (Fortran 2008 or later.)
12928 @item @code{IOSTAT_END}:
12929 The value assigned to the variable passed to the @code{IOSTAT=} specifier of
12930 an input/output statement if an end-of-file condition occurred.
12932 @item @code{IOSTAT_EOR}:
12933 The value assigned to the variable passed to the @code{IOSTAT=} specifier of
12934 an input/output statement if an end-of-record condition occurred.
12936 @item @code{IOSTAT_INQUIRE_INTERNAL_UNIT}:
12937 Scalar default-integer constant, used by @code{INQUIRE} for the
12938 @code{IOSTAT=} specifier to denote an that a unit number identifies an
12939 internal unit. (Fortran 2008 or later.)
12941 @item @code{NUMERIC_STORAGE_SIZE}:
12942 The size in bits of the numeric storage unit.
12944 @item @code{LOGICAL_KINDS}:
12945 Default-kind integer constant array of rank one containing the supported kind
12946 parameters of the @code{LOGICAL} type. (Fortran 2008 or later.)
12948 @item @code{OUTPUT_UNIT}:
12949 Identifies the preconnected unit identified by the asterisk
12950 (@code{*}) in @code{WRITE} statement.
12952 @item @code{REAL32}, @code{REAL64}, @code{REAL128}:
12953 Kind type parameters to specify a REAL type with a storage
12954 size of 32, 64, and 128 bits. It is negative if a target platform
12955 does not support the particular kind. (Fortran 2008 or later.)
12957 @item @code{REAL_KINDS}:
12958 Default-kind integer constant array of rank one containing the supported kind
12959 parameters of the @code{REAL} type. (Fortran 2008 or later.)
12961 @item @code{STAT_LOCKED}:
12962 Scalar default-integer constant used as STAT= return value by @code{LOCK} to
12963 denote that the lock variable is locked by the executing image. (Fortran 2008
12966 @item @code{STAT_LOCKED_OTHER_IMAGE}:
12967 Scalar default-integer constant used as STAT= return value by @code{UNLOCK} to
12968 denote that the lock variable is locked by another image. (Fortran 2008 or
12971 @item @code{STAT_STOPPED_IMAGE}:
12972 Positive, scalar default-integer constant used as STAT= return value if the
12973 argument in the statement requires synchronisation with an image, which has
12974 initiated the termination of the execution. (Fortran 2008 or later.)
12976 @item @code{STAT_UNLOCKED}:
12977 Scalar default-integer constant used as STAT= return value by @code{UNLOCK} to
12978 denote that the lock variable is unlocked. (Fortran 2008 or later.)
12981 The module provides the following derived type:
12984 @item @code{LOCK_TYPE}:
12985 Derived type with private components to be use with the @code{LOCK} and
12986 @code{UNLOCK} statement. A variable of its type has to be always declared
12987 as coarray and may not appear in a variable-definition context.
12988 (Fortran 2008 or later.)
12991 The module also provides the following intrinsic procedures:
12992 @ref{COMPILER_OPTIONS} and @ref{COMPILER_VERSION}.
12996 @node ISO_C_BINDING
12997 @section @code{ISO_C_BINDING}
12999 @item @emph{Standard}:
13000 Fortran 2003 and later, GNU extensions
13003 The following intrinsic procedures are provided by the module; their
13004 definition can be found in the section Intrinsic Procedures of this
13008 @item @code{C_ASSOCIATED}
13009 @item @code{C_F_POINTER}
13010 @item @code{C_F_PROCPOINTER}
13011 @item @code{C_FUNLOC}
13013 @item @code{C_SIZEOF}
13015 @c TODO: Vertical spacing between C_FUNLOC and C_LOC wrong in PDF,
13016 @c don't really know why.
13018 The @code{ISO_C_BINDING} module provides the following named constants of
13019 type default integer, which can be used as KIND type parameters.
13021 In addition to the integer named constants required by the Fortran 2003
13022 standard, GNU Fortran provides as an extension named constants for the
13023 128-bit integer types supported by the C compiler: @code{C_INT128_T,
13024 C_INT_LEAST128_T, C_INT_FAST128_T}. Furthermore, if @code{__float} is
13025 supported in C, the named constants @code{C_FLOAT128, C_FLOAT128_COMPLEX}
13028 @multitable @columnfractions .15 .35 .35 .35
13029 @item Fortran Type @tab Named constant @tab C type @tab Extension
13030 @item @code{INTEGER}@tab @code{C_INT} @tab @code{int}
13031 @item @code{INTEGER}@tab @code{C_SHORT} @tab @code{short int}
13032 @item @code{INTEGER}@tab @code{C_LONG} @tab @code{long int}
13033 @item @code{INTEGER}@tab @code{C_LONG_LONG} @tab @code{long long int}
13034 @item @code{INTEGER}@tab @code{C_SIGNED_CHAR} @tab @code{signed char}/@code{unsigned char}
13035 @item @code{INTEGER}@tab @code{C_SIZE_T} @tab @code{size_t}
13036 @item @code{INTEGER}@tab @code{C_INT8_T} @tab @code{int8_t}
13037 @item @code{INTEGER}@tab @code{C_INT16_T} @tab @code{int16_t}
13038 @item @code{INTEGER}@tab @code{C_INT32_T} @tab @code{int32_t}
13039 @item @code{INTEGER}@tab @code{C_INT64_T} @tab @code{int64_t}
13040 @item @code{INTEGER}@tab @code{C_INT128_T} @tab @code{int128_t} @tab Ext.
13041 @item @code{INTEGER}@tab @code{C_INT_LEAST8_T} @tab @code{int_least8_t}
13042 @item @code{INTEGER}@tab @code{C_INT_LEAST16_T} @tab @code{int_least16_t}
13043 @item @code{INTEGER}@tab @code{C_INT_LEAST32_T} @tab @code{int_least32_t}
13044 @item @code{INTEGER}@tab @code{C_INT_LEAST64_T} @tab @code{int_least64_t}
13045 @item @code{INTEGER}@tab @code{C_INT_LEAST128_T}@tab @code{int_least128_t} @tab Ext.
13046 @item @code{INTEGER}@tab @code{C_INT_FAST8_T} @tab @code{int_fast8_t}
13047 @item @code{INTEGER}@tab @code{C_INT_FAST16_T} @tab @code{int_fast16_t}
13048 @item @code{INTEGER}@tab @code{C_INT_FAST32_T} @tab @code{int_fast32_t}
13049 @item @code{INTEGER}@tab @code{C_INT_FAST64_T} @tab @code{int_fast64_t}
13050 @item @code{INTEGER}@tab @code{C_INT_FAST128_T} @tab @code{int_fast128_t} @tab Ext.
13051 @item @code{INTEGER}@tab @code{C_INTMAX_T} @tab @code{intmax_t}
13052 @item @code{INTEGER}@tab @code{C_INTPTR_T} @tab @code{intptr_t}
13053 @item @code{REAL} @tab @code{C_FLOAT} @tab @code{float}
13054 @item @code{REAL} @tab @code{C_DOUBLE} @tab @code{double}
13055 @item @code{REAL} @tab @code{C_LONG_DOUBLE} @tab @code{long double}
13056 @item @code{REAL} @tab @code{C_FLOAT128} @tab @code{__float128} @tab Ext.
13057 @item @code{COMPLEX}@tab @code{C_FLOAT_COMPLEX} @tab @code{float _Complex}
13058 @item @code{COMPLEX}@tab @code{C_DOUBLE_COMPLEX}@tab @code{double _Complex}
13059 @item @code{COMPLEX}@tab @code{C_LONG_DOUBLE_COMPLEX}@tab @code{long double _Complex}
13060 @item @code{REAL} @tab @code{C_FLOAT128_COMPLEX} @tab @code{__float128 _Complex} @tab Ext.
13061 @item @code{LOGICAL}@tab @code{C_BOOL} @tab @code{_Bool}
13062 @item @code{CHARACTER}@tab @code{C_CHAR} @tab @code{char}
13065 Additionally, the following parameters of type @code{CHARACTER(KIND=C_CHAR)}
13068 @multitable @columnfractions .20 .45 .15
13069 @item Name @tab C definition @tab Value
13070 @item @code{C_NULL_CHAR} @tab null character @tab @code{'\0'}
13071 @item @code{C_ALERT} @tab alert @tab @code{'\a'}
13072 @item @code{C_BACKSPACE} @tab backspace @tab @code{'\b'}
13073 @item @code{C_FORM_FEED} @tab form feed @tab @code{'\f'}
13074 @item @code{C_NEW_LINE} @tab new line @tab @code{'\n'}
13075 @item @code{C_CARRIAGE_RETURN} @tab carriage return @tab @code{'\r'}
13076 @item @code{C_HORIZONTAL_TAB} @tab horizontal tab @tab @code{'\t'}
13077 @item @code{C_VERTICAL_TAB} @tab vertical tab @tab @code{'\v'}
13080 Moreover, the following two named constants are defined:
13082 @multitable @columnfractions .20 .80
13083 @item Name @tab Type
13084 @item @code{C_NULL_PTR} @tab @code{C_PTR}
13085 @item @code{C_NULL_FUNPTR} @tab @code{C_FUNPTR}
13088 Both are equivalent to the value @code{NULL} in C.
13090 @node OpenMP Modules OMP_LIB and OMP_LIB_KINDS
13091 @section OpenMP Modules @code{OMP_LIB} and @code{OMP_LIB_KINDS}
13093 @item @emph{Standard}:
13094 OpenMP Application Program Interface v3.1
13098 The OpenMP Fortran runtime library routines are provided both in
13099 a form of two Fortran 90 modules, named @code{OMP_LIB} and
13100 @code{OMP_LIB_KINDS}, and in a form of a Fortran @code{include} file named
13101 @file{omp_lib.h}. The procedures provided by @code{OMP_LIB} can be found
13102 in the @ref{Top,,Introduction,libgomp,GNU OpenMP runtime library} manual,
13103 the named constants defined in the modules are listed
13106 For details refer to the actual
13107 @uref{http://www.openmp.org/mp-documents/spec31.pdf,
13108 OpenMP Application Program Interface v3.1}.
13110 @code{OMP_LIB_KINDS} provides the following scalar default-integer
13114 @item @code{omp_lock_kind}
13115 @item @code{omp_nest_lock_kind}
13116 @item @code{omp_sched_kind}
13119 @code{OMP_LIB} provides the scalar default-integer
13120 named constant @code{openmp_version} with a value of the form
13121 @var{yyyymm}, where @code{yyyy} is the year and @var{mm} the month
13122 of the OpenMP version; for OpenMP v3.1 the value is @code{201107}.
13124 And the following scalar integer named constants of the
13125 kind @code{omp_sched_kind}:
13128 @item @code{omp_sched_static}
13129 @item @code{omp_sched_dynamic}
13130 @item @code{omp_sched_guided}
13131 @item @code{omp_sched_auto}