2 Copyright (C) 2005, 2006, 2007, 2008, 2009, 2010
3 Free Software Foundation, Inc.
4 This is part of the GNU Fortran manual.
5 For copying conditions, see the file gfortran.texi.
7 Permission is granted to copy, distribute and/or modify this document
8 under the terms of the GNU Free Documentation License, Version 1.3 or
9 any later version published by the Free Software Foundation; with the
10 Invariant Sections being ``Funding Free Software'', the Front-Cover
11 Texts being (a) (see below), and with the Back-Cover Texts being (b)
12 (see below). A copy of the license is included in the gfdl(7) man page.
15 Some basic guidelines for editing this document:
17 (1) The intrinsic procedures are to be listed in alphabetical order.
18 (2) The generic name is to be used.
19 (3) The specific names are included in the function index and in a
20 table at the end of the node (See ABS entry).
21 (4) Try to maintain the same style for each entry.
27 \gdef\acos{\mathop{\rm acos}\nolimits}
28 \gdef\asin{\mathop{\rm asin}\nolimits}
29 \gdef\atan{\mathop{\rm atan}\nolimits}
30 \gdef\acosh{\mathop{\rm acosh}\nolimits}
31 \gdef\asinh{\mathop{\rm asinh}\nolimits}
32 \gdef\atanh{\mathop{\rm atanh}\nolimits}
36 @node Intrinsic Procedures
37 @chapter Intrinsic Procedures
38 @cindex intrinsic procedures
41 * Introduction: Introduction to Intrinsics
42 * @code{ABORT}: ABORT, Abort the program
43 * @code{ABS}: ABS, Absolute value
44 * @code{ACCESS}: ACCESS, Checks file access modes
45 * @code{ACHAR}: ACHAR, Character in @acronym{ASCII} collating sequence
46 * @code{ACOS}: ACOS, Arccosine function
47 * @code{ACOSH}: ACOSH, Inverse hyperbolic cosine function
48 * @code{ADJUSTL}: ADJUSTL, Left adjust a string
49 * @code{ADJUSTR}: ADJUSTR, Right adjust a string
50 * @code{AIMAG}: AIMAG, Imaginary part of complex number
51 * @code{AINT}: AINT, Truncate to a whole number
52 * @code{ALARM}: ALARM, Set an alarm clock
53 * @code{ALL}: ALL, Determine if all values are true
54 * @code{ALLOCATED}: ALLOCATED, Status of allocatable entity
55 * @code{AND}: AND, Bitwise logical AND
56 * @code{ANINT}: ANINT, Nearest whole number
57 * @code{ANY}: ANY, Determine if any values are true
58 * @code{ASIN}: ASIN, Arcsine function
59 * @code{ASINH}: ASINH, Inverse hyperbolic sine function
60 * @code{ASSOCIATED}: ASSOCIATED, Status of a pointer or pointer/target pair
61 * @code{ATAN}: ATAN, Arctangent function
62 * @code{ATAN2}: ATAN2, Arctangent function
63 * @code{ATANH}: ATANH, Inverse hyperbolic tangent function
64 * @code{ATOMIC_DEFINE}: ATOMIC_DEFINE, Setting a variable atomically
65 * @code{ATOMIC_REF}: ATOMIC_REF, Obtaining the value of a variable atomically
66 * @code{BESSEL_J0}: BESSEL_J0, Bessel function of the first kind of order 0
67 * @code{BESSEL_J1}: BESSEL_J1, Bessel function of the first kind of order 1
68 * @code{BESSEL_JN}: BESSEL_JN, Bessel function of the first kind
69 * @code{BESSEL_Y0}: BESSEL_Y0, Bessel function of the second kind of order 0
70 * @code{BESSEL_Y1}: BESSEL_Y1, Bessel function of the second kind of order 1
71 * @code{BESSEL_YN}: BESSEL_YN, Bessel function of the second kind
72 * @code{BGE}: BGE, Bitwise greater than or equal to
73 * @code{BGT}: BGT, Bitwise greater than
74 * @code{BIT_SIZE}: BIT_SIZE, Bit size inquiry function
75 * @code{BLE}: BLE, Bitwise less than or equal to
76 * @code{BLT}: BLT, Bitwise less than
77 * @code{BTEST}: BTEST, Bit test function
78 * @code{C_ASSOCIATED}: C_ASSOCIATED, Status of a C pointer
79 * @code{C_F_POINTER}: C_F_POINTER, Convert C into Fortran pointer
80 * @code{C_F_PROCPOINTER}: C_F_PROCPOINTER, Convert C into Fortran procedure pointer
81 * @code{C_FUNLOC}: C_FUNLOC, Obtain the C address of a procedure
82 * @code{C_LOC}: C_LOC, Obtain the C address of an object
83 * @code{C_SIZEOF}: C_SIZEOF, Size in bytes of an expression
84 * @code{CEILING}: CEILING, Integer ceiling function
85 * @code{CHAR}: CHAR, Integer-to-character conversion function
86 * @code{CHDIR}: CHDIR, Change working directory
87 * @code{CHMOD}: CHMOD, Change access permissions of files
88 * @code{CMPLX}: CMPLX, Complex conversion function
89 * @code{COMMAND_ARGUMENT_COUNT}: COMMAND_ARGUMENT_COUNT, Get number of command line arguments
90 * @code{COMPLEX}: COMPLEX, Complex conversion function
91 * @code{COMPILER_VERSION}: COMPILER_VERSION, Compiler version string
92 * @code{COMPILER_OPTIONS}: COMPILER_OPTIONS, Options passed to the compiler
93 * @code{CONJG}: CONJG, Complex conjugate function
94 * @code{COS}: COS, Cosine function
95 * @code{COSH}: COSH, Hyperbolic cosine function
96 * @code{COUNT}: COUNT, Count occurrences of TRUE in an array
97 * @code{CPU_TIME}: CPU_TIME, CPU time subroutine
98 * @code{CSHIFT}: CSHIFT, Circular shift elements of an array
99 * @code{CTIME}: CTIME, Subroutine (or function) to convert a time into a string
100 * @code{DATE_AND_TIME}: DATE_AND_TIME, Date and time subroutine
101 * @code{DBLE}: DBLE, Double precision conversion function
102 * @code{DCMPLX}: DCMPLX, Double complex conversion function
103 * @code{DIGITS}: DIGITS, Significant digits function
104 * @code{DIM}: DIM, Positive difference
105 * @code{DOT_PRODUCT}: DOT_PRODUCT, Dot product function
106 * @code{DPROD}: DPROD, Double product function
107 * @code{DREAL}: DREAL, Double real part function
108 * @code{DSHIFTL}: DSHIFTL, Combined left shift
109 * @code{DSHIFTR}: DSHIFTR, Combined right shift
110 * @code{DTIME}: DTIME, Execution time subroutine (or function)
111 * @code{EOSHIFT}: EOSHIFT, End-off shift elements of an array
112 * @code{EPSILON}: EPSILON, Epsilon function
113 * @code{ERF}: ERF, Error function
114 * @code{ERFC}: ERFC, Complementary error function
115 * @code{ERFC_SCALED}: ERFC_SCALED, Exponentially-scaled complementary error function
116 * @code{ETIME}: ETIME, Execution time subroutine (or function)
117 * @code{EXECUTE_COMMAND_LINE}: EXECUTE_COMMAND_LINE, Execute a shell command
118 * @code{EXIT}: EXIT, Exit the program with status.
119 * @code{EXP}: EXP, Exponential function
120 * @code{EXPONENT}: EXPONENT, Exponent function
121 * @code{EXTENDS_TYPE_OF}: EXTENDS_TYPE_OF, Query dynamic type for extension
122 * @code{FDATE}: FDATE, Subroutine (or function) to get the current time as a string
123 * @code{FGET}: FGET, Read a single character in stream mode from stdin
124 * @code{FGETC}: FGETC, Read a single character in stream mode
125 * @code{FLOOR}: FLOOR, Integer floor function
126 * @code{FLUSH}: FLUSH, Flush I/O unit(s)
127 * @code{FNUM}: FNUM, File number function
128 * @code{FPUT}: FPUT, Write a single character in stream mode to stdout
129 * @code{FPUTC}: FPUTC, Write a single character in stream mode
130 * @code{FRACTION}: FRACTION, Fractional part of the model representation
131 * @code{FREE}: FREE, Memory de-allocation subroutine
132 * @code{FSEEK}: FSEEK, Low level file positioning subroutine
133 * @code{FSTAT}: FSTAT, Get file status
134 * @code{FTELL}: FTELL, Current stream position
135 * @code{GAMMA}: GAMMA, Gamma function
136 * @code{GERROR}: GERROR, Get last system error message
137 * @code{GETARG}: GETARG, Get command line arguments
138 * @code{GET_COMMAND}: GET_COMMAND, Get the entire command line
139 * @code{GET_COMMAND_ARGUMENT}: GET_COMMAND_ARGUMENT, Get command line arguments
140 * @code{GETCWD}: GETCWD, Get current working directory
141 * @code{GETENV}: GETENV, Get an environmental variable
142 * @code{GET_ENVIRONMENT_VARIABLE}: GET_ENVIRONMENT_VARIABLE, Get an environmental variable
143 * @code{GETGID}: GETGID, Group ID function
144 * @code{GETLOG}: GETLOG, Get login name
145 * @code{GETPID}: GETPID, Process ID function
146 * @code{GETUID}: GETUID, User ID function
147 * @code{GMTIME}: GMTIME, Convert time to GMT info
148 * @code{HOSTNM}: HOSTNM, Get system host name
149 * @code{HUGE}: HUGE, Largest number of a kind
150 * @code{HYPOT}: HYPOT, Euclidean distance function
151 * @code{IACHAR}: IACHAR, Code in @acronym{ASCII} collating sequence
152 * @code{IALL}: IALL, Bitwise AND of array elements
153 * @code{IAND}: IAND, Bitwise logical and
154 * @code{IANY}: IANY, Bitwise OR of array elements
155 * @code{IARGC}: IARGC, Get the number of command line arguments
156 * @code{IBCLR}: IBCLR, Clear bit
157 * @code{IBITS}: IBITS, Bit extraction
158 * @code{IBSET}: IBSET, Set bit
159 * @code{ICHAR}: ICHAR, Character-to-integer conversion function
160 * @code{IDATE}: IDATE, Current local time (day/month/year)
161 * @code{IEOR}: IEOR, Bitwise logical exclusive or
162 * @code{IERRNO}: IERRNO, Function to get the last system error number
163 * @code{IMAGE_INDEX}: IMAGE_INDEX, Cosubscript to image index conversion
164 * @code{INDEX}: INDEX intrinsic, Position of a substring within a string
165 * @code{INT}: INT, Convert to integer type
166 * @code{INT2}: INT2, Convert to 16-bit integer type
167 * @code{INT8}: INT8, Convert to 64-bit integer type
168 * @code{IOR}: IOR, Bitwise logical or
169 * @code{IPARITY}: IPARITY, Bitwise XOR of array elements
170 * @code{IRAND}: IRAND, Integer pseudo-random number
171 * @code{IS_IOSTAT_END}: IS_IOSTAT_END, Test for end-of-file value
172 * @code{IS_IOSTAT_EOR}: IS_IOSTAT_EOR, Test for end-of-record value
173 * @code{ISATTY}: ISATTY, Whether a unit is a terminal device
174 * @code{ISHFT}: ISHFT, Shift bits
175 * @code{ISHFTC}: ISHFTC, Shift bits circularly
176 * @code{ISNAN}: ISNAN, Tests for a NaN
177 * @code{ITIME}: ITIME, Current local time (hour/minutes/seconds)
178 * @code{KILL}: KILL, Send a signal to a process
179 * @code{KIND}: KIND, Kind of an entity
180 * @code{LBOUND}: LBOUND, Lower dimension bounds of an array
181 * @code{LCOBOUND}: LCOBOUND, Lower codimension bounds of an array
182 * @code{LEADZ}: LEADZ, Number of leading zero bits of an integer
183 * @code{LEN}: LEN, Length of a character entity
184 * @code{LEN_TRIM}: LEN_TRIM, Length of a character entity without trailing blank characters
185 * @code{LGE}: LGE, Lexical greater than or equal
186 * @code{LGT}: LGT, Lexical greater than
187 * @code{LINK}: LINK, Create a hard link
188 * @code{LLE}: LLE, Lexical less than or equal
189 * @code{LLT}: LLT, Lexical less than
190 * @code{LNBLNK}: LNBLNK, Index of the last non-blank character in a string
191 * @code{LOC}: LOC, Returns the address of a variable
192 * @code{LOG}: LOG, Logarithm function
193 * @code{LOG10}: LOG10, Base 10 logarithm function
194 * @code{LOG_GAMMA}: LOG_GAMMA, Logarithm of the Gamma function
195 * @code{LOGICAL}: LOGICAL, Convert to logical type
196 * @code{LONG}: LONG, Convert to integer type
197 * @code{LSHIFT}: LSHIFT, Left shift bits
198 * @code{LSTAT}: LSTAT, Get file status
199 * @code{LTIME}: LTIME, Convert time to local time info
200 * @code{MALLOC}: MALLOC, Dynamic memory allocation function
201 * @code{MASKL}: MASKL, Left justified mask
202 * @code{MASKR}: MASKR, Right justified mask
203 * @code{MATMUL}: MATMUL, matrix multiplication
204 * @code{MAX}: MAX, Maximum value of an argument list
205 * @code{MAXEXPONENT}: MAXEXPONENT, Maximum exponent of a real kind
206 * @code{MAXLOC}: MAXLOC, Location of the maximum value within an array
207 * @code{MAXVAL}: MAXVAL, Maximum value of an array
208 * @code{MCLOCK}: MCLOCK, Time function
209 * @code{MCLOCK8}: MCLOCK8, Time function (64-bit)
210 * @code{MERGE}: MERGE, Merge arrays
211 * @code{MERGE_BITS}: MERGE_BITS, Merge of bits under mask
212 * @code{MIN}: MIN, Minimum value of an argument list
213 * @code{MINEXPONENT}: MINEXPONENT, Minimum exponent of a real kind
214 * @code{MINLOC}: MINLOC, Location of the minimum value within an array
215 * @code{MINVAL}: MINVAL, Minimum value of an array
216 * @code{MOD}: MOD, Remainder function
217 * @code{MODULO}: MODULO, Modulo function
218 * @code{MOVE_ALLOC}: MOVE_ALLOC, Move allocation from one object to another
219 * @code{MVBITS}: MVBITS, Move bits from one integer to another
220 * @code{NEAREST}: NEAREST, Nearest representable number
221 * @code{NEW_LINE}: NEW_LINE, New line character
222 * @code{NINT}: NINT, Nearest whole number
223 * @code{NORM2}: NORM2, Euclidean vector norm
224 * @code{NOT}: NOT, Logical negation
225 * @code{NULL}: NULL, Function that returns an disassociated pointer
226 * @code{NUM_IMAGES}: NUM_IMAGES, Number of images
227 * @code{OR}: OR, Bitwise logical OR
228 * @code{PACK}: PACK, Pack an array into an array of rank one
229 * @code{PARITY}: PARITY, Reduction with exclusive OR
230 * @code{PERROR}: PERROR, Print system error message
231 * @code{POPCNT}: POPCNT, Number of bits set
232 * @code{POPPAR}: POPPAR, Parity of the number of bits set
233 * @code{PRECISION}: PRECISION, Decimal precision of a real kind
234 * @code{PRESENT}: PRESENT, Determine whether an optional dummy argument is specified
235 * @code{PRODUCT}: PRODUCT, Product of array elements
236 * @code{RADIX}: RADIX, Base of a data model
237 * @code{RANDOM_NUMBER}: RANDOM_NUMBER, Pseudo-random number
238 * @code{RANDOM_SEED}: RANDOM_SEED, Initialize a pseudo-random number sequence
239 * @code{RAND}: RAND, Real pseudo-random number
240 * @code{RANGE}: RANGE, Decimal exponent range
241 * @code{RANK} : RANK, Rank of a data object
242 * @code{RAN}: RAN, Real pseudo-random number
243 * @code{REAL}: REAL, Convert to real type
244 * @code{RENAME}: RENAME, Rename a file
245 * @code{REPEAT}: REPEAT, Repeated string concatenation
246 * @code{RESHAPE}: RESHAPE, Function to reshape an array
247 * @code{RRSPACING}: RRSPACING, Reciprocal of the relative spacing
248 * @code{RSHIFT}: RSHIFT, Right shift bits
249 * @code{SAME_TYPE_AS}: SAME_TYPE_AS, Query dynamic types for equality
250 * @code{SCALE}: SCALE, Scale a real value
251 * @code{SCAN}: SCAN, Scan a string for the presence of a set of characters
252 * @code{SECNDS}: SECNDS, Time function
253 * @code{SECOND}: SECOND, CPU time function
254 * @code{SELECTED_CHAR_KIND}: SELECTED_CHAR_KIND, Choose character kind
255 * @code{SELECTED_INT_KIND}: SELECTED_INT_KIND, Choose integer kind
256 * @code{SELECTED_REAL_KIND}: SELECTED_REAL_KIND, Choose real kind
257 * @code{SET_EXPONENT}: SET_EXPONENT, Set the exponent of the model
258 * @code{SHAPE}: SHAPE, Determine the shape of an array
259 * @code{SHIFTA}: SHIFTA, Right shift with fill
260 * @code{SHIFTL}: SHIFTL, Left shift
261 * @code{SHIFTR}: SHIFTR, Right shift
262 * @code{SIGN}: SIGN, Sign copying function
263 * @code{SIGNAL}: SIGNAL, Signal handling subroutine (or function)
264 * @code{SIN}: SIN, Sine function
265 * @code{SINH}: SINH, Hyperbolic sine function
266 * @code{SIZE}: SIZE, Function to determine the size of an array
267 * @code{SIZEOF}: SIZEOF, Determine the size in bytes of an expression
268 * @code{SLEEP}: SLEEP, Sleep for the specified number of seconds
269 * @code{SPACING}: SPACING, Smallest distance between two numbers of a given type
270 * @code{SPREAD}: SPREAD, Add a dimension to an array
271 * @code{SQRT}: SQRT, Square-root function
272 * @code{SRAND}: SRAND, Reinitialize the random number generator
273 * @code{STAT}: STAT, Get file status
274 * @code{STORAGE_SIZE}: STORAGE_SIZE, Storage size in bits
275 * @code{SUM}: SUM, Sum of array elements
276 * @code{SYMLNK}: SYMLNK, Create a symbolic link
277 * @code{SYSTEM}: SYSTEM, Execute a shell command
278 * @code{SYSTEM_CLOCK}: SYSTEM_CLOCK, Time function
279 * @code{TAN}: TAN, Tangent function
280 * @code{TANH}: TANH, Hyperbolic tangent function
281 * @code{THIS_IMAGE}: THIS_IMAGE, Cosubscript index of this image
282 * @code{TIME}: TIME, Time function
283 * @code{TIME8}: TIME8, Time function (64-bit)
284 * @code{TINY}: TINY, Smallest positive number of a real kind
285 * @code{TRAILZ}: TRAILZ, Number of trailing zero bits of an integer
286 * @code{TRANSFER}: TRANSFER, Transfer bit patterns
287 * @code{TRANSPOSE}: TRANSPOSE, Transpose an array of rank two
288 * @code{TRIM}: TRIM, Remove trailing blank characters of a string
289 * @code{TTYNAM}: TTYNAM, Get the name of a terminal device.
290 * @code{UBOUND}: UBOUND, Upper dimension bounds of an array
291 * @code{UCOBOUND}: UCOBOUND, Upper codimension bounds of an array
292 * @code{UMASK}: UMASK, Set the file creation mask
293 * @code{UNLINK}: UNLINK, Remove a file from the file system
294 * @code{UNPACK}: UNPACK, Unpack an array of rank one into an array
295 * @code{VERIFY}: VERIFY, Scan a string for the absence of a set of characters
296 * @code{XOR}: XOR, Bitwise logical exclusive or
299 @node Introduction to Intrinsics
300 @section Introduction to intrinsic procedures
302 The intrinsic procedures provided by GNU Fortran include all of the
303 intrinsic procedures required by the Fortran 95 standard, a set of
304 intrinsic procedures for backwards compatibility with G77, and a
305 selection of intrinsic procedures from the Fortran 2003 and Fortran 2008
306 standards. Any conflict between a description here and a description in
307 either the Fortran 95 standard, the Fortran 2003 standard or the Fortran
308 2008 standard is unintentional, and the standard(s) should be considered
311 The enumeration of the @code{KIND} type parameter is processor defined in
312 the Fortran 95 standard. GNU Fortran defines the default integer type and
313 default real type by @code{INTEGER(KIND=4)} and @code{REAL(KIND=4)},
314 respectively. The standard mandates that both data types shall have
315 another kind, which have more precision. On typical target architectures
316 supported by @command{gfortran}, this kind type parameter is @code{KIND=8}.
317 Hence, @code{REAL(KIND=8)} and @code{DOUBLE PRECISION} are equivalent.
318 In the description of generic intrinsic procedures, the kind type parameter
319 will be specified by @code{KIND=*}, and in the description of specific
320 names for an intrinsic procedure the kind type parameter will be explicitly
321 given (e.g., @code{REAL(KIND=4)} or @code{REAL(KIND=8)}). Finally, for
322 brevity the optional @code{KIND=} syntax will be omitted.
324 Many of the intrinsic procedures take one or more optional arguments.
325 This document follows the convention used in the Fortran 95 standard,
326 and denotes such arguments by square brackets.
328 GNU Fortran offers the @option{-std=f95} and @option{-std=gnu} options,
329 which can be used to restrict the set of intrinsic procedures to a
330 given standard. By default, @command{gfortran} sets the @option{-std=gnu}
331 option, and so all intrinsic procedures described here are accepted. There
332 is one caveat. For a select group of intrinsic procedures, @command{g77}
333 implemented both a function and a subroutine. Both classes
334 have been implemented in @command{gfortran} for backwards compatibility
335 with @command{g77}. It is noted here that these functions and subroutines
336 cannot be intermixed in a given subprogram. In the descriptions that follow,
337 the applicable standard for each intrinsic procedure is noted.
342 @section @code{ABORT} --- Abort the program
344 @cindex program termination, with core dump
345 @cindex terminate program, with core dump
349 @item @emph{Description}:
350 @code{ABORT} causes immediate termination of the program. On operating
351 systems that support a core dump, @code{ABORT} will produce a core dump.
353 @item @emph{Standard}:
362 @item @emph{Return value}:
365 @item @emph{Example}:
368 integer :: i = 1, j = 2
369 if (i /= j) call abort
370 end program test_abort
373 @item @emph{See also}:
374 @ref{EXIT}, @ref{KILL}
381 @section @code{ABS} --- Absolute value
388 @cindex absolute value
391 @item @emph{Description}:
392 @code{ABS(A)} computes the absolute value of @code{A}.
394 @item @emph{Standard}:
395 Fortran 77 and later, has overloads that are GNU extensions
401 @code{RESULT = ABS(A)}
403 @item @emph{Arguments}:
404 @multitable @columnfractions .15 .70
405 @item @var{A} @tab The type of the argument shall be an @code{INTEGER},
406 @code{REAL}, or @code{COMPLEX}.
409 @item @emph{Return value}:
410 The return value is of the same type and
411 kind as the argument except the return value is @code{REAL} for a
412 @code{COMPLEX} argument.
414 @item @emph{Example}:
419 complex :: z = (-1.e0,0.e0)
426 @item @emph{Specific names}:
427 @multitable @columnfractions .20 .20 .20 .25
428 @item Name @tab Argument @tab Return type @tab Standard
429 @item @code{ABS(A)} @tab @code{REAL(4) A} @tab @code{REAL(4)} @tab Fortran 77 and later
430 @item @code{CABS(A)} @tab @code{COMPLEX(4) A} @tab @code{REAL(4)} @tab Fortran 77 and later
431 @item @code{DABS(A)} @tab @code{REAL(8) A} @tab @code{REAL(8)} @tab Fortran 77 and later
432 @item @code{IABS(A)} @tab @code{INTEGER(4) A} @tab @code{INTEGER(4)} @tab Fortran 77 and later
433 @item @code{ZABS(A)} @tab @code{COMPLEX(8) A} @tab @code{COMPLEX(8)} @tab GNU extension
434 @item @code{CDABS(A)} @tab @code{COMPLEX(8) A} @tab @code{COMPLEX(8)} @tab GNU extension
441 @section @code{ACCESS} --- Checks file access modes
443 @cindex file system, access mode
446 @item @emph{Description}:
447 @code{ACCESS(NAME, MODE)} checks whether the file @var{NAME}
448 exists, is readable, writable or executable. Except for the
449 executable check, @code{ACCESS} can be replaced by
450 Fortran 95's @code{INQUIRE}.
452 @item @emph{Standard}:
459 @code{RESULT = ACCESS(NAME, MODE)}
461 @item @emph{Arguments}:
462 @multitable @columnfractions .15 .70
463 @item @var{NAME} @tab Scalar @code{CHARACTER} of default kind with the
464 file name. Tailing blank are ignored unless the character @code{achar(0)}
465 is present, then all characters up to and excluding @code{achar(0)} are
467 @item @var{MODE} @tab Scalar @code{CHARACTER} of default kind with the
468 file access mode, may be any concatenation of @code{"r"} (readable),
469 @code{"w"} (writable) and @code{"x"} (executable), or @code{" "} to check
473 @item @emph{Return value}:
474 Returns a scalar @code{INTEGER}, which is @code{0} if the file is
475 accessible in the given mode; otherwise or if an invalid argument
476 has been given for @code{MODE} the value @code{1} is returned.
478 @item @emph{Example}:
482 character(len=*), parameter :: file = 'test.dat'
483 character(len=*), parameter :: file2 = 'test.dat '//achar(0)
484 if(access(file,' ') == 0) print *, trim(file),' is exists'
485 if(access(file,'r') == 0) print *, trim(file),' is readable'
486 if(access(file,'w') == 0) print *, trim(file),' is writable'
487 if(access(file,'x') == 0) print *, trim(file),' is executable'
488 if(access(file2,'rwx') == 0) &
489 print *, trim(file2),' is readable, writable and executable'
490 end program access_test
492 @item @emph{Specific names}:
493 @item @emph{See also}:
500 @section @code{ACHAR} --- Character in @acronym{ASCII} collating sequence
502 @cindex @acronym{ASCII} collating sequence
503 @cindex collating sequence, @acronym{ASCII}
506 @item @emph{Description}:
507 @code{ACHAR(I)} returns the character located at position @code{I}
508 in the @acronym{ASCII} collating sequence.
510 @item @emph{Standard}:
511 Fortran 77 and later, with @var{KIND} argument Fortran 2003 and later
517 @code{RESULT = ACHAR(I [, KIND])}
519 @item @emph{Arguments}:
520 @multitable @columnfractions .15 .70
521 @item @var{I} @tab The type shall be @code{INTEGER}.
522 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
523 expression indicating the kind parameter of the result.
526 @item @emph{Return value}:
527 The return value is of type @code{CHARACTER} with a length of one.
528 If the @var{KIND} argument is present, the return value is of the
529 specified kind and of the default kind otherwise.
531 @item @emph{Example}:
536 end program test_achar
540 See @ref{ICHAR} for a discussion of converting between numerical values
541 and formatted string representations.
543 @item @emph{See also}:
544 @ref{CHAR}, @ref{IACHAR}, @ref{ICHAR}
551 @section @code{ACOS} --- Arccosine function
554 @cindex trigonometric function, cosine, inverse
555 @cindex cosine, inverse
558 @item @emph{Description}:
559 @code{ACOS(X)} computes the arccosine of @var{X} (inverse of @code{COS(X)}).
561 @item @emph{Standard}:
562 Fortran 77 and later, for a complex argument Fortran 2008 or later
568 @code{RESULT = ACOS(X)}
570 @item @emph{Arguments}:
571 @multitable @columnfractions .15 .70
572 @item @var{X} @tab The type shall either be @code{REAL} with a magnitude that is
573 less than or equal to one - or the type shall be @code{COMPLEX}.
576 @item @emph{Return value}:
577 The return value is of the same type and kind as @var{X}.
578 The real part of the result is in radians and lies in the range
579 @math{0 \leq \Re \acos(x) \leq \pi}.
581 @item @emph{Example}:
584 real(8) :: x = 0.866_8
586 end program test_acos
589 @item @emph{Specific names}:
590 @multitable @columnfractions .20 .20 .20 .25
591 @item Name @tab Argument @tab Return type @tab Standard
592 @item @code{ACOS(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab Fortran 77 and later
593 @item @code{DACOS(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab Fortran 77 and later
596 @item @emph{See also}:
597 Inverse function: @ref{COS}
604 @section @code{ACOSH} --- Inverse hyperbolic cosine function
607 @cindex area hyperbolic cosine
608 @cindex inverse hyperbolic cosine
609 @cindex hyperbolic function, cosine, inverse
610 @cindex cosine, hyperbolic, inverse
613 @item @emph{Description}:
614 @code{ACOSH(X)} computes the inverse hyperbolic cosine of @var{X}.
616 @item @emph{Standard}:
617 Fortran 2008 and later
623 @code{RESULT = ACOSH(X)}
625 @item @emph{Arguments}:
626 @multitable @columnfractions .15 .70
627 @item @var{X} @tab The type shall be @code{REAL} or @code{COMPLEX}.
630 @item @emph{Return value}:
631 The return value has the same type and kind as @var{X}. If @var{X} is
632 complex, the imaginary part of the result is in radians and lies between
633 @math{ 0 \leq \Im \acosh(x) \leq \pi}.
635 @item @emph{Example}:
638 REAL(8), DIMENSION(3) :: x = (/ 1.0, 2.0, 3.0 /)
643 @item @emph{Specific names}:
644 @multitable @columnfractions .20 .20 .20 .25
645 @item Name @tab Argument @tab Return type @tab Standard
646 @item @code{DACOSH(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU extension
649 @item @emph{See also}:
650 Inverse function: @ref{COSH}
656 @section @code{ADJUSTL} --- Left adjust a string
658 @cindex string, adjust left
659 @cindex adjust string
662 @item @emph{Description}:
663 @code{ADJUSTL(STRING)} will left adjust a string by removing leading spaces.
664 Spaces are inserted at the end of the string as needed.
666 @item @emph{Standard}:
673 @code{RESULT = ADJUSTL(STRING)}
675 @item @emph{Arguments}:
676 @multitable @columnfractions .15 .70
677 @item @var{STRING} @tab The type shall be @code{CHARACTER}.
680 @item @emph{Return value}:
681 The return value is of type @code{CHARACTER} and of the same kind as
682 @var{STRING} where leading spaces are removed and the same number of
683 spaces are inserted on the end of @var{STRING}.
685 @item @emph{Example}:
688 character(len=20) :: str = ' gfortran'
691 end program test_adjustl
694 @item @emph{See also}:
695 @ref{ADJUSTR}, @ref{TRIM}
701 @section @code{ADJUSTR} --- Right adjust a string
703 @cindex string, adjust right
704 @cindex adjust string
707 @item @emph{Description}:
708 @code{ADJUSTR(STRING)} will right adjust a string by removing trailing spaces.
709 Spaces are inserted at the start of the string as needed.
711 @item @emph{Standard}:
718 @code{RESULT = ADJUSTR(STRING)}
720 @item @emph{Arguments}:
721 @multitable @columnfractions .15 .70
722 @item @var{STR} @tab The type shall be @code{CHARACTER}.
725 @item @emph{Return value}:
726 The return value is of type @code{CHARACTER} and of the same kind as
727 @var{STRING} where trailing spaces are removed and the same number of
728 spaces are inserted at the start of @var{STRING}.
730 @item @emph{Example}:
733 character(len=20) :: str = 'gfortran'
736 end program test_adjustr
739 @item @emph{See also}:
740 @ref{ADJUSTL}, @ref{TRIM}
746 @section @code{AIMAG} --- Imaginary part of complex number
751 @cindex complex numbers, imaginary part
754 @item @emph{Description}:
755 @code{AIMAG(Z)} yields the imaginary part of complex argument @code{Z}.
756 The @code{IMAG(Z)} and @code{IMAGPART(Z)} intrinsic functions are provided
757 for compatibility with @command{g77}, and their use in new code is
758 strongly discouraged.
760 @item @emph{Standard}:
761 Fortran 77 and later, has overloads that are GNU extensions
767 @code{RESULT = AIMAG(Z)}
769 @item @emph{Arguments}:
770 @multitable @columnfractions .15 .70
771 @item @var{Z} @tab The type of the argument shall be @code{COMPLEX}.
774 @item @emph{Return value}:
775 The return value is of type @code{REAL} with the
776 kind type parameter of the argument.
778 @item @emph{Example}:
783 z4 = cmplx(1.e0_4, 0.e0_4)
784 z8 = cmplx(0.e0_8, 1.e0_8)
785 print *, aimag(z4), dimag(z8)
786 end program test_aimag
789 @item @emph{Specific names}:
790 @multitable @columnfractions .20 .20 .20 .25
791 @item Name @tab Argument @tab Return type @tab Standard
792 @item @code{AIMAG(Z)} @tab @code{COMPLEX Z} @tab @code{REAL} @tab GNU extension
793 @item @code{DIMAG(Z)} @tab @code{COMPLEX(8) Z} @tab @code{REAL(8)} @tab GNU extension
794 @item @code{IMAG(Z)} @tab @code{COMPLEX Z} @tab @code{REAL} @tab GNU extension
795 @item @code{IMAGPART(Z)} @tab @code{COMPLEX Z} @tab @code{REAL} @tab GNU extension
802 @section @code{AINT} --- Truncate to a whole number
806 @cindex rounding, floor
809 @item @emph{Description}:
810 @code{AINT(A [, KIND])} truncates its argument to a whole number.
812 @item @emph{Standard}:
819 @code{RESULT = AINT(A [, KIND])}
821 @item @emph{Arguments}:
822 @multitable @columnfractions .15 .70
823 @item @var{A} @tab The type of the argument shall be @code{REAL}.
824 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
825 expression indicating the kind parameter of the result.
828 @item @emph{Return value}:
829 The return value is of type @code{REAL} with the kind type parameter of the
830 argument if the optional @var{KIND} is absent; otherwise, the kind
831 type parameter will be given by @var{KIND}. If the magnitude of
832 @var{X} is less than one, @code{AINT(X)} returns zero. If the
833 magnitude is equal to or greater than one then it returns the largest
834 whole number that does not exceed its magnitude. The sign is the same
835 as the sign of @var{X}.
837 @item @emph{Example}:
844 print *, aint(x4), dint(x8)
846 end program test_aint
849 @item @emph{Specific names}:
850 @multitable @columnfractions .20 .20 .20 .25
851 @item Name @tab Argument @tab Return type @tab Standard
852 @item @code{AINT(A)} @tab @code{REAL(4) A} @tab @code{REAL(4)} @tab Fortran 77 and later
853 @item @code{DINT(A)} @tab @code{REAL(8) A} @tab @code{REAL(8)} @tab Fortran 77 and later
860 @section @code{ALARM} --- Execute a routine after a given delay
862 @cindex delayed execution
865 @item @emph{Description}:
866 @code{ALARM(SECONDS, HANDLER [, STATUS])} causes external subroutine @var{HANDLER}
867 to be executed after a delay of @var{SECONDS} by using @code{alarm(2)} to
868 set up a signal and @code{signal(2)} to catch it. If @var{STATUS} is
869 supplied, it will be returned with the number of seconds remaining until
870 any previously scheduled alarm was due to be delivered, or zero if there
871 was no previously scheduled alarm.
873 @item @emph{Standard}:
880 @code{CALL ALARM(SECONDS, HANDLER [, STATUS])}
882 @item @emph{Arguments}:
883 @multitable @columnfractions .15 .70
884 @item @var{SECONDS} @tab The type of the argument shall be a scalar
885 @code{INTEGER}. It is @code{INTENT(IN)}.
886 @item @var{HANDLER} @tab Signal handler (@code{INTEGER FUNCTION} or
887 @code{SUBROUTINE}) or dummy/global @code{INTEGER} scalar. The scalar
888 values may be either @code{SIG_IGN=1} to ignore the alarm generated
889 or @code{SIG_DFL=0} to set the default action. It is @code{INTENT(IN)}.
890 @item @var{STATUS} @tab (Optional) @var{STATUS} shall be a scalar
891 variable of the default @code{INTEGER} kind. It is @code{INTENT(OUT)}.
894 @item @emph{Example}:
897 external handler_print
899 call alarm (3, handler_print, i)
902 end program test_alarm
904 This will cause the external routine @var{handler_print} to be called
911 @section @code{ALL} --- All values in @var{MASK} along @var{DIM} are true
913 @cindex array, apply condition
914 @cindex array, condition testing
917 @item @emph{Description}:
918 @code{ALL(MASK [, DIM])} determines if all the values are true in @var{MASK}
919 in the array along dimension @var{DIM}.
921 @item @emph{Standard}:
925 Transformational function
928 @code{RESULT = ALL(MASK [, DIM])}
930 @item @emph{Arguments}:
931 @multitable @columnfractions .15 .70
932 @item @var{MASK} @tab The type of the argument shall be @code{LOGICAL} and
933 it shall not be scalar.
934 @item @var{DIM} @tab (Optional) @var{DIM} shall be a scalar integer
935 with a value that lies between one and the rank of @var{MASK}.
938 @item @emph{Return value}:
939 @code{ALL(MASK)} returns a scalar value of type @code{LOGICAL} where
940 the kind type parameter is the same as the kind type parameter of
941 @var{MASK}. If @var{DIM} is present, then @code{ALL(MASK, DIM)} returns
942 an array with the rank of @var{MASK} minus 1. The shape is determined from
943 the shape of @var{MASK} where the @var{DIM} dimension is elided.
947 @code{ALL(MASK)} is true if all elements of @var{MASK} are true.
948 It also is true if @var{MASK} has zero size; otherwise, it is false.
950 If the rank of @var{MASK} is one, then @code{ALL(MASK,DIM)} is equivalent
951 to @code{ALL(MASK)}. If the rank is greater than one, then @code{ALL(MASK,DIM)}
952 is determined by applying @code{ALL} to the array sections.
955 @item @emph{Example}:
959 l = all((/.true., .true., .true./))
964 integer a(2,3), b(2,3)
968 print *, all(a .eq. b, 1)
969 print *, all(a .eq. b, 2)
970 end subroutine section
978 @section @code{ALLOCATED} --- Status of an allocatable entity
980 @cindex allocation, status
983 @item @emph{Description}:
984 @code{ALLOCATED(ARRAY)} and @code{ALLOCATED(SCALAR)} check the allocation
985 status of @var{ARRAY} and @var{SCALAR}, respectively.
987 @item @emph{Standard}:
988 Fortran 95 and later. Note, the @code{SCALAR=} keyword and allocatable
989 scalar entities are available in Fortran 2003 and later.
995 @multitable @columnfractions .80
996 @item @code{RESULT = ALLOCATED(ARRAY)}
997 @item @code{RESULT = ALLOCATED(SCALAR)}
1000 @item @emph{Arguments}:
1001 @multitable @columnfractions .15 .70
1002 @item @var{ARRAY} @tab The argument shall be an @code{ALLOCATABLE} array.
1003 @item @var{SCALAR} @tab The argument shall be an @code{ALLOCATABLE} scalar.
1006 @item @emph{Return value}:
1007 The return value is a scalar @code{LOGICAL} with the default logical
1008 kind type parameter. If the argument is allocated, then the result is
1009 @code{.TRUE.}; otherwise, it returns @code{.FALSE.}
1011 @item @emph{Example}:
1013 program test_allocated
1015 real(4), allocatable :: x(:)
1016 if (.not. allocated(x)) allocate(x(i))
1017 end program test_allocated
1024 @section @code{AND} --- Bitwise logical AND
1026 @cindex bitwise logical and
1027 @cindex logical and, bitwise
1030 @item @emph{Description}:
1031 Bitwise logical @code{AND}.
1033 This intrinsic routine is provided for backwards compatibility with
1034 GNU Fortran 77. For integer arguments, programmers should consider
1035 the use of the @ref{IAND} intrinsic defined by the Fortran standard.
1037 @item @emph{Standard}:
1043 @item @emph{Syntax}:
1044 @code{RESULT = AND(I, J)}
1046 @item @emph{Arguments}:
1047 @multitable @columnfractions .15 .70
1048 @item @var{I} @tab The type shall be either a scalar @code{INTEGER}
1049 type or a scalar @code{LOGICAL} type.
1050 @item @var{J} @tab The type shall be the same as the type of @var{I}.
1053 @item @emph{Return value}:
1054 The return type is either a scalar @code{INTEGER} or a scalar
1055 @code{LOGICAL}. If the kind type parameters differ, then the
1056 smaller kind type is implicitly converted to larger kind, and the
1057 return has the larger kind.
1059 @item @emph{Example}:
1062 LOGICAL :: T = .TRUE., F = .FALSE.
1064 DATA a / Z'F' /, b / Z'3' /
1066 WRITE (*,*) AND(T, T), AND(T, F), AND(F, T), AND(F, F)
1067 WRITE (*,*) AND(a, b)
1071 @item @emph{See also}:
1072 Fortran 95 elemental function: @ref{IAND}
1078 @section @code{ANINT} --- Nearest whole number
1082 @cindex rounding, ceiling
1085 @item @emph{Description}:
1086 @code{ANINT(A [, KIND])} rounds its argument to the nearest whole number.
1088 @item @emph{Standard}:
1089 Fortran 77 and later
1094 @item @emph{Syntax}:
1095 @code{RESULT = ANINT(A [, KIND])}
1097 @item @emph{Arguments}:
1098 @multitable @columnfractions .15 .70
1099 @item @var{A} @tab The type of the argument shall be @code{REAL}.
1100 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
1101 expression indicating the kind parameter of the result.
1104 @item @emph{Return value}:
1105 The return value is of type real with the kind type parameter of the
1106 argument if the optional @var{KIND} is absent; otherwise, the kind
1107 type parameter will be given by @var{KIND}. If @var{A} is greater than
1108 zero, @code{ANINT(A)} returns @code{AINT(X+0.5)}. If @var{A} is
1109 less than or equal to zero then it returns @code{AINT(X-0.5)}.
1111 @item @emph{Example}:
1118 print *, anint(x4), dnint(x8)
1120 end program test_anint
1123 @item @emph{Specific names}:
1124 @multitable @columnfractions .20 .20 .20 .25
1125 @item Name @tab Argument @tab Return type @tab Standard
1126 @item @code{AINT(A)} @tab @code{REAL(4) A} @tab @code{REAL(4)} @tab Fortran 77 and later
1127 @item @code{DNINT(A)} @tab @code{REAL(8) A} @tab @code{REAL(8)} @tab Fortran 77 and later
1134 @section @code{ANY} --- Any value in @var{MASK} along @var{DIM} is true
1136 @cindex array, apply condition
1137 @cindex array, condition testing
1140 @item @emph{Description}:
1141 @code{ANY(MASK [, DIM])} determines if any of the values in the logical array
1142 @var{MASK} along dimension @var{DIM} are @code{.TRUE.}.
1144 @item @emph{Standard}:
1145 Fortran 95 and later
1148 Transformational function
1150 @item @emph{Syntax}:
1151 @code{RESULT = ANY(MASK [, DIM])}
1153 @item @emph{Arguments}:
1154 @multitable @columnfractions .15 .70
1155 @item @var{MASK} @tab The type of the argument shall be @code{LOGICAL} and
1156 it shall not be scalar.
1157 @item @var{DIM} @tab (Optional) @var{DIM} shall be a scalar integer
1158 with a value that lies between one and the rank of @var{MASK}.
1161 @item @emph{Return value}:
1162 @code{ANY(MASK)} returns a scalar value of type @code{LOGICAL} where
1163 the kind type parameter is the same as the kind type parameter of
1164 @var{MASK}. If @var{DIM} is present, then @code{ANY(MASK, DIM)} returns
1165 an array with the rank of @var{MASK} minus 1. The shape is determined from
1166 the shape of @var{MASK} where the @var{DIM} dimension is elided.
1170 @code{ANY(MASK)} is true if any element of @var{MASK} is true;
1171 otherwise, it is false. It also is false if @var{MASK} has zero size.
1173 If the rank of @var{MASK} is one, then @code{ANY(MASK,DIM)} is equivalent
1174 to @code{ANY(MASK)}. If the rank is greater than one, then @code{ANY(MASK,DIM)}
1175 is determined by applying @code{ANY} to the array sections.
1178 @item @emph{Example}:
1182 l = any((/.true., .true., .true./))
1187 integer a(2,3), b(2,3)
1191 print *, any(a .eq. b, 1)
1192 print *, any(a .eq. b, 2)
1193 end subroutine section
1194 end program test_any
1201 @section @code{ASIN} --- Arcsine function
1204 @cindex trigonometric function, sine, inverse
1205 @cindex sine, inverse
1208 @item @emph{Description}:
1209 @code{ASIN(X)} computes the arcsine of its @var{X} (inverse of @code{SIN(X)}).
1211 @item @emph{Standard}:
1212 Fortran 77 and later, for a complex argument Fortran 2008 or later
1217 @item @emph{Syntax}:
1218 @code{RESULT = ASIN(X)}
1220 @item @emph{Arguments}:
1221 @multitable @columnfractions .15 .70
1222 @item @var{X} @tab The type shall be either @code{REAL} and a magnitude that is
1223 less than or equal to one - or be @code{COMPLEX}.
1226 @item @emph{Return value}:
1227 The return value is of the same type and kind as @var{X}.
1228 The real part of the result is in radians and lies in the range
1229 @math{-\pi/2 \leq \Re \asin(x) \leq \pi/2}.
1231 @item @emph{Example}:
1234 real(8) :: x = 0.866_8
1236 end program test_asin
1239 @item @emph{Specific names}:
1240 @multitable @columnfractions .20 .20 .20 .25
1241 @item Name @tab Argument @tab Return type @tab Standard
1242 @item @code{ASIN(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab Fortran 77 and later
1243 @item @code{DASIN(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab Fortran 77 and later
1246 @item @emph{See also}:
1247 Inverse function: @ref{SIN}
1254 @section @code{ASINH} --- Inverse hyperbolic sine function
1257 @cindex area hyperbolic sine
1258 @cindex inverse hyperbolic sine
1259 @cindex hyperbolic function, sine, inverse
1260 @cindex sine, hyperbolic, inverse
1263 @item @emph{Description}:
1264 @code{ASINH(X)} computes the inverse hyperbolic sine of @var{X}.
1266 @item @emph{Standard}:
1267 Fortran 2008 and later
1272 @item @emph{Syntax}:
1273 @code{RESULT = ASINH(X)}
1275 @item @emph{Arguments}:
1276 @multitable @columnfractions .15 .70
1277 @item @var{X} @tab The type shall be @code{REAL} or @code{COMPLEX}.
1280 @item @emph{Return value}:
1281 The return value is of the same type and kind as @var{X}. If @var{X} is
1282 complex, the imaginary part of the result is in radians and lies between
1283 @math{-\pi/2 \leq \Im \asinh(x) \leq \pi/2}.
1285 @item @emph{Example}:
1288 REAL(8), DIMENSION(3) :: x = (/ -1.0, 0.0, 1.0 /)
1289 WRITE (*,*) ASINH(x)
1293 @item @emph{Specific names}:
1294 @multitable @columnfractions .20 .20 .20 .25
1295 @item Name @tab Argument @tab Return type @tab Standard
1296 @item @code{DASINH(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU extension.
1299 @item @emph{See also}:
1300 Inverse function: @ref{SINH}
1306 @section @code{ASSOCIATED} --- Status of a pointer or pointer/target pair
1308 @cindex pointer, status
1309 @cindex association status
1312 @item @emph{Description}:
1313 @code{ASSOCIATED(POINTER [, TARGET])} determines the status of the pointer
1314 @var{POINTER} or if @var{POINTER} is associated with the target @var{TARGET}.
1316 @item @emph{Standard}:
1317 Fortran 95 and later
1322 @item @emph{Syntax}:
1323 @code{RESULT = ASSOCIATED(POINTER [, TARGET])}
1325 @item @emph{Arguments}:
1326 @multitable @columnfractions .15 .70
1327 @item @var{POINTER} @tab @var{POINTER} shall have the @code{POINTER} attribute
1328 and it can be of any type.
1329 @item @var{TARGET} @tab (Optional) @var{TARGET} shall be a pointer or
1330 a target. It must have the same type, kind type parameter, and
1331 array rank as @var{POINTER}.
1333 The association status of neither @var{POINTER} nor @var{TARGET} shall be
1336 @item @emph{Return value}:
1337 @code{ASSOCIATED(POINTER)} returns a scalar value of type @code{LOGICAL(4)}.
1338 There are several cases:
1340 @item (A) When the optional @var{TARGET} is not present then
1341 @code{ASSOCIATED(POINTER)} is true if @var{POINTER} is associated with a target; otherwise, it returns false.
1342 @item (B) If @var{TARGET} is present and a scalar target, the result is true if
1343 @var{TARGET} is not a zero-sized storage sequence and the target associated with @var{POINTER} occupies the same storage units. If @var{POINTER} is
1344 disassociated, the result is false.
1345 @item (C) If @var{TARGET} is present and an array target, the result is true if
1346 @var{TARGET} and @var{POINTER} have the same shape, are not zero-sized arrays,
1347 are arrays whose elements are not zero-sized storage sequences, and
1348 @var{TARGET} and @var{POINTER} occupy the same storage units in array element
1350 As in case(B), the result is false, if @var{POINTER} is disassociated.
1351 @item (D) If @var{TARGET} is present and an scalar pointer, the result is true
1352 if @var{TARGET} is associated with @var{POINTER}, the target associated with
1353 @var{TARGET} are not zero-sized storage sequences and occupy the same storage
1355 The result is false, if either @var{TARGET} or @var{POINTER} is disassociated.
1356 @item (E) If @var{TARGET} is present and an array pointer, the result is true if
1357 target associated with @var{POINTER} and the target associated with @var{TARGET}
1358 have the same shape, are not zero-sized arrays, are arrays whose elements are
1359 not zero-sized storage sequences, and @var{TARGET} and @var{POINTER} occupy
1360 the same storage units in array element order.
1361 The result is false, if either @var{TARGET} or @var{POINTER} is disassociated.
1364 @item @emph{Example}:
1366 program test_associated
1368 real, target :: tgt(2) = (/1., 2./)
1369 real, pointer :: ptr(:)
1371 if (associated(ptr) .eqv. .false.) call abort
1372 if (associated(ptr,tgt) .eqv. .false.) call abort
1373 end program test_associated
1376 @item @emph{See also}:
1383 @section @code{ATAN} --- Arctangent function
1386 @cindex trigonometric function, tangent, inverse
1387 @cindex tangent, inverse
1390 @item @emph{Description}:
1391 @code{ATAN(X)} computes the arctangent of @var{X}.
1393 @item @emph{Standard}:
1394 Fortran 77 and later, for a complex argument and for two arguments
1395 Fortran 2008 or later
1400 @item @emph{Syntax}:
1401 @multitable @columnfractions .80
1402 @item @code{RESULT = ATAN(X)}
1403 @item @code{RESULT = ATAN(Y, X)}
1406 @item @emph{Arguments}:
1407 @multitable @columnfractions .15 .70
1408 @item @var{X} @tab The type shall be @code{REAL} or @code{COMPLEX};
1409 if @var{Y} is present, @var{X} shall be REAL.
1410 @item @var{Y} shall be of the same type and kind as @var{X}.
1413 @item @emph{Return value}:
1414 The return value is of the same type and kind as @var{X}.
1415 If @var{Y} is present, the result is identical to @code{ATAN2(Y,X)}.
1416 Otherwise, it the arcus tangent of @var{X}, where the real part of
1417 the result is in radians and lies in the range
1418 @math{-\pi/2 \leq \Re \atan(x) \leq \pi/2}.
1420 @item @emph{Example}:
1423 real(8) :: x = 2.866_8
1425 end program test_atan
1428 @item @emph{Specific names}:
1429 @multitable @columnfractions .20 .20 .20 .25
1430 @item Name @tab Argument @tab Return type @tab Standard
1431 @item @code{ATAN(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab Fortran 77 and later
1432 @item @code{DATAN(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab Fortran 77 and later
1435 @item @emph{See also}:
1436 Inverse function: @ref{TAN}
1443 @section @code{ATAN2} --- Arctangent function
1446 @cindex trigonometric function, tangent, inverse
1447 @cindex tangent, inverse
1450 @item @emph{Description}:
1451 @code{ATAN2(Y, X)} computes the principal value of the argument
1452 function of the complex number @math{X + i Y}. This function can
1453 be used to transform from Cartesian into polar coordinates and
1454 allows to determine the angle in the correct quadrant.
1456 @item @emph{Standard}:
1457 Fortran 77 and later
1462 @item @emph{Syntax}:
1463 @code{RESULT = ATAN2(Y, X)}
1465 @item @emph{Arguments}:
1466 @multitable @columnfractions .15 .70
1467 @item @var{Y} @tab The type shall be @code{REAL}.
1468 @item @var{X} @tab The type and kind type parameter shall be the same as @var{Y}.
1469 If @var{Y} is zero, then @var{X} must be nonzero.
1472 @item @emph{Return value}:
1473 The return value has the same type and kind type parameter as @var{Y}.
1474 It is the principal value of the complex number @math{X + i Y}. If
1475 @var{X} is nonzero, then it lies in the range @math{-\pi \le \atan (x) \leq \pi}.
1476 The sign is positive if @var{Y} is positive. If @var{Y} is zero, then
1477 the return value is zero if @var{X} is positive and @math{\pi} if @var{X}
1478 is negative. Finally, if @var{X} is zero, then the magnitude of the result
1481 @item @emph{Example}:
1484 real(4) :: x = 1.e0_4, y = 0.5e0_4
1486 end program test_atan2
1489 @item @emph{Specific names}:
1490 @multitable @columnfractions .20 .20 .20 .25
1491 @item Name @tab Argument @tab Return type @tab Standard
1492 @item @code{ATAN2(X, Y)} @tab @code{REAL(4) X, Y} @tab @code{REAL(4)} @tab Fortran 77 and later
1493 @item @code{DATAN2(X, Y)} @tab @code{REAL(8) X, Y} @tab @code{REAL(8)} @tab Fortran 77 and later
1500 @section @code{ATANH} --- Inverse hyperbolic tangent function
1503 @cindex area hyperbolic tangent
1504 @cindex inverse hyperbolic tangent
1505 @cindex hyperbolic function, tangent, inverse
1506 @cindex tangent, hyperbolic, inverse
1509 @item @emph{Description}:
1510 @code{ATANH(X)} computes the inverse hyperbolic tangent of @var{X}.
1512 @item @emph{Standard}:
1513 Fortran 2008 and later
1518 @item @emph{Syntax}:
1519 @code{RESULT = ATANH(X)}
1521 @item @emph{Arguments}:
1522 @multitable @columnfractions .15 .70
1523 @item @var{X} @tab The type shall be @code{REAL} or @code{COMPLEX}.
1526 @item @emph{Return value}:
1527 The return value has same type and kind as @var{X}. If @var{X} is
1528 complex, the imaginary part of the result is in radians and lies between
1529 @math{-\pi/2 \leq \Im \atanh(x) \leq \pi/2}.
1531 @item @emph{Example}:
1534 REAL, DIMENSION(3) :: x = (/ -1.0, 0.0, 1.0 /)
1535 WRITE (*,*) ATANH(x)
1539 @item @emph{Specific names}:
1540 @multitable @columnfractions .20 .20 .20 .25
1541 @item Name @tab Argument @tab Return type @tab Standard
1542 @item @code{DATANH(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU extension
1545 @item @emph{See also}:
1546 Inverse function: @ref{TANH}
1552 @section @code{ATOMIC_DEFINE} --- Setting a variable atomically
1553 @fnindex ATOMIC_DEFINE
1554 @cindex Atomic subroutine, define
1557 @item @emph{Description}:
1558 @code{ATOMIC_DEFINE(ATOM, VALUE)} defines the variable @var{ATOM} with the value
1559 @var{VALUE} atomically.
1561 @item @emph{Standard}:
1562 Fortran 2008 and later
1567 @item @emph{Syntax}:
1568 @code{CALL ATOMIC_DEFINE(ATOM, VALUE)}
1570 @item @emph{Arguments}:
1571 @multitable @columnfractions .15 .70
1572 @item @var{ATOM} @tab Scalar coarray or coindexed variable of either integer
1573 type with @code{ATOMIC_INT_KIND} kind or logical type
1574 with @code{ATOMIC_LOGICAL_KIND} kind.
1575 @item @var{VALURE} @tab Scalar and of the same type as @var{ATOM}. If the kind
1576 is different, the value is converted to the kind of
1580 @item @emph{Example}:
1584 integer(atomic_int_kind) :: atom[*]
1585 call atomic_define (atom[1], this_image())
1589 @item @emph{See also}:
1590 @ref{ATOMIC_REF}, @ref{ISO_FORTRAN_ENV}
1596 @section @code{ATOMIC_REF} --- Obtaining the value of a variable atomically
1598 @cindex Atomic subroutine, reference
1601 @item @emph{Description}:
1602 @code{ATOMIC_DEFINE(ATOM, VALUE)} atomically assigns the value of the
1603 variable @var{ATOM} to @var{VALUE}.
1605 @item @emph{Standard}:
1606 Fortran 2008 and later
1611 @item @emph{Syntax}:
1612 @code{CALL ATOMIC_REF(VALUE, ATOM)}
1614 @item @emph{Arguments}:
1615 @multitable @columnfractions .15 .70
1616 @item @var{VALURE} @tab Scalar and of the same type as @var{ATOM}. If the kind
1617 is different, the value is converted to the kind of
1619 @item @var{ATOM} @tab Scalar coarray or coindexed variable of either integer
1620 type with @code{ATOMIC_INT_KIND} kind or logical type
1621 with @code{ATOMIC_LOGICAL_KIND} kind.
1624 @item @emph{Example}:
1628 logical(atomic_logical_kind) :: atom[*]
1630 call atomic_ref (atom, .false.)
1632 call atomic_ref (atom, val)
1639 @item @emph{See also}:
1640 @ref{ATOMIC_DEFINE}, @ref{ISO_FORTRAN_ENV}
1646 @section @code{BESSEL_J0} --- Bessel function of the first kind of order 0
1650 @cindex Bessel function, first kind
1653 @item @emph{Description}:
1654 @code{BESSEL_J0(X)} computes the Bessel function of the first kind of
1655 order 0 of @var{X}. This function is available under the name
1656 @code{BESJ0} as a GNU extension.
1658 @item @emph{Standard}:
1659 Fortran 2008 and later
1664 @item @emph{Syntax}:
1665 @code{RESULT = BESSEL_J0(X)}
1667 @item @emph{Arguments}:
1668 @multitable @columnfractions .15 .70
1669 @item @var{X} @tab The type shall be @code{REAL}, and it shall be scalar.
1672 @item @emph{Return value}:
1673 The return value is of type @code{REAL} and lies in the
1674 range @math{ - 0.4027... \leq Bessel (0,x) \leq 1}. It has the same
1677 @item @emph{Example}:
1680 real(8) :: x = 0.0_8
1682 end program test_besj0
1685 @item @emph{Specific names}:
1686 @multitable @columnfractions .20 .20 .20 .25
1687 @item Name @tab Argument @tab Return type @tab Standard
1688 @item @code{DBESJ0(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU extension
1695 @section @code{BESSEL_J1} --- Bessel function of the first kind of order 1
1699 @cindex Bessel function, first kind
1702 @item @emph{Description}:
1703 @code{BESSEL_J1(X)} computes the Bessel function of the first kind of
1704 order 1 of @var{X}. This function is available under the name
1705 @code{BESJ1} as a GNU extension.
1707 @item @emph{Standard}:
1713 @item @emph{Syntax}:
1714 @code{RESULT = BESSEL_J1(X)}
1716 @item @emph{Arguments}:
1717 @multitable @columnfractions .15 .70
1718 @item @var{X} @tab The type shall be @code{REAL}, and it shall be scalar.
1721 @item @emph{Return value}:
1722 The return value is of type @code{REAL} and it lies in the
1723 range @math{ - 0.5818... \leq Bessel (0,x) \leq 0.5818 }. It has the same
1726 @item @emph{Example}:
1729 real(8) :: x = 1.0_8
1731 end program test_besj1
1734 @item @emph{Specific names}:
1735 @multitable @columnfractions .20 .20 .20 .25
1736 @item Name @tab Argument @tab Return type @tab Standard
1737 @item @code{DBESJ1(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU extension
1744 @section @code{BESSEL_JN} --- Bessel function of the first kind
1748 @cindex Bessel function, first kind
1751 @item @emph{Description}:
1752 @code{BESSEL_JN(N, X)} computes the Bessel function of the first kind of
1753 order @var{N} of @var{X}. This function is available under the name
1754 @code{BESJN} as a GNU extension. If @var{N} and @var{X} are arrays,
1755 their ranks and shapes shall conform.
1757 @code{BESSEL_JN(N1, N2, X)} returns an array with the Bessel functions
1758 of the first kind of the orders @var{N1} to @var{N2}.
1760 @item @emph{Standard}:
1761 Fortran 2008 and later, negative @var{N} is allowed as GNU extension
1764 Elemental function, except for the transformational function
1765 @code{BESSEL_JN(N1, N2, X)}
1767 @item @emph{Syntax}:
1768 @multitable @columnfractions .80
1769 @item @code{RESULT = BESSEL_JN(N, X)}
1770 @item @code{RESULT = BESSEL_JN(N1, N2, X)}
1773 @item @emph{Arguments}:
1774 @multitable @columnfractions .15 .70
1775 @item @var{N} @tab Shall be a scalar or an array of type @code{INTEGER}.
1776 @item @var{N1} @tab Shall be a non-negative scalar of type @code{INTEGER}.
1777 @item @var{N2} @tab Shall be a non-negative scalar of type @code{INTEGER}.
1778 @item @var{X} @tab Shall be a scalar or an array of type @code{REAL};
1779 for @code{BESSEL_JN(N1, N2, X)} it shall be scalar.
1782 @item @emph{Return value}:
1783 The return value is a scalar of type @code{REAL}. It has the same
1787 The transformational function uses a recurrence algorithm which might,
1788 for some values of @var{X}, lead to different results than calls to
1789 the elemental function.
1791 @item @emph{Example}:
1794 real(8) :: x = 1.0_8
1796 end program test_besjn
1799 @item @emph{Specific names}:
1800 @multitable @columnfractions .20 .20 .20 .25
1801 @item Name @tab Argument @tab Return type @tab Standard
1802 @item @code{DBESJN(N, X)} @tab @code{INTEGER N} @tab @code{REAL(8)} @tab GNU extension
1803 @item @tab @code{REAL(8) X} @tab @tab
1810 @section @code{BESSEL_Y0} --- Bessel function of the second kind of order 0
1814 @cindex Bessel function, second kind
1817 @item @emph{Description}:
1818 @code{BESSEL_Y0(X)} computes the Bessel function of the second kind of
1819 order 0 of @var{X}. This function is available under the name
1820 @code{BESY0} as a GNU extension.
1822 @item @emph{Standard}:
1823 Fortran 2008 and later
1828 @item @emph{Syntax}:
1829 @code{RESULT = BESSEL_Y0(X)}
1831 @item @emph{Arguments}:
1832 @multitable @columnfractions .15 .70
1833 @item @var{X} @tab The type shall be @code{REAL}, and it shall be scalar.
1836 @item @emph{Return value}:
1837 The return value is a scalar of type @code{REAL}. It has the same
1840 @item @emph{Example}:
1843 real(8) :: x = 0.0_8
1845 end program test_besy0
1848 @item @emph{Specific names}:
1849 @multitable @columnfractions .20 .20 .20 .25
1850 @item Name @tab Argument @tab Return type @tab Standard
1851 @item @code{DBESY0(X)}@tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU extension
1858 @section @code{BESSEL_Y1} --- Bessel function of the second kind of order 1
1862 @cindex Bessel function, second kind
1865 @item @emph{Description}:
1866 @code{BESSEL_Y1(X)} computes the Bessel function of the second kind of
1867 order 1 of @var{X}. This function is available under the name
1868 @code{BESY1} as a GNU extension.
1870 @item @emph{Standard}:
1871 Fortran 2008 and later
1876 @item @emph{Syntax}:
1877 @code{RESULT = BESSEL_Y1(X)}
1879 @item @emph{Arguments}:
1880 @multitable @columnfractions .15 .70
1881 @item @var{X} @tab The type shall be @code{REAL}, and it shall be scalar.
1884 @item @emph{Return value}:
1885 The return value is a scalar of type @code{REAL}. It has the same
1888 @item @emph{Example}:
1891 real(8) :: x = 1.0_8
1893 end program test_besy1
1896 @item @emph{Specific names}:
1897 @multitable @columnfractions .20 .20 .20 .25
1898 @item Name @tab Argument @tab Return type @tab Standard
1899 @item @code{DBESY1(X)}@tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU extension
1906 @section @code{BESSEL_YN} --- Bessel function of the second kind
1910 @cindex Bessel function, second kind
1913 @item @emph{Description}:
1914 @code{BESSEL_YN(N, X)} computes the Bessel function of the second kind of
1915 order @var{N} of @var{X}. This function is available under the name
1916 @code{BESYN} as a GNU extension. If @var{N} and @var{X} are arrays,
1917 their ranks and shapes shall conform.
1919 @code{BESSEL_YN(N1, N2, X)} returns an array with the Bessel functions
1920 of the first kind of the orders @var{N1} to @var{N2}.
1922 @item @emph{Standard}:
1923 Fortran 2008 and later, negative @var{N} is allowed as GNU extension
1926 Elemental function, except for the transformational function
1927 @code{BESSEL_YN(N1, N2, X)}
1929 @item @emph{Syntax}:
1930 @multitable @columnfractions .80
1931 @item @code{RESULT = BESSEL_YN(N, X)}
1932 @item @code{RESULT = BESSEL_YN(N1, N2, X)}
1935 @item @emph{Arguments}:
1936 @multitable @columnfractions .15 .70
1937 @item @var{N} @tab Shall be a scalar or an array of type @code{INTEGER} .
1938 @item @var{N1} @tab Shall be a non-negative scalar of type @code{INTEGER}.
1939 @item @var{N2} @tab Shall be a non-negative scalar of type @code{INTEGER}.
1940 @item @var{X} @tab Shall be a scalar or an array of type @code{REAL};
1941 for @code{BESSEL_YN(N1, N2, X)} it shall be scalar.
1944 @item @emph{Return value}:
1945 The return value is a scalar of type @code{REAL}. It has the same
1949 The transformational function uses a recurrence algorithm which might,
1950 for some values of @var{X}, lead to different results than calls to
1951 the elemental function.
1953 @item @emph{Example}:
1956 real(8) :: x = 1.0_8
1958 end program test_besyn
1961 @item @emph{Specific names}:
1962 @multitable @columnfractions .20 .20 .20 .25
1963 @item Name @tab Argument @tab Return type @tab Standard
1964 @item @code{DBESYN(N,X)} @tab @code{INTEGER N} @tab @code{REAL(8)} @tab GNU extension
1965 @item @tab @code{REAL(8) X} @tab @tab
1972 @section @code{BGE} --- Bitwise greater than or equal to
1974 @cindex bitwise comparison
1977 @item @emph{Description}:
1978 Determines whether an integral is a bitwise greater than or equal to
1981 @item @emph{Standard}:
1982 Fortran 2008 and later
1987 @item @emph{Syntax}:
1988 @code{RESULT = BGE(I, J)}
1990 @item @emph{Arguments}:
1991 @multitable @columnfractions .15 .70
1992 @item @var{I} @tab Shall be of @code{INTEGER} type.
1993 @item @var{J} @tab Shall be of @code{INTEGER} type, and of the same kind
1997 @item @emph{Return value}:
1998 The return value is of type @code{LOGICAL} and of the default kind.
2000 @item @emph{See also}:
2001 @ref{BGT}, @ref{BLE}, @ref{BLT}
2007 @section @code{BGT} --- Bitwise greater than
2009 @cindex bitwise comparison
2012 @item @emph{Description}:
2013 Determines whether an integral is a bitwise greater than another.
2015 @item @emph{Standard}:
2016 Fortran 2008 and later
2021 @item @emph{Syntax}:
2022 @code{RESULT = BGT(I, J)}
2024 @item @emph{Arguments}:
2025 @multitable @columnfractions .15 .70
2026 @item @var{I} @tab Shall be of @code{INTEGER} type.
2027 @item @var{J} @tab Shall be of @code{INTEGER} type, and of the same kind
2031 @item @emph{Return value}:
2032 The return value is of type @code{LOGICAL} and of the default kind.
2034 @item @emph{See also}:
2035 @ref{BGE}, @ref{BLE}, @ref{BLT}
2041 @section @code{BIT_SIZE} --- Bit size inquiry function
2043 @cindex bits, number of
2044 @cindex size of a variable, in bits
2047 @item @emph{Description}:
2048 @code{BIT_SIZE(I)} returns the number of bits (integer precision plus sign bit)
2049 represented by the type of @var{I}. The result of @code{BIT_SIZE(I)} is
2050 independent of the actual value of @var{I}.
2052 @item @emph{Standard}:
2053 Fortran 95 and later
2058 @item @emph{Syntax}:
2059 @code{RESULT = BIT_SIZE(I)}
2061 @item @emph{Arguments}:
2062 @multitable @columnfractions .15 .70
2063 @item @var{I} @tab The type shall be @code{INTEGER}.
2066 @item @emph{Return value}:
2067 The return value is of type @code{INTEGER}
2069 @item @emph{Example}:
2071 program test_bit_size
2076 end program test_bit_size
2083 @section @code{BLE} --- Bitwise less than or equal to
2085 @cindex bitwise comparison
2088 @item @emph{Description}:
2089 Determines whether an integral is a bitwise less than or equal to
2092 @item @emph{Standard}:
2093 Fortran 2008 and later
2098 @item @emph{Syntax}:
2099 @code{RESULT = BLE(I, J)}
2101 @item @emph{Arguments}:
2102 @multitable @columnfractions .15 .70
2103 @item @var{I} @tab Shall be of @code{INTEGER} type.
2104 @item @var{J} @tab Shall be of @code{INTEGER} type, and of the same kind
2108 @item @emph{Return value}:
2109 The return value is of type @code{LOGICAL} and of the default kind.
2111 @item @emph{See also}:
2112 @ref{BGT}, @ref{BGE}, @ref{BLT}
2118 @section @code{BLT} --- Bitwise less than
2120 @cindex bitwise comparison
2123 @item @emph{Description}:
2124 Determines whether an integral is a bitwise less than another.
2126 @item @emph{Standard}:
2127 Fortran 2008 and later
2132 @item @emph{Syntax}:
2133 @code{RESULT = BLT(I, J)}
2135 @item @emph{Arguments}:
2136 @multitable @columnfractions .15 .70
2137 @item @var{I} @tab Shall be of @code{INTEGER} type.
2138 @item @var{J} @tab Shall be of @code{INTEGER} type, and of the same kind
2142 @item @emph{Return value}:
2143 The return value is of type @code{LOGICAL} and of the default kind.
2145 @item @emph{See also}:
2146 @ref{BGE}, @ref{BGT}, @ref{BLE}
2152 @section @code{BTEST} --- Bit test function
2154 @cindex bits, testing
2157 @item @emph{Description}:
2158 @code{BTEST(I,POS)} returns logical @code{.TRUE.} if the bit at @var{POS}
2159 in @var{I} is set. The counting of the bits starts at 0.
2161 @item @emph{Standard}:
2162 Fortran 95 and later
2167 @item @emph{Syntax}:
2168 @code{RESULT = BTEST(I, POS)}
2170 @item @emph{Arguments}:
2171 @multitable @columnfractions .15 .70
2172 @item @var{I} @tab The type shall be @code{INTEGER}.
2173 @item @var{POS} @tab The type shall be @code{INTEGER}.
2176 @item @emph{Return value}:
2177 The return value is of type @code{LOGICAL}
2179 @item @emph{Example}:
2182 integer :: i = 32768 + 1024 + 64
2186 bool = btest(i, pos)
2189 end program test_btest
2195 @section @code{C_ASSOCIATED} --- Status of a C pointer
2196 @fnindex C_ASSOCIATED
2197 @cindex association status, C pointer
2198 @cindex pointer, C association status
2201 @item @emph{Description}:
2202 @code{C_ASSOCIATED(c_prt_1[, c_ptr_2])} determines the status of the C pointer
2203 @var{c_ptr_1} or if @var{c_ptr_1} is associated with the target @var{c_ptr_2}.
2205 @item @emph{Standard}:
2206 Fortran 2003 and later
2211 @item @emph{Syntax}:
2212 @code{RESULT = C_ASSOCIATED(c_prt_1[, c_ptr_2])}
2214 @item @emph{Arguments}:
2215 @multitable @columnfractions .15 .70
2216 @item @var{c_ptr_1} @tab Scalar of the type @code{C_PTR} or @code{C_FUNPTR}.
2217 @item @var{c_ptr_2} @tab (Optional) Scalar of the same type as @var{c_ptr_1}.
2220 @item @emph{Return value}:
2221 The return value is of type @code{LOGICAL}; it is @code{.false.} if either
2222 @var{c_ptr_1} is a C NULL pointer or if @var{c_ptr1} and @var{c_ptr_2}
2223 point to different addresses.
2225 @item @emph{Example}:
2227 subroutine association_test(a,b)
2228 use iso_c_binding, only: c_associated, c_loc, c_ptr
2232 if(c_associated(b, c_loc(a))) &
2233 stop 'b and a do not point to same target'
2234 end subroutine association_test
2237 @item @emph{See also}:
2238 @ref{C_LOC}, @ref{C_FUNLOC}
2243 @section @code{C_FUNLOC} --- Obtain the C address of a procedure
2245 @cindex pointer, C address of procedures
2248 @item @emph{Description}:
2249 @code{C_FUNLOC(x)} determines the C address of the argument.
2251 @item @emph{Standard}:
2252 Fortran 2003 and later
2257 @item @emph{Syntax}:
2258 @code{RESULT = C_FUNLOC(x)}
2260 @item @emph{Arguments}:
2261 @multitable @columnfractions .15 .70
2262 @item @var{x} @tab Interoperable function or pointer to such function.
2265 @item @emph{Return value}:
2266 The return value is of type @code{C_FUNPTR} and contains the C address
2269 @item @emph{Example}:
2275 subroutine sub(a) bind(c)
2285 subroutine my_routine(p) bind(c,name='myC_func')
2287 type(c_funptr), intent(in) :: p
2290 call my_routine(c_funloc(sub))
2294 @item @emph{See also}:
2295 @ref{C_ASSOCIATED}, @ref{C_LOC}, @ref{C_F_POINTER}, @ref{C_F_PROCPOINTER}
2299 @node C_F_PROCPOINTER
2300 @section @code{C_F_PROCPOINTER} --- Convert C into Fortran procedure pointer
2301 @fnindex C_F_PROCPOINTER
2302 @cindex pointer, C address of pointers
2305 @item @emph{Description}:
2306 @code{C_F_PROCPOINTER(CPTR, FPTR)} Assign the target of the C function pointer
2307 @var{CPTR} to the Fortran procedure pointer @var{FPTR}.
2309 @item @emph{Standard}:
2310 Fortran 2003 and later
2315 @item @emph{Syntax}:
2316 @code{CALL C_F_PROCPOINTER(cptr, fptr)}
2318 @item @emph{Arguments}:
2319 @multitable @columnfractions .15 .70
2320 @item @var{CPTR} @tab scalar of the type @code{C_FUNPTR}. It is
2322 @item @var{FPTR} @tab procedure pointer interoperable with @var{cptr}. It is
2326 @item @emph{Example}:
2334 real(c_float), intent(in) :: a
2335 real(c_float) :: func
2339 function getIterFunc() bind(c,name="getIterFunc")
2341 type(c_funptr) :: getIterFunc
2344 type(c_funptr) :: cfunptr
2345 procedure(func), pointer :: myFunc
2346 cfunptr = getIterFunc()
2347 call c_f_procpointer(cfunptr, myFunc)
2351 @item @emph{See also}:
2352 @ref{C_LOC}, @ref{C_F_POINTER}
2357 @section @code{C_F_POINTER} --- Convert C into Fortran pointer
2358 @fnindex C_F_POINTER
2359 @cindex pointer, convert C to Fortran
2362 @item @emph{Description}:
2363 @code{C_F_POINTER(CPTR, FPTR[, SHAPE])} Assign the target the C pointer
2364 @var{CPTR} to the Fortran pointer @var{FPTR} and specify its
2367 @item @emph{Standard}:
2368 Fortran 2003 and later
2373 @item @emph{Syntax}:
2374 @code{CALL C_F_POINTER(CPTR, FPTR[, SHAPE])}
2376 @item @emph{Arguments}:
2377 @multitable @columnfractions .15 .70
2378 @item @var{CPTR} @tab scalar of the type @code{C_PTR}. It is
2380 @item @var{FPTR} @tab pointer interoperable with @var{cptr}. It is
2382 @item @var{SHAPE} @tab (Optional) Rank-one array of type @code{INTEGER}
2383 with @code{INTENT(IN)}. It shall be present
2384 if and only if @var{fptr} is an array. The size
2385 must be equal to the rank of @var{fptr}.
2388 @item @emph{Example}:
2394 subroutine my_routine(p) bind(c,name='myC_func')
2396 type(c_ptr), intent(out) :: p
2400 real,pointer :: a(:)
2401 call my_routine(cptr)
2402 call c_f_pointer(cptr, a, [12])
2406 @item @emph{See also}:
2407 @ref{C_LOC}, @ref{C_F_PROCPOINTER}
2412 @section @code{C_LOC} --- Obtain the C address of an object
2414 @cindex procedure pointer, convert C to Fortran
2417 @item @emph{Description}:
2418 @code{C_LOC(X)} determines the C address of the argument.
2420 @item @emph{Standard}:
2421 Fortran 2003 and later
2426 @item @emph{Syntax}:
2427 @code{RESULT = C_LOC(X)}
2429 @item @emph{Arguments}:
2430 @multitable @columnfractions .10 .75
2431 @item @var{X} @tab Shall have either the POINTER or TARGET attribute. It shall not be a coindexed object. It shall either be a variable with interoperable type and kind type parameters, or be a scalar, nonpolymorphic variable with no length type parameters.
2435 @item @emph{Return value}:
2436 The return value is of type @code{C_PTR} and contains the C address
2439 @item @emph{Example}:
2441 subroutine association_test(a,b)
2442 use iso_c_binding, only: c_associated, c_loc, c_ptr
2446 if(c_associated(b, c_loc(a))) &
2447 stop 'b and a do not point to same target'
2448 end subroutine association_test
2451 @item @emph{See also}:
2452 @ref{C_ASSOCIATED}, @ref{C_FUNLOC}, @ref{C_F_POINTER}, @ref{C_F_PROCPOINTER}
2457 @section @code{C_SIZEOF} --- Size in bytes of an expression
2459 @cindex expression size
2460 @cindex size of an expression
2463 @item @emph{Description}:
2464 @code{C_SIZEOF(X)} calculates the number of bytes of storage the
2465 expression @code{X} occupies.
2467 @item @emph{Standard}:
2471 Inquiry function of the module @code{ISO_C_BINDING}
2473 @item @emph{Syntax}:
2474 @code{N = C_SIZEOF(X)}
2476 @item @emph{Arguments}:
2477 @multitable @columnfractions .15 .70
2478 @item @var{X} @tab The argument shall be an interoperable data entity.
2481 @item @emph{Return value}:
2482 The return value is of type integer and of the system-dependent kind
2483 @code{C_SIZE_T} (from the @code{ISO_C_BINDING} module). Its value is the
2484 number of bytes occupied by the argument. If the argument has the
2485 @code{POINTER} attribute, the number of bytes of the storage area pointed
2486 to is returned. If the argument is of a derived type with @code{POINTER}
2487 or @code{ALLOCATABLE} components, the return value doesn't account for
2488 the sizes of the data pointed to by these components.
2490 @item @emph{Example}:
2494 real(c_float) :: r, s(5)
2495 print *, (c_sizeof(s)/c_sizeof(r) == 5)
2498 The example will print @code{.TRUE.} unless you are using a platform
2499 where default @code{REAL} variables are unusually padded.
2501 @item @emph{See also}:
2502 @ref{SIZEOF}, @ref{STORAGE_SIZE}
2507 @section @code{CEILING} --- Integer ceiling function
2510 @cindex rounding, ceiling
2513 @item @emph{Description}:
2514 @code{CEILING(A)} returns the least integer greater than or equal to @var{A}.
2516 @item @emph{Standard}:
2517 Fortran 95 and later
2522 @item @emph{Syntax}:
2523 @code{RESULT = CEILING(A [, KIND])}
2525 @item @emph{Arguments}:
2526 @multitable @columnfractions .15 .70
2527 @item @var{A} @tab The type shall be @code{REAL}.
2528 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
2529 expression indicating the kind parameter of the result.
2532 @item @emph{Return value}:
2533 The return value is of type @code{INTEGER(KIND)} if @var{KIND} is present
2534 and a default-kind @code{INTEGER} otherwise.
2536 @item @emph{Example}:
2538 program test_ceiling
2541 print *, ceiling(x) ! returns 64
2542 print *, ceiling(y) ! returns -63
2543 end program test_ceiling
2546 @item @emph{See also}:
2547 @ref{FLOOR}, @ref{NINT}
2554 @section @code{CHAR} --- Character conversion function
2556 @cindex conversion, to character
2559 @item @emph{Description}:
2560 @code{CHAR(I [, KIND])} returns the character represented by the integer @var{I}.
2562 @item @emph{Standard}:
2563 Fortran 77 and later
2568 @item @emph{Syntax}:
2569 @code{RESULT = CHAR(I [, KIND])}
2571 @item @emph{Arguments}:
2572 @multitable @columnfractions .15 .70
2573 @item @var{I} @tab The type shall be @code{INTEGER}.
2574 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
2575 expression indicating the kind parameter of the result.
2578 @item @emph{Return value}:
2579 The return value is of type @code{CHARACTER(1)}
2581 @item @emph{Example}:
2587 print *, i, c ! returns 'J'
2588 end program test_char
2591 @item @emph{Specific names}:
2592 @multitable @columnfractions .20 .20 .20 .25
2593 @item Name @tab Argument @tab Return type @tab Standard
2594 @item @code{CHAR(I)} @tab @code{INTEGER I} @tab @code{CHARACTER(LEN=1)} @tab F77 and later
2598 See @ref{ICHAR} for a discussion of converting between numerical values
2599 and formatted string representations.
2601 @item @emph{See also}:
2602 @ref{ACHAR}, @ref{IACHAR}, @ref{ICHAR}
2609 @section @code{CHDIR} --- Change working directory
2611 @cindex system, working directory
2614 @item @emph{Description}:
2615 Change current working directory to a specified path.
2617 This intrinsic is provided in both subroutine and function forms; however,
2618 only one form can be used in any given program unit.
2620 @item @emph{Standard}:
2624 Subroutine, function
2626 @item @emph{Syntax}:
2627 @multitable @columnfractions .80
2628 @item @code{CALL CHDIR(NAME [, STATUS])}
2629 @item @code{STATUS = CHDIR(NAME)}
2632 @item @emph{Arguments}:
2633 @multitable @columnfractions .15 .70
2634 @item @var{NAME} @tab The type shall be @code{CHARACTER} of default
2635 kind and shall specify a valid path within the file system.
2636 @item @var{STATUS} @tab (Optional) @code{INTEGER} status flag of the default
2637 kind. Returns 0 on success, and a system specific and nonzero error code
2641 @item @emph{Example}:
2644 CHARACTER(len=255) :: path
2646 WRITE(*,*) TRIM(path)
2649 WRITE(*,*) TRIM(path)
2653 @item @emph{See also}:
2660 @section @code{CHMOD} --- Change access permissions of files
2662 @cindex file system, change access mode
2665 @item @emph{Description}:
2666 @code{CHMOD} changes the permissions of a file. This function invokes
2667 @code{/bin/chmod} and might therefore not work on all platforms.
2669 This intrinsic is provided in both subroutine and function forms; however,
2670 only one form can be used in any given program unit.
2672 @item @emph{Standard}:
2676 Subroutine, function
2678 @item @emph{Syntax}:
2679 @multitable @columnfractions .80
2680 @item @code{CALL CHMOD(NAME, MODE[, STATUS])}
2681 @item @code{STATUS = CHMOD(NAME, MODE)}
2684 @item @emph{Arguments}:
2685 @multitable @columnfractions .15 .70
2687 @item @var{NAME} @tab Scalar @code{CHARACTER} of default kind with the
2688 file name. Trailing blanks are ignored unless the character
2689 @code{achar(0)} is present, then all characters up to and excluding
2690 @code{achar(0)} are used as the file name.
2692 @item @var{MODE} @tab Scalar @code{CHARACTER} of default kind giving the
2693 file permission. @var{MODE} uses the same syntax as the @var{MODE}
2694 argument of @code{/bin/chmod}.
2696 @item @var{STATUS} @tab (optional) scalar @code{INTEGER}, which is
2697 @code{0} on success and nonzero otherwise.
2700 @item @emph{Return value}:
2701 In either syntax, @var{STATUS} is set to @code{0} on success and nonzero
2704 @item @emph{Example}:
2705 @code{CHMOD} as subroutine
2710 call chmod('test.dat','u+x',status)
2711 print *, 'Status: ', status
2712 end program chmod_test
2714 @code{CHMOD} as function:
2719 status = chmod('test.dat','u+x')
2720 print *, 'Status: ', status
2721 end program chmod_test
2729 @section @code{CMPLX} --- Complex conversion function
2731 @cindex complex numbers, conversion to
2732 @cindex conversion, to complex
2735 @item @emph{Description}:
2736 @code{CMPLX(X [, Y [, KIND]])} returns a complex number where @var{X} is converted to
2737 the real component. If @var{Y} is present it is converted to the imaginary
2738 component. If @var{Y} is not present then the imaginary component is set to
2739 0.0. If @var{X} is complex then @var{Y} must not be present.
2741 @item @emph{Standard}:
2742 Fortran 77 and later
2747 @item @emph{Syntax}:
2748 @code{RESULT = CMPLX(X [, Y [, KIND]])}
2750 @item @emph{Arguments}:
2751 @multitable @columnfractions .15 .70
2752 @item @var{X} @tab The type may be @code{INTEGER}, @code{REAL},
2754 @item @var{Y} @tab (Optional; only allowed if @var{X} is not
2755 @code{COMPLEX}.) May be @code{INTEGER} or @code{REAL}.
2756 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
2757 expression indicating the kind parameter of the result.
2760 @item @emph{Return value}:
2761 The return value is of @code{COMPLEX} type, with a kind equal to
2762 @var{KIND} if it is specified. If @var{KIND} is not specified, the
2763 result is of the default @code{COMPLEX} kind, regardless of the kinds of
2764 @var{X} and @var{Y}.
2766 @item @emph{Example}:
2773 print *, z, cmplx(x)
2774 end program test_cmplx
2777 @item @emph{See also}:
2783 @node COMMAND_ARGUMENT_COUNT
2784 @section @code{COMMAND_ARGUMENT_COUNT} --- Get number of command line arguments
2785 @fnindex COMMAND_ARGUMENT_COUNT
2786 @cindex command-line arguments
2787 @cindex command-line arguments, number of
2788 @cindex arguments, to program
2791 @item @emph{Description}:
2792 @code{COMMAND_ARGUMENT_COUNT} returns the number of arguments passed on the
2793 command line when the containing program was invoked.
2795 @item @emph{Standard}:
2796 Fortran 2003 and later
2801 @item @emph{Syntax}:
2802 @code{RESULT = COMMAND_ARGUMENT_COUNT()}
2804 @item @emph{Arguments}:
2805 @multitable @columnfractions .15 .70
2809 @item @emph{Return value}:
2810 The return value is an @code{INTEGER} of default kind.
2812 @item @emph{Example}:
2814 program test_command_argument_count
2816 count = command_argument_count()
2818 end program test_command_argument_count
2821 @item @emph{See also}:
2822 @ref{GET_COMMAND}, @ref{GET_COMMAND_ARGUMENT}
2827 @node COMPILER_OPTIONS
2828 @section @code{COMPILER_OPTIONS} --- Options passed to the compiler
2829 @fnindex COMPILER_OPTIONS
2830 @cindex flags inquiry function
2831 @cindex options inquiry function
2832 @cindex compiler flags inquiry function
2835 @item @emph{Description}:
2836 @code{COMPILER_OPTIONS} returns a string with the options used for
2839 @item @emph{Standard}:
2843 Inquiry function of the module @code{ISO_FORTRAN_ENV}
2845 @item @emph{Syntax}:
2846 @code{STR = COMPILER_OPTIONS()}
2848 @item @emph{Arguments}:
2851 @item @emph{Return value}:
2852 The return value is a default-kind string with system-dependent length.
2853 It contains the compiler flags used to compile the file, which called
2854 the @code{COMPILER_OPTIONS} intrinsic.
2856 @item @emph{Example}:
2859 print '(4a)', 'This file was compiled by ', &
2860 compiler_version(), ' using the options ', &
2865 @item @emph{See also}:
2866 @ref{COMPILER_VERSION}, @ref{ISO_FORTRAN_ENV}
2871 @node COMPILER_VERSION
2872 @section @code{COMPILER_VERSION} --- Compiler version string
2873 @fnindex COMPILER_VERSION
2874 @cindex compiler, name and version
2875 @cindex version of the compiler
2878 @item @emph{Description}:
2879 @code{COMPILER_VERSION} returns a string with the name and the
2880 version of the compiler.
2882 @item @emph{Standard}:
2886 Inquiry function of the module @code{ISO_FORTRAN_ENV}
2888 @item @emph{Syntax}:
2889 @code{STR = COMPILER_VERSION()}
2891 @item @emph{Arguments}:
2894 @item @emph{Return value}:
2895 The return value is a default-kind string with system-dependent length.
2896 It contains the name of the compiler and its version number.
2898 @item @emph{Example}:
2901 print '(4a)', 'This file was compiled by ', &
2902 compiler_version(), ' using the options ', &
2907 @item @emph{See also}:
2908 @ref{COMPILER_OPTIONS}, @ref{ISO_FORTRAN_ENV}
2914 @section @code{COMPLEX} --- Complex conversion function
2916 @cindex complex numbers, conversion to
2917 @cindex conversion, to complex
2920 @item @emph{Description}:
2921 @code{COMPLEX(X, Y)} returns a complex number where @var{X} is converted
2922 to the real component and @var{Y} is converted to the imaginary
2925 @item @emph{Standard}:
2931 @item @emph{Syntax}:
2932 @code{RESULT = COMPLEX(X, Y)}
2934 @item @emph{Arguments}:
2935 @multitable @columnfractions .15 .70
2936 @item @var{X} @tab The type may be @code{INTEGER} or @code{REAL}.
2937 @item @var{Y} @tab The type may be @code{INTEGER} or @code{REAL}.
2940 @item @emph{Return value}:
2941 If @var{X} and @var{Y} are both of @code{INTEGER} type, then the return
2942 value is of default @code{COMPLEX} type.
2944 If @var{X} and @var{Y} are of @code{REAL} type, or one is of @code{REAL}
2945 type and one is of @code{INTEGER} type, then the return value is of
2946 @code{COMPLEX} type with a kind equal to that of the @code{REAL}
2947 argument with the highest precision.
2949 @item @emph{Example}:
2951 program test_complex
2954 print *, complex(i, x)
2955 end program test_complex
2958 @item @emph{See also}:
2965 @section @code{CONJG} --- Complex conjugate function
2968 @cindex complex conjugate
2971 @item @emph{Description}:
2972 @code{CONJG(Z)} returns the conjugate of @var{Z}. If @var{Z} is @code{(x, y)}
2973 then the result is @code{(x, -y)}
2975 @item @emph{Standard}:
2976 Fortran 77 and later, has overloads that are GNU extensions
2981 @item @emph{Syntax}:
2984 @item @emph{Arguments}:
2985 @multitable @columnfractions .15 .70
2986 @item @var{Z} @tab The type shall be @code{COMPLEX}.
2989 @item @emph{Return value}:
2990 The return value is of type @code{COMPLEX}.
2992 @item @emph{Example}:
2995 complex :: z = (2.0, 3.0)
2996 complex(8) :: dz = (2.71_8, -3.14_8)
3001 end program test_conjg
3004 @item @emph{Specific names}:
3005 @multitable @columnfractions .20 .20 .20 .25
3006 @item Name @tab Argument @tab Return type @tab Standard
3007 @item @code{CONJG(Z)} @tab @code{COMPLEX Z} @tab @code{COMPLEX} @tab GNU extension
3008 @item @code{DCONJG(Z)} @tab @code{COMPLEX(8) Z} @tab @code{COMPLEX(8)} @tab GNU extension
3015 @section @code{COS} --- Cosine function
3021 @cindex trigonometric function, cosine
3025 @item @emph{Description}:
3026 @code{COS(X)} computes the cosine of @var{X}.
3028 @item @emph{Standard}:
3029 Fortran 77 and later, has overloads that are GNU extensions
3034 @item @emph{Syntax}:
3035 @code{RESULT = COS(X)}
3037 @item @emph{Arguments}:
3038 @multitable @columnfractions .15 .70
3039 @item @var{X} @tab The type shall be @code{REAL} or
3043 @item @emph{Return value}:
3044 The return value is of the same type and kind as @var{X}. The real part
3045 of the result is in radians. If @var{X} is of the type @code{REAL},
3046 the return value lies in the range @math{ -1 \leq \cos (x) \leq 1}.
3048 @item @emph{Example}:
3053 end program test_cos
3056 @item @emph{Specific names}:
3057 @multitable @columnfractions .20 .20 .20 .25
3058 @item Name @tab Argument @tab Return type @tab Standard
3059 @item @code{COS(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab Fortran 77 and later
3060 @item @code{DCOS(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab Fortran 77 and later
3061 @item @code{CCOS(X)} @tab @code{COMPLEX(4) X} @tab @code{COMPLEX(4)} @tab Fortran 77 and later
3062 @item @code{ZCOS(X)} @tab @code{COMPLEX(8) X} @tab @code{COMPLEX(8)} @tab GNU extension
3063 @item @code{CDCOS(X)} @tab @code{COMPLEX(8) X} @tab @code{COMPLEX(8)} @tab GNU extension
3066 @item @emph{See also}:
3067 Inverse function: @ref{ACOS}
3074 @section @code{COSH} --- Hyperbolic cosine function
3077 @cindex hyperbolic cosine
3078 @cindex hyperbolic function, cosine
3079 @cindex cosine, hyperbolic
3082 @item @emph{Description}:
3083 @code{COSH(X)} computes the hyperbolic cosine of @var{X}.
3085 @item @emph{Standard}:
3086 Fortran 77 and later, for a complex argument Fortran 2008 or later
3091 @item @emph{Syntax}:
3094 @item @emph{Arguments}:
3095 @multitable @columnfractions .15 .70
3096 @item @var{X} @tab The type shall be @code{REAL} or @code{COMPLEX}.
3099 @item @emph{Return value}:
3100 The return value has same type and kind as @var{X}. If @var{X} is
3101 complex, the imaginary part of the result is in radians. If @var{X}
3102 is @code{REAL}, the return value has a lower bound of one,
3103 @math{\cosh (x) \geq 1}.
3105 @item @emph{Example}:
3108 real(8) :: x = 1.0_8
3110 end program test_cosh
3113 @item @emph{Specific names}:
3114 @multitable @columnfractions .20 .20 .20 .25
3115 @item Name @tab Argument @tab Return type @tab Standard
3116 @item @code{COSH(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab Fortran 77 and later
3117 @item @code{DCOSH(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab Fortran 77 and later
3120 @item @emph{See also}:
3121 Inverse function: @ref{ACOSH}
3128 @section @code{COUNT} --- Count function
3130 @cindex array, conditionally count elements
3131 @cindex array, element counting
3132 @cindex array, number of elements
3135 @item @emph{Description}:
3137 Counts the number of @code{.TRUE.} elements in a logical @var{MASK},
3138 or, if the @var{DIM} argument is supplied, counts the number of
3139 elements along each row of the array in the @var{DIM} direction.
3140 If the array has zero size, or all of the elements of @var{MASK} are
3141 @code{.FALSE.}, then the result is @code{0}.
3143 @item @emph{Standard}:
3144 Fortran 95 and later, with @var{KIND} argument Fortran 2003 and later
3147 Transformational function
3149 @item @emph{Syntax}:
3150 @code{RESULT = COUNT(MASK [, DIM, KIND])}
3152 @item @emph{Arguments}:
3153 @multitable @columnfractions .15 .70
3154 @item @var{MASK} @tab The type shall be @code{LOGICAL}.
3155 @item @var{DIM} @tab (Optional) The type shall be @code{INTEGER}.
3156 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
3157 expression indicating the kind parameter of the result.
3160 @item @emph{Return value}:
3161 The return value is of type @code{INTEGER} and of kind @var{KIND}. If
3162 @var{KIND} is absent, the return value is of default integer kind.
3163 If @var{DIM} is present, the result is an array with a rank one less
3164 than the rank of @var{ARRAY}, and a size corresponding to the shape
3165 of @var{ARRAY} with the @var{DIM} dimension removed.
3167 @item @emph{Example}:
3170 integer, dimension(2,3) :: a, b
3171 logical, dimension(2,3) :: mask
3172 a = reshape( (/ 1, 2, 3, 4, 5, 6 /), (/ 2, 3 /))
3173 b = reshape( (/ 0, 7, 3, 4, 5, 8 /), (/ 2, 3 /))
3174 print '(3i3)', a(1,:)
3175 print '(3i3)', a(2,:)
3177 print '(3i3)', b(1,:)
3178 print '(3i3)', b(2,:)
3181 print '(3l3)', mask(1,:)
3182 print '(3l3)', mask(2,:)
3184 print '(3i3)', count(mask)
3186 print '(3i3)', count(mask, 1)
3188 print '(3i3)', count(mask, 2)
3189 end program test_count
3196 @section @code{CPU_TIME} --- CPU elapsed time in seconds
3198 @cindex time, elapsed
3201 @item @emph{Description}:
3202 Returns a @code{REAL} value representing the elapsed CPU time in
3203 seconds. This is useful for testing segments of code to determine
3206 If a time source is available, time will be reported with microsecond
3207 resolution. If no time source is available, @var{TIME} is set to
3210 Note that @var{TIME} may contain a, system dependent, arbitrary offset
3211 and may not start with @code{0.0}. For @code{CPU_TIME}, the absolute
3212 value is meaningless, only differences between subsequent calls to
3213 this subroutine, as shown in the example below, should be used.
3216 @item @emph{Standard}:
3217 Fortran 95 and later
3222 @item @emph{Syntax}:
3223 @code{CALL CPU_TIME(TIME)}
3225 @item @emph{Arguments}:
3226 @multitable @columnfractions .15 .70
3227 @item @var{TIME} @tab The type shall be @code{REAL} with @code{INTENT(OUT)}.
3230 @item @emph{Return value}:
3233 @item @emph{Example}:
3235 program test_cpu_time
3236 real :: start, finish
3237 call cpu_time(start)
3238 ! put code to test here
3239 call cpu_time(finish)
3240 print '("Time = ",f6.3," seconds.")',finish-start
3241 end program test_cpu_time
3244 @item @emph{See also}:
3245 @ref{SYSTEM_CLOCK}, @ref{DATE_AND_TIME}
3251 @section @code{CSHIFT} --- Circular shift elements of an array
3253 @cindex array, shift circularly
3254 @cindex array, permutation
3255 @cindex array, rotate
3258 @item @emph{Description}:
3259 @code{CSHIFT(ARRAY, SHIFT [, DIM])} performs a circular shift on elements of
3260 @var{ARRAY} along the dimension of @var{DIM}. If @var{DIM} is omitted it is
3261 taken to be @code{1}. @var{DIM} is a scalar of type @code{INTEGER} in the
3262 range of @math{1 \leq DIM \leq n)} where @math{n} is the rank of @var{ARRAY}.
3263 If the rank of @var{ARRAY} is one, then all elements of @var{ARRAY} are shifted
3264 by @var{SHIFT} places. If rank is greater than one, then all complete rank one
3265 sections of @var{ARRAY} along the given dimension are shifted. Elements
3266 shifted out one end of each rank one section are shifted back in the other end.
3268 @item @emph{Standard}:
3269 Fortran 95 and later
3272 Transformational function
3274 @item @emph{Syntax}:
3275 @code{RESULT = CSHIFT(ARRAY, SHIFT [, DIM])}
3277 @item @emph{Arguments}:
3278 @multitable @columnfractions .15 .70
3279 @item @var{ARRAY} @tab Shall be an array of any type.
3280 @item @var{SHIFT} @tab The type shall be @code{INTEGER}.
3281 @item @var{DIM} @tab The type shall be @code{INTEGER}.
3284 @item @emph{Return value}:
3285 Returns an array of same type and rank as the @var{ARRAY} argument.
3287 @item @emph{Example}:
3290 integer, dimension(3,3) :: a
3291 a = reshape( (/ 1, 2, 3, 4, 5, 6, 7, 8, 9 /), (/ 3, 3 /))
3292 print '(3i3)', a(1,:)
3293 print '(3i3)', a(2,:)
3294 print '(3i3)', a(3,:)
3295 a = cshift(a, SHIFT=(/1, 2, -1/), DIM=2)
3297 print '(3i3)', a(1,:)
3298 print '(3i3)', a(2,:)
3299 print '(3i3)', a(3,:)
3300 end program test_cshift
3307 @section @code{CTIME} --- Convert a time into a string
3309 @cindex time, conversion to string
3310 @cindex conversion, to string
3313 @item @emph{Description}:
3314 @code{CTIME} converts a system time value, such as returned by
3315 @code{TIME8}, to a string. Unless the application has called
3316 @code{setlocale}, the output will be in the default locale, of length
3317 24 and of the form @samp{Sat Aug 19 18:13:14 1995}. In other locales,
3318 a longer string may result.
3320 This intrinsic is provided in both subroutine and function forms; however,
3321 only one form can be used in any given program unit.
3323 @item @emph{Standard}:
3327 Subroutine, function
3329 @item @emph{Syntax}:
3330 @multitable @columnfractions .80
3331 @item @code{CALL CTIME(TIME, RESULT)}.
3332 @item @code{RESULT = CTIME(TIME)}.
3335 @item @emph{Arguments}:
3336 @multitable @columnfractions .15 .70
3337 @item @var{TIME} @tab The type shall be of type @code{INTEGER}.
3338 @item @var{RESULT} @tab The type shall be of type @code{CHARACTER} and
3339 of default kind. It is an @code{INTENT(OUT)} argument. If the length
3340 of this variable is too short for the time and date string to fit
3341 completely, it will be blank on procedure return.
3344 @item @emph{Return value}:
3345 The converted date and time as a string.
3347 @item @emph{Example}:
3351 character(len=30) :: date
3354 ! Do something, main part of the program
3357 print *, 'Program was started on ', date
3358 end program test_ctime
3361 @item @emph{See Also}:
3362 @ref{DATE_AND_TIME}, @ref{GMTIME}, @ref{LTIME}, @ref{TIME}, @ref{TIME8}
3368 @section @code{DATE_AND_TIME} --- Date and time subroutine
3369 @fnindex DATE_AND_TIME
3370 @cindex date, current
3371 @cindex current date
3372 @cindex time, current
3373 @cindex current time
3376 @item @emph{Description}:
3377 @code{DATE_AND_TIME(DATE, TIME, ZONE, VALUES)} gets the corresponding date and
3378 time information from the real-time system clock. @var{DATE} is
3379 @code{INTENT(OUT)} and has form ccyymmdd. @var{TIME} is @code{INTENT(OUT)} and
3380 has form hhmmss.sss. @var{ZONE} is @code{INTENT(OUT)} and has form (+-)hhmm,
3381 representing the difference with respect to Coordinated Universal Time (UTC).
3382 Unavailable time and date parameters return blanks.
3384 @var{VALUES} is @code{INTENT(OUT)} and provides the following:
3386 @multitable @columnfractions .15 .30 .40
3387 @item @tab @code{VALUE(1)}: @tab The year
3388 @item @tab @code{VALUE(2)}: @tab The month
3389 @item @tab @code{VALUE(3)}: @tab The day of the month
3390 @item @tab @code{VALUE(4)}: @tab Time difference with UTC in minutes
3391 @item @tab @code{VALUE(5)}: @tab The hour of the day
3392 @item @tab @code{VALUE(6)}: @tab The minutes of the hour
3393 @item @tab @code{VALUE(7)}: @tab The seconds of the minute
3394 @item @tab @code{VALUE(8)}: @tab The milliseconds of the second
3397 @item @emph{Standard}:
3398 Fortran 95 and later
3403 @item @emph{Syntax}:
3404 @code{CALL DATE_AND_TIME([DATE, TIME, ZONE, VALUES])}
3406 @item @emph{Arguments}:
3407 @multitable @columnfractions .15 .70
3408 @item @var{DATE} @tab (Optional) The type shall be @code{CHARACTER(LEN=8)}
3409 or larger, and of default kind.
3410 @item @var{TIME} @tab (Optional) The type shall be @code{CHARACTER(LEN=10)}
3411 or larger, and of default kind.
3412 @item @var{ZONE} @tab (Optional) The type shall be @code{CHARACTER(LEN=5)}
3413 or larger, and of default kind.
3414 @item @var{VALUES}@tab (Optional) The type shall be @code{INTEGER(8)}.
3417 @item @emph{Return value}:
3420 @item @emph{Example}:
3422 program test_time_and_date
3423 character(8) :: date
3424 character(10) :: time
3425 character(5) :: zone
3426 integer,dimension(8) :: values
3427 ! using keyword arguments
3428 call date_and_time(date,time,zone,values)
3429 call date_and_time(DATE=date,ZONE=zone)
3430 call date_and_time(TIME=time)
3431 call date_and_time(VALUES=values)
3432 print '(a,2x,a,2x,a)', date, time, zone
3433 print '(8i5))', values
3434 end program test_time_and_date
3437 @item @emph{See also}:
3438 @ref{CPU_TIME}, @ref{SYSTEM_CLOCK}
3444 @section @code{DBLE} --- Double conversion function
3446 @cindex conversion, to real
3449 @item @emph{Description}:
3450 @code{DBLE(A)} Converts @var{A} to double precision real type.
3452 @item @emph{Standard}:
3453 Fortran 77 and later
3458 @item @emph{Syntax}:
3459 @code{RESULT = DBLE(A)}
3461 @item @emph{Arguments}:
3462 @multitable @columnfractions .15 .70
3463 @item @var{A} @tab The type shall be @code{INTEGER}, @code{REAL},
3467 @item @emph{Return value}:
3468 The return value is of type double precision real.
3470 @item @emph{Example}:
3475 complex :: z = (2.3,1.14)
3476 print *, dble(x), dble(i), dble(z)
3477 end program test_dble
3480 @item @emph{See also}:
3487 @section @code{DCMPLX} --- Double complex conversion function
3489 @cindex complex numbers, conversion to
3490 @cindex conversion, to complex
3493 @item @emph{Description}:
3494 @code{DCMPLX(X [,Y])} returns a double complex number where @var{X} is
3495 converted to the real component. If @var{Y} is present it is converted to the
3496 imaginary component. If @var{Y} is not present then the imaginary component is
3497 set to 0.0. If @var{X} is complex then @var{Y} must not be present.
3499 @item @emph{Standard}:
3505 @item @emph{Syntax}:
3506 @code{RESULT = DCMPLX(X [, Y])}
3508 @item @emph{Arguments}:
3509 @multitable @columnfractions .15 .70
3510 @item @var{X} @tab The type may be @code{INTEGER}, @code{REAL},
3512 @item @var{Y} @tab (Optional if @var{X} is not @code{COMPLEX}.) May be
3513 @code{INTEGER} or @code{REAL}.
3516 @item @emph{Return value}:
3517 The return value is of type @code{COMPLEX(8)}
3519 @item @emph{Example}:
3529 print *, dcmplx(x,i)
3530 end program test_dcmplx
3536 @section @code{DIGITS} --- Significant binary digits function
3538 @cindex model representation, significant digits
3541 @item @emph{Description}:
3542 @code{DIGITS(X)} returns the number of significant binary digits of the internal
3543 model representation of @var{X}. For example, on a system using a 32-bit
3544 floating point representation, a default real number would likely return 24.
3546 @item @emph{Standard}:
3547 Fortran 95 and later
3552 @item @emph{Syntax}:
3553 @code{RESULT = DIGITS(X)}
3555 @item @emph{Arguments}:
3556 @multitable @columnfractions .15 .70
3557 @item @var{X} @tab The type may be @code{INTEGER} or @code{REAL}.
3560 @item @emph{Return value}:
3561 The return value is of type @code{INTEGER}.
3563 @item @emph{Example}:
3566 integer :: i = 12345
3572 end program test_digits
3579 @section @code{DIM} --- Positive difference
3583 @cindex positive difference
3586 @item @emph{Description}:
3587 @code{DIM(X,Y)} returns the difference @code{X-Y} if the result is positive;
3588 otherwise returns zero.
3590 @item @emph{Standard}:
3591 Fortran 77 and later
3596 @item @emph{Syntax}:
3597 @code{RESULT = DIM(X, Y)}
3599 @item @emph{Arguments}:
3600 @multitable @columnfractions .15 .70
3601 @item @var{X} @tab The type shall be @code{INTEGER} or @code{REAL}
3602 @item @var{Y} @tab The type shall be the same type and kind as @var{X}.
3605 @item @emph{Return value}:
3606 The return value is of type @code{INTEGER} or @code{REAL}.
3608 @item @emph{Example}:
3614 x = dim(4.345_8, 2.111_8)
3617 end program test_dim
3620 @item @emph{Specific names}:
3621 @multitable @columnfractions .20 .20 .20 .25
3622 @item Name @tab Argument @tab Return type @tab Standard
3623 @item @code{DIM(X,Y)} @tab @code{REAL(4) X, Y} @tab @code{REAL(4)} @tab Fortran 77 and later
3624 @item @code{IDIM(X,Y)} @tab @code{INTEGER(4) X, Y} @tab @code{INTEGER(4)} @tab Fortran 77 and later
3625 @item @code{DDIM(X,Y)} @tab @code{REAL(8) X, Y} @tab @code{REAL(8)} @tab Fortran 77 and later
3632 @section @code{DOT_PRODUCT} --- Dot product function
3633 @fnindex DOT_PRODUCT
3635 @cindex vector product
3636 @cindex product, vector
3639 @item @emph{Description}:
3640 @code{DOT_PRODUCT(VECTOR_A, VECTOR_B)} computes the dot product multiplication
3641 of two vectors @var{VECTOR_A} and @var{VECTOR_B}. The two vectors may be
3642 either numeric or logical and must be arrays of rank one and of equal size. If
3643 the vectors are @code{INTEGER} or @code{REAL}, the result is
3644 @code{SUM(VECTOR_A*VECTOR_B)}. If the vectors are @code{COMPLEX}, the result
3645 is @code{SUM(CONJG(VECTOR_A)*VECTOR_B)}. If the vectors are @code{LOGICAL},
3646 the result is @code{ANY(VECTOR_A .AND. VECTOR_B)}.
3648 @item @emph{Standard}:
3649 Fortran 95 and later
3652 Transformational function
3654 @item @emph{Syntax}:
3655 @code{RESULT = DOT_PRODUCT(VECTOR_A, VECTOR_B)}
3657 @item @emph{Arguments}:
3658 @multitable @columnfractions .15 .70
3659 @item @var{VECTOR_A} @tab The type shall be numeric or @code{LOGICAL}, rank 1.
3660 @item @var{VECTOR_B} @tab The type shall be numeric if @var{VECTOR_A} is of numeric type or @code{LOGICAL} if @var{VECTOR_A} is of type @code{LOGICAL}. @var{VECTOR_B} shall be a rank-one array.
3663 @item @emph{Return value}:
3664 If the arguments are numeric, the return value is a scalar of numeric type,
3665 @code{INTEGER}, @code{REAL}, or @code{COMPLEX}. If the arguments are
3666 @code{LOGICAL}, the return value is @code{.TRUE.} or @code{.FALSE.}.
3668 @item @emph{Example}:
3670 program test_dot_prod
3671 integer, dimension(3) :: a, b
3678 print *, dot_product(a,b)
3679 end program test_dot_prod
3686 @section @code{DPROD} --- Double product function
3688 @cindex product, double-precision
3691 @item @emph{Description}:
3692 @code{DPROD(X,Y)} returns the product @code{X*Y}.
3694 @item @emph{Standard}:
3695 Fortran 77 and later
3700 @item @emph{Syntax}:
3701 @code{RESULT = DPROD(X, Y)}
3703 @item @emph{Arguments}:
3704 @multitable @columnfractions .15 .70
3705 @item @var{X} @tab The type shall be @code{REAL}.
3706 @item @var{Y} @tab The type shall be @code{REAL}.
3709 @item @emph{Return value}:
3710 The return value is of type @code{REAL(8)}.
3712 @item @emph{Example}:
3720 end program test_dprod
3723 @item @emph{Specific names}:
3724 @multitable @columnfractions .20 .20 .20 .25
3725 @item Name @tab Argument @tab Return type @tab Standard
3726 @item @code{DPROD(X,Y)} @tab @code{REAL(4) X, Y} @tab @code{REAL(4)} @tab Fortran 77 and later
3733 @section @code{DREAL} --- Double real part function
3735 @cindex complex numbers, real part
3738 @item @emph{Description}:
3739 @code{DREAL(Z)} returns the real part of complex variable @var{Z}.
3741 @item @emph{Standard}:
3747 @item @emph{Syntax}:
3748 @code{RESULT = DREAL(A)}
3750 @item @emph{Arguments}:
3751 @multitable @columnfractions .15 .70
3752 @item @var{A} @tab The type shall be @code{COMPLEX(8)}.
3755 @item @emph{Return value}:
3756 The return value is of type @code{REAL(8)}.
3758 @item @emph{Example}:
3761 complex(8) :: z = (1.3_8,7.2_8)
3763 end program test_dreal
3766 @item @emph{See also}:
3774 @section @code{DSHIFTL} --- Combined left shift
3776 @cindex left shift, combined
3780 @item @emph{Description}:
3781 @code{DSHIFTL(I, J, SHIFT)} combines bits of @var{I} and @var{J}. The
3782 rightmost @var{SHIFT} bits of the result are the leftmost @var{SHIFT}
3783 bits of @var{J}, and the remaining bits are the rightmost bits of
3786 @item @emph{Standard}:
3787 Fortran 2008 and later
3792 @item @emph{Syntax}:
3793 @code{RESULT = DSHIFTL(I, J, SHIFT)}
3795 @item @emph{Arguments}:
3796 @multitable @columnfractions .15 .70
3797 @item @var{I} @tab Shall be of type @code{INTEGER}.
3798 @item @var{J} @tab Shall be of type @code{INTEGER}, and of the same kind
3800 @item @var{SHIFT} @tab Shall be of type @code{INTEGER}.
3803 @item @emph{Return value}:
3804 The return value has same type and kind as @var{I}.
3806 @item @emph{See also}:
3814 @section @code{DSHIFTR} --- Combined right shift
3816 @cindex right shift, combined
3817 @cindex shift, right
3820 @item @emph{Description}:
3821 @code{DSHIFTR(I, J, SHIFT)} combines bits of @var{I} and @var{J}. The
3822 leftmost @var{SHIFT} bits of the result are the rightmost @var{SHIFT}
3823 bits of @var{I}, and the remaining bits are the leftmost bits of
3826 @item @emph{Standard}:
3827 Fortran 2008 and later
3832 @item @emph{Syntax}:
3833 @code{RESULT = DSHIFTR(I, J, SHIFT)}
3835 @item @emph{Arguments}:
3836 @multitable @columnfractions .15 .70
3837 @item @var{I} @tab Shall be of type @code{INTEGER}.
3838 @item @var{J} @tab Shall be of type @code{INTEGER}, and of the same kind
3840 @item @var{SHIFT} @tab Shall be of type @code{INTEGER}.
3843 @item @emph{Return value}:
3844 The return value has same type and kind as @var{I}.
3846 @item @emph{See also}:
3854 @section @code{DTIME} --- Execution time subroutine (or function)
3856 @cindex time, elapsed
3857 @cindex elapsed time
3860 @item @emph{Description}:
3861 @code{DTIME(VALUES, TIME)} initially returns the number of seconds of runtime
3862 since the start of the process's execution in @var{TIME}. @var{VALUES}
3863 returns the user and system components of this time in @code{VALUES(1)} and
3864 @code{VALUES(2)} respectively. @var{TIME} is equal to @code{VALUES(1) +
3867 Subsequent invocations of @code{DTIME} return values accumulated since the
3868 previous invocation.
3870 On some systems, the underlying timings are represented using types with
3871 sufficiently small limits that overflows (wrap around) are possible, such as
3872 32-bit types. Therefore, the values returned by this intrinsic might be, or
3873 become, negative, or numerically less than previous values, during a single
3874 run of the compiled program.
3876 Please note, that this implementation is thread safe if used within OpenMP
3877 directives, i.e., its state will be consistent while called from multiple
3878 threads. However, if @code{DTIME} is called from multiple threads, the result
3879 is still the time since the last invocation. This may not give the intended
3880 results. If possible, use @code{CPU_TIME} instead.
3882 This intrinsic is provided in both subroutine and function forms; however,
3883 only one form can be used in any given program unit.
3885 @var{VALUES} and @var{TIME} are @code{INTENT(OUT)} and provide the following:
3887 @multitable @columnfractions .15 .30 .40
3888 @item @tab @code{VALUES(1)}: @tab User time in seconds.
3889 @item @tab @code{VALUES(2)}: @tab System time in seconds.
3890 @item @tab @code{TIME}: @tab Run time since start in seconds.
3893 @item @emph{Standard}:
3897 Subroutine, function
3899 @item @emph{Syntax}:
3900 @multitable @columnfractions .80
3901 @item @code{CALL DTIME(VALUES, TIME)}.
3902 @item @code{TIME = DTIME(VALUES)}, (not recommended).
3905 @item @emph{Arguments}:
3906 @multitable @columnfractions .15 .70
3907 @item @var{VALUES}@tab The type shall be @code{REAL(4), DIMENSION(2)}.
3908 @item @var{TIME}@tab The type shall be @code{REAL(4)}.
3911 @item @emph{Return value}:
3912 Elapsed time in seconds since the last invocation or since the start of program
3913 execution if not called before.
3915 @item @emph{Example}:
3919 real, dimension(2) :: tarray
3921 call dtime(tarray, result)
3925 do i=1,100000000 ! Just a delay
3928 call dtime(tarray, result)
3932 end program test_dtime
3935 @item @emph{See also}:
3943 @section @code{EOSHIFT} --- End-off shift elements of an array
3945 @cindex array, shift
3948 @item @emph{Description}:
3949 @code{EOSHIFT(ARRAY, SHIFT[, BOUNDARY, DIM])} performs an end-off shift on
3950 elements of @var{ARRAY} along the dimension of @var{DIM}. If @var{DIM} is
3951 omitted it is taken to be @code{1}. @var{DIM} is a scalar of type
3952 @code{INTEGER} in the range of @math{1 \leq DIM \leq n)} where @math{n} is the
3953 rank of @var{ARRAY}. If the rank of @var{ARRAY} is one, then all elements of
3954 @var{ARRAY} are shifted by @var{SHIFT} places. If rank is greater than one,
3955 then all complete rank one sections of @var{ARRAY} along the given dimension are
3956 shifted. Elements shifted out one end of each rank one section are dropped. If
3957 @var{BOUNDARY} is present then the corresponding value of from @var{BOUNDARY}
3958 is copied back in the other end. If @var{BOUNDARY} is not present then the
3959 following are copied in depending on the type of @var{ARRAY}.
3961 @multitable @columnfractions .15 .80
3962 @item @emph{Array Type} @tab @emph{Boundary Value}
3963 @item Numeric @tab 0 of the type and kind of @var{ARRAY}.
3964 @item Logical @tab @code{.FALSE.}.
3965 @item Character(@var{len}) @tab @var{len} blanks.
3968 @item @emph{Standard}:
3969 Fortran 95 and later
3972 Transformational function
3974 @item @emph{Syntax}:
3975 @code{RESULT = EOSHIFT(ARRAY, SHIFT [, BOUNDARY, DIM])}
3977 @item @emph{Arguments}:
3978 @multitable @columnfractions .15 .70
3979 @item @var{ARRAY} @tab May be any type, not scalar.
3980 @item @var{SHIFT} @tab The type shall be @code{INTEGER}.
3981 @item @var{BOUNDARY} @tab Same type as @var{ARRAY}.
3982 @item @var{DIM} @tab The type shall be @code{INTEGER}.
3985 @item @emph{Return value}:
3986 Returns an array of same type and rank as the @var{ARRAY} argument.
3988 @item @emph{Example}:
3990 program test_eoshift
3991 integer, dimension(3,3) :: a
3992 a = reshape( (/ 1, 2, 3, 4, 5, 6, 7, 8, 9 /), (/ 3, 3 /))
3993 print '(3i3)', a(1,:)
3994 print '(3i3)', a(2,:)
3995 print '(3i3)', a(3,:)
3996 a = EOSHIFT(a, SHIFT=(/1, 2, 1/), BOUNDARY=-5, DIM=2)
3998 print '(3i3)', a(1,:)
3999 print '(3i3)', a(2,:)
4000 print '(3i3)', a(3,:)
4001 end program test_eoshift
4008 @section @code{EPSILON} --- Epsilon function
4010 @cindex model representation, epsilon
4013 @item @emph{Description}:
4014 @code{EPSILON(X)} returns the smallest number @var{E} of the same kind
4015 as @var{X} such that @math{1 + E > 1}.
4017 @item @emph{Standard}:
4018 Fortran 95 and later
4023 @item @emph{Syntax}:
4024 @code{RESULT = EPSILON(X)}
4026 @item @emph{Arguments}:
4027 @multitable @columnfractions .15 .70
4028 @item @var{X} @tab The type shall be @code{REAL}.
4031 @item @emph{Return value}:
4032 The return value is of same type as the argument.
4034 @item @emph{Example}:
4036 program test_epsilon
4041 end program test_epsilon
4048 @section @code{ERF} --- Error function
4050 @cindex error function
4053 @item @emph{Description}:
4054 @code{ERF(X)} computes the error function of @var{X}.
4056 @item @emph{Standard}:
4057 Fortran 2008 and later
4062 @item @emph{Syntax}:
4063 @code{RESULT = ERF(X)}
4065 @item @emph{Arguments}:
4066 @multitable @columnfractions .15 .70
4067 @item @var{X} @tab The type shall be @code{REAL}.
4070 @item @emph{Return value}:
4071 The return value is of type @code{REAL}, of the same kind as
4072 @var{X} and lies in the range @math{-1 \leq erf (x) \leq 1 }.
4074 @item @emph{Example}:
4077 real(8) :: x = 0.17_8
4079 end program test_erf
4082 @item @emph{Specific names}:
4083 @multitable @columnfractions .20 .20 .20 .25
4084 @item Name @tab Argument @tab Return type @tab Standard
4085 @item @code{DERF(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU extension
4092 @section @code{ERFC} --- Error function
4094 @cindex error function, complementary
4097 @item @emph{Description}:
4098 @code{ERFC(X)} computes the complementary error function of @var{X}.
4100 @item @emph{Standard}:
4101 Fortran 2008 and later
4106 @item @emph{Syntax}:
4107 @code{RESULT = ERFC(X)}
4109 @item @emph{Arguments}:
4110 @multitable @columnfractions .15 .70
4111 @item @var{X} @tab The type shall be @code{REAL}.
4114 @item @emph{Return value}:
4115 The return value is of type @code{REAL} and of the same kind as @var{X}.
4116 It lies in the range @math{ 0 \leq erfc (x) \leq 2 }.
4118 @item @emph{Example}:
4121 real(8) :: x = 0.17_8
4123 end program test_erfc
4126 @item @emph{Specific names}:
4127 @multitable @columnfractions .20 .20 .20 .25
4128 @item Name @tab Argument @tab Return type @tab Standard
4129 @item @code{DERFC(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU extension
4136 @section @code{ERFC_SCALED} --- Error function
4137 @fnindex ERFC_SCALED
4138 @cindex error function, complementary, exponentially-scaled
4141 @item @emph{Description}:
4142 @code{ERFC_SCALED(X)} computes the exponentially-scaled complementary
4143 error function of @var{X}.
4145 @item @emph{Standard}:
4146 Fortran 2008 and later
4151 @item @emph{Syntax}:
4152 @code{RESULT = ERFC_SCALED(X)}
4154 @item @emph{Arguments}:
4155 @multitable @columnfractions .15 .70
4156 @item @var{X} @tab The type shall be @code{REAL}.
4159 @item @emph{Return value}:
4160 The return value is of type @code{REAL} and of the same kind as @var{X}.
4162 @item @emph{Example}:
4164 program test_erfc_scaled
4165 real(8) :: x = 0.17_8
4167 end program test_erfc_scaled
4174 @section @code{ETIME} --- Execution time subroutine (or function)
4176 @cindex time, elapsed
4179 @item @emph{Description}:
4180 @code{ETIME(VALUES, TIME)} returns the number of seconds of runtime
4181 since the start of the process's execution in @var{TIME}. @var{VALUES}
4182 returns the user and system components of this time in @code{VALUES(1)} and
4183 @code{VALUES(2)} respectively. @var{TIME} is equal to @code{VALUES(1) + VALUES(2)}.
4185 On some systems, the underlying timings are represented using types with
4186 sufficiently small limits that overflows (wrap around) are possible, such as
4187 32-bit types. Therefore, the values returned by this intrinsic might be, or
4188 become, negative, or numerically less than previous values, during a single
4189 run of the compiled program.
4191 This intrinsic is provided in both subroutine and function forms; however,
4192 only one form can be used in any given program unit.
4194 @var{VALUES} and @var{TIME} are @code{INTENT(OUT)} and provide the following:
4196 @multitable @columnfractions .15 .30 .60
4197 @item @tab @code{VALUES(1)}: @tab User time in seconds.
4198 @item @tab @code{VALUES(2)}: @tab System time in seconds.
4199 @item @tab @code{TIME}: @tab Run time since start in seconds.
4202 @item @emph{Standard}:
4206 Subroutine, function
4208 @item @emph{Syntax}:
4209 @multitable @columnfractions .80
4210 @item @code{CALL ETIME(VALUES, TIME)}.
4211 @item @code{TIME = ETIME(VALUES)}, (not recommended).
4214 @item @emph{Arguments}:
4215 @multitable @columnfractions .15 .70
4216 @item @var{VALUES}@tab The type shall be @code{REAL(4), DIMENSION(2)}.
4217 @item @var{TIME}@tab The type shall be @code{REAL(4)}.
4220 @item @emph{Return value}:
4221 Elapsed time in seconds since the start of program execution.
4223 @item @emph{Example}:
4227 real, dimension(2) :: tarray
4229 call ETIME(tarray, result)
4233 do i=1,100000000 ! Just a delay
4236 call ETIME(tarray, result)
4240 end program test_etime
4243 @item @emph{See also}:
4250 @node EXECUTE_COMMAND_LINE
4251 @section @code{EXECUTE_COMMAND_LINE} --- Execute a shell command
4252 @fnindex EXECUTE_COMMAND_LINE
4253 @cindex system, system call
4254 @cindex command line
4257 @item @emph{Description}:
4258 @code{EXECUTE_COMMAND_LINE} runs a shell command, synchronously or
4261 The @code{COMMAND} argument is passed to the shell and executed, using
4262 the C library's @code{system} call. (The shell is @code{sh} on Unix
4263 systems, and @code{cmd.exe} on Windows.) If @code{WAIT} is present
4264 and has the value false, the execution of the command is asynchronous
4265 if the system supports it; otherwise, the command is executed
4268 The three last arguments allow the user to get status information. After
4269 synchronous execution, @code{EXITSTAT} contains the integer exit code of
4270 the command, as returned by @code{system}. @code{CMDSTAT} is set to zero
4271 if the command line was executed (whatever its exit status was).
4272 @code{CMDMSG} is assigned an error message if an error has occurred.
4274 Note that the @code{system} function need not be thread-safe. It is
4275 the responsibility of the user to ensure that @code{system} is not
4276 called concurrently.
4278 @item @emph{Standard}:
4279 Fortran 2008 and later
4284 @item @emph{Syntax}:
4285 @code{CALL EXECUTE_COMMAND_LINE(COMMAND [, WAIT, EXITSTAT, CMDSTAT, CMDMSG ])}
4287 @item @emph{Arguments}:
4288 @multitable @columnfractions .15 .70
4289 @item @var{COMMAND} @tab Shall be a default @code{CHARACTER} scalar.
4290 @item @var{WAIT} @tab (Optional) Shall be a default @code{LOGICAL} scalar.
4291 @item @var{EXITSTAT} @tab (Optional) Shall be an @code{INTEGER} of the
4293 @item @var{CMDSTAT} @tab (Optional) Shall be an @code{INTEGER} of the
4295 @item @var{CMDMSG} @tab (Optional) Shall be an @code{CHARACTER} scalar of the
4299 @item @emph{Example}:
4304 call execute_command_line ("external_prog.exe", exitstat=i)
4305 print *, "Exit status of external_prog.exe was ", i
4307 call execute_command_line ("reindex_files.exe", wait=.false.)
4308 print *, "Now reindexing files in the background"
4310 end program test_exec
4316 Because this intrinsic is implemented in terms of the @code{system}
4317 function call, its behavior with respect to signaling is processor
4318 dependent. In particular, on POSIX-compliant systems, the SIGINT and
4319 SIGQUIT signals will be ignored, and the SIGCHLD will be blocked. As
4320 such, if the parent process is terminated, the child process might not be
4321 terminated alongside.
4324 @item @emph{See also}:
4331 @section @code{EXIT} --- Exit the program with status.
4333 @cindex program termination
4334 @cindex terminate program
4337 @item @emph{Description}:
4338 @code{EXIT} causes immediate termination of the program with status. If status
4339 is omitted it returns the canonical @emph{success} for the system. All Fortran
4340 I/O units are closed.
4342 @item @emph{Standard}:
4348 @item @emph{Syntax}:
4349 @code{CALL EXIT([STATUS])}
4351 @item @emph{Arguments}:
4352 @multitable @columnfractions .15 .70
4353 @item @var{STATUS} @tab Shall be an @code{INTEGER} of the default kind.
4356 @item @emph{Return value}:
4357 @code{STATUS} is passed to the parent process on exit.
4359 @item @emph{Example}:
4362 integer :: STATUS = 0
4363 print *, 'This program is going to exit.'
4365 end program test_exit
4368 @item @emph{See also}:
4369 @ref{ABORT}, @ref{KILL}
4375 @section @code{EXP} --- Exponential function
4381 @cindex exponential function
4382 @cindex logarithm function, inverse
4385 @item @emph{Description}:
4386 @code{EXP(X)} computes the base @math{e} exponential of @var{X}.
4388 @item @emph{Standard}:
4389 Fortran 77 and later, has overloads that are GNU extensions
4394 @item @emph{Syntax}:
4395 @code{RESULT = EXP(X)}
4397 @item @emph{Arguments}:
4398 @multitable @columnfractions .15 .70
4399 @item @var{X} @tab The type shall be @code{REAL} or
4403 @item @emph{Return value}:
4404 The return value has same type and kind as @var{X}.
4406 @item @emph{Example}:
4411 end program test_exp
4414 @item @emph{Specific names}:
4415 @multitable @columnfractions .20 .20 .20 .25
4416 @item Name @tab Argument @tab Return type @tab Standard
4417 @item @code{EXP(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab Fortran 77 and later
4418 @item @code{DEXP(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab Fortran 77 and later
4419 @item @code{CEXP(X)} @tab @code{COMPLEX(4) X} @tab @code{COMPLEX(4)} @tab Fortran 77 and later
4420 @item @code{ZEXP(X)} @tab @code{COMPLEX(8) X} @tab @code{COMPLEX(8)} @tab GNU extension
4421 @item @code{CDEXP(X)} @tab @code{COMPLEX(8) X} @tab @code{COMPLEX(8)} @tab GNU extension
4428 @section @code{EXPONENT} --- Exponent function
4430 @cindex real number, exponent
4431 @cindex floating point, exponent
4434 @item @emph{Description}:
4435 @code{EXPONENT(X)} returns the value of the exponent part of @var{X}. If @var{X}
4436 is zero the value returned is zero.
4438 @item @emph{Standard}:
4439 Fortran 95 and later
4444 @item @emph{Syntax}:
4445 @code{RESULT = EXPONENT(X)}
4447 @item @emph{Arguments}:
4448 @multitable @columnfractions .15 .70
4449 @item @var{X} @tab The type shall be @code{REAL}.
4452 @item @emph{Return value}:
4453 The return value is of type default @code{INTEGER}.
4455 @item @emph{Example}:
4457 program test_exponent
4462 print *, exponent(0.0)
4463 end program test_exponent
4469 @node EXTENDS_TYPE_OF
4470 @section @code{EXTENDS_TYPE_OF} --- Query dynamic type for extension
4471 @fnindex EXTENDS_TYPE_OF
4474 @item @emph{Description}:
4475 Query dynamic type for extension.
4477 @item @emph{Standard}:
4478 Fortran 2003 and later
4483 @item @emph{Syntax}:
4484 @code{RESULT = EXTENDS_TYPE_OF(A, MOLD)}
4486 @item @emph{Arguments}:
4487 @multitable @columnfractions .15 .70
4488 @item @var{A} @tab Shall be an object of extensible declared type or
4489 unlimited polymorphic.
4490 @item @var{MOLD} @tab Shall be an object of extensible declared type or
4491 unlimited polymorphic.
4494 @item @emph{Return value}:
4495 The return value is a scalar of type default logical. It is true if and only if
4496 the dynamic type of A is an extension type of the dynamic type of MOLD.
4499 @item @emph{See also}:
4506 @section @code{FDATE} --- Get the current time as a string
4508 @cindex time, current
4509 @cindex current time
4510 @cindex date, current
4511 @cindex current date
4514 @item @emph{Description}:
4515 @code{FDATE(DATE)} returns the current date (using the same format as
4516 @code{CTIME}) in @var{DATE}. It is equivalent to @code{CALL CTIME(DATE,
4519 This intrinsic is provided in both subroutine and function forms; however,
4520 only one form can be used in any given program unit.
4522 @item @emph{Standard}:
4526 Subroutine, function
4528 @item @emph{Syntax}:
4529 @multitable @columnfractions .80
4530 @item @code{CALL FDATE(DATE)}.
4531 @item @code{DATE = FDATE()}.
4534 @item @emph{Arguments}:
4535 @multitable @columnfractions .15 .70
4536 @item @var{DATE}@tab The type shall be of type @code{CHARACTER} of the
4537 default kind. It is an @code{INTENT(OUT)} argument. If the length of
4538 this variable is too short for the date and time string to fit
4539 completely, it will be blank on procedure return.
4542 @item @emph{Return value}:
4543 The current date and time as a string.
4545 @item @emph{Example}:
4549 character(len=30) :: date
4551 print *, 'Program started on ', date
4552 do i = 1, 100000000 ! Just a delay
4556 print *, 'Program ended on ', date
4557 end program test_fdate
4560 @item @emph{See also}:
4561 @ref{DATE_AND_TIME}, @ref{CTIME}
4566 @section @code{FGET} --- Read a single character in stream mode from stdin
4568 @cindex read character, stream mode
4569 @cindex stream mode, read character
4570 @cindex file operation, read character
4573 @item @emph{Description}:
4574 Read a single character in stream mode from stdin by bypassing normal
4575 formatted output. Stream I/O should not be mixed with normal record-oriented
4576 (formatted or unformatted) I/O on the same unit; the results are unpredictable.
4578 This intrinsic is provided in both subroutine and function forms; however,
4579 only one form can be used in any given program unit.
4581 Note that the @code{FGET} intrinsic is provided for backwards compatibility with
4582 @command{g77}. GNU Fortran provides the Fortran 2003 Stream facility.
4583 Programmers should consider the use of new stream IO feature in new code
4584 for future portability. See also @ref{Fortran 2003 status}.
4586 @item @emph{Standard}:
4590 Subroutine, function
4592 @item @emph{Syntax}:
4593 @multitable @columnfractions .80
4594 @item @code{CALL FGET(C [, STATUS])}
4595 @item @code{STATUS = FGET(C)}
4598 @item @emph{Arguments}:
4599 @multitable @columnfractions .15 .70
4600 @item @var{C} @tab The type shall be @code{CHARACTER} and of default
4602 @item @var{STATUS} @tab (Optional) status flag of type @code{INTEGER}.
4603 Returns 0 on success, -1 on end-of-file, and a system specific positive
4604 error code otherwise.
4607 @item @emph{Example}:
4610 INTEGER, PARAMETER :: strlen = 100
4611 INTEGER :: status, i = 1
4612 CHARACTER(len=strlen) :: str = ""
4614 WRITE (*,*) 'Enter text:'
4616 CALL fget(str(i:i), status)
4617 if (status /= 0 .OR. i > strlen) exit
4620 WRITE (*,*) TRIM(str)
4624 @item @emph{See also}:
4625 @ref{FGETC}, @ref{FPUT}, @ref{FPUTC}
4631 @section @code{FGETC} --- Read a single character in stream mode
4633 @cindex read character, stream mode
4634 @cindex stream mode, read character
4635 @cindex file operation, read character
4638 @item @emph{Description}:
4639 Read a single character in stream mode by bypassing normal formatted output.
4640 Stream I/O should not be mixed with normal record-oriented (formatted or
4641 unformatted) I/O on the same unit; the results are unpredictable.
4643 This intrinsic is provided in both subroutine and function forms; however,
4644 only one form can be used in any given program unit.
4646 Note that the @code{FGET} intrinsic is provided for backwards compatibility
4647 with @command{g77}. GNU Fortran provides the Fortran 2003 Stream facility.
4648 Programmers should consider the use of new stream IO feature in new code
4649 for future portability. See also @ref{Fortran 2003 status}.
4651 @item @emph{Standard}:
4655 Subroutine, function
4657 @item @emph{Syntax}:
4658 @multitable @columnfractions .80
4659 @item @code{CALL FGETC(UNIT, C [, STATUS])}
4660 @item @code{STATUS = FGETC(UNIT, C)}
4663 @item @emph{Arguments}:
4664 @multitable @columnfractions .15 .70
4665 @item @var{UNIT} @tab The type shall be @code{INTEGER}.
4666 @item @var{C} @tab The type shall be @code{CHARACTER} and of default
4668 @item @var{STATUS} @tab (Optional) status flag of type @code{INTEGER}.
4669 Returns 0 on success, -1 on end-of-file and a system specific positive
4670 error code otherwise.
4673 @item @emph{Example}:
4676 INTEGER :: fd = 42, status
4679 OPEN(UNIT=fd, FILE="/etc/passwd", ACTION="READ", STATUS = "OLD")
4681 CALL fgetc(fd, c, status)
4682 IF (status /= 0) EXIT
4689 @item @emph{See also}:
4690 @ref{FGET}, @ref{FPUT}, @ref{FPUTC}
4696 @section @code{FLOOR} --- Integer floor function
4699 @cindex rounding, floor
4702 @item @emph{Description}:
4703 @code{FLOOR(A)} returns the greatest integer less than or equal to @var{X}.
4705 @item @emph{Standard}:
4706 Fortran 95 and later
4711 @item @emph{Syntax}:
4712 @code{RESULT = FLOOR(A [, KIND])}
4714 @item @emph{Arguments}:
4715 @multitable @columnfractions .15 .70
4716 @item @var{A} @tab The type shall be @code{REAL}.
4717 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
4718 expression indicating the kind parameter of the result.
4721 @item @emph{Return value}:
4722 The return value is of type @code{INTEGER(KIND)} if @var{KIND} is present
4723 and of default-kind @code{INTEGER} otherwise.
4725 @item @emph{Example}:
4730 print *, floor(x) ! returns 63
4731 print *, floor(y) ! returns -64
4732 end program test_floor
4735 @item @emph{See also}:
4736 @ref{CEILING}, @ref{NINT}
4743 @section @code{FLUSH} --- Flush I/O unit(s)
4745 @cindex file operation, flush
4748 @item @emph{Description}:
4749 Flushes Fortran unit(s) currently open for output. Without the optional
4750 argument, all units are flushed, otherwise just the unit specified.
4752 @item @emph{Standard}:
4758 @item @emph{Syntax}:
4759 @code{CALL FLUSH(UNIT)}
4761 @item @emph{Arguments}:
4762 @multitable @columnfractions .15 .70
4763 @item @var{UNIT} @tab (Optional) The type shall be @code{INTEGER}.
4767 Beginning with the Fortran 2003 standard, there is a @code{FLUSH}
4768 statement that should be preferred over the @code{FLUSH} intrinsic.
4770 The @code{FLUSH} intrinsic and the Fortran 2003 @code{FLUSH} statement
4771 have identical effect: they flush the runtime library's I/O buffer so
4772 that the data becomes visible to other processes. This does not guarantee
4773 that the data is committed to disk.
4775 On POSIX systems, you can request that all data is transferred to the
4776 storage device by calling the @code{fsync} function, with the POSIX file
4777 descriptor of the I/O unit as argument (retrieved with GNU intrinsic
4778 @code{FNUM}). The following example shows how:
4781 ! Declare the interface for POSIX fsync function
4783 function fsync (fd) bind(c,name="fsync")
4784 use iso_c_binding, only: c_int
4785 integer(c_int), value :: fd
4786 integer(c_int) :: fsync
4790 ! Variable declaration
4794 open (10,file="foo")
4797 ! Perform I/O on unit 10
4802 ret = fsync(fnum(10))
4804 ! Handle possible error
4805 if (ret /= 0) stop "Error calling FSYNC"
4813 @section @code{FNUM} --- File number function
4815 @cindex file operation, file number
4818 @item @emph{Description}:
4819 @code{FNUM(UNIT)} returns the POSIX file descriptor number corresponding to the
4820 open Fortran I/O unit @code{UNIT}.
4822 @item @emph{Standard}:
4828 @item @emph{Syntax}:
4829 @code{RESULT = FNUM(UNIT)}
4831 @item @emph{Arguments}:
4832 @multitable @columnfractions .15 .70
4833 @item @var{UNIT} @tab The type shall be @code{INTEGER}.
4836 @item @emph{Return value}:
4837 The return value is of type @code{INTEGER}
4839 @item @emph{Example}:
4843 open (unit=10, status = "scratch")
4847 end program test_fnum
4854 @section @code{FPUT} --- Write a single character in stream mode to stdout
4856 @cindex write character, stream mode
4857 @cindex stream mode, write character
4858 @cindex file operation, write character
4861 @item @emph{Description}:
4862 Write a single character in stream mode to stdout by bypassing normal
4863 formatted output. Stream I/O should not be mixed with normal record-oriented
4864 (formatted or unformatted) I/O on the same unit; the results are unpredictable.
4866 This intrinsic is provided in both subroutine and function forms; however,
4867 only one form can be used in any given program unit.
4869 Note that the @code{FGET} intrinsic is provided for backwards compatibility with
4870 @command{g77}. GNU Fortran provides the Fortran 2003 Stream facility.
4871 Programmers should consider the use of new stream IO feature in new code
4872 for future portability. See also @ref{Fortran 2003 status}.
4874 @item @emph{Standard}:
4878 Subroutine, function
4880 @item @emph{Syntax}:
4881 @multitable @columnfractions .80
4882 @item @code{CALL FPUT(C [, STATUS])}
4883 @item @code{STATUS = FPUT(C)}
4886 @item @emph{Arguments}:
4887 @multitable @columnfractions .15 .70
4888 @item @var{C} @tab The type shall be @code{CHARACTER} and of default
4890 @item @var{STATUS} @tab (Optional) status flag of type @code{INTEGER}.
4891 Returns 0 on success, -1 on end-of-file and a system specific positive
4892 error code otherwise.
4895 @item @emph{Example}:
4898 CHARACTER(len=10) :: str = "gfortran"
4900 DO i = 1, len_trim(str)
4906 @item @emph{See also}:
4907 @ref{FPUTC}, @ref{FGET}, @ref{FGETC}
4913 @section @code{FPUTC} --- Write a single character in stream mode
4915 @cindex write character, stream mode
4916 @cindex stream mode, write character
4917 @cindex file operation, write character
4920 @item @emph{Description}:
4921 Write a single character in stream mode by bypassing normal formatted
4922 output. Stream I/O should not be mixed with normal record-oriented
4923 (formatted or unformatted) I/O on the same unit; the results are unpredictable.
4925 This intrinsic is provided in both subroutine and function forms; however,
4926 only one form can be used in any given program unit.
4928 Note that the @code{FGET} intrinsic is provided for backwards compatibility with
4929 @command{g77}. GNU Fortran provides the Fortran 2003 Stream facility.
4930 Programmers should consider the use of new stream IO feature in new code
4931 for future portability. See also @ref{Fortran 2003 status}.
4933 @item @emph{Standard}:
4937 Subroutine, function
4939 @item @emph{Syntax}:
4940 @multitable @columnfractions .80
4941 @item @code{CALL FPUTC(UNIT, C [, STATUS])}
4942 @item @code{STATUS = FPUTC(UNIT, C)}
4945 @item @emph{Arguments}:
4946 @multitable @columnfractions .15 .70
4947 @item @var{UNIT} @tab The type shall be @code{INTEGER}.
4948 @item @var{C} @tab The type shall be @code{CHARACTER} and of default
4950 @item @var{STATUS} @tab (Optional) status flag of type @code{INTEGER}.
4951 Returns 0 on success, -1 on end-of-file and a system specific positive
4952 error code otherwise.
4955 @item @emph{Example}:
4958 CHARACTER(len=10) :: str = "gfortran"
4959 INTEGER :: fd = 42, i
4961 OPEN(UNIT = fd, FILE = "out", ACTION = "WRITE", STATUS="NEW")
4962 DO i = 1, len_trim(str)
4963 CALL fputc(fd, str(i:i))
4969 @item @emph{See also}:
4970 @ref{FPUT}, @ref{FGET}, @ref{FGETC}
4976 @section @code{FRACTION} --- Fractional part of the model representation
4978 @cindex real number, fraction
4979 @cindex floating point, fraction
4982 @item @emph{Description}:
4983 @code{FRACTION(X)} returns the fractional part of the model
4984 representation of @code{X}.
4986 @item @emph{Standard}:
4987 Fortran 95 and later
4992 @item @emph{Syntax}:
4993 @code{Y = FRACTION(X)}
4995 @item @emph{Arguments}:
4996 @multitable @columnfractions .15 .70
4997 @item @var{X} @tab The type of the argument shall be a @code{REAL}.
5000 @item @emph{Return value}:
5001 The return value is of the same type and kind as the argument.
5002 The fractional part of the model representation of @code{X} is returned;
5003 it is @code{X * RADIX(X)**(-EXPONENT(X))}.
5005 @item @emph{Example}:
5007 program test_fraction
5010 print *, fraction(x), x * radix(x)**(-exponent(x))
5011 end program test_fraction
5019 @section @code{FREE} --- Frees memory
5021 @cindex pointer, cray
5024 @item @emph{Description}:
5025 Frees memory previously allocated by @code{MALLOC}. The @code{FREE}
5026 intrinsic is an extension intended to be used with Cray pointers, and is
5027 provided in GNU Fortran to allow user to compile legacy code. For
5028 new code using Fortran 95 pointers, the memory de-allocation intrinsic is
5031 @item @emph{Standard}:
5037 @item @emph{Syntax}:
5038 @code{CALL FREE(PTR)}
5040 @item @emph{Arguments}:
5041 @multitable @columnfractions .15 .70
5042 @item @var{PTR} @tab The type shall be @code{INTEGER}. It represents the
5043 location of the memory that should be de-allocated.
5046 @item @emph{Return value}:
5049 @item @emph{Example}:
5050 See @code{MALLOC} for an example.
5052 @item @emph{See also}:
5059 @section @code{FSEEK} --- Low level file positioning subroutine
5061 @cindex file operation, seek
5062 @cindex file operation, position
5065 @item @emph{Description}:
5066 Moves @var{UNIT} to the specified @var{OFFSET}. If @var{WHENCE}
5067 is set to 0, the @var{OFFSET} is taken as an absolute value @code{SEEK_SET},
5068 if set to 1, @var{OFFSET} is taken to be relative to the current position
5069 @code{SEEK_CUR}, and if set to 2 relative to the end of the file @code{SEEK_END}.
5070 On error, @var{STATUS} is set to a nonzero value. If @var{STATUS} the seek
5073 This intrinsic routine is not fully backwards compatible with @command{g77}.
5074 In @command{g77}, the @code{FSEEK} takes a statement label instead of a
5075 @var{STATUS} variable. If FSEEK is used in old code, change
5077 CALL FSEEK(UNIT, OFFSET, WHENCE, *label)
5082 CALL FSEEK(UNIT, OFFSET, WHENCE, status)
5083 IF (status /= 0) GOTO label
5086 Please note that GNU Fortran provides the Fortran 2003 Stream facility.
5087 Programmers should consider the use of new stream IO feature in new code
5088 for future portability. See also @ref{Fortran 2003 status}.
5090 @item @emph{Standard}:
5096 @item @emph{Syntax}:
5097 @code{CALL FSEEK(UNIT, OFFSET, WHENCE[, STATUS])}
5099 @item @emph{Arguments}:
5100 @multitable @columnfractions .15 .70
5101 @item @var{UNIT} @tab Shall be a scalar of type @code{INTEGER}.
5102 @item @var{OFFSET} @tab Shall be a scalar of type @code{INTEGER}.
5103 @item @var{WHENCE} @tab Shall be a scalar of type @code{INTEGER}.
5104 Its value shall be either 0, 1 or 2.
5105 @item @var{STATUS} @tab (Optional) shall be a scalar of type
5109 @item @emph{Example}:
5112 INTEGER, PARAMETER :: SEEK_SET = 0, SEEK_CUR = 1, SEEK_END = 2
5113 INTEGER :: fd, offset, ierr
5119 OPEN(UNIT=fd, FILE="fseek.test")
5120 CALL FSEEK(fd, offset, SEEK_SET, ierr) ! move to OFFSET
5121 print *, FTELL(fd), ierr
5123 CALL FSEEK(fd, 0, SEEK_END, ierr) ! move to end
5124 print *, FTELL(fd), ierr
5126 CALL FSEEK(fd, 0, SEEK_SET, ierr) ! move to beginning
5127 print *, FTELL(fd), ierr
5133 @item @emph{See also}:
5140 @section @code{FSTAT} --- Get file status
5142 @cindex file system, file status
5145 @item @emph{Description}:
5146 @code{FSTAT} is identical to @ref{STAT}, except that information about an
5147 already opened file is obtained.
5149 The elements in @code{VALUES} are the same as described by @ref{STAT}.
5151 This intrinsic is provided in both subroutine and function forms; however,
5152 only one form can be used in any given program unit.
5154 @item @emph{Standard}:
5158 Subroutine, function
5160 @item @emph{Syntax}:
5161 @multitable @columnfractions .80
5162 @item @code{CALL FSTAT(UNIT, VALUES [, STATUS])}
5163 @item @code{STATUS = FSTAT(UNIT, VALUES)}
5166 @item @emph{Arguments}:
5167 @multitable @columnfractions .15 .70
5168 @item @var{UNIT} @tab An open I/O unit number of type @code{INTEGER}.
5169 @item @var{VALUES} @tab The type shall be @code{INTEGER(4), DIMENSION(13)}.
5170 @item @var{STATUS} @tab (Optional) status flag of type @code{INTEGER(4)}. Returns 0
5171 on success and a system specific error code otherwise.
5174 @item @emph{Example}:
5175 See @ref{STAT} for an example.
5177 @item @emph{See also}:
5178 To stat a link: @ref{LSTAT}, to stat a file: @ref{STAT}
5184 @section @code{FTELL} --- Current stream position
5186 @cindex file operation, position
5189 @item @emph{Description}:
5190 Retrieves the current position within an open file.
5192 This intrinsic is provided in both subroutine and function forms; however,
5193 only one form can be used in any given program unit.
5195 @item @emph{Standard}:
5199 Subroutine, function
5201 @item @emph{Syntax}:
5202 @multitable @columnfractions .80
5203 @item @code{CALL FTELL(UNIT, OFFSET)}
5204 @item @code{OFFSET = FTELL(UNIT)}
5207 @item @emph{Arguments}:
5208 @multitable @columnfractions .15 .70
5209 @item @var{OFFSET} @tab Shall of type @code{INTEGER}.
5210 @item @var{UNIT} @tab Shall of type @code{INTEGER}.
5213 @item @emph{Return value}:
5214 In either syntax, @var{OFFSET} is set to the current offset of unit
5215 number @var{UNIT}, or to @math{-1} if the unit is not currently open.
5217 @item @emph{Example}:
5221 OPEN(10, FILE="temp.dat")
5227 @item @emph{See also}:
5234 @section @code{GAMMA} --- Gamma function
5237 @cindex Gamma function
5238 @cindex Factorial function
5241 @item @emph{Description}:
5242 @code{GAMMA(X)} computes Gamma (@math{\Gamma}) of @var{X}. For positive,
5243 integer values of @var{X} the Gamma function simplifies to the factorial
5244 function @math{\Gamma(x)=(x-1)!}.
5248 \Gamma(x) = \int_0^\infty t^{x-1}{\rm e}^{-t}\,{\rm d}t
5252 @item @emph{Standard}:
5253 Fortran 2008 and later
5258 @item @emph{Syntax}:
5261 @item @emph{Arguments}:
5262 @multitable @columnfractions .15 .70
5263 @item @var{X} @tab Shall be of type @code{REAL} and neither zero
5264 nor a negative integer.
5267 @item @emph{Return value}:
5268 The return value is of type @code{REAL} of the same kind as @var{X}.
5270 @item @emph{Example}:
5274 x = gamma(x) ! returns 1.0
5275 end program test_gamma
5278 @item @emph{Specific names}:
5279 @multitable @columnfractions .20 .20 .20 .25
5280 @item Name @tab Argument @tab Return type @tab Standard
5281 @item @code{GAMMA(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab GNU Extension
5282 @item @code{DGAMMA(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU Extension
5285 @item @emph{See also}:
5286 Logarithm of the Gamma function: @ref{LOG_GAMMA}
5293 @section @code{GERROR} --- Get last system error message
5295 @cindex system, error handling
5298 @item @emph{Description}:
5299 Returns the system error message corresponding to the last system error.
5300 This resembles the functionality of @code{strerror(3)} in C.
5302 @item @emph{Standard}:
5308 @item @emph{Syntax}:
5309 @code{CALL GERROR(RESULT)}
5311 @item @emph{Arguments}:
5312 @multitable @columnfractions .15 .70
5313 @item @var{RESULT} @tab Shall of type @code{CHARACTER} and of default
5316 @item @emph{Example}:
5319 CHARACTER(len=100) :: msg
5325 @item @emph{See also}:
5326 @ref{IERRNO}, @ref{PERROR}
5332 @section @code{GETARG} --- Get command line arguments
5334 @cindex command-line arguments
5335 @cindex arguments, to program
5338 @item @emph{Description}:
5339 Retrieve the @var{POS}-th argument that was passed on the
5340 command line when the containing program was invoked.
5342 This intrinsic routine is provided for backwards compatibility with
5343 GNU Fortran 77. In new code, programmers should consider the use of
5344 the @ref{GET_COMMAND_ARGUMENT} intrinsic defined by the Fortran 2003
5347 @item @emph{Standard}:
5353 @item @emph{Syntax}:
5354 @code{CALL GETARG(POS, VALUE)}
5356 @item @emph{Arguments}:
5357 @multitable @columnfractions .15 .70
5358 @item @var{POS} @tab Shall be of type @code{INTEGER} and not wider than
5359 the default integer kind; @math{@var{POS} \geq 0}
5360 @item @var{VALUE} @tab Shall be of type @code{CHARACTER} and of default
5362 @item @var{VALUE} @tab Shall be of type @code{CHARACTER}.
5365 @item @emph{Return value}:
5366 After @code{GETARG} returns, the @var{VALUE} argument holds the
5367 @var{POS}th command line argument. If @var{VALUE} can not hold the
5368 argument, it is truncated to fit the length of @var{VALUE}. If there are
5369 less than @var{POS} arguments specified at the command line, @var{VALUE}
5370 will be filled with blanks. If @math{@var{POS} = 0}, @var{VALUE} is set
5371 to the name of the program (on systems that support this feature).
5373 @item @emph{Example}:
5377 CHARACTER(len=32) :: arg
5386 @item @emph{See also}:
5387 GNU Fortran 77 compatibility function: @ref{IARGC}
5389 Fortran 2003 functions and subroutines: @ref{GET_COMMAND},
5390 @ref{GET_COMMAND_ARGUMENT}, @ref{COMMAND_ARGUMENT_COUNT}
5396 @section @code{GET_COMMAND} --- Get the entire command line
5397 @fnindex GET_COMMAND
5398 @cindex command-line arguments
5399 @cindex arguments, to program
5402 @item @emph{Description}:
5403 Retrieve the entire command line that was used to invoke the program.
5405 @item @emph{Standard}:
5406 Fortran 2003 and later
5411 @item @emph{Syntax}:
5412 @code{CALL GET_COMMAND([COMMAND, LENGTH, STATUS])}
5414 @item @emph{Arguments}:
5415 @multitable @columnfractions .15 .70
5416 @item @var{COMMAND} @tab (Optional) shall be of type @code{CHARACTER} and
5418 @item @var{LENGTH} @tab (Optional) Shall be of type @code{INTEGER} and of
5420 @item @var{STATUS} @tab (Optional) Shall be of type @code{INTEGER} and of
5424 @item @emph{Return value}:
5425 If @var{COMMAND} is present, stores the entire command line that was used
5426 to invoke the program in @var{COMMAND}. If @var{LENGTH} is present, it is
5427 assigned the length of the command line. If @var{STATUS} is present, it
5428 is assigned 0 upon success of the command, -1 if @var{COMMAND} is too
5429 short to store the command line, or a positive value in case of an error.
5431 @item @emph{Example}:
5433 PROGRAM test_get_command
5434 CHARACTER(len=255) :: cmd
5435 CALL get_command(cmd)
5436 WRITE (*,*) TRIM(cmd)
5440 @item @emph{See also}:
5441 @ref{GET_COMMAND_ARGUMENT}, @ref{COMMAND_ARGUMENT_COUNT}
5446 @node GET_COMMAND_ARGUMENT
5447 @section @code{GET_COMMAND_ARGUMENT} --- Get command line arguments
5448 @fnindex GET_COMMAND_ARGUMENT
5449 @cindex command-line arguments
5450 @cindex arguments, to program
5453 @item @emph{Description}:
5454 Retrieve the @var{NUMBER}-th argument that was passed on the
5455 command line when the containing program was invoked.
5457 @item @emph{Standard}:
5458 Fortran 2003 and later
5463 @item @emph{Syntax}:
5464 @code{CALL GET_COMMAND_ARGUMENT(NUMBER [, VALUE, LENGTH, STATUS])}
5466 @item @emph{Arguments}:
5467 @multitable @columnfractions .15 .70
5468 @item @var{NUMBER} @tab Shall be a scalar of type @code{INTEGER} and of
5469 default kind, @math{@var{NUMBER} \geq 0}
5470 @item @var{VALUE} @tab (Optional) Shall be a scalar of type @code{CHARACTER}
5471 and of default kind.
5472 @item @var{LENGTH} @tab (Optional) Shall be a scalar of type @code{INTEGER}
5473 and of default kind.
5474 @item @var{STATUS} @tab (Optional) Shall be a scalar of type @code{INTEGER}
5475 and of default kind.
5478 @item @emph{Return value}:
5479 After @code{GET_COMMAND_ARGUMENT} returns, the @var{VALUE} argument holds the
5480 @var{NUMBER}-th command line argument. If @var{VALUE} can not hold the argument, it is
5481 truncated to fit the length of @var{VALUE}. If there are less than @var{NUMBER}
5482 arguments specified at the command line, @var{VALUE} will be filled with blanks.
5483 If @math{@var{NUMBER} = 0}, @var{VALUE} is set to the name of the program (on
5484 systems that support this feature). The @var{LENGTH} argument contains the
5485 length of the @var{NUMBER}-th command line argument. If the argument retrieval
5486 fails, @var{STATUS} is a positive number; if @var{VALUE} contains a truncated
5487 command line argument, @var{STATUS} is -1; and otherwise the @var{STATUS} is
5490 @item @emph{Example}:
5492 PROGRAM test_get_command_argument
5494 CHARACTER(len=32) :: arg
5498 CALL get_command_argument(i, arg)
5499 IF (LEN_TRIM(arg) == 0) EXIT
5501 WRITE (*,*) TRIM(arg)
5507 @item @emph{See also}:
5508 @ref{GET_COMMAND}, @ref{COMMAND_ARGUMENT_COUNT}
5514 @section @code{GETCWD} --- Get current working directory
5516 @cindex system, working directory
5519 @item @emph{Description}:
5520 Get current working directory.
5522 This intrinsic is provided in both subroutine and function forms; however,
5523 only one form can be used in any given program unit.
5525 @item @emph{Standard}:
5529 Subroutine, function
5531 @item @emph{Syntax}:
5532 @multitable @columnfractions .80
5533 @item @code{CALL GETCWD(C [, STATUS])}
5534 @item @code{STATUS = GETCWD(C)}
5537 @item @emph{Arguments}:
5538 @multitable @columnfractions .15 .70
5539 @item @var{C} @tab The type shall be @code{CHARACTER} and of default kind.
5540 @item @var{STATUS} @tab (Optional) status flag. Returns 0 on success,
5541 a system specific and nonzero error code otherwise.
5544 @item @emph{Example}:
5547 CHARACTER(len=255) :: cwd
5549 WRITE(*,*) TRIM(cwd)
5553 @item @emph{See also}:
5560 @section @code{GETENV} --- Get an environmental variable
5562 @cindex environment variable
5565 @item @emph{Description}:
5566 Get the @var{VALUE} of the environmental variable @var{NAME}.
5568 This intrinsic routine is provided for backwards compatibility with
5569 GNU Fortran 77. In new code, programmers should consider the use of
5570 the @ref{GET_ENVIRONMENT_VARIABLE} intrinsic defined by the Fortran
5573 Note that @code{GETENV} need not be thread-safe. It is the
5574 responsibility of the user to ensure that the environment is not being
5575 updated concurrently with a call to the @code{GETENV} intrinsic.
5577 @item @emph{Standard}:
5583 @item @emph{Syntax}:
5584 @code{CALL GETENV(NAME, VALUE)}
5586 @item @emph{Arguments}:
5587 @multitable @columnfractions .15 .70
5588 @item @var{NAME} @tab Shall be of type @code{CHARACTER} and of default kind.
5589 @item @var{VALUE} @tab Shall be of type @code{CHARACTER} and of default kind.
5592 @item @emph{Return value}:
5593 Stores the value of @var{NAME} in @var{VALUE}. If @var{VALUE} is
5594 not large enough to hold the data, it is truncated. If @var{NAME}
5595 is not set, @var{VALUE} will be filled with blanks.
5597 @item @emph{Example}:
5600 CHARACTER(len=255) :: homedir
5601 CALL getenv("HOME", homedir)
5602 WRITE (*,*) TRIM(homedir)
5606 @item @emph{See also}:
5607 @ref{GET_ENVIRONMENT_VARIABLE}
5612 @node GET_ENVIRONMENT_VARIABLE
5613 @section @code{GET_ENVIRONMENT_VARIABLE} --- Get an environmental variable
5614 @fnindex GET_ENVIRONMENT_VARIABLE
5615 @cindex environment variable
5618 @item @emph{Description}:
5619 Get the @var{VALUE} of the environmental variable @var{NAME}.
5621 Note that @code{GET_ENVIRONMENT_VARIABLE} need not be thread-safe. It
5622 is the responsibility of the user to ensure that the environment is
5623 not being updated concurrently with a call to the
5624 @code{GET_ENVIRONMENT_VARIABLE} intrinsic.
5626 @item @emph{Standard}:
5627 Fortran 2003 and later
5632 @item @emph{Syntax}:
5633 @code{CALL GET_ENVIRONMENT_VARIABLE(NAME[, VALUE, LENGTH, STATUS, TRIM_NAME)}
5635 @item @emph{Arguments}:
5636 @multitable @columnfractions .15 .70
5637 @item @var{NAME} @tab Shall be a scalar of type @code{CHARACTER}
5638 and of default kind.
5639 @item @var{VALUE} @tab (Optional) Shall be a scalar of type @code{CHARACTER}
5640 and of default kind.
5641 @item @var{LENGTH} @tab (Optional) Shall be a scalar of type @code{INTEGER}
5642 and of default kind.
5643 @item @var{STATUS} @tab (Optional) Shall be a scalar of type @code{INTEGER}
5644 and of default kind.
5645 @item @var{TRIM_NAME} @tab (Optional) Shall be a scalar of type @code{LOGICAL}
5646 and of default kind.
5649 @item @emph{Return value}:
5650 Stores the value of @var{NAME} in @var{VALUE}. If @var{VALUE} is
5651 not large enough to hold the data, it is truncated. If @var{NAME}
5652 is not set, @var{VALUE} will be filled with blanks. Argument @var{LENGTH}
5653 contains the length needed for storing the environment variable @var{NAME}
5654 or zero if it is not present. @var{STATUS} is -1 if @var{VALUE} is present
5655 but too short for the environment variable; it is 1 if the environment
5656 variable does not exist and 2 if the processor does not support environment
5657 variables; in all other cases @var{STATUS} is zero. If @var{TRIM_NAME} is
5658 present with the value @code{.FALSE.}, the trailing blanks in @var{NAME}
5659 are significant; otherwise they are not part of the environment variable
5662 @item @emph{Example}:
5665 CHARACTER(len=255) :: homedir
5666 CALL get_environment_variable("HOME", homedir)
5667 WRITE (*,*) TRIM(homedir)
5675 @section @code{GETGID} --- Group ID function
5677 @cindex system, group ID
5680 @item @emph{Description}:
5681 Returns the numerical group ID of the current process.
5683 @item @emph{Standard}:
5689 @item @emph{Syntax}:
5690 @code{RESULT = GETGID()}
5692 @item @emph{Return value}:
5693 The return value of @code{GETGID} is an @code{INTEGER} of the default
5697 @item @emph{Example}:
5698 See @code{GETPID} for an example.
5700 @item @emph{See also}:
5701 @ref{GETPID}, @ref{GETUID}
5707 @section @code{GETLOG} --- Get login name
5709 @cindex system, login name
5713 @item @emph{Description}:
5714 Gets the username under which the program is running.
5716 @item @emph{Standard}:
5722 @item @emph{Syntax}:
5723 @code{CALL GETLOG(C)}
5725 @item @emph{Arguments}:
5726 @multitable @columnfractions .15 .70
5727 @item @var{C} @tab Shall be of type @code{CHARACTER} and of default kind.
5730 @item @emph{Return value}:
5731 Stores the current user name in @var{LOGIN}. (On systems where POSIX
5732 functions @code{geteuid} and @code{getpwuid} are not available, and
5733 the @code{getlogin} function is not implemented either, this will
5734 return a blank string.)
5736 @item @emph{Example}:
5739 CHARACTER(32) :: login
5745 @item @emph{See also}:
5752 @section @code{GETPID} --- Process ID function
5754 @cindex system, process ID
5758 @item @emph{Description}:
5759 Returns the numerical process identifier of the current process.
5761 @item @emph{Standard}:
5767 @item @emph{Syntax}:
5768 @code{RESULT = GETPID()}
5770 @item @emph{Return value}:
5771 The return value of @code{GETPID} is an @code{INTEGER} of the default
5775 @item @emph{Example}:
5778 print *, "The current process ID is ", getpid()
5779 print *, "Your numerical user ID is ", getuid()
5780 print *, "Your numerical group ID is ", getgid()
5784 @item @emph{See also}:
5785 @ref{GETGID}, @ref{GETUID}
5791 @section @code{GETUID} --- User ID function
5793 @cindex system, user ID
5797 @item @emph{Description}:
5798 Returns the numerical user ID of the current process.
5800 @item @emph{Standard}:
5806 @item @emph{Syntax}:
5807 @code{RESULT = GETUID()}
5809 @item @emph{Return value}:
5810 The return value of @code{GETUID} is an @code{INTEGER} of the default
5814 @item @emph{Example}:
5815 See @code{GETPID} for an example.
5817 @item @emph{See also}:
5818 @ref{GETPID}, @ref{GETLOG}
5824 @section @code{GMTIME} --- Convert time to GMT info
5826 @cindex time, conversion to GMT info
5829 @item @emph{Description}:
5830 Given a system time value @var{TIME} (as provided by the @code{TIME8}
5831 intrinsic), fills @var{VALUES} with values extracted from it appropriate
5832 to the UTC time zone (Universal Coordinated Time, also known in some
5833 countries as GMT, Greenwich Mean Time), using @code{gmtime(3)}.
5835 @item @emph{Standard}:
5841 @item @emph{Syntax}:
5842 @code{CALL GMTIME(TIME, VALUES)}
5844 @item @emph{Arguments}:
5845 @multitable @columnfractions .15 .70
5846 @item @var{TIME} @tab An @code{INTEGER} scalar expression
5847 corresponding to a system time, with @code{INTENT(IN)}.
5848 @item @var{VALUES} @tab A default @code{INTEGER} array with 9 elements,
5849 with @code{INTENT(OUT)}.
5852 @item @emph{Return value}:
5853 The elements of @var{VALUES} are assigned as follows:
5855 @item Seconds after the minute, range 0--59 or 0--61 to allow for leap
5857 @item Minutes after the hour, range 0--59
5858 @item Hours past midnight, range 0--23
5859 @item Day of month, range 0--31
5860 @item Number of months since January, range 0--12
5861 @item Years since 1900
5862 @item Number of days since Sunday, range 0--6
5863 @item Days since January 1
5864 @item Daylight savings indicator: positive if daylight savings is in
5865 effect, zero if not, and negative if the information is not available.
5868 @item @emph{See also}:
5869 @ref{CTIME}, @ref{LTIME}, @ref{TIME}, @ref{TIME8}
5876 @section @code{HOSTNM} --- Get system host name
5878 @cindex system, host name
5881 @item @emph{Description}:
5882 Retrieves the host name of the system on which the program is running.
5884 This intrinsic is provided in both subroutine and function forms; however,
5885 only one form can be used in any given program unit.
5887 @item @emph{Standard}:
5891 Subroutine, function
5893 @item @emph{Syntax}:
5894 @multitable @columnfractions .80
5895 @item @code{CALL HOSTNM(C [, STATUS])}
5896 @item @code{STATUS = HOSTNM(NAME)}
5899 @item @emph{Arguments}:
5900 @multitable @columnfractions .15 .70
5901 @item @var{C} @tab Shall of type @code{CHARACTER} and of default kind.
5902 @item @var{STATUS} @tab (Optional) status flag of type @code{INTEGER}.
5903 Returns 0 on success, or a system specific error code otherwise.
5906 @item @emph{Return value}:
5907 In either syntax, @var{NAME} is set to the current hostname if it can
5908 be obtained, or to a blank string otherwise.
5915 @section @code{HUGE} --- Largest number of a kind
5917 @cindex limits, largest number
5918 @cindex model representation, largest number
5921 @item @emph{Description}:
5922 @code{HUGE(X)} returns the largest number that is not an infinity in
5923 the model of the type of @code{X}.
5925 @item @emph{Standard}:
5926 Fortran 95 and later
5931 @item @emph{Syntax}:
5932 @code{RESULT = HUGE(X)}
5934 @item @emph{Arguments}:
5935 @multitable @columnfractions .15 .70
5936 @item @var{X} @tab Shall be of type @code{REAL} or @code{INTEGER}.
5939 @item @emph{Return value}:
5940 The return value is of the same type and kind as @var{X}
5942 @item @emph{Example}:
5944 program test_huge_tiny
5945 print *, huge(0), huge(0.0), huge(0.0d0)
5946 print *, tiny(0.0), tiny(0.0d0)
5947 end program test_huge_tiny
5954 @section @code{HYPOT} --- Euclidean distance function
5956 @cindex Euclidean distance
5959 @item @emph{Description}:
5960 @code{HYPOT(X,Y)} is the Euclidean distance function. It is equal to
5961 @math{\sqrt{X^2 + Y^2}}, without undue underflow or overflow.
5963 @item @emph{Standard}:
5964 Fortran 2008 and later
5969 @item @emph{Syntax}:
5970 @code{RESULT = HYPOT(X, Y)}
5972 @item @emph{Arguments}:
5973 @multitable @columnfractions .15 .70
5974 @item @var{X} @tab The type shall be @code{REAL}.
5975 @item @var{Y} @tab The type and kind type parameter shall be the same as
5979 @item @emph{Return value}:
5980 The return value has the same type and kind type parameter as @var{X}.
5982 @item @emph{Example}:
5985 real(4) :: x = 1.e0_4, y = 0.5e0_4
5987 end program test_hypot
5994 @section @code{IACHAR} --- Code in @acronym{ASCII} collating sequence
5996 @cindex @acronym{ASCII} collating sequence
5997 @cindex collating sequence, @acronym{ASCII}
5998 @cindex conversion, to integer
6001 @item @emph{Description}:
6002 @code{IACHAR(C)} returns the code for the @acronym{ASCII} character
6003 in the first character position of @code{C}.
6005 @item @emph{Standard}:
6006 Fortran 95 and later, with @var{KIND} argument Fortran 2003 and later
6011 @item @emph{Syntax}:
6012 @code{RESULT = IACHAR(C [, KIND])}
6014 @item @emph{Arguments}:
6015 @multitable @columnfractions .15 .70
6016 @item @var{C} @tab Shall be a scalar @code{CHARACTER}, with @code{INTENT(IN)}
6017 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
6018 expression indicating the kind parameter of the result.
6021 @item @emph{Return value}:
6022 The return value is of type @code{INTEGER} and of kind @var{KIND}. If
6023 @var{KIND} is absent, the return value is of default integer kind.
6025 @item @emph{Example}:
6030 end program test_iachar
6034 See @ref{ICHAR} for a discussion of converting between numerical values
6035 and formatted string representations.
6037 @item @emph{See also}:
6038 @ref{ACHAR}, @ref{CHAR}, @ref{ICHAR}
6045 @section @code{IALL} --- Bitwise AND of array elements
6048 @cindex bits, AND of array elements
6051 @item @emph{Description}:
6052 Reduces with bitwise AND the elements of @var{ARRAY} along dimension @var{DIM}
6053 if the corresponding element in @var{MASK} is @code{TRUE}.
6055 @item @emph{Standard}:
6056 Fortran 2008 and later
6059 Transformational function
6061 @item @emph{Syntax}:
6062 @multitable @columnfractions .80
6063 @item @code{RESULT = IALL(ARRAY[, MASK])}
6064 @item @code{RESULT = IALL(ARRAY, DIM[, MASK])}
6067 @item @emph{Arguments}:
6068 @multitable @columnfractions .15 .70
6069 @item @var{ARRAY} @tab Shall be an array of type @code{INTEGER}
6070 @item @var{DIM} @tab (Optional) shall be a scalar of type
6071 @code{INTEGER} with a value in the range from 1 to n, where n
6072 equals the rank of @var{ARRAY}.
6073 @item @var{MASK} @tab (Optional) shall be of type @code{LOGICAL}
6074 and either be a scalar or an array of the same shape as @var{ARRAY}.
6077 @item @emph{Return value}:
6078 The result is of the same type as @var{ARRAY}.
6080 If @var{DIM} is absent, a scalar with the bitwise ALL of all elements in
6081 @var{ARRAY} is returned. Otherwise, an array of rank n-1, where n equals
6082 the rank of @var{ARRAY}, and a shape similar to that of @var{ARRAY} with
6083 dimension @var{DIM} dropped is returned.
6085 @item @emph{Example}:
6094 PRINT '(b8.8)', IALL(a)
6098 @item @emph{See also}:
6099 @ref{IANY}, @ref{IPARITY}, @ref{IAND}
6105 @section @code{IAND} --- Bitwise logical and
6107 @cindex bitwise logical and
6108 @cindex logical and, bitwise
6111 @item @emph{Description}:
6112 Bitwise logical @code{AND}.
6114 @item @emph{Standard}:
6115 Fortran 95 and later
6120 @item @emph{Syntax}:
6121 @code{RESULT = IAND(I, J)}
6123 @item @emph{Arguments}:
6124 @multitable @columnfractions .15 .70
6125 @item @var{I} @tab The type shall be @code{INTEGER}.
6126 @item @var{J} @tab The type shall be @code{INTEGER}, of the same
6127 kind as @var{I}. (As a GNU extension, different kinds are also
6131 @item @emph{Return value}:
6132 The return type is @code{INTEGER}, of the same kind as the
6133 arguments. (If the argument kinds differ, it is of the same kind as
6134 the larger argument.)
6136 @item @emph{Example}:
6140 DATA a / Z'F' /, b / Z'3' /
6141 WRITE (*,*) IAND(a, b)
6145 @item @emph{See also}:
6146 @ref{IOR}, @ref{IEOR}, @ref{IBITS}, @ref{IBSET}, @ref{IBCLR}, @ref{NOT}
6153 @section @code{IANY} --- Bitwise OR of array elements
6156 @cindex bits, OR of array elements
6159 @item @emph{Description}:
6160 Reduces with bitwise OR (inclusive or) the elements of @var{ARRAY} along
6161 dimension @var{DIM} if the corresponding element in @var{MASK} is @code{TRUE}.
6163 @item @emph{Standard}:
6164 Fortran 2008 and later
6167 Transformational function
6169 @item @emph{Syntax}:
6170 @multitable @columnfractions .80
6171 @item @code{RESULT = IANY(ARRAY[, MASK])}
6172 @item @code{RESULT = IANY(ARRAY, DIM[, MASK])}
6175 @item @emph{Arguments}:
6176 @multitable @columnfractions .15 .70
6177 @item @var{ARRAY} @tab Shall be an array of type @code{INTEGER}
6178 @item @var{DIM} @tab (Optional) shall be a scalar of type
6179 @code{INTEGER} with a value in the range from 1 to n, where n
6180 equals the rank of @var{ARRAY}.
6181 @item @var{MASK} @tab (Optional) shall be of type @code{LOGICAL}
6182 and either be a scalar or an array of the same shape as @var{ARRAY}.
6185 @item @emph{Return value}:
6186 The result is of the same type as @var{ARRAY}.
6188 If @var{DIM} is absent, a scalar with the bitwise OR of all elements in
6189 @var{ARRAY} is returned. Otherwise, an array of rank n-1, where n equals
6190 the rank of @var{ARRAY}, and a shape similar to that of @var{ARRAY} with
6191 dimension @var{DIM} dropped is returned.
6193 @item @emph{Example}:
6202 PRINT '(b8.8)', IANY(a)
6206 @item @emph{See also}:
6207 @ref{IPARITY}, @ref{IALL}, @ref{IOR}
6213 @section @code{IARGC} --- Get the number of command line arguments
6215 @cindex command-line arguments
6216 @cindex command-line arguments, number of
6217 @cindex arguments, to program
6220 @item @emph{Description}:
6221 @code{IARGC} returns the number of arguments passed on the
6222 command line when the containing program was invoked.
6224 This intrinsic routine is provided for backwards compatibility with
6225 GNU Fortran 77. In new code, programmers should consider the use of
6226 the @ref{COMMAND_ARGUMENT_COUNT} intrinsic defined by the Fortran 2003
6229 @item @emph{Standard}:
6235 @item @emph{Syntax}:
6236 @code{RESULT = IARGC()}
6238 @item @emph{Arguments}:
6241 @item @emph{Return value}:
6242 The number of command line arguments, type @code{INTEGER(4)}.
6244 @item @emph{Example}:
6247 @item @emph{See also}:
6248 GNU Fortran 77 compatibility subroutine: @ref{GETARG}
6250 Fortran 2003 functions and subroutines: @ref{GET_COMMAND},
6251 @ref{GET_COMMAND_ARGUMENT}, @ref{COMMAND_ARGUMENT_COUNT}
6257 @section @code{IBCLR} --- Clear bit
6263 @item @emph{Description}:
6264 @code{IBCLR} returns the value of @var{I} with the bit at position
6265 @var{POS} set to zero.
6267 @item @emph{Standard}:
6268 Fortran 95 and later
6273 @item @emph{Syntax}:
6274 @code{RESULT = IBCLR(I, POS)}
6276 @item @emph{Arguments}:
6277 @multitable @columnfractions .15 .70
6278 @item @var{I} @tab The type shall be @code{INTEGER}.
6279 @item @var{POS} @tab The type shall be @code{INTEGER}.
6282 @item @emph{Return value}:
6283 The return value is of type @code{INTEGER} and of the same kind as
6286 @item @emph{See also}:
6287 @ref{IBITS}, @ref{IBSET}, @ref{IAND}, @ref{IOR}, @ref{IEOR}, @ref{MVBITS}
6294 @section @code{IBITS} --- Bit extraction
6297 @cindex bits, extract
6300 @item @emph{Description}:
6301 @code{IBITS} extracts a field of length @var{LEN} from @var{I},
6302 starting from bit position @var{POS} and extending left for @var{LEN}
6303 bits. The result is right-justified and the remaining bits are
6304 zeroed. The value of @code{POS+LEN} must be less than or equal to the
6305 value @code{BIT_SIZE(I)}.
6307 @item @emph{Standard}:
6308 Fortran 95 and later
6313 @item @emph{Syntax}:
6314 @code{RESULT = IBITS(I, POS, LEN)}
6316 @item @emph{Arguments}:
6317 @multitable @columnfractions .15 .70
6318 @item @var{I} @tab The type shall be @code{INTEGER}.
6319 @item @var{POS} @tab The type shall be @code{INTEGER}.
6320 @item @var{LEN} @tab The type shall be @code{INTEGER}.
6323 @item @emph{Return value}:
6324 The return value is of type @code{INTEGER} and of the same kind as
6327 @item @emph{See also}:
6328 @ref{BIT_SIZE}, @ref{IBCLR}, @ref{IBSET}, @ref{IAND}, @ref{IOR}, @ref{IEOR}
6334 @section @code{IBSET} --- Set bit
6339 @item @emph{Description}:
6340 @code{IBSET} returns the value of @var{I} with the bit at position
6341 @var{POS} set to one.
6343 @item @emph{Standard}:
6344 Fortran 95 and later
6349 @item @emph{Syntax}:
6350 @code{RESULT = IBSET(I, POS)}
6352 @item @emph{Arguments}:
6353 @multitable @columnfractions .15 .70
6354 @item @var{I} @tab The type shall be @code{INTEGER}.
6355 @item @var{POS} @tab The type shall be @code{INTEGER}.
6358 @item @emph{Return value}:
6359 The return value is of type @code{INTEGER} and of the same kind as
6362 @item @emph{See also}:
6363 @ref{IBCLR}, @ref{IBITS}, @ref{IAND}, @ref{IOR}, @ref{IEOR}, @ref{MVBITS}
6370 @section @code{ICHAR} --- Character-to-integer conversion function
6372 @cindex conversion, to integer
6375 @item @emph{Description}:
6376 @code{ICHAR(C)} returns the code for the character in the first character
6377 position of @code{C} in the system's native character set.
6378 The correspondence between characters and their codes is not necessarily
6379 the same across different GNU Fortran implementations.
6381 @item @emph{Standard}:
6382 Fortran 95 and later, with @var{KIND} argument Fortran 2003 and later
6387 @item @emph{Syntax}:
6388 @code{RESULT = ICHAR(C [, KIND])}
6390 @item @emph{Arguments}:
6391 @multitable @columnfractions .15 .70
6392 @item @var{C} @tab Shall be a scalar @code{CHARACTER}, with @code{INTENT(IN)}
6393 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
6394 expression indicating the kind parameter of the result.
6397 @item @emph{Return value}:
6398 The return value is of type @code{INTEGER} and of kind @var{KIND}. If
6399 @var{KIND} is absent, the return value is of default integer kind.
6401 @item @emph{Example}:
6406 end program test_ichar
6409 @item @emph{Specific names}:
6410 @multitable @columnfractions .20 .20 .20 .25
6411 @item Name @tab Argument @tab Return type @tab Standard
6412 @item @code{ICHAR(C)} @tab @code{CHARACTER C} @tab @code{INTEGER(4)} @tab Fortran 77 and later
6416 No intrinsic exists to convert between a numeric value and a formatted
6417 character string representation -- for instance, given the
6418 @code{CHARACTER} value @code{'154'}, obtaining an @code{INTEGER} or
6419 @code{REAL} value with the value 154, or vice versa. Instead, this
6420 functionality is provided by internal-file I/O, as in the following
6425 character(len=10) string, string2
6428 ! Convert a string to a numeric value
6429 read (string,'(I10)') value
6432 ! Convert a value to a formatted string
6433 write (string2,'(I10)') value
6435 end program read_val
6438 @item @emph{See also}:
6439 @ref{ACHAR}, @ref{CHAR}, @ref{IACHAR}
6446 @section @code{IDATE} --- Get current local time subroutine (day/month/year)
6448 @cindex date, current
6449 @cindex current date
6452 @item @emph{Description}:
6453 @code{IDATE(VALUES)} Fills @var{VALUES} with the numerical values at the
6454 current local time. The day (in the range 1-31), month (in the range 1-12),
6455 and year appear in elements 1, 2, and 3 of @var{VALUES}, respectively.
6456 The year has four significant digits.
6458 @item @emph{Standard}:
6464 @item @emph{Syntax}:
6465 @code{CALL IDATE(VALUES)}
6467 @item @emph{Arguments}:
6468 @multitable @columnfractions .15 .70
6469 @item @var{VALUES} @tab The type shall be @code{INTEGER, DIMENSION(3)} and
6470 the kind shall be the default integer kind.
6473 @item @emph{Return value}:
6474 Does not return anything.
6476 @item @emph{Example}:
6479 integer, dimension(3) :: tarray
6484 end program test_idate
6491 @section @code{IEOR} --- Bitwise logical exclusive or
6493 @cindex bitwise logical exclusive or
6494 @cindex logical exclusive or, bitwise
6497 @item @emph{Description}:
6498 @code{IEOR} returns the bitwise Boolean exclusive-OR of @var{I} and
6501 @item @emph{Standard}:
6502 Fortran 95 and later
6507 @item @emph{Syntax}:
6508 @code{RESULT = IEOR(I, J)}
6510 @item @emph{Arguments}:
6511 @multitable @columnfractions .15 .70
6512 @item @var{I} @tab The type shall be @code{INTEGER}.
6513 @item @var{J} @tab The type shall be @code{INTEGER}, of the same
6514 kind as @var{I}. (As a GNU extension, different kinds are also
6518 @item @emph{Return value}:
6519 The return type is @code{INTEGER}, of the same kind as the
6520 arguments. (If the argument kinds differ, it is of the same kind as
6521 the larger argument.)
6523 @item @emph{See also}:
6524 @ref{IOR}, @ref{IAND}, @ref{IBITS}, @ref{IBSET}, @ref{IBCLR}, @ref{NOT}
6530 @section @code{IERRNO} --- Get the last system error number
6532 @cindex system, error handling
6535 @item @emph{Description}:
6536 Returns the last system error number, as given by the C @code{errno}
6539 @item @emph{Standard}:
6545 @item @emph{Syntax}:
6546 @code{RESULT = IERRNO()}
6548 @item @emph{Arguments}:
6551 @item @emph{Return value}:
6552 The return value is of type @code{INTEGER} and of the default integer
6555 @item @emph{See also}:
6562 @section @code{IMAGE_INDEX} --- Function that converts a cosubscript to an image index
6563 @fnindex IMAGE_INDEX
6564 @cindex coarray, @code{IMAGE_INDEX}
6565 @cindex images, cosubscript to image index conversion
6568 @item @emph{Description}:
6569 Returns the image index belonging to a cosubscript.
6571 @item @emph{Standard}:
6572 Fortran 2008 and later
6577 @item @emph{Syntax}:
6578 @code{RESULT = IMAGE_INDEX(COARRAY, SUB)}
6580 @item @emph{Arguments}: None.
6581 @multitable @columnfractions .15 .70
6582 @item @var{COARRAY} @tab Coarray of any type.
6583 @item @var{SUB} @tab default integer rank-1 array of a size equal to
6584 the corank of @var{COARRAY}.
6588 @item @emph{Return value}:
6589 Scalar default integer with the value of the image index which corresponds
6590 to the cosubscripts. For invalid cosubscripts the result is zero.
6592 @item @emph{Example}:
6594 INTEGER :: array[2,-1:4,8,*]
6595 ! Writes 28 (or 0 if there are fewer than 28 images)
6596 WRITE (*,*) IMAGE_INDEX (array, [2,0,3,1])
6599 @item @emph{See also}:
6600 @ref{THIS_IMAGE}, @ref{NUM_IMAGES}
6605 @node INDEX intrinsic
6606 @section @code{INDEX} --- Position of a substring within a string
6608 @cindex substring position
6609 @cindex string, find substring
6612 @item @emph{Description}:
6613 Returns the position of the start of the first occurrence of string
6614 @var{SUBSTRING} as a substring in @var{STRING}, counting from one. If
6615 @var{SUBSTRING} is not present in @var{STRING}, zero is returned. If
6616 the @var{BACK} argument is present and true, the return value is the
6617 start of the last occurrence rather than the first.
6619 @item @emph{Standard}:
6620 Fortran 77 and later, with @var{KIND} argument Fortran 2003 and later
6625 @item @emph{Syntax}:
6626 @code{RESULT = INDEX(STRING, SUBSTRING [, BACK [, KIND]])}
6628 @item @emph{Arguments}:
6629 @multitable @columnfractions .15 .70
6630 @item @var{STRING} @tab Shall be a scalar @code{CHARACTER}, with
6632 @item @var{SUBSTRING} @tab Shall be a scalar @code{CHARACTER}, with
6634 @item @var{BACK} @tab (Optional) Shall be a scalar @code{LOGICAL}, with
6636 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
6637 expression indicating the kind parameter of the result.
6640 @item @emph{Return value}:
6641 The return value is of type @code{INTEGER} and of kind @var{KIND}. If
6642 @var{KIND} is absent, the return value is of default integer kind.
6644 @item @emph{Specific names}:
6645 @multitable @columnfractions .20 .20 .20 .25
6646 @item Name @tab Argument @tab Return type @tab Standard
6647 @item @code{INDEX(STRING, SUBSTRING)} @tab @code{CHARACTER} @tab @code{INTEGER(4)} @tab Fortran 77 and later
6650 @item @emph{See also}:
6651 @ref{SCAN}, @ref{VERIFY}
6657 @section @code{INT} --- Convert to integer type
6661 @cindex conversion, to integer
6664 @item @emph{Description}:
6665 Convert to integer type
6667 @item @emph{Standard}:
6668 Fortran 77 and later
6673 @item @emph{Syntax}:
6674 @code{RESULT = INT(A [, KIND))}
6676 @item @emph{Arguments}:
6677 @multitable @columnfractions .15 .70
6678 @item @var{A} @tab Shall be of type @code{INTEGER},
6679 @code{REAL}, or @code{COMPLEX}.
6680 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
6681 expression indicating the kind parameter of the result.
6684 @item @emph{Return value}:
6685 These functions return a @code{INTEGER} variable or array under
6686 the following rules:
6690 If @var{A} is of type @code{INTEGER}, @code{INT(A) = A}
6692 If @var{A} is of type @code{REAL} and @math{|A| < 1}, @code{INT(A)} equals @code{0}.
6693 If @math{|A| \geq 1}, then @code{INT(A)} equals the largest integer that does not exceed
6694 the range of @var{A} and whose sign is the same as the sign of @var{A}.
6696 If @var{A} is of type @code{COMPLEX}, rule B is applied to the real part of @var{A}.
6699 @item @emph{Example}:
6703 complex :: z = (-3.7, 1.0)
6705 print *, int(z), int(z,8)
6709 @item @emph{Specific names}:
6710 @multitable @columnfractions .20 .20 .20 .25
6711 @item Name @tab Argument @tab Return type @tab Standard
6712 @item @code{INT(A)} @tab @code{REAL(4) A} @tab @code{INTEGER} @tab Fortran 77 and later
6713 @item @code{IFIX(A)} @tab @code{REAL(4) A} @tab @code{INTEGER} @tab Fortran 77 and later
6714 @item @code{IDINT(A)} @tab @code{REAL(8) A} @tab @code{INTEGER} @tab Fortran 77 and later
6721 @section @code{INT2} --- Convert to 16-bit integer type
6724 @cindex conversion, to integer
6727 @item @emph{Description}:
6728 Convert to a @code{KIND=2} integer type. This is equivalent to the
6729 standard @code{INT} intrinsic with an optional argument of
6730 @code{KIND=2}, and is only included for backwards compatibility.
6732 The @code{SHORT} intrinsic is equivalent to @code{INT2}.
6734 @item @emph{Standard}:
6740 @item @emph{Syntax}:
6741 @code{RESULT = INT2(A)}
6743 @item @emph{Arguments}:
6744 @multitable @columnfractions .15 .70
6745 @item @var{A} @tab Shall be of type @code{INTEGER},
6746 @code{REAL}, or @code{COMPLEX}.
6749 @item @emph{Return value}:
6750 The return value is a @code{INTEGER(2)} variable.
6752 @item @emph{See also}:
6753 @ref{INT}, @ref{INT8}, @ref{LONG}
6759 @section @code{INT8} --- Convert to 64-bit integer type
6761 @cindex conversion, to integer
6764 @item @emph{Description}:
6765 Convert to a @code{KIND=8} integer type. This is equivalent to the
6766 standard @code{INT} intrinsic with an optional argument of
6767 @code{KIND=8}, and is only included for backwards compatibility.
6769 @item @emph{Standard}:
6775 @item @emph{Syntax}:
6776 @code{RESULT = INT8(A)}
6778 @item @emph{Arguments}:
6779 @multitable @columnfractions .15 .70
6780 @item @var{A} @tab Shall be of type @code{INTEGER},
6781 @code{REAL}, or @code{COMPLEX}.
6784 @item @emph{Return value}:
6785 The return value is a @code{INTEGER(8)} variable.
6787 @item @emph{See also}:
6788 @ref{INT}, @ref{INT2}, @ref{LONG}
6794 @section @code{IOR} --- Bitwise logical or
6796 @cindex bitwise logical or
6797 @cindex logical or, bitwise
6800 @item @emph{Description}:
6801 @code{IOR} returns the bitwise Boolean inclusive-OR of @var{I} and
6804 @item @emph{Standard}:
6805 Fortran 95 and later
6810 @item @emph{Syntax}:
6811 @code{RESULT = IOR(I, J)}
6813 @item @emph{Arguments}:
6814 @multitable @columnfractions .15 .70
6815 @item @var{I} @tab The type shall be @code{INTEGER}.
6816 @item @var{J} @tab The type shall be @code{INTEGER}, of the same
6817 kind as @var{I}. (As a GNU extension, different kinds are also
6821 @item @emph{Return value}:
6822 The return type is @code{INTEGER}, of the same kind as the
6823 arguments. (If the argument kinds differ, it is of the same kind as
6824 the larger argument.)
6826 @item @emph{See also}:
6827 @ref{IEOR}, @ref{IAND}, @ref{IBITS}, @ref{IBSET}, @ref{IBCLR}, @ref{NOT}
6833 @section @code{IPARITY} --- Bitwise XOR of array elements
6835 @cindex array, parity
6837 @cindex bits, XOR of array elements
6840 @item @emph{Description}:
6841 Reduces with bitwise XOR (exclusive or) the elements of @var{ARRAY} along
6842 dimension @var{DIM} if the corresponding element in @var{MASK} is @code{TRUE}.
6844 @item @emph{Standard}:
6845 Fortran 2008 and later
6848 Transformational function
6850 @item @emph{Syntax}:
6851 @multitable @columnfractions .80
6852 @item @code{RESULT = IPARITY(ARRAY[, MASK])}
6853 @item @code{RESULT = IPARITY(ARRAY, DIM[, MASK])}
6856 @item @emph{Arguments}:
6857 @multitable @columnfractions .15 .70
6858 @item @var{ARRAY} @tab Shall be an array of type @code{INTEGER}
6859 @item @var{DIM} @tab (Optional) shall be a scalar of type
6860 @code{INTEGER} with a value in the range from 1 to n, where n
6861 equals the rank of @var{ARRAY}.
6862 @item @var{MASK} @tab (Optional) shall be of type @code{LOGICAL}
6863 and either be a scalar or an array of the same shape as @var{ARRAY}.
6866 @item @emph{Return value}:
6867 The result is of the same type as @var{ARRAY}.
6869 If @var{DIM} is absent, a scalar with the bitwise XOR of all elements in
6870 @var{ARRAY} is returned. Otherwise, an array of rank n-1, where n equals
6871 the rank of @var{ARRAY}, and a shape similar to that of @var{ARRAY} with
6872 dimension @var{DIM} dropped is returned.
6874 @item @emph{Example}:
6876 PROGRAM test_iparity
6883 PRINT '(b8.8)', IPARITY(a)
6887 @item @emph{See also}:
6888 @ref{IANY}, @ref{IALL}, @ref{IEOR}, @ref{PARITY}
6894 @section @code{IRAND} --- Integer pseudo-random number
6896 @cindex random number generation
6899 @item @emph{Description}:
6900 @code{IRAND(FLAG)} returns a pseudo-random number from a uniform
6901 distribution between 0 and a system-dependent limit (which is in most
6902 cases 2147483647). If @var{FLAG} is 0, the next number
6903 in the current sequence is returned; if @var{FLAG} is 1, the generator
6904 is restarted by @code{CALL SRAND(0)}; if @var{FLAG} has any other value,
6905 it is used as a new seed with @code{SRAND}.
6907 This intrinsic routine is provided for backwards compatibility with
6908 GNU Fortran 77. It implements a simple modulo generator as provided
6909 by @command{g77}. For new code, one should consider the use of
6910 @ref{RANDOM_NUMBER} as it implements a superior algorithm.
6912 @item @emph{Standard}:
6918 @item @emph{Syntax}:
6919 @code{RESULT = IRAND(I)}
6921 @item @emph{Arguments}:
6922 @multitable @columnfractions .15 .70
6923 @item @var{I} @tab Shall be a scalar @code{INTEGER} of kind 4.
6926 @item @emph{Return value}:
6927 The return value is of @code{INTEGER(kind=4)} type.
6929 @item @emph{Example}:
6932 integer,parameter :: seed = 86456
6935 print *, irand(), irand(), irand(), irand()
6936 print *, irand(seed), irand(), irand(), irand()
6937 end program test_irand
6945 @section @code{IS_IOSTAT_END} --- Test for end-of-file value
6946 @fnindex IS_IOSTAT_END
6947 @cindex @code{IOSTAT}, end of file
6950 @item @emph{Description}:
6951 @code{IS_IOSTAT_END} tests whether an variable has the value of the I/O
6952 status ``end of file''. The function is equivalent to comparing the variable
6953 with the @code{IOSTAT_END} parameter of the intrinsic module
6954 @code{ISO_FORTRAN_ENV}.
6956 @item @emph{Standard}:
6957 Fortran 2003 and later
6962 @item @emph{Syntax}:
6963 @code{RESULT = IS_IOSTAT_END(I)}
6965 @item @emph{Arguments}:
6966 @multitable @columnfractions .15 .70
6967 @item @var{I} @tab Shall be of the type @code{INTEGER}.
6970 @item @emph{Return value}:
6971 Returns a @code{LOGICAL} of the default kind, which @code{.TRUE.} if
6972 @var{I} has the value which indicates an end of file condition for
6973 @code{IOSTAT=} specifiers, and is @code{.FALSE.} otherwise.
6975 @item @emph{Example}:
6980 OPEN(88, FILE='test.dat')
6981 READ(88, *, IOSTAT=stat) i
6982 IF(IS_IOSTAT_END(stat)) STOP 'END OF FILE'
6990 @section @code{IS_IOSTAT_EOR} --- Test for end-of-record value
6991 @fnindex IS_IOSTAT_EOR
6992 @cindex @code{IOSTAT}, end of record
6995 @item @emph{Description}:
6996 @code{IS_IOSTAT_EOR} tests whether an variable has the value of the I/O
6997 status ``end of record''. The function is equivalent to comparing the
6998 variable with the @code{IOSTAT_EOR} parameter of the intrinsic module
6999 @code{ISO_FORTRAN_ENV}.
7001 @item @emph{Standard}:
7002 Fortran 2003 and later
7007 @item @emph{Syntax}:
7008 @code{RESULT = IS_IOSTAT_EOR(I)}
7010 @item @emph{Arguments}:
7011 @multitable @columnfractions .15 .70
7012 @item @var{I} @tab Shall be of the type @code{INTEGER}.
7015 @item @emph{Return value}:
7016 Returns a @code{LOGICAL} of the default kind, which @code{.TRUE.} if
7017 @var{I} has the value which indicates an end of file condition for
7018 @code{IOSTAT=} specifiers, and is @code{.FALSE.} otherwise.
7020 @item @emph{Example}:
7024 INTEGER :: stat, i(50)
7025 OPEN(88, FILE='test.dat', FORM='UNFORMATTED')
7026 READ(88, IOSTAT=stat) i
7027 IF(IS_IOSTAT_EOR(stat)) STOP 'END OF RECORD'
7035 @section @code{ISATTY} --- Whether a unit is a terminal device.
7037 @cindex system, terminal
7040 @item @emph{Description}:
7041 Determine whether a unit is connected to a terminal device.
7043 @item @emph{Standard}:
7049 @item @emph{Syntax}:
7050 @code{RESULT = ISATTY(UNIT)}
7052 @item @emph{Arguments}:
7053 @multitable @columnfractions .15 .70
7054 @item @var{UNIT} @tab Shall be a scalar @code{INTEGER}.
7057 @item @emph{Return value}:
7058 Returns @code{.TRUE.} if the @var{UNIT} is connected to a terminal
7059 device, @code{.FALSE.} otherwise.
7061 @item @emph{Example}:
7064 INTEGER(kind=1) :: unit
7066 write(*,*) isatty(unit=unit)
7070 @item @emph{See also}:
7077 @section @code{ISHFT} --- Shift bits
7082 @item @emph{Description}:
7083 @code{ISHFT} returns a value corresponding to @var{I} with all of the
7084 bits shifted @var{SHIFT} places. A value of @var{SHIFT} greater than
7085 zero corresponds to a left shift, a value of zero corresponds to no
7086 shift, and a value less than zero corresponds to a right shift. If the
7087 absolute value of @var{SHIFT} is greater than @code{BIT_SIZE(I)}, the
7088 value is undefined. Bits shifted out from the left end or right end are
7089 lost; zeros are shifted in from the opposite end.
7091 @item @emph{Standard}:
7092 Fortran 95 and later
7097 @item @emph{Syntax}:
7098 @code{RESULT = ISHFT(I, SHIFT)}
7100 @item @emph{Arguments}:
7101 @multitable @columnfractions .15 .70
7102 @item @var{I} @tab The type shall be @code{INTEGER}.
7103 @item @var{SHIFT} @tab The type shall be @code{INTEGER}.
7106 @item @emph{Return value}:
7107 The return value is of type @code{INTEGER} and of the same kind as
7110 @item @emph{See also}:
7117 @section @code{ISHFTC} --- Shift bits circularly
7119 @cindex bits, shift circular
7122 @item @emph{Description}:
7123 @code{ISHFTC} returns a value corresponding to @var{I} with the
7124 rightmost @var{SIZE} bits shifted circularly @var{SHIFT} places; that
7125 is, bits shifted out one end are shifted into the opposite end. A value
7126 of @var{SHIFT} greater than zero corresponds to a left shift, a value of
7127 zero corresponds to no shift, and a value less than zero corresponds to
7128 a right shift. The absolute value of @var{SHIFT} must be less than
7129 @var{SIZE}. If the @var{SIZE} argument is omitted, it is taken to be
7130 equivalent to @code{BIT_SIZE(I)}.
7132 @item @emph{Standard}:
7133 Fortran 95 and later
7138 @item @emph{Syntax}:
7139 @code{RESULT = ISHFTC(I, SHIFT [, SIZE])}
7141 @item @emph{Arguments}:
7142 @multitable @columnfractions .15 .70
7143 @item @var{I} @tab The type shall be @code{INTEGER}.
7144 @item @var{SHIFT} @tab The type shall be @code{INTEGER}.
7145 @item @var{SIZE} @tab (Optional) The type shall be @code{INTEGER};
7146 the value must be greater than zero and less than or equal to
7150 @item @emph{Return value}:
7151 The return value is of type @code{INTEGER} and of the same kind as
7154 @item @emph{See also}:
7161 @section @code{ISNAN} --- Test for a NaN
7166 @item @emph{Description}:
7167 @code{ISNAN} tests whether a floating-point value is an IEEE
7169 @item @emph{Standard}:
7175 @item @emph{Syntax}:
7178 @item @emph{Arguments}:
7179 @multitable @columnfractions .15 .70
7180 @item @var{X} @tab Variable of the type @code{REAL}.
7184 @item @emph{Return value}:
7185 Returns a default-kind @code{LOGICAL}. The returned value is @code{TRUE}
7186 if @var{X} is a NaN and @code{FALSE} otherwise.
7188 @item @emph{Example}:
7195 if (isnan(x)) stop '"x" is a NaN'
7196 end program test_nan
7203 @section @code{ITIME} --- Get current local time subroutine (hour/minutes/seconds)
7205 @cindex time, current
7206 @cindex current time
7209 @item @emph{Description}:
7210 @code{IDATE(VALUES)} Fills @var{VALUES} with the numerical values at the
7211 current local time. The hour (in the range 1-24), minute (in the range 1-60),
7212 and seconds (in the range 1-60) appear in elements 1, 2, and 3 of @var{VALUES},
7215 @item @emph{Standard}:
7221 @item @emph{Syntax}:
7222 @code{CALL ITIME(VALUES)}
7224 @item @emph{Arguments}:
7225 @multitable @columnfractions .15 .70
7226 @item @var{VALUES} @tab The type shall be @code{INTEGER, DIMENSION(3)}
7227 and the kind shall be the default integer kind.
7230 @item @emph{Return value}:
7231 Does not return anything.
7234 @item @emph{Example}:
7237 integer, dimension(3) :: tarray
7242 end program test_itime
7249 @section @code{KILL} --- Send a signal to a process
7253 @item @emph{Description}:
7254 @item @emph{Standard}:
7255 Sends the signal specified by @var{SIGNAL} to the process @var{PID}.
7258 This intrinsic is provided in both subroutine and function forms; however,
7259 only one form can be used in any given program unit.
7262 Subroutine, function
7264 @item @emph{Syntax}:
7265 @multitable @columnfractions .80
7266 @item @code{CALL KILL(C, VALUE [, STATUS])}
7267 @item @code{STATUS = KILL(C, VALUE)}
7270 @item @emph{Arguments}:
7271 @multitable @columnfractions .15 .70
7272 @item @var{C} @tab Shall be a scalar @code{INTEGER}, with
7274 @item @var{VALUE} @tab Shall be a scalar @code{INTEGER}, with
7276 @item @var{STATUS} @tab (Optional) status flag of type @code{INTEGER(4)} or
7277 @code{INTEGER(8)}. Returns 0 on success, or a system-specific error code
7281 @item @emph{See also}:
7282 @ref{ABORT}, @ref{EXIT}
7288 @section @code{KIND} --- Kind of an entity
7293 @item @emph{Description}:
7294 @code{KIND(X)} returns the kind value of the entity @var{X}.
7296 @item @emph{Standard}:
7297 Fortran 95 and later
7302 @item @emph{Syntax}:
7305 @item @emph{Arguments}:
7306 @multitable @columnfractions .15 .70
7307 @item @var{X} @tab Shall be of type @code{LOGICAL}, @code{INTEGER},
7308 @code{REAL}, @code{COMPLEX} or @code{CHARACTER}.
7311 @item @emph{Return value}:
7312 The return value is a scalar of type @code{INTEGER} and of the default
7315 @item @emph{Example}:
7318 integer,parameter :: kc = kind(' ')
7319 integer,parameter :: kl = kind(.true.)
7321 print *, "The default character kind is ", kc
7322 print *, "The default logical kind is ", kl
7323 end program test_kind
7331 @section @code{LBOUND} --- Lower dimension bounds of an array
7333 @cindex array, lower bound
7336 @item @emph{Description}:
7337 Returns the lower bounds of an array, or a single lower bound
7338 along the @var{DIM} dimension.
7339 @item @emph{Standard}:
7340 Fortran 95 and later, with @var{KIND} argument Fortran 2003 and later
7345 @item @emph{Syntax}:
7346 @code{RESULT = LBOUND(ARRAY [, DIM [, KIND]])}
7348 @item @emph{Arguments}:
7349 @multitable @columnfractions .15 .70
7350 @item @var{ARRAY} @tab Shall be an array, of any type.
7351 @item @var{DIM} @tab (Optional) Shall be a scalar @code{INTEGER}.
7352 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
7353 expression indicating the kind parameter of the result.
7356 @item @emph{Return value}:
7357 The return value is of type @code{INTEGER} and of kind @var{KIND}. If
7358 @var{KIND} is absent, the return value is of default integer kind.
7359 If @var{DIM} is absent, the result is an array of the lower bounds of
7360 @var{ARRAY}. If @var{DIM} is present, the result is a scalar
7361 corresponding to the lower bound of the array along that dimension. If
7362 @var{ARRAY} is an expression rather than a whole array or array
7363 structure component, or if it has a zero extent along the relevant
7364 dimension, the lower bound is taken to be 1.
7366 @item @emph{See also}:
7367 @ref{UBOUND}, @ref{LCOBOUND}
7373 @section @code{LCOBOUND} --- Lower codimension bounds of an array
7375 @cindex coarray, lower bound
7378 @item @emph{Description}:
7379 Returns the lower bounds of a coarray, or a single lower cobound
7380 along the @var{DIM} codimension.
7381 @item @emph{Standard}:
7382 Fortran 2008 and later
7387 @item @emph{Syntax}:
7388 @code{RESULT = LCOBOUND(COARRAY [, DIM [, KIND]])}
7390 @item @emph{Arguments}:
7391 @multitable @columnfractions .15 .70
7392 @item @var{ARRAY} @tab Shall be an coarray, of any type.
7393 @item @var{DIM} @tab (Optional) Shall be a scalar @code{INTEGER}.
7394 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
7395 expression indicating the kind parameter of the result.
7398 @item @emph{Return value}:
7399 The return value is of type @code{INTEGER} and of kind @var{KIND}. If
7400 @var{KIND} is absent, the return value is of default integer kind.
7401 If @var{DIM} is absent, the result is an array of the lower cobounds of
7402 @var{COARRAY}. If @var{DIM} is present, the result is a scalar
7403 corresponding to the lower cobound of the array along that codimension.
7405 @item @emph{See also}:
7406 @ref{UCOBOUND}, @ref{LBOUND}
7412 @section @code{LEADZ} --- Number of leading zero bits of an integer
7417 @item @emph{Description}:
7418 @code{LEADZ} returns the number of leading zero bits of an integer.
7420 @item @emph{Standard}:
7421 Fortran 2008 and later
7426 @item @emph{Syntax}:
7427 @code{RESULT = LEADZ(I)}
7429 @item @emph{Arguments}:
7430 @multitable @columnfractions .15 .70
7431 @item @var{I} @tab Shall be of type @code{INTEGER}.
7434 @item @emph{Return value}:
7435 The type of the return value is the default @code{INTEGER}.
7436 If all the bits of @code{I} are zero, the result value is @code{BIT_SIZE(I)}.
7438 @item @emph{Example}:
7441 WRITE (*,*) BIT_SIZE(1) ! prints 32
7442 WRITE (*,*) LEADZ(1) ! prints 31
7446 @item @emph{See also}:
7447 @ref{BIT_SIZE}, @ref{TRAILZ}, @ref{POPCNT}, @ref{POPPAR}
7453 @section @code{LEN} --- Length of a character entity
7455 @cindex string, length
7458 @item @emph{Description}:
7459 Returns the length of a character string. If @var{STRING} is an array,
7460 the length of an element of @var{STRING} is returned. Note that
7461 @var{STRING} need not be defined when this intrinsic is invoked, since
7462 only the length, not the content, of @var{STRING} is needed.
7464 @item @emph{Standard}:
7465 Fortran 77 and later, with @var{KIND} argument Fortran 2003 and later
7470 @item @emph{Syntax}:
7471 @code{L = LEN(STRING [, KIND])}
7473 @item @emph{Arguments}:
7474 @multitable @columnfractions .15 .70
7475 @item @var{STRING} @tab Shall be a scalar or array of type
7476 @code{CHARACTER}, with @code{INTENT(IN)}
7477 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
7478 expression indicating the kind parameter of the result.
7481 @item @emph{Return value}:
7482 The return value is of type @code{INTEGER} and of kind @var{KIND}. If
7483 @var{KIND} is absent, the return value is of default integer kind.
7486 @item @emph{Specific names}:
7487 @multitable @columnfractions .20 .20 .20 .25
7488 @item Name @tab Argument @tab Return type @tab Standard
7489 @item @code{LEN(STRING)} @tab @code{CHARACTER} @tab @code{INTEGER} @tab Fortran 77 and later
7493 @item @emph{See also}:
7494 @ref{LEN_TRIM}, @ref{ADJUSTL}, @ref{ADJUSTR}
7500 @section @code{LEN_TRIM} --- Length of a character entity without trailing blank characters
7502 @cindex string, length, without trailing whitespace
7505 @item @emph{Description}:
7506 Returns the length of a character string, ignoring any trailing blanks.
7508 @item @emph{Standard}:
7509 Fortran 95 and later, with @var{KIND} argument Fortran 2003 and later
7514 @item @emph{Syntax}:
7515 @code{RESULT = LEN_TRIM(STRING [, KIND])}
7517 @item @emph{Arguments}:
7518 @multitable @columnfractions .15 .70
7519 @item @var{STRING} @tab Shall be a scalar of type @code{CHARACTER},
7520 with @code{INTENT(IN)}
7521 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
7522 expression indicating the kind parameter of the result.
7525 @item @emph{Return value}:
7526 The return value is of type @code{INTEGER} and of kind @var{KIND}. If
7527 @var{KIND} is absent, the return value is of default integer kind.
7529 @item @emph{See also}:
7530 @ref{LEN}, @ref{ADJUSTL}, @ref{ADJUSTR}
7536 @section @code{LGE} --- Lexical greater than or equal
7538 @cindex lexical comparison of strings
7539 @cindex string, comparison
7542 @item @emph{Description}:
7543 Determines whether one string is lexically greater than or equal to
7544 another string, where the two strings are interpreted as containing
7545 ASCII character codes. If the String A and String B are not the same
7546 length, the shorter is compared as if spaces were appended to it to form
7547 a value that has the same length as the longer.
7549 In general, the lexical comparison intrinsics @code{LGE}, @code{LGT},
7550 @code{LLE}, and @code{LLT} differ from the corresponding intrinsic
7551 operators @code{.GE.}, @code{.GT.}, @code{.LE.}, and @code{.LT.}, in
7552 that the latter use the processor's character ordering (which is not
7553 ASCII on some targets), whereas the former always use the ASCII
7556 @item @emph{Standard}:
7557 Fortran 77 and later
7562 @item @emph{Syntax}:
7563 @code{RESULT = LGE(STRING_A, STRING_B)}
7565 @item @emph{Arguments}:
7566 @multitable @columnfractions .15 .70
7567 @item @var{STRING_A} @tab Shall be of default @code{CHARACTER} type.
7568 @item @var{STRING_B} @tab Shall be of default @code{CHARACTER} type.
7571 @item @emph{Return value}:
7572 Returns @code{.TRUE.} if @code{STRING_A >= STRING_B}, and @code{.FALSE.}
7573 otherwise, based on the ASCII ordering.
7575 @item @emph{Specific names}:
7576 @multitable @columnfractions .20 .20 .20 .25
7577 @item Name @tab Argument @tab Return type @tab Standard
7578 @item @code{LGE(STRING_A, STRING_B)} @tab @code{CHARACTER} @tab @code{LOGICAL} @tab Fortran 77 and later
7581 @item @emph{See also}:
7582 @ref{LGT}, @ref{LLE}, @ref{LLT}
7588 @section @code{LGT} --- Lexical greater than
7590 @cindex lexical comparison of strings
7591 @cindex string, comparison
7594 @item @emph{Description}:
7595 Determines whether one string is lexically greater than another string,
7596 where the two strings are interpreted as containing ASCII character
7597 codes. If the String A and String B are not the same length, the
7598 shorter is compared as if spaces were appended to it to form a value
7599 that has the same length as the longer.
7601 In general, the lexical comparison intrinsics @code{LGE}, @code{LGT},
7602 @code{LLE}, and @code{LLT} differ from the corresponding intrinsic
7603 operators @code{.GE.}, @code{.GT.}, @code{.LE.}, and @code{.LT.}, in
7604 that the latter use the processor's character ordering (which is not
7605 ASCII on some targets), whereas the former always use the ASCII
7608 @item @emph{Standard}:
7609 Fortran 77 and later
7614 @item @emph{Syntax}:
7615 @code{RESULT = LGT(STRING_A, STRING_B)}
7617 @item @emph{Arguments}:
7618 @multitable @columnfractions .15 .70
7619 @item @var{STRING_A} @tab Shall be of default @code{CHARACTER} type.
7620 @item @var{STRING_B} @tab Shall be of default @code{CHARACTER} type.
7623 @item @emph{Return value}:
7624 Returns @code{.TRUE.} if @code{STRING_A > STRING_B}, and @code{.FALSE.}
7625 otherwise, based on the ASCII ordering.
7627 @item @emph{Specific names}:
7628 @multitable @columnfractions .20 .20 .20 .25
7629 @item Name @tab Argument @tab Return type @tab Standard
7630 @item @code{LGT(STRING_A, STRING_B)} @tab @code{CHARACTER} @tab @code{LOGICAL} @tab Fortran 77 and later
7633 @item @emph{See also}:
7634 @ref{LGE}, @ref{LLE}, @ref{LLT}
7640 @section @code{LINK} --- Create a hard link
7642 @cindex file system, create link
7643 @cindex file system, hard link
7646 @item @emph{Description}:
7647 Makes a (hard) link from file @var{PATH1} to @var{PATH2}. A null
7648 character (@code{CHAR(0)}) can be used to mark the end of the names in
7649 @var{PATH1} and @var{PATH2}; otherwise, trailing blanks in the file
7650 names are ignored. If the @var{STATUS} argument is supplied, it
7651 contains 0 on success or a nonzero error code upon return; see
7654 This intrinsic is provided in both subroutine and function forms;
7655 however, only one form can be used in any given program unit.
7657 @item @emph{Standard}:
7661 Subroutine, function
7663 @item @emph{Syntax}:
7664 @multitable @columnfractions .80
7665 @item @code{CALL LINK(PATH1, PATH2 [, STATUS])}
7666 @item @code{STATUS = LINK(PATH1, PATH2)}
7669 @item @emph{Arguments}:
7670 @multitable @columnfractions .15 .70
7671 @item @var{PATH1} @tab Shall be of default @code{CHARACTER} type.
7672 @item @var{PATH2} @tab Shall be of default @code{CHARACTER} type.
7673 @item @var{STATUS} @tab (Optional) Shall be of default @code{INTEGER} type.
7676 @item @emph{See also}:
7677 @ref{SYMLNK}, @ref{UNLINK}
7683 @section @code{LLE} --- Lexical less than or equal
7685 @cindex lexical comparison of strings
7686 @cindex string, comparison
7689 @item @emph{Description}:
7690 Determines whether one string is lexically less than or equal to another
7691 string, where the two strings are interpreted as containing ASCII
7692 character codes. If the String A and String B are not the same length,
7693 the shorter is compared as if spaces were appended to it to form a value
7694 that has the same length as the longer.
7696 In general, the lexical comparison intrinsics @code{LGE}, @code{LGT},
7697 @code{LLE}, and @code{LLT} differ from the corresponding intrinsic
7698 operators @code{.GE.}, @code{.GT.}, @code{.LE.}, and @code{.LT.}, in
7699 that the latter use the processor's character ordering (which is not
7700 ASCII on some targets), whereas the former always use the ASCII
7703 @item @emph{Standard}:
7704 Fortran 77 and later
7709 @item @emph{Syntax}:
7710 @code{RESULT = LLE(STRING_A, STRING_B)}
7712 @item @emph{Arguments}:
7713 @multitable @columnfractions .15 .70
7714 @item @var{STRING_A} @tab Shall be of default @code{CHARACTER} type.
7715 @item @var{STRING_B} @tab Shall be of default @code{CHARACTER} type.
7718 @item @emph{Return value}:
7719 Returns @code{.TRUE.} if @code{STRING_A <= STRING_B}, and @code{.FALSE.}
7720 otherwise, based on the ASCII ordering.
7722 @item @emph{Specific names}:
7723 @multitable @columnfractions .20 .20 .20 .25
7724 @item Name @tab Argument @tab Return type @tab Standard
7725 @item @code{LLE(STRING_A, STRING_B)} @tab @code{CHARACTER} @tab @code{LOGICAL} @tab Fortran 77 and later
7728 @item @emph{See also}:
7729 @ref{LGE}, @ref{LGT}, @ref{LLT}
7735 @section @code{LLT} --- Lexical less than
7737 @cindex lexical comparison of strings
7738 @cindex string, comparison
7741 @item @emph{Description}:
7742 Determines whether one string is lexically less than another string,
7743 where the two strings are interpreted as containing ASCII character
7744 codes. If the String A and String B are not the same length, the
7745 shorter is compared as if spaces were appended to it to form a value
7746 that has the same length as the longer.
7748 In general, the lexical comparison intrinsics @code{LGE}, @code{LGT},
7749 @code{LLE}, and @code{LLT} differ from the corresponding intrinsic
7750 operators @code{.GE.}, @code{.GT.}, @code{.LE.}, and @code{.LT.}, in
7751 that the latter use the processor's character ordering (which is not
7752 ASCII on some targets), whereas the former always use the ASCII
7755 @item @emph{Standard}:
7756 Fortran 77 and later
7761 @item @emph{Syntax}:
7762 @code{RESULT = LLT(STRING_A, STRING_B)}
7764 @item @emph{Arguments}:
7765 @multitable @columnfractions .15 .70
7766 @item @var{STRING_A} @tab Shall be of default @code{CHARACTER} type.
7767 @item @var{STRING_B} @tab Shall be of default @code{CHARACTER} type.
7770 @item @emph{Return value}:
7771 Returns @code{.TRUE.} if @code{STRING_A < STRING_B}, and @code{.FALSE.}
7772 otherwise, based on the ASCII ordering.
7774 @item @emph{Specific names}:
7775 @multitable @columnfractions .20 .20 .20 .25
7776 @item Name @tab Argument @tab Return type @tab Standard
7777 @item @code{LLT(STRING_A, STRING_B)} @tab @code{CHARACTER} @tab @code{LOGICAL} @tab Fortran 77 and later
7780 @item @emph{See also}:
7781 @ref{LGE}, @ref{LGT}, @ref{LLE}
7787 @section @code{LNBLNK} --- Index of the last non-blank character in a string
7789 @cindex string, find non-blank character
7792 @item @emph{Description}:
7793 Returns the length of a character string, ignoring any trailing blanks.
7794 This is identical to the standard @code{LEN_TRIM} intrinsic, and is only
7795 included for backwards compatibility.
7797 @item @emph{Standard}:
7803 @item @emph{Syntax}:
7804 @code{RESULT = LNBLNK(STRING)}
7806 @item @emph{Arguments}:
7807 @multitable @columnfractions .15 .70
7808 @item @var{STRING} @tab Shall be a scalar of type @code{CHARACTER},
7809 with @code{INTENT(IN)}
7812 @item @emph{Return value}:
7813 The return value is of @code{INTEGER(kind=4)} type.
7815 @item @emph{See also}:
7816 @ref{INDEX intrinsic}, @ref{LEN_TRIM}
7822 @section @code{LOC} --- Returns the address of a variable
7824 @cindex location of a variable in memory
7827 @item @emph{Description}:
7828 @code{LOC(X)} returns the address of @var{X} as an integer.
7830 @item @emph{Standard}:
7836 @item @emph{Syntax}:
7837 @code{RESULT = LOC(X)}
7839 @item @emph{Arguments}:
7840 @multitable @columnfractions .15 .70
7841 @item @var{X} @tab Variable of any type.
7844 @item @emph{Return value}:
7845 The return value is of type @code{INTEGER}, with a @code{KIND}
7846 corresponding to the size (in bytes) of a memory address on the target
7849 @item @emph{Example}:
7856 end program test_loc
7863 @section @code{LOG} --- Natural logarithm function
7870 @cindex exponential function, inverse
7871 @cindex logarithm function
7872 @cindex natural logarithm function
7875 @item @emph{Description}:
7876 @code{LOG(X)} computes the natural logarithm of @var{X}, i.e. the
7877 logarithm to the base @math{e}.
7879 @item @emph{Standard}:
7880 Fortran 77 and later
7885 @item @emph{Syntax}:
7886 @code{RESULT = LOG(X)}
7888 @item @emph{Arguments}:
7889 @multitable @columnfractions .15 .70
7890 @item @var{X} @tab The type shall be @code{REAL} or
7894 @item @emph{Return value}:
7895 The return value is of type @code{REAL} or @code{COMPLEX}.
7896 The kind type parameter is the same as @var{X}.
7897 If @var{X} is @code{COMPLEX}, the imaginary part @math{\omega} is in the range
7898 @math{-\pi \leq \omega \leq \pi}.
7900 @item @emph{Example}:
7903 real(8) :: x = 2.7182818284590451_8
7904 complex :: z = (1.0, 2.0)
7905 x = log(x) ! will yield (approximately) 1
7907 end program test_log
7910 @item @emph{Specific names}:
7911 @multitable @columnfractions .20 .20 .20 .25
7912 @item Name @tab Argument @tab Return type @tab Standard
7913 @item @code{ALOG(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab f95, gnu
7914 @item @code{DLOG(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab f95, gnu
7915 @item @code{CLOG(X)} @tab @code{COMPLEX(4) X} @tab @code{COMPLEX(4)} @tab f95, gnu
7916 @item @code{ZLOG(X)} @tab @code{COMPLEX(8) X} @tab @code{COMPLEX(8)} @tab f95, gnu
7917 @item @code{CDLOG(X)} @tab @code{COMPLEX(8) X} @tab @code{COMPLEX(8)} @tab f95, gnu
7924 @section @code{LOG10} --- Base 10 logarithm function
7928 @cindex exponential function, inverse
7929 @cindex logarithm function with base 10
7930 @cindex base 10 logarithm function
7933 @item @emph{Description}:
7934 @code{LOG10(X)} computes the base 10 logarithm of @var{X}.
7936 @item @emph{Standard}:
7937 Fortran 77 and later
7942 @item @emph{Syntax}:
7943 @code{RESULT = LOG10(X)}
7945 @item @emph{Arguments}:
7946 @multitable @columnfractions .15 .70
7947 @item @var{X} @tab The type shall be @code{REAL}.
7950 @item @emph{Return value}:
7951 The return value is of type @code{REAL} or @code{COMPLEX}.
7952 The kind type parameter is the same as @var{X}.
7954 @item @emph{Example}:
7957 real(8) :: x = 10.0_8
7959 end program test_log10
7962 @item @emph{Specific names}:
7963 @multitable @columnfractions .20 .20 .20 .25
7964 @item Name @tab Argument @tab Return type @tab Standard
7965 @item @code{ALOG10(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab Fortran 95 and later
7966 @item @code{DLOG10(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab Fortran 95 and later
7973 @section @code{LOG_GAMMA} --- Logarithm of the Gamma function
7978 @cindex Gamma function, logarithm of
7981 @item @emph{Description}:
7982 @code{LOG_GAMMA(X)} computes the natural logarithm of the absolute value
7983 of the Gamma (@math{\Gamma}) function.
7985 @item @emph{Standard}:
7986 Fortran 2008 and later
7991 @item @emph{Syntax}:
7992 @code{X = LOG_GAMMA(X)}
7994 @item @emph{Arguments}:
7995 @multitable @columnfractions .15 .70
7996 @item @var{X} @tab Shall be of type @code{REAL} and neither zero
7997 nor a negative integer.
8000 @item @emph{Return value}:
8001 The return value is of type @code{REAL} of the same kind as @var{X}.
8003 @item @emph{Example}:
8005 program test_log_gamma
8007 x = lgamma(x) ! returns 0.0
8008 end program test_log_gamma
8011 @item @emph{Specific names}:
8012 @multitable @columnfractions .20 .20 .20 .25
8013 @item Name @tab Argument @tab Return type @tab Standard
8014 @item @code{LGAMMA(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab GNU Extension
8015 @item @code{ALGAMA(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab GNU Extension
8016 @item @code{DLGAMA(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU Extension
8019 @item @emph{See also}:
8020 Gamma function: @ref{GAMMA}
8027 @section @code{LOGICAL} --- Convert to logical type
8029 @cindex conversion, to logical
8032 @item @emph{Description}:
8033 Converts one kind of @code{LOGICAL} variable to another.
8035 @item @emph{Standard}:
8036 Fortran 95 and later
8041 @item @emph{Syntax}:
8042 @code{RESULT = LOGICAL(L [, KIND])}
8044 @item @emph{Arguments}:
8045 @multitable @columnfractions .15 .70
8046 @item @var{L} @tab The type shall be @code{LOGICAL}.
8047 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
8048 expression indicating the kind parameter of the result.
8051 @item @emph{Return value}:
8052 The return value is a @code{LOGICAL} value equal to @var{L}, with a
8053 kind corresponding to @var{KIND}, or of the default logical kind if
8054 @var{KIND} is not given.
8056 @item @emph{See also}:
8057 @ref{INT}, @ref{REAL}, @ref{CMPLX}
8063 @section @code{LONG} --- Convert to integer type
8065 @cindex conversion, to integer
8068 @item @emph{Description}:
8069 Convert to a @code{KIND=4} integer type, which is the same size as a C
8070 @code{long} integer. This is equivalent to the standard @code{INT}
8071 intrinsic with an optional argument of @code{KIND=4}, and is only
8072 included for backwards compatibility.
8074 @item @emph{Standard}:
8080 @item @emph{Syntax}:
8081 @code{RESULT = LONG(A)}
8083 @item @emph{Arguments}:
8084 @multitable @columnfractions .15 .70
8085 @item @var{A} @tab Shall be of type @code{INTEGER},
8086 @code{REAL}, or @code{COMPLEX}.
8089 @item @emph{Return value}:
8090 The return value is a @code{INTEGER(4)} variable.
8092 @item @emph{See also}:
8093 @ref{INT}, @ref{INT2}, @ref{INT8}
8099 @section @code{LSHIFT} --- Left shift bits
8101 @cindex bits, shift left
8104 @item @emph{Description}:
8105 @code{LSHIFT} returns a value corresponding to @var{I} with all of the
8106 bits shifted left by @var{SHIFT} places. If the absolute value of
8107 @var{SHIFT} is greater than @code{BIT_SIZE(I)}, the value is undefined.
8108 Bits shifted out from the left end are lost; zeros are shifted in from
8111 This function has been superseded by the @code{ISHFT} intrinsic, which
8112 is standard in Fortran 95 and later, and the @code{SHIFTL} intrinsic,
8113 which is standard in Fortran 2008 and later.
8115 @item @emph{Standard}:
8121 @item @emph{Syntax}:
8122 @code{RESULT = LSHIFT(I, SHIFT)}
8124 @item @emph{Arguments}:
8125 @multitable @columnfractions .15 .70
8126 @item @var{I} @tab The type shall be @code{INTEGER}.
8127 @item @var{SHIFT} @tab The type shall be @code{INTEGER}.
8130 @item @emph{Return value}:
8131 The return value is of type @code{INTEGER} and of the same kind as
8134 @item @emph{See also}:
8135 @ref{ISHFT}, @ref{ISHFTC}, @ref{RSHIFT}, @ref{SHIFTA}, @ref{SHIFTL},
8143 @section @code{LSTAT} --- Get file status
8145 @cindex file system, file status
8148 @item @emph{Description}:
8149 @code{LSTAT} is identical to @ref{STAT}, except that if path is a
8150 symbolic link, then the link itself is statted, not the file that it
8153 The elements in @code{VALUES} are the same as described by @ref{STAT}.
8155 This intrinsic is provided in both subroutine and function forms;
8156 however, only one form can be used in any given program unit.
8158 @item @emph{Standard}:
8162 Subroutine, function
8164 @item @emph{Syntax}:
8165 @multitable @columnfractions .80
8166 @item @code{CALL LSTAT(NAME, VALUES [, STATUS])}
8167 @item @code{STATUS = LSTAT(NAME, VALUES)}
8170 @item @emph{Arguments}:
8171 @multitable @columnfractions .15 .70
8172 @item @var{NAME} @tab The type shall be @code{CHARACTER} of the default
8173 kind, a valid path within the file system.
8174 @item @var{VALUES} @tab The type shall be @code{INTEGER(4), DIMENSION(13)}.
8175 @item @var{STATUS} @tab (Optional) status flag of type @code{INTEGER(4)}.
8176 Returns 0 on success and a system specific error code otherwise.
8179 @item @emph{Example}:
8180 See @ref{STAT} for an example.
8182 @item @emph{See also}:
8183 To stat an open file: @ref{FSTAT}, to stat a file: @ref{STAT}
8189 @section @code{LTIME} --- Convert time to local time info
8191 @cindex time, conversion to local time info
8194 @item @emph{Description}:
8195 Given a system time value @var{TIME} (as provided by the @code{TIME8}
8196 intrinsic), fills @var{VALUES} with values extracted from it appropriate
8197 to the local time zone using @code{localtime(3)}.
8199 @item @emph{Standard}:
8205 @item @emph{Syntax}:
8206 @code{CALL LTIME(TIME, VALUES)}
8208 @item @emph{Arguments}:
8209 @multitable @columnfractions .15 .70
8210 @item @var{TIME} @tab An @code{INTEGER} scalar expression
8211 corresponding to a system time, with @code{INTENT(IN)}.
8212 @item @var{VALUES} @tab A default @code{INTEGER} array with 9 elements,
8213 with @code{INTENT(OUT)}.
8216 @item @emph{Return value}:
8217 The elements of @var{VALUES} are assigned as follows:
8219 @item Seconds after the minute, range 0--59 or 0--61 to allow for leap
8221 @item Minutes after the hour, range 0--59
8222 @item Hours past midnight, range 0--23
8223 @item Day of month, range 0--31
8224 @item Number of months since January, range 0--12
8225 @item Years since 1900
8226 @item Number of days since Sunday, range 0--6
8227 @item Days since January 1
8228 @item Daylight savings indicator: positive if daylight savings is in
8229 effect, zero if not, and negative if the information is not available.
8232 @item @emph{See also}:
8233 @ref{CTIME}, @ref{GMTIME}, @ref{TIME}, @ref{TIME8}
8240 @section @code{MALLOC} --- Allocate dynamic memory
8242 @cindex pointer, cray
8245 @item @emph{Description}:
8246 @code{MALLOC(SIZE)} allocates @var{SIZE} bytes of dynamic memory and
8247 returns the address of the allocated memory. The @code{MALLOC} intrinsic
8248 is an extension intended to be used with Cray pointers, and is provided
8249 in GNU Fortran to allow the user to compile legacy code. For new code
8250 using Fortran 95 pointers, the memory allocation intrinsic is
8253 @item @emph{Standard}:
8259 @item @emph{Syntax}:
8260 @code{PTR = MALLOC(SIZE)}
8262 @item @emph{Arguments}:
8263 @multitable @columnfractions .15 .70
8264 @item @var{SIZE} @tab The type shall be @code{INTEGER}.
8267 @item @emph{Return value}:
8268 The return value is of type @code{INTEGER(K)}, with @var{K} such that
8269 variables of type @code{INTEGER(K)} have the same size as
8270 C pointers (@code{sizeof(void *)}).
8272 @item @emph{Example}:
8273 The following example demonstrates the use of @code{MALLOC} and
8274 @code{FREE} with Cray pointers.
8283 ptr_x = malloc(20*8)
8285 x(i) = sqrt(1.0d0 / i)
8293 end program test_malloc
8296 @item @emph{See also}:
8303 @section @code{MASKL} --- Left justified mask
8305 @cindex mask, left justified
8308 @item @emph{Description}:
8309 @code{MASKL(I[, KIND])} has its leftmost @var{I} bits set to 1, and the
8310 remaining bits set to 0.
8312 @item @emph{Standard}:
8313 Fortran 2008 and later
8318 @item @emph{Syntax}:
8319 @code{RESULT = MASKL(I[, KIND])}
8321 @item @emph{Arguments}:
8322 @multitable @columnfractions .15 .70
8323 @item @var{I} @tab Shall be of type @code{INTEGER}.
8324 @item @var{KIND} @tab Shall be a scalar constant expression of type
8328 @item @emph{Return value}:
8329 The return value is of type @code{INTEGER}. If @var{KIND} is present, it
8330 specifies the kind value of the return type; otherwise, it is of the
8331 default integer kind.
8333 @item @emph{See also}:
8340 @section @code{MASKR} --- Right justified mask
8342 @cindex mask, right justified
8345 @item @emph{Description}:
8346 @code{MASKL(I[, KIND])} has its rightmost @var{I} bits set to 1, and the
8347 remaining bits set to 0.
8349 @item @emph{Standard}:
8350 Fortran 2008 and later
8355 @item @emph{Syntax}:
8356 @code{RESULT = MASKR(I[, KIND])}
8358 @item @emph{Arguments}:
8359 @multitable @columnfractions .15 .70
8360 @item @var{I} @tab Shall be of type @code{INTEGER}.
8361 @item @var{KIND} @tab Shall be a scalar constant expression of type
8365 @item @emph{Return value}:
8366 The return value is of type @code{INTEGER}. If @var{KIND} is present, it
8367 specifies the kind value of the return type; otherwise, it is of the
8368 default integer kind.
8370 @item @emph{See also}:
8377 @section @code{MATMUL} --- matrix multiplication
8379 @cindex matrix multiplication
8380 @cindex product, matrix
8383 @item @emph{Description}:
8384 Performs a matrix multiplication on numeric or logical arguments.
8386 @item @emph{Standard}:
8387 Fortran 95 and later
8390 Transformational function
8392 @item @emph{Syntax}:
8393 @code{RESULT = MATMUL(MATRIX_A, MATRIX_B)}
8395 @item @emph{Arguments}:
8396 @multitable @columnfractions .15 .70
8397 @item @var{MATRIX_A} @tab An array of @code{INTEGER},
8398 @code{REAL}, @code{COMPLEX}, or @code{LOGICAL} type, with a rank of
8400 @item @var{MATRIX_B} @tab An array of @code{INTEGER},
8401 @code{REAL}, or @code{COMPLEX} type if @var{MATRIX_A} is of a numeric
8402 type; otherwise, an array of @code{LOGICAL} type. The rank shall be one
8403 or two, and the first (or only) dimension of @var{MATRIX_B} shall be
8404 equal to the last (or only) dimension of @var{MATRIX_A}.
8407 @item @emph{Return value}:
8408 The matrix product of @var{MATRIX_A} and @var{MATRIX_B}. The type and
8409 kind of the result follow the usual type and kind promotion rules, as
8410 for the @code{*} or @code{.AND.} operators.
8412 @item @emph{See also}:
8418 @section @code{MAX} --- Maximum value of an argument list
8425 @cindex maximum value
8428 @item @emph{Description}:
8429 Returns the argument with the largest (most positive) value.
8431 @item @emph{Standard}:
8432 Fortran 77 and later
8437 @item @emph{Syntax}:
8438 @code{RESULT = MAX(A1, A2 [, A3 [, ...]])}
8440 @item @emph{Arguments}:
8441 @multitable @columnfractions .15 .70
8442 @item @var{A1} @tab The type shall be @code{INTEGER} or
8444 @item @var{A2}, @var{A3}, ... @tab An expression of the same type and kind
8445 as @var{A1}. (As a GNU extension, arguments of different kinds are
8449 @item @emph{Return value}:
8450 The return value corresponds to the maximum value among the arguments,
8451 and has the same type and kind as the first argument.
8453 @item @emph{Specific names}:
8454 @multitable @columnfractions .20 .20 .20 .25
8455 @item Name @tab Argument @tab Return type @tab Standard
8456 @item @code{MAX0(A1)} @tab @code{INTEGER(4) A1} @tab @code{INTEGER(4)} @tab Fortran 77 and later
8457 @item @code{AMAX0(A1)} @tab @code{INTEGER(4) A1} @tab @code{REAL(MAX(X))} @tab Fortran 77 and later
8458 @item @code{MAX1(A1)} @tab @code{REAL A1} @tab @code{INT(MAX(X))} @tab Fortran 77 and later
8459 @item @code{AMAX1(A1)} @tab @code{REAL(4) A1} @tab @code{REAL(4)} @tab Fortran 77 and later
8460 @item @code{DMAX1(A1)} @tab @code{REAL(8) A1} @tab @code{REAL(8)} @tab Fortran 77 and later
8463 @item @emph{See also}:
8464 @ref{MAXLOC} @ref{MAXVAL}, @ref{MIN}
8471 @section @code{MAXEXPONENT} --- Maximum exponent of a real kind
8472 @fnindex MAXEXPONENT
8473 @cindex model representation, maximum exponent
8476 @item @emph{Description}:
8477 @code{MAXEXPONENT(X)} returns the maximum exponent in the model of the
8480 @item @emph{Standard}:
8481 Fortran 95 and later
8486 @item @emph{Syntax}:
8487 @code{RESULT = MAXEXPONENT(X)}
8489 @item @emph{Arguments}:
8490 @multitable @columnfractions .15 .70
8491 @item @var{X} @tab Shall be of type @code{REAL}.
8494 @item @emph{Return value}:
8495 The return value is of type @code{INTEGER} and of the default integer
8498 @item @emph{Example}:
8504 print *, minexponent(x), maxexponent(x)
8505 print *, minexponent(y), maxexponent(y)
8506 end program exponents
8513 @section @code{MAXLOC} --- Location of the maximum value within an array
8515 @cindex array, location of maximum element
8518 @item @emph{Description}:
8519 Determines the location of the element in the array with the maximum
8520 value, or, if the @var{DIM} argument is supplied, determines the
8521 locations of the maximum element along each row of the array in the
8522 @var{DIM} direction. If @var{MASK} is present, only the elements for
8523 which @var{MASK} is @code{.TRUE.} are considered. If more than one
8524 element in the array has the maximum value, the location returned is
8525 that of the first such element in array element order. If the array has
8526 zero size, or all of the elements of @var{MASK} are @code{.FALSE.}, then
8527 the result is an array of zeroes. Similarly, if @var{DIM} is supplied
8528 and all of the elements of @var{MASK} along a given row are zero, the
8529 result value for that row is zero.
8531 @item @emph{Standard}:
8532 Fortran 95 and later
8535 Transformational function
8537 @item @emph{Syntax}:
8538 @multitable @columnfractions .80
8539 @item @code{RESULT = MAXLOC(ARRAY, DIM [, MASK])}
8540 @item @code{RESULT = MAXLOC(ARRAY [, MASK])}
8543 @item @emph{Arguments}:
8544 @multitable @columnfractions .15 .70
8545 @item @var{ARRAY} @tab Shall be an array of type @code{INTEGER} or
8547 @item @var{DIM} @tab (Optional) Shall be a scalar of type
8548 @code{INTEGER}, with a value between one and the rank of @var{ARRAY},
8549 inclusive. It may not be an optional dummy argument.
8550 @item @var{MASK} @tab Shall be an array of type @code{LOGICAL},
8551 and conformable with @var{ARRAY}.
8554 @item @emph{Return value}:
8555 If @var{DIM} is absent, the result is a rank-one array with a length
8556 equal to the rank of @var{ARRAY}. If @var{DIM} is present, the result
8557 is an array with a rank one less than the rank of @var{ARRAY}, and a
8558 size corresponding to the size of @var{ARRAY} with the @var{DIM}
8559 dimension removed. If @var{DIM} is present and @var{ARRAY} has a rank
8560 of one, the result is a scalar. In all cases, the result is of default
8561 @code{INTEGER} type.
8563 @item @emph{See also}:
8564 @ref{MAX}, @ref{MAXVAL}
8571 @section @code{MAXVAL} --- Maximum value of an array
8573 @cindex array, maximum value
8574 @cindex maximum value
8577 @item @emph{Description}:
8578 Determines the maximum value of the elements in an array value, or, if
8579 the @var{DIM} argument is supplied, determines the maximum value along
8580 each row of the array in the @var{DIM} direction. If @var{MASK} is
8581 present, only the elements for which @var{MASK} is @code{.TRUE.} are
8582 considered. If the array has zero size, or all of the elements of
8583 @var{MASK} are @code{.FALSE.}, then the result is @code{-HUGE(ARRAY)}
8584 if @var{ARRAY} is numeric, or a string of nulls if @var{ARRAY} is of character
8587 @item @emph{Standard}:
8588 Fortran 95 and later
8591 Transformational function
8593 @item @emph{Syntax}:
8594 @multitable @columnfractions .80
8595 @item @code{RESULT = MAXVAL(ARRAY, DIM [, MASK])}
8596 @item @code{RESULT = MAXVAL(ARRAY [, MASK])}
8599 @item @emph{Arguments}:
8600 @multitable @columnfractions .15 .70
8601 @item @var{ARRAY} @tab Shall be an array of type @code{INTEGER} or
8603 @item @var{DIM} @tab (Optional) Shall be a scalar of type
8604 @code{INTEGER}, with a value between one and the rank of @var{ARRAY},
8605 inclusive. It may not be an optional dummy argument.
8606 @item @var{MASK} @tab Shall be an array of type @code{LOGICAL},
8607 and conformable with @var{ARRAY}.
8610 @item @emph{Return value}:
8611 If @var{DIM} is absent, or if @var{ARRAY} has a rank of one, the result
8612 is a scalar. If @var{DIM} is present, the result is an array with a
8613 rank one less than the rank of @var{ARRAY}, and a size corresponding to
8614 the size of @var{ARRAY} with the @var{DIM} dimension removed. In all
8615 cases, the result is of the same type and kind as @var{ARRAY}.
8617 @item @emph{See also}:
8618 @ref{MAX}, @ref{MAXLOC}
8624 @section @code{MCLOCK} --- Time function
8626 @cindex time, clock ticks
8630 @item @emph{Description}:
8631 Returns the number of clock ticks since the start of the process, based
8632 on the UNIX function @code{clock(3)}.
8634 This intrinsic is not fully portable, such as to systems with 32-bit
8635 @code{INTEGER} types but supporting times wider than 32 bits. Therefore,
8636 the values returned by this intrinsic might be, or become, negative, or
8637 numerically less than previous values, during a single run of the
8640 @item @emph{Standard}:
8646 @item @emph{Syntax}:
8647 @code{RESULT = MCLOCK()}
8649 @item @emph{Return value}:
8650 The return value is a scalar of type @code{INTEGER(4)}, equal to the
8651 number of clock ticks since the start of the process, or @code{-1} if
8652 the system does not support @code{clock(3)}.
8654 @item @emph{See also}:
8655 @ref{CTIME}, @ref{GMTIME}, @ref{LTIME}, @ref{MCLOCK}, @ref{TIME}
8662 @section @code{MCLOCK8} --- Time function (64-bit)
8664 @cindex time, clock ticks
8668 @item @emph{Description}:
8669 Returns the number of clock ticks since the start of the process, based
8670 on the UNIX function @code{clock(3)}.
8672 @emph{Warning:} this intrinsic does not increase the range of the timing
8673 values over that returned by @code{clock(3)}. On a system with a 32-bit
8674 @code{clock(3)}, @code{MCLOCK8} will return a 32-bit value, even though
8675 it is converted to a 64-bit @code{INTEGER(8)} value. That means
8676 overflows of the 32-bit value can still occur. Therefore, the values
8677 returned by this intrinsic might be or become negative or numerically
8678 less than previous values during a single run of the compiled program.
8680 @item @emph{Standard}:
8686 @item @emph{Syntax}:
8687 @code{RESULT = MCLOCK8()}
8689 @item @emph{Return value}:
8690 The return value is a scalar of type @code{INTEGER(8)}, equal to the
8691 number of clock ticks since the start of the process, or @code{-1} if
8692 the system does not support @code{clock(3)}.
8694 @item @emph{See also}:
8695 @ref{CTIME}, @ref{GMTIME}, @ref{LTIME}, @ref{MCLOCK}, @ref{TIME8}
8702 @section @code{MERGE} --- Merge variables
8704 @cindex array, merge arrays
8705 @cindex array, combine arrays
8708 @item @emph{Description}:
8709 Select values from two arrays according to a logical mask. The result
8710 is equal to @var{TSOURCE} if @var{MASK} is @code{.TRUE.}, or equal to
8711 @var{FSOURCE} if it is @code{.FALSE.}.
8713 @item @emph{Standard}:
8714 Fortran 95 and later
8719 @item @emph{Syntax}:
8720 @code{RESULT = MERGE(TSOURCE, FSOURCE, MASK)}
8722 @item @emph{Arguments}:
8723 @multitable @columnfractions .15 .70
8724 @item @var{TSOURCE} @tab May be of any type.
8725 @item @var{FSOURCE} @tab Shall be of the same type and type parameters
8727 @item @var{MASK} @tab Shall be of type @code{LOGICAL}.
8730 @item @emph{Return value}:
8731 The result is of the same type and type parameters as @var{TSOURCE}.
8738 @section @code{MERGE_BITS} --- Merge of bits under mask
8743 @item @emph{Description}:
8744 @code{MERGE_BITS(I, J, MASK)} merges the bits of @var{I} and @var{J}
8745 as determined by the mask. The i-th bit of the result is equal to the
8746 i-th bit of @var{I} if the i-th bit of @var{MASK} is 1; it is equal to
8747 the i-th bit of @var{J} otherwise.
8749 @item @emph{Standard}:
8750 Fortran 2008 and later
8755 @item @emph{Syntax}:
8756 @code{RESULT = MERGE_BITS(I, J, MASK)}
8758 @item @emph{Arguments}:
8759 @multitable @columnfractions .15 .70
8760 @item @var{I} @tab Shall be of type @code{INTEGER}.
8761 @item @var{J} @tab Shall be of type @code{INTEGER} and of the same
8763 @item @var{MASK} @tab Shall be of type @code{INTEGER} and of the same
8767 @item @emph{Return value}:
8768 The result is of the same type and kind as @var{I}.
8775 @section @code{MIN} --- Minimum value of an argument list
8782 @cindex minimum value
8785 @item @emph{Description}:
8786 Returns the argument with the smallest (most negative) value.
8788 @item @emph{Standard}:
8789 Fortran 77 and later
8794 @item @emph{Syntax}:
8795 @code{RESULT = MIN(A1, A2 [, A3, ...])}
8797 @item @emph{Arguments}:
8798 @multitable @columnfractions .15 .70
8799 @item @var{A1} @tab The type shall be @code{INTEGER} or
8801 @item @var{A2}, @var{A3}, ... @tab An expression of the same type and kind
8802 as @var{A1}. (As a GNU extension, arguments of different kinds are
8806 @item @emph{Return value}:
8807 The return value corresponds to the maximum value among the arguments,
8808 and has the same type and kind as the first argument.
8810 @item @emph{Specific names}:
8811 @multitable @columnfractions .20 .20 .20 .25
8812 @item Name @tab Argument @tab Return type @tab Standard
8813 @item @code{MIN0(A1)} @tab @code{INTEGER(4) A1} @tab @code{INTEGER(4)} @tab Fortran 77 and later
8814 @item @code{AMIN0(A1)} @tab @code{INTEGER(4) A1} @tab @code{REAL(4)} @tab Fortran 77 and later
8815 @item @code{MIN1(A1)} @tab @code{REAL A1} @tab @code{INTEGER(4)} @tab Fortran 77 and later
8816 @item @code{AMIN1(A1)} @tab @code{REAL(4) A1} @tab @code{REAL(4)} @tab Fortran 77 and later
8817 @item @code{DMIN1(A1)} @tab @code{REAL(8) A1} @tab @code{REAL(8)} @tab Fortran 77 and later
8820 @item @emph{See also}:
8821 @ref{MAX}, @ref{MINLOC}, @ref{MINVAL}
8827 @section @code{MINEXPONENT} --- Minimum exponent of a real kind
8828 @fnindex MINEXPONENT
8829 @cindex model representation, minimum exponent
8832 @item @emph{Description}:
8833 @code{MINEXPONENT(X)} returns the minimum exponent in the model of the
8836 @item @emph{Standard}:
8837 Fortran 95 and later
8842 @item @emph{Syntax}:
8843 @code{RESULT = MINEXPONENT(X)}
8845 @item @emph{Arguments}:
8846 @multitable @columnfractions .15 .70
8847 @item @var{X} @tab Shall be of type @code{REAL}.
8850 @item @emph{Return value}:
8851 The return value is of type @code{INTEGER} and of the default integer
8854 @item @emph{Example}:
8855 See @code{MAXEXPONENT} for an example.
8861 @section @code{MINLOC} --- Location of the minimum value within an array
8863 @cindex array, location of minimum element
8866 @item @emph{Description}:
8867 Determines the location of the element in the array with the minimum
8868 value, or, if the @var{DIM} argument is supplied, determines the
8869 locations of the minimum element along each row of the array in the
8870 @var{DIM} direction. If @var{MASK} is present, only the elements for
8871 which @var{MASK} is @code{.TRUE.} are considered. If more than one
8872 element in the array has the minimum value, the location returned is
8873 that of the first such element in array element order. If the array has
8874 zero size, or all of the elements of @var{MASK} are @code{.FALSE.}, then
8875 the result is an array of zeroes. Similarly, if @var{DIM} is supplied
8876 and all of the elements of @var{MASK} along a given row are zero, the
8877 result value for that row is zero.
8879 @item @emph{Standard}:
8880 Fortran 95 and later
8883 Transformational function
8885 @item @emph{Syntax}:
8886 @multitable @columnfractions .80
8887 @item @code{RESULT = MINLOC(ARRAY, DIM [, MASK])}
8888 @item @code{RESULT = MINLOC(ARRAY [, MASK])}
8891 @item @emph{Arguments}:
8892 @multitable @columnfractions .15 .70
8893 @item @var{ARRAY} @tab Shall be an array of type @code{INTEGER} or
8895 @item @var{DIM} @tab (Optional) Shall be a scalar of type
8896 @code{INTEGER}, with a value between one and the rank of @var{ARRAY},
8897 inclusive. It may not be an optional dummy argument.
8898 @item @var{MASK} @tab Shall be an array of type @code{LOGICAL},
8899 and conformable with @var{ARRAY}.
8902 @item @emph{Return value}:
8903 If @var{DIM} is absent, the result is a rank-one array with a length
8904 equal to the rank of @var{ARRAY}. If @var{DIM} is present, the result
8905 is an array with a rank one less than the rank of @var{ARRAY}, and a
8906 size corresponding to the size of @var{ARRAY} with the @var{DIM}
8907 dimension removed. If @var{DIM} is present and @var{ARRAY} has a rank
8908 of one, the result is a scalar. In all cases, the result is of default
8909 @code{INTEGER} type.
8911 @item @emph{See also}:
8912 @ref{MIN}, @ref{MINVAL}
8919 @section @code{MINVAL} --- Minimum value of an array
8921 @cindex array, minimum value
8922 @cindex minimum value
8925 @item @emph{Description}:
8926 Determines the minimum value of the elements in an array value, or, if
8927 the @var{DIM} argument is supplied, determines the minimum value along
8928 each row of the array in the @var{DIM} direction. If @var{MASK} is
8929 present, only the elements for which @var{MASK} is @code{.TRUE.} are
8930 considered. If the array has zero size, or all of the elements of
8931 @var{MASK} are @code{.FALSE.}, then the result is @code{HUGE(ARRAY)} if
8932 @var{ARRAY} is numeric, or a string of @code{CHAR(255)} characters if
8933 @var{ARRAY} is of character type.
8935 @item @emph{Standard}:
8936 Fortran 95 and later
8939 Transformational function
8941 @item @emph{Syntax}:
8942 @multitable @columnfractions .80
8943 @item @code{RESULT = MINVAL(ARRAY, DIM [, MASK])}
8944 @item @code{RESULT = MINVAL(ARRAY [, MASK])}
8947 @item @emph{Arguments}:
8948 @multitable @columnfractions .15 .70
8949 @item @var{ARRAY} @tab Shall be an array of type @code{INTEGER} or
8951 @item @var{DIM} @tab (Optional) Shall be a scalar of type
8952 @code{INTEGER}, with a value between one and the rank of @var{ARRAY},
8953 inclusive. It may not be an optional dummy argument.
8954 @item @var{MASK} @tab Shall be an array of type @code{LOGICAL},
8955 and conformable with @var{ARRAY}.
8958 @item @emph{Return value}:
8959 If @var{DIM} is absent, or if @var{ARRAY} has a rank of one, the result
8960 is a scalar. If @var{DIM} is present, the result is an array with a
8961 rank one less than the rank of @var{ARRAY}, and a size corresponding to
8962 the size of @var{ARRAY} with the @var{DIM} dimension removed. In all
8963 cases, the result is of the same type and kind as @var{ARRAY}.
8965 @item @emph{See also}:
8966 @ref{MIN}, @ref{MINLOC}
8973 @section @code{MOD} --- Remainder function
8978 @cindex division, remainder
8981 @item @emph{Description}:
8982 @code{MOD(A,P)} computes the remainder of the division of A by P@. It is
8983 calculated as @code{A - (INT(A/P) * P)}.
8985 @item @emph{Standard}:
8986 Fortran 77 and later
8991 @item @emph{Syntax}:
8992 @code{RESULT = MOD(A, P)}
8994 @item @emph{Arguments}:
8995 @multitable @columnfractions .15 .70
8996 @item @var{A} @tab Shall be a scalar of type @code{INTEGER} or @code{REAL}
8997 @item @var{P} @tab Shall be a scalar of the same type as @var{A} and not
9001 @item @emph{Return value}:
9002 The kind of the return value is the result of cross-promoting
9003 the kinds of the arguments.
9005 @item @emph{Example}:
9009 print *, mod(17.5,5.5)
9010 print *, mod(17.5d0,5.5)
9011 print *, mod(17.5,5.5d0)
9014 print *, mod(-17.5,5.5)
9015 print *, mod(-17.5d0,5.5)
9016 print *, mod(-17.5,5.5d0)
9019 print *, mod(17.5,-5.5)
9020 print *, mod(17.5d0,-5.5)
9021 print *, mod(17.5,-5.5d0)
9022 end program test_mod
9025 @item @emph{Specific names}:
9026 @multitable @columnfractions .20 .20 .20 .25
9027 @item Name @tab Arguments @tab Return type @tab Standard
9028 @item @code{MOD(A,P)} @tab @code{INTEGER A,P} @tab @code{INTEGER} @tab Fortran 95 and later
9029 @item @code{AMOD(A,P)} @tab @code{REAL(4) A,P} @tab @code{REAL(4)} @tab Fortran 95 and later
9030 @item @code{DMOD(A,P)} @tab @code{REAL(8) A,P} @tab @code{REAL(8)} @tab Fortran 95 and later
9037 @section @code{MODULO} --- Modulo function
9040 @cindex division, modulo
9043 @item @emph{Description}:
9044 @code{MODULO(A,P)} computes the @var{A} modulo @var{P}.
9046 @item @emph{Standard}:
9047 Fortran 95 and later
9052 @item @emph{Syntax}:
9053 @code{RESULT = MODULO(A, P)}
9055 @item @emph{Arguments}:
9056 @multitable @columnfractions .15 .70
9057 @item @var{A} @tab Shall be a scalar of type @code{INTEGER} or @code{REAL}
9058 @item @var{P} @tab Shall be a scalar of the same type and kind as @var{A}
9061 @item @emph{Return value}:
9062 The type and kind of the result are those of the arguments.
9064 @item If @var{A} and @var{P} are of type @code{INTEGER}:
9065 @code{MODULO(A,P)} has the value @var{R} such that @code{A=Q*P+R}, where
9066 @var{Q} is an integer and @var{R} is between 0 (inclusive) and @var{P}
9068 @item If @var{A} and @var{P} are of type @code{REAL}:
9069 @code{MODULO(A,P)} has the value of @code{A - FLOOR (A / P) * P}.
9071 In all cases, if @var{P} is zero the result is processor-dependent.
9073 @item @emph{Example}:
9076 print *, modulo(17,3)
9077 print *, modulo(17.5,5.5)
9079 print *, modulo(-17,3)
9080 print *, modulo(-17.5,5.5)
9082 print *, modulo(17,-3)
9083 print *, modulo(17.5,-5.5)
9092 @section @code{MOVE_ALLOC} --- Move allocation from one object to another
9094 @cindex moving allocation
9095 @cindex allocation, moving
9098 @item @emph{Description}:
9099 @code{MOVE_ALLOC(FROM, TO)} moves the allocation from @var{FROM} to
9100 @var{TO}. @var{FROM} will become deallocated in the process.
9102 @item @emph{Standard}:
9103 Fortran 2003 and later
9108 @item @emph{Syntax}:
9109 @code{CALL MOVE_ALLOC(FROM, TO)}
9111 @item @emph{Arguments}:
9112 @multitable @columnfractions .15 .70
9113 @item @var{FROM} @tab @code{ALLOCATABLE}, @code{INTENT(INOUT)}, may be
9114 of any type and kind.
9115 @item @var{TO} @tab @code{ALLOCATABLE}, @code{INTENT(OUT)}, shall be
9116 of the same type, kind and rank as @var{FROM}.
9119 @item @emph{Return value}:
9122 @item @emph{Example}:
9124 program test_move_alloc
9125 integer, allocatable :: a(:), b(:)
9129 call move_alloc(a, b)
9130 print *, allocated(a), allocated(b)
9132 end program test_move_alloc
9139 @section @code{MVBITS} --- Move bits from one integer to another
9144 @item @emph{Description}:
9145 Moves @var{LEN} bits from positions @var{FROMPOS} through
9146 @code{FROMPOS+LEN-1} of @var{FROM} to positions @var{TOPOS} through
9147 @code{TOPOS+LEN-1} of @var{TO}. The portion of argument @var{TO} not
9148 affected by the movement of bits is unchanged. The values of
9149 @code{FROMPOS+LEN-1} and @code{TOPOS+LEN-1} must be less than
9150 @code{BIT_SIZE(FROM)}.
9152 @item @emph{Standard}:
9153 Fortran 95 and later
9156 Elemental subroutine
9158 @item @emph{Syntax}:
9159 @code{CALL MVBITS(FROM, FROMPOS, LEN, TO, TOPOS)}
9161 @item @emph{Arguments}:
9162 @multitable @columnfractions .15 .70
9163 @item @var{FROM} @tab The type shall be @code{INTEGER}.
9164 @item @var{FROMPOS} @tab The type shall be @code{INTEGER}.
9165 @item @var{LEN} @tab The type shall be @code{INTEGER}.
9166 @item @var{TO} @tab The type shall be @code{INTEGER}, of the
9167 same kind as @var{FROM}.
9168 @item @var{TOPOS} @tab The type shall be @code{INTEGER}.
9171 @item @emph{See also}:
9172 @ref{IBCLR}, @ref{IBSET}, @ref{IBITS}, @ref{IAND}, @ref{IOR}, @ref{IEOR}
9178 @section @code{NEAREST} --- Nearest representable number
9180 @cindex real number, nearest different
9181 @cindex floating point, nearest different
9184 @item @emph{Description}:
9185 @code{NEAREST(X, S)} returns the processor-representable number nearest
9186 to @code{X} in the direction indicated by the sign of @code{S}.
9188 @item @emph{Standard}:
9189 Fortran 95 and later
9194 @item @emph{Syntax}:
9195 @code{RESULT = NEAREST(X, S)}
9197 @item @emph{Arguments}:
9198 @multitable @columnfractions .15 .70
9199 @item @var{X} @tab Shall be of type @code{REAL}.
9200 @item @var{S} @tab (Optional) shall be of type @code{REAL} and
9204 @item @emph{Return value}:
9205 The return value is of the same type as @code{X}. If @code{S} is
9206 positive, @code{NEAREST} returns the processor-representable number
9207 greater than @code{X} and nearest to it. If @code{S} is negative,
9208 @code{NEAREST} returns the processor-representable number smaller than
9209 @code{X} and nearest to it.
9211 @item @emph{Example}:
9213 program test_nearest
9215 x = nearest(42.0, 1.0)
9216 y = nearest(42.0, -1.0)
9217 write (*,"(3(G20.15))") x, y, x - y
9218 end program test_nearest
9225 @section @code{NEW_LINE} --- New line character
9228 @cindex output, newline
9231 @item @emph{Description}:
9232 @code{NEW_LINE(C)} returns the new-line character.
9234 @item @emph{Standard}:
9235 Fortran 2003 and later
9240 @item @emph{Syntax}:
9241 @code{RESULT = NEW_LINE(C)}
9243 @item @emph{Arguments}:
9244 @multitable @columnfractions .15 .70
9245 @item @var{C} @tab The argument shall be a scalar or array of the
9246 type @code{CHARACTER}.
9249 @item @emph{Return value}:
9250 Returns a @var{CHARACTER} scalar of length one with the new-line character of
9251 the same kind as parameter @var{C}.
9253 @item @emph{Example}:
9257 write(*,'(A)') 'This is record 1.'//NEW_LINE('A')//'This is record 2.'
9265 @section @code{NINT} --- Nearest whole number
9268 @cindex rounding, nearest whole number
9271 @item @emph{Description}:
9272 @code{NINT(A)} rounds its argument to the nearest whole number.
9274 @item @emph{Standard}:
9275 Fortran 77 and later, with @var{KIND} argument Fortran 90 and later
9280 @item @emph{Syntax}:
9281 @code{RESULT = NINT(A [, KIND])}
9283 @item @emph{Arguments}:
9284 @multitable @columnfractions .15 .70
9285 @item @var{A} @tab The type of the argument shall be @code{REAL}.
9286 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
9287 expression indicating the kind parameter of the result.
9290 @item @emph{Return value}:
9291 Returns @var{A} with the fractional portion of its magnitude eliminated by
9292 rounding to the nearest whole number and with its sign preserved,
9293 converted to an @code{INTEGER} of the default kind.
9295 @item @emph{Example}:
9302 print *, nint(x4), idnint(x8)
9303 end program test_nint
9306 @item @emph{Specific names}:
9307 @multitable @columnfractions .20 .20 .20 .25
9308 @item Name @tab Argument @tab Return Type @tab Standard
9309 @item @code{NINT(A)} @tab @code{REAL(4) A} @tab @code{INTEGER} @tab Fortran 95 and later
9310 @item @code{IDNINT(A)} @tab @code{REAL(8) A} @tab @code{INTEGER} @tab Fortran 95 and later
9313 @item @emph{See also}:
9314 @ref{CEILING}, @ref{FLOOR}
9321 @section @code{NORM2} --- Euclidean vector norms
9323 @cindex Euclidean vector norm
9324 @cindex L2 vector norm
9325 @cindex norm, Euclidean
9328 @item @emph{Description}:
9329 Calculates the Euclidean vector norm (@math{L_2} norm) of
9330 of @var{ARRAY} along dimension @var{DIM}.
9332 @item @emph{Standard}:
9333 Fortran 2008 and later
9336 Transformational function
9338 @item @emph{Syntax}:
9339 @multitable @columnfractions .80
9340 @item @code{RESULT = NORM2(ARRAY[, DIM])}
9343 @item @emph{Arguments}:
9344 @multitable @columnfractions .15 .70
9345 @item @var{ARRAY} @tab Shall be an array of type @code{REAL}
9346 @item @var{DIM} @tab (Optional) shall be a scalar of type
9347 @code{INTEGER} with a value in the range from 1 to n, where n
9348 equals the rank of @var{ARRAY}.
9351 @item @emph{Return value}:
9352 The result is of the same type as @var{ARRAY}.
9354 If @var{DIM} is absent, a scalar with the square root of the sum of all
9355 elements in @var{ARRAY} squared is returned. Otherwise, an array of
9356 rank @math{n-1}, where @math{n} equals the rank of @var{ARRAY}, and a
9357 shape similar to that of @var{ARRAY} with dimension @var{DIM} dropped
9360 @item @emph{Example}:
9363 REAL :: x(5) = [ real :: 1, 2, 3, 4, 5 ]
9364 print *, NORM2(x) ! = sqrt(55.) ~ 7.416
9372 @section @code{NOT} --- Logical negation
9374 @cindex bits, negate
9375 @cindex bitwise logical not
9376 @cindex logical not, bitwise
9379 @item @emph{Description}:
9380 @code{NOT} returns the bitwise Boolean inverse of @var{I}.
9382 @item @emph{Standard}:
9383 Fortran 95 and later
9388 @item @emph{Syntax}:
9389 @code{RESULT = NOT(I)}
9391 @item @emph{Arguments}:
9392 @multitable @columnfractions .15 .70
9393 @item @var{I} @tab The type shall be @code{INTEGER}.
9396 @item @emph{Return value}:
9397 The return type is @code{INTEGER}, of the same kind as the
9400 @item @emph{See also}:
9401 @ref{IAND}, @ref{IEOR}, @ref{IOR}, @ref{IBITS}, @ref{IBSET}, @ref{IBCLR}
9408 @section @code{NULL} --- Function that returns an disassociated pointer
9410 @cindex pointer, status
9411 @cindex pointer, disassociated
9414 @item @emph{Description}:
9415 Returns a disassociated pointer.
9417 If @var{MOLD} is present, a disassociated pointer of the same type is
9418 returned, otherwise the type is determined by context.
9420 In Fortran 95, @var{MOLD} is optional. Please note that Fortran 2003
9421 includes cases where it is required.
9423 @item @emph{Standard}:
9424 Fortran 95 and later
9427 Transformational function
9429 @item @emph{Syntax}:
9430 @code{PTR => NULL([MOLD])}
9432 @item @emph{Arguments}:
9433 @multitable @columnfractions .15 .70
9434 @item @var{MOLD} @tab (Optional) shall be a pointer of any association
9435 status and of any type.
9438 @item @emph{Return value}:
9439 A disassociated pointer.
9441 @item @emph{Example}:
9443 REAL, POINTER, DIMENSION(:) :: VEC => NULL ()
9446 @item @emph{See also}:
9453 @section @code{NUM_IMAGES} --- Function that returns the number of images
9455 @cindex coarray, @code{NUM_IMAGES}
9456 @cindex images, number of
9459 @item @emph{Description}:
9460 Returns the number of images.
9462 @item @emph{Standard}:
9463 Fortran 2008 and later
9466 Transformational function
9468 @item @emph{Syntax}:
9469 @code{RESULT = NUM_IMAGES()}
9471 @item @emph{Arguments}: None.
9473 @item @emph{Return value}:
9474 Scalar default-kind integer.
9476 @item @emph{Example}:
9480 value = THIS_IMAGE()
9482 IF (THIS_IMAGE() == 1) THEN
9483 DO i = 1, NUM_IMAGES()
9484 WRITE(*,'(2(a,i0))') 'value[', i, '] is ', value[i]
9489 @item @emph{See also}:
9490 @ref{THIS_IMAGE}, @ref{IMAGE_INDEX}
9496 @section @code{OR} --- Bitwise logical OR
9498 @cindex bitwise logical or
9499 @cindex logical or, bitwise
9502 @item @emph{Description}:
9503 Bitwise logical @code{OR}.
9505 This intrinsic routine is provided for backwards compatibility with
9506 GNU Fortran 77. For integer arguments, programmers should consider
9507 the use of the @ref{IOR} intrinsic defined by the Fortran standard.
9509 @item @emph{Standard}:
9515 @item @emph{Syntax}:
9516 @code{RESULT = OR(I, J)}
9518 @item @emph{Arguments}:
9519 @multitable @columnfractions .15 .70
9520 @item @var{I} @tab The type shall be either a scalar @code{INTEGER}
9521 type or a scalar @code{LOGICAL} type.
9522 @item @var{J} @tab The type shall be the same as the type of @var{J}.
9525 @item @emph{Return value}:
9526 The return type is either a scalar @code{INTEGER} or a scalar
9527 @code{LOGICAL}. If the kind type parameters differ, then the
9528 smaller kind type is implicitly converted to larger kind, and the
9529 return has the larger kind.
9531 @item @emph{Example}:
9534 LOGICAL :: T = .TRUE., F = .FALSE.
9536 DATA a / Z'F' /, b / Z'3' /
9538 WRITE (*,*) OR(T, T), OR(T, F), OR(F, T), OR(F, F)
9539 WRITE (*,*) OR(a, b)
9543 @item @emph{See also}:
9544 Fortran 95 elemental function: @ref{IOR}
9550 @section @code{PACK} --- Pack an array into an array of rank one
9552 @cindex array, packing
9553 @cindex array, reduce dimension
9554 @cindex array, gather elements
9557 @item @emph{Description}:
9558 Stores the elements of @var{ARRAY} in an array of rank one.
9560 The beginning of the resulting array is made up of elements whose @var{MASK}
9561 equals @code{TRUE}. Afterwards, positions are filled with elements taken from
9564 @item @emph{Standard}:
9565 Fortran 95 and later
9568 Transformational function
9570 @item @emph{Syntax}:
9571 @code{RESULT = PACK(ARRAY, MASK[,VECTOR]}
9573 @item @emph{Arguments}:
9574 @multitable @columnfractions .15 .70
9575 @item @var{ARRAY} @tab Shall be an array of any type.
9576 @item @var{MASK} @tab Shall be an array of type @code{LOGICAL} and
9577 of the same size as @var{ARRAY}. Alternatively, it may be a @code{LOGICAL}
9579 @item @var{VECTOR} @tab (Optional) shall be an array of the same type
9580 as @var{ARRAY} and of rank one. If present, the number of elements in
9581 @var{VECTOR} shall be equal to or greater than the number of true elements
9582 in @var{MASK}. If @var{MASK} is scalar, the number of elements in
9583 @var{VECTOR} shall be equal to or greater than the number of elements in
9587 @item @emph{Return value}:
9588 The result is an array of rank one and the same type as that of @var{ARRAY}.
9589 If @var{VECTOR} is present, the result size is that of @var{VECTOR}, the
9590 number of @code{TRUE} values in @var{MASK} otherwise.
9592 @item @emph{Example}:
9593 Gathering nonzero elements from an array:
9597 m = (/ 1, 0, 0, 0, 5, 0 /)
9598 WRITE(*, FMT="(6(I0, ' '))") pack(m, m /= 0) ! "1 5"
9602 Gathering nonzero elements from an array and appending elements from @var{VECTOR}:
9606 m = (/ 1, 0, 0, 2 /)
9607 WRITE(*, FMT="(4(I0, ' '))") pack(m, m /= 0, (/ 0, 0, 3, 4 /)) ! "1 2 3 4"
9611 @item @emph{See also}:
9618 @section @code{PARITY} --- Reduction with exclusive OR
9621 @cindex Reduction, XOR
9622 @cindex XOR reduction
9625 @item @emph{Description}:
9626 Calculates the parity, i.e. the reduction using @code{.XOR.},
9627 of @var{MASK} along dimension @var{DIM}.
9629 @item @emph{Standard}:
9630 Fortran 2008 and later
9633 Transformational function
9635 @item @emph{Syntax}:
9636 @multitable @columnfractions .80
9637 @item @code{RESULT = PARITY(MASK[, DIM])}
9640 @item @emph{Arguments}:
9641 @multitable @columnfractions .15 .70
9642 @item @var{LOGICAL} @tab Shall be an array of type @code{LOGICAL}
9643 @item @var{DIM} @tab (Optional) shall be a scalar of type
9644 @code{INTEGER} with a value in the range from 1 to n, where n
9645 equals the rank of @var{MASK}.
9648 @item @emph{Return value}:
9649 The result is of the same type as @var{MASK}.
9651 If @var{DIM} is absent, a scalar with the parity of all elements in
9652 @var{MASK} is returned, i.e. true if an odd number of elements is
9653 @code{.true.} and false otherwise. If @var{DIM} is present, an array
9654 of rank @math{n-1}, where @math{n} equals the rank of @var{ARRAY},
9655 and a shape similar to that of @var{MASK} with dimension @var{DIM}
9656 dropped is returned.
9658 @item @emph{Example}:
9661 LOGICAL :: x(2) = [ .true., .false. ]
9662 print *, PARITY(x) ! prints "T" (true).
9670 @section @code{PERROR} --- Print system error message
9672 @cindex system, error handling
9675 @item @emph{Description}:
9676 Prints (on the C @code{stderr} stream) a newline-terminated error
9677 message corresponding to the last system error. This is prefixed by
9678 @var{STRING}, a colon and a space. See @code{perror(3)}.
9680 @item @emph{Standard}:
9686 @item @emph{Syntax}:
9687 @code{CALL PERROR(STRING)}
9689 @item @emph{Arguments}:
9690 @multitable @columnfractions .15 .70
9691 @item @var{STRING} @tab A scalar of type @code{CHARACTER} and of the
9695 @item @emph{See also}:
9702 @section @code{PRECISION} --- Decimal precision of a real kind
9704 @cindex model representation, precision
9707 @item @emph{Description}:
9708 @code{PRECISION(X)} returns the decimal precision in the model of the
9711 @item @emph{Standard}:
9712 Fortran 95 and later
9717 @item @emph{Syntax}:
9718 @code{RESULT = PRECISION(X)}
9720 @item @emph{Arguments}:
9721 @multitable @columnfractions .15 .70
9722 @item @var{X} @tab Shall be of type @code{REAL} or @code{COMPLEX}.
9725 @item @emph{Return value}:
9726 The return value is of type @code{INTEGER} and of the default integer
9729 @item @emph{See also}:
9730 @ref{SELECTED_REAL_KIND}, @ref{RANGE}
9732 @item @emph{Example}:
9734 program prec_and_range
9735 real(kind=4) :: x(2)
9736 complex(kind=8) :: y
9738 print *, precision(x), range(x)
9739 print *, precision(y), range(y)
9740 end program prec_and_range
9747 @section @code{POPCNT} --- Number of bits set
9749 @cindex binary representation
9753 @item @emph{Description}:
9754 @code{POPCNT(I)} returns the number of bits set ('1' bits) in the binary
9755 representation of @code{I}.
9757 @item @emph{Standard}:
9758 Fortran 2008 and later
9763 @item @emph{Syntax}:
9764 @code{RESULT = POPCNT(I)}
9766 @item @emph{Arguments}:
9767 @multitable @columnfractions .15 .70
9768 @item @var{I} @tab Shall be of type @code{INTEGER}.
9771 @item @emph{Return value}:
9772 The return value is of type @code{INTEGER} and of the default integer
9775 @item @emph{See also}:
9776 @ref{POPPAR}, @ref{LEADZ}, @ref{TRAILZ}
9778 @item @emph{Example}:
9780 program test_population
9781 print *, popcnt(127), poppar(127)
9782 print *, popcnt(huge(0_4)), poppar(huge(0_4))
9783 print *, popcnt(huge(0_8)), poppar(huge(0_8))
9784 end program test_population
9790 @section @code{POPPAR} --- Parity of the number of bits set
9792 @cindex binary representation
9796 @item @emph{Description}:
9797 @code{POPPAR(I)} returns parity of the integer @code{I}, i.e. the parity
9798 of the number of bits set ('1' bits) in the binary representation of
9799 @code{I}. It is equal to 0 if @code{I} has an even number of bits set,
9800 and 1 for an odd number of '1' bits.
9802 @item @emph{Standard}:
9803 Fortran 2008 and later
9808 @item @emph{Syntax}:
9809 @code{RESULT = POPPAR(I)}
9811 @item @emph{Arguments}:
9812 @multitable @columnfractions .15 .70
9813 @item @var{I} @tab Shall be of type @code{INTEGER}.
9816 @item @emph{Return value}:
9817 The return value is of type @code{INTEGER} and of the default integer
9820 @item @emph{See also}:
9821 @ref{POPCNT}, @ref{LEADZ}, @ref{TRAILZ}
9823 @item @emph{Example}:
9825 program test_population
9826 print *, popcnt(127), poppar(127)
9827 print *, popcnt(huge(0_4)), poppar(huge(0_4))
9828 print *, popcnt(huge(0_8)), poppar(huge(0_8))
9829 end program test_population
9836 @section @code{PRESENT} --- Determine whether an optional dummy argument is specified
9840 @item @emph{Description}:
9841 Determines whether an optional dummy argument is present.
9843 @item @emph{Standard}:
9844 Fortran 95 and later
9849 @item @emph{Syntax}:
9850 @code{RESULT = PRESENT(A)}
9852 @item @emph{Arguments}:
9853 @multitable @columnfractions .15 .70
9854 @item @var{A} @tab May be of any type and may be a pointer, scalar or array
9855 value, or a dummy procedure. It shall be the name of an optional dummy argument
9856 accessible within the current subroutine or function.
9859 @item @emph{Return value}:
9860 Returns either @code{TRUE} if the optional argument @var{A} is present, or
9861 @code{FALSE} otherwise.
9863 @item @emph{Example}:
9865 PROGRAM test_present
9866 WRITE(*,*) f(), f(42) ! "F T"
9868 LOGICAL FUNCTION f(x)
9869 INTEGER, INTENT(IN), OPTIONAL :: x
9879 @section @code{PRODUCT} --- Product of array elements
9881 @cindex array, product
9882 @cindex array, multiply elements
9883 @cindex array, conditionally multiply elements
9884 @cindex multiply array elements
9887 @item @emph{Description}:
9888 Multiplies the elements of @var{ARRAY} along dimension @var{DIM} if
9889 the corresponding element in @var{MASK} is @code{TRUE}.
9891 @item @emph{Standard}:
9892 Fortran 95 and later
9895 Transformational function
9897 @item @emph{Syntax}:
9898 @multitable @columnfractions .80
9899 @item @code{RESULT = PRODUCT(ARRAY[, MASK])}
9900 @item @code{RESULT = PRODUCT(ARRAY, DIM[, MASK])}
9903 @item @emph{Arguments}:
9904 @multitable @columnfractions .15 .70
9905 @item @var{ARRAY} @tab Shall be an array of type @code{INTEGER},
9906 @code{REAL} or @code{COMPLEX}.
9907 @item @var{DIM} @tab (Optional) shall be a scalar of type
9908 @code{INTEGER} with a value in the range from 1 to n, where n
9909 equals the rank of @var{ARRAY}.
9910 @item @var{MASK} @tab (Optional) shall be of type @code{LOGICAL}
9911 and either be a scalar or an array of the same shape as @var{ARRAY}.
9914 @item @emph{Return value}:
9915 The result is of the same type as @var{ARRAY}.
9917 If @var{DIM} is absent, a scalar with the product of all elements in
9918 @var{ARRAY} is returned. Otherwise, an array of rank n-1, where n equals
9919 the rank of @var{ARRAY}, and a shape similar to that of @var{ARRAY} with
9920 dimension @var{DIM} dropped is returned.
9923 @item @emph{Example}:
9925 PROGRAM test_product
9926 INTEGER :: x(5) = (/ 1, 2, 3, 4 ,5 /)
9927 print *, PRODUCT(x) ! all elements, product = 120
9928 print *, PRODUCT(x, MASK=MOD(x, 2)==1) ! odd elements, product = 15
9932 @item @emph{See also}:
9939 @section @code{RADIX} --- Base of a model number
9941 @cindex model representation, base
9942 @cindex model representation, radix
9945 @item @emph{Description}:
9946 @code{RADIX(X)} returns the base of the model representing the entity @var{X}.
9948 @item @emph{Standard}:
9949 Fortran 95 and later
9954 @item @emph{Syntax}:
9955 @code{RESULT = RADIX(X)}
9957 @item @emph{Arguments}:
9958 @multitable @columnfractions .15 .70
9959 @item @var{X} @tab Shall be of type @code{INTEGER} or @code{REAL}
9962 @item @emph{Return value}:
9963 The return value is a scalar of type @code{INTEGER} and of the default
9966 @item @emph{See also}:
9967 @ref{SELECTED_REAL_KIND}
9969 @item @emph{Example}:
9972 print *, "The radix for the default integer kind is", radix(0)
9973 print *, "The radix for the default real kind is", radix(0.0)
9974 end program test_radix
9982 @section @code{RAN} --- Real pseudo-random number
9984 @cindex random number generation
9987 @item @emph{Description}:
9988 For compatibility with HP FORTRAN 77/iX, the @code{RAN} intrinsic is
9989 provided as an alias for @code{RAND}. See @ref{RAND} for complete
9992 @item @emph{Standard}:
9998 @item @emph{See also}:
9999 @ref{RAND}, @ref{RANDOM_NUMBER}
10005 @section @code{RAND} --- Real pseudo-random number
10007 @cindex random number generation
10010 @item @emph{Description}:
10011 @code{RAND(FLAG)} returns a pseudo-random number from a uniform
10012 distribution between 0 and 1. If @var{FLAG} is 0, the next number
10013 in the current sequence is returned; if @var{FLAG} is 1, the generator
10014 is restarted by @code{CALL SRAND(0)}; if @var{FLAG} has any other value,
10015 it is used as a new seed with @code{SRAND}.
10017 This intrinsic routine is provided for backwards compatibility with
10018 GNU Fortran 77. It implements a simple modulo generator as provided
10019 by @command{g77}. For new code, one should consider the use of
10020 @ref{RANDOM_NUMBER} as it implements a superior algorithm.
10022 @item @emph{Standard}:
10025 @item @emph{Class}:
10028 @item @emph{Syntax}:
10029 @code{RESULT = RAND(I)}
10031 @item @emph{Arguments}:
10032 @multitable @columnfractions .15 .70
10033 @item @var{I} @tab Shall be a scalar @code{INTEGER} of kind 4.
10036 @item @emph{Return value}:
10037 The return value is of @code{REAL} type and the default kind.
10039 @item @emph{Example}:
10042 integer,parameter :: seed = 86456
10045 print *, rand(), rand(), rand(), rand()
10046 print *, rand(seed), rand(), rand(), rand()
10047 end program test_rand
10050 @item @emph{See also}:
10051 @ref{SRAND}, @ref{RANDOM_NUMBER}
10057 @node RANDOM_NUMBER
10058 @section @code{RANDOM_NUMBER} --- Pseudo-random number
10059 @fnindex RANDOM_NUMBER
10060 @cindex random number generation
10063 @item @emph{Description}:
10064 Returns a single pseudorandom number or an array of pseudorandom numbers
10065 from the uniform distribution over the range @math{ 0 \leq x < 1}.
10067 The runtime-library implements George Marsaglia's KISS (Keep It Simple
10068 Stupid) random number generator (RNG). This RNG combines:
10070 @item The congruential generator @math{x(n) = 69069 \cdot x(n-1) + 1327217885}
10071 with a period of @math{2^{32}},
10072 @item A 3-shift shift-register generator with a period of @math{2^{32} - 1},
10073 @item Two 16-bit multiply-with-carry generators with a period of
10074 @math{597273182964842497 > 2^{59}}.
10076 The overall period exceeds @math{2^{123}}.
10078 Please note, this RNG is thread safe if used within OpenMP directives,
10079 i.e., its state will be consistent while called from multiple threads.
10080 However, the KISS generator does not create random numbers in parallel
10081 from multiple sources, but in sequence from a single source. If an
10082 OpenMP-enabled application heavily relies on random numbers, one should
10083 consider employing a dedicated parallel random number generator instead.
10085 @item @emph{Standard}:
10086 Fortran 95 and later
10088 @item @emph{Class}:
10091 @item @emph{Syntax}:
10092 @code{RANDOM_NUMBER(HARVEST)}
10094 @item @emph{Arguments}:
10095 @multitable @columnfractions .15 .70
10096 @item @var{HARVEST} @tab Shall be a scalar or an array of type @code{REAL}.
10099 @item @emph{Example}:
10101 program test_random_number
10103 CALL init_random_seed() ! see example of RANDOM_SEED
10104 CALL RANDOM_NUMBER(r)
10108 @item @emph{See also}:
10115 @section @code{RANDOM_SEED} --- Initialize a pseudo-random number sequence
10116 @fnindex RANDOM_SEED
10117 @cindex random number generation, seeding
10118 @cindex seeding a random number generator
10121 @item @emph{Description}:
10122 Restarts or queries the state of the pseudorandom number generator used by
10123 @code{RANDOM_NUMBER}.
10125 If @code{RANDOM_SEED} is called without arguments, it is initialized to
10126 a default state. The example below shows how to initialize the random
10127 seed based on the system's time.
10129 @item @emph{Standard}:
10130 Fortran 95 and later
10132 @item @emph{Class}:
10135 @item @emph{Syntax}:
10136 @code{CALL RANDOM_SEED([SIZE, PUT, GET])}
10138 @item @emph{Arguments}:
10139 @multitable @columnfractions .15 .70
10140 @item @var{SIZE} @tab (Optional) Shall be a scalar and of type default
10141 @code{INTEGER}, with @code{INTENT(OUT)}. It specifies the minimum size
10142 of the arrays used with the @var{PUT} and @var{GET} arguments.
10143 @item @var{PUT} @tab (Optional) Shall be an array of type default
10144 @code{INTEGER} and rank one. It is @code{INTENT(IN)} and the size of
10145 the array must be larger than or equal to the number returned by the
10146 @var{SIZE} argument.
10147 @item @var{GET} @tab (Optional) Shall be an array of type default
10148 @code{INTEGER} and rank one. It is @code{INTENT(OUT)} and the size
10149 of the array must be larger than or equal to the number returned by
10150 the @var{SIZE} argument.
10153 @item @emph{Example}:
10155 SUBROUTINE init_random_seed()
10156 INTEGER :: i, n, clock
10157 INTEGER, DIMENSION(:), ALLOCATABLE :: seed
10159 CALL RANDOM_SEED(size = n)
10162 CALL SYSTEM_CLOCK(COUNT=clock)
10164 seed = clock + 37 * (/ (i - 1, i = 1, n) /)
10165 CALL RANDOM_SEED(PUT = seed)
10171 @item @emph{See also}:
10172 @ref{RANDOM_NUMBER}
10178 @section @code{RANGE} --- Decimal exponent range
10180 @cindex model representation, range
10183 @item @emph{Description}:
10184 @code{RANGE(X)} returns the decimal exponent range in the model of the
10187 @item @emph{Standard}:
10188 Fortran 95 and later
10190 @item @emph{Class}:
10193 @item @emph{Syntax}:
10194 @code{RESULT = RANGE(X)}
10196 @item @emph{Arguments}:
10197 @multitable @columnfractions .15 .70
10198 @item @var{X} @tab Shall be of type @code{INTEGER}, @code{REAL}
10202 @item @emph{Return value}:
10203 The return value is of type @code{INTEGER} and of the default integer
10206 @item @emph{See also}:
10207 @ref{SELECTED_REAL_KIND}, @ref{PRECISION}
10209 @item @emph{Example}:
10210 See @code{PRECISION} for an example.
10216 @section @code{RANK} --- Rank of a data object
10221 @item @emph{Description}:
10222 @code{RANK(A)} returns the rank of a scalar or array data object.
10224 @item @emph{Standard}:
10225 Technical Report (TR) 29113
10227 @item @emph{Class}:
10230 @item @emph{Syntax}:
10231 @code{RESULT = RANGE(A)}
10233 @item @emph{Arguments}:
10234 @multitable @columnfractions .15 .70
10235 @item @var{A} @tab can be of any type
10238 @item @emph{Return value}:
10239 The return value is of type @code{INTEGER} and of the default integer
10240 kind. For arrays, their rank is returned; for scalars zero is returned.
10242 @item @emph{Example}:
10246 real, allocatable :: b(:,:)
10248 print *, rank(a), rank(b) ! Prints: 0 3
10249 end program test_rank
10257 @section @code{REAL} --- Convert to real type
10263 @cindex conversion, to real
10264 @cindex complex numbers, real part
10267 @item @emph{Description}:
10268 @code{REAL(A [, KIND])} converts its argument @var{A} to a real type. The
10269 @code{REALPART} function is provided for compatibility with @command{g77},
10270 and its use is strongly discouraged.
10272 @item @emph{Standard}:
10273 Fortran 77 and later
10275 @item @emph{Class}:
10278 @item @emph{Syntax}:
10279 @multitable @columnfractions .80
10280 @item @code{RESULT = REAL(A [, KIND])}
10281 @item @code{RESULT = REALPART(Z)}
10284 @item @emph{Arguments}:
10285 @multitable @columnfractions .15 .70
10286 @item @var{A} @tab Shall be @code{INTEGER}, @code{REAL}, or
10288 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
10289 expression indicating the kind parameter of the result.
10292 @item @emph{Return value}:
10293 These functions return a @code{REAL} variable or array under
10294 the following rules:
10298 @code{REAL(A)} is converted to a default real type if @var{A} is an
10299 integer or real variable.
10301 @code{REAL(A)} is converted to a real type with the kind type parameter
10302 of @var{A} if @var{A} is a complex variable.
10304 @code{REAL(A, KIND)} is converted to a real type with kind type
10305 parameter @var{KIND} if @var{A} is a complex, integer, or real
10309 @item @emph{Example}:
10312 complex :: x = (1.0, 2.0)
10313 print *, real(x), real(x,8), realpart(x)
10314 end program test_real
10317 @item @emph{Specific names}:
10318 @multitable @columnfractions .20 .20 .20 .25
10319 @item Name @tab Argument @tab Return type @tab Standard
10320 @item @code{FLOAT(A)} @tab @code{INTEGER(4)} @tab @code{REAL(4)} @tab Fortran 77 and later
10321 @item @code{DFLOAT(A)} @tab @code{INTEGER(4)} @tab @code{REAL(8)} @tab GNU extension
10322 @item @code{SNGL(A)} @tab @code{INTEGER(8)} @tab @code{REAL(4)} @tab Fortran 77 and later
10326 @item @emph{See also}:
10334 @section @code{RENAME} --- Rename a file
10336 @cindex file system, rename file
10339 @item @emph{Description}:
10340 Renames a file from file @var{PATH1} to @var{PATH2}. A null
10341 character (@code{CHAR(0)}) can be used to mark the end of the names in
10342 @var{PATH1} and @var{PATH2}; otherwise, trailing blanks in the file
10343 names are ignored. If the @var{STATUS} argument is supplied, it
10344 contains 0 on success or a nonzero error code upon return; see
10347 This intrinsic is provided in both subroutine and function forms;
10348 however, only one form can be used in any given program unit.
10350 @item @emph{Standard}:
10353 @item @emph{Class}:
10354 Subroutine, function
10356 @item @emph{Syntax}:
10357 @multitable @columnfractions .80
10358 @item @code{CALL RENAME(PATH1, PATH2 [, STATUS])}
10359 @item @code{STATUS = RENAME(PATH1, PATH2)}
10362 @item @emph{Arguments}:
10363 @multitable @columnfractions .15 .70
10364 @item @var{PATH1} @tab Shall be of default @code{CHARACTER} type.
10365 @item @var{PATH2} @tab Shall be of default @code{CHARACTER} type.
10366 @item @var{STATUS} @tab (Optional) Shall be of default @code{INTEGER} type.
10369 @item @emph{See also}:
10377 @section @code{REPEAT} --- Repeated string concatenation
10379 @cindex string, repeat
10380 @cindex string, concatenate
10383 @item @emph{Description}:
10384 Concatenates @var{NCOPIES} copies of a string.
10386 @item @emph{Standard}:
10387 Fortran 95 and later
10389 @item @emph{Class}:
10390 Transformational function
10392 @item @emph{Syntax}:
10393 @code{RESULT = REPEAT(STRING, NCOPIES)}
10395 @item @emph{Arguments}:
10396 @multitable @columnfractions .15 .70
10397 @item @var{STRING} @tab Shall be scalar and of type @code{CHARACTER}.
10398 @item @var{NCOPIES} @tab Shall be scalar and of type @code{INTEGER}.
10401 @item @emph{Return value}:
10402 A new scalar of type @code{CHARACTER} built up from @var{NCOPIES} copies
10405 @item @emph{Example}:
10407 program test_repeat
10408 write(*,*) repeat("x", 5) ! "xxxxx"
10416 @section @code{RESHAPE} --- Function to reshape an array
10418 @cindex array, change dimensions
10419 @cindex array, transmogrify
10422 @item @emph{Description}:
10423 Reshapes @var{SOURCE} to correspond to @var{SHAPE}. If necessary,
10424 the new array may be padded with elements from @var{PAD} or permuted
10425 as defined by @var{ORDER}.
10427 @item @emph{Standard}:
10428 Fortran 95 and later
10430 @item @emph{Class}:
10431 Transformational function
10433 @item @emph{Syntax}:
10434 @code{RESULT = RESHAPE(SOURCE, SHAPE[, PAD, ORDER])}
10436 @item @emph{Arguments}:
10437 @multitable @columnfractions .15 .70
10438 @item @var{SOURCE} @tab Shall be an array of any type.
10439 @item @var{SHAPE} @tab Shall be of type @code{INTEGER} and an
10440 array of rank one. Its values must be positive or zero.
10441 @item @var{PAD} @tab (Optional) shall be an array of the same
10442 type as @var{SOURCE}.
10443 @item @var{ORDER} @tab (Optional) shall be of type @code{INTEGER}
10444 and an array of the same shape as @var{SHAPE}. Its values shall
10445 be a permutation of the numbers from 1 to n, where n is the size of
10446 @var{SHAPE}. If @var{ORDER} is absent, the natural ordering shall
10450 @item @emph{Return value}:
10451 The result is an array of shape @var{SHAPE} with the same type as
10454 @item @emph{Example}:
10456 PROGRAM test_reshape
10457 INTEGER, DIMENSION(4) :: x
10458 WRITE(*,*) SHAPE(x) ! prints "4"
10459 WRITE(*,*) SHAPE(RESHAPE(x, (/2, 2/))) ! prints "2 2"
10463 @item @emph{See also}:
10470 @section @code{RRSPACING} --- Reciprocal of the relative spacing
10472 @cindex real number, relative spacing
10473 @cindex floating point, relative spacing
10477 @item @emph{Description}:
10478 @code{RRSPACING(X)} returns the reciprocal of the relative spacing of
10479 model numbers near @var{X}.
10481 @item @emph{Standard}:
10482 Fortran 95 and later
10484 @item @emph{Class}:
10487 @item @emph{Syntax}:
10488 @code{RESULT = RRSPACING(X)}
10490 @item @emph{Arguments}:
10491 @multitable @columnfractions .15 .70
10492 @item @var{X} @tab Shall be of type @code{REAL}.
10495 @item @emph{Return value}:
10496 The return value is of the same type and kind as @var{X}.
10497 The value returned is equal to
10498 @code{ABS(FRACTION(X)) * FLOAT(RADIX(X))**DIGITS(X)}.
10500 @item @emph{See also}:
10507 @section @code{RSHIFT} --- Right shift bits
10509 @cindex bits, shift right
10512 @item @emph{Description}:
10513 @code{RSHIFT} returns a value corresponding to @var{I} with all of the
10514 bits shifted right by @var{SHIFT} places. If the absolute value of
10515 @var{SHIFT} is greater than @code{BIT_SIZE(I)}, the value is undefined.
10516 Bits shifted out from the right end are lost. The fill is arithmetic: the
10517 bits shifted in from the left end are equal to the leftmost bit, which in
10518 two's complement representation is the sign bit.
10520 This function has been superseded by the @code{SHIFTA} intrinsic, which
10521 is standard in Fortran 2008 and later.
10523 @item @emph{Standard}:
10526 @item @emph{Class}:
10529 @item @emph{Syntax}:
10530 @code{RESULT = RSHIFT(I, SHIFT)}
10532 @item @emph{Arguments}:
10533 @multitable @columnfractions .15 .70
10534 @item @var{I} @tab The type shall be @code{INTEGER}.
10535 @item @var{SHIFT} @tab The type shall be @code{INTEGER}.
10538 @item @emph{Return value}:
10539 The return value is of type @code{INTEGER} and of the same kind as
10542 @item @emph{See also}:
10543 @ref{ISHFT}, @ref{ISHFTC}, @ref{LSHIFT}, @ref{SHIFTA}, @ref{SHIFTR},
10551 @section @code{SAME_TYPE_AS} --- Query dynamic types for equality
10552 @fnindex SAME_TYPE_AS
10555 @item @emph{Description}:
10556 Query dynamic types for equality.
10558 @item @emph{Standard}:
10559 Fortran 2003 and later
10561 @item @emph{Class}:
10564 @item @emph{Syntax}:
10565 @code{RESULT = SAME_TYPE_AS(A, B)}
10567 @item @emph{Arguments}:
10568 @multitable @columnfractions .15 .70
10569 @item @var{A} @tab Shall be an object of extensible declared type or
10570 unlimited polymorphic.
10571 @item @var{B} @tab Shall be an object of extensible declared type or
10572 unlimited polymorphic.
10575 @item @emph{Return value}:
10576 The return value is a scalar of type default logical. It is true if and
10577 only if the dynamic type of A is the same as the dynamic type of B.
10579 @item @emph{See also}:
10580 @ref{EXTENDS_TYPE_OF}
10587 @section @code{SCALE} --- Scale a real value
10589 @cindex real number, scale
10590 @cindex floating point, scale
10593 @item @emph{Description}:
10594 @code{SCALE(X,I)} returns @code{X * RADIX(X)**I}.
10596 @item @emph{Standard}:
10597 Fortran 95 and later
10599 @item @emph{Class}:
10602 @item @emph{Syntax}:
10603 @code{RESULT = SCALE(X, I)}
10605 @item @emph{Arguments}:
10606 @multitable @columnfractions .15 .70
10607 @item @var{X} @tab The type of the argument shall be a @code{REAL}.
10608 @item @var{I} @tab The type of the argument shall be a @code{INTEGER}.
10611 @item @emph{Return value}:
10612 The return value is of the same type and kind as @var{X}.
10613 Its value is @code{X * RADIX(X)**I}.
10615 @item @emph{Example}:
10618 real :: x = 178.1387e-4
10620 print *, scale(x,i), x*radix(x)**i
10621 end program test_scale
10629 @section @code{SCAN} --- Scan a string for the presence of a set of characters
10631 @cindex string, find subset
10634 @item @emph{Description}:
10635 Scans a @var{STRING} for any of the characters in a @var{SET}
10638 If @var{BACK} is either absent or equals @code{FALSE}, this function
10639 returns the position of the leftmost character of @var{STRING} that is
10640 in @var{SET}. If @var{BACK} equals @code{TRUE}, the rightmost position
10641 is returned. If no character of @var{SET} is found in @var{STRING}, the
10644 @item @emph{Standard}:
10645 Fortran 95 and later, with @var{KIND} argument Fortran 2003 and later
10647 @item @emph{Class}:
10650 @item @emph{Syntax}:
10651 @code{RESULT = SCAN(STRING, SET[, BACK [, KIND]])}
10653 @item @emph{Arguments}:
10654 @multitable @columnfractions .15 .70
10655 @item @var{STRING} @tab Shall be of type @code{CHARACTER}.
10656 @item @var{SET} @tab Shall be of type @code{CHARACTER}.
10657 @item @var{BACK} @tab (Optional) shall be of type @code{LOGICAL}.
10658 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
10659 expression indicating the kind parameter of the result.
10662 @item @emph{Return value}:
10663 The return value is of type @code{INTEGER} and of kind @var{KIND}. If
10664 @var{KIND} is absent, the return value is of default integer kind.
10666 @item @emph{Example}:
10669 WRITE(*,*) SCAN("FORTRAN", "AO") ! 2, found 'O'
10670 WRITE(*,*) SCAN("FORTRAN", "AO", .TRUE.) ! 6, found 'A'
10671 WRITE(*,*) SCAN("FORTRAN", "C++") ! 0, found none
10675 @item @emph{See also}:
10676 @ref{INDEX intrinsic}, @ref{VERIFY}
10682 @section @code{SECNDS} --- Time function
10684 @cindex time, elapsed
10685 @cindex elapsed time
10688 @item @emph{Description}:
10689 @code{SECNDS(X)} gets the time in seconds from the real-time system clock.
10690 @var{X} is a reference time, also in seconds. If this is zero, the time in
10691 seconds from midnight is returned. This function is non-standard and its
10692 use is discouraged.
10694 @item @emph{Standard}:
10697 @item @emph{Class}:
10700 @item @emph{Syntax}:
10701 @code{RESULT = SECNDS (X)}
10703 @item @emph{Arguments}:
10704 @multitable @columnfractions .15 .70
10705 @item @var{T} @tab Shall be of type @code{REAL(4)}.
10706 @item @var{X} @tab Shall be of type @code{REAL(4)}.
10709 @item @emph{Return value}:
10712 @item @emph{Example}:
10714 program test_secnds
10717 print *, secnds (0.0) ! seconds since midnight
10718 t1 = secnds (0.0) ! reference time
10719 do i = 1, 10000000 ! do something
10721 t2 = secnds (t1) ! elapsed time
10722 print *, "Something took ", t2, " seconds."
10723 end program test_secnds
10730 @section @code{SECOND} --- CPU time function
10732 @cindex time, elapsed
10733 @cindex elapsed time
10736 @item @emph{Description}:
10737 Returns a @code{REAL(4)} value representing the elapsed CPU time in
10738 seconds. This provides the same functionality as the standard
10739 @code{CPU_TIME} intrinsic, and is only included for backwards
10742 This intrinsic is provided in both subroutine and function forms;
10743 however, only one form can be used in any given program unit.
10745 @item @emph{Standard}:
10748 @item @emph{Class}:
10749 Subroutine, function
10751 @item @emph{Syntax}:
10752 @multitable @columnfractions .80
10753 @item @code{CALL SECOND(TIME)}
10754 @item @code{TIME = SECOND()}
10757 @item @emph{Arguments}:
10758 @multitable @columnfractions .15 .70
10759 @item @var{TIME} @tab Shall be of type @code{REAL(4)}.
10762 @item @emph{Return value}:
10763 In either syntax, @var{TIME} is set to the process's current runtime in
10766 @item @emph{See also}:
10773 @node SELECTED_CHAR_KIND
10774 @section @code{SELECTED_CHAR_KIND} --- Choose character kind
10775 @fnindex SELECTED_CHAR_KIND
10776 @cindex character kind
10777 @cindex kind, character
10780 @item @emph{Description}:
10782 @code{SELECTED_CHAR_KIND(NAME)} returns the kind value for the character
10783 set named @var{NAME}, if a character set with such a name is supported,
10784 or @math{-1} otherwise. Currently, supported character sets include
10785 ``ASCII'' and ``DEFAULT'', which are equivalent, and ``ISO_10646''
10786 (Universal Character Set, UCS-4) which is commonly known as Unicode.
10788 @item @emph{Standard}:
10789 Fortran 2003 and later
10791 @item @emph{Class}:
10792 Transformational function
10794 @item @emph{Syntax}:
10795 @code{RESULT = SELECTED_CHAR_KIND(NAME)}
10797 @item @emph{Arguments}:
10798 @multitable @columnfractions .15 .70
10799 @item @var{NAME} @tab Shall be a scalar and of the default character type.
10802 @item @emph{Example}:
10804 program character_kind
10805 use iso_fortran_env
10807 integer, parameter :: ascii = selected_char_kind ("ascii")
10808 integer, parameter :: ucs4 = selected_char_kind ('ISO_10646')
10810 character(kind=ascii, len=26) :: alphabet
10811 character(kind=ucs4, len=30) :: hello_world
10813 alphabet = ascii_"abcdefghijklmnopqrstuvwxyz"
10814 hello_world = ucs4_'Hello World and Ni Hao -- ' &
10815 // char (int (z'4F60'), ucs4) &
10816 // char (int (z'597D'), ucs4)
10818 write (*,*) alphabet
10820 open (output_unit, encoding='UTF-8')
10821 write (*,*) trim (hello_world)
10822 end program character_kind
10828 @node SELECTED_INT_KIND
10829 @section @code{SELECTED_INT_KIND} --- Choose integer kind
10830 @fnindex SELECTED_INT_KIND
10831 @cindex integer kind
10832 @cindex kind, integer
10835 @item @emph{Description}:
10836 @code{SELECTED_INT_KIND(R)} return the kind value of the smallest integer
10837 type that can represent all values ranging from @math{-10^R} (exclusive)
10838 to @math{10^R} (exclusive). If there is no integer kind that accommodates
10839 this range, @code{SELECTED_INT_KIND} returns @math{-1}.
10841 @item @emph{Standard}:
10842 Fortran 95 and later
10844 @item @emph{Class}:
10845 Transformational function
10847 @item @emph{Syntax}:
10848 @code{RESULT = SELECTED_INT_KIND(R)}
10850 @item @emph{Arguments}:
10851 @multitable @columnfractions .15 .70
10852 @item @var{R} @tab Shall be a scalar and of type @code{INTEGER}.
10855 @item @emph{Example}:
10857 program large_integers
10858 integer,parameter :: k5 = selected_int_kind(5)
10859 integer,parameter :: k15 = selected_int_kind(15)
10860 integer(kind=k5) :: i5
10861 integer(kind=k15) :: i15
10863 print *, huge(i5), huge(i15)
10865 ! The following inequalities are always true
10866 print *, huge(i5) >= 10_k5**5-1
10867 print *, huge(i15) >= 10_k15**15-1
10868 end program large_integers
10874 @node SELECTED_REAL_KIND
10875 @section @code{SELECTED_REAL_KIND} --- Choose real kind
10876 @fnindex SELECTED_REAL_KIND
10879 @cindex radix, real
10882 @item @emph{Description}:
10883 @code{SELECTED_REAL_KIND(P,R)} returns the kind value of a real data type
10884 with decimal precision of at least @code{P} digits, exponent range of
10885 at least @code{R}, and with a radix of @code{RADIX}.
10887 @item @emph{Standard}:
10888 Fortran 95 and later, with @code{RADIX} Fortran 2008 or later
10890 @item @emph{Class}:
10891 Transformational function
10893 @item @emph{Syntax}:
10894 @code{RESULT = SELECTED_REAL_KIND([P, R, RADIX])}
10896 @item @emph{Arguments}:
10897 @multitable @columnfractions .15 .70
10898 @item @var{P} @tab (Optional) shall be a scalar and of type @code{INTEGER}.
10899 @item @var{R} @tab (Optional) shall be a scalar and of type @code{INTEGER}.
10900 @item @var{RADIX} @tab (Optional) shall be a scalar and of type @code{INTEGER}.
10902 Before Fortran 2008, at least one of the arguments @var{R} or @var{P} shall
10903 be present; since Fortran 2008, they are assumed to be zero if absent.
10905 @item @emph{Return value}:
10907 @code{SELECTED_REAL_KIND} returns the value of the kind type parameter of
10908 a real data type with decimal precision of at least @code{P} digits, a
10909 decimal exponent range of at least @code{R}, and with the requested
10910 @code{RADIX}. If the @code{RADIX} parameter is absent, real kinds with
10911 any radix can be returned. If more than one real data type meet the
10912 criteria, the kind of the data type with the smallest decimal precision
10913 is returned. If no real data type matches the criteria, the result is
10915 @item -1 if the processor does not support a real data type with a
10916 precision greater than or equal to @code{P}, but the @code{R} and
10917 @code{RADIX} requirements can be fulfilled
10918 @item -2 if the processor does not support a real type with an exponent
10919 range greater than or equal to @code{R}, but @code{P} and @code{RADIX}
10921 @item -3 if @code{RADIX} but not @code{P} and @code{R} requirements
10923 @item -4 if @code{RADIX} and either @code{P} or @code{R} requirements
10925 @item -5 if there is no real type with the given @code{RADIX}
10928 @item @emph{See also}:
10929 @ref{PRECISION}, @ref{RANGE}, @ref{RADIX}
10931 @item @emph{Example}:
10934 integer,parameter :: p6 = selected_real_kind(6)
10935 integer,parameter :: p10r100 = selected_real_kind(10,100)
10936 integer,parameter :: r400 = selected_real_kind(r=400)
10938 real(kind=p10r100) :: y
10939 real(kind=r400) :: z
10941 print *, precision(x), range(x)
10942 print *, precision(y), range(y)
10943 print *, precision(z), range(z)
10944 end program real_kinds
10951 @section @code{SET_EXPONENT} --- Set the exponent of the model
10952 @fnindex SET_EXPONENT
10953 @cindex real number, set exponent
10954 @cindex floating point, set exponent
10957 @item @emph{Description}:
10958 @code{SET_EXPONENT(X, I)} returns the real number whose fractional part
10959 is that that of @var{X} and whose exponent part is @var{I}.
10961 @item @emph{Standard}:
10962 Fortran 95 and later
10964 @item @emph{Class}:
10967 @item @emph{Syntax}:
10968 @code{RESULT = SET_EXPONENT(X, I)}
10970 @item @emph{Arguments}:
10971 @multitable @columnfractions .15 .70
10972 @item @var{X} @tab Shall be of type @code{REAL}.
10973 @item @var{I} @tab Shall be of type @code{INTEGER}.
10976 @item @emph{Return value}:
10977 The return value is of the same type and kind as @var{X}.
10978 The real number whose fractional part
10979 is that that of @var{X} and whose exponent part if @var{I} is returned;
10980 it is @code{FRACTION(X) * RADIX(X)**I}.
10982 @item @emph{Example}:
10984 PROGRAM test_setexp
10985 REAL :: x = 178.1387e-4
10987 PRINT *, SET_EXPONENT(x, i), FRACTION(x) * RADIX(x)**i
10996 @section @code{SHAPE} --- Determine the shape of an array
10998 @cindex array, shape
11001 @item @emph{Description}:
11002 Determines the shape of an array.
11004 @item @emph{Standard}:
11005 Fortran 95 and later, with @var{KIND} argument Fortran 2003 and later
11007 @item @emph{Class}:
11010 @item @emph{Syntax}:
11011 @code{RESULT = SHAPE(SOURCE [, KIND])}
11013 @item @emph{Arguments}:
11014 @multitable @columnfractions .15 .70
11015 @item @var{SOURCE} @tab Shall be an array or scalar of any type.
11016 If @var{SOURCE} is a pointer it must be associated and allocatable
11017 arrays must be allocated.
11018 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
11019 expression indicating the kind parameter of the result.
11022 @item @emph{Return value}:
11023 An @code{INTEGER} array of rank one with as many elements as @var{SOURCE}
11024 has dimensions. The elements of the resulting array correspond to the extend
11025 of @var{SOURCE} along the respective dimensions. If @var{SOURCE} is a scalar,
11026 the result is the rank one array of size zero. If @var{KIND} is absent, the
11027 return value has the default integer kind otherwise the specified kind.
11029 @item @emph{Example}:
11032 INTEGER, DIMENSION(-1:1, -1:2) :: A
11033 WRITE(*,*) SHAPE(A) ! (/ 3, 4 /)
11034 WRITE(*,*) SIZE(SHAPE(42)) ! (/ /)
11038 @item @emph{See also}:
11039 @ref{RESHAPE}, @ref{SIZE}
11045 @section @code{SHIFTA} --- Right shift with fill
11047 @cindex bits, shift right
11048 @cindex shift, right with fill
11051 @item @emph{Description}:
11052 @code{SHIFTA} returns a value corresponding to @var{I} with all of the
11053 bits shifted right by @var{SHIFT} places. If the absolute value of
11054 @var{SHIFT} is greater than @code{BIT_SIZE(I)}, the value is undefined.
11055 Bits shifted out from the right end are lost. The fill is arithmetic: the
11056 bits shifted in from the left end are equal to the leftmost bit, which in
11057 two's complement representation is the sign bit.
11059 @item @emph{Standard}:
11060 Fortran 2008 and later
11062 @item @emph{Class}:
11065 @item @emph{Syntax}:
11066 @code{RESULT = SHIFTA(I, SHIFT)}
11068 @item @emph{Arguments}:
11069 @multitable @columnfractions .15 .70
11070 @item @var{I} @tab The type shall be @code{INTEGER}.
11071 @item @var{SHIFT} @tab The type shall be @code{INTEGER}.
11074 @item @emph{Return value}:
11075 The return value is of type @code{INTEGER} and of the same kind as
11078 @item @emph{See also}:
11079 @ref{SHIFTL}, @ref{SHIFTR}
11085 @section @code{SHIFTL} --- Left shift
11087 @cindex bits, shift left
11088 @cindex shift, left
11091 @item @emph{Description}:
11092 @code{SHIFTL} returns a value corresponding to @var{I} with all of the
11093 bits shifted left by @var{SHIFT} places. If the absolute value of
11094 @var{SHIFT} is greater than @code{BIT_SIZE(I)}, the value is undefined.
11095 Bits shifted out from the left end are lost, and bits shifted in from
11096 the right end are set to 0.
11098 @item @emph{Standard}:
11099 Fortran 2008 and later
11101 @item @emph{Class}:
11104 @item @emph{Syntax}:
11105 @code{RESULT = SHIFTL(I, SHIFT)}
11107 @item @emph{Arguments}:
11108 @multitable @columnfractions .15 .70
11109 @item @var{I} @tab The type shall be @code{INTEGER}.
11110 @item @var{SHIFT} @tab The type shall be @code{INTEGER}.
11113 @item @emph{Return value}:
11114 The return value is of type @code{INTEGER} and of the same kind as
11117 @item @emph{See also}:
11118 @ref{SHIFTA}, @ref{SHIFTR}
11124 @section @code{SHIFTR} --- Right shift
11126 @cindex bits, shift right
11127 @cindex shift, right
11130 @item @emph{Description}:
11131 @code{SHIFTR} returns a value corresponding to @var{I} with all of the
11132 bits shifted right by @var{SHIFT} places. If the absolute value of
11133 @var{SHIFT} is greater than @code{BIT_SIZE(I)}, the value is undefined.
11134 Bits shifted out from the right end are lost, and bits shifted in from
11135 the left end are set to 0.
11137 @item @emph{Standard}:
11138 Fortran 2008 and later
11140 @item @emph{Class}:
11143 @item @emph{Syntax}:
11144 @code{RESULT = SHIFTR(I, SHIFT)}
11146 @item @emph{Arguments}:
11147 @multitable @columnfractions .15 .70
11148 @item @var{I} @tab The type shall be @code{INTEGER}.
11149 @item @var{SHIFT} @tab The type shall be @code{INTEGER}.
11152 @item @emph{Return value}:
11153 The return value is of type @code{INTEGER} and of the same kind as
11156 @item @emph{See also}:
11157 @ref{SHIFTA}, @ref{SHIFTL}
11163 @section @code{SIGN} --- Sign copying function
11167 @cindex sign copying
11170 @item @emph{Description}:
11171 @code{SIGN(A,B)} returns the value of @var{A} with the sign of @var{B}.
11173 @item @emph{Standard}:
11174 Fortran 77 and later
11176 @item @emph{Class}:
11179 @item @emph{Syntax}:
11180 @code{RESULT = SIGN(A, B)}
11182 @item @emph{Arguments}:
11183 @multitable @columnfractions .15 .70
11184 @item @var{A} @tab Shall be of type @code{INTEGER} or @code{REAL}
11185 @item @var{B} @tab Shall be of the same type and kind as @var{A}
11188 @item @emph{Return value}:
11189 The kind of the return value is that of @var{A} and @var{B}.
11190 If @math{B\ge 0} then the result is @code{ABS(A)}, else
11191 it is @code{-ABS(A)}.
11193 @item @emph{Example}:
11196 print *, sign(-12,1)
11197 print *, sign(-12,0)
11198 print *, sign(-12,-1)
11200 print *, sign(-12.,1.)
11201 print *, sign(-12.,0.)
11202 print *, sign(-12.,-1.)
11203 end program test_sign
11206 @item @emph{Specific names}:
11207 @multitable @columnfractions .20 .20 .20 .25
11208 @item Name @tab Arguments @tab Return type @tab Standard
11209 @item @code{SIGN(A,B)} @tab @code{REAL(4) A, B} @tab @code{REAL(4)} @tab f77, gnu
11210 @item @code{ISIGN(A,B)} @tab @code{INTEGER(4) A, B} @tab @code{INTEGER(4)} @tab f77, gnu
11211 @item @code{DSIGN(A,B)} @tab @code{REAL(8) A, B} @tab @code{REAL(8)} @tab f77, gnu
11218 @section @code{SIGNAL} --- Signal handling subroutine (or function)
11220 @cindex system, signal handling
11223 @item @emph{Description}:
11224 @code{SIGNAL(NUMBER, HANDLER [, STATUS])} causes external subroutine
11225 @var{HANDLER} to be executed with a single integer argument when signal
11226 @var{NUMBER} occurs. If @var{HANDLER} is an integer, it can be used to
11227 turn off handling of signal @var{NUMBER} or revert to its default
11228 action. See @code{signal(2)}.
11230 If @code{SIGNAL} is called as a subroutine and the @var{STATUS} argument
11231 is supplied, it is set to the value returned by @code{signal(2)}.
11233 @item @emph{Standard}:
11236 @item @emph{Class}:
11237 Subroutine, function
11239 @item @emph{Syntax}:
11240 @multitable @columnfractions .80
11241 @item @code{CALL SIGNAL(NUMBER, HANDLER [, STATUS])}
11242 @item @code{STATUS = SIGNAL(NUMBER, HANDLER)}
11245 @item @emph{Arguments}:
11246 @multitable @columnfractions .15 .70
11247 @item @var{NUMBER} @tab Shall be a scalar integer, with @code{INTENT(IN)}
11248 @item @var{HANDLER}@tab Signal handler (@code{INTEGER FUNCTION} or
11249 @code{SUBROUTINE}) or dummy/global @code{INTEGER} scalar.
11250 @code{INTEGER}. It is @code{INTENT(IN)}.
11251 @item @var{STATUS} @tab (Optional) @var{STATUS} shall be a scalar
11252 integer. It has @code{INTENT(OUT)}.
11254 @c TODO: What should the interface of the handler be? Does it take arguments?
11256 @item @emph{Return value}:
11257 The @code{SIGNAL} function returns the value returned by @code{signal(2)}.
11259 @item @emph{Example}:
11261 program test_signal
11263 external handler_print
11265 call signal (12, handler_print)
11266 call signal (10, 1)
11269 end program test_signal
11276 @section @code{SIN} --- Sine function
11282 @cindex trigonometric function, sine
11286 @item @emph{Description}:
11287 @code{SIN(X)} computes the sine of @var{X}.
11289 @item @emph{Standard}:
11290 Fortran 77 and later
11292 @item @emph{Class}:
11295 @item @emph{Syntax}:
11296 @code{RESULT = SIN(X)}
11298 @item @emph{Arguments}:
11299 @multitable @columnfractions .15 .70
11300 @item @var{X} @tab The type shall be @code{REAL} or
11304 @item @emph{Return value}:
11305 The return value has same type and kind as @var{X}.
11307 @item @emph{Example}:
11312 end program test_sin
11315 @item @emph{Specific names}:
11316 @multitable @columnfractions .20 .20 .20 .25
11317 @item Name @tab Argument @tab Return type @tab Standard
11318 @item @code{SIN(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab f77, gnu
11319 @item @code{DSIN(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab f95, gnu
11320 @item @code{CSIN(X)} @tab @code{COMPLEX(4) X} @tab @code{COMPLEX(4)} @tab f95, gnu
11321 @item @code{ZSIN(X)} @tab @code{COMPLEX(8) X} @tab @code{COMPLEX(8)} @tab f95, gnu
11322 @item @code{CDSIN(X)} @tab @code{COMPLEX(8) X} @tab @code{COMPLEX(8)} @tab f95, gnu
11325 @item @emph{See also}:
11332 @section @code{SINH} --- Hyperbolic sine function
11335 @cindex hyperbolic sine
11336 @cindex hyperbolic function, sine
11337 @cindex sine, hyperbolic
11340 @item @emph{Description}:
11341 @code{SINH(X)} computes the hyperbolic sine of @var{X}.
11343 @item @emph{Standard}:
11344 Fortran 95 and later, for a complex argument Fortran 2008 or later
11346 @item @emph{Class}:
11349 @item @emph{Syntax}:
11350 @code{RESULT = SINH(X)}
11352 @item @emph{Arguments}:
11353 @multitable @columnfractions .15 .70
11354 @item @var{X} @tab The type shall be @code{REAL} or @code{COMPLEX}.
11357 @item @emph{Return value}:
11358 The return value has same type and kind as @var{X}.
11360 @item @emph{Example}:
11363 real(8) :: x = - 1.0_8
11365 end program test_sinh
11368 @item @emph{Specific names}:
11369 @multitable @columnfractions .20 .20 .20 .25
11370 @item Name @tab Argument @tab Return type @tab Standard
11371 @item @code{SINH(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab Fortran 95 and later
11372 @item @code{DSINH(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab Fortran 95 and later
11375 @item @emph{See also}:
11382 @section @code{SIZE} --- Determine the size of an array
11384 @cindex array, size
11385 @cindex array, number of elements
11386 @cindex array, count elements
11389 @item @emph{Description}:
11390 Determine the extent of @var{ARRAY} along a specified dimension @var{DIM},
11391 or the total number of elements in @var{ARRAY} if @var{DIM} is absent.
11393 @item @emph{Standard}:
11394 Fortran 95 and later, with @var{KIND} argument Fortran 2003 and later
11396 @item @emph{Class}:
11399 @item @emph{Syntax}:
11400 @code{RESULT = SIZE(ARRAY[, DIM [, KIND]])}
11402 @item @emph{Arguments}:
11403 @multitable @columnfractions .15 .70
11404 @item @var{ARRAY} @tab Shall be an array of any type. If @var{ARRAY} is
11405 a pointer it must be associated and allocatable arrays must be allocated.
11406 @item @var{DIM} @tab (Optional) shall be a scalar of type @code{INTEGER}
11407 and its value shall be in the range from 1 to n, where n equals the rank
11409 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
11410 expression indicating the kind parameter of the result.
11413 @item @emph{Return value}:
11414 The return value is of type @code{INTEGER} and of kind @var{KIND}. If
11415 @var{KIND} is absent, the return value is of default integer kind.
11417 @item @emph{Example}:
11420 WRITE(*,*) SIZE((/ 1, 2 /)) ! 2
11424 @item @emph{See also}:
11425 @ref{SHAPE}, @ref{RESHAPE}
11430 @section @code{SIZEOF} --- Size in bytes of an expression
11432 @cindex expression size
11433 @cindex size of an expression
11436 @item @emph{Description}:
11437 @code{SIZEOF(X)} calculates the number of bytes of storage the
11438 expression @code{X} occupies.
11440 @item @emph{Standard}:
11443 @item @emph{Class}:
11446 @item @emph{Syntax}:
11447 @code{N = SIZEOF(X)}
11449 @item @emph{Arguments}:
11450 @multitable @columnfractions .15 .70
11451 @item @var{X} @tab The argument shall be of any type, rank or shape.
11454 @item @emph{Return value}:
11455 The return value is of type integer and of the system-dependent kind
11456 @var{C_SIZE_T} (from the @var{ISO_C_BINDING} module). Its value is the
11457 number of bytes occupied by the argument. If the argument has the
11458 @code{POINTER} attribute, the number of bytes of the storage area pointed
11459 to is returned. If the argument is of a derived type with @code{POINTER}
11460 or @code{ALLOCATABLE} components, the return value doesn't account for
11461 the sizes of the data pointed to by these components. If the argument is
11462 polymorphic, the size according to the declared type is returned.
11464 @item @emph{Example}:
11468 print *, (sizeof(s)/sizeof(r) == 5)
11471 The example will print @code{.TRUE.} unless you are using a platform
11472 where default @code{REAL} variables are unusually padded.
11474 @item @emph{See also}:
11475 @ref{C_SIZEOF}, @ref{STORAGE_SIZE}
11480 @section @code{SLEEP} --- Sleep for the specified number of seconds
11482 @cindex delayed execution
11485 @item @emph{Description}:
11486 Calling this subroutine causes the process to pause for @var{SECONDS} seconds.
11488 @item @emph{Standard}:
11491 @item @emph{Class}:
11494 @item @emph{Syntax}:
11495 @code{CALL SLEEP(SECONDS)}
11497 @item @emph{Arguments}:
11498 @multitable @columnfractions .15 .70
11499 @item @var{SECONDS} @tab The type shall be of default @code{INTEGER}.
11502 @item @emph{Example}:
11513 @section @code{SPACING} --- Smallest distance between two numbers of a given type
11515 @cindex real number, relative spacing
11516 @cindex floating point, relative spacing
11519 @item @emph{Description}:
11520 Determines the distance between the argument @var{X} and the nearest
11521 adjacent number of the same type.
11523 @item @emph{Standard}:
11524 Fortran 95 and later
11526 @item @emph{Class}:
11529 @item @emph{Syntax}:
11530 @code{RESULT = SPACING(X)}
11532 @item @emph{Arguments}:
11533 @multitable @columnfractions .15 .70
11534 @item @var{X} @tab Shall be of type @code{REAL}.
11537 @item @emph{Return value}:
11538 The result is of the same type as the input argument @var{X}.
11540 @item @emph{Example}:
11542 PROGRAM test_spacing
11543 INTEGER, PARAMETER :: SGL = SELECTED_REAL_KIND(p=6, r=37)
11544 INTEGER, PARAMETER :: DBL = SELECTED_REAL_KIND(p=13, r=200)
11546 WRITE(*,*) spacing(1.0_SGL) ! "1.1920929E-07" on i686
11547 WRITE(*,*) spacing(1.0_DBL) ! "2.220446049250313E-016" on i686
11551 @item @emph{See also}:
11558 @section @code{SPREAD} --- Add a dimension to an array
11560 @cindex array, increase dimension
11561 @cindex array, duplicate elements
11562 @cindex array, duplicate dimensions
11565 @item @emph{Description}:
11566 Replicates a @var{SOURCE} array @var{NCOPIES} times along a specified
11567 dimension @var{DIM}.
11569 @item @emph{Standard}:
11570 Fortran 95 and later
11572 @item @emph{Class}:
11573 Transformational function
11575 @item @emph{Syntax}:
11576 @code{RESULT = SPREAD(SOURCE, DIM, NCOPIES)}
11578 @item @emph{Arguments}:
11579 @multitable @columnfractions .15 .70
11580 @item @var{SOURCE} @tab Shall be a scalar or an array of any type and
11581 a rank less than seven.
11582 @item @var{DIM} @tab Shall be a scalar of type @code{INTEGER} with a
11583 value in the range from 1 to n+1, where n equals the rank of @var{SOURCE}.
11584 @item @var{NCOPIES} @tab Shall be a scalar of type @code{INTEGER}.
11587 @item @emph{Return value}:
11588 The result is an array of the same type as @var{SOURCE} and has rank n+1
11589 where n equals the rank of @var{SOURCE}.
11591 @item @emph{Example}:
11593 PROGRAM test_spread
11594 INTEGER :: a = 1, b(2) = (/ 1, 2 /)
11595 WRITE(*,*) SPREAD(A, 1, 2) ! "1 1"
11596 WRITE(*,*) SPREAD(B, 1, 2) ! "1 1 2 2"
11600 @item @emph{See also}:
11607 @section @code{SQRT} --- Square-root function
11614 @cindex square-root
11617 @item @emph{Description}:
11618 @code{SQRT(X)} computes the square root of @var{X}.
11620 @item @emph{Standard}:
11621 Fortran 77 and later
11623 @item @emph{Class}:
11626 @item @emph{Syntax}:
11627 @code{RESULT = SQRT(X)}
11629 @item @emph{Arguments}:
11630 @multitable @columnfractions .15 .70
11631 @item @var{X} @tab The type shall be @code{REAL} or
11635 @item @emph{Return value}:
11636 The return value is of type @code{REAL} or @code{COMPLEX}.
11637 The kind type parameter is the same as @var{X}.
11639 @item @emph{Example}:
11642 real(8) :: x = 2.0_8
11643 complex :: z = (1.0, 2.0)
11646 end program test_sqrt
11649 @item @emph{Specific names}:
11650 @multitable @columnfractions .20 .20 .20 .25
11651 @item Name @tab Argument @tab Return type @tab Standard
11652 @item @code{SQRT(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab Fortran 95 and later
11653 @item @code{DSQRT(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab Fortran 95 and later
11654 @item @code{CSQRT(X)} @tab @code{COMPLEX(4) X} @tab @code{COMPLEX(4)} @tab Fortran 95 and later
11655 @item @code{ZSQRT(X)} @tab @code{COMPLEX(8) X} @tab @code{COMPLEX(8)} @tab GNU extension
11656 @item @code{CDSQRT(X)} @tab @code{COMPLEX(8) X} @tab @code{COMPLEX(8)} @tab GNU extension
11663 @section @code{SRAND} --- Reinitialize the random number generator
11665 @cindex random number generation, seeding
11666 @cindex seeding a random number generator
11669 @item @emph{Description}:
11670 @code{SRAND} reinitializes the pseudo-random number generator
11671 called by @code{RAND} and @code{IRAND}. The new seed used by the
11672 generator is specified by the required argument @var{SEED}.
11674 @item @emph{Standard}:
11677 @item @emph{Class}:
11680 @item @emph{Syntax}:
11681 @code{CALL SRAND(SEED)}
11683 @item @emph{Arguments}:
11684 @multitable @columnfractions .15 .70
11685 @item @var{SEED} @tab Shall be a scalar @code{INTEGER(kind=4)}.
11688 @item @emph{Return value}:
11689 Does not return anything.
11691 @item @emph{Example}:
11692 See @code{RAND} and @code{IRAND} for examples.
11694 @item @emph{Notes}:
11695 The Fortran 2003 standard specifies the intrinsic @code{RANDOM_SEED} to
11696 initialize the pseudo-random numbers generator and @code{RANDOM_NUMBER}
11697 to generate pseudo-random numbers. Please note that in
11698 GNU Fortran, these two sets of intrinsics (@code{RAND},
11699 @code{IRAND} and @code{SRAND} on the one hand, @code{RANDOM_NUMBER} and
11700 @code{RANDOM_SEED} on the other hand) access two independent
11701 pseudo-random number generators.
11703 @item @emph{See also}:
11704 @ref{RAND}, @ref{RANDOM_SEED}, @ref{RANDOM_NUMBER}
11711 @section @code{STAT} --- Get file status
11713 @cindex file system, file status
11716 @item @emph{Description}:
11717 This function returns information about a file. No permissions are required on
11718 the file itself, but execute (search) permission is required on all of the
11719 directories in path that lead to the file.
11721 The elements that are obtained and stored in the array @code{VALUES}:
11722 @multitable @columnfractions .15 .70
11723 @item @code{VALUES(1)} @tab Device ID
11724 @item @code{VALUES(2)} @tab Inode number
11725 @item @code{VALUES(3)} @tab File mode
11726 @item @code{VALUES(4)} @tab Number of links
11727 @item @code{VALUES(5)} @tab Owner's uid
11728 @item @code{VALUES(6)} @tab Owner's gid
11729 @item @code{VALUES(7)} @tab ID of device containing directory entry for file (0 if not available)
11730 @item @code{VALUES(8)} @tab File size (bytes)
11731 @item @code{VALUES(9)} @tab Last access time
11732 @item @code{VALUES(10)} @tab Last modification time
11733 @item @code{VALUES(11)} @tab Last file status change time
11734 @item @code{VALUES(12)} @tab Preferred I/O block size (-1 if not available)
11735 @item @code{VALUES(13)} @tab Number of blocks allocated (-1 if not available)
11738 Not all these elements are relevant on all systems.
11739 If an element is not relevant, it is returned as 0.
11741 This intrinsic is provided in both subroutine and function forms; however,
11742 only one form can be used in any given program unit.
11744 @item @emph{Standard}:
11747 @item @emph{Class}:
11748 Subroutine, function
11750 @item @emph{Syntax}:
11751 @multitable @columnfractions .80
11752 @item @code{CALL STAT(NAME, VALUES [, STATUS])}
11753 @item @code{STATUS = STAT(NAME, VALUES)}
11756 @item @emph{Arguments}:
11757 @multitable @columnfractions .15 .70
11758 @item @var{NAME} @tab The type shall be @code{CHARACTER}, of the
11759 default kind and a valid path within the file system.
11760 @item @var{VALUES} @tab The type shall be @code{INTEGER(4), DIMENSION(13)}.
11761 @item @var{STATUS} @tab (Optional) status flag of type @code{INTEGER(4)}. Returns 0
11762 on success and a system specific error code otherwise.
11765 @item @emph{Example}:
11768 INTEGER, DIMENSION(13) :: buff
11771 CALL STAT("/etc/passwd", buff, status)
11773 IF (status == 0) THEN
11774 WRITE (*, FMT="('Device ID:', T30, I19)") buff(1)
11775 WRITE (*, FMT="('Inode number:', T30, I19)") buff(2)
11776 WRITE (*, FMT="('File mode (octal):', T30, O19)") buff(3)
11777 WRITE (*, FMT="('Number of links:', T30, I19)") buff(4)
11778 WRITE (*, FMT="('Owner''s uid:', T30, I19)") buff(5)
11779 WRITE (*, FMT="('Owner''s gid:', T30, I19)") buff(6)
11780 WRITE (*, FMT="('Device where located:', T30, I19)") buff(7)
11781 WRITE (*, FMT="('File size:', T30, I19)") buff(8)
11782 WRITE (*, FMT="('Last access time:', T30, A19)") CTIME(buff(9))
11783 WRITE (*, FMT="('Last modification time', T30, A19)") CTIME(buff(10))
11784 WRITE (*, FMT="('Last status change time:', T30, A19)") CTIME(buff(11))
11785 WRITE (*, FMT="('Preferred block size:', T30, I19)") buff(12)
11786 WRITE (*, FMT="('No. of blocks allocated:', T30, I19)") buff(13)
11791 @item @emph{See also}:
11792 To stat an open file: @ref{FSTAT}, to stat a link: @ref{LSTAT}
11798 @section @code{STORAGE_SIZE} --- Storage size in bits
11799 @fnindex STORAGE_SIZE
11800 @cindex storage size
11803 @item @emph{Description}:
11804 Returns the storage size of argument @var{A} in bits.
11805 @item @emph{Standard}:
11806 Fortran 2008 and later
11807 @item @emph{Class}:
11809 @item @emph{Syntax}:
11810 @code{RESULT = STORAGE_SIZE(A [, KIND])}
11812 @item @emph{Arguments}:
11813 @multitable @columnfractions .15 .70
11814 @item @var{A} @tab Shall be a scalar or array of any type.
11815 @item @var{KIND} @tab (Optional) shall be a scalar integer constant expression.
11818 @item @emph{Return Value}:
11819 The result is a scalar integer with the kind type parameter specified by KIND (or default integer type if KIND is missing). The result value is the size expressed in bits for an element of an array that
11820 has the dynamic type and type parameters of A.
11822 @item @emph{See also}:
11823 @ref{C_SIZEOF}, @ref{SIZEOF}
11829 @section @code{SUM} --- Sum of array elements
11832 @cindex array, add elements
11833 @cindex array, conditionally add elements
11834 @cindex sum array elements
11837 @item @emph{Description}:
11838 Adds the elements of @var{ARRAY} along dimension @var{DIM} if
11839 the corresponding element in @var{MASK} is @code{TRUE}.
11841 @item @emph{Standard}:
11842 Fortran 95 and later
11844 @item @emph{Class}:
11845 Transformational function
11847 @item @emph{Syntax}:
11848 @multitable @columnfractions .80
11849 @item @code{RESULT = SUM(ARRAY[, MASK])}
11850 @item @code{RESULT = SUM(ARRAY, DIM[, MASK])}
11853 @item @emph{Arguments}:
11854 @multitable @columnfractions .15 .70
11855 @item @var{ARRAY} @tab Shall be an array of type @code{INTEGER},
11856 @code{REAL} or @code{COMPLEX}.
11857 @item @var{DIM} @tab (Optional) shall be a scalar of type
11858 @code{INTEGER} with a value in the range from 1 to n, where n
11859 equals the rank of @var{ARRAY}.
11860 @item @var{MASK} @tab (Optional) shall be of type @code{LOGICAL}
11861 and either be a scalar or an array of the same shape as @var{ARRAY}.
11864 @item @emph{Return value}:
11865 The result is of the same type as @var{ARRAY}.
11867 If @var{DIM} is absent, a scalar with the sum of all elements in @var{ARRAY}
11868 is returned. Otherwise, an array of rank n-1, where n equals the rank of
11869 @var{ARRAY}, and a shape similar to that of @var{ARRAY} with dimension @var{DIM}
11870 dropped is returned.
11872 @item @emph{Example}:
11875 INTEGER :: x(5) = (/ 1, 2, 3, 4 ,5 /)
11876 print *, SUM(x) ! all elements, sum = 15
11877 print *, SUM(x, MASK=MOD(x, 2)==1) ! odd elements, sum = 9
11881 @item @emph{See also}:
11888 @section @code{SYMLNK} --- Create a symbolic link
11890 @cindex file system, create link
11891 @cindex file system, soft link
11894 @item @emph{Description}:
11895 Makes a symbolic link from file @var{PATH1} to @var{PATH2}. A null
11896 character (@code{CHAR(0)}) can be used to mark the end of the names in
11897 @var{PATH1} and @var{PATH2}; otherwise, trailing blanks in the file
11898 names are ignored. If the @var{STATUS} argument is supplied, it
11899 contains 0 on success or a nonzero error code upon return; see
11900 @code{symlink(2)}. If the system does not supply @code{symlink(2)},
11901 @code{ENOSYS} is returned.
11903 This intrinsic is provided in both subroutine and function forms;
11904 however, only one form can be used in any given program unit.
11906 @item @emph{Standard}:
11909 @item @emph{Class}:
11910 Subroutine, function
11912 @item @emph{Syntax}:
11913 @multitable @columnfractions .80
11914 @item @code{CALL SYMLNK(PATH1, PATH2 [, STATUS])}
11915 @item @code{STATUS = SYMLNK(PATH1, PATH2)}
11918 @item @emph{Arguments}:
11919 @multitable @columnfractions .15 .70
11920 @item @var{PATH1} @tab Shall be of default @code{CHARACTER} type.
11921 @item @var{PATH2} @tab Shall be of default @code{CHARACTER} type.
11922 @item @var{STATUS} @tab (Optional) Shall be of default @code{INTEGER} type.
11925 @item @emph{See also}:
11926 @ref{LINK}, @ref{UNLINK}
11933 @section @code{SYSTEM} --- Execute a shell command
11935 @cindex system, system call
11938 @item @emph{Description}:
11939 Passes the command @var{COMMAND} to a shell (see @code{system(3)}). If
11940 argument @var{STATUS} is present, it contains the value returned by
11941 @code{system(3)}, which is presumably 0 if the shell command succeeded.
11942 Note that which shell is used to invoke the command is system-dependent
11943 and environment-dependent.
11945 This intrinsic is provided in both subroutine and function forms;
11946 however, only one form can be used in any given program unit.
11948 Note that the @code{system} function need not be thread-safe. It is
11949 the responsibility of the user to ensure that @code{system} is not
11950 called concurrently.
11952 @item @emph{Standard}:
11955 @item @emph{Class}:
11956 Subroutine, function
11958 @item @emph{Syntax}:
11959 @multitable @columnfractions .80
11960 @item @code{CALL SYSTEM(COMMAND [, STATUS])}
11961 @item @code{STATUS = SYSTEM(COMMAND)}
11964 @item @emph{Arguments}:
11965 @multitable @columnfractions .15 .70
11966 @item @var{COMMAND} @tab Shall be of default @code{CHARACTER} type.
11967 @item @var{STATUS} @tab (Optional) Shall be of default @code{INTEGER} type.
11970 @item @emph{See also}:
11971 @ref{EXECUTE_COMMAND_LINE}, which is part of the Fortran 2008 standard
11972 and should considered in new code for future portability.
11978 @section @code{SYSTEM_CLOCK} --- Time function
11979 @fnindex SYSTEM_CLOCK
11980 @cindex time, clock ticks
11981 @cindex clock ticks
11984 @item @emph{Description}:
11985 Determines the @var{COUNT} of a processor clock since an unspecified
11986 time in the past modulo @var{COUNT_MAX}, @var{COUNT_RATE} determines
11987 the number of clock ticks per second. If the platform supports a high
11988 resolution monotonic clock, that clock is used and can provide up to
11989 nanosecond resolution. If a high resolution monotonic clock is not
11990 available, the implementation falls back to a potentially lower
11991 resolution realtime clock.
11993 @var{COUNT_RATE} and @var{COUNT_MAX} vary depending on the kind of the
11994 arguments. For @var{kind=8} arguments, @var{COUNT} represents
11995 nanoseconds, and for @var{kind=4} arguments, @var{COUNT} represents
11996 milliseconds. Other than the kind dependency, @var{COUNT_RATE} and
11997 @var{COUNT_MAX} are constant, however the particular values are
11998 specific to @command{gfortran}.
12000 If there is no clock, @var{COUNT} is set to @code{-HUGE(COUNT)}, and
12001 @var{COUNT_RATE} and @var{COUNT_MAX} are set to zero.
12003 When running on a platform using the GNU C library (glibc), or a
12004 derivative thereof, the high resolution monotonic clock is available
12005 only when linking with the @var{rt} library. This can be done
12006 explicitly by adding the @code{-lrt} flag when linking the
12007 application, but is also done implicitly when using OpenMP.
12009 @item @emph{Standard}:
12010 Fortran 95 and later
12012 @item @emph{Class}:
12015 @item @emph{Syntax}:
12016 @code{CALL SYSTEM_CLOCK([COUNT, COUNT_RATE, COUNT_MAX])}
12018 @item @emph{Arguments}:
12019 @multitable @columnfractions .15 .70
12020 @item @var{COUNT} @tab (Optional) shall be a scalar of type
12021 @code{INTEGER} with @code{INTENT(OUT)}.
12022 @item @var{COUNT_RATE} @tab (Optional) shall be a scalar of type
12023 @code{INTEGER} with @code{INTENT(OUT)}.
12024 @item @var{COUNT_MAX} @tab (Optional) shall be a scalar of type
12025 @code{INTEGER} with @code{INTENT(OUT)}.
12028 @item @emph{Example}:
12030 PROGRAM test_system_clock
12031 INTEGER :: count, count_rate, count_max
12032 CALL SYSTEM_CLOCK(count, count_rate, count_max)
12033 WRITE(*,*) count, count_rate, count_max
12037 @item @emph{See also}:
12038 @ref{DATE_AND_TIME}, @ref{CPU_TIME}
12044 @section @code{TAN} --- Tangent function
12047 @cindex trigonometric function, tangent
12051 @item @emph{Description}:
12052 @code{TAN(X)} computes the tangent of @var{X}.
12054 @item @emph{Standard}:
12055 Fortran 77 and later, for a complex argument Fortran 2008 or later
12057 @item @emph{Class}:
12060 @item @emph{Syntax}:
12061 @code{RESULT = TAN(X)}
12063 @item @emph{Arguments}:
12064 @multitable @columnfractions .15 .70
12065 @item @var{X} @tab The type shall be @code{REAL} or @code{COMPLEX}.
12068 @item @emph{Return value}:
12069 The return value has same type and kind as @var{X}.
12071 @item @emph{Example}:
12074 real(8) :: x = 0.165_8
12076 end program test_tan
12079 @item @emph{Specific names}:
12080 @multitable @columnfractions .20 .20 .20 .25
12081 @item Name @tab Argument @tab Return type @tab Standard
12082 @item @code{TAN(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab Fortran 95 and later
12083 @item @code{DTAN(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab Fortran 95 and later
12086 @item @emph{See also}:
12093 @section @code{TANH} --- Hyperbolic tangent function
12096 @cindex hyperbolic tangent
12097 @cindex hyperbolic function, tangent
12098 @cindex tangent, hyperbolic
12101 @item @emph{Description}:
12102 @code{TANH(X)} computes the hyperbolic tangent of @var{X}.
12104 @item @emph{Standard}:
12105 Fortran 77 and later, for a complex argument Fortran 2008 or later
12107 @item @emph{Class}:
12110 @item @emph{Syntax}:
12113 @item @emph{Arguments}:
12114 @multitable @columnfractions .15 .70
12115 @item @var{X} @tab The type shall be @code{REAL} or @code{COMPLEX}.
12118 @item @emph{Return value}:
12119 The return value has same type and kind as @var{X}. If @var{X} is
12120 complex, the imaginary part of the result is in radians. If @var{X}
12121 is @code{REAL}, the return value lies in the range
12122 @math{ - 1 \leq tanh(x) \leq 1 }.
12124 @item @emph{Example}:
12127 real(8) :: x = 2.1_8
12129 end program test_tanh
12132 @item @emph{Specific names}:
12133 @multitable @columnfractions .20 .20 .20 .25
12134 @item Name @tab Argument @tab Return type @tab Standard
12135 @item @code{TANH(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab Fortran 95 and later
12136 @item @code{DTANH(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab Fortran 95 and later
12139 @item @emph{See also}:
12146 @section @code{THIS_IMAGE} --- Function that returns the cosubscript index of this image
12147 @fnindex THIS_IMAGE
12148 @cindex coarray, @code{THIS_IMAGE}
12149 @cindex images, index of this image
12152 @item @emph{Description}:
12153 Returns the cosubscript for this image.
12155 @item @emph{Standard}:
12156 Fortran 2008 and later
12158 @item @emph{Class}:
12159 Transformational function
12161 @item @emph{Syntax}:
12162 @multitable @columnfractions .80
12163 @item @code{RESULT = THIS_IMAGE()}
12164 @item @code{RESULT = THIS_IMAGE(COARRAY [, DIM])}
12167 @item @emph{Arguments}:
12168 @multitable @columnfractions .15 .70
12169 @item @var{COARRAY} @tab Coarray of any type (optional; if @var{DIM}
12170 present, required).
12171 @item @var{DIM} @tab default integer scalar (optional). If present,
12172 @var{DIM} shall be between one and the corank of @var{COARRAY}.
12176 @item @emph{Return value}:
12177 Default integer. If @var{COARRAY} is not present, it is scalar and its value
12178 is the index of the invoking image. Otherwise, if @var{DIM} is not present,
12179 a rank-1 array with corank elements is returned, containing the cosubscripts
12180 for @var{COARRAY} specifying the invoking image. If @var{DIM} is present,
12181 a scalar is returned, with the value of the @var{DIM} element of
12182 @code{THIS_IMAGE(COARRAY)}.
12184 @item @emph{Example}:
12186 INTEGER :: value[*]
12188 value = THIS_IMAGE()
12190 IF (THIS_IMAGE() == 1) THEN
12191 DO i = 1, NUM_IMAGES()
12192 WRITE(*,'(2(a,i0))') 'value[', i, '] is ', value[i]
12197 @item @emph{See also}:
12198 @ref{NUM_IMAGES}, @ref{IMAGE_INDEX}
12204 @section @code{TIME} --- Time function
12206 @cindex time, current
12207 @cindex current time
12210 @item @emph{Description}:
12211 Returns the current time encoded as an integer (in the manner of the
12212 UNIX function @code{time(3)}). This value is suitable for passing to
12213 @code{CTIME}, @code{GMTIME}, and @code{LTIME}.
12215 This intrinsic is not fully portable, such as to systems with 32-bit
12216 @code{INTEGER} types but supporting times wider than 32 bits. Therefore,
12217 the values returned by this intrinsic might be, or become, negative, or
12218 numerically less than previous values, during a single run of the
12221 See @ref{TIME8}, for information on a similar intrinsic that might be
12222 portable to more GNU Fortran implementations, though to fewer Fortran
12225 @item @emph{Standard}:
12228 @item @emph{Class}:
12231 @item @emph{Syntax}:
12232 @code{RESULT = TIME()}
12234 @item @emph{Return value}:
12235 The return value is a scalar of type @code{INTEGER(4)}.
12237 @item @emph{See also}:
12238 @ref{CTIME}, @ref{GMTIME}, @ref{LTIME}, @ref{MCLOCK}, @ref{TIME8}
12245 @section @code{TIME8} --- Time function (64-bit)
12247 @cindex time, current
12248 @cindex current time
12251 @item @emph{Description}:
12252 Returns the current time encoded as an integer (in the manner of the
12253 UNIX function @code{time(3)}). This value is suitable for passing to
12254 @code{CTIME}, @code{GMTIME}, and @code{LTIME}.
12256 @emph{Warning:} this intrinsic does not increase the range of the timing
12257 values over that returned by @code{time(3)}. On a system with a 32-bit
12258 @code{time(3)}, @code{TIME8} will return a 32-bit value, even though
12259 it is converted to a 64-bit @code{INTEGER(8)} value. That means
12260 overflows of the 32-bit value can still occur. Therefore, the values
12261 returned by this intrinsic might be or become negative or numerically
12262 less than previous values during a single run of the compiled program.
12264 @item @emph{Standard}:
12267 @item @emph{Class}:
12270 @item @emph{Syntax}:
12271 @code{RESULT = TIME8()}
12273 @item @emph{Return value}:
12274 The return value is a scalar of type @code{INTEGER(8)}.
12276 @item @emph{See also}:
12277 @ref{CTIME}, @ref{GMTIME}, @ref{LTIME}, @ref{MCLOCK8}, @ref{TIME}
12284 @section @code{TINY} --- Smallest positive number of a real kind
12286 @cindex limits, smallest number
12287 @cindex model representation, smallest number
12290 @item @emph{Description}:
12291 @code{TINY(X)} returns the smallest positive (non zero) number
12292 in the model of the type of @code{X}.
12294 @item @emph{Standard}:
12295 Fortran 95 and later
12297 @item @emph{Class}:
12300 @item @emph{Syntax}:
12301 @code{RESULT = TINY(X)}
12303 @item @emph{Arguments}:
12304 @multitable @columnfractions .15 .70
12305 @item @var{X} @tab Shall be of type @code{REAL}.
12308 @item @emph{Return value}:
12309 The return value is of the same type and kind as @var{X}
12311 @item @emph{Example}:
12312 See @code{HUGE} for an example.
12318 @section @code{TRAILZ} --- Number of trailing zero bits of an integer
12323 @item @emph{Description}:
12324 @code{TRAILZ} returns the number of trailing zero bits of an integer.
12326 @item @emph{Standard}:
12327 Fortran 2008 and later
12329 @item @emph{Class}:
12332 @item @emph{Syntax}:
12333 @code{RESULT = TRAILZ(I)}
12335 @item @emph{Arguments}:
12336 @multitable @columnfractions .15 .70
12337 @item @var{I} @tab Shall be of type @code{INTEGER}.
12340 @item @emph{Return value}:
12341 The type of the return value is the default @code{INTEGER}.
12342 If all the bits of @code{I} are zero, the result value is @code{BIT_SIZE(I)}.
12344 @item @emph{Example}:
12346 PROGRAM test_trailz
12347 WRITE (*,*) TRAILZ(8) ! prints 3
12351 @item @emph{See also}:
12352 @ref{BIT_SIZE}, @ref{LEADZ}, @ref{POPPAR}, @ref{POPCNT}
12358 @section @code{TRANSFER} --- Transfer bit patterns
12364 @item @emph{Description}:
12365 Interprets the bitwise representation of @var{SOURCE} in memory as if it
12366 is the representation of a variable or array of the same type and type
12367 parameters as @var{MOLD}.
12369 This is approximately equivalent to the C concept of @emph{casting} one
12372 @item @emph{Standard}:
12373 Fortran 95 and later
12375 @item @emph{Class}:
12376 Transformational function
12378 @item @emph{Syntax}:
12379 @code{RESULT = TRANSFER(SOURCE, MOLD[, SIZE])}
12381 @item @emph{Arguments}:
12382 @multitable @columnfractions .15 .70
12383 @item @var{SOURCE} @tab Shall be a scalar or an array of any type.
12384 @item @var{MOLD} @tab Shall be a scalar or an array of any type.
12385 @item @var{SIZE} @tab (Optional) shall be a scalar of type
12389 @item @emph{Return value}:
12390 The result has the same type as @var{MOLD}, with the bit level
12391 representation of @var{SOURCE}. If @var{SIZE} is present, the result is
12392 a one-dimensional array of length @var{SIZE}. If @var{SIZE} is absent
12393 but @var{MOLD} is an array (of any size or shape), the result is a one-
12394 dimensional array of the minimum length needed to contain the entirety
12395 of the bitwise representation of @var{SOURCE}. If @var{SIZE} is absent
12396 and @var{MOLD} is a scalar, the result is a scalar.
12398 If the bitwise representation of the result is longer than that of
12399 @var{SOURCE}, then the leading bits of the result correspond to those of
12400 @var{SOURCE} and any trailing bits are filled arbitrarily.
12402 When the resulting bit representation does not correspond to a valid
12403 representation of a variable of the same type as @var{MOLD}, the results
12404 are undefined, and subsequent operations on the result cannot be
12405 guaranteed to produce sensible behavior. For example, it is possible to
12406 create @code{LOGICAL} variables for which @code{@var{VAR}} and
12407 @code{.NOT.@var{VAR}} both appear to be true.
12409 @item @emph{Example}:
12411 PROGRAM test_transfer
12412 integer :: x = 2143289344
12413 print *, transfer(x, 1.0) ! prints "NaN" on i686
12421 @section @code{TRANSPOSE} --- Transpose an array of rank two
12423 @cindex array, transpose
12424 @cindex matrix, transpose
12428 @item @emph{Description}:
12429 Transpose an array of rank two. Element (i, j) of the result has the value
12430 @code{MATRIX(j, i)}, for all i, j.
12432 @item @emph{Standard}:
12433 Fortran 95 and later
12435 @item @emph{Class}:
12436 Transformational function
12438 @item @emph{Syntax}:
12439 @code{RESULT = TRANSPOSE(MATRIX)}
12441 @item @emph{Arguments}:
12442 @multitable @columnfractions .15 .70
12443 @item @var{MATRIX} @tab Shall be an array of any type and have a rank of two.
12446 @item @emph{Return value}:
12447 The result has the same type as @var{MATRIX}, and has shape
12448 @code{(/ m, n /)} if @var{MATRIX} has shape @code{(/ n, m /)}.
12454 @section @code{TRIM} --- Remove trailing blank characters of a string
12456 @cindex string, remove trailing whitespace
12459 @item @emph{Description}:
12460 Removes trailing blank characters of a string.
12462 @item @emph{Standard}:
12463 Fortran 95 and later
12465 @item @emph{Class}:
12466 Transformational function
12468 @item @emph{Syntax}:
12469 @code{RESULT = TRIM(STRING)}
12471 @item @emph{Arguments}:
12472 @multitable @columnfractions .15 .70
12473 @item @var{STRING} @tab Shall be a scalar of type @code{CHARACTER}.
12476 @item @emph{Return value}:
12477 A scalar of type @code{CHARACTER} which length is that of @var{STRING}
12478 less the number of trailing blanks.
12480 @item @emph{Example}:
12483 CHARACTER(len=10), PARAMETER :: s = "GFORTRAN "
12484 WRITE(*,*) LEN(s), LEN(TRIM(s)) ! "10 8", with/without trailing blanks
12488 @item @emph{See also}:
12489 @ref{ADJUSTL}, @ref{ADJUSTR}
12495 @section @code{TTYNAM} --- Get the name of a terminal device.
12497 @cindex system, terminal
12500 @item @emph{Description}:
12501 Get the name of a terminal device. For more information,
12502 see @code{ttyname(3)}.
12504 This intrinsic is provided in both subroutine and function forms;
12505 however, only one form can be used in any given program unit.
12507 @item @emph{Standard}:
12510 @item @emph{Class}:
12511 Subroutine, function
12513 @item @emph{Syntax}:
12514 @multitable @columnfractions .80
12515 @item @code{CALL TTYNAM(UNIT, NAME)}
12516 @item @code{NAME = TTYNAM(UNIT)}
12519 @item @emph{Arguments}:
12520 @multitable @columnfractions .15 .70
12521 @item @var{UNIT} @tab Shall be a scalar @code{INTEGER}.
12522 @item @var{NAME} @tab Shall be of type @code{CHARACTER}.
12525 @item @emph{Example}:
12527 PROGRAM test_ttynam
12530 IF (isatty(unit=unit)) write(*,*) ttynam(unit)
12535 @item @emph{See also}:
12542 @section @code{UBOUND} --- Upper dimension bounds of an array
12544 @cindex array, upper bound
12547 @item @emph{Description}:
12548 Returns the upper bounds of an array, or a single upper bound
12549 along the @var{DIM} dimension.
12550 @item @emph{Standard}:
12551 Fortran 95 and later, with @var{KIND} argument Fortran 2003 and later
12553 @item @emph{Class}:
12556 @item @emph{Syntax}:
12557 @code{RESULT = UBOUND(ARRAY [, DIM [, KIND]])}
12559 @item @emph{Arguments}:
12560 @multitable @columnfractions .15 .70
12561 @item @var{ARRAY} @tab Shall be an array, of any type.
12562 @item @var{DIM} @tab (Optional) Shall be a scalar @code{INTEGER}.
12563 @item @var{KIND}@tab (Optional) An @code{INTEGER} initialization
12564 expression indicating the kind parameter of the result.
12567 @item @emph{Return value}:
12568 The return value is of type @code{INTEGER} and of kind @var{KIND}. If
12569 @var{KIND} is absent, the return value is of default integer kind.
12570 If @var{DIM} is absent, the result is an array of the upper bounds of
12571 @var{ARRAY}. If @var{DIM} is present, the result is a scalar
12572 corresponding to the upper bound of the array along that dimension. If
12573 @var{ARRAY} is an expression rather than a whole array or array
12574 structure component, or if it has a zero extent along the relevant
12575 dimension, the upper bound is taken to be the number of elements along
12576 the relevant dimension.
12578 @item @emph{See also}:
12579 @ref{LBOUND}, @ref{LCOBOUND}
12585 @section @code{UCOBOUND} --- Upper codimension bounds of an array
12587 @cindex coarray, upper bound
12590 @item @emph{Description}:
12591 Returns the upper cobounds of a coarray, or a single upper cobound
12592 along the @var{DIM} codimension.
12593 @item @emph{Standard}:
12594 Fortran 2008 and later
12596 @item @emph{Class}:
12599 @item @emph{Syntax}:
12600 @code{RESULT = UCOBOUND(COARRAY [, DIM [, KIND]])}
12602 @item @emph{Arguments}:
12603 @multitable @columnfractions .15 .70
12604 @item @var{ARRAY} @tab Shall be an coarray, of any type.
12605 @item @var{DIM} @tab (Optional) Shall be a scalar @code{INTEGER}.
12606 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
12607 expression indicating the kind parameter of the result.
12610 @item @emph{Return value}:
12611 The return value is of type @code{INTEGER} and of kind @var{KIND}. If
12612 @var{KIND} is absent, the return value is of default integer kind.
12613 If @var{DIM} is absent, the result is an array of the lower cobounds of
12614 @var{COARRAY}. If @var{DIM} is present, the result is a scalar
12615 corresponding to the lower cobound of the array along that codimension.
12617 @item @emph{See also}:
12618 @ref{LCOBOUND}, @ref{LBOUND}
12624 @section @code{UMASK} --- Set the file creation mask
12626 @cindex file system, file creation mask
12629 @item @emph{Description}:
12630 Sets the file creation mask to @var{MASK}. If called as a function, it
12631 returns the old value. If called as a subroutine and argument @var{OLD}
12632 if it is supplied, it is set to the old value. See @code{umask(2)}.
12634 @item @emph{Standard}:
12637 @item @emph{Class}:
12638 Subroutine, function
12640 @item @emph{Syntax}:
12641 @multitable @columnfractions .80
12642 @item @code{CALL UMASK(MASK [, OLD])}
12643 @item @code{OLD = UMASK(MASK)}
12646 @item @emph{Arguments}:
12647 @multitable @columnfractions .15 .70
12648 @item @var{MASK} @tab Shall be a scalar of type @code{INTEGER}.
12649 @item @var{OLD} @tab (Optional) Shall be a scalar of type
12658 @section @code{UNLINK} --- Remove a file from the file system
12660 @cindex file system, remove file
12663 @item @emph{Description}:
12664 Unlinks the file @var{PATH}. A null character (@code{CHAR(0)}) can be
12665 used to mark the end of the name in @var{PATH}; otherwise, trailing
12666 blanks in the file name are ignored. If the @var{STATUS} argument is
12667 supplied, it contains 0 on success or a nonzero error code upon return;
12668 see @code{unlink(2)}.
12670 This intrinsic is provided in both subroutine and function forms;
12671 however, only one form can be used in any given program unit.
12673 @item @emph{Standard}:
12676 @item @emph{Class}:
12677 Subroutine, function
12679 @item @emph{Syntax}:
12680 @multitable @columnfractions .80
12681 @item @code{CALL UNLINK(PATH [, STATUS])}
12682 @item @code{STATUS = UNLINK(PATH)}
12685 @item @emph{Arguments}:
12686 @multitable @columnfractions .15 .70
12687 @item @var{PATH} @tab Shall be of default @code{CHARACTER} type.
12688 @item @var{STATUS} @tab (Optional) Shall be of default @code{INTEGER} type.
12691 @item @emph{See also}:
12692 @ref{LINK}, @ref{SYMLNK}
12698 @section @code{UNPACK} --- Unpack an array of rank one into an array
12700 @cindex array, unpacking
12701 @cindex array, increase dimension
12702 @cindex array, scatter elements
12705 @item @emph{Description}:
12706 Store the elements of @var{VECTOR} in an array of higher rank.
12708 @item @emph{Standard}:
12709 Fortran 95 and later
12711 @item @emph{Class}:
12712 Transformational function
12714 @item @emph{Syntax}:
12715 @code{RESULT = UNPACK(VECTOR, MASK, FIELD)}
12717 @item @emph{Arguments}:
12718 @multitable @columnfractions .15 .70
12719 @item @var{VECTOR} @tab Shall be an array of any type and rank one. It
12720 shall have at least as many elements as @var{MASK} has @code{TRUE} values.
12721 @item @var{MASK} @tab Shall be an array of type @code{LOGICAL}.
12722 @item @var{FIELD} @tab Shall be of the same type as @var{VECTOR} and have
12723 the same shape as @var{MASK}.
12726 @item @emph{Return value}:
12727 The resulting array corresponds to @var{FIELD} with @code{TRUE} elements
12728 of @var{MASK} replaced by values from @var{VECTOR} in array element order.
12730 @item @emph{Example}:
12732 PROGRAM test_unpack
12733 integer :: vector(2) = (/1,1/)
12734 logical :: mask(4) = (/ .TRUE., .FALSE., .FALSE., .TRUE. /)
12735 integer :: field(2,2) = 0, unity(2,2)
12737 ! result: unity matrix
12738 unity = unpack(vector, reshape(mask, (/2,2/)), field)
12742 @item @emph{See also}:
12743 @ref{PACK}, @ref{SPREAD}
12749 @section @code{VERIFY} --- Scan a string for characters not a given set
12751 @cindex string, find missing set
12754 @item @emph{Description}:
12755 Verifies that all the characters in @var{STRING} belong to the set of
12756 characters in @var{SET}.
12758 If @var{BACK} is either absent or equals @code{FALSE}, this function
12759 returns the position of the leftmost character of @var{STRING} that is
12760 not in @var{SET}. If @var{BACK} equals @code{TRUE}, the rightmost
12761 position is returned. If all characters of @var{STRING} are found in
12762 @var{SET}, the result is zero.
12764 @item @emph{Standard}:
12765 Fortran 95 and later, with @var{KIND} argument Fortran 2003 and later
12767 @item @emph{Class}:
12770 @item @emph{Syntax}:
12771 @code{RESULT = VERIFY(STRING, SET[, BACK [, KIND]])}
12773 @item @emph{Arguments}:
12774 @multitable @columnfractions .15 .70
12775 @item @var{STRING} @tab Shall be of type @code{CHARACTER}.
12776 @item @var{SET} @tab Shall be of type @code{CHARACTER}.
12777 @item @var{BACK} @tab (Optional) shall be of type @code{LOGICAL}.
12778 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
12779 expression indicating the kind parameter of the result.
12782 @item @emph{Return value}:
12783 The return value is of type @code{INTEGER} and of kind @var{KIND}. If
12784 @var{KIND} is absent, the return value is of default integer kind.
12786 @item @emph{Example}:
12788 PROGRAM test_verify
12789 WRITE(*,*) VERIFY("FORTRAN", "AO") ! 1, found 'F'
12790 WRITE(*,*) VERIFY("FORTRAN", "FOO") ! 3, found 'R'
12791 WRITE(*,*) VERIFY("FORTRAN", "C++") ! 1, found 'F'
12792 WRITE(*,*) VERIFY("FORTRAN", "C++", .TRUE.) ! 7, found 'N'
12793 WRITE(*,*) VERIFY("FORTRAN", "FORTRAN") ! 0' found none
12797 @item @emph{See also}:
12798 @ref{SCAN}, @ref{INDEX intrinsic}
12804 @section @code{XOR} --- Bitwise logical exclusive OR
12806 @cindex bitwise logical exclusive or
12807 @cindex logical exclusive or, bitwise
12810 @item @emph{Description}:
12811 Bitwise logical exclusive or.
12813 This intrinsic routine is provided for backwards compatibility with
12814 GNU Fortran 77. For integer arguments, programmers should consider
12815 the use of the @ref{IEOR} intrinsic and for logical arguments the
12816 @code{.NEQV.} operator, which are both defined by the Fortran standard.
12818 @item @emph{Standard}:
12821 @item @emph{Class}:
12824 @item @emph{Syntax}:
12825 @code{RESULT = XOR(I, J)}
12827 @item @emph{Arguments}:
12828 @multitable @columnfractions .15 .70
12829 @item @var{I} @tab The type shall be either a scalar @code{INTEGER}
12830 type or a scalar @code{LOGICAL} type.
12831 @item @var{J} @tab The type shall be the same as the type of @var{I}.
12834 @item @emph{Return value}:
12835 The return type is either a scalar @code{INTEGER} or a scalar
12836 @code{LOGICAL}. If the kind type parameters differ, then the
12837 smaller kind type is implicitly converted to larger kind, and the
12838 return has the larger kind.
12840 @item @emph{Example}:
12843 LOGICAL :: T = .TRUE., F = .FALSE.
12845 DATA a / Z'F' /, b / Z'3' /
12847 WRITE (*,*) XOR(T, T), XOR(T, F), XOR(F, T), XOR(F, F)
12848 WRITE (*,*) XOR(a, b)
12852 @item @emph{See also}:
12853 Fortran 95 elemental function: @ref{IEOR}
12858 @node Intrinsic Modules
12859 @chapter Intrinsic Modules
12860 @cindex intrinsic Modules
12863 * ISO_FORTRAN_ENV::
12865 * OpenMP Modules OMP_LIB and OMP_LIB_KINDS::
12868 @node ISO_FORTRAN_ENV
12869 @section @code{ISO_FORTRAN_ENV}
12871 @item @emph{Standard}:
12872 Fortran 2003 and later, except when otherwise noted
12875 The @code{ISO_FORTRAN_ENV} module provides the following scalar default-integer
12879 @item @code{ATOMIC_INT_KIND}:
12880 Default-kind integer constant to be used as kind parameter when defining
12881 integer variables used in atomic operations. (Fortran 2008 or later.)
12883 @item @code{ATOMIC_LOGICAL_KIND}:
12884 Default-kind integer constant to be used as kind parameter when defining
12885 logical variables used in atomic operations. (Fortran 2008 or later.)
12887 @item @code{CHARACTER_KINDS}:
12888 Default-kind integer constant array of rank one containing the supported kind
12889 parameters of the @code{CHARACTER} type. (Fortran 2008 or later.)
12891 @item @code{CHARACTER_STORAGE_SIZE}:
12892 Size in bits of the character storage unit.
12894 @item @code{ERROR_UNIT}:
12895 Identifies the preconnected unit used for error reporting.
12897 @item @code{FILE_STORAGE_SIZE}:
12898 Size in bits of the file-storage unit.
12900 @item @code{INPUT_UNIT}:
12901 Identifies the preconnected unit identified by the asterisk
12902 (@code{*}) in @code{READ} statement.
12904 @item @code{INT8}, @code{INT16}, @code{INT32}, @code{INT64}:
12905 Kind type parameters to specify an INTEGER type with a storage
12906 size of 16, 32, and 64 bits. It is negative if a target platform
12907 does not support the particular kind. (Fortran 2008 or later.)
12909 @item @code{INTEGER_KINDS}:
12910 Default-kind integer constant array of rank one containing the supported kind
12911 parameters of the @code{INTEGER} type. (Fortran 2008 or later.)
12913 @item @code{IOSTAT_END}:
12914 The value assigned to the variable passed to the @code{IOSTAT=} specifier of
12915 an input/output statement if an end-of-file condition occurred.
12917 @item @code{IOSTAT_EOR}:
12918 The value assigned to the variable passed to the @code{IOSTAT=} specifier of
12919 an input/output statement if an end-of-record condition occurred.
12921 @item @code{IOSTAT_INQUIRE_INTERNAL_UNIT}:
12922 Scalar default-integer constant, used by @code{INQUIRE} for the
12923 @code{IOSTAT=} specifier to denote an that a unit number identifies an
12924 internal unit. (Fortran 2008 or later.)
12926 @item @code{NUMERIC_STORAGE_SIZE}:
12927 The size in bits of the numeric storage unit.
12929 @item @code{LOGICAL_KINDS}:
12930 Default-kind integer constant array of rank one containing the supported kind
12931 parameters of the @code{LOGICAL} type. (Fortran 2008 or later.)
12933 @item @code{OUTPUT_UNIT}:
12934 Identifies the preconnected unit identified by the asterisk
12935 (@code{*}) in @code{WRITE} statement.
12937 @item @code{REAL32}, @code{REAL64}, @code{REAL128}:
12938 Kind type parameters to specify a REAL type with a storage
12939 size of 32, 64, and 128 bits. It is negative if a target platform
12940 does not support the particular kind. (Fortran 2008 or later.)
12942 @item @code{REAL_KINDS}:
12943 Default-kind integer constant array of rank one containing the supported kind
12944 parameters of the @code{REAL} type. (Fortran 2008 or later.)
12946 @item @code{STAT_LOCKED}:
12947 Scalar default-integer constant used as STAT= return value by @code{LOCK} to
12948 denote that the lock variable is locked by the executing image. (Fortran 2008
12951 @item @code{STAT_LOCKED_OTHER_IMAGE}:
12952 Scalar default-integer constant used as STAT= return value by @code{UNLOCK} to
12953 denote that the lock variable is locked by another image. (Fortran 2008 or
12956 @item @code{STAT_STOPPED_IMAGE}:
12957 Positive, scalar default-integer constant used as STAT= return value if the
12958 argument in the statement requires synchronisation with an image, which has
12959 initiated the termination of the execution. (Fortran 2008 or later.)
12961 @item @code{STAT_UNLOCKED}:
12962 Scalar default-integer constant used as STAT= return value by @code{UNLOCK} to
12963 denote that the lock variable is unlocked. (Fortran 2008 or later.)
12966 The module also provides the following intrinsic procedures:
12967 @ref{COMPILER_OPTIONS} and @ref{COMPILER_VERSION}.
12971 @node ISO_C_BINDING
12972 @section @code{ISO_C_BINDING}
12974 @item @emph{Standard}:
12975 Fortran 2003 and later, GNU extensions
12978 The following intrinsic procedures are provided by the module; their
12979 definition can be found in the section Intrinsic Procedures of this
12983 @item @code{C_ASSOCIATED}
12984 @item @code{C_F_POINTER}
12985 @item @code{C_F_PROCPOINTER}
12986 @item @code{C_FUNLOC}
12988 @item @code{C_SIZEOF}
12990 @c TODO: Vertical spacing between C_FUNLOC and C_LOC wrong in PDF,
12991 @c don't really know why.
12993 The @code{ISO_C_BINDING} module provides the following named constants of
12994 type default integer, which can be used as KIND type parameters.
12996 In addition to the integer named constants required by the Fortran 2003
12997 standard, GNU Fortran provides as an extension named constants for the
12998 128-bit integer types supported by the C compiler: @code{C_INT128_T,
12999 C_INT_LEAST128_T, C_INT_FAST128_T}.
13001 @multitable @columnfractions .15 .35 .35 .35
13002 @item Fortran Type @tab Named constant @tab C type @tab Extension
13003 @item @code{INTEGER}@tab @code{C_INT} @tab @code{int}
13004 @item @code{INTEGER}@tab @code{C_SHORT} @tab @code{short int}
13005 @item @code{INTEGER}@tab @code{C_LONG} @tab @code{long int}
13006 @item @code{INTEGER}@tab @code{C_LONG_LONG} @tab @code{long long int}
13007 @item @code{INTEGER}@tab @code{C_SIGNED_CHAR} @tab @code{signed char}/@code{unsigned char}
13008 @item @code{INTEGER}@tab @code{C_SIZE_T} @tab @code{size_t}
13009 @item @code{INTEGER}@tab @code{C_INT8_T} @tab @code{int8_t}
13010 @item @code{INTEGER}@tab @code{C_INT16_T} @tab @code{int16_t}
13011 @item @code{INTEGER}@tab @code{C_INT32_T} @tab @code{int32_t}
13012 @item @code{INTEGER}@tab @code{C_INT64_T} @tab @code{int64_t}
13013 @item @code{INTEGER}@tab @code{C_INT128_T} @tab @code{int128_t} @tab Ext.
13014 @item @code{INTEGER}@tab @code{C_INT_LEAST8_T} @tab @code{int_least8_t}
13015 @item @code{INTEGER}@tab @code{C_INT_LEAST16_T} @tab @code{int_least16_t}
13016 @item @code{INTEGER}@tab @code{C_INT_LEAST32_T} @tab @code{int_least32_t}
13017 @item @code{INTEGER}@tab @code{C_INT_LEAST64_T} @tab @code{int_least64_t}
13018 @item @code{INTEGER}@tab @code{C_INT_LEAST128_T}@tab @code{int_least128_t} @tab Ext.
13019 @item @code{INTEGER}@tab @code{C_INT_FAST8_T} @tab @code{int_fast8_t}
13020 @item @code{INTEGER}@tab @code{C_INT_FAST16_T} @tab @code{int_fast16_t}
13021 @item @code{INTEGER}@tab @code{C_INT_FAST32_T} @tab @code{int_fast32_t}
13022 @item @code{INTEGER}@tab @code{C_INT_FAST64_T} @tab @code{int_fast64_t}
13023 @item @code{INTEGER}@tab @code{C_INT_FAST128_T} @tab @code{int_fast128_t} @tab Ext.
13024 @item @code{INTEGER}@tab @code{C_INTMAX_T} @tab @code{intmax_t}
13025 @item @code{INTEGER}@tab @code{C_INTPTR_T} @tab @code{intptr_t}
13026 @item @code{REAL} @tab @code{C_FLOAT} @tab @code{float}
13027 @item @code{REAL} @tab @code{C_DOUBLE} @tab @code{double}
13028 @item @code{REAL} @tab @code{C_LONG_DOUBLE} @tab @code{long double}
13029 @item @code{COMPLEX}@tab @code{C_FLOAT_COMPLEX} @tab @code{float _Complex}
13030 @item @code{COMPLEX}@tab @code{C_DOUBLE_COMPLEX}@tab @code{double _Complex}
13031 @item @code{COMPLEX}@tab @code{C_LONG_DOUBLE_COMPLEX}@tab @code{long double _Complex}
13032 @item @code{LOGICAL}@tab @code{C_BOOL} @tab @code{_Bool}
13033 @item @code{CHARACTER}@tab @code{C_CHAR} @tab @code{char}
13036 Additionally, the following parameters of type @code{CHARACTER(KIND=C_CHAR)}
13039 @multitable @columnfractions .20 .45 .15
13040 @item Name @tab C definition @tab Value
13041 @item @code{C_NULL_CHAR} @tab null character @tab @code{'\0'}
13042 @item @code{C_ALERT} @tab alert @tab @code{'\a'}
13043 @item @code{C_BACKSPACE} @tab backspace @tab @code{'\b'}
13044 @item @code{C_FORM_FEED} @tab form feed @tab @code{'\f'}
13045 @item @code{C_NEW_LINE} @tab new line @tab @code{'\n'}
13046 @item @code{C_CARRIAGE_RETURN} @tab carriage return @tab @code{'\r'}
13047 @item @code{C_HORIZONTAL_TAB} @tab horizontal tab @tab @code{'\t'}
13048 @item @code{C_VERTICAL_TAB} @tab vertical tab @tab @code{'\v'}
13051 Moreover, the following two named constants are defined:
13053 @multitable @columnfractions .20 .80
13054 @item Name @tab Type
13055 @item @code{C_NULL_PTR} @tab @code{C_PTR}
13056 @item @code{C_NULL_FUNPTR} @tab @code{C_FUNPTR}
13059 Both are equivalent to the value @code{NULL} in C.
13061 @node OpenMP Modules OMP_LIB and OMP_LIB_KINDS
13062 @section OpenMP Modules @code{OMP_LIB} and @code{OMP_LIB_KINDS}
13064 @item @emph{Standard}:
13065 OpenMP Application Program Interface v3.0
13069 The OpenMP Fortran runtime library routines are provided both in
13070 a form of two Fortran 90 modules, named @code{OMP_LIB} and
13071 @code{OMP_LIB_KINDS}, and in a form of a Fortran @code{include} file named
13072 @file{omp_lib.h}. The procedures provided by @code{OMP_LIB} can be found
13073 in the @ref{Top,,Introduction,libgomp,GNU OpenMP runtime library} manual,
13074 the named constants defined in the modules are listed
13077 For details refer to the actual
13078 @uref{http://www.openmp.org/mp-documents/spec30.pdf,
13079 OpenMP Application Program Interface v3.0}.
13081 @code{OMP_LIB_KINDS} provides the following scalar default-integer
13085 @item @code{omp_integer_kind}
13086 @item @code{omp_logical_kind}
13087 @item @code{omp_lock_kind}
13088 @item @code{omp_nest_lock_kind}
13089 @item @code{omp_sched_kind}
13092 @code{OMP_LIB} provides the scalar default-integer
13093 named constant @code{openmp_version} with a value of the form
13094 @var{yyyymm}, where @code{yyyy} is the year and @var{mm} the month
13095 of the OpenMP version; for OpenMP v3.0 the value is @code{200805}.
13097 And the following scalar integer named constants of the
13098 kind @code{omp_sched_kind}:
13101 @item @code{omp_sched_static}
13102 @item @code{omp_sched_dynamic}
13103 @item @code{omp_sched_guided}
13104 @item @code{omp_sched_auto}