2 Copyright (C) 2005-2016 Free Software Foundation, Inc.
3 This is part of the GNU Fortran manual.
4 For copying conditions, see the file gfortran.texi.
6 Permission is granted to copy, distribute and/or modify this document
7 under the terms of the GNU Free Documentation License, Version 1.3 or
8 any later version published by the Free Software Foundation; with the
9 Invariant Sections being ``Funding Free Software'', the Front-Cover
10 Texts being (a) (see below), and with the Back-Cover Texts being (b)
11 (see below). A copy of the license is included in the gfdl(7) man page.
14 Some basic guidelines for editing this document:
16 (1) The intrinsic procedures are to be listed in alphabetical order.
17 (2) The generic name is to be used.
18 (3) The specific names are included in the function index and in a
19 table at the end of the node (See ABS entry).
20 (4) Try to maintain the same style for each entry.
26 \gdef\acos{\mathop{\rm acos}\nolimits}
27 \gdef\asin{\mathop{\rm asin}\nolimits}
28 \gdef\atan{\mathop{\rm atan}\nolimits}
29 \gdef\acosh{\mathop{\rm acosh}\nolimits}
30 \gdef\asinh{\mathop{\rm asinh}\nolimits}
31 \gdef\atanh{\mathop{\rm atanh}\nolimits}
35 @node Intrinsic Procedures
36 @chapter Intrinsic Procedures
37 @cindex intrinsic procedures
40 * Introduction: Introduction to Intrinsics
41 * @code{ABORT}: ABORT, Abort the program
42 * @code{ABS}: ABS, Absolute value
43 * @code{ACCESS}: ACCESS, Checks file access modes
44 * @code{ACHAR}: ACHAR, Character in @acronym{ASCII} collating sequence
45 * @code{ACOS}: ACOS, Arccosine function
46 * @code{ACOSH}: ACOSH, Inverse hyperbolic cosine function
47 * @code{ADJUSTL}: ADJUSTL, Left adjust a string
48 * @code{ADJUSTR}: ADJUSTR, Right adjust a string
49 * @code{AIMAG}: AIMAG, Imaginary part of complex number
50 * @code{AINT}: AINT, Truncate to a whole number
51 * @code{ALARM}: ALARM, Set an alarm clock
52 * @code{ALL}: ALL, Determine if all values are true
53 * @code{ALLOCATED}: ALLOCATED, Status of allocatable entity
54 * @code{AND}: AND, Bitwise logical AND
55 * @code{ANINT}: ANINT, Nearest whole number
56 * @code{ANY}: ANY, Determine if any values are true
57 * @code{ASIN}: ASIN, Arcsine function
58 * @code{ASINH}: ASINH, Inverse hyperbolic sine function
59 * @code{ASSOCIATED}: ASSOCIATED, Status of a pointer or pointer/target pair
60 * @code{ATAN}: ATAN, Arctangent function
61 * @code{ATAN2}: ATAN2, Arctangent function
62 * @code{ATANH}: ATANH, Inverse hyperbolic tangent function
63 * @code{ATOMIC_ADD}: ATOMIC_ADD, Atomic ADD operation
64 * @code{ATOMIC_AND}: ATOMIC_AND, Atomic bitwise AND operation
65 * @code{ATOMIC_CAS}: ATOMIC_CAS, Atomic compare and swap
66 * @code{ATOMIC_DEFINE}: ATOMIC_DEFINE, Setting a variable atomically
67 * @code{ATOMIC_FETCH_ADD}: ATOMIC_FETCH_ADD, Atomic ADD operation with prior fetch
68 * @code{ATOMIC_FETCH_AND}: ATOMIC_FETCH_AND, Atomic bitwise AND operation with prior fetch
69 * @code{ATOMIC_FETCH_OR}: ATOMIC_FETCH_OR, Atomic bitwise OR operation with prior fetch
70 * @code{ATOMIC_FETCH_XOR}: ATOMIC_FETCH_XOR, Atomic bitwise XOR operation with prior fetch
71 * @code{ATOMIC_OR}: ATOMIC_OR, Atomic bitwise OR operation
72 * @code{ATOMIC_REF}: ATOMIC_REF, Obtaining the value of a variable atomically
73 * @code{ATOMIC_XOR}: ATOMIC_XOR, Atomic bitwise OR operation
74 * @code{BACKTRACE}: BACKTRACE, Show a backtrace
75 * @code{BESSEL_J0}: BESSEL_J0, Bessel function of the first kind of order 0
76 * @code{BESSEL_J1}: BESSEL_J1, Bessel function of the first kind of order 1
77 * @code{BESSEL_JN}: BESSEL_JN, Bessel function of the first kind
78 * @code{BESSEL_Y0}: BESSEL_Y0, Bessel function of the second kind of order 0
79 * @code{BESSEL_Y1}: BESSEL_Y1, Bessel function of the second kind of order 1
80 * @code{BESSEL_YN}: BESSEL_YN, Bessel function of the second kind
81 * @code{BGE}: BGE, Bitwise greater than or equal to
82 * @code{BGT}: BGT, Bitwise greater than
83 * @code{BIT_SIZE}: BIT_SIZE, Bit size inquiry function
84 * @code{BLE}: BLE, Bitwise less than or equal to
85 * @code{BLT}: BLT, Bitwise less than
86 * @code{BTEST}: BTEST, Bit test function
87 * @code{C_ASSOCIATED}: C_ASSOCIATED, Status of a C pointer
88 * @code{C_F_POINTER}: C_F_POINTER, Convert C into Fortran pointer
89 * @code{C_F_PROCPOINTER}: C_F_PROCPOINTER, Convert C into Fortran procedure pointer
90 * @code{C_FUNLOC}: C_FUNLOC, Obtain the C address of a procedure
91 * @code{C_LOC}: C_LOC, Obtain the C address of an object
92 * @code{C_SIZEOF}: C_SIZEOF, Size in bytes of an expression
93 * @code{CEILING}: CEILING, Integer ceiling function
94 * @code{CHAR}: CHAR, Integer-to-character conversion function
95 * @code{CHDIR}: CHDIR, Change working directory
96 * @code{CHMOD}: CHMOD, Change access permissions of files
97 * @code{CMPLX}: CMPLX, Complex conversion function
98 * @code{CO_BROADCAST}: CO_BROADCAST, Copy a value to all images the current set of images
99 * @code{CO_MAX}: CO_MAX, Maximal value on the current set of images
100 * @code{CO_MIN}: CO_MIN, Minimal value on the current set of images
101 * @code{CO_REDUCE}: CO_REDUCE, Reduction of values on the current set of images
102 * @code{CO_SUM}: CO_SUM, Sum of values on the current set of images
103 * @code{COMMAND_ARGUMENT_COUNT}: COMMAND_ARGUMENT_COUNT, Get number of command line arguments
104 * @code{COMPILER_OPTIONS}: COMPILER_OPTIONS, Options passed to the compiler
105 * @code{COMPILER_VERSION}: COMPILER_VERSION, Compiler version string
106 * @code{COMPLEX}: COMPLEX, Complex conversion function
107 * @code{CONJG}: CONJG, Complex conjugate function
108 * @code{COS}: COS, Cosine function
109 * @code{COSH}: COSH, Hyperbolic cosine function
110 * @code{COUNT}: COUNT, Count occurrences of TRUE in an array
111 * @code{CPU_TIME}: CPU_TIME, CPU time subroutine
112 * @code{CSHIFT}: CSHIFT, Circular shift elements of an array
113 * @code{CTIME}: CTIME, Subroutine (or function) to convert a time into a string
114 * @code{DATE_AND_TIME}: DATE_AND_TIME, Date and time subroutine
115 * @code{DBLE}: DBLE, Double precision conversion function
116 * @code{DCMPLX}: DCMPLX, Double complex conversion function
117 * @code{DIGITS}: DIGITS, Significant digits function
118 * @code{DIM}: DIM, Positive difference
119 * @code{DOT_PRODUCT}: DOT_PRODUCT, Dot product function
120 * @code{DPROD}: DPROD, Double product function
121 * @code{DREAL}: DREAL, Double real part function
122 * @code{DSHIFTL}: DSHIFTL, Combined left shift
123 * @code{DSHIFTR}: DSHIFTR, Combined right shift
124 * @code{DTIME}: DTIME, Execution time subroutine (or function)
125 * @code{EOSHIFT}: EOSHIFT, End-off shift elements of an array
126 * @code{EPSILON}: EPSILON, Epsilon function
127 * @code{ERF}: ERF, Error function
128 * @code{ERFC}: ERFC, Complementary error function
129 * @code{ERFC_SCALED}: ERFC_SCALED, Exponentially-scaled complementary error function
130 * @code{ETIME}: ETIME, Execution time subroutine (or function)
131 * @code{EVENT_QUERY}: EVENT_QUERY, Query whether a coarray event has occurred
132 * @code{EXECUTE_COMMAND_LINE}: EXECUTE_COMMAND_LINE, Execute a shell command
133 * @code{EXIT}: EXIT, Exit the program with status.
134 * @code{EXP}: EXP, Exponential function
135 * @code{EXPONENT}: EXPONENT, Exponent function
136 * @code{EXTENDS_TYPE_OF}: EXTENDS_TYPE_OF, Query dynamic type for extension
137 * @code{FDATE}: FDATE, Subroutine (or function) to get the current time as a string
138 * @code{FGET}: FGET, Read a single character in stream mode from stdin
139 * @code{FGETC}: FGETC, Read a single character in stream mode
140 * @code{FLOOR}: FLOOR, Integer floor function
141 * @code{FLUSH}: FLUSH, Flush I/O unit(s)
142 * @code{FNUM}: FNUM, File number function
143 * @code{FPUT}: FPUT, Write a single character in stream mode to stdout
144 * @code{FPUTC}: FPUTC, Write a single character in stream mode
145 * @code{FRACTION}: FRACTION, Fractional part of the model representation
146 * @code{FREE}: FREE, Memory de-allocation subroutine
147 * @code{FSEEK}: FSEEK, Low level file positioning subroutine
148 * @code{FSTAT}: FSTAT, Get file status
149 * @code{FTELL}: FTELL, Current stream position
150 * @code{GAMMA}: GAMMA, Gamma function
151 * @code{GERROR}: GERROR, Get last system error message
152 * @code{GETARG}: GETARG, Get command line arguments
153 * @code{GET_COMMAND}: GET_COMMAND, Get the entire command line
154 * @code{GET_COMMAND_ARGUMENT}: GET_COMMAND_ARGUMENT, Get command line arguments
155 * @code{GETCWD}: GETCWD, Get current working directory
156 * @code{GETENV}: GETENV, Get an environmental variable
157 * @code{GET_ENVIRONMENT_VARIABLE}: GET_ENVIRONMENT_VARIABLE, Get an environmental variable
158 * @code{GETGID}: GETGID, Group ID function
159 * @code{GETLOG}: GETLOG, Get login name
160 * @code{GETPID}: GETPID, Process ID function
161 * @code{GETUID}: GETUID, User ID function
162 * @code{GMTIME}: GMTIME, Convert time to GMT info
163 * @code{HOSTNM}: HOSTNM, Get system host name
164 * @code{HUGE}: HUGE, Largest number of a kind
165 * @code{HYPOT}: HYPOT, Euclidean distance function
166 * @code{IACHAR}: IACHAR, Code in @acronym{ASCII} collating sequence
167 * @code{IALL}: IALL, Bitwise AND of array elements
168 * @code{IAND}: IAND, Bitwise logical and
169 * @code{IANY}: IANY, Bitwise OR of array elements
170 * @code{IARGC}: IARGC, Get the number of command line arguments
171 * @code{IBCLR}: IBCLR, Clear bit
172 * @code{IBITS}: IBITS, Bit extraction
173 * @code{IBSET}: IBSET, Set bit
174 * @code{ICHAR}: ICHAR, Character-to-integer conversion function
175 * @code{IDATE}: IDATE, Current local time (day/month/year)
176 * @code{IEOR}: IEOR, Bitwise logical exclusive or
177 * @code{IERRNO}: IERRNO, Function to get the last system error number
178 * @code{IMAGE_INDEX}: IMAGE_INDEX, Cosubscript to image index conversion
179 * @code{INDEX}: INDEX intrinsic, Position of a substring within a string
180 * @code{INT}: INT, Convert to integer type
181 * @code{INT2}: INT2, Convert to 16-bit integer type
182 * @code{INT8}: INT8, Convert to 64-bit integer type
183 * @code{IOR}: IOR, Bitwise logical or
184 * @code{IPARITY}: IPARITY, Bitwise XOR of array elements
185 * @code{IRAND}: IRAND, Integer pseudo-random number
186 * @code{IS_IOSTAT_END}: IS_IOSTAT_END, Test for end-of-file value
187 * @code{IS_IOSTAT_EOR}: IS_IOSTAT_EOR, Test for end-of-record value
188 * @code{ISATTY}: ISATTY, Whether a unit is a terminal device
189 * @code{ISHFT}: ISHFT, Shift bits
190 * @code{ISHFTC}: ISHFTC, Shift bits circularly
191 * @code{ISNAN}: ISNAN, Tests for a NaN
192 * @code{ITIME}: ITIME, Current local time (hour/minutes/seconds)
193 * @code{KILL}: KILL, Send a signal to a process
194 * @code{KIND}: KIND, Kind of an entity
195 * @code{LBOUND}: LBOUND, Lower dimension bounds of an array
196 * @code{LCOBOUND}: LCOBOUND, Lower codimension bounds of an array
197 * @code{LEADZ}: LEADZ, Number of leading zero bits of an integer
198 * @code{LEN}: LEN, Length of a character entity
199 * @code{LEN_TRIM}: LEN_TRIM, Length of a character entity without trailing blank characters
200 * @code{LGE}: LGE, Lexical greater than or equal
201 * @code{LGT}: LGT, Lexical greater than
202 * @code{LINK}: LINK, Create a hard link
203 * @code{LLE}: LLE, Lexical less than or equal
204 * @code{LLT}: LLT, Lexical less than
205 * @code{LNBLNK}: LNBLNK, Index of the last non-blank character in a string
206 * @code{LOC}: LOC, Returns the address of a variable
207 * @code{LOG}: LOG, Logarithm function
208 * @code{LOG10}: LOG10, Base 10 logarithm function
209 * @code{LOG_GAMMA}: LOG_GAMMA, Logarithm of the Gamma function
210 * @code{LOGICAL}: LOGICAL, Convert to logical type
211 * @code{LONG}: LONG, Convert to integer type
212 * @code{LSHIFT}: LSHIFT, Left shift bits
213 * @code{LSTAT}: LSTAT, Get file status
214 * @code{LTIME}: LTIME, Convert time to local time info
215 * @code{MALLOC}: MALLOC, Dynamic memory allocation function
216 * @code{MASKL}: MASKL, Left justified mask
217 * @code{MASKR}: MASKR, Right justified mask
218 * @code{MATMUL}: MATMUL, matrix multiplication
219 * @code{MAX}: MAX, Maximum value of an argument list
220 * @code{MAXEXPONENT}: MAXEXPONENT, Maximum exponent of a real kind
221 * @code{MAXLOC}: MAXLOC, Location of the maximum value within an array
222 * @code{MAXVAL}: MAXVAL, Maximum value of an array
223 * @code{MCLOCK}: MCLOCK, Time function
224 * @code{MCLOCK8}: MCLOCK8, Time function (64-bit)
225 * @code{MERGE}: MERGE, Merge arrays
226 * @code{MERGE_BITS}: MERGE_BITS, Merge of bits under mask
227 * @code{MIN}: MIN, Minimum value of an argument list
228 * @code{MINEXPONENT}: MINEXPONENT, Minimum exponent of a real kind
229 * @code{MINLOC}: MINLOC, Location of the minimum value within an array
230 * @code{MINVAL}: MINVAL, Minimum value of an array
231 * @code{MOD}: MOD, Remainder function
232 * @code{MODULO}: MODULO, Modulo function
233 * @code{MOVE_ALLOC}: MOVE_ALLOC, Move allocation from one object to another
234 * @code{MVBITS}: MVBITS, Move bits from one integer to another
235 * @code{NEAREST}: NEAREST, Nearest representable number
236 * @code{NEW_LINE}: NEW_LINE, New line character
237 * @code{NINT}: NINT, Nearest whole number
238 * @code{NORM2}: NORM2, Euclidean vector norm
239 * @code{NOT}: NOT, Logical negation
240 * @code{NULL}: NULL, Function that returns an disassociated pointer
241 * @code{NUM_IMAGES}: NUM_IMAGES, Number of images
242 * @code{OR}: OR, Bitwise logical OR
243 * @code{PACK}: PACK, Pack an array into an array of rank one
244 * @code{PARITY}: PARITY, Reduction with exclusive OR
245 * @code{PERROR}: PERROR, Print system error message
246 * @code{POPCNT}: POPCNT, Number of bits set
247 * @code{POPPAR}: POPPAR, Parity of the number of bits set
248 * @code{PRECISION}: PRECISION, Decimal precision of a real kind
249 * @code{PRESENT}: PRESENT, Determine whether an optional dummy argument is specified
250 * @code{PRODUCT}: PRODUCT, Product of array elements
251 * @code{RADIX}: RADIX, Base of a data model
252 * @code{RAN}: RAN, Real pseudo-random number
253 * @code{RAND}: RAND, Real pseudo-random number
254 * @code{RANDOM_NUMBER}: RANDOM_NUMBER, Pseudo-random number
255 * @code{RANDOM_SEED}: RANDOM_SEED, Initialize a pseudo-random number sequence
256 * @code{RANGE}: RANGE, Decimal exponent range
257 * @code{RANK} : RANK, Rank of a data object
258 * @code{REAL}: REAL, Convert to real type
259 * @code{RENAME}: RENAME, Rename a file
260 * @code{REPEAT}: REPEAT, Repeated string concatenation
261 * @code{RESHAPE}: RESHAPE, Function to reshape an array
262 * @code{RRSPACING}: RRSPACING, Reciprocal of the relative spacing
263 * @code{RSHIFT}: RSHIFT, Right shift bits
264 * @code{SAME_TYPE_AS}: SAME_TYPE_AS, Query dynamic types for equality
265 * @code{SCALE}: SCALE, Scale a real value
266 * @code{SCAN}: SCAN, Scan a string for the presence of a set of characters
267 * @code{SECNDS}: SECNDS, Time function
268 * @code{SECOND}: SECOND, CPU time function
269 * @code{SELECTED_CHAR_KIND}: SELECTED_CHAR_KIND, Choose character kind
270 * @code{SELECTED_INT_KIND}: SELECTED_INT_KIND, Choose integer kind
271 * @code{SELECTED_REAL_KIND}: SELECTED_REAL_KIND, Choose real kind
272 * @code{SET_EXPONENT}: SET_EXPONENT, Set the exponent of the model
273 * @code{SHAPE}: SHAPE, Determine the shape of an array
274 * @code{SHIFTA}: SHIFTA, Right shift with fill
275 * @code{SHIFTL}: SHIFTL, Left shift
276 * @code{SHIFTR}: SHIFTR, Right shift
277 * @code{SIGN}: SIGN, Sign copying function
278 * @code{SIGNAL}: SIGNAL, Signal handling subroutine (or function)
279 * @code{SIN}: SIN, Sine function
280 * @code{SINH}: SINH, Hyperbolic sine function
281 * @code{SIZE}: SIZE, Function to determine the size of an array
282 * @code{SIZEOF}: SIZEOF, Determine the size in bytes of an expression
283 * @code{SLEEP}: SLEEP, Sleep for the specified number of seconds
284 * @code{SPACING}: SPACING, Smallest distance between two numbers of a given type
285 * @code{SPREAD}: SPREAD, Add a dimension to an array
286 * @code{SQRT}: SQRT, Square-root function
287 * @code{SRAND}: SRAND, Reinitialize the random number generator
288 * @code{STAT}: STAT, Get file status
289 * @code{STORAGE_SIZE}: STORAGE_SIZE, Storage size in bits
290 * @code{SUM}: SUM, Sum of array elements
291 * @code{SYMLNK}: SYMLNK, Create a symbolic link
292 * @code{SYSTEM}: SYSTEM, Execute a shell command
293 * @code{SYSTEM_CLOCK}: SYSTEM_CLOCK, Time function
294 * @code{TAN}: TAN, Tangent function
295 * @code{TANH}: TANH, Hyperbolic tangent function
296 * @code{THIS_IMAGE}: THIS_IMAGE, Cosubscript index of this image
297 * @code{TIME}: TIME, Time function
298 * @code{TIME8}: TIME8, Time function (64-bit)
299 * @code{TINY}: TINY, Smallest positive number of a real kind
300 * @code{TRAILZ}: TRAILZ, Number of trailing zero bits of an integer
301 * @code{TRANSFER}: TRANSFER, Transfer bit patterns
302 * @code{TRANSPOSE}: TRANSPOSE, Transpose an array of rank two
303 * @code{TRIM}: TRIM, Remove trailing blank characters of a string
304 * @code{TTYNAM}: TTYNAM, Get the name of a terminal device.
305 * @code{UBOUND}: UBOUND, Upper dimension bounds of an array
306 * @code{UCOBOUND}: UCOBOUND, Upper codimension bounds of an array
307 * @code{UMASK}: UMASK, Set the file creation mask
308 * @code{UNLINK}: UNLINK, Remove a file from the file system
309 * @code{UNPACK}: UNPACK, Unpack an array of rank one into an array
310 * @code{VERIFY}: VERIFY, Scan a string for the absence of a set of characters
311 * @code{XOR}: XOR, Bitwise logical exclusive or
314 @node Introduction to Intrinsics
315 @section Introduction to intrinsic procedures
317 The intrinsic procedures provided by GNU Fortran include all of the
318 intrinsic procedures required by the Fortran 95 standard, a set of
319 intrinsic procedures for backwards compatibility with G77, and a
320 selection of intrinsic procedures from the Fortran 2003 and Fortran 2008
321 standards. Any conflict between a description here and a description in
322 either the Fortran 95 standard, the Fortran 2003 standard or the Fortran
323 2008 standard is unintentional, and the standard(s) should be considered
326 The enumeration of the @code{KIND} type parameter is processor defined in
327 the Fortran 95 standard. GNU Fortran defines the default integer type and
328 default real type by @code{INTEGER(KIND=4)} and @code{REAL(KIND=4)},
329 respectively. The standard mandates that both data types shall have
330 another kind, which have more precision. On typical target architectures
331 supported by @command{gfortran}, this kind type parameter is @code{KIND=8}.
332 Hence, @code{REAL(KIND=8)} and @code{DOUBLE PRECISION} are equivalent.
333 In the description of generic intrinsic procedures, the kind type parameter
334 will be specified by @code{KIND=*}, and in the description of specific
335 names for an intrinsic procedure the kind type parameter will be explicitly
336 given (e.g., @code{REAL(KIND=4)} or @code{REAL(KIND=8)}). Finally, for
337 brevity the optional @code{KIND=} syntax will be omitted.
339 Many of the intrinsic procedures take one or more optional arguments.
340 This document follows the convention used in the Fortran 95 standard,
341 and denotes such arguments by square brackets.
343 GNU Fortran offers the @option{-std=f95} and @option{-std=gnu} options,
344 which can be used to restrict the set of intrinsic procedures to a
345 given standard. By default, @command{gfortran} sets the @option{-std=gnu}
346 option, and so all intrinsic procedures described here are accepted. There
347 is one caveat. For a select group of intrinsic procedures, @command{g77}
348 implemented both a function and a subroutine. Both classes
349 have been implemented in @command{gfortran} for backwards compatibility
350 with @command{g77}. It is noted here that these functions and subroutines
351 cannot be intermixed in a given subprogram. In the descriptions that follow,
352 the applicable standard for each intrinsic procedure is noted.
357 @section @code{ABORT} --- Abort the program
359 @cindex program termination, with core dump
360 @cindex terminate program, with core dump
364 @item @emph{Description}:
365 @code{ABORT} causes immediate termination of the program. On operating
366 systems that support a core dump, @code{ABORT} will produce a core dump.
367 It will also print a backtrace, unless @code{-fno-backtrace} is given.
369 @item @emph{Standard}:
378 @item @emph{Return value}:
381 @item @emph{Example}:
384 integer :: i = 1, j = 2
385 if (i /= j) call abort
386 end program test_abort
389 @item @emph{See also}:
390 @ref{EXIT}, @ref{KILL}, @ref{BACKTRACE}
397 @section @code{ABS} --- Absolute value
408 @cindex absolute value
411 @item @emph{Description}:
412 @code{ABS(A)} computes the absolute value of @code{A}.
414 @item @emph{Standard}:
415 Fortran 77 and later, has overloads that are GNU extensions
421 @code{RESULT = ABS(A)}
423 @item @emph{Arguments}:
424 @multitable @columnfractions .15 .70
425 @item @var{A} @tab The type of the argument shall be an @code{INTEGER},
426 @code{REAL}, or @code{COMPLEX}.
429 @item @emph{Return value}:
430 The return value is of the same type and
431 kind as the argument except the return value is @code{REAL} for a
432 @code{COMPLEX} argument.
434 @item @emph{Example}:
439 complex :: z = (-1.e0,0.e0)
446 @item @emph{Specific names}:
447 @multitable @columnfractions .20 .20 .20 .25
448 @item Name @tab Argument @tab Return type @tab Standard
449 @item @code{ABS(A)} @tab @code{REAL(4) A} @tab @code{REAL(4)} @tab Fortran 77 and later
450 @item @code{CABS(A)} @tab @code{COMPLEX(4) A} @tab @code{REAL(4)} @tab Fortran 77 and later
451 @item @code{DABS(A)} @tab @code{REAL(8) A} @tab @code{REAL(8)} @tab Fortran 77 and later
452 @item @code{IABS(A)} @tab @code{INTEGER(4) A} @tab @code{INTEGER(4)} @tab Fortran 77 and later
453 @item @code{BABS(A)} @tab @code{INTEGER(1) A} @tab @code{INTEGER(1)} @tab GNU extension
454 @item @code{IIABS(A)} @tab @code{INTEGER(2) A} @tab @code{INTEGER(2)} @tab GNU extension
455 @item @code{JIABS(A)} @tab @code{INTEGER(4) A} @tab @code{INTEGER(4)} @tab GNU extension
456 @item @code{KIABS(A)} @tab @code{INTEGER(8) A} @tab @code{INTEGER(8)} @tab GNU extension
457 @item @code{ZABS(A)} @tab @code{COMPLEX(8) A} @tab @code{COMPLEX(8)} @tab GNU extension
458 @item @code{CDABS(A)} @tab @code{COMPLEX(8) A} @tab @code{COMPLEX(8)} @tab GNU extension
465 @section @code{ACCESS} --- Checks file access modes
467 @cindex file system, access mode
470 @item @emph{Description}:
471 @code{ACCESS(NAME, MODE)} checks whether the file @var{NAME}
472 exists, is readable, writable or executable. Except for the
473 executable check, @code{ACCESS} can be replaced by
474 Fortran 95's @code{INQUIRE}.
476 @item @emph{Standard}:
483 @code{RESULT = ACCESS(NAME, MODE)}
485 @item @emph{Arguments}:
486 @multitable @columnfractions .15 .70
487 @item @var{NAME} @tab Scalar @code{CHARACTER} of default kind with the
488 file name. Tailing blank are ignored unless the character @code{achar(0)}
489 is present, then all characters up to and excluding @code{achar(0)} are
491 @item @var{MODE} @tab Scalar @code{CHARACTER} of default kind with the
492 file access mode, may be any concatenation of @code{"r"} (readable),
493 @code{"w"} (writable) and @code{"x"} (executable), or @code{" "} to check
497 @item @emph{Return value}:
498 Returns a scalar @code{INTEGER}, which is @code{0} if the file is
499 accessible in the given mode; otherwise or if an invalid argument
500 has been given for @code{MODE} the value @code{1} is returned.
502 @item @emph{Example}:
506 character(len=*), parameter :: file = 'test.dat'
507 character(len=*), parameter :: file2 = 'test.dat '//achar(0)
508 if(access(file,' ') == 0) print *, trim(file),' is exists'
509 if(access(file,'r') == 0) print *, trim(file),' is readable'
510 if(access(file,'w') == 0) print *, trim(file),' is writable'
511 if(access(file,'x') == 0) print *, trim(file),' is executable'
512 if(access(file2,'rwx') == 0) &
513 print *, trim(file2),' is readable, writable and executable'
514 end program access_test
516 @item @emph{Specific names}:
517 @item @emph{See also}:
524 @section @code{ACHAR} --- Character in @acronym{ASCII} collating sequence
526 @cindex @acronym{ASCII} collating sequence
527 @cindex collating sequence, @acronym{ASCII}
530 @item @emph{Description}:
531 @code{ACHAR(I)} returns the character located at position @code{I}
532 in the @acronym{ASCII} collating sequence.
534 @item @emph{Standard}:
535 Fortran 77 and later, with @var{KIND} argument Fortran 2003 and later
541 @code{RESULT = ACHAR(I [, KIND])}
543 @item @emph{Arguments}:
544 @multitable @columnfractions .15 .70
545 @item @var{I} @tab The type shall be @code{INTEGER}.
546 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
547 expression indicating the kind parameter of the result.
550 @item @emph{Return value}:
551 The return value is of type @code{CHARACTER} with a length of one.
552 If the @var{KIND} argument is present, the return value is of the
553 specified kind and of the default kind otherwise.
555 @item @emph{Example}:
560 end program test_achar
564 See @ref{ICHAR} for a discussion of converting between numerical values
565 and formatted string representations.
567 @item @emph{See also}:
568 @ref{CHAR}, @ref{IACHAR}, @ref{ICHAR}
575 @section @code{ACOS} --- Arccosine function
578 @cindex trigonometric function, cosine, inverse
579 @cindex cosine, inverse
582 @item @emph{Description}:
583 @code{ACOS(X)} computes the arccosine of @var{X} (inverse of @code{COS(X)}).
585 @item @emph{Standard}:
586 Fortran 77 and later, for a complex argument Fortran 2008 or later
592 @code{RESULT = ACOS(X)}
594 @item @emph{Arguments}:
595 @multitable @columnfractions .15 .70
596 @item @var{X} @tab The type shall either be @code{REAL} with a magnitude that is
597 less than or equal to one - or the type shall be @code{COMPLEX}.
600 @item @emph{Return value}:
601 The return value is of the same type and kind as @var{X}.
602 The real part of the result is in radians and lies in the range
603 @math{0 \leq \Re \acos(x) \leq \pi}.
605 @item @emph{Example}:
608 real(8) :: x = 0.866_8
610 end program test_acos
613 @item @emph{Specific names}:
614 @multitable @columnfractions .20 .20 .20 .25
615 @item Name @tab Argument @tab Return type @tab Standard
616 @item @code{ACOS(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab Fortran 77 and later
617 @item @code{DACOS(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab Fortran 77 and later
620 @item @emph{See also}:
621 Inverse function: @ref{COS}
628 @section @code{ACOSH} --- Inverse hyperbolic cosine function
631 @cindex area hyperbolic cosine
632 @cindex inverse hyperbolic cosine
633 @cindex hyperbolic function, cosine, inverse
634 @cindex cosine, hyperbolic, inverse
637 @item @emph{Description}:
638 @code{ACOSH(X)} computes the inverse hyperbolic cosine of @var{X}.
640 @item @emph{Standard}:
641 Fortran 2008 and later
647 @code{RESULT = ACOSH(X)}
649 @item @emph{Arguments}:
650 @multitable @columnfractions .15 .70
651 @item @var{X} @tab The type shall be @code{REAL} or @code{COMPLEX}.
654 @item @emph{Return value}:
655 The return value has the same type and kind as @var{X}. If @var{X} is
656 complex, the imaginary part of the result is in radians and lies between
657 @math{ 0 \leq \Im \acosh(x) \leq \pi}.
659 @item @emph{Example}:
662 REAL(8), DIMENSION(3) :: x = (/ 1.0, 2.0, 3.0 /)
667 @item @emph{Specific names}:
668 @multitable @columnfractions .20 .20 .20 .25
669 @item Name @tab Argument @tab Return type @tab Standard
670 @item @code{DACOSH(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU extension
673 @item @emph{See also}:
674 Inverse function: @ref{COSH}
680 @section @code{ADJUSTL} --- Left adjust a string
682 @cindex string, adjust left
683 @cindex adjust string
686 @item @emph{Description}:
687 @code{ADJUSTL(STRING)} will left adjust a string by removing leading spaces.
688 Spaces are inserted at the end of the string as needed.
690 @item @emph{Standard}:
697 @code{RESULT = ADJUSTL(STRING)}
699 @item @emph{Arguments}:
700 @multitable @columnfractions .15 .70
701 @item @var{STRING} @tab The type shall be @code{CHARACTER}.
704 @item @emph{Return value}:
705 The return value is of type @code{CHARACTER} and of the same kind as
706 @var{STRING} where leading spaces are removed and the same number of
707 spaces are inserted on the end of @var{STRING}.
709 @item @emph{Example}:
712 character(len=20) :: str = ' gfortran'
715 end program test_adjustl
718 @item @emph{See also}:
719 @ref{ADJUSTR}, @ref{TRIM}
725 @section @code{ADJUSTR} --- Right adjust a string
727 @cindex string, adjust right
728 @cindex adjust string
731 @item @emph{Description}:
732 @code{ADJUSTR(STRING)} will right adjust a string by removing trailing spaces.
733 Spaces are inserted at the start of the string as needed.
735 @item @emph{Standard}:
742 @code{RESULT = ADJUSTR(STRING)}
744 @item @emph{Arguments}:
745 @multitable @columnfractions .15 .70
746 @item @var{STR} @tab The type shall be @code{CHARACTER}.
749 @item @emph{Return value}:
750 The return value is of type @code{CHARACTER} and of the same kind as
751 @var{STRING} where trailing spaces are removed and the same number of
752 spaces are inserted at the start of @var{STRING}.
754 @item @emph{Example}:
757 character(len=20) :: str = 'gfortran'
760 end program test_adjustr
763 @item @emph{See also}:
764 @ref{ADJUSTL}, @ref{TRIM}
770 @section @code{AIMAG} --- Imaginary part of complex number
775 @cindex complex numbers, imaginary part
778 @item @emph{Description}:
779 @code{AIMAG(Z)} yields the imaginary part of complex argument @code{Z}.
780 The @code{IMAG(Z)} and @code{IMAGPART(Z)} intrinsic functions are provided
781 for compatibility with @command{g77}, and their use in new code is
782 strongly discouraged.
784 @item @emph{Standard}:
785 Fortran 77 and later, has overloads that are GNU extensions
791 @code{RESULT = AIMAG(Z)}
793 @item @emph{Arguments}:
794 @multitable @columnfractions .15 .70
795 @item @var{Z} @tab The type of the argument shall be @code{COMPLEX}.
798 @item @emph{Return value}:
799 The return value is of type @code{REAL} with the
800 kind type parameter of the argument.
802 @item @emph{Example}:
807 z4 = cmplx(1.e0_4, 0.e0_4)
808 z8 = cmplx(0.e0_8, 1.e0_8)
809 print *, aimag(z4), dimag(z8)
810 end program test_aimag
813 @item @emph{Specific names}:
814 @multitable @columnfractions .20 .20 .20 .25
815 @item Name @tab Argument @tab Return type @tab Standard
816 @item @code{AIMAG(Z)} @tab @code{COMPLEX Z} @tab @code{REAL} @tab GNU extension
817 @item @code{DIMAG(Z)} @tab @code{COMPLEX(8) Z} @tab @code{REAL(8)} @tab GNU extension
818 @item @code{IMAG(Z)} @tab @code{COMPLEX Z} @tab @code{REAL} @tab GNU extension
819 @item @code{IMAGPART(Z)} @tab @code{COMPLEX Z} @tab @code{REAL} @tab GNU extension
826 @section @code{AINT} --- Truncate to a whole number
830 @cindex rounding, floor
833 @item @emph{Description}:
834 @code{AINT(A [, KIND])} truncates its argument to a whole number.
836 @item @emph{Standard}:
843 @code{RESULT = AINT(A [, KIND])}
845 @item @emph{Arguments}:
846 @multitable @columnfractions .15 .70
847 @item @var{A} @tab The type of the argument shall be @code{REAL}.
848 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
849 expression indicating the kind parameter of the result.
852 @item @emph{Return value}:
853 The return value is of type @code{REAL} with the kind type parameter of the
854 argument if the optional @var{KIND} is absent; otherwise, the kind
855 type parameter will be given by @var{KIND}. If the magnitude of
856 @var{X} is less than one, @code{AINT(X)} returns zero. If the
857 magnitude is equal to or greater than one then it returns the largest
858 whole number that does not exceed its magnitude. The sign is the same
859 as the sign of @var{X}.
861 @item @emph{Example}:
868 print *, aint(x4), dint(x8)
870 end program test_aint
873 @item @emph{Specific names}:
874 @multitable @columnfractions .20 .20 .20 .25
875 @item Name @tab Argument @tab Return type @tab Standard
876 @item @code{AINT(A)} @tab @code{REAL(4) A} @tab @code{REAL(4)} @tab Fortran 77 and later
877 @item @code{DINT(A)} @tab @code{REAL(8) A} @tab @code{REAL(8)} @tab Fortran 77 and later
884 @section @code{ALARM} --- Execute a routine after a given delay
886 @cindex delayed execution
889 @item @emph{Description}:
890 @code{ALARM(SECONDS, HANDLER [, STATUS])} causes external subroutine @var{HANDLER}
891 to be executed after a delay of @var{SECONDS} by using @code{alarm(2)} to
892 set up a signal and @code{signal(2)} to catch it. If @var{STATUS} is
893 supplied, it will be returned with the number of seconds remaining until
894 any previously scheduled alarm was due to be delivered, or zero if there
895 was no previously scheduled alarm.
897 @item @emph{Standard}:
904 @code{CALL ALARM(SECONDS, HANDLER [, STATUS])}
906 @item @emph{Arguments}:
907 @multitable @columnfractions .15 .70
908 @item @var{SECONDS} @tab The type of the argument shall be a scalar
909 @code{INTEGER}. It is @code{INTENT(IN)}.
910 @item @var{HANDLER} @tab Signal handler (@code{INTEGER FUNCTION} or
911 @code{SUBROUTINE}) or dummy/global @code{INTEGER} scalar. The scalar
912 values may be either @code{SIG_IGN=1} to ignore the alarm generated
913 or @code{SIG_DFL=0} to set the default action. It is @code{INTENT(IN)}.
914 @item @var{STATUS} @tab (Optional) @var{STATUS} shall be a scalar
915 variable of the default @code{INTEGER} kind. It is @code{INTENT(OUT)}.
918 @item @emph{Example}:
921 external handler_print
923 call alarm (3, handler_print, i)
926 end program test_alarm
928 This will cause the external routine @var{handler_print} to be called
935 @section @code{ALL} --- All values in @var{MASK} along @var{DIM} are true
937 @cindex array, apply condition
938 @cindex array, condition testing
941 @item @emph{Description}:
942 @code{ALL(MASK [, DIM])} determines if all the values are true in @var{MASK}
943 in the array along dimension @var{DIM}.
945 @item @emph{Standard}:
949 Transformational function
952 @code{RESULT = ALL(MASK [, DIM])}
954 @item @emph{Arguments}:
955 @multitable @columnfractions .15 .70
956 @item @var{MASK} @tab The type of the argument shall be @code{LOGICAL} and
957 it shall not be scalar.
958 @item @var{DIM} @tab (Optional) @var{DIM} shall be a scalar integer
959 with a value that lies between one and the rank of @var{MASK}.
962 @item @emph{Return value}:
963 @code{ALL(MASK)} returns a scalar value of type @code{LOGICAL} where
964 the kind type parameter is the same as the kind type parameter of
965 @var{MASK}. If @var{DIM} is present, then @code{ALL(MASK, DIM)} returns
966 an array with the rank of @var{MASK} minus 1. The shape is determined from
967 the shape of @var{MASK} where the @var{DIM} dimension is elided.
971 @code{ALL(MASK)} is true if all elements of @var{MASK} are true.
972 It also is true if @var{MASK} has zero size; otherwise, it is false.
974 If the rank of @var{MASK} is one, then @code{ALL(MASK,DIM)} is equivalent
975 to @code{ALL(MASK)}. If the rank is greater than one, then @code{ALL(MASK,DIM)}
976 is determined by applying @code{ALL} to the array sections.
979 @item @emph{Example}:
983 l = all((/.true., .true., .true./))
988 integer a(2,3), b(2,3)
992 print *, all(a .eq. b, 1)
993 print *, all(a .eq. b, 2)
994 end subroutine section
1002 @section @code{ALLOCATED} --- Status of an allocatable entity
1004 @cindex allocation, status
1007 @item @emph{Description}:
1008 @code{ALLOCATED(ARRAY)} and @code{ALLOCATED(SCALAR)} check the allocation
1009 status of @var{ARRAY} and @var{SCALAR}, respectively.
1011 @item @emph{Standard}:
1012 Fortran 95 and later. Note, the @code{SCALAR=} keyword and allocatable
1013 scalar entities are available in Fortran 2003 and later.
1018 @item @emph{Syntax}:
1019 @multitable @columnfractions .80
1020 @item @code{RESULT = ALLOCATED(ARRAY)}
1021 @item @code{RESULT = ALLOCATED(SCALAR)}
1024 @item @emph{Arguments}:
1025 @multitable @columnfractions .15 .70
1026 @item @var{ARRAY} @tab The argument shall be an @code{ALLOCATABLE} array.
1027 @item @var{SCALAR} @tab The argument shall be an @code{ALLOCATABLE} scalar.
1030 @item @emph{Return value}:
1031 The return value is a scalar @code{LOGICAL} with the default logical
1032 kind type parameter. If the argument is allocated, then the result is
1033 @code{.TRUE.}; otherwise, it returns @code{.FALSE.}
1035 @item @emph{Example}:
1037 program test_allocated
1039 real(4), allocatable :: x(:)
1040 if (.not. allocated(x)) allocate(x(i))
1041 end program test_allocated
1048 @section @code{AND} --- Bitwise logical AND
1050 @cindex bitwise logical and
1051 @cindex logical and, bitwise
1054 @item @emph{Description}:
1055 Bitwise logical @code{AND}.
1057 This intrinsic routine is provided for backwards compatibility with
1058 GNU Fortran 77. For integer arguments, programmers should consider
1059 the use of the @ref{IAND} intrinsic defined by the Fortran standard.
1061 @item @emph{Standard}:
1067 @item @emph{Syntax}:
1068 @code{RESULT = AND(I, J)}
1070 @item @emph{Arguments}:
1071 @multitable @columnfractions .15 .70
1072 @item @var{I} @tab The type shall be either a scalar @code{INTEGER}
1073 type or a scalar @code{LOGICAL} type.
1074 @item @var{J} @tab The type shall be the same as the type of @var{I}.
1077 @item @emph{Return value}:
1078 The return type is either a scalar @code{INTEGER} or a scalar
1079 @code{LOGICAL}. If the kind type parameters differ, then the
1080 smaller kind type is implicitly converted to larger kind, and the
1081 return has the larger kind.
1083 @item @emph{Example}:
1086 LOGICAL :: T = .TRUE., F = .FALSE.
1088 DATA a / Z'F' /, b / Z'3' /
1090 WRITE (*,*) AND(T, T), AND(T, F), AND(F, T), AND(F, F)
1091 WRITE (*,*) AND(a, b)
1095 @item @emph{See also}:
1096 Fortran 95 elemental function: @ref{IAND}
1102 @section @code{ANINT} --- Nearest whole number
1106 @cindex rounding, ceiling
1109 @item @emph{Description}:
1110 @code{ANINT(A [, KIND])} rounds its argument to the nearest whole number.
1112 @item @emph{Standard}:
1113 Fortran 77 and later
1118 @item @emph{Syntax}:
1119 @code{RESULT = ANINT(A [, KIND])}
1121 @item @emph{Arguments}:
1122 @multitable @columnfractions .15 .70
1123 @item @var{A} @tab The type of the argument shall be @code{REAL}.
1124 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
1125 expression indicating the kind parameter of the result.
1128 @item @emph{Return value}:
1129 The return value is of type real with the kind type parameter of the
1130 argument if the optional @var{KIND} is absent; otherwise, the kind
1131 type parameter will be given by @var{KIND}. If @var{A} is greater than
1132 zero, @code{ANINT(A)} returns @code{AINT(X+0.5)}. If @var{A} is
1133 less than or equal to zero then it returns @code{AINT(X-0.5)}.
1135 @item @emph{Example}:
1142 print *, anint(x4), dnint(x8)
1144 end program test_anint
1147 @item @emph{Specific names}:
1148 @multitable @columnfractions .20 .20 .20 .25
1149 @item Name @tab Argument @tab Return type @tab Standard
1150 @item @code{AINT(A)} @tab @code{REAL(4) A} @tab @code{REAL(4)} @tab Fortran 77 and later
1151 @item @code{DNINT(A)} @tab @code{REAL(8) A} @tab @code{REAL(8)} @tab Fortran 77 and later
1158 @section @code{ANY} --- Any value in @var{MASK} along @var{DIM} is true
1160 @cindex array, apply condition
1161 @cindex array, condition testing
1164 @item @emph{Description}:
1165 @code{ANY(MASK [, DIM])} determines if any of the values in the logical array
1166 @var{MASK} along dimension @var{DIM} are @code{.TRUE.}.
1168 @item @emph{Standard}:
1169 Fortran 95 and later
1172 Transformational function
1174 @item @emph{Syntax}:
1175 @code{RESULT = ANY(MASK [, DIM])}
1177 @item @emph{Arguments}:
1178 @multitable @columnfractions .15 .70
1179 @item @var{MASK} @tab The type of the argument shall be @code{LOGICAL} and
1180 it shall not be scalar.
1181 @item @var{DIM} @tab (Optional) @var{DIM} shall be a scalar integer
1182 with a value that lies between one and the rank of @var{MASK}.
1185 @item @emph{Return value}:
1186 @code{ANY(MASK)} returns a scalar value of type @code{LOGICAL} where
1187 the kind type parameter is the same as the kind type parameter of
1188 @var{MASK}. If @var{DIM} is present, then @code{ANY(MASK, DIM)} returns
1189 an array with the rank of @var{MASK} minus 1. The shape is determined from
1190 the shape of @var{MASK} where the @var{DIM} dimension is elided.
1194 @code{ANY(MASK)} is true if any element of @var{MASK} is true;
1195 otherwise, it is false. It also is false if @var{MASK} has zero size.
1197 If the rank of @var{MASK} is one, then @code{ANY(MASK,DIM)} is equivalent
1198 to @code{ANY(MASK)}. If the rank is greater than one, then @code{ANY(MASK,DIM)}
1199 is determined by applying @code{ANY} to the array sections.
1202 @item @emph{Example}:
1206 l = any((/.true., .true., .true./))
1211 integer a(2,3), b(2,3)
1215 print *, any(a .eq. b, 1)
1216 print *, any(a .eq. b, 2)
1217 end subroutine section
1218 end program test_any
1225 @section @code{ASIN} --- Arcsine function
1228 @cindex trigonometric function, sine, inverse
1229 @cindex sine, inverse
1232 @item @emph{Description}:
1233 @code{ASIN(X)} computes the arcsine of its @var{X} (inverse of @code{SIN(X)}).
1235 @item @emph{Standard}:
1236 Fortran 77 and later, for a complex argument Fortran 2008 or later
1241 @item @emph{Syntax}:
1242 @code{RESULT = ASIN(X)}
1244 @item @emph{Arguments}:
1245 @multitable @columnfractions .15 .70
1246 @item @var{X} @tab The type shall be either @code{REAL} and a magnitude that is
1247 less than or equal to one - or be @code{COMPLEX}.
1250 @item @emph{Return value}:
1251 The return value is of the same type and kind as @var{X}.
1252 The real part of the result is in radians and lies in the range
1253 @math{-\pi/2 \leq \Re \asin(x) \leq \pi/2}.
1255 @item @emph{Example}:
1258 real(8) :: x = 0.866_8
1260 end program test_asin
1263 @item @emph{Specific names}:
1264 @multitable @columnfractions .20 .20 .20 .25
1265 @item Name @tab Argument @tab Return type @tab Standard
1266 @item @code{ASIN(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab Fortran 77 and later
1267 @item @code{DASIN(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab Fortran 77 and later
1270 @item @emph{See also}:
1271 Inverse function: @ref{SIN}
1278 @section @code{ASINH} --- Inverse hyperbolic sine function
1281 @cindex area hyperbolic sine
1282 @cindex inverse hyperbolic sine
1283 @cindex hyperbolic function, sine, inverse
1284 @cindex sine, hyperbolic, inverse
1287 @item @emph{Description}:
1288 @code{ASINH(X)} computes the inverse hyperbolic sine of @var{X}.
1290 @item @emph{Standard}:
1291 Fortran 2008 and later
1296 @item @emph{Syntax}:
1297 @code{RESULT = ASINH(X)}
1299 @item @emph{Arguments}:
1300 @multitable @columnfractions .15 .70
1301 @item @var{X} @tab The type shall be @code{REAL} or @code{COMPLEX}.
1304 @item @emph{Return value}:
1305 The return value is of the same type and kind as @var{X}. If @var{X} is
1306 complex, the imaginary part of the result is in radians and lies between
1307 @math{-\pi/2 \leq \Im \asinh(x) \leq \pi/2}.
1309 @item @emph{Example}:
1312 REAL(8), DIMENSION(3) :: x = (/ -1.0, 0.0, 1.0 /)
1313 WRITE (*,*) ASINH(x)
1317 @item @emph{Specific names}:
1318 @multitable @columnfractions .20 .20 .20 .25
1319 @item Name @tab Argument @tab Return type @tab Standard
1320 @item @code{DASINH(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU extension.
1323 @item @emph{See also}:
1324 Inverse function: @ref{SINH}
1330 @section @code{ASSOCIATED} --- Status of a pointer or pointer/target pair
1332 @cindex pointer, status
1333 @cindex association status
1336 @item @emph{Description}:
1337 @code{ASSOCIATED(POINTER [, TARGET])} determines the status of the pointer
1338 @var{POINTER} or if @var{POINTER} is associated with the target @var{TARGET}.
1340 @item @emph{Standard}:
1341 Fortran 95 and later
1346 @item @emph{Syntax}:
1347 @code{RESULT = ASSOCIATED(POINTER [, TARGET])}
1349 @item @emph{Arguments}:
1350 @multitable @columnfractions .15 .70
1351 @item @var{POINTER} @tab @var{POINTER} shall have the @code{POINTER} attribute
1352 and it can be of any type.
1353 @item @var{TARGET} @tab (Optional) @var{TARGET} shall be a pointer or
1354 a target. It must have the same type, kind type parameter, and
1355 array rank as @var{POINTER}.
1357 The association status of neither @var{POINTER} nor @var{TARGET} shall be
1360 @item @emph{Return value}:
1361 @code{ASSOCIATED(POINTER)} returns a scalar value of type @code{LOGICAL(4)}.
1362 There are several cases:
1364 @item (A) When the optional @var{TARGET} is not present then
1365 @code{ASSOCIATED(POINTER)} is true if @var{POINTER} is associated with a target; otherwise, it returns false.
1366 @item (B) If @var{TARGET} is present and a scalar target, the result is true if
1367 @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
1368 disassociated, the result is false.
1369 @item (C) If @var{TARGET} is present and an array target, the result is true if
1370 @var{TARGET} and @var{POINTER} have the same shape, are not zero-sized arrays,
1371 are arrays whose elements are not zero-sized storage sequences, and
1372 @var{TARGET} and @var{POINTER} occupy the same storage units in array element
1374 As in case(B), the result is false, if @var{POINTER} is disassociated.
1375 @item (D) If @var{TARGET} is present and an scalar pointer, the result is true
1376 if @var{TARGET} is associated with @var{POINTER}, the target associated with
1377 @var{TARGET} are not zero-sized storage sequences and occupy the same storage
1379 The result is false, if either @var{TARGET} or @var{POINTER} is disassociated.
1380 @item (E) If @var{TARGET} is present and an array pointer, the result is true if
1381 target associated with @var{POINTER} and the target associated with @var{TARGET}
1382 have the same shape, are not zero-sized arrays, are arrays whose elements are
1383 not zero-sized storage sequences, and @var{TARGET} and @var{POINTER} occupy
1384 the same storage units in array element order.
1385 The result is false, if either @var{TARGET} or @var{POINTER} is disassociated.
1388 @item @emph{Example}:
1390 program test_associated
1392 real, target :: tgt(2) = (/1., 2./)
1393 real, pointer :: ptr(:)
1395 if (associated(ptr) .eqv. .false.) call abort
1396 if (associated(ptr,tgt) .eqv. .false.) call abort
1397 end program test_associated
1400 @item @emph{See also}:
1407 @section @code{ATAN} --- Arctangent function
1410 @cindex trigonometric function, tangent, inverse
1411 @cindex tangent, inverse
1414 @item @emph{Description}:
1415 @code{ATAN(X)} computes the arctangent of @var{X}.
1417 @item @emph{Standard}:
1418 Fortran 77 and later, for a complex argument and for two arguments
1419 Fortran 2008 or later
1424 @item @emph{Syntax}:
1425 @multitable @columnfractions .80
1426 @item @code{RESULT = ATAN(X)}
1427 @item @code{RESULT = ATAN(Y, X)}
1430 @item @emph{Arguments}:
1431 @multitable @columnfractions .15 .70
1432 @item @var{X} @tab The type shall be @code{REAL} or @code{COMPLEX};
1433 if @var{Y} is present, @var{X} shall be REAL.
1434 @item @var{Y} shall be of the same type and kind as @var{X}.
1437 @item @emph{Return value}:
1438 The return value is of the same type and kind as @var{X}.
1439 If @var{Y} is present, the result is identical to @code{ATAN2(Y,X)}.
1440 Otherwise, it the arcus tangent of @var{X}, where the real part of
1441 the result is in radians and lies in the range
1442 @math{-\pi/2 \leq \Re \atan(x) \leq \pi/2}.
1444 @item @emph{Example}:
1447 real(8) :: x = 2.866_8
1449 end program test_atan
1452 @item @emph{Specific names}:
1453 @multitable @columnfractions .20 .20 .20 .25
1454 @item Name @tab Argument @tab Return type @tab Standard
1455 @item @code{ATAN(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab Fortran 77 and later
1456 @item @code{DATAN(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab Fortran 77 and later
1459 @item @emph{See also}:
1460 Inverse function: @ref{TAN}
1467 @section @code{ATAN2} --- Arctangent function
1470 @cindex trigonometric function, tangent, inverse
1471 @cindex tangent, inverse
1474 @item @emph{Description}:
1475 @code{ATAN2(Y, X)} computes the principal value of the argument
1476 function of the complex number @math{X + i Y}. This function can
1477 be used to transform from Cartesian into polar coordinates and
1478 allows to determine the angle in the correct quadrant.
1480 @item @emph{Standard}:
1481 Fortran 77 and later
1486 @item @emph{Syntax}:
1487 @code{RESULT = ATAN2(Y, X)}
1489 @item @emph{Arguments}:
1490 @multitable @columnfractions .15 .70
1491 @item @var{Y} @tab The type shall be @code{REAL}.
1492 @item @var{X} @tab The type and kind type parameter shall be the same as @var{Y}.
1493 If @var{Y} is zero, then @var{X} must be nonzero.
1496 @item @emph{Return value}:
1497 The return value has the same type and kind type parameter as @var{Y}. It
1498 is the principal value of the complex number @math{X + i Y}. If @var{X}
1499 is nonzero, then it lies in the range @math{-\pi \le \atan (x) \leq \pi}.
1500 The sign is positive if @var{Y} is positive. If @var{Y} is zero, then
1501 the return value is zero if @var{X} is strictly positive, @math{\pi} if
1502 @var{X} is negative and @var{Y} is positive zero (or the processor does
1503 not handle signed zeros), and @math{-\pi} if @var{X} is negative and
1504 @var{Y} is negative zero. Finally, if @var{X} is zero, then the
1505 magnitude of the result is @math{\pi/2}.
1507 @item @emph{Example}:
1510 real(4) :: x = 1.e0_4, y = 0.5e0_4
1512 end program test_atan2
1515 @item @emph{Specific names}:
1516 @multitable @columnfractions .20 .20 .20 .25
1517 @item Name @tab Argument @tab Return type @tab Standard
1518 @item @code{ATAN2(X, Y)} @tab @code{REAL(4) X, Y} @tab @code{REAL(4)} @tab Fortran 77 and later
1519 @item @code{DATAN2(X, Y)} @tab @code{REAL(8) X, Y} @tab @code{REAL(8)} @tab Fortran 77 and later
1526 @section @code{ATANH} --- Inverse hyperbolic tangent function
1529 @cindex area hyperbolic tangent
1530 @cindex inverse hyperbolic tangent
1531 @cindex hyperbolic function, tangent, inverse
1532 @cindex tangent, hyperbolic, inverse
1535 @item @emph{Description}:
1536 @code{ATANH(X)} computes the inverse hyperbolic tangent of @var{X}.
1538 @item @emph{Standard}:
1539 Fortran 2008 and later
1544 @item @emph{Syntax}:
1545 @code{RESULT = ATANH(X)}
1547 @item @emph{Arguments}:
1548 @multitable @columnfractions .15 .70
1549 @item @var{X} @tab The type shall be @code{REAL} or @code{COMPLEX}.
1552 @item @emph{Return value}:
1553 The return value has same type and kind as @var{X}. If @var{X} is
1554 complex, the imaginary part of the result is in radians and lies between
1555 @math{-\pi/2 \leq \Im \atanh(x) \leq \pi/2}.
1557 @item @emph{Example}:
1560 REAL, DIMENSION(3) :: x = (/ -1.0, 0.0, 1.0 /)
1561 WRITE (*,*) ATANH(x)
1565 @item @emph{Specific names}:
1566 @multitable @columnfractions .20 .20 .20 .25
1567 @item Name @tab Argument @tab Return type @tab Standard
1568 @item @code{DATANH(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU extension
1571 @item @emph{See also}:
1572 Inverse function: @ref{TANH}
1578 @section @code{ATOMIC_ADD} --- Atomic ADD operation
1580 @cindex Atomic subroutine, add
1583 @item @emph{Description}:
1584 @code{ATOMIC_ADD(ATOM, VALUE)} atomically adds the value of @var{VAR} to the
1585 variable @var{ATOM}. When @var{STAT} is present and the invokation was
1586 successful, it is assigned the value 0. If it is present and the invokation
1587 has failed, it is assigned a positive value; in particular, for a coindexed
1588 @var{ATOM}, if the remote image has stopped, it is assigned the value of
1589 @code{ISO_FORTRAN_ENV}'s @code{STAT_STOPPED_IMAGE} and if the remote image has
1590 failed, the value @code{STAT_FAILED_IMAGE}.
1592 @item @emph{Standard}:
1598 @item @emph{Syntax}:
1599 @code{CALL ATOMIC_ADD (ATOM, VALUE [, STAT])}
1601 @item @emph{Arguments}:
1602 @multitable @columnfractions .15 .70
1603 @item @var{ATOM} @tab Scalar coarray or coindexed variable of integer
1604 type with @code{ATOMIC_INT_KIND} kind.
1605 @item @var{VALUE} @tab Scalar of the same type as @var{ATOM}. If the kind
1606 is different, the value is converted to the kind of @var{ATOM}.
1607 @item @var{STAT} @tab (optional) Scalar default-kind integer variable.
1610 @item @emph{Example}:
1614 integer(atomic_int_kind) :: atom[*]
1615 call atomic_add (atom[1], this_image())
1619 @item @emph{See also}:
1620 @ref{ATOMIC_DEFINE}, @ref{ATOMIC_FETCH_ADD}, @ref{ISO_FORTRAN_ENV},
1621 @ref{ATOMIC_AND}, @ref{ATOMIC_OR}, @ref{ATOMIC_XOR}
1628 @section @code{ATOMIC_AND} --- Atomic bitwise AND operation
1630 @cindex Atomic subroutine, AND
1633 @item @emph{Description}:
1634 @code{ATOMIC_AND(ATOM, VALUE)} atomically defines @var{ATOM} with the bitwise
1635 AND between the values of @var{ATOM} and @var{VALUE}. When @var{STAT} is present
1636 and the invokation was successful, it is assigned the value 0. If it is present
1637 and the invokation has failed, it is assigned a positive value; in particular,
1638 for a coindexed @var{ATOM}, if the remote image has stopped, it is assigned the
1639 value of @code{ISO_FORTRAN_ENV}'s @code{STAT_STOPPED_IMAGE} and if the remote
1640 image has failed, the value @code{STAT_FAILED_IMAGE}.
1642 @item @emph{Standard}:
1648 @item @emph{Syntax}:
1649 @code{CALL ATOMIC_AND (ATOM, VALUE [, STAT])}
1651 @item @emph{Arguments}:
1652 @multitable @columnfractions .15 .70
1653 @item @var{ATOM} @tab Scalar coarray or coindexed variable of integer
1654 type with @code{ATOMIC_INT_KIND} kind.
1655 @item @var{VALUE} @tab Scalar of the same type as @var{ATOM}. If the kind
1656 is different, the value is converted to the kind of @var{ATOM}.
1657 @item @var{STAT} @tab (optional) Scalar default-kind integer variable.
1660 @item @emph{Example}:
1664 integer(atomic_int_kind) :: atom[*]
1665 call atomic_and (atom[1], int(b'10100011101'))
1669 @item @emph{See also}:
1670 @ref{ATOMIC_DEFINE}, @ref{ATOMIC_FETCH_AND}, @ref{ISO_FORTRAN_ENV},
1671 @ref{ATOMIC_ADD}, @ref{ATOMIC_OR}, @ref{ATOMIC_XOR}
1677 @section @code{ATOMIC_CAS} --- Atomic compare and swap
1678 @fnindex ATOMIC_DEFINE
1679 @cindex Atomic subroutine, compare and swap
1682 @item @emph{Description}:
1683 @code{ATOMIC_CAS} compares the variable @var{ATOM} with the value of
1684 @var{COMPARE}; if the value is the same, @var{ATOM} is set to the value
1685 of @var{NEW}. Additionally, @var{OLD} is set to the value of @var{ATOM}
1686 that was used for the comparison. When @var{STAT} is present and the invokation
1687 was successful, it is assigned the value 0. If it is present and the invokation
1688 has failed, it is assigned a positive value; in particular, for a coindexed
1689 @var{ATOM}, if the remote image has stopped, it is assigned the value of
1690 @code{ISO_FORTRAN_ENV}'s @code{STAT_STOPPED_IMAGE} and if the remote image has
1691 failed, the value @code{STAT_FAILED_IMAGE}.
1693 @item @emph{Standard}:
1699 @item @emph{Syntax}:
1700 @code{CALL ATOMIC_CAS (ATOM, OLD, COMPARE, NEW [, STAT])}
1702 @item @emph{Arguments}:
1703 @multitable @columnfractions .15 .70
1704 @item @var{ATOM} @tab Scalar coarray or coindexed variable of either integer
1705 type with @code{ATOMIC_INT_KIND} kind or logical type with
1706 @code{ATOMIC_LOGICAL_KIND} kind.
1707 @item @var{OLD} @tab Scalar of the same type and kind as @var{ATOM}.
1708 @item @var{COMPARE} @tab Scalar variable of the same type and kind as
1710 @item @var{NEW} @tab Scalar variable of the same type as @var{ATOM}. If kind
1711 is different, the value is converted to the kind of @var{ATOM}.
1712 @item @var{STAT} @tab (optional) Scalar default-kind integer variable.
1715 @item @emph{Example}:
1719 logical(atomic_logical_kind) :: atom[*], prev
1720 call atomic_cas (atom[1], prev, .false., .true.))
1724 @item @emph{See also}:
1725 @ref{ATOMIC_DEFINE}, @ref{ATOMIC_REF}, @ref{ISO_FORTRAN_ENV}
1731 @section @code{ATOMIC_DEFINE} --- Setting a variable atomically
1732 @fnindex ATOMIC_DEFINE
1733 @cindex Atomic subroutine, define
1736 @item @emph{Description}:
1737 @code{ATOMIC_DEFINE(ATOM, VALUE)} defines the variable @var{ATOM} with the value
1738 @var{VALUE} atomically. When @var{STAT} is present and the invokation was
1739 successful, it is assigned the value 0. If it is present and the invokation
1740 has failed, it is assigned a positive value; in particular, for a coindexed
1741 @var{ATOM}, if the remote image has stopped, it is assigned the value of
1742 @code{ISO_FORTRAN_ENV}'s @code{STAT_STOPPED_IMAGE} and if the remote image has
1743 failed, the value @code{STAT_FAILED_IMAGE}.
1745 @item @emph{Standard}:
1746 Fortran 2008 and later; with @var{STAT}, TS 18508 or later
1751 @item @emph{Syntax}:
1752 @code{CALL ATOMIC_DEFINE (ATOM, VALUE [, STAT])}
1754 @item @emph{Arguments}:
1755 @multitable @columnfractions .15 .70
1756 @item @var{ATOM} @tab Scalar coarray or coindexed variable of either integer
1757 type with @code{ATOMIC_INT_KIND} kind or logical type with
1758 @code{ATOMIC_LOGICAL_KIND} kind.
1760 @item @var{VALUE} @tab Scalar of the same type as @var{ATOM}. If the kind
1761 is different, the value is converted to the kind of @var{ATOM}.
1762 @item @var{STAT} @tab (optional) Scalar default-kind integer variable.
1765 @item @emph{Example}:
1769 integer(atomic_int_kind) :: atom[*]
1770 call atomic_define (atom[1], this_image())
1774 @item @emph{See also}:
1775 @ref{ATOMIC_REF}, @ref{ATOMIC_CAS}, @ref{ISO_FORTRAN_ENV},
1776 @ref{ATOMIC_ADD}, @ref{ATOMIC_AND}, @ref{ATOMIC_OR}, @ref{ATOMIC_XOR}
1781 @node ATOMIC_FETCH_ADD
1782 @section @code{ATOMIC_FETCH_ADD} --- Atomic ADD operation with prior fetch
1783 @fnindex ATOMIC_FETCH_ADD
1784 @cindex Atomic subroutine, ADD with fetch
1787 @item @emph{Description}:
1788 @code{ATOMIC_FETCH_ADD(ATOM, VALUE, OLD)} atomically stores the value of
1789 @var{ATOM} in @var{OLD} and adds the value of @var{VAR} to the
1790 variable @var{ATOM}. When @var{STAT} is present and the invokation was
1791 successful, it is assigned the value 0. If it is present and the invokation
1792 has failed, it is assigned a positive value; in particular, for a coindexed
1793 @var{ATOM}, if the remote image has stopped, it is assigned the value of
1794 @code{ISO_FORTRAN_ENV}'s @code{STAT_STOPPED_IMAGE} and if the remote image has
1795 failed, the value @code{STAT_FAILED_IMAGE}.
1797 @item @emph{Standard}:
1803 @item @emph{Syntax}:
1804 @code{CALL ATOMIC_FETCH_ADD (ATOM, VALUE, old [, STAT])}
1806 @item @emph{Arguments}:
1807 @multitable @columnfractions .15 .70
1808 @item @var{ATOM} @tab Scalar coarray or coindexed variable of integer
1809 type with @code{ATOMIC_INT_KIND} kind.
1810 @code{ATOMIC_LOGICAL_KIND} kind.
1812 @item @var{VALUE} @tab Scalar of the same type as @var{ATOM}. If the kind
1813 is different, the value is converted to the kind of @var{ATOM}.
1814 @item @var{OLD} @tab Scalar of the same type and kind as @var{ATOM}.
1815 @item @var{STAT} @tab (optional) Scalar default-kind integer variable.
1818 @item @emph{Example}:
1822 integer(atomic_int_kind) :: atom[*], old
1823 call atomic_add (atom[1], this_image(), old)
1827 @item @emph{See also}:
1828 @ref{ATOMIC_DEFINE}, @ref{ATOMIC_ADD}, @ref{ISO_FORTRAN_ENV},
1829 @ref{ATOMIC_FETCH_AND}, @ref{ATOMIC_FETCH_OR}, @ref{ATOMIC_FETCH_XOR}
1834 @node ATOMIC_FETCH_AND
1835 @section @code{ATOMIC_FETCH_AND} --- Atomic bitwise AND operation with prior fetch
1836 @fnindex ATOMIC_FETCH_AND
1837 @cindex Atomic subroutine, AND with fetch
1840 @item @emph{Description}:
1841 @code{ATOMIC_AND(ATOM, VALUE)} atomically stores the value of @var{ATOM} in
1842 @var{OLD} and defines @var{ATOM} with the bitwise AND between the values of
1843 @var{ATOM} and @var{VALUE}. When @var{STAT} is present and the invokation was
1844 successful, it is assigned the value 0. If it is present and the invokation has
1845 failed, it is assigned a positive value; in particular, for a coindexed
1846 @var{ATOM}, if the remote image has stopped, it is assigned the value of
1847 @code{ISO_FORTRAN_ENV}'s @code{STAT_STOPPED_IMAGE} and if the remote image has
1848 failed, the value @code{STAT_FAILED_IMAGE}.
1850 @item @emph{Standard}:
1856 @item @emph{Syntax}:
1857 @code{CALL ATOMIC_FETCH_AND (ATOM, VALUE, OLD [, STAT])}
1859 @item @emph{Arguments}:
1860 @multitable @columnfractions .15 .70
1861 @item @var{ATOM} @tab Scalar coarray or coindexed variable of integer
1862 type with @code{ATOMIC_INT_KIND} kind.
1863 @item @var{VALUE} @tab Scalar of the same type as @var{ATOM}. If the kind
1864 is different, the value is converted to the kind of @var{ATOM}.
1865 @item @var{OLD} @tab Scalar of the same type and kind as @var{ATOM}.
1866 @item @var{STAT} @tab (optional) Scalar default-kind integer variable.
1869 @item @emph{Example}:
1873 integer(atomic_int_kind) :: atom[*], old
1874 call atomic_fetch_and (atom[1], int(b'10100011101'), old)
1878 @item @emph{See also}:
1879 @ref{ATOMIC_DEFINE}, @ref{ATOMIC_AND}, @ref{ISO_FORTRAN_ENV},
1880 @ref{ATOMIC_FETCH_ADD}, @ref{ATOMIC_FETCH_OR}, @ref{ATOMIC_FETCH_XOR}
1885 @node ATOMIC_FETCH_OR
1886 @section @code{ATOMIC_FETCH_OR} --- Atomic bitwise OR operation with prior fetch
1887 @fnindex ATOMIC_FETCH_OR
1888 @cindex Atomic subroutine, OR with fetch
1891 @item @emph{Description}:
1892 @code{ATOMIC_OR(ATOM, VALUE)} atomically stores the value of @var{ATOM} in
1893 @var{OLD} and defines @var{ATOM} with the bitwise OR between the values of
1894 @var{ATOM} and @var{VALUE}. When @var{STAT} is present and the invokation was
1895 successful, it is assigned the value 0. If it is present and the invokation has
1896 failed, it is assigned a positive value; in particular, for a coindexed
1897 @var{ATOM}, if the remote image has stopped, it is assigned the value of
1898 @code{ISO_FORTRAN_ENV}'s @code{STAT_STOPPED_IMAGE} and if the remote image has
1899 failed, the value @code{STAT_FAILED_IMAGE}.
1901 @item @emph{Standard}:
1907 @item @emph{Syntax}:
1908 @code{CALL ATOMIC_FETCH_OR (ATOM, VALUE, OLD [, STAT])}
1910 @item @emph{Arguments}:
1911 @multitable @columnfractions .15 .70
1912 @item @var{ATOM} @tab Scalar coarray or coindexed variable of integer
1913 type with @code{ATOMIC_INT_KIND} kind.
1914 @item @var{VALUE} @tab Scalar of the same type as @var{ATOM}. If the kind
1915 is different, the value is converted to the kind of @var{ATOM}.
1916 @item @var{OLD} @tab Scalar of the same type and kind as @var{ATOM}.
1917 @item @var{STAT} @tab (optional) Scalar default-kind integer variable.
1920 @item @emph{Example}:
1924 integer(atomic_int_kind) :: atom[*], old
1925 call atomic_fetch_or (atom[1], int(b'10100011101'), old)
1929 @item @emph{See also}:
1930 @ref{ATOMIC_DEFINE}, @ref{ATOMIC_OR}, @ref{ISO_FORTRAN_ENV},
1931 @ref{ATOMIC_FETCH_ADD}, @ref{ATOMIC_FETCH_AND}, @ref{ATOMIC_FETCH_XOR}
1936 @node ATOMIC_FETCH_XOR
1937 @section @code{ATOMIC_FETCH_XOR} --- Atomic bitwise XOR operation with prior fetch
1938 @fnindex ATOMIC_FETCH_XOR
1939 @cindex Atomic subroutine, XOR with fetch
1942 @item @emph{Description}:
1943 @code{ATOMIC_XOR(ATOM, VALUE)} atomically stores the value of @var{ATOM} in
1944 @var{OLD} and defines @var{ATOM} with the bitwise XOR between the values of
1945 @var{ATOM} and @var{VALUE}. When @var{STAT} is present and the invokation was
1946 successful, it is assigned the value 0. If it is present and the invokation has
1947 failed, it is assigned a positive value; in particular, for a coindexed
1948 @var{ATOM}, if the remote image has stopped, it is assigned the value of
1949 @code{ISO_FORTRAN_ENV}'s @code{STAT_STOPPED_IMAGE} and if the remote image has
1950 failed, the value @code{STAT_FAILED_IMAGE}.
1952 @item @emph{Standard}:
1958 @item @emph{Syntax}:
1959 @code{CALL ATOMIC_FETCH_XOR (ATOM, VALUE, OLD [, STAT])}
1961 @item @emph{Arguments}:
1962 @multitable @columnfractions .15 .70
1963 @item @var{ATOM} @tab Scalar coarray or coindexed variable of integer
1964 type with @code{ATOMIC_INT_KIND} kind.
1965 @item @var{VALUE} @tab Scalar of the same type as @var{ATOM}. If the kind
1966 is different, the value is converted to the kind of @var{ATOM}.
1967 @item @var{OLD} @tab Scalar of the same type and kind as @var{ATOM}.
1968 @item @var{STAT} @tab (optional) Scalar default-kind integer variable.
1971 @item @emph{Example}:
1975 integer(atomic_int_kind) :: atom[*], old
1976 call atomic_fetch_xor (atom[1], int(b'10100011101'), old)
1980 @item @emph{See also}:
1981 @ref{ATOMIC_DEFINE}, @ref{ATOMIC_XOR}, @ref{ISO_FORTRAN_ENV},
1982 @ref{ATOMIC_FETCH_ADD}, @ref{ATOMIC_FETCH_AND}, @ref{ATOMIC_FETCH_OR}
1988 @section @code{ATOMIC_OR} --- Atomic bitwise OR operation
1990 @cindex Atomic subroutine, OR
1993 @item @emph{Description}:
1994 @code{ATOMIC_OR(ATOM, VALUE)} atomically defines @var{ATOM} with the bitwise
1995 AND between the values of @var{ATOM} and @var{VALUE}. When @var{STAT} is present
1996 and the invokation was successful, it is assigned the value 0. If it is present
1997 and the invokation has failed, it is assigned a positive value; in particular,
1998 for a coindexed @var{ATOM}, if the remote image has stopped, it is assigned the
1999 value of @code{ISO_FORTRAN_ENV}'s @code{STAT_STOPPED_IMAGE} and if the remote
2000 image has failed, the value @code{STAT_FAILED_IMAGE}.
2002 @item @emph{Standard}:
2008 @item @emph{Syntax}:
2009 @code{CALL ATOMIC_OR (ATOM, VALUE [, STAT])}
2011 @item @emph{Arguments}:
2012 @multitable @columnfractions .15 .70
2013 @item @var{ATOM} @tab Scalar coarray or coindexed variable of integer
2014 type with @code{ATOMIC_INT_KIND} kind.
2015 @item @var{VALUE} @tab Scalar of the same type as @var{ATOM}. If the kind
2016 is different, the value is converted to the kind of @var{ATOM}.
2017 @item @var{STAT} @tab (optional) Scalar default-kind integer variable.
2020 @item @emph{Example}:
2024 integer(atomic_int_kind) :: atom[*]
2025 call atomic_or (atom[1], int(b'10100011101'))
2029 @item @emph{See also}:
2030 @ref{ATOMIC_DEFINE}, @ref{ATOMIC_FETCH_OR}, @ref{ISO_FORTRAN_ENV},
2031 @ref{ATOMIC_ADD}, @ref{ATOMIC_OR}, @ref{ATOMIC_XOR}
2037 @section @code{ATOMIC_REF} --- Obtaining the value of a variable atomically
2039 @cindex Atomic subroutine, reference
2042 @item @emph{Description}:
2043 @code{ATOMIC_DEFINE(ATOM, VALUE)} atomically assigns the value of the
2044 variable @var{ATOM} to @var{VALUE}. When @var{STAT} is present and the
2045 invokation was successful, it is assigned the value 0. If it is present and the
2046 invokation has failed, it is assigned a positive value; in particular, for a
2047 coindexed @var{ATOM}, if the remote image has stopped, it is assigned the value
2048 of @code{ISO_FORTRAN_ENV}'s @code{STAT_STOPPED_IMAGE} and if the remote image
2049 has failed, the value @code{STAT_FAILED_IMAGE}.
2052 @item @emph{Standard}:
2053 Fortran 2008 and later; with @var{STAT}, TS 18508 or later
2058 @item @emph{Syntax}:
2059 @code{CALL ATOMIC_REF(VALUE, ATOM [, STAT])}
2061 @item @emph{Arguments}:
2062 @multitable @columnfractions .15 .70
2063 @item @var{VALUE} @tab Scalar of the same type as @var{ATOM}. If the kind
2064 is different, the value is converted to the kind of @var{ATOM}.
2065 @item @var{ATOM} @tab Scalar coarray or coindexed variable of either integer
2066 type with @code{ATOMIC_INT_KIND} kind or logical type with
2067 @code{ATOMIC_LOGICAL_KIND} kind.
2068 @item @var{STAT} @tab (optional) Scalar default-kind integer variable.
2071 @item @emph{Example}:
2075 logical(atomic_logical_kind) :: atom[*]
2077 call atomic_ref (atom, .false.)
2079 call atomic_ref (atom, val)
2086 @item @emph{See also}:
2087 @ref{ATOMIC_DEFINE}, @ref{ATOMIC_CAS}, @ref{ISO_FORTRAN_ENV},
2088 @ref{ATOMIC_FETCH_ADD}, @ref{ATOMIC_FETCH_AND}, @ref{ATOMIC_FETCH_OR},
2089 @ref{ATOMIC_FETCH_XOR}
2094 @section @code{ATOMIC_XOR} --- Atomic bitwise OR operation
2096 @cindex Atomic subroutine, XOR
2099 @item @emph{Description}:
2100 @code{ATOMIC_AND(ATOM, VALUE)} atomically defines @var{ATOM} with the bitwise
2101 XOR between the values of @var{ATOM} and @var{VALUE}. When @var{STAT} is present
2102 and the invokation was successful, it is assigned the value 0. If it is present
2103 and the invokation has failed, it is assigned a positive value; in particular,
2104 for a coindexed @var{ATOM}, if the remote image has stopped, it is assigned the
2105 value of @code{ISO_FORTRAN_ENV}'s @code{STAT_STOPPED_IMAGE} and if the remote
2106 image has failed, the value @code{STAT_FAILED_IMAGE}.
2108 @item @emph{Standard}:
2114 @item @emph{Syntax}:
2115 @code{CALL ATOMIC_XOR (ATOM, VALUE [, STAT])}
2117 @item @emph{Arguments}:
2118 @multitable @columnfractions .15 .70
2119 @item @var{ATOM} @tab Scalar coarray or coindexed variable of integer
2120 type with @code{ATOMIC_INT_KIND} kind.
2121 @item @var{VALUE} @tab Scalar of the same type as @var{ATOM}. If the kind
2122 is different, the value is converted to the kind of @var{ATOM}.
2123 @item @var{STAT} @tab (optional) Scalar default-kind integer variable.
2126 @item @emph{Example}:
2130 integer(atomic_int_kind) :: atom[*]
2131 call atomic_xor (atom[1], int(b'10100011101'))
2135 @item @emph{See also}:
2136 @ref{ATOMIC_DEFINE}, @ref{ATOMIC_FETCH_XOR}, @ref{ISO_FORTRAN_ENV},
2137 @ref{ATOMIC_ADD}, @ref{ATOMIC_OR}, @ref{ATOMIC_XOR}
2142 @section @code{BACKTRACE} --- Show a backtrace
2147 @item @emph{Description}:
2148 @code{BACKTRACE} shows a backtrace at an arbitrary place in user code. Program
2149 execution continues normally afterwards. The backtrace information is printed
2150 to the unit corresponding to @code{ERROR_UNIT} in @code{ISO_FORTRAN_ENV}.
2152 @item @emph{Standard}:
2158 @item @emph{Syntax}:
2159 @code{CALL BACKTRACE}
2161 @item @emph{Arguments}:
2164 @item @emph{See also}:
2171 @section @code{BESSEL_J0} --- Bessel function of the first kind of order 0
2175 @cindex Bessel function, first kind
2178 @item @emph{Description}:
2179 @code{BESSEL_J0(X)} computes the Bessel function of the first kind of
2180 order 0 of @var{X}. This function is available under the name
2181 @code{BESJ0} as a GNU extension.
2183 @item @emph{Standard}:
2184 Fortran 2008 and later
2189 @item @emph{Syntax}:
2190 @code{RESULT = BESSEL_J0(X)}
2192 @item @emph{Arguments}:
2193 @multitable @columnfractions .15 .70
2194 @item @var{X} @tab The type shall be @code{REAL}.
2197 @item @emph{Return value}:
2198 The return value is of type @code{REAL} and lies in the
2199 range @math{ - 0.4027... \leq Bessel (0,x) \leq 1}. It has the same
2202 @item @emph{Example}:
2205 real(8) :: x = 0.0_8
2207 end program test_besj0
2210 @item @emph{Specific names}:
2211 @multitable @columnfractions .20 .20 .20 .25
2212 @item Name @tab Argument @tab Return type @tab Standard
2213 @item @code{DBESJ0(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU extension
2220 @section @code{BESSEL_J1} --- Bessel function of the first kind of order 1
2224 @cindex Bessel function, first kind
2227 @item @emph{Description}:
2228 @code{BESSEL_J1(X)} computes the Bessel function of the first kind of
2229 order 1 of @var{X}. This function is available under the name
2230 @code{BESJ1} as a GNU extension.
2232 @item @emph{Standard}:
2238 @item @emph{Syntax}:
2239 @code{RESULT = BESSEL_J1(X)}
2241 @item @emph{Arguments}:
2242 @multitable @columnfractions .15 .70
2243 @item @var{X} @tab The type shall be @code{REAL}.
2246 @item @emph{Return value}:
2247 The return value is of type @code{REAL} and lies in the
2248 range @math{ - 0.5818... \leq Bessel (0,x) \leq 0.5818 }. It has the same
2251 @item @emph{Example}:
2254 real(8) :: x = 1.0_8
2256 end program test_besj1
2259 @item @emph{Specific names}:
2260 @multitable @columnfractions .20 .20 .20 .25
2261 @item Name @tab Argument @tab Return type @tab Standard
2262 @item @code{DBESJ1(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU extension
2269 @section @code{BESSEL_JN} --- Bessel function of the first kind
2273 @cindex Bessel function, first kind
2276 @item @emph{Description}:
2277 @code{BESSEL_JN(N, X)} computes the Bessel function of the first kind of
2278 order @var{N} of @var{X}. This function is available under the name
2279 @code{BESJN} as a GNU extension. If @var{N} and @var{X} are arrays,
2280 their ranks and shapes shall conform.
2282 @code{BESSEL_JN(N1, N2, X)} returns an array with the Bessel functions
2283 of the first kind of the orders @var{N1} to @var{N2}.
2285 @item @emph{Standard}:
2286 Fortran 2008 and later, negative @var{N} is allowed as GNU extension
2289 Elemental function, except for the transformational function
2290 @code{BESSEL_JN(N1, N2, X)}
2292 @item @emph{Syntax}:
2293 @multitable @columnfractions .80
2294 @item @code{RESULT = BESSEL_JN(N, X)}
2295 @item @code{RESULT = BESSEL_JN(N1, N2, X)}
2298 @item @emph{Arguments}:
2299 @multitable @columnfractions .15 .70
2300 @item @var{N} @tab Shall be a scalar or an array of type @code{INTEGER}.
2301 @item @var{N1} @tab Shall be a non-negative scalar of type @code{INTEGER}.
2302 @item @var{N2} @tab Shall be a non-negative scalar of type @code{INTEGER}.
2303 @item @var{X} @tab Shall be a scalar or an array of type @code{REAL};
2304 for @code{BESSEL_JN(N1, N2, X)} it shall be scalar.
2307 @item @emph{Return value}:
2308 The return value is a scalar of type @code{REAL}. It has the same
2312 The transformational function uses a recurrence algorithm which might,
2313 for some values of @var{X}, lead to different results than calls to
2314 the elemental function.
2316 @item @emph{Example}:
2319 real(8) :: x = 1.0_8
2321 end program test_besjn
2324 @item @emph{Specific names}:
2325 @multitable @columnfractions .20 .20 .20 .25
2326 @item Name @tab Argument @tab Return type @tab Standard
2327 @item @code{DBESJN(N, X)} @tab @code{INTEGER N} @tab @code{REAL(8)} @tab GNU extension
2328 @item @tab @code{REAL(8) X} @tab @tab
2335 @section @code{BESSEL_Y0} --- Bessel function of the second kind of order 0
2339 @cindex Bessel function, second kind
2342 @item @emph{Description}:
2343 @code{BESSEL_Y0(X)} computes the Bessel function of the second kind of
2344 order 0 of @var{X}. This function is available under the name
2345 @code{BESY0} as a GNU extension.
2347 @item @emph{Standard}:
2348 Fortran 2008 and later
2353 @item @emph{Syntax}:
2354 @code{RESULT = BESSEL_Y0(X)}
2356 @item @emph{Arguments}:
2357 @multitable @columnfractions .15 .70
2358 @item @var{X} @tab The type shall be @code{REAL}.
2361 @item @emph{Return value}:
2362 The return value is of type @code{REAL}. It has the same kind as @var{X}.
2364 @item @emph{Example}:
2367 real(8) :: x = 0.0_8
2369 end program test_besy0
2372 @item @emph{Specific names}:
2373 @multitable @columnfractions .20 .20 .20 .25
2374 @item Name @tab Argument @tab Return type @tab Standard
2375 @item @code{DBESY0(X)}@tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU extension
2382 @section @code{BESSEL_Y1} --- Bessel function of the second kind of order 1
2386 @cindex Bessel function, second kind
2389 @item @emph{Description}:
2390 @code{BESSEL_Y1(X)} computes the Bessel function of the second kind of
2391 order 1 of @var{X}. This function is available under the name
2392 @code{BESY1} as a GNU extension.
2394 @item @emph{Standard}:
2395 Fortran 2008 and later
2400 @item @emph{Syntax}:
2401 @code{RESULT = BESSEL_Y1(X)}
2403 @item @emph{Arguments}:
2404 @multitable @columnfractions .15 .70
2405 @item @var{X} @tab The type shall be @code{REAL}.
2408 @item @emph{Return value}:
2409 The return value is of type @code{REAL}. It has the same kind as @var{X}.
2411 @item @emph{Example}:
2414 real(8) :: x = 1.0_8
2416 end program test_besy1
2419 @item @emph{Specific names}:
2420 @multitable @columnfractions .20 .20 .20 .25
2421 @item Name @tab Argument @tab Return type @tab Standard
2422 @item @code{DBESY1(X)}@tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU extension
2429 @section @code{BESSEL_YN} --- Bessel function of the second kind
2433 @cindex Bessel function, second kind
2436 @item @emph{Description}:
2437 @code{BESSEL_YN(N, X)} computes the Bessel function of the second kind of
2438 order @var{N} of @var{X}. This function is available under the name
2439 @code{BESYN} as a GNU extension. If @var{N} and @var{X} are arrays,
2440 their ranks and shapes shall conform.
2442 @code{BESSEL_YN(N1, N2, X)} returns an array with the Bessel functions
2443 of the first kind of the orders @var{N1} to @var{N2}.
2445 @item @emph{Standard}:
2446 Fortran 2008 and later, negative @var{N} is allowed as GNU extension
2449 Elemental function, except for the transformational function
2450 @code{BESSEL_YN(N1, N2, X)}
2452 @item @emph{Syntax}:
2453 @multitable @columnfractions .80
2454 @item @code{RESULT = BESSEL_YN(N, X)}
2455 @item @code{RESULT = BESSEL_YN(N1, N2, X)}
2458 @item @emph{Arguments}:
2459 @multitable @columnfractions .15 .70
2460 @item @var{N} @tab Shall be a scalar or an array of type @code{INTEGER} .
2461 @item @var{N1} @tab Shall be a non-negative scalar of type @code{INTEGER}.
2462 @item @var{N2} @tab Shall be a non-negative scalar of type @code{INTEGER}.
2463 @item @var{X} @tab Shall be a scalar or an array of type @code{REAL};
2464 for @code{BESSEL_YN(N1, N2, X)} it shall be scalar.
2467 @item @emph{Return value}:
2468 The return value is a scalar of type @code{REAL}. It has the same
2472 The transformational function uses a recurrence algorithm which might,
2473 for some values of @var{X}, lead to different results than calls to
2474 the elemental function.
2476 @item @emph{Example}:
2479 real(8) :: x = 1.0_8
2481 end program test_besyn
2484 @item @emph{Specific names}:
2485 @multitable @columnfractions .20 .20 .20 .25
2486 @item Name @tab Argument @tab Return type @tab Standard
2487 @item @code{DBESYN(N,X)} @tab @code{INTEGER N} @tab @code{REAL(8)} @tab GNU extension
2488 @item @tab @code{REAL(8) X} @tab @tab
2495 @section @code{BGE} --- Bitwise greater than or equal to
2497 @cindex bitwise comparison
2500 @item @emph{Description}:
2501 Determines whether an integral is a bitwise greater than or equal to
2504 @item @emph{Standard}:
2505 Fortran 2008 and later
2510 @item @emph{Syntax}:
2511 @code{RESULT = BGE(I, J)}
2513 @item @emph{Arguments}:
2514 @multitable @columnfractions .15 .70
2515 @item @var{I} @tab Shall be of @code{INTEGER} type.
2516 @item @var{J} @tab Shall be of @code{INTEGER} type, and of the same kind
2520 @item @emph{Return value}:
2521 The return value is of type @code{LOGICAL} and of the default kind.
2523 @item @emph{See also}:
2524 @ref{BGT}, @ref{BLE}, @ref{BLT}
2530 @section @code{BGT} --- Bitwise greater than
2532 @cindex bitwise comparison
2535 @item @emph{Description}:
2536 Determines whether an integral is a bitwise greater than another.
2538 @item @emph{Standard}:
2539 Fortran 2008 and later
2544 @item @emph{Syntax}:
2545 @code{RESULT = BGT(I, J)}
2547 @item @emph{Arguments}:
2548 @multitable @columnfractions .15 .70
2549 @item @var{I} @tab Shall be of @code{INTEGER} type.
2550 @item @var{J} @tab Shall be of @code{INTEGER} type, and of the same kind
2554 @item @emph{Return value}:
2555 The return value is of type @code{LOGICAL} and of the default kind.
2557 @item @emph{See also}:
2558 @ref{BGE}, @ref{BLE}, @ref{BLT}
2564 @section @code{BIT_SIZE} --- Bit size inquiry function
2566 @cindex bits, number of
2567 @cindex size of a variable, in bits
2570 @item @emph{Description}:
2571 @code{BIT_SIZE(I)} returns the number of bits (integer precision plus sign bit)
2572 represented by the type of @var{I}. The result of @code{BIT_SIZE(I)} is
2573 independent of the actual value of @var{I}.
2575 @item @emph{Standard}:
2576 Fortran 95 and later
2581 @item @emph{Syntax}:
2582 @code{RESULT = BIT_SIZE(I)}
2584 @item @emph{Arguments}:
2585 @multitable @columnfractions .15 .70
2586 @item @var{I} @tab The type shall be @code{INTEGER}.
2589 @item @emph{Return value}:
2590 The return value is of type @code{INTEGER}
2592 @item @emph{Example}:
2594 program test_bit_size
2599 end program test_bit_size
2606 @section @code{BLE} --- Bitwise less than or equal to
2608 @cindex bitwise comparison
2611 @item @emph{Description}:
2612 Determines whether an integral is a bitwise less than or equal to
2615 @item @emph{Standard}:
2616 Fortran 2008 and later
2621 @item @emph{Syntax}:
2622 @code{RESULT = BLE(I, J)}
2624 @item @emph{Arguments}:
2625 @multitable @columnfractions .15 .70
2626 @item @var{I} @tab Shall be of @code{INTEGER} type.
2627 @item @var{J} @tab Shall be of @code{INTEGER} type, and of the same kind
2631 @item @emph{Return value}:
2632 The return value is of type @code{LOGICAL} and of the default kind.
2634 @item @emph{See also}:
2635 @ref{BGT}, @ref{BGE}, @ref{BLT}
2641 @section @code{BLT} --- Bitwise less than
2643 @cindex bitwise comparison
2646 @item @emph{Description}:
2647 Determines whether an integral is a bitwise less than another.
2649 @item @emph{Standard}:
2650 Fortran 2008 and later
2655 @item @emph{Syntax}:
2656 @code{RESULT = BLT(I, J)}
2658 @item @emph{Arguments}:
2659 @multitable @columnfractions .15 .70
2660 @item @var{I} @tab Shall be of @code{INTEGER} type.
2661 @item @var{J} @tab Shall be of @code{INTEGER} type, and of the same kind
2665 @item @emph{Return value}:
2666 The return value is of type @code{LOGICAL} and of the default kind.
2668 @item @emph{See also}:
2669 @ref{BGE}, @ref{BGT}, @ref{BLE}
2675 @section @code{BTEST} --- Bit test function
2681 @cindex bits, testing
2684 @item @emph{Description}:
2685 @code{BTEST(I,POS)} returns logical @code{.TRUE.} if the bit at @var{POS}
2686 in @var{I} is set. The counting of the bits starts at 0.
2688 @item @emph{Standard}:
2689 Fortran 95 and later, has overloads that are GNU extensions
2694 @item @emph{Syntax}:
2695 @code{RESULT = BTEST(I, POS)}
2697 @item @emph{Arguments}:
2698 @multitable @columnfractions .15 .70
2699 @item @var{I} @tab The type shall be @code{INTEGER}.
2700 @item @var{POS} @tab The type shall be @code{INTEGER}.
2703 @item @emph{Return value}:
2704 The return value is of type @code{LOGICAL}
2706 @item @emph{Example}:
2709 integer :: i = 32768 + 1024 + 64
2713 bool = btest(i, pos)
2716 end program test_btest
2719 @item @emph{Specific names}:
2720 @multitable @columnfractions .20 .20 .20 .25
2721 @item Name @tab Argument @tab Return type @tab Standard
2722 @item @code{BTEST(I,POS)} @tab @code{INTEGER I,POS} @tab @code{LOGICAL} @tab F95 and later
2723 @item @code{BBTEST(I,POS)} @tab @code{INTEGER(1) I,POS} @tab @code{LOGICAL(1)} @tab GNU extension
2724 @item @code{BITEST(I,POS)} @tab @code{INTEGER(2) I,POS} @tab @code{LOGICAL(2)} @tab GNU extension
2725 @item @code{BJTEST(I,POS)} @tab @code{INTEGER(4) I,POS} @tab @code{LOGICAL(4)} @tab GNU extension
2726 @item @code{BKTEST(I,POS)} @tab @code{INTEGER(8) I,POS} @tab @code{LOGICAL(8)} @tab GNU extension
2731 @section @code{C_ASSOCIATED} --- Status of a C pointer
2732 @fnindex C_ASSOCIATED
2733 @cindex association status, C pointer
2734 @cindex pointer, C association status
2737 @item @emph{Description}:
2738 @code{C_ASSOCIATED(c_ptr_1[, c_ptr_2])} determines the status of the C pointer
2739 @var{c_ptr_1} or if @var{c_ptr_1} is associated with the target @var{c_ptr_2}.
2741 @item @emph{Standard}:
2742 Fortran 2003 and later
2747 @item @emph{Syntax}:
2748 @code{RESULT = C_ASSOCIATED(c_ptr_1[, c_ptr_2])}
2750 @item @emph{Arguments}:
2751 @multitable @columnfractions .15 .70
2752 @item @var{c_ptr_1} @tab Scalar of the type @code{C_PTR} or @code{C_FUNPTR}.
2753 @item @var{c_ptr_2} @tab (Optional) Scalar of the same type as @var{c_ptr_1}.
2756 @item @emph{Return value}:
2757 The return value is of type @code{LOGICAL}; it is @code{.false.} if either
2758 @var{c_ptr_1} is a C NULL pointer or if @var{c_ptr1} and @var{c_ptr_2}
2759 point to different addresses.
2761 @item @emph{Example}:
2763 subroutine association_test(a,b)
2764 use iso_c_binding, only: c_associated, c_loc, c_ptr
2768 if(c_associated(b, c_loc(a))) &
2769 stop 'b and a do not point to same target'
2770 end subroutine association_test
2773 @item @emph{See also}:
2774 @ref{C_LOC}, @ref{C_FUNLOC}
2779 @section @code{C_F_POINTER} --- Convert C into Fortran pointer
2780 @fnindex C_F_POINTER
2781 @cindex pointer, convert C to Fortran
2784 @item @emph{Description}:
2785 @code{C_F_POINTER(CPTR, FPTR[, SHAPE])} assigns the target of the C pointer
2786 @var{CPTR} to the Fortran pointer @var{FPTR} and specifies its shape.
2788 @item @emph{Standard}:
2789 Fortran 2003 and later
2794 @item @emph{Syntax}:
2795 @code{CALL C_F_POINTER(CPTR, FPTR[, SHAPE])}
2797 @item @emph{Arguments}:
2798 @multitable @columnfractions .15 .70
2799 @item @var{CPTR} @tab scalar of the type @code{C_PTR}. It is
2801 @item @var{FPTR} @tab pointer interoperable with @var{cptr}. It is
2803 @item @var{SHAPE} @tab (Optional) Rank-one array of type @code{INTEGER}
2804 with @code{INTENT(IN)}. It shall be present
2805 if and only if @var{fptr} is an array. The size
2806 must be equal to the rank of @var{fptr}.
2809 @item @emph{Example}:
2815 subroutine my_routine(p) bind(c,name='myC_func')
2817 type(c_ptr), intent(out) :: p
2821 real,pointer :: a(:)
2822 call my_routine(cptr)
2823 call c_f_pointer(cptr, a, [12])
2827 @item @emph{See also}:
2828 @ref{C_LOC}, @ref{C_F_PROCPOINTER}
2832 @node C_F_PROCPOINTER
2833 @section @code{C_F_PROCPOINTER} --- Convert C into Fortran procedure pointer
2834 @fnindex C_F_PROCPOINTER
2835 @cindex pointer, C address of pointers
2838 @item @emph{Description}:
2839 @code{C_F_PROCPOINTER(CPTR, FPTR)} Assign the target of the C function pointer
2840 @var{CPTR} to the Fortran procedure pointer @var{FPTR}.
2842 @item @emph{Standard}:
2843 Fortran 2003 and later
2848 @item @emph{Syntax}:
2849 @code{CALL C_F_PROCPOINTER(cptr, fptr)}
2851 @item @emph{Arguments}:
2852 @multitable @columnfractions .15 .70
2853 @item @var{CPTR} @tab scalar of the type @code{C_FUNPTR}. It is
2855 @item @var{FPTR} @tab procedure pointer interoperable with @var{cptr}. It is
2859 @item @emph{Example}:
2867 real(c_float), intent(in) :: a
2868 real(c_float) :: func
2872 function getIterFunc() bind(c,name="getIterFunc")
2874 type(c_funptr) :: getIterFunc
2877 type(c_funptr) :: cfunptr
2878 procedure(func), pointer :: myFunc
2879 cfunptr = getIterFunc()
2880 call c_f_procpointer(cfunptr, myFunc)
2884 @item @emph{See also}:
2885 @ref{C_LOC}, @ref{C_F_POINTER}
2890 @section @code{C_FUNLOC} --- Obtain the C address of a procedure
2892 @cindex pointer, C address of procedures
2895 @item @emph{Description}:
2896 @code{C_FUNLOC(x)} determines the C address of the argument.
2898 @item @emph{Standard}:
2899 Fortran 2003 and later
2904 @item @emph{Syntax}:
2905 @code{RESULT = C_FUNLOC(x)}
2907 @item @emph{Arguments}:
2908 @multitable @columnfractions .15 .70
2909 @item @var{x} @tab Interoperable function or pointer to such function.
2912 @item @emph{Return value}:
2913 The return value is of type @code{C_FUNPTR} and contains the C address
2916 @item @emph{Example}:
2922 subroutine sub(a) bind(c)
2932 subroutine my_routine(p) bind(c,name='myC_func')
2934 type(c_funptr), intent(in) :: p
2937 call my_routine(c_funloc(sub))
2941 @item @emph{See also}:
2942 @ref{C_ASSOCIATED}, @ref{C_LOC}, @ref{C_F_POINTER}, @ref{C_F_PROCPOINTER}
2947 @section @code{C_LOC} --- Obtain the C address of an object
2949 @cindex procedure pointer, convert C to Fortran
2952 @item @emph{Description}:
2953 @code{C_LOC(X)} determines the C address of the argument.
2955 @item @emph{Standard}:
2956 Fortran 2003 and later
2961 @item @emph{Syntax}:
2962 @code{RESULT = C_LOC(X)}
2964 @item @emph{Arguments}:
2965 @multitable @columnfractions .10 .75
2966 @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.
2970 @item @emph{Return value}:
2971 The return value is of type @code{C_PTR} and contains the C address
2974 @item @emph{Example}:
2976 subroutine association_test(a,b)
2977 use iso_c_binding, only: c_associated, c_loc, c_ptr
2981 if(c_associated(b, c_loc(a))) &
2982 stop 'b and a do not point to same target'
2983 end subroutine association_test
2986 @item @emph{See also}:
2987 @ref{C_ASSOCIATED}, @ref{C_FUNLOC}, @ref{C_F_POINTER}, @ref{C_F_PROCPOINTER}
2992 @section @code{C_SIZEOF} --- Size in bytes of an expression
2994 @cindex expression size
2995 @cindex size of an expression
2998 @item @emph{Description}:
2999 @code{C_SIZEOF(X)} calculates the number of bytes of storage the
3000 expression @code{X} occupies.
3002 @item @emph{Standard}:
3006 Inquiry function of the module @code{ISO_C_BINDING}
3008 @item @emph{Syntax}:
3009 @code{N = C_SIZEOF(X)}
3011 @item @emph{Arguments}:
3012 @multitable @columnfractions .15 .70
3013 @item @var{X} @tab The argument shall be an interoperable data entity.
3016 @item @emph{Return value}:
3017 The return value is of type integer and of the system-dependent kind
3018 @code{C_SIZE_T} (from the @code{ISO_C_BINDING} module). Its value is the
3019 number of bytes occupied by the argument. If the argument has the
3020 @code{POINTER} attribute, the number of bytes of the storage area pointed
3021 to is returned. If the argument is of a derived type with @code{POINTER}
3022 or @code{ALLOCATABLE} components, the return value does not account for
3023 the sizes of the data pointed to by these components.
3025 @item @emph{Example}:
3029 real(c_float) :: r, s(5)
3030 print *, (c_sizeof(s)/c_sizeof(r) == 5)
3033 The example will print @code{.TRUE.} unless you are using a platform
3034 where default @code{REAL} variables are unusually padded.
3036 @item @emph{See also}:
3037 @ref{SIZEOF}, @ref{STORAGE_SIZE}
3042 @section @code{CEILING} --- Integer ceiling function
3045 @cindex rounding, ceiling
3048 @item @emph{Description}:
3049 @code{CEILING(A)} returns the least integer greater than or equal to @var{A}.
3051 @item @emph{Standard}:
3052 Fortran 95 and later
3057 @item @emph{Syntax}:
3058 @code{RESULT = CEILING(A [, KIND])}
3060 @item @emph{Arguments}:
3061 @multitable @columnfractions .15 .70
3062 @item @var{A} @tab The type shall be @code{REAL}.
3063 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
3064 expression indicating the kind parameter of the result.
3067 @item @emph{Return value}:
3068 The return value is of type @code{INTEGER(KIND)} if @var{KIND} is present
3069 and a default-kind @code{INTEGER} otherwise.
3071 @item @emph{Example}:
3073 program test_ceiling
3076 print *, ceiling(x) ! returns 64
3077 print *, ceiling(y) ! returns -63
3078 end program test_ceiling
3081 @item @emph{See also}:
3082 @ref{FLOOR}, @ref{NINT}
3089 @section @code{CHAR} --- Character conversion function
3091 @cindex conversion, to character
3094 @item @emph{Description}:
3095 @code{CHAR(I [, KIND])} returns the character represented by the integer @var{I}.
3097 @item @emph{Standard}:
3098 Fortran 77 and later
3103 @item @emph{Syntax}:
3104 @code{RESULT = CHAR(I [, KIND])}
3106 @item @emph{Arguments}:
3107 @multitable @columnfractions .15 .70
3108 @item @var{I} @tab The type shall be @code{INTEGER}.
3109 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
3110 expression indicating the kind parameter of the result.
3113 @item @emph{Return value}:
3114 The return value is of type @code{CHARACTER(1)}
3116 @item @emph{Example}:
3122 print *, i, c ! returns 'J'
3123 end program test_char
3126 @item @emph{Specific names}:
3127 @multitable @columnfractions .20 .20 .20 .25
3128 @item Name @tab Argument @tab Return type @tab Standard
3129 @item @code{CHAR(I)} @tab @code{INTEGER I} @tab @code{CHARACTER(LEN=1)} @tab F77 and later
3133 See @ref{ICHAR} for a discussion of converting between numerical values
3134 and formatted string representations.
3136 @item @emph{See also}:
3137 @ref{ACHAR}, @ref{IACHAR}, @ref{ICHAR}
3144 @section @code{CHDIR} --- Change working directory
3146 @cindex system, working directory
3149 @item @emph{Description}:
3150 Change current working directory to a specified path.
3152 This intrinsic is provided in both subroutine and function forms; however,
3153 only one form can be used in any given program unit.
3155 @item @emph{Standard}:
3159 Subroutine, function
3161 @item @emph{Syntax}:
3162 @multitable @columnfractions .80
3163 @item @code{CALL CHDIR(NAME [, STATUS])}
3164 @item @code{STATUS = CHDIR(NAME)}
3167 @item @emph{Arguments}:
3168 @multitable @columnfractions .15 .70
3169 @item @var{NAME} @tab The type shall be @code{CHARACTER} of default
3170 kind and shall specify a valid path within the file system.
3171 @item @var{STATUS} @tab (Optional) @code{INTEGER} status flag of the default
3172 kind. Returns 0 on success, and a system specific and nonzero error code
3176 @item @emph{Example}:
3179 CHARACTER(len=255) :: path
3181 WRITE(*,*) TRIM(path)
3184 WRITE(*,*) TRIM(path)
3188 @item @emph{See also}:
3195 @section @code{CHMOD} --- Change access permissions of files
3197 @cindex file system, change access mode
3200 @item @emph{Description}:
3201 @code{CHMOD} changes the permissions of a file.
3203 This intrinsic is provided in both subroutine and function forms; however,
3204 only one form can be used in any given program unit.
3206 @item @emph{Standard}:
3210 Subroutine, function
3212 @item @emph{Syntax}:
3213 @multitable @columnfractions .80
3214 @item @code{CALL CHMOD(NAME, MODE[, STATUS])}
3215 @item @code{STATUS = CHMOD(NAME, MODE)}
3218 @item @emph{Arguments}:
3219 @multitable @columnfractions .15 .70
3221 @item @var{NAME} @tab Scalar @code{CHARACTER} of default kind with the
3222 file name. Trailing blanks are ignored unless the character
3223 @code{achar(0)} is present, then all characters up to and excluding
3224 @code{achar(0)} are used as the file name.
3226 @item @var{MODE} @tab Scalar @code{CHARACTER} of default kind giving the
3227 file permission. @var{MODE} uses the same syntax as the @code{chmod} utility
3228 as defined by the POSIX standard. The argument shall either be a string of
3229 a nonnegative octal number or a symbolic mode.
3231 @item @var{STATUS} @tab (optional) scalar @code{INTEGER}, which is
3232 @code{0} on success and nonzero otherwise.
3235 @item @emph{Return value}:
3236 In either syntax, @var{STATUS} is set to @code{0} on success and nonzero
3239 @item @emph{Example}:
3240 @code{CHMOD} as subroutine
3245 call chmod('test.dat','u+x',status)
3246 print *, 'Status: ', status
3247 end program chmod_test
3249 @code{CHMOD} as function:
3254 status = chmod('test.dat','u+x')
3255 print *, 'Status: ', status
3256 end program chmod_test
3264 @section @code{CMPLX} --- Complex conversion function
3266 @cindex complex numbers, conversion to
3267 @cindex conversion, to complex
3270 @item @emph{Description}:
3271 @code{CMPLX(X [, Y [, KIND]])} returns a complex number where @var{X} is converted to
3272 the real component. If @var{Y} is present it is converted to the imaginary
3273 component. If @var{Y} is not present then the imaginary component is set to
3274 0.0. If @var{X} is complex then @var{Y} must not be present.
3276 @item @emph{Standard}:
3277 Fortran 77 and later
3282 @item @emph{Syntax}:
3283 @code{RESULT = CMPLX(X [, Y [, KIND]])}
3285 @item @emph{Arguments}:
3286 @multitable @columnfractions .15 .70
3287 @item @var{X} @tab The type may be @code{INTEGER}, @code{REAL},
3289 @item @var{Y} @tab (Optional; only allowed if @var{X} is not
3290 @code{COMPLEX}.) May be @code{INTEGER} or @code{REAL}.
3291 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
3292 expression indicating the kind parameter of the result.
3295 @item @emph{Return value}:
3296 The return value is of @code{COMPLEX} type, with a kind equal to
3297 @var{KIND} if it is specified. If @var{KIND} is not specified, the
3298 result is of the default @code{COMPLEX} kind, regardless of the kinds of
3299 @var{X} and @var{Y}.
3301 @item @emph{Example}:
3308 print *, z, cmplx(x)
3309 end program test_cmplx
3312 @item @emph{See also}:
3319 @section @code{CO_BROADCAST} --- Copy a value to all images the current set of images
3320 @fnindex CO_BROADCAST
3321 @cindex Collectives, value broadcasting
3324 @item @emph{Description}:
3325 @code{CO_BROADCAST} copies the value of argument @var{A} on the image with
3326 image index @code{SOURCE_IMAGE} to all images in the current team. @var{A}
3327 becomes defined as if by intrinsic assignment. If the execution was
3328 successful and @var{STAT} is present, it is assigned the value zero. If the
3329 execution failed, @var{STAT} gets assigned a nonzero value and, if present,
3330 @var{ERRMSG} gets assigned a value describing the occurred error.
3332 @item @emph{Standard}:
3333 Technical Specification (TS) 18508 or later
3336 Collective subroutine
3338 @item @emph{Syntax}:
3339 @code{CALL CO_BROADCAST(A, SOURCE_IMAGE [, STAT, ERRMSG])}
3341 @item @emph{Arguments}:
3342 @multitable @columnfractions .15 .70
3343 @item @var{A} @tab INTENT(INOUT) argument; shall have the same
3344 dynamic type and type paramters on all images of the current team. If it
3345 is an array, it shall have the same shape on all images.
3346 @item @var{SOURCE_IMAGE} @tab a scalar integer expression.
3347 It shall have the same the same value on all images and refer to an
3348 image of the current team.
3349 @item @var{STAT} @tab (optional) a scalar integer variable
3350 @item @var{ERRMSG} @tab (optional) a scalar character variable
3353 @item @emph{Example}:
3357 if (this_image() == 1) then
3360 call co_broadcast (val, source_image=1)
3361 print *, this_image, ":", val
3365 @item @emph{See also}:
3366 @ref{CO_MAX}, @ref{CO_MIN}, @ref{CO_SUM}, @ref{CO_REDUCE}
3372 @section @code{CO_MAX} --- Maximal value on the current set of images
3374 @cindex Collectives, maximal value
3377 @item @emph{Description}:
3378 @code{CO_MAX} determines element-wise the maximal value of @var{A} on all
3379 images of the current team. If @var{RESULT_IMAGE} is present, the maximum
3380 values are returned in @var{A} on the specified image only and the value
3381 of @var{A} on the other images become undefined. If @var{RESULT_IMAGE} is
3382 not present, the value is returned on all images. If the execution was
3383 successful and @var{STAT} is present, it is assigned the value zero. If the
3384 execution failed, @var{STAT} gets assigned a nonzero value and, if present,
3385 @var{ERRMSG} gets assigned a value describing the occurred error.
3387 @item @emph{Standard}:
3388 Technical Specification (TS) 18508 or later
3391 Collective subroutine
3393 @item @emph{Syntax}:
3394 @code{CALL CO_MAX(A [, RESULT_IMAGE, STAT, ERRMSG])}
3396 @item @emph{Arguments}:
3397 @multitable @columnfractions .15 .70
3398 @item @var{A} @tab shall be an integer, real or character variable,
3399 which has the same type and type parameters on all images of the team.
3400 @item @var{RESULT_IMAGE} @tab (optional) a scalar integer expression; if
3401 present, it shall have the same the same value on all images and refer to an
3402 image of the current team.
3403 @item @var{STAT} @tab (optional) a scalar integer variable
3404 @item @var{ERRMSG} @tab (optional) a scalar character variable
3407 @item @emph{Example}:
3412 call co_max (val, result_image=1)
3413 if (this_image() == 1) then
3414 write(*,*) "Maximal value", val ! prints num_images()
3419 @item @emph{See also}:
3420 @ref{CO_MIN}, @ref{CO_SUM}, @ref{CO_REDUCE}, @ref{CO_BROADCAST}
3426 @section @code{CO_MIN} --- Minimal value on the current set of images
3428 @cindex Collectives, minimal value
3431 @item @emph{Description}:
3432 @code{CO_MIN} determines element-wise the minimal value of @var{A} on all
3433 images of the current team. If @var{RESULT_IMAGE} is present, the minimal
3434 values are returned in @var{A} on the specified image only and the value
3435 of @var{A} on the other images become undefined. If @var{RESULT_IMAGE} is
3436 not present, the value is returned on all images. If the execution was
3437 successful and @var{STAT} is present, it is assigned the value zero. If the
3438 execution failed, @var{STAT} gets assigned a nonzero value and, if present,
3439 @var{ERRMSG} gets assigned a value describing the occurred error.
3441 @item @emph{Standard}:
3442 Technical Specification (TS) 18508 or later
3445 Collective subroutine
3447 @item @emph{Syntax}:
3448 @code{CALL CO_MIN(A [, RESULT_IMAGE, STAT, ERRMSG])}
3450 @item @emph{Arguments}:
3451 @multitable @columnfractions .15 .70
3452 @item @var{A} @tab shall be an integer, real or character variable,
3453 which has the same type and type parameters on all images of the team.
3454 @item @var{RESULT_IMAGE} @tab (optional) a scalar integer expression; if
3455 present, it shall have the same the same value on all images and refer to an
3456 image of the current team.
3457 @item @var{STAT} @tab (optional) a scalar integer variable
3458 @item @var{ERRMSG} @tab (optional) a scalar character variable
3461 @item @emph{Example}:
3466 call co_min (val, result_image=1)
3467 if (this_image() == 1) then
3468 write(*,*) "Minimal value", val ! prints 1
3473 @item @emph{See also}:
3474 @ref{CO_MAX}, @ref{CO_SUM}, @ref{CO_REDUCE}, @ref{CO_BROADCAST}
3480 @section @code{CO_REDUCE} --- Reduction of values on the current set of images
3482 @cindex Collectives, generic reduction
3485 @item @emph{Description}:
3486 @code{CO_REDUCE} determines element-wise the reduction of the value of @var{A}
3487 on all images of the current team. The pure function passed as @var{OPERATOR}
3488 is used to pairwise reduce the values of @var{A} by passing either the value
3489 of @var{A} of different images or the result values of such a reduction as
3490 argument. If @var{A} is an array, the deduction is done element wise. If
3491 @var{RESULT_IMAGE} is present, the result values are returned in @var{A} on
3492 the specified image only and the value of @var{A} on the other images become
3493 undefined. If @var{RESULT_IMAGE} is not present, the value is returned on all
3494 images. If the execution was successful and @var{STAT} is present, it is
3495 assigned the value zero. If the execution failed, @var{STAT} gets assigned
3496 a nonzero value and, if present, @var{ERRMSG} gets assigned a value describing
3499 @item @emph{Standard}:
3500 Technical Specification (TS) 18508 or later
3503 Collective subroutine
3505 @item @emph{Syntax}:
3506 @code{CALL CO_REDUCE(A, OPERATOR, [, RESULT_IMAGE, STAT, ERRMSG])}
3508 @item @emph{Arguments}:
3509 @multitable @columnfractions .15 .70
3510 @item @var{A} @tab is an @code{INTENT(INOUT)} argument and shall be
3511 nonpolymorphic. If it is allocatable, it shall be allocated; if it is a pointer,
3512 it shall be associated. @var{A} shall have the same type and type parameters on
3513 all images of the team; if it is an array, it shall have the same shape on all
3515 @item @var{OPERATOR} @tab pure function with two scalar nonallocatable
3516 arguments, which shall be nonpolymorphic and have the same type and type
3517 parameters as @var{A}. The function shall return a nonallocatable scalar of
3518 the same type and type parameters as @var{A}. The function shall be the same on
3519 all images and with regards to the arguments mathematically commutative and
3520 associative. Note that @var{OPERATOR} may not be an elemental function, unless
3521 it is an intrisic function.
3522 @item @var{RESULT_IMAGE} @tab (optional) a scalar integer expression; if
3523 present, it shall have the same the same value on all images and refer to an
3524 image of the current team.
3525 @item @var{STAT} @tab (optional) a scalar integer variable
3526 @item @var{ERRMSG} @tab (optional) a scalar character variable
3529 @item @emph{Example}:
3534 call co_reduce (val, result_image=1, operator=myprod)
3535 if (this_image() == 1) then
3536 write(*,*) "Product value", val ! prints num_images() factorial
3539 pure function myprod(a, b)
3540 integer, value :: a, b
3548 While the rules permit in principle an intrinsic function, none of the
3549 intrinsics in the standard fulfill the criteria of having a specific
3550 function, which takes two arguments of the same type and returning that
3553 @item @emph{See also}:
3554 @ref{CO_MIN}, @ref{CO_MAX}, @ref{CO_SUM}, @ref{CO_BROADCAST}
3560 @section @code{CO_SUM} --- Sum of values on the current set of images
3562 @cindex Collectives, sum of values
3565 @item @emph{Description}:
3566 @code{CO_SUM} sums up the values of each element of @var{A} on all
3567 images of the current team. If @var{RESULT_IMAGE} is present, the summed-up
3568 values are returned in @var{A} on the specified image only and the value
3569 of @var{A} on the other images become undefined. If @var{RESULT_IMAGE} is
3570 not present, the value is returned on all images. If the execution was
3571 successful and @var{STAT} is present, it is assigned the value zero. If the
3572 execution failed, @var{STAT} gets assigned a nonzero value and, if present,
3573 @var{ERRMSG} gets assigned a value describing the occurred error.
3575 @item @emph{Standard}:
3576 Technical Specification (TS) 18508 or later
3579 Collective subroutine
3581 @item @emph{Syntax}:
3582 @code{CALL CO_MIN(A [, RESULT_IMAGE, STAT, ERRMSG])}
3584 @item @emph{Arguments}:
3585 @multitable @columnfractions .15 .70
3586 @item @var{A} @tab shall be an integer, real or complex variable,
3587 which has the same type and type parameters on all images of the team.
3588 @item @var{RESULT_IMAGE} @tab (optional) a scalar integer expression; if
3589 present, it shall have the same the same value on all images and refer to an
3590 image of the current team.
3591 @item @var{STAT} @tab (optional) a scalar integer variable
3592 @item @var{ERRMSG} @tab (optional) a scalar character variable
3595 @item @emph{Example}:
3600 call co_sum (val, result_image=1)
3601 if (this_image() == 1) then
3602 write(*,*) "The sum is ", val ! prints (n**2 + n)/2, with n = num_images()
3607 @item @emph{See also}:
3608 @ref{CO_MAX}, @ref{CO_MIN}, @ref{CO_REDUCE}, @ref{CO_BROADCAST}
3613 @node COMMAND_ARGUMENT_COUNT
3614 @section @code{COMMAND_ARGUMENT_COUNT} --- Get number of command line arguments
3615 @fnindex COMMAND_ARGUMENT_COUNT
3616 @cindex command-line arguments
3617 @cindex command-line arguments, number of
3618 @cindex arguments, to program
3621 @item @emph{Description}:
3622 @code{COMMAND_ARGUMENT_COUNT} returns the number of arguments passed on the
3623 command line when the containing program was invoked.
3625 @item @emph{Standard}:
3626 Fortran 2003 and later
3631 @item @emph{Syntax}:
3632 @code{RESULT = COMMAND_ARGUMENT_COUNT()}
3634 @item @emph{Arguments}:
3635 @multitable @columnfractions .15 .70
3639 @item @emph{Return value}:
3640 The return value is an @code{INTEGER} of default kind.
3642 @item @emph{Example}:
3644 program test_command_argument_count
3646 count = command_argument_count()
3648 end program test_command_argument_count
3651 @item @emph{See also}:
3652 @ref{GET_COMMAND}, @ref{GET_COMMAND_ARGUMENT}
3657 @node COMPILER_OPTIONS
3658 @section @code{COMPILER_OPTIONS} --- Options passed to the compiler
3659 @fnindex COMPILER_OPTIONS
3660 @cindex flags inquiry function
3661 @cindex options inquiry function
3662 @cindex compiler flags inquiry function
3665 @item @emph{Description}:
3666 @code{COMPILER_OPTIONS} returns a string with the options used for
3669 @item @emph{Standard}:
3673 Inquiry function of the module @code{ISO_FORTRAN_ENV}
3675 @item @emph{Syntax}:
3676 @code{STR = COMPILER_OPTIONS()}
3678 @item @emph{Arguments}:
3681 @item @emph{Return value}:
3682 The return value is a default-kind string with system-dependent length.
3683 It contains the compiler flags used to compile the file, which called
3684 the @code{COMPILER_OPTIONS} intrinsic.
3686 @item @emph{Example}:
3689 print '(4a)', 'This file was compiled by ', &
3690 compiler_version(), ' using the options ', &
3695 @item @emph{See also}:
3696 @ref{COMPILER_VERSION}, @ref{ISO_FORTRAN_ENV}
3701 @node COMPILER_VERSION
3702 @section @code{COMPILER_VERSION} --- Compiler version string
3703 @fnindex COMPILER_VERSION
3704 @cindex compiler, name and version
3705 @cindex version of the compiler
3708 @item @emph{Description}:
3709 @code{COMPILER_VERSION} returns a string with the name and the
3710 version of the compiler.
3712 @item @emph{Standard}:
3716 Inquiry function of the module @code{ISO_FORTRAN_ENV}
3718 @item @emph{Syntax}:
3719 @code{STR = COMPILER_VERSION()}
3721 @item @emph{Arguments}:
3724 @item @emph{Return value}:
3725 The return value is a default-kind string with system-dependent length.
3726 It contains the name of the compiler and its version number.
3728 @item @emph{Example}:
3731 print '(4a)', 'This file was compiled by ', &
3732 compiler_version(), ' using the options ', &
3737 @item @emph{See also}:
3738 @ref{COMPILER_OPTIONS}, @ref{ISO_FORTRAN_ENV}
3744 @section @code{COMPLEX} --- Complex conversion function
3746 @cindex complex numbers, conversion to
3747 @cindex conversion, to complex
3750 @item @emph{Description}:
3751 @code{COMPLEX(X, Y)} returns a complex number where @var{X} is converted
3752 to the real component and @var{Y} is converted to the imaginary
3755 @item @emph{Standard}:
3761 @item @emph{Syntax}:
3762 @code{RESULT = COMPLEX(X, Y)}
3764 @item @emph{Arguments}:
3765 @multitable @columnfractions .15 .70
3766 @item @var{X} @tab The type may be @code{INTEGER} or @code{REAL}.
3767 @item @var{Y} @tab The type may be @code{INTEGER} or @code{REAL}.
3770 @item @emph{Return value}:
3771 If @var{X} and @var{Y} are both of @code{INTEGER} type, then the return
3772 value is of default @code{COMPLEX} type.
3774 If @var{X} and @var{Y} are of @code{REAL} type, or one is of @code{REAL}
3775 type and one is of @code{INTEGER} type, then the return value is of
3776 @code{COMPLEX} type with a kind equal to that of the @code{REAL}
3777 argument with the highest precision.
3779 @item @emph{Example}:
3781 program test_complex
3784 print *, complex(i, x)
3785 end program test_complex
3788 @item @emph{See also}:
3795 @section @code{CONJG} --- Complex conjugate function
3798 @cindex complex conjugate
3801 @item @emph{Description}:
3802 @code{CONJG(Z)} returns the conjugate of @var{Z}. If @var{Z} is @code{(x, y)}
3803 then the result is @code{(x, -y)}
3805 @item @emph{Standard}:
3806 Fortran 77 and later, has overloads that are GNU extensions
3811 @item @emph{Syntax}:
3814 @item @emph{Arguments}:
3815 @multitable @columnfractions .15 .70
3816 @item @var{Z} @tab The type shall be @code{COMPLEX}.
3819 @item @emph{Return value}:
3820 The return value is of type @code{COMPLEX}.
3822 @item @emph{Example}:
3825 complex :: z = (2.0, 3.0)
3826 complex(8) :: dz = (2.71_8, -3.14_8)
3831 end program test_conjg
3834 @item @emph{Specific names}:
3835 @multitable @columnfractions .20 .20 .20 .25
3836 @item Name @tab Argument @tab Return type @tab Standard
3837 @item @code{CONJG(Z)} @tab @code{COMPLEX Z} @tab @code{COMPLEX} @tab GNU extension
3838 @item @code{DCONJG(Z)} @tab @code{COMPLEX(8) Z} @tab @code{COMPLEX(8)} @tab GNU extension
3845 @section @code{COS} --- Cosine function
3851 @cindex trigonometric function, cosine
3855 @item @emph{Description}:
3856 @code{COS(X)} computes the cosine of @var{X}.
3858 @item @emph{Standard}:
3859 Fortran 77 and later, has overloads that are GNU extensions
3864 @item @emph{Syntax}:
3865 @code{RESULT = COS(X)}
3867 @item @emph{Arguments}:
3868 @multitable @columnfractions .15 .70
3869 @item @var{X} @tab The type shall be @code{REAL} or
3873 @item @emph{Return value}:
3874 The return value is of the same type and kind as @var{X}. The real part
3875 of the result is in radians. If @var{X} is of the type @code{REAL},
3876 the return value lies in the range @math{ -1 \leq \cos (x) \leq 1}.
3878 @item @emph{Example}:
3883 end program test_cos
3886 @item @emph{Specific names}:
3887 @multitable @columnfractions .20 .20 .20 .25
3888 @item Name @tab Argument @tab Return type @tab Standard
3889 @item @code{COS(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab Fortran 77 and later
3890 @item @code{DCOS(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab Fortran 77 and later
3891 @item @code{CCOS(X)} @tab @code{COMPLEX(4) X} @tab @code{COMPLEX(4)} @tab Fortran 77 and later
3892 @item @code{ZCOS(X)} @tab @code{COMPLEX(8) X} @tab @code{COMPLEX(8)} @tab GNU extension
3893 @item @code{CDCOS(X)} @tab @code{COMPLEX(8) X} @tab @code{COMPLEX(8)} @tab GNU extension
3896 @item @emph{See also}:
3897 Inverse function: @ref{ACOS}
3904 @section @code{COSH} --- Hyperbolic cosine function
3907 @cindex hyperbolic cosine
3908 @cindex hyperbolic function, cosine
3909 @cindex cosine, hyperbolic
3912 @item @emph{Description}:
3913 @code{COSH(X)} computes the hyperbolic cosine of @var{X}.
3915 @item @emph{Standard}:
3916 Fortran 77 and later, for a complex argument Fortran 2008 or later
3921 @item @emph{Syntax}:
3924 @item @emph{Arguments}:
3925 @multitable @columnfractions .15 .70
3926 @item @var{X} @tab The type shall be @code{REAL} or @code{COMPLEX}.
3929 @item @emph{Return value}:
3930 The return value has same type and kind as @var{X}. If @var{X} is
3931 complex, the imaginary part of the result is in radians. If @var{X}
3932 is @code{REAL}, the return value has a lower bound of one,
3933 @math{\cosh (x) \geq 1}.
3935 @item @emph{Example}:
3938 real(8) :: x = 1.0_8
3940 end program test_cosh
3943 @item @emph{Specific names}:
3944 @multitable @columnfractions .20 .20 .20 .25
3945 @item Name @tab Argument @tab Return type @tab Standard
3946 @item @code{COSH(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab Fortran 77 and later
3947 @item @code{DCOSH(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab Fortran 77 and later
3950 @item @emph{See also}:
3951 Inverse function: @ref{ACOSH}
3958 @section @code{COUNT} --- Count function
3960 @cindex array, conditionally count elements
3961 @cindex array, element counting
3962 @cindex array, number of elements
3965 @item @emph{Description}:
3967 Counts the number of @code{.TRUE.} elements in a logical @var{MASK},
3968 or, if the @var{DIM} argument is supplied, counts the number of
3969 elements along each row of the array in the @var{DIM} direction.
3970 If the array has zero size, or all of the elements of @var{MASK} are
3971 @code{.FALSE.}, then the result is @code{0}.
3973 @item @emph{Standard}:
3974 Fortran 95 and later, with @var{KIND} argument Fortran 2003 and later
3977 Transformational function
3979 @item @emph{Syntax}:
3980 @code{RESULT = COUNT(MASK [, DIM, KIND])}
3982 @item @emph{Arguments}:
3983 @multitable @columnfractions .15 .70
3984 @item @var{MASK} @tab The type shall be @code{LOGICAL}.
3985 @item @var{DIM} @tab (Optional) The type shall be @code{INTEGER}.
3986 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
3987 expression indicating the kind parameter of the result.
3990 @item @emph{Return value}:
3991 The return value is of type @code{INTEGER} and of kind @var{KIND}. If
3992 @var{KIND} is absent, the return value is of default integer kind.
3993 If @var{DIM} is present, the result is an array with a rank one less
3994 than the rank of @var{ARRAY}, and a size corresponding to the shape
3995 of @var{ARRAY} with the @var{DIM} dimension removed.
3997 @item @emph{Example}:
4000 integer, dimension(2,3) :: a, b
4001 logical, dimension(2,3) :: mask
4002 a = reshape( (/ 1, 2, 3, 4, 5, 6 /), (/ 2, 3 /))
4003 b = reshape( (/ 0, 7, 3, 4, 5, 8 /), (/ 2, 3 /))
4004 print '(3i3)', a(1,:)
4005 print '(3i3)', a(2,:)
4007 print '(3i3)', b(1,:)
4008 print '(3i3)', b(2,:)
4011 print '(3l3)', mask(1,:)
4012 print '(3l3)', mask(2,:)
4014 print '(3i3)', count(mask)
4016 print '(3i3)', count(mask, 1)
4018 print '(3i3)', count(mask, 2)
4019 end program test_count
4026 @section @code{CPU_TIME} --- CPU elapsed time in seconds
4028 @cindex time, elapsed
4031 @item @emph{Description}:
4032 Returns a @code{REAL} value representing the elapsed CPU time in
4033 seconds. This is useful for testing segments of code to determine
4036 If a time source is available, time will be reported with microsecond
4037 resolution. If no time source is available, @var{TIME} is set to
4040 Note that @var{TIME} may contain a, system dependent, arbitrary offset
4041 and may not start with @code{0.0}. For @code{CPU_TIME}, the absolute
4042 value is meaningless, only differences between subsequent calls to
4043 this subroutine, as shown in the example below, should be used.
4046 @item @emph{Standard}:
4047 Fortran 95 and later
4052 @item @emph{Syntax}:
4053 @code{CALL CPU_TIME(TIME)}
4055 @item @emph{Arguments}:
4056 @multitable @columnfractions .15 .70
4057 @item @var{TIME} @tab The type shall be @code{REAL} with @code{INTENT(OUT)}.
4060 @item @emph{Return value}:
4063 @item @emph{Example}:
4065 program test_cpu_time
4066 real :: start, finish
4067 call cpu_time(start)
4068 ! put code to test here
4069 call cpu_time(finish)
4070 print '("Time = ",f6.3," seconds.")',finish-start
4071 end program test_cpu_time
4074 @item @emph{See also}:
4075 @ref{SYSTEM_CLOCK}, @ref{DATE_AND_TIME}
4081 @section @code{CSHIFT} --- Circular shift elements of an array
4083 @cindex array, shift circularly
4084 @cindex array, permutation
4085 @cindex array, rotate
4088 @item @emph{Description}:
4089 @code{CSHIFT(ARRAY, SHIFT [, DIM])} performs a circular shift on elements of
4090 @var{ARRAY} along the dimension of @var{DIM}. If @var{DIM} is omitted it is
4091 taken to be @code{1}. @var{DIM} is a scalar of type @code{INTEGER} in the
4092 range of @math{1 \leq DIM \leq n)} where @math{n} is the rank of @var{ARRAY}.
4093 If the rank of @var{ARRAY} is one, then all elements of @var{ARRAY} are shifted
4094 by @var{SHIFT} places. If rank is greater than one, then all complete rank one
4095 sections of @var{ARRAY} along the given dimension are shifted. Elements
4096 shifted out one end of each rank one section are shifted back in the other end.
4098 @item @emph{Standard}:
4099 Fortran 95 and later
4102 Transformational function
4104 @item @emph{Syntax}:
4105 @code{RESULT = CSHIFT(ARRAY, SHIFT [, DIM])}
4107 @item @emph{Arguments}:
4108 @multitable @columnfractions .15 .70
4109 @item @var{ARRAY} @tab Shall be an array of any type.
4110 @item @var{SHIFT} @tab The type shall be @code{INTEGER}.
4111 @item @var{DIM} @tab The type shall be @code{INTEGER}.
4114 @item @emph{Return value}:
4115 Returns an array of same type and rank as the @var{ARRAY} argument.
4117 @item @emph{Example}:
4120 integer, dimension(3,3) :: a
4121 a = reshape( (/ 1, 2, 3, 4, 5, 6, 7, 8, 9 /), (/ 3, 3 /))
4122 print '(3i3)', a(1,:)
4123 print '(3i3)', a(2,:)
4124 print '(3i3)', a(3,:)
4125 a = cshift(a, SHIFT=(/1, 2, -1/), DIM=2)
4127 print '(3i3)', a(1,:)
4128 print '(3i3)', a(2,:)
4129 print '(3i3)', a(3,:)
4130 end program test_cshift
4137 @section @code{CTIME} --- Convert a time into a string
4139 @cindex time, conversion to string
4140 @cindex conversion, to string
4143 @item @emph{Description}:
4144 @code{CTIME} converts a system time value, such as returned by
4145 @code{TIME8}, to a string. The output will be of the form @samp{Sat
4146 Aug 19 18:13:14 1995}.
4148 This intrinsic is provided in both subroutine and function forms; however,
4149 only one form can be used in any given program unit.
4151 @item @emph{Standard}:
4155 Subroutine, function
4157 @item @emph{Syntax}:
4158 @multitable @columnfractions .80
4159 @item @code{CALL CTIME(TIME, RESULT)}.
4160 @item @code{RESULT = CTIME(TIME)}.
4163 @item @emph{Arguments}:
4164 @multitable @columnfractions .15 .70
4165 @item @var{TIME} @tab The type shall be of type @code{INTEGER}.
4166 @item @var{RESULT} @tab The type shall be of type @code{CHARACTER} and
4167 of default kind. It is an @code{INTENT(OUT)} argument. If the length
4168 of this variable is too short for the time and date string to fit
4169 completely, it will be blank on procedure return.
4172 @item @emph{Return value}:
4173 The converted date and time as a string.
4175 @item @emph{Example}:
4179 character(len=30) :: date
4182 ! Do something, main part of the program
4185 print *, 'Program was started on ', date
4186 end program test_ctime
4189 @item @emph{See Also}:
4190 @ref{DATE_AND_TIME}, @ref{GMTIME}, @ref{LTIME}, @ref{TIME}, @ref{TIME8}
4196 @section @code{DATE_AND_TIME} --- Date and time subroutine
4197 @fnindex DATE_AND_TIME
4198 @cindex date, current
4199 @cindex current date
4200 @cindex time, current
4201 @cindex current time
4204 @item @emph{Description}:
4205 @code{DATE_AND_TIME(DATE, TIME, ZONE, VALUES)} gets the corresponding date and
4206 time information from the real-time system clock. @var{DATE} is
4207 @code{INTENT(OUT)} and has form ccyymmdd. @var{TIME} is @code{INTENT(OUT)} and
4208 has form hhmmss.sss. @var{ZONE} is @code{INTENT(OUT)} and has form (+-)hhmm,
4209 representing the difference with respect to Coordinated Universal Time (UTC).
4210 Unavailable time and date parameters return blanks.
4212 @var{VALUES} is @code{INTENT(OUT)} and provides the following:
4214 @multitable @columnfractions .15 .30 .40
4215 @item @tab @code{VALUE(1)}: @tab The year
4216 @item @tab @code{VALUE(2)}: @tab The month
4217 @item @tab @code{VALUE(3)}: @tab The day of the month
4218 @item @tab @code{VALUE(4)}: @tab Time difference with UTC in minutes
4219 @item @tab @code{VALUE(5)}: @tab The hour of the day
4220 @item @tab @code{VALUE(6)}: @tab The minutes of the hour
4221 @item @tab @code{VALUE(7)}: @tab The seconds of the minute
4222 @item @tab @code{VALUE(8)}: @tab The milliseconds of the second
4225 @item @emph{Standard}:
4226 Fortran 95 and later
4231 @item @emph{Syntax}:
4232 @code{CALL DATE_AND_TIME([DATE, TIME, ZONE, VALUES])}
4234 @item @emph{Arguments}:
4235 @multitable @columnfractions .15 .70
4236 @item @var{DATE} @tab (Optional) The type shall be @code{CHARACTER(LEN=8)}
4237 or larger, and of default kind.
4238 @item @var{TIME} @tab (Optional) The type shall be @code{CHARACTER(LEN=10)}
4239 or larger, and of default kind.
4240 @item @var{ZONE} @tab (Optional) The type shall be @code{CHARACTER(LEN=5)}
4241 or larger, and of default kind.
4242 @item @var{VALUES}@tab (Optional) The type shall be @code{INTEGER(8)}.
4245 @item @emph{Return value}:
4248 @item @emph{Example}:
4250 program test_time_and_date
4251 character(8) :: date
4252 character(10) :: time
4253 character(5) :: zone
4254 integer,dimension(8) :: values
4255 ! using keyword arguments
4256 call date_and_time(date,time,zone,values)
4257 call date_and_time(DATE=date,ZONE=zone)
4258 call date_and_time(TIME=time)
4259 call date_and_time(VALUES=values)
4260 print '(a,2x,a,2x,a)', date, time, zone
4261 print '(8i5)', values
4262 end program test_time_and_date
4265 @item @emph{See also}:
4266 @ref{CPU_TIME}, @ref{SYSTEM_CLOCK}
4272 @section @code{DBLE} --- Double conversion function
4274 @cindex conversion, to real
4277 @item @emph{Description}:
4278 @code{DBLE(A)} Converts @var{A} to double precision real type.
4280 @item @emph{Standard}:
4281 Fortran 77 and later
4286 @item @emph{Syntax}:
4287 @code{RESULT = DBLE(A)}
4289 @item @emph{Arguments}:
4290 @multitable @columnfractions .15 .70
4291 @item @var{A} @tab The type shall be @code{INTEGER}, @code{REAL},
4295 @item @emph{Return value}:
4296 The return value is of type double precision real.
4298 @item @emph{Example}:
4303 complex :: z = (2.3,1.14)
4304 print *, dble(x), dble(i), dble(z)
4305 end program test_dble
4308 @item @emph{See also}:
4315 @section @code{DCMPLX} --- Double complex conversion function
4317 @cindex complex numbers, conversion to
4318 @cindex conversion, to complex
4321 @item @emph{Description}:
4322 @code{DCMPLX(X [,Y])} returns a double complex number where @var{X} is
4323 converted to the real component. If @var{Y} is present it is converted to the
4324 imaginary component. If @var{Y} is not present then the imaginary component is
4325 set to 0.0. If @var{X} is complex then @var{Y} must not be present.
4327 @item @emph{Standard}:
4333 @item @emph{Syntax}:
4334 @code{RESULT = DCMPLX(X [, Y])}
4336 @item @emph{Arguments}:
4337 @multitable @columnfractions .15 .70
4338 @item @var{X} @tab The type may be @code{INTEGER}, @code{REAL},
4340 @item @var{Y} @tab (Optional if @var{X} is not @code{COMPLEX}.) May be
4341 @code{INTEGER} or @code{REAL}.
4344 @item @emph{Return value}:
4345 The return value is of type @code{COMPLEX(8)}
4347 @item @emph{Example}:
4357 print *, dcmplx(x,i)
4358 end program test_dcmplx
4364 @section @code{DIGITS} --- Significant binary digits function
4366 @cindex model representation, significant digits
4369 @item @emph{Description}:
4370 @code{DIGITS(X)} returns the number of significant binary digits of the internal
4371 model representation of @var{X}. For example, on a system using a 32-bit
4372 floating point representation, a default real number would likely return 24.
4374 @item @emph{Standard}:
4375 Fortran 95 and later
4380 @item @emph{Syntax}:
4381 @code{RESULT = DIGITS(X)}
4383 @item @emph{Arguments}:
4384 @multitable @columnfractions .15 .70
4385 @item @var{X} @tab The type may be @code{INTEGER} or @code{REAL}.
4388 @item @emph{Return value}:
4389 The return value is of type @code{INTEGER}.
4391 @item @emph{Example}:
4394 integer :: i = 12345
4400 end program test_digits
4407 @section @code{DIM} --- Positive difference
4411 @cindex positive difference
4414 @item @emph{Description}:
4415 @code{DIM(X,Y)} returns the difference @code{X-Y} if the result is positive;
4416 otherwise returns zero.
4418 @item @emph{Standard}:
4419 Fortran 77 and later
4424 @item @emph{Syntax}:
4425 @code{RESULT = DIM(X, Y)}
4427 @item @emph{Arguments}:
4428 @multitable @columnfractions .15 .70
4429 @item @var{X} @tab The type shall be @code{INTEGER} or @code{REAL}
4430 @item @var{Y} @tab The type shall be the same type and kind as @var{X}.
4433 @item @emph{Return value}:
4434 The return value is of type @code{INTEGER} or @code{REAL}.
4436 @item @emph{Example}:
4442 x = dim(4.345_8, 2.111_8)
4445 end program test_dim
4448 @item @emph{Specific names}:
4449 @multitable @columnfractions .20 .20 .20 .25
4450 @item Name @tab Argument @tab Return type @tab Standard
4451 @item @code{DIM(X,Y)} @tab @code{REAL(4) X, Y} @tab @code{REAL(4)} @tab Fortran 77 and later
4452 @item @code{IDIM(X,Y)} @tab @code{INTEGER(4) X, Y} @tab @code{INTEGER(4)} @tab Fortran 77 and later
4453 @item @code{DDIM(X,Y)} @tab @code{REAL(8) X, Y} @tab @code{REAL(8)} @tab Fortran 77 and later
4460 @section @code{DOT_PRODUCT} --- Dot product function
4461 @fnindex DOT_PRODUCT
4463 @cindex vector product
4464 @cindex product, vector
4467 @item @emph{Description}:
4468 @code{DOT_PRODUCT(VECTOR_A, VECTOR_B)} computes the dot product multiplication
4469 of two vectors @var{VECTOR_A} and @var{VECTOR_B}. The two vectors may be
4470 either numeric or logical and must be arrays of rank one and of equal size. If
4471 the vectors are @code{INTEGER} or @code{REAL}, the result is
4472 @code{SUM(VECTOR_A*VECTOR_B)}. If the vectors are @code{COMPLEX}, the result
4473 is @code{SUM(CONJG(VECTOR_A)*VECTOR_B)}. If the vectors are @code{LOGICAL},
4474 the result is @code{ANY(VECTOR_A .AND. VECTOR_B)}.
4476 @item @emph{Standard}:
4477 Fortran 95 and later
4480 Transformational function
4482 @item @emph{Syntax}:
4483 @code{RESULT = DOT_PRODUCT(VECTOR_A, VECTOR_B)}
4485 @item @emph{Arguments}:
4486 @multitable @columnfractions .15 .70
4487 @item @var{VECTOR_A} @tab The type shall be numeric or @code{LOGICAL}, rank 1.
4488 @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.
4491 @item @emph{Return value}:
4492 If the arguments are numeric, the return value is a scalar of numeric type,
4493 @code{INTEGER}, @code{REAL}, or @code{COMPLEX}. If the arguments are
4494 @code{LOGICAL}, the return value is @code{.TRUE.} or @code{.FALSE.}.
4496 @item @emph{Example}:
4498 program test_dot_prod
4499 integer, dimension(3) :: a, b
4506 print *, dot_product(a,b)
4507 end program test_dot_prod
4514 @section @code{DPROD} --- Double product function
4516 @cindex product, double-precision
4519 @item @emph{Description}:
4520 @code{DPROD(X,Y)} returns the product @code{X*Y}.
4522 @item @emph{Standard}:
4523 Fortran 77 and later
4528 @item @emph{Syntax}:
4529 @code{RESULT = DPROD(X, Y)}
4531 @item @emph{Arguments}:
4532 @multitable @columnfractions .15 .70
4533 @item @var{X} @tab The type shall be @code{REAL}.
4534 @item @var{Y} @tab The type shall be @code{REAL}.
4537 @item @emph{Return value}:
4538 The return value is of type @code{REAL(8)}.
4540 @item @emph{Example}:
4548 end program test_dprod
4551 @item @emph{Specific names}:
4552 @multitable @columnfractions .20 .20 .20 .25
4553 @item Name @tab Argument @tab Return type @tab Standard
4554 @item @code{DPROD(X,Y)} @tab @code{REAL(4) X, Y} @tab @code{REAL(8)} @tab Fortran 77 and later
4561 @section @code{DREAL} --- Double real part function
4563 @cindex complex numbers, real part
4566 @item @emph{Description}:
4567 @code{DREAL(Z)} returns the real part of complex variable @var{Z}.
4569 @item @emph{Standard}:
4575 @item @emph{Syntax}:
4576 @code{RESULT = DREAL(A)}
4578 @item @emph{Arguments}:
4579 @multitable @columnfractions .15 .70
4580 @item @var{A} @tab The type shall be @code{COMPLEX(8)}.
4583 @item @emph{Return value}:
4584 The return value is of type @code{REAL(8)}.
4586 @item @emph{Example}:
4589 complex(8) :: z = (1.3_8,7.2_8)
4591 end program test_dreal
4594 @item @emph{See also}:
4602 @section @code{DSHIFTL} --- Combined left shift
4604 @cindex left shift, combined
4608 @item @emph{Description}:
4609 @code{DSHIFTL(I, J, SHIFT)} combines bits of @var{I} and @var{J}. The
4610 rightmost @var{SHIFT} bits of the result are the leftmost @var{SHIFT}
4611 bits of @var{J}, and the remaining bits are the rightmost bits of
4614 @item @emph{Standard}:
4615 Fortran 2008 and later
4620 @item @emph{Syntax}:
4621 @code{RESULT = DSHIFTL(I, J, SHIFT)}
4623 @item @emph{Arguments}:
4624 @multitable @columnfractions .15 .70
4625 @item @var{I} @tab Shall be of type @code{INTEGER} or a BOZ constant.
4626 @item @var{J} @tab Shall be of type @code{INTEGER} or a BOZ constant.
4627 If both @var{I} and @var{J} have integer type, then they shall have
4628 the same kind type parameter. @var{I} and @var{J} shall not both be
4630 @item @var{SHIFT} @tab Shall be of type @code{INTEGER}. It shall
4631 be nonnegative. If @var{I} is not a BOZ constant, then @var{SHIFT}
4632 shall be less than or equal to @code{BIT_SIZE(I)}; otherwise,
4633 @var{SHIFT} shall be less than or equal to @code{BIT_SIZE(J)}.
4636 @item @emph{Return value}:
4637 If either @var{I} or @var{J} is a BOZ constant, it is first converted
4638 as if by the intrinsic function @code{INT} to an integer type with the
4639 kind type parameter of the other.
4641 @item @emph{See also}:
4647 @section @code{DSHIFTR} --- Combined right shift
4649 @cindex right shift, combined
4650 @cindex shift, right
4653 @item @emph{Description}:
4654 @code{DSHIFTR(I, J, SHIFT)} combines bits of @var{I} and @var{J}. The
4655 leftmost @var{SHIFT} bits of the result are the rightmost @var{SHIFT}
4656 bits of @var{I}, and the remaining bits are the leftmost bits of
4659 @item @emph{Standard}:
4660 Fortran 2008 and later
4665 @item @emph{Syntax}:
4666 @code{RESULT = DSHIFTR(I, J, SHIFT)}
4668 @item @emph{Arguments}:
4669 @multitable @columnfractions .15 .70
4670 @item @var{I} @tab Shall be of type @code{INTEGER} or a BOZ constant.
4671 @item @var{J} @tab Shall be of type @code{INTEGER} or a BOZ constant.
4672 If both @var{I} and @var{J} have integer type, then they shall have
4673 the same kind type parameter. @var{I} and @var{J} shall not both be
4675 @item @var{SHIFT} @tab Shall be of type @code{INTEGER}. It shall
4676 be nonnegative. If @var{I} is not a BOZ constant, then @var{SHIFT}
4677 shall be less than or equal to @code{BIT_SIZE(I)}; otherwise,
4678 @var{SHIFT} shall be less than or equal to @code{BIT_SIZE(J)}.
4681 @item @emph{Return value}:
4682 If either @var{I} or @var{J} is a BOZ constant, it is first converted
4683 as if by the intrinsic function @code{INT} to an integer type with the
4684 kind type parameter of the other.
4686 @item @emph{See also}:
4692 @section @code{DTIME} --- Execution time subroutine (or function)
4694 @cindex time, elapsed
4695 @cindex elapsed time
4698 @item @emph{Description}:
4699 @code{DTIME(VALUES, TIME)} initially returns the number of seconds of runtime
4700 since the start of the process's execution in @var{TIME}. @var{VALUES}
4701 returns the user and system components of this time in @code{VALUES(1)} and
4702 @code{VALUES(2)} respectively. @var{TIME} is equal to @code{VALUES(1) +
4705 Subsequent invocations of @code{DTIME} return values accumulated since the
4706 previous invocation.
4708 On some systems, the underlying timings are represented using types with
4709 sufficiently small limits that overflows (wrap around) are possible, such as
4710 32-bit types. Therefore, the values returned by this intrinsic might be, or
4711 become, negative, or numerically less than previous values, during a single
4712 run of the compiled program.
4714 Please note, that this implementation is thread safe if used within OpenMP
4715 directives, i.e., its state will be consistent while called from multiple
4716 threads. However, if @code{DTIME} is called from multiple threads, the result
4717 is still the time since the last invocation. This may not give the intended
4718 results. If possible, use @code{CPU_TIME} instead.
4720 This intrinsic is provided in both subroutine and function forms; however,
4721 only one form can be used in any given program unit.
4723 @var{VALUES} and @var{TIME} are @code{INTENT(OUT)} and provide the following:
4725 @multitable @columnfractions .15 .30 .40
4726 @item @tab @code{VALUES(1)}: @tab User time in seconds.
4727 @item @tab @code{VALUES(2)}: @tab System time in seconds.
4728 @item @tab @code{TIME}: @tab Run time since start in seconds.
4731 @item @emph{Standard}:
4735 Subroutine, function
4737 @item @emph{Syntax}:
4738 @multitable @columnfractions .80
4739 @item @code{CALL DTIME(VALUES, TIME)}.
4740 @item @code{TIME = DTIME(VALUES)}, (not recommended).
4743 @item @emph{Arguments}:
4744 @multitable @columnfractions .15 .70
4745 @item @var{VALUES}@tab The type shall be @code{REAL(4), DIMENSION(2)}.
4746 @item @var{TIME}@tab The type shall be @code{REAL(4)}.
4749 @item @emph{Return value}:
4750 Elapsed time in seconds since the last invocation or since the start of program
4751 execution if not called before.
4753 @item @emph{Example}:
4757 real, dimension(2) :: tarray
4759 call dtime(tarray, result)
4763 do i=1,100000000 ! Just a delay
4766 call dtime(tarray, result)
4770 end program test_dtime
4773 @item @emph{See also}:
4781 @section @code{EOSHIFT} --- End-off shift elements of an array
4783 @cindex array, shift
4786 @item @emph{Description}:
4787 @code{EOSHIFT(ARRAY, SHIFT[, BOUNDARY, DIM])} performs an end-off shift on
4788 elements of @var{ARRAY} along the dimension of @var{DIM}. If @var{DIM} is
4789 omitted it is taken to be @code{1}. @var{DIM} is a scalar of type
4790 @code{INTEGER} in the range of @math{1 \leq DIM \leq n)} where @math{n} is the
4791 rank of @var{ARRAY}. If the rank of @var{ARRAY} is one, then all elements of
4792 @var{ARRAY} are shifted by @var{SHIFT} places. If rank is greater than one,
4793 then all complete rank one sections of @var{ARRAY} along the given dimension are
4794 shifted. Elements shifted out one end of each rank one section are dropped. If
4795 @var{BOUNDARY} is present then the corresponding value of from @var{BOUNDARY}
4796 is copied back in the other end. If @var{BOUNDARY} is not present then the
4797 following are copied in depending on the type of @var{ARRAY}.
4799 @multitable @columnfractions .15 .80
4800 @item @emph{Array Type} @tab @emph{Boundary Value}
4801 @item Numeric @tab 0 of the type and kind of @var{ARRAY}.
4802 @item Logical @tab @code{.FALSE.}.
4803 @item Character(@var{len}) @tab @var{len} blanks.
4806 @item @emph{Standard}:
4807 Fortran 95 and later
4810 Transformational function
4812 @item @emph{Syntax}:
4813 @code{RESULT = EOSHIFT(ARRAY, SHIFT [, BOUNDARY, DIM])}
4815 @item @emph{Arguments}:
4816 @multitable @columnfractions .15 .70
4817 @item @var{ARRAY} @tab May be any type, not scalar.
4818 @item @var{SHIFT} @tab The type shall be @code{INTEGER}.
4819 @item @var{BOUNDARY} @tab Same type as @var{ARRAY}.
4820 @item @var{DIM} @tab The type shall be @code{INTEGER}.
4823 @item @emph{Return value}:
4824 Returns an array of same type and rank as the @var{ARRAY} argument.
4826 @item @emph{Example}:
4828 program test_eoshift
4829 integer, dimension(3,3) :: a
4830 a = reshape( (/ 1, 2, 3, 4, 5, 6, 7, 8, 9 /), (/ 3, 3 /))
4831 print '(3i3)', a(1,:)
4832 print '(3i3)', a(2,:)
4833 print '(3i3)', a(3,:)
4834 a = EOSHIFT(a, SHIFT=(/1, 2, 1/), BOUNDARY=-5, DIM=2)
4836 print '(3i3)', a(1,:)
4837 print '(3i3)', a(2,:)
4838 print '(3i3)', a(3,:)
4839 end program test_eoshift
4846 @section @code{EPSILON} --- Epsilon function
4848 @cindex model representation, epsilon
4851 @item @emph{Description}:
4852 @code{EPSILON(X)} returns the smallest number @var{E} of the same kind
4853 as @var{X} such that @math{1 + E > 1}.
4855 @item @emph{Standard}:
4856 Fortran 95 and later
4861 @item @emph{Syntax}:
4862 @code{RESULT = EPSILON(X)}
4864 @item @emph{Arguments}:
4865 @multitable @columnfractions .15 .70
4866 @item @var{X} @tab The type shall be @code{REAL}.
4869 @item @emph{Return value}:
4870 The return value is of same type as the argument.
4872 @item @emph{Example}:
4874 program test_epsilon
4879 end program test_epsilon
4886 @section @code{ERF} --- Error function
4888 @cindex error function
4891 @item @emph{Description}:
4892 @code{ERF(X)} computes the error function of @var{X}.
4894 @item @emph{Standard}:
4895 Fortran 2008 and later
4900 @item @emph{Syntax}:
4901 @code{RESULT = ERF(X)}
4903 @item @emph{Arguments}:
4904 @multitable @columnfractions .15 .70
4905 @item @var{X} @tab The type shall be @code{REAL}.
4908 @item @emph{Return value}:
4909 The return value is of type @code{REAL}, of the same kind as
4910 @var{X} and lies in the range @math{-1 \leq erf (x) \leq 1 }.
4912 @item @emph{Example}:
4915 real(8) :: x = 0.17_8
4917 end program test_erf
4920 @item @emph{Specific names}:
4921 @multitable @columnfractions .20 .20 .20 .25
4922 @item Name @tab Argument @tab Return type @tab Standard
4923 @item @code{DERF(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU extension
4930 @section @code{ERFC} --- Error function
4932 @cindex error function, complementary
4935 @item @emph{Description}:
4936 @code{ERFC(X)} computes the complementary error function of @var{X}.
4938 @item @emph{Standard}:
4939 Fortran 2008 and later
4944 @item @emph{Syntax}:
4945 @code{RESULT = ERFC(X)}
4947 @item @emph{Arguments}:
4948 @multitable @columnfractions .15 .70
4949 @item @var{X} @tab The type shall be @code{REAL}.
4952 @item @emph{Return value}:
4953 The return value is of type @code{REAL} and of the same kind as @var{X}.
4954 It lies in the range @math{ 0 \leq erfc (x) \leq 2 }.
4956 @item @emph{Example}:
4959 real(8) :: x = 0.17_8
4961 end program test_erfc
4964 @item @emph{Specific names}:
4965 @multitable @columnfractions .20 .20 .20 .25
4966 @item Name @tab Argument @tab Return type @tab Standard
4967 @item @code{DERFC(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU extension
4974 @section @code{ERFC_SCALED} --- Error function
4975 @fnindex ERFC_SCALED
4976 @cindex error function, complementary, exponentially-scaled
4979 @item @emph{Description}:
4980 @code{ERFC_SCALED(X)} computes the exponentially-scaled complementary
4981 error function of @var{X}.
4983 @item @emph{Standard}:
4984 Fortran 2008 and later
4989 @item @emph{Syntax}:
4990 @code{RESULT = ERFC_SCALED(X)}
4992 @item @emph{Arguments}:
4993 @multitable @columnfractions .15 .70
4994 @item @var{X} @tab The type shall be @code{REAL}.
4997 @item @emph{Return value}:
4998 The return value is of type @code{REAL} and of the same kind as @var{X}.
5000 @item @emph{Example}:
5002 program test_erfc_scaled
5003 real(8) :: x = 0.17_8
5005 end program test_erfc_scaled
5012 @section @code{ETIME} --- Execution time subroutine (or function)
5014 @cindex time, elapsed
5017 @item @emph{Description}:
5018 @code{ETIME(VALUES, TIME)} returns the number of seconds of runtime
5019 since the start of the process's execution in @var{TIME}. @var{VALUES}
5020 returns the user and system components of this time in @code{VALUES(1)} and
5021 @code{VALUES(2)} respectively. @var{TIME} is equal to @code{VALUES(1) + VALUES(2)}.
5023 On some systems, the underlying timings are represented using types with
5024 sufficiently small limits that overflows (wrap around) are possible, such as
5025 32-bit types. Therefore, the values returned by this intrinsic might be, or
5026 become, negative, or numerically less than previous values, during a single
5027 run of the compiled program.
5029 This intrinsic is provided in both subroutine and function forms; however,
5030 only one form can be used in any given program unit.
5032 @var{VALUES} and @var{TIME} are @code{INTENT(OUT)} and provide the following:
5034 @multitable @columnfractions .15 .30 .60
5035 @item @tab @code{VALUES(1)}: @tab User time in seconds.
5036 @item @tab @code{VALUES(2)}: @tab System time in seconds.
5037 @item @tab @code{TIME}: @tab Run time since start in seconds.
5040 @item @emph{Standard}:
5044 Subroutine, function
5046 @item @emph{Syntax}:
5047 @multitable @columnfractions .80
5048 @item @code{CALL ETIME(VALUES, TIME)}.
5049 @item @code{TIME = ETIME(VALUES)}, (not recommended).
5052 @item @emph{Arguments}:
5053 @multitable @columnfractions .15 .70
5054 @item @var{VALUES}@tab The type shall be @code{REAL(4), DIMENSION(2)}.
5055 @item @var{TIME}@tab The type shall be @code{REAL(4)}.
5058 @item @emph{Return value}:
5059 Elapsed time in seconds since the start of program execution.
5061 @item @emph{Example}:
5065 real, dimension(2) :: tarray
5067 call ETIME(tarray, result)
5071 do i=1,100000000 ! Just a delay
5074 call ETIME(tarray, result)
5078 end program test_etime
5081 @item @emph{See also}:
5089 @section @code{EVENT_QUERY} --- Query whether a coarray event has occurred
5090 @fnindex EVENT_QUERY
5091 @cindex Events, EVENT_QUERY
5094 @item @emph{Description}:
5095 @code{EVENT_QUERY} assignes the number of events to @var{COUNT} which have been
5096 posted to the @var{EVENT} variable and not yet been removed by calling
5097 @code{EVENT WAIT}. When @var{STAT} is present and the invokation was successful,
5098 it is assigned the value 0. If it is present and the invokation has failed,
5099 it is assigned a positive value and @var{COUNT} is assigned the value @math{-1}.
5101 @item @emph{Standard}:
5107 @item @emph{Syntax}:
5108 @code{CALL EVENT_QUERY (EVENT, COUNT [, STAT])}
5110 @item @emph{Arguments}:
5111 @multitable @columnfractions .15 .70
5112 @item @var{EVENT} @tab (intent(IN)) Scalar of type @code{EVENT_TYPE},
5113 defined in @code{ISO_FORTRAN_ENV}; shall not be coindexed.
5114 @item @var{COUNT} @tab (intent(out))Scalar integer with at least the
5115 precision of default integer.
5116 @item @var{STAT} @tab (optional) Scalar default-kind integer variable.
5119 @item @emph{Example}:
5124 type(event_type) :: event_value_has_been_set[*]
5126 if (this_image() == 1) then
5127 call event_query (event_value_has_been_set, cnt)
5128 if (cnt > 0) write(*,*) "Value has been set"
5129 elseif (this_image() == 2) then
5130 event post (event_value_has_been_set[1])
5139 @node EXECUTE_COMMAND_LINE
5140 @section @code{EXECUTE_COMMAND_LINE} --- Execute a shell command
5141 @fnindex EXECUTE_COMMAND_LINE
5142 @cindex system, system call
5143 @cindex command line
5146 @item @emph{Description}:
5147 @code{EXECUTE_COMMAND_LINE} runs a shell command, synchronously or
5150 The @code{COMMAND} argument is passed to the shell and executed, using
5151 the C library's @code{system} call. (The shell is @code{sh} on Unix
5152 systems, and @code{cmd.exe} on Windows.) If @code{WAIT} is present
5153 and has the value false, the execution of the command is asynchronous
5154 if the system supports it; otherwise, the command is executed
5157 The three last arguments allow the user to get status information. After
5158 synchronous execution, @code{EXITSTAT} contains the integer exit code of
5159 the command, as returned by @code{system}. @code{CMDSTAT} is set to zero
5160 if the command line was executed (whatever its exit status was).
5161 @code{CMDMSG} is assigned an error message if an error has occurred.
5163 Note that the @code{system} function need not be thread-safe. It is
5164 the responsibility of the user to ensure that @code{system} is not
5165 called concurrently.
5167 @item @emph{Standard}:
5168 Fortran 2008 and later
5173 @item @emph{Syntax}:
5174 @code{CALL EXECUTE_COMMAND_LINE(COMMAND [, WAIT, EXITSTAT, CMDSTAT, CMDMSG ])}
5176 @item @emph{Arguments}:
5177 @multitable @columnfractions .15 .70
5178 @item @var{COMMAND} @tab Shall be a default @code{CHARACTER} scalar.
5179 @item @var{WAIT} @tab (Optional) Shall be a default @code{LOGICAL} scalar.
5180 @item @var{EXITSTAT} @tab (Optional) Shall be an @code{INTEGER} of the
5182 @item @var{CMDSTAT} @tab (Optional) Shall be an @code{INTEGER} of the
5184 @item @var{CMDMSG} @tab (Optional) Shall be an @code{CHARACTER} scalar of the
5188 @item @emph{Example}:
5193 call execute_command_line ("external_prog.exe", exitstat=i)
5194 print *, "Exit status of external_prog.exe was ", i
5196 call execute_command_line ("reindex_files.exe", wait=.false.)
5197 print *, "Now reindexing files in the background"
5199 end program test_exec
5205 Because this intrinsic is implemented in terms of the @code{system}
5206 function call, its behavior with respect to signaling is processor
5207 dependent. In particular, on POSIX-compliant systems, the SIGINT and
5208 SIGQUIT signals will be ignored, and the SIGCHLD will be blocked. As
5209 such, if the parent process is terminated, the child process might not be
5210 terminated alongside.
5213 @item @emph{See also}:
5220 @section @code{EXIT} --- Exit the program with status.
5222 @cindex program termination
5223 @cindex terminate program
5226 @item @emph{Description}:
5227 @code{EXIT} causes immediate termination of the program with status. If status
5228 is omitted it returns the canonical @emph{success} for the system. All Fortran
5229 I/O units are closed.
5231 @item @emph{Standard}:
5237 @item @emph{Syntax}:
5238 @code{CALL EXIT([STATUS])}
5240 @item @emph{Arguments}:
5241 @multitable @columnfractions .15 .70
5242 @item @var{STATUS} @tab Shall be an @code{INTEGER} of the default kind.
5245 @item @emph{Return value}:
5246 @code{STATUS} is passed to the parent process on exit.
5248 @item @emph{Example}:
5251 integer :: STATUS = 0
5252 print *, 'This program is going to exit.'
5254 end program test_exit
5257 @item @emph{See also}:
5258 @ref{ABORT}, @ref{KILL}
5264 @section @code{EXP} --- Exponential function
5270 @cindex exponential function
5271 @cindex logarithm function, inverse
5274 @item @emph{Description}:
5275 @code{EXP(X)} computes the base @math{e} exponential of @var{X}.
5277 @item @emph{Standard}:
5278 Fortran 77 and later, has overloads that are GNU extensions
5283 @item @emph{Syntax}:
5284 @code{RESULT = EXP(X)}
5286 @item @emph{Arguments}:
5287 @multitable @columnfractions .15 .70
5288 @item @var{X} @tab The type shall be @code{REAL} or
5292 @item @emph{Return value}:
5293 The return value has same type and kind as @var{X}.
5295 @item @emph{Example}:
5300 end program test_exp
5303 @item @emph{Specific names}:
5304 @multitable @columnfractions .20 .20 .20 .25
5305 @item Name @tab Argument @tab Return type @tab Standard
5306 @item @code{EXP(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab Fortran 77 and later
5307 @item @code{DEXP(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab Fortran 77 and later
5308 @item @code{CEXP(X)} @tab @code{COMPLEX(4) X} @tab @code{COMPLEX(4)} @tab Fortran 77 and later
5309 @item @code{ZEXP(X)} @tab @code{COMPLEX(8) X} @tab @code{COMPLEX(8)} @tab GNU extension
5310 @item @code{CDEXP(X)} @tab @code{COMPLEX(8) X} @tab @code{COMPLEX(8)} @tab GNU extension
5317 @section @code{EXPONENT} --- Exponent function
5319 @cindex real number, exponent
5320 @cindex floating point, exponent
5323 @item @emph{Description}:
5324 @code{EXPONENT(X)} returns the value of the exponent part of @var{X}. If @var{X}
5325 is zero the value returned is zero.
5327 @item @emph{Standard}:
5328 Fortran 95 and later
5333 @item @emph{Syntax}:
5334 @code{RESULT = EXPONENT(X)}
5336 @item @emph{Arguments}:
5337 @multitable @columnfractions .15 .70
5338 @item @var{X} @tab The type shall be @code{REAL}.
5341 @item @emph{Return value}:
5342 The return value is of type default @code{INTEGER}.
5344 @item @emph{Example}:
5346 program test_exponent
5351 print *, exponent(0.0)
5352 end program test_exponent
5358 @node EXTENDS_TYPE_OF
5359 @section @code{EXTENDS_TYPE_OF} --- Query dynamic type for extension
5360 @fnindex EXTENDS_TYPE_OF
5363 @item @emph{Description}:
5364 Query dynamic type for extension.
5366 @item @emph{Standard}:
5367 Fortran 2003 and later
5372 @item @emph{Syntax}:
5373 @code{RESULT = EXTENDS_TYPE_OF(A, MOLD)}
5375 @item @emph{Arguments}:
5376 @multitable @columnfractions .15 .70
5377 @item @var{A} @tab Shall be an object of extensible declared type or
5378 unlimited polymorphic.
5379 @item @var{MOLD} @tab Shall be an object of extensible declared type or
5380 unlimited polymorphic.
5383 @item @emph{Return value}:
5384 The return value is a scalar of type default logical. It is true if and only if
5385 the dynamic type of A is an extension type of the dynamic type of MOLD.
5388 @item @emph{See also}:
5395 @section @code{FDATE} --- Get the current time as a string
5397 @cindex time, current
5398 @cindex current time
5399 @cindex date, current
5400 @cindex current date
5403 @item @emph{Description}:
5404 @code{FDATE(DATE)} returns the current date (using the same format as
5405 @code{CTIME}) in @var{DATE}. It is equivalent to @code{CALL CTIME(DATE,
5408 This intrinsic is provided in both subroutine and function forms; however,
5409 only one form can be used in any given program unit.
5411 @item @emph{Standard}:
5415 Subroutine, function
5417 @item @emph{Syntax}:
5418 @multitable @columnfractions .80
5419 @item @code{CALL FDATE(DATE)}.
5420 @item @code{DATE = FDATE()}.
5423 @item @emph{Arguments}:
5424 @multitable @columnfractions .15 .70
5425 @item @var{DATE}@tab The type shall be of type @code{CHARACTER} of the
5426 default kind. It is an @code{INTENT(OUT)} argument. If the length of
5427 this variable is too short for the date and time string to fit
5428 completely, it will be blank on procedure return.
5431 @item @emph{Return value}:
5432 The current date and time as a string.
5434 @item @emph{Example}:
5438 character(len=30) :: date
5440 print *, 'Program started on ', date
5441 do i = 1, 100000000 ! Just a delay
5445 print *, 'Program ended on ', date
5446 end program test_fdate
5449 @item @emph{See also}:
5450 @ref{DATE_AND_TIME}, @ref{CTIME}
5455 @section @code{FGET} --- Read a single character in stream mode from stdin
5457 @cindex read character, stream mode
5458 @cindex stream mode, read character
5459 @cindex file operation, read character
5462 @item @emph{Description}:
5463 Read a single character in stream mode from stdin by bypassing normal
5464 formatted output. Stream I/O should not be mixed with normal record-oriented
5465 (formatted or unformatted) I/O on the same unit; the results are unpredictable.
5467 This intrinsic is provided in both subroutine and function forms; however,
5468 only one form can be used in any given program unit.
5470 Note that the @code{FGET} intrinsic is provided for backwards compatibility with
5471 @command{g77}. GNU Fortran provides the Fortran 2003 Stream facility.
5472 Programmers should consider the use of new stream IO feature in new code
5473 for future portability. See also @ref{Fortran 2003 status}.
5475 @item @emph{Standard}:
5479 Subroutine, function
5481 @item @emph{Syntax}:
5482 @multitable @columnfractions .80
5483 @item @code{CALL FGET(C [, STATUS])}
5484 @item @code{STATUS = FGET(C)}
5487 @item @emph{Arguments}:
5488 @multitable @columnfractions .15 .70
5489 @item @var{C} @tab The type shall be @code{CHARACTER} and of default
5491 @item @var{STATUS} @tab (Optional) status flag of type @code{INTEGER}.
5492 Returns 0 on success, -1 on end-of-file, and a system specific positive
5493 error code otherwise.
5496 @item @emph{Example}:
5499 INTEGER, PARAMETER :: strlen = 100
5500 INTEGER :: status, i = 1
5501 CHARACTER(len=strlen) :: str = ""
5503 WRITE (*,*) 'Enter text:'
5505 CALL fget(str(i:i), status)
5506 if (status /= 0 .OR. i > strlen) exit
5509 WRITE (*,*) TRIM(str)
5513 @item @emph{See also}:
5514 @ref{FGETC}, @ref{FPUT}, @ref{FPUTC}
5520 @section @code{FGETC} --- Read a single character in stream mode
5522 @cindex read character, stream mode
5523 @cindex stream mode, read character
5524 @cindex file operation, read character
5527 @item @emph{Description}:
5528 Read a single character in stream mode by bypassing normal formatted output.
5529 Stream I/O should not be mixed with normal record-oriented (formatted or
5530 unformatted) I/O on the same unit; the results are unpredictable.
5532 This intrinsic is provided in both subroutine and function forms; however,
5533 only one form can be used in any given program unit.
5535 Note that the @code{FGET} intrinsic is provided for backwards compatibility
5536 with @command{g77}. GNU Fortran provides the Fortran 2003 Stream facility.
5537 Programmers should consider the use of new stream IO feature in new code
5538 for future portability. See also @ref{Fortran 2003 status}.
5540 @item @emph{Standard}:
5544 Subroutine, function
5546 @item @emph{Syntax}:
5547 @multitable @columnfractions .80
5548 @item @code{CALL FGETC(UNIT, C [, STATUS])}
5549 @item @code{STATUS = FGETC(UNIT, C)}
5552 @item @emph{Arguments}:
5553 @multitable @columnfractions .15 .70
5554 @item @var{UNIT} @tab The type shall be @code{INTEGER}.
5555 @item @var{C} @tab The type shall be @code{CHARACTER} and of default
5557 @item @var{STATUS} @tab (Optional) status flag of type @code{INTEGER}.
5558 Returns 0 on success, -1 on end-of-file and a system specific positive
5559 error code otherwise.
5562 @item @emph{Example}:
5565 INTEGER :: fd = 42, status
5568 OPEN(UNIT=fd, FILE="/etc/passwd", ACTION="READ", STATUS = "OLD")
5570 CALL fgetc(fd, c, status)
5571 IF (status /= 0) EXIT
5578 @item @emph{See also}:
5579 @ref{FGET}, @ref{FPUT}, @ref{FPUTC}
5585 @section @code{FLOOR} --- Integer floor function
5588 @cindex rounding, floor
5591 @item @emph{Description}:
5592 @code{FLOOR(A)} returns the greatest integer less than or equal to @var{X}.
5594 @item @emph{Standard}:
5595 Fortran 95 and later
5600 @item @emph{Syntax}:
5601 @code{RESULT = FLOOR(A [, KIND])}
5603 @item @emph{Arguments}:
5604 @multitable @columnfractions .15 .70
5605 @item @var{A} @tab The type shall be @code{REAL}.
5606 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
5607 expression indicating the kind parameter of the result.
5610 @item @emph{Return value}:
5611 The return value is of type @code{INTEGER(KIND)} if @var{KIND} is present
5612 and of default-kind @code{INTEGER} otherwise.
5614 @item @emph{Example}:
5619 print *, floor(x) ! returns 63
5620 print *, floor(y) ! returns -64
5621 end program test_floor
5624 @item @emph{See also}:
5625 @ref{CEILING}, @ref{NINT}
5632 @section @code{FLUSH} --- Flush I/O unit(s)
5634 @cindex file operation, flush
5637 @item @emph{Description}:
5638 Flushes Fortran unit(s) currently open for output. Without the optional
5639 argument, all units are flushed, otherwise just the unit specified.
5641 @item @emph{Standard}:
5647 @item @emph{Syntax}:
5648 @code{CALL FLUSH(UNIT)}
5650 @item @emph{Arguments}:
5651 @multitable @columnfractions .15 .70
5652 @item @var{UNIT} @tab (Optional) The type shall be @code{INTEGER}.
5656 Beginning with the Fortran 2003 standard, there is a @code{FLUSH}
5657 statement that should be preferred over the @code{FLUSH} intrinsic.
5659 The @code{FLUSH} intrinsic and the Fortran 2003 @code{FLUSH} statement
5660 have identical effect: they flush the runtime library's I/O buffer so
5661 that the data becomes visible to other processes. This does not guarantee
5662 that the data is committed to disk.
5664 On POSIX systems, you can request that all data is transferred to the
5665 storage device by calling the @code{fsync} function, with the POSIX file
5666 descriptor of the I/O unit as argument (retrieved with GNU intrinsic
5667 @code{FNUM}). The following example shows how:
5670 ! Declare the interface for POSIX fsync function
5672 function fsync (fd) bind(c,name="fsync")
5673 use iso_c_binding, only: c_int
5674 integer(c_int), value :: fd
5675 integer(c_int) :: fsync
5679 ! Variable declaration
5683 open (10,file="foo")
5686 ! Perform I/O on unit 10
5691 ret = fsync(fnum(10))
5693 ! Handle possible error
5694 if (ret /= 0) stop "Error calling FSYNC"
5702 @section @code{FNUM} --- File number function
5704 @cindex file operation, file number
5707 @item @emph{Description}:
5708 @code{FNUM(UNIT)} returns the POSIX file descriptor number corresponding to the
5709 open Fortran I/O unit @code{UNIT}.
5711 @item @emph{Standard}:
5717 @item @emph{Syntax}:
5718 @code{RESULT = FNUM(UNIT)}
5720 @item @emph{Arguments}:
5721 @multitable @columnfractions .15 .70
5722 @item @var{UNIT} @tab The type shall be @code{INTEGER}.
5725 @item @emph{Return value}:
5726 The return value is of type @code{INTEGER}
5728 @item @emph{Example}:
5732 open (unit=10, status = "scratch")
5736 end program test_fnum
5743 @section @code{FPUT} --- Write a single character in stream mode to stdout
5745 @cindex write character, stream mode
5746 @cindex stream mode, write character
5747 @cindex file operation, write character
5750 @item @emph{Description}:
5751 Write a single character in stream mode to stdout by bypassing normal
5752 formatted output. Stream I/O should not be mixed with normal record-oriented
5753 (formatted or unformatted) I/O on the same unit; the results are unpredictable.
5755 This intrinsic is provided in both subroutine and function forms; however,
5756 only one form can be used in any given program unit.
5758 Note that the @code{FGET} intrinsic is provided for backwards compatibility with
5759 @command{g77}. GNU Fortran provides the Fortran 2003 Stream facility.
5760 Programmers should consider the use of new stream IO feature in new code
5761 for future portability. See also @ref{Fortran 2003 status}.
5763 @item @emph{Standard}:
5767 Subroutine, function
5769 @item @emph{Syntax}:
5770 @multitable @columnfractions .80
5771 @item @code{CALL FPUT(C [, STATUS])}
5772 @item @code{STATUS = FPUT(C)}
5775 @item @emph{Arguments}:
5776 @multitable @columnfractions .15 .70
5777 @item @var{C} @tab The type shall be @code{CHARACTER} and of default
5779 @item @var{STATUS} @tab (Optional) status flag of type @code{INTEGER}.
5780 Returns 0 on success, -1 on end-of-file and a system specific positive
5781 error code otherwise.
5784 @item @emph{Example}:
5787 CHARACTER(len=10) :: str = "gfortran"
5789 DO i = 1, len_trim(str)
5795 @item @emph{See also}:
5796 @ref{FPUTC}, @ref{FGET}, @ref{FGETC}
5802 @section @code{FPUTC} --- Write a single character in stream mode
5804 @cindex write character, stream mode
5805 @cindex stream mode, write character
5806 @cindex file operation, write character
5809 @item @emph{Description}:
5810 Write a single character in stream mode by bypassing normal formatted
5811 output. Stream I/O should not be mixed with normal record-oriented
5812 (formatted or unformatted) I/O on the same unit; the results are unpredictable.
5814 This intrinsic is provided in both subroutine and function forms; however,
5815 only one form can be used in any given program unit.
5817 Note that the @code{FGET} intrinsic is provided for backwards compatibility with
5818 @command{g77}. GNU Fortran provides the Fortran 2003 Stream facility.
5819 Programmers should consider the use of new stream IO feature in new code
5820 for future portability. See also @ref{Fortran 2003 status}.
5822 @item @emph{Standard}:
5826 Subroutine, function
5828 @item @emph{Syntax}:
5829 @multitable @columnfractions .80
5830 @item @code{CALL FPUTC(UNIT, C [, STATUS])}
5831 @item @code{STATUS = FPUTC(UNIT, C)}
5834 @item @emph{Arguments}:
5835 @multitable @columnfractions .15 .70
5836 @item @var{UNIT} @tab The type shall be @code{INTEGER}.
5837 @item @var{C} @tab The type shall be @code{CHARACTER} and of default
5839 @item @var{STATUS} @tab (Optional) status flag of type @code{INTEGER}.
5840 Returns 0 on success, -1 on end-of-file and a system specific positive
5841 error code otherwise.
5844 @item @emph{Example}:
5847 CHARACTER(len=10) :: str = "gfortran"
5848 INTEGER :: fd = 42, i
5850 OPEN(UNIT = fd, FILE = "out", ACTION = "WRITE", STATUS="NEW")
5851 DO i = 1, len_trim(str)
5852 CALL fputc(fd, str(i:i))
5858 @item @emph{See also}:
5859 @ref{FPUT}, @ref{FGET}, @ref{FGETC}
5865 @section @code{FRACTION} --- Fractional part of the model representation
5867 @cindex real number, fraction
5868 @cindex floating point, fraction
5871 @item @emph{Description}:
5872 @code{FRACTION(X)} returns the fractional part of the model
5873 representation of @code{X}.
5875 @item @emph{Standard}:
5876 Fortran 95 and later
5881 @item @emph{Syntax}:
5882 @code{Y = FRACTION(X)}
5884 @item @emph{Arguments}:
5885 @multitable @columnfractions .15 .70
5886 @item @var{X} @tab The type of the argument shall be a @code{REAL}.
5889 @item @emph{Return value}:
5890 The return value is of the same type and kind as the argument.
5891 The fractional part of the model representation of @code{X} is returned;
5892 it is @code{X * RADIX(X)**(-EXPONENT(X))}.
5894 @item @emph{Example}:
5896 program test_fraction
5899 print *, fraction(x), x * radix(x)**(-exponent(x))
5900 end program test_fraction
5908 @section @code{FREE} --- Frees memory
5910 @cindex pointer, cray
5913 @item @emph{Description}:
5914 Frees memory previously allocated by @code{MALLOC}. The @code{FREE}
5915 intrinsic is an extension intended to be used with Cray pointers, and is
5916 provided in GNU Fortran to allow user to compile legacy code. For
5917 new code using Fortran 95 pointers, the memory de-allocation intrinsic is
5920 @item @emph{Standard}:
5926 @item @emph{Syntax}:
5927 @code{CALL FREE(PTR)}
5929 @item @emph{Arguments}:
5930 @multitable @columnfractions .15 .70
5931 @item @var{PTR} @tab The type shall be @code{INTEGER}. It represents the
5932 location of the memory that should be de-allocated.
5935 @item @emph{Return value}:
5938 @item @emph{Example}:
5939 See @code{MALLOC} for an example.
5941 @item @emph{See also}:
5948 @section @code{FSEEK} --- Low level file positioning subroutine
5950 @cindex file operation, seek
5951 @cindex file operation, position
5954 @item @emph{Description}:
5955 Moves @var{UNIT} to the specified @var{OFFSET}. If @var{WHENCE}
5956 is set to 0, the @var{OFFSET} is taken as an absolute value @code{SEEK_SET},
5957 if set to 1, @var{OFFSET} is taken to be relative to the current position
5958 @code{SEEK_CUR}, and if set to 2 relative to the end of the file @code{SEEK_END}.
5959 On error, @var{STATUS} is set to a nonzero value. If @var{STATUS} the seek
5962 This intrinsic routine is not fully backwards compatible with @command{g77}.
5963 In @command{g77}, the @code{FSEEK} takes a statement label instead of a
5964 @var{STATUS} variable. If FSEEK is used in old code, change
5966 CALL FSEEK(UNIT, OFFSET, WHENCE, *label)
5971 CALL FSEEK(UNIT, OFFSET, WHENCE, status)
5972 IF (status /= 0) GOTO label
5975 Please note that GNU Fortran provides the Fortran 2003 Stream facility.
5976 Programmers should consider the use of new stream IO feature in new code
5977 for future portability. See also @ref{Fortran 2003 status}.
5979 @item @emph{Standard}:
5985 @item @emph{Syntax}:
5986 @code{CALL FSEEK(UNIT, OFFSET, WHENCE[, STATUS])}
5988 @item @emph{Arguments}:
5989 @multitable @columnfractions .15 .70
5990 @item @var{UNIT} @tab Shall be a scalar of type @code{INTEGER}.
5991 @item @var{OFFSET} @tab Shall be a scalar of type @code{INTEGER}.
5992 @item @var{WHENCE} @tab Shall be a scalar of type @code{INTEGER}.
5993 Its value shall be either 0, 1 or 2.
5994 @item @var{STATUS} @tab (Optional) shall be a scalar of type
5998 @item @emph{Example}:
6001 INTEGER, PARAMETER :: SEEK_SET = 0, SEEK_CUR = 1, SEEK_END = 2
6002 INTEGER :: fd, offset, ierr
6008 OPEN(UNIT=fd, FILE="fseek.test")
6009 CALL FSEEK(fd, offset, SEEK_SET, ierr) ! move to OFFSET
6010 print *, FTELL(fd), ierr
6012 CALL FSEEK(fd, 0, SEEK_END, ierr) ! move to end
6013 print *, FTELL(fd), ierr
6015 CALL FSEEK(fd, 0, SEEK_SET, ierr) ! move to beginning
6016 print *, FTELL(fd), ierr
6022 @item @emph{See also}:
6029 @section @code{FSTAT} --- Get file status
6031 @cindex file system, file status
6034 @item @emph{Description}:
6035 @code{FSTAT} is identical to @ref{STAT}, except that information about an
6036 already opened file is obtained.
6038 The elements in @code{VALUES} are the same as described by @ref{STAT}.
6040 This intrinsic is provided in both subroutine and function forms; however,
6041 only one form can be used in any given program unit.
6043 @item @emph{Standard}:
6047 Subroutine, function
6049 @item @emph{Syntax}:
6050 @multitable @columnfractions .80
6051 @item @code{CALL FSTAT(UNIT, VALUES [, STATUS])}
6052 @item @code{STATUS = FSTAT(UNIT, VALUES)}
6055 @item @emph{Arguments}:
6056 @multitable @columnfractions .15 .70
6057 @item @var{UNIT} @tab An open I/O unit number of type @code{INTEGER}.
6058 @item @var{VALUES} @tab The type shall be @code{INTEGER(4), DIMENSION(13)}.
6059 @item @var{STATUS} @tab (Optional) status flag of type @code{INTEGER(4)}. Returns 0
6060 on success and a system specific error code otherwise.
6063 @item @emph{Example}:
6064 See @ref{STAT} for an example.
6066 @item @emph{See also}:
6067 To stat a link: @ref{LSTAT}, to stat a file: @ref{STAT}
6073 @section @code{FTELL} --- Current stream position
6075 @cindex file operation, position
6078 @item @emph{Description}:
6079 Retrieves the current position within an open file.
6081 This intrinsic is provided in both subroutine and function forms; however,
6082 only one form can be used in any given program unit.
6084 @item @emph{Standard}:
6088 Subroutine, function
6090 @item @emph{Syntax}:
6091 @multitable @columnfractions .80
6092 @item @code{CALL FTELL(UNIT, OFFSET)}
6093 @item @code{OFFSET = FTELL(UNIT)}
6096 @item @emph{Arguments}:
6097 @multitable @columnfractions .15 .70
6098 @item @var{OFFSET} @tab Shall of type @code{INTEGER}.
6099 @item @var{UNIT} @tab Shall of type @code{INTEGER}.
6102 @item @emph{Return value}:
6103 In either syntax, @var{OFFSET} is set to the current offset of unit
6104 number @var{UNIT}, or to @math{-1} if the unit is not currently open.
6106 @item @emph{Example}:
6110 OPEN(10, FILE="temp.dat")
6116 @item @emph{See also}:
6123 @section @code{GAMMA} --- Gamma function
6126 @cindex Gamma function
6127 @cindex Factorial function
6130 @item @emph{Description}:
6131 @code{GAMMA(X)} computes Gamma (@math{\Gamma}) of @var{X}. For positive,
6132 integer values of @var{X} the Gamma function simplifies to the factorial
6133 function @math{\Gamma(x)=(x-1)!}.
6137 \Gamma(x) = \int_0^\infty t^{x-1}{\rm e}^{-t}\,{\rm d}t
6141 @item @emph{Standard}:
6142 Fortran 2008 and later
6147 @item @emph{Syntax}:
6150 @item @emph{Arguments}:
6151 @multitable @columnfractions .15 .70
6152 @item @var{X} @tab Shall be of type @code{REAL} and neither zero
6153 nor a negative integer.
6156 @item @emph{Return value}:
6157 The return value is of type @code{REAL} of the same kind as @var{X}.
6159 @item @emph{Example}:
6163 x = gamma(x) ! returns 1.0
6164 end program test_gamma
6167 @item @emph{Specific names}:
6168 @multitable @columnfractions .20 .20 .20 .25
6169 @item Name @tab Argument @tab Return type @tab Standard
6170 @item @code{GAMMA(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab GNU Extension
6171 @item @code{DGAMMA(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU Extension
6174 @item @emph{See also}:
6175 Logarithm of the Gamma function: @ref{LOG_GAMMA}
6182 @section @code{GERROR} --- Get last system error message
6184 @cindex system, error handling
6187 @item @emph{Description}:
6188 Returns the system error message corresponding to the last system error.
6189 This resembles the functionality of @code{strerror(3)} in C.
6191 @item @emph{Standard}:
6197 @item @emph{Syntax}:
6198 @code{CALL GERROR(RESULT)}
6200 @item @emph{Arguments}:
6201 @multitable @columnfractions .15 .70
6202 @item @var{RESULT} @tab Shall of type @code{CHARACTER} and of default
6205 @item @emph{Example}:
6208 CHARACTER(len=100) :: msg
6214 @item @emph{See also}:
6215 @ref{IERRNO}, @ref{PERROR}
6221 @section @code{GETARG} --- Get command line arguments
6223 @cindex command-line arguments
6224 @cindex arguments, to program
6227 @item @emph{Description}:
6228 Retrieve the @var{POS}-th argument that was passed on the
6229 command line when the containing program was invoked.
6231 This intrinsic routine is provided for backwards compatibility with
6232 GNU Fortran 77. In new code, programmers should consider the use of
6233 the @ref{GET_COMMAND_ARGUMENT} intrinsic defined by the Fortran 2003
6236 @item @emph{Standard}:
6242 @item @emph{Syntax}:
6243 @code{CALL GETARG(POS, VALUE)}
6245 @item @emph{Arguments}:
6246 @multitable @columnfractions .15 .70
6247 @item @var{POS} @tab Shall be of type @code{INTEGER} and not wider than
6248 the default integer kind; @math{@var{POS} \geq 0}
6249 @item @var{VALUE} @tab Shall be of type @code{CHARACTER} and of default
6251 @item @var{VALUE} @tab Shall be of type @code{CHARACTER}.
6254 @item @emph{Return value}:
6255 After @code{GETARG} returns, the @var{VALUE} argument holds the
6256 @var{POS}th command line argument. If @var{VALUE} can not hold the
6257 argument, it is truncated to fit the length of @var{VALUE}. If there are
6258 less than @var{POS} arguments specified at the command line, @var{VALUE}
6259 will be filled with blanks. If @math{@var{POS} = 0}, @var{VALUE} is set
6260 to the name of the program (on systems that support this feature).
6262 @item @emph{Example}:
6266 CHARACTER(len=32) :: arg
6275 @item @emph{See also}:
6276 GNU Fortran 77 compatibility function: @ref{IARGC}
6278 Fortran 2003 functions and subroutines: @ref{GET_COMMAND},
6279 @ref{GET_COMMAND_ARGUMENT}, @ref{COMMAND_ARGUMENT_COUNT}
6285 @section @code{GET_COMMAND} --- Get the entire command line
6286 @fnindex GET_COMMAND
6287 @cindex command-line arguments
6288 @cindex arguments, to program
6291 @item @emph{Description}:
6292 Retrieve the entire command line that was used to invoke the program.
6294 @item @emph{Standard}:
6295 Fortran 2003 and later
6300 @item @emph{Syntax}:
6301 @code{CALL GET_COMMAND([COMMAND, LENGTH, STATUS])}
6303 @item @emph{Arguments}:
6304 @multitable @columnfractions .15 .70
6305 @item @var{COMMAND} @tab (Optional) shall be of type @code{CHARACTER} and
6307 @item @var{LENGTH} @tab (Optional) Shall be of type @code{INTEGER} and of
6309 @item @var{STATUS} @tab (Optional) Shall be of type @code{INTEGER} and of
6313 @item @emph{Return value}:
6314 If @var{COMMAND} is present, stores the entire command line that was used
6315 to invoke the program in @var{COMMAND}. If @var{LENGTH} is present, it is
6316 assigned the length of the command line. If @var{STATUS} is present, it
6317 is assigned 0 upon success of the command, -1 if @var{COMMAND} is too
6318 short to store the command line, or a positive value in case of an error.
6320 @item @emph{Example}:
6322 PROGRAM test_get_command
6323 CHARACTER(len=255) :: cmd
6324 CALL get_command(cmd)
6325 WRITE (*,*) TRIM(cmd)
6329 @item @emph{See also}:
6330 @ref{GET_COMMAND_ARGUMENT}, @ref{COMMAND_ARGUMENT_COUNT}
6335 @node GET_COMMAND_ARGUMENT
6336 @section @code{GET_COMMAND_ARGUMENT} --- Get command line arguments
6337 @fnindex GET_COMMAND_ARGUMENT
6338 @cindex command-line arguments
6339 @cindex arguments, to program
6342 @item @emph{Description}:
6343 Retrieve the @var{NUMBER}-th argument that was passed on the
6344 command line when the containing program was invoked.
6346 @item @emph{Standard}:
6347 Fortran 2003 and later
6352 @item @emph{Syntax}:
6353 @code{CALL GET_COMMAND_ARGUMENT(NUMBER [, VALUE, LENGTH, STATUS])}
6355 @item @emph{Arguments}:
6356 @multitable @columnfractions .15 .70
6357 @item @var{NUMBER} @tab Shall be a scalar of type @code{INTEGER} and of
6358 default kind, @math{@var{NUMBER} \geq 0}
6359 @item @var{VALUE} @tab (Optional) Shall be a scalar of type @code{CHARACTER}
6360 and of default kind.
6361 @item @var{LENGTH} @tab (Optional) Shall be a scalar of type @code{INTEGER}
6362 and of default kind.
6363 @item @var{STATUS} @tab (Optional) Shall be a scalar of type @code{INTEGER}
6364 and of default kind.
6367 @item @emph{Return value}:
6368 After @code{GET_COMMAND_ARGUMENT} returns, the @var{VALUE} argument holds the
6369 @var{NUMBER}-th command line argument. If @var{VALUE} can not hold the argument, it is
6370 truncated to fit the length of @var{VALUE}. If there are less than @var{NUMBER}
6371 arguments specified at the command line, @var{VALUE} will be filled with blanks.
6372 If @math{@var{NUMBER} = 0}, @var{VALUE} is set to the name of the program (on
6373 systems that support this feature). The @var{LENGTH} argument contains the
6374 length of the @var{NUMBER}-th command line argument. If the argument retrieval
6375 fails, @var{STATUS} is a positive number; if @var{VALUE} contains a truncated
6376 command line argument, @var{STATUS} is -1; and otherwise the @var{STATUS} is
6379 @item @emph{Example}:
6381 PROGRAM test_get_command_argument
6383 CHARACTER(len=32) :: arg
6387 CALL get_command_argument(i, arg)
6388 IF (LEN_TRIM(arg) == 0) EXIT
6390 WRITE (*,*) TRIM(arg)
6396 @item @emph{See also}:
6397 @ref{GET_COMMAND}, @ref{COMMAND_ARGUMENT_COUNT}
6403 @section @code{GETCWD} --- Get current working directory
6405 @cindex system, working directory
6408 @item @emph{Description}:
6409 Get current working directory.
6411 This intrinsic is provided in both subroutine and function forms; however,
6412 only one form can be used in any given program unit.
6414 @item @emph{Standard}:
6418 Subroutine, function
6420 @item @emph{Syntax}:
6421 @multitable @columnfractions .80
6422 @item @code{CALL GETCWD(C [, STATUS])}
6423 @item @code{STATUS = GETCWD(C)}
6426 @item @emph{Arguments}:
6427 @multitable @columnfractions .15 .70
6428 @item @var{C} @tab The type shall be @code{CHARACTER} and of default kind.
6429 @item @var{STATUS} @tab (Optional) status flag. Returns 0 on success,
6430 a system specific and nonzero error code otherwise.
6433 @item @emph{Example}:
6436 CHARACTER(len=255) :: cwd
6438 WRITE(*,*) TRIM(cwd)
6442 @item @emph{See also}:
6449 @section @code{GETENV} --- Get an environmental variable
6451 @cindex environment variable
6454 @item @emph{Description}:
6455 Get the @var{VALUE} of the environmental variable @var{NAME}.
6457 This intrinsic routine is provided for backwards compatibility with
6458 GNU Fortran 77. In new code, programmers should consider the use of
6459 the @ref{GET_ENVIRONMENT_VARIABLE} intrinsic defined by the Fortran
6462 Note that @code{GETENV} need not be thread-safe. It is the
6463 responsibility of the user to ensure that the environment is not being
6464 updated concurrently with a call to the @code{GETENV} intrinsic.
6466 @item @emph{Standard}:
6472 @item @emph{Syntax}:
6473 @code{CALL GETENV(NAME, VALUE)}
6475 @item @emph{Arguments}:
6476 @multitable @columnfractions .15 .70
6477 @item @var{NAME} @tab Shall be of type @code{CHARACTER} and of default kind.
6478 @item @var{VALUE} @tab Shall be of type @code{CHARACTER} and of default kind.
6481 @item @emph{Return value}:
6482 Stores the value of @var{NAME} in @var{VALUE}. If @var{VALUE} is
6483 not large enough to hold the data, it is truncated. If @var{NAME}
6484 is not set, @var{VALUE} will be filled with blanks.
6486 @item @emph{Example}:
6489 CHARACTER(len=255) :: homedir
6490 CALL getenv("HOME", homedir)
6491 WRITE (*,*) TRIM(homedir)
6495 @item @emph{See also}:
6496 @ref{GET_ENVIRONMENT_VARIABLE}
6501 @node GET_ENVIRONMENT_VARIABLE
6502 @section @code{GET_ENVIRONMENT_VARIABLE} --- Get an environmental variable
6503 @fnindex GET_ENVIRONMENT_VARIABLE
6504 @cindex environment variable
6507 @item @emph{Description}:
6508 Get the @var{VALUE} of the environmental variable @var{NAME}.
6510 Note that @code{GET_ENVIRONMENT_VARIABLE} need not be thread-safe. It
6511 is the responsibility of the user to ensure that the environment is
6512 not being updated concurrently with a call to the
6513 @code{GET_ENVIRONMENT_VARIABLE} intrinsic.
6515 @item @emph{Standard}:
6516 Fortran 2003 and later
6521 @item @emph{Syntax}:
6522 @code{CALL GET_ENVIRONMENT_VARIABLE(NAME[, VALUE, LENGTH, STATUS, TRIM_NAME)}
6524 @item @emph{Arguments}:
6525 @multitable @columnfractions .15 .70
6526 @item @var{NAME} @tab Shall be a scalar of type @code{CHARACTER}
6527 and of default kind.
6528 @item @var{VALUE} @tab (Optional) Shall be a scalar of type @code{CHARACTER}
6529 and of default kind.
6530 @item @var{LENGTH} @tab (Optional) Shall be a scalar of type @code{INTEGER}
6531 and of default kind.
6532 @item @var{STATUS} @tab (Optional) Shall be a scalar of type @code{INTEGER}
6533 and of default kind.
6534 @item @var{TRIM_NAME} @tab (Optional) Shall be a scalar of type @code{LOGICAL}
6535 and of default kind.
6538 @item @emph{Return value}:
6539 Stores the value of @var{NAME} in @var{VALUE}. If @var{VALUE} is
6540 not large enough to hold the data, it is truncated. If @var{NAME}
6541 is not set, @var{VALUE} will be filled with blanks. Argument @var{LENGTH}
6542 contains the length needed for storing the environment variable @var{NAME}
6543 or zero if it is not present. @var{STATUS} is -1 if @var{VALUE} is present
6544 but too short for the environment variable; it is 1 if the environment
6545 variable does not exist and 2 if the processor does not support environment
6546 variables; in all other cases @var{STATUS} is zero. If @var{TRIM_NAME} is
6547 present with the value @code{.FALSE.}, the trailing blanks in @var{NAME}
6548 are significant; otherwise they are not part of the environment variable
6551 @item @emph{Example}:
6554 CHARACTER(len=255) :: homedir
6555 CALL get_environment_variable("HOME", homedir)
6556 WRITE (*,*) TRIM(homedir)
6564 @section @code{GETGID} --- Group ID function
6566 @cindex system, group ID
6569 @item @emph{Description}:
6570 Returns the numerical group ID of the current process.
6572 @item @emph{Standard}:
6578 @item @emph{Syntax}:
6579 @code{RESULT = GETGID()}
6581 @item @emph{Return value}:
6582 The return value of @code{GETGID} is an @code{INTEGER} of the default
6586 @item @emph{Example}:
6587 See @code{GETPID} for an example.
6589 @item @emph{See also}:
6590 @ref{GETPID}, @ref{GETUID}
6596 @section @code{GETLOG} --- Get login name
6598 @cindex system, login name
6602 @item @emph{Description}:
6603 Gets the username under which the program is running.
6605 @item @emph{Standard}:
6611 @item @emph{Syntax}:
6612 @code{CALL GETLOG(C)}
6614 @item @emph{Arguments}:
6615 @multitable @columnfractions .15 .70
6616 @item @var{C} @tab Shall be of type @code{CHARACTER} and of default kind.
6619 @item @emph{Return value}:
6620 Stores the current user name in @var{LOGIN}. (On systems where POSIX
6621 functions @code{geteuid} and @code{getpwuid} are not available, and
6622 the @code{getlogin} function is not implemented either, this will
6623 return a blank string.)
6625 @item @emph{Example}:
6628 CHARACTER(32) :: login
6634 @item @emph{See also}:
6641 @section @code{GETPID} --- Process ID function
6643 @cindex system, process ID
6647 @item @emph{Description}:
6648 Returns the numerical process identifier of the current process.
6650 @item @emph{Standard}:
6656 @item @emph{Syntax}:
6657 @code{RESULT = GETPID()}
6659 @item @emph{Return value}:
6660 The return value of @code{GETPID} is an @code{INTEGER} of the default
6664 @item @emph{Example}:
6667 print *, "The current process ID is ", getpid()
6668 print *, "Your numerical user ID is ", getuid()
6669 print *, "Your numerical group ID is ", getgid()
6673 @item @emph{See also}:
6674 @ref{GETGID}, @ref{GETUID}
6680 @section @code{GETUID} --- User ID function
6682 @cindex system, user ID
6686 @item @emph{Description}:
6687 Returns the numerical user ID of the current process.
6689 @item @emph{Standard}:
6695 @item @emph{Syntax}:
6696 @code{RESULT = GETUID()}
6698 @item @emph{Return value}:
6699 The return value of @code{GETUID} is an @code{INTEGER} of the default
6703 @item @emph{Example}:
6704 See @code{GETPID} for an example.
6706 @item @emph{See also}:
6707 @ref{GETPID}, @ref{GETLOG}
6713 @section @code{GMTIME} --- Convert time to GMT info
6715 @cindex time, conversion to GMT info
6718 @item @emph{Description}:
6719 Given a system time value @var{TIME} (as provided by the @code{TIME8}
6720 intrinsic), fills @var{VALUES} with values extracted from it appropriate
6721 to the UTC time zone (Universal Coordinated Time, also known in some
6722 countries as GMT, Greenwich Mean Time), using @code{gmtime(3)}.
6724 @item @emph{Standard}:
6730 @item @emph{Syntax}:
6731 @code{CALL GMTIME(TIME, VALUES)}
6733 @item @emph{Arguments}:
6734 @multitable @columnfractions .15 .70
6735 @item @var{TIME} @tab An @code{INTEGER} scalar expression
6736 corresponding to a system time, with @code{INTENT(IN)}.
6737 @item @var{VALUES} @tab A default @code{INTEGER} array with 9 elements,
6738 with @code{INTENT(OUT)}.
6741 @item @emph{Return value}:
6742 The elements of @var{VALUES} are assigned as follows:
6744 @item Seconds after the minute, range 0--59 or 0--61 to allow for leap
6746 @item Minutes after the hour, range 0--59
6747 @item Hours past midnight, range 0--23
6748 @item Day of month, range 0--31
6749 @item Number of months since January, range 0--12
6750 @item Years since 1900
6751 @item Number of days since Sunday, range 0--6
6752 @item Days since January 1
6753 @item Daylight savings indicator: positive if daylight savings is in
6754 effect, zero if not, and negative if the information is not available.
6757 @item @emph{See also}:
6758 @ref{CTIME}, @ref{LTIME}, @ref{TIME}, @ref{TIME8}
6765 @section @code{HOSTNM} --- Get system host name
6767 @cindex system, host name
6770 @item @emph{Description}:
6771 Retrieves the host name of the system on which the program is running.
6773 This intrinsic is provided in both subroutine and function forms; however,
6774 only one form can be used in any given program unit.
6776 @item @emph{Standard}:
6780 Subroutine, function
6782 @item @emph{Syntax}:
6783 @multitable @columnfractions .80
6784 @item @code{CALL HOSTNM(C [, STATUS])}
6785 @item @code{STATUS = HOSTNM(NAME)}
6788 @item @emph{Arguments}:
6789 @multitable @columnfractions .15 .70
6790 @item @var{C} @tab Shall of type @code{CHARACTER} and of default kind.
6791 @item @var{STATUS} @tab (Optional) status flag of type @code{INTEGER}.
6792 Returns 0 on success, or a system specific error code otherwise.
6795 @item @emph{Return value}:
6796 In either syntax, @var{NAME} is set to the current hostname if it can
6797 be obtained, or to a blank string otherwise.
6804 @section @code{HUGE} --- Largest number of a kind
6806 @cindex limits, largest number
6807 @cindex model representation, largest number
6810 @item @emph{Description}:
6811 @code{HUGE(X)} returns the largest number that is not an infinity in
6812 the model of the type of @code{X}.
6814 @item @emph{Standard}:
6815 Fortran 95 and later
6820 @item @emph{Syntax}:
6821 @code{RESULT = HUGE(X)}
6823 @item @emph{Arguments}:
6824 @multitable @columnfractions .15 .70
6825 @item @var{X} @tab Shall be of type @code{REAL} or @code{INTEGER}.
6828 @item @emph{Return value}:
6829 The return value is of the same type and kind as @var{X}
6831 @item @emph{Example}:
6833 program test_huge_tiny
6834 print *, huge(0), huge(0.0), huge(0.0d0)
6835 print *, tiny(0.0), tiny(0.0d0)
6836 end program test_huge_tiny
6843 @section @code{HYPOT} --- Euclidean distance function
6845 @cindex Euclidean distance
6848 @item @emph{Description}:
6849 @code{HYPOT(X,Y)} is the Euclidean distance function. It is equal to
6850 @math{\sqrt{X^2 + Y^2}}, without undue underflow or overflow.
6852 @item @emph{Standard}:
6853 Fortran 2008 and later
6858 @item @emph{Syntax}:
6859 @code{RESULT = HYPOT(X, Y)}
6861 @item @emph{Arguments}:
6862 @multitable @columnfractions .15 .70
6863 @item @var{X} @tab The type shall be @code{REAL}.
6864 @item @var{Y} @tab The type and kind type parameter shall be the same as
6868 @item @emph{Return value}:
6869 The return value has the same type and kind type parameter as @var{X}.
6871 @item @emph{Example}:
6874 real(4) :: x = 1.e0_4, y = 0.5e0_4
6876 end program test_hypot
6883 @section @code{IACHAR} --- Code in @acronym{ASCII} collating sequence
6885 @cindex @acronym{ASCII} collating sequence
6886 @cindex collating sequence, @acronym{ASCII}
6887 @cindex conversion, to integer
6890 @item @emph{Description}:
6891 @code{IACHAR(C)} returns the code for the @acronym{ASCII} character
6892 in the first character position of @code{C}.
6894 @item @emph{Standard}:
6895 Fortran 95 and later, with @var{KIND} argument Fortran 2003 and later
6900 @item @emph{Syntax}:
6901 @code{RESULT = IACHAR(C [, KIND])}
6903 @item @emph{Arguments}:
6904 @multitable @columnfractions .15 .70
6905 @item @var{C} @tab Shall be a scalar @code{CHARACTER}, with @code{INTENT(IN)}
6906 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
6907 expression indicating the kind parameter of the result.
6910 @item @emph{Return value}:
6911 The return value is of type @code{INTEGER} and of kind @var{KIND}. If
6912 @var{KIND} is absent, the return value is of default integer kind.
6914 @item @emph{Example}:
6919 end program test_iachar
6923 See @ref{ICHAR} for a discussion of converting between numerical values
6924 and formatted string representations.
6926 @item @emph{See also}:
6927 @ref{ACHAR}, @ref{CHAR}, @ref{ICHAR}
6934 @section @code{IALL} --- Bitwise AND of array elements
6937 @cindex bits, AND of array elements
6940 @item @emph{Description}:
6941 Reduces with bitwise AND the elements of @var{ARRAY} along dimension @var{DIM}
6942 if the corresponding element in @var{MASK} is @code{TRUE}.
6944 @item @emph{Standard}:
6945 Fortran 2008 and later
6948 Transformational function
6950 @item @emph{Syntax}:
6951 @multitable @columnfractions .80
6952 @item @code{RESULT = IALL(ARRAY[, MASK])}
6953 @item @code{RESULT = IALL(ARRAY, DIM[, MASK])}
6956 @item @emph{Arguments}:
6957 @multitable @columnfractions .15 .70
6958 @item @var{ARRAY} @tab Shall be an array of type @code{INTEGER}
6959 @item @var{DIM} @tab (Optional) shall be a scalar of type
6960 @code{INTEGER} with a value in the range from 1 to n, where n
6961 equals the rank of @var{ARRAY}.
6962 @item @var{MASK} @tab (Optional) shall be of type @code{LOGICAL}
6963 and either be a scalar or an array of the same shape as @var{ARRAY}.
6966 @item @emph{Return value}:
6967 The result is of the same type as @var{ARRAY}.
6969 If @var{DIM} is absent, a scalar with the bitwise ALL of all elements in
6970 @var{ARRAY} is returned. Otherwise, an array of rank n-1, where n equals
6971 the rank of @var{ARRAY}, and a shape similar to that of @var{ARRAY} with
6972 dimension @var{DIM} dropped is returned.
6974 @item @emph{Example}:
6983 PRINT '(b8.8)', IALL(a)
6987 @item @emph{See also}:
6988 @ref{IANY}, @ref{IPARITY}, @ref{IAND}
6994 @section @code{IAND} --- Bitwise logical and
7000 @cindex bitwise logical and
7001 @cindex logical and, bitwise
7004 @item @emph{Description}:
7005 Bitwise logical @code{AND}.
7007 @item @emph{Standard}:
7008 Fortran 95 and later, has overloads that are GNU extensions
7013 @item @emph{Syntax}:
7014 @code{RESULT = IAND(I, J)}
7016 @item @emph{Arguments}:
7017 @multitable @columnfractions .15 .70
7018 @item @var{I} @tab The type shall be @code{INTEGER}.
7019 @item @var{J} @tab The type shall be @code{INTEGER}, of the same
7020 kind as @var{I}. (As a GNU extension, different kinds are also
7024 @item @emph{Return value}:
7025 The return type is @code{INTEGER}, of the same kind as the
7026 arguments. (If the argument kinds differ, it is of the same kind as
7027 the larger argument.)
7029 @item @emph{Example}:
7033 DATA a / Z'F' /, b / Z'3' /
7034 WRITE (*,*) IAND(a, b)
7038 @item @emph{Specific names}:
7039 @multitable @columnfractions .20 .20 .20 .25
7040 @item Name @tab Argument @tab Return type @tab Standard
7041 @item @code{IAND(A)} @tab @code{INTEGER A} @tab @code{INTEGER} @tab Fortran 95 and later
7042 @item @code{BIAND(A)} @tab @code{INTEGER(1) A} @tab @code{INTEGER(1)} @tab GNU extension
7043 @item @code{IIAND(A)} @tab @code{INTEGER(2) A} @tab @code{INTEGER(2)} @tab GNU extension
7044 @item @code{JIAND(A)} @tab @code{INTEGER(4) A} @tab @code{INTEGER(4)} @tab GNU extension
7045 @item @code{KIAND(A)} @tab @code{INTEGER(8) A} @tab @code{INTEGER(8)} @tab GNU extension
7048 @item @emph{See also}:
7049 @ref{IOR}, @ref{IEOR}, @ref{IBITS}, @ref{IBSET}, @ref{IBCLR}, @ref{NOT}
7056 @section @code{IANY} --- Bitwise OR of array elements
7059 @cindex bits, OR of array elements
7062 @item @emph{Description}:
7063 Reduces with bitwise OR (inclusive or) the elements of @var{ARRAY} along
7064 dimension @var{DIM} if the corresponding element in @var{MASK} is @code{TRUE}.
7066 @item @emph{Standard}:
7067 Fortran 2008 and later
7070 Transformational function
7072 @item @emph{Syntax}:
7073 @multitable @columnfractions .80
7074 @item @code{RESULT = IANY(ARRAY[, MASK])}
7075 @item @code{RESULT = IANY(ARRAY, DIM[, MASK])}
7078 @item @emph{Arguments}:
7079 @multitable @columnfractions .15 .70
7080 @item @var{ARRAY} @tab Shall be an array of type @code{INTEGER}
7081 @item @var{DIM} @tab (Optional) shall be a scalar of type
7082 @code{INTEGER} with a value in the range from 1 to n, where n
7083 equals the rank of @var{ARRAY}.
7084 @item @var{MASK} @tab (Optional) shall be of type @code{LOGICAL}
7085 and either be a scalar or an array of the same shape as @var{ARRAY}.
7088 @item @emph{Return value}:
7089 The result is of the same type as @var{ARRAY}.
7091 If @var{DIM} is absent, a scalar with the bitwise OR of all elements in
7092 @var{ARRAY} is returned. Otherwise, an array of rank n-1, where n equals
7093 the rank of @var{ARRAY}, and a shape similar to that of @var{ARRAY} with
7094 dimension @var{DIM} dropped is returned.
7096 @item @emph{Example}:
7105 PRINT '(b8.8)', IANY(a)
7109 @item @emph{See also}:
7110 @ref{IPARITY}, @ref{IALL}, @ref{IOR}
7116 @section @code{IARGC} --- Get the number of command line arguments
7118 @cindex command-line arguments
7119 @cindex command-line arguments, number of
7120 @cindex arguments, to program
7123 @item @emph{Description}:
7124 @code{IARGC} returns the number of arguments passed on the
7125 command line when the containing program was invoked.
7127 This intrinsic routine is provided for backwards compatibility with
7128 GNU Fortran 77. In new code, programmers should consider the use of
7129 the @ref{COMMAND_ARGUMENT_COUNT} intrinsic defined by the Fortran 2003
7132 @item @emph{Standard}:
7138 @item @emph{Syntax}:
7139 @code{RESULT = IARGC()}
7141 @item @emph{Arguments}:
7144 @item @emph{Return value}:
7145 The number of command line arguments, type @code{INTEGER(4)}.
7147 @item @emph{Example}:
7150 @item @emph{See also}:
7151 GNU Fortran 77 compatibility subroutine: @ref{GETARG}
7153 Fortran 2003 functions and subroutines: @ref{GET_COMMAND},
7154 @ref{GET_COMMAND_ARGUMENT}, @ref{COMMAND_ARGUMENT_COUNT}
7160 @section @code{IBCLR} --- Clear bit
7170 @item @emph{Description}:
7171 @code{IBCLR} returns the value of @var{I} with the bit at position
7172 @var{POS} set to zero.
7174 @item @emph{Standard}:
7175 Fortran 95 and later, has overloads that are GNU extensions
7180 @item @emph{Syntax}:
7181 @code{RESULT = IBCLR(I, POS)}
7183 @item @emph{Arguments}:
7184 @multitable @columnfractions .15 .70
7185 @item @var{I} @tab The type shall be @code{INTEGER}.
7186 @item @var{POS} @tab The type shall be @code{INTEGER}.
7189 @item @emph{Return value}:
7190 The return value is of type @code{INTEGER} and of the same kind as
7193 @item @emph{Specific names}:
7194 @multitable @columnfractions .20 .20 .20 .25
7195 @item Name @tab Argument @tab Return type @tab Standard
7196 @item @code{IBCLR(A)} @tab @code{INTEGER A} @tab @code{INTEGER} @tab Fortran 95 and later
7197 @item @code{BBCLR(A)} @tab @code{INTEGER(1) A} @tab @code{INTEGER(1)} @tab GNU extension
7198 @item @code{IIBCLR(A)} @tab @code{INTEGER(2) A} @tab @code{INTEGER(2)} @tab GNU extension
7199 @item @code{JIBCLR(A)} @tab @code{INTEGER(4) A} @tab @code{INTEGER(4)} @tab GNU extension
7200 @item @code{KIBCLR(A)} @tab @code{INTEGER(8) A} @tab @code{INTEGER(8)} @tab GNU extension
7203 @item @emph{See also}:
7204 @ref{IBITS}, @ref{IBSET}, @ref{IAND}, @ref{IOR}, @ref{IEOR}, @ref{MVBITS}
7211 @section @code{IBITS} --- Bit extraction
7218 @cindex bits, extract
7221 @item @emph{Description}:
7222 @code{IBITS} extracts a field of length @var{LEN} from @var{I},
7223 starting from bit position @var{POS} and extending left for @var{LEN}
7224 bits. The result is right-justified and the remaining bits are
7225 zeroed. The value of @code{POS+LEN} must be less than or equal to the
7226 value @code{BIT_SIZE(I)}.
7228 @item @emph{Standard}:
7229 Fortran 95 and later, has overloads that are GNU extensions
7234 @item @emph{Syntax}:
7235 @code{RESULT = IBITS(I, POS, LEN)}
7237 @item @emph{Arguments}:
7238 @multitable @columnfractions .15 .70
7239 @item @var{I} @tab The type shall be @code{INTEGER}.
7240 @item @var{POS} @tab The type shall be @code{INTEGER}.
7241 @item @var{LEN} @tab The type shall be @code{INTEGER}.
7244 @item @emph{Return value}:
7245 The return value is of type @code{INTEGER} and of the same kind as
7248 @item @emph{Specific names}:
7249 @multitable @columnfractions .20 .20 .20 .25
7250 @item Name @tab Argument @tab Return type @tab Standard
7251 @item @code{IBITS(A)} @tab @code{INTEGER A} @tab @code{INTEGER} @tab Fortran 95 and later
7252 @item @code{BBITS(A)} @tab @code{INTEGER(1) A} @tab @code{INTEGER(1)} @tab GNU extension
7253 @item @code{IIBITS(A)} @tab @code{INTEGER(2) A} @tab @code{INTEGER(2)} @tab GNU extension
7254 @item @code{JIBITS(A)} @tab @code{INTEGER(4) A} @tab @code{INTEGER(4)} @tab GNU extension
7255 @item @code{KIBITS(A)} @tab @code{INTEGER(8) A} @tab @code{INTEGER(8)} @tab GNU extension
7258 @item @emph{See also}:
7259 @ref{BIT_SIZE}, @ref{IBCLR}, @ref{IBSET}, @ref{IAND}, @ref{IOR}, @ref{IEOR}
7265 @section @code{IBSET} --- Set bit
7274 @item @emph{Description}:
7275 @code{IBSET} returns the value of @var{I} with the bit at position
7276 @var{POS} set to one.
7278 @item @emph{Standard}:
7279 Fortran 95 and later, has overloads that are GNU extensions
7284 @item @emph{Syntax}:
7285 @code{RESULT = IBSET(I, POS)}
7287 @item @emph{Arguments}:
7288 @multitable @columnfractions .15 .70
7289 @item @var{I} @tab The type shall be @code{INTEGER}.
7290 @item @var{POS} @tab The type shall be @code{INTEGER}.
7293 @item @emph{Return value}:
7294 The return value is of type @code{INTEGER} and of the same kind as
7297 @item @emph{Specific names}:
7298 @multitable @columnfractions .20 .20 .20 .25
7299 @item Name @tab Argument @tab Return type @tab Standard
7300 @item @code{IBSET(A)} @tab @code{INTEGER A} @tab @code{INTEGER} @tab Fortran 95 and later
7301 @item @code{BBSET(A)} @tab @code{INTEGER(1) A} @tab @code{INTEGER(1)} @tab GNU extension
7302 @item @code{IIBSET(A)} @tab @code{INTEGER(2) A} @tab @code{INTEGER(2)} @tab GNU extension
7303 @item @code{JIBSET(A)} @tab @code{INTEGER(4) A} @tab @code{INTEGER(4)} @tab GNU extension
7304 @item @code{KIBSET(A)} @tab @code{INTEGER(8) A} @tab @code{INTEGER(8)} @tab GNU extension
7307 @item @emph{See also}:
7308 @ref{IBCLR}, @ref{IBITS}, @ref{IAND}, @ref{IOR}, @ref{IEOR}, @ref{MVBITS}
7315 @section @code{ICHAR} --- Character-to-integer conversion function
7317 @cindex conversion, to integer
7320 @item @emph{Description}:
7321 @code{ICHAR(C)} returns the code for the character in the first character
7322 position of @code{C} in the system's native character set.
7323 The correspondence between characters and their codes is not necessarily
7324 the same across different GNU Fortran implementations.
7326 @item @emph{Standard}:
7327 Fortran 95 and later, with @var{KIND} argument Fortran 2003 and later
7332 @item @emph{Syntax}:
7333 @code{RESULT = ICHAR(C [, KIND])}
7335 @item @emph{Arguments}:
7336 @multitable @columnfractions .15 .70
7337 @item @var{C} @tab Shall be a scalar @code{CHARACTER}, with @code{INTENT(IN)}
7338 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
7339 expression indicating the kind parameter of the result.
7342 @item @emph{Return value}:
7343 The return value is of type @code{INTEGER} and of kind @var{KIND}. If
7344 @var{KIND} is absent, the return value is of default integer kind.
7346 @item @emph{Example}:
7351 end program test_ichar
7354 @item @emph{Specific names}:
7355 @multitable @columnfractions .20 .20 .20 .25
7356 @item Name @tab Argument @tab Return type @tab Standard
7357 @item @code{ICHAR(C)} @tab @code{CHARACTER C} @tab @code{INTEGER(4)} @tab Fortran 77 and later
7361 No intrinsic exists to convert between a numeric value and a formatted
7362 character string representation -- for instance, given the
7363 @code{CHARACTER} value @code{'154'}, obtaining an @code{INTEGER} or
7364 @code{REAL} value with the value 154, or vice versa. Instead, this
7365 functionality is provided by internal-file I/O, as in the following
7370 character(len=10) string, string2
7373 ! Convert a string to a numeric value
7374 read (string,'(I10)') value
7377 ! Convert a value to a formatted string
7378 write (string2,'(I10)') value
7380 end program read_val
7383 @item @emph{See also}:
7384 @ref{ACHAR}, @ref{CHAR}, @ref{IACHAR}
7391 @section @code{IDATE} --- Get current local time subroutine (day/month/year)
7393 @cindex date, current
7394 @cindex current date
7397 @item @emph{Description}:
7398 @code{IDATE(VALUES)} Fills @var{VALUES} with the numerical values at the
7399 current local time. The day (in the range 1-31), month (in the range 1-12),
7400 and year appear in elements 1, 2, and 3 of @var{VALUES}, respectively.
7401 The year has four significant digits.
7403 @item @emph{Standard}:
7409 @item @emph{Syntax}:
7410 @code{CALL IDATE(VALUES)}
7412 @item @emph{Arguments}:
7413 @multitable @columnfractions .15 .70
7414 @item @var{VALUES} @tab The type shall be @code{INTEGER, DIMENSION(3)} and
7415 the kind shall be the default integer kind.
7418 @item @emph{Return value}:
7419 Does not return anything.
7421 @item @emph{Example}:
7424 integer, dimension(3) :: tarray
7429 end program test_idate
7436 @section @code{IEOR} --- Bitwise logical exclusive or
7442 @cindex bitwise logical exclusive or
7443 @cindex logical exclusive or, bitwise
7446 @item @emph{Description}:
7447 @code{IEOR} returns the bitwise Boolean exclusive-OR of @var{I} and
7450 @item @emph{Standard}:
7451 Fortran 95 and later, has overloads that are GNU extensions
7456 @item @emph{Syntax}:
7457 @code{RESULT = IEOR(I, J)}
7459 @item @emph{Arguments}:
7460 @multitable @columnfractions .15 .70
7461 @item @var{I} @tab The type shall be @code{INTEGER}.
7462 @item @var{J} @tab The type shall be @code{INTEGER}, of the same
7463 kind as @var{I}. (As a GNU extension, different kinds are also
7467 @item @emph{Return value}:
7468 The return type is @code{INTEGER}, of the same kind as the
7469 arguments. (If the argument kinds differ, it is of the same kind as
7470 the larger argument.)
7472 @item @emph{Specific names}:
7473 @multitable @columnfractions .20 .20 .20 .25
7474 @item Name @tab Argument @tab Return type @tab Standard
7475 @item @code{IEOR(A)} @tab @code{INTEGER A} @tab @code{INTEGER} @tab Fortran 95 and later
7476 @item @code{BIEOR(A)} @tab @code{INTEGER(1) A} @tab @code{INTEGER(1)} @tab GNU extension
7477 @item @code{IIEOR(A)} @tab @code{INTEGER(2) A} @tab @code{INTEGER(2)} @tab GNU extension
7478 @item @code{JIEOR(A)} @tab @code{INTEGER(4) A} @tab @code{INTEGER(4)} @tab GNU extension
7479 @item @code{KIEOR(A)} @tab @code{INTEGER(8) A} @tab @code{INTEGER(8)} @tab GNU extension
7482 @item @emph{See also}:
7483 @ref{IOR}, @ref{IAND}, @ref{IBITS}, @ref{IBSET}, @ref{IBCLR}, @ref{NOT}
7489 @section @code{IERRNO} --- Get the last system error number
7491 @cindex system, error handling
7494 @item @emph{Description}:
7495 Returns the last system error number, as given by the C @code{errno}
7498 @item @emph{Standard}:
7504 @item @emph{Syntax}:
7505 @code{RESULT = IERRNO()}
7507 @item @emph{Arguments}:
7510 @item @emph{Return value}:
7511 The return value is of type @code{INTEGER} and of the default integer
7514 @item @emph{See also}:
7521 @section @code{IMAGE_INDEX} --- Function that converts a cosubscript to an image index
7522 @fnindex IMAGE_INDEX
7523 @cindex coarray, @code{IMAGE_INDEX}
7524 @cindex images, cosubscript to image index conversion
7527 @item @emph{Description}:
7528 Returns the image index belonging to a cosubscript.
7530 @item @emph{Standard}:
7531 Fortran 2008 and later
7536 @item @emph{Syntax}:
7537 @code{RESULT = IMAGE_INDEX(COARRAY, SUB)}
7539 @item @emph{Arguments}: None.
7540 @multitable @columnfractions .15 .70
7541 @item @var{COARRAY} @tab Coarray of any type.
7542 @item @var{SUB} @tab default integer rank-1 array of a size equal to
7543 the corank of @var{COARRAY}.
7547 @item @emph{Return value}:
7548 Scalar default integer with the value of the image index which corresponds
7549 to the cosubscripts. For invalid cosubscripts the result is zero.
7551 @item @emph{Example}:
7553 INTEGER :: array[2,-1:4,8,*]
7554 ! Writes 28 (or 0 if there are fewer than 28 images)
7555 WRITE (*,*) IMAGE_INDEX (array, [2,0,3,1])
7558 @item @emph{See also}:
7559 @ref{THIS_IMAGE}, @ref{NUM_IMAGES}
7564 @node INDEX intrinsic
7565 @section @code{INDEX} --- Position of a substring within a string
7567 @cindex substring position
7568 @cindex string, find substring
7571 @item @emph{Description}:
7572 Returns the position of the start of the first occurrence of string
7573 @var{SUBSTRING} as a substring in @var{STRING}, counting from one. If
7574 @var{SUBSTRING} is not present in @var{STRING}, zero is returned. If
7575 the @var{BACK} argument is present and true, the return value is the
7576 start of the last occurrence rather than the first.
7578 @item @emph{Standard}:
7579 Fortran 77 and later, with @var{KIND} argument Fortran 2003 and later
7584 @item @emph{Syntax}:
7585 @code{RESULT = INDEX(STRING, SUBSTRING [, BACK [, KIND]])}
7587 @item @emph{Arguments}:
7588 @multitable @columnfractions .15 .70
7589 @item @var{STRING} @tab Shall be a scalar @code{CHARACTER}, with
7591 @item @var{SUBSTRING} @tab Shall be a scalar @code{CHARACTER}, with
7593 @item @var{BACK} @tab (Optional) Shall be a scalar @code{LOGICAL}, with
7595 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
7596 expression indicating the kind parameter of the result.
7599 @item @emph{Return value}:
7600 The return value is of type @code{INTEGER} and of kind @var{KIND}. If
7601 @var{KIND} is absent, the return value is of default integer kind.
7603 @item @emph{Specific names}:
7604 @multitable @columnfractions .20 .20 .20 .25
7605 @item Name @tab Argument @tab Return type @tab Standard
7606 @item @code{INDEX(STRING, SUBSTRING)} @tab @code{CHARACTER} @tab @code{INTEGER(4)} @tab Fortran 77 and later
7609 @item @emph{See also}:
7610 @ref{SCAN}, @ref{VERIFY}
7616 @section @code{INT} --- Convert to integer type
7620 @cindex conversion, to integer
7623 @item @emph{Description}:
7624 Convert to integer type
7626 @item @emph{Standard}:
7627 Fortran 77 and later
7632 @item @emph{Syntax}:
7633 @code{RESULT = INT(A [, KIND))}
7635 @item @emph{Arguments}:
7636 @multitable @columnfractions .15 .70
7637 @item @var{A} @tab Shall be of type @code{INTEGER},
7638 @code{REAL}, or @code{COMPLEX}.
7639 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
7640 expression indicating the kind parameter of the result.
7643 @item @emph{Return value}:
7644 These functions return a @code{INTEGER} variable or array under
7645 the following rules:
7649 If @var{A} is of type @code{INTEGER}, @code{INT(A) = A}
7651 If @var{A} is of type @code{REAL} and @math{|A| < 1}, @code{INT(A)}
7652 equals @code{0}. If @math{|A| \geq 1}, then @code{INT(A)} is the integer
7653 whose magnitude is the largest integer that does not exceed the magnitude
7654 of @var{A} and whose sign is the same as the sign of @var{A}.
7656 If @var{A} is of type @code{COMPLEX}, rule B is applied to the real part of @var{A}.
7659 @item @emph{Example}:
7663 complex :: z = (-3.7, 1.0)
7665 print *, int(z), int(z,8)
7669 @item @emph{Specific names}:
7670 @multitable @columnfractions .20 .20 .20 .25
7671 @item Name @tab Argument @tab Return type @tab Standard
7672 @item @code{INT(A)} @tab @code{REAL(4) A} @tab @code{INTEGER} @tab Fortran 77 and later
7673 @item @code{IFIX(A)} @tab @code{REAL(4) A} @tab @code{INTEGER} @tab Fortran 77 and later
7674 @item @code{IDINT(A)} @tab @code{REAL(8) A} @tab @code{INTEGER} @tab Fortran 77 and later
7681 @section @code{INT2} --- Convert to 16-bit integer type
7684 @cindex conversion, to integer
7687 @item @emph{Description}:
7688 Convert to a @code{KIND=2} integer type. This is equivalent to the
7689 standard @code{INT} intrinsic with an optional argument of
7690 @code{KIND=2}, and is only included for backwards compatibility.
7692 The @code{SHORT} intrinsic is equivalent to @code{INT2}.
7694 @item @emph{Standard}:
7700 @item @emph{Syntax}:
7701 @code{RESULT = INT2(A)}
7703 @item @emph{Arguments}:
7704 @multitable @columnfractions .15 .70
7705 @item @var{A} @tab Shall be of type @code{INTEGER},
7706 @code{REAL}, or @code{COMPLEX}.
7709 @item @emph{Return value}:
7710 The return value is a @code{INTEGER(2)} variable.
7712 @item @emph{See also}:
7713 @ref{INT}, @ref{INT8}, @ref{LONG}
7719 @section @code{INT8} --- Convert to 64-bit integer type
7721 @cindex conversion, to integer
7724 @item @emph{Description}:
7725 Convert to a @code{KIND=8} integer type. This is equivalent to the
7726 standard @code{INT} intrinsic with an optional argument of
7727 @code{KIND=8}, and is only included for backwards compatibility.
7729 @item @emph{Standard}:
7735 @item @emph{Syntax}:
7736 @code{RESULT = INT8(A)}
7738 @item @emph{Arguments}:
7739 @multitable @columnfractions .15 .70
7740 @item @var{A} @tab Shall be of type @code{INTEGER},
7741 @code{REAL}, or @code{COMPLEX}.
7744 @item @emph{Return value}:
7745 The return value is a @code{INTEGER(8)} variable.
7747 @item @emph{See also}:
7748 @ref{INT}, @ref{INT2}, @ref{LONG}
7754 @section @code{IOR} --- Bitwise logical or
7760 @cindex bitwise logical or
7761 @cindex logical or, bitwise
7764 @item @emph{Description}:
7765 @code{IOR} returns the bitwise Boolean inclusive-OR of @var{I} and
7768 @item @emph{Standard}:
7769 Fortran 95 and later, has overloads that are GNU extensions
7774 @item @emph{Syntax}:
7775 @code{RESULT = IOR(I, J)}
7777 @item @emph{Arguments}:
7778 @multitable @columnfractions .15 .70
7779 @item @var{I} @tab The type shall be @code{INTEGER}.
7780 @item @var{J} @tab The type shall be @code{INTEGER}, of the same
7781 kind as @var{I}. (As a GNU extension, different kinds are also
7785 @item @emph{Return value}:
7786 The return type is @code{INTEGER}, of the same kind as the
7787 arguments. (If the argument kinds differ, it is of the same kind as
7788 the larger argument.)
7790 @item @emph{Specific names}:
7791 @multitable @columnfractions .20 .20 .20 .25
7792 @item Name @tab Argument @tab Return type @tab Standard
7793 @item @code{IOR(A)} @tab @code{INTEGER A} @tab @code{INTEGER} @tab Fortran 95 and later
7794 @item @code{BIOR(A)} @tab @code{INTEGER(1) A} @tab @code{INTEGER(1)} @tab GNU extension
7795 @item @code{IIOR(A)} @tab @code{INTEGER(2) A} @tab @code{INTEGER(2)} @tab GNU extension
7796 @item @code{JIOR(A)} @tab @code{INTEGER(4) A} @tab @code{INTEGER(4)} @tab GNU extension
7797 @item @code{KIOR(A)} @tab @code{INTEGER(8) A} @tab @code{INTEGER(8)} @tab GNU extension
7800 @item @emph{See also}:
7801 @ref{IEOR}, @ref{IAND}, @ref{IBITS}, @ref{IBSET}, @ref{IBCLR}, @ref{NOT}
7807 @section @code{IPARITY} --- Bitwise XOR of array elements
7809 @cindex array, parity
7811 @cindex bits, XOR of array elements
7814 @item @emph{Description}:
7815 Reduces with bitwise XOR (exclusive or) the elements of @var{ARRAY} along
7816 dimension @var{DIM} if the corresponding element in @var{MASK} is @code{TRUE}.
7818 @item @emph{Standard}:
7819 Fortran 2008 and later
7822 Transformational function
7824 @item @emph{Syntax}:
7825 @multitable @columnfractions .80
7826 @item @code{RESULT = IPARITY(ARRAY[, MASK])}
7827 @item @code{RESULT = IPARITY(ARRAY, DIM[, MASK])}
7830 @item @emph{Arguments}:
7831 @multitable @columnfractions .15 .70
7832 @item @var{ARRAY} @tab Shall be an array of type @code{INTEGER}
7833 @item @var{DIM} @tab (Optional) shall be a scalar of type
7834 @code{INTEGER} with a value in the range from 1 to n, where n
7835 equals the rank of @var{ARRAY}.
7836 @item @var{MASK} @tab (Optional) shall be of type @code{LOGICAL}
7837 and either be a scalar or an array of the same shape as @var{ARRAY}.
7840 @item @emph{Return value}:
7841 The result is of the same type as @var{ARRAY}.
7843 If @var{DIM} is absent, a scalar with the bitwise XOR of all elements in
7844 @var{ARRAY} is returned. Otherwise, an array of rank n-1, where n equals
7845 the rank of @var{ARRAY}, and a shape similar to that of @var{ARRAY} with
7846 dimension @var{DIM} dropped is returned.
7848 @item @emph{Example}:
7850 PROGRAM test_iparity
7857 PRINT '(b8.8)', IPARITY(a)
7861 @item @emph{See also}:
7862 @ref{IANY}, @ref{IALL}, @ref{IEOR}, @ref{PARITY}
7868 @section @code{IRAND} --- Integer pseudo-random number
7870 @cindex random number generation
7873 @item @emph{Description}:
7874 @code{IRAND(FLAG)} returns a pseudo-random number from a uniform
7875 distribution between 0 and a system-dependent limit (which is in most
7876 cases 2147483647). If @var{FLAG} is 0, the next number
7877 in the current sequence is returned; if @var{FLAG} is 1, the generator
7878 is restarted by @code{CALL SRAND(0)}; if @var{FLAG} has any other value,
7879 it is used as a new seed with @code{SRAND}.
7881 This intrinsic routine is provided for backwards compatibility with
7882 GNU Fortran 77. It implements a simple modulo generator as provided
7883 by @command{g77}. For new code, one should consider the use of
7884 @ref{RANDOM_NUMBER} as it implements a superior algorithm.
7886 @item @emph{Standard}:
7892 @item @emph{Syntax}:
7893 @code{RESULT = IRAND(I)}
7895 @item @emph{Arguments}:
7896 @multitable @columnfractions .15 .70
7897 @item @var{I} @tab Shall be a scalar @code{INTEGER} of kind 4.
7900 @item @emph{Return value}:
7901 The return value is of @code{INTEGER(kind=4)} type.
7903 @item @emph{Example}:
7906 integer,parameter :: seed = 86456
7909 print *, irand(), irand(), irand(), irand()
7910 print *, irand(seed), irand(), irand(), irand()
7911 end program test_irand
7919 @section @code{IS_IOSTAT_END} --- Test for end-of-file value
7920 @fnindex IS_IOSTAT_END
7921 @cindex @code{IOSTAT}, end of file
7924 @item @emph{Description}:
7925 @code{IS_IOSTAT_END} tests whether an variable has the value of the I/O
7926 status ``end of file''. The function is equivalent to comparing the variable
7927 with the @code{IOSTAT_END} parameter of the intrinsic module
7928 @code{ISO_FORTRAN_ENV}.
7930 @item @emph{Standard}:
7931 Fortran 2003 and later
7936 @item @emph{Syntax}:
7937 @code{RESULT = IS_IOSTAT_END(I)}
7939 @item @emph{Arguments}:
7940 @multitable @columnfractions .15 .70
7941 @item @var{I} @tab Shall be of the type @code{INTEGER}.
7944 @item @emph{Return value}:
7945 Returns a @code{LOGICAL} of the default kind, which @code{.TRUE.} if
7946 @var{I} has the value which indicates an end of file condition for
7947 @code{IOSTAT=} specifiers, and is @code{.FALSE.} otherwise.
7949 @item @emph{Example}:
7954 OPEN(88, FILE='test.dat')
7955 READ(88, *, IOSTAT=stat) i
7956 IF(IS_IOSTAT_END(stat)) STOP 'END OF FILE'
7964 @section @code{IS_IOSTAT_EOR} --- Test for end-of-record value
7965 @fnindex IS_IOSTAT_EOR
7966 @cindex @code{IOSTAT}, end of record
7969 @item @emph{Description}:
7970 @code{IS_IOSTAT_EOR} tests whether an variable has the value of the I/O
7971 status ``end of record''. The function is equivalent to comparing the
7972 variable with the @code{IOSTAT_EOR} parameter of the intrinsic module
7973 @code{ISO_FORTRAN_ENV}.
7975 @item @emph{Standard}:
7976 Fortran 2003 and later
7981 @item @emph{Syntax}:
7982 @code{RESULT = IS_IOSTAT_EOR(I)}
7984 @item @emph{Arguments}:
7985 @multitable @columnfractions .15 .70
7986 @item @var{I} @tab Shall be of the type @code{INTEGER}.
7989 @item @emph{Return value}:
7990 Returns a @code{LOGICAL} of the default kind, which @code{.TRUE.} if
7991 @var{I} has the value which indicates an end of file condition for
7992 @code{IOSTAT=} specifiers, and is @code{.FALSE.} otherwise.
7994 @item @emph{Example}:
7998 INTEGER :: stat, i(50)
7999 OPEN(88, FILE='test.dat', FORM='UNFORMATTED')
8000 READ(88, IOSTAT=stat) i
8001 IF(IS_IOSTAT_EOR(stat)) STOP 'END OF RECORD'
8009 @section @code{ISATTY} --- Whether a unit is a terminal device.
8011 @cindex system, terminal
8014 @item @emph{Description}:
8015 Determine whether a unit is connected to a terminal device.
8017 @item @emph{Standard}:
8023 @item @emph{Syntax}:
8024 @code{RESULT = ISATTY(UNIT)}
8026 @item @emph{Arguments}:
8027 @multitable @columnfractions .15 .70
8028 @item @var{UNIT} @tab Shall be a scalar @code{INTEGER}.
8031 @item @emph{Return value}:
8032 Returns @code{.TRUE.} if the @var{UNIT} is connected to a terminal
8033 device, @code{.FALSE.} otherwise.
8035 @item @emph{Example}:
8038 INTEGER(kind=1) :: unit
8040 write(*,*) isatty(unit=unit)
8044 @item @emph{See also}:
8051 @section @code{ISHFT} --- Shift bits
8060 @item @emph{Description}:
8061 @code{ISHFT} returns a value corresponding to @var{I} with all of the
8062 bits shifted @var{SHIFT} places. A value of @var{SHIFT} greater than
8063 zero corresponds to a left shift, a value of zero corresponds to no
8064 shift, and a value less than zero corresponds to a right shift. If the
8065 absolute value of @var{SHIFT} is greater than @code{BIT_SIZE(I)}, the
8066 value is undefined. Bits shifted out from the left end or right end are
8067 lost; zeros are shifted in from the opposite end.
8069 @item @emph{Standard}:
8070 Fortran 95 and later, has overloads that are GNU extensions
8075 @item @emph{Syntax}:
8076 @code{RESULT = ISHFT(I, SHIFT)}
8078 @item @emph{Arguments}:
8079 @multitable @columnfractions .15 .70
8080 @item @var{I} @tab The type shall be @code{INTEGER}.
8081 @item @var{SHIFT} @tab The type shall be @code{INTEGER}.
8084 @item @emph{Return value}:
8085 The return value is of type @code{INTEGER} and of the same kind as
8088 @item @emph{Specific names}:
8089 @multitable @columnfractions .20 .20 .20 .25
8090 @item Name @tab Argument @tab Return type @tab Standard
8091 @item @code{ISHFT(A)} @tab @code{INTEGER A} @tab @code{INTEGER} @tab Fortran 95 and later
8092 @item @code{BSHFT(A)} @tab @code{INTEGER(1) A} @tab @code{INTEGER(1)} @tab GNU extension
8093 @item @code{IISHFT(A)} @tab @code{INTEGER(2) A} @tab @code{INTEGER(2)} @tab GNU extension
8094 @item @code{JISHFT(A)} @tab @code{INTEGER(4) A} @tab @code{INTEGER(4)} @tab GNU extension
8095 @item @code{KISHFT(A)} @tab @code{INTEGER(8) A} @tab @code{INTEGER(8)} @tab GNU extension
8098 @item @emph{See also}:
8105 @section @code{ISHFTC} --- Shift bits circularly
8111 @cindex bits, shift circular
8114 @item @emph{Description}:
8115 @code{ISHFTC} returns a value corresponding to @var{I} with the
8116 rightmost @var{SIZE} bits shifted circularly @var{SHIFT} places; that
8117 is, bits shifted out one end are shifted into the opposite end. A value
8118 of @var{SHIFT} greater than zero corresponds to a left shift, a value of
8119 zero corresponds to no shift, and a value less than zero corresponds to
8120 a right shift. The absolute value of @var{SHIFT} must be less than
8121 @var{SIZE}. If the @var{SIZE} argument is omitted, it is taken to be
8122 equivalent to @code{BIT_SIZE(I)}.
8124 @item @emph{Standard}:
8125 Fortran 95 and later, has overloads that are GNU extensions
8130 @item @emph{Syntax}:
8131 @code{RESULT = ISHFTC(I, SHIFT [, SIZE])}
8133 @item @emph{Arguments}:
8134 @multitable @columnfractions .15 .70
8135 @item @var{I} @tab The type shall be @code{INTEGER}.
8136 @item @var{SHIFT} @tab The type shall be @code{INTEGER}.
8137 @item @var{SIZE} @tab (Optional) The type shall be @code{INTEGER};
8138 the value must be greater than zero and less than or equal to
8142 @item @emph{Return value}:
8143 The return value is of type @code{INTEGER} and of the same kind as
8146 @item @emph{Specific names}:
8147 @multitable @columnfractions .20 .20 .20 .25
8148 @item Name @tab Argument @tab Return type @tab Standard
8149 @item @code{ISHFTC(A)} @tab @code{INTEGER A} @tab @code{INTEGER} @tab Fortran 95 and later
8150 @item @code{BSHFTC(A)} @tab @code{INTEGER(1) A} @tab @code{INTEGER(1)} @tab GNU extension
8151 @item @code{IISHFTC(A)} @tab @code{INTEGER(2) A} @tab @code{INTEGER(2)} @tab GNU extension
8152 @item @code{JISHFTC(A)} @tab @code{INTEGER(4) A} @tab @code{INTEGER(4)} @tab GNU extension
8153 @item @code{KISHFTC(A)} @tab @code{INTEGER(8) A} @tab @code{INTEGER(8)} @tab GNU extension
8156 @item @emph{See also}:
8163 @section @code{ISNAN} --- Test for a NaN
8168 @item @emph{Description}:
8169 @code{ISNAN} tests whether a floating-point value is an IEEE
8171 @item @emph{Standard}:
8177 @item @emph{Syntax}:
8180 @item @emph{Arguments}:
8181 @multitable @columnfractions .15 .70
8182 @item @var{X} @tab Variable of the type @code{REAL}.
8186 @item @emph{Return value}:
8187 Returns a default-kind @code{LOGICAL}. The returned value is @code{TRUE}
8188 if @var{X} is a NaN and @code{FALSE} otherwise.
8190 @item @emph{Example}:
8197 if (isnan(x)) stop '"x" is a NaN'
8198 end program test_nan
8205 @section @code{ITIME} --- Get current local time subroutine (hour/minutes/seconds)
8207 @cindex time, current
8208 @cindex current time
8211 @item @emph{Description}:
8212 @code{IDATE(VALUES)} Fills @var{VALUES} with the numerical values at the
8213 current local time. The hour (in the range 1-24), minute (in the range 1-60),
8214 and seconds (in the range 1-60) appear in elements 1, 2, and 3 of @var{VALUES},
8217 @item @emph{Standard}:
8223 @item @emph{Syntax}:
8224 @code{CALL ITIME(VALUES)}
8226 @item @emph{Arguments}:
8227 @multitable @columnfractions .15 .70
8228 @item @var{VALUES} @tab The type shall be @code{INTEGER, DIMENSION(3)}
8229 and the kind shall be the default integer kind.
8232 @item @emph{Return value}:
8233 Does not return anything.
8236 @item @emph{Example}:
8239 integer, dimension(3) :: tarray
8244 end program test_itime
8251 @section @code{KILL} --- Send a signal to a process
8255 @item @emph{Description}:
8256 @item @emph{Standard}:
8257 Sends the signal specified by @var{SIGNAL} to the process @var{PID}.
8260 This intrinsic is provided in both subroutine and function forms; however,
8261 only one form can be used in any given program unit.
8264 Subroutine, function
8266 @item @emph{Syntax}:
8267 @multitable @columnfractions .80
8268 @item @code{CALL KILL(C, VALUE [, STATUS])}
8269 @item @code{STATUS = KILL(C, VALUE)}
8272 @item @emph{Arguments}:
8273 @multitable @columnfractions .15 .70
8274 @item @var{C} @tab Shall be a scalar @code{INTEGER}, with
8276 @item @var{VALUE} @tab Shall be a scalar @code{INTEGER}, with
8278 @item @var{STATUS} @tab (Optional) status flag of type @code{INTEGER(4)} or
8279 @code{INTEGER(8)}. Returns 0 on success, or a system-specific error code
8283 @item @emph{See also}:
8284 @ref{ABORT}, @ref{EXIT}
8290 @section @code{KIND} --- Kind of an entity
8295 @item @emph{Description}:
8296 @code{KIND(X)} returns the kind value of the entity @var{X}.
8298 @item @emph{Standard}:
8299 Fortran 95 and later
8304 @item @emph{Syntax}:
8307 @item @emph{Arguments}:
8308 @multitable @columnfractions .15 .70
8309 @item @var{X} @tab Shall be of type @code{LOGICAL}, @code{INTEGER},
8310 @code{REAL}, @code{COMPLEX} or @code{CHARACTER}.
8313 @item @emph{Return value}:
8314 The return value is a scalar of type @code{INTEGER} and of the default
8317 @item @emph{Example}:
8320 integer,parameter :: kc = kind(' ')
8321 integer,parameter :: kl = kind(.true.)
8323 print *, "The default character kind is ", kc
8324 print *, "The default logical kind is ", kl
8325 end program test_kind
8333 @section @code{LBOUND} --- Lower dimension bounds of an array
8335 @cindex array, lower bound
8338 @item @emph{Description}:
8339 Returns the lower bounds of an array, or a single lower bound
8340 along the @var{DIM} dimension.
8341 @item @emph{Standard}:
8342 Fortran 95 and later, with @var{KIND} argument Fortran 2003 and later
8347 @item @emph{Syntax}:
8348 @code{RESULT = LBOUND(ARRAY [, DIM [, KIND]])}
8350 @item @emph{Arguments}:
8351 @multitable @columnfractions .15 .70
8352 @item @var{ARRAY} @tab Shall be an array, of any type.
8353 @item @var{DIM} @tab (Optional) Shall be a scalar @code{INTEGER}.
8354 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
8355 expression indicating the kind parameter of the result.
8358 @item @emph{Return value}:
8359 The return value is of type @code{INTEGER} and of kind @var{KIND}. If
8360 @var{KIND} is absent, the return value is of default integer kind.
8361 If @var{DIM} is absent, the result is an array of the lower bounds of
8362 @var{ARRAY}. If @var{DIM} is present, the result is a scalar
8363 corresponding to the lower bound of the array along that dimension. If
8364 @var{ARRAY} is an expression rather than a whole array or array
8365 structure component, or if it has a zero extent along the relevant
8366 dimension, the lower bound is taken to be 1.
8368 @item @emph{See also}:
8369 @ref{UBOUND}, @ref{LCOBOUND}
8375 @section @code{LCOBOUND} --- Lower codimension bounds of an array
8377 @cindex coarray, lower bound
8380 @item @emph{Description}:
8381 Returns the lower bounds of a coarray, or a single lower cobound
8382 along the @var{DIM} codimension.
8383 @item @emph{Standard}:
8384 Fortran 2008 and later
8389 @item @emph{Syntax}:
8390 @code{RESULT = LCOBOUND(COARRAY [, DIM [, KIND]])}
8392 @item @emph{Arguments}:
8393 @multitable @columnfractions .15 .70
8394 @item @var{ARRAY} @tab Shall be an coarray, of any type.
8395 @item @var{DIM} @tab (Optional) Shall be a scalar @code{INTEGER}.
8396 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
8397 expression indicating the kind parameter of the result.
8400 @item @emph{Return value}:
8401 The return value is of type @code{INTEGER} and of kind @var{KIND}. If
8402 @var{KIND} is absent, the return value is of default integer kind.
8403 If @var{DIM} is absent, the result is an array of the lower cobounds of
8404 @var{COARRAY}. If @var{DIM} is present, the result is a scalar
8405 corresponding to the lower cobound of the array along that codimension.
8407 @item @emph{See also}:
8408 @ref{UCOBOUND}, @ref{LBOUND}
8414 @section @code{LEADZ} --- Number of leading zero bits of an integer
8419 @item @emph{Description}:
8420 @code{LEADZ} returns the number of leading zero bits of an integer.
8422 @item @emph{Standard}:
8423 Fortran 2008 and later
8428 @item @emph{Syntax}:
8429 @code{RESULT = LEADZ(I)}
8431 @item @emph{Arguments}:
8432 @multitable @columnfractions .15 .70
8433 @item @var{I} @tab Shall be of type @code{INTEGER}.
8436 @item @emph{Return value}:
8437 The type of the return value is the default @code{INTEGER}.
8438 If all the bits of @code{I} are zero, the result value is @code{BIT_SIZE(I)}.
8440 @item @emph{Example}:
8443 WRITE (*,*) BIT_SIZE(1) ! prints 32
8444 WRITE (*,*) LEADZ(1) ! prints 31
8448 @item @emph{See also}:
8449 @ref{BIT_SIZE}, @ref{TRAILZ}, @ref{POPCNT}, @ref{POPPAR}
8455 @section @code{LEN} --- Length of a character entity
8457 @cindex string, length
8460 @item @emph{Description}:
8461 Returns the length of a character string. If @var{STRING} is an array,
8462 the length of an element of @var{STRING} is returned. Note that
8463 @var{STRING} need not be defined when this intrinsic is invoked, since
8464 only the length, not the content, of @var{STRING} is needed.
8466 @item @emph{Standard}:
8467 Fortran 77 and later, with @var{KIND} argument Fortran 2003 and later
8472 @item @emph{Syntax}:
8473 @code{L = LEN(STRING [, KIND])}
8475 @item @emph{Arguments}:
8476 @multitable @columnfractions .15 .70
8477 @item @var{STRING} @tab Shall be a scalar or array of type
8478 @code{CHARACTER}, with @code{INTENT(IN)}
8479 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
8480 expression indicating the kind parameter of the result.
8483 @item @emph{Return value}:
8484 The return value is of type @code{INTEGER} and of kind @var{KIND}. If
8485 @var{KIND} is absent, the return value is of default integer kind.
8488 @item @emph{Specific names}:
8489 @multitable @columnfractions .20 .20 .20 .25
8490 @item Name @tab Argument @tab Return type @tab Standard
8491 @item @code{LEN(STRING)} @tab @code{CHARACTER} @tab @code{INTEGER} @tab Fortran 77 and later
8495 @item @emph{See also}:
8496 @ref{LEN_TRIM}, @ref{ADJUSTL}, @ref{ADJUSTR}
8502 @section @code{LEN_TRIM} --- Length of a character entity without trailing blank characters
8504 @cindex string, length, without trailing whitespace
8507 @item @emph{Description}:
8508 Returns the length of a character string, ignoring any trailing blanks.
8510 @item @emph{Standard}:
8511 Fortran 95 and later, with @var{KIND} argument Fortran 2003 and later
8516 @item @emph{Syntax}:
8517 @code{RESULT = LEN_TRIM(STRING [, KIND])}
8519 @item @emph{Arguments}:
8520 @multitable @columnfractions .15 .70
8521 @item @var{STRING} @tab Shall be a scalar of type @code{CHARACTER},
8522 with @code{INTENT(IN)}
8523 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
8524 expression indicating the kind parameter of the result.
8527 @item @emph{Return value}:
8528 The return value is of type @code{INTEGER} and of kind @var{KIND}. If
8529 @var{KIND} is absent, the return value is of default integer kind.
8531 @item @emph{See also}:
8532 @ref{LEN}, @ref{ADJUSTL}, @ref{ADJUSTR}
8538 @section @code{LGE} --- Lexical greater than or equal
8540 @cindex lexical comparison of strings
8541 @cindex string, comparison
8544 @item @emph{Description}:
8545 Determines whether one string is lexically greater than or equal to
8546 another string, where the two strings are interpreted as containing
8547 ASCII character codes. If the String A and String B are not the same
8548 length, the shorter is compared as if spaces were appended to it to form
8549 a value that has the same length as the longer.
8551 In general, the lexical comparison intrinsics @code{LGE}, @code{LGT},
8552 @code{LLE}, and @code{LLT} differ from the corresponding intrinsic
8553 operators @code{.GE.}, @code{.GT.}, @code{.LE.}, and @code{.LT.}, in
8554 that the latter use the processor's character ordering (which is not
8555 ASCII on some targets), whereas the former always use the ASCII
8558 @item @emph{Standard}:
8559 Fortran 77 and later
8564 @item @emph{Syntax}:
8565 @code{RESULT = LGE(STRING_A, STRING_B)}
8567 @item @emph{Arguments}:
8568 @multitable @columnfractions .15 .70
8569 @item @var{STRING_A} @tab Shall be of default @code{CHARACTER} type.
8570 @item @var{STRING_B} @tab Shall be of default @code{CHARACTER} type.
8573 @item @emph{Return value}:
8574 Returns @code{.TRUE.} if @code{STRING_A >= STRING_B}, and @code{.FALSE.}
8575 otherwise, based on the ASCII ordering.
8577 @item @emph{Specific names}:
8578 @multitable @columnfractions .20 .20 .20 .25
8579 @item Name @tab Argument @tab Return type @tab Standard
8580 @item @code{LGE(STRING_A, STRING_B)} @tab @code{CHARACTER} @tab @code{LOGICAL} @tab Fortran 77 and later
8583 @item @emph{See also}:
8584 @ref{LGT}, @ref{LLE}, @ref{LLT}
8590 @section @code{LGT} --- Lexical greater than
8592 @cindex lexical comparison of strings
8593 @cindex string, comparison
8596 @item @emph{Description}:
8597 Determines whether one string is lexically greater than another string,
8598 where the two strings are interpreted as containing ASCII character
8599 codes. If the String A and String B are not the same length, the
8600 shorter is compared as if spaces were appended to it to form a value
8601 that has the same length as the longer.
8603 In general, the lexical comparison intrinsics @code{LGE}, @code{LGT},
8604 @code{LLE}, and @code{LLT} differ from the corresponding intrinsic
8605 operators @code{.GE.}, @code{.GT.}, @code{.LE.}, and @code{.LT.}, in
8606 that the latter use the processor's character ordering (which is not
8607 ASCII on some targets), whereas the former always use the ASCII
8610 @item @emph{Standard}:
8611 Fortran 77 and later
8616 @item @emph{Syntax}:
8617 @code{RESULT = LGT(STRING_A, STRING_B)}
8619 @item @emph{Arguments}:
8620 @multitable @columnfractions .15 .70
8621 @item @var{STRING_A} @tab Shall be of default @code{CHARACTER} type.
8622 @item @var{STRING_B} @tab Shall be of default @code{CHARACTER} type.
8625 @item @emph{Return value}:
8626 Returns @code{.TRUE.} if @code{STRING_A > STRING_B}, and @code{.FALSE.}
8627 otherwise, based on the ASCII ordering.
8629 @item @emph{Specific names}:
8630 @multitable @columnfractions .20 .20 .20 .25
8631 @item Name @tab Argument @tab Return type @tab Standard
8632 @item @code{LGT(STRING_A, STRING_B)} @tab @code{CHARACTER} @tab @code{LOGICAL} @tab Fortran 77 and later
8635 @item @emph{See also}:
8636 @ref{LGE}, @ref{LLE}, @ref{LLT}
8642 @section @code{LINK} --- Create a hard link
8644 @cindex file system, create link
8645 @cindex file system, hard link
8648 @item @emph{Description}:
8649 Makes a (hard) link from file @var{PATH1} to @var{PATH2}. A null
8650 character (@code{CHAR(0)}) can be used to mark the end of the names in
8651 @var{PATH1} and @var{PATH2}; otherwise, trailing blanks in the file
8652 names are ignored. If the @var{STATUS} argument is supplied, it
8653 contains 0 on success or a nonzero error code upon return; see
8656 This intrinsic is provided in both subroutine and function forms;
8657 however, only one form can be used in any given program unit.
8659 @item @emph{Standard}:
8663 Subroutine, function
8665 @item @emph{Syntax}:
8666 @multitable @columnfractions .80
8667 @item @code{CALL LINK(PATH1, PATH2 [, STATUS])}
8668 @item @code{STATUS = LINK(PATH1, PATH2)}
8671 @item @emph{Arguments}:
8672 @multitable @columnfractions .15 .70
8673 @item @var{PATH1} @tab Shall be of default @code{CHARACTER} type.
8674 @item @var{PATH2} @tab Shall be of default @code{CHARACTER} type.
8675 @item @var{STATUS} @tab (Optional) Shall be of default @code{INTEGER} type.
8678 @item @emph{See also}:
8679 @ref{SYMLNK}, @ref{UNLINK}
8685 @section @code{LLE} --- Lexical less than or equal
8687 @cindex lexical comparison of strings
8688 @cindex string, comparison
8691 @item @emph{Description}:
8692 Determines whether one string is lexically less than or equal to another
8693 string, where the two strings are interpreted as containing ASCII
8694 character codes. If the String A and String B are not the same length,
8695 the shorter is compared as if spaces were appended to it to form a value
8696 that has the same length as the longer.
8698 In general, the lexical comparison intrinsics @code{LGE}, @code{LGT},
8699 @code{LLE}, and @code{LLT} differ from the corresponding intrinsic
8700 operators @code{.GE.}, @code{.GT.}, @code{.LE.}, and @code{.LT.}, in
8701 that the latter use the processor's character ordering (which is not
8702 ASCII on some targets), whereas the former always use the ASCII
8705 @item @emph{Standard}:
8706 Fortran 77 and later
8711 @item @emph{Syntax}:
8712 @code{RESULT = LLE(STRING_A, STRING_B)}
8714 @item @emph{Arguments}:
8715 @multitable @columnfractions .15 .70
8716 @item @var{STRING_A} @tab Shall be of default @code{CHARACTER} type.
8717 @item @var{STRING_B} @tab Shall be of default @code{CHARACTER} type.
8720 @item @emph{Return value}:
8721 Returns @code{.TRUE.} if @code{STRING_A <= STRING_B}, and @code{.FALSE.}
8722 otherwise, based on the ASCII ordering.
8724 @item @emph{Specific names}:
8725 @multitable @columnfractions .20 .20 .20 .25
8726 @item Name @tab Argument @tab Return type @tab Standard
8727 @item @code{LLE(STRING_A, STRING_B)} @tab @code{CHARACTER} @tab @code{LOGICAL} @tab Fortran 77 and later
8730 @item @emph{See also}:
8731 @ref{LGE}, @ref{LGT}, @ref{LLT}
8737 @section @code{LLT} --- Lexical less than
8739 @cindex lexical comparison of strings
8740 @cindex string, comparison
8743 @item @emph{Description}:
8744 Determines whether one string is lexically less than another string,
8745 where the two strings are interpreted as containing ASCII character
8746 codes. If the String A and String B are not the same length, the
8747 shorter is compared as if spaces were appended to it to form a value
8748 that has the same length as the longer.
8750 In general, the lexical comparison intrinsics @code{LGE}, @code{LGT},
8751 @code{LLE}, and @code{LLT} differ from the corresponding intrinsic
8752 operators @code{.GE.}, @code{.GT.}, @code{.LE.}, and @code{.LT.}, in
8753 that the latter use the processor's character ordering (which is not
8754 ASCII on some targets), whereas the former always use the ASCII
8757 @item @emph{Standard}:
8758 Fortran 77 and later
8763 @item @emph{Syntax}:
8764 @code{RESULT = LLT(STRING_A, STRING_B)}
8766 @item @emph{Arguments}:
8767 @multitable @columnfractions .15 .70
8768 @item @var{STRING_A} @tab Shall be of default @code{CHARACTER} type.
8769 @item @var{STRING_B} @tab Shall be of default @code{CHARACTER} type.
8772 @item @emph{Return value}:
8773 Returns @code{.TRUE.} if @code{STRING_A < STRING_B}, and @code{.FALSE.}
8774 otherwise, based on the ASCII ordering.
8776 @item @emph{Specific names}:
8777 @multitable @columnfractions .20 .20 .20 .25
8778 @item Name @tab Argument @tab Return type @tab Standard
8779 @item @code{LLT(STRING_A, STRING_B)} @tab @code{CHARACTER} @tab @code{LOGICAL} @tab Fortran 77 and later
8782 @item @emph{See also}:
8783 @ref{LGE}, @ref{LGT}, @ref{LLE}
8789 @section @code{LNBLNK} --- Index of the last non-blank character in a string
8791 @cindex string, find non-blank character
8794 @item @emph{Description}:
8795 Returns the length of a character string, ignoring any trailing blanks.
8796 This is identical to the standard @code{LEN_TRIM} intrinsic, and is only
8797 included for backwards compatibility.
8799 @item @emph{Standard}:
8805 @item @emph{Syntax}:
8806 @code{RESULT = LNBLNK(STRING)}
8808 @item @emph{Arguments}:
8809 @multitable @columnfractions .15 .70
8810 @item @var{STRING} @tab Shall be a scalar of type @code{CHARACTER},
8811 with @code{INTENT(IN)}
8814 @item @emph{Return value}:
8815 The return value is of @code{INTEGER(kind=4)} type.
8817 @item @emph{See also}:
8818 @ref{INDEX intrinsic}, @ref{LEN_TRIM}
8824 @section @code{LOC} --- Returns the address of a variable
8826 @cindex location of a variable in memory
8829 @item @emph{Description}:
8830 @code{LOC(X)} returns the address of @var{X} as an integer.
8832 @item @emph{Standard}:
8838 @item @emph{Syntax}:
8839 @code{RESULT = LOC(X)}
8841 @item @emph{Arguments}:
8842 @multitable @columnfractions .15 .70
8843 @item @var{X} @tab Variable of any type.
8846 @item @emph{Return value}:
8847 The return value is of type @code{INTEGER}, with a @code{KIND}
8848 corresponding to the size (in bytes) of a memory address on the target
8851 @item @emph{Example}:
8858 end program test_loc
8865 @section @code{LOG} --- Natural logarithm function
8872 @cindex exponential function, inverse
8873 @cindex logarithm function
8874 @cindex natural logarithm function
8877 @item @emph{Description}:
8878 @code{LOG(X)} computes the natural logarithm of @var{X}, i.e. the
8879 logarithm to the base @math{e}.
8881 @item @emph{Standard}:
8882 Fortran 77 and later
8887 @item @emph{Syntax}:
8888 @code{RESULT = LOG(X)}
8890 @item @emph{Arguments}:
8891 @multitable @columnfractions .15 .70
8892 @item @var{X} @tab The type shall be @code{REAL} or
8896 @item @emph{Return value}:
8897 The return value is of type @code{REAL} or @code{COMPLEX}.
8898 The kind type parameter is the same as @var{X}.
8899 If @var{X} is @code{COMPLEX}, the imaginary part @math{\omega} is in the range
8900 @math{-\pi < \omega \leq \pi}.
8902 @item @emph{Example}:
8905 real(8) :: x = 2.7182818284590451_8
8906 complex :: z = (1.0, 2.0)
8907 x = log(x) ! will yield (approximately) 1
8909 end program test_log
8912 @item @emph{Specific names}:
8913 @multitable @columnfractions .20 .20 .20 .25
8914 @item Name @tab Argument @tab Return type @tab Standard
8915 @item @code{ALOG(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab f95, gnu
8916 @item @code{DLOG(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab f95, gnu
8917 @item @code{CLOG(X)} @tab @code{COMPLEX(4) X} @tab @code{COMPLEX(4)} @tab f95, gnu
8918 @item @code{ZLOG(X)} @tab @code{COMPLEX(8) X} @tab @code{COMPLEX(8)} @tab f95, gnu
8919 @item @code{CDLOG(X)} @tab @code{COMPLEX(8) X} @tab @code{COMPLEX(8)} @tab f95, gnu
8926 @section @code{LOG10} --- Base 10 logarithm function
8930 @cindex exponential function, inverse
8931 @cindex logarithm function with base 10
8932 @cindex base 10 logarithm function
8935 @item @emph{Description}:
8936 @code{LOG10(X)} computes the base 10 logarithm of @var{X}.
8938 @item @emph{Standard}:
8939 Fortran 77 and later
8944 @item @emph{Syntax}:
8945 @code{RESULT = LOG10(X)}
8947 @item @emph{Arguments}:
8948 @multitable @columnfractions .15 .70
8949 @item @var{X} @tab The type shall be @code{REAL}.
8952 @item @emph{Return value}:
8953 The return value is of type @code{REAL} or @code{COMPLEX}.
8954 The kind type parameter is the same as @var{X}.
8956 @item @emph{Example}:
8959 real(8) :: x = 10.0_8
8961 end program test_log10
8964 @item @emph{Specific names}:
8965 @multitable @columnfractions .20 .20 .20 .25
8966 @item Name @tab Argument @tab Return type @tab Standard
8967 @item @code{ALOG10(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab Fortran 95 and later
8968 @item @code{DLOG10(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab Fortran 95 and later
8975 @section @code{LOG_GAMMA} --- Logarithm of the Gamma function
8980 @cindex Gamma function, logarithm of
8983 @item @emph{Description}:
8984 @code{LOG_GAMMA(X)} computes the natural logarithm of the absolute value
8985 of the Gamma (@math{\Gamma}) function.
8987 @item @emph{Standard}:
8988 Fortran 2008 and later
8993 @item @emph{Syntax}:
8994 @code{X = LOG_GAMMA(X)}
8996 @item @emph{Arguments}:
8997 @multitable @columnfractions .15 .70
8998 @item @var{X} @tab Shall be of type @code{REAL} and neither zero
8999 nor a negative integer.
9002 @item @emph{Return value}:
9003 The return value is of type @code{REAL} of the same kind as @var{X}.
9005 @item @emph{Example}:
9007 program test_log_gamma
9009 x = lgamma(x) ! returns 0.0
9010 end program test_log_gamma
9013 @item @emph{Specific names}:
9014 @multitable @columnfractions .20 .20 .20 .25
9015 @item Name @tab Argument @tab Return type @tab Standard
9016 @item @code{LGAMMA(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab GNU Extension
9017 @item @code{ALGAMA(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab GNU Extension
9018 @item @code{DLGAMA(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU Extension
9021 @item @emph{See also}:
9022 Gamma function: @ref{GAMMA}
9029 @section @code{LOGICAL} --- Convert to logical type
9031 @cindex conversion, to logical
9034 @item @emph{Description}:
9035 Converts one kind of @code{LOGICAL} variable to another.
9037 @item @emph{Standard}:
9038 Fortran 95 and later
9043 @item @emph{Syntax}:
9044 @code{RESULT = LOGICAL(L [, KIND])}
9046 @item @emph{Arguments}:
9047 @multitable @columnfractions .15 .70
9048 @item @var{L} @tab The type shall be @code{LOGICAL}.
9049 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
9050 expression indicating the kind parameter of the result.
9053 @item @emph{Return value}:
9054 The return value is a @code{LOGICAL} value equal to @var{L}, with a
9055 kind corresponding to @var{KIND}, or of the default logical kind if
9056 @var{KIND} is not given.
9058 @item @emph{See also}:
9059 @ref{INT}, @ref{REAL}, @ref{CMPLX}
9065 @section @code{LONG} --- Convert to integer type
9067 @cindex conversion, to integer
9070 @item @emph{Description}:
9071 Convert to a @code{KIND=4} integer type, which is the same size as a C
9072 @code{long} integer. This is equivalent to the standard @code{INT}
9073 intrinsic with an optional argument of @code{KIND=4}, and is only
9074 included for backwards compatibility.
9076 @item @emph{Standard}:
9082 @item @emph{Syntax}:
9083 @code{RESULT = LONG(A)}
9085 @item @emph{Arguments}:
9086 @multitable @columnfractions .15 .70
9087 @item @var{A} @tab Shall be of type @code{INTEGER},
9088 @code{REAL}, or @code{COMPLEX}.
9091 @item @emph{Return value}:
9092 The return value is a @code{INTEGER(4)} variable.
9094 @item @emph{See also}:
9095 @ref{INT}, @ref{INT2}, @ref{INT8}
9101 @section @code{LSHIFT} --- Left shift bits
9103 @cindex bits, shift left
9106 @item @emph{Description}:
9107 @code{LSHIFT} returns a value corresponding to @var{I} with all of the
9108 bits shifted left by @var{SHIFT} places. If the absolute value of
9109 @var{SHIFT} is greater than @code{BIT_SIZE(I)}, the value is undefined.
9110 Bits shifted out from the left end are lost; zeros are shifted in from
9113 This function has been superseded by the @code{ISHFT} intrinsic, which
9114 is standard in Fortran 95 and later, and the @code{SHIFTL} intrinsic,
9115 which is standard in Fortran 2008 and later.
9117 @item @emph{Standard}:
9123 @item @emph{Syntax}:
9124 @code{RESULT = LSHIFT(I, SHIFT)}
9126 @item @emph{Arguments}:
9127 @multitable @columnfractions .15 .70
9128 @item @var{I} @tab The type shall be @code{INTEGER}.
9129 @item @var{SHIFT} @tab The type shall be @code{INTEGER}.
9132 @item @emph{Return value}:
9133 The return value is of type @code{INTEGER} and of the same kind as
9136 @item @emph{See also}:
9137 @ref{ISHFT}, @ref{ISHFTC}, @ref{RSHIFT}, @ref{SHIFTA}, @ref{SHIFTL},
9145 @section @code{LSTAT} --- Get file status
9147 @cindex file system, file status
9150 @item @emph{Description}:
9151 @code{LSTAT} is identical to @ref{STAT}, except that if path is a
9152 symbolic link, then the link itself is statted, not the file that it
9155 The elements in @code{VALUES} are the same as described by @ref{STAT}.
9157 This intrinsic is provided in both subroutine and function forms;
9158 however, only one form can be used in any given program unit.
9160 @item @emph{Standard}:
9164 Subroutine, function
9166 @item @emph{Syntax}:
9167 @multitable @columnfractions .80
9168 @item @code{CALL LSTAT(NAME, VALUES [, STATUS])}
9169 @item @code{STATUS = LSTAT(NAME, VALUES)}
9172 @item @emph{Arguments}:
9173 @multitable @columnfractions .15 .70
9174 @item @var{NAME} @tab The type shall be @code{CHARACTER} of the default
9175 kind, a valid path within the file system.
9176 @item @var{VALUES} @tab The type shall be @code{INTEGER(4), DIMENSION(13)}.
9177 @item @var{STATUS} @tab (Optional) status flag of type @code{INTEGER(4)}.
9178 Returns 0 on success and a system specific error code otherwise.
9181 @item @emph{Example}:
9182 See @ref{STAT} for an example.
9184 @item @emph{See also}:
9185 To stat an open file: @ref{FSTAT}, to stat a file: @ref{STAT}
9191 @section @code{LTIME} --- Convert time to local time info
9193 @cindex time, conversion to local time info
9196 @item @emph{Description}:
9197 Given a system time value @var{TIME} (as provided by the @code{TIME8}
9198 intrinsic), fills @var{VALUES} with values extracted from it appropriate
9199 to the local time zone using @code{localtime(3)}.
9201 @item @emph{Standard}:
9207 @item @emph{Syntax}:
9208 @code{CALL LTIME(TIME, VALUES)}
9210 @item @emph{Arguments}:
9211 @multitable @columnfractions .15 .70
9212 @item @var{TIME} @tab An @code{INTEGER} scalar expression
9213 corresponding to a system time, with @code{INTENT(IN)}.
9214 @item @var{VALUES} @tab A default @code{INTEGER} array with 9 elements,
9215 with @code{INTENT(OUT)}.
9218 @item @emph{Return value}:
9219 The elements of @var{VALUES} are assigned as follows:
9221 @item Seconds after the minute, range 0--59 or 0--61 to allow for leap
9223 @item Minutes after the hour, range 0--59
9224 @item Hours past midnight, range 0--23
9225 @item Day of month, range 0--31
9226 @item Number of months since January, range 0--12
9227 @item Years since 1900
9228 @item Number of days since Sunday, range 0--6
9229 @item Days since January 1
9230 @item Daylight savings indicator: positive if daylight savings is in
9231 effect, zero if not, and negative if the information is not available.
9234 @item @emph{See also}:
9235 @ref{CTIME}, @ref{GMTIME}, @ref{TIME}, @ref{TIME8}
9242 @section @code{MALLOC} --- Allocate dynamic memory
9244 @cindex pointer, cray
9247 @item @emph{Description}:
9248 @code{MALLOC(SIZE)} allocates @var{SIZE} bytes of dynamic memory and
9249 returns the address of the allocated memory. The @code{MALLOC} intrinsic
9250 is an extension intended to be used with Cray pointers, and is provided
9251 in GNU Fortran to allow the user to compile legacy code. For new code
9252 using Fortran 95 pointers, the memory allocation intrinsic is
9255 @item @emph{Standard}:
9261 @item @emph{Syntax}:
9262 @code{PTR = MALLOC(SIZE)}
9264 @item @emph{Arguments}:
9265 @multitable @columnfractions .15 .70
9266 @item @var{SIZE} @tab The type shall be @code{INTEGER}.
9269 @item @emph{Return value}:
9270 The return value is of type @code{INTEGER(K)}, with @var{K} such that
9271 variables of type @code{INTEGER(K)} have the same size as
9272 C pointers (@code{sizeof(void *)}).
9274 @item @emph{Example}:
9275 The following example demonstrates the use of @code{MALLOC} and
9276 @code{FREE} with Cray pointers.
9285 ptr_x = malloc(20*8)
9287 x(i) = sqrt(1.0d0 / i)
9295 end program test_malloc
9298 @item @emph{See also}:
9305 @section @code{MASKL} --- Left justified mask
9307 @cindex mask, left justified
9310 @item @emph{Description}:
9311 @code{MASKL(I[, KIND])} has its leftmost @var{I} bits set to 1, and the
9312 remaining bits set to 0.
9314 @item @emph{Standard}:
9315 Fortran 2008 and later
9320 @item @emph{Syntax}:
9321 @code{RESULT = MASKL(I[, KIND])}
9323 @item @emph{Arguments}:
9324 @multitable @columnfractions .15 .70
9325 @item @var{I} @tab Shall be of type @code{INTEGER}.
9326 @item @var{KIND} @tab Shall be a scalar constant expression of type
9330 @item @emph{Return value}:
9331 The return value is of type @code{INTEGER}. If @var{KIND} is present, it
9332 specifies the kind value of the return type; otherwise, it is of the
9333 default integer kind.
9335 @item @emph{See also}:
9342 @section @code{MASKR} --- Right justified mask
9344 @cindex mask, right justified
9347 @item @emph{Description}:
9348 @code{MASKL(I[, KIND])} has its rightmost @var{I} bits set to 1, and the
9349 remaining bits set to 0.
9351 @item @emph{Standard}:
9352 Fortran 2008 and later
9357 @item @emph{Syntax}:
9358 @code{RESULT = MASKR(I[, KIND])}
9360 @item @emph{Arguments}:
9361 @multitable @columnfractions .15 .70
9362 @item @var{I} @tab Shall be of type @code{INTEGER}.
9363 @item @var{KIND} @tab Shall be a scalar constant expression of type
9367 @item @emph{Return value}:
9368 The return value is of type @code{INTEGER}. If @var{KIND} is present, it
9369 specifies the kind value of the return type; otherwise, it is of the
9370 default integer kind.
9372 @item @emph{See also}:
9379 @section @code{MATMUL} --- matrix multiplication
9381 @cindex matrix multiplication
9382 @cindex product, matrix
9385 @item @emph{Description}:
9386 Performs a matrix multiplication on numeric or logical arguments.
9388 @item @emph{Standard}:
9389 Fortran 95 and later
9392 Transformational function
9394 @item @emph{Syntax}:
9395 @code{RESULT = MATMUL(MATRIX_A, MATRIX_B)}
9397 @item @emph{Arguments}:
9398 @multitable @columnfractions .15 .70
9399 @item @var{MATRIX_A} @tab An array of @code{INTEGER},
9400 @code{REAL}, @code{COMPLEX}, or @code{LOGICAL} type, with a rank of
9402 @item @var{MATRIX_B} @tab An array of @code{INTEGER},
9403 @code{REAL}, or @code{COMPLEX} type if @var{MATRIX_A} is of a numeric
9404 type; otherwise, an array of @code{LOGICAL} type. The rank shall be one
9405 or two, and the first (or only) dimension of @var{MATRIX_B} shall be
9406 equal to the last (or only) dimension of @var{MATRIX_A}.
9409 @item @emph{Return value}:
9410 The matrix product of @var{MATRIX_A} and @var{MATRIX_B}. The type and
9411 kind of the result follow the usual type and kind promotion rules, as
9412 for the @code{*} or @code{.AND.} operators.
9414 @item @emph{See also}:
9420 @section @code{MAX} --- Maximum value of an argument list
9427 @cindex maximum value
9430 @item @emph{Description}:
9431 Returns the argument with the largest (most positive) value.
9433 @item @emph{Standard}:
9434 Fortran 77 and later
9439 @item @emph{Syntax}:
9440 @code{RESULT = MAX(A1, A2 [, A3 [, ...]])}
9442 @item @emph{Arguments}:
9443 @multitable @columnfractions .15 .70
9444 @item @var{A1} @tab The type shall be @code{INTEGER} or
9446 @item @var{A2}, @var{A3}, ... @tab An expression of the same type and kind
9447 as @var{A1}. (As a GNU extension, arguments of different kinds are
9451 @item @emph{Return value}:
9452 The return value corresponds to the maximum value among the arguments,
9453 and has the same type and kind as the first argument.
9455 @item @emph{Specific names}:
9456 @multitable @columnfractions .20 .20 .20 .25
9457 @item Name @tab Argument @tab Return type @tab Standard
9458 @item @code{MAX0(A1)} @tab @code{INTEGER(4) A1} @tab @code{INTEGER(4)} @tab Fortran 77 and later
9459 @item @code{AMAX0(A1)} @tab @code{INTEGER(4) A1} @tab @code{REAL(MAX(X))} @tab Fortran 77 and later
9460 @item @code{MAX1(A1)} @tab @code{REAL A1} @tab @code{INT(MAX(X))} @tab Fortran 77 and later
9461 @item @code{AMAX1(A1)} @tab @code{REAL(4) A1} @tab @code{REAL(4)} @tab Fortran 77 and later
9462 @item @code{DMAX1(A1)} @tab @code{REAL(8) A1} @tab @code{REAL(8)} @tab Fortran 77 and later
9465 @item @emph{See also}:
9466 @ref{MAXLOC} @ref{MAXVAL}, @ref{MIN}
9473 @section @code{MAXEXPONENT} --- Maximum exponent of a real kind
9474 @fnindex MAXEXPONENT
9475 @cindex model representation, maximum exponent
9478 @item @emph{Description}:
9479 @code{MAXEXPONENT(X)} returns the maximum exponent in the model of the
9482 @item @emph{Standard}:
9483 Fortran 95 and later
9488 @item @emph{Syntax}:
9489 @code{RESULT = MAXEXPONENT(X)}
9491 @item @emph{Arguments}:
9492 @multitable @columnfractions .15 .70
9493 @item @var{X} @tab Shall be of type @code{REAL}.
9496 @item @emph{Return value}:
9497 The return value is of type @code{INTEGER} and of the default integer
9500 @item @emph{Example}:
9506 print *, minexponent(x), maxexponent(x)
9507 print *, minexponent(y), maxexponent(y)
9508 end program exponents
9515 @section @code{MAXLOC} --- Location of the maximum value within an array
9517 @cindex array, location of maximum element
9520 @item @emph{Description}:
9521 Determines the location of the element in the array with the maximum
9522 value, or, if the @var{DIM} argument is supplied, determines the
9523 locations of the maximum element along each row of the array in the
9524 @var{DIM} direction. If @var{MASK} is present, only the elements for
9525 which @var{MASK} is @code{.TRUE.} are considered. If more than one
9526 element in the array has the maximum value, the location returned is
9527 that of the first such element in array element order. If the array has
9528 zero size, or all of the elements of @var{MASK} are @code{.FALSE.}, then
9529 the result is an array of zeroes. Similarly, if @var{DIM} is supplied
9530 and all of the elements of @var{MASK} along a given row are zero, the
9531 result value for that row is zero.
9533 @item @emph{Standard}:
9534 Fortran 95 and later
9537 Transformational function
9539 @item @emph{Syntax}:
9540 @multitable @columnfractions .80
9541 @item @code{RESULT = MAXLOC(ARRAY, DIM [, MASK])}
9542 @item @code{RESULT = MAXLOC(ARRAY [, MASK])}
9545 @item @emph{Arguments}:
9546 @multitable @columnfractions .15 .70
9547 @item @var{ARRAY} @tab Shall be an array of type @code{INTEGER} or
9549 @item @var{DIM} @tab (Optional) Shall be a scalar of type
9550 @code{INTEGER}, with a value between one and the rank of @var{ARRAY},
9551 inclusive. It may not be an optional dummy argument.
9552 @item @var{MASK} @tab Shall be an array of type @code{LOGICAL},
9553 and conformable with @var{ARRAY}.
9556 @item @emph{Return value}:
9557 If @var{DIM} is absent, the result is a rank-one array with a length
9558 equal to the rank of @var{ARRAY}. If @var{DIM} is present, the result
9559 is an array with a rank one less than the rank of @var{ARRAY}, and a
9560 size corresponding to the size of @var{ARRAY} with the @var{DIM}
9561 dimension removed. If @var{DIM} is present and @var{ARRAY} has a rank
9562 of one, the result is a scalar. In all cases, the result is of default
9563 @code{INTEGER} type.
9565 @item @emph{See also}:
9566 @ref{MAX}, @ref{MAXVAL}
9573 @section @code{MAXVAL} --- Maximum value of an array
9575 @cindex array, maximum value
9576 @cindex maximum value
9579 @item @emph{Description}:
9580 Determines the maximum value of the elements in an array value, or, if
9581 the @var{DIM} argument is supplied, determines the maximum value along
9582 each row of the array in the @var{DIM} direction. If @var{MASK} is
9583 present, only the elements for which @var{MASK} is @code{.TRUE.} are
9584 considered. If the array has zero size, or all of the elements of
9585 @var{MASK} are @code{.FALSE.}, then the result is @code{-HUGE(ARRAY)}
9586 if @var{ARRAY} is numeric, or a string of nulls if @var{ARRAY} is of character
9589 @item @emph{Standard}:
9590 Fortran 95 and later
9593 Transformational function
9595 @item @emph{Syntax}:
9596 @multitable @columnfractions .80
9597 @item @code{RESULT = MAXVAL(ARRAY, DIM [, MASK])}
9598 @item @code{RESULT = MAXVAL(ARRAY [, MASK])}
9601 @item @emph{Arguments}:
9602 @multitable @columnfractions .15 .70
9603 @item @var{ARRAY} @tab Shall be an array of type @code{INTEGER} or
9605 @item @var{DIM} @tab (Optional) Shall be a scalar of type
9606 @code{INTEGER}, with a value between one and the rank of @var{ARRAY},
9607 inclusive. It may not be an optional dummy argument.
9608 @item @var{MASK} @tab Shall be an array of type @code{LOGICAL},
9609 and conformable with @var{ARRAY}.
9612 @item @emph{Return value}:
9613 If @var{DIM} is absent, or if @var{ARRAY} has a rank of one, the result
9614 is a scalar. If @var{DIM} is present, the result is an array with a
9615 rank one less than the rank of @var{ARRAY}, and a size corresponding to
9616 the size of @var{ARRAY} with the @var{DIM} dimension removed. In all
9617 cases, the result is of the same type and kind as @var{ARRAY}.
9619 @item @emph{See also}:
9620 @ref{MAX}, @ref{MAXLOC}
9626 @section @code{MCLOCK} --- Time function
9628 @cindex time, clock ticks
9632 @item @emph{Description}:
9633 Returns the number of clock ticks since the start of the process, based
9634 on the function @code{clock(3)} in the C standard library.
9636 This intrinsic is not fully portable, such as to systems with 32-bit
9637 @code{INTEGER} types but supporting times wider than 32 bits. Therefore,
9638 the values returned by this intrinsic might be, or become, negative, or
9639 numerically less than previous values, during a single run of the
9642 @item @emph{Standard}:
9648 @item @emph{Syntax}:
9649 @code{RESULT = MCLOCK()}
9651 @item @emph{Return value}:
9652 The return value is a scalar of type @code{INTEGER(4)}, equal to the
9653 number of clock ticks since the start of the process, or @code{-1} if
9654 the system does not support @code{clock(3)}.
9656 @item @emph{See also}:
9657 @ref{CTIME}, @ref{GMTIME}, @ref{LTIME}, @ref{MCLOCK}, @ref{TIME}
9664 @section @code{MCLOCK8} --- Time function (64-bit)
9666 @cindex time, clock ticks
9670 @item @emph{Description}:
9671 Returns the number of clock ticks since the start of the process, based
9672 on the function @code{clock(3)} in the C standard library.
9674 @emph{Warning:} this intrinsic does not increase the range of the timing
9675 values over that returned by @code{clock(3)}. On a system with a 32-bit
9676 @code{clock(3)}, @code{MCLOCK8} will return a 32-bit value, even though
9677 it is converted to a 64-bit @code{INTEGER(8)} value. That means
9678 overflows of the 32-bit value can still occur. Therefore, the values
9679 returned by this intrinsic might be or become negative or numerically
9680 less than previous values during a single run of the compiled program.
9682 @item @emph{Standard}:
9688 @item @emph{Syntax}:
9689 @code{RESULT = MCLOCK8()}
9691 @item @emph{Return value}:
9692 The return value is a scalar of type @code{INTEGER(8)}, equal to the
9693 number of clock ticks since the start of the process, or @code{-1} if
9694 the system does not support @code{clock(3)}.
9696 @item @emph{See also}:
9697 @ref{CTIME}, @ref{GMTIME}, @ref{LTIME}, @ref{MCLOCK}, @ref{TIME8}
9704 @section @code{MERGE} --- Merge variables
9706 @cindex array, merge arrays
9707 @cindex array, combine arrays
9710 @item @emph{Description}:
9711 Select values from two arrays according to a logical mask. The result
9712 is equal to @var{TSOURCE} if @var{MASK} is @code{.TRUE.}, or equal to
9713 @var{FSOURCE} if it is @code{.FALSE.}.
9715 @item @emph{Standard}:
9716 Fortran 95 and later
9721 @item @emph{Syntax}:
9722 @code{RESULT = MERGE(TSOURCE, FSOURCE, MASK)}
9724 @item @emph{Arguments}:
9725 @multitable @columnfractions .15 .70
9726 @item @var{TSOURCE} @tab May be of any type.
9727 @item @var{FSOURCE} @tab Shall be of the same type and type parameters
9729 @item @var{MASK} @tab Shall be of type @code{LOGICAL}.
9732 @item @emph{Return value}:
9733 The result is of the same type and type parameters as @var{TSOURCE}.
9740 @section @code{MERGE_BITS} --- Merge of bits under mask
9745 @item @emph{Description}:
9746 @code{MERGE_BITS(I, J, MASK)} merges the bits of @var{I} and @var{J}
9747 as determined by the mask. The i-th bit of the result is equal to the
9748 i-th bit of @var{I} if the i-th bit of @var{MASK} is 1; it is equal to
9749 the i-th bit of @var{J} otherwise.
9751 @item @emph{Standard}:
9752 Fortran 2008 and later
9757 @item @emph{Syntax}:
9758 @code{RESULT = MERGE_BITS(I, J, MASK)}
9760 @item @emph{Arguments}:
9761 @multitable @columnfractions .15 .70
9762 @item @var{I} @tab Shall be of type @code{INTEGER}.
9763 @item @var{J} @tab Shall be of type @code{INTEGER} and of the same
9765 @item @var{MASK} @tab Shall be of type @code{INTEGER} and of the same
9769 @item @emph{Return value}:
9770 The result is of the same type and kind as @var{I}.
9777 @section @code{MIN} --- Minimum value of an argument list
9784 @cindex minimum value
9787 @item @emph{Description}:
9788 Returns the argument with the smallest (most negative) value.
9790 @item @emph{Standard}:
9791 Fortran 77 and later
9796 @item @emph{Syntax}:
9797 @code{RESULT = MIN(A1, A2 [, A3, ...])}
9799 @item @emph{Arguments}:
9800 @multitable @columnfractions .15 .70
9801 @item @var{A1} @tab The type shall be @code{INTEGER} or
9803 @item @var{A2}, @var{A3}, ... @tab An expression of the same type and kind
9804 as @var{A1}. (As a GNU extension, arguments of different kinds are
9808 @item @emph{Return value}:
9809 The return value corresponds to the maximum value among the arguments,
9810 and has the same type and kind as the first argument.
9812 @item @emph{Specific names}:
9813 @multitable @columnfractions .20 .20 .20 .25
9814 @item Name @tab Argument @tab Return type @tab Standard
9815 @item @code{MIN0(A1)} @tab @code{INTEGER(4) A1} @tab @code{INTEGER(4)} @tab Fortran 77 and later
9816 @item @code{AMIN0(A1)} @tab @code{INTEGER(4) A1} @tab @code{REAL(4)} @tab Fortran 77 and later
9817 @item @code{MIN1(A1)} @tab @code{REAL A1} @tab @code{INTEGER(4)} @tab Fortran 77 and later
9818 @item @code{AMIN1(A1)} @tab @code{REAL(4) A1} @tab @code{REAL(4)} @tab Fortran 77 and later
9819 @item @code{DMIN1(A1)} @tab @code{REAL(8) A1} @tab @code{REAL(8)} @tab Fortran 77 and later
9822 @item @emph{See also}:
9823 @ref{MAX}, @ref{MINLOC}, @ref{MINVAL}
9829 @section @code{MINEXPONENT} --- Minimum exponent of a real kind
9830 @fnindex MINEXPONENT
9831 @cindex model representation, minimum exponent
9834 @item @emph{Description}:
9835 @code{MINEXPONENT(X)} returns the minimum exponent in the model of the
9838 @item @emph{Standard}:
9839 Fortran 95 and later
9844 @item @emph{Syntax}:
9845 @code{RESULT = MINEXPONENT(X)}
9847 @item @emph{Arguments}:
9848 @multitable @columnfractions .15 .70
9849 @item @var{X} @tab Shall be of type @code{REAL}.
9852 @item @emph{Return value}:
9853 The return value is of type @code{INTEGER} and of the default integer
9856 @item @emph{Example}:
9857 See @code{MAXEXPONENT} for an example.
9863 @section @code{MINLOC} --- Location of the minimum value within an array
9865 @cindex array, location of minimum element
9868 @item @emph{Description}:
9869 Determines the location of the element in the array with the minimum
9870 value, or, if the @var{DIM} argument is supplied, determines the
9871 locations of the minimum element along each row of the array in the
9872 @var{DIM} direction. If @var{MASK} is present, only the elements for
9873 which @var{MASK} is @code{.TRUE.} are considered. If more than one
9874 element in the array has the minimum value, the location returned is
9875 that of the first such element in array element order. If the array has
9876 zero size, or all of the elements of @var{MASK} are @code{.FALSE.}, then
9877 the result is an array of zeroes. Similarly, if @var{DIM} is supplied
9878 and all of the elements of @var{MASK} along a given row are zero, the
9879 result value for that row is zero.
9881 @item @emph{Standard}:
9882 Fortran 95 and later
9885 Transformational function
9887 @item @emph{Syntax}:
9888 @multitable @columnfractions .80
9889 @item @code{RESULT = MINLOC(ARRAY, DIM [, MASK])}
9890 @item @code{RESULT = MINLOC(ARRAY [, MASK])}
9893 @item @emph{Arguments}:
9894 @multitable @columnfractions .15 .70
9895 @item @var{ARRAY} @tab Shall be an array of type @code{INTEGER} or
9897 @item @var{DIM} @tab (Optional) Shall be a scalar of type
9898 @code{INTEGER}, with a value between one and the rank of @var{ARRAY},
9899 inclusive. It may not be an optional dummy argument.
9900 @item @var{MASK} @tab Shall be an array of type @code{LOGICAL},
9901 and conformable with @var{ARRAY}.
9904 @item @emph{Return value}:
9905 If @var{DIM} is absent, the result is a rank-one array with a length
9906 equal to the rank of @var{ARRAY}. If @var{DIM} is present, the result
9907 is an array with a rank one less than the rank of @var{ARRAY}, and a
9908 size corresponding to the size of @var{ARRAY} with the @var{DIM}
9909 dimension removed. If @var{DIM} is present and @var{ARRAY} has a rank
9910 of one, the result is a scalar. In all cases, the result is of default
9911 @code{INTEGER} type.
9913 @item @emph{See also}:
9914 @ref{MIN}, @ref{MINVAL}
9921 @section @code{MINVAL} --- Minimum value of an array
9923 @cindex array, minimum value
9924 @cindex minimum value
9927 @item @emph{Description}:
9928 Determines the minimum value of the elements in an array value, or, if
9929 the @var{DIM} argument is supplied, determines the minimum value along
9930 each row of the array in the @var{DIM} direction. If @var{MASK} is
9931 present, only the elements for which @var{MASK} is @code{.TRUE.} are
9932 considered. If the array has zero size, or all of the elements of
9933 @var{MASK} are @code{.FALSE.}, then the result is @code{HUGE(ARRAY)} if
9934 @var{ARRAY} is numeric, or a string of @code{CHAR(255)} characters if
9935 @var{ARRAY} is of character type.
9937 @item @emph{Standard}:
9938 Fortran 95 and later
9941 Transformational function
9943 @item @emph{Syntax}:
9944 @multitable @columnfractions .80
9945 @item @code{RESULT = MINVAL(ARRAY, DIM [, MASK])}
9946 @item @code{RESULT = MINVAL(ARRAY [, MASK])}
9949 @item @emph{Arguments}:
9950 @multitable @columnfractions .15 .70
9951 @item @var{ARRAY} @tab Shall be an array of type @code{INTEGER} or
9953 @item @var{DIM} @tab (Optional) Shall be a scalar of type
9954 @code{INTEGER}, with a value between one and the rank of @var{ARRAY},
9955 inclusive. It may not be an optional dummy argument.
9956 @item @var{MASK} @tab Shall be an array of type @code{LOGICAL},
9957 and conformable with @var{ARRAY}.
9960 @item @emph{Return value}:
9961 If @var{DIM} is absent, or if @var{ARRAY} has a rank of one, the result
9962 is a scalar. If @var{DIM} is present, the result is an array with a
9963 rank one less than the rank of @var{ARRAY}, and a size corresponding to
9964 the size of @var{ARRAY} with the @var{DIM} dimension removed. In all
9965 cases, the result is of the same type and kind as @var{ARRAY}.
9967 @item @emph{See also}:
9968 @ref{MIN}, @ref{MINLOC}
9975 @section @code{MOD} --- Remainder function
9984 @cindex division, remainder
9987 @item @emph{Description}:
9988 @code{MOD(A,P)} computes the remainder of the division of A by P@.
9990 @item @emph{Standard}:
9991 Fortran 77 and later, has overloads that are GNU extensions
9996 @item @emph{Syntax}:
9997 @code{RESULT = MOD(A, P)}
9999 @item @emph{Arguments}:
10000 @multitable @columnfractions .15 .70
10001 @item @var{A} @tab Shall be a scalar of type @code{INTEGER} or @code{REAL}.
10002 @item @var{P} @tab Shall be a scalar of the same type and kind as @var{A}
10003 and not equal to zero.
10006 @item @emph{Return value}:
10007 The return value is the result of @code{A - (INT(A/P) * P)}. The type
10008 and kind of the return value is the same as that of the arguments. The
10009 returned value has the same sign as A and a magnitude less than the
10012 @item @emph{Example}:
10016 print *, mod(17.5,5.5)
10017 print *, mod(17.5d0,5.5)
10018 print *, mod(17.5,5.5d0)
10020 print *, mod(-17,3)
10021 print *, mod(-17.5,5.5)
10022 print *, mod(-17.5d0,5.5)
10023 print *, mod(-17.5,5.5d0)
10025 print *, mod(17,-3)
10026 print *, mod(17.5,-5.5)
10027 print *, mod(17.5d0,-5.5)
10028 print *, mod(17.5,-5.5d0)
10029 end program test_mod
10032 @item @emph{Specific names}:
10033 @multitable @columnfractions .20 .20 .20 .25
10034 @item Name @tab Arguments @tab Return type @tab Standard
10035 @item @code{MOD(A,P)} @tab @code{INTEGER A,P} @tab @code{INTEGER} @tab Fortran 95 and later
10036 @item @code{AMOD(A,P)} @tab @code{REAL(4) A,P} @tab @code{REAL(4)} @tab Fortran 95 and later
10037 @item @code{DMOD(A,P)} @tab @code{REAL(8) A,P} @tab @code{REAL(8)} @tab Fortran 95 and later
10038 @item @code{BMOD(A,P)} @tab @code{INTEGER(1) A,P} @tab @code{INTEGER(1)} @tab GNU extension
10039 @item @code{IMOD(A,P)} @tab @code{INTEGER(2) A,P} @tab @code{INTEGER(2)} @tab GNU extension
10040 @item @code{JMOD(A,P)} @tab @code{INTEGER(4) A,P} @tab @code{INTEGER(4)} @tab GNU extension
10041 @item @code{KMOD(A,P)} @tab @code{INTEGER(8) A,P} @tab @code{INTEGER(8)} @tab GNU extension
10044 @item @emph{See also}:
10052 @section @code{MODULO} --- Modulo function
10055 @cindex division, modulo
10058 @item @emph{Description}:
10059 @code{MODULO(A,P)} computes the @var{A} modulo @var{P}.
10061 @item @emph{Standard}:
10062 Fortran 95 and later
10064 @item @emph{Class}:
10067 @item @emph{Syntax}:
10068 @code{RESULT = MODULO(A, P)}
10070 @item @emph{Arguments}:
10071 @multitable @columnfractions .15 .70
10072 @item @var{A} @tab Shall be a scalar of type @code{INTEGER} or @code{REAL}.
10073 @item @var{P} @tab Shall be a scalar of the same type and kind as @var{A}.
10074 It shall not be zero.
10077 @item @emph{Return value}:
10078 The type and kind of the result are those of the arguments.
10080 @item If @var{A} and @var{P} are of type @code{INTEGER}:
10081 @code{MODULO(A,P)} has the value @var{R} such that @code{A=Q*P+R}, where
10082 @var{Q} is an integer and @var{R} is between 0 (inclusive) and @var{P}
10084 @item If @var{A} and @var{P} are of type @code{REAL}:
10085 @code{MODULO(A,P)} has the value of @code{A - FLOOR (A / P) * P}.
10087 The returned value has the same sign as P and a magnitude less than
10088 the magnitude of P.
10090 @item @emph{Example}:
10092 program test_modulo
10093 print *, modulo(17,3)
10094 print *, modulo(17.5,5.5)
10096 print *, modulo(-17,3)
10097 print *, modulo(-17.5,5.5)
10099 print *, modulo(17,-3)
10100 print *, modulo(17.5,-5.5)
10104 @item @emph{See also}:
10112 @section @code{MOVE_ALLOC} --- Move allocation from one object to another
10113 @fnindex MOVE_ALLOC
10114 @cindex moving allocation
10115 @cindex allocation, moving
10118 @item @emph{Description}:
10119 @code{MOVE_ALLOC(FROM, TO)} moves the allocation from @var{FROM} to
10120 @var{TO}. @var{FROM} will become deallocated in the process.
10122 @item @emph{Standard}:
10123 Fortran 2003 and later
10125 @item @emph{Class}:
10128 @item @emph{Syntax}:
10129 @code{CALL MOVE_ALLOC(FROM, TO)}
10131 @item @emph{Arguments}:
10132 @multitable @columnfractions .15 .70
10133 @item @var{FROM} @tab @code{ALLOCATABLE}, @code{INTENT(INOUT)}, may be
10134 of any type and kind.
10135 @item @var{TO} @tab @code{ALLOCATABLE}, @code{INTENT(OUT)}, shall be
10136 of the same type, kind and rank as @var{FROM}.
10139 @item @emph{Return value}:
10142 @item @emph{Example}:
10144 program test_move_alloc
10145 integer, allocatable :: a(:), b(:)
10149 call move_alloc(a, b)
10150 print *, allocated(a), allocated(b)
10152 end program test_move_alloc
10159 @section @code{MVBITS} --- Move bits from one integer to another
10168 @item @emph{Description}:
10169 Moves @var{LEN} bits from positions @var{FROMPOS} through
10170 @code{FROMPOS+LEN-1} of @var{FROM} to positions @var{TOPOS} through
10171 @code{TOPOS+LEN-1} of @var{TO}. The portion of argument @var{TO} not
10172 affected by the movement of bits is unchanged. The values of
10173 @code{FROMPOS+LEN-1} and @code{TOPOS+LEN-1} must be less than
10174 @code{BIT_SIZE(FROM)}.
10176 @item @emph{Standard}:
10177 Fortran 95 and later, has overloads that are GNU extensions
10179 @item @emph{Class}:
10180 Elemental subroutine
10182 @item @emph{Syntax}:
10183 @code{CALL MVBITS(FROM, FROMPOS, LEN, TO, TOPOS)}
10185 @item @emph{Arguments}:
10186 @multitable @columnfractions .15 .70
10187 @item @var{FROM} @tab The type shall be @code{INTEGER}.
10188 @item @var{FROMPOS} @tab The type shall be @code{INTEGER}.
10189 @item @var{LEN} @tab The type shall be @code{INTEGER}.
10190 @item @var{TO} @tab The type shall be @code{INTEGER}, of the
10191 same kind as @var{FROM}.
10192 @item @var{TOPOS} @tab The type shall be @code{INTEGER}.
10195 @item @emph{Specific names}:
10196 @multitable @columnfractions .20 .20 .20 .25
10197 @item Name @tab Argument @tab Return type @tab Standard
10198 @item @code{MVBITS(A)} @tab @code{INTEGER A} @tab @code{INTEGER} @tab Fortran 95 and later
10199 @item @code{BMVBITS(A)} @tab @code{INTEGER(1) A} @tab @code{INTEGER(1)} @tab GNU extension
10200 @item @code{IMVBITS(A)} @tab @code{INTEGER(2) A} @tab @code{INTEGER(2)} @tab GNU extension
10201 @item @code{JMVBITS(A)} @tab @code{INTEGER(4) A} @tab @code{INTEGER(4)} @tab GNU extension
10202 @item @code{KMVBITS(A)} @tab @code{INTEGER(8) A} @tab @code{INTEGER(8)} @tab GNU extension
10205 @item @emph{See also}:
10206 @ref{IBCLR}, @ref{IBSET}, @ref{IBITS}, @ref{IAND}, @ref{IOR}, @ref{IEOR}
10212 @section @code{NEAREST} --- Nearest representable number
10214 @cindex real number, nearest different
10215 @cindex floating point, nearest different
10218 @item @emph{Description}:
10219 @code{NEAREST(X, S)} returns the processor-representable number nearest
10220 to @code{X} in the direction indicated by the sign of @code{S}.
10222 @item @emph{Standard}:
10223 Fortran 95 and later
10225 @item @emph{Class}:
10228 @item @emph{Syntax}:
10229 @code{RESULT = NEAREST(X, S)}
10231 @item @emph{Arguments}:
10232 @multitable @columnfractions .15 .70
10233 @item @var{X} @tab Shall be of type @code{REAL}.
10234 @item @var{S} @tab Shall be of type @code{REAL} and
10238 @item @emph{Return value}:
10239 The return value is of the same type as @code{X}. If @code{S} is
10240 positive, @code{NEAREST} returns the processor-representable number
10241 greater than @code{X} and nearest to it. If @code{S} is negative,
10242 @code{NEAREST} returns the processor-representable number smaller than
10243 @code{X} and nearest to it.
10245 @item @emph{Example}:
10247 program test_nearest
10249 x = nearest(42.0, 1.0)
10250 y = nearest(42.0, -1.0)
10251 write (*,"(3(G20.15))") x, y, x - y
10252 end program test_nearest
10259 @section @code{NEW_LINE} --- New line character
10262 @cindex output, newline
10265 @item @emph{Description}:
10266 @code{NEW_LINE(C)} returns the new-line character.
10268 @item @emph{Standard}:
10269 Fortran 2003 and later
10271 @item @emph{Class}:
10274 @item @emph{Syntax}:
10275 @code{RESULT = NEW_LINE(C)}
10277 @item @emph{Arguments}:
10278 @multitable @columnfractions .15 .70
10279 @item @var{C} @tab The argument shall be a scalar or array of the
10280 type @code{CHARACTER}.
10283 @item @emph{Return value}:
10284 Returns a @var{CHARACTER} scalar of length one with the new-line character of
10285 the same kind as parameter @var{C}.
10287 @item @emph{Example}:
10291 write(*,'(A)') 'This is record 1.'//NEW_LINE('A')//'This is record 2.'
10292 end program newline
10299 @section @code{NINT} --- Nearest whole number
10302 @cindex rounding, nearest whole number
10305 @item @emph{Description}:
10306 @code{NINT(A)} rounds its argument to the nearest whole number.
10308 @item @emph{Standard}:
10309 Fortran 77 and later, with @var{KIND} argument Fortran 90 and later
10311 @item @emph{Class}:
10314 @item @emph{Syntax}:
10315 @code{RESULT = NINT(A [, KIND])}
10317 @item @emph{Arguments}:
10318 @multitable @columnfractions .15 .70
10319 @item @var{A} @tab The type of the argument shall be @code{REAL}.
10320 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
10321 expression indicating the kind parameter of the result.
10324 @item @emph{Return value}:
10325 Returns @var{A} with the fractional portion of its magnitude eliminated by
10326 rounding to the nearest whole number and with its sign preserved,
10327 converted to an @code{INTEGER} of the default kind.
10329 @item @emph{Example}:
10336 print *, nint(x4), idnint(x8)
10337 end program test_nint
10340 @item @emph{Specific names}:
10341 @multitable @columnfractions .20 .20 .20 .25
10342 @item Name @tab Argument @tab Return Type @tab Standard
10343 @item @code{NINT(A)} @tab @code{REAL(4) A} @tab @code{INTEGER} @tab Fortran 95 and later
10344 @item @code{IDNINT(A)} @tab @code{REAL(8) A} @tab @code{INTEGER} @tab Fortran 95 and later
10347 @item @emph{See also}:
10348 @ref{CEILING}, @ref{FLOOR}
10355 @section @code{NORM2} --- Euclidean vector norms
10357 @cindex Euclidean vector norm
10358 @cindex L2 vector norm
10359 @cindex norm, Euclidean
10362 @item @emph{Description}:
10363 Calculates the Euclidean vector norm (@math{L_2} norm) of
10364 of @var{ARRAY} along dimension @var{DIM}.
10366 @item @emph{Standard}:
10367 Fortran 2008 and later
10369 @item @emph{Class}:
10370 Transformational function
10372 @item @emph{Syntax}:
10373 @multitable @columnfractions .80
10374 @item @code{RESULT = NORM2(ARRAY[, DIM])}
10377 @item @emph{Arguments}:
10378 @multitable @columnfractions .15 .70
10379 @item @var{ARRAY} @tab Shall be an array of type @code{REAL}
10380 @item @var{DIM} @tab (Optional) shall be a scalar of type
10381 @code{INTEGER} with a value in the range from 1 to n, where n
10382 equals the rank of @var{ARRAY}.
10385 @item @emph{Return value}:
10386 The result is of the same type as @var{ARRAY}.
10388 If @var{DIM} is absent, a scalar with the square root of the sum of all
10389 elements in @var{ARRAY} squared is returned. Otherwise, an array of
10390 rank @math{n-1}, where @math{n} equals the rank of @var{ARRAY}, and a
10391 shape similar to that of @var{ARRAY} with dimension @var{DIM} dropped
10394 @item @emph{Example}:
10397 REAL :: x(5) = [ real :: 1, 2, 3, 4, 5 ]
10398 print *, NORM2(x) ! = sqrt(55.) ~ 7.416
10406 @section @code{NOT} --- Logical negation
10412 @cindex bits, negate
10413 @cindex bitwise logical not
10414 @cindex logical not, bitwise
10417 @item @emph{Description}:
10418 @code{NOT} returns the bitwise Boolean inverse of @var{I}.
10420 @item @emph{Standard}:
10421 Fortran 95 and later, has overloads that are GNU extensions
10423 @item @emph{Class}:
10426 @item @emph{Syntax}:
10427 @code{RESULT = NOT(I)}
10429 @item @emph{Arguments}:
10430 @multitable @columnfractions .15 .70
10431 @item @var{I} @tab The type shall be @code{INTEGER}.
10434 @item @emph{Return value}:
10435 The return type is @code{INTEGER}, of the same kind as the
10438 @item @emph{Specific names}:
10439 @multitable @columnfractions .20 .20 .20 .25
10440 @item Name @tab Argument @tab Return type @tab Standard
10441 @item @code{NOT(A)} @tab @code{INTEGER A} @tab @code{INTEGER} @tab Fortran 95 and later
10442 @item @code{BNOT(A)} @tab @code{INTEGER(1) A} @tab @code{INTEGER(1)} @tab GNU extension
10443 @item @code{INOT(A)} @tab @code{INTEGER(2) A} @tab @code{INTEGER(2)} @tab GNU extension
10444 @item @code{JNOT(A)} @tab @code{INTEGER(4) A} @tab @code{INTEGER(4)} @tab GNU extension
10445 @item @code{KNOT(A)} @tab @code{INTEGER(8) A} @tab @code{INTEGER(8)} @tab GNU extension
10448 @item @emph{See also}:
10449 @ref{IAND}, @ref{IEOR}, @ref{IOR}, @ref{IBITS}, @ref{IBSET}, @ref{IBCLR}
10456 @section @code{NULL} --- Function that returns an disassociated pointer
10458 @cindex pointer, status
10459 @cindex pointer, disassociated
10462 @item @emph{Description}:
10463 Returns a disassociated pointer.
10465 If @var{MOLD} is present, a disassociated pointer of the same type is
10466 returned, otherwise the type is determined by context.
10468 In Fortran 95, @var{MOLD} is optional. Please note that Fortran 2003
10469 includes cases where it is required.
10471 @item @emph{Standard}:
10472 Fortran 95 and later
10474 @item @emph{Class}:
10475 Transformational function
10477 @item @emph{Syntax}:
10478 @code{PTR => NULL([MOLD])}
10480 @item @emph{Arguments}:
10481 @multitable @columnfractions .15 .70
10482 @item @var{MOLD} @tab (Optional) shall be a pointer of any association
10483 status and of any type.
10486 @item @emph{Return value}:
10487 A disassociated pointer.
10489 @item @emph{Example}:
10491 REAL, POINTER, DIMENSION(:) :: VEC => NULL ()
10494 @item @emph{See also}:
10501 @section @code{NUM_IMAGES} --- Function that returns the number of images
10502 @fnindex NUM_IMAGES
10503 @cindex coarray, @code{NUM_IMAGES}
10504 @cindex images, number of
10507 @item @emph{Description}:
10508 Returns the number of images.
10510 @item @emph{Standard}:
10511 Fortran 2008 and later. With @var{DISTANCE} or @var{FAILED} argument,
10512 Technical Specification (TS) 18508 or later
10515 @item @emph{Class}:
10516 Transformational function
10518 @item @emph{Syntax}:
10519 @code{RESULT = NUM_IMAGES(DISTANCE, FAILED)}
10521 @item @emph{Arguments}:
10522 @multitable @columnfractions .15 .70
10523 @item @var{DISTANCE} @tab (optional, intent(in)) Nonnegative scalar integer
10524 @item @var{FAILED} @tab (optional, intent(in)) Scalar logical expression
10527 @item @emph{Return value}:
10528 Scalar default-kind integer. If @var{DISTANCE} is not present or has value 0,
10529 the number of images in the current team is returned. For values smaller or
10530 equal distance to the initial team, it returns the number of images index
10531 on the ancestor team which has a distance of @var{DISTANCE} from the invoking
10532 team. If @var{DISTANCE} is larger than the distance to the initial team, the
10533 number of images of the initial team is returned. If @var{FAILED} is not present
10534 the total number of images is returned; if it has the value @code{.TRUE.},
10535 the number of failed images is returned, otherwise, the number of images which
10536 do have not the failed status.
10538 @item @emph{Example}:
10540 INTEGER :: value[*]
10542 value = THIS_IMAGE()
10544 IF (THIS_IMAGE() == 1) THEN
10545 DO i = 1, NUM_IMAGES()
10546 WRITE(*,'(2(a,i0))') 'value[', i, '] is ', value[i]
10551 @item @emph{See also}:
10552 @ref{THIS_IMAGE}, @ref{IMAGE_INDEX}
10558 @section @code{OR} --- Bitwise logical OR
10560 @cindex bitwise logical or
10561 @cindex logical or, bitwise
10564 @item @emph{Description}:
10565 Bitwise logical @code{OR}.
10567 This intrinsic routine is provided for backwards compatibility with
10568 GNU Fortran 77. For integer arguments, programmers should consider
10569 the use of the @ref{IOR} intrinsic defined by the Fortran standard.
10571 @item @emph{Standard}:
10574 @item @emph{Class}:
10577 @item @emph{Syntax}:
10578 @code{RESULT = OR(I, J)}
10580 @item @emph{Arguments}:
10581 @multitable @columnfractions .15 .70
10582 @item @var{I} @tab The type shall be either a scalar @code{INTEGER}
10583 type or a scalar @code{LOGICAL} type.
10584 @item @var{J} @tab The type shall be the same as the type of @var{J}.
10587 @item @emph{Return value}:
10588 The return type is either a scalar @code{INTEGER} or a scalar
10589 @code{LOGICAL}. If the kind type parameters differ, then the
10590 smaller kind type is implicitly converted to larger kind, and the
10591 return has the larger kind.
10593 @item @emph{Example}:
10596 LOGICAL :: T = .TRUE., F = .FALSE.
10598 DATA a / Z'F' /, b / Z'3' /
10600 WRITE (*,*) OR(T, T), OR(T, F), OR(F, T), OR(F, F)
10601 WRITE (*,*) OR(a, b)
10605 @item @emph{See also}:
10606 Fortran 95 elemental function: @ref{IOR}
10612 @section @code{PACK} --- Pack an array into an array of rank one
10614 @cindex array, packing
10615 @cindex array, reduce dimension
10616 @cindex array, gather elements
10619 @item @emph{Description}:
10620 Stores the elements of @var{ARRAY} in an array of rank one.
10622 The beginning of the resulting array is made up of elements whose @var{MASK}
10623 equals @code{TRUE}. Afterwards, positions are filled with elements taken from
10626 @item @emph{Standard}:
10627 Fortran 95 and later
10629 @item @emph{Class}:
10630 Transformational function
10632 @item @emph{Syntax}:
10633 @code{RESULT = PACK(ARRAY, MASK[,VECTOR])}
10635 @item @emph{Arguments}:
10636 @multitable @columnfractions .15 .70
10637 @item @var{ARRAY} @tab Shall be an array of any type.
10638 @item @var{MASK} @tab Shall be an array of type @code{LOGICAL} and
10639 of the same size as @var{ARRAY}. Alternatively, it may be a @code{LOGICAL}
10641 @item @var{VECTOR} @tab (Optional) shall be an array of the same type
10642 as @var{ARRAY} and of rank one. If present, the number of elements in
10643 @var{VECTOR} shall be equal to or greater than the number of true elements
10644 in @var{MASK}. If @var{MASK} is scalar, the number of elements in
10645 @var{VECTOR} shall be equal to or greater than the number of elements in
10649 @item @emph{Return value}:
10650 The result is an array of rank one and the same type as that of @var{ARRAY}.
10651 If @var{VECTOR} is present, the result size is that of @var{VECTOR}, the
10652 number of @code{TRUE} values in @var{MASK} otherwise.
10654 @item @emph{Example}:
10655 Gathering nonzero elements from an array:
10657 PROGRAM test_pack_1
10659 m = (/ 1, 0, 0, 0, 5, 0 /)
10660 WRITE(*, FMT="(6(I0, ' '))") pack(m, m /= 0) ! "1 5"
10664 Gathering nonzero elements from an array and appending elements from @var{VECTOR}:
10666 PROGRAM test_pack_2
10668 m = (/ 1, 0, 0, 2 /)
10669 WRITE(*, FMT="(4(I0, ' '))") pack(m, m /= 0, (/ 0, 0, 3, 4 /)) ! "1 2 3 4"
10673 @item @emph{See also}:
10680 @section @code{PARITY} --- Reduction with exclusive OR
10683 @cindex Reduction, XOR
10684 @cindex XOR reduction
10687 @item @emph{Description}:
10688 Calculates the parity, i.e. the reduction using @code{.XOR.},
10689 of @var{MASK} along dimension @var{DIM}.
10691 @item @emph{Standard}:
10692 Fortran 2008 and later
10694 @item @emph{Class}:
10695 Transformational function
10697 @item @emph{Syntax}:
10698 @multitable @columnfractions .80
10699 @item @code{RESULT = PARITY(MASK[, DIM])}
10702 @item @emph{Arguments}:
10703 @multitable @columnfractions .15 .70
10704 @item @var{LOGICAL} @tab Shall be an array of type @code{LOGICAL}
10705 @item @var{DIM} @tab (Optional) shall be a scalar of type
10706 @code{INTEGER} with a value in the range from 1 to n, where n
10707 equals the rank of @var{MASK}.
10710 @item @emph{Return value}:
10711 The result is of the same type as @var{MASK}.
10713 If @var{DIM} is absent, a scalar with the parity of all elements in
10714 @var{MASK} is returned, i.e. true if an odd number of elements is
10715 @code{.true.} and false otherwise. If @var{DIM} is present, an array
10716 of rank @math{n-1}, where @math{n} equals the rank of @var{ARRAY},
10717 and a shape similar to that of @var{MASK} with dimension @var{DIM}
10718 dropped is returned.
10720 @item @emph{Example}:
10723 LOGICAL :: x(2) = [ .true., .false. ]
10724 print *, PARITY(x) ! prints "T" (true).
10732 @section @code{PERROR} --- Print system error message
10734 @cindex system, error handling
10737 @item @emph{Description}:
10738 Prints (on the C @code{stderr} stream) a newline-terminated error
10739 message corresponding to the last system error. This is prefixed by
10740 @var{STRING}, a colon and a space. See @code{perror(3)}.
10742 @item @emph{Standard}:
10745 @item @emph{Class}:
10748 @item @emph{Syntax}:
10749 @code{CALL PERROR(STRING)}
10751 @item @emph{Arguments}:
10752 @multitable @columnfractions .15 .70
10753 @item @var{STRING} @tab A scalar of type @code{CHARACTER} and of the
10757 @item @emph{See also}:
10764 @section @code{POPCNT} --- Number of bits set
10766 @cindex binary representation
10770 @item @emph{Description}:
10771 @code{POPCNT(I)} returns the number of bits set ('1' bits) in the binary
10772 representation of @code{I}.
10774 @item @emph{Standard}:
10775 Fortran 2008 and later
10777 @item @emph{Class}:
10780 @item @emph{Syntax}:
10781 @code{RESULT = POPCNT(I)}
10783 @item @emph{Arguments}:
10784 @multitable @columnfractions .15 .70
10785 @item @var{I} @tab Shall be of type @code{INTEGER}.
10788 @item @emph{Return value}:
10789 The return value is of type @code{INTEGER} and of the default integer
10792 @item @emph{See also}:
10793 @ref{POPPAR}, @ref{LEADZ}, @ref{TRAILZ}
10795 @item @emph{Example}:
10797 program test_population
10798 print *, popcnt(127), poppar(127)
10799 print *, popcnt(huge(0_4)), poppar(huge(0_4))
10800 print *, popcnt(huge(0_8)), poppar(huge(0_8))
10801 end program test_population
10807 @section @code{POPPAR} --- Parity of the number of bits set
10809 @cindex binary representation
10813 @item @emph{Description}:
10814 @code{POPPAR(I)} returns parity of the integer @code{I}, i.e. the parity
10815 of the number of bits set ('1' bits) in the binary representation of
10816 @code{I}. It is equal to 0 if @code{I} has an even number of bits set,
10817 and 1 for an odd number of '1' bits.
10819 @item @emph{Standard}:
10820 Fortran 2008 and later
10822 @item @emph{Class}:
10825 @item @emph{Syntax}:
10826 @code{RESULT = POPPAR(I)}
10828 @item @emph{Arguments}:
10829 @multitable @columnfractions .15 .70
10830 @item @var{I} @tab Shall be of type @code{INTEGER}.
10833 @item @emph{Return value}:
10834 The return value is of type @code{INTEGER} and of the default integer
10837 @item @emph{See also}:
10838 @ref{POPCNT}, @ref{LEADZ}, @ref{TRAILZ}
10840 @item @emph{Example}:
10842 program test_population
10843 print *, popcnt(127), poppar(127)
10844 print *, popcnt(huge(0_4)), poppar(huge(0_4))
10845 print *, popcnt(huge(0_8)), poppar(huge(0_8))
10846 end program test_population
10853 @section @code{PRECISION} --- Decimal precision of a real kind
10855 @cindex model representation, precision
10858 @item @emph{Description}:
10859 @code{PRECISION(X)} returns the decimal precision in the model of the
10862 @item @emph{Standard}:
10863 Fortran 95 and later
10865 @item @emph{Class}:
10868 @item @emph{Syntax}:
10869 @code{RESULT = PRECISION(X)}
10871 @item @emph{Arguments}:
10872 @multitable @columnfractions .15 .70
10873 @item @var{X} @tab Shall be of type @code{REAL} or @code{COMPLEX}.
10876 @item @emph{Return value}:
10877 The return value is of type @code{INTEGER} and of the default integer
10880 @item @emph{See also}:
10881 @ref{SELECTED_REAL_KIND}, @ref{RANGE}
10883 @item @emph{Example}:
10885 program prec_and_range
10886 real(kind=4) :: x(2)
10887 complex(kind=8) :: y
10889 print *, precision(x), range(x)
10890 print *, precision(y), range(y)
10891 end program prec_and_range
10898 @section @code{PRESENT} --- Determine whether an optional dummy argument is specified
10902 @item @emph{Description}:
10903 Determines whether an optional dummy argument is present.
10905 @item @emph{Standard}:
10906 Fortran 95 and later
10908 @item @emph{Class}:
10911 @item @emph{Syntax}:
10912 @code{RESULT = PRESENT(A)}
10914 @item @emph{Arguments}:
10915 @multitable @columnfractions .15 .70
10916 @item @var{A} @tab May be of any type and may be a pointer, scalar or array
10917 value, or a dummy procedure. It shall be the name of an optional dummy argument
10918 accessible within the current subroutine or function.
10921 @item @emph{Return value}:
10922 Returns either @code{TRUE} if the optional argument @var{A} is present, or
10923 @code{FALSE} otherwise.
10925 @item @emph{Example}:
10927 PROGRAM test_present
10928 WRITE(*,*) f(), f(42) ! "F T"
10930 LOGICAL FUNCTION f(x)
10931 INTEGER, INTENT(IN), OPTIONAL :: x
10941 @section @code{PRODUCT} --- Product of array elements
10943 @cindex array, product
10944 @cindex array, multiply elements
10945 @cindex array, conditionally multiply elements
10946 @cindex multiply array elements
10949 @item @emph{Description}:
10950 Multiplies the elements of @var{ARRAY} along dimension @var{DIM} if
10951 the corresponding element in @var{MASK} is @code{TRUE}.
10953 @item @emph{Standard}:
10954 Fortran 95 and later
10956 @item @emph{Class}:
10957 Transformational function
10959 @item @emph{Syntax}:
10960 @multitable @columnfractions .80
10961 @item @code{RESULT = PRODUCT(ARRAY[, MASK])}
10962 @item @code{RESULT = PRODUCT(ARRAY, DIM[, MASK])}
10965 @item @emph{Arguments}:
10966 @multitable @columnfractions .15 .70
10967 @item @var{ARRAY} @tab Shall be an array of type @code{INTEGER},
10968 @code{REAL} or @code{COMPLEX}.
10969 @item @var{DIM} @tab (Optional) shall be a scalar of type
10970 @code{INTEGER} with a value in the range from 1 to n, where n
10971 equals the rank of @var{ARRAY}.
10972 @item @var{MASK} @tab (Optional) shall be of type @code{LOGICAL}
10973 and either be a scalar or an array of the same shape as @var{ARRAY}.
10976 @item @emph{Return value}:
10977 The result is of the same type as @var{ARRAY}.
10979 If @var{DIM} is absent, a scalar with the product of all elements in
10980 @var{ARRAY} is returned. Otherwise, an array of rank n-1, where n equals
10981 the rank of @var{ARRAY}, and a shape similar to that of @var{ARRAY} with
10982 dimension @var{DIM} dropped is returned.
10985 @item @emph{Example}:
10987 PROGRAM test_product
10988 INTEGER :: x(5) = (/ 1, 2, 3, 4 ,5 /)
10989 print *, PRODUCT(x) ! all elements, product = 120
10990 print *, PRODUCT(x, MASK=MOD(x, 2)==1) ! odd elements, product = 15
10994 @item @emph{See also}:
11001 @section @code{RADIX} --- Base of a model number
11003 @cindex model representation, base
11004 @cindex model representation, radix
11007 @item @emph{Description}:
11008 @code{RADIX(X)} returns the base of the model representing the entity @var{X}.
11010 @item @emph{Standard}:
11011 Fortran 95 and later
11013 @item @emph{Class}:
11016 @item @emph{Syntax}:
11017 @code{RESULT = RADIX(X)}
11019 @item @emph{Arguments}:
11020 @multitable @columnfractions .15 .70
11021 @item @var{X} @tab Shall be of type @code{INTEGER} or @code{REAL}
11024 @item @emph{Return value}:
11025 The return value is a scalar of type @code{INTEGER} and of the default
11028 @item @emph{See also}:
11029 @ref{SELECTED_REAL_KIND}
11031 @item @emph{Example}:
11034 print *, "The radix for the default integer kind is", radix(0)
11035 print *, "The radix for the default real kind is", radix(0.0)
11036 end program test_radix
11044 @section @code{RAN} --- Real pseudo-random number
11046 @cindex random number generation
11049 @item @emph{Description}:
11050 For compatibility with HP FORTRAN 77/iX, the @code{RAN} intrinsic is
11051 provided as an alias for @code{RAND}. See @ref{RAND} for complete
11054 @item @emph{Standard}:
11057 @item @emph{Class}:
11060 @item @emph{See also}:
11061 @ref{RAND}, @ref{RANDOM_NUMBER}
11067 @section @code{RAND} --- Real pseudo-random number
11069 @cindex random number generation
11072 @item @emph{Description}:
11073 @code{RAND(FLAG)} returns a pseudo-random number from a uniform
11074 distribution between 0 and 1. If @var{FLAG} is 0, the next number
11075 in the current sequence is returned; if @var{FLAG} is 1, the generator
11076 is restarted by @code{CALL SRAND(0)}; if @var{FLAG} has any other value,
11077 it is used as a new seed with @code{SRAND}.
11079 This intrinsic routine is provided for backwards compatibility with
11080 GNU Fortran 77. It implements a simple modulo generator as provided
11081 by @command{g77}. For new code, one should consider the use of
11082 @ref{RANDOM_NUMBER} as it implements a superior algorithm.
11084 @item @emph{Standard}:
11087 @item @emph{Class}:
11090 @item @emph{Syntax}:
11091 @code{RESULT = RAND(I)}
11093 @item @emph{Arguments}:
11094 @multitable @columnfractions .15 .70
11095 @item @var{I} @tab Shall be a scalar @code{INTEGER} of kind 4.
11098 @item @emph{Return value}:
11099 The return value is of @code{REAL} type and the default kind.
11101 @item @emph{Example}:
11104 integer,parameter :: seed = 86456
11107 print *, rand(), rand(), rand(), rand()
11108 print *, rand(seed), rand(), rand(), rand()
11109 end program test_rand
11112 @item @emph{See also}:
11113 @ref{SRAND}, @ref{RANDOM_NUMBER}
11119 @node RANDOM_NUMBER
11120 @section @code{RANDOM_NUMBER} --- Pseudo-random number
11121 @fnindex RANDOM_NUMBER
11122 @cindex random number generation
11125 @item @emph{Description}:
11126 Returns a single pseudorandom number or an array of pseudorandom numbers
11127 from the uniform distribution over the range @math{ 0 \leq x < 1}.
11129 The runtime-library implements the xorshift1024* random number
11130 generator (RNG). This generator has a period of @math{2^{1024} - 1},
11131 and when using multiple threads up to @math{2^{512}} threads can each
11132 generate @math{2^{512}} random numbers before any aliasing occurs.
11134 Note that in a multi-threaded program (e.g. using OpenMP directives),
11135 each thread will have its own random number state. For details of the
11136 seeding procedure, see the documentation for the @code{RANDOM_SEED}
11140 @item @emph{Standard}:
11141 Fortran 95 and later
11143 @item @emph{Class}:
11146 @item @emph{Syntax}:
11147 @code{RANDOM_NUMBER(HARVEST)}
11149 @item @emph{Arguments}:
11150 @multitable @columnfractions .15 .70
11151 @item @var{HARVEST} @tab Shall be a scalar or an array of type @code{REAL}.
11154 @item @emph{Example}:
11156 program test_random_number
11158 CALL RANDOM_NUMBER(r)
11162 @item @emph{See also}:
11169 @section @code{RANDOM_SEED} --- Initialize a pseudo-random number sequence
11170 @fnindex RANDOM_SEED
11171 @cindex random number generation, seeding
11172 @cindex seeding a random number generator
11175 @item @emph{Description}:
11176 Restarts or queries the state of the pseudorandom number generator used by
11177 @code{RANDOM_NUMBER}.
11179 If @code{RANDOM_SEED} is called without arguments, it is seeded with
11180 random data retrieved from the operating system.
11182 As an extension to the Fortran standard, the GFortran
11183 @code{RANDOM_NUMBER} supports multiple threads. Each thread in a
11184 multi-threaded program has its own seed. When @code{RANDOM_SEED} is
11185 called either without arguments or with the @var{PUT} argument, the
11186 given seed is copied into a master seed as well as the seed of the
11187 current thread. When a new thread uses @code{RANDOM_NUMBER} for the
11188 first time, the seed is copied from the master seed, and forwarded
11189 @math{N * 2^{512}} steps to guarantee that the random stream does not
11190 alias any other stream in the system, where @var{N} is the number of
11191 threads that have used @code{RANDOM_NUMBER} so far during the program
11194 @item @emph{Standard}:
11195 Fortran 95 and later
11197 @item @emph{Class}:
11200 @item @emph{Syntax}:
11201 @code{CALL RANDOM_SEED([SIZE, PUT, GET])}
11203 @item @emph{Arguments}:
11204 @multitable @columnfractions .15 .70
11205 @item @var{SIZE} @tab (Optional) Shall be a scalar and of type default
11206 @code{INTEGER}, with @code{INTENT(OUT)}. It specifies the minimum size
11207 of the arrays used with the @var{PUT} and @var{GET} arguments.
11208 @item @var{PUT} @tab (Optional) Shall be an array of type default
11209 @code{INTEGER} and rank one. It is @code{INTENT(IN)} and the size of
11210 the array must be larger than or equal to the number returned by the
11211 @var{SIZE} argument.
11212 @item @var{GET} @tab (Optional) Shall be an array of type default
11213 @code{INTEGER} and rank one. It is @code{INTENT(OUT)} and the size
11214 of the array must be larger than or equal to the number returned by
11215 the @var{SIZE} argument.
11218 @item @emph{Example}:
11220 program test_random_seed
11222 integer, allocatable :: seed(:)
11225 call random_seed(size = n)
11227 call random_seed(get=seed)
11229 end program test_random_seed
11232 @item @emph{See also}:
11233 @ref{RANDOM_NUMBER}
11239 @section @code{RANGE} --- Decimal exponent range
11241 @cindex model representation, range
11244 @item @emph{Description}:
11245 @code{RANGE(X)} returns the decimal exponent range in the model of the
11248 @item @emph{Standard}:
11249 Fortran 95 and later
11251 @item @emph{Class}:
11254 @item @emph{Syntax}:
11255 @code{RESULT = RANGE(X)}
11257 @item @emph{Arguments}:
11258 @multitable @columnfractions .15 .70
11259 @item @var{X} @tab Shall be of type @code{INTEGER}, @code{REAL}
11263 @item @emph{Return value}:
11264 The return value is of type @code{INTEGER} and of the default integer
11267 @item @emph{See also}:
11268 @ref{SELECTED_REAL_KIND}, @ref{PRECISION}
11270 @item @emph{Example}:
11271 See @code{PRECISION} for an example.
11277 @section @code{RANK} --- Rank of a data object
11282 @item @emph{Description}:
11283 @code{RANK(A)} returns the rank of a scalar or array data object.
11285 @item @emph{Standard}:
11286 Technical Specification (TS) 29113
11288 @item @emph{Class}:
11291 @item @emph{Syntax}:
11292 @code{RESULT = RANK(A)}
11294 @item @emph{Arguments}:
11295 @multitable @columnfractions .15 .70
11296 @item @var{A} @tab can be of any type
11299 @item @emph{Return value}:
11300 The return value is of type @code{INTEGER} and of the default integer
11301 kind. For arrays, their rank is returned; for scalars zero is returned.
11303 @item @emph{Example}:
11307 real, allocatable :: b(:,:)
11309 print *, rank(a), rank(b) ! Prints: 0 2
11310 end program test_rank
11318 @section @code{REAL} --- Convert to real type
11327 @cindex conversion, to real
11328 @cindex complex numbers, real part
11331 @item @emph{Description}:
11332 @code{REAL(A [, KIND])} converts its argument @var{A} to a real type. The
11333 @code{REALPART} function is provided for compatibility with @command{g77},
11334 and its use is strongly discouraged.
11336 @item @emph{Standard}:
11337 Fortran 77 and later
11339 @item @emph{Class}:
11342 @item @emph{Syntax}:
11343 @multitable @columnfractions .80
11344 @item @code{RESULT = REAL(A [, KIND])}
11345 @item @code{RESULT = REALPART(Z)}
11348 @item @emph{Arguments}:
11349 @multitable @columnfractions .15 .70
11350 @item @var{A} @tab Shall be @code{INTEGER}, @code{REAL}, or
11352 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
11353 expression indicating the kind parameter of the result.
11356 @item @emph{Return value}:
11357 These functions return a @code{REAL} variable or array under
11358 the following rules:
11362 @code{REAL(A)} is converted to a default real type if @var{A} is an
11363 integer or real variable.
11365 @code{REAL(A)} is converted to a real type with the kind type parameter
11366 of @var{A} if @var{A} is a complex variable.
11368 @code{REAL(A, KIND)} is converted to a real type with kind type
11369 parameter @var{KIND} if @var{A} is a complex, integer, or real
11373 @item @emph{Example}:
11376 complex :: x = (1.0, 2.0)
11377 print *, real(x), real(x,8), realpart(x)
11378 end program test_real
11381 @item @emph{Specific names}:
11382 @multitable @columnfractions .20 .20 .20 .25
11383 @item Name @tab Argument @tab Return type @tab Standard
11384 @item @code{FLOAT(A)} @tab @code{INTEGER(4)} @tab @code{REAL(4)} @tab Fortran 77 and later
11385 @item @code{DFLOAT(A)} @tab @code{INTEGER(4)} @tab @code{REAL(8)} @tab GNU extension
11386 @item @code{FLOATI(A)} @tab @code{INTEGER(2)} @tab @code{REAL(4)} @tab GNU extension
11387 @item @code{FLOATJ(A)} @tab @code{INTEGER(4)} @tab @code{REAL(4)} @tab GNU extension
11388 @item @code{FLOATK(A)} @tab @code{INTEGER(8)} @tab @code{REAL(4)} @tab GNU extension
11389 @item @code{SNGL(A)} @tab @code{INTEGER(8)} @tab @code{REAL(4)} @tab Fortran 77 and later
11393 @item @emph{See also}:
11401 @section @code{RENAME} --- Rename a file
11403 @cindex file system, rename file
11406 @item @emph{Description}:
11407 Renames a file from file @var{PATH1} to @var{PATH2}. A null
11408 character (@code{CHAR(0)}) can be used to mark the end of the names in
11409 @var{PATH1} and @var{PATH2}; otherwise, trailing blanks in the file
11410 names are ignored. If the @var{STATUS} argument is supplied, it
11411 contains 0 on success or a nonzero error code upon return; see
11414 This intrinsic is provided in both subroutine and function forms;
11415 however, only one form can be used in any given program unit.
11417 @item @emph{Standard}:
11420 @item @emph{Class}:
11421 Subroutine, function
11423 @item @emph{Syntax}:
11424 @multitable @columnfractions .80
11425 @item @code{CALL RENAME(PATH1, PATH2 [, STATUS])}
11426 @item @code{STATUS = RENAME(PATH1, PATH2)}
11429 @item @emph{Arguments}:
11430 @multitable @columnfractions .15 .70
11431 @item @var{PATH1} @tab Shall be of default @code{CHARACTER} type.
11432 @item @var{PATH2} @tab Shall be of default @code{CHARACTER} type.
11433 @item @var{STATUS} @tab (Optional) Shall be of default @code{INTEGER} type.
11436 @item @emph{See also}:
11444 @section @code{REPEAT} --- Repeated string concatenation
11446 @cindex string, repeat
11447 @cindex string, concatenate
11450 @item @emph{Description}:
11451 Concatenates @var{NCOPIES} copies of a string.
11453 @item @emph{Standard}:
11454 Fortran 95 and later
11456 @item @emph{Class}:
11457 Transformational function
11459 @item @emph{Syntax}:
11460 @code{RESULT = REPEAT(STRING, NCOPIES)}
11462 @item @emph{Arguments}:
11463 @multitable @columnfractions .15 .70
11464 @item @var{STRING} @tab Shall be scalar and of type @code{CHARACTER}.
11465 @item @var{NCOPIES} @tab Shall be scalar and of type @code{INTEGER}.
11468 @item @emph{Return value}:
11469 A new scalar of type @code{CHARACTER} built up from @var{NCOPIES} copies
11472 @item @emph{Example}:
11474 program test_repeat
11475 write(*,*) repeat("x", 5) ! "xxxxx"
11483 @section @code{RESHAPE} --- Function to reshape an array
11485 @cindex array, change dimensions
11486 @cindex array, transmogrify
11489 @item @emph{Description}:
11490 Reshapes @var{SOURCE} to correspond to @var{SHAPE}. If necessary,
11491 the new array may be padded with elements from @var{PAD} or permuted
11492 as defined by @var{ORDER}.
11494 @item @emph{Standard}:
11495 Fortran 95 and later
11497 @item @emph{Class}:
11498 Transformational function
11500 @item @emph{Syntax}:
11501 @code{RESULT = RESHAPE(SOURCE, SHAPE[, PAD, ORDER])}
11503 @item @emph{Arguments}:
11504 @multitable @columnfractions .15 .70
11505 @item @var{SOURCE} @tab Shall be an array of any type.
11506 @item @var{SHAPE} @tab Shall be of type @code{INTEGER} and an
11507 array of rank one. Its values must be positive or zero.
11508 @item @var{PAD} @tab (Optional) shall be an array of the same
11509 type as @var{SOURCE}.
11510 @item @var{ORDER} @tab (Optional) shall be of type @code{INTEGER}
11511 and an array of the same shape as @var{SHAPE}. Its values shall
11512 be a permutation of the numbers from 1 to n, where n is the size of
11513 @var{SHAPE}. If @var{ORDER} is absent, the natural ordering shall
11517 @item @emph{Return value}:
11518 The result is an array of shape @var{SHAPE} with the same type as
11521 @item @emph{Example}:
11523 PROGRAM test_reshape
11524 INTEGER, DIMENSION(4) :: x
11525 WRITE(*,*) SHAPE(x) ! prints "4"
11526 WRITE(*,*) SHAPE(RESHAPE(x, (/2, 2/))) ! prints "2 2"
11530 @item @emph{See also}:
11537 @section @code{RRSPACING} --- Reciprocal of the relative spacing
11539 @cindex real number, relative spacing
11540 @cindex floating point, relative spacing
11544 @item @emph{Description}:
11545 @code{RRSPACING(X)} returns the reciprocal of the relative spacing of
11546 model numbers near @var{X}.
11548 @item @emph{Standard}:
11549 Fortran 95 and later
11551 @item @emph{Class}:
11554 @item @emph{Syntax}:
11555 @code{RESULT = RRSPACING(X)}
11557 @item @emph{Arguments}:
11558 @multitable @columnfractions .15 .70
11559 @item @var{X} @tab Shall be of type @code{REAL}.
11562 @item @emph{Return value}:
11563 The return value is of the same type and kind as @var{X}.
11564 The value returned is equal to
11565 @code{ABS(FRACTION(X)) * FLOAT(RADIX(X))**DIGITS(X)}.
11567 @item @emph{See also}:
11574 @section @code{RSHIFT} --- Right shift bits
11576 @cindex bits, shift right
11579 @item @emph{Description}:
11580 @code{RSHIFT} returns a value corresponding to @var{I} with all of the
11581 bits shifted right by @var{SHIFT} places. If the absolute value of
11582 @var{SHIFT} is greater than @code{BIT_SIZE(I)}, the value is undefined.
11583 Bits shifted out from the right end are lost. The fill is arithmetic: the
11584 bits shifted in from the left end are equal to the leftmost bit, which in
11585 two's complement representation is the sign bit.
11587 This function has been superseded by the @code{SHIFTA} intrinsic, which
11588 is standard in Fortran 2008 and later.
11590 @item @emph{Standard}:
11593 @item @emph{Class}:
11596 @item @emph{Syntax}:
11597 @code{RESULT = RSHIFT(I, SHIFT)}
11599 @item @emph{Arguments}:
11600 @multitable @columnfractions .15 .70
11601 @item @var{I} @tab The type shall be @code{INTEGER}.
11602 @item @var{SHIFT} @tab The type shall be @code{INTEGER}.
11605 @item @emph{Return value}:
11606 The return value is of type @code{INTEGER} and of the same kind as
11609 @item @emph{See also}:
11610 @ref{ISHFT}, @ref{ISHFTC}, @ref{LSHIFT}, @ref{SHIFTA}, @ref{SHIFTR},
11618 @section @code{SAME_TYPE_AS} --- Query dynamic types for equality
11619 @fnindex SAME_TYPE_AS
11622 @item @emph{Description}:
11623 Query dynamic types for equality.
11625 @item @emph{Standard}:
11626 Fortran 2003 and later
11628 @item @emph{Class}:
11631 @item @emph{Syntax}:
11632 @code{RESULT = SAME_TYPE_AS(A, B)}
11634 @item @emph{Arguments}:
11635 @multitable @columnfractions .15 .70
11636 @item @var{A} @tab Shall be an object of extensible declared type or
11637 unlimited polymorphic.
11638 @item @var{B} @tab Shall be an object of extensible declared type or
11639 unlimited polymorphic.
11642 @item @emph{Return value}:
11643 The return value is a scalar of type default logical. It is true if and
11644 only if the dynamic type of A is the same as the dynamic type of B.
11646 @item @emph{See also}:
11647 @ref{EXTENDS_TYPE_OF}
11654 @section @code{SCALE} --- Scale a real value
11656 @cindex real number, scale
11657 @cindex floating point, scale
11660 @item @emph{Description}:
11661 @code{SCALE(X,I)} returns @code{X * RADIX(X)**I}.
11663 @item @emph{Standard}:
11664 Fortran 95 and later
11666 @item @emph{Class}:
11669 @item @emph{Syntax}:
11670 @code{RESULT = SCALE(X, I)}
11672 @item @emph{Arguments}:
11673 @multitable @columnfractions .15 .70
11674 @item @var{X} @tab The type of the argument shall be a @code{REAL}.
11675 @item @var{I} @tab The type of the argument shall be a @code{INTEGER}.
11678 @item @emph{Return value}:
11679 The return value is of the same type and kind as @var{X}.
11680 Its value is @code{X * RADIX(X)**I}.
11682 @item @emph{Example}:
11685 real :: x = 178.1387e-4
11687 print *, scale(x,i), x*radix(x)**i
11688 end program test_scale
11696 @section @code{SCAN} --- Scan a string for the presence of a set of characters
11698 @cindex string, find subset
11701 @item @emph{Description}:
11702 Scans a @var{STRING} for any of the characters in a @var{SET}
11705 If @var{BACK} is either absent or equals @code{FALSE}, this function
11706 returns the position of the leftmost character of @var{STRING} that is
11707 in @var{SET}. If @var{BACK} equals @code{TRUE}, the rightmost position
11708 is returned. If no character of @var{SET} is found in @var{STRING}, the
11711 @item @emph{Standard}:
11712 Fortran 95 and later, with @var{KIND} argument Fortran 2003 and later
11714 @item @emph{Class}:
11717 @item @emph{Syntax}:
11718 @code{RESULT = SCAN(STRING, SET[, BACK [, KIND]])}
11720 @item @emph{Arguments}:
11721 @multitable @columnfractions .15 .70
11722 @item @var{STRING} @tab Shall be of type @code{CHARACTER}.
11723 @item @var{SET} @tab Shall be of type @code{CHARACTER}.
11724 @item @var{BACK} @tab (Optional) shall be of type @code{LOGICAL}.
11725 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
11726 expression indicating the kind parameter of the result.
11729 @item @emph{Return value}:
11730 The return value is of type @code{INTEGER} and of kind @var{KIND}. If
11731 @var{KIND} is absent, the return value is of default integer kind.
11733 @item @emph{Example}:
11736 WRITE(*,*) SCAN("FORTRAN", "AO") ! 2, found 'O'
11737 WRITE(*,*) SCAN("FORTRAN", "AO", .TRUE.) ! 6, found 'A'
11738 WRITE(*,*) SCAN("FORTRAN", "C++") ! 0, found none
11742 @item @emph{See also}:
11743 @ref{INDEX intrinsic}, @ref{VERIFY}
11749 @section @code{SECNDS} --- Time function
11751 @cindex time, elapsed
11752 @cindex elapsed time
11755 @item @emph{Description}:
11756 @code{SECNDS(X)} gets the time in seconds from the real-time system clock.
11757 @var{X} is a reference time, also in seconds. If this is zero, the time in
11758 seconds from midnight is returned. This function is non-standard and its
11759 use is discouraged.
11761 @item @emph{Standard}:
11764 @item @emph{Class}:
11767 @item @emph{Syntax}:
11768 @code{RESULT = SECNDS (X)}
11770 @item @emph{Arguments}:
11771 @multitable @columnfractions .15 .70
11772 @item @var{T} @tab Shall be of type @code{REAL(4)}.
11773 @item @var{X} @tab Shall be of type @code{REAL(4)}.
11776 @item @emph{Return value}:
11779 @item @emph{Example}:
11781 program test_secnds
11784 print *, secnds (0.0) ! seconds since midnight
11785 t1 = secnds (0.0) ! reference time
11786 do i = 1, 10000000 ! do something
11788 t2 = secnds (t1) ! elapsed time
11789 print *, "Something took ", t2, " seconds."
11790 end program test_secnds
11797 @section @code{SECOND} --- CPU time function
11799 @cindex time, elapsed
11800 @cindex elapsed time
11803 @item @emph{Description}:
11804 Returns a @code{REAL(4)} value representing the elapsed CPU time in
11805 seconds. This provides the same functionality as the standard
11806 @code{CPU_TIME} intrinsic, and is only included for backwards
11809 This intrinsic is provided in both subroutine and function forms;
11810 however, only one form can be used in any given program unit.
11812 @item @emph{Standard}:
11815 @item @emph{Class}:
11816 Subroutine, function
11818 @item @emph{Syntax}:
11819 @multitable @columnfractions .80
11820 @item @code{CALL SECOND(TIME)}
11821 @item @code{TIME = SECOND()}
11824 @item @emph{Arguments}:
11825 @multitable @columnfractions .15 .70
11826 @item @var{TIME} @tab Shall be of type @code{REAL(4)}.
11829 @item @emph{Return value}:
11830 In either syntax, @var{TIME} is set to the process's current runtime in
11833 @item @emph{See also}:
11840 @node SELECTED_CHAR_KIND
11841 @section @code{SELECTED_CHAR_KIND} --- Choose character kind
11842 @fnindex SELECTED_CHAR_KIND
11843 @cindex character kind
11844 @cindex kind, character
11847 @item @emph{Description}:
11849 @code{SELECTED_CHAR_KIND(NAME)} returns the kind value for the character
11850 set named @var{NAME}, if a character set with such a name is supported,
11851 or @math{-1} otherwise. Currently, supported character sets include
11852 ``ASCII'' and ``DEFAULT'', which are equivalent, and ``ISO_10646''
11853 (Universal Character Set, UCS-4) which is commonly known as Unicode.
11855 @item @emph{Standard}:
11856 Fortran 2003 and later
11858 @item @emph{Class}:
11859 Transformational function
11861 @item @emph{Syntax}:
11862 @code{RESULT = SELECTED_CHAR_KIND(NAME)}
11864 @item @emph{Arguments}:
11865 @multitable @columnfractions .15 .70
11866 @item @var{NAME} @tab Shall be a scalar and of the default character type.
11869 @item @emph{Example}:
11871 program character_kind
11872 use iso_fortran_env
11874 integer, parameter :: ascii = selected_char_kind ("ascii")
11875 integer, parameter :: ucs4 = selected_char_kind ('ISO_10646')
11877 character(kind=ascii, len=26) :: alphabet
11878 character(kind=ucs4, len=30) :: hello_world
11880 alphabet = ascii_"abcdefghijklmnopqrstuvwxyz"
11881 hello_world = ucs4_'Hello World and Ni Hao -- ' &
11882 // char (int (z'4F60'), ucs4) &
11883 // char (int (z'597D'), ucs4)
11885 write (*,*) alphabet
11887 open (output_unit, encoding='UTF-8')
11888 write (*,*) trim (hello_world)
11889 end program character_kind
11895 @node SELECTED_INT_KIND
11896 @section @code{SELECTED_INT_KIND} --- Choose integer kind
11897 @fnindex SELECTED_INT_KIND
11898 @cindex integer kind
11899 @cindex kind, integer
11902 @item @emph{Description}:
11903 @code{SELECTED_INT_KIND(R)} return the kind value of the smallest integer
11904 type that can represent all values ranging from @math{-10^R} (exclusive)
11905 to @math{10^R} (exclusive). If there is no integer kind that accommodates
11906 this range, @code{SELECTED_INT_KIND} returns @math{-1}.
11908 @item @emph{Standard}:
11909 Fortran 95 and later
11911 @item @emph{Class}:
11912 Transformational function
11914 @item @emph{Syntax}:
11915 @code{RESULT = SELECTED_INT_KIND(R)}
11917 @item @emph{Arguments}:
11918 @multitable @columnfractions .15 .70
11919 @item @var{R} @tab Shall be a scalar and of type @code{INTEGER}.
11922 @item @emph{Example}:
11924 program large_integers
11925 integer,parameter :: k5 = selected_int_kind(5)
11926 integer,parameter :: k15 = selected_int_kind(15)
11927 integer(kind=k5) :: i5
11928 integer(kind=k15) :: i15
11930 print *, huge(i5), huge(i15)
11932 ! The following inequalities are always true
11933 print *, huge(i5) >= 10_k5**5-1
11934 print *, huge(i15) >= 10_k15**15-1
11935 end program large_integers
11941 @node SELECTED_REAL_KIND
11942 @section @code{SELECTED_REAL_KIND} --- Choose real kind
11943 @fnindex SELECTED_REAL_KIND
11946 @cindex radix, real
11949 @item @emph{Description}:
11950 @code{SELECTED_REAL_KIND(P,R)} returns the kind value of a real data type
11951 with decimal precision of at least @code{P} digits, exponent range of
11952 at least @code{R}, and with a radix of @code{RADIX}.
11954 @item @emph{Standard}:
11955 Fortran 95 and later, with @code{RADIX} Fortran 2008 or later
11957 @item @emph{Class}:
11958 Transformational function
11960 @item @emph{Syntax}:
11961 @code{RESULT = SELECTED_REAL_KIND([P, R, RADIX])}
11963 @item @emph{Arguments}:
11964 @multitable @columnfractions .15 .70
11965 @item @var{P} @tab (Optional) shall be a scalar and of type @code{INTEGER}.
11966 @item @var{R} @tab (Optional) shall be a scalar and of type @code{INTEGER}.
11967 @item @var{RADIX} @tab (Optional) shall be a scalar and of type @code{INTEGER}.
11969 Before Fortran 2008, at least one of the arguments @var{R} or @var{P} shall
11970 be present; since Fortran 2008, they are assumed to be zero if absent.
11972 @item @emph{Return value}:
11974 @code{SELECTED_REAL_KIND} returns the value of the kind type parameter of
11975 a real data type with decimal precision of at least @code{P} digits, a
11976 decimal exponent range of at least @code{R}, and with the requested
11977 @code{RADIX}. If the @code{RADIX} parameter is absent, real kinds with
11978 any radix can be returned. If more than one real data type meet the
11979 criteria, the kind of the data type with the smallest decimal precision
11980 is returned. If no real data type matches the criteria, the result is
11982 @item -1 if the processor does not support a real data type with a
11983 precision greater than or equal to @code{P}, but the @code{R} and
11984 @code{RADIX} requirements can be fulfilled
11985 @item -2 if the processor does not support a real type with an exponent
11986 range greater than or equal to @code{R}, but @code{P} and @code{RADIX}
11988 @item -3 if @code{RADIX} but not @code{P} and @code{R} requirements
11990 @item -4 if @code{RADIX} and either @code{P} or @code{R} requirements
11992 @item -5 if there is no real type with the given @code{RADIX}
11995 @item @emph{See also}:
11996 @ref{PRECISION}, @ref{RANGE}, @ref{RADIX}
11998 @item @emph{Example}:
12001 integer,parameter :: p6 = selected_real_kind(6)
12002 integer,parameter :: p10r100 = selected_real_kind(10,100)
12003 integer,parameter :: r400 = selected_real_kind(r=400)
12005 real(kind=p10r100) :: y
12006 real(kind=r400) :: z
12008 print *, precision(x), range(x)
12009 print *, precision(y), range(y)
12010 print *, precision(z), range(z)
12011 end program real_kinds
12018 @section @code{SET_EXPONENT} --- Set the exponent of the model
12019 @fnindex SET_EXPONENT
12020 @cindex real number, set exponent
12021 @cindex floating point, set exponent
12024 @item @emph{Description}:
12025 @code{SET_EXPONENT(X, I)} returns the real number whose fractional part
12026 is that that of @var{X} and whose exponent part is @var{I}.
12028 @item @emph{Standard}:
12029 Fortran 95 and later
12031 @item @emph{Class}:
12034 @item @emph{Syntax}:
12035 @code{RESULT = SET_EXPONENT(X, I)}
12037 @item @emph{Arguments}:
12038 @multitable @columnfractions .15 .70
12039 @item @var{X} @tab Shall be of type @code{REAL}.
12040 @item @var{I} @tab Shall be of type @code{INTEGER}.
12043 @item @emph{Return value}:
12044 The return value is of the same type and kind as @var{X}.
12045 The real number whose fractional part
12046 is that that of @var{X} and whose exponent part if @var{I} is returned;
12047 it is @code{FRACTION(X) * RADIX(X)**I}.
12049 @item @emph{Example}:
12051 PROGRAM test_setexp
12052 REAL :: x = 178.1387e-4
12054 PRINT *, SET_EXPONENT(x, i), FRACTION(x) * RADIX(x)**i
12063 @section @code{SHAPE} --- Determine the shape of an array
12065 @cindex array, shape
12068 @item @emph{Description}:
12069 Determines the shape of an array.
12071 @item @emph{Standard}:
12072 Fortran 95 and later, with @var{KIND} argument Fortran 2003 and later
12074 @item @emph{Class}:
12077 @item @emph{Syntax}:
12078 @code{RESULT = SHAPE(SOURCE [, KIND])}
12080 @item @emph{Arguments}:
12081 @multitable @columnfractions .15 .70
12082 @item @var{SOURCE} @tab Shall be an array or scalar of any type.
12083 If @var{SOURCE} is a pointer it must be associated and allocatable
12084 arrays must be allocated.
12085 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
12086 expression indicating the kind parameter of the result.
12089 @item @emph{Return value}:
12090 An @code{INTEGER} array of rank one with as many elements as @var{SOURCE}
12091 has dimensions. The elements of the resulting array correspond to the extend
12092 of @var{SOURCE} along the respective dimensions. If @var{SOURCE} is a scalar,
12093 the result is the rank one array of size zero. If @var{KIND} is absent, the
12094 return value has the default integer kind otherwise the specified kind.
12096 @item @emph{Example}:
12099 INTEGER, DIMENSION(-1:1, -1:2) :: A
12100 WRITE(*,*) SHAPE(A) ! (/ 3, 4 /)
12101 WRITE(*,*) SIZE(SHAPE(42)) ! (/ /)
12105 @item @emph{See also}:
12106 @ref{RESHAPE}, @ref{SIZE}
12112 @section @code{SHIFTA} --- Right shift with fill
12114 @cindex bits, shift right
12115 @cindex shift, right with fill
12118 @item @emph{Description}:
12119 @code{SHIFTA} returns a value corresponding to @var{I} with all of the
12120 bits shifted right by @var{SHIFT} places. If the absolute value of
12121 @var{SHIFT} is greater than @code{BIT_SIZE(I)}, the value is undefined.
12122 Bits shifted out from the right end are lost. The fill is arithmetic: the
12123 bits shifted in from the left end are equal to the leftmost bit, which in
12124 two's complement representation is the sign bit.
12126 @item @emph{Standard}:
12127 Fortran 2008 and later
12129 @item @emph{Class}:
12132 @item @emph{Syntax}:
12133 @code{RESULT = SHIFTA(I, SHIFT)}
12135 @item @emph{Arguments}:
12136 @multitable @columnfractions .15 .70
12137 @item @var{I} @tab The type shall be @code{INTEGER}.
12138 @item @var{SHIFT} @tab The type shall be @code{INTEGER}.
12141 @item @emph{Return value}:
12142 The return value is of type @code{INTEGER} and of the same kind as
12145 @item @emph{See also}:
12146 @ref{SHIFTL}, @ref{SHIFTR}
12152 @section @code{SHIFTL} --- Left shift
12154 @cindex bits, shift left
12155 @cindex shift, left
12158 @item @emph{Description}:
12159 @code{SHIFTL} returns a value corresponding to @var{I} with all of the
12160 bits shifted left by @var{SHIFT} places. If the absolute value of
12161 @var{SHIFT} is greater than @code{BIT_SIZE(I)}, the value is undefined.
12162 Bits shifted out from the left end are lost, and bits shifted in from
12163 the right end are set to 0.
12165 @item @emph{Standard}:
12166 Fortran 2008 and later
12168 @item @emph{Class}:
12171 @item @emph{Syntax}:
12172 @code{RESULT = SHIFTL(I, SHIFT)}
12174 @item @emph{Arguments}:
12175 @multitable @columnfractions .15 .70
12176 @item @var{I} @tab The type shall be @code{INTEGER}.
12177 @item @var{SHIFT} @tab The type shall be @code{INTEGER}.
12180 @item @emph{Return value}:
12181 The return value is of type @code{INTEGER} and of the same kind as
12184 @item @emph{See also}:
12185 @ref{SHIFTA}, @ref{SHIFTR}
12191 @section @code{SHIFTR} --- Right shift
12193 @cindex bits, shift right
12194 @cindex shift, right
12197 @item @emph{Description}:
12198 @code{SHIFTR} returns a value corresponding to @var{I} with all of the
12199 bits shifted right by @var{SHIFT} places. If the absolute value of
12200 @var{SHIFT} is greater than @code{BIT_SIZE(I)}, the value is undefined.
12201 Bits shifted out from the right end are lost, and bits shifted in from
12202 the left end are set to 0.
12204 @item @emph{Standard}:
12205 Fortran 2008 and later
12207 @item @emph{Class}:
12210 @item @emph{Syntax}:
12211 @code{RESULT = SHIFTR(I, SHIFT)}
12213 @item @emph{Arguments}:
12214 @multitable @columnfractions .15 .70
12215 @item @var{I} @tab The type shall be @code{INTEGER}.
12216 @item @var{SHIFT} @tab The type shall be @code{INTEGER}.
12219 @item @emph{Return value}:
12220 The return value is of type @code{INTEGER} and of the same kind as
12223 @item @emph{See also}:
12224 @ref{SHIFTA}, @ref{SHIFTL}
12230 @section @code{SIGN} --- Sign copying function
12234 @cindex sign copying
12237 @item @emph{Description}:
12238 @code{SIGN(A,B)} returns the value of @var{A} with the sign of @var{B}.
12240 @item @emph{Standard}:
12241 Fortran 77 and later
12243 @item @emph{Class}:
12246 @item @emph{Syntax}:
12247 @code{RESULT = SIGN(A, B)}
12249 @item @emph{Arguments}:
12250 @multitable @columnfractions .15 .70
12251 @item @var{A} @tab Shall be of type @code{INTEGER} or @code{REAL}
12252 @item @var{B} @tab Shall be of the same type and kind as @var{A}
12255 @item @emph{Return value}:
12256 The kind of the return value is that of @var{A} and @var{B}.
12257 If @math{B\ge 0} then the result is @code{ABS(A)}, else
12258 it is @code{-ABS(A)}.
12260 @item @emph{Example}:
12263 print *, sign(-12,1)
12264 print *, sign(-12,0)
12265 print *, sign(-12,-1)
12267 print *, sign(-12.,1.)
12268 print *, sign(-12.,0.)
12269 print *, sign(-12.,-1.)
12270 end program test_sign
12273 @item @emph{Specific names}:
12274 @multitable @columnfractions .20 .20 .20 .25
12275 @item Name @tab Arguments @tab Return type @tab Standard
12276 @item @code{SIGN(A,B)} @tab @code{REAL(4) A, B} @tab @code{REAL(4)} @tab f77, gnu
12277 @item @code{ISIGN(A,B)} @tab @code{INTEGER(4) A, B} @tab @code{INTEGER(4)} @tab f77, gnu
12278 @item @code{DSIGN(A,B)} @tab @code{REAL(8) A, B} @tab @code{REAL(8)} @tab f77, gnu
12285 @section @code{SIGNAL} --- Signal handling subroutine (or function)
12287 @cindex system, signal handling
12290 @item @emph{Description}:
12291 @code{SIGNAL(NUMBER, HANDLER [, STATUS])} causes external subroutine
12292 @var{HANDLER} to be executed with a single integer argument when signal
12293 @var{NUMBER} occurs. If @var{HANDLER} is an integer, it can be used to
12294 turn off handling of signal @var{NUMBER} or revert to its default
12295 action. See @code{signal(2)}.
12297 If @code{SIGNAL} is called as a subroutine and the @var{STATUS} argument
12298 is supplied, it is set to the value returned by @code{signal(2)}.
12300 @item @emph{Standard}:
12303 @item @emph{Class}:
12304 Subroutine, function
12306 @item @emph{Syntax}:
12307 @multitable @columnfractions .80
12308 @item @code{CALL SIGNAL(NUMBER, HANDLER [, STATUS])}
12309 @item @code{STATUS = SIGNAL(NUMBER, HANDLER)}
12312 @item @emph{Arguments}:
12313 @multitable @columnfractions .15 .70
12314 @item @var{NUMBER} @tab Shall be a scalar integer, with @code{INTENT(IN)}
12315 @item @var{HANDLER}@tab Signal handler (@code{INTEGER FUNCTION} or
12316 @code{SUBROUTINE}) or dummy/global @code{INTEGER} scalar.
12317 @code{INTEGER}. It is @code{INTENT(IN)}.
12318 @item @var{STATUS} @tab (Optional) @var{STATUS} shall be a scalar
12319 integer. It has @code{INTENT(OUT)}.
12321 @c TODO: What should the interface of the handler be? Does it take arguments?
12323 @item @emph{Return value}:
12324 The @code{SIGNAL} function returns the value returned by @code{signal(2)}.
12326 @item @emph{Example}:
12328 program test_signal
12330 external handler_print
12332 call signal (12, handler_print)
12333 call signal (10, 1)
12336 end program test_signal
12343 @section @code{SIN} --- Sine function
12349 @cindex trigonometric function, sine
12353 @item @emph{Description}:
12354 @code{SIN(X)} computes the sine of @var{X}.
12356 @item @emph{Standard}:
12357 Fortran 77 and later
12359 @item @emph{Class}:
12362 @item @emph{Syntax}:
12363 @code{RESULT = SIN(X)}
12365 @item @emph{Arguments}:
12366 @multitable @columnfractions .15 .70
12367 @item @var{X} @tab The type shall be @code{REAL} or
12371 @item @emph{Return value}:
12372 The return value has same type and kind as @var{X}.
12374 @item @emph{Example}:
12379 end program test_sin
12382 @item @emph{Specific names}:
12383 @multitable @columnfractions .20 .20 .20 .25
12384 @item Name @tab Argument @tab Return type @tab Standard
12385 @item @code{SIN(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab f77, gnu
12386 @item @code{DSIN(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab f95, gnu
12387 @item @code{CSIN(X)} @tab @code{COMPLEX(4) X} @tab @code{COMPLEX(4)} @tab f95, gnu
12388 @item @code{ZSIN(X)} @tab @code{COMPLEX(8) X} @tab @code{COMPLEX(8)} @tab f95, gnu
12389 @item @code{CDSIN(X)} @tab @code{COMPLEX(8) X} @tab @code{COMPLEX(8)} @tab f95, gnu
12392 @item @emph{See also}:
12399 @section @code{SINH} --- Hyperbolic sine function
12402 @cindex hyperbolic sine
12403 @cindex hyperbolic function, sine
12404 @cindex sine, hyperbolic
12407 @item @emph{Description}:
12408 @code{SINH(X)} computes the hyperbolic sine of @var{X}.
12410 @item @emph{Standard}:
12411 Fortran 95 and later, for a complex argument Fortran 2008 or later
12413 @item @emph{Class}:
12416 @item @emph{Syntax}:
12417 @code{RESULT = SINH(X)}
12419 @item @emph{Arguments}:
12420 @multitable @columnfractions .15 .70
12421 @item @var{X} @tab The type shall be @code{REAL} or @code{COMPLEX}.
12424 @item @emph{Return value}:
12425 The return value has same type and kind as @var{X}.
12427 @item @emph{Example}:
12430 real(8) :: x = - 1.0_8
12432 end program test_sinh
12435 @item @emph{Specific names}:
12436 @multitable @columnfractions .20 .20 .20 .25
12437 @item Name @tab Argument @tab Return type @tab Standard
12438 @item @code{SINH(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab Fortran 95 and later
12439 @item @code{DSINH(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab Fortran 95 and later
12442 @item @emph{See also}:
12449 @section @code{SIZE} --- Determine the size of an array
12451 @cindex array, size
12452 @cindex array, number of elements
12453 @cindex array, count elements
12456 @item @emph{Description}:
12457 Determine the extent of @var{ARRAY} along a specified dimension @var{DIM},
12458 or the total number of elements in @var{ARRAY} if @var{DIM} is absent.
12460 @item @emph{Standard}:
12461 Fortran 95 and later, with @var{KIND} argument Fortran 2003 and later
12463 @item @emph{Class}:
12466 @item @emph{Syntax}:
12467 @code{RESULT = SIZE(ARRAY[, DIM [, KIND]])}
12469 @item @emph{Arguments}:
12470 @multitable @columnfractions .15 .70
12471 @item @var{ARRAY} @tab Shall be an array of any type. If @var{ARRAY} is
12472 a pointer it must be associated and allocatable arrays must be allocated.
12473 @item @var{DIM} @tab (Optional) shall be a scalar of type @code{INTEGER}
12474 and its value shall be in the range from 1 to n, where n equals the rank
12476 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
12477 expression indicating the kind parameter of the result.
12480 @item @emph{Return value}:
12481 The return value is of type @code{INTEGER} and of kind @var{KIND}. If
12482 @var{KIND} is absent, the return value is of default integer kind.
12484 @item @emph{Example}:
12487 WRITE(*,*) SIZE((/ 1, 2 /)) ! 2
12491 @item @emph{See also}:
12492 @ref{SHAPE}, @ref{RESHAPE}
12497 @section @code{SIZEOF} --- Size in bytes of an expression
12499 @cindex expression size
12500 @cindex size of an expression
12503 @item @emph{Description}:
12504 @code{SIZEOF(X)} calculates the number of bytes of storage the
12505 expression @code{X} occupies.
12507 @item @emph{Standard}:
12510 @item @emph{Class}:
12513 @item @emph{Syntax}:
12514 @code{N = SIZEOF(X)}
12516 @item @emph{Arguments}:
12517 @multitable @columnfractions .15 .70
12518 @item @var{X} @tab The argument shall be of any type, rank or shape.
12521 @item @emph{Return value}:
12522 The return value is of type integer and of the system-dependent kind
12523 @var{C_SIZE_T} (from the @var{ISO_C_BINDING} module). Its value is the
12524 number of bytes occupied by the argument. If the argument has the
12525 @code{POINTER} attribute, the number of bytes of the storage area pointed
12526 to is returned. If the argument is of a derived type with @code{POINTER}
12527 or @code{ALLOCATABLE} components, the return value does not account for
12528 the sizes of the data pointed to by these components. If the argument is
12529 polymorphic, the size according to the dynamic type is returned. The argument
12530 may not be a procedure or procedure pointer. Note that the code assumes for
12531 arrays that those are contiguous; for contiguous arrays, it returns the
12532 storage or an array element multiplied by the size of the array.
12534 @item @emph{Example}:
12538 print *, (sizeof(s)/sizeof(r) == 5)
12541 The example will print @code{.TRUE.} unless you are using a platform
12542 where default @code{REAL} variables are unusually padded.
12544 @item @emph{See also}:
12545 @ref{C_SIZEOF}, @ref{STORAGE_SIZE}
12550 @section @code{SLEEP} --- Sleep for the specified number of seconds
12552 @cindex delayed execution
12555 @item @emph{Description}:
12556 Calling this subroutine causes the process to pause for @var{SECONDS} seconds.
12558 @item @emph{Standard}:
12561 @item @emph{Class}:
12564 @item @emph{Syntax}:
12565 @code{CALL SLEEP(SECONDS)}
12567 @item @emph{Arguments}:
12568 @multitable @columnfractions .15 .70
12569 @item @var{SECONDS} @tab The type shall be of default @code{INTEGER}.
12572 @item @emph{Example}:
12583 @section @code{SPACING} --- Smallest distance between two numbers of a given type
12585 @cindex real number, relative spacing
12586 @cindex floating point, relative spacing
12589 @item @emph{Description}:
12590 Determines the distance between the argument @var{X} and the nearest
12591 adjacent number of the same type.
12593 @item @emph{Standard}:
12594 Fortran 95 and later
12596 @item @emph{Class}:
12599 @item @emph{Syntax}:
12600 @code{RESULT = SPACING(X)}
12602 @item @emph{Arguments}:
12603 @multitable @columnfractions .15 .70
12604 @item @var{X} @tab Shall be of type @code{REAL}.
12607 @item @emph{Return value}:
12608 The result is of the same type as the input argument @var{X}.
12610 @item @emph{Example}:
12612 PROGRAM test_spacing
12613 INTEGER, PARAMETER :: SGL = SELECTED_REAL_KIND(p=6, r=37)
12614 INTEGER, PARAMETER :: DBL = SELECTED_REAL_KIND(p=13, r=200)
12616 WRITE(*,*) spacing(1.0_SGL) ! "1.1920929E-07" on i686
12617 WRITE(*,*) spacing(1.0_DBL) ! "2.220446049250313E-016" on i686
12621 @item @emph{See also}:
12628 @section @code{SPREAD} --- Add a dimension to an array
12630 @cindex array, increase dimension
12631 @cindex array, duplicate elements
12632 @cindex array, duplicate dimensions
12635 @item @emph{Description}:
12636 Replicates a @var{SOURCE} array @var{NCOPIES} times along a specified
12637 dimension @var{DIM}.
12639 @item @emph{Standard}:
12640 Fortran 95 and later
12642 @item @emph{Class}:
12643 Transformational function
12645 @item @emph{Syntax}:
12646 @code{RESULT = SPREAD(SOURCE, DIM, NCOPIES)}
12648 @item @emph{Arguments}:
12649 @multitable @columnfractions .15 .70
12650 @item @var{SOURCE} @tab Shall be a scalar or an array of any type and
12651 a rank less than seven.
12652 @item @var{DIM} @tab Shall be a scalar of type @code{INTEGER} with a
12653 value in the range from 1 to n+1, where n equals the rank of @var{SOURCE}.
12654 @item @var{NCOPIES} @tab Shall be a scalar of type @code{INTEGER}.
12657 @item @emph{Return value}:
12658 The result is an array of the same type as @var{SOURCE} and has rank n+1
12659 where n equals the rank of @var{SOURCE}.
12661 @item @emph{Example}:
12663 PROGRAM test_spread
12664 INTEGER :: a = 1, b(2) = (/ 1, 2 /)
12665 WRITE(*,*) SPREAD(A, 1, 2) ! "1 1"
12666 WRITE(*,*) SPREAD(B, 1, 2) ! "1 1 2 2"
12670 @item @emph{See also}:
12677 @section @code{SQRT} --- Square-root function
12684 @cindex square-root
12687 @item @emph{Description}:
12688 @code{SQRT(X)} computes the square root of @var{X}.
12690 @item @emph{Standard}:
12691 Fortran 77 and later
12693 @item @emph{Class}:
12696 @item @emph{Syntax}:
12697 @code{RESULT = SQRT(X)}
12699 @item @emph{Arguments}:
12700 @multitable @columnfractions .15 .70
12701 @item @var{X} @tab The type shall be @code{REAL} or
12705 @item @emph{Return value}:
12706 The return value is of type @code{REAL} or @code{COMPLEX}.
12707 The kind type parameter is the same as @var{X}.
12709 @item @emph{Example}:
12712 real(8) :: x = 2.0_8
12713 complex :: z = (1.0, 2.0)
12716 end program test_sqrt
12719 @item @emph{Specific names}:
12720 @multitable @columnfractions .20 .20 .20 .25
12721 @item Name @tab Argument @tab Return type @tab Standard
12722 @item @code{SQRT(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab Fortran 95 and later
12723 @item @code{DSQRT(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab Fortran 95 and later
12724 @item @code{CSQRT(X)} @tab @code{COMPLEX(4) X} @tab @code{COMPLEX(4)} @tab Fortran 95 and later
12725 @item @code{ZSQRT(X)} @tab @code{COMPLEX(8) X} @tab @code{COMPLEX(8)} @tab GNU extension
12726 @item @code{CDSQRT(X)} @tab @code{COMPLEX(8) X} @tab @code{COMPLEX(8)} @tab GNU extension
12733 @section @code{SRAND} --- Reinitialize the random number generator
12735 @cindex random number generation, seeding
12736 @cindex seeding a random number generator
12739 @item @emph{Description}:
12740 @code{SRAND} reinitializes the pseudo-random number generator
12741 called by @code{RAND} and @code{IRAND}. The new seed used by the
12742 generator is specified by the required argument @var{SEED}.
12744 @item @emph{Standard}:
12747 @item @emph{Class}:
12750 @item @emph{Syntax}:
12751 @code{CALL SRAND(SEED)}
12753 @item @emph{Arguments}:
12754 @multitable @columnfractions .15 .70
12755 @item @var{SEED} @tab Shall be a scalar @code{INTEGER(kind=4)}.
12758 @item @emph{Return value}:
12759 Does not return anything.
12761 @item @emph{Example}:
12762 See @code{RAND} and @code{IRAND} for examples.
12764 @item @emph{Notes}:
12765 The Fortran standard specifies the intrinsic subroutines
12766 @code{RANDOM_SEED} to initialize the pseudo-random number
12767 generator and @code{RANDOM_NUMBER} to generate pseudo-random numbers.
12768 These subroutines should be used in new codes.
12770 Please note that in GNU Fortran, these two sets of intrinsics (@code{RAND},
12771 @code{IRAND} and @code{SRAND} on the one hand, @code{RANDOM_NUMBER} and
12772 @code{RANDOM_SEED} on the other hand) access two independent
12773 pseudo-random number generators.
12775 @item @emph{See also}:
12776 @ref{RAND}, @ref{RANDOM_SEED}, @ref{RANDOM_NUMBER}
12783 @section @code{STAT} --- Get file status
12785 @cindex file system, file status
12788 @item @emph{Description}:
12789 This function returns information about a file. No permissions are required on
12790 the file itself, but execute (search) permission is required on all of the
12791 directories in path that lead to the file.
12793 The elements that are obtained and stored in the array @code{VALUES}:
12794 @multitable @columnfractions .15 .70
12795 @item @code{VALUES(1)} @tab Device ID
12796 @item @code{VALUES(2)} @tab Inode number
12797 @item @code{VALUES(3)} @tab File mode
12798 @item @code{VALUES(4)} @tab Number of links
12799 @item @code{VALUES(5)} @tab Owner's uid
12800 @item @code{VALUES(6)} @tab Owner's gid
12801 @item @code{VALUES(7)} @tab ID of device containing directory entry for file (0 if not available)
12802 @item @code{VALUES(8)} @tab File size (bytes)
12803 @item @code{VALUES(9)} @tab Last access time
12804 @item @code{VALUES(10)} @tab Last modification time
12805 @item @code{VALUES(11)} @tab Last file status change time
12806 @item @code{VALUES(12)} @tab Preferred I/O block size (-1 if not available)
12807 @item @code{VALUES(13)} @tab Number of blocks allocated (-1 if not available)
12810 Not all these elements are relevant on all systems.
12811 If an element is not relevant, it is returned as 0.
12813 This intrinsic is provided in both subroutine and function forms; however,
12814 only one form can be used in any given program unit.
12816 @item @emph{Standard}:
12819 @item @emph{Class}:
12820 Subroutine, function
12822 @item @emph{Syntax}:
12823 @multitable @columnfractions .80
12824 @item @code{CALL STAT(NAME, VALUES [, STATUS])}
12825 @item @code{STATUS = STAT(NAME, VALUES)}
12828 @item @emph{Arguments}:
12829 @multitable @columnfractions .15 .70
12830 @item @var{NAME} @tab The type shall be @code{CHARACTER}, of the
12831 default kind and a valid path within the file system.
12832 @item @var{VALUES} @tab The type shall be @code{INTEGER(4), DIMENSION(13)}.
12833 @item @var{STATUS} @tab (Optional) status flag of type @code{INTEGER(4)}. Returns 0
12834 on success and a system specific error code otherwise.
12837 @item @emph{Example}:
12840 INTEGER, DIMENSION(13) :: buff
12843 CALL STAT("/etc/passwd", buff, status)
12845 IF (status == 0) THEN
12846 WRITE (*, FMT="('Device ID:', T30, I19)") buff(1)
12847 WRITE (*, FMT="('Inode number:', T30, I19)") buff(2)
12848 WRITE (*, FMT="('File mode (octal):', T30, O19)") buff(3)
12849 WRITE (*, FMT="('Number of links:', T30, I19)") buff(4)
12850 WRITE (*, FMT="('Owner''s uid:', T30, I19)") buff(5)
12851 WRITE (*, FMT="('Owner''s gid:', T30, I19)") buff(6)
12852 WRITE (*, FMT="('Device where located:', T30, I19)") buff(7)
12853 WRITE (*, FMT="('File size:', T30, I19)") buff(8)
12854 WRITE (*, FMT="('Last access time:', T30, A19)") CTIME(buff(9))
12855 WRITE (*, FMT="('Last modification time', T30, A19)") CTIME(buff(10))
12856 WRITE (*, FMT="('Last status change time:', T30, A19)") CTIME(buff(11))
12857 WRITE (*, FMT="('Preferred block size:', T30, I19)") buff(12)
12858 WRITE (*, FMT="('No. of blocks allocated:', T30, I19)") buff(13)
12863 @item @emph{See also}:
12864 To stat an open file: @ref{FSTAT}, to stat a link: @ref{LSTAT}
12870 @section @code{STORAGE_SIZE} --- Storage size in bits
12871 @fnindex STORAGE_SIZE
12872 @cindex storage size
12875 @item @emph{Description}:
12876 Returns the storage size of argument @var{A} in bits.
12877 @item @emph{Standard}:
12878 Fortran 2008 and later
12879 @item @emph{Class}:
12881 @item @emph{Syntax}:
12882 @code{RESULT = STORAGE_SIZE(A [, KIND])}
12884 @item @emph{Arguments}:
12885 @multitable @columnfractions .15 .70
12886 @item @var{A} @tab Shall be a scalar or array of any type.
12887 @item @var{KIND} @tab (Optional) shall be a scalar integer constant expression.
12890 @item @emph{Return Value}:
12891 The result is a scalar integer with the kind type parameter specified by KIND
12892 (or default integer type if KIND is missing). The result value is the size
12893 expressed in bits for an element of an array that has the dynamic type and type
12896 @item @emph{See also}:
12897 @ref{C_SIZEOF}, @ref{SIZEOF}
12903 @section @code{SUM} --- Sum of array elements
12906 @cindex array, add elements
12907 @cindex array, conditionally add elements
12908 @cindex sum array elements
12911 @item @emph{Description}:
12912 Adds the elements of @var{ARRAY} along dimension @var{DIM} if
12913 the corresponding element in @var{MASK} is @code{TRUE}.
12915 @item @emph{Standard}:
12916 Fortran 95 and later
12918 @item @emph{Class}:
12919 Transformational function
12921 @item @emph{Syntax}:
12922 @multitable @columnfractions .80
12923 @item @code{RESULT = SUM(ARRAY[, MASK])}
12924 @item @code{RESULT = SUM(ARRAY, DIM[, MASK])}
12927 @item @emph{Arguments}:
12928 @multitable @columnfractions .15 .70
12929 @item @var{ARRAY} @tab Shall be an array of type @code{INTEGER},
12930 @code{REAL} or @code{COMPLEX}.
12931 @item @var{DIM} @tab (Optional) shall be a scalar of type
12932 @code{INTEGER} with a value in the range from 1 to n, where n
12933 equals the rank of @var{ARRAY}.
12934 @item @var{MASK} @tab (Optional) shall be of type @code{LOGICAL}
12935 and either be a scalar or an array of the same shape as @var{ARRAY}.
12938 @item @emph{Return value}:
12939 The result is of the same type as @var{ARRAY}.
12941 If @var{DIM} is absent, a scalar with the sum of all elements in @var{ARRAY}
12942 is returned. Otherwise, an array of rank n-1, where n equals the rank of
12943 @var{ARRAY}, and a shape similar to that of @var{ARRAY} with dimension @var{DIM}
12944 dropped is returned.
12946 @item @emph{Example}:
12949 INTEGER :: x(5) = (/ 1, 2, 3, 4 ,5 /)
12950 print *, SUM(x) ! all elements, sum = 15
12951 print *, SUM(x, MASK=MOD(x, 2)==1) ! odd elements, sum = 9
12955 @item @emph{See also}:
12962 @section @code{SYMLNK} --- Create a symbolic link
12964 @cindex file system, create link
12965 @cindex file system, soft link
12968 @item @emph{Description}:
12969 Makes a symbolic link from file @var{PATH1} to @var{PATH2}. A null
12970 character (@code{CHAR(0)}) can be used to mark the end of the names in
12971 @var{PATH1} and @var{PATH2}; otherwise, trailing blanks in the file
12972 names are ignored. If the @var{STATUS} argument is supplied, it
12973 contains 0 on success or a nonzero error code upon return; see
12974 @code{symlink(2)}. If the system does not supply @code{symlink(2)},
12975 @code{ENOSYS} is returned.
12977 This intrinsic is provided in both subroutine and function forms;
12978 however, only one form can be used in any given program unit.
12980 @item @emph{Standard}:
12983 @item @emph{Class}:
12984 Subroutine, function
12986 @item @emph{Syntax}:
12987 @multitable @columnfractions .80
12988 @item @code{CALL SYMLNK(PATH1, PATH2 [, STATUS])}
12989 @item @code{STATUS = SYMLNK(PATH1, PATH2)}
12992 @item @emph{Arguments}:
12993 @multitable @columnfractions .15 .70
12994 @item @var{PATH1} @tab Shall be of default @code{CHARACTER} type.
12995 @item @var{PATH2} @tab Shall be of default @code{CHARACTER} type.
12996 @item @var{STATUS} @tab (Optional) Shall be of default @code{INTEGER} type.
12999 @item @emph{See also}:
13000 @ref{LINK}, @ref{UNLINK}
13007 @section @code{SYSTEM} --- Execute a shell command
13009 @cindex system, system call
13012 @item @emph{Description}:
13013 Passes the command @var{COMMAND} to a shell (see @code{system(3)}). If
13014 argument @var{STATUS} is present, it contains the value returned by
13015 @code{system(3)}, which is presumably 0 if the shell command succeeded.
13016 Note that which shell is used to invoke the command is system-dependent
13017 and environment-dependent.
13019 This intrinsic is provided in both subroutine and function forms;
13020 however, only one form can be used in any given program unit.
13022 Note that the @code{system} function need not be thread-safe. It is
13023 the responsibility of the user to ensure that @code{system} is not
13024 called concurrently.
13026 @item @emph{Standard}:
13029 @item @emph{Class}:
13030 Subroutine, function
13032 @item @emph{Syntax}:
13033 @multitable @columnfractions .80
13034 @item @code{CALL SYSTEM(COMMAND [, STATUS])}
13035 @item @code{STATUS = SYSTEM(COMMAND)}
13038 @item @emph{Arguments}:
13039 @multitable @columnfractions .15 .70
13040 @item @var{COMMAND} @tab Shall be of default @code{CHARACTER} type.
13041 @item @var{STATUS} @tab (Optional) Shall be of default @code{INTEGER} type.
13044 @item @emph{See also}:
13045 @ref{EXECUTE_COMMAND_LINE}, which is part of the Fortran 2008 standard
13046 and should considered in new code for future portability.
13052 @section @code{SYSTEM_CLOCK} --- Time function
13053 @fnindex SYSTEM_CLOCK
13054 @cindex time, clock ticks
13055 @cindex clock ticks
13058 @item @emph{Description}:
13059 Determines the @var{COUNT} of a processor clock since an unspecified
13060 time in the past modulo @var{COUNT_MAX}, @var{COUNT_RATE} determines
13061 the number of clock ticks per second. If the platform supports a
13062 monotonic clock, that clock is used and can, depending on the platform
13063 clock implementation, provide up to nanosecond resolution. If a
13064 monotonic clock is not available, the implementation falls back to a
13067 @var{COUNT_RATE} is system dependent and can vary depending on the kind of
13068 the arguments. For @var{kind=4} arguments (and smaller integer kinds),
13069 @var{COUNT} represents milliseconds, while for @var{kind=8} arguments (and
13070 larger integer kinds), @var{COUNT} typically represents micro- or
13071 nanoseconds depending on resolution of the underlying platform clock.
13072 @var{COUNT_MAX} usually equals @code{HUGE(COUNT_MAX)}. Note that the
13073 millisecond resolution of the @var{kind=4} version implies that the
13074 @var{COUNT} will wrap around in roughly 25 days. In order to avoid issues
13075 with the wrap around and for more precise timing, please use the
13076 @var{kind=8} version.
13078 If there is no clock, or querying the clock fails, @var{COUNT} is set
13079 to @code{-HUGE(COUNT)}, and @var{COUNT_RATE} and @var{COUNT_MAX} are
13082 When running on a platform using the GNU C library (glibc) version
13083 2.16 or older, or a derivative thereof, the high resolution monotonic
13084 clock is available only when linking with the @var{rt} library. This
13085 can be done explicitly by adding the @code{-lrt} flag when linking the
13086 application, but is also done implicitly when using OpenMP.
13088 On the Windows platform, the version with @var{kind=4} arguments uses
13089 the @code{GetTickCount} function, whereas the @var{kind=8} version
13090 uses @code{QueryPerformanceCounter} and
13091 @code{QueryPerformanceCounterFrequency}. For more information, and
13092 potential caveats, please see the platform documentation.
13094 @item @emph{Standard}:
13095 Fortran 95 and later
13097 @item @emph{Class}:
13100 @item @emph{Syntax}:
13101 @code{CALL SYSTEM_CLOCK([COUNT, COUNT_RATE, COUNT_MAX])}
13103 @item @emph{Arguments}:
13104 @multitable @columnfractions .15 .70
13105 @item @var{COUNT} @tab (Optional) shall be a scalar of type
13106 @code{INTEGER} with @code{INTENT(OUT)}.
13107 @item @var{COUNT_RATE} @tab (Optional) shall be a scalar of type
13108 @code{INTEGER} or @code{REAL}, with @code{INTENT(OUT)}.
13109 @item @var{COUNT_MAX} @tab (Optional) shall be a scalar of type
13110 @code{INTEGER} with @code{INTENT(OUT)}.
13113 @item @emph{Example}:
13115 PROGRAM test_system_clock
13116 INTEGER :: count, count_rate, count_max
13117 CALL SYSTEM_CLOCK(count, count_rate, count_max)
13118 WRITE(*,*) count, count_rate, count_max
13122 @item @emph{See also}:
13123 @ref{DATE_AND_TIME}, @ref{CPU_TIME}
13129 @section @code{TAN} --- Tangent function
13132 @cindex trigonometric function, tangent
13136 @item @emph{Description}:
13137 @code{TAN(X)} computes the tangent of @var{X}.
13139 @item @emph{Standard}:
13140 Fortran 77 and later, for a complex argument Fortran 2008 or later
13142 @item @emph{Class}:
13145 @item @emph{Syntax}:
13146 @code{RESULT = TAN(X)}
13148 @item @emph{Arguments}:
13149 @multitable @columnfractions .15 .70
13150 @item @var{X} @tab The type shall be @code{REAL} or @code{COMPLEX}.
13153 @item @emph{Return value}:
13154 The return value has same type and kind as @var{X}.
13156 @item @emph{Example}:
13159 real(8) :: x = 0.165_8
13161 end program test_tan
13164 @item @emph{Specific names}:
13165 @multitable @columnfractions .20 .20 .20 .25
13166 @item Name @tab Argument @tab Return type @tab Standard
13167 @item @code{TAN(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab Fortran 95 and later
13168 @item @code{DTAN(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab Fortran 95 and later
13171 @item @emph{See also}:
13178 @section @code{TANH} --- Hyperbolic tangent function
13181 @cindex hyperbolic tangent
13182 @cindex hyperbolic function, tangent
13183 @cindex tangent, hyperbolic
13186 @item @emph{Description}:
13187 @code{TANH(X)} computes the hyperbolic tangent of @var{X}.
13189 @item @emph{Standard}:
13190 Fortran 77 and later, for a complex argument Fortran 2008 or later
13192 @item @emph{Class}:
13195 @item @emph{Syntax}:
13198 @item @emph{Arguments}:
13199 @multitable @columnfractions .15 .70
13200 @item @var{X} @tab The type shall be @code{REAL} or @code{COMPLEX}.
13203 @item @emph{Return value}:
13204 The return value has same type and kind as @var{X}. If @var{X} is
13205 complex, the imaginary part of the result is in radians. If @var{X}
13206 is @code{REAL}, the return value lies in the range
13207 @math{ - 1 \leq tanh(x) \leq 1 }.
13209 @item @emph{Example}:
13212 real(8) :: x = 2.1_8
13214 end program test_tanh
13217 @item @emph{Specific names}:
13218 @multitable @columnfractions .20 .20 .20 .25
13219 @item Name @tab Argument @tab Return type @tab Standard
13220 @item @code{TANH(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab Fortran 95 and later
13221 @item @code{DTANH(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab Fortran 95 and later
13224 @item @emph{See also}:
13231 @section @code{THIS_IMAGE} --- Function that returns the cosubscript index of this image
13232 @fnindex THIS_IMAGE
13233 @cindex coarray, @code{THIS_IMAGE}
13234 @cindex images, index of this image
13237 @item @emph{Description}:
13238 Returns the cosubscript for this image.
13240 @item @emph{Standard}:
13241 Fortran 2008 and later. With @var{DISTANCE} argument,
13242 Technical Specification (TS) 18508 or later
13244 @item @emph{Class}:
13245 Transformational function
13247 @item @emph{Syntax}:
13248 @multitable @columnfractions .80
13249 @item @code{RESULT = THIS_IMAGE()}
13250 @item @code{RESULT = THIS_IMAGE(DISTANCE)}
13251 @item @code{RESULT = THIS_IMAGE(COARRAY [, DIM])}
13254 @item @emph{Arguments}:
13255 @multitable @columnfractions .15 .70
13256 @item @var{DISTANCE} @tab (optional, intent(in)) Nonnegative scalar integer
13257 (not permitted together with @var{COARRAY}).
13258 @item @var{COARRAY} @tab Coarray of any type (optional; if @var{DIM}
13259 present, required).
13260 @item @var{DIM} @tab default integer scalar (optional). If present,
13261 @var{DIM} shall be between one and the corank of @var{COARRAY}.
13265 @item @emph{Return value}:
13266 Default integer. If @var{COARRAY} is not present, it is scalar; if
13267 @var{DISTANCE} is not present or has value 0, its value is the image index on
13268 the invoking image for the current team, for values smaller or equal
13269 distance to the initial team, it returns the image index on the ancestor team
13270 which has a distance of @var{DISTANCE} from the invoking team. If
13271 @var{DISTANCE} is larger than the distance to the initial team, the image
13272 index of the initial team is returned. Otherwise when the @var{COARRAY} is
13273 present, if @var{DIM} is not present, a rank-1 array with corank elements is
13274 returned, containing the cosubscripts for @var{COARRAY} specifying the invoking
13275 image. If @var{DIM} is present, a scalar is returned, with the value of
13276 the @var{DIM} element of @code{THIS_IMAGE(COARRAY)}.
13278 @item @emph{Example}:
13280 INTEGER :: value[*]
13282 value = THIS_IMAGE()
13284 IF (THIS_IMAGE() == 1) THEN
13285 DO i = 1, NUM_IMAGES()
13286 WRITE(*,'(2(a,i0))') 'value[', i, '] is ', value[i]
13290 ! Check whether the current image is the initial image
13291 IF (THIS_IMAGE(HUGE(1)) /= THIS_IMAGE())
13292 error stop "something is rotten here"
13295 @item @emph{See also}:
13296 @ref{NUM_IMAGES}, @ref{IMAGE_INDEX}
13302 @section @code{TIME} --- Time function
13304 @cindex time, current
13305 @cindex current time
13308 @item @emph{Description}:
13309 Returns the current time encoded as an integer (in the manner of the
13310 function @code{time(3)} in the C standard library). This value is
13311 suitable for passing to @code{CTIME}, @code{GMTIME}, and @code{LTIME}.
13313 This intrinsic is not fully portable, such as to systems with 32-bit
13314 @code{INTEGER} types but supporting times wider than 32 bits. Therefore,
13315 the values returned by this intrinsic might be, or become, negative, or
13316 numerically less than previous values, during a single run of the
13319 See @ref{TIME8}, for information on a similar intrinsic that might be
13320 portable to more GNU Fortran implementations, though to fewer Fortran
13323 @item @emph{Standard}:
13326 @item @emph{Class}:
13329 @item @emph{Syntax}:
13330 @code{RESULT = TIME()}
13332 @item @emph{Return value}:
13333 The return value is a scalar of type @code{INTEGER(4)}.
13335 @item @emph{See also}:
13336 @ref{CTIME}, @ref{GMTIME}, @ref{LTIME}, @ref{MCLOCK}, @ref{TIME8}
13343 @section @code{TIME8} --- Time function (64-bit)
13345 @cindex time, current
13346 @cindex current time
13349 @item @emph{Description}:
13350 Returns the current time encoded as an integer (in the manner of the
13351 function @code{time(3)} in the C standard library). This value is
13352 suitable for passing to @code{CTIME}, @code{GMTIME}, and @code{LTIME}.
13354 @emph{Warning:} this intrinsic does not increase the range of the timing
13355 values over that returned by @code{time(3)}. On a system with a 32-bit
13356 @code{time(3)}, @code{TIME8} will return a 32-bit value, even though
13357 it is converted to a 64-bit @code{INTEGER(8)} value. That means
13358 overflows of the 32-bit value can still occur. Therefore, the values
13359 returned by this intrinsic might be or become negative or numerically
13360 less than previous values during a single run of the compiled program.
13362 @item @emph{Standard}:
13365 @item @emph{Class}:
13368 @item @emph{Syntax}:
13369 @code{RESULT = TIME8()}
13371 @item @emph{Return value}:
13372 The return value is a scalar of type @code{INTEGER(8)}.
13374 @item @emph{See also}:
13375 @ref{CTIME}, @ref{GMTIME}, @ref{LTIME}, @ref{MCLOCK8}, @ref{TIME}
13382 @section @code{TINY} --- Smallest positive number of a real kind
13384 @cindex limits, smallest number
13385 @cindex model representation, smallest number
13388 @item @emph{Description}:
13389 @code{TINY(X)} returns the smallest positive (non zero) number
13390 in the model of the type of @code{X}.
13392 @item @emph{Standard}:
13393 Fortran 95 and later
13395 @item @emph{Class}:
13398 @item @emph{Syntax}:
13399 @code{RESULT = TINY(X)}
13401 @item @emph{Arguments}:
13402 @multitable @columnfractions .15 .70
13403 @item @var{X} @tab Shall be of type @code{REAL}.
13406 @item @emph{Return value}:
13407 The return value is of the same type and kind as @var{X}
13409 @item @emph{Example}:
13410 See @code{HUGE} for an example.
13416 @section @code{TRAILZ} --- Number of trailing zero bits of an integer
13421 @item @emph{Description}:
13422 @code{TRAILZ} returns the number of trailing zero bits of an integer.
13424 @item @emph{Standard}:
13425 Fortran 2008 and later
13427 @item @emph{Class}:
13430 @item @emph{Syntax}:
13431 @code{RESULT = TRAILZ(I)}
13433 @item @emph{Arguments}:
13434 @multitable @columnfractions .15 .70
13435 @item @var{I} @tab Shall be of type @code{INTEGER}.
13438 @item @emph{Return value}:
13439 The type of the return value is the default @code{INTEGER}.
13440 If all the bits of @code{I} are zero, the result value is @code{BIT_SIZE(I)}.
13442 @item @emph{Example}:
13444 PROGRAM test_trailz
13445 WRITE (*,*) TRAILZ(8) ! prints 3
13449 @item @emph{See also}:
13450 @ref{BIT_SIZE}, @ref{LEADZ}, @ref{POPPAR}, @ref{POPCNT}
13456 @section @code{TRANSFER} --- Transfer bit patterns
13462 @item @emph{Description}:
13463 Interprets the bitwise representation of @var{SOURCE} in memory as if it
13464 is the representation of a variable or array of the same type and type
13465 parameters as @var{MOLD}.
13467 This is approximately equivalent to the C concept of @emph{casting} one
13470 @item @emph{Standard}:
13471 Fortran 95 and later
13473 @item @emph{Class}:
13474 Transformational function
13476 @item @emph{Syntax}:
13477 @code{RESULT = TRANSFER(SOURCE, MOLD[, SIZE])}
13479 @item @emph{Arguments}:
13480 @multitable @columnfractions .15 .70
13481 @item @var{SOURCE} @tab Shall be a scalar or an array of any type.
13482 @item @var{MOLD} @tab Shall be a scalar or an array of any type.
13483 @item @var{SIZE} @tab (Optional) shall be a scalar of type
13487 @item @emph{Return value}:
13488 The result has the same type as @var{MOLD}, with the bit level
13489 representation of @var{SOURCE}. If @var{SIZE} is present, the result is
13490 a one-dimensional array of length @var{SIZE}. If @var{SIZE} is absent
13491 but @var{MOLD} is an array (of any size or shape), the result is a one-
13492 dimensional array of the minimum length needed to contain the entirety
13493 of the bitwise representation of @var{SOURCE}. If @var{SIZE} is absent
13494 and @var{MOLD} is a scalar, the result is a scalar.
13496 If the bitwise representation of the result is longer than that of
13497 @var{SOURCE}, then the leading bits of the result correspond to those of
13498 @var{SOURCE} and any trailing bits are filled arbitrarily.
13500 When the resulting bit representation does not correspond to a valid
13501 representation of a variable of the same type as @var{MOLD}, the results
13502 are undefined, and subsequent operations on the result cannot be
13503 guaranteed to produce sensible behavior. For example, it is possible to
13504 create @code{LOGICAL} variables for which @code{@var{VAR}} and
13505 @code{.NOT.@var{VAR}} both appear to be true.
13507 @item @emph{Example}:
13509 PROGRAM test_transfer
13510 integer :: x = 2143289344
13511 print *, transfer(x, 1.0) ! prints "NaN" on i686
13519 @section @code{TRANSPOSE} --- Transpose an array of rank two
13521 @cindex array, transpose
13522 @cindex matrix, transpose
13526 @item @emph{Description}:
13527 Transpose an array of rank two. Element (i, j) of the result has the value
13528 @code{MATRIX(j, i)}, for all i, j.
13530 @item @emph{Standard}:
13531 Fortran 95 and later
13533 @item @emph{Class}:
13534 Transformational function
13536 @item @emph{Syntax}:
13537 @code{RESULT = TRANSPOSE(MATRIX)}
13539 @item @emph{Arguments}:
13540 @multitable @columnfractions .15 .70
13541 @item @var{MATRIX} @tab Shall be an array of any type and have a rank of two.
13544 @item @emph{Return value}:
13545 The result has the same type as @var{MATRIX}, and has shape
13546 @code{(/ m, n /)} if @var{MATRIX} has shape @code{(/ n, m /)}.
13552 @section @code{TRIM} --- Remove trailing blank characters of a string
13554 @cindex string, remove trailing whitespace
13557 @item @emph{Description}:
13558 Removes trailing blank characters of a string.
13560 @item @emph{Standard}:
13561 Fortran 95 and later
13563 @item @emph{Class}:
13564 Transformational function
13566 @item @emph{Syntax}:
13567 @code{RESULT = TRIM(STRING)}
13569 @item @emph{Arguments}:
13570 @multitable @columnfractions .15 .70
13571 @item @var{STRING} @tab Shall be a scalar of type @code{CHARACTER}.
13574 @item @emph{Return value}:
13575 A scalar of type @code{CHARACTER} which length is that of @var{STRING}
13576 less the number of trailing blanks.
13578 @item @emph{Example}:
13581 CHARACTER(len=10), PARAMETER :: s = "GFORTRAN "
13582 WRITE(*,*) LEN(s), LEN(TRIM(s)) ! "10 8", with/without trailing blanks
13586 @item @emph{See also}:
13587 @ref{ADJUSTL}, @ref{ADJUSTR}
13593 @section @code{TTYNAM} --- Get the name of a terminal device.
13595 @cindex system, terminal
13598 @item @emph{Description}:
13599 Get the name of a terminal device. For more information,
13600 see @code{ttyname(3)}.
13602 This intrinsic is provided in both subroutine and function forms;
13603 however, only one form can be used in any given program unit.
13605 @item @emph{Standard}:
13608 @item @emph{Class}:
13609 Subroutine, function
13611 @item @emph{Syntax}:
13612 @multitable @columnfractions .80
13613 @item @code{CALL TTYNAM(UNIT, NAME)}
13614 @item @code{NAME = TTYNAM(UNIT)}
13617 @item @emph{Arguments}:
13618 @multitable @columnfractions .15 .70
13619 @item @var{UNIT} @tab Shall be a scalar @code{INTEGER}.
13620 @item @var{NAME} @tab Shall be of type @code{CHARACTER}.
13623 @item @emph{Example}:
13625 PROGRAM test_ttynam
13628 IF (isatty(unit=unit)) write(*,*) ttynam(unit)
13633 @item @emph{See also}:
13640 @section @code{UBOUND} --- Upper dimension bounds of an array
13642 @cindex array, upper bound
13645 @item @emph{Description}:
13646 Returns the upper bounds of an array, or a single upper bound
13647 along the @var{DIM} dimension.
13648 @item @emph{Standard}:
13649 Fortran 95 and later, with @var{KIND} argument Fortran 2003 and later
13651 @item @emph{Class}:
13654 @item @emph{Syntax}:
13655 @code{RESULT = UBOUND(ARRAY [, DIM [, KIND]])}
13657 @item @emph{Arguments}:
13658 @multitable @columnfractions .15 .70
13659 @item @var{ARRAY} @tab Shall be an array, of any type.
13660 @item @var{DIM} @tab (Optional) Shall be a scalar @code{INTEGER}.
13661 @item @var{KIND}@tab (Optional) An @code{INTEGER} initialization
13662 expression indicating the kind parameter of the result.
13665 @item @emph{Return value}:
13666 The return value is of type @code{INTEGER} and of kind @var{KIND}. If
13667 @var{KIND} is absent, the return value is of default integer kind.
13668 If @var{DIM} is absent, the result is an array of the upper bounds of
13669 @var{ARRAY}. If @var{DIM} is present, the result is a scalar
13670 corresponding to the upper bound of the array along that dimension. If
13671 @var{ARRAY} is an expression rather than a whole array or array
13672 structure component, or if it has a zero extent along the relevant
13673 dimension, the upper bound is taken to be the number of elements along
13674 the relevant dimension.
13676 @item @emph{See also}:
13677 @ref{LBOUND}, @ref{LCOBOUND}
13683 @section @code{UCOBOUND} --- Upper codimension bounds of an array
13685 @cindex coarray, upper bound
13688 @item @emph{Description}:
13689 Returns the upper cobounds of a coarray, or a single upper cobound
13690 along the @var{DIM} codimension.
13691 @item @emph{Standard}:
13692 Fortran 2008 and later
13694 @item @emph{Class}:
13697 @item @emph{Syntax}:
13698 @code{RESULT = UCOBOUND(COARRAY [, DIM [, KIND]])}
13700 @item @emph{Arguments}:
13701 @multitable @columnfractions .15 .70
13702 @item @var{ARRAY} @tab Shall be an coarray, of any type.
13703 @item @var{DIM} @tab (Optional) Shall be a scalar @code{INTEGER}.
13704 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
13705 expression indicating the kind parameter of the result.
13708 @item @emph{Return value}:
13709 The return value is of type @code{INTEGER} and of kind @var{KIND}. If
13710 @var{KIND} is absent, the return value is of default integer kind.
13711 If @var{DIM} is absent, the result is an array of the lower cobounds of
13712 @var{COARRAY}. If @var{DIM} is present, the result is a scalar
13713 corresponding to the lower cobound of the array along that codimension.
13715 @item @emph{See also}:
13716 @ref{LCOBOUND}, @ref{LBOUND}
13722 @section @code{UMASK} --- Set the file creation mask
13724 @cindex file system, file creation mask
13727 @item @emph{Description}:
13728 Sets the file creation mask to @var{MASK}. If called as a function, it
13729 returns the old value. If called as a subroutine and argument @var{OLD}
13730 if it is supplied, it is set to the old value. See @code{umask(2)}.
13732 @item @emph{Standard}:
13735 @item @emph{Class}:
13736 Subroutine, function
13738 @item @emph{Syntax}:
13739 @multitable @columnfractions .80
13740 @item @code{CALL UMASK(MASK [, OLD])}
13741 @item @code{OLD = UMASK(MASK)}
13744 @item @emph{Arguments}:
13745 @multitable @columnfractions .15 .70
13746 @item @var{MASK} @tab Shall be a scalar of type @code{INTEGER}.
13747 @item @var{OLD} @tab (Optional) Shall be a scalar of type
13756 @section @code{UNLINK} --- Remove a file from the file system
13758 @cindex file system, remove file
13761 @item @emph{Description}:
13762 Unlinks the file @var{PATH}. A null character (@code{CHAR(0)}) can be
13763 used to mark the end of the name in @var{PATH}; otherwise, trailing
13764 blanks in the file name are ignored. If the @var{STATUS} argument is
13765 supplied, it contains 0 on success or a nonzero error code upon return;
13766 see @code{unlink(2)}.
13768 This intrinsic is provided in both subroutine and function forms;
13769 however, only one form can be used in any given program unit.
13771 @item @emph{Standard}:
13774 @item @emph{Class}:
13775 Subroutine, function
13777 @item @emph{Syntax}:
13778 @multitable @columnfractions .80
13779 @item @code{CALL UNLINK(PATH [, STATUS])}
13780 @item @code{STATUS = UNLINK(PATH)}
13783 @item @emph{Arguments}:
13784 @multitable @columnfractions .15 .70
13785 @item @var{PATH} @tab Shall be of default @code{CHARACTER} type.
13786 @item @var{STATUS} @tab (Optional) Shall be of default @code{INTEGER} type.
13789 @item @emph{See also}:
13790 @ref{LINK}, @ref{SYMLNK}
13796 @section @code{UNPACK} --- Unpack an array of rank one into an array
13798 @cindex array, unpacking
13799 @cindex array, increase dimension
13800 @cindex array, scatter elements
13803 @item @emph{Description}:
13804 Store the elements of @var{VECTOR} in an array of higher rank.
13806 @item @emph{Standard}:
13807 Fortran 95 and later
13809 @item @emph{Class}:
13810 Transformational function
13812 @item @emph{Syntax}:
13813 @code{RESULT = UNPACK(VECTOR, MASK, FIELD)}
13815 @item @emph{Arguments}:
13816 @multitable @columnfractions .15 .70
13817 @item @var{VECTOR} @tab Shall be an array of any type and rank one. It
13818 shall have at least as many elements as @var{MASK} has @code{TRUE} values.
13819 @item @var{MASK} @tab Shall be an array of type @code{LOGICAL}.
13820 @item @var{FIELD} @tab Shall be of the same type as @var{VECTOR} and have
13821 the same shape as @var{MASK}.
13824 @item @emph{Return value}:
13825 The resulting array corresponds to @var{FIELD} with @code{TRUE} elements
13826 of @var{MASK} replaced by values from @var{VECTOR} in array element order.
13828 @item @emph{Example}:
13830 PROGRAM test_unpack
13831 integer :: vector(2) = (/1,1/)
13832 logical :: mask(4) = (/ .TRUE., .FALSE., .FALSE., .TRUE. /)
13833 integer :: field(2,2) = 0, unity(2,2)
13835 ! result: unity matrix
13836 unity = unpack(vector, reshape(mask, (/2,2/)), field)
13840 @item @emph{See also}:
13841 @ref{PACK}, @ref{SPREAD}
13847 @section @code{VERIFY} --- Scan a string for characters not a given set
13849 @cindex string, find missing set
13852 @item @emph{Description}:
13853 Verifies that all the characters in @var{STRING} belong to the set of
13854 characters in @var{SET}.
13856 If @var{BACK} is either absent or equals @code{FALSE}, this function
13857 returns the position of the leftmost character of @var{STRING} that is
13858 not in @var{SET}. If @var{BACK} equals @code{TRUE}, the rightmost
13859 position is returned. If all characters of @var{STRING} are found in
13860 @var{SET}, the result is zero.
13862 @item @emph{Standard}:
13863 Fortran 95 and later, with @var{KIND} argument Fortran 2003 and later
13865 @item @emph{Class}:
13868 @item @emph{Syntax}:
13869 @code{RESULT = VERIFY(STRING, SET[, BACK [, KIND]])}
13871 @item @emph{Arguments}:
13872 @multitable @columnfractions .15 .70
13873 @item @var{STRING} @tab Shall be of type @code{CHARACTER}.
13874 @item @var{SET} @tab Shall be of type @code{CHARACTER}.
13875 @item @var{BACK} @tab (Optional) shall be of type @code{LOGICAL}.
13876 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
13877 expression indicating the kind parameter of the result.
13880 @item @emph{Return value}:
13881 The return value is of type @code{INTEGER} and of kind @var{KIND}. If
13882 @var{KIND} is absent, the return value is of default integer kind.
13884 @item @emph{Example}:
13886 PROGRAM test_verify
13887 WRITE(*,*) VERIFY("FORTRAN", "AO") ! 1, found 'F'
13888 WRITE(*,*) VERIFY("FORTRAN", "FOO") ! 3, found 'R'
13889 WRITE(*,*) VERIFY("FORTRAN", "C++") ! 1, found 'F'
13890 WRITE(*,*) VERIFY("FORTRAN", "C++", .TRUE.) ! 7, found 'N'
13891 WRITE(*,*) VERIFY("FORTRAN", "FORTRAN") ! 0' found none
13895 @item @emph{See also}:
13896 @ref{SCAN}, @ref{INDEX intrinsic}
13902 @section @code{XOR} --- Bitwise logical exclusive OR
13904 @cindex bitwise logical exclusive or
13905 @cindex logical exclusive or, bitwise
13908 @item @emph{Description}:
13909 Bitwise logical exclusive or.
13911 This intrinsic routine is provided for backwards compatibility with
13912 GNU Fortran 77. For integer arguments, programmers should consider
13913 the use of the @ref{IEOR} intrinsic and for logical arguments the
13914 @code{.NEQV.} operator, which are both defined by the Fortran standard.
13916 @item @emph{Standard}:
13919 @item @emph{Class}:
13922 @item @emph{Syntax}:
13923 @code{RESULT = XOR(I, J)}
13925 @item @emph{Arguments}:
13926 @multitable @columnfractions .15 .70
13927 @item @var{I} @tab The type shall be either a scalar @code{INTEGER}
13928 type or a scalar @code{LOGICAL} type.
13929 @item @var{J} @tab The type shall be the same as the type of @var{I}.
13932 @item @emph{Return value}:
13933 The return type is either a scalar @code{INTEGER} or a scalar
13934 @code{LOGICAL}. If the kind type parameters differ, then the
13935 smaller kind type is implicitly converted to larger kind, and the
13936 return has the larger kind.
13938 @item @emph{Example}:
13941 LOGICAL :: T = .TRUE., F = .FALSE.
13943 DATA a / Z'F' /, b / Z'3' /
13945 WRITE (*,*) XOR(T, T), XOR(T, F), XOR(F, T), XOR(F, F)
13946 WRITE (*,*) XOR(a, b)
13950 @item @emph{See also}:
13951 Fortran 95 elemental function: @ref{IEOR}
13956 @node Intrinsic Modules
13957 @chapter Intrinsic Modules
13958 @cindex intrinsic Modules
13961 * ISO_FORTRAN_ENV::
13964 * OpenMP Modules OMP_LIB and OMP_LIB_KINDS::
13965 * OpenACC Module OPENACC::
13968 @node ISO_FORTRAN_ENV
13969 @section @code{ISO_FORTRAN_ENV}
13971 @item @emph{Standard}:
13972 Fortran 2003 and later, except when otherwise noted
13975 The @code{ISO_FORTRAN_ENV} module provides the following scalar default-integer
13979 @item @code{ATOMIC_INT_KIND}:
13980 Default-kind integer constant to be used as kind parameter when defining
13981 integer variables used in atomic operations. (Fortran 2008 or later.)
13983 @item @code{ATOMIC_LOGICAL_KIND}:
13984 Default-kind integer constant to be used as kind parameter when defining
13985 logical variables used in atomic operations. (Fortran 2008 or later.)
13987 @item @code{CHARACTER_KINDS}:
13988 Default-kind integer constant array of rank one containing the supported kind
13989 parameters of the @code{CHARACTER} type. (Fortran 2008 or later.)
13991 @item @code{CHARACTER_STORAGE_SIZE}:
13992 Size in bits of the character storage unit.
13994 @item @code{ERROR_UNIT}:
13995 Identifies the preconnected unit used for error reporting.
13997 @item @code{FILE_STORAGE_SIZE}:
13998 Size in bits of the file-storage unit.
14000 @item @code{INPUT_UNIT}:
14001 Identifies the preconnected unit identified by the asterisk
14002 (@code{*}) in @code{READ} statement.
14004 @item @code{INT8}, @code{INT16}, @code{INT32}, @code{INT64}:
14005 Kind type parameters to specify an INTEGER type with a storage
14006 size of 16, 32, and 64 bits. It is negative if a target platform
14007 does not support the particular kind. (Fortran 2008 or later.)
14009 @item @code{INTEGER_KINDS}:
14010 Default-kind integer constant array of rank one containing the supported kind
14011 parameters of the @code{INTEGER} type. (Fortran 2008 or later.)
14013 @item @code{IOSTAT_END}:
14014 The value assigned to the variable passed to the @code{IOSTAT=} specifier of
14015 an input/output statement if an end-of-file condition occurred.
14017 @item @code{IOSTAT_EOR}:
14018 The value assigned to the variable passed to the @code{IOSTAT=} specifier of
14019 an input/output statement if an end-of-record condition occurred.
14021 @item @code{IOSTAT_INQUIRE_INTERNAL_UNIT}:
14022 Scalar default-integer constant, used by @code{INQUIRE} for the
14023 @code{IOSTAT=} specifier to denote an that a unit number identifies an
14024 internal unit. (Fortran 2008 or later.)
14026 @item @code{NUMERIC_STORAGE_SIZE}:
14027 The size in bits of the numeric storage unit.
14029 @item @code{LOGICAL_KINDS}:
14030 Default-kind integer constant array of rank one containing the supported kind
14031 parameters of the @code{LOGICAL} type. (Fortran 2008 or later.)
14033 @item @code{OUTPUT_UNIT}:
14034 Identifies the preconnected unit identified by the asterisk
14035 (@code{*}) in @code{WRITE} statement.
14037 @item @code{REAL32}, @code{REAL64}, @code{REAL128}:
14038 Kind type parameters to specify a REAL type with a storage
14039 size of 32, 64, and 128 bits. It is negative if a target platform
14040 does not support the particular kind. (Fortran 2008 or later.)
14042 @item @code{REAL_KINDS}:
14043 Default-kind integer constant array of rank one containing the supported kind
14044 parameters of the @code{REAL} type. (Fortran 2008 or later.)
14046 @item @code{STAT_LOCKED}:
14047 Scalar default-integer constant used as STAT= return value by @code{LOCK} to
14048 denote that the lock variable is locked by the executing image. (Fortran 2008
14051 @item @code{STAT_LOCKED_OTHER_IMAGE}:
14052 Scalar default-integer constant used as STAT= return value by @code{UNLOCK} to
14053 denote that the lock variable is locked by another image. (Fortran 2008 or
14056 @item @code{STAT_STOPPED_IMAGE}:
14057 Positive, scalar default-integer constant used as STAT= return value if the
14058 argument in the statement requires synchronisation with an image, which has
14059 initiated the termination of the execution. (Fortran 2008 or later.)
14061 @item @code{STAT_FAILED_IMAGE}:
14062 Positive, scalar default-integer constant used as STAT= return value if the
14063 argument in the statement requires communication with an image, which has
14064 is in the failed state. (TS 18508 or later.)
14066 @item @code{STAT_UNLOCKED}:
14067 Scalar default-integer constant used as STAT= return value by @code{UNLOCK} to
14068 denote that the lock variable is unlocked. (Fortran 2008 or later.)
14071 The module provides the following derived type:
14074 @item @code{LOCK_TYPE}:
14075 Derived type with private components to be use with the @code{LOCK} and
14076 @code{UNLOCK} statement. A variable of its type has to be always declared
14077 as coarray and may not appear in a variable-definition context.
14078 (Fortran 2008 or later.)
14081 The module also provides the following intrinsic procedures:
14082 @ref{COMPILER_OPTIONS} and @ref{COMPILER_VERSION}.
14086 @node ISO_C_BINDING
14087 @section @code{ISO_C_BINDING}
14089 @item @emph{Standard}:
14090 Fortran 2003 and later, GNU extensions
14093 The following intrinsic procedures are provided by the module; their
14094 definition can be found in the section Intrinsic Procedures of this
14098 @item @code{C_ASSOCIATED}
14099 @item @code{C_F_POINTER}
14100 @item @code{C_F_PROCPOINTER}
14101 @item @code{C_FUNLOC}
14103 @item @code{C_SIZEOF}
14105 @c TODO: Vertical spacing between C_FUNLOC and C_LOC wrong in PDF,
14106 @c don't really know why.
14108 The @code{ISO_C_BINDING} module provides the following named constants of
14109 type default integer, which can be used as KIND type parameters.
14111 In addition to the integer named constants required by the Fortran 2003
14112 standard and @code{C_PTRDIFF_T} of TS 29113, GNU Fortran provides as an
14113 extension named constants for the 128-bit integer types supported by the
14114 C compiler: @code{C_INT128_T, C_INT_LEAST128_T, C_INT_FAST128_T}.
14115 Furthermore, if @code{__float128} is supported in C, the named constants
14116 @code{C_FLOAT128, C_FLOAT128_COMPLEX} are defined.
14118 @multitable @columnfractions .15 .35 .35 .35
14119 @item Fortran Type @tab Named constant @tab C type @tab Extension
14120 @item @code{INTEGER}@tab @code{C_INT} @tab @code{int}
14121 @item @code{INTEGER}@tab @code{C_SHORT} @tab @code{short int}
14122 @item @code{INTEGER}@tab @code{C_LONG} @tab @code{long int}
14123 @item @code{INTEGER}@tab @code{C_LONG_LONG} @tab @code{long long int}
14124 @item @code{INTEGER}@tab @code{C_SIGNED_CHAR} @tab @code{signed char}/@code{unsigned char}
14125 @item @code{INTEGER}@tab @code{C_SIZE_T} @tab @code{size_t}
14126 @item @code{INTEGER}@tab @code{C_INT8_T} @tab @code{int8_t}
14127 @item @code{INTEGER}@tab @code{C_INT16_T} @tab @code{int16_t}
14128 @item @code{INTEGER}@tab @code{C_INT32_T} @tab @code{int32_t}
14129 @item @code{INTEGER}@tab @code{C_INT64_T} @tab @code{int64_t}
14130 @item @code{INTEGER}@tab @code{C_INT128_T} @tab @code{int128_t} @tab Ext.
14131 @item @code{INTEGER}@tab @code{C_INT_LEAST8_T} @tab @code{int_least8_t}
14132 @item @code{INTEGER}@tab @code{C_INT_LEAST16_T} @tab @code{int_least16_t}
14133 @item @code{INTEGER}@tab @code{C_INT_LEAST32_T} @tab @code{int_least32_t}
14134 @item @code{INTEGER}@tab @code{C_INT_LEAST64_T} @tab @code{int_least64_t}
14135 @item @code{INTEGER}@tab @code{C_INT_LEAST128_T}@tab @code{int_least128_t} @tab Ext.
14136 @item @code{INTEGER}@tab @code{C_INT_FAST8_T} @tab @code{int_fast8_t}
14137 @item @code{INTEGER}@tab @code{C_INT_FAST16_T} @tab @code{int_fast16_t}
14138 @item @code{INTEGER}@tab @code{C_INT_FAST32_T} @tab @code{int_fast32_t}
14139 @item @code{INTEGER}@tab @code{C_INT_FAST64_T} @tab @code{int_fast64_t}
14140 @item @code{INTEGER}@tab @code{C_INT_FAST128_T} @tab @code{int_fast128_t} @tab Ext.
14141 @item @code{INTEGER}@tab @code{C_INTMAX_T} @tab @code{intmax_t}
14142 @item @code{INTEGER}@tab @code{C_INTPTR_T} @tab @code{intptr_t}
14143 @item @code{INTEGER}@tab @code{C_PTRDIFF_T} @tab @code{intptr_t} @tab TS 29113
14144 @item @code{REAL} @tab @code{C_FLOAT} @tab @code{float}
14145 @item @code{REAL} @tab @code{C_DOUBLE} @tab @code{double}
14146 @item @code{REAL} @tab @code{C_LONG_DOUBLE} @tab @code{long double}
14147 @item @code{REAL} @tab @code{C_FLOAT128} @tab @code{__float128} @tab Ext.
14148 @item @code{COMPLEX}@tab @code{C_FLOAT_COMPLEX} @tab @code{float _Complex}
14149 @item @code{COMPLEX}@tab @code{C_DOUBLE_COMPLEX}@tab @code{double _Complex}
14150 @item @code{COMPLEX}@tab @code{C_LONG_DOUBLE_COMPLEX}@tab @code{long double _Complex}
14151 @item @code{REAL} @tab @code{C_FLOAT128_COMPLEX} @tab @code{__float128 _Complex} @tab Ext.
14152 @item @code{LOGICAL}@tab @code{C_BOOL} @tab @code{_Bool}
14153 @item @code{CHARACTER}@tab @code{C_CHAR} @tab @code{char}
14156 Additionally, the following parameters of type @code{CHARACTER(KIND=C_CHAR)}
14159 @multitable @columnfractions .20 .45 .15
14160 @item Name @tab C definition @tab Value
14161 @item @code{C_NULL_CHAR} @tab null character @tab @code{'\0'}
14162 @item @code{C_ALERT} @tab alert @tab @code{'\a'}
14163 @item @code{C_BACKSPACE} @tab backspace @tab @code{'\b'}
14164 @item @code{C_FORM_FEED} @tab form feed @tab @code{'\f'}
14165 @item @code{C_NEW_LINE} @tab new line @tab @code{'\n'}
14166 @item @code{C_CARRIAGE_RETURN} @tab carriage return @tab @code{'\r'}
14167 @item @code{C_HORIZONTAL_TAB} @tab horizontal tab @tab @code{'\t'}
14168 @item @code{C_VERTICAL_TAB} @tab vertical tab @tab @code{'\v'}
14171 Moreover, the following two named constants are defined:
14173 @multitable @columnfractions .20 .80
14174 @item Name @tab Type
14175 @item @code{C_NULL_PTR} @tab @code{C_PTR}
14176 @item @code{C_NULL_FUNPTR} @tab @code{C_FUNPTR}
14179 Both are equivalent to the value @code{NULL} in C.
14184 @section IEEE modules: @code{IEEE_EXCEPTIONS}, @code{IEEE_ARITHMETIC}, and @code{IEEE_FEATURES}
14186 @item @emph{Standard}:
14187 Fortran 2003 and later
14190 The @code{IEEE_EXCEPTIONS}, @code{IEEE_ARITHMETIC}, and @code{IEEE_FEATURES}
14191 intrinsic modules provide support for exceptions and IEEE arithmetic, as
14192 defined in Fortran 2003 and later standards, and the IEC 60559:1989 standard
14193 (@emph{Binary floating-point arithmetic for microprocessor systems}). These
14194 modules are only provided on the following supported platforms:
14197 @item i386 and x86_64 processors
14198 @item platforms which use the GNU C Library (glibc)
14199 @item platforms with support for SysV/386 routines for floating point
14200 interface (including Solaris and BSDs)
14201 @item platforms with the AIX OS
14204 For full compliance with the Fortran standards, code using the
14205 @code{IEEE_EXCEPTIONS} or @code{IEEE_ARITHMETIC} modules should be compiled
14206 with the following options: @code{-fno-unsafe-math-optimizations
14207 -frounding-math -fsignaling-nans}.
14211 @node OpenMP Modules OMP_LIB and OMP_LIB_KINDS
14212 @section OpenMP Modules @code{OMP_LIB} and @code{OMP_LIB_KINDS}
14214 @item @emph{Standard}:
14215 OpenMP Application Program Interface v4.0
14219 The OpenMP Fortran runtime library routines are provided both in
14220 a form of two Fortran 90 modules, named @code{OMP_LIB} and
14221 @code{OMP_LIB_KINDS}, and in a form of a Fortran @code{include} file named
14222 @file{omp_lib.h}. The procedures provided by @code{OMP_LIB} can be found
14223 in the @ref{Top,,Introduction,libgomp,GNU Offloading and Multi
14224 Processing Runtime Library} manual,
14225 the named constants defined in the modules are listed
14228 For details refer to the actual
14229 @uref{http://www.openmp.org/mp-documents/OpenMP4.0.0.pdf,
14230 OpenMP Application Program Interface v4.0}.
14232 @code{OMP_LIB_KINDS} provides the following scalar default-integer
14236 @item @code{omp_lock_kind}
14237 @item @code{omp_nest_lock_kind}
14238 @item @code{omp_proc_bind_kind}
14239 @item @code{omp_sched_kind}
14242 @code{OMP_LIB} provides the scalar default-integer
14243 named constant @code{openmp_version} with a value of the form
14244 @var{yyyymm}, where @code{yyyy} is the year and @var{mm} the month
14245 of the OpenMP version; for OpenMP v4.0 the value is @code{201307}.
14247 The following scalar integer named constants of the
14248 kind @code{omp_sched_kind}:
14251 @item @code{omp_sched_static}
14252 @item @code{omp_sched_dynamic}
14253 @item @code{omp_sched_guided}
14254 @item @code{omp_sched_auto}
14257 And the following scalar integer named constants of the
14258 kind @code{omp_proc_bind_kind}:
14261 @item @code{omp_proc_bind_false}
14262 @item @code{omp_proc_bind_true}
14263 @item @code{omp_proc_bind_master}
14264 @item @code{omp_proc_bind_close}
14265 @item @code{omp_proc_bind_spread}
14270 @node OpenACC Module OPENACC
14271 @section OpenACC Module @code{OPENACC}
14273 @item @emph{Standard}:
14274 OpenACC Application Programming Interface v2.0
14278 The OpenACC Fortran runtime library routines are provided both in a
14279 form of a Fortran 90 module, named @code{OPENACC}, and in form of a
14280 Fortran @code{include} file named @file{openacc_lib.h}. The
14281 procedures provided by @code{OPENACC} can be found in the
14282 @ref{Top,,Introduction,libgomp,GNU Offloading and Multi Processing
14283 Runtime Library} manual, the named constants defined in the modules
14286 For details refer to the actual
14287 @uref{http://www.openacc.org/,
14288 OpenACC Application Programming Interface v2.0}.
14290 @code{OPENACC} provides the scalar default-integer
14291 named constant @code{openacc_version} with a value of the form
14292 @var{yyyymm}, where @code{yyyy} is the year and @var{mm} the month
14293 of the OpenACC version; for OpenACC v2.0 the value is @code{201306}.