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, Hyperbolic arccosine 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, Hyperbolic arcsine 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, Hyperbolic arctangent function
64 * @code{BESSEL_J0}: BESSEL_J0, Bessel function of the first kind of order 0
65 * @code{BESSEL_J1}: BESSEL_J1, Bessel function of the first kind of order 1
66 * @code{BESSEL_JN}: BESSEL_JN, Bessel function of the first kind
67 * @code{BESSEL_Y0}: BESSEL_Y0, Bessel function of the second kind of order 0
68 * @code{BESSEL_Y1}: BESSEL_Y1, Bessel function of the second kind of order 1
69 * @code{BESSEL_YN}: BESSEL_YN, Bessel function of the second kind
70 * @code{BIT_SIZE}: BIT_SIZE, Bit size inquiry function
71 * @code{BTEST}: BTEST, Bit test function
72 * @code{C_ASSOCIATED}: C_ASSOCIATED, Status of a C pointer
73 * @code{C_F_POINTER}: C_F_POINTER, Convert C into Fortran pointer
74 * @code{C_F_PROCPOINTER}: C_F_PROCPOINTER, Convert C into Fortran procedure pointer
75 * @code{C_FUNLOC}: C_FUNLOC, Obtain the C address of a procedure
76 * @code{C_LOC}: C_LOC, Obtain the C address of an object
77 * @code{C_SIZEOF}: C_SIZEOF, Size in bytes of an expression
78 * @code{CEILING}: CEILING, Integer ceiling function
79 * @code{CHAR}: CHAR, Integer-to-character conversion function
80 * @code{CHDIR}: CHDIR, Change working directory
81 * @code{CHMOD}: CHMOD, Change access permissions of files
82 * @code{CMPLX}: CMPLX, Complex conversion function
83 * @code{COMMAND_ARGUMENT_COUNT}: COMMAND_ARGUMENT_COUNT, Get number of command line arguments
84 * @code{COMPLEX}: COMPLEX, Complex conversion function
85 * @code{CONJG}: CONJG, Complex conjugate function
86 * @code{COS}: COS, Cosine function
87 * @code{COSH}: COSH, Hyperbolic cosine function
88 * @code{COUNT}: COUNT, Count occurrences of TRUE in an array
89 * @code{CPU_TIME}: CPU_TIME, CPU time subroutine
90 * @code{CSHIFT}: CSHIFT, Circular shift elements of an array
91 * @code{CTIME}: CTIME, Subroutine (or function) to convert a time into a string
92 * @code{DATE_AND_TIME}: DATE_AND_TIME, Date and time subroutine
93 * @code{DBLE}: DBLE, Double precision conversion function
94 * @code{DCMPLX}: DCMPLX, Double complex conversion function
95 * @code{DIGITS}: DIGITS, Significant digits function
96 * @code{DIM}: DIM, Positive difference
97 * @code{DOT_PRODUCT}: DOT_PRODUCT, Dot product function
98 * @code{DPROD}: DPROD, Double product function
99 * @code{DREAL}: DREAL, Double real part function
100 * @code{DTIME}: DTIME, Execution time subroutine (or function)
101 * @code{EOSHIFT}: EOSHIFT, End-off shift elements of an array
102 * @code{EPSILON}: EPSILON, Epsilon function
103 * @code{ERF}: ERF, Error function
104 * @code{ERFC}: ERFC, Complementary error function
105 * @code{ERFC_SCALED}: ERFC_SCALED, Exponentially-scaled complementary error function
106 * @code{ETIME}: ETIME, Execution time subroutine (or function)
107 * @code{EXIT}: EXIT, Exit the program with status.
108 * @code{EXP}: EXP, Exponential function
109 * @code{EXPONENT}: EXPONENT, Exponent function
110 * @code{FDATE}: FDATE, Subroutine (or function) to get the current time as a string
111 * @code{FGET}: FGET, Read a single character in stream mode from stdin
112 * @code{FGETC}: FGETC, Read a single character in stream mode
113 * @code{FLOOR}: FLOOR, Integer floor function
114 * @code{FLUSH}: FLUSH, Flush I/O unit(s)
115 * @code{FNUM}: FNUM, File number function
116 * @code{FPUT}: FPUT, Write a single character in stream mode to stdout
117 * @code{FPUTC}: FPUTC, Write a single character in stream mode
118 * @code{FRACTION}: FRACTION, Fractional part of the model representation
119 * @code{FREE}: FREE, Memory de-allocation subroutine
120 * @code{FSEEK}: FSEEK, Low level file positioning subroutine
121 * @code{FSTAT}: FSTAT, Get file status
122 * @code{FTELL}: FTELL, Current stream position
123 * @code{GAMMA}: GAMMA, Gamma function
124 * @code{GERROR}: GERROR, Get last system error message
125 * @code{GETARG}: GETARG, Get command line arguments
126 * @code{GET_COMMAND}: GET_COMMAND, Get the entire command line
127 * @code{GET_COMMAND_ARGUMENT}: GET_COMMAND_ARGUMENT, Get command line arguments
128 * @code{GETCWD}: GETCWD, Get current working directory
129 * @code{GETENV}: GETENV, Get an environmental variable
130 * @code{GET_ENVIRONMENT_VARIABLE}: GET_ENVIRONMENT_VARIABLE, Get an environmental variable
131 * @code{GETGID}: GETGID, Group ID function
132 * @code{GETLOG}: GETLOG, Get login name
133 * @code{GETPID}: GETPID, Process ID function
134 * @code{GETUID}: GETUID, User ID function
135 * @code{GMTIME}: GMTIME, Convert time to GMT info
136 * @code{HOSTNM}: HOSTNM, Get system host name
137 * @code{HUGE}: HUGE, Largest number of a kind
138 * @code{HYPOT}: HYPOT, Euclidian distance function
139 * @code{IACHAR}: IACHAR, Code in @acronym{ASCII} collating sequence
140 * @code{IAND}: IAND, Bitwise logical and
141 * @code{IARGC}: IARGC, Get the number of command line arguments
142 * @code{IBCLR}: IBCLR, Clear bit
143 * @code{IBITS}: IBITS, Bit extraction
144 * @code{IBSET}: IBSET, Set bit
145 * @code{ICHAR}: ICHAR, Character-to-integer conversion function
146 * @code{IDATE}: IDATE, Current local time (day/month/year)
147 * @code{IEOR}: IEOR, Bitwise logical exclusive or
148 * @code{IERRNO}: IERRNO, Function to get the last system error number
149 * @code{INDEX}: INDEX intrinsic, Position of a substring within a string
150 * @code{INT}: INT, Convert to integer type
151 * @code{INT2}: INT2, Convert to 16-bit integer type
152 * @code{INT8}: INT8, Convert to 64-bit integer type
153 * @code{IOR}: IOR, Bitwise logical or
154 * @code{IRAND}: IRAND, Integer pseudo-random number
155 * @code{IMAGE_INDEX}: IMAGE_INDEX, Cosubscript to image index convertion
156 * @code{IS_IOSTAT_END}: IS_IOSTAT_END, Test for end-of-file value
157 * @code{IS_IOSTAT_EOR}: IS_IOSTAT_EOR, Test for end-of-record value
158 * @code{ISATTY}: ISATTY, Whether a unit is a terminal device
159 * @code{ISHFT}: ISHFT, Shift bits
160 * @code{ISHFTC}: ISHFTC, Shift bits circularly
161 * @code{ISNAN}: ISNAN, Tests for a NaN
162 * @code{ITIME}: ITIME, Current local time (hour/minutes/seconds)
163 * @code{KILL}: KILL, Send a signal to a process
164 * @code{KIND}: KIND, Kind of an entity
165 * @code{LBOUND}: LBOUND, Lower dimension bounds of an array
166 * @code{LCOBOUND}: LCOBOUND, Lower codimension bounds of an array
167 * @code{LEADZ}: LEADZ, Number of leading zero bits of an integer
168 * @code{LEN}: LEN, Length of a character entity
169 * @code{LEN_TRIM}: LEN_TRIM, Length of a character entity without trailing blank characters
170 * @code{LGE}: LGE, Lexical greater than or equal
171 * @code{LGT}: LGT, Lexical greater than
172 * @code{LINK}: LINK, Create a hard link
173 * @code{LLE}: LLE, Lexical less than or equal
174 * @code{LLT}: LLT, Lexical less than
175 * @code{LNBLNK}: LNBLNK, Index of the last non-blank character in a string
176 * @code{LOC}: LOC, Returns the address of a variable
177 * @code{LOG}: LOG, Logarithm function
178 * @code{LOG10}: LOG10, Base 10 logarithm function
179 * @code{LOG_GAMMA}: LOG_GAMMA, Logarithm of the Gamma function
180 * @code{LOGICAL}: LOGICAL, Convert to logical type
181 * @code{LONG}: LONG, Convert to integer type
182 * @code{LSHIFT}: LSHIFT, Left shift bits
183 * @code{LSTAT}: LSTAT, Get file status
184 * @code{LTIME}: LTIME, Convert time to local time info
185 * @code{MALLOC}: MALLOC, Dynamic memory allocation function
186 * @code{MATMUL}: MATMUL, matrix multiplication
187 * @code{MAX}: MAX, Maximum value of an argument list
188 * @code{MAXEXPONENT}: MAXEXPONENT, Maximum exponent of a real kind
189 * @code{MAXLOC}: MAXLOC, Location of the maximum value within an array
190 * @code{MAXVAL}: MAXVAL, Maximum value of an array
191 * @code{MCLOCK}: MCLOCK, Time function
192 * @code{MCLOCK8}: MCLOCK8, Time function (64-bit)
193 * @code{MERGE}: MERGE, Merge arrays
194 * @code{MIN}: MIN, Minimum value of an argument list
195 * @code{MINEXPONENT}: MINEXPONENT, Minimum exponent of a real kind
196 * @code{MINLOC}: MINLOC, Location of the minimum value within an array
197 * @code{MINVAL}: MINVAL, Minimum value of an array
198 * @code{MOD}: MOD, Remainder function
199 * @code{MODULO}: MODULO, Modulo function
200 * @code{MOVE_ALLOC}: MOVE_ALLOC, Move allocation from one object to another
201 * @code{MVBITS}: MVBITS, Move bits from one integer to another
202 * @code{NEAREST}: NEAREST, Nearest representable number
203 * @code{NEW_LINE}: NEW_LINE, New line character
204 * @code{NINT}: NINT, Nearest whole number
205 * @code{NOT}: NOT, Logical negation
206 * @code{NULL}: NULL, Function that returns an disassociated pointer
207 * @code{NUM_IMAGES}: NUM_IMAGES, Number of images
208 * @code{OR}: OR, Bitwise logical OR
209 * @code{PACK}: PACK, Pack an array into an array of rank one
210 * @code{PERROR}: PERROR, Print system error message
211 * @code{PRECISION}: PRECISION, Decimal precision of a real kind
212 * @code{PRESENT}: PRESENT, Determine whether an optional dummy argument is specified
213 * @code{PRODUCT}: PRODUCT, Product of array elements
214 * @code{RADIX}: RADIX, Base of a data model
215 * @code{RANDOM_NUMBER}: RANDOM_NUMBER, Pseudo-random number
216 * @code{RANDOM_SEED}: RANDOM_SEED, Initialize a pseudo-random number sequence
217 * @code{RAND}: RAND, Real pseudo-random number
218 * @code{RANGE}: RANGE, Decimal exponent range
219 * @code{RAN}: RAN, Real pseudo-random number
220 * @code{REAL}: REAL, Convert to real type
221 * @code{RENAME}: RENAME, Rename a file
222 * @code{REPEAT}: REPEAT, Repeated string concatenation
223 * @code{RESHAPE}: RESHAPE, Function to reshape an array
224 * @code{RRSPACING}: RRSPACING, Reciprocal of the relative spacing
225 * @code{RSHIFT}: RSHIFT, Right shift bits
226 * @code{SCALE}: SCALE, Scale a real value
227 * @code{SCAN}: SCAN, Scan a string for the presence of a set of characters
228 * @code{SECNDS}: SECNDS, Time function
229 * @code{SECOND}: SECOND, CPU time function
230 * @code{SELECTED_CHAR_KIND}: SELECTED_CHAR_KIND, Choose character kind
231 * @code{SELECTED_INT_KIND}: SELECTED_INT_KIND, Choose integer kind
232 * @code{SELECTED_REAL_KIND}: SELECTED_REAL_KIND, Choose real kind
233 * @code{SET_EXPONENT}: SET_EXPONENT, Set the exponent of the model
234 * @code{SHAPE}: SHAPE, Determine the shape of an array
235 * @code{SIGN}: SIGN, Sign copying function
236 * @code{SIGNAL}: SIGNAL, Signal handling subroutine (or function)
237 * @code{SIN}: SIN, Sine function
238 * @code{SINH}: SINH, Hyperbolic sine function
239 * @code{SIZE}: SIZE, Function to determine the size of an array
240 * @code{SIZEOF}: SIZEOF, Determine the size in bytes of an expression
241 * @code{SLEEP}: SLEEP, Sleep for the specified number of seconds
242 * @code{SPACING}: SPACING, Smallest distance between two numbers of a given type
243 * @code{SPREAD}: SPREAD, Add a dimension to an array
244 * @code{SQRT}: SQRT, Square-root function
245 * @code{SRAND}: SRAND, Reinitialize the random number generator
246 * @code{STAT}: STAT, Get file status
247 * @code{SUM}: SUM, Sum of array elements
248 * @code{SYMLNK}: SYMLNK, Create a symbolic link
249 * @code{SYSTEM}: SYSTEM, Execute a shell command
250 * @code{SYSTEM_CLOCK}: SYSTEM_CLOCK, Time function
251 * @code{TAN}: TAN, Tangent function
252 * @code{TANH}: TANH, Hyperbolic tangent function
253 * @code{THIS_IMAGE}: THIS_IMAGE, Cosubscript index of this image
254 * @code{TIME}: TIME, Time function
255 * @code{TIME8}: TIME8, Time function (64-bit)
256 * @code{TINY}: TINY, Smallest positive number of a real kind
257 * @code{TRAILZ}: TRAILZ, Number of trailing zero bits of an integer
258 * @code{TRANSFER}: TRANSFER, Transfer bit patterns
259 * @code{TRANSPOSE}: TRANSPOSE, Transpose an array of rank two
260 * @code{TRIM}: TRIM, Remove trailing blank characters of a string
261 * @code{TTYNAM}: TTYNAM, Get the name of a terminal device.
262 * @code{UBOUND}: UBOUND, Upper dimension bounds of an array
263 * @code{UCOBOUND}: UCOBOUND, Upper codimension bounds of an array
264 * @code{UMASK}: UMASK, Set the file creation mask
265 * @code{UNLINK}: UNLINK, Remove a file from the file system
266 * @code{UNPACK}: UNPACK, Unpack an array of rank one into an array
267 * @code{VERIFY}: VERIFY, Scan a string for the absence of a set of characters
268 * @code{XOR}: XOR, Bitwise logical exclusive or
271 @node Introduction to Intrinsics
272 @section Introduction to intrinsic procedures
274 The intrinsic procedures provided by GNU Fortran include all of the
275 intrinsic procedures required by the Fortran 95 standard, a set of
276 intrinsic procedures for backwards compatibility with G77, and a
277 selection of intrinsic procedures from the Fortran 2003 and Fortran 2008
278 standards. Any conflict between a description here and a description in
279 either the Fortran 95 standard, the Fortran 2003 standard or the Fortran
280 2008 standard is unintentional, and the standard(s) should be considered
283 The enumeration of the @code{KIND} type parameter is processor defined in
284 the Fortran 95 standard. GNU Fortran defines the default integer type and
285 default real type by @code{INTEGER(KIND=4)} and @code{REAL(KIND=4)},
286 respectively. The standard mandates that both data types shall have
287 another kind, which have more precision. On typical target architectures
288 supported by @command{gfortran}, this kind type parameter is @code{KIND=8}.
289 Hence, @code{REAL(KIND=8)} and @code{DOUBLE PRECISION} are equivalent.
290 In the description of generic intrinsic procedures, the kind type parameter
291 will be specified by @code{KIND=*}, and in the description of specific
292 names for an intrinsic procedure the kind type parameter will be explicitly
293 given (e.g., @code{REAL(KIND=4)} or @code{REAL(KIND=8)}). Finally, for
294 brevity the optional @code{KIND=} syntax will be omitted.
296 Many of the intrinsic procedures take one or more optional arguments.
297 This document follows the convention used in the Fortran 95 standard,
298 and denotes such arguments by square brackets.
300 GNU Fortran offers the @option{-std=f95} and @option{-std=gnu} options,
301 which can be used to restrict the set of intrinsic procedures to a
302 given standard. By default, @command{gfortran} sets the @option{-std=gnu}
303 option, and so all intrinsic procedures described here are accepted. There
304 is one caveat. For a select group of intrinsic procedures, @command{g77}
305 implemented both a function and a subroutine. Both classes
306 have been implemented in @command{gfortran} for backwards compatibility
307 with @command{g77}. It is noted here that these functions and subroutines
308 cannot be intermixed in a given subprogram. In the descriptions that follow,
309 the applicable standard for each intrinsic procedure is noted.
314 @section @code{ABORT} --- Abort the program
316 @cindex program termination, with core dump
317 @cindex terminate program, with core dump
321 @item @emph{Description}:
322 @code{ABORT} causes immediate termination of the program. On operating
323 systems that support a core dump, @code{ABORT} will produce a core dump even if
324 the option @option{-fno-dump-core} is in effect, which is suitable for debugging
326 @c TODO: Check if this (with -fno-dump-core) is correct.
328 @item @emph{Standard}:
337 @item @emph{Return value}:
340 @item @emph{Example}:
343 integer :: i = 1, j = 2
344 if (i /= j) call abort
345 end program test_abort
348 @item @emph{See also}:
349 @ref{EXIT}, @ref{KILL}
356 @section @code{ABS} --- Absolute value
363 @cindex absolute value
366 @item @emph{Description}:
367 @code{ABS(A)} computes the absolute value of @code{A}.
369 @item @emph{Standard}:
370 Fortran 77 and later, has overloads that are GNU extensions
376 @code{RESULT = ABS(A)}
378 @item @emph{Arguments}:
379 @multitable @columnfractions .15 .70
380 @item @var{A} @tab The type of the argument shall be an @code{INTEGER},
381 @code{REAL}, or @code{COMPLEX}.
384 @item @emph{Return value}:
385 The return value is of the same type and
386 kind as the argument except the return value is @code{REAL} for a
387 @code{COMPLEX} argument.
389 @item @emph{Example}:
394 complex :: z = (-1.e0,0.e0)
401 @item @emph{Specific names}:
402 @multitable @columnfractions .20 .20 .20 .25
403 @item Name @tab Argument @tab Return type @tab Standard
404 @item @code{ABS(A)} @tab @code{REAL(4) A} @tab @code{REAL(4)} @tab Fortran 77 and later
405 @item @code{CABS(A)} @tab @code{COMPLEX(4) A} @tab @code{REAL(4)} @tab Fortran 77 and later
406 @item @code{DABS(A)} @tab @code{REAL(8) A} @tab @code{REAL(8)} @tab Fortran 77 and later
407 @item @code{IABS(A)} @tab @code{INTEGER(4) A} @tab @code{INTEGER(4)} @tab Fortran 77 and later
408 @item @code{ZABS(A)} @tab @code{COMPLEX(8) A} @tab @code{COMPLEX(8)} @tab GNU extension
409 @item @code{CDABS(A)} @tab @code{COMPLEX(8) A} @tab @code{COMPLEX(8)} @tab GNU extension
416 @section @code{ACCESS} --- Checks file access modes
418 @cindex file system, access mode
421 @item @emph{Description}:
422 @code{ACCESS(NAME, MODE)} checks whether the file @var{NAME}
423 exists, is readable, writable or executable. Except for the
424 executable check, @code{ACCESS} can be replaced by
425 Fortran 95's @code{INQUIRE}.
427 @item @emph{Standard}:
434 @code{RESULT = ACCESS(NAME, MODE)}
436 @item @emph{Arguments}:
437 @multitable @columnfractions .15 .70
438 @item @var{NAME} @tab Scalar @code{CHARACTER} of default kind with the
439 file name. Tailing blank are ignored unless the character @code{achar(0)}
440 is present, then all characters up to and excluding @code{achar(0)} are
442 @item @var{MODE} @tab Scalar @code{CHARACTER} of default kind with the
443 file access mode, may be any concatenation of @code{"r"} (readable),
444 @code{"w"} (writable) and @code{"x"} (executable), or @code{" "} to check
448 @item @emph{Return value}:
449 Returns a scalar @code{INTEGER}, which is @code{0} if the file is
450 accessible in the given mode; otherwise or if an invalid argument
451 has been given for @code{MODE} the value @code{1} is returned.
453 @item @emph{Example}:
457 character(len=*), parameter :: file = 'test.dat'
458 character(len=*), parameter :: file2 = 'test.dat '//achar(0)
459 if(access(file,' ') == 0) print *, trim(file),' is exists'
460 if(access(file,'r') == 0) print *, trim(file),' is readable'
461 if(access(file,'w') == 0) print *, trim(file),' is writable'
462 if(access(file,'x') == 0) print *, trim(file),' is executable'
463 if(access(file2,'rwx') == 0) &
464 print *, trim(file2),' is readable, writable and executable'
465 end program access_test
467 @item @emph{Specific names}:
468 @item @emph{See also}:
475 @section @code{ACHAR} --- Character in @acronym{ASCII} collating sequence
477 @cindex @acronym{ASCII} collating sequence
478 @cindex collating sequence, @acronym{ASCII}
481 @item @emph{Description}:
482 @code{ACHAR(I)} returns the character located at position @code{I}
483 in the @acronym{ASCII} collating sequence.
485 @item @emph{Standard}:
486 Fortran 77 and later, with @var{KIND} argument Fortran 2003 and later
492 @code{RESULT = ACHAR(I [, KIND])}
494 @item @emph{Arguments}:
495 @multitable @columnfractions .15 .70
496 @item @var{I} @tab The type shall be @code{INTEGER}.
497 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
498 expression indicating the kind parameter of the result.
501 @item @emph{Return value}:
502 The return value is of type @code{CHARACTER} with a length of one.
503 If the @var{KIND} argument is present, the return value is of the
504 specified kind and of the default kind otherwise.
506 @item @emph{Example}:
511 end program test_achar
515 See @ref{ICHAR} for a discussion of converting between numerical values
516 and formatted string representations.
518 @item @emph{See also}:
519 @ref{CHAR}, @ref{IACHAR}, @ref{ICHAR}
526 @section @code{ACOS} --- Arccosine function
529 @cindex trigonometric function, cosine, inverse
530 @cindex cosine, inverse
533 @item @emph{Description}:
534 @code{ACOS(X)} computes the arccosine of @var{X} (inverse of @code{COS(X)}).
536 @item @emph{Standard}:
537 Fortran 77 and later, for a complex argument Fortran 2008 or later
543 @code{RESULT = ACOS(X)}
545 @item @emph{Arguments}:
546 @multitable @columnfractions .15 .70
547 @item @var{X} @tab The type shall either be @code{REAL} with a magnitude that is
548 less than or equal to one - or the type shall be @code{COMPLEX}.
551 @item @emph{Return value}:
552 The return value is of the same type and kind as @var{X}.
553 The real part of the result is in radians and lies in the range
554 @math{0 \leq \Re \acos(x) \leq \pi}.
556 @item @emph{Example}:
559 real(8) :: x = 0.866_8
561 end program test_acos
564 @item @emph{Specific names}:
565 @multitable @columnfractions .20 .20 .20 .25
566 @item Name @tab Argument @tab Return type @tab Standard
567 @item @code{ACOS(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab Fortran 77 and later
568 @item @code{DACOS(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab Fortran 77 and later
571 @item @emph{See also}:
572 Inverse function: @ref{COS}
579 @section @code{ACOSH} --- Hyperbolic arccosine function
582 @cindex area hyperbolic cosine
583 @cindex hyperbolic arccosine
584 @cindex hyperbolic function, cosine, inverse
585 @cindex cosine, hyperbolic, inverse
588 @item @emph{Description}:
589 @code{ACOSH(X)} computes the hyperbolic arccosine of @var{X} (inverse of
592 @item @emph{Standard}:
593 Fortran 2008 and later
599 @code{RESULT = ACOSH(X)}
601 @item @emph{Arguments}:
602 @multitable @columnfractions .15 .70
603 @item @var{X} @tab The type shall be @code{REAL} or @code{COMPLEX}.
606 @item @emph{Return value}:
607 The return value has the same type and kind as @var{X}. If @var{X} is
608 complex, the imaginary part of the result is in radians and lies between
609 @math{ 0 \leq \Im \acosh(x) \leq \pi}.
611 @item @emph{Example}:
614 REAL(8), DIMENSION(3) :: x = (/ 1.0, 2.0, 3.0 /)
619 @item @emph{Specific names}:
620 @multitable @columnfractions .20 .20 .20 .25
621 @item Name @tab Argument @tab Return type @tab Standard
622 @item @code{DACOSH(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU extension
625 @item @emph{See also}:
626 Inverse function: @ref{COSH}
632 @section @code{ADJUSTL} --- Left adjust a string
634 @cindex string, adjust left
635 @cindex adjust string
638 @item @emph{Description}:
639 @code{ADJUSTL(STRING)} will left adjust a string by removing leading spaces.
640 Spaces are inserted at the end of the string as needed.
642 @item @emph{Standard}:
649 @code{RESULT = ADJUSTL(STRING)}
651 @item @emph{Arguments}:
652 @multitable @columnfractions .15 .70
653 @item @var{STRING} @tab The type shall be @code{CHARACTER}.
656 @item @emph{Return value}:
657 The return value is of type @code{CHARACTER} and of the same kind as
658 @var{STRING} where leading spaces are removed and the same number of
659 spaces are inserted on the end of @var{STRING}.
661 @item @emph{Example}:
664 character(len=20) :: str = ' gfortran'
667 end program test_adjustl
670 @item @emph{See also}:
671 @ref{ADJUSTR}, @ref{TRIM}
677 @section @code{ADJUSTR} --- Right adjust a string
679 @cindex string, adjust right
680 @cindex adjust string
683 @item @emph{Description}:
684 @code{ADJUSTR(STRING)} will right adjust a string by removing trailing spaces.
685 Spaces are inserted at the start of the string as needed.
687 @item @emph{Standard}:
694 @code{RESULT = ADJUSTR(STRING)}
696 @item @emph{Arguments}:
697 @multitable @columnfractions .15 .70
698 @item @var{STR} @tab The type shall be @code{CHARACTER}.
701 @item @emph{Return value}:
702 The return value is of type @code{CHARACTER} and of the same kind as
703 @var{STRING} where trailing spaces are removed and the same number of
704 spaces are inserted at the start of @var{STRING}.
706 @item @emph{Example}:
709 character(len=20) :: str = 'gfortran'
712 end program test_adjustr
715 @item @emph{See also}:
716 @ref{ADJUSTL}, @ref{TRIM}
722 @section @code{AIMAG} --- Imaginary part of complex number
727 @cindex complex numbers, imaginary part
730 @item @emph{Description}:
731 @code{AIMAG(Z)} yields the imaginary part of complex argument @code{Z}.
732 The @code{IMAG(Z)} and @code{IMAGPART(Z)} intrinsic functions are provided
733 for compatibility with @command{g77}, and their use in new code is
734 strongly discouraged.
736 @item @emph{Standard}:
737 Fortran 77 and later, has overloads that are GNU extensions
743 @code{RESULT = AIMAG(Z)}
745 @item @emph{Arguments}:
746 @multitable @columnfractions .15 .70
747 @item @var{Z} @tab The type of the argument shall be @code{COMPLEX}.
750 @item @emph{Return value}:
751 The return value is of type @code{REAL} with the
752 kind type parameter of the argument.
754 @item @emph{Example}:
759 z4 = cmplx(1.e0_4, 0.e0_4)
760 z8 = cmplx(0.e0_8, 1.e0_8)
761 print *, aimag(z4), dimag(z8)
762 end program test_aimag
765 @item @emph{Specific names}:
766 @multitable @columnfractions .20 .20 .20 .25
767 @item Name @tab Argument @tab Return type @tab Standard
768 @item @code{AIMAG(Z)} @tab @code{COMPLEX Z} @tab @code{REAL} @tab GNU extension
769 @item @code{DIMAG(Z)} @tab @code{COMPLEX(8) Z} @tab @code{REAL(8)} @tab GNU extension
770 @item @code{IMAG(Z)} @tab @code{COMPLEX Z} @tab @code{REAL} @tab GNU extension
771 @item @code{IMAGPART(Z)} @tab @code{COMPLEX Z} @tab @code{REAL} @tab GNU extension
778 @section @code{AINT} --- Truncate to a whole number
782 @cindex rounding, floor
785 @item @emph{Description}:
786 @code{AINT(A [, KIND])} truncates its argument to a whole number.
788 @item @emph{Standard}:
795 @code{RESULT = AINT(A [, KIND])}
797 @item @emph{Arguments}:
798 @multitable @columnfractions .15 .70
799 @item @var{A} @tab The type of the argument shall be @code{REAL}.
800 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
801 expression indicating the kind parameter of the result.
804 @item @emph{Return value}:
805 The return value is of type @code{REAL} with the kind type parameter of the
806 argument if the optional @var{KIND} is absent; otherwise, the kind
807 type parameter will be given by @var{KIND}. If the magnitude of
808 @var{X} is less than one, @code{AINT(X)} returns zero. If the
809 magnitude is equal to or greater than one then it returns the largest
810 whole number that does not exceed its magnitude. The sign is the same
811 as the sign of @var{X}.
813 @item @emph{Example}:
820 print *, aint(x4), dint(x8)
822 end program test_aint
825 @item @emph{Specific names}:
826 @multitable @columnfractions .20 .20 .20 .25
827 @item Name @tab Argument @tab Return type @tab Standard
828 @item @code{AINT(A)} @tab @code{REAL(4) A} @tab @code{REAL(4)} @tab Fortran 77 and later
829 @item @code{DINT(A)} @tab @code{REAL(8) A} @tab @code{REAL(8)} @tab Fortran 77 and later
836 @section @code{ALARM} --- Execute a routine after a given delay
838 @cindex delayed execution
841 @item @emph{Description}:
842 @code{ALARM(SECONDS, HANDLER [, STATUS])} causes external subroutine @var{HANDLER}
843 to be executed after a delay of @var{SECONDS} by using @code{alarm(2)} to
844 set up a signal and @code{signal(2)} to catch it. If @var{STATUS} is
845 supplied, it will be returned with the number of seconds remaining until
846 any previously scheduled alarm was due to be delivered, or zero if there
847 was no previously scheduled alarm.
849 @item @emph{Standard}:
856 @code{CALL ALARM(SECONDS, HANDLER [, STATUS])}
858 @item @emph{Arguments}:
859 @multitable @columnfractions .15 .70
860 @item @var{SECONDS} @tab The type of the argument shall be a scalar
861 @code{INTEGER}. It is @code{INTENT(IN)}.
862 @item @var{HANDLER} @tab Signal handler (@code{INTEGER FUNCTION} or
863 @code{SUBROUTINE}) or dummy/global @code{INTEGER} scalar. The scalar
864 values may be either @code{SIG_IGN=1} to ignore the alarm generated
865 or @code{SIG_DFL=0} to set the default action. It is @code{INTENT(IN)}.
866 @item @var{STATUS} @tab (Optional) @var{STATUS} shall be a scalar
867 variable of the default @code{INTEGER} kind. It is @code{INTENT(OUT)}.
870 @item @emph{Example}:
873 external handler_print
875 call alarm (3, handler_print, i)
878 end program test_alarm
880 This will cause the external routine @var{handler_print} to be called
887 @section @code{ALL} --- All values in @var{MASK} along @var{DIM} are true
889 @cindex array, apply condition
890 @cindex array, condition testing
893 @item @emph{Description}:
894 @code{ALL(MASK [, DIM])} determines if all the values are true in @var{MASK}
895 in the array along dimension @var{DIM}.
897 @item @emph{Standard}:
901 Transformational function
904 @code{RESULT = ALL(MASK [, DIM])}
906 @item @emph{Arguments}:
907 @multitable @columnfractions .15 .70
908 @item @var{MASK} @tab The type of the argument shall be @code{LOGICAL} and
909 it shall not be scalar.
910 @item @var{DIM} @tab (Optional) @var{DIM} shall be a scalar integer
911 with a value that lies between one and the rank of @var{MASK}.
914 @item @emph{Return value}:
915 @code{ALL(MASK)} returns a scalar value of type @code{LOGICAL} where
916 the kind type parameter is the same as the kind type parameter of
917 @var{MASK}. If @var{DIM} is present, then @code{ALL(MASK, DIM)} returns
918 an array with the rank of @var{MASK} minus 1. The shape is determined from
919 the shape of @var{MASK} where the @var{DIM} dimension is elided.
923 @code{ALL(MASK)} is true if all elements of @var{MASK} are true.
924 It also is true if @var{MASK} has zero size; otherwise, it is false.
926 If the rank of @var{MASK} is one, then @code{ALL(MASK,DIM)} is equivalent
927 to @code{ALL(MASK)}. If the rank is greater than one, then @code{ALL(MASK,DIM)}
928 is determined by applying @code{ALL} to the array sections.
931 @item @emph{Example}:
935 l = all((/.true., .true., .true./))
940 integer a(2,3), b(2,3)
944 print *, all(a .eq. b, 1)
945 print *, all(a .eq. b, 2)
946 end subroutine section
954 @section @code{ALLOCATED} --- Status of an allocatable entity
956 @cindex allocation, status
959 @item @emph{Description}:
960 @code{ALLOCATED(ARRAY)} and @code{ALLOCATED(SCALAR)} check the allocation
961 status of @var{ARRAY} and @var{SCALAR}, respectively.
963 @item @emph{Standard}:
964 Fortran 95 and later. Note, the @code{SCALAR=} keyword and allocatable
965 scalar entities are available in Fortran 2003 and later.
971 @code{RESULT = ALLOCATED(ARRAY)} or @code{RESULT = ALLOCATED(SCALAR)}
973 @item @emph{Arguments}:
974 @multitable @columnfractions .15 .70
975 @item @var{ARRAY} @tab The argument shall be an @code{ALLOCATABLE} array.
976 @item @var{SCALAR} @tab The argument shall be an @code{ALLOCATABLE} scalar.
979 @item @emph{Return value}:
980 The return value is a scalar @code{LOGICAL} with the default logical
981 kind type parameter. If the argument is allocated, then the result is
982 @code{.TRUE.}; otherwise, it returns @code{.FALSE.}
984 @item @emph{Example}:
986 program test_allocated
988 real(4), allocatable :: x(:)
989 if (.not. allocated(x)) allocate(x(i))
990 end program test_allocated
997 @section @code{AND} --- Bitwise logical AND
999 @cindex bitwise logical and
1000 @cindex logical and, bitwise
1003 @item @emph{Description}:
1004 Bitwise logical @code{AND}.
1006 This intrinsic routine is provided for backwards compatibility with
1007 GNU Fortran 77. For integer arguments, programmers should consider
1008 the use of the @ref{IAND} intrinsic defined by the Fortran standard.
1010 @item @emph{Standard}:
1016 @item @emph{Syntax}:
1017 @code{RESULT = AND(I, J)}
1019 @item @emph{Arguments}:
1020 @multitable @columnfractions .15 .70
1021 @item @var{I} @tab The type shall be either a scalar @code{INTEGER}
1022 type or a scalar @code{LOGICAL} type.
1023 @item @var{J} @tab The type shall be the same as the type of @var{I}.
1026 @item @emph{Return value}:
1027 The return type is either a scalar @code{INTEGER} or a scalar
1028 @code{LOGICAL}. If the kind type parameters differ, then the
1029 smaller kind type is implicitly converted to larger kind, and the
1030 return has the larger kind.
1032 @item @emph{Example}:
1035 LOGICAL :: T = .TRUE., F = .FALSE.
1037 DATA a / Z'F' /, b / Z'3' /
1039 WRITE (*,*) AND(T, T), AND(T, F), AND(F, T), AND(F, F)
1040 WRITE (*,*) AND(a, b)
1044 @item @emph{See also}:
1045 Fortran 95 elemental function: @ref{IAND}
1051 @section @code{ANINT} --- Nearest whole number
1055 @cindex rounding, ceiling
1058 @item @emph{Description}:
1059 @code{ANINT(A [, KIND])} rounds its argument to the nearest whole number.
1061 @item @emph{Standard}:
1062 Fortran 77 and later
1067 @item @emph{Syntax}:
1068 @code{RESULT = ANINT(A [, KIND])}
1070 @item @emph{Arguments}:
1071 @multitable @columnfractions .15 .70
1072 @item @var{A} @tab The type of the argument shall be @code{REAL}.
1073 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
1074 expression indicating the kind parameter of the result.
1077 @item @emph{Return value}:
1078 The return value is of type real with the kind type parameter of the
1079 argument if the optional @var{KIND} is absent; otherwise, the kind
1080 type parameter will be given by @var{KIND}. If @var{A} is greater than
1081 zero, @code{ANINT(A)} returns @code{AINT(X+0.5)}. If @var{A} is
1082 less than or equal to zero then it returns @code{AINT(X-0.5)}.
1084 @item @emph{Example}:
1091 print *, anint(x4), dnint(x8)
1093 end program test_anint
1096 @item @emph{Specific names}:
1097 @multitable @columnfractions .20 .20 .20 .25
1098 @item Name @tab Argument @tab Return type @tab Standard
1099 @item @code{AINT(A)} @tab @code{REAL(4) A} @tab @code{REAL(4)} @tab Fortran 77 and later
1100 @item @code{DNINT(A)} @tab @code{REAL(8) A} @tab @code{REAL(8)} @tab Fortran 77 and later
1107 @section @code{ANY} --- Any value in @var{MASK} along @var{DIM} is true
1109 @cindex array, apply condition
1110 @cindex array, condition testing
1113 @item @emph{Description}:
1114 @code{ANY(MASK [, DIM])} determines if any of the values in the logical array
1115 @var{MASK} along dimension @var{DIM} are @code{.TRUE.}.
1117 @item @emph{Standard}:
1118 Fortran 95 and later
1121 Transformational function
1123 @item @emph{Syntax}:
1124 @code{RESULT = ANY(MASK [, DIM])}
1126 @item @emph{Arguments}:
1127 @multitable @columnfractions .15 .70
1128 @item @var{MASK} @tab The type of the argument shall be @code{LOGICAL} and
1129 it shall not be scalar.
1130 @item @var{DIM} @tab (Optional) @var{DIM} shall be a scalar integer
1131 with a value that lies between one and the rank of @var{MASK}.
1134 @item @emph{Return value}:
1135 @code{ANY(MASK)} returns a scalar value of type @code{LOGICAL} where
1136 the kind type parameter is the same as the kind type parameter of
1137 @var{MASK}. If @var{DIM} is present, then @code{ANY(MASK, DIM)} returns
1138 an array with the rank of @var{MASK} minus 1. The shape is determined from
1139 the shape of @var{MASK} where the @var{DIM} dimension is elided.
1143 @code{ANY(MASK)} is true if any element of @var{MASK} is true;
1144 otherwise, it is false. It also is false if @var{MASK} has zero size.
1146 If the rank of @var{MASK} is one, then @code{ANY(MASK,DIM)} is equivalent
1147 to @code{ANY(MASK)}. If the rank is greater than one, then @code{ANY(MASK,DIM)}
1148 is determined by applying @code{ANY} to the array sections.
1151 @item @emph{Example}:
1155 l = any((/.true., .true., .true./))
1160 integer a(2,3), b(2,3)
1164 print *, any(a .eq. b, 1)
1165 print *, any(a .eq. b, 2)
1166 end subroutine section
1167 end program test_any
1174 @section @code{ASIN} --- Arcsine function
1177 @cindex trigonometric function, sine, inverse
1178 @cindex sine, inverse
1181 @item @emph{Description}:
1182 @code{ASIN(X)} computes the arcsine of its @var{X} (inverse of @code{SIN(X)}).
1184 @item @emph{Standard}:
1185 Fortran 77 and later, for a complex argument Fortran 2008 or later
1190 @item @emph{Syntax}:
1191 @code{RESULT = ASIN(X)}
1193 @item @emph{Arguments}:
1194 @multitable @columnfractions .15 .70
1195 @item @var{X} @tab The type shall be either @code{REAL} and a magnitude that is
1196 less than or equal to one - or be @code{COMPLEX}.
1199 @item @emph{Return value}:
1200 The return value is of the same type and kind as @var{X}.
1201 The real part of the result is in radians and lies in the range
1202 @math{-\pi/2 \leq \Re \asin(x) \leq \pi/2}.
1204 @item @emph{Example}:
1207 real(8) :: x = 0.866_8
1209 end program test_asin
1212 @item @emph{Specific names}:
1213 @multitable @columnfractions .20 .20 .20 .25
1214 @item Name @tab Argument @tab Return type @tab Standard
1215 @item @code{ASIN(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab Fortran 77 and later
1216 @item @code{DASIN(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab Fortran 77 and later
1219 @item @emph{See also}:
1220 Inverse function: @ref{SIN}
1227 @section @code{ASINH} --- Hyperbolic arcsine function
1230 @cindex area hyperbolic sine
1231 @cindex hyperbolic arcsine
1232 @cindex hyperbolic function, sine, inverse
1233 @cindex sine, hyperbolic, inverse
1236 @item @emph{Description}:
1237 @code{ASINH(X)} computes the hyperbolic arcsine of @var{X} (inverse of @code{SINH(X)}).
1239 @item @emph{Standard}:
1240 Fortran 2008 and later
1245 @item @emph{Syntax}:
1246 @code{RESULT = ASINH(X)}
1248 @item @emph{Arguments}:
1249 @multitable @columnfractions .15 .70
1250 @item @var{X} @tab The type shall be @code{REAL} or @code{COMPLEX}.
1253 @item @emph{Return value}:
1254 The return value is of the same type and kind as @var{X}. If @var{X} is
1255 complex, the imaginary part of the result is in radians and lies between
1256 @math{-\pi/2 \leq \Im \asinh(x) \leq \pi/2}.
1258 @item @emph{Example}:
1261 REAL(8), DIMENSION(3) :: x = (/ -1.0, 0.0, 1.0 /)
1262 WRITE (*,*) ASINH(x)
1266 @item @emph{Specific names}:
1267 @multitable @columnfractions .20 .20 .20 .25
1268 @item Name @tab Argument @tab Return type @tab Standard
1269 @item @code{DASINH(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU extension.
1272 @item @emph{See also}:
1273 Inverse function: @ref{SINH}
1279 @section @code{ASSOCIATED} --- Status of a pointer or pointer/target pair
1281 @cindex pointer, status
1282 @cindex association status
1285 @item @emph{Description}:
1286 @code{ASSOCIATED(POINTER [, TARGET])} determines the status of the pointer
1287 @var{POINTER} or if @var{POINTER} is associated with the target @var{TARGET}.
1289 @item @emph{Standard}:
1290 Fortran 95 and later
1295 @item @emph{Syntax}:
1296 @code{RESULT = ASSOCIATED(POINTER [, TARGET])}
1298 @item @emph{Arguments}:
1299 @multitable @columnfractions .15 .70
1300 @item @var{POINTER} @tab @var{POINTER} shall have the @code{POINTER} attribute
1301 and it can be of any type.
1302 @item @var{TARGET} @tab (Optional) @var{TARGET} shall be a pointer or
1303 a target. It must have the same type, kind type parameter, and
1304 array rank as @var{POINTER}.
1306 The association status of neither @var{POINTER} nor @var{TARGET} shall be
1309 @item @emph{Return value}:
1310 @code{ASSOCIATED(POINTER)} returns a scalar value of type @code{LOGICAL(4)}.
1311 There are several cases:
1313 @item (A) When the optional @var{TARGET} is not present then
1314 @code{ASSOCIATED(POINTER)} is true if @var{POINTER} is associated with a target; otherwise, it returns false.
1315 @item (B) If @var{TARGET} is present and a scalar target, the result is true if
1316 @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
1317 disassociated, the result is false.
1318 @item (C) If @var{TARGET} is present and an array target, the result is true if
1319 @var{TARGET} and @var{POINTER} have the same shape, are not zero-sized arrays,
1320 are arrays whose elements are not zero-sized storage sequences, and
1321 @var{TARGET} and @var{POINTER} occupy the same storage units in array element
1323 As in case(B), the result is false, if @var{POINTER} is disassociated.
1324 @item (D) If @var{TARGET} is present and an scalar pointer, the result is true
1325 if @var{TARGET} is associated with @var{POINTER}, the target associated with
1326 @var{TARGET} are not zero-sized storage sequences and occupy the same storage
1328 The result is false, if either @var{TARGET} or @var{POINTER} is disassociated.
1329 @item (E) If @var{TARGET} is present and an array pointer, the result is true if
1330 target associated with @var{POINTER} and the target associated with @var{TARGET}
1331 have the same shape, are not zero-sized arrays, are arrays whose elements are
1332 not zero-sized storage sequences, and @var{TARGET} and @var{POINTER} occupy
1333 the same storage units in array element order.
1334 The result is false, if either @var{TARGET} or @var{POINTER} is disassociated.
1337 @item @emph{Example}:
1339 program test_associated
1341 real, target :: tgt(2) = (/1., 2./)
1342 real, pointer :: ptr(:)
1344 if (associated(ptr) .eqv. .false.) call abort
1345 if (associated(ptr,tgt) .eqv. .false.) call abort
1346 end program test_associated
1349 @item @emph{See also}:
1356 @section @code{ATAN} --- Arctangent function
1359 @cindex trigonometric function, tangent, inverse
1360 @cindex tangent, inverse
1363 @item @emph{Description}:
1364 @code{ATAN(X)} computes the arctangent of @var{X}.
1366 @item @emph{Standard}:
1367 Fortran 77 and later, for a complex argument and for two arguments
1368 Fortran 2008 or later
1373 @item @emph{Syntax}:
1374 @code{RESULT = ATAN(X)}
1375 @code{RESULT = ATAN(Y, X)}
1377 @item @emph{Arguments}:
1378 @multitable @columnfractions .15 .70
1379 @item @var{X} @tab The type shall be @code{REAL} or @code{COMPLEX};
1380 if @var{Y} is present, @var{X} shall be REAL.
1381 @item @var{Y} shall be of the same type and kind as @var{X}.
1384 @item @emph{Return value}:
1385 The return value is of the same type and kind as @var{X}.
1386 If @var{Y} is present, the result is identical to @code{ATAN2(Y,X)}.
1387 Otherwise, it the arcus tangent of @var{X}, where the real part of
1388 the result is in radians and lies in the range
1389 @math{-\pi/2 \leq \Re \atan(x) \leq \pi/2}.
1391 @item @emph{Example}:
1394 real(8) :: x = 2.866_8
1396 end program test_atan
1399 @item @emph{Specific names}:
1400 @multitable @columnfractions .20 .20 .20 .25
1401 @item Name @tab Argument @tab Return type @tab Standard
1402 @item @code{ATAN(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab Fortran 77 and later
1403 @item @code{DATAN(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab Fortran 77 and later
1406 @item @emph{See also}:
1407 Inverse function: @ref{TAN}
1414 @section @code{ATAN2} --- Arctangent function
1417 @cindex trigonometric function, tangent, inverse
1418 @cindex tangent, inverse
1421 @item @emph{Description}:
1422 @code{ATAN2(Y, X)} computes the principal value of the argument
1423 function of the complex number @math{X + i Y}. This function can
1424 be used to transform from carthesian into polar coordinates and
1425 allows to determine the angle in the correct quadrant.
1427 @item @emph{Standard}:
1428 Fortran 77 and later
1433 @item @emph{Syntax}:
1434 @code{RESULT = ATAN2(Y, X)}
1436 @item @emph{Arguments}:
1437 @multitable @columnfractions .15 .70
1438 @item @var{Y} @tab The type shall be @code{REAL}.
1439 @item @var{X} @tab The type and kind type parameter shall be the same as @var{Y}.
1440 If @var{Y} is zero, then @var{X} must be nonzero.
1443 @item @emph{Return value}:
1444 The return value has the same type and kind type parameter as @var{Y}.
1445 It is the principal value of the complex number @math{X + i Y}. If
1446 @var{X} is nonzero, then it lies in the range @math{-\pi \le \atan (x) \leq \pi}.
1447 The sign is positive if @var{Y} is positive. If @var{Y} is zero, then
1448 the return value is zero if @var{X} is positive and @math{\pi} if @var{X}
1449 is negative. Finally, if @var{X} is zero, then the magnitude of the result
1452 @item @emph{Example}:
1455 real(4) :: x = 1.e0_4, y = 0.5e0_4
1457 end program test_atan2
1460 @item @emph{Specific names}:
1461 @multitable @columnfractions .20 .20 .20 .25
1462 @item Name @tab Argument @tab Return type @tab Standard
1463 @item @code{ATAN2(X, Y)} @tab @code{REAL(4) X, Y} @tab @code{REAL(4)} @tab Fortran 77 and later
1464 @item @code{DATAN2(X, Y)} @tab @code{REAL(8) X, Y} @tab @code{REAL(8)} @tab Fortran 77 and later
1471 @section @code{ATANH} --- Hyperbolic arctangent function
1474 @cindex area hyperbolic tangent
1475 @cindex hyperbolic arctangent
1476 @cindex hyperbolic function, tangent, inverse
1477 @cindex tangent, hyperbolic, inverse
1480 @item @emph{Description}:
1481 @code{ATANH(X)} computes the hyperbolic arctangent of @var{X} (inverse
1484 @item @emph{Standard}:
1485 Fortran 2008 and later
1490 @item @emph{Syntax}:
1491 @code{RESULT = ATANH(X)}
1493 @item @emph{Arguments}:
1494 @multitable @columnfractions .15 .70
1495 @item @var{X} @tab The type shall be @code{REAL} or @code{COMPLEX}.
1498 @item @emph{Return value}:
1499 The return value has same type and kind as @var{X}. If @var{X} is
1500 complex, the imaginary part of the result is in radians and lies between
1501 @math{-\pi/2 \leq \Im \atanh(x) \leq \pi/2}.
1503 @item @emph{Example}:
1506 REAL, DIMENSION(3) :: x = (/ -1.0, 0.0, 1.0 /)
1507 WRITE (*,*) ATANH(x)
1511 @item @emph{Specific names}:
1512 @multitable @columnfractions .20 .20 .20 .25
1513 @item Name @tab Argument @tab Return type @tab Standard
1514 @item @code{DATANH(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU extension
1517 @item @emph{See also}:
1518 Inverse function: @ref{TANH}
1524 @section @code{BESSEL_J0} --- Bessel function of the first kind of order 0
1528 @cindex Bessel function, first kind
1531 @item @emph{Description}:
1532 @code{BESSEL_J0(X)} computes the Bessel function of the first kind of
1533 order 0 of @var{X}. This function is available under the name
1534 @code{BESJ0} as a GNU extension.
1536 @item @emph{Standard}:
1537 Fortran 2008 and later
1542 @item @emph{Syntax}:
1543 @code{RESULT = BESSEL_J0(X)}
1545 @item @emph{Arguments}:
1546 @multitable @columnfractions .15 .70
1547 @item @var{X} @tab The type shall be @code{REAL}, and it shall be scalar.
1550 @item @emph{Return value}:
1551 The return value is of type @code{REAL} and lies in the
1552 range @math{ - 0.4027... \leq Bessel (0,x) \leq 1}. It has the same
1555 @item @emph{Example}:
1558 real(8) :: x = 0.0_8
1560 end program test_besj0
1563 @item @emph{Specific names}:
1564 @multitable @columnfractions .20 .20 .20 .25
1565 @item Name @tab Argument @tab Return type @tab Standard
1566 @item @code{DBESJ0(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU extension
1573 @section @code{BESSEL_J1} --- Bessel function of the first kind of order 1
1577 @cindex Bessel function, first kind
1580 @item @emph{Description}:
1581 @code{BESSEL_J1(X)} computes the Bessel function of the first kind of
1582 order 1 of @var{X}. This function is available under the name
1583 @code{BESJ1} as a GNU extension.
1585 @item @emph{Standard}:
1591 @item @emph{Syntax}:
1592 @code{RESULT = BESSEL_J1(X)}
1594 @item @emph{Arguments}:
1595 @multitable @columnfractions .15 .70
1596 @item @var{X} @tab The type shall be @code{REAL}, and it shall be scalar.
1599 @item @emph{Return value}:
1600 The return value is of type @code{REAL} and it lies in the
1601 range @math{ - 0.5818... \leq Bessel (0,x) \leq 0.5818 }. It has the same
1604 @item @emph{Example}:
1607 real(8) :: x = 1.0_8
1609 end program test_besj1
1612 @item @emph{Specific names}:
1613 @multitable @columnfractions .20 .20 .20 .25
1614 @item Name @tab Argument @tab Return type @tab Standard
1615 @item @code{DBESJ1(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU extension
1622 @section @code{BESSEL_JN} --- Bessel function of the first kind
1626 @cindex Bessel function, first kind
1629 @item @emph{Description}:
1630 @code{BESSEL_JN(N, X)} computes the Bessel function of the first kind of
1631 order @var{N} of @var{X}. This function is available under the name
1632 @code{BESJN} as a GNU extension.
1634 If both arguments are arrays, their ranks and shapes shall conform.
1636 @item @emph{Standard}:
1637 Fortran 2008 and later
1642 @item @emph{Syntax}:
1643 @code{RESULT = BESSEL_JN(N, X)}
1645 @item @emph{Arguments}:
1646 @multitable @columnfractions .15 .70
1647 @item @var{N} @tab Shall be a scalar or an array of type @code{INTEGER}.
1648 @item @var{X} @tab Shall be a scalar or an array of type @code{REAL}.
1651 @item @emph{Return value}:
1652 The return value is a scalar of type @code{REAL}. It has the same
1655 @item @emph{Example}:
1658 real(8) :: x = 1.0_8
1660 end program test_besjn
1663 @item @emph{Specific names}:
1664 @multitable @columnfractions .20 .20 .20 .25
1665 @item Name @tab Argument @tab Return type @tab Standard
1666 @item @code{DBESJN(N, X)} @tab @code{INTEGER N} @tab @code{REAL(8)} @tab GNU extension
1667 @item @tab @code{REAL(8) X} @tab @tab
1674 @section @code{BESSEL_Y0} --- Bessel function of the second kind of order 0
1678 @cindex Bessel function, second kind
1681 @item @emph{Description}:
1682 @code{BESSEL_Y0(X)} computes the Bessel function of the second kind of
1683 order 0 of @var{X}. This function is available under the name
1684 @code{BESY0} as a GNU extension.
1686 @item @emph{Standard}:
1687 Fortran 2008 and later
1692 @item @emph{Syntax}:
1693 @code{RESULT = BESSEL_Y0(X)}
1695 @item @emph{Arguments}:
1696 @multitable @columnfractions .15 .70
1697 @item @var{X} @tab The type shall be @code{REAL}, and it shall be scalar.
1700 @item @emph{Return value}:
1701 The return value is a scalar of type @code{REAL}. It has the same
1704 @item @emph{Example}:
1707 real(8) :: x = 0.0_8
1709 end program test_besy0
1712 @item @emph{Specific names}:
1713 @multitable @columnfractions .20 .20 .20 .25
1714 @item Name @tab Argument @tab Return type @tab Standard
1715 @item @code{DBESY0(X)}@tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU extension
1722 @section @code{BESSEL_Y1} --- Bessel function of the second kind of order 1
1726 @cindex Bessel function, second kind
1729 @item @emph{Description}:
1730 @code{BESSEL_Y1(X)} computes the Bessel function of the second kind of
1731 order 1 of @var{X}. This function is available under the name
1732 @code{BESY1} as a GNU extension.
1734 @item @emph{Standard}:
1735 Fortran 2008 and later
1740 @item @emph{Syntax}:
1741 @code{RESULT = BESSEL_Y1(X)}
1743 @item @emph{Arguments}:
1744 @multitable @columnfractions .15 .70
1745 @item @var{X} @tab The type shall be @code{REAL}, and it shall be scalar.
1748 @item @emph{Return value}:
1749 The return value is a scalar of type @code{REAL}. It has the same
1752 @item @emph{Example}:
1755 real(8) :: x = 1.0_8
1757 end program test_besy1
1760 @item @emph{Specific names}:
1761 @multitable @columnfractions .20 .20 .20 .25
1762 @item Name @tab Argument @tab Return type @tab Standard
1763 @item @code{DBESY1(X)}@tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU extension
1770 @section @code{BESSEL_YN} --- Bessel function of the second kind
1774 @cindex Bessel function, second kind
1777 @item @emph{Description}:
1778 @code{BESSEL_YN(N, X)} computes the Bessel function of the second kind of
1779 order @var{N} of @var{X}. This function is available under the name
1780 @code{BESYN} as a GNU extension.
1782 If both arguments are arrays, their ranks and shapes shall conform.
1784 @item @emph{Standard}:
1785 Fortran 2008 and later
1790 @item @emph{Syntax}:
1791 @code{RESULT = BESSEL_YN(N, X)}
1793 @item @emph{Arguments}:
1794 @multitable @columnfractions .15 .70
1795 @item @var{N} @tab Shall be a scalar or an array of type @code{INTEGER}.
1796 @item @var{X} @tab Shall be a scalar or an array of type @code{REAL}.
1799 @item @emph{Return value}:
1800 The return value is a scalar of type @code{REAL}. It has the same
1803 @item @emph{Example}:
1806 real(8) :: x = 1.0_8
1808 end program test_besyn
1811 @item @emph{Specific names}:
1812 @multitable @columnfractions .20 .20 .20 .25
1813 @item Name @tab Argument @tab Return type @tab Standard
1814 @item @code{DBESYN(N,X)} @tab @code{INTEGER N} @tab @code{REAL(8)} @tab GNU extension
1815 @item @tab @code{REAL(8) X} @tab @tab
1822 @section @code{BIT_SIZE} --- Bit size inquiry function
1824 @cindex bits, number of
1825 @cindex size of a variable, in bits
1828 @item @emph{Description}:
1829 @code{BIT_SIZE(I)} returns the number of bits (integer precision plus sign bit)
1830 represented by the type of @var{I}. The result of @code{BIT_SIZE(I)} is
1831 independent of the actual value of @var{I}.
1833 @item @emph{Standard}:
1834 Fortran 95 and later
1839 @item @emph{Syntax}:
1840 @code{RESULT = BIT_SIZE(I)}
1842 @item @emph{Arguments}:
1843 @multitable @columnfractions .15 .70
1844 @item @var{I} @tab The type shall be @code{INTEGER}.
1847 @item @emph{Return value}:
1848 The return value is of type @code{INTEGER}
1850 @item @emph{Example}:
1852 program test_bit_size
1857 end program test_bit_size
1864 @section @code{BTEST} --- Bit test function
1866 @cindex bits, testing
1869 @item @emph{Description}:
1870 @code{BTEST(I,POS)} returns logical @code{.TRUE.} if the bit at @var{POS}
1871 in @var{I} is set. The counting of the bits starts at 0.
1873 @item @emph{Standard}:
1874 Fortran 95 and later
1879 @item @emph{Syntax}:
1880 @code{RESULT = BTEST(I, POS)}
1882 @item @emph{Arguments}:
1883 @multitable @columnfractions .15 .70
1884 @item @var{I} @tab The type shall be @code{INTEGER}.
1885 @item @var{POS} @tab The type shall be @code{INTEGER}.
1888 @item @emph{Return value}:
1889 The return value is of type @code{LOGICAL}
1891 @item @emph{Example}:
1894 integer :: i = 32768 + 1024 + 64
1898 bool = btest(i, pos)
1901 end program test_btest
1907 @section @code{C_ASSOCIATED} --- Status of a C pointer
1908 @fnindex C_ASSOCIATED
1909 @cindex association status, C pointer
1910 @cindex pointer, C association status
1913 @item @emph{Description}:
1914 @code{C_ASSOCIATED(c_prt_1[, c_ptr_2])} determines the status of the C pointer
1915 @var{c_ptr_1} or if @var{c_ptr_1} is associated with the target @var{c_ptr_2}.
1917 @item @emph{Standard}:
1918 Fortran 2003 and later
1923 @item @emph{Syntax}:
1924 @code{RESULT = C_ASSOCIATED(c_prt_1[, c_ptr_2])}
1926 @item @emph{Arguments}:
1927 @multitable @columnfractions .15 .70
1928 @item @var{c_ptr_1} @tab Scalar of the type @code{C_PTR} or @code{C_FUNPTR}.
1929 @item @var{c_ptr_2} @tab (Optional) Scalar of the same type as @var{c_ptr_1}.
1932 @item @emph{Return value}:
1933 The return value is of type @code{LOGICAL}; it is @code{.false.} if either
1934 @var{c_ptr_1} is a C NULL pointer or if @var{c_ptr1} and @var{c_ptr_2}
1935 point to different addresses.
1937 @item @emph{Example}:
1939 subroutine association_test(a,b)
1940 use iso_c_binding, only: c_associated, c_loc, c_ptr
1944 if(c_associated(b, c_loc(a))) &
1945 stop 'b and a do not point to same target'
1946 end subroutine association_test
1949 @item @emph{See also}:
1950 @ref{C_LOC}, @ref{C_FUNLOC}
1955 @section @code{C_FUNLOC} --- Obtain the C address of a procedure
1957 @cindex pointer, C address of procedures
1960 @item @emph{Description}:
1961 @code{C_FUNLOC(x)} determines the C address of the argument.
1963 @item @emph{Standard}:
1964 Fortran 2003 and later
1969 @item @emph{Syntax}:
1970 @code{RESULT = C_FUNLOC(x)}
1972 @item @emph{Arguments}:
1973 @multitable @columnfractions .15 .70
1974 @item @var{x} @tab Interoperable function or pointer to such function.
1977 @item @emph{Return value}:
1978 The return value is of type @code{C_FUNPTR} and contains the C address
1981 @item @emph{Example}:
1987 subroutine sub(a) bind(c)
1997 subroutine my_routine(p) bind(c,name='myC_func')
1999 type(c_funptr), intent(in) :: p
2002 call my_routine(c_funloc(sub))
2006 @item @emph{See also}:
2007 @ref{C_ASSOCIATED}, @ref{C_LOC}, @ref{C_F_POINTER}, @ref{C_F_PROCPOINTER}
2011 @node C_F_PROCPOINTER
2012 @section @code{C_F_PROCPOINTER} --- Convert C into Fortran procedure pointer
2013 @fnindex C_F_PROCPOINTER
2014 @cindex pointer, C address of pointers
2017 @item @emph{Description}:
2018 @code{C_F_PROCPOINTER(CPTR, FPTR)} Assign the target of the C function pointer
2019 @var{CPTR} to the Fortran procedure pointer @var{FPTR}.
2021 @item @emph{Standard}:
2022 Fortran 2003 and later
2027 @item @emph{Syntax}:
2028 @code{CALL C_F_PROCPOINTER(cptr, fptr)}
2030 @item @emph{Arguments}:
2031 @multitable @columnfractions .15 .70
2032 @item @var{CPTR} @tab scalar of the type @code{C_FUNPTR}. It is
2034 @item @var{FPTR} @tab procedure pointer interoperable with @var{cptr}. It is
2038 @item @emph{Example}:
2046 real(c_float), intent(in) :: a
2047 real(c_float) :: func
2051 function getIterFunc() bind(c,name="getIterFunc")
2053 type(c_funptr) :: getIterFunc
2056 type(c_funptr) :: cfunptr
2057 procedure(func), pointer :: myFunc
2058 cfunptr = getIterFunc()
2059 call c_f_procpointer(cfunptr, myFunc)
2063 @item @emph{See also}:
2064 @ref{C_LOC}, @ref{C_F_POINTER}
2069 @section @code{C_F_POINTER} --- Convert C into Fortran pointer
2070 @fnindex C_F_POINTER
2071 @cindex pointer, convert C to Fortran
2074 @item @emph{Description}:
2075 @code{C_F_POINTER(CPTR, FPTR[, SHAPE])} Assign the target the C pointer
2076 @var{CPTR} to the Fortran pointer @var{FPTR} and specify its
2079 @item @emph{Standard}:
2080 Fortran 2003 and later
2085 @item @emph{Syntax}:
2086 @code{CALL C_F_POINTER(CPTR, FPTR[, SHAPE])}
2088 @item @emph{Arguments}:
2089 @multitable @columnfractions .15 .70
2090 @item @var{CPTR} @tab scalar of the type @code{C_PTR}. It is
2092 @item @var{FPTR} @tab pointer interoperable with @var{cptr}. It is
2094 @item @var{SHAPE} @tab (Optional) Rank-one array of type @code{INTEGER}
2095 with @code{INTENT(IN)}. It shall be present
2096 if and only if @var{fptr} is an array. The size
2097 must be equal to the rank of @var{fptr}.
2100 @item @emph{Example}:
2106 subroutine my_routine(p) bind(c,name='myC_func')
2108 type(c_ptr), intent(out) :: p
2112 real,pointer :: a(:)
2113 call my_routine(cptr)
2114 call c_f_pointer(cptr, a, [12])
2118 @item @emph{See also}:
2119 @ref{C_LOC}, @ref{C_F_PROCPOINTER}
2124 @section @code{C_LOC} --- Obtain the C address of an object
2126 @cindex procedure pointer, convert C to Fortran
2129 @item @emph{Description}:
2130 @code{C_LOC(X)} determines the C address of the argument.
2132 @item @emph{Standard}:
2133 Fortran 2003 and later
2138 @item @emph{Syntax}:
2139 @code{RESULT = C_LOC(X)}
2141 @item @emph{Arguments}:
2142 @multitable @columnfractions .15 .70
2143 @item @var{X} @tab Associated scalar pointer or interoperable scalar
2144 or allocated allocatable variable with @code{TARGET} attribute.
2147 @item @emph{Return value}:
2148 The return value is of type @code{C_PTR} and contains the C address
2151 @item @emph{Example}:
2153 subroutine association_test(a,b)
2154 use iso_c_binding, only: c_associated, c_loc, c_ptr
2158 if(c_associated(b, c_loc(a))) &
2159 stop 'b and a do not point to same target'
2160 end subroutine association_test
2163 @item @emph{See also}:
2164 @ref{C_ASSOCIATED}, @ref{C_FUNLOC}, @ref{C_F_POINTER}, @ref{C_F_PROCPOINTER}
2169 @section @code{C_SIZEOF} --- Size in bytes of an expression
2171 @cindex expression size
2172 @cindex size of an expression
2175 @item @emph{Description}:
2176 @code{C_SIZEOF(X)} calculates the number of bytes of storage the
2177 expression @code{X} occupies.
2179 @item @emph{Standard}:
2185 @item @emph{Syntax}:
2186 @code{N = C_SIZEOF(X)}
2188 @item @emph{Arguments}:
2189 @multitable @columnfractions .15 .70
2190 @item @var{X} @tab The argument shall be of any type, rank or shape.
2193 @item @emph{Return value}:
2194 The return value is of type integer and of the system-dependent kind
2195 @var{C_SIZE_T} (from the @var{ISO_C_BINDING} module). Its value is the
2196 number of bytes occupied by the argument. If the argument has the
2197 @code{POINTER} attribute, the number of bytes of the storage area pointed
2198 to is returned. If the argument is of a derived type with @code{POINTER}
2199 or @code{ALLOCATABLE} components, the return value doesn't account for
2200 the sizes of the data pointed to by these components.
2202 @item @emph{Example}:
2206 real(c_float) :: r, s(5)
2207 print *, (c_sizeof(s)/c_sizeof(r) == 5)
2210 The example will print @code{.TRUE.} unless you are using a platform
2211 where default @code{REAL} variables are unusually padded.
2213 @item @emph{See also}:
2219 @section @code{CEILING} --- Integer ceiling function
2222 @cindex rounding, ceiling
2225 @item @emph{Description}:
2226 @code{CEILING(A)} returns the least integer greater than or equal to @var{A}.
2228 @item @emph{Standard}:
2229 Fortran 95 and later
2234 @item @emph{Syntax}:
2235 @code{RESULT = CEILING(A [, KIND])}
2237 @item @emph{Arguments}:
2238 @multitable @columnfractions .15 .70
2239 @item @var{A} @tab The type shall be @code{REAL}.
2240 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
2241 expression indicating the kind parameter of the result.
2244 @item @emph{Return value}:
2245 The return value is of type @code{INTEGER(KIND)} if @var{KIND} is present
2246 and a default-kind @code{INTEGER} otherwise.
2248 @item @emph{Example}:
2250 program test_ceiling
2253 print *, ceiling(x) ! returns 64
2254 print *, ceiling(y) ! returns -63
2255 end program test_ceiling
2258 @item @emph{See also}:
2259 @ref{FLOOR}, @ref{NINT}
2266 @section @code{CHAR} --- Character conversion function
2268 @cindex conversion, to character
2271 @item @emph{Description}:
2272 @code{CHAR(I [, KIND])} returns the character represented by the integer @var{I}.
2274 @item @emph{Standard}:
2275 Fortran 77 and later
2280 @item @emph{Syntax}:
2281 @code{RESULT = CHAR(I [, KIND])}
2283 @item @emph{Arguments}:
2284 @multitable @columnfractions .15 .70
2285 @item @var{I} @tab The type shall be @code{INTEGER}.
2286 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
2287 expression indicating the kind parameter of the result.
2290 @item @emph{Return value}:
2291 The return value is of type @code{CHARACTER(1)}
2293 @item @emph{Example}:
2299 print *, i, c ! returns 'J'
2300 end program test_char
2303 @item @emph{Specific names}:
2304 @multitable @columnfractions .20 .20 .20 .25
2305 @item Name @tab Argument @tab Return type @tab Standard
2306 @item @code{CHAR(I)} @tab @code{INTEGER I} @tab @code{CHARACTER(LEN=1)} @tab F77 and later
2310 See @ref{ICHAR} for a discussion of converting between numerical values
2311 and formatted string representations.
2313 @item @emph{See also}:
2314 @ref{ACHAR}, @ref{IACHAR}, @ref{ICHAR}
2321 @section @code{CHDIR} --- Change working directory
2323 @cindex system, working directory
2326 @item @emph{Description}:
2327 Change current working directory to a specified path.
2329 This intrinsic is provided in both subroutine and function forms; however,
2330 only one form can be used in any given program unit.
2332 @item @emph{Standard}:
2336 Subroutine, function
2338 @item @emph{Syntax}:
2339 @multitable @columnfractions .80
2340 @item @code{CALL CHDIR(NAME [, STATUS])}
2341 @item @code{STATUS = CHDIR(NAME)}
2344 @item @emph{Arguments}:
2345 @multitable @columnfractions .15 .70
2346 @item @var{NAME} @tab The type shall be @code{CHARACTER} of default
2347 kind and shall specify a valid path within the file system.
2348 @item @var{STATUS} @tab (Optional) @code{INTEGER} status flag of the default
2349 kind. Returns 0 on success, and a system specific and nonzero error code
2353 @item @emph{Example}:
2356 CHARACTER(len=255) :: path
2358 WRITE(*,*) TRIM(path)
2361 WRITE(*,*) TRIM(path)
2365 @item @emph{See also}:
2372 @section @code{CHMOD} --- Change access permissions of files
2374 @cindex file system, change access mode
2377 @item @emph{Description}:
2378 @code{CHMOD} changes the permissions of a file. This function invokes
2379 @code{/bin/chmod} and might therefore not work on all platforms.
2381 This intrinsic is provided in both subroutine and function forms; however,
2382 only one form can be used in any given program unit.
2384 @item @emph{Standard}:
2388 Subroutine, function
2390 @item @emph{Syntax}:
2391 @multitable @columnfractions .80
2392 @item @code{CALL CHMOD(NAME, MODE[, STATUS])}
2393 @item @code{STATUS = CHMOD(NAME, MODE)}
2396 @item @emph{Arguments}:
2397 @multitable @columnfractions .15 .70
2399 @item @var{NAME} @tab Scalar @code{CHARACTER} of default kind with the
2400 file name. Trailing blanks are ignored unless the character
2401 @code{achar(0)} is present, then all characters up to and excluding
2402 @code{achar(0)} are used as the file name.
2404 @item @var{MODE} @tab Scalar @code{CHARACTER} of default kind giving the
2405 file permission. @var{MODE} uses the same syntax as the @var{MODE}
2406 argument of @code{/bin/chmod}.
2408 @item @var{STATUS} @tab (optional) scalar @code{INTEGER}, which is
2409 @code{0} on success and nonzero otherwise.
2412 @item @emph{Return value}:
2413 In either syntax, @var{STATUS} is set to @code{0} on success and nonzero
2416 @item @emph{Example}:
2417 @code{CHMOD} as subroutine
2422 call chmod('test.dat','u+x',status)
2423 print *, 'Status: ', status
2424 end program chmod_test
2426 @code{CHMOD} as function:
2431 status = chmod('test.dat','u+x')
2432 print *, 'Status: ', status
2433 end program chmod_test
2441 @section @code{CMPLX} --- Complex conversion function
2443 @cindex complex numbers, conversion to
2444 @cindex conversion, to complex
2447 @item @emph{Description}:
2448 @code{CMPLX(X [, Y [, KIND]])} returns a complex number where @var{X} is converted to
2449 the real component. If @var{Y} is present it is converted to the imaginary
2450 component. If @var{Y} is not present then the imaginary component is set to
2451 0.0. If @var{X} is complex then @var{Y} must not be present.
2453 @item @emph{Standard}:
2454 Fortran 77 and later
2459 @item @emph{Syntax}:
2460 @code{RESULT = CMPLX(X [, Y [, KIND]])}
2462 @item @emph{Arguments}:
2463 @multitable @columnfractions .15 .70
2464 @item @var{X} @tab The type may be @code{INTEGER}, @code{REAL},
2466 @item @var{Y} @tab (Optional; only allowed if @var{X} is not
2467 @code{COMPLEX}.) May be @code{INTEGER} or @code{REAL}.
2468 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
2469 expression indicating the kind parameter of the result.
2472 @item @emph{Return value}:
2473 The return value is of @code{COMPLEX} type, with a kind equal to
2474 @var{KIND} if it is specified. If @var{KIND} is not specified, the
2475 result is of the default @code{COMPLEX} kind, regardless of the kinds of
2476 @var{X} and @var{Y}.
2478 @item @emph{Example}:
2485 print *, z, cmplx(x)
2486 end program test_cmplx
2489 @item @emph{See also}:
2495 @node COMMAND_ARGUMENT_COUNT
2496 @section @code{COMMAND_ARGUMENT_COUNT} --- Get number of command line arguments
2497 @fnindex COMMAND_ARGUMENT_COUNT
2498 @cindex command-line arguments
2499 @cindex command-line arguments, number of
2500 @cindex arguments, to program
2503 @item @emph{Description}:
2504 @code{COMMAND_ARGUMENT_COUNT()} returns the number of arguments passed on the
2505 command line when the containing program was invoked.
2507 @item @emph{Standard}:
2508 Fortran 2003 and later
2513 @item @emph{Syntax}:
2514 @code{RESULT = COMMAND_ARGUMENT_COUNT()}
2516 @item @emph{Arguments}:
2517 @multitable @columnfractions .15 .70
2521 @item @emph{Return value}:
2522 The return value is an @code{INTEGER} of default kind.
2524 @item @emph{Example}:
2526 program test_command_argument_count
2528 count = command_argument_count()
2530 end program test_command_argument_count
2533 @item @emph{See also}:
2534 @ref{GET_COMMAND}, @ref{GET_COMMAND_ARGUMENT}
2540 @section @code{COMPLEX} --- Complex conversion function
2542 @cindex complex numbers, conversion to
2543 @cindex conversion, to complex
2546 @item @emph{Description}:
2547 @code{COMPLEX(X, Y)} returns a complex number where @var{X} is converted
2548 to the real component and @var{Y} is converted to the imaginary
2551 @item @emph{Standard}:
2557 @item @emph{Syntax}:
2558 @code{RESULT = COMPLEX(X, Y)}
2560 @item @emph{Arguments}:
2561 @multitable @columnfractions .15 .70
2562 @item @var{X} @tab The type may be @code{INTEGER} or @code{REAL}.
2563 @item @var{Y} @tab The type may be @code{INTEGER} or @code{REAL}.
2566 @item @emph{Return value}:
2567 If @var{X} and @var{Y} are both of @code{INTEGER} type, then the return
2568 value is of default @code{COMPLEX} type.
2570 If @var{X} and @var{Y} are of @code{REAL} type, or one is of @code{REAL}
2571 type and one is of @code{INTEGER} type, then the return value is of
2572 @code{COMPLEX} type with a kind equal to that of the @code{REAL}
2573 argument with the highest precision.
2575 @item @emph{Example}:
2577 program test_complex
2580 print *, complex(i, x)
2581 end program test_complex
2584 @item @emph{See also}:
2591 @section @code{CONJG} --- Complex conjugate function
2594 @cindex complex conjugate
2597 @item @emph{Description}:
2598 @code{CONJG(Z)} returns the conjugate of @var{Z}. If @var{Z} is @code{(x, y)}
2599 then the result is @code{(x, -y)}
2601 @item @emph{Standard}:
2602 Fortran 77 and later, has overloads that are GNU extensions
2607 @item @emph{Syntax}:
2610 @item @emph{Arguments}:
2611 @multitable @columnfractions .15 .70
2612 @item @var{Z} @tab The type shall be @code{COMPLEX}.
2615 @item @emph{Return value}:
2616 The return value is of type @code{COMPLEX}.
2618 @item @emph{Example}:
2621 complex :: z = (2.0, 3.0)
2622 complex(8) :: dz = (2.71_8, -3.14_8)
2627 end program test_conjg
2630 @item @emph{Specific names}:
2631 @multitable @columnfractions .20 .20 .20 .25
2632 @item Name @tab Argument @tab Return type @tab Standard
2633 @item @code{CONJG(Z)} @tab @code{COMPLEX Z} @tab @code{COMPLEX} @tab GNU extension
2634 @item @code{DCONJG(Z)} @tab @code{COMPLEX(8) Z} @tab @code{COMPLEX(8)} @tab GNU extension
2641 @section @code{COS} --- Cosine function
2647 @cindex trigonometric function, cosine
2651 @item @emph{Description}:
2652 @code{COS(X)} computes the cosine of @var{X}.
2654 @item @emph{Standard}:
2655 Fortran 77 and later, has overloads that are GNU extensions
2660 @item @emph{Syntax}:
2661 @code{RESULT = COS(X)}
2663 @item @emph{Arguments}:
2664 @multitable @columnfractions .15 .70
2665 @item @var{X} @tab The type shall be @code{REAL} or
2669 @item @emph{Return value}:
2670 The return value is of the same type and kind as @var{X}. The real part
2671 of the result is in radians. If @var{X} is of the type @code{REAL},
2672 the return value lies in the range @math{ -1 \leq \cos (x) \leq 1}.
2674 @item @emph{Example}:
2679 end program test_cos
2682 @item @emph{Specific names}:
2683 @multitable @columnfractions .20 .20 .20 .25
2684 @item Name @tab Argument @tab Return type @tab Standard
2685 @item @code{COS(X)} n@tab @code{REAL(4) X} @tab @code{REAL(4)} @tab Fortran 77 and later
2686 @item @code{DCOS(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab Fortran 77 and later
2687 @item @code{CCOS(X)} @tab @code{COMPLEX(4) X} @tab @code{COMPLEX(4)} @tab Fortran 77 and later
2688 @item @code{ZCOS(X)} @tab @code{COMPLEX(8) X} @tab @code{COMPLEX(8)} @tab GNU extension
2689 @item @code{CDCOS(X)} @tab @code{COMPLEX(8) X} @tab @code{COMPLEX(8)} @tab GNU extension
2692 @item @emph{See also}:
2693 Inverse function: @ref{ACOS}
2700 @section @code{COSH} --- Hyperbolic cosine function
2703 @cindex hyperbolic cosine
2704 @cindex hyperbolic function, cosine
2705 @cindex cosine, hyperbolic
2708 @item @emph{Description}:
2709 @code{COSH(X)} computes the hyperbolic cosine of @var{X}.
2711 @item @emph{Standard}:
2712 Fortran 77 and later, for a complex argument Fortran 2008 or later
2717 @item @emph{Syntax}:
2720 @item @emph{Arguments}:
2721 @multitable @columnfractions .15 .70
2722 @item @var{X} @tab The type shall be @code{REAL} or @code{COMPLEX}.
2725 @item @emph{Return value}:
2726 The return value has same type and kind as @var{X}. If @var{X} is
2727 complex, the imaginary part of the result is in radians. If @var{X}
2728 is @code{REAL}, the return value has a lower bound of one,
2729 @math{\cosh (x) \geq 1}.
2731 @item @emph{Example}:
2734 real(8) :: x = 1.0_8
2736 end program test_cosh
2739 @item @emph{Specific names}:
2740 @multitable @columnfractions .20 .20 .20 .25
2741 @item Name @tab Argument @tab Return type @tab Standard
2742 @item @code{COSH(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab Fortran 77 and later
2743 @item @code{DCOSH(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab Fortran 77 and later
2746 @item @emph{See also}:
2747 Inverse function: @ref{ACOSH}
2754 @section @code{COUNT} --- Count function
2756 @cindex array, conditionally count elements
2757 @cindex array, element counting
2758 @cindex array, number of elements
2761 @item @emph{Description}:
2763 Counts the number of @code{.TRUE.} elements in a logical @var{MASK},
2764 or, if the @var{DIM} argument is supplied, counts the number of
2765 elements along each row of the array in the @var{DIM} direction.
2766 If the array has zero size, or all of the elements of @var{MASK} are
2767 @code{.FALSE.}, then the result is @code{0}.
2769 @item @emph{Standard}:
2770 Fortran 95 and later, with @var{KIND} argument Fortran 2003 and later
2773 Transformational function
2775 @item @emph{Syntax}:
2776 @code{RESULT = COUNT(MASK [, DIM, KIND])}
2778 @item @emph{Arguments}:
2779 @multitable @columnfractions .15 .70
2780 @item @var{MASK} @tab The type shall be @code{LOGICAL}.
2781 @item @var{DIM} @tab (Optional) The type shall be @code{INTEGER}.
2782 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
2783 expression indicating the kind parameter of the result.
2786 @item @emph{Return value}:
2787 The return value is of type @code{INTEGER} and of kind @var{KIND}. If
2788 @var{KIND} is absent, the return value is of default integer kind.
2789 If @var{DIM} is present, the result is an array with a rank one less
2790 than the rank of @var{ARRAY}, and a size corresponding to the shape
2791 of @var{ARRAY} with the @var{DIM} dimension removed.
2793 @item @emph{Example}:
2796 integer, dimension(2,3) :: a, b
2797 logical, dimension(2,3) :: mask
2798 a = reshape( (/ 1, 2, 3, 4, 5, 6 /), (/ 2, 3 /))
2799 b = reshape( (/ 0, 7, 3, 4, 5, 8 /), (/ 2, 3 /))
2800 print '(3i3)', a(1,:)
2801 print '(3i3)', a(2,:)
2803 print '(3i3)', b(1,:)
2804 print '(3i3)', b(2,:)
2807 print '(3l3)', mask(1,:)
2808 print '(3l3)', mask(2,:)
2810 print '(3i3)', count(mask)
2812 print '(3i3)', count(mask, 1)
2814 print '(3i3)', count(mask, 2)
2815 end program test_count
2822 @section @code{CPU_TIME} --- CPU elapsed time in seconds
2824 @cindex time, elapsed
2827 @item @emph{Description}:
2828 Returns a @code{REAL} value representing the elapsed CPU time in
2829 seconds. This is useful for testing segments of code to determine
2832 If a time source is available, time will be reported with microsecond
2833 resolution. If no time source is available, @var{TIME} is set to
2836 Note that @var{TIME} may contain a, system dependent, arbitrary offset
2837 and may not start with @code{0.0}. For @code{CPU_TIME}, the absolute
2838 value is meaningless, only differences between subsequent calls to
2839 this subroutine, as shown in the example below, should be used.
2842 @item @emph{Standard}:
2843 Fortran 95 and later
2848 @item @emph{Syntax}:
2849 @code{CALL CPU_TIME(TIME)}
2851 @item @emph{Arguments}:
2852 @multitable @columnfractions .15 .70
2853 @item @var{TIME} @tab The type shall be @code{REAL} with @code{INTENT(OUT)}.
2856 @item @emph{Return value}:
2859 @item @emph{Example}:
2861 program test_cpu_time
2862 real :: start, finish
2863 call cpu_time(start)
2864 ! put code to test here
2865 call cpu_time(finish)
2866 print '("Time = ",f6.3," seconds.")',finish-start
2867 end program test_cpu_time
2870 @item @emph{See also}:
2871 @ref{SYSTEM_CLOCK}, @ref{DATE_AND_TIME}
2877 @section @code{CSHIFT} --- Circular shift elements of an array
2879 @cindex array, shift circularly
2880 @cindex array, permutation
2881 @cindex array, rotate
2884 @item @emph{Description}:
2885 @code{CSHIFT(ARRAY, SHIFT [, DIM])} performs a circular shift on elements of
2886 @var{ARRAY} along the dimension of @var{DIM}. If @var{DIM} is omitted it is
2887 taken to be @code{1}. @var{DIM} is a scalar of type @code{INTEGER} in the
2888 range of @math{1 \leq DIM \leq n)} where @math{n} is the rank of @var{ARRAY}.
2889 If the rank of @var{ARRAY} is one, then all elements of @var{ARRAY} are shifted
2890 by @var{SHIFT} places. If rank is greater than one, then all complete rank one
2891 sections of @var{ARRAY} along the given dimension are shifted. Elements
2892 shifted out one end of each rank one section are shifted back in the other end.
2894 @item @emph{Standard}:
2895 Fortran 95 and later
2898 Transformational function
2900 @item @emph{Syntax}:
2901 @code{RESULT = CSHIFT(ARRAY, SHIFT [, DIM])}
2903 @item @emph{Arguments}:
2904 @multitable @columnfractions .15 .70
2905 @item @var{ARRAY} @tab Shall be an array of any type.
2906 @item @var{SHIFT} @tab The type shall be @code{INTEGER}.
2907 @item @var{DIM} @tab The type shall be @code{INTEGER}.
2910 @item @emph{Return value}:
2911 Returns an array of same type and rank as the @var{ARRAY} argument.
2913 @item @emph{Example}:
2916 integer, dimension(3,3) :: a
2917 a = reshape( (/ 1, 2, 3, 4, 5, 6, 7, 8, 9 /), (/ 3, 3 /))
2918 print '(3i3)', a(1,:)
2919 print '(3i3)', a(2,:)
2920 print '(3i3)', a(3,:)
2921 a = cshift(a, SHIFT=(/1, 2, -1/), DIM=2)
2923 print '(3i3)', a(1,:)
2924 print '(3i3)', a(2,:)
2925 print '(3i3)', a(3,:)
2926 end program test_cshift
2933 @section @code{CTIME} --- Convert a time into a string
2935 @cindex time, conversion to string
2936 @cindex conversion, to string
2939 @item @emph{Description}:
2940 @code{CTIME} converts a system time value, such as returned by
2941 @code{TIME8()}, to a string of the form @samp{Sat Aug 19 18:13:14 1995}.
2943 This intrinsic is provided in both subroutine and function forms; however,
2944 only one form can be used in any given program unit.
2946 @item @emph{Standard}:
2950 Subroutine, function
2952 @item @emph{Syntax}:
2953 @multitable @columnfractions .80
2954 @item @code{CALL CTIME(TIME, RESULT)}.
2955 @item @code{RESULT = CTIME(TIME)}, (not recommended).
2958 @item @emph{Arguments}:
2959 @multitable @columnfractions .15 .70
2960 @item @var{TIME} @tab The type shall be of type @code{INTEGER(KIND=8)}.
2961 @item @var{RESULT} @tab The type shall be of type @code{CHARACTER} and
2965 @item @emph{Return value}:
2966 The converted date and time as a string.
2968 @item @emph{Example}:
2972 character(len=30) :: date
2975 ! Do something, main part of the program
2978 print *, 'Program was started on ', date
2979 end program test_ctime
2982 @item @emph{See Also}:
2983 @ref{GMTIME}, @ref{LTIME}, @ref{TIME}, @ref{TIME8}
2989 @section @code{DATE_AND_TIME} --- Date and time subroutine
2990 @fnindex DATE_AND_TIME
2991 @cindex date, current
2992 @cindex current date
2993 @cindex time, current
2994 @cindex current time
2997 @item @emph{Description}:
2998 @code{DATE_AND_TIME(DATE, TIME, ZONE, VALUES)} gets the corresponding date and
2999 time information from the real-time system clock. @var{DATE} is
3000 @code{INTENT(OUT)} and has form ccyymmdd. @var{TIME} is @code{INTENT(OUT)} and
3001 has form hhmmss.sss. @var{ZONE} is @code{INTENT(OUT)} and has form (+-)hhmm,
3002 representing the difference with respect to Coordinated Universal Time (UTC).
3003 Unavailable time and date parameters return blanks.
3005 @var{VALUES} is @code{INTENT(OUT)} and provides the following:
3007 @multitable @columnfractions .15 .30 .40
3008 @item @tab @code{VALUE(1)}: @tab The year
3009 @item @tab @code{VALUE(2)}: @tab The month
3010 @item @tab @code{VALUE(3)}: @tab The day of the month
3011 @item @tab @code{VALUE(4)}: @tab Time difference with UTC in minutes
3012 @item @tab @code{VALUE(5)}: @tab The hour of the day
3013 @item @tab @code{VALUE(6)}: @tab The minutes of the hour
3014 @item @tab @code{VALUE(7)}: @tab The seconds of the minute
3015 @item @tab @code{VALUE(8)}: @tab The milliseconds of the second
3018 @item @emph{Standard}:
3019 Fortran 95 and later
3024 @item @emph{Syntax}:
3025 @code{CALL DATE_AND_TIME([DATE, TIME, ZONE, VALUES])}
3027 @item @emph{Arguments}:
3028 @multitable @columnfractions .15 .70
3029 @item @var{DATE} @tab (Optional) The type shall be @code{CHARACTER(LEN=8)}
3030 or larger, and of default kind.
3031 @item @var{TIME} @tab (Optional) The type shall be @code{CHARACTER(LEN=10)}
3032 or larger, and of default kind.
3033 @item @var{ZONE} @tab (Optional) The type shall be @code{CHARACTER(LEN=5)}
3034 or larger, and of default kind.
3035 @item @var{VALUES}@tab (Optional) The type shall be @code{INTEGER(8)}.
3038 @item @emph{Return value}:
3041 @item @emph{Example}:
3043 program test_time_and_date
3044 character(8) :: date
3045 character(10) :: time
3046 character(5) :: zone
3047 integer,dimension(8) :: values
3048 ! using keyword arguments
3049 call date_and_time(date,time,zone,values)
3050 call date_and_time(DATE=date,ZONE=zone)
3051 call date_and_time(TIME=time)
3052 call date_and_time(VALUES=values)
3053 print '(a,2x,a,2x,a)', date, time, zone
3054 print '(8i5))', values
3055 end program test_time_and_date
3058 @item @emph{See also}:
3059 @ref{CPU_TIME}, @ref{SYSTEM_CLOCK}
3065 @section @code{DBLE} --- Double conversion function
3067 @cindex conversion, to real
3070 @item @emph{Description}:
3071 @code{DBLE(A)} Converts @var{A} to double precision real type.
3073 @item @emph{Standard}:
3074 Fortran 77 and later
3079 @item @emph{Syntax}:
3080 @code{RESULT = DBLE(A)}
3082 @item @emph{Arguments}:
3083 @multitable @columnfractions .15 .70
3084 @item @var{A} @tab The type shall be @code{INTEGER}, @code{REAL},
3088 @item @emph{Return value}:
3089 The return value is of type double precision real.
3091 @item @emph{Example}:
3096 complex :: z = (2.3,1.14)
3097 print *, dble(x), dble(i), dble(z)
3098 end program test_dble
3101 @item @emph{See also}:
3108 @section @code{DCMPLX} --- Double complex conversion function
3110 @cindex complex numbers, conversion to
3111 @cindex conversion, to complex
3114 @item @emph{Description}:
3115 @code{DCMPLX(X [,Y])} returns a double complex number where @var{X} is
3116 converted to the real component. If @var{Y} is present it is converted to the
3117 imaginary component. If @var{Y} is not present then the imaginary component is
3118 set to 0.0. If @var{X} is complex then @var{Y} must not be present.
3120 @item @emph{Standard}:
3126 @item @emph{Syntax}:
3127 @code{RESULT = DCMPLX(X [, Y])}
3129 @item @emph{Arguments}:
3130 @multitable @columnfractions .15 .70
3131 @item @var{X} @tab The type may be @code{INTEGER}, @code{REAL},
3133 @item @var{Y} @tab (Optional if @var{X} is not @code{COMPLEX}.) May be
3134 @code{INTEGER} or @code{REAL}.
3137 @item @emph{Return value}:
3138 The return value is of type @code{COMPLEX(8)}
3140 @item @emph{Example}:
3150 print *, dcmplx(x,i)
3151 end program test_dcmplx
3157 @section @code{DIGITS} --- Significant binary digits function
3159 @cindex model representation, significant digits
3162 @item @emph{Description}:
3163 @code{DIGITS(X)} returns the number of significant binary digits of the internal
3164 model representation of @var{X}. For example, on a system using a 32-bit
3165 floating point representation, a default real number would likely return 24.
3167 @item @emph{Standard}:
3168 Fortran 95 and later
3173 @item @emph{Syntax}:
3174 @code{RESULT = DIGITS(X)}
3176 @item @emph{Arguments}:
3177 @multitable @columnfractions .15 .70
3178 @item @var{X} @tab The type may be @code{INTEGER} or @code{REAL}.
3181 @item @emph{Return value}:
3182 The return value is of type @code{INTEGER}.
3184 @item @emph{Example}:
3187 integer :: i = 12345
3193 end program test_digits
3200 @section @code{DIM} --- Positive difference
3204 @cindex positive difference
3207 @item @emph{Description}:
3208 @code{DIM(X,Y)} returns the difference @code{X-Y} if the result is positive;
3209 otherwise returns zero.
3211 @item @emph{Standard}:
3212 Fortran 77 and later
3217 @item @emph{Syntax}:
3218 @code{RESULT = DIM(X, Y)}
3220 @item @emph{Arguments}:
3221 @multitable @columnfractions .15 .70
3222 @item @var{X} @tab The type shall be @code{INTEGER} or @code{REAL}
3223 @item @var{Y} @tab The type shall be the same type and kind as @var{X}.
3226 @item @emph{Return value}:
3227 The return value is of type @code{INTEGER} or @code{REAL}.
3229 @item @emph{Example}:
3235 x = dim(4.345_8, 2.111_8)
3238 end program test_dim
3241 @item @emph{Specific names}:
3242 @multitable @columnfractions .20 .20 .20 .25
3243 @item Name @tab Argument @tab Return type @tab Standard
3244 @item @code{DIM(X,Y)} @tab @code{REAL(4) X, Y} @tab @code{REAL(4)} @tab Fortran 77 and later
3245 @item @code{IDIM(X,Y)} @tab @code{INTEGER(4) X, Y} @tab @code{INTEGER(4)} @tab Fortran 77 and later
3246 @item @code{DDIM(X,Y)} @tab @code{REAL(8) X, Y} @tab @code{REAL(8)} @tab Fortran 77 and later
3253 @section @code{DOT_PRODUCT} --- Dot product function
3254 @fnindex DOT_PRODUCT
3256 @cindex vector product
3257 @cindex product, vector
3260 @item @emph{Description}:
3261 @code{DOT_PRODUCT(VECTOR_A, VECTOR_B)} computes the dot product multiplication
3262 of two vectors @var{VECTOR_A} and @var{VECTOR_B}. The two vectors may be
3263 either numeric or logical and must be arrays of rank one and of equal size. If
3264 the vectors are @code{INTEGER} or @code{REAL}, the result is
3265 @code{SUM(VECTOR_A*VECTOR_B)}. If the vectors are @code{COMPLEX}, the result
3266 is @code{SUM(CONJG(VECTOR_A)*VECTOR_B)}. If the vectors are @code{LOGICAL},
3267 the result is @code{ANY(VECTOR_A .AND. VECTOR_B)}.
3269 @item @emph{Standard}:
3270 Fortran 95 and later
3273 Transformational function
3275 @item @emph{Syntax}:
3276 @code{RESULT = DOT_PRODUCT(VECTOR_A, VECTOR_B)}
3278 @item @emph{Arguments}:
3279 @multitable @columnfractions .15 .70
3280 @item @var{VECTOR_A} @tab The type shall be numeric or @code{LOGICAL}, rank 1.
3281 @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.
3284 @item @emph{Return value}:
3285 If the arguments are numeric, the return value is a scalar of numeric type,
3286 @code{INTEGER}, @code{REAL}, or @code{COMPLEX}. If the arguments are
3287 @code{LOGICAL}, the return value is @code{.TRUE.} or @code{.FALSE.}.
3289 @item @emph{Example}:
3291 program test_dot_prod
3292 integer, dimension(3) :: a, b
3299 print *, dot_product(a,b)
3300 end program test_dot_prod
3307 @section @code{DPROD} --- Double product function
3309 @cindex product, double-precision
3312 @item @emph{Description}:
3313 @code{DPROD(X,Y)} returns the product @code{X*Y}.
3315 @item @emph{Standard}:
3316 Fortran 77 and later
3321 @item @emph{Syntax}:
3322 @code{RESULT = DPROD(X, Y)}
3324 @item @emph{Arguments}:
3325 @multitable @columnfractions .15 .70
3326 @item @var{X} @tab The type shall be @code{REAL}.
3327 @item @var{Y} @tab The type shall be @code{REAL}.
3330 @item @emph{Return value}:
3331 The return value is of type @code{REAL(8)}.
3333 @item @emph{Example}:
3341 end program test_dprod
3344 @item @emph{Specific names}:
3345 @multitable @columnfractions .20 .20 .20 .25
3346 @item Name @tab Argument @tab Return type @tab Standard
3347 @item @code{DPROD(X,Y)} @tab @code{REAL(4) X, Y} @tab @code{REAL(4)} @tab Fortran 77 and later
3354 @section @code{DREAL} --- Double real part function
3356 @cindex complex numbers, real part
3359 @item @emph{Description}:
3360 @code{DREAL(Z)} returns the real part of complex variable @var{Z}.
3362 @item @emph{Standard}:
3368 @item @emph{Syntax}:
3369 @code{RESULT = DREAL(A)}
3371 @item @emph{Arguments}:
3372 @multitable @columnfractions .15 .70
3373 @item @var{A} @tab The type shall be @code{COMPLEX(8)}.
3376 @item @emph{Return value}:
3377 The return value is of type @code{REAL(8)}.
3379 @item @emph{Example}:
3382 complex(8) :: z = (1.3_8,7.2_8)
3384 end program test_dreal
3387 @item @emph{See also}:
3395 @section @code{DTIME} --- Execution time subroutine (or function)
3397 @cindex time, elapsed
3398 @cindex elapsed time
3401 @item @emph{Description}:
3402 @code{DTIME(VALUES, TIME)} initially returns the number of seconds of runtime
3403 since the start of the process's execution in @var{TIME}. @var{VALUES}
3404 returns the user and system components of this time in @code{VALUES(1)} and
3405 @code{VALUES(2)} respectively. @var{TIME} is equal to @code{VALUES(1) +
3408 Subsequent invocations of @code{DTIME} return values accumulated since the
3409 previous invocation.
3411 On some systems, the underlying timings are represented using types with
3412 sufficiently small limits that overflows (wrap around) are possible, such as
3413 32-bit types. Therefore, the values returned by this intrinsic might be, or
3414 become, negative, or numerically less than previous values, during a single
3415 run of the compiled program.
3417 Please note, that this implementation is thread safe if used within OpenMP
3418 directives, i.e., its state will be consistent while called from multiple
3419 threads. However, if @code{DTIME} is called from multiple threads, the result
3420 is still the time since the last invocation. This may not give the intended
3421 results. If possible, use @code{CPU_TIME} instead.
3423 This intrinsic is provided in both subroutine and function forms; however,
3424 only one form can be used in any given program unit.
3426 @var{VALUES} and @var{TIME} are @code{INTENT(OUT)} and provide the following:
3428 @multitable @columnfractions .15 .30 .40
3429 @item @tab @code{VALUES(1)}: @tab User time in seconds.
3430 @item @tab @code{VALUES(2)}: @tab System time in seconds.
3431 @item @tab @code{TIME}: @tab Run time since start in seconds.
3434 @item @emph{Standard}:
3438 Subroutine, function
3440 @item @emph{Syntax}:
3441 @multitable @columnfractions .80
3442 @item @code{CALL DTIME(VALUES, TIME)}.
3443 @item @code{TIME = DTIME(VALUES)}, (not recommended).
3446 @item @emph{Arguments}:
3447 @multitable @columnfractions .15 .70
3448 @item @var{VALUES}@tab The type shall be @code{REAL(4), DIMENSION(2)}.
3449 @item @var{TIME}@tab The type shall be @code{REAL(4)}.
3452 @item @emph{Return value}:
3453 Elapsed time in seconds since the last invocation or since the start of program
3454 execution if not called before.
3456 @item @emph{Example}:
3460 real, dimension(2) :: tarray
3462 call dtime(tarray, result)
3466 do i=1,100000000 ! Just a delay
3469 call dtime(tarray, result)
3473 end program test_dtime
3476 @item @emph{See also}:
3484 @section @code{EOSHIFT} --- End-off shift elements of an array
3486 @cindex array, shift
3489 @item @emph{Description}:
3490 @code{EOSHIFT(ARRAY, SHIFT[, BOUNDARY, DIM])} performs an end-off shift on
3491 elements of @var{ARRAY} along the dimension of @var{DIM}. If @var{DIM} is
3492 omitted it is taken to be @code{1}. @var{DIM} is a scalar of type
3493 @code{INTEGER} in the range of @math{1 \leq DIM \leq n)} where @math{n} is the
3494 rank of @var{ARRAY}. If the rank of @var{ARRAY} is one, then all elements of
3495 @var{ARRAY} are shifted by @var{SHIFT} places. If rank is greater than one,
3496 then all complete rank one sections of @var{ARRAY} along the given dimension are
3497 shifted. Elements shifted out one end of each rank one section are dropped. If
3498 @var{BOUNDARY} is present then the corresponding value of from @var{BOUNDARY}
3499 is copied back in the other end. If @var{BOUNDARY} is not present then the
3500 following are copied in depending on the type of @var{ARRAY}.
3502 @multitable @columnfractions .15 .80
3503 @item @emph{Array Type} @tab @emph{Boundary Value}
3504 @item Numeric @tab 0 of the type and kind of @var{ARRAY}.
3505 @item Logical @tab @code{.FALSE.}.
3506 @item Character(@var{len}) @tab @var{len} blanks.
3509 @item @emph{Standard}:
3510 Fortran 95 and later
3513 Transformational function
3515 @item @emph{Syntax}:
3516 @code{RESULT = EOSHIFT(ARRAY, SHIFT [, BOUNDARY, DIM])}
3518 @item @emph{Arguments}:
3519 @multitable @columnfractions .15 .70
3520 @item @var{ARRAY} @tab May be any type, not scalar.
3521 @item @var{SHIFT} @tab The type shall be @code{INTEGER}.
3522 @item @var{BOUNDARY} @tab Same type as @var{ARRAY}.
3523 @item @var{DIM} @tab The type shall be @code{INTEGER}.
3526 @item @emph{Return value}:
3527 Returns an array of same type and rank as the @var{ARRAY} argument.
3529 @item @emph{Example}:
3531 program test_eoshift
3532 integer, dimension(3,3) :: a
3533 a = reshape( (/ 1, 2, 3, 4, 5, 6, 7, 8, 9 /), (/ 3, 3 /))
3534 print '(3i3)', a(1,:)
3535 print '(3i3)', a(2,:)
3536 print '(3i3)', a(3,:)
3537 a = EOSHIFT(a, SHIFT=(/1, 2, 1/), BOUNDARY=-5, DIM=2)
3539 print '(3i3)', a(1,:)
3540 print '(3i3)', a(2,:)
3541 print '(3i3)', a(3,:)
3542 end program test_eoshift
3549 @section @code{EPSILON} --- Epsilon function
3551 @cindex model representation, epsilon
3554 @item @emph{Description}:
3555 @code{EPSILON(X)} returns the smallest number @var{E} of the same kind
3556 as @var{X} such that @math{1 + E > 1}.
3558 @item @emph{Standard}:
3559 Fortran 95 and later
3564 @item @emph{Syntax}:
3565 @code{RESULT = EPSILON(X)}
3567 @item @emph{Arguments}:
3568 @multitable @columnfractions .15 .70
3569 @item @var{X} @tab The type shall be @code{REAL}.
3572 @item @emph{Return value}:
3573 The return value is of same type as the argument.
3575 @item @emph{Example}:
3577 program test_epsilon
3582 end program test_epsilon
3589 @section @code{ERF} --- Error function
3591 @cindex error function
3594 @item @emph{Description}:
3595 @code{ERF(X)} computes the error function of @var{X}.
3597 @item @emph{Standard}:
3598 Fortran 2008 and later
3603 @item @emph{Syntax}:
3604 @code{RESULT = ERF(X)}
3606 @item @emph{Arguments}:
3607 @multitable @columnfractions .15 .70
3608 @item @var{X} @tab The type shall be @code{REAL}.
3611 @item @emph{Return value}:
3612 The return value is of type @code{REAL}, of the same kind as
3613 @var{X} and lies in the range @math{-1 \leq erf (x) \leq 1 }.
3615 @item @emph{Example}:
3618 real(8) :: x = 0.17_8
3620 end program test_erf
3623 @item @emph{Specific names}:
3624 @multitable @columnfractions .20 .20 .20 .25
3625 @item Name @tab Argument @tab Return type @tab Standard
3626 @item @code{DERF(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU extension
3633 @section @code{ERFC} --- Error function
3635 @cindex error function, complementary
3638 @item @emph{Description}:
3639 @code{ERFC(X)} computes the complementary error function of @var{X}.
3641 @item @emph{Standard}:
3642 Fortran 2008 and later
3647 @item @emph{Syntax}:
3648 @code{RESULT = ERFC(X)}
3650 @item @emph{Arguments}:
3651 @multitable @columnfractions .15 .70
3652 @item @var{X} @tab The type shall be @code{REAL}.
3655 @item @emph{Return value}:
3656 The return value is of type @code{REAL} and of the same kind as @var{X}.
3657 It lies in the range @math{ 0 \leq erfc (x) \leq 2 }.
3659 @item @emph{Example}:
3662 real(8) :: x = 0.17_8
3664 end program test_erfc
3667 @item @emph{Specific names}:
3668 @multitable @columnfractions .20 .20 .20 .25
3669 @item Name @tab Argument @tab Return type @tab Standard
3670 @item @code{DERFC(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU extension
3677 @section @code{ERFC_SCALED} --- Error function
3678 @fnindex ERFC_SCALED
3679 @cindex error function, complementary, exponentially-scaled
3682 @item @emph{Description}:
3683 @code{ERFC_SCALED(X)} computes the exponentially-scaled complementary
3684 error function of @var{X}.
3686 @item @emph{Standard}:
3687 Fortran 2008 and later
3692 @item @emph{Syntax}:
3693 @code{RESULT = ERFC_SCALED(X)}
3695 @item @emph{Arguments}:
3696 @multitable @columnfractions .15 .70
3697 @item @var{X} @tab The type shall be @code{REAL}.
3700 @item @emph{Return value}:
3701 The return value is of type @code{REAL} and of the same kind as @var{X}.
3703 @item @emph{Example}:
3705 program test_erfc_scaled
3706 real(8) :: x = 0.17_8
3708 end program test_erfc_scaled
3715 @section @code{ETIME} --- Execution time subroutine (or function)
3717 @cindex time, elapsed
3720 @item @emph{Description}:
3721 @code{ETIME(VALUES, TIME)} returns the number of seconds of runtime
3722 since the start of the process's execution in @var{TIME}. @var{VALUES}
3723 returns the user and system components of this time in @code{VALUES(1)} and
3724 @code{VALUES(2)} respectively. @var{TIME} is equal to @code{VALUES(1) + VALUES(2)}.
3726 On some systems, the underlying timings are represented using types with
3727 sufficiently small limits that overflows (wrap around) are possible, such as
3728 32-bit types. Therefore, the values returned by this intrinsic might be, or
3729 become, negative, or numerically less than previous values, during a single
3730 run of the compiled program.
3732 This intrinsic is provided in both subroutine and function forms; however,
3733 only one form can be used in any given program unit.
3735 @var{VALUES} and @var{TIME} are @code{INTENT(OUT)} and provide the following:
3737 @multitable @columnfractions .15 .30 .60
3738 @item @tab @code{VALUES(1)}: @tab User time in seconds.
3739 @item @tab @code{VALUES(2)}: @tab System time in seconds.
3740 @item @tab @code{TIME}: @tab Run time since start in seconds.
3743 @item @emph{Standard}:
3747 Subroutine, function
3749 @item @emph{Syntax}:
3750 @multitable @columnfractions .80
3751 @item @code{CALL ETIME(VALUES, TIME)}.
3752 @item @code{TIME = ETIME(VALUES)}, (not recommended).
3755 @item @emph{Arguments}:
3756 @multitable @columnfractions .15 .70
3757 @item @var{VALUES}@tab The type shall be @code{REAL(4), DIMENSION(2)}.
3758 @item @var{TIME}@tab The type shall be @code{REAL(4)}.
3761 @item @emph{Return value}:
3762 Elapsed time in seconds since the start of program execution.
3764 @item @emph{Example}:
3768 real, dimension(2) :: tarray
3770 call ETIME(tarray, result)
3774 do i=1,100000000 ! Just a delay
3777 call ETIME(tarray, result)
3781 end program test_etime
3784 @item @emph{See also}:
3792 @section @code{EXIT} --- Exit the program with status.
3794 @cindex program termination
3795 @cindex terminate program
3798 @item @emph{Description}:
3799 @code{EXIT} causes immediate termination of the program with status. If status
3800 is omitted it returns the canonical @emph{success} for the system. All Fortran
3801 I/O units are closed.
3803 @item @emph{Standard}:
3809 @item @emph{Syntax}:
3810 @code{CALL EXIT([STATUS])}
3812 @item @emph{Arguments}:
3813 @multitable @columnfractions .15 .70
3814 @item @var{STATUS} @tab Shall be an @code{INTEGER} of the default kind.
3817 @item @emph{Return value}:
3818 @code{STATUS} is passed to the parent process on exit.
3820 @item @emph{Example}:
3823 integer :: STATUS = 0
3824 print *, 'This program is going to exit.'
3826 end program test_exit
3829 @item @emph{See also}:
3830 @ref{ABORT}, @ref{KILL}
3836 @section @code{EXP} --- Exponential function
3842 @cindex exponential function
3843 @cindex logarithmic function, inverse
3846 @item @emph{Description}:
3847 @code{EXP(X)} computes the base @math{e} exponential of @var{X}.
3849 @item @emph{Standard}:
3850 Fortran 77 and later, has overloads that are GNU extensions
3855 @item @emph{Syntax}:
3856 @code{RESULT = EXP(X)}
3858 @item @emph{Arguments}:
3859 @multitable @columnfractions .15 .70
3860 @item @var{X} @tab The type shall be @code{REAL} or
3864 @item @emph{Return value}:
3865 The return value has same type and kind as @var{X}.
3867 @item @emph{Example}:
3872 end program test_exp
3875 @item @emph{Specific names}:
3876 @multitable @columnfractions .20 .20 .20 .25
3877 @item Name @tab Argument @tab Return type @tab Standard
3878 @item @code{EXP(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab Fortran 77 and later
3879 @item @code{DEXP(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab Fortran 77 and later
3880 @item @code{CEXP(X)} @tab @code{COMPLEX(4) X} @tab @code{COMPLEX(4)} @tab Fortran 77 and later
3881 @item @code{ZEXP(X)} @tab @code{COMPLEX(8) X} @tab @code{COMPLEX(8)} @tab GNU extension
3882 @item @code{CDEXP(X)} @tab @code{COMPLEX(8) X} @tab @code{COMPLEX(8)} @tab GNU extension
3889 @section @code{EXPONENT} --- Exponent function
3891 @cindex real number, exponent
3892 @cindex floating point, exponent
3895 @item @emph{Description}:
3896 @code{EXPONENT(X)} returns the value of the exponent part of @var{X}. If @var{X}
3897 is zero the value returned is zero.
3899 @item @emph{Standard}:
3900 Fortran 95 and later
3905 @item @emph{Syntax}:
3906 @code{RESULT = EXPONENT(X)}
3908 @item @emph{Arguments}:
3909 @multitable @columnfractions .15 .70
3910 @item @var{X} @tab The type shall be @code{REAL}.
3913 @item @emph{Return value}:
3914 The return value is of type default @code{INTEGER}.
3916 @item @emph{Example}:
3918 program test_exponent
3923 print *, exponent(0.0)
3924 end program test_exponent
3931 @section @code{FDATE} --- Get the current time as a string
3933 @cindex time, current
3934 @cindex current time
3935 @cindex date, current
3936 @cindex current date
3939 @item @emph{Description}:
3940 @code{FDATE(DATE)} returns the current date (using the same format as
3941 @code{CTIME}) in @var{DATE}. It is equivalent to @code{CALL CTIME(DATE,
3944 This intrinsic is provided in both subroutine and function forms; however,
3945 only one form can be used in any given program unit.
3947 @var{DATE} is an @code{INTENT(OUT)} @code{CHARACTER} variable of the
3950 @item @emph{Standard}:
3954 Subroutine, function
3956 @item @emph{Syntax}:
3957 @multitable @columnfractions .80
3958 @item @code{CALL FDATE(DATE)}.
3959 @item @code{DATE = FDATE()}, (not recommended).
3962 @item @emph{Arguments}:
3963 @multitable @columnfractions .15 .70
3964 @item @var{DATE}@tab The type shall be of type @code{CHARACTER} of the
3968 @item @emph{Return value}:
3969 The current date as a string.
3971 @item @emph{Example}:
3975 character(len=30) :: date
3977 print *, 'Program started on ', date
3978 do i = 1, 100000000 ! Just a delay
3982 print *, 'Program ended on ', date
3983 end program test_fdate
3990 @section @code{FGET} --- Read a single character in stream mode from stdin
3992 @cindex read character, stream mode
3993 @cindex stream mode, read character
3994 @cindex file operation, read character
3997 @item @emph{Description}:
3998 Read a single character in stream mode from stdin by bypassing normal
3999 formatted output. Stream I/O should not be mixed with normal record-oriented
4000 (formatted or unformatted) I/O on the same unit; the results are unpredictable.
4002 This intrinsic is provided in both subroutine and function forms; however,
4003 only one form can be used in any given program unit.
4005 Note that the @code{FGET} intrinsic is provided for backwards compatibility with
4006 @command{g77}. GNU Fortran provides the Fortran 2003 Stream facility.
4007 Programmers should consider the use of new stream IO feature in new code
4008 for future portability. See also @ref{Fortran 2003 status}.
4010 @item @emph{Standard}:
4014 Subroutine, function
4016 @item @emph{Syntax}:
4017 @code{CALL FGET(C [, STATUS])}
4019 @item @emph{Arguments}:
4020 @multitable @columnfractions .15 .70
4021 @item @var{C} @tab The type shall be @code{CHARACTER} and of default
4023 @item @var{STATUS} @tab (Optional) status flag of type @code{INTEGER}.
4024 Returns 0 on success, -1 on end-of-file, and a system specific positive
4025 error code otherwise.
4028 @item @emph{Example}:
4031 INTEGER, PARAMETER :: strlen = 100
4032 INTEGER :: status, i = 1
4033 CHARACTER(len=strlen) :: str = ""
4035 WRITE (*,*) 'Enter text:'
4037 CALL fget(str(i:i), status)
4038 if (status /= 0 .OR. i > strlen) exit
4041 WRITE (*,*) TRIM(str)
4045 @item @emph{See also}:
4046 @ref{FGETC}, @ref{FPUT}, @ref{FPUTC}
4052 @section @code{FGETC} --- Read a single character in stream mode
4054 @cindex read character, stream mode
4055 @cindex stream mode, read character
4056 @cindex file operation, read character
4059 @item @emph{Description}:
4060 Read a single character in stream mode by bypassing normal formatted output.
4061 Stream I/O should not be mixed with normal record-oriented (formatted or
4062 unformatted) I/O on the same unit; the results are unpredictable.
4064 This intrinsic is provided in both subroutine and function forms; however,
4065 only one form can be used in any given program unit.
4067 Note that the @code{FGET} intrinsic is provided for backwards compatibility
4068 with @command{g77}. GNU Fortran provides the Fortran 2003 Stream facility.
4069 Programmers should consider the use of new stream IO feature in new code
4070 for future portability. See also @ref{Fortran 2003 status}.
4072 @item @emph{Standard}:
4076 Subroutine, function
4078 @item @emph{Syntax}:
4079 @code{CALL FGETC(UNIT, C [, STATUS])}
4081 @item @emph{Arguments}:
4082 @multitable @columnfractions .15 .70
4083 @item @var{UNIT} @tab The type shall be @code{INTEGER}.
4084 @item @var{C} @tab The type shall be @code{CHARACTER} and of default
4086 @item @var{STATUS} @tab (Optional) status flag of type @code{INTEGER}.
4087 Returns 0 on success, -1 on end-of-file and a system specific positive
4088 error code otherwise.
4091 @item @emph{Example}:
4094 INTEGER :: fd = 42, status
4097 OPEN(UNIT=fd, FILE="/etc/passwd", ACTION="READ", STATUS = "OLD")
4099 CALL fgetc(fd, c, status)
4100 IF (status /= 0) EXIT
4107 @item @emph{See also}:
4108 @ref{FGET}, @ref{FPUT}, @ref{FPUTC}
4114 @section @code{FLOOR} --- Integer floor function
4117 @cindex rounding, floor
4120 @item @emph{Description}:
4121 @code{FLOOR(A)} returns the greatest integer less than or equal to @var{X}.
4123 @item @emph{Standard}:
4124 Fortran 95 and later
4129 @item @emph{Syntax}:
4130 @code{RESULT = FLOOR(A [, KIND])}
4132 @item @emph{Arguments}:
4133 @multitable @columnfractions .15 .70
4134 @item @var{A} @tab The type shall be @code{REAL}.
4135 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
4136 expression indicating the kind parameter of the result.
4139 @item @emph{Return value}:
4140 The return value is of type @code{INTEGER(KIND)} if @var{KIND} is present
4141 and of default-kind @code{INTEGER} otherwise.
4143 @item @emph{Example}:
4148 print *, floor(x) ! returns 63
4149 print *, floor(y) ! returns -64
4150 end program test_floor
4153 @item @emph{See also}:
4154 @ref{CEILING}, @ref{NINT}
4161 @section @code{FLUSH} --- Flush I/O unit(s)
4163 @cindex file operation, flush
4166 @item @emph{Description}:
4167 Flushes Fortran unit(s) currently open for output. Without the optional
4168 argument, all units are flushed, otherwise just the unit specified.
4170 @item @emph{Standard}:
4176 @item @emph{Syntax}:
4177 @code{CALL FLUSH(UNIT)}
4179 @item @emph{Arguments}:
4180 @multitable @columnfractions .15 .70
4181 @item @var{UNIT} @tab (Optional) The type shall be @code{INTEGER}.
4185 Beginning with the Fortran 2003 standard, there is a @code{FLUSH}
4186 statement that should be preferred over the @code{FLUSH} intrinsic.
4188 The @code{FLUSH} intrinsic and the Fortran 2003 @code{FLUSH} statement
4189 have identical effect: they flush the runtime library's I/O buffer so
4190 that the data becomes visible to other processes. This does not guarantee
4191 that the data is committed to disk.
4193 On POSIX systems, you can request that all data is transferred to the
4194 storage device by calling the @code{fsync} function, with the POSIX file
4195 descriptor of the I/O unit as argument (retrieved with GNU intrinsic
4196 @code{FNUM}). The following example shows how:
4199 ! Declare the interface for POSIX fsync function
4201 function fsync (fd) bind(c,name="fsync")
4202 use iso_c_binding, only: c_int
4203 integer(c_int), value :: fd
4204 integer(c_int) :: fsync
4208 ! Variable declaration
4212 open (10,file="foo")
4215 ! Perform I/O on unit 10
4220 ret = fsync(fnum(10))
4222 ! Handle possible error
4223 if (ret /= 0) stop "Error calling FSYNC"
4231 @section @code{FNUM} --- File number function
4233 @cindex file operation, file number
4236 @item @emph{Description}:
4237 @code{FNUM(UNIT)} returns the POSIX file descriptor number corresponding to the
4238 open Fortran I/O unit @code{UNIT}.
4240 @item @emph{Standard}:
4246 @item @emph{Syntax}:
4247 @code{RESULT = FNUM(UNIT)}
4249 @item @emph{Arguments}:
4250 @multitable @columnfractions .15 .70
4251 @item @var{UNIT} @tab The type shall be @code{INTEGER}.
4254 @item @emph{Return value}:
4255 The return value is of type @code{INTEGER}
4257 @item @emph{Example}:
4261 open (unit=10, status = "scratch")
4265 end program test_fnum
4272 @section @code{FPUT} --- Write a single character in stream mode to stdout
4274 @cindex write character, stream mode
4275 @cindex stream mode, write character
4276 @cindex file operation, write character
4279 @item @emph{Description}:
4280 Write a single character in stream mode to stdout by bypassing normal
4281 formatted output. Stream I/O should not be mixed with normal record-oriented
4282 (formatted or unformatted) I/O on the same unit; the results are unpredictable.
4284 This intrinsic is provided in both subroutine and function forms; however,
4285 only one form can be used in any given program unit.
4287 Note that the @code{FGET} intrinsic is provided for backwards compatibility with
4288 @command{g77}. GNU Fortran provides the Fortran 2003 Stream facility.
4289 Programmers should consider the use of new stream IO feature in new code
4290 for future portability. See also @ref{Fortran 2003 status}.
4292 @item @emph{Standard}:
4296 Subroutine, function
4298 @item @emph{Syntax}:
4299 @code{CALL FPUT(C [, STATUS])}
4301 @item @emph{Arguments}:
4302 @multitable @columnfractions .15 .70
4303 @item @var{C} @tab The type shall be @code{CHARACTER} and of default
4305 @item @var{STATUS} @tab (Optional) status flag of type @code{INTEGER}.
4306 Returns 0 on success, -1 on end-of-file and a system specific positive
4307 error code otherwise.
4310 @item @emph{Example}:
4313 CHARACTER(len=10) :: str = "gfortran"
4315 DO i = 1, len_trim(str)
4321 @item @emph{See also}:
4322 @ref{FPUTC}, @ref{FGET}, @ref{FGETC}
4328 @section @code{FPUTC} --- Write a single character in stream mode
4330 @cindex write character, stream mode
4331 @cindex stream mode, write character
4332 @cindex file operation, write character
4335 @item @emph{Description}:
4336 Write a single character in stream mode by bypassing normal formatted
4337 output. Stream I/O should not be mixed with normal record-oriented
4338 (formatted or unformatted) I/O on the same unit; the results are unpredictable.
4340 This intrinsic is provided in both subroutine and function forms; however,
4341 only one form can be used in any given program unit.
4343 Note that the @code{FGET} intrinsic is provided for backwards compatibility with
4344 @command{g77}. GNU Fortran provides the Fortran 2003 Stream facility.
4345 Programmers should consider the use of new stream IO feature in new code
4346 for future portability. See also @ref{Fortran 2003 status}.
4348 @item @emph{Standard}:
4352 Subroutine, function
4354 @item @emph{Syntax}:
4355 @code{CALL FPUTC(UNIT, C [, STATUS])}
4357 @item @emph{Arguments}:
4358 @multitable @columnfractions .15 .70
4359 @item @var{UNIT} @tab The type shall be @code{INTEGER}.
4360 @item @var{C} @tab The type shall be @code{CHARACTER} and of default
4362 @item @var{STATUS} @tab (Optional) status flag of type @code{INTEGER}.
4363 Returns 0 on success, -1 on end-of-file and a system specific positive
4364 error code otherwise.
4367 @item @emph{Example}:
4370 CHARACTER(len=10) :: str = "gfortran"
4371 INTEGER :: fd = 42, i
4373 OPEN(UNIT = fd, FILE = "out", ACTION = "WRITE", STATUS="NEW")
4374 DO i = 1, len_trim(str)
4375 CALL fputc(fd, str(i:i))
4381 @item @emph{See also}:
4382 @ref{FPUT}, @ref{FGET}, @ref{FGETC}
4388 @section @code{FRACTION} --- Fractional part of the model representation
4390 @cindex real number, fraction
4391 @cindex floating point, fraction
4394 @item @emph{Description}:
4395 @code{FRACTION(X)} returns the fractional part of the model
4396 representation of @code{X}.
4398 @item @emph{Standard}:
4399 Fortran 95 and later
4404 @item @emph{Syntax}:
4405 @code{Y = FRACTION(X)}
4407 @item @emph{Arguments}:
4408 @multitable @columnfractions .15 .70
4409 @item @var{X} @tab The type of the argument shall be a @code{REAL}.
4412 @item @emph{Return value}:
4413 The return value is of the same type and kind as the argument.
4414 The fractional part of the model representation of @code{X} is returned;
4415 it is @code{X * RADIX(X)**(-EXPONENT(X))}.
4417 @item @emph{Example}:
4419 program test_fraction
4422 print *, fraction(x), x * radix(x)**(-exponent(x))
4423 end program test_fraction
4431 @section @code{FREE} --- Frees memory
4433 @cindex pointer, cray
4436 @item @emph{Description}:
4437 Frees memory previously allocated by @code{MALLOC()}. The @code{FREE}
4438 intrinsic is an extension intended to be used with Cray pointers, and is
4439 provided in GNU Fortran to allow user to compile legacy code. For
4440 new code using Fortran 95 pointers, the memory de-allocation intrinsic is
4443 @item @emph{Standard}:
4449 @item @emph{Syntax}:
4450 @code{CALL FREE(PTR)}
4452 @item @emph{Arguments}:
4453 @multitable @columnfractions .15 .70
4454 @item @var{PTR} @tab The type shall be @code{INTEGER}. It represents the
4455 location of the memory that should be de-allocated.
4458 @item @emph{Return value}:
4461 @item @emph{Example}:
4462 See @code{MALLOC} for an example.
4464 @item @emph{See also}:
4471 @section @code{FSEEK} --- Low level file positioning subroutine
4473 @cindex file operation, seek
4474 @cindex file operation, position
4477 @item @emph{Description}:
4478 Moves @var{UNIT} to the specified @var{OFFSET}. If @var{WHENCE}
4479 is set to 0, the @var{OFFSET} is taken as an absolute value @code{SEEK_SET},
4480 if set to 1, @var{OFFSET} is taken to be relative to the current position
4481 @code{SEEK_CUR}, and if set to 2 relative to the end of the file @code{SEEK_END}.
4482 On error, @var{STATUS} is set to a nonzero value. If @var{STATUS} the seek
4485 This intrinsic routine is not fully backwards compatible with @command{g77}.
4486 In @command{g77}, the @code{FSEEK} takes a statement label instead of a
4487 @var{STATUS} variable. If FSEEK is used in old code, change
4489 CALL FSEEK(UNIT, OFFSET, WHENCE, *label)
4494 CALL FSEEK(UNIT, OFFSET, WHENCE, status)
4495 IF (status /= 0) GOTO label
4498 Please note that GNU Fortran provides the Fortran 2003 Stream facility.
4499 Programmers should consider the use of new stream IO feature in new code
4500 for future portability. See also @ref{Fortran 2003 status}.
4502 @item @emph{Standard}:
4508 @item @emph{Syntax}:
4509 @code{CALL FSEEK(UNIT, OFFSET, WHENCE[, STATUS])}
4511 @item @emph{Arguments}:
4512 @multitable @columnfractions .15 .70
4513 @item @var{UNIT} @tab Shall be a scalar of type @code{INTEGER}.
4514 @item @var{OFFSET} @tab Shall be a scalar of type @code{INTEGER}.
4515 @item @var{WHENCE} @tab Shall be a scalar of type @code{INTEGER}.
4516 Its value shall be either 0, 1 or 2.
4517 @item @var{STATUS} @tab (Optional) shall be a scalar of type
4521 @item @emph{Example}:
4524 INTEGER, PARAMETER :: SEEK_SET = 0, SEEK_CUR = 1, SEEK_END = 2
4525 INTEGER :: fd, offset, ierr
4531 OPEN(UNIT=fd, FILE="fseek.test")
4532 CALL FSEEK(fd, offset, SEEK_SET, ierr) ! move to OFFSET
4533 print *, FTELL(fd), ierr
4535 CALL FSEEK(fd, 0, SEEK_END, ierr) ! move to end
4536 print *, FTELL(fd), ierr
4538 CALL FSEEK(fd, 0, SEEK_SET, ierr) ! move to beginning
4539 print *, FTELL(fd), ierr
4545 @item @emph{See also}:
4552 @section @code{FSTAT} --- Get file status
4554 @cindex file system, file status
4557 @item @emph{Description}:
4558 @code{FSTAT} is identical to @ref{STAT}, except that information about an
4559 already opened file is obtained.
4561 The elements in @code{VALUES} are the same as described by @ref{STAT}.
4563 This intrinsic is provided in both subroutine and function forms; however,
4564 only one form can be used in any given program unit.
4566 @item @emph{Standard}:
4570 Subroutine, function
4572 @item @emph{Syntax}:
4573 @code{CALL FSTAT(UNIT, VALUES [, STATUS])}
4575 @item @emph{Arguments}:
4576 @multitable @columnfractions .15 .70
4577 @item @var{UNIT} @tab An open I/O unit number of type @code{INTEGER}.
4578 @item @var{VALUES} @tab The type shall be @code{INTEGER(4), DIMENSION(13)}.
4579 @item @var{STATUS} @tab (Optional) status flag of type @code{INTEGER(4)}. Returns 0
4580 on success and a system specific error code otherwise.
4583 @item @emph{Example}:
4584 See @ref{STAT} for an example.
4586 @item @emph{See also}:
4587 To stat a link: @ref{LSTAT}, to stat a file: @ref{STAT}
4593 @section @code{FTELL} --- Current stream position
4595 @cindex file operation, position
4598 @item @emph{Description}:
4599 Retrieves the current position within an open file.
4601 This intrinsic is provided in both subroutine and function forms; however,
4602 only one form can be used in any given program unit.
4604 @item @emph{Standard}:
4608 Subroutine, function
4610 @item @emph{Syntax}:
4611 @multitable @columnfractions .80
4612 @item @code{CALL FTELL(UNIT, OFFSET)}
4613 @item @code{OFFSET = FTELL(UNIT)}
4616 @item @emph{Arguments}:
4617 @multitable @columnfractions .15 .70
4618 @item @var{OFFSET} @tab Shall of type @code{INTEGER}.
4619 @item @var{UNIT} @tab Shall of type @code{INTEGER}.
4622 @item @emph{Return value}:
4623 In either syntax, @var{OFFSET} is set to the current offset of unit
4624 number @var{UNIT}, or to @math{-1} if the unit is not currently open.
4626 @item @emph{Example}:
4630 OPEN(10, FILE="temp.dat")
4636 @item @emph{See also}:
4643 @section @code{GAMMA} --- Gamma function
4646 @cindex Gamma function
4647 @cindex Factorial function
4650 @item @emph{Description}:
4651 @code{GAMMA(X)} computes Gamma (@math{\Gamma}) of @var{X}. For positive,
4652 integer values of @var{X} the Gamma function simplifies to the factorial
4653 function @math{\Gamma(x)=(x-1)!}.
4657 \Gamma(x) = \int_0^\infty t^{x-1}{\rm e}^{-t}\,{\rm d}t
4661 @item @emph{Standard}:
4662 Fortran 2008 and later
4667 @item @emph{Syntax}:
4670 @item @emph{Arguments}:
4671 @multitable @columnfractions .15 .70
4672 @item @var{X} @tab Shall be of type @code{REAL} and neither zero
4673 nor a negative integer.
4676 @item @emph{Return value}:
4677 The return value is of type @code{REAL} of the same kind as @var{X}.
4679 @item @emph{Example}:
4683 x = gamma(x) ! returns 1.0
4684 end program test_gamma
4687 @item @emph{Specific names}:
4688 @multitable @columnfractions .20 .20 .20 .25
4689 @item Name @tab Argument @tab Return type @tab Standard
4690 @item @code{GAMMA(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab GNU Extension
4691 @item @code{DGAMMA(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU Extension
4694 @item @emph{See also}:
4695 Logarithm of the Gamma function: @ref{LOG_GAMMA}
4702 @section @code{GERROR} --- Get last system error message
4704 @cindex system, error handling
4707 @item @emph{Description}:
4708 Returns the system error message corresponding to the last system error.
4709 This resembles the functionality of @code{strerror(3)} in C.
4711 @item @emph{Standard}:
4717 @item @emph{Syntax}:
4718 @code{CALL GERROR(RESULT)}
4720 @item @emph{Arguments}:
4721 @multitable @columnfractions .15 .70
4722 @item @var{RESULT} @tab Shall of type @code{CHARACTER} and of default
4725 @item @emph{Example}:
4728 CHARACTER(len=100) :: msg
4734 @item @emph{See also}:
4735 @ref{IERRNO}, @ref{PERROR}
4741 @section @code{GETARG} --- Get command line arguments
4743 @cindex command-line arguments
4744 @cindex arguments, to program
4747 @item @emph{Description}:
4748 Retrieve the @var{POS}-th argument that was passed on the
4749 command line when the containing program was invoked.
4751 This intrinsic routine is provided for backwards compatibility with
4752 GNU Fortran 77. In new code, programmers should consider the use of
4753 the @ref{GET_COMMAND_ARGUMENT} intrinsic defined by the Fortran 2003
4756 @item @emph{Standard}:
4762 @item @emph{Syntax}:
4763 @code{CALL GETARG(POS, VALUE)}
4765 @item @emph{Arguments}:
4766 @multitable @columnfractions .15 .70
4767 @item @var{POS} @tab Shall be of type @code{INTEGER} and not wider than
4768 the default integer kind; @math{@var{POS} \geq 0}
4769 @item @var{VALUE} @tab Shall be of type @code{CHARACTER} and of default
4771 @item @var{VALUE} @tab Shall be of type @code{CHARACTER}.
4774 @item @emph{Return value}:
4775 After @code{GETARG} returns, the @var{VALUE} argument holds the
4776 @var{POS}th command line argument. If @var{VALUE} can not hold the
4777 argument, it is truncated to fit the length of @var{VALUE}. If there are
4778 less than @var{POS} arguments specified at the command line, @var{VALUE}
4779 will be filled with blanks. If @math{@var{POS} = 0}, @var{VALUE} is set
4780 to the name of the program (on systems that support this feature).
4782 @item @emph{Example}:
4786 CHARACTER(len=32) :: arg
4795 @item @emph{See also}:
4796 GNU Fortran 77 compatibility function: @ref{IARGC}
4798 Fortran 2003 functions and subroutines: @ref{GET_COMMAND},
4799 @ref{GET_COMMAND_ARGUMENT}, @ref{COMMAND_ARGUMENT_COUNT}
4805 @section @code{GET_COMMAND} --- Get the entire command line
4806 @fnindex GET_COMMAND
4807 @cindex command-line arguments
4808 @cindex arguments, to program
4811 @item @emph{Description}:
4812 Retrieve the entire command line that was used to invoke the program.
4814 @item @emph{Standard}:
4815 Fortran 2003 and later
4820 @item @emph{Syntax}:
4821 @code{CALL GET_COMMAND([COMMAND, LENGTH, STATUS])}
4823 @item @emph{Arguments}:
4824 @multitable @columnfractions .15 .70
4825 @item @var{COMMAND} @tab (Optional) shall be of type @code{CHARACTER} and
4827 @item @var{LENGTH} @tab (Optional) Shall be of type @code{INTEGER} and of
4829 @item @var{STATUS} @tab (Optional) Shall be of type @code{INTEGER} and of
4833 @item @emph{Return value}:
4834 If @var{COMMAND} is present, stores the entire command line that was used
4835 to invoke the program in @var{COMMAND}. If @var{LENGTH} is present, it is
4836 assigned the length of the command line. If @var{STATUS} is present, it
4837 is assigned 0 upon success of the command, -1 if @var{COMMAND} is too
4838 short to store the command line, or a positive value in case of an error.
4840 @item @emph{Example}:
4842 PROGRAM test_get_command
4843 CHARACTER(len=255) :: cmd
4844 CALL get_command(cmd)
4845 WRITE (*,*) TRIM(cmd)
4849 @item @emph{See also}:
4850 @ref{GET_COMMAND_ARGUMENT}, @ref{COMMAND_ARGUMENT_COUNT}
4855 @node GET_COMMAND_ARGUMENT
4856 @section @code{GET_COMMAND_ARGUMENT} --- Get command line arguments
4857 @fnindex GET_COMMAND_ARGUMENT
4858 @cindex command-line arguments
4859 @cindex arguments, to program
4862 @item @emph{Description}:
4863 Retrieve the @var{NUMBER}-th argument that was passed on the
4864 command line when the containing program was invoked.
4866 @item @emph{Standard}:
4867 Fortran 2003 and later
4872 @item @emph{Syntax}:
4873 @code{CALL GET_COMMAND_ARGUMENT(NUMBER [, VALUE, LENGTH, STATUS])}
4875 @item @emph{Arguments}:
4876 @multitable @columnfractions .15 .70
4877 @item @var{NUMBER} @tab Shall be a scalar of type @code{INTEGER} and of
4878 default kind, @math{@var{NUMBER} \geq 0}
4879 @item @var{VALUE} @tab Shall be a scalar of type @code{CHARACTER}
4880 and of default kind.
4881 @item @var{LENGTH} @tab (Option) Shall be a scalar of type @code{INTEGER}
4882 and of default kind.
4883 @item @var{STATUS} @tab (Option) Shall be a scalar of type @code{INTEGER}
4884 and of default kind.
4887 @item @emph{Return value}:
4888 After @code{GET_COMMAND_ARGUMENT} returns, the @var{VALUE} argument holds the
4889 @var{NUMBER}-th command line argument. If @var{VALUE} can not hold the argument, it is
4890 truncated to fit the length of @var{VALUE}. If there are less than @var{NUMBER}
4891 arguments specified at the command line, @var{VALUE} will be filled with blanks.
4892 If @math{@var{NUMBER} = 0}, @var{VALUE} is set to the name of the program (on
4893 systems that support this feature). The @var{LENGTH} argument contains the
4894 length of the @var{NUMBER}-th command line argument. If the argument retrieval
4895 fails, @var{STATUS} is a positive number; if @var{VALUE} contains a truncated
4896 command line argument, @var{STATUS} is -1; and otherwise the @var{STATUS} is
4899 @item @emph{Example}:
4901 PROGRAM test_get_command_argument
4903 CHARACTER(len=32) :: arg
4907 CALL get_command_argument(i, arg)
4908 IF (LEN_TRIM(arg) == 0) EXIT
4910 WRITE (*,*) TRIM(arg)
4916 @item @emph{See also}:
4917 @ref{GET_COMMAND}, @ref{COMMAND_ARGUMENT_COUNT}
4923 @section @code{GETCWD} --- Get current working directory
4925 @cindex system, working directory
4928 @item @emph{Description}:
4929 Get current working directory.
4931 This intrinsic is provided in both subroutine and function forms; however,
4932 only one form can be used in any given program unit.
4934 @item @emph{Standard}:
4938 Subroutine, function
4940 @item @emph{Syntax}:
4941 @code{CALL GETCWD(C [, STATUS])}
4943 @item @emph{Arguments}:
4944 @multitable @columnfractions .15 .70
4945 @item @var{C} @tab The type shall be @code{CHARACTER} and of default kind.
4946 @item @var{STATUS} @tab (Optional) status flag. Returns 0 on success,
4947 a system specific and nonzero error code otherwise.
4950 @item @emph{Example}:
4953 CHARACTER(len=255) :: cwd
4955 WRITE(*,*) TRIM(cwd)
4959 @item @emph{See also}:
4966 @section @code{GETENV} --- Get an environmental variable
4968 @cindex environment variable
4971 @item @emph{Description}:
4972 Get the @var{VALUE} of the environmental variable @var{NAME}.
4974 This intrinsic routine is provided for backwards compatibility with
4975 GNU Fortran 77. In new code, programmers should consider the use of
4976 the @ref{GET_ENVIRONMENT_VARIABLE} intrinsic defined by the Fortran
4979 @item @emph{Standard}:
4985 @item @emph{Syntax}:
4986 @code{CALL GETENV(NAME, VALUE)}
4988 @item @emph{Arguments}:
4989 @multitable @columnfractions .15 .70
4990 @item @var{NAME} @tab Shall be of type @code{CHARACTER} and of default kind.
4991 @item @var{VALUE} @tab Shall be of type @code{CHARACTER} and of default kind.
4994 @item @emph{Return value}:
4995 Stores the value of @var{NAME} in @var{VALUE}. If @var{VALUE} is
4996 not large enough to hold the data, it is truncated. If @var{NAME}
4997 is not set, @var{VALUE} will be filled with blanks.
4999 @item @emph{Example}:
5002 CHARACTER(len=255) :: homedir
5003 CALL getenv("HOME", homedir)
5004 WRITE (*,*) TRIM(homedir)
5008 @item @emph{See also}:
5009 @ref{GET_ENVIRONMENT_VARIABLE}
5014 @node GET_ENVIRONMENT_VARIABLE
5015 @section @code{GET_ENVIRONMENT_VARIABLE} --- Get an environmental variable
5016 @fnindex GET_ENVIRONMENT_VARIABLE
5017 @cindex environment variable
5020 @item @emph{Description}:
5021 Get the @var{VALUE} of the environmental variable @var{NAME}.
5023 @item @emph{Standard}:
5024 Fortran 2003 and later
5029 @item @emph{Syntax}:
5030 @code{CALL GET_ENVIRONMENT_VARIABLE(NAME[, VALUE, LENGTH, STATUS, TRIM_NAME)}
5032 @item @emph{Arguments}:
5033 @multitable @columnfractions .15 .70
5034 @item @var{NAME} @tab Shall be a scalar of type @code{CHARACTER}
5035 and of default kind.
5036 @item @var{VALUE} @tab Shall be a scalar of type @code{CHARACTER}
5037 and of default kind.
5038 @item @var{LENGTH} @tab Shall be a scalar of type @code{INTEGER}
5039 and of default kind.
5040 @item @var{STATUS} @tab Shall be a scalar of type @code{INTEGER}
5041 and of default kind.
5042 @item @var{TRIM_NAME} @tab Shall be a scalar of type @code{LOGICAL}
5043 and of default kind.
5046 @item @emph{Return value}:
5047 Stores the value of @var{NAME} in @var{VALUE}. If @var{VALUE} is
5048 not large enough to hold the data, it is truncated. If @var{NAME}
5049 is not set, @var{VALUE} will be filled with blanks. Argument @var{LENGTH}
5050 contains the length needed for storing the environment variable @var{NAME}
5051 or zero if it is not present. @var{STATUS} is -1 if @var{VALUE} is present
5052 but too short for the environment variable; it is 1 if the environment
5053 variable does not exist and 2 if the processor does not support environment
5054 variables; in all other cases @var{STATUS} is zero. If @var{TRIM_NAME} is
5055 present with the value @code{.FALSE.}, the trailing blanks in @var{NAME}
5056 are significant; otherwise they are not part of the environment variable
5059 @item @emph{Example}:
5062 CHARACTER(len=255) :: homedir
5063 CALL get_environment_variable("HOME", homedir)
5064 WRITE (*,*) TRIM(homedir)
5072 @section @code{GETGID} --- Group ID function
5074 @cindex system, group id
5077 @item @emph{Description}:
5078 Returns the numerical group ID of the current process.
5080 @item @emph{Standard}:
5086 @item @emph{Syntax}:
5087 @code{RESULT = GETGID()}
5089 @item @emph{Return value}:
5090 The return value of @code{GETGID} is an @code{INTEGER} of the default
5094 @item @emph{Example}:
5095 See @code{GETPID} for an example.
5097 @item @emph{See also}:
5098 @ref{GETPID}, @ref{GETUID}
5104 @section @code{GETLOG} --- Get login name
5106 @cindex system, login name
5110 @item @emph{Description}:
5111 Gets the username under which the program is running.
5113 @item @emph{Standard}:
5119 @item @emph{Syntax}:
5120 @code{CALL GETLOG(C)}
5122 @item @emph{Arguments}:
5123 @multitable @columnfractions .15 .70
5124 @item @var{C} @tab Shall be of type @code{CHARACTER} and of default kind.
5127 @item @emph{Return value}:
5128 Stores the current user name in @var{LOGIN}. (On systems where POSIX
5129 functions @code{geteuid} and @code{getpwuid} are not available, and
5130 the @code{getlogin} function is not implemented either, this will
5131 return a blank string.)
5133 @item @emph{Example}:
5136 CHARACTER(32) :: login
5142 @item @emph{See also}:
5149 @section @code{GETPID} --- Process ID function
5151 @cindex system, process id
5155 @item @emph{Description}:
5156 Returns the numerical process identifier of the current process.
5158 @item @emph{Standard}:
5164 @item @emph{Syntax}:
5165 @code{RESULT = GETPID()}
5167 @item @emph{Return value}:
5168 The return value of @code{GETPID} is an @code{INTEGER} of the default
5172 @item @emph{Example}:
5175 print *, "The current process ID is ", getpid()
5176 print *, "Your numerical user ID is ", getuid()
5177 print *, "Your numerical group ID is ", getgid()
5181 @item @emph{See also}:
5182 @ref{GETGID}, @ref{GETUID}
5188 @section @code{GETUID} --- User ID function
5190 @cindex system, user id
5194 @item @emph{Description}:
5195 Returns the numerical user ID of the current process.
5197 @item @emph{Standard}:
5203 @item @emph{Syntax}:
5204 @code{RESULT = GETUID()}
5206 @item @emph{Return value}:
5207 The return value of @code{GETUID} is an @code{INTEGER} of the default
5211 @item @emph{Example}:
5212 See @code{GETPID} for an example.
5214 @item @emph{See also}:
5215 @ref{GETPID}, @ref{GETLOG}
5221 @section @code{GMTIME} --- Convert time to GMT info
5223 @cindex time, conversion to GMT info
5226 @item @emph{Description}:
5227 Given a system time value @var{TIME} (as provided by the @code{TIME8()}
5228 intrinsic), fills @var{VALUES} with values extracted from it appropriate
5229 to the UTC time zone (Universal Coordinated Time, also known in some
5230 countries as GMT, Greenwich Mean Time), using @code{gmtime(3)}.
5232 @item @emph{Standard}:
5238 @item @emph{Syntax}:
5239 @code{CALL GMTIME(TIME, VALUES)}
5241 @item @emph{Arguments}:
5242 @multitable @columnfractions .15 .70
5243 @item @var{TIME} @tab An @code{INTEGER} scalar expression
5244 corresponding to a system time, with @code{INTENT(IN)}.
5245 @item @var{VALUES} @tab A default @code{INTEGER} array with 9 elements,
5246 with @code{INTENT(OUT)}.
5249 @item @emph{Return value}:
5250 The elements of @var{VALUES} are assigned as follows:
5252 @item Seconds after the minute, range 0--59 or 0--61 to allow for leap
5254 @item Minutes after the hour, range 0--59
5255 @item Hours past midnight, range 0--23
5256 @item Day of month, range 0--31
5257 @item Number of months since January, range 0--12
5258 @item Years since 1900
5259 @item Number of days since Sunday, range 0--6
5260 @item Days since January 1
5261 @item Daylight savings indicator: positive if daylight savings is in
5262 effect, zero if not, and negative if the information is not available.
5265 @item @emph{See also}:
5266 @ref{CTIME}, @ref{LTIME}, @ref{TIME}, @ref{TIME8}
5273 @section @code{HOSTNM} --- Get system host name
5275 @cindex system, host name
5278 @item @emph{Description}:
5279 Retrieves the host name of the system on which the program is running.
5281 This intrinsic is provided in both subroutine and function forms; however,
5282 only one form can be used in any given program unit.
5284 @item @emph{Standard}:
5288 Subroutine, function
5290 @item @emph{Syntax}:
5291 @multitable @columnfractions .80
5292 @item @code{CALL HOSTNM(C [, STATUS])}
5293 @item @code{STATUS = HOSTNM(NAME)}
5296 @item @emph{Arguments}:
5297 @multitable @columnfractions .15 .70
5298 @item @var{C} @tab Shall of type @code{CHARACTER} and of default kind.
5299 @item @var{STATUS} @tab (Optional) status flag of type @code{INTEGER}.
5300 Returns 0 on success, or a system specific error code otherwise.
5303 @item @emph{Return value}:
5304 In either syntax, @var{NAME} is set to the current hostname if it can
5305 be obtained, or to a blank string otherwise.
5312 @section @code{HUGE} --- Largest number of a kind
5314 @cindex limits, largest number
5315 @cindex model representation, largest number
5318 @item @emph{Description}:
5319 @code{HUGE(X)} returns the largest number that is not an infinity in
5320 the model of the type of @code{X}.
5322 @item @emph{Standard}:
5323 Fortran 95 and later
5328 @item @emph{Syntax}:
5329 @code{RESULT = HUGE(X)}
5331 @item @emph{Arguments}:
5332 @multitable @columnfractions .15 .70
5333 @item @var{X} @tab Shall be of type @code{REAL} or @code{INTEGER}.
5336 @item @emph{Return value}:
5337 The return value is of the same type and kind as @var{X}
5339 @item @emph{Example}:
5341 program test_huge_tiny
5342 print *, huge(0), huge(0.0), huge(0.0d0)
5343 print *, tiny(0.0), tiny(0.0d0)
5344 end program test_huge_tiny
5351 @section @code{HYPOT} --- Euclidean distance function
5353 @cindex Euclidean distance
5356 @item @emph{Description}:
5357 @code{HYPOT(X,Y)} is the Euclidean distance function. It is equal to
5358 @math{\sqrt{X^2 + Y^2}}, without undue underflow or overflow.
5360 @item @emph{Standard}:
5361 Fortran 2008 and later
5366 @item @emph{Syntax}:
5367 @code{RESULT = HYPOT(X, Y)}
5369 @item @emph{Arguments}:
5370 @multitable @columnfractions .15 .70
5371 @item @var{X} @tab The type shall be @code{REAL}.
5372 @item @var{Y} @tab The type and kind type parameter shall be the same as
5376 @item @emph{Return value}:
5377 The return value has the same type and kind type parameter as @var{X}.
5379 @item @emph{Example}:
5382 real(4) :: x = 1.e0_4, y = 0.5e0_4
5384 end program test_hypot
5391 @section @code{IACHAR} --- Code in @acronym{ASCII} collating sequence
5393 @cindex @acronym{ASCII} collating sequence
5394 @cindex collating sequence, @acronym{ASCII}
5395 @cindex conversion, to integer
5398 @item @emph{Description}:
5399 @code{IACHAR(C)} returns the code for the @acronym{ASCII} character
5400 in the first character position of @code{C}.
5402 @item @emph{Standard}:
5403 Fortran 95 and later, with @var{KIND} argument Fortran 2003 and later
5408 @item @emph{Syntax}:
5409 @code{RESULT = IACHAR(C [, KIND])}
5411 @item @emph{Arguments}:
5412 @multitable @columnfractions .15 .70
5413 @item @var{C} @tab Shall be a scalar @code{CHARACTER}, with @code{INTENT(IN)}
5414 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
5415 expression indicating the kind parameter of the result.
5418 @item @emph{Return value}:
5419 The return value is of type @code{INTEGER} and of kind @var{KIND}. If
5420 @var{KIND} is absent, the return value is of default integer kind.
5422 @item @emph{Example}:
5427 end program test_iachar
5431 See @ref{ICHAR} for a discussion of converting between numerical values
5432 and formatted string representations.
5434 @item @emph{See also}:
5435 @ref{ACHAR}, @ref{CHAR}, @ref{ICHAR}
5442 @section @code{IAND} --- Bitwise logical and
5444 @cindex bitwise logical and
5445 @cindex logical and, bitwise
5448 @item @emph{Description}:
5449 Bitwise logical @code{AND}.
5451 @item @emph{Standard}:
5452 Fortran 95 and later
5457 @item @emph{Syntax}:
5458 @code{RESULT = IAND(I, J)}
5460 @item @emph{Arguments}:
5461 @multitable @columnfractions .15 .70
5462 @item @var{I} @tab The type shall be @code{INTEGER}.
5463 @item @var{J} @tab The type shall be @code{INTEGER}, of the same
5464 kind as @var{I}. (As a GNU extension, different kinds are also
5468 @item @emph{Return value}:
5469 The return type is @code{INTEGER}, of the same kind as the
5470 arguments. (If the argument kinds differ, it is of the same kind as
5471 the larger argument.)
5473 @item @emph{Example}:
5477 DATA a / Z'F' /, b / Z'3' /
5478 WRITE (*,*) IAND(a, b)
5482 @item @emph{See also}:
5483 @ref{IOR}, @ref{IEOR}, @ref{IBITS}, @ref{IBSET}, @ref{IBCLR}, @ref{NOT}
5490 @section @code{IARGC} --- Get the number of command line arguments
5492 @cindex command-line arguments
5493 @cindex command-line arguments, number of
5494 @cindex arguments, to program
5497 @item @emph{Description}:
5498 @code{IARGC()} returns the number of arguments passed on the
5499 command line when the containing program was invoked.
5501 This intrinsic routine is provided for backwards compatibility with
5502 GNU Fortran 77. In new code, programmers should consider the use of
5503 the @ref{COMMAND_ARGUMENT_COUNT} intrinsic defined by the Fortran 2003
5506 @item @emph{Standard}:
5512 @item @emph{Syntax}:
5513 @code{RESULT = IARGC()}
5515 @item @emph{Arguments}:
5518 @item @emph{Return value}:
5519 The number of command line arguments, type @code{INTEGER(4)}.
5521 @item @emph{Example}:
5524 @item @emph{See also}:
5525 GNU Fortran 77 compatibility subroutine: @ref{GETARG}
5527 Fortran 2003 functions and subroutines: @ref{GET_COMMAND},
5528 @ref{GET_COMMAND_ARGUMENT}, @ref{COMMAND_ARGUMENT_COUNT}
5534 @section @code{IBCLR} --- Clear bit
5540 @item @emph{Description}:
5541 @code{IBCLR} returns the value of @var{I} with the bit at position
5542 @var{POS} set to zero.
5544 @item @emph{Standard}:
5545 Fortran 95 and later
5550 @item @emph{Syntax}:
5551 @code{RESULT = IBCLR(I, POS)}
5553 @item @emph{Arguments}:
5554 @multitable @columnfractions .15 .70
5555 @item @var{I} @tab The type shall be @code{INTEGER}.
5556 @item @var{POS} @tab The type shall be @code{INTEGER}.
5559 @item @emph{Return value}:
5560 The return value is of type @code{INTEGER} and of the same kind as
5563 @item @emph{See also}:
5564 @ref{IBITS}, @ref{IBSET}, @ref{IAND}, @ref{IOR}, @ref{IEOR}, @ref{MVBITS}
5571 @section @code{IBITS} --- Bit extraction
5574 @cindex bits, extract
5577 @item @emph{Description}:
5578 @code{IBITS} extracts a field of length @var{LEN} from @var{I},
5579 starting from bit position @var{POS} and extending left for @var{LEN}
5580 bits. The result is right-justified and the remaining bits are
5581 zeroed. The value of @code{POS+LEN} must be less than or equal to the
5582 value @code{BIT_SIZE(I)}.
5584 @item @emph{Standard}:
5585 Fortran 95 and later
5590 @item @emph{Syntax}:
5591 @code{RESULT = IBITS(I, POS, LEN)}
5593 @item @emph{Arguments}:
5594 @multitable @columnfractions .15 .70
5595 @item @var{I} @tab The type shall be @code{INTEGER}.
5596 @item @var{POS} @tab The type shall be @code{INTEGER}.
5597 @item @var{LEN} @tab The type shall be @code{INTEGER}.
5600 @item @emph{Return value}:
5601 The return value is of type @code{INTEGER} and of the same kind as
5604 @item @emph{See also}:
5605 @ref{BIT_SIZE}, @ref{IBCLR}, @ref{IBSET}, @ref{IAND}, @ref{IOR}, @ref{IEOR}
5611 @section @code{IBSET} --- Set bit
5616 @item @emph{Description}:
5617 @code{IBSET} returns the value of @var{I} with the bit at position
5618 @var{POS} set to one.
5620 @item @emph{Standard}:
5621 Fortran 95 and later
5626 @item @emph{Syntax}:
5627 @code{RESULT = IBSET(I, POS)}
5629 @item @emph{Arguments}:
5630 @multitable @columnfractions .15 .70
5631 @item @var{I} @tab The type shall be @code{INTEGER}.
5632 @item @var{POS} @tab The type shall be @code{INTEGER}.
5635 @item @emph{Return value}:
5636 The return value is of type @code{INTEGER} and of the same kind as
5639 @item @emph{See also}:
5640 @ref{IBCLR}, @ref{IBITS}, @ref{IAND}, @ref{IOR}, @ref{IEOR}, @ref{MVBITS}
5647 @section @code{ICHAR} --- Character-to-integer conversion function
5649 @cindex conversion, to integer
5652 @item @emph{Description}:
5653 @code{ICHAR(C)} returns the code for the character in the first character
5654 position of @code{C} in the system's native character set.
5655 The correspondence between characters and their codes is not necessarily
5656 the same across different GNU Fortran implementations.
5658 @item @emph{Standard}:
5659 Fortan 95 and later, with @var{KIND} argument Fortran 2003 and later
5664 @item @emph{Syntax}:
5665 @code{RESULT = ICHAR(C [, KIND])}
5667 @item @emph{Arguments}:
5668 @multitable @columnfractions .15 .70
5669 @item @var{C} @tab Shall be a scalar @code{CHARACTER}, with @code{INTENT(IN)}
5670 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
5671 expression indicating the kind parameter of the result.
5674 @item @emph{Return value}:
5675 The return value is of type @code{INTEGER} and of kind @var{KIND}. If
5676 @var{KIND} is absent, the return value is of default integer kind.
5678 @item @emph{Example}:
5683 end program test_ichar
5686 @item @emph{Specific names}:
5687 @multitable @columnfractions .20 .20 .20 .25
5688 @item Name @tab Argument @tab Return type @tab Standard
5689 @item @code{ICHAR(C)} @tab @code{CHARACTER C} @tab @code{INTEGER(4)} @tab Fortran 77 and later
5693 No intrinsic exists to convert between a numeric value and a formatted
5694 character string representation -- for instance, given the
5695 @code{CHARACTER} value @code{'154'}, obtaining an @code{INTEGER} or
5696 @code{REAL} value with the value 154, or vice versa. Instead, this
5697 functionality is provided by internal-file I/O, as in the following
5702 character(len=10) string, string2
5705 ! Convert a string to a numeric value
5706 read (string,'(I10)') value
5709 ! Convert a value to a formatted string
5710 write (string2,'(I10)') value
5712 end program read_val
5715 @item @emph{See also}:
5716 @ref{ACHAR}, @ref{CHAR}, @ref{IACHAR}
5723 @section @code{IDATE} --- Get current local time subroutine (day/month/year)
5725 @cindex date, current
5726 @cindex current date
5729 @item @emph{Description}:
5730 @code{IDATE(VALUES)} Fills @var{VALUES} with the numerical values at the
5731 current local time. The day (in the range 1-31), month (in the range 1-12),
5732 and year appear in elements 1, 2, and 3 of @var{VALUES}, respectively.
5733 The year has four significant digits.
5735 @item @emph{Standard}:
5741 @item @emph{Syntax}:
5742 @code{CALL IDATE(VALUES)}
5744 @item @emph{Arguments}:
5745 @multitable @columnfractions .15 .70
5746 @item @var{VALUES} @tab The type shall be @code{INTEGER, DIMENSION(3)} and
5747 the kind shall be the default integer kind.
5750 @item @emph{Return value}:
5751 Does not return anything.
5753 @item @emph{Example}:
5756 integer, dimension(3) :: tarray
5761 end program test_idate
5768 @section @code{IEOR} --- Bitwise logical exclusive or
5770 @cindex bitwise logical exclusive or
5771 @cindex logical exclusive or, bitwise
5774 @item @emph{Description}:
5775 @code{IEOR} returns the bitwise boolean exclusive-OR of @var{I} and
5778 @item @emph{Standard}:
5779 Fortran 95 and later
5784 @item @emph{Syntax}:
5785 @code{RESULT = IEOR(I, J)}
5787 @item @emph{Arguments}:
5788 @multitable @columnfractions .15 .70
5789 @item @var{I} @tab The type shall be @code{INTEGER}.
5790 @item @var{J} @tab The type shall be @code{INTEGER}, of the same
5791 kind as @var{I}. (As a GNU extension, different kinds are also
5795 @item @emph{Return value}:
5796 The return type is @code{INTEGER}, of the same kind as the
5797 arguments. (If the argument kinds differ, it is of the same kind as
5798 the larger argument.)
5800 @item @emph{See also}:
5801 @ref{IOR}, @ref{IAND}, @ref{IBITS}, @ref{IBSET}, @ref{IBCLR}, @ref{NOT}
5807 @section @code{IERRNO} --- Get the last system error number
5809 @cindex system, error handling
5812 @item @emph{Description}:
5813 Returns the last system error number, as given by the C @code{errno()}
5816 @item @emph{Standard}:
5822 @item @emph{Syntax}:
5823 @code{RESULT = IERRNO()}
5825 @item @emph{Arguments}:
5828 @item @emph{Return value}:
5829 The return value is of type @code{INTEGER} and of the default integer
5832 @item @emph{See also}:
5838 @node INDEX intrinsic
5839 @section @code{INDEX} --- Position of a substring within a string
5841 @cindex substring position
5842 @cindex string, find substring
5845 @item @emph{Description}:
5846 Returns the position of the start of the first occurrence of string
5847 @var{SUBSTRING} as a substring in @var{STRING}, counting from one. If
5848 @var{SUBSTRING} is not present in @var{STRING}, zero is returned. If
5849 the @var{BACK} argument is present and true, the return value is the
5850 start of the last occurrence rather than the first.
5852 @item @emph{Standard}:
5853 Fortran 77 and later, with @var{KIND} argument Fortran 2003 and later
5858 @item @emph{Syntax}:
5859 @code{RESULT = INDEX(STRING, SUBSTRING [, BACK [, KIND]])}
5861 @item @emph{Arguments}:
5862 @multitable @columnfractions .15 .70
5863 @item @var{STRING} @tab Shall be a scalar @code{CHARACTER}, with
5865 @item @var{SUBSTRING} @tab Shall be a scalar @code{CHARACTER}, with
5867 @item @var{BACK} @tab (Optional) Shall be a scalar @code{LOGICAL}, with
5869 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
5870 expression indicating the kind parameter of the result.
5873 @item @emph{Return value}:
5874 The return value is of type @code{INTEGER} and of kind @var{KIND}. If
5875 @var{KIND} is absent, the return value is of default integer kind.
5877 @item @emph{Specific names}:
5878 @multitable @columnfractions .20 .20 .20 .25
5879 @item Name @tab Argument @tab Return type @tab Standard
5880 @item @code{INDEX(STRING, SUBSTRING)} @tab @code{CHARACTER} @tab @code{INTEGER(4)} @tab Fortran 77 and later
5883 @item @emph{See also}:
5884 @ref{SCAN}, @ref{VERIFY}
5890 @section @code{INT} --- Convert to integer type
5894 @cindex conversion, to integer
5897 @item @emph{Description}:
5898 Convert to integer type
5900 @item @emph{Standard}:
5901 Fortran 77 and later
5906 @item @emph{Syntax}:
5907 @code{RESULT = INT(A [, KIND))}
5909 @item @emph{Arguments}:
5910 @multitable @columnfractions .15 .70
5911 @item @var{A} @tab Shall be of type @code{INTEGER},
5912 @code{REAL}, or @code{COMPLEX}.
5913 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
5914 expression indicating the kind parameter of the result.
5917 @item @emph{Return value}:
5918 These functions return a @code{INTEGER} variable or array under
5919 the following rules:
5923 If @var{A} is of type @code{INTEGER}, @code{INT(A) = A}
5925 If @var{A} is of type @code{REAL} and @math{|A| < 1}, @code{INT(A)} equals @code{0}.
5926 If @math{|A| \geq 1}, then @code{INT(A)} equals the largest integer that does not exceed
5927 the range of @var{A} and whose sign is the same as the sign of @var{A}.
5929 If @var{A} is of type @code{COMPLEX}, rule B is applied to the real part of @var{A}.
5932 @item @emph{Example}:
5936 complex :: z = (-3.7, 1.0)
5938 print *, int(z), int(z,8)
5942 @item @emph{Specific names}:
5943 @multitable @columnfractions .20 .20 .20 .25
5944 @item Name @tab Argument @tab Return type @tab Standard
5945 @item @code{INT(A)} @tab @code{REAL(4) A} @tab @code{INTEGER} @tab Fortran 77 and later
5946 @item @code{IFIX(A)} @tab @code{REAL(4) A} @tab @code{INTEGER} @tab Fortran 77 and later
5947 @item @code{IDINT(A)} @tab @code{REAL(8) A} @tab @code{INTEGER} @tab Fortran 77 and later
5954 @section @code{INT2} --- Convert to 16-bit integer type
5957 @cindex conversion, to integer
5960 @item @emph{Description}:
5961 Convert to a @code{KIND=2} integer type. This is equivalent to the
5962 standard @code{INT} intrinsic with an optional argument of
5963 @code{KIND=2}, and is only included for backwards compatibility.
5965 The @code{SHORT} intrinsic is equivalent to @code{INT2}.
5967 @item @emph{Standard}:
5973 @item @emph{Syntax}:
5974 @code{RESULT = INT2(A)}
5976 @item @emph{Arguments}:
5977 @multitable @columnfractions .15 .70
5978 @item @var{A} @tab Shall be of type @code{INTEGER},
5979 @code{REAL}, or @code{COMPLEX}.
5982 @item @emph{Return value}:
5983 The return value is a @code{INTEGER(2)} variable.
5985 @item @emph{See also}:
5986 @ref{INT}, @ref{INT8}, @ref{LONG}
5992 @section @code{INT8} --- Convert to 64-bit integer type
5994 @cindex conversion, to integer
5997 @item @emph{Description}:
5998 Convert to a @code{KIND=8} integer type. This is equivalent to the
5999 standard @code{INT} intrinsic with an optional argument of
6000 @code{KIND=8}, and is only included for backwards compatibility.
6002 @item @emph{Standard}:
6008 @item @emph{Syntax}:
6009 @code{RESULT = INT8(A)}
6011 @item @emph{Arguments}:
6012 @multitable @columnfractions .15 .70
6013 @item @var{A} @tab Shall be of type @code{INTEGER},
6014 @code{REAL}, or @code{COMPLEX}.
6017 @item @emph{Return value}:
6018 The return value is a @code{INTEGER(8)} variable.
6020 @item @emph{See also}:
6021 @ref{INT}, @ref{INT2}, @ref{LONG}
6027 @section @code{IOR} --- Bitwise logical or
6029 @cindex bitwise logical or
6030 @cindex logical or, bitwise
6033 @item @emph{Description}:
6034 @code{IOR} returns the bitwise boolean inclusive-OR of @var{I} and
6037 @item @emph{Standard}:
6038 Fortran 95 and later
6043 @item @emph{Syntax}:
6044 @code{RESULT = IOR(I, J)}
6046 @item @emph{Arguments}:
6047 @multitable @columnfractions .15 .70
6048 @item @var{I} @tab The type shall be @code{INTEGER}.
6049 @item @var{J} @tab The type shall be @code{INTEGER}, of the same
6050 kind as @var{I}. (As a GNU extension, different kinds are also
6054 @item @emph{Return value}:
6055 The return type is @code{INTEGER}, of the same kind as the
6056 arguments. (If the argument kinds differ, it is of the same kind as
6057 the larger argument.)
6059 @item @emph{See also}:
6060 @ref{IEOR}, @ref{IAND}, @ref{IBITS}, @ref{IBSET}, @ref{IBCLR}, @ref{NOT}
6066 @section @code{IRAND} --- Integer pseudo-random number
6068 @cindex random number generation
6071 @item @emph{Description}:
6072 @code{IRAND(FLAG)} returns a pseudo-random number from a uniform
6073 distribution between 0 and a system-dependent limit (which is in most
6074 cases 2147483647). If @var{FLAG} is 0, the next number
6075 in the current sequence is returned; if @var{FLAG} is 1, the generator
6076 is restarted by @code{CALL SRAND(0)}; if @var{FLAG} has any other value,
6077 it is used as a new seed with @code{SRAND}.
6079 This intrinsic routine is provided for backwards compatibility with
6080 GNU Fortran 77. It implements a simple modulo generator as provided
6081 by @command{g77}. For new code, one should consider the use of
6082 @ref{RANDOM_NUMBER} as it implements a superior algorithm.
6084 @item @emph{Standard}:
6090 @item @emph{Syntax}:
6091 @code{RESULT = IRAND(I)}
6093 @item @emph{Arguments}:
6094 @multitable @columnfractions .15 .70
6095 @item @var{I} @tab Shall be a scalar @code{INTEGER} of kind 4.
6098 @item @emph{Return value}:
6099 The return value is of @code{INTEGER(kind=4)} type.
6101 @item @emph{Example}:
6104 integer,parameter :: seed = 86456
6107 print *, irand(), irand(), irand(), irand()
6108 print *, irand(seed), irand(), irand(), irand()
6109 end program test_irand
6117 @section @code{IMAGE_INDEX} --- Function that converts a cosubscript to an image index
6118 @fnindex IMAGE_INDEX
6119 @cindex coarray, IMAGE_INDEX
6120 @cindex images, cosubscript to image index conversion
6123 @item @emph{Description}:
6124 Returns the image index belonging to a cosubscript.
6126 @item @emph{Standard}:
6127 Fortran 2008 and later
6132 @item @emph{Syntax}:
6133 @code{RESULT = IMAGE_INDEX(COARRAY, SUB)}
6135 @item @emph{Arguments}: None.
6136 @multitable @columnfractions .15 .70
6137 @item @var{COARRAY} @tab Coarray of any type.
6138 @item @var{SUB} @tab default integer rank-1 array of a size equal to
6139 the corank of @var{COARRAY}.
6143 @item @emph{Return value}:
6144 Scalar default integer with the value of the image index which corresponds
6145 to the cosubscripts. For invalid cosubscripts the result is zero.
6147 @item @emph{Example}:
6149 INTEGER :: array[2,-1:4,8,*]
6150 ! Writes 28 (or 0 if there are fewer than 28 images)
6151 WRITE (*,*) IMAGE_INDEX (array, [2,0,3,1])
6154 @item @emph{See also}:
6155 @ref{THIS_IMAGE}, @ref{NUM_IMAGES}
6161 @section @code{IS_IOSTAT_END} --- Test for end-of-file value
6162 @fnindex IS_IOSTAT_END
6163 @cindex IOSTAT, end of file
6166 @item @emph{Description}:
6167 @code{IS_IOSTAT_END} tests whether an variable has the value of the I/O
6168 status ``end of file''. The function is equivalent to comparing the variable
6169 with the @code{IOSTAT_END} parameter of the intrinsic module
6170 @code{ISO_FORTRAN_ENV}.
6172 @item @emph{Standard}:
6173 Fortran 2003 and later
6178 @item @emph{Syntax}:
6179 @code{RESULT = IS_IOSTAT_END(I)}
6181 @item @emph{Arguments}:
6182 @multitable @columnfractions .15 .70
6183 @item @var{I} @tab Shall be of the type @code{INTEGER}.
6186 @item @emph{Return value}:
6187 Returns a @code{LOGICAL} of the default kind, which @code{.TRUE.} if
6188 @var{I} has the value which indicates an end of file condition for
6189 IOSTAT= specifiers, and is @code{.FALSE.} otherwise.
6191 @item @emph{Example}:
6196 OPEN(88, FILE='test.dat')
6197 READ(88, *, IOSTAT=stat) i
6198 IF(IS_IOSTAT_END(stat)) STOP 'END OF FILE'
6206 @section @code{IS_IOSTAT_EOR} --- Test for end-of-record value
6207 @fnindex IS_IOSTAT_EOR
6208 @cindex IOSTAT, end of record
6211 @item @emph{Description}:
6212 @code{IS_IOSTAT_EOR} tests whether an variable has the value of the I/O
6213 status ``end of record''. The function is equivalent to comparing the
6214 variable with the @code{IOSTAT_EOR} parameter of the intrinsic module
6215 @code{ISO_FORTRAN_ENV}.
6217 @item @emph{Standard}:
6218 Fortran 2003 and later
6223 @item @emph{Syntax}:
6224 @code{RESULT = IS_IOSTAT_EOR(I)}
6226 @item @emph{Arguments}:
6227 @multitable @columnfractions .15 .70
6228 @item @var{I} @tab Shall be of the type @code{INTEGER}.
6231 @item @emph{Return value}:
6232 Returns a @code{LOGICAL} of the default kind, which @code{.TRUE.} if
6233 @var{I} has the value which indicates an end of file condition for
6234 IOSTAT= specifiers, and is @code{.FALSE.} otherwise.
6236 @item @emph{Example}:
6240 INTEGER :: stat, i(50)
6241 OPEN(88, FILE='test.dat', FORM='UNFORMATTED')
6242 READ(88, IOSTAT=stat) i
6243 IF(IS_IOSTAT_EOR(stat)) STOP 'END OF RECORD'
6251 @section @code{ISATTY} --- Whether a unit is a terminal device.
6253 @cindex system, terminal
6256 @item @emph{Description}:
6257 Determine whether a unit is connected to a terminal device.
6259 @item @emph{Standard}:
6265 @item @emph{Syntax}:
6266 @code{RESULT = ISATTY(UNIT)}
6268 @item @emph{Arguments}:
6269 @multitable @columnfractions .15 .70
6270 @item @var{UNIT} @tab Shall be a scalar @code{INTEGER}.
6273 @item @emph{Return value}:
6274 Returns @code{.TRUE.} if the @var{UNIT} is connected to a terminal
6275 device, @code{.FALSE.} otherwise.
6277 @item @emph{Example}:
6280 INTEGER(kind=1) :: unit
6282 write(*,*) isatty(unit=unit)
6286 @item @emph{See also}:
6293 @section @code{ISHFT} --- Shift bits
6298 @item @emph{Description}:
6299 @code{ISHFT} returns a value corresponding to @var{I} with all of the
6300 bits shifted @var{SHIFT} places. A value of @var{SHIFT} greater than
6301 zero corresponds to a left shift, a value of zero corresponds to no
6302 shift, and a value less than zero corresponds to a right shift. If the
6303 absolute value of @var{SHIFT} is greater than @code{BIT_SIZE(I)}, the
6304 value is undefined. Bits shifted out from the left end or right end are
6305 lost; zeros are shifted in from the opposite end.
6307 @item @emph{Standard}:
6308 Fortran 95 and later
6313 @item @emph{Syntax}:
6314 @code{RESULT = ISHFT(I, SHIFT)}
6316 @item @emph{Arguments}:
6317 @multitable @columnfractions .15 .70
6318 @item @var{I} @tab The type shall be @code{INTEGER}.
6319 @item @var{SHIFT} @tab The type shall be @code{INTEGER}.
6322 @item @emph{Return value}:
6323 The return value is of type @code{INTEGER} and of the same kind as
6326 @item @emph{See also}:
6333 @section @code{ISHFTC} --- Shift bits circularly
6335 @cindex bits, shift circular
6338 @item @emph{Description}:
6339 @code{ISHFTC} returns a value corresponding to @var{I} with the
6340 rightmost @var{SIZE} bits shifted circularly @var{SHIFT} places; that
6341 is, bits shifted out one end are shifted into the opposite end. A value
6342 of @var{SHIFT} greater than zero corresponds to a left shift, a value of
6343 zero corresponds to no shift, and a value less than zero corresponds to
6344 a right shift. The absolute value of @var{SHIFT} must be less than
6345 @var{SIZE}. If the @var{SIZE} argument is omitted, it is taken to be
6346 equivalent to @code{BIT_SIZE(I)}.
6348 @item @emph{Standard}:
6349 Fortran 95 and later
6354 @item @emph{Syntax}:
6355 @code{RESULT = ISHFTC(I, SHIFT [, SIZE])}
6357 @item @emph{Arguments}:
6358 @multitable @columnfractions .15 .70
6359 @item @var{I} @tab The type shall be @code{INTEGER}.
6360 @item @var{SHIFT} @tab The type shall be @code{INTEGER}.
6361 @item @var{SIZE} @tab (Optional) The type shall be @code{INTEGER};
6362 the value must be greater than zero and less than or equal to
6366 @item @emph{Return value}:
6367 The return value is of type @code{INTEGER} and of the same kind as
6370 @item @emph{See also}:
6377 @section @code{ISNAN} --- Test for a NaN
6382 @item @emph{Description}:
6383 @code{ISNAN} tests whether a floating-point value is an IEEE
6385 @item @emph{Standard}:
6391 @item @emph{Syntax}:
6394 @item @emph{Arguments}:
6395 @multitable @columnfractions .15 .70
6396 @item @var{X} @tab Variable of the type @code{REAL}.
6400 @item @emph{Return value}:
6401 Returns a default-kind @code{LOGICAL}. The returned value is @code{TRUE}
6402 if @var{X} is a NaN and @code{FALSE} otherwise.
6404 @item @emph{Example}:
6411 if (isnan(x)) stop '"x" is a NaN'
6412 end program test_nan
6419 @section @code{ITIME} --- Get current local time subroutine (hour/minutes/seconds)
6421 @cindex time, current
6422 @cindex current time
6425 @item @emph{Description}:
6426 @code{IDATE(VALUES)} Fills @var{VALUES} with the numerical values at the
6427 current local time. The hour (in the range 1-24), minute (in the range 1-60),
6428 and seconds (in the range 1-60) appear in elements 1, 2, and 3 of @var{VALUES},
6431 @item @emph{Standard}:
6437 @item @emph{Syntax}:
6438 @code{CALL ITIME(VALUES)}
6440 @item @emph{Arguments}:
6441 @multitable @columnfractions .15 .70
6442 @item @var{VALUES} @tab The type shall be @code{INTEGER, DIMENSION(3)}
6443 and the kind shall be the default integer kind.
6446 @item @emph{Return value}:
6447 Does not return anything.
6450 @item @emph{Example}:
6453 integer, dimension(3) :: tarray
6458 end program test_itime
6465 @section @code{KILL} --- Send a signal to a process
6469 @item @emph{Description}:
6470 @item @emph{Standard}:
6471 Sends the signal specified by @var{SIGNAL} to the process @var{PID}.
6474 This intrinsic is provided in both subroutine and function forms; however,
6475 only one form can be used in any given program unit.
6478 Subroutine, function
6480 @item @emph{Syntax}:
6481 @code{CALL KILL(C, VALUE [, STATUS])}
6483 @item @emph{Arguments}:
6484 @multitable @columnfractions .15 .70
6485 @item @var{C} @tab Shall be a scalar @code{INTEGER}, with
6487 @item @var{VALUE} @tab Shall be a scalar @code{INTEGER}, with
6489 @item @var{STATUS} @tab (Optional) status flag of type @code{INTEGER(4)} or
6490 @code{INTEGER(8)}. Returns 0 on success, or a system-specific error code
6494 @item @emph{See also}:
6495 @ref{ABORT}, @ref{EXIT}
6501 @section @code{KIND} --- Kind of an entity
6506 @item @emph{Description}:
6507 @code{KIND(X)} returns the kind value of the entity @var{X}.
6509 @item @emph{Standard}:
6510 Fortran 95 and later
6515 @item @emph{Syntax}:
6518 @item @emph{Arguments}:
6519 @multitable @columnfractions .15 .70
6520 @item @var{X} @tab Shall be of type @code{LOGICAL}, @code{INTEGER},
6521 @code{REAL}, @code{COMPLEX} or @code{CHARACTER}.
6524 @item @emph{Return value}:
6525 The return value is a scalar of type @code{INTEGER} and of the default
6528 @item @emph{Example}:
6531 integer,parameter :: kc = kind(' ')
6532 integer,parameter :: kl = kind(.true.)
6534 print *, "The default character kind is ", kc
6535 print *, "The default logical kind is ", kl
6536 end program test_kind
6544 @section @code{LBOUND} --- Lower dimension bounds of an array
6546 @cindex array, lower bound
6549 @item @emph{Description}:
6550 Returns the lower bounds of an array, or a single lower bound
6551 along the @var{DIM} dimension.
6552 @item @emph{Standard}:
6553 Fortran 95 and later, with @var{KIND} argument Fortran 2003 and later
6558 @item @emph{Syntax}:
6559 @code{RESULT = LBOUND(ARRAY [, DIM [, KIND]])}
6561 @item @emph{Arguments}:
6562 @multitable @columnfractions .15 .70
6563 @item @var{ARRAY} @tab Shall be an array, of any type.
6564 @item @var{DIM} @tab (Optional) Shall be a scalar @code{INTEGER}.
6565 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
6566 expression indicating the kind parameter of the result.
6569 @item @emph{Return value}:
6570 The return value is of type @code{INTEGER} and of kind @var{KIND}. If
6571 @var{KIND} is absent, the return value is of default integer kind.
6572 If @var{DIM} is absent, the result is an array of the lower bounds of
6573 @var{ARRAY}. If @var{DIM} is present, the result is a scalar
6574 corresponding to the lower bound of the array along that dimension. If
6575 @var{ARRAY} is an expression rather than a whole array or array
6576 structure component, or if it has a zero extent along the relevant
6577 dimension, the lower bound is taken to be 1.
6579 @item @emph{See also}:
6580 @ref{UBOUND}, @ref{LCOBOUND}
6586 @section @code{LCOBOUND} --- Lower codimension bounds of an array
6588 @cindex coarray, lower bound
6591 @item @emph{Description}:
6592 Returns the lower bounds of a coarray, or a single lower cobound
6593 along the @var{DIM} codimension.
6594 @item @emph{Standard}:
6595 Fortran 2008 and later
6600 @item @emph{Syntax}:
6601 @code{RESULT = LCOBOUND(COARRAY [, DIM [, KIND]])}
6603 @item @emph{Arguments}:
6604 @multitable @columnfractions .15 .70
6605 @item @var{ARRAY} @tab Shall be an coarray, of any type.
6606 @item @var{DIM} @tab (Optional) Shall be a scalar @code{INTEGER}.
6607 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
6608 expression indicating the kind parameter of the result.
6611 @item @emph{Return value}:
6612 The return value is of type @code{INTEGER} and of kind @var{KIND}. If
6613 @var{KIND} is absent, the return value is of default integer kind.
6614 If @var{DIM} is absent, the result is an array of the lower cobounds of
6615 @var{COARRAY}. If @var{DIM} is present, the result is a scalar
6616 corresponding to the lower cobound of the array along that codimension.
6618 @item @emph{See also}:
6619 @ref{UCOBOUND}, @ref{LBOUND}
6625 @section @code{LEADZ} --- Number of leading zero bits of an integer
6630 @item @emph{Description}:
6631 @code{LEADZ} returns the number of leading zero bits of an integer.
6633 @item @emph{Standard}:
6634 Fortran 2008 and later
6639 @item @emph{Syntax}:
6640 @code{RESULT = LEADZ(I)}
6642 @item @emph{Arguments}:
6643 @multitable @columnfractions .15 .70
6644 @item @var{I} @tab Shall be of type @code{INTEGER}.
6647 @item @emph{Return value}:
6648 The type of the return value is the default @code{INTEGER}.
6649 If all the bits of @code{I} are zero, the result value is @code{BIT_SIZE(I)}.
6651 @item @emph{Example}:
6654 WRITE (*,*) LEADZ(1) ! prints 8 if BITSIZE(I) has the value 32
6658 @item @emph{See also}:
6659 @ref{BIT_SIZE}, @ref{TRAILZ}
6665 @section @code{LEN} --- Length of a character entity
6667 @cindex string, length
6670 @item @emph{Description}:
6671 Returns the length of a character string. If @var{STRING} is an array,
6672 the length of an element of @var{STRING} is returned. Note that
6673 @var{STRING} need not be defined when this intrinsic is invoked, since
6674 only the length, not the content, of @var{STRING} is needed.
6676 @item @emph{Standard}:
6677 Fortran 77 and later, with @var{KIND} argument Fortran 2003 and later
6682 @item @emph{Syntax}:
6683 @code{L = LEN(STRING [, KIND])}
6685 @item @emph{Arguments}:
6686 @multitable @columnfractions .15 .70
6687 @item @var{STRING} @tab Shall be a scalar or array of type
6688 @code{CHARACTER}, with @code{INTENT(IN)}
6689 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
6690 expression indicating the kind parameter of the result.
6693 @item @emph{Return value}:
6694 The return value is of type @code{INTEGER} and of kind @var{KIND}. If
6695 @var{KIND} is absent, the return value is of default integer kind.
6698 @item @emph{Specific names}:
6699 @multitable @columnfractions .20 .20 .20 .25
6700 @item Name @tab Argument @tab Return type @tab Standard
6701 @item @code{LEN(STRING)} @tab @code{CHARACTER} @tab @code{INTEGER} @tab Fortran 77 and later
6705 @item @emph{See also}:
6706 @ref{LEN_TRIM}, @ref{ADJUSTL}, @ref{ADJUSTR}
6712 @section @code{LEN_TRIM} --- Length of a character entity without trailing blank characters
6714 @cindex string, length, without trailing whitespace
6717 @item @emph{Description}:
6718 Returns the length of a character string, ignoring any trailing blanks.
6720 @item @emph{Standard}:
6721 Fortran 95 and later, with @var{KIND} argument Fortran 2003 and later
6726 @item @emph{Syntax}:
6727 @code{RESULT = LEN_TRIM(STRING [, KIND])}
6729 @item @emph{Arguments}:
6730 @multitable @columnfractions .15 .70
6731 @item @var{STRING} @tab Shall be a scalar of type @code{CHARACTER},
6732 with @code{INTENT(IN)}
6733 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
6734 expression indicating the kind parameter of the result.
6737 @item @emph{Return value}:
6738 The return value is of type @code{INTEGER} and of kind @var{KIND}. If
6739 @var{KIND} is absent, the return value is of default integer kind.
6741 @item @emph{See also}:
6742 @ref{LEN}, @ref{ADJUSTL}, @ref{ADJUSTR}
6748 @section @code{LGE} --- Lexical greater than or equal
6750 @cindex lexical comparison of strings
6751 @cindex string, comparison
6754 @item @emph{Description}:
6755 Determines whether one string is lexically greater than or equal to
6756 another string, where the two strings are interpreted as containing
6757 ASCII character codes. If the String A and String B are not the same
6758 length, the shorter is compared as if spaces were appended to it to form
6759 a value that has the same length as the longer.
6761 In general, the lexical comparison intrinsics @code{LGE}, @code{LGT},
6762 @code{LLE}, and @code{LLT} differ from the corresponding intrinsic
6763 operators @code{.GE.}, @code{.GT.}, @code{.LE.}, and @code{.LT.}, in
6764 that the latter use the processor's character ordering (which is not
6765 ASCII on some targets), whereas the former always use the ASCII
6768 @item @emph{Standard}:
6769 Fortran 77 and later
6774 @item @emph{Syntax}:
6775 @code{RESULT = LGE(STRING_A, STRING_B)}
6777 @item @emph{Arguments}:
6778 @multitable @columnfractions .15 .70
6779 @item @var{STRING_A} @tab Shall be of default @code{CHARACTER} type.
6780 @item @var{STRING_B} @tab Shall be of default @code{CHARACTER} type.
6783 @item @emph{Return value}:
6784 Returns @code{.TRUE.} if @code{STRING_A >= STRING_B}, and @code{.FALSE.}
6785 otherwise, based on the ASCII ordering.
6787 @item @emph{Specific names}:
6788 @multitable @columnfractions .20 .20 .20 .25
6789 @item Name @tab Argument @tab Return type @tab Standard
6790 @item @code{LGE(STRING_A, STRING_B)} @tab @code{CHARACTER} @tab @code{LOGICAL} @tab Fortran 77 and later
6793 @item @emph{See also}:
6794 @ref{LGT}, @ref{LLE}, @ref{LLT}
6800 @section @code{LGT} --- Lexical greater than
6802 @cindex lexical comparison of strings
6803 @cindex string, comparison
6806 @item @emph{Description}:
6807 Determines whether one string is lexically greater than another string,
6808 where the two strings are interpreted as containing ASCII character
6809 codes. If the String A and String B are not the same length, the
6810 shorter is compared as if spaces were appended to it to form a value
6811 that has the same length as the longer.
6813 In general, the lexical comparison intrinsics @code{LGE}, @code{LGT},
6814 @code{LLE}, and @code{LLT} differ from the corresponding intrinsic
6815 operators @code{.GE.}, @code{.GT.}, @code{.LE.}, and @code{.LT.}, in
6816 that the latter use the processor's character ordering (which is not
6817 ASCII on some targets), whereas the former always use the ASCII
6820 @item @emph{Standard}:
6821 Fortran 77 and later
6826 @item @emph{Syntax}:
6827 @code{RESULT = LGT(STRING_A, STRING_B)}
6829 @item @emph{Arguments}:
6830 @multitable @columnfractions .15 .70
6831 @item @var{STRING_A} @tab Shall be of default @code{CHARACTER} type.
6832 @item @var{STRING_B} @tab Shall be of default @code{CHARACTER} type.
6835 @item @emph{Return value}:
6836 Returns @code{.TRUE.} if @code{STRING_A > STRING_B}, and @code{.FALSE.}
6837 otherwise, based on the ASCII ordering.
6839 @item @emph{Specific names}:
6840 @multitable @columnfractions .20 .20 .20 .25
6841 @item Name @tab Argument @tab Return type @tab Standard
6842 @item @code{LGT(STRING_A, STRING_B)} @tab @code{CHARACTER} @tab @code{LOGICAL} @tab Fortran 77 and later
6845 @item @emph{See also}:
6846 @ref{LGE}, @ref{LLE}, @ref{LLT}
6852 @section @code{LINK} --- Create a hard link
6854 @cindex file system, create link
6855 @cindex file system, hard link
6858 @item @emph{Description}:
6859 Makes a (hard) link from file @var{PATH1} to @var{PATH2}. A null
6860 character (@code{CHAR(0)}) can be used to mark the end of the names in
6861 @var{PATH1} and @var{PATH2}; otherwise, trailing blanks in the file
6862 names are ignored. If the @var{STATUS} argument is supplied, it
6863 contains 0 on success or a nonzero error code upon return; see
6866 This intrinsic is provided in both subroutine and function forms;
6867 however, only one form can be used in any given program unit.
6869 @item @emph{Standard}:
6873 Subroutine, function
6875 @item @emph{Syntax}:
6876 @multitable @columnfractions .80
6877 @item @code{CALL LINK(PATH1, PATH2 [, STATUS])}
6878 @item @code{STATUS = LINK(PATH1, PATH2)}
6881 @item @emph{Arguments}:
6882 @multitable @columnfractions .15 .70
6883 @item @var{PATH1} @tab Shall be of default @code{CHARACTER} type.
6884 @item @var{PATH2} @tab Shall be of default @code{CHARACTER} type.
6885 @item @var{STATUS} @tab (Optional) Shall be of default @code{INTEGER} type.
6888 @item @emph{See also}:
6889 @ref{SYMLNK}, @ref{UNLINK}
6895 @section @code{LLE} --- Lexical less than or equal
6897 @cindex lexical comparison of strings
6898 @cindex string, comparison
6901 @item @emph{Description}:
6902 Determines whether one string is lexically less than or equal to another
6903 string, where the two strings are interpreted as containing ASCII
6904 character codes. If the String A and String B are not the same length,
6905 the shorter is compared as if spaces were appended to it to form a value
6906 that has the same length as the longer.
6908 In general, the lexical comparison intrinsics @code{LGE}, @code{LGT},
6909 @code{LLE}, and @code{LLT} differ from the corresponding intrinsic
6910 operators @code{.GE.}, @code{.GT.}, @code{.LE.}, and @code{.LT.}, in
6911 that the latter use the processor's character ordering (which is not
6912 ASCII on some targets), whereas the former always use the ASCII
6915 @item @emph{Standard}:
6916 Fortran 77 and later
6921 @item @emph{Syntax}:
6922 @code{RESULT = LLE(STRING_A, STRING_B)}
6924 @item @emph{Arguments}:
6925 @multitable @columnfractions .15 .70
6926 @item @var{STRING_A} @tab Shall be of default @code{CHARACTER} type.
6927 @item @var{STRING_B} @tab Shall be of default @code{CHARACTER} type.
6930 @item @emph{Return value}:
6931 Returns @code{.TRUE.} if @code{STRING_A <= STRING_B}, and @code{.FALSE.}
6932 otherwise, based on the ASCII ordering.
6934 @item @emph{Specific names}:
6935 @multitable @columnfractions .20 .20 .20 .25
6936 @item Name @tab Argument @tab Return type @tab Standard
6937 @item @code{LLE(STRING_A, STRING_B)} @tab @code{CHARACTER} @tab @code{LOGICAL} @tab Fortran 77 and later
6940 @item @emph{See also}:
6941 @ref{LGE}, @ref{LGT}, @ref{LLT}
6947 @section @code{LLT} --- Lexical less than
6949 @cindex lexical comparison of strings
6950 @cindex string, comparison
6953 @item @emph{Description}:
6954 Determines whether one string is lexically less than another string,
6955 where the two strings are interpreted as containing ASCII character
6956 codes. If the String A and String B are not the same length, the
6957 shorter is compared as if spaces were appended to it to form a value
6958 that has the same length as the longer.
6960 In general, the lexical comparison intrinsics @code{LGE}, @code{LGT},
6961 @code{LLE}, and @code{LLT} differ from the corresponding intrinsic
6962 operators @code{.GE.}, @code{.GT.}, @code{.LE.}, and @code{.LT.}, in
6963 that the latter use the processor's character ordering (which is not
6964 ASCII on some targets), whereas the former always use the ASCII
6967 @item @emph{Standard}:
6968 Fortran 77 and later
6973 @item @emph{Syntax}:
6974 @code{RESULT = LLT(STRING_A, STRING_B)}
6976 @item @emph{Arguments}:
6977 @multitable @columnfractions .15 .70
6978 @item @var{STRING_A} @tab Shall be of default @code{CHARACTER} type.
6979 @item @var{STRING_B} @tab Shall be of default @code{CHARACTER} type.
6982 @item @emph{Return value}:
6983 Returns @code{.TRUE.} if @code{STRING_A < STRING_B}, and @code{.FALSE.}
6984 otherwise, based on the ASCII ordering.
6986 @item @emph{Specific names}:
6987 @multitable @columnfractions .20 .20 .20 .25
6988 @item Name @tab Argument @tab Return type @tab Standard
6989 @item @code{LLT(STRING_A, STRING_B)} @tab @code{CHARACTER} @tab @code{LOGICAL} @tab Fortran 77 and later
6992 @item @emph{See also}:
6993 @ref{LGE}, @ref{LGT}, @ref{LLE}
6999 @section @code{LNBLNK} --- Index of the last non-blank character in a string
7001 @cindex string, find non-blank character
7004 @item @emph{Description}:
7005 Returns the length of a character string, ignoring any trailing blanks.
7006 This is identical to the standard @code{LEN_TRIM} intrinsic, and is only
7007 included for backwards compatibility.
7009 @item @emph{Standard}:
7015 @item @emph{Syntax}:
7016 @code{RESULT = LNBLNK(STRING)}
7018 @item @emph{Arguments}:
7019 @multitable @columnfractions .15 .70
7020 @item @var{STRING} @tab Shall be a scalar of type @code{CHARACTER},
7021 with @code{INTENT(IN)}
7024 @item @emph{Return value}:
7025 The return value is of @code{INTEGER(kind=4)} type.
7027 @item @emph{See also}:
7028 @ref{INDEX intrinsic}, @ref{LEN_TRIM}
7034 @section @code{LOC} --- Returns the address of a variable
7036 @cindex location of a variable in memory
7039 @item @emph{Description}:
7040 @code{LOC(X)} returns the address of @var{X} as an integer.
7042 @item @emph{Standard}:
7048 @item @emph{Syntax}:
7049 @code{RESULT = LOC(X)}
7051 @item @emph{Arguments}:
7052 @multitable @columnfractions .15 .70
7053 @item @var{X} @tab Variable of any type.
7056 @item @emph{Return value}:
7057 The return value is of type @code{INTEGER}, with a @code{KIND}
7058 corresponding to the size (in bytes) of a memory address on the target
7061 @item @emph{Example}:
7068 end program test_loc
7075 @section @code{LOG} --- Logarithm function
7082 @cindex exponential function, inverse
7083 @cindex logarithmic function
7086 @item @emph{Description}:
7087 @code{LOG(X)} computes the logarithm of @var{X}.
7089 @item @emph{Standard}:
7090 Fortran 77 and later
7095 @item @emph{Syntax}:
7096 @code{RESULT = LOG(X)}
7098 @item @emph{Arguments}:
7099 @multitable @columnfractions .15 .70
7100 @item @var{X} @tab The type shall be @code{REAL} or
7104 @item @emph{Return value}:
7105 The return value is of type @code{REAL} or @code{COMPLEX}.
7106 The kind type parameter is the same as @var{X}.
7107 If @var{X} is @code{COMPLEX}, the imaginary part @math{\omega} is in the range
7108 @math{-\pi \leq \omega \leq \pi}.
7110 @item @emph{Example}:
7113 real(8) :: x = 1.0_8
7114 complex :: z = (1.0, 2.0)
7117 end program test_log
7120 @item @emph{Specific names}:
7121 @multitable @columnfractions .20 .20 .20 .25
7122 @item Name @tab Argument @tab Return type @tab Standard
7123 @item @code{ALOG(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab f95, gnu
7124 @item @code{DLOG(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab f95, gnu
7125 @item @code{CLOG(X)} @tab @code{COMPLEX(4) X} @tab @code{COMPLEX(4)} @tab f95, gnu
7126 @item @code{ZLOG(X)} @tab @code{COMPLEX(8) X} @tab @code{COMPLEX(8)} @tab f95, gnu
7127 @item @code{CDLOG(X)} @tab @code{COMPLEX(8) X} @tab @code{COMPLEX(8)} @tab f95, gnu
7134 @section @code{LOG10} --- Base 10 logarithm function
7138 @cindex exponential function, inverse
7139 @cindex logarithmic function
7142 @item @emph{Description}:
7143 @code{LOG10(X)} computes the base 10 logarithm of @var{X}.
7145 @item @emph{Standard}:
7146 Fortran 77 and later
7151 @item @emph{Syntax}:
7152 @code{RESULT = LOG10(X)}
7154 @item @emph{Arguments}:
7155 @multitable @columnfractions .15 .70
7156 @item @var{X} @tab The type shall be @code{REAL}.
7159 @item @emph{Return value}:
7160 The return value is of type @code{REAL} or @code{COMPLEX}.
7161 The kind type parameter is the same as @var{X}.
7163 @item @emph{Example}:
7166 real(8) :: x = 10.0_8
7168 end program test_log10
7171 @item @emph{Specific names}:
7172 @multitable @columnfractions .20 .20 .20 .25
7173 @item Name @tab Argument @tab Return type @tab Standard
7174 @item @code{ALOG10(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab Fortran 95 and later
7175 @item @code{DLOG10(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab Fortran 95 and later
7182 @section @code{LOG_GAMMA} --- Logarithm of the Gamma function
7187 @cindex Gamma function, logarithm of
7190 @item @emph{Description}:
7191 @code{LOG_GAMMA(X)} computes the natural logarithm of the absolute value
7192 of the Gamma (@math{\Gamma}) function.
7194 @item @emph{Standard}:
7195 Fortran 2008 and later
7200 @item @emph{Syntax}:
7201 @code{X = LOG_GAMMA(X)}
7203 @item @emph{Arguments}:
7204 @multitable @columnfractions .15 .70
7205 @item @var{X} @tab Shall be of type @code{REAL} and neither zero
7206 nor a negative integer.
7209 @item @emph{Return value}:
7210 The return value is of type @code{REAL} of the same kind as @var{X}.
7212 @item @emph{Example}:
7214 program test_log_gamma
7216 x = lgamma(x) ! returns 0.0
7217 end program test_log_gamma
7220 @item @emph{Specific names}:
7221 @multitable @columnfractions .20 .20 .20 .25
7222 @item Name @tab Argument @tab Return type @tab Standard
7223 @item @code{LGAMMA(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab GNU Extension
7224 @item @code{ALGAMA(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab GNU Extension
7225 @item @code{DLGAMA(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU Extension
7228 @item @emph{See also}:
7229 Gamma function: @ref{GAMMA}
7236 @section @code{LOGICAL} --- Convert to logical type
7238 @cindex conversion, to logical
7241 @item @emph{Description}:
7242 Converts one kind of @code{LOGICAL} variable to another.
7244 @item @emph{Standard}:
7245 Fortran 95 and later
7250 @item @emph{Syntax}:
7251 @code{RESULT = LOGICAL(L [, KIND])}
7253 @item @emph{Arguments}:
7254 @multitable @columnfractions .15 .70
7255 @item @var{L} @tab The type shall be @code{LOGICAL}.
7256 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
7257 expression indicating the kind parameter of the result.
7260 @item @emph{Return value}:
7261 The return value is a @code{LOGICAL} value equal to @var{L}, with a
7262 kind corresponding to @var{KIND}, or of the default logical kind if
7263 @var{KIND} is not given.
7265 @item @emph{See also}:
7266 @ref{INT}, @ref{REAL}, @ref{CMPLX}
7272 @section @code{LONG} --- Convert to integer type
7274 @cindex conversion, to integer
7277 @item @emph{Description}:
7278 Convert to a @code{KIND=4} integer type, which is the same size as a C
7279 @code{long} integer. This is equivalent to the standard @code{INT}
7280 intrinsic with an optional argument of @code{KIND=4}, and is only
7281 included for backwards compatibility.
7283 @item @emph{Standard}:
7289 @item @emph{Syntax}:
7290 @code{RESULT = LONG(A)}
7292 @item @emph{Arguments}:
7293 @multitable @columnfractions .15 .70
7294 @item @var{A} @tab Shall be of type @code{INTEGER},
7295 @code{REAL}, or @code{COMPLEX}.
7298 @item @emph{Return value}:
7299 The return value is a @code{INTEGER(4)} variable.
7301 @item @emph{See also}:
7302 @ref{INT}, @ref{INT2}, @ref{INT8}
7308 @section @code{LSHIFT} --- Left shift bits
7310 @cindex bits, shift left
7313 @item @emph{Description}:
7314 @code{LSHIFT} returns a value corresponding to @var{I} with all of the
7315 bits shifted left by @var{SHIFT} places. If the absolute value of
7316 @var{SHIFT} is greater than @code{BIT_SIZE(I)}, the value is undefined.
7317 Bits shifted out from the left end are lost; zeros are shifted in from
7320 This function has been superseded by the @code{ISHFT} intrinsic, which
7321 is standard in Fortran 95 and later.
7323 @item @emph{Standard}:
7329 @item @emph{Syntax}:
7330 @code{RESULT = LSHIFT(I, SHIFT)}
7332 @item @emph{Arguments}:
7333 @multitable @columnfractions .15 .70
7334 @item @var{I} @tab The type shall be @code{INTEGER}.
7335 @item @var{SHIFT} @tab The type shall be @code{INTEGER}.
7338 @item @emph{Return value}:
7339 The return value is of type @code{INTEGER} and of the same kind as
7342 @item @emph{See also}:
7343 @ref{ISHFT}, @ref{ISHFTC}, @ref{RSHIFT}
7350 @section @code{LSTAT} --- Get file status
7352 @cindex file system, file status
7355 @item @emph{Description}:
7356 @code{LSTAT} is identical to @ref{STAT}, except that if path is a
7357 symbolic link, then the link itself is statted, not the file that it
7360 The elements in @code{VALUES} are the same as described by @ref{STAT}.
7362 This intrinsic is provided in both subroutine and function forms;
7363 however, only one form can be used in any given program unit.
7365 @item @emph{Standard}:
7369 Subroutine, function
7371 @item @emph{Syntax}:
7372 @code{CALL LSTAT(NAME, VALUES [, STATUS])}
7374 @item @emph{Arguments}:
7375 @multitable @columnfractions .15 .70
7376 @item @var{NAME} @tab The type shall be @code{CHARACTER} of the default
7377 kind, a valid path within the file system.
7378 @item @var{VALUES} @tab The type shall be @code{INTEGER(4), DIMENSION(13)}.
7379 @item @var{STATUS} @tab (Optional) status flag of type @code{INTEGER(4)}.
7380 Returns 0 on success and a system specific error code otherwise.
7383 @item @emph{Example}:
7384 See @ref{STAT} for an example.
7386 @item @emph{See also}:
7387 To stat an open file: @ref{FSTAT}, to stat a file: @ref{STAT}
7393 @section @code{LTIME} --- Convert time to local time info
7395 @cindex time, conversion to local time info
7398 @item @emph{Description}:
7399 Given a system time value @var{TIME} (as provided by the @code{TIME8()}
7400 intrinsic), fills @var{VALUES} with values extracted from it appropriate
7401 to the local time zone using @code{localtime(3)}.
7403 @item @emph{Standard}:
7409 @item @emph{Syntax}:
7410 @code{CALL LTIME(TIME, VALUES)}
7412 @item @emph{Arguments}:
7413 @multitable @columnfractions .15 .70
7414 @item @var{TIME} @tab An @code{INTEGER} scalar expression
7415 corresponding to a system time, with @code{INTENT(IN)}.
7416 @item @var{VALUES} @tab A default @code{INTEGER} array with 9 elements,
7417 with @code{INTENT(OUT)}.
7420 @item @emph{Return value}:
7421 The elements of @var{VALUES} are assigned as follows:
7423 @item Seconds after the minute, range 0--59 or 0--61 to allow for leap
7425 @item Minutes after the hour, range 0--59
7426 @item Hours past midnight, range 0--23
7427 @item Day of month, range 0--31
7428 @item Number of months since January, range 0--12
7429 @item Years since 1900
7430 @item Number of days since Sunday, range 0--6
7431 @item Days since January 1
7432 @item Daylight savings indicator: positive if daylight savings is in
7433 effect, zero if not, and negative if the information is not available.
7436 @item @emph{See also}:
7437 @ref{CTIME}, @ref{GMTIME}, @ref{TIME}, @ref{TIME8}
7444 @section @code{MALLOC} --- Allocate dynamic memory
7446 @cindex pointer, cray
7449 @item @emph{Description}:
7450 @code{MALLOC(SIZE)} allocates @var{SIZE} bytes of dynamic memory and
7451 returns the address of the allocated memory. The @code{MALLOC} intrinsic
7452 is an extension intended to be used with Cray pointers, and is provided
7453 in GNU Fortran to allow the user to compile legacy code. For new code
7454 using Fortran 95 pointers, the memory allocation intrinsic is
7457 @item @emph{Standard}:
7463 @item @emph{Syntax}:
7464 @code{PTR = MALLOC(SIZE)}
7466 @item @emph{Arguments}:
7467 @multitable @columnfractions .15 .70
7468 @item @var{SIZE} @tab The type shall be @code{INTEGER}.
7471 @item @emph{Return value}:
7472 The return value is of type @code{INTEGER(K)}, with @var{K} such that
7473 variables of type @code{INTEGER(K)} have the same size as
7474 C pointers (@code{sizeof(void *)}).
7476 @item @emph{Example}:
7477 The following example demonstrates the use of @code{MALLOC} and
7478 @code{FREE} with Cray pointers.
7487 ptr_x = malloc(20*8)
7489 x(i) = sqrt(1.0d0 / i)
7497 end program test_malloc
7500 @item @emph{See also}:
7507 @section @code{MATMUL} --- matrix multiplication
7509 @cindex matrix multiplication
7510 @cindex product, matrix
7513 @item @emph{Description}:
7514 Performs a matrix multiplication on numeric or logical arguments.
7516 @item @emph{Standard}:
7517 Fortran 95 and later
7520 Transformational function
7522 @item @emph{Syntax}:
7523 @code{RESULT = MATMUL(MATRIX_A, MATRIX_B)}
7525 @item @emph{Arguments}:
7526 @multitable @columnfractions .15 .70
7527 @item @var{MATRIX_A} @tab An array of @code{INTEGER},
7528 @code{REAL}, @code{COMPLEX}, or @code{LOGICAL} type, with a rank of
7530 @item @var{MATRIX_B} @tab An array of @code{INTEGER},
7531 @code{REAL}, or @code{COMPLEX} type if @var{MATRIX_A} is of a numeric
7532 type; otherwise, an array of @code{LOGICAL} type. The rank shall be one
7533 or two, and the first (or only) dimension of @var{MATRIX_B} shall be
7534 equal to the last (or only) dimension of @var{MATRIX_A}.
7537 @item @emph{Return value}:
7538 The matrix product of @var{MATRIX_A} and @var{MATRIX_B}. The type and
7539 kind of the result follow the usual type and kind promotion rules, as
7540 for the @code{*} or @code{.AND.} operators.
7542 @item @emph{See also}:
7548 @section @code{MAX} --- Maximum value of an argument list
7555 @cindex maximum value
7558 @item @emph{Description}:
7559 Returns the argument with the largest (most positive) value.
7561 @item @emph{Standard}:
7562 Fortran 77 and later
7567 @item @emph{Syntax}:
7568 @code{RESULT = MAX(A1, A2 [, A3 [, ...]])}
7570 @item @emph{Arguments}:
7571 @multitable @columnfractions .15 .70
7572 @item @var{A1} @tab The type shall be @code{INTEGER} or
7574 @item @var{A2}, @var{A3}, ... @tab An expression of the same type and kind
7575 as @var{A1}. (As a GNU extension, arguments of different kinds are
7579 @item @emph{Return value}:
7580 The return value corresponds to the maximum value among the arguments,
7581 and has the same type and kind as the first argument.
7583 @item @emph{Specific names}:
7584 @multitable @columnfractions .20 .20 .20 .25
7585 @item Name @tab Argument @tab Return type @tab Standard
7586 @item @code{MAX0(A1)} @tab @code{INTEGER(4) A1} @tab @code{INTEGER(4)} @tab Fortran 77 and later
7587 @item @code{AMAX0(A1)} @tab @code{INTEGER(4) A1} @tab @code{REAL(MAX(X))} @tab Fortran 77 and later
7588 @item @code{MAX1(A1)} @tab @code{REAL A1} @tab @code{INT(MAX(X))} @tab Fortran 77 and later
7589 @item @code{AMAX1(A1)} @tab @code{REAL(4) A1} @tab @code{REAL(4)} @tab Fortran 77 and later
7590 @item @code{DMAX1(A1)} @tab @code{REAL(8) A1} @tab @code{REAL(8)} @tab Fortran 77 and later
7593 @item @emph{See also}:
7594 @ref{MAXLOC} @ref{MAXVAL}, @ref{MIN}
7601 @section @code{MAXEXPONENT} --- Maximum exponent of a real kind
7602 @fnindex MAXEXPONENT
7603 @cindex model representation, maximum exponent
7606 @item @emph{Description}:
7607 @code{MAXEXPONENT(X)} returns the maximum exponent in the model of the
7610 @item @emph{Standard}:
7611 Fortran 95 and later
7616 @item @emph{Syntax}:
7617 @code{RESULT = MAXEXPONENT(X)}
7619 @item @emph{Arguments}:
7620 @multitable @columnfractions .15 .70
7621 @item @var{X} @tab Shall be of type @code{REAL}.
7624 @item @emph{Return value}:
7625 The return value is of type @code{INTEGER} and of the default integer
7628 @item @emph{Example}:
7634 print *, minexponent(x), maxexponent(x)
7635 print *, minexponent(y), maxexponent(y)
7636 end program exponents
7643 @section @code{MAXLOC} --- Location of the maximum value within an array
7645 @cindex array, location of maximum element
7648 @item @emph{Description}:
7649 Determines the location of the element in the array with the maximum
7650 value, or, if the @var{DIM} argument is supplied, determines the
7651 locations of the maximum element along each row of the array in the
7652 @var{DIM} direction. If @var{MASK} is present, only the elements for
7653 which @var{MASK} is @code{.TRUE.} are considered. If more than one
7654 element in the array has the maximum value, the location returned is
7655 that of the first such element in array element order. If the array has
7656 zero size, or all of the elements of @var{MASK} are @code{.FALSE.}, then
7657 the result is an array of zeroes. Similarly, if @var{DIM} is supplied
7658 and all of the elements of @var{MASK} along a given row are zero, the
7659 result value for that row is zero.
7661 @item @emph{Standard}:
7662 Fortran 95 and later
7665 Transformational function
7667 @item @emph{Syntax}:
7668 @multitable @columnfractions .80
7669 @item @code{RESULT = MAXLOC(ARRAY, DIM [, MASK])}
7670 @item @code{RESULT = MAXLOC(ARRAY [, MASK])}
7673 @item @emph{Arguments}:
7674 @multitable @columnfractions .15 .70
7675 @item @var{ARRAY} @tab Shall be an array of type @code{INTEGER} or
7677 @item @var{DIM} @tab (Optional) Shall be a scalar of type
7678 @code{INTEGER}, with a value between one and the rank of @var{ARRAY},
7679 inclusive. It may not be an optional dummy argument.
7680 @item @var{MASK} @tab Shall be an array of type @code{LOGICAL},
7681 and conformable with @var{ARRAY}.
7684 @item @emph{Return value}:
7685 If @var{DIM} is absent, the result is a rank-one array with a length
7686 equal to the rank of @var{ARRAY}. If @var{DIM} is present, the result
7687 is an array with a rank one less than the rank of @var{ARRAY}, and a
7688 size corresponding to the size of @var{ARRAY} with the @var{DIM}
7689 dimension removed. If @var{DIM} is present and @var{ARRAY} has a rank
7690 of one, the result is a scalar. In all cases, the result is of default
7691 @code{INTEGER} type.
7693 @item @emph{See also}:
7694 @ref{MAX}, @ref{MAXVAL}
7701 @section @code{MAXVAL} --- Maximum value of an array
7703 @cindex array, maximum value
7704 @cindex maximum value
7707 @item @emph{Description}:
7708 Determines the maximum value of the elements in an array value, or, if
7709 the @var{DIM} argument is supplied, determines the maximum value along
7710 each row of the array in the @var{DIM} direction. If @var{MASK} is
7711 present, only the elements for which @var{MASK} is @code{.TRUE.} are
7712 considered. If the array has zero size, or all of the elements of
7713 @var{MASK} are @code{.FALSE.}, then the result is @code{-HUGE(ARRAY)}
7714 if @var{ARRAY} is numeric, or a string of nulls if @var{ARRAY} is of character
7717 @item @emph{Standard}:
7718 Fortran 95 and later
7721 Transformational function
7723 @item @emph{Syntax}:
7724 @multitable @columnfractions .80
7725 @item @code{RESULT = MAXVAL(ARRAY, DIM [, MASK])}
7726 @item @code{RESULT = MAXVAL(ARRAY [, MASK])}
7729 @item @emph{Arguments}:
7730 @multitable @columnfractions .15 .70
7731 @item @var{ARRAY} @tab Shall be an array of type @code{INTEGER} or
7733 @item @var{DIM} @tab (Optional) Shall be a scalar of type
7734 @code{INTEGER}, with a value between one and the rank of @var{ARRAY},
7735 inclusive. It may not be an optional dummy argument.
7736 @item @var{MASK} @tab Shall be an array of type @code{LOGICAL},
7737 and conformable with @var{ARRAY}.
7740 @item @emph{Return value}:
7741 If @var{DIM} is absent, or if @var{ARRAY} has a rank of one, the result
7742 is a scalar. If @var{DIM} is present, the result is an array with a
7743 rank one less than the rank of @var{ARRAY}, and a size corresponding to
7744 the size of @var{ARRAY} with the @var{DIM} dimension removed. In all
7745 cases, the result is of the same type and kind as @var{ARRAY}.
7747 @item @emph{See also}:
7748 @ref{MAX}, @ref{MAXLOC}
7754 @section @code{MCLOCK} --- Time function
7756 @cindex time, clock ticks
7760 @item @emph{Description}:
7761 Returns the number of clock ticks since the start of the process, based
7762 on the UNIX function @code{clock(3)}.
7764 This intrinsic is not fully portable, such as to systems with 32-bit
7765 @code{INTEGER} types but supporting times wider than 32 bits. Therefore,
7766 the values returned by this intrinsic might be, or become, negative, or
7767 numerically less than previous values, during a single run of the
7770 @item @emph{Standard}:
7776 @item @emph{Syntax}:
7777 @code{RESULT = MCLOCK()}
7779 @item @emph{Return value}:
7780 The return value is a scalar of type @code{INTEGER(4)}, equal to the
7781 number of clock ticks since the start of the process, or @code{-1} if
7782 the system does not support @code{clock(3)}.
7784 @item @emph{See also}:
7785 @ref{CTIME}, @ref{GMTIME}, @ref{LTIME}, @ref{MCLOCK}, @ref{TIME}
7792 @section @code{MCLOCK8} --- Time function (64-bit)
7794 @cindex time, clock ticks
7798 @item @emph{Description}:
7799 Returns the number of clock ticks since the start of the process, based
7800 on the UNIX function @code{clock(3)}.
7802 @emph{Warning:} this intrinsic does not increase the range of the timing
7803 values over that returned by @code{clock(3)}. On a system with a 32-bit
7804 @code{clock(3)}, @code{MCLOCK8()} will return a 32-bit value, even though
7805 it is converted to a 64-bit @code{INTEGER(8)} value. That means
7806 overflows of the 32-bit value can still occur. Therefore, the values
7807 returned by this intrinsic might be or become negative or numerically
7808 less than previous values during a single run of the compiled program.
7810 @item @emph{Standard}:
7816 @item @emph{Syntax}:
7817 @code{RESULT = MCLOCK8()}
7819 @item @emph{Return value}:
7820 The return value is a scalar of type @code{INTEGER(8)}, equal to the
7821 number of clock ticks since the start of the process, or @code{-1} if
7822 the system does not support @code{clock(3)}.
7824 @item @emph{See also}:
7825 @ref{CTIME}, @ref{GMTIME}, @ref{LTIME}, @ref{MCLOCK}, @ref{TIME8}
7832 @section @code{MERGE} --- Merge variables
7834 @cindex array, merge arrays
7835 @cindex array, combine arrays
7838 @item @emph{Description}:
7839 Select values from two arrays according to a logical mask. The result
7840 is equal to @var{TSOURCE} if @var{MASK} is @code{.TRUE.}, or equal to
7841 @var{FSOURCE} if it is @code{.FALSE.}.
7843 @item @emph{Standard}:
7844 Fortran 95 and later
7849 @item @emph{Syntax}:
7850 @code{RESULT = MERGE(TSOURCE, FSOURCE, MASK)}
7852 @item @emph{Arguments}:
7853 @multitable @columnfractions .15 .70
7854 @item @var{TSOURCE} @tab May be of any type.
7855 @item @var{FSOURCE} @tab Shall be of the same type and type parameters
7857 @item @var{MASK} @tab Shall be of type @code{LOGICAL}.
7860 @item @emph{Return value}:
7861 The result is of the same type and type parameters as @var{TSOURCE}.
7868 @section @code{MIN} --- Minimum value of an argument list
7875 @cindex minimum value
7878 @item @emph{Description}:
7879 Returns the argument with the smallest (most negative) value.
7881 @item @emph{Standard}:
7882 Fortran 77 and later
7887 @item @emph{Syntax}:
7888 @code{RESULT = MIN(A1, A2 [, A3, ...])}
7890 @item @emph{Arguments}:
7891 @multitable @columnfractions .15 .70
7892 @item @var{A1} @tab The type shall be @code{INTEGER} or
7894 @item @var{A2}, @var{A3}, ... @tab An expression of the same type and kind
7895 as @var{A1}. (As a GNU extension, arguments of different kinds are
7899 @item @emph{Return value}:
7900 The return value corresponds to the maximum value among the arguments,
7901 and has the same type and kind as the first argument.
7903 @item @emph{Specific names}:
7904 @multitable @columnfractions .20 .20 .20 .25
7905 @item Name @tab Argument @tab Return type @tab Standard
7906 @item @code{MIN0(A1)} @tab @code{INTEGER(4) A1} @tab @code{INTEGER(4)} @tab Fortran 77 and later
7907 @item @code{AMIN0(A1)} @tab @code{INTEGER(4) A1} @tab @code{REAL(4)} @tab Fortran 77 and later
7908 @item @code{MIN1(A1)} @tab @code{REAL A1} @tab @code{INTEGER(4)} @tab Fortran 77 and later
7909 @item @code{AMIN1(A1)} @tab @code{REAL(4) A1} @tab @code{REAL(4)} @tab Fortran 77 and later
7910 @item @code{DMIN1(A1)} @tab @code{REAL(8) A1} @tab @code{REAL(8)} @tab Fortran 77 and later
7913 @item @emph{See also}:
7914 @ref{MAX}, @ref{MINLOC}, @ref{MINVAL}
7920 @section @code{MINEXPONENT} --- Minimum exponent of a real kind
7921 @fnindex MINEXPONENT
7922 @cindex model representation, minimum exponent
7925 @item @emph{Description}:
7926 @code{MINEXPONENT(X)} returns the minimum exponent in the model of the
7929 @item @emph{Standard}:
7930 Fortran 95 and later
7935 @item @emph{Syntax}:
7936 @code{RESULT = MINEXPONENT(X)}
7938 @item @emph{Arguments}:
7939 @multitable @columnfractions .15 .70
7940 @item @var{X} @tab Shall be of type @code{REAL}.
7943 @item @emph{Return value}:
7944 The return value is of type @code{INTEGER} and of the default integer
7947 @item @emph{Example}:
7948 See @code{MAXEXPONENT} for an example.
7954 @section @code{MINLOC} --- Location of the minimum value within an array
7956 @cindex array, location of minimum element
7959 @item @emph{Description}:
7960 Determines the location of the element in the array with the minimum
7961 value, or, if the @var{DIM} argument is supplied, determines the
7962 locations of the minimum element along each row of the array in the
7963 @var{DIM} direction. If @var{MASK} is present, only the elements for
7964 which @var{MASK} is @code{.TRUE.} are considered. If more than one
7965 element in the array has the minimum value, the location returned is
7966 that of the first such element in array element order. If the array has
7967 zero size, or all of the elements of @var{MASK} are @code{.FALSE.}, then
7968 the result is an array of zeroes. Similarly, if @var{DIM} is supplied
7969 and all of the elements of @var{MASK} along a given row are zero, the
7970 result value for that row is zero.
7972 @item @emph{Standard}:
7973 Fortran 95 and later
7976 Transformational function
7978 @item @emph{Syntax}:
7979 @multitable @columnfractions .80
7980 @item @code{RESULT = MINLOC(ARRAY, DIM [, MASK])}
7981 @item @code{RESULT = MINLOC(ARRAY [, MASK])}
7984 @item @emph{Arguments}:
7985 @multitable @columnfractions .15 .70
7986 @item @var{ARRAY} @tab Shall be an array of type @code{INTEGER} or
7988 @item @var{DIM} @tab (Optional) Shall be a scalar of type
7989 @code{INTEGER}, with a value between one and the rank of @var{ARRAY},
7990 inclusive. It may not be an optional dummy argument.
7991 @item @var{MASK} @tab Shall be an array of type @code{LOGICAL},
7992 and conformable with @var{ARRAY}.
7995 @item @emph{Return value}:
7996 If @var{DIM} is absent, the result is a rank-one array with a length
7997 equal to the rank of @var{ARRAY}. If @var{DIM} is present, the result
7998 is an array with a rank one less than the rank of @var{ARRAY}, and a
7999 size corresponding to the size of @var{ARRAY} with the @var{DIM}
8000 dimension removed. If @var{DIM} is present and @var{ARRAY} has a rank
8001 of one, the result is a scalar. In all cases, the result is of default
8002 @code{INTEGER} type.
8004 @item @emph{See also}:
8005 @ref{MIN}, @ref{MINVAL}
8012 @section @code{MINVAL} --- Minimum value of an array
8014 @cindex array, minimum value
8015 @cindex minimum value
8018 @item @emph{Description}:
8019 Determines the minimum value of the elements in an array value, or, if
8020 the @var{DIM} argument is supplied, determines the minimum value along
8021 each row of the array in the @var{DIM} direction. If @var{MASK} is
8022 present, only the elements for which @var{MASK} is @code{.TRUE.} are
8023 considered. If the array has zero size, or all of the elements of
8024 @var{MASK} are @code{.FALSE.}, then the result is @code{HUGE(ARRAY)} if
8025 @var{ARRAY} is numeric, or a string of @code{CHAR(255)} characters if
8026 @var{ARRAY} is of character type.
8028 @item @emph{Standard}:
8029 Fortran 95 and later
8032 Transformational function
8034 @item @emph{Syntax}:
8035 @multitable @columnfractions .80
8036 @item @code{RESULT = MINVAL(ARRAY, DIM [, MASK])}
8037 @item @code{RESULT = MINVAL(ARRAY [, MASK])}
8040 @item @emph{Arguments}:
8041 @multitable @columnfractions .15 .70
8042 @item @var{ARRAY} @tab Shall be an array of type @code{INTEGER} or
8044 @item @var{DIM} @tab (Optional) Shall be a scalar of type
8045 @code{INTEGER}, with a value between one and the rank of @var{ARRAY},
8046 inclusive. It may not be an optional dummy argument.
8047 @item @var{MASK} @tab Shall be an array of type @code{LOGICAL},
8048 and conformable with @var{ARRAY}.
8051 @item @emph{Return value}:
8052 If @var{DIM} is absent, or if @var{ARRAY} has a rank of one, the result
8053 is a scalar. If @var{DIM} is present, the result is an array with a
8054 rank one less than the rank of @var{ARRAY}, and a size corresponding to
8055 the size of @var{ARRAY} with the @var{DIM} dimension removed. In all
8056 cases, the result is of the same type and kind as @var{ARRAY}.
8058 @item @emph{See also}:
8059 @ref{MIN}, @ref{MINLOC}
8066 @section @code{MOD} --- Remainder function
8071 @cindex division, remainder
8074 @item @emph{Description}:
8075 @code{MOD(A,P)} computes the remainder of the division of A by P@. It is
8076 calculated as @code{A - (INT(A/P) * P)}.
8078 @item @emph{Standard}:
8079 Fortran 77 and later
8084 @item @emph{Syntax}:
8085 @code{RESULT = MOD(A, P)}
8087 @item @emph{Arguments}:
8088 @multitable @columnfractions .15 .70
8089 @item @var{A} @tab Shall be a scalar of type @code{INTEGER} or @code{REAL}
8090 @item @var{P} @tab Shall be a scalar of the same type as @var{A} and not
8094 @item @emph{Return value}:
8095 The kind of the return value is the result of cross-promoting
8096 the kinds of the arguments.
8098 @item @emph{Example}:
8102 print *, mod(17.5,5.5)
8103 print *, mod(17.5d0,5.5)
8104 print *, mod(17.5,5.5d0)
8107 print *, mod(-17.5,5.5)
8108 print *, mod(-17.5d0,5.5)
8109 print *, mod(-17.5,5.5d0)
8112 print *, mod(17.5,-5.5)
8113 print *, mod(17.5d0,-5.5)
8114 print *, mod(17.5,-5.5d0)
8115 end program test_mod
8118 @item @emph{Specific names}:
8119 @multitable @columnfractions .20 .20 .20 .25
8120 @item Name @tab Arguments @tab Return type @tab Standard
8121 @item @code{MOD(A,P)} @tab @code{INTEGER A,P} @tab @code{INTEGER} @tab Fortran 95 and later
8122 @item @code{AMOD(A,P)} @tab @code{REAL(4) A,P} @tab @code{REAL(4)} @tab Fortran 95 and later
8123 @item @code{DMOD(A,P)} @tab @code{REAL(8) A,P} @tab @code{REAL(8)} @tab Fortran 95 and later
8130 @section @code{MODULO} --- Modulo function
8133 @cindex division, modulo
8136 @item @emph{Description}:
8137 @code{MODULO(A,P)} computes the @var{A} modulo @var{P}.
8139 @item @emph{Standard}:
8140 Fortran 95 and later
8145 @item @emph{Syntax}:
8146 @code{RESULT = MODULO(A, P)}
8148 @item @emph{Arguments}:
8149 @multitable @columnfractions .15 .70
8150 @item @var{A} @tab Shall be a scalar of type @code{INTEGER} or @code{REAL}
8151 @item @var{P} @tab Shall be a scalar of the same type and kind as @var{A}
8154 @item @emph{Return value}:
8155 The type and kind of the result are those of the arguments.
8157 @item If @var{A} and @var{P} are of type @code{INTEGER}:
8158 @code{MODULO(A,P)} has the value @var{R} such that @code{A=Q*P+R}, where
8159 @var{Q} is an integer and @var{R} is between 0 (inclusive) and @var{P}
8161 @item If @var{A} and @var{P} are of type @code{REAL}:
8162 @code{MODULO(A,P)} has the value of @code{A - FLOOR (A / P) * P}.
8164 In all cases, if @var{P} is zero the result is processor-dependent.
8166 @item @emph{Example}:
8169 print *, modulo(17,3)
8170 print *, modulo(17.5,5.5)
8172 print *, modulo(-17,3)
8173 print *, modulo(-17.5,5.5)
8175 print *, modulo(17,-3)
8176 print *, modulo(17.5,-5.5)
8185 @section @code{MOVE_ALLOC} --- Move allocation from one object to another
8187 @cindex moving allocation
8188 @cindex allocation, moving
8191 @item @emph{Description}:
8192 @code{MOVE_ALLOC(FROM, TO)} moves the allocation from @var{FROM} to
8193 @var{TO}. @var{FROM} will become deallocated in the process.
8195 @item @emph{Standard}:
8196 Fortran 2003 and later
8201 @item @emph{Syntax}:
8202 @code{CALL MOVE_ALLOC(FROM, TO)}
8204 @item @emph{Arguments}:
8205 @multitable @columnfractions .15 .70
8206 @item @var{FROM} @tab @code{ALLOCATABLE}, @code{INTENT(INOUT)}, may be
8207 of any type and kind.
8208 @item @var{TO} @tab @code{ALLOCATABLE}, @code{INTENT(OUT)}, shall be
8209 of the same type, kind and rank as @var{FROM}.
8212 @item @emph{Return value}:
8215 @item @emph{Example}:
8217 program test_move_alloc
8218 integer, allocatable :: a(:), b(:)
8222 call move_alloc(a, b)
8223 print *, allocated(a), allocated(b)
8225 end program test_move_alloc
8232 @section @code{MVBITS} --- Move bits from one integer to another
8237 @item @emph{Description}:
8238 Moves @var{LEN} bits from positions @var{FROMPOS} through
8239 @code{FROMPOS+LEN-1} of @var{FROM} to positions @var{TOPOS} through
8240 @code{TOPOS+LEN-1} of @var{TO}. The portion of argument @var{TO} not
8241 affected by the movement of bits is unchanged. The values of
8242 @code{FROMPOS+LEN-1} and @code{TOPOS+LEN-1} must be less than
8243 @code{BIT_SIZE(FROM)}.
8245 @item @emph{Standard}:
8246 Fortran 95 and later
8249 Elemental subroutine
8251 @item @emph{Syntax}:
8252 @code{CALL MVBITS(FROM, FROMPOS, LEN, TO, TOPOS)}
8254 @item @emph{Arguments}:
8255 @multitable @columnfractions .15 .70
8256 @item @var{FROM} @tab The type shall be @code{INTEGER}.
8257 @item @var{FROMPOS} @tab The type shall be @code{INTEGER}.
8258 @item @var{LEN} @tab The type shall be @code{INTEGER}.
8259 @item @var{TO} @tab The type shall be @code{INTEGER}, of the
8260 same kind as @var{FROM}.
8261 @item @var{TOPOS} @tab The type shall be @code{INTEGER}.
8264 @item @emph{See also}:
8265 @ref{IBCLR}, @ref{IBSET}, @ref{IBITS}, @ref{IAND}, @ref{IOR}, @ref{IEOR}
8271 @section @code{NEAREST} --- Nearest representable number
8273 @cindex real number, nearest different
8274 @cindex floating point, nearest different
8277 @item @emph{Description}:
8278 @code{NEAREST(X, S)} returns the processor-representable number nearest
8279 to @code{X} in the direction indicated by the sign of @code{S}.
8281 @item @emph{Standard}:
8282 Fortran 95 and later
8287 @item @emph{Syntax}:
8288 @code{RESULT = NEAREST(X, S)}
8290 @item @emph{Arguments}:
8291 @multitable @columnfractions .15 .70
8292 @item @var{X} @tab Shall be of type @code{REAL}.
8293 @item @var{S} @tab (Optional) shall be of type @code{REAL} and
8297 @item @emph{Return value}:
8298 The return value is of the same type as @code{X}. If @code{S} is
8299 positive, @code{NEAREST} returns the processor-representable number
8300 greater than @code{X} and nearest to it. If @code{S} is negative,
8301 @code{NEAREST} returns the processor-representable number smaller than
8302 @code{X} and nearest to it.
8304 @item @emph{Example}:
8306 program test_nearest
8308 x = nearest(42.0, 1.0)
8309 y = nearest(42.0, -1.0)
8310 write (*,"(3(G20.15))") x, y, x - y
8311 end program test_nearest
8318 @section @code{NEW_LINE} --- New line character
8321 @cindex output, newline
8324 @item @emph{Description}:
8325 @code{NEW_LINE(C)} returns the new-line character.
8327 @item @emph{Standard}:
8328 Fortran 2003 and later
8333 @item @emph{Syntax}:
8334 @code{RESULT = NEW_LINE(C)}
8336 @item @emph{Arguments}:
8337 @multitable @columnfractions .15 .70
8338 @item @var{C} @tab The argument shall be a scalar or array of the
8339 type @code{CHARACTER}.
8342 @item @emph{Return value}:
8343 Returns a @var{CHARACTER} scalar of length one with the new-line character of
8344 the same kind as parameter @var{C}.
8346 @item @emph{Example}:
8350 write(*,'(A)') 'This is record 1.'//NEW_LINE('A')//'This is record 2.'
8358 @section @code{NINT} --- Nearest whole number
8361 @cindex rounding, nearest whole number
8364 @item @emph{Description}:
8365 @code{NINT(A)} rounds its argument to the nearest whole number.
8367 @item @emph{Standard}:
8368 Fortran 77 and later, with @var{KIND} argument Fortran 90 and later
8373 @item @emph{Syntax}:
8374 @code{RESULT = NINT(A [, KIND])}
8376 @item @emph{Arguments}:
8377 @multitable @columnfractions .15 .70
8378 @item @var{A} @tab The type of the argument shall be @code{REAL}.
8379 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
8380 expression indicating the kind parameter of the result.
8383 @item @emph{Return value}:
8384 Returns @var{A} with the fractional portion of its magnitude eliminated by
8385 rounding to the nearest whole number and with its sign preserved,
8386 converted to an @code{INTEGER} of the default kind.
8388 @item @emph{Example}:
8395 print *, nint(x4), idnint(x8)
8396 end program test_nint
8399 @item @emph{Specific names}:
8400 @multitable @columnfractions .20 .20 .20 .25
8401 @item Name @tab Argument @tab Return Type @tab Standard
8402 @item @code{NINT(A)} @tab @code{REAL(4) A} @tab @code{INTEGER} @tab Fortran 95 and later
8403 @item @code{IDNINT(A)} @tab @code{REAL(8) A} @tab @code{INTEGER} @tab Fortran 95 and later
8406 @item @emph{See also}:
8407 @ref{CEILING}, @ref{FLOOR}
8414 @section @code{NOT} --- Logical negation
8416 @cindex bits, negate
8417 @cindex bitwise logical not
8418 @cindex logical not, bitwise
8421 @item @emph{Description}:
8422 @code{NOT} returns the bitwise boolean inverse of @var{I}.
8424 @item @emph{Standard}:
8425 Fortran 95 and later
8430 @item @emph{Syntax}:
8431 @code{RESULT = NOT(I)}
8433 @item @emph{Arguments}:
8434 @multitable @columnfractions .15 .70
8435 @item @var{I} @tab The type shall be @code{INTEGER}.
8438 @item @emph{Return value}:
8439 The return type is @code{INTEGER}, of the same kind as the
8442 @item @emph{See also}:
8443 @ref{IAND}, @ref{IEOR}, @ref{IOR}, @ref{IBITS}, @ref{IBSET}, @ref{IBCLR}
8450 @section @code{NULL} --- Function that returns an disassociated pointer
8452 @cindex pointer, status
8453 @cindex pointer, disassociated
8456 @item @emph{Description}:
8457 Returns a disassociated pointer.
8459 If @var{MOLD} is present, a dissassociated pointer of the same type is
8460 returned, otherwise the type is determined by context.
8462 In Fortran 95, @var{MOLD} is optional. Please note that Fortran 2003
8463 includes cases where it is required.
8465 @item @emph{Standard}:
8466 Fortran 95 and later
8469 Transformational function
8471 @item @emph{Syntax}:
8472 @code{PTR => NULL([MOLD])}
8474 @item @emph{Arguments}:
8475 @multitable @columnfractions .15 .70
8476 @item @var{MOLD} @tab (Optional) shall be a pointer of any association
8477 status and of any type.
8480 @item @emph{Return value}:
8481 A disassociated pointer.
8483 @item @emph{Example}:
8485 REAL, POINTER, DIMENSION(:) :: VEC => NULL ()
8488 @item @emph{See also}:
8495 @section @code{NUM_IMAGES} --- Function that returns the number of images
8497 @cindex coarray, NUM_IMAGES
8498 @cindex images, number of
8501 @item @emph{Description}:
8502 Returns the number of images.
8504 @item @emph{Standard}:
8505 Fortran 2008 and later
8508 Transformational function
8510 @item @emph{Syntax}:
8511 @code{RESULT = NUM_IMAGES()}
8513 @item @emph{Arguments}: None.
8515 @item @emph{Return value}:
8516 Scalar default-kind integer.
8518 @item @emph{Example}:
8522 value = THIS_IMAGE()
8524 IF (THIS_IMAGE() == 1) THEN
8525 DO i = 1, NUM_IMAGES()
8526 WRITE(*,'(2(a,i0))') 'value[', i, '] is ', value[i]
8531 @item @emph{See also}:
8532 @ref{THIS_IMAGE}, @ref{IMAGE_INDEX}
8538 @section @code{OR} --- Bitwise logical OR
8540 @cindex bitwise logical or
8541 @cindex logical or, bitwise
8544 @item @emph{Description}:
8545 Bitwise logical @code{OR}.
8547 This intrinsic routine is provided for backwards compatibility with
8548 GNU Fortran 77. For integer arguments, programmers should consider
8549 the use of the @ref{IOR} intrinsic defined by the Fortran standard.
8551 @item @emph{Standard}:
8557 @item @emph{Syntax}:
8558 @code{RESULT = OR(I, J)}
8560 @item @emph{Arguments}:
8561 @multitable @columnfractions .15 .70
8562 @item @var{I} @tab The type shall be either a scalar @code{INTEGER}
8563 type or a scalar @code{LOGICAL} type.
8564 @item @var{J} @tab The type shall be the same as the type of @var{J}.
8567 @item @emph{Return value}:
8568 The return type is either a scalar @code{INTEGER} or a scalar
8569 @code{LOGICAL}. If the kind type parameters differ, then the
8570 smaller kind type is implicitly converted to larger kind, and the
8571 return has the larger kind.
8573 @item @emph{Example}:
8576 LOGICAL :: T = .TRUE., F = .FALSE.
8578 DATA a / Z'F' /, b / Z'3' /
8580 WRITE (*,*) OR(T, T), OR(T, F), OR(F, T), OR(F, F)
8581 WRITE (*,*) OR(a, b)
8585 @item @emph{See also}:
8586 Fortran 95 elemental function: @ref{IOR}
8592 @section @code{PACK} --- Pack an array into an array of rank one
8594 @cindex array, packing
8595 @cindex array, reduce dimension
8596 @cindex array, gather elements
8599 @item @emph{Description}:
8600 Stores the elements of @var{ARRAY} in an array of rank one.
8602 The beginning of the resulting array is made up of elements whose @var{MASK}
8603 equals @code{TRUE}. Afterwards, positions are filled with elements taken from
8606 @item @emph{Standard}:
8607 Fortran 95 and later
8610 Transformational function
8612 @item @emph{Syntax}:
8613 @code{RESULT = PACK(ARRAY, MASK[,VECTOR]}
8615 @item @emph{Arguments}:
8616 @multitable @columnfractions .15 .70
8617 @item @var{ARRAY} @tab Shall be an array of any type.
8618 @item @var{MASK} @tab Shall be an array of type @code{LOGICAL} and
8619 of the same size as @var{ARRAY}. Alternatively, it may be a @code{LOGICAL}
8621 @item @var{VECTOR} @tab (Optional) shall be an array of the same type
8622 as @var{ARRAY} and of rank one. If present, the number of elements in
8623 @var{VECTOR} shall be equal to or greater than the number of true elements
8624 in @var{MASK}. If @var{MASK} is scalar, the number of elements in
8625 @var{VECTOR} shall be equal to or greater than the number of elements in
8629 @item @emph{Return value}:
8630 The result is an array of rank one and the same type as that of @var{ARRAY}.
8631 If @var{VECTOR} is present, the result size is that of @var{VECTOR}, the
8632 number of @code{TRUE} values in @var{MASK} otherwise.
8634 @item @emph{Example}:
8635 Gathering nonzero elements from an array:
8639 m = (/ 1, 0, 0, 0, 5, 0 /)
8640 WRITE(*, FMT="(6(I0, ' '))") pack(m, m /= 0) ! "1 5"
8644 Gathering nonzero elements from an array and appending elements from @var{VECTOR}:
8648 m = (/ 1, 0, 0, 2 /)
8649 WRITE(*, FMT="(4(I0, ' '))") pack(m, m /= 0, (/ 0, 0, 3, 4 /)) ! "1 2 3 4"
8653 @item @emph{See also}:
8660 @section @code{PERROR} --- Print system error message
8662 @cindex system, error handling
8665 @item @emph{Description}:
8666 Prints (on the C @code{stderr} stream) a newline-terminated error
8667 message corresponding to the last system error. This is prefixed by
8668 @var{STRING}, a colon and a space. See @code{perror(3)}.
8670 @item @emph{Standard}:
8676 @item @emph{Syntax}:
8677 @code{CALL PERROR(STRING)}
8679 @item @emph{Arguments}:
8680 @multitable @columnfractions .15 .70
8681 @item @var{STRING} @tab A scalar of type @code{CHARACTER} and of the
8685 @item @emph{See also}:
8692 @section @code{PRECISION} --- Decimal precision of a real kind
8694 @cindex model representation, precision
8697 @item @emph{Description}:
8698 @code{PRECISION(X)} returns the decimal precision in the model of the
8701 @item @emph{Standard}:
8702 Fortran 95 and later
8707 @item @emph{Syntax}:
8708 @code{RESULT = PRECISION(X)}
8710 @item @emph{Arguments}:
8711 @multitable @columnfractions .15 .70
8712 @item @var{X} @tab Shall be of type @code{REAL} or @code{COMPLEX}.
8715 @item @emph{Return value}:
8716 The return value is of type @code{INTEGER} and of the default integer
8719 @item @emph{See also}:
8720 @ref{SELECTED_REAL_KIND}, @ref{RANGE}
8722 @item @emph{Example}:
8724 program prec_and_range
8725 real(kind=4) :: x(2)
8726 complex(kind=8) :: y
8728 print *, precision(x), range(x)
8729 print *, precision(y), range(y)
8730 end program prec_and_range
8737 @section @code{PRESENT} --- Determine whether an optional dummy argument is specified
8741 @item @emph{Description}:
8742 Determines whether an optional dummy argument is present.
8744 @item @emph{Standard}:
8745 Fortran 95 and later
8750 @item @emph{Syntax}:
8751 @code{RESULT = PRESENT(A)}
8753 @item @emph{Arguments}:
8754 @multitable @columnfractions .15 .70
8755 @item @var{A} @tab May be of any type and may be a pointer, scalar or array
8756 value, or a dummy procedure. It shall be the name of an optional dummy argument
8757 accessible within the current subroutine or function.
8760 @item @emph{Return value}:
8761 Returns either @code{TRUE} if the optional argument @var{A} is present, or
8762 @code{FALSE} otherwise.
8764 @item @emph{Example}:
8766 PROGRAM test_present
8767 WRITE(*,*) f(), f(42) ! "F T"
8769 LOGICAL FUNCTION f(x)
8770 INTEGER, INTENT(IN), OPTIONAL :: x
8780 @section @code{PRODUCT} --- Product of array elements
8782 @cindex array, product
8783 @cindex array, multiply elements
8784 @cindex array, conditionally multiply elements
8785 @cindex multiply array elements
8788 @item @emph{Description}:
8789 Multiplies the elements of @var{ARRAY} along dimension @var{DIM} if
8790 the corresponding element in @var{MASK} is @code{TRUE}.
8792 @item @emph{Standard}:
8793 Fortran 95 and later
8796 Transformational function
8798 @item @emph{Syntax}:
8799 @multitable @columnfractions .80
8800 @item @code{RESULT = PRODUCT(ARRAY[, MASK])}
8801 @item @code{RESULT = PRODUCT(ARRAY, DIM[, MASK])}
8804 @item @emph{Arguments}:
8805 @multitable @columnfractions .15 .70
8806 @item @var{ARRAY} @tab Shall be an array of type @code{INTEGER},
8807 @code{REAL} or @code{COMPLEX}.
8808 @item @var{DIM} @tab (Optional) shall be a scalar of type
8809 @code{INTEGER} with a value in the range from 1 to n, where n
8810 equals the rank of @var{ARRAY}.
8811 @item @var{MASK} @tab (Optional) shall be of type @code{LOGICAL}
8812 and either be a scalar or an array of the same shape as @var{ARRAY}.
8815 @item @emph{Return value}:
8816 The result is of the same type as @var{ARRAY}.
8818 If @var{DIM} is absent, a scalar with the product of all elements in
8819 @var{ARRAY} is returned. Otherwise, an array of rank n-1, where n equals
8820 the rank of @var{ARRAY}, and a shape similar to that of @var{ARRAY} with
8821 dimension @var{DIM} dropped is returned.
8824 @item @emph{Example}:
8826 PROGRAM test_product
8827 INTEGER :: x(5) = (/ 1, 2, 3, 4 ,5 /)
8828 print *, PRODUCT(x) ! all elements, product = 120
8829 print *, PRODUCT(x, MASK=MOD(x, 2)==1) ! odd elements, product = 15
8833 @item @emph{See also}:
8840 @section @code{RADIX} --- Base of a model number
8842 @cindex model representation, base
8843 @cindex model representation, radix
8846 @item @emph{Description}:
8847 @code{RADIX(X)} returns the base of the model representing the entity @var{X}.
8849 @item @emph{Standard}:
8850 Fortran 95 and later
8855 @item @emph{Syntax}:
8856 @code{RESULT = RADIX(X)}
8858 @item @emph{Arguments}:
8859 @multitable @columnfractions .15 .70
8860 @item @var{X} @tab Shall be of type @code{INTEGER} or @code{REAL}
8863 @item @emph{Return value}:
8864 The return value is a scalar of type @code{INTEGER} and of the default
8867 @item @emph{See also}:
8868 @ref{SELECTED_REAL_KIND}
8870 @item @emph{Example}:
8873 print *, "The radix for the default integer kind is", radix(0)
8874 print *, "The radix for the default real kind is", radix(0.0)
8875 end program test_radix
8883 @section @code{RAN} --- Real pseudo-random number
8885 @cindex random number generation
8888 @item @emph{Description}:
8889 For compatibility with HP FORTRAN 77/iX, the @code{RAN} intrinsic is
8890 provided as an alias for @code{RAND}. See @ref{RAND} for complete
8893 @item @emph{Standard}:
8899 @item @emph{See also}:
8900 @ref{RAND}, @ref{RANDOM_NUMBER}
8906 @section @code{RAND} --- Real pseudo-random number
8908 @cindex random number generation
8911 @item @emph{Description}:
8912 @code{RAND(FLAG)} returns a pseudo-random number from a uniform
8913 distribution between 0 and 1. If @var{FLAG} is 0, the next number
8914 in the current sequence is returned; if @var{FLAG} is 1, the generator
8915 is restarted by @code{CALL SRAND(0)}; if @var{FLAG} has any other value,
8916 it is used as a new seed with @code{SRAND}.
8918 This intrinsic routine is provided for backwards compatibility with
8919 GNU Fortran 77. It implements a simple modulo generator as provided
8920 by @command{g77}. For new code, one should consider the use of
8921 @ref{RANDOM_NUMBER} as it implements a superior algorithm.
8923 @item @emph{Standard}:
8929 @item @emph{Syntax}:
8930 @code{RESULT = RAND(I)}
8932 @item @emph{Arguments}:
8933 @multitable @columnfractions .15 .70
8934 @item @var{I} @tab Shall be a scalar @code{INTEGER} of kind 4.
8937 @item @emph{Return value}:
8938 The return value is of @code{REAL} type and the default kind.
8940 @item @emph{Example}:
8943 integer,parameter :: seed = 86456
8946 print *, rand(), rand(), rand(), rand()
8947 print *, rand(seed), rand(), rand(), rand()
8948 end program test_rand
8951 @item @emph{See also}:
8952 @ref{SRAND}, @ref{RANDOM_NUMBER}
8959 @section @code{RANDOM_NUMBER} --- Pseudo-random number
8960 @fnindex RANDOM_NUMBER
8961 @cindex random number generation
8964 @item @emph{Description}:
8965 Returns a single pseudorandom number or an array of pseudorandom numbers
8966 from the uniform distribution over the range @math{ 0 \leq x < 1}.
8968 The runtime-library implements George Marsaglia's KISS (Keep It Simple
8969 Stupid) random number generator (RNG). This RNG combines:
8971 @item The congruential generator @math{x(n) = 69069 \cdot x(n-1) + 1327217885}
8972 with a period of @math{2^{32}},
8973 @item A 3-shift shift-register generator with a period of @math{2^{32} - 1},
8974 @item Two 16-bit multiply-with-carry generators with a period of
8975 @math{597273182964842497 > 2^{59}}.
8977 The overall period exceeds @math{2^{123}}.
8979 Please note, this RNG is thread safe if used within OpenMP directives,
8980 i.e., its state will be consistent while called from multiple threads.
8981 However, the KISS generator does not create random numbers in parallel
8982 from multiple sources, but in sequence from a single source. If an
8983 OpenMP-enabled application heavily relies on random numbers, one should
8984 consider employing a dedicated parallel random number generator instead.
8986 @item @emph{Standard}:
8987 Fortran 95 and later
8992 @item @emph{Syntax}:
8993 @code{RANDOM_NUMBER(HARVEST)}
8995 @item @emph{Arguments}:
8996 @multitable @columnfractions .15 .70
8997 @item @var{HARVEST} @tab Shall be a scalar or an array of type @code{REAL}.
9000 @item @emph{Example}:
9002 program test_random_number
9004 CALL init_random_seed() ! see example of RANDOM_SEED
9005 CALL RANDOM_NUMBER(r)
9009 @item @emph{See also}:
9016 @section @code{RANDOM_SEED} --- Initialize a pseudo-random number sequence
9017 @fnindex RANDOM_SEED
9018 @cindex random number generation, seeding
9019 @cindex seeding a random number generator
9022 @item @emph{Description}:
9023 Restarts or queries the state of the pseudorandom number generator used by
9024 @code{RANDOM_NUMBER}.
9026 If @code{RANDOM_SEED} is called without arguments, it is initialized to
9027 a default state. The example below shows how to initialize the random
9028 seed based on the system's time.
9030 @item @emph{Standard}:
9031 Fortran 95 and later
9036 @item @emph{Syntax}:
9037 @code{CALL RANDOM_SEED([SIZE, PUT, GET])}
9039 @item @emph{Arguments}:
9040 @multitable @columnfractions .15 .70
9041 @item @var{SIZE} @tab (Optional) Shall be a scalar and of type default
9042 @code{INTEGER}, with @code{INTENT(OUT)}. It specifies the minimum size
9043 of the arrays used with the @var{PUT} and @var{GET} arguments.
9044 @item @var{PUT} @tab (Optional) Shall be an array of type default
9045 @code{INTEGER} and rank one. It is @code{INTENT(IN)} and the size of
9046 the array must be larger than or equal to the number returned by the
9047 @var{SIZE} argument.
9048 @item @var{GET} @tab (Optional) Shall be an array of type default
9049 @code{INTEGER} and rank one. It is @code{INTENT(OUT)} and the size
9050 of the array must be larger than or equal to the number returned by
9051 the @var{SIZE} argument.
9054 @item @emph{Example}:
9056 SUBROUTINE init_random_seed()
9057 INTEGER :: i, n, clock
9058 INTEGER, DIMENSION(:), ALLOCATABLE :: seed
9060 CALL RANDOM_SEED(size = n)
9063 CALL SYSTEM_CLOCK(COUNT=clock)
9065 seed = clock + 37 * (/ (i - 1, i = 1, n) /)
9066 CALL RANDOM_SEED(PUT = seed)
9072 @item @emph{See also}:
9079 @section @code{RANGE} --- Decimal exponent range
9081 @cindex model representation, range
9084 @item @emph{Description}:
9085 @code{RANGE(X)} returns the decimal exponent range in the model of the
9088 @item @emph{Standard}:
9089 Fortran 95 and later
9094 @item @emph{Syntax}:
9095 @code{RESULT = RANGE(X)}
9097 @item @emph{Arguments}:
9098 @multitable @columnfractions .15 .70
9099 @item @var{X} @tab Shall be of type @code{INTEGER}, @code{REAL}
9103 @item @emph{Return value}:
9104 The return value is of type @code{INTEGER} and of the default integer
9107 @item @emph{See also}:
9108 @ref{SELECTED_REAL_KIND}, @ref{PRECISION}
9110 @item @emph{Example}:
9111 See @code{PRECISION} for an example.
9117 @section @code{REAL} --- Convert to real type
9123 @cindex conversion, to real
9124 @cindex complex numbers, real part
9127 @item @emph{Description}:
9128 @code{REAL(A [, KIND])} converts its argument @var{A} to a real type. The
9129 @code{REALPART} function is provided for compatibility with @command{g77},
9130 and its use is strongly discouraged.
9132 @item @emph{Standard}:
9133 Fortran 77 and later
9138 @item @emph{Syntax}:
9139 @multitable @columnfractions .80
9140 @item @code{RESULT = REAL(A [, KIND])}
9141 @item @code{RESULT = REALPART(Z)}
9144 @item @emph{Arguments}:
9145 @multitable @columnfractions .15 .70
9146 @item @var{A} @tab Shall be @code{INTEGER}, @code{REAL}, or
9148 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
9149 expression indicating the kind parameter of the result.
9152 @item @emph{Return value}:
9153 These functions return a @code{REAL} variable or array under
9154 the following rules:
9158 @code{REAL(A)} is converted to a default real type if @var{A} is an
9159 integer or real variable.
9161 @code{REAL(A)} is converted to a real type with the kind type parameter
9162 of @var{A} if @var{A} is a complex variable.
9164 @code{REAL(A, KIND)} is converted to a real type with kind type
9165 parameter @var{KIND} if @var{A} is a complex, integer, or real
9169 @item @emph{Example}:
9172 complex :: x = (1.0, 2.0)
9173 print *, real(x), real(x,8), realpart(x)
9174 end program test_real
9177 @item @emph{Specific names}:
9178 @multitable @columnfractions .20 .20 .20 .25
9179 @item Name @tab Argument @tab Return type @tab Standard
9180 @item @code{FLOAT(A)} @tab @code{INTEGER(4)} @tab @code{REAL(4)} @tab Fortran 77 and later
9181 @item @code{DFLOAT(A)} @tab @code{INTEGER(4)} @tab @code{REAL(8)} @tab GNU extension
9182 @item @code{SNGL(A)} @tab @code{INTEGER(8)} @tab @code{REAL(4)} @tab Fortran 77 and later
9186 @item @emph{See also}:
9194 @section @code{RENAME} --- Rename a file
9196 @cindex file system, rename file
9199 @item @emph{Description}:
9200 Renames a file from file @var{PATH1} to @var{PATH2}. A null
9201 character (@code{CHAR(0)}) can be used to mark the end of the names in
9202 @var{PATH1} and @var{PATH2}; otherwise, trailing blanks in the file
9203 names are ignored. If the @var{STATUS} argument is supplied, it
9204 contains 0 on success or a nonzero error code upon return; see
9207 This intrinsic is provided in both subroutine and function forms;
9208 however, only one form can be used in any given program unit.
9210 @item @emph{Standard}:
9214 Subroutine, function
9216 @item @emph{Syntax}:
9217 @multitable @columnfractions .80
9218 @item @code{CALL RENAME(PATH1, PATH2 [, STATUS])}
9219 @item @code{STATUS = RENAME(PATH1, PATH2)}
9222 @item @emph{Arguments}:
9223 @multitable @columnfractions .15 .70
9224 @item @var{PATH1} @tab Shall be of default @code{CHARACTER} type.
9225 @item @var{PATH2} @tab Shall be of default @code{CHARACTER} type.
9226 @item @var{STATUS} @tab (Optional) Shall be of default @code{INTEGER} type.
9229 @item @emph{See also}:
9237 @section @code{REPEAT} --- Repeated string concatenation
9239 @cindex string, repeat
9240 @cindex string, concatenate
9243 @item @emph{Description}:
9244 Concatenates @var{NCOPIES} copies of a string.
9246 @item @emph{Standard}:
9247 Fortran 95 and later
9250 Transformational function
9252 @item @emph{Syntax}:
9253 @code{RESULT = REPEAT(STRING, NCOPIES)}
9255 @item @emph{Arguments}:
9256 @multitable @columnfractions .15 .70
9257 @item @var{STRING} @tab Shall be scalar and of type @code{CHARACTER}.
9258 @item @var{NCOPIES} @tab Shall be scalar and of type @code{INTEGER}.
9261 @item @emph{Return value}:
9262 A new scalar of type @code{CHARACTER} built up from @var{NCOPIES} copies
9265 @item @emph{Example}:
9268 write(*,*) repeat("x", 5) ! "xxxxx"
9276 @section @code{RESHAPE} --- Function to reshape an array
9278 @cindex array, change dimensions
9279 @cindex array, transmogrify
9282 @item @emph{Description}:
9283 Reshapes @var{SOURCE} to correspond to @var{SHAPE}. If necessary,
9284 the new array may be padded with elements from @var{PAD} or permuted
9285 as defined by @var{ORDER}.
9287 @item @emph{Standard}:
9288 Fortran 95 and later
9291 Transformational function
9293 @item @emph{Syntax}:
9294 @code{RESULT = RESHAPE(SOURCE, SHAPE[, PAD, ORDER])}
9296 @item @emph{Arguments}:
9297 @multitable @columnfractions .15 .70
9298 @item @var{SOURCE} @tab Shall be an array of any type.
9299 @item @var{SHAPE} @tab Shall be of type @code{INTEGER} and an
9300 array of rank one. Its values must be positive or zero.
9301 @item @var{PAD} @tab (Optional) shall be an array of the same
9302 type as @var{SOURCE}.
9303 @item @var{ORDER} @tab (Optional) shall be of type @code{INTEGER}
9304 and an array of the same shape as @var{SHAPE}. Its values shall
9305 be a permutation of the numbers from 1 to n, where n is the size of
9306 @var{SHAPE}. If @var{ORDER} is absent, the natural ordering shall
9310 @item @emph{Return value}:
9311 The result is an array of shape @var{SHAPE} with the same type as
9314 @item @emph{Example}:
9316 PROGRAM test_reshape
9317 INTEGER, DIMENSION(4) :: x
9318 WRITE(*,*) SHAPE(x) ! prints "4"
9319 WRITE(*,*) SHAPE(RESHAPE(x, (/2, 2/))) ! prints "2 2"
9323 @item @emph{See also}:
9330 @section @code{RRSPACING} --- Reciprocal of the relative spacing
9332 @cindex real number, relative spacing
9333 @cindex floating point, relative spacing
9337 @item @emph{Description}:
9338 @code{RRSPACING(X)} returns the reciprocal of the relative spacing of
9339 model numbers near @var{X}.
9341 @item @emph{Standard}:
9342 Fortran 95 and later
9347 @item @emph{Syntax}:
9348 @code{RESULT = RRSPACING(X)}
9350 @item @emph{Arguments}:
9351 @multitable @columnfractions .15 .70
9352 @item @var{X} @tab Shall be of type @code{REAL}.
9355 @item @emph{Return value}:
9356 The return value is of the same type and kind as @var{X}.
9357 The value returned is equal to
9358 @code{ABS(FRACTION(X)) * FLOAT(RADIX(X))**DIGITS(X)}.
9360 @item @emph{See also}:
9367 @section @code{RSHIFT} --- Right shift bits
9369 @cindex bits, shift right
9372 @item @emph{Description}:
9373 @code{RSHIFT} returns a value corresponding to @var{I} with all of the
9374 bits shifted right by @var{SHIFT} places. If the absolute value of
9375 @var{SHIFT} is greater than @code{BIT_SIZE(I)}, the value is undefined.
9376 Bits shifted out from the left end are lost; zeros are shifted in from
9379 This function has been superseded by the @code{ISHFT} intrinsic, which
9380 is standard in Fortran 95 and later.
9382 @item @emph{Standard}:
9388 @item @emph{Syntax}:
9389 @code{RESULT = RSHIFT(I, SHIFT)}
9391 @item @emph{Arguments}:
9392 @multitable @columnfractions .15 .70
9393 @item @var{I} @tab The type shall be @code{INTEGER}.
9394 @item @var{SHIFT} @tab The type shall be @code{INTEGER}.
9397 @item @emph{Return value}:
9398 The return value is of type @code{INTEGER} and of the same kind as
9401 @item @emph{See also}:
9402 @ref{ISHFT}, @ref{ISHFTC}, @ref{LSHIFT}
9409 @section @code{SCALE} --- Scale a real value
9411 @cindex real number, scale
9412 @cindex floating point, scale
9415 @item @emph{Description}:
9416 @code{SCALE(X,I)} returns @code{X * RADIX(X)**I}.
9418 @item @emph{Standard}:
9419 Fortran 95 and later
9424 @item @emph{Syntax}:
9425 @code{RESULT = SCALE(X, I)}
9427 @item @emph{Arguments}:
9428 @multitable @columnfractions .15 .70
9429 @item @var{X} @tab The type of the argument shall be a @code{REAL}.
9430 @item @var{I} @tab The type of the argument shall be a @code{INTEGER}.
9433 @item @emph{Return value}:
9434 The return value is of the same type and kind as @var{X}.
9435 Its value is @code{X * RADIX(X)**I}.
9437 @item @emph{Example}:
9440 real :: x = 178.1387e-4
9442 print *, scale(x,i), x*radix(x)**i
9443 end program test_scale
9451 @section @code{SCAN} --- Scan a string for the presence of a set of characters
9453 @cindex string, find subset
9456 @item @emph{Description}:
9457 Scans a @var{STRING} for any of the characters in a @var{SET}
9460 If @var{BACK} is either absent or equals @code{FALSE}, this function
9461 returns the position of the leftmost character of @var{STRING} that is
9462 in @var{SET}. If @var{BACK} equals @code{TRUE}, the rightmost position
9463 is returned. If no character of @var{SET} is found in @var{STRING}, the
9466 @item @emph{Standard}:
9467 Fortran 95 and later, with @var{KIND} argument Fortran 2003 and later
9472 @item @emph{Syntax}:
9473 @code{RESULT = SCAN(STRING, SET[, BACK [, KIND]])}
9475 @item @emph{Arguments}:
9476 @multitable @columnfractions .15 .70
9477 @item @var{STRING} @tab Shall be of type @code{CHARACTER}.
9478 @item @var{SET} @tab Shall be of type @code{CHARACTER}.
9479 @item @var{BACK} @tab (Optional) shall be of type @code{LOGICAL}.
9480 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
9481 expression indicating the kind parameter of the result.
9484 @item @emph{Return value}:
9485 The return value is of type @code{INTEGER} and of kind @var{KIND}. If
9486 @var{KIND} is absent, the return value is of default integer kind.
9488 @item @emph{Example}:
9491 WRITE(*,*) SCAN("FORTRAN", "AO") ! 2, found 'O'
9492 WRITE(*,*) SCAN("FORTRAN", "AO", .TRUE.) ! 6, found 'A'
9493 WRITE(*,*) SCAN("FORTRAN", "C++") ! 0, found none
9497 @item @emph{See also}:
9498 @ref{INDEX intrinsic}, @ref{VERIFY}
9504 @section @code{SECNDS} --- Time function
9506 @cindex time, elapsed
9507 @cindex elapsed time
9510 @item @emph{Description}:
9511 @code{SECNDS(X)} gets the time in seconds from the real-time system clock.
9512 @var{X} is a reference time, also in seconds. If this is zero, the time in
9513 seconds from midnight is returned. This function is non-standard and its
9516 @item @emph{Standard}:
9522 @item @emph{Syntax}:
9523 @code{RESULT = SECNDS (X)}
9525 @item @emph{Arguments}:
9526 @multitable @columnfractions .15 .70
9527 @item @var{T} @tab Shall be of type @code{REAL(4)}.
9528 @item @var{X} @tab Shall be of type @code{REAL(4)}.
9531 @item @emph{Return value}:
9534 @item @emph{Example}:
9539 print *, secnds (0.0) ! seconds since midnight
9540 t1 = secnds (0.0) ! reference time
9541 do i = 1, 10000000 ! do something
9543 t2 = secnds (t1) ! elapsed time
9544 print *, "Something took ", t2, " seconds."
9545 end program test_secnds
9552 @section @code{SECOND} --- CPU time function
9554 @cindex time, elapsed
9555 @cindex elapsed time
9558 @item @emph{Description}:
9559 Returns a @code{REAL(4)} value representing the elapsed CPU time in
9560 seconds. This provides the same functionality as the standard
9561 @code{CPU_TIME} intrinsic, and is only included for backwards
9564 This intrinsic is provided in both subroutine and function forms;
9565 however, only one form can be used in any given program unit.
9567 @item @emph{Standard}:
9571 Subroutine, function
9573 @item @emph{Syntax}:
9574 @multitable @columnfractions .80
9575 @item @code{CALL SECOND(TIME)}
9576 @item @code{TIME = SECOND()}
9579 @item @emph{Arguments}:
9580 @multitable @columnfractions .15 .70
9581 @item @var{TIME} @tab Shall be of type @code{REAL(4)}.
9584 @item @emph{Return value}:
9585 In either syntax, @var{TIME} is set to the process's current runtime in
9588 @item @emph{See also}:
9595 @node SELECTED_CHAR_KIND
9596 @section @code{SELECTED_CHAR_KIND} --- Choose character kind
9597 @fnindex SELECTED_CHAR_KIND
9598 @cindex character kind
9599 @cindex kind, character
9602 @item @emph{Description}:
9604 @code{SELECTED_CHAR_KIND(NAME)} returns the kind value for the character
9605 set named @var{NAME}, if a character set with such a name is supported,
9606 or @math{-1} otherwise. Currently, supported character sets include
9607 ``ASCII'' and ``DEFAULT'', which are equivalent.
9609 @item @emph{Standard}:
9610 Fortran 2003 and later
9613 Transformational function
9615 @item @emph{Syntax}:
9616 @code{RESULT = SELECTED_CHAR_KIND(NAME)}
9618 @item @emph{Arguments}:
9619 @multitable @columnfractions .15 .70
9620 @item @var{NAME} @tab Shall be a scalar and of the default character type.
9623 @item @emph{Example}:
9626 integer,parameter :: ascii = selected_char_kind("ascii")
9627 character(kind=ascii, len=26) :: s
9629 s = ascii_"abcdefghijklmnopqrstuvwxyz"
9631 end program ascii_kind
9637 @node SELECTED_INT_KIND
9638 @section @code{SELECTED_INT_KIND} --- Choose integer kind
9639 @fnindex SELECTED_INT_KIND
9640 @cindex integer kind
9641 @cindex kind, integer
9644 @item @emph{Description}:
9645 @code{SELECTED_INT_KIND(R)} return the kind value of the smallest integer
9646 type that can represent all values ranging from @math{-10^R} (exclusive)
9647 to @math{10^R} (exclusive). If there is no integer kind that accommodates
9648 this range, @code{SELECTED_INT_KIND} returns @math{-1}.
9650 @item @emph{Standard}:
9651 Fortran 95 and later
9654 Transformational function
9656 @item @emph{Syntax}:
9657 @code{RESULT = SELECTED_INT_KIND(R)}
9659 @item @emph{Arguments}:
9660 @multitable @columnfractions .15 .70
9661 @item @var{R} @tab Shall be a scalar and of type @code{INTEGER}.
9664 @item @emph{Example}:
9666 program large_integers
9667 integer,parameter :: k5 = selected_int_kind(5)
9668 integer,parameter :: k15 = selected_int_kind(15)
9669 integer(kind=k5) :: i5
9670 integer(kind=k15) :: i15
9672 print *, huge(i5), huge(i15)
9674 ! The following inequalities are always true
9675 print *, huge(i5) >= 10_k5**5-1
9676 print *, huge(i15) >= 10_k15**15-1
9677 end program large_integers
9683 @node SELECTED_REAL_KIND
9684 @section @code{SELECTED_REAL_KIND} --- Choose real kind
9685 @fnindex SELECTED_REAL_KIND
9691 @item @emph{Description}:
9692 @code{SELECTED_REAL_KIND(P,R)} returns the kind value of a real data type
9693 with decimal precision of at least @code{P} digits, exponent range of
9694 at least @code{R}, and with a radix of @code{RADIX}.
9696 @item @emph{Standard}:
9697 Fortran 95 and later, with @code{RADIX} Fortran 2008 or later
9700 Transformational function
9702 @item @emph{Syntax}:
9703 @code{RESULT = SELECTED_REAL_KIND([P, R, RADIX])}
9705 @item @emph{Arguments}:
9706 @multitable @columnfractions .15 .70
9707 @item @var{P} @tab (Optional) shall be a scalar and of type @code{INTEGER}.
9708 @item @var{R} @tab (Optional) shall be a scalar and of type @code{INTEGER}.
9709 @item @var{RADIX} @tab (Optional) shall be a scalar and of type @code{INTEGER}.
9711 Before Fortran 2008, at least one of the arguments @var{R} or @var{P} shall
9712 be present; since Fortran 2008, they are assumed to be zero if absent.
9714 @item @emph{Return value}:
9716 @code{SELECTED_REAL_KIND} returns the value of the kind type parameter of
9717 a real data type with decimal precision of at least @code{P} digits, a
9718 decimal exponent range of at least @code{R}, and with the requested
9719 @code{RADIX}. If the @code{RADIX} parameter is absent, real kinds with
9720 any radix can be returned. If more than one real data type meet the
9721 criteria, the kind of the data type with the smallest decimal precision
9722 is returned. If no real data type matches the criteria, the result is
9724 @item -1 if the processor does not support a real data type with a
9725 precision greater than or equal to @code{P}, but the @code{R} and
9726 @code{RADIX} requirements can be fulfilled
9727 @item -2 if the processor does not support a real type with an exponent
9728 range greater than or equal to @code{R}, but @code{P} and @code{RADIX}
9730 @item -3 if @code{RADIX} but not @code{P} and @code{R} requirements
9732 @item -4 if @code{RADIX} and either @code{P} or @code{R} requirements
9734 @item -5 if there is no real type with the given @code{RADIX}
9737 @item @emph{See also}:
9738 @ref{PRECISION}, @ref{RANGE}, @ref{RADIX}
9740 @item @emph{Example}:
9743 integer,parameter :: p6 = selected_real_kind(6)
9744 integer,parameter :: p10r100 = selected_real_kind(10,100)
9745 integer,parameter :: r400 = selected_real_kind(r=400)
9747 real(kind=p10r100) :: y
9748 real(kind=r400) :: z
9750 print *, precision(x), range(x)
9751 print *, precision(y), range(y)
9752 print *, precision(z), range(z)
9753 end program real_kinds
9760 @section @code{SET_EXPONENT} --- Set the exponent of the model
9761 @fnindex SET_EXPONENT
9762 @cindex real number, set exponent
9763 @cindex floating point, set exponent
9766 @item @emph{Description}:
9767 @code{SET_EXPONENT(X, I)} returns the real number whose fractional part
9768 is that that of @var{X} and whose exponent part is @var{I}.
9770 @item @emph{Standard}:
9771 Fortran 95 and later
9776 @item @emph{Syntax}:
9777 @code{RESULT = SET_EXPONENT(X, I)}
9779 @item @emph{Arguments}:
9780 @multitable @columnfractions .15 .70
9781 @item @var{X} @tab Shall be of type @code{REAL}.
9782 @item @var{I} @tab Shall be of type @code{INTEGER}.
9785 @item @emph{Return value}:
9786 The return value is of the same type and kind as @var{X}.
9787 The real number whose fractional part
9788 is that that of @var{X} and whose exponent part if @var{I} is returned;
9789 it is @code{FRACTION(X) * RADIX(X)**I}.
9791 @item @emph{Example}:
9794 REAL :: x = 178.1387e-4
9796 PRINT *, SET_EXPONENT(x, i), FRACTION(x) * RADIX(x)**i
9805 @section @code{SHAPE} --- Determine the shape of an array
9807 @cindex array, shape
9810 @item @emph{Description}:
9811 Determines the shape of an array.
9813 @item @emph{Standard}:
9814 Fortran 95 and later
9819 @item @emph{Syntax}:
9820 @code{RESULT = SHAPE(SOURCE)}
9822 @item @emph{Arguments}:
9823 @multitable @columnfractions .15 .70
9824 @item @var{SOURCE} @tab Shall be an array or scalar of any type.
9825 If @var{SOURCE} is a pointer it must be associated and allocatable
9826 arrays must be allocated.
9829 @item @emph{Return value}:
9830 An @code{INTEGER} array of rank one with as many elements as @var{SOURCE}
9831 has dimensions. The elements of the resulting array correspond to the extend
9832 of @var{SOURCE} along the respective dimensions. If @var{SOURCE} is a scalar,
9833 the result is the rank one array of size zero.
9835 @item @emph{Example}:
9838 INTEGER, DIMENSION(-1:1, -1:2) :: A
9839 WRITE(*,*) SHAPE(A) ! (/ 3, 4 /)
9840 WRITE(*,*) SIZE(SHAPE(42)) ! (/ /)
9844 @item @emph{See also}:
9845 @ref{RESHAPE}, @ref{SIZE}
9851 @section @code{SIGN} --- Sign copying function
9855 @cindex sign copying
9858 @item @emph{Description}:
9859 @code{SIGN(A,B)} returns the value of @var{A} with the sign of @var{B}.
9861 @item @emph{Standard}:
9862 Fortran 77 and later
9867 @item @emph{Syntax}:
9868 @code{RESULT = SIGN(A, B)}
9870 @item @emph{Arguments}:
9871 @multitable @columnfractions .15 .70
9872 @item @var{A} @tab Shall be of type @code{INTEGER} or @code{REAL}
9873 @item @var{B} @tab Shall be of the same type and kind as @var{A}
9876 @item @emph{Return value}:
9877 The kind of the return value is that of @var{A} and @var{B}.
9878 If @math{B\ge 0} then the result is @code{ABS(A)}, else
9879 it is @code{-ABS(A)}.
9881 @item @emph{Example}:
9884 print *, sign(-12,1)
9885 print *, sign(-12,0)
9886 print *, sign(-12,-1)
9888 print *, sign(-12.,1.)
9889 print *, sign(-12.,0.)
9890 print *, sign(-12.,-1.)
9891 end program test_sign
9894 @item @emph{Specific names}:
9895 @multitable @columnfractions .20 .20 .20 .25
9896 @item Name @tab Arguments @tab Return type @tab Standard
9897 @item @code{SIGN(A,B)} @tab @code{REAL(4) A, B} @tab @code{REAL(4)} @tab f77, gnu
9898 @item @code{ISIGN(A,B)} @tab @code{INTEGER(4) A, B} @tab @code{INTEGER(4)} @tab f77, gnu
9899 @item @code{DSIGN(A,B)} @tab @code{REAL(8) A, B} @tab @code{REAL(8)} @tab f77, gnu
9906 @section @code{SIGNAL} --- Signal handling subroutine (or function)
9908 @cindex system, signal handling
9911 @item @emph{Description}:
9912 @code{SIGNAL(NUMBER, HANDLER [, STATUS])} causes external subroutine
9913 @var{HANDLER} to be executed with a single integer argument when signal
9914 @var{NUMBER} occurs. If @var{HANDLER} is an integer, it can be used to
9915 turn off handling of signal @var{NUMBER} or revert to its default
9916 action. See @code{signal(2)}.
9918 If @code{SIGNAL} is called as a subroutine and the @var{STATUS} argument
9919 is supplied, it is set to the value returned by @code{signal(2)}.
9921 @item @emph{Standard}:
9925 Subroutine, function
9927 @item @emph{Syntax}:
9928 @multitable @columnfractions .80
9929 @item @code{CALL SIGNAL(NUMBER, HANDLER [, STATUS])}
9930 @item @code{STATUS = SIGNAL(NUMBER, HANDLER)}
9933 @item @emph{Arguments}:
9934 @multitable @columnfractions .15 .70
9935 @item @var{NUMBER} @tab Shall be a scalar integer, with @code{INTENT(IN)}
9936 @item @var{HANDLER}@tab Signal handler (@code{INTEGER FUNCTION} or
9937 @code{SUBROUTINE}) or dummy/global @code{INTEGER} scalar.
9938 @code{INTEGER}. It is @code{INTENT(IN)}.
9939 @item @var{STATUS} @tab (Optional) @var{STATUS} shall be a scalar
9940 integer. It has @code{INTENT(OUT)}.
9942 @c TODO: What should the interface of the handler be? Does it take arguments?
9944 @item @emph{Return value}:
9945 The @code{SIGNAL} function returns the value returned by @code{signal(2)}.
9947 @item @emph{Example}:
9951 external handler_print
9953 call signal (12, handler_print)
9957 end program test_signal
9964 @section @code{SIN} --- Sine function
9970 @cindex trigonometric function, sine
9974 @item @emph{Description}:
9975 @code{SIN(X)} computes the sine of @var{X}.
9977 @item @emph{Standard}:
9978 Fortran 77 and later
9983 @item @emph{Syntax}:
9984 @code{RESULT = SIN(X)}
9986 @item @emph{Arguments}:
9987 @multitable @columnfractions .15 .70
9988 @item @var{X} @tab The type shall be @code{REAL} or
9992 @item @emph{Return value}:
9993 The return value has same type and kind as @var{X}.
9995 @item @emph{Example}:
10000 end program test_sin
10003 @item @emph{Specific names}:
10004 @multitable @columnfractions .20 .20 .20 .25
10005 @item Name @tab Argument @tab Return type @tab Standard
10006 @item @code{SIN(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab f77, gnu
10007 @item @code{DSIN(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab f95, gnu
10008 @item @code{CSIN(X)} @tab @code{COMPLEX(4) X} @tab @code{COMPLEX(4)} @tab f95, gnu
10009 @item @code{ZSIN(X)} @tab @code{COMPLEX(8) X} @tab @code{COMPLEX(8)} @tab f95, gnu
10010 @item @code{CDSIN(X)} @tab @code{COMPLEX(8) X} @tab @code{COMPLEX(8)} @tab f95, gnu
10013 @item @emph{See also}:
10020 @section @code{SINH} --- Hyperbolic sine function
10023 @cindex hyperbolic sine
10024 @cindex hyperbolic function, sine
10025 @cindex sine, hyperbolic
10028 @item @emph{Description}:
10029 @code{SINH(X)} computes the hyperbolic sine of @var{X}.
10031 @item @emph{Standard}:
10032 Fortran 95 and later, for a complex argument Fortran 2008 or later
10034 @item @emph{Class}:
10037 @item @emph{Syntax}:
10038 @code{RESULT = SINH(X)}
10040 @item @emph{Arguments}:
10041 @multitable @columnfractions .15 .70
10042 @item @var{X} @tab The type shall be @code{REAL} or @code{COMPLEX}.
10045 @item @emph{Return value}:
10046 The return value has same type and kind as @var{X}.
10048 @item @emph{Example}:
10051 real(8) :: x = - 1.0_8
10053 end program test_sinh
10056 @item @emph{Specific names}:
10057 @multitable @columnfractions .20 .20 .20 .25
10058 @item Name @tab Argument @tab Return type @tab Standard
10059 @item @code{SINH(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab Fortran 95 and later
10060 @item @code{DSINH(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab Fortran 95 and later
10063 @item @emph{See also}:
10070 @section @code{SIZE} --- Determine the size of an array
10072 @cindex array, size
10073 @cindex array, number of elements
10074 @cindex array, count elements
10077 @item @emph{Description}:
10078 Determine the extent of @var{ARRAY} along a specified dimension @var{DIM},
10079 or the total number of elements in @var{ARRAY} if @var{DIM} is absent.
10081 @item @emph{Standard}:
10082 Fortran 95 and later, with @var{KIND} argument Fortran 2003 and later
10084 @item @emph{Class}:
10087 @item @emph{Syntax}:
10088 @code{RESULT = SIZE(ARRAY[, DIM [, KIND]])}
10090 @item @emph{Arguments}:
10091 @multitable @columnfractions .15 .70
10092 @item @var{ARRAY} @tab Shall be an array of any type. If @var{ARRAY} is
10093 a pointer it must be associated and allocatable arrays must be allocated.
10094 @item @var{DIM} @tab (Optional) shall be a scalar of type @code{INTEGER}
10095 and its value shall be in the range from 1 to n, where n equals the rank
10097 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
10098 expression indicating the kind parameter of the result.
10101 @item @emph{Return value}:
10102 The return value is of type @code{INTEGER} and of kind @var{KIND}. If
10103 @var{KIND} is absent, the return value is of default integer kind.
10105 @item @emph{Example}:
10108 WRITE(*,*) SIZE((/ 1, 2 /)) ! 2
10112 @item @emph{See also}:
10113 @ref{SHAPE}, @ref{RESHAPE}
10118 @section @code{SIZEOF} --- Size in bytes of an expression
10120 @cindex expression size
10121 @cindex size of an expression
10124 @item @emph{Description}:
10125 @code{SIZEOF(X)} calculates the number of bytes of storage the
10126 expression @code{X} occupies.
10128 @item @emph{Standard}:
10131 @item @emph{Class}:
10134 @item @emph{Syntax}:
10135 @code{N = SIZEOF(X)}
10137 @item @emph{Arguments}:
10138 @multitable @columnfractions .15 .70
10139 @item @var{X} @tab The argument shall be of any type, rank or shape.
10142 @item @emph{Return value}:
10143 The return value is of type integer and of the system-dependent kind
10144 @var{C_SIZE_T} (from the @var{ISO_C_BINDING} module). Its value is the
10145 number of bytes occupied by the argument. If the argument has the
10146 @code{POINTER} attribute, the number of bytes of the storage area pointed
10147 to is returned. If the argument is of a derived type with @code{POINTER}
10148 or @code{ALLOCATABLE} components, the return value doesn't account for
10149 the sizes of the data pointed to by these components.
10151 @item @emph{Example}:
10155 print *, (sizeof(s)/sizeof(r) == 5)
10158 The example will print @code{.TRUE.} unless you are using a platform
10159 where default @code{REAL} variables are unusually padded.
10161 @item @emph{See also}:
10167 @section @code{SLEEP} --- Sleep for the specified number of seconds
10169 @cindex delayed execution
10172 @item @emph{Description}:
10173 Calling this subroutine causes the process to pause for @var{SECONDS} seconds.
10175 @item @emph{Standard}:
10178 @item @emph{Class}:
10181 @item @emph{Syntax}:
10182 @code{CALL SLEEP(SECONDS)}
10184 @item @emph{Arguments}:
10185 @multitable @columnfractions .15 .70
10186 @item @var{SECONDS} @tab The type shall be of default @code{INTEGER}.
10189 @item @emph{Example}:
10200 @section @code{SPACING} --- Smallest distance between two numbers of a given type
10202 @cindex real number, relative spacing
10203 @cindex floating point, relative spacing
10206 @item @emph{Description}:
10207 Determines the distance between the argument @var{X} and the nearest
10208 adjacent number of the same type.
10210 @item @emph{Standard}:
10211 Fortran 95 and later
10213 @item @emph{Class}:
10216 @item @emph{Syntax}:
10217 @code{RESULT = SPACING(X)}
10219 @item @emph{Arguments}:
10220 @multitable @columnfractions .15 .70
10221 @item @var{X} @tab Shall be of type @code{REAL}.
10224 @item @emph{Return value}:
10225 The result is of the same type as the input argument @var{X}.
10227 @item @emph{Example}:
10229 PROGRAM test_spacing
10230 INTEGER, PARAMETER :: SGL = SELECTED_REAL_KIND(p=6, r=37)
10231 INTEGER, PARAMETER :: DBL = SELECTED_REAL_KIND(p=13, r=200)
10233 WRITE(*,*) spacing(1.0_SGL) ! "1.1920929E-07" on i686
10234 WRITE(*,*) spacing(1.0_DBL) ! "2.220446049250313E-016" on i686
10238 @item @emph{See also}:
10245 @section @code{SPREAD} --- Add a dimension to an array
10247 @cindex array, increase dimension
10248 @cindex array, duplicate elements
10249 @cindex array, duplicate dimensions
10252 @item @emph{Description}:
10253 Replicates a @var{SOURCE} array @var{NCOPIES} times along a specified
10254 dimension @var{DIM}.
10256 @item @emph{Standard}:
10257 Fortran 95 and later
10259 @item @emph{Class}:
10260 Transformational function
10262 @item @emph{Syntax}:
10263 @code{RESULT = SPREAD(SOURCE, DIM, NCOPIES)}
10265 @item @emph{Arguments}:
10266 @multitable @columnfractions .15 .70
10267 @item @var{SOURCE} @tab Shall be a scalar or an array of any type and
10268 a rank less than seven.
10269 @item @var{DIM} @tab Shall be a scalar of type @code{INTEGER} with a
10270 value in the range from 1 to n+1, where n equals the rank of @var{SOURCE}.
10271 @item @var{NCOPIES} @tab Shall be a scalar of type @code{INTEGER}.
10274 @item @emph{Return value}:
10275 The result is an array of the same type as @var{SOURCE} and has rank n+1
10276 where n equals the rank of @var{SOURCE}.
10278 @item @emph{Example}:
10280 PROGRAM test_spread
10281 INTEGER :: a = 1, b(2) = (/ 1, 2 /)
10282 WRITE(*,*) SPREAD(A, 1, 2) ! "1 1"
10283 WRITE(*,*) SPREAD(B, 1, 2) ! "1 1 2 2"
10287 @item @emph{See also}:
10294 @section @code{SQRT} --- Square-root function
10301 @cindex square-root
10304 @item @emph{Description}:
10305 @code{SQRT(X)} computes the square root of @var{X}.
10307 @item @emph{Standard}:
10308 Fortran 77 and later
10310 @item @emph{Class}:
10313 @item @emph{Syntax}:
10314 @code{RESULT = SQRT(X)}
10316 @item @emph{Arguments}:
10317 @multitable @columnfractions .15 .70
10318 @item @var{X} @tab The type shall be @code{REAL} or
10322 @item @emph{Return value}:
10323 The return value is of type @code{REAL} or @code{COMPLEX}.
10324 The kind type parameter is the same as @var{X}.
10326 @item @emph{Example}:
10329 real(8) :: x = 2.0_8
10330 complex :: z = (1.0, 2.0)
10333 end program test_sqrt
10336 @item @emph{Specific names}:
10337 @multitable @columnfractions .20 .20 .20 .25
10338 @item Name @tab Argument @tab Return type @tab Standard
10339 @item @code{SQRT(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab Fortran 95 and later
10340 @item @code{DSQRT(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab Fortran 95 and later
10341 @item @code{CSQRT(X)} @tab @code{COMPLEX(4) X} @tab @code{COMPLEX(4)} @tab Fortran 95 and later
10342 @item @code{ZSQRT(X)} @tab @code{COMPLEX(8) X} @tab @code{COMPLEX(8)} @tab GNU extension
10343 @item @code{CDSQRT(X)} @tab @code{COMPLEX(8) X} @tab @code{COMPLEX(8)} @tab GNU extension
10350 @section @code{SRAND} --- Reinitialize the random number generator
10352 @cindex random number generation, seeding
10353 @cindex seeding a random number generator
10356 @item @emph{Description}:
10357 @code{SRAND} reinitializes the pseudo-random number generator
10358 called by @code{RAND} and @code{IRAND}. The new seed used by the
10359 generator is specified by the required argument @var{SEED}.
10361 @item @emph{Standard}:
10364 @item @emph{Class}:
10367 @item @emph{Syntax}:
10368 @code{CALL SRAND(SEED)}
10370 @item @emph{Arguments}:
10371 @multitable @columnfractions .15 .70
10372 @item @var{SEED} @tab Shall be a scalar @code{INTEGER(kind=4)}.
10375 @item @emph{Return value}:
10376 Does not return anything.
10378 @item @emph{Example}:
10379 See @code{RAND} and @code{IRAND} for examples.
10381 @item @emph{Notes}:
10382 The Fortran 2003 standard specifies the intrinsic @code{RANDOM_SEED} to
10383 initialize the pseudo-random numbers generator and @code{RANDOM_NUMBER}
10384 to generate pseudo-random numbers. Please note that in
10385 GNU Fortran, these two sets of intrinsics (@code{RAND},
10386 @code{IRAND} and @code{SRAND} on the one hand, @code{RANDOM_NUMBER} and
10387 @code{RANDOM_SEED} on the other hand) access two independent
10388 pseudo-random number generators.
10390 @item @emph{See also}:
10391 @ref{RAND}, @ref{RANDOM_SEED}, @ref{RANDOM_NUMBER}
10398 @section @code{STAT} --- Get file status
10400 @cindex file system, file status
10403 @item @emph{Description}:
10404 This function returns information about a file. No permissions are required on
10405 the file itself, but execute (search) permission is required on all of the
10406 directories in path that lead to the file.
10408 The elements that are obtained and stored in the array @code{VALUES}:
10409 @multitable @columnfractions .15 .70
10410 @item @code{VALUES(1)} @tab Device ID
10411 @item @code{VALUES(2)} @tab Inode number
10412 @item @code{VALUES(3)} @tab File mode
10413 @item @code{VALUES(4)} @tab Number of links
10414 @item @code{VALUES(5)} @tab Owner's uid
10415 @item @code{VALUES(6)} @tab Owner's gid
10416 @item @code{VALUES(7)} @tab ID of device containing directory entry for file (0 if not available)
10417 @item @code{VALUES(8)} @tab File size (bytes)
10418 @item @code{VALUES(9)} @tab Last access time
10419 @item @code{VALUES(10)} @tab Last modification time
10420 @item @code{VALUES(11)} @tab Last file status change time
10421 @item @code{VALUES(12)} @tab Preferred I/O block size (-1 if not available)
10422 @item @code{VALUES(13)} @tab Number of blocks allocated (-1 if not available)
10425 Not all these elements are relevant on all systems.
10426 If an element is not relevant, it is returned as 0.
10428 This intrinsic is provided in both subroutine and function forms; however,
10429 only one form can be used in any given program unit.
10431 @item @emph{Standard}:
10434 @item @emph{Class}:
10435 Subroutine, function
10437 @item @emph{Syntax}:
10438 @code{CALL STAT(NAME, VALUES [, STATUS])}
10440 @item @emph{Arguments}:
10441 @multitable @columnfractions .15 .70
10442 @item @var{NAME} @tab The type shall be @code{CHARACTER}, of the
10443 default kind and a valid path within the file system.
10444 @item @var{VALUES} @tab The type shall be @code{INTEGER(4), DIMENSION(13)}.
10445 @item @var{STATUS} @tab (Optional) status flag of type @code{INTEGER(4)}. Returns 0
10446 on success and a system specific error code otherwise.
10449 @item @emph{Example}:
10452 INTEGER, DIMENSION(13) :: buff
10455 CALL STAT("/etc/passwd", buff, status)
10457 IF (status == 0) THEN
10458 WRITE (*, FMT="('Device ID:', T30, I19)") buff(1)
10459 WRITE (*, FMT="('Inode number:', T30, I19)") buff(2)
10460 WRITE (*, FMT="('File mode (octal):', T30, O19)") buff(3)
10461 WRITE (*, FMT="('Number of links:', T30, I19)") buff(4)
10462 WRITE (*, FMT="('Owner''s uid:', T30, I19)") buff(5)
10463 WRITE (*, FMT="('Owner''s gid:', T30, I19)") buff(6)
10464 WRITE (*, FMT="('Device where located:', T30, I19)") buff(7)
10465 WRITE (*, FMT="('File size:', T30, I19)") buff(8)
10466 WRITE (*, FMT="('Last access time:', T30, A19)") CTIME(buff(9))
10467 WRITE (*, FMT="('Last modification time', T30, A19)") CTIME(buff(10))
10468 WRITE (*, FMT="('Last status change time:', T30, A19)") CTIME(buff(11))
10469 WRITE (*, FMT="('Preferred block size:', T30, I19)") buff(12)
10470 WRITE (*, FMT="('No. of blocks allocated:', T30, I19)") buff(13)
10475 @item @emph{See also}:
10476 To stat an open file: @ref{FSTAT}, to stat a link: @ref{LSTAT}
10482 @section @code{SUM} --- Sum of array elements
10485 @cindex array, add elements
10486 @cindex array, conditionally add elements
10487 @cindex sum array elements
10490 @item @emph{Description}:
10491 Adds the elements of @var{ARRAY} along dimension @var{DIM} if
10492 the corresponding element in @var{MASK} is @code{TRUE}.
10494 @item @emph{Standard}:
10495 Fortran 95 and later
10497 @item @emph{Class}:
10498 Transformational function
10500 @item @emph{Syntax}:
10501 @multitable @columnfractions .80
10502 @item @code{RESULT = SUM(ARRAY[, MASK])}
10503 @item @code{RESULT = SUM(ARRAY, DIM[, MASK])}
10506 @item @emph{Arguments}:
10507 @multitable @columnfractions .15 .70
10508 @item @var{ARRAY} @tab Shall be an array of type @code{INTEGER},
10509 @code{REAL} or @code{COMPLEX}.
10510 @item @var{DIM} @tab (Optional) shall be a scalar of type
10511 @code{INTEGER} with a value in the range from 1 to n, where n
10512 equals the rank of @var{ARRAY}.
10513 @item @var{MASK} @tab (Optional) shall be of type @code{LOGICAL}
10514 and either be a scalar or an array of the same shape as @var{ARRAY}.
10517 @item @emph{Return value}:
10518 The result is of the same type as @var{ARRAY}.
10520 If @var{DIM} is absent, a scalar with the sum of all elements in @var{ARRAY}
10521 is returned. Otherwise, an array of rank n-1, where n equals the rank of
10522 @var{ARRAY},and a shape similar to that of @var{ARRAY} with dimension @var{DIM}
10523 dropped is returned.
10525 @item @emph{Example}:
10528 INTEGER :: x(5) = (/ 1, 2, 3, 4 ,5 /)
10529 print *, SUM(x) ! all elements, sum = 15
10530 print *, SUM(x, MASK=MOD(x, 2)==1) ! odd elements, sum = 9
10534 @item @emph{See also}:
10541 @section @code{SYMLNK} --- Create a symbolic link
10543 @cindex file system, create link
10544 @cindex file system, soft link
10547 @item @emph{Description}:
10548 Makes a symbolic link from file @var{PATH1} to @var{PATH2}. A null
10549 character (@code{CHAR(0)}) can be used to mark the end of the names in
10550 @var{PATH1} and @var{PATH2}; otherwise, trailing blanks in the file
10551 names are ignored. If the @var{STATUS} argument is supplied, it
10552 contains 0 on success or a nonzero error code upon return; see
10553 @code{symlink(2)}. If the system does not supply @code{symlink(2)},
10554 @code{ENOSYS} is returned.
10556 This intrinsic is provided in both subroutine and function forms;
10557 however, only one form can be used in any given program unit.
10559 @item @emph{Standard}:
10562 @item @emph{Class}:
10563 Subroutine, function
10565 @item @emph{Syntax}:
10566 @multitable @columnfractions .80
10567 @item @code{CALL SYMLNK(PATH1, PATH2 [, STATUS])}
10568 @item @code{STATUS = SYMLNK(PATH1, PATH2)}
10571 @item @emph{Arguments}:
10572 @multitable @columnfractions .15 .70
10573 @item @var{PATH1} @tab Shall be of default @code{CHARACTER} type.
10574 @item @var{PATH2} @tab Shall be of default @code{CHARACTER} type.
10575 @item @var{STATUS} @tab (Optional) Shall be of default @code{INTEGER} type.
10578 @item @emph{See also}:
10579 @ref{LINK}, @ref{UNLINK}
10586 @section @code{SYSTEM} --- Execute a shell command
10588 @cindex system, system call
10591 @item @emph{Description}:
10592 Passes the command @var{COMMAND} to a shell (see @code{system(3)}). If
10593 argument @var{STATUS} is present, it contains the value returned by
10594 @code{system(3)}, which is presumably 0 if the shell command succeeded.
10595 Note that which shell is used to invoke the command is system-dependent
10596 and environment-dependent.
10598 This intrinsic is provided in both subroutine and function forms;
10599 however, only one form can be used in any given program unit.
10601 @item @emph{Standard}:
10604 @item @emph{Class}:
10605 Subroutine, function
10607 @item @emph{Syntax}:
10608 @multitable @columnfractions .80
10609 @item @code{CALL SYSTEM(COMMAND [, STATUS])}
10610 @item @code{STATUS = SYSTEM(COMMAND)}
10613 @item @emph{Arguments}:
10614 @multitable @columnfractions .15 .70
10615 @item @var{COMMAND} @tab Shall be of default @code{CHARACTER} type.
10616 @item @var{STATUS} @tab (Optional) Shall be of default @code{INTEGER} type.
10619 @item @emph{See also}:
10625 @section @code{SYSTEM_CLOCK} --- Time function
10626 @fnindex SYSTEM_CLOCK
10627 @cindex time, clock ticks
10628 @cindex clock ticks
10631 @item @emph{Description}:
10632 Determines the @var{COUNT} of milliseconds of wall clock time since
10633 the Epoch (00:00:00 UTC, January 1, 1970) modulo @var{COUNT_MAX},
10634 @var{COUNT_RATE} determines the number of clock ticks per second.
10635 @var{COUNT_RATE} and @var{COUNT_MAX} are constant and specific to
10636 @command{gfortran}.
10638 If there is no clock, @var{COUNT} is set to @code{-HUGE(COUNT)}, and
10639 @var{COUNT_RATE} and @var{COUNT_MAX} are set to zero
10641 @item @emph{Standard}:
10642 Fortran 95 and later
10644 @item @emph{Class}:
10647 @item @emph{Syntax}:
10648 @code{CALL SYSTEM_CLOCK([COUNT, COUNT_RATE, COUNT_MAX])}
10650 @item @emph{Arguments}:
10651 @item @emph{Arguments}:
10652 @multitable @columnfractions .15 .70
10653 @item @var{COUNT} @tab (Optional) shall be a scalar of type default
10654 @code{INTEGER} with @code{INTENT(OUT)}.
10655 @item @var{COUNT_RATE} @tab (Optional) shall be a scalar of type default
10656 @code{INTEGER} with @code{INTENT(OUT)}.
10657 @item @var{COUNT_MAX} @tab (Optional) shall be a scalar of type default
10658 @code{INTEGER} with @code{INTENT(OUT)}.
10661 @item @emph{Example}:
10663 PROGRAM test_system_clock
10664 INTEGER :: count, count_rate, count_max
10665 CALL SYSTEM_CLOCK(count, count_rate, count_max)
10666 WRITE(*,*) count, count_rate, count_max
10670 @item @emph{See also}:
10671 @ref{DATE_AND_TIME}, @ref{CPU_TIME}
10677 @section @code{TAN} --- Tangent function
10680 @cindex trigonometric function, tangent
10684 @item @emph{Description}:
10685 @code{TAN(X)} computes the tangent of @var{X}.
10687 @item @emph{Standard}:
10688 Fortran 77 and later, for a complex argument Fortran 2008 or later
10690 @item @emph{Class}:
10693 @item @emph{Syntax}:
10694 @code{RESULT = TAN(X)}
10696 @item @emph{Arguments}:
10697 @multitable @columnfractions .15 .70
10698 @item @var{X} @tab The type shall be @code{REAL} or @code{COMPLEX}.
10701 @item @emph{Return value}:
10702 The return value has same type and kind as @var{X}.
10704 @item @emph{Example}:
10707 real(8) :: x = 0.165_8
10709 end program test_tan
10712 @item @emph{Specific names}:
10713 @multitable @columnfractions .20 .20 .20 .25
10714 @item Name @tab Argument @tab Return type @tab Standard
10715 @item @code{TAN(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab Fortran 95 and later
10716 @item @code{DTAN(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab Fortran 95 and later
10719 @item @emph{See also}:
10726 @section @code{TANH} --- Hyperbolic tangent function
10729 @cindex hyperbolic tangent
10730 @cindex hyperbolic function, tangent
10731 @cindex tangent, hyperbolic
10734 @item @emph{Description}:
10735 @code{TANH(X)} computes the hyperbolic tangent of @var{X}.
10737 @item @emph{Standard}:
10738 Fortran 77 and later, for a complex argument Fortran 2008 or later
10740 @item @emph{Class}:
10743 @item @emph{Syntax}:
10746 @item @emph{Arguments}:
10747 @multitable @columnfractions .15 .70
10748 @item @var{X} @tab The type shall be @code{REAL} or @code{COMPLEX}.
10751 @item @emph{Return value}:
10752 The return value has same type and kind as @var{X}. If @var{X} is
10753 complex, the imaginary part of the result is in radians. If @var{X}
10754 is @code{REAL}, the return value lies in the range
10755 @math{ - 1 \leq tanh(x) \leq 1 }.
10757 @item @emph{Example}:
10760 real(8) :: x = 2.1_8
10762 end program test_tanh
10765 @item @emph{Specific names}:
10766 @multitable @columnfractions .20 .20 .20 .25
10767 @item Name @tab Argument @tab Return type @tab Standard
10768 @item @code{TANH(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab Fortran 95 and later
10769 @item @code{DTANH(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab Fortran 95 and later
10772 @item @emph{See also}:
10779 @section @code{THIS_IMAGE} --- Function that returns the cosubscript index of this image
10780 @fnindex THIS_IMAGE
10781 @cindex coarray, THIS_IMAGE
10782 @cindex images, index of this image
10785 @item @emph{Description}:
10786 Returns the cosubscript for this image.
10788 @item @emph{Standard}:
10789 Fortran 2008 and later
10791 @item @emph{Class}:
10792 Transformational function
10794 @item @emph{Syntax}:
10795 @multitable @columnfractions .80
10796 @item @code{RESULT = THIS_IMAGE()}
10797 @item @code{RESULT = THIS_IMAGE(COARRAY [, DIM])}
10800 @item @emph{Arguments}:
10801 @multitable @columnfractions .15 .70
10802 @item @var{COARRAY} @tab Coarray of any type (optional; if @var{DIM}
10803 present, required).
10804 @item @var{DIM} @tab default integer scalar (optional). If present,
10805 @var{DIM} shall be between one and the corank of @var{COARRAY}.
10809 @item @emph{Return value}:
10810 Default integer. If @var{COARRAY} is not present, it is scalar and its value
10811 is the index of the invoking image. Otherwise, if @var{DIM} is not present,
10812 a rank-1 array with corank elements is returned, containing the cosubscripts
10813 for @var{COARRAY} specifying the invoking image. If @var{DIM} is present,
10814 a scalar is returned, with the value of the @var{DIM} element of
10815 @code{THIS_IMAGE(COARRAY)}.
10817 @item @emph{Example}:
10819 INTEGER :: value[*]
10821 value = THIS_IMAGE()
10823 IF (THIS_IMAGE() == 1) THEN
10824 DO i = 1, NUM_IMAGES()
10825 WRITE(*,'(2(a,i0))') 'value[', i, '] is ', value[i]
10830 @item @emph{See also}:
10831 @ref{NUM_IMAGES}, @ref{IMAGE_INDEX}
10837 @section @code{TIME} --- Time function
10839 @cindex time, current
10840 @cindex current time
10843 @item @emph{Description}:
10844 Returns the current time encoded as an integer (in the manner of the
10845 UNIX function @code{time(3)}). This value is suitable for passing to
10846 @code{CTIME()}, @code{GMTIME()}, and @code{LTIME()}.
10848 This intrinsic is not fully portable, such as to systems with 32-bit
10849 @code{INTEGER} types but supporting times wider than 32 bits. Therefore,
10850 the values returned by this intrinsic might be, or become, negative, or
10851 numerically less than previous values, during a single run of the
10854 See @ref{TIME8}, for information on a similar intrinsic that might be
10855 portable to more GNU Fortran implementations, though to fewer Fortran
10858 @item @emph{Standard}:
10861 @item @emph{Class}:
10864 @item @emph{Syntax}:
10865 @code{RESULT = TIME()}
10867 @item @emph{Return value}:
10868 The return value is a scalar of type @code{INTEGER(4)}.
10870 @item @emph{See also}:
10871 @ref{CTIME}, @ref{GMTIME}, @ref{LTIME}, @ref{MCLOCK}, @ref{TIME8}
10878 @section @code{TIME8} --- Time function (64-bit)
10880 @cindex time, current
10881 @cindex current time
10884 @item @emph{Description}:
10885 Returns the current time encoded as an integer (in the manner of the
10886 UNIX function @code{time(3)}). This value is suitable for passing to
10887 @code{CTIME()}, @code{GMTIME()}, and @code{LTIME()}.
10889 @emph{Warning:} this intrinsic does not increase the range of the timing
10890 values over that returned by @code{time(3)}. On a system with a 32-bit
10891 @code{time(3)}, @code{TIME8()} will return a 32-bit value, even though
10892 it is converted to a 64-bit @code{INTEGER(8)} value. That means
10893 overflows of the 32-bit value can still occur. Therefore, the values
10894 returned by this intrinsic might be or become negative or numerically
10895 less than previous values during a single run of the compiled program.
10897 @item @emph{Standard}:
10900 @item @emph{Class}:
10903 @item @emph{Syntax}:
10904 @code{RESULT = TIME8()}
10906 @item @emph{Return value}:
10907 The return value is a scalar of type @code{INTEGER(8)}.
10909 @item @emph{See also}:
10910 @ref{CTIME}, @ref{GMTIME}, @ref{LTIME}, @ref{MCLOCK8}, @ref{TIME}
10917 @section @code{TINY} --- Smallest positive number of a real kind
10919 @cindex limits, smallest number
10920 @cindex model representation, smallest number
10923 @item @emph{Description}:
10924 @code{TINY(X)} returns the smallest positive (non zero) number
10925 in the model of the type of @code{X}.
10927 @item @emph{Standard}:
10928 Fortran 95 and later
10930 @item @emph{Class}:
10933 @item @emph{Syntax}:
10934 @code{RESULT = TINY(X)}
10936 @item @emph{Arguments}:
10937 @multitable @columnfractions .15 .70
10938 @item @var{X} @tab Shall be of type @code{REAL}.
10941 @item @emph{Return value}:
10942 The return value is of the same type and kind as @var{X}
10944 @item @emph{Example}:
10945 See @code{HUGE} for an example.
10951 @section @code{TRAILZ} --- Number of trailing zero bits of an integer
10956 @item @emph{Description}:
10957 @code{TRAILZ} returns the number of trailing zero bits of an integer.
10959 @item @emph{Standard}:
10960 Fortran 2008 and later
10962 @item @emph{Class}:
10965 @item @emph{Syntax}:
10966 @code{RESULT = TRAILZ(I)}
10968 @item @emph{Arguments}:
10969 @multitable @columnfractions .15 .70
10970 @item @var{I} @tab Shall be of type @code{INTEGER}.
10973 @item @emph{Return value}:
10974 The type of the return value is the default @code{INTEGER}.
10975 If all the bits of @code{I} are zero, the result value is @code{BIT_SIZE(I)}.
10977 @item @emph{Example}:
10979 PROGRAM test_trailz
10980 WRITE (*,*) TRAILZ(8) ! prints 3
10984 @item @emph{See also}:
10985 @ref{BIT_SIZE}, @ref{LEADZ}
10991 @section @code{TRANSFER} --- Transfer bit patterns
10997 @item @emph{Description}:
10998 Interprets the bitwise representation of @var{SOURCE} in memory as if it
10999 is the representation of a variable or array of the same type and type
11000 parameters as @var{MOLD}.
11002 This is approximately equivalent to the C concept of @emph{casting} one
11005 @item @emph{Standard}:
11006 Fortran 95 and later
11008 @item @emph{Class}:
11009 Transformational function
11011 @item @emph{Syntax}:
11012 @code{RESULT = TRANSFER(SOURCE, MOLD[, SIZE])}
11014 @item @emph{Arguments}:
11015 @multitable @columnfractions .15 .70
11016 @item @var{SOURCE} @tab Shall be a scalar or an array of any type.
11017 @item @var{MOLD} @tab Shall be a scalar or an array of any type.
11018 @item @var{SIZE} @tab (Optional) shall be a scalar of type
11022 @item @emph{Return value}:
11023 The result has the same type as @var{MOLD}, with the bit level
11024 representation of @var{SOURCE}. If @var{SIZE} is present, the result is
11025 a one-dimensional array of length @var{SIZE}. If @var{SIZE} is absent
11026 but @var{MOLD} is an array (of any size or shape), the result is a one-
11027 dimensional array of the minimum length needed to contain the entirety
11028 of the bitwise representation of @var{SOURCE}. If @var{SIZE} is absent
11029 and @var{MOLD} is a scalar, the result is a scalar.
11031 If the bitwise representation of the result is longer than that of
11032 @var{SOURCE}, then the leading bits of the result correspond to those of
11033 @var{SOURCE} and any trailing bits are filled arbitrarily.
11035 When the resulting bit representation does not correspond to a valid
11036 representation of a variable of the same type as @var{MOLD}, the results
11037 are undefined, and subsequent operations on the result cannot be
11038 guaranteed to produce sensible behavior. For example, it is possible to
11039 create @code{LOGICAL} variables for which @code{@var{VAR}} and
11040 @code{.NOT.@var{VAR}} both appear to be true.
11042 @item @emph{Example}:
11044 PROGRAM test_transfer
11045 integer :: x = 2143289344
11046 print *, transfer(x, 1.0) ! prints "NaN" on i686
11054 @section @code{TRANSPOSE} --- Transpose an array of rank two
11056 @cindex array, transpose
11057 @cindex matrix, transpose
11061 @item @emph{Description}:
11062 Transpose an array of rank two. Element (i, j) of the result has the value
11063 @code{MATRIX(j, i)}, for all i, j.
11065 @item @emph{Standard}:
11066 Fortran 95 and later
11068 @item @emph{Class}:
11069 Transformational function
11071 @item @emph{Syntax}:
11072 @code{RESULT = TRANSPOSE(MATRIX)}
11074 @item @emph{Arguments}:
11075 @multitable @columnfractions .15 .70
11076 @item @var{MATRIX} @tab Shall be an array of any type and have a rank of two.
11079 @item @emph{Return value}:
11080 The result has the same type as @var{MATRIX}, and has shape
11081 @code{(/ m, n /)} if @var{MATRIX} has shape @code{(/ n, m /)}.
11087 @section @code{TRIM} --- Remove trailing blank characters of a string
11089 @cindex string, remove trailing whitespace
11092 @item @emph{Description}:
11093 Removes trailing blank characters of a string.
11095 @item @emph{Standard}:
11096 Fortran 95 and later
11098 @item @emph{Class}:
11099 Transformational function
11101 @item @emph{Syntax}:
11102 @code{RESULT = TRIM(STRING)}
11104 @item @emph{Arguments}:
11105 @multitable @columnfractions .15 .70
11106 @item @var{STRING} @tab Shall be a scalar of type @code{CHARACTER}.
11109 @item @emph{Return value}:
11110 A scalar of type @code{CHARACTER} which length is that of @var{STRING}
11111 less the number of trailing blanks.
11113 @item @emph{Example}:
11116 CHARACTER(len=10), PARAMETER :: s = "GFORTRAN "
11117 WRITE(*,*) LEN(s), LEN(TRIM(s)) ! "10 8", with/without trailing blanks
11121 @item @emph{See also}:
11122 @ref{ADJUSTL}, @ref{ADJUSTR}
11128 @section @code{TTYNAM} --- Get the name of a terminal device.
11130 @cindex system, terminal
11133 @item @emph{Description}:
11134 Get the name of a terminal device. For more information,
11135 see @code{ttyname(3)}.
11137 This intrinsic is provided in both subroutine and function forms;
11138 however, only one form can be used in any given program unit.
11140 @item @emph{Standard}:
11143 @item @emph{Class}:
11144 Subroutine, function
11146 @item @emph{Syntax}:
11147 @multitable @columnfractions .80
11148 @item @code{CALL TTYNAM(UNIT, NAME)}
11149 @item @code{NAME = TTYNAM(UNIT)}
11152 @item @emph{Arguments}:
11153 @multitable @columnfractions .15 .70
11154 @item @var{UNIT} @tab Shall be a scalar @code{INTEGER}.
11155 @item @var{NAME} @tab Shall be of type @code{CHARACTER}.
11158 @item @emph{Example}:
11160 PROGRAM test_ttynam
11163 IF (isatty(unit=unit)) write(*,*) ttynam(unit)
11168 @item @emph{See also}:
11175 @section @code{UBOUND} --- Upper dimension bounds of an array
11177 @cindex array, upper bound
11180 @item @emph{Description}:
11181 Returns the upper bounds of an array, or a single upper bound
11182 along the @var{DIM} dimension.
11183 @item @emph{Standard}:
11184 Fortran 95 and later, with @var{KIND} argument Fortran 2003 and later
11186 @item @emph{Class}:
11189 @item @emph{Syntax}:
11190 @code{RESULT = UBOUND(ARRAY [, DIM [, KIND]])}
11192 @item @emph{Arguments}:
11193 @multitable @columnfractions .15 .70
11194 @item @var{ARRAY} @tab Shall be an array, of any type.
11195 @item @var{DIM} @tab (Optional) Shall be a scalar @code{INTEGER}.
11196 @item @var{KIND}@tab (Optional) An @code{INTEGER} initialization
11197 expression indicating the kind parameter of the result.
11200 @item @emph{Return value}:
11201 The return value is of type @code{INTEGER} and of kind @var{KIND}. If
11202 @var{KIND} is absent, the return value is of default integer kind.
11203 If @var{DIM} is absent, the result is an array of the upper bounds of
11204 @var{ARRAY}. If @var{DIM} is present, the result is a scalar
11205 corresponding to the upper bound of the array along that dimension. If
11206 @var{ARRAY} is an expression rather than a whole array or array
11207 structure component, or if it has a zero extent along the relevant
11208 dimension, the upper bound is taken to be the number of elements along
11209 the relevant dimension.
11211 @item @emph{See also}:
11212 @ref{LBOUND}, @ref{LCOBOUND}
11218 @section @code{UCOBOUND} --- Upper codimension bounds of an array
11220 @cindex coarray, upper bound
11223 @item @emph{Description}:
11224 Returns the upper cobounds of a coarray, or a single upper cobound
11225 along the @var{DIM} codimension.
11226 @item @emph{Standard}:
11227 Fortran 2008 and later
11229 @item @emph{Class}:
11232 @item @emph{Syntax}:
11233 @code{RESULT = UCOBOUND(COARRAY [, DIM [, KIND]])}
11235 @item @emph{Arguments}:
11236 @multitable @columnfractions .15 .70
11237 @item @var{ARRAY} @tab Shall be an coarray, of any type.
11238 @item @var{DIM} @tab (Optional) Shall be a scalar @code{INTEGER}.
11239 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
11240 expression indicating the kind parameter of the result.
11243 @item @emph{Return value}:
11244 The return value is of type @code{INTEGER} and of kind @var{KIND}. If
11245 @var{KIND} is absent, the return value is of default integer kind.
11246 If @var{DIM} is absent, the result is an array of the lower cobounds of
11247 @var{COARRAY}. If @var{DIM} is present, the result is a scalar
11248 corresponding to the lower cobound of the array along that codimension.
11250 @item @emph{See also}:
11251 @ref{LCOBOUND}, @ref{LBOUND}
11257 @section @code{UMASK} --- Set the file creation mask
11259 @cindex file system, file creation mask
11262 @item @emph{Description}:
11263 Sets the file creation mask to @var{MASK}. If called as a function, it
11264 returns the old value. If called as a subroutine and argument @var{OLD}
11265 if it is supplied, it is set to the old value. See @code{umask(2)}.
11267 @item @emph{Standard}:
11270 @item @emph{Class}:
11271 Subroutine, function
11273 @item @emph{Syntax}:
11274 @code{CALL UMASK(MASK [, OLD])}
11275 @code{OLD = UMASK(MASK)}
11277 @item @emph{Arguments}:
11278 @multitable @columnfractions .15 .70
11279 @item @var{MASK} @tab Shall be a scalar of type @code{INTEGER}.
11280 @item @var{OLD} @tab (Optional) Shall be a scalar of type
11289 @section @code{UNLINK} --- Remove a file from the file system
11291 @cindex file system, remove file
11294 @item @emph{Description}:
11295 Unlinks the file @var{PATH}. A null character (@code{CHAR(0)}) can be
11296 used to mark the end of the name in @var{PATH}; otherwise, trailing
11297 blanks in the file name are ignored. If the @var{STATUS} argument is
11298 supplied, it contains 0 on success or a nonzero error code upon return;
11299 see @code{unlink(2)}.
11301 This intrinsic is provided in both subroutine and function forms;
11302 however, only one form can be used in any given program unit.
11304 @item @emph{Standard}:
11307 @item @emph{Class}:
11308 Subroutine, function
11310 @item @emph{Syntax}:
11311 @multitable @columnfractions .80
11312 @item @code{CALL UNLINK(PATH [, STATUS])}
11313 @item @code{STATUS = UNLINK(PATH)}
11316 @item @emph{Arguments}:
11317 @multitable @columnfractions .15 .70
11318 @item @var{PATH} @tab Shall be of default @code{CHARACTER} type.
11319 @item @var{STATUS} @tab (Optional) Shall be of default @code{INTEGER} type.
11322 @item @emph{See also}:
11323 @ref{LINK}, @ref{SYMLNK}
11329 @section @code{UNPACK} --- Unpack an array of rank one into an array
11331 @cindex array, unpacking
11332 @cindex array, increase dimension
11333 @cindex array, scatter elements
11336 @item @emph{Description}:
11337 Store the elements of @var{VECTOR} in an array of higher rank.
11339 @item @emph{Standard}:
11340 Fortran 95 and later
11342 @item @emph{Class}:
11343 Transformational function
11345 @item @emph{Syntax}:
11346 @code{RESULT = UNPACK(VECTOR, MASK, FIELD)}
11348 @item @emph{Arguments}:
11349 @multitable @columnfractions .15 .70
11350 @item @var{VECTOR} @tab Shall be an array of any type and rank one. It
11351 shall have at least as many elements as @var{MASK} has @code{TRUE} values.
11352 @item @var{MASK} @tab Shall be an array of type @code{LOGICAL}.
11353 @item @var{FIELD} @tab Shall be of the same type as @var{VECTOR} and have
11354 the same shape as @var{MASK}.
11357 @item @emph{Return value}:
11358 The resulting array corresponds to @var{FIELD} with @code{TRUE} elements
11359 of @var{MASK} replaced by values from @var{VECTOR} in array element order.
11361 @item @emph{Example}:
11363 PROGRAM test_unpack
11364 integer :: vector(2) = (/1,1/)
11365 logical :: mask(4) = (/ .TRUE., .FALSE., .FALSE., .TRUE. /)
11366 integer :: field(2,2) = 0, unity(2,2)
11368 ! result: unity matrix
11369 unity = unpack(vector, reshape(mask, (/2,2/)), field)
11373 @item @emph{See also}:
11374 @ref{PACK}, @ref{SPREAD}
11380 @section @code{VERIFY} --- Scan a string for the absence of a set of characters
11382 @cindex string, find missing set
11385 @item @emph{Description}:
11386 Verifies that all the characters in a @var{SET} are present in a @var{STRING}.
11388 If @var{BACK} is either absent or equals @code{FALSE}, this function
11389 returns the position of the leftmost character of @var{STRING} that is
11390 not in @var{SET}. If @var{BACK} equals @code{TRUE}, the rightmost position
11391 is returned. If all characters of @var{SET} are found in @var{STRING}, the
11394 @item @emph{Standard}:
11395 Fortran 95 and later, with @var{KIND} argument Fortran 2003 and later
11397 @item @emph{Class}:
11400 @item @emph{Syntax}:
11401 @code{RESULT = VERIFY(STRING, SET[, BACK [, KIND]])}
11403 @item @emph{Arguments}:
11404 @multitable @columnfractions .15 .70
11405 @item @var{STRING} @tab Shall be of type @code{CHARACTER}.
11406 @item @var{SET} @tab Shall be of type @code{CHARACTER}.
11407 @item @var{BACK} @tab (Optional) shall be of type @code{LOGICAL}.
11408 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
11409 expression indicating the kind parameter of the result.
11412 @item @emph{Return value}:
11413 The return value is of type @code{INTEGER} and of kind @var{KIND}. If
11414 @var{KIND} is absent, the return value is of default integer kind.
11416 @item @emph{Example}:
11418 PROGRAM test_verify
11419 WRITE(*,*) VERIFY("FORTRAN", "AO") ! 1, found 'F'
11420 WRITE(*,*) VERIFY("FORTRAN", "FOO") ! 3, found 'R'
11421 WRITE(*,*) VERIFY("FORTRAN", "C++") ! 1, found 'F'
11422 WRITE(*,*) VERIFY("FORTRAN", "C++", .TRUE.) ! 7, found 'N'
11423 WRITE(*,*) VERIFY("FORTRAN", "FORTRAN") ! 0' found none
11427 @item @emph{See also}:
11428 @ref{SCAN}, @ref{INDEX intrinsic}
11434 @section @code{XOR} --- Bitwise logical exclusive OR
11436 @cindex bitwise logical exclusive or
11437 @cindex logical exclusive or, bitwise
11440 @item @emph{Description}:
11441 Bitwise logical exclusive or.
11443 This intrinsic routine is provided for backwards compatibility with
11444 GNU Fortran 77. For integer arguments, programmers should consider
11445 the use of the @ref{IEOR} intrinsic and for logical arguments the
11446 @code{.NEQV.} operator, which are both defined by the Fortran standard.
11448 @item @emph{Standard}:
11451 @item @emph{Class}:
11454 @item @emph{Syntax}:
11455 @code{RESULT = XOR(I, J)}
11457 @item @emph{Arguments}:
11458 @multitable @columnfractions .15 .70
11459 @item @var{I} @tab The type shall be either a scalar @code{INTEGER}
11460 type or a scalar @code{LOGICAL} type.
11461 @item @var{J} @tab The type shall be the same as the type of @var{I}.
11464 @item @emph{Return value}:
11465 The return type is either a scalar @code{INTEGER} or a scalar
11466 @code{LOGICAL}. If the kind type parameters differ, then the
11467 smaller kind type is implicitly converted to larger kind, and the
11468 return has the larger kind.
11470 @item @emph{Example}:
11473 LOGICAL :: T = .TRUE., F = .FALSE.
11475 DATA a / Z'F' /, b / Z'3' /
11477 WRITE (*,*) XOR(T, T), XOR(T, F), XOR(F, T), XOR(F, F)
11478 WRITE (*,*) XOR(a, b)
11482 @item @emph{See also}:
11483 Fortran 95 elemental function: @ref{IEOR}
11488 @node Intrinsic Modules
11489 @chapter Intrinsic Modules
11490 @cindex intrinsic Modules
11493 * ISO_FORTRAN_ENV::
11495 * OpenMP Modules OMP_LIB and OMP_LIB_KINDS::
11498 @node ISO_FORTRAN_ENV
11499 @section @code{ISO_FORTRAN_ENV}
11501 @item @emph{Standard}:
11502 Fortran 2003 and later, except when otherwise noted
11505 The @code{ISO_FORTRAN_ENV} module provides the following scalar default-integer
11509 @item @code{ATOMIC_INT_KIND}:
11510 Default-kind integer constant to be used as kind parameter when defining
11511 integer variables used in atomic operations. (Fortran 2008 or later.)
11513 @item @code{ATOMIC_LOGICAL_KIND}:
11514 Default-kind integer constant to be used as kind parameter when defining
11515 logical variables used in atomic operations. (Fortran 2008 or later.)
11517 @item @code{CHARACTER_STORAGE_SIZE}:
11518 Size in bits of the character storage unit.
11520 @item @code{ERROR_UNIT}:
11521 Identifies the preconnected unit used for error reporting.
11523 @item @code{FILE_STORAGE_SIZE}:
11524 Size in bits of the file-storage unit.
11526 @item @code{INPUT_UNIT}:
11527 Identifies the preconnected unit identified by the asterisk
11528 (@code{*}) in @code{READ} statement.
11530 @item @code{INT8}, @code{INT16}, @code{INT32}, @code{INT64}:
11531 Kind type parameters to specify an INTEGER type with a storage
11532 size of 16, 32, and 64 bits. It is negative if a target platform
11533 does not support the particular kind. (Fortran 2008 or later.)
11535 @item @code{IOSTAT_END}:
11536 The value assigned to the variable passed to the IOSTAT= specifier of
11537 an input/output statement if an end-of-file condition occurred.
11539 @item @code{IOSTAT_EOR}:
11540 The value assigned to the variable passed to the IOSTAT= specifier of
11541 an input/output statement if an end-of-record condition occurred.
11543 @item @code{IOSTAT_INQUIRE_INTERNAL_UNIT}:
11544 Scalar default-integer constant, used by @code{INQUIRE} for the
11545 IOSTAT= specifier to denote an that a unit number identifies an
11546 internal unit. (Fortran 2008 or later.)
11548 @item @code{NUMERIC_STORAGE_SIZE}:
11549 The size in bits of the numeric storage unit.
11551 @item @code{OUTPUT_UNIT}:
11552 Identifies the preconnected unit identified by the asterisk
11553 (@code{*}) in @code{WRITE} statement.
11555 @item @code{REAL32}, @code{REAL64}, @code{REAL128}:
11556 Kind type parameters to specify a REAL type with a storage
11557 size of 32, 64, and 128 bits. It is negative if a target platform
11558 does not support the particular kind. (Fortran 2008 or later.)
11560 @item @code{STAT_LOCKED}:
11561 Scalar default-integer constant used as STAT= return value by @code{LOCK} to
11562 denote that the lock variable is locked by the executing image. (Fortran 2008
11565 @item @code{STAT_LOCKED_OTHER_IMAGE}:
11566 Scalar default-integer constant used as STAT= return value by @code{UNLOCK} to
11567 denote that the lock variable is locked by another image. (Fortran 2008 or
11570 @item @code{STAT_STOPPED_IMAGE}:
11571 Positive, scalar default-integer constant used as STAT= return value if the
11572 argument in the statement requires synchronisation with an image, which has
11573 initiated the termination of the execution. (Fortran 2008 or later.)
11575 @item @code{STAT_UNLOCKED}:
11576 Scalar default-integer constant used as STAT= return value by @code{UNLOCK} to
11577 denote that the lock variable is unlocked. (Fortran 2008 or later.)
11582 @node ISO_C_BINDING
11583 @section @code{ISO_C_BINDING}
11585 @item @emph{Standard}:
11586 Fortran 2003 and later, GNU extensions
11589 The following intrinsic procedures are provided by the module; their
11590 definition can be found in the section Intrinsic Procedures of this
11594 @item @code{C_ASSOCIATED}
11595 @item @code{C_F_POINTER}
11596 @item @code{C_F_PROCPOINTER}
11597 @item @code{C_FUNLOC}
11600 @c TODO: Vertical spacing between C_FUNLOC and C_LOC wrong in PDF,
11601 @c don't really know why.
11603 The @code{ISO_C_BINDING} module provides the following named constants of
11604 type default integer, which can be used as KIND type parameters.
11606 In addition to the integer named constants required by the Fortran 2003
11607 standard, GNU Fortran provides as an extension named constants for the
11608 128-bit integer types supported by the C compiler: @code{C_INT128_T,
11609 C_INT_LEAST128_T, C_INT_FAST128_T}.
11611 @multitable @columnfractions .15 .35 .35 .35
11612 @item Fortran Type @tab Named constant @tab C type @tab Extension
11613 @item @code{INTEGER}@tab @code{C_INT} @tab @code{int}
11614 @item @code{INTEGER}@tab @code{C_SHORT} @tab @code{short int}
11615 @item @code{INTEGER}@tab @code{C_LONG} @tab @code{long int}
11616 @item @code{INTEGER}@tab @code{C_LONG_LONG} @tab @code{long long int}
11617 @item @code{INTEGER}@tab @code{C_SIGNED_CHAR} @tab @code{signed char}/@code{unsigned char}
11618 @item @code{INTEGER}@tab @code{C_SIZE_T} @tab @code{size_t}
11619 @item @code{INTEGER}@tab @code{C_INT8_T} @tab @code{int8_t}
11620 @item @code{INTEGER}@tab @code{C_INT16_T} @tab @code{int16_t}
11621 @item @code{INTEGER}@tab @code{C_INT32_T} @tab @code{int32_t}
11622 @item @code{INTEGER}@tab @code{C_INT64_T} @tab @code{int64_t}
11623 @item @code{INTEGER}@tab @code{C_INT128_T} @tab @code{int128_t} @tab Ext.
11624 @item @code{INTEGER}@tab @code{C_INT_LEAST8_T} @tab @code{int_least8_t}
11625 @item @code{INTEGER}@tab @code{C_INT_LEAST16_T} @tab @code{int_least16_t}
11626 @item @code{INTEGER}@tab @code{C_INT_LEAST32_T} @tab @code{int_least32_t}
11627 @item @code{INTEGER}@tab @code{C_INT_LEAST64_T} @tab @code{int_least64_t}
11628 @item @code{INTEGER}@tab @code{C_INT_LEAST128_T}@tab @code{int_least128_t} @tab Ext.
11629 @item @code{INTEGER}@tab @code{C_INT_FAST8_T} @tab @code{int_fast8_t}
11630 @item @code{INTEGER}@tab @code{C_INT_FAST16_T} @tab @code{int_fast16_t}
11631 @item @code{INTEGER}@tab @code{C_INT_FAST32_T} @tab @code{int_fast32_t}
11632 @item @code{INTEGER}@tab @code{C_INT_FAST64_T} @tab @code{int_fast64_t}
11633 @item @code{INTEGER}@tab @code{C_INT_FAST128_T} @tab @code{int_fast128_t} @tab Ext.
11634 @item @code{INTEGER}@tab @code{C_INTMAX_T} @tab @code{intmax_t}
11635 @item @code{INTEGER}@tab @code{C_INTPTR_T} @tab @code{intptr_t}
11636 @item @code{REAL} @tab @code{C_FLOAT} @tab @code{float}
11637 @item @code{REAL} @tab @code{C_DOUBLE} @tab @code{double}
11638 @item @code{REAL} @tab @code{C_LONG_DOUBLE} @tab @code{long double}
11639 @item @code{COMPLEX}@tab @code{C_FLOAT_COMPLEX} @tab @code{float _Complex}
11640 @item @code{COMPLEX}@tab @code{C_DOUBLE_COMPLEX}@tab @code{double _Complex}
11641 @item @code{COMPLEX}@tab @code{C_LONG_DOUBLE_COMPLEX}@tab @code{long double _Complex}
11642 @item @code{LOGICAL}@tab @code{C_BOOL} @tab @code{_Bool}
11643 @item @code{CHARACTER}@tab @code{C_CHAR} @tab @code{char}
11646 Additionally, the following parameters of type @code{CHARACTER(KIND=C_CHAR)}
11649 @multitable @columnfractions .20 .45 .15
11650 @item Name @tab C definition @tab Value
11651 @item @code{C_NULL_CHAR} @tab null character @tab @code{'\0'}
11652 @item @code{C_ALERT} @tab alert @tab @code{'\a'}
11653 @item @code{C_BACKSPACE} @tab backspace @tab @code{'\b'}
11654 @item @code{C_FORM_FEED} @tab form feed @tab @code{'\f'}
11655 @item @code{C_NEW_LINE} @tab new line @tab @code{'\n'}
11656 @item @code{C_CARRIAGE_RETURN} @tab carriage return @tab @code{'\r'}
11657 @item @code{C_HORIZONTAL_TAB} @tab horizontal tab @tab @code{'\t'}
11658 @item @code{C_VERTICAL_TAB} @tab vertical tab @tab @code{'\v'}
11661 @node OpenMP Modules OMP_LIB and OMP_LIB_KINDS
11662 @section OpenMP Modules @code{OMP_LIB} and @code{OMP_LIB_KINDS}
11664 @item @emph{Standard}:
11665 OpenMP Application Program Interface v3.0
11669 The OpenMP Fortran runtime library routines are provided both in
11670 a form of two Fortran 90 modules, named @code{OMP_LIB} and
11671 @code{OMP_LIB_KINDS}, and in a form of a Fortran @code{include} file named
11672 @file{omp_lib.h}. The procedures provided by @code{OMP_LIB} can be found
11673 in the @ref{Top,,Introduction,libgomp,GNU OpenMP runtime library} manual,
11674 the named constants defined in the @code{OMP_LIB_KINDS} module are listed
11677 For details refer to the actual
11678 @uref{http://www.openmp.org/mp-documents/spec30.pdf,
11679 OpenMP Application Program Interface v3.0}.
11681 @code{OMP_LIB_KINDS} provides the following scalar default-integer
11685 @item @code{omp_integer_kind}
11686 @item @code{omp_logical_kind}
11687 @item @code{omp_lock_kind}
11688 @item @code{omp_nest_lock_kind}
11689 @item @code{omp_sched_kind}