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.2 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{DFLOAT}: DFLOAT, Double precision conversion function
96 * @code{DIGITS}: DIGITS, Significant digits function
97 * @code{DIM}: DIM, Positive difference
98 * @code{DOT_PRODUCT}: DOT_PRODUCT, Dot product function
99 * @code{DPROD}: DPROD, Double product function
100 * @code{DREAL}: DREAL, Double real part function
101 * @code{DTIME}: DTIME, Execution time subroutine (or function)
102 * @code{EOSHIFT}: EOSHIFT, End-off shift elements of an array
103 * @code{EPSILON}: EPSILON, Epsilon function
104 * @code{ERF}: ERF, Error function
105 * @code{ERFC}: ERFC, Complementary error function
106 * @code{ERFC_SCALED}: ERFC_SCALED, Exponentially-scaled complementary error function
107 * @code{ETIME}: ETIME, Execution time subroutine (or function)
108 * @code{EXIT}: EXIT, Exit the program with status.
109 * @code{EXP}: EXP, Exponential function
110 * @code{EXPONENT}: EXPONENT, Exponent function
111 * @code{FDATE}: FDATE, Subroutine (or function) to get the current time as a string
112 * @code{FGET}: FGET, Read a single character in stream mode from stdin
113 * @code{FGETC}: FGETC, Read a single character in stream mode
114 * @code{FLOAT}: FLOAT, Convert integer to default real
115 * @code{FLOOR}: FLOOR, Integer floor function
116 * @code{FLUSH}: FLUSH, Flush I/O unit(s)
117 * @code{FNUM}: FNUM, File number function
118 * @code{FPUT}: FPUT, Write a single character in stream mode to stdout
119 * @code{FPUTC}: FPUTC, Write a single character in stream mode
120 * @code{FRACTION}: FRACTION, Fractional part of the model representation
121 * @code{FREE}: FREE, Memory de-allocation subroutine
122 * @code{FSEEK}: FSEEK, Low level file positioning subroutine
123 * @code{FSTAT}: FSTAT, Get file status
124 * @code{FTELL}: FTELL, Current stream position
125 * @code{GAMMA}: GAMMA, Gamma function
126 * @code{GERROR}: GERROR, Get last system error message
127 * @code{GETARG}: GETARG, Get command line arguments
128 * @code{GET_COMMAND}: GET_COMMAND, Get the entire command line
129 * @code{GET_COMMAND_ARGUMENT}: GET_COMMAND_ARGUMENT, Get command line arguments
130 * @code{GETCWD}: GETCWD, Get current working directory
131 * @code{GETENV}: GETENV, Get an environmental variable
132 * @code{GET_ENVIRONMENT_VARIABLE}: GET_ENVIRONMENT_VARIABLE, Get an environmental variable
133 * @code{GETGID}: GETGID, Group ID function
134 * @code{GETLOG}: GETLOG, Get login name
135 * @code{GETPID}: GETPID, Process ID function
136 * @code{GETUID}: GETUID, User ID function
137 * @code{GMTIME}: GMTIME, Convert time to GMT info
138 * @code{HOSTNM}: HOSTNM, Get system host name
139 * @code{HUGE}: HUGE, Largest number of a kind
140 * @code{HYPOT}: HYPOT, Euclidian distance function
141 * @code{IACHAR}: IACHAR, Code in @acronym{ASCII} collating sequence
142 * @code{IAND}: IAND, Bitwise logical and
143 * @code{IARGC}: IARGC, Get the number of command line arguments
144 * @code{IBCLR}: IBCLR, Clear bit
145 * @code{IBITS}: IBITS, Bit extraction
146 * @code{IBSET}: IBSET, Set bit
147 * @code{ICHAR}: ICHAR, Character-to-integer conversion function
148 * @code{IDATE}: IDATE, Current local time (day/month/year)
149 * @code{IEOR}: IEOR, Bitwise logical exclusive or
150 * @code{IERRNO}: IERRNO, Function to get the last system error number
151 * @code{INDEX}: INDEX intrinsic, Position of a substring within a string
152 * @code{INT}: INT, Convert to integer type
153 * @code{INT2}: INT2, Convert to 16-bit integer type
154 * @code{INT8}: INT8, Convert to 64-bit integer type
155 * @code{IOR}: IOR, Bitwise logical or
156 * @code{IRAND}: IRAND, Integer pseudo-random number
157 * @code{IS_IOSTAT_END}: IS_IOSTAT_END, Test for end-of-file value
158 * @code{IS_IOSTAT_EOR}: IS_IOSTAT_EOR, Test for end-of-record value
159 * @code{ISATTY}: ISATTY, Whether a unit is a terminal device
160 * @code{ISHFT}: ISHFT, Shift bits
161 * @code{ISHFTC}: ISHFTC, Shift bits circularly
162 * @code{ISNAN}: ISNAN, Tests for a NaN
163 * @code{ITIME}: ITIME, Current local time (hour/minutes/seconds)
164 * @code{KILL}: KILL, Send a signal to a process
165 * @code{KIND}: KIND, Kind of an entity
166 * @code{LBOUND}: LBOUND, Lower dimension 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{SNGL}: SNGL, Convert double precision real to default real
243 * @code{SPACING}: SPACING, Smallest distance between two numbers of a given type
244 * @code{SPREAD}: SPREAD, Add a dimension to an array
245 * @code{SQRT}: SQRT, Square-root function
246 * @code{SRAND}: SRAND, Reinitialize the random number generator
247 * @code{STAT}: STAT, Get file status
248 * @code{SUM}: SUM, Sum of array elements
249 * @code{SYMLNK}: SYMLNK, Create a symbolic link
250 * @code{SYSTEM}: SYSTEM, Execute a shell command
251 * @code{SYSTEM_CLOCK}: SYSTEM_CLOCK, Time function
252 * @code{TAN}: TAN, Tangent function
253 * @code{TANH}: TANH, Hyperbolic tangent function
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{UMASK}: UMASK, Set the file creation mask
264 * @code{UNLINK}: UNLINK, Remove a file from the file system
265 * @code{UNPACK}: UNPACK, Unpack an array of rank one into an array
266 * @code{VERIFY}: VERIFY, Scan a string for the absence of a set of characters
267 * @code{XOR}: XOR, Bitwise logical exclusive or
270 @node Introduction to Intrinsics
271 @section Introduction to intrinsic procedures
273 The intrinsic procedures provided by GNU Fortran include all of the
274 intrinsic procedures required by the Fortran 95 standard, a set of
275 intrinsic procedures for backwards compatibility with G77, and a
276 selection of intrinsic procedures from the Fortran 2003 and Fortran 2008
277 standards. Any conflict between a description here and a description in
278 either the Fortran 95 standard, the Fortran 2003 standard or the Fortran
279 2008 standard is unintentional, and the standard(s) should be considered
282 The enumeration of the @code{KIND} type parameter is processor defined in
283 the Fortran 95 standard. GNU Fortran defines the default integer type and
284 default real type by @code{INTEGER(KIND=4)} and @code{REAL(KIND=4)},
285 respectively. The standard mandates that both data types shall have
286 another kind, which have more precision. On typical target architectures
287 supported by @command{gfortran}, this kind type parameter is @code{KIND=8}.
288 Hence, @code{REAL(KIND=8)} and @code{DOUBLE PRECISION} are equivalent.
289 In the description of generic intrinsic procedures, the kind type parameter
290 will be specified by @code{KIND=*}, and in the description of specific
291 names for an intrinsic procedure the kind type parameter will be explicitly
292 given (e.g., @code{REAL(KIND=4)} or @code{REAL(KIND=8)}). Finally, for
293 brevity the optional @code{KIND=} syntax will be omitted.
295 Many of the intrinsic procedures take one or more optional arguments.
296 This document follows the convention used in the Fortran 95 standard,
297 and denotes such arguments by square brackets.
299 GNU Fortran offers the @option{-std=f95} and @option{-std=gnu} options,
300 which can be used to restrict the set of intrinsic procedures to a
301 given standard. By default, @command{gfortran} sets the @option{-std=gnu}
302 option, and so all intrinsic procedures described here are accepted. There
303 is one caveat. For a select group of intrinsic procedures, @command{g77}
304 implemented both a function and a subroutine. Both classes
305 have been implemented in @command{gfortran} for backwards compatibility
306 with @command{g77}. It is noted here that these functions and subroutines
307 cannot be intermixed in a given subprogram. In the descriptions that follow,
308 the applicable standard for each intrinsic procedure is noted.
313 @section @code{ABORT} --- Abort the program
315 @cindex program termination, with core dump
316 @cindex terminate program, with core dump
320 @item @emph{Description}:
321 @code{ABORT} causes immediate termination of the program. On operating
322 systems that support a core dump, @code{ABORT} will produce a core dump even if
323 the option @option{-fno-dump-core} is in effect, which is suitable for debugging
325 @c TODO: Check if this (with -fno-dump-core) is correct.
327 @item @emph{Standard}:
336 @item @emph{Return value}:
339 @item @emph{Example}:
342 integer :: i = 1, j = 2
343 if (i /= j) call abort
344 end program test_abort
347 @item @emph{See also}:
348 @ref{EXIT}, @ref{KILL}
355 @section @code{ABS} --- Absolute value
362 @cindex absolute value
365 @item @emph{Description}:
366 @code{ABS(A)} computes the absolute value of @code{A}.
368 @item @emph{Standard}:
369 Fortran 77 and later, has overloads that are GNU extensions
375 @code{RESULT = ABS(A)}
377 @item @emph{Arguments}:
378 @multitable @columnfractions .15 .70
379 @item @var{A} @tab The type of the argument shall be an @code{INTEGER},
380 @code{REAL}, or @code{COMPLEX}.
383 @item @emph{Return value}:
384 The return value is of the same type and
385 kind as the argument except the return value is @code{REAL} for a
386 @code{COMPLEX} argument.
388 @item @emph{Example}:
393 complex :: z = (-1.e0,0.e0)
400 @item @emph{Specific names}:
401 @multitable @columnfractions .20 .20 .20 .25
402 @item Name @tab Argument @tab Return type @tab Standard
403 @item @code{CABS(A)} @tab @code{COMPLEX(4) Z} @tab @code{REAL(4)} @tab Fortran 77 and later
404 @item @code{DABS(A)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab Fortran 77 and later
405 @item @code{IABS(A)} @tab @code{INTEGER(4) I} @tab @code{INTEGER(4)} @tab Fortran 77 and later
406 @item @code{ZABS(A)} @tab @code{COMPLEX(8) Z} @tab @code{COMPLEX(8)} @tab GNU extension
407 @item @code{CDABS(A)} @tab @code{COMPLEX(8) Z} @tab @code{COMPLEX(8)} @tab GNU extension
414 @section @code{ACCESS} --- Checks file access modes
416 @cindex file system, access mode
419 @item @emph{Description}:
420 @code{ACCESS(NAME, MODE)} checks whether the file @var{NAME}
421 exists, is readable, writable or executable. Except for the
422 executable check, @code{ACCESS} can be replaced by
423 Fortran 95's @code{INQUIRE}.
425 @item @emph{Standard}:
432 @code{RESULT = ACCESS(NAME, MODE)}
434 @item @emph{Arguments}:
435 @multitable @columnfractions .15 .70
436 @item @var{NAME} @tab Scalar @code{CHARACTER} of default kind with the
437 file name. Tailing blank are ignored unless the character @code{achar(0)}
438 is present, then all characters up to and excluding @code{achar(0)} are
440 @item @var{MODE} @tab Scalar @code{CHARACTER} of default kind with the
441 file access mode, may be any concatenation of @code{"r"} (readable),
442 @code{"w"} (writable) and @code{"x"} (executable), or @code{" "} to check
446 @item @emph{Return value}:
447 Returns a scalar @code{INTEGER}, which is @code{0} if the file is
448 accessible in the given mode; otherwise or if an invalid argument
449 has been given for @code{MODE} the value @code{1} is returned.
451 @item @emph{Example}:
455 character(len=*), parameter :: file = 'test.dat'
456 character(len=*), parameter :: file2 = 'test.dat '//achar(0)
457 if(access(file,' ') == 0) print *, trim(file),' is exists'
458 if(access(file,'r') == 0) print *, trim(file),' is readable'
459 if(access(file,'w') == 0) print *, trim(file),' is writable'
460 if(access(file,'x') == 0) print *, trim(file),' is executable'
461 if(access(file2,'rwx') == 0) &
462 print *, trim(file2),' is readable, writable and executable'
463 end program access_test
465 @item @emph{Specific names}:
466 @item @emph{See also}:
473 @section @code{ACHAR} --- Character in @acronym{ASCII} collating sequence
475 @cindex @acronym{ASCII} collating sequence
476 @cindex collating sequence, @acronym{ASCII}
479 @item @emph{Description}:
480 @code{ACHAR(I)} returns the character located at position @code{I}
481 in the @acronym{ASCII} collating sequence.
483 @item @emph{Standard}:
484 Fortran 77 and later, with @var{KIND} argument Fortran 2003 and later
490 @code{RESULT = ACHAR(I [, KIND])}
492 @item @emph{Arguments}:
493 @multitable @columnfractions .15 .70
494 @item @var{I} @tab The type shall be @code{INTEGER}.
495 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
496 expression indicating the kind parameter of the result.
499 @item @emph{Return value}:
500 The return value is of type @code{CHARACTER} with a length of one.
501 If the @var{KIND} argument is present, the return value is of the
502 specified kind and of the default kind otherwise.
504 @item @emph{Example}:
509 end program test_achar
513 See @ref{ICHAR} for a discussion of converting between numerical values
514 and formatted string representations.
516 @item @emph{See also}:
517 @ref{CHAR}, @ref{IACHAR}, @ref{ICHAR}
524 @section @code{ACOS} --- Arccosine function
527 @cindex trigonometric function, cosine, inverse
528 @cindex cosine, inverse
531 @item @emph{Description}:
532 @code{ACOS(X)} computes the arccosine of @var{X} (inverse of @code{COS(X)}).
534 @item @emph{Standard}:
535 Fortran 77 and later, for a complex argument Fortran 2008 or later
541 @code{RESULT = ACOS(X)}
543 @item @emph{Arguments}:
544 @multitable @columnfractions .15 .70
545 @item @var{X} @tab The type shall either be @code{REAL} with a magnitude that is
546 less than or equal to one - or the type shall be @code{COMPLEX}.
549 @item @emph{Return value}:
550 The return value is of the same type and kind as @var{X}.
551 The real part of the result is in radians and lies in the range
552 @math{0 \leq \Re \acos(x) \leq \pi}.
554 @item @emph{Example}:
557 real(8) :: x = 0.866_8
559 end program test_acos
562 @item @emph{Specific names}:
563 @multitable @columnfractions .20 .20 .20 .25
564 @item Name @tab Argument @tab Return type @tab Standard
565 @item @code{DACOS(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab Fortran 77 and later
568 @item @emph{See also}:
569 Inverse function: @ref{COS}
576 @section @code{ACOSH} --- Hyperbolic arccosine function
579 @cindex area hyperbolic cosine
580 @cindex hyperbolic arccosine
581 @cindex hyperbolic function, cosine, inverse
582 @cindex cosine, hyperbolic, inverse
585 @item @emph{Description}:
586 @code{ACOSH(X)} computes the hyperbolic arccosine of @var{X} (inverse of
589 @item @emph{Standard}:
590 Fortran 2008 and later
596 @code{RESULT = ACOSH(X)}
598 @item @emph{Arguments}:
599 @multitable @columnfractions .15 .70
600 @item @var{X} @tab The type shall be @code{REAL} or @code{COMPLEX}.
603 @item @emph{Return value}:
604 The return value has the same type and kind as @var{X}. If @var{X} is
605 complex, the imaginary part of the result is in radians and lies between
606 @math{ 0 \leq \Im \acosh(x) \leq \pi}.
608 @item @emph{Example}:
611 REAL(8), DIMENSION(3) :: x = (/ 1.0, 2.0, 3.0 /)
616 @item @emph{Specific names}:
617 @multitable @columnfractions .20 .20 .20 .25
618 @item Name @tab Argument @tab Return type @tab Standard
619 @item @code{DACOSH(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU extension
622 @item @emph{See also}:
623 Inverse function: @ref{COSH}
629 @section @code{ADJUSTL} --- Left adjust a string
631 @cindex string, adjust left
632 @cindex adjust string
635 @item @emph{Description}:
636 @code{ADJUSTL(STRING)} will left adjust a string by removing leading spaces.
637 Spaces are inserted at the end of the string as needed.
639 @item @emph{Standard}:
646 @code{RESULT = ADJUSTL(STRING)}
648 @item @emph{Arguments}:
649 @multitable @columnfractions .15 .70
650 @item @var{STRING} @tab The type shall be @code{CHARACTER}.
653 @item @emph{Return value}:
654 The return value is of type @code{CHARACTER} and of the same kind as
655 @var{STRING} where leading spaces are removed and the same number of
656 spaces are inserted on the end of @var{STRING}.
658 @item @emph{Example}:
661 character(len=20) :: str = ' gfortran'
664 end program test_adjustl
667 @item @emph{See also}:
668 @ref{ADJUSTR}, @ref{TRIM}
674 @section @code{ADJUSTR} --- Right adjust a string
676 @cindex string, adjust right
677 @cindex adjust string
680 @item @emph{Description}:
681 @code{ADJUSTR(STRING)} will right adjust a string by removing trailing spaces.
682 Spaces are inserted at the start of the string as needed.
684 @item @emph{Standard}:
691 @code{RESULT = ADJUSTR(STRING)}
693 @item @emph{Arguments}:
694 @multitable @columnfractions .15 .70
695 @item @var{STR} @tab The type shall be @code{CHARACTER}.
698 @item @emph{Return value}:
699 The return value is of type @code{CHARACTER} and of the same kind as
700 @var{STRING} where trailing spaces are removed and the same number of
701 spaces are inserted at the start of @var{STRING}.
703 @item @emph{Example}:
706 character(len=20) :: str = 'gfortran'
709 end program test_adjustr
712 @item @emph{See also}:
713 @ref{ADJUSTL}, @ref{TRIM}
719 @section @code{AIMAG} --- Imaginary part of complex number
724 @cindex complex numbers, imaginary part
727 @item @emph{Description}:
728 @code{AIMAG(Z)} yields the imaginary part of complex argument @code{Z}.
729 The @code{IMAG(Z)} and @code{IMAGPART(Z)} intrinsic functions are provided
730 for compatibility with @command{g77}, and their use in new code is
731 strongly discouraged.
733 @item @emph{Standard}:
734 Fortran 77 and later, has overloads that are GNU extensions
740 @code{RESULT = AIMAG(Z)}
742 @item @emph{Arguments}:
743 @multitable @columnfractions .15 .70
744 @item @var{Z} @tab The type of the argument shall be @code{COMPLEX}.
747 @item @emph{Return value}:
748 The return value is of type @code{REAL} with the
749 kind type parameter of the argument.
751 @item @emph{Example}:
756 z4 = cmplx(1.e0_4, 0.e0_4)
757 z8 = cmplx(0.e0_8, 1.e0_8)
758 print *, aimag(z4), dimag(z8)
759 end program test_aimag
762 @item @emph{Specific names}:
763 @multitable @columnfractions .20 .20 .20 .25
764 @item Name @tab Argument @tab Return type @tab Standard
765 @item @code{DIMAG(Z)} @tab @code{COMPLEX(8) Z} @tab @code{REAL(8)} @tab GNU extension
766 @item @code{IMAG(Z)} @tab @code{COMPLEX Z} @tab @code{REAL} @tab GNU extension
767 @item @code{IMAGPART(Z)} @tab @code{COMPLEX Z} @tab @code{REAL} @tab GNU extension
774 @section @code{AINT} --- Truncate to a whole number
778 @cindex rounding, floor
781 @item @emph{Description}:
782 @code{AINT(A [, KIND])} truncates its argument to a whole number.
784 @item @emph{Standard}:
791 @code{RESULT = AINT(A [, KIND])}
793 @item @emph{Arguments}:
794 @multitable @columnfractions .15 .70
795 @item @var{A} @tab The type of the argument shall be @code{REAL}.
796 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
797 expression indicating the kind parameter of the result.
800 @item @emph{Return value}:
801 The return value is of type @code{REAL} with the kind type parameter of the
802 argument if the optional @var{KIND} is absent; otherwise, the kind
803 type parameter will be given by @var{KIND}. If the magnitude of
804 @var{X} is less than one, @code{AINT(X)} returns zero. If the
805 magnitude is equal to or greater than one then it returns the largest
806 whole number that does not exceed its magnitude. The sign is the same
807 as the sign of @var{X}.
809 @item @emph{Example}:
816 print *, aint(x4), dint(x8)
818 end program test_aint
821 @item @emph{Specific names}:
822 @multitable @columnfractions .20 .20 .20 .25
823 @item Name @tab Argument @tab Return type @tab Standard
824 @item @code{DINT(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab Fortran 77 and later
831 @section @code{ALARM} --- Execute a routine after a given delay
833 @cindex delayed execution
836 @item @emph{Description}:
837 @code{ALARM(SECONDS, HANDLER [, STATUS])} causes external subroutine @var{HANDLER}
838 to be executed after a delay of @var{SECONDS} by using @code{alarm(2)} to
839 set up a signal and @code{signal(2)} to catch it. If @var{STATUS} is
840 supplied, it will be returned with the number of seconds remaining until
841 any previously scheduled alarm was due to be delivered, or zero if there
842 was no previously scheduled alarm.
844 @item @emph{Standard}:
851 @code{CALL ALARM(SECONDS, HANDLER [, STATUS])}
853 @item @emph{Arguments}:
854 @multitable @columnfractions .15 .70
855 @item @var{SECONDS} @tab The type of the argument shall be a scalar
856 @code{INTEGER}. It is @code{INTENT(IN)}.
857 @item @var{HANDLER} @tab Signal handler (@code{INTEGER FUNCTION} or
858 @code{SUBROUTINE}) or dummy/global @code{INTEGER} scalar. The scalar
859 values may be either @code{SIG_IGN=1} to ignore the alarm generated
860 or @code{SIG_DFL=0} to set the default action. It is @code{INTENT(IN)}.
861 @item @var{STATUS} @tab (Optional) @var{STATUS} shall be a scalar
862 variable of the default @code{INTEGER} kind. It is @code{INTENT(OUT)}.
865 @item @emph{Example}:
868 external handler_print
870 call alarm (3, handler_print, i)
873 end program test_alarm
875 This will cause the external routine @var{handler_print} to be called
882 @section @code{ALL} --- All values in @var{MASK} along @var{DIM} are true
884 @cindex array, apply condition
885 @cindex array, condition testing
888 @item @emph{Description}:
889 @code{ALL(MASK [, DIM])} determines if all the values are true in @var{MASK}
890 in the array along dimension @var{DIM}.
892 @item @emph{Standard}:
896 Transformational function
899 @code{RESULT = ALL(MASK [, DIM])}
901 @item @emph{Arguments}:
902 @multitable @columnfractions .15 .70
903 @item @var{MASK} @tab The type of the argument shall be @code{LOGICAL} and
904 it shall not be scalar.
905 @item @var{DIM} @tab (Optional) @var{DIM} shall be a scalar integer
906 with a value that lies between one and the rank of @var{MASK}.
909 @item @emph{Return value}:
910 @code{ALL(MASK)} returns a scalar value of type @code{LOGICAL} where
911 the kind type parameter is the same as the kind type parameter of
912 @var{MASK}. If @var{DIM} is present, then @code{ALL(MASK, DIM)} returns
913 an array with the rank of @var{MASK} minus 1. The shape is determined from
914 the shape of @var{MASK} where the @var{DIM} dimension is elided.
918 @code{ALL(MASK)} is true if all elements of @var{MASK} are true.
919 It also is true if @var{MASK} has zero size; otherwise, it is false.
921 If the rank of @var{MASK} is one, then @code{ALL(MASK,DIM)} is equivalent
922 to @code{ALL(MASK)}. If the rank is greater than one, then @code{ALL(MASK,DIM)}
923 is determined by applying @code{ALL} to the array sections.
926 @item @emph{Example}:
930 l = all((/.true., .true., .true./))
935 integer a(2,3), b(2,3)
939 print *, all(a .eq. b, 1)
940 print *, all(a .eq. b, 2)
941 end subroutine section
949 @section @code{ALLOCATED} --- Status of an allocatable entity
951 @cindex allocation, status
954 @item @emph{Description}:
955 @code{ALLOCATED(ARRAY)} checks the status of whether @var{X} is allocated.
957 @item @emph{Standard}:
964 @code{RESULT = ALLOCATED(ARRAY)}
966 @item @emph{Arguments}:
967 @multitable @columnfractions .15 .70
968 @item @var{ARRAY} @tab The argument shall be an @code{ALLOCATABLE} array.
971 @item @emph{Return value}:
972 The return value is a scalar @code{LOGICAL} with the default logical
973 kind type parameter. If @var{ARRAY} is allocated, @code{ALLOCATED(ARRAY)}
974 is @code{.TRUE.}; otherwise, it returns @code{.FALSE.}
976 @item @emph{Example}:
978 program test_allocated
980 real(4), allocatable :: x(:)
981 if (.not. allocated(x)) allocate(x(i))
982 end program test_allocated
989 @section @code{AND} --- Bitwise logical AND
991 @cindex bitwise logical and
992 @cindex logical and, bitwise
995 @item @emph{Description}:
996 Bitwise logical @code{AND}.
998 This intrinsic routine is provided for backwards compatibility with
999 GNU Fortran 77. For integer arguments, programmers should consider
1000 the use of the @ref{IAND} intrinsic defined by the Fortran standard.
1002 @item @emph{Standard}:
1008 @item @emph{Syntax}:
1009 @code{RESULT = AND(I, J)}
1011 @item @emph{Arguments}:
1012 @multitable @columnfractions .15 .70
1013 @item @var{I} @tab The type shall be either a scalar @code{INTEGER}
1014 type or a scalar @code{LOGICAL} type.
1015 @item @var{J} @tab The type shall be the same as the type of @var{I}.
1018 @item @emph{Return value}:
1019 The return type is either a scalar @code{INTEGER} or a scalar
1020 @code{LOGICAL}. If the kind type parameters differ, then the
1021 smaller kind type is implicitly converted to larger kind, and the
1022 return has the larger kind.
1024 @item @emph{Example}:
1027 LOGICAL :: T = .TRUE., F = .FALSE.
1029 DATA a / Z'F' /, b / Z'3' /
1031 WRITE (*,*) AND(T, T), AND(T, F), AND(F, T), AND(F, F)
1032 WRITE (*,*) AND(a, b)
1036 @item @emph{See also}:
1037 Fortran 95 elemental function: @ref{IAND}
1043 @section @code{ANINT} --- Nearest whole number
1047 @cindex rounding, ceiling
1050 @item @emph{Description}:
1051 @code{ANINT(A [, KIND])} rounds its argument to the nearest whole number.
1053 @item @emph{Standard}:
1054 Fortran 77 and later
1059 @item @emph{Syntax}:
1060 @code{RESULT = ANINT(A [, KIND])}
1062 @item @emph{Arguments}:
1063 @multitable @columnfractions .15 .70
1064 @item @var{A} @tab The type of the argument shall be @code{REAL}.
1065 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
1066 expression indicating the kind parameter of the result.
1069 @item @emph{Return value}:
1070 The return value is of type real with the kind type parameter of the
1071 argument if the optional @var{KIND} is absent; otherwise, the kind
1072 type parameter will be given by @var{KIND}. If @var{A} is greater than
1073 zero, @code{ANINT(A)} returns @code{AINT(X+0.5)}. If @var{A} is
1074 less than or equal to zero then it returns @code{AINT(X-0.5)}.
1076 @item @emph{Example}:
1083 print *, anint(x4), dnint(x8)
1085 end program test_anint
1088 @item @emph{Specific names}:
1089 @multitable @columnfractions .20 .20 .20 .25
1090 @item Name @tab Argument @tab Return type @tab Standard
1091 @item @code{DNINT(A)} @tab @code{REAL(8) A} @tab @code{REAL(8)} @tab Fortran 77 and later
1098 @section @code{ANY} --- Any value in @var{MASK} along @var{DIM} is true
1100 @cindex array, apply condition
1101 @cindex array, condition testing
1104 @item @emph{Description}:
1105 @code{ANY(MASK [, DIM])} determines if any of the values in the logical array
1106 @var{MASK} along dimension @var{DIM} are @code{.TRUE.}.
1108 @item @emph{Standard}:
1109 Fortran 95 and later
1112 Transformational function
1114 @item @emph{Syntax}:
1115 @code{RESULT = ANY(MASK [, DIM])}
1117 @item @emph{Arguments}:
1118 @multitable @columnfractions .15 .70
1119 @item @var{MASK} @tab The type of the argument shall be @code{LOGICAL} and
1120 it shall not be scalar.
1121 @item @var{DIM} @tab (Optional) @var{DIM} shall be a scalar integer
1122 with a value that lies between one and the rank of @var{MASK}.
1125 @item @emph{Return value}:
1126 @code{ANY(MASK)} returns a scalar value of type @code{LOGICAL} where
1127 the kind type parameter is the same as the kind type parameter of
1128 @var{MASK}. If @var{DIM} is present, then @code{ANY(MASK, DIM)} returns
1129 an array with the rank of @var{MASK} minus 1. The shape is determined from
1130 the shape of @var{MASK} where the @var{DIM} dimension is elided.
1134 @code{ANY(MASK)} is true if any element of @var{MASK} is true;
1135 otherwise, it is false. It also is false if @var{MASK} has zero size.
1137 If the rank of @var{MASK} is one, then @code{ANY(MASK,DIM)} is equivalent
1138 to @code{ANY(MASK)}. If the rank is greater than one, then @code{ANY(MASK,DIM)}
1139 is determined by applying @code{ANY} to the array sections.
1142 @item @emph{Example}:
1146 l = any((/.true., .true., .true./))
1151 integer a(2,3), b(2,3)
1155 print *, any(a .eq. b, 1)
1156 print *, any(a .eq. b, 2)
1157 end subroutine section
1158 end program test_any
1165 @section @code{ASIN} --- Arcsine function
1168 @cindex trigonometric function, sine, inverse
1169 @cindex sine, inverse
1172 @item @emph{Description}:
1173 @code{ASIN(X)} computes the arcsine of its @var{X} (inverse of @code{SIN(X)}).
1175 @item @emph{Standard}:
1176 Fortran 77 and later, for a complex argument Fortran 2008 or later
1181 @item @emph{Syntax}:
1182 @code{RESULT = ASIN(X)}
1184 @item @emph{Arguments}:
1185 @multitable @columnfractions .15 .70
1186 @item @var{X} @tab The type shall be either @code{REAL} and a magnitude that is
1187 less than or equal to one - or be @code{COMPLEX}.
1190 @item @emph{Return value}:
1191 The return value is of the same type and kind as @var{X}.
1192 The real part of the result is in radians and lies in the range
1193 @math{-\pi/2 \leq \Re \asin(x) \leq \pi/2}.
1195 @item @emph{Example}:
1198 real(8) :: x = 0.866_8
1200 end program test_asin
1203 @item @emph{Specific names}:
1204 @multitable @columnfractions .20 .20 .20 .25
1205 @item Name @tab Argument @tab Return type @tab Standard
1206 @item @code{DASIN(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab Fortran 77 and later
1209 @item @emph{See also}:
1210 Inverse function: @ref{SIN}
1217 @section @code{ASINH} --- Hyperbolic arcsine function
1220 @cindex area hyperbolic sine
1221 @cindex hyperbolic arcsine
1222 @cindex hyperbolic function, sine, inverse
1223 @cindex sine, hyperbolic, inverse
1226 @item @emph{Description}:
1227 @code{ASINH(X)} computes the hyperbolic arcsine of @var{X} (inverse of @code{SINH(X)}).
1229 @item @emph{Standard}:
1230 Fortran 2008 and later
1235 @item @emph{Syntax}:
1236 @code{RESULT = ASINH(X)}
1238 @item @emph{Arguments}:
1239 @multitable @columnfractions .15 .70
1240 @item @var{X} @tab The type shall be @code{REAL} or @code{COMPLEX}.
1243 @item @emph{Return value}:
1244 The return value is of the same type and kind as @var{X}. If @var{X} is
1245 complex, the imaginary part of the result is in radians and lies between
1246 @math{-\pi/2 \leq \Im \asinh(x) \leq \pi/2}.
1248 @item @emph{Example}:
1251 REAL(8), DIMENSION(3) :: x = (/ -1.0, 0.0, 1.0 /)
1252 WRITE (*,*) ASINH(x)
1256 @item @emph{Specific names}:
1257 @multitable @columnfractions .20 .20 .20 .25
1258 @item Name @tab Argument @tab Return type @tab Standard
1259 @item @code{DASINH(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU extension.
1262 @item @emph{See also}:
1263 Inverse function: @ref{SINH}
1269 @section @code{ASSOCIATED} --- Status of a pointer or pointer/target pair
1271 @cindex pointer, status
1272 @cindex association status
1275 @item @emph{Description}:
1276 @code{ASSOCIATED(POINTER [, TARGET])} determines the status of the pointer
1277 @var{POINTER} or if @var{POINTER} is associated with the target @var{TARGET}.
1279 @item @emph{Standard}:
1280 Fortran 95 and later
1285 @item @emph{Syntax}:
1286 @code{RESULT = ASSOCIATED(POINTER [, TARGET])}
1288 @item @emph{Arguments}:
1289 @multitable @columnfractions .15 .70
1290 @item @var{POINTER} @tab @var{POINTER} shall have the @code{POINTER} attribute
1291 and it can be of any type.
1292 @item @var{TARGET} @tab (Optional) @var{TARGET} shall be a pointer or
1293 a target. It must have the same type, kind type parameter, and
1294 array rank as @var{POINTER}.
1296 The association status of neither @var{POINTER} nor @var{TARGET} shall be
1299 @item @emph{Return value}:
1300 @code{ASSOCIATED(POINTER)} returns a scalar value of type @code{LOGICAL(4)}.
1301 There are several cases:
1303 @item (A) When the optional @var{TARGET} is not present then
1304 @code{ASSOCIATED(POINTER)} is true if @var{POINTER} is associated with a target; otherwise, it returns false.
1305 @item (B) If @var{TARGET} is present and a scalar target, the result is true if
1306 @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
1307 disassociated, the result is false.
1308 @item (C) If @var{TARGET} is present and an array target, the result is true if
1309 @var{TARGET} and @var{POINTER} have the same shape, are not zero-sized arrays,
1310 are arrays whose elements are not zero-sized storage sequences, and
1311 @var{TARGET} and @var{POINTER} occupy the same storage units in array element
1313 As in case(B), the result is false, if @var{POINTER} is disassociated.
1314 @item (D) If @var{TARGET} is present and an scalar pointer, the result is true
1315 if @var{TARGET} is associated with @var{POINTER}, the target associated with
1316 @var{TARGET} are not zero-sized storage sequences and occupy the same storage
1318 The result is false, if either @var{TARGET} or @var{POINTER} is disassociated.
1319 @item (E) If @var{TARGET} is present and an array pointer, the result is true if
1320 target associated with @var{POINTER} and the target associated with @var{TARGET}
1321 have the same shape, are not zero-sized arrays, are arrays whose elements are
1322 not zero-sized storage sequences, and @var{TARGET} and @var{POINTER} occupy
1323 the same storage units in array element order.
1324 The result is false, if either @var{TARGET} or @var{POINTER} is disassociated.
1327 @item @emph{Example}:
1329 program test_associated
1331 real, target :: tgt(2) = (/1., 2./)
1332 real, pointer :: ptr(:)
1334 if (associated(ptr) .eqv. .false.) call abort
1335 if (associated(ptr,tgt) .eqv. .false.) call abort
1336 end program test_associated
1339 @item @emph{See also}:
1346 @section @code{ATAN} --- Arctangent function
1349 @cindex trigonometric function, tangent, inverse
1350 @cindex tangent, inverse
1353 @item @emph{Description}:
1354 @code{ATAN(X)} computes the arctangent of @var{X}.
1356 @item @emph{Standard}:
1357 Fortran 77 and later, for a complex argument and for two arguments
1358 Fortran 2008 or later
1363 @item @emph{Syntax}:
1364 @code{RESULT = ATAN(X)}
1365 @code{RESULT = ATAN(Y, X)}
1367 @item @emph{Arguments}:
1368 @multitable @columnfractions .15 .70
1369 @item @var{X} @tab The type shall be @code{REAL} or @code{COMPLEX};
1370 if @var{Y} is present, @var{X} shall be REAL.
1371 @item @var{Y} shall be of the same type and kind as @var{X}.
1374 @item @emph{Return value}:
1375 The return value is of the same type and kind as @var{X}.
1376 If @var{Y} is present, the result is identical to @code{ATAN2(Y,X)}.
1377 Otherwise, it the arcus tangent of @var{X}, where the real part of
1378 the result is in radians and lies in the range
1379 @math{-\pi/2 \leq \Re \atan(x) \leq \pi/2}.
1381 @item @emph{Example}:
1384 real(8) :: x = 2.866_8
1386 end program test_atan
1389 @item @emph{Specific names}:
1390 @multitable @columnfractions .20 .20 .20 .25
1391 @item Name @tab Argument @tab Return type @tab Standard
1392 @item @code{DATAN(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab Fortran 77 and later
1395 @item @emph{See also}:
1396 Inverse function: @ref{TAN}
1403 @section @code{ATAN2} --- Arctangent function
1406 @cindex trigonometric function, tangent, inverse
1407 @cindex tangent, inverse
1410 @item @emph{Description}:
1411 @code{ATAN2(Y, X)} computes the principal value of the argument
1412 function of the complex number @math{X + i Y}. This function can
1413 be used to transform from carthesian into polar coordinates and
1414 allows to determine the angle in the correct quadrant.
1416 @item @emph{Standard}:
1417 Fortran 77 and later
1422 @item @emph{Syntax}:
1423 @code{RESULT = ATAN2(Y, X)}
1425 @item @emph{Arguments}:
1426 @multitable @columnfractions .15 .70
1427 @item @var{Y} @tab The type shall be @code{REAL}.
1428 @item @var{X} @tab The type and kind type parameter shall be the same as @var{Y}.
1429 If @var{Y} is zero, then @var{X} must be nonzero.
1432 @item @emph{Return value}:
1433 The return value has the same type and kind type parameter as @var{Y}.
1434 It is the principal value of the complex number @math{X + i Y}. If
1435 @var{X} is nonzero, then it lies in the range @math{-\pi \le \atan (x) \leq \pi}.
1436 The sign is positive if @var{Y} is positive. If @var{Y} is zero, then
1437 the return value is zero if @var{X} is positive and @math{\pi} if @var{X}
1438 is negative. Finally, if @var{X} is zero, then the magnitude of the result
1441 @item @emph{Example}:
1444 real(4) :: x = 1.e0_4, y = 0.5e0_4
1446 end program test_atan2
1449 @item @emph{Specific names}:
1450 @multitable @columnfractions .20 .20 .20 .25
1451 @item Name @tab Argument @tab Return type @tab Standard
1452 @item @code{DATAN2(X, Y)} @tab @code{REAL(8) X}, @code{REAL(8) Y} @tab @code{REAL(8)} @tab Fortran 77 and later
1459 @section @code{ATANH} --- Hyperbolic arctangent function
1462 @cindex area hyperbolic tangent
1463 @cindex hyperbolic arctangent
1464 @cindex hyperbolic function, tangent, inverse
1465 @cindex tangent, hyperbolic, inverse
1468 @item @emph{Description}:
1469 @code{ATANH(X)} computes the hyperbolic arctangent of @var{X} (inverse
1472 @item @emph{Standard}:
1473 Fortran 2008 and later
1478 @item @emph{Syntax}:
1479 @code{RESULT = ATANH(X)}
1481 @item @emph{Arguments}:
1482 @multitable @columnfractions .15 .70
1483 @item @var{X} @tab The type shall be @code{REAL} or @code{COMPLEX}.
1486 @item @emph{Return value}:
1487 The return value has same type and kind as @var{X}. If @var{X} is
1488 complex, the imaginary part of the result is in radians and lies between
1489 @math{-\pi/2 \leq \Im \atanh(x) \leq \pi/2}.
1491 @item @emph{Example}:
1494 REAL, DIMENSION(3) :: x = (/ -1.0, 0.0, 1.0 /)
1495 WRITE (*,*) ATANH(x)
1499 @item @emph{Specific names}:
1500 @multitable @columnfractions .20 .20 .20 .25
1501 @item Name @tab Argument @tab Return type @tab Standard
1502 @item @code{DATANH(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU extension
1505 @item @emph{See also}:
1506 Inverse function: @ref{TANH}
1512 @section @code{BESSEL_J0} --- Bessel function of the first kind of order 0
1516 @cindex Bessel function, first kind
1519 @item @emph{Description}:
1520 @code{BESSEL_J0(X)} computes the Bessel function of the first kind of
1521 order 0 of @var{X}. This function is available under the name
1522 @code{BESJ0} as a GNU extension.
1524 @item @emph{Standard}:
1525 Fortran 2008 and later
1530 @item @emph{Syntax}:
1531 @code{RESULT = BESSEL_J0(X)}
1533 @item @emph{Arguments}:
1534 @multitable @columnfractions .15 .70
1535 @item @var{X} @tab The type shall be @code{REAL}, and it shall be scalar.
1538 @item @emph{Return value}:
1539 The return value is of type @code{REAL} and lies in the
1540 range @math{ - 0.4027... \leq Bessel (0,x) \leq 1}. It has the same
1543 @item @emph{Example}:
1546 real(8) :: x = 0.0_8
1548 end program test_besj0
1551 @item @emph{Specific names}:
1552 @multitable @columnfractions .20 .20 .20 .25
1553 @item Name @tab Argument @tab Return type @tab Standard
1554 @item @code{DBESJ0(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU extension
1561 @section @code{BESSEL_J1} --- Bessel function of the first kind of order 1
1565 @cindex Bessel function, first kind
1568 @item @emph{Description}:
1569 @code{BESSEL_J1(X)} computes the Bessel function of the first kind of
1570 order 1 of @var{X}. This function is available under the name
1571 @code{BESJ1} as a GNU extension.
1573 @item @emph{Standard}:
1579 @item @emph{Syntax}:
1580 @code{RESULT = BESSEL_J1(X)}
1582 @item @emph{Arguments}:
1583 @multitable @columnfractions .15 .70
1584 @item @var{X} @tab The type shall be @code{REAL}, and it shall be scalar.
1587 @item @emph{Return value}:
1588 The return value is of type @code{REAL} and it lies in the
1589 range @math{ - 0.5818... \leq Bessel (0,x) \leq 0.5818 }. It has the same
1592 @item @emph{Example}:
1595 real(8) :: x = 1.0_8
1597 end program test_besj1
1600 @item @emph{Specific names}:
1601 @multitable @columnfractions .20 .20 .20 .25
1602 @item Name @tab Argument @tab Return type @tab Standard
1603 @item @code{DBESJ1(X)}@tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU extension
1610 @section @code{BESSEL_JN} --- Bessel function of the first kind
1614 @cindex Bessel function, first kind
1617 @item @emph{Description}:
1618 @code{BESSEL_JN(N, X)} computes the Bessel function of the first kind of
1619 order @var{N} of @var{X}. This function is available under the name
1620 @code{BESJN} as a GNU extension.
1622 If both arguments are arrays, their ranks and shapes shall conform.
1624 @item @emph{Standard}:
1625 Fortran 2008 and later
1630 @item @emph{Syntax}:
1631 @code{RESULT = BESSEL_JN(N, X)}
1633 @item @emph{Arguments}:
1634 @multitable @columnfractions .15 .70
1635 @item @var{N} @tab Shall be a scalar or an array of type @code{INTEGER}.
1636 @item @var{X} @tab Shall be a scalar or an array of type @code{REAL}.
1639 @item @emph{Return value}:
1640 The return value is a scalar of type @code{REAL}. It has the same
1643 @item @emph{Example}:
1646 real(8) :: x = 1.0_8
1648 end program test_besjn
1651 @item @emph{Specific names}:
1652 @multitable @columnfractions .20 .20 .20 .25
1653 @item Name @tab Argument @tab Return type @tab Standard
1654 @item @code{DBESJN(N, X)} @tab @code{INTEGER N} @tab @code{REAL(8)} @tab GNU extension
1655 @item @tab @code{REAL(8) X} @tab @tab
1662 @section @code{BESSEL_Y0} --- Bessel function of the second kind of order 0
1666 @cindex Bessel function, second kind
1669 @item @emph{Description}:
1670 @code{BESSEL_Y0(X)} computes the Bessel function of the second kind of
1671 order 0 of @var{X}. This function is available under the name
1672 @code{BESY0} as a GNU extension.
1674 @item @emph{Standard}:
1675 Fortran 2008 and later
1680 @item @emph{Syntax}:
1681 @code{RESULT = BESSEL_Y0(X)}
1683 @item @emph{Arguments}:
1684 @multitable @columnfractions .15 .70
1685 @item @var{X} @tab The type shall be @code{REAL}, and it shall be scalar.
1688 @item @emph{Return value}:
1689 The return value is a scalar of type @code{REAL}. It has the same
1692 @item @emph{Example}:
1695 real(8) :: x = 0.0_8
1697 end program test_besy0
1700 @item @emph{Specific names}:
1701 @multitable @columnfractions .20 .20 .20 .25
1702 @item Name @tab Argument @tab Return type @tab Standard
1703 @item @code{DBESY0(X)}@tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU extension
1710 @section @code{BESSEL_Y1} --- Bessel function of the second kind of order 1
1714 @cindex Bessel function, second kind
1717 @item @emph{Description}:
1718 @code{BESSEL_Y1(X)} computes the Bessel function of the second kind of
1719 order 1 of @var{X}. This function is available under the name
1720 @code{BESY1} as a GNU extension.
1722 @item @emph{Standard}:
1723 Fortran 2008 and later
1728 @item @emph{Syntax}:
1729 @code{RESULT = BESSEL_Y1(X)}
1731 @item @emph{Arguments}:
1732 @multitable @columnfractions .15 .70
1733 @item @var{X} @tab The type shall be @code{REAL}, and it shall be scalar.
1736 @item @emph{Return value}:
1737 The return value is a scalar of type @code{REAL}. It has the same
1740 @item @emph{Example}:
1743 real(8) :: x = 1.0_8
1745 end program test_besy1
1748 @item @emph{Specific names}:
1749 @multitable @columnfractions .20 .20 .20 .25
1750 @item Name @tab Argument @tab Return type @tab Standard
1751 @item @code{DBESY1(X)}@tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU extension
1758 @section @code{BESSEL_YN} --- Bessel function of the second kind
1762 @cindex Bessel function, second kind
1765 @item @emph{Description}:
1766 @code{BESSEL_YN(N, X)} computes the Bessel function of the second kind of
1767 order @var{N} of @var{X}. This function is available under the name
1768 @code{BESYN} as a GNU extension.
1770 If both arguments are arrays, their ranks and shapes shall conform.
1772 @item @emph{Standard}:
1773 Fortran 2008 and later
1778 @item @emph{Syntax}:
1779 @code{RESULT = BESSEL_YN(N, X)}
1781 @item @emph{Arguments}:
1782 @multitable @columnfractions .15 .70
1783 @item @var{N} @tab Shall be a scalar or an array of type @code{INTEGER}.
1784 @item @var{X} @tab Shall be a scalar or an array of type @code{REAL}.
1787 @item @emph{Return value}:
1788 The return value is a scalar of type @code{REAL}. It has the same
1791 @item @emph{Example}:
1794 real(8) :: x = 1.0_8
1796 end program test_besyn
1799 @item @emph{Specific names}:
1800 @multitable @columnfractions .20 .20 .20 .25
1801 @item Name @tab Argument @tab Return type @tab Standard
1802 @item @code{DBESYN(N,X)} @tab @code{INTEGER N} @tab @code{REAL(8)} @tab GNU extension
1803 @item @tab @code{REAL(8) X} @tab @tab
1810 @section @code{BIT_SIZE} --- Bit size inquiry function
1812 @cindex bits, number of
1813 @cindex size of a variable, in bits
1816 @item @emph{Description}:
1817 @code{BIT_SIZE(I)} returns the number of bits (integer precision plus sign bit)
1818 represented by the type of @var{I}. The result of @code{BIT_SIZE(I)} is
1819 independent of the actual value of @var{I}.
1821 @item @emph{Standard}:
1822 Fortran 95 and later
1827 @item @emph{Syntax}:
1828 @code{RESULT = BIT_SIZE(I)}
1830 @item @emph{Arguments}:
1831 @multitable @columnfractions .15 .70
1832 @item @var{I} @tab The type shall be @code{INTEGER}.
1835 @item @emph{Return value}:
1836 The return value is of type @code{INTEGER}
1838 @item @emph{Example}:
1840 program test_bit_size
1845 end program test_bit_size
1852 @section @code{BTEST} --- Bit test function
1854 @cindex bits, testing
1857 @item @emph{Description}:
1858 @code{BTEST(I,POS)} returns logical @code{.TRUE.} if the bit at @var{POS}
1859 in @var{I} is set. The counting of the bits starts at 0.
1861 @item @emph{Standard}:
1862 Fortran 95 and later
1867 @item @emph{Syntax}:
1868 @code{RESULT = BTEST(I, POS)}
1870 @item @emph{Arguments}:
1871 @multitable @columnfractions .15 .70
1872 @item @var{I} @tab The type shall be @code{INTEGER}.
1873 @item @var{POS} @tab The type shall be @code{INTEGER}.
1876 @item @emph{Return value}:
1877 The return value is of type @code{LOGICAL}
1879 @item @emph{Example}:
1882 integer :: i = 32768 + 1024 + 64
1886 bool = btest(i, pos)
1889 end program test_btest
1895 @section @code{C_ASSOCIATED} --- Status of a C pointer
1896 @fnindex C_ASSOCIATED
1897 @cindex association status, C pointer
1898 @cindex pointer, C association status
1901 @item @emph{Description}:
1902 @code{C_ASSOCIATED(c_prt_1[, c_ptr_2])} determines the status of the C pointer
1903 @var{c_ptr_1} or if @var{c_ptr_1} is associated with the target @var{c_ptr_2}.
1905 @item @emph{Standard}:
1906 Fortran 2003 and later
1911 @item @emph{Syntax}:
1912 @code{RESULT = C_ASSOCIATED(c_prt_1[, c_ptr_2])}
1914 @item @emph{Arguments}:
1915 @multitable @columnfractions .15 .70
1916 @item @var{c_ptr_1} @tab Scalar of the type @code{C_PTR} or @code{C_FUNPTR}.
1917 @item @var{c_ptr_2} @tab (Optional) Scalar of the same type as @var{c_ptr_1}.
1920 @item @emph{Return value}:
1921 The return value is of type @code{LOGICAL}; it is @code{.false.} if either
1922 @var{c_ptr_1} is a C NULL pointer or if @var{c_ptr1} and @var{c_ptr_2}
1923 point to different addresses.
1925 @item @emph{Example}:
1927 subroutine association_test(a,b)
1928 use iso_c_binding, only: c_associated, c_loc, c_ptr
1932 if(c_associated(b, c_loc(a))) &
1933 stop 'b and a do not point to same target'
1934 end subroutine association_test
1937 @item @emph{See also}:
1938 @ref{C_LOC}, @ref{C_FUNLOC}
1943 @section @code{C_FUNLOC} --- Obtain the C address of a procedure
1945 @cindex pointer, C address of procedures
1948 @item @emph{Description}:
1949 @code{C_FUNLOC(x)} determines the C address of the argument.
1951 @item @emph{Standard}:
1952 Fortran 2003 and later
1957 @item @emph{Syntax}:
1958 @code{RESULT = C_FUNLOC(x)}
1960 @item @emph{Arguments}:
1961 @multitable @columnfractions .15 .70
1962 @item @var{x} @tab Interoperable function or pointer to such function.
1965 @item @emph{Return value}:
1966 The return value is of type @code{C_FUNPTR} and contains the C address
1969 @item @emph{Example}:
1975 subroutine sub(a) bind(c)
1985 subroutine my_routine(p) bind(c,name='myC_func')
1987 type(c_funptr), intent(in) :: p
1990 call my_routine(c_funloc(sub))
1994 @item @emph{See also}:
1995 @ref{C_ASSOCIATED}, @ref{C_LOC}, @ref{C_F_POINTER}, @ref{C_F_PROCPOINTER}
1999 @node C_F_PROCPOINTER
2000 @section @code{C_F_PROCPOINTER} --- Convert C into Fortran procedure pointer
2001 @fnindex C_F_PROCPOINTER
2002 @cindex pointer, C address of pointers
2005 @item @emph{Description}:
2006 @code{C_F_PROCPOINTER(CPTR, FPTR)} Assign the target of the C function pointer
2007 @var{CPTR} to the Fortran procedure pointer @var{FPTR}.
2009 @item @emph{Standard}:
2010 Fortran 2003 and later
2015 @item @emph{Syntax}:
2016 @code{CALL C_F_PROCPOINTER(cptr, fptr)}
2018 @item @emph{Arguments}:
2019 @multitable @columnfractions .15 .70
2020 @item @var{CPTR} @tab scalar of the type @code{C_FUNPTR}. It is
2022 @item @var{FPTR} @tab procedure pointer interoperable with @var{cptr}. It is
2026 @item @emph{Example}:
2034 real(c_float), intent(in) :: a
2035 real(c_float) :: func
2039 function getIterFunc() bind(c,name="getIterFunc")
2041 type(c_funptr) :: getIterFunc
2044 type(c_funptr) :: cfunptr
2045 procedure(func), pointer :: myFunc
2046 cfunptr = getIterFunc()
2047 call c_f_procpointer(cfunptr, myFunc)
2051 @item @emph{See also}:
2052 @ref{C_LOC}, @ref{C_F_POINTER}
2057 @section @code{C_F_POINTER} --- Convert C into Fortran pointer
2058 @fnindex C_F_POINTER
2059 @cindex pointer, convert C to Fortran
2062 @item @emph{Description}:
2063 @code{C_F_POINTER(CPTR, FPTR[, SHAPE])} Assign the target the C pointer
2064 @var{CPTR} to the Fortran pointer @var{FPTR} and specify its
2067 @item @emph{Standard}:
2068 Fortran 2003 and later
2073 @item @emph{Syntax}:
2074 @code{CALL C_F_POINTER(CPTR, FPTR[, SHAPE])}
2076 @item @emph{Arguments}:
2077 @multitable @columnfractions .15 .70
2078 @item @var{CPTR} @tab scalar of the type @code{C_PTR}. It is
2080 @item @var{FPTR} @tab pointer interoperable with @var{cptr}. It is
2082 @item @var{SHAPE} @tab (Optional) Rank-one array of type @code{INTEGER}
2083 with @code{INTENT(IN)}. It shall be present
2084 if and only if @var{fptr} is an array. The size
2085 must be equal to the rank of @var{fptr}.
2088 @item @emph{Example}:
2094 subroutine my_routine(p) bind(c,name='myC_func')
2096 type(c_ptr), intent(out) :: p
2100 real,pointer :: a(:)
2101 call my_routine(cptr)
2102 call c_f_pointer(cptr, a, [12])
2106 @item @emph{See also}:
2107 @ref{C_LOC}, @ref{C_F_PROCPOINTER}
2112 @section @code{C_LOC} --- Obtain the C address of an object
2114 @cindex procedure pointer, convert C to Fortran
2117 @item @emph{Description}:
2118 @code{C_LOC(X)} determines the C address of the argument.
2120 @item @emph{Standard}:
2121 Fortran 2003 and later
2126 @item @emph{Syntax}:
2127 @code{RESULT = C_LOC(X)}
2129 @item @emph{Arguments}:
2130 @multitable @columnfractions .15 .70
2131 @item @var{X} @tab Associated scalar pointer or interoperable scalar
2132 or allocated allocatable variable with @code{TARGET} attribute.
2135 @item @emph{Return value}:
2136 The return value is of type @code{C_PTR} and contains the C address
2139 @item @emph{Example}:
2141 subroutine association_test(a,b)
2142 use iso_c_binding, only: c_associated, c_loc, c_ptr
2146 if(c_associated(b, c_loc(a))) &
2147 stop 'b and a do not point to same target'
2148 end subroutine association_test
2151 @item @emph{See also}:
2152 @ref{C_ASSOCIATED}, @ref{C_FUNLOC}, @ref{C_F_POINTER}, @ref{C_F_PROCPOINTER}
2157 @section @code{C_SIZEOF} --- Size in bytes of an expression
2159 @cindex expression size
2160 @cindex size of an expression
2163 @item @emph{Description}:
2164 @code{C_SIZEOF(X)} calculates the number of bytes of storage the
2165 expression @code{X} occupies.
2167 @item @emph{Standard}:
2173 @item @emph{Syntax}:
2174 @code{N = C_SIZEOF(X)}
2176 @item @emph{Arguments}:
2177 @multitable @columnfractions .15 .70
2178 @item @var{X} @tab The argument shall be of any type, rank or shape.
2181 @item @emph{Return value}:
2182 The return value is of type integer and of the system-dependent kind
2183 @var{C_SIZE_T} (from the @var{ISO_C_BINDING} module). Its value is the
2184 number of bytes occupied by the argument. If the argument has the
2185 @code{POINTER} attribute, the number of bytes of the storage area pointed
2186 to is returned. If the argument is of a derived type with @code{POINTER}
2187 or @code{ALLOCATABLE} components, the return value doesn't account for
2188 the sizes of the data pointed to by these components.
2190 @item @emph{Example}:
2194 real(c_float) :: r, s(5)
2195 print *, (c_sizeof(s)/c_sizeof(r) == 5)
2198 The example will print @code{.TRUE.} unless you are using a platform
2199 where default @code{REAL} variables are unusually padded.
2201 @item @emph{See also}:
2207 @section @code{CEILING} --- Integer ceiling function
2210 @cindex rounding, ceiling
2213 @item @emph{Description}:
2214 @code{CEILING(A)} returns the least integer greater than or equal to @var{A}.
2216 @item @emph{Standard}:
2217 Fortran 95 and later
2222 @item @emph{Syntax}:
2223 @code{RESULT = CEILING(A [, KIND])}
2225 @item @emph{Arguments}:
2226 @multitable @columnfractions .15 .70
2227 @item @var{A} @tab The type shall be @code{REAL}.
2228 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
2229 expression indicating the kind parameter of the result.
2232 @item @emph{Return value}:
2233 The return value is of type @code{INTEGER(KIND)} if @var{KIND} is present
2234 and a default-kind @code{INTEGER} otherwise.
2236 @item @emph{Example}:
2238 program test_ceiling
2241 print *, ceiling(x) ! returns 64
2242 print *, ceiling(y) ! returns -63
2243 end program test_ceiling
2246 @item @emph{See also}:
2247 @ref{FLOOR}, @ref{NINT}
2254 @section @code{CHAR} --- Character conversion function
2256 @cindex conversion, to character
2259 @item @emph{Description}:
2260 @code{CHAR(I [, KIND])} returns the character represented by the integer @var{I}.
2262 @item @emph{Standard}:
2263 Fortran 77 and later
2268 @item @emph{Syntax}:
2269 @code{RESULT = CHAR(I [, KIND])}
2271 @item @emph{Arguments}:
2272 @multitable @columnfractions .15 .70
2273 @item @var{I} @tab The type shall be @code{INTEGER}.
2274 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
2275 expression indicating the kind parameter of the result.
2278 @item @emph{Return value}:
2279 The return value is of type @code{CHARACTER(1)}
2281 @item @emph{Example}:
2287 print *, i, c ! returns 'J'
2288 end program test_char
2292 See @ref{ICHAR} for a discussion of converting between numerical values
2293 and formatted string representations.
2295 @item @emph{See also}:
2296 @ref{ACHAR}, @ref{IACHAR}, @ref{ICHAR}
2303 @section @code{CHDIR} --- Change working directory
2305 @cindex system, working directory
2308 @item @emph{Description}:
2309 Change current working directory to a specified path.
2311 This intrinsic is provided in both subroutine and function forms; however,
2312 only one form can be used in any given program unit.
2314 @item @emph{Standard}:
2318 Subroutine, function
2320 @item @emph{Syntax}:
2321 @multitable @columnfractions .80
2322 @item @code{CALL CHDIR(NAME [, STATUS])}
2323 @item @code{STATUS = CHDIR(NAME)}
2326 @item @emph{Arguments}:
2327 @multitable @columnfractions .15 .70
2328 @item @var{NAME} @tab The type shall be @code{CHARACTER} of default
2329 kind and shall specify a valid path within the file system.
2330 @item @var{STATUS} @tab (Optional) @code{INTEGER} status flag of the default
2331 kind. Returns 0 on success, and a system specific and nonzero error code
2335 @item @emph{Example}:
2338 CHARACTER(len=255) :: path
2340 WRITE(*,*) TRIM(path)
2343 WRITE(*,*) TRIM(path)
2347 @item @emph{See also}:
2354 @section @code{CHMOD} --- Change access permissions of files
2356 @cindex file system, change access mode
2359 @item @emph{Description}:
2360 @code{CHMOD} changes the permissions of a file. This function invokes
2361 @code{/bin/chmod} and might therefore not work on all platforms.
2363 This intrinsic is provided in both subroutine and function forms; however,
2364 only one form can be used in any given program unit.
2366 @item @emph{Standard}:
2370 Subroutine, function
2372 @item @emph{Syntax}:
2373 @multitable @columnfractions .80
2374 @item @code{CALL CHMOD(NAME, MODE[, STATUS])}
2375 @item @code{STATUS = CHMOD(NAME, MODE)}
2378 @item @emph{Arguments}:
2379 @multitable @columnfractions .15 .70
2381 @item @var{NAME} @tab Scalar @code{CHARACTER} of default kind with the
2382 file name. Trailing blanks are ignored unless the character
2383 @code{achar(0)} is present, then all characters up to and excluding
2384 @code{achar(0)} are used as the file name.
2386 @item @var{MODE} @tab Scalar @code{CHARACTER} of default kind giving the
2387 file permission. @var{MODE} uses the same syntax as the @var{MODE}
2388 argument of @code{/bin/chmod}.
2390 @item @var{STATUS} @tab (optional) scalar @code{INTEGER}, which is
2391 @code{0} on success and nonzero otherwise.
2394 @item @emph{Return value}:
2395 In either syntax, @var{STATUS} is set to @code{0} on success and nonzero
2398 @item @emph{Example}:
2399 @code{CHMOD} as subroutine
2404 call chmod('test.dat','u+x',status)
2405 print *, 'Status: ', status
2406 end program chmod_test
2408 @code{CHMOD} as function:
2413 status = chmod('test.dat','u+x')
2414 print *, 'Status: ', status
2415 end program chmod_test
2423 @section @code{CMPLX} --- Complex conversion function
2425 @cindex complex numbers, conversion to
2426 @cindex conversion, to complex
2429 @item @emph{Description}:
2430 @code{CMPLX(X [, Y [, KIND]])} returns a complex number where @var{X} is converted to
2431 the real component. If @var{Y} is present it is converted to the imaginary
2432 component. If @var{Y} is not present then the imaginary component is set to
2433 0.0. If @var{X} is complex then @var{Y} must not be present.
2435 @item @emph{Standard}:
2436 Fortran 77 and later
2441 @item @emph{Syntax}:
2442 @code{RESULT = CMPLX(X [, Y [, KIND]])}
2444 @item @emph{Arguments}:
2445 @multitable @columnfractions .15 .70
2446 @item @var{X} @tab The type may be @code{INTEGER}, @code{REAL},
2448 @item @var{Y} @tab (Optional; only allowed if @var{X} is not
2449 @code{COMPLEX}.) May be @code{INTEGER} or @code{REAL}.
2450 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
2451 expression indicating the kind parameter of the result.
2454 @item @emph{Return value}:
2455 The return value is of @code{COMPLEX} type, with a kind equal to
2456 @var{KIND} if it is specified. If @var{KIND} is not specified, the
2457 result is of the default @code{COMPLEX} kind, regardless of the kinds of
2458 @var{X} and @var{Y}.
2460 @item @emph{Example}:
2467 print *, z, cmplx(x)
2468 end program test_cmplx
2471 @item @emph{See also}:
2477 @node COMMAND_ARGUMENT_COUNT
2478 @section @code{COMMAND_ARGUMENT_COUNT} --- Get number of command line arguments
2479 @fnindex COMMAND_ARGUMENT_COUNT
2480 @cindex command-line arguments
2481 @cindex command-line arguments, number of
2482 @cindex arguments, to program
2485 @item @emph{Description}:
2486 @code{COMMAND_ARGUMENT_COUNT()} returns the number of arguments passed on the
2487 command line when the containing program was invoked.
2489 @item @emph{Standard}:
2490 Fortran 2003 and later
2495 @item @emph{Syntax}:
2496 @code{RESULT = COMMAND_ARGUMENT_COUNT()}
2498 @item @emph{Arguments}:
2499 @multitable @columnfractions .15 .70
2503 @item @emph{Return value}:
2504 The return value is an @code{INTEGER} of default kind.
2506 @item @emph{Example}:
2508 program test_command_argument_count
2510 count = command_argument_count()
2512 end program test_command_argument_count
2515 @item @emph{See also}:
2516 @ref{GET_COMMAND}, @ref{GET_COMMAND_ARGUMENT}
2522 @section @code{COMPLEX} --- Complex conversion function
2524 @cindex complex numbers, conversion to
2525 @cindex conversion, to complex
2528 @item @emph{Description}:
2529 @code{COMPLEX(X, Y)} returns a complex number where @var{X} is converted
2530 to the real component and @var{Y} is converted to the imaginary
2533 @item @emph{Standard}:
2539 @item @emph{Syntax}:
2540 @code{RESULT = COMPLEX(X, Y)}
2542 @item @emph{Arguments}:
2543 @multitable @columnfractions .15 .70
2544 @item @var{X} @tab The type may be @code{INTEGER} or @code{REAL}.
2545 @item @var{Y} @tab The type may be @code{INTEGER} or @code{REAL}.
2548 @item @emph{Return value}:
2549 If @var{X} and @var{Y} are both of @code{INTEGER} type, then the return
2550 value is of default @code{COMPLEX} type.
2552 If @var{X} and @var{Y} are of @code{REAL} type, or one is of @code{REAL}
2553 type and one is of @code{INTEGER} type, then the return value is of
2554 @code{COMPLEX} type with a kind equal to that of the @code{REAL}
2555 argument with the highest precision.
2557 @item @emph{Example}:
2559 program test_complex
2562 print *, complex(i, x)
2563 end program test_complex
2566 @item @emph{See also}:
2573 @section @code{CONJG} --- Complex conjugate function
2576 @cindex complex conjugate
2579 @item @emph{Description}:
2580 @code{CONJG(Z)} returns the conjugate of @var{Z}. If @var{Z} is @code{(x, y)}
2581 then the result is @code{(x, -y)}
2583 @item @emph{Standard}:
2584 Fortran 77 and later, has overloads that are GNU extensions
2589 @item @emph{Syntax}:
2592 @item @emph{Arguments}:
2593 @multitable @columnfractions .15 .70
2594 @item @var{Z} @tab The type shall be @code{COMPLEX}.
2597 @item @emph{Return value}:
2598 The return value is of type @code{COMPLEX}.
2600 @item @emph{Example}:
2603 complex :: z = (2.0, 3.0)
2604 complex(8) :: dz = (2.71_8, -3.14_8)
2609 end program test_conjg
2612 @item @emph{Specific names}:
2613 @multitable @columnfractions .20 .20 .20 .25
2614 @item Name @tab Argument @tab Return type @tab Standard
2615 @item @code{DCONJG(Z)} @tab @code{COMPLEX(8) Z} @tab @code{COMPLEX(8)} @tab GNU extension
2622 @section @code{COS} --- Cosine function
2628 @cindex trigonometric function, cosine
2632 @item @emph{Description}:
2633 @code{COS(X)} computes the cosine of @var{X}.
2635 @item @emph{Standard}:
2636 Fortran 77 and later, has overloads that are GNU extensions
2641 @item @emph{Syntax}:
2642 @code{RESULT = COS(X)}
2644 @item @emph{Arguments}:
2645 @multitable @columnfractions .15 .70
2646 @item @var{X} @tab The type shall be @code{REAL} or
2650 @item @emph{Return value}:
2651 The return value is of the same type and kind as @var{X}. The real part
2652 of the result is in radians. If @var{X} is of the type @code{REAL},
2653 the return value lies in the range @math{ -1 \leq \cos (x) \leq 1}.
2655 @item @emph{Example}:
2660 end program test_cos
2663 @item @emph{Specific names}:
2664 @multitable @columnfractions .20 .20 .20 .25
2665 @item Name @tab Argument @tab Return type @tab Standard
2666 @item @code{DCOS(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab Fortran 77 and later
2667 @item @code{CCOS(X)} @tab @code{COMPLEX(4) X} @tab @code{COMPLEX(4)} @tab Fortran 77 and later
2668 @item @code{ZCOS(X)} @tab @code{COMPLEX(8) X} @tab @code{COMPLEX(8)} @tab GNU extension
2669 @item @code{CDCOS(X)} @tab @code{COMPLEX(8) X} @tab @code{COMPLEX(8)} @tab GNU extension
2672 @item @emph{See also}:
2673 Inverse function: @ref{ACOS}
2680 @section @code{COSH} --- Hyperbolic cosine function
2683 @cindex hyperbolic cosine
2684 @cindex hyperbolic function, cosine
2685 @cindex cosine, hyperbolic
2688 @item @emph{Description}:
2689 @code{COSH(X)} computes the hyperbolic cosine of @var{X}.
2691 @item @emph{Standard}:
2692 Fortran 77 and later, for a complex argument Fortran 2008 or later
2697 @item @emph{Syntax}:
2700 @item @emph{Arguments}:
2701 @multitable @columnfractions .15 .70
2702 @item @var{X} @tab The type shall be @code{REAL} or @code{COMPLEX}.
2705 @item @emph{Return value}:
2706 The return value has same type and kind as @var{X}. If @var{X} is
2707 complex, the imaginary part of the result is in radians. If @var{X}
2708 is @code{REAL}, the return value has a lower bound of one,
2709 @math{\cosh (x) \geq 1}.
2711 @item @emph{Example}:
2714 real(8) :: x = 1.0_8
2716 end program test_cosh
2719 @item @emph{Specific names}:
2720 @multitable @columnfractions .20 .20 .20 .25
2721 @item Name @tab Argument @tab Return type @tab Standard
2722 @item @code{DCOSH(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab Fortran 77 and later
2725 @item @emph{See also}:
2726 Inverse function: @ref{ACOSH}
2733 @section @code{COUNT} --- Count function
2735 @cindex array, conditionally count elements
2736 @cindex array, element counting
2737 @cindex array, number of elements
2740 @item @emph{Description}:
2742 Counts the number of @code{.TRUE.} elements in a logical @var{MASK},
2743 or, if the @var{DIM} argument is supplied, counts the number of
2744 elements along each row of the array in the @var{DIM} direction.
2745 If the array has zero size, or all of the elements of @var{MASK} are
2746 @code{.FALSE.}, then the result is @code{0}.
2748 @item @emph{Standard}:
2749 Fortran 95 and later, with @var{KIND} argument Fortran 2003 and later
2752 Transformational function
2754 @item @emph{Syntax}:
2755 @code{RESULT = COUNT(MASK [, DIM, KIND])}
2757 @item @emph{Arguments}:
2758 @multitable @columnfractions .15 .70
2759 @item @var{MASK} @tab The type shall be @code{LOGICAL}.
2760 @item @var{DIM} @tab (Optional) The type shall be @code{INTEGER}.
2761 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
2762 expression indicating the kind parameter of the result.
2765 @item @emph{Return value}:
2766 The return value is of type @code{INTEGER} and of kind @var{KIND}. If
2767 @var{KIND} is absent, the return value is of default integer kind.
2768 If @var{DIM} is present, the result is an array with a rank one less
2769 than the rank of @var{ARRAY}, and a size corresponding to the shape
2770 of @var{ARRAY} with the @var{DIM} dimension removed.
2772 @item @emph{Example}:
2775 integer, dimension(2,3) :: a, b
2776 logical, dimension(2,3) :: mask
2777 a = reshape( (/ 1, 2, 3, 4, 5, 6 /), (/ 2, 3 /))
2778 b = reshape( (/ 0, 7, 3, 4, 5, 8 /), (/ 2, 3 /))
2779 print '(3i3)', a(1,:)
2780 print '(3i3)', a(2,:)
2782 print '(3i3)', b(1,:)
2783 print '(3i3)', b(2,:)
2786 print '(3l3)', mask(1,:)
2787 print '(3l3)', mask(2,:)
2789 print '(3i3)', count(mask)
2791 print '(3i3)', count(mask, 1)
2793 print '(3i3)', count(mask, 2)
2794 end program test_count
2801 @section @code{CPU_TIME} --- CPU elapsed time in seconds
2803 @cindex time, elapsed
2806 @item @emph{Description}:
2807 Returns a @code{REAL} value representing the elapsed CPU time in
2808 seconds. This is useful for testing segments of code to determine
2811 If a time source is available, time will be reported with microsecond
2812 resolution. If no time source is available, @var{TIME} is set to
2815 Note that @var{TIME} may contain a, system dependent, arbitrary offset
2816 and may not start with @code{0.0}. For @code{CPU_TIME}, the absolute
2817 value is meaningless, only differences between subsequent calls to
2818 this subroutine, as shown in the example below, should be used.
2821 @item @emph{Standard}:
2822 Fortran 95 and later
2827 @item @emph{Syntax}:
2828 @code{CALL CPU_TIME(TIME)}
2830 @item @emph{Arguments}:
2831 @multitable @columnfractions .15 .70
2832 @item @var{TIME} @tab The type shall be @code{REAL} with @code{INTENT(OUT)}.
2835 @item @emph{Return value}:
2838 @item @emph{Example}:
2840 program test_cpu_time
2841 real :: start, finish
2842 call cpu_time(start)
2843 ! put code to test here
2844 call cpu_time(finish)
2845 print '("Time = ",f6.3," seconds.")',finish-start
2846 end program test_cpu_time
2849 @item @emph{See also}:
2850 @ref{SYSTEM_CLOCK}, @ref{DATE_AND_TIME}
2856 @section @code{CSHIFT} --- Circular shift elements of an array
2858 @cindex array, shift circularly
2859 @cindex array, permutation
2860 @cindex array, rotate
2863 @item @emph{Description}:
2864 @code{CSHIFT(ARRAY, SHIFT [, DIM])} performs a circular shift on elements of
2865 @var{ARRAY} along the dimension of @var{DIM}. If @var{DIM} is omitted it is
2866 taken to be @code{1}. @var{DIM} is a scalar of type @code{INTEGER} in the
2867 range of @math{1 \leq DIM \leq n)} where @math{n} is the rank of @var{ARRAY}.
2868 If the rank of @var{ARRAY} is one, then all elements of @var{ARRAY} are shifted
2869 by @var{SHIFT} places. If rank is greater than one, then all complete rank one
2870 sections of @var{ARRAY} along the given dimension are shifted. Elements
2871 shifted out one end of each rank one section are shifted back in the other end.
2873 @item @emph{Standard}:
2874 Fortran 95 and later
2877 Transformational function
2879 @item @emph{Syntax}:
2880 @code{RESULT = CSHIFT(ARRAY, SHIFT [, DIM])}
2882 @item @emph{Arguments}:
2883 @multitable @columnfractions .15 .70
2884 @item @var{ARRAY} @tab Shall be an array of any type.
2885 @item @var{SHIFT} @tab The type shall be @code{INTEGER}.
2886 @item @var{DIM} @tab The type shall be @code{INTEGER}.
2889 @item @emph{Return value}:
2890 Returns an array of same type and rank as the @var{ARRAY} argument.
2892 @item @emph{Example}:
2895 integer, dimension(3,3) :: a
2896 a = reshape( (/ 1, 2, 3, 4, 5, 6, 7, 8, 9 /), (/ 3, 3 /))
2897 print '(3i3)', a(1,:)
2898 print '(3i3)', a(2,:)
2899 print '(3i3)', a(3,:)
2900 a = cshift(a, SHIFT=(/1, 2, -1/), DIM=2)
2902 print '(3i3)', a(1,:)
2903 print '(3i3)', a(2,:)
2904 print '(3i3)', a(3,:)
2905 end program test_cshift
2912 @section @code{CTIME} --- Convert a time into a string
2914 @cindex time, conversion to string
2915 @cindex conversion, to string
2918 @item @emph{Description}:
2919 @code{CTIME} converts a system time value, such as returned by
2920 @code{TIME8()}, to a string of the form @samp{Sat Aug 19 18:13:14 1995}.
2922 This intrinsic is provided in both subroutine and function forms; however,
2923 only one form can be used in any given program unit.
2925 @item @emph{Standard}:
2929 Subroutine, function
2931 @item @emph{Syntax}:
2932 @multitable @columnfractions .80
2933 @item @code{CALL CTIME(TIME, RESULT)}.
2934 @item @code{RESULT = CTIME(TIME)}, (not recommended).
2937 @item @emph{Arguments}:
2938 @multitable @columnfractions .15 .70
2939 @item @var{TIME} @tab The type shall be of type @code{INTEGER(KIND=8)}.
2940 @item @var{RESULT} @tab The type shall be of type @code{CHARACTER} and
2944 @item @emph{Return value}:
2945 The converted date and time as a string.
2947 @item @emph{Example}:
2951 character(len=30) :: date
2954 ! Do something, main part of the program
2957 print *, 'Program was started on ', date
2958 end program test_ctime
2961 @item @emph{See Also}:
2962 @ref{GMTIME}, @ref{LTIME}, @ref{TIME}, @ref{TIME8}
2968 @section @code{DATE_AND_TIME} --- Date and time subroutine
2969 @fnindex DATE_AND_TIME
2970 @cindex date, current
2971 @cindex current date
2972 @cindex time, current
2973 @cindex current time
2976 @item @emph{Description}:
2977 @code{DATE_AND_TIME(DATE, TIME, ZONE, VALUES)} gets the corresponding date and
2978 time information from the real-time system clock. @var{DATE} is
2979 @code{INTENT(OUT)} and has form ccyymmdd. @var{TIME} is @code{INTENT(OUT)} and
2980 has form hhmmss.sss. @var{ZONE} is @code{INTENT(OUT)} and has form (+-)hhmm,
2981 representing the difference with respect to Coordinated Universal Time (UTC).
2982 Unavailable time and date parameters return blanks.
2984 @var{VALUES} is @code{INTENT(OUT)} and provides the following:
2986 @multitable @columnfractions .15 .30 .40
2987 @item @tab @code{VALUE(1)}: @tab The year
2988 @item @tab @code{VALUE(2)}: @tab The month
2989 @item @tab @code{VALUE(3)}: @tab The day of the month
2990 @item @tab @code{VALUE(4)}: @tab Time difference with UTC in minutes
2991 @item @tab @code{VALUE(5)}: @tab The hour of the day
2992 @item @tab @code{VALUE(6)}: @tab The minutes of the hour
2993 @item @tab @code{VALUE(7)}: @tab The seconds of the minute
2994 @item @tab @code{VALUE(8)}: @tab The milliseconds of the second
2997 @item @emph{Standard}:
2998 Fortran 95 and later
3003 @item @emph{Syntax}:
3004 @code{CALL DATE_AND_TIME([DATE, TIME, ZONE, VALUES])}
3006 @item @emph{Arguments}:
3007 @multitable @columnfractions .15 .70
3008 @item @var{DATE} @tab (Optional) The type shall be @code{CHARACTER(LEN=8)}
3009 or larger, and of default kind.
3010 @item @var{TIME} @tab (Optional) The type shall be @code{CHARACTER(LEN=10)}
3011 or larger, and of default kind.
3012 @item @var{ZONE} @tab (Optional) The type shall be @code{CHARACTER(LEN=5)}
3013 or larger, and of default kind.
3014 @item @var{VALUES}@tab (Optional) The type shall be @code{INTEGER(8)}.
3017 @item @emph{Return value}:
3020 @item @emph{Example}:
3022 program test_time_and_date
3023 character(8) :: date
3024 character(10) :: time
3025 character(5) :: zone
3026 integer,dimension(8) :: values
3027 ! using keyword arguments
3028 call date_and_time(date,time,zone,values)
3029 call date_and_time(DATE=date,ZONE=zone)
3030 call date_and_time(TIME=time)
3031 call date_and_time(VALUES=values)
3032 print '(a,2x,a,2x,a)', date, time, zone
3033 print '(8i5))', values
3034 end program test_time_and_date
3037 @item @emph{See also}:
3038 @ref{CPU_TIME}, @ref{SYSTEM_CLOCK}
3044 @section @code{DBLE} --- Double conversion function
3046 @cindex conversion, to real
3049 @item @emph{Description}:
3050 @code{DBLE(A)} Converts @var{A} to double precision real type.
3052 @item @emph{Standard}:
3053 Fortran 77 and later
3058 @item @emph{Syntax}:
3059 @code{RESULT = DBLE(A)}
3061 @item @emph{Arguments}:
3062 @multitable @columnfractions .15 .70
3063 @item @var{A} @tab The type shall be @code{INTEGER}, @code{REAL},
3067 @item @emph{Return value}:
3068 The return value is of type double precision real.
3070 @item @emph{Example}:
3075 complex :: z = (2.3,1.14)
3076 print *, dble(x), dble(i), dble(z)
3077 end program test_dble
3080 @item @emph{See also}:
3081 @ref{DFLOAT}, @ref{FLOAT}, @ref{REAL}
3087 @section @code{DCMPLX} --- Double complex conversion function
3089 @cindex complex numbers, conversion to
3090 @cindex conversion, to complex
3093 @item @emph{Description}:
3094 @code{DCMPLX(X [,Y])} returns a double complex number where @var{X} is
3095 converted to the real component. If @var{Y} is present it is converted to the
3096 imaginary component. If @var{Y} is not present then the imaginary component is
3097 set to 0.0. If @var{X} is complex then @var{Y} must not be present.
3099 @item @emph{Standard}:
3105 @item @emph{Syntax}:
3106 @code{RESULT = DCMPLX(X [, Y])}
3108 @item @emph{Arguments}:
3109 @multitable @columnfractions .15 .70
3110 @item @var{X} @tab The type may be @code{INTEGER}, @code{REAL},
3112 @item @var{Y} @tab (Optional if @var{X} is not @code{COMPLEX}.) May be
3113 @code{INTEGER} or @code{REAL}.
3116 @item @emph{Return value}:
3117 The return value is of type @code{COMPLEX(8)}
3119 @item @emph{Example}:
3129 print *, dcmplx(x,i)
3130 end program test_dcmplx
3137 @section @code{DFLOAT} --- Double conversion function
3139 @cindex conversion, to real
3142 @item @emph{Description}:
3143 @code{DFLOAT(A)} Converts @var{A} to double precision real type.
3145 @item @emph{Standard}:
3151 @item @emph{Syntax}:
3152 @code{RESULT = DFLOAT(A)}
3154 @item @emph{Arguments}:
3155 @multitable @columnfractions .15 .70
3156 @item @var{A} @tab The type shall be @code{INTEGER}.
3159 @item @emph{Return value}:
3160 The return value is of type double precision real.
3162 @item @emph{Example}:
3167 end program test_dfloat
3170 @item @emph{See also}:
3171 @ref{DBLE}, @ref{FLOAT}, @ref{REAL}
3177 @section @code{DIGITS} --- Significant binary digits function
3179 @cindex model representation, significant digits
3182 @item @emph{Description}:
3183 @code{DIGITS(X)} returns the number of significant binary digits of the internal
3184 model representation of @var{X}. For example, on a system using a 32-bit
3185 floating point representation, a default real number would likely return 24.
3187 @item @emph{Standard}:
3188 Fortran 95 and later
3193 @item @emph{Syntax}:
3194 @code{RESULT = DIGITS(X)}
3196 @item @emph{Arguments}:
3197 @multitable @columnfractions .15 .70
3198 @item @var{X} @tab The type may be @code{INTEGER} or @code{REAL}.
3201 @item @emph{Return value}:
3202 The return value is of type @code{INTEGER}.
3204 @item @emph{Example}:
3207 integer :: i = 12345
3213 end program test_digits
3220 @section @code{DIM} --- Positive difference
3224 @cindex positive difference
3227 @item @emph{Description}:
3228 @code{DIM(X,Y)} returns the difference @code{X-Y} if the result is positive;
3229 otherwise returns zero.
3231 @item @emph{Standard}:
3232 Fortran 77 and later
3237 @item @emph{Syntax}:
3238 @code{RESULT = DIM(X, Y)}
3240 @item @emph{Arguments}:
3241 @multitable @columnfractions .15 .70
3242 @item @var{X} @tab The type shall be @code{INTEGER} or @code{REAL}
3243 @item @var{Y} @tab The type shall be the same type and kind as @var{X}.
3246 @item @emph{Return value}:
3247 The return value is of type @code{INTEGER} or @code{REAL}.
3249 @item @emph{Example}:
3255 x = dim(4.345_8, 2.111_8)
3258 end program test_dim
3261 @item @emph{Specific names}:
3262 @multitable @columnfractions .20 .20 .20 .25
3263 @item Name @tab Argument @tab Return type @tab Standard
3264 @item @code{IDIM(X,Y)} @tab @code{INTEGER(4) X,Y} @tab @code{INTEGER(4)} @tab Fortran 77 and later
3265 @item @code{DDIM(X,Y)} @tab @code{REAL(8) X,Y} @tab @code{REAL(8)} @tab Fortran 77 and later
3272 @section @code{DOT_PRODUCT} --- Dot product function
3273 @fnindex DOT_PRODUCT
3275 @cindex vector product
3276 @cindex product, vector
3279 @item @emph{Description}:
3280 @code{DOT_PRODUCT(VECTOR_A, VECTOR_B)} computes the dot product multiplication
3281 of two vectors @var{VECTOR_A} and @var{VECTOR_B}. The two vectors may be
3282 either numeric or logical and must be arrays of rank one and of equal size. If
3283 the vectors are @code{INTEGER} or @code{REAL}, the result is
3284 @code{SUM(VECTOR_A*VECTOR_B)}. If the vectors are @code{COMPLEX}, the result
3285 is @code{SUM(CONJG(VECTOR_A)*VECTOR_B)}. If the vectors are @code{LOGICAL},
3286 the result is @code{ANY(VECTOR_A .AND. VECTOR_B)}.
3288 @item @emph{Standard}:
3289 Fortran 95 and later
3292 Transformational function
3294 @item @emph{Syntax}:
3295 @code{RESULT = DOT_PRODUCT(VECTOR_A, VECTOR_B)}
3297 @item @emph{Arguments}:
3298 @multitable @columnfractions .15 .70
3299 @item @var{VECTOR_A} @tab The type shall be numeric or @code{LOGICAL}, rank 1.
3300 @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.
3303 @item @emph{Return value}:
3304 If the arguments are numeric, the return value is a scalar of numeric type,
3305 @code{INTEGER}, @code{REAL}, or @code{COMPLEX}. If the arguments are
3306 @code{LOGICAL}, the return value is @code{.TRUE.} or @code{.FALSE.}.
3308 @item @emph{Example}:
3310 program test_dot_prod
3311 integer, dimension(3) :: a, b
3318 print *, dot_product(a,b)
3319 end program test_dot_prod
3326 @section @code{DPROD} --- Double product function
3328 @cindex product, double-precision
3331 @item @emph{Description}:
3332 @code{DPROD(X,Y)} returns the product @code{X*Y}.
3334 @item @emph{Standard}:
3335 Fortran 77 and later
3340 @item @emph{Syntax}:
3341 @code{RESULT = DPROD(X, Y)}
3343 @item @emph{Arguments}:
3344 @multitable @columnfractions .15 .70
3345 @item @var{X} @tab The type shall be @code{REAL}.
3346 @item @var{Y} @tab The type shall be @code{REAL}.
3349 @item @emph{Return value}:
3350 The return value is of type @code{REAL(8)}.
3352 @item @emph{Example}:
3360 end program test_dprod
3367 @section @code{DREAL} --- Double real part function
3369 @cindex complex numbers, real part
3372 @item @emph{Description}:
3373 @code{DREAL(Z)} returns the real part of complex variable @var{Z}.
3375 @item @emph{Standard}:
3381 @item @emph{Syntax}:
3382 @code{RESULT = DREAL(A)}
3384 @item @emph{Arguments}:
3385 @multitable @columnfractions .15 .70
3386 @item @var{A} @tab The type shall be @code{COMPLEX(8)}.
3389 @item @emph{Return value}:
3390 The return value is of type @code{REAL(8)}.
3392 @item @emph{Example}:
3395 complex(8) :: z = (1.3_8,7.2_8)
3397 end program test_dreal
3400 @item @emph{See also}:
3408 @section @code{DTIME} --- Execution time subroutine (or function)
3410 @cindex time, elapsed
3411 @cindex elapsed time
3414 @item @emph{Description}:
3415 @code{DTIME(VALUES, TIME)} initially returns the number of seconds of runtime
3416 since the start of the process's execution in @var{TIME}. @var{VALUES}
3417 returns the user and system components of this time in @code{VALUES(1)} and
3418 @code{VALUES(2)} respectively. @var{TIME} is equal to @code{VALUES(1) +
3421 Subsequent invocations of @code{DTIME} return values accumulated since the
3422 previous invocation.
3424 On some systems, the underlying timings are represented using types with
3425 sufficiently small limits that overflows (wrap around) are possible, such as
3426 32-bit types. Therefore, the values returned by this intrinsic might be, or
3427 become, negative, or numerically less than previous values, during a single
3428 run of the compiled program.
3430 Please note, that this implementation is thread safe if used within OpenMP
3431 directives, i.e., its state will be consistent while called from multiple
3432 threads. However, if @code{DTIME} is called from multiple threads, the result
3433 is still the time since the last invocation. This may not give the intended
3434 results. If possible, use @code{CPU_TIME} instead.
3436 This intrinsic is provided in both subroutine and function forms; however,
3437 only one form can be used in any given program unit.
3439 @var{VALUES} and @var{TIME} are @code{INTENT(OUT)} and provide the following:
3441 @multitable @columnfractions .15 .30 .40
3442 @item @tab @code{VALUES(1)}: @tab User time in seconds.
3443 @item @tab @code{VALUES(2)}: @tab System time in seconds.
3444 @item @tab @code{TIME}: @tab Run time since start in seconds.
3447 @item @emph{Standard}:
3451 Subroutine, function
3453 @item @emph{Syntax}:
3454 @multitable @columnfractions .80
3455 @item @code{CALL DTIME(VALUES, TIME)}.
3456 @item @code{TIME = DTIME(VALUES)}, (not recommended).
3459 @item @emph{Arguments}:
3460 @multitable @columnfractions .15 .70
3461 @item @var{VALUES}@tab The type shall be @code{REAL(4), DIMENSION(2)}.
3462 @item @var{TIME}@tab The type shall be @code{REAL(4)}.
3465 @item @emph{Return value}:
3466 Elapsed time in seconds since the last invocation or since the start of program
3467 execution if not called before.
3469 @item @emph{Example}:
3473 real, dimension(2) :: tarray
3475 call dtime(tarray, result)
3479 do i=1,100000000 ! Just a delay
3482 call dtime(tarray, result)
3486 end program test_dtime
3489 @item @emph{See also}:
3497 @section @code{EOSHIFT} --- End-off shift elements of an array
3499 @cindex array, shift
3502 @item @emph{Description}:
3503 @code{EOSHIFT(ARRAY, SHIFT[, BOUNDARY, DIM])} performs an end-off shift on
3504 elements of @var{ARRAY} along the dimension of @var{DIM}. If @var{DIM} is
3505 omitted it is taken to be @code{1}. @var{DIM} is a scalar of type
3506 @code{INTEGER} in the range of @math{1 \leq DIM \leq n)} where @math{n} is the
3507 rank of @var{ARRAY}. If the rank of @var{ARRAY} is one, then all elements of
3508 @var{ARRAY} are shifted by @var{SHIFT} places. If rank is greater than one,
3509 then all complete rank one sections of @var{ARRAY} along the given dimension are
3510 shifted. Elements shifted out one end of each rank one section are dropped. If
3511 @var{BOUNDARY} is present then the corresponding value of from @var{BOUNDARY}
3512 is copied back in the other end. If @var{BOUNDARY} is not present then the
3513 following are copied in depending on the type of @var{ARRAY}.
3515 @multitable @columnfractions .15 .80
3516 @item @emph{Array Type} @tab @emph{Boundary Value}
3517 @item Numeric @tab 0 of the type and kind of @var{ARRAY}.
3518 @item Logical @tab @code{.FALSE.}.
3519 @item Character(@var{len}) @tab @var{len} blanks.
3522 @item @emph{Standard}:
3523 Fortran 95 and later
3526 Transformational function
3528 @item @emph{Syntax}:
3529 @code{RESULT = EOSHIFT(ARRAY, SHIFT [, BOUNDARY, DIM])}
3531 @item @emph{Arguments}:
3532 @multitable @columnfractions .15 .70
3533 @item @var{ARRAY} @tab May be any type, not scalar.
3534 @item @var{SHIFT} @tab The type shall be @code{INTEGER}.
3535 @item @var{BOUNDARY} @tab Same type as @var{ARRAY}.
3536 @item @var{DIM} @tab The type shall be @code{INTEGER}.
3539 @item @emph{Return value}:
3540 Returns an array of same type and rank as the @var{ARRAY} argument.
3542 @item @emph{Example}:
3544 program test_eoshift
3545 integer, dimension(3,3) :: a
3546 a = reshape( (/ 1, 2, 3, 4, 5, 6, 7, 8, 9 /), (/ 3, 3 /))
3547 print '(3i3)', a(1,:)
3548 print '(3i3)', a(2,:)
3549 print '(3i3)', a(3,:)
3550 a = EOSHIFT(a, SHIFT=(/1, 2, 1/), BOUNDARY=-5, DIM=2)
3552 print '(3i3)', a(1,:)
3553 print '(3i3)', a(2,:)
3554 print '(3i3)', a(3,:)
3555 end program test_eoshift
3562 @section @code{EPSILON} --- Epsilon function
3564 @cindex model representation, epsilon
3567 @item @emph{Description}:
3568 @code{EPSILON(X)} returns the smallest number @var{E} of the same kind
3569 as @var{X} such that @math{1 + E > 1}.
3571 @item @emph{Standard}:
3572 Fortran 95 and later
3577 @item @emph{Syntax}:
3578 @code{RESULT = EPSILON(X)}
3580 @item @emph{Arguments}:
3581 @multitable @columnfractions .15 .70
3582 @item @var{X} @tab The type shall be @code{REAL}.
3585 @item @emph{Return value}:
3586 The return value is of same type as the argument.
3588 @item @emph{Example}:
3590 program test_epsilon
3595 end program test_epsilon
3602 @section @code{ERF} --- Error function
3604 @cindex error function
3607 @item @emph{Description}:
3608 @code{ERF(X)} computes the error function of @var{X}.
3610 @item @emph{Standard}:
3611 Fortran 2008 and later
3616 @item @emph{Syntax}:
3617 @code{RESULT = ERF(X)}
3619 @item @emph{Arguments}:
3620 @multitable @columnfractions .15 .70
3621 @item @var{X} @tab The type shall be @code{REAL}.
3624 @item @emph{Return value}:
3625 The return value is of type @code{REAL}, of the same kind as
3626 @var{X} and lies in the range @math{-1 \leq erf (x) \leq 1 }.
3628 @item @emph{Example}:
3631 real(8) :: x = 0.17_8
3633 end program test_erf
3636 @item @emph{Specific names}:
3637 @multitable @columnfractions .20 .20 .20 .25
3638 @item Name @tab Argument @tab Return type @tab Standard
3639 @item @code{DERF(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU extension
3646 @section @code{ERFC} --- Error function
3648 @cindex error function, complementary
3651 @item @emph{Description}:
3652 @code{ERFC(X)} computes the complementary error function of @var{X}.
3654 @item @emph{Standard}:
3655 Fortran 2008 and later
3660 @item @emph{Syntax}:
3661 @code{RESULT = ERFC(X)}
3663 @item @emph{Arguments}:
3664 @multitable @columnfractions .15 .70
3665 @item @var{X} @tab The type shall be @code{REAL}.
3668 @item @emph{Return value}:
3669 The return value is of type @code{REAL} and of the same kind as @var{X}.
3670 It lies in the range @math{ 0 \leq erfc (x) \leq 2 }.
3672 @item @emph{Example}:
3675 real(8) :: x = 0.17_8
3677 end program test_erfc
3680 @item @emph{Specific names}:
3681 @multitable @columnfractions .20 .20 .20 .25
3682 @item Name @tab Argument @tab Return type @tab Standard
3683 @item @code{DERFC(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU extension
3690 @section @code{ERFC_SCALED} --- Error function
3691 @fnindex ERFC_SCALED
3692 @cindex error function, complementary, exponentially-scaled
3695 @item @emph{Description}:
3696 @code{ERFC_SCALED(X)} computes the exponentially-scaled complementary
3697 error function of @var{X}.
3699 @item @emph{Standard}:
3700 Fortran 2008 and later
3705 @item @emph{Syntax}:
3706 @code{RESULT = ERFC_SCALED(X)}
3708 @item @emph{Arguments}:
3709 @multitable @columnfractions .15 .70
3710 @item @var{X} @tab The type shall be @code{REAL}.
3713 @item @emph{Return value}:
3714 The return value is of type @code{REAL} and of the same kind as @var{X}.
3716 @item @emph{Example}:
3718 program test_erfc_scaled
3719 real(8) :: x = 0.17_8
3721 end program test_erfc_scaled
3728 @section @code{ETIME} --- Execution time subroutine (or function)
3730 @cindex time, elapsed
3733 @item @emph{Description}:
3734 @code{ETIME(VALUES, TIME)} returns the number of seconds of runtime
3735 since the start of the process's execution in @var{TIME}. @var{VALUES}
3736 returns the user and system components of this time in @code{VALUES(1)} and
3737 @code{VALUES(2)} respectively. @var{TIME} is equal to @code{VALUES(1) + VALUES(2)}.
3739 On some systems, the underlying timings are represented using types with
3740 sufficiently small limits that overflows (wrap around) are possible, such as
3741 32-bit types. Therefore, the values returned by this intrinsic might be, or
3742 become, negative, or numerically less than previous values, during a single
3743 run of the compiled program.
3745 This intrinsic is provided in both subroutine and function forms; however,
3746 only one form can be used in any given program unit.
3748 @var{VALUES} and @var{TIME} are @code{INTENT(OUT)} and provide the following:
3750 @multitable @columnfractions .15 .30 .60
3751 @item @tab @code{VALUES(1)}: @tab User time in seconds.
3752 @item @tab @code{VALUES(2)}: @tab System time in seconds.
3753 @item @tab @code{TIME}: @tab Run time since start in seconds.
3756 @item @emph{Standard}:
3760 Subroutine, function
3762 @item @emph{Syntax}:
3763 @multitable @columnfractions .80
3764 @item @code{CALL ETIME(VALUES, TIME)}.
3765 @item @code{TIME = ETIME(VALUES)}, (not recommended).
3768 @item @emph{Arguments}:
3769 @multitable @columnfractions .15 .70
3770 @item @var{VALUES}@tab The type shall be @code{REAL(4), DIMENSION(2)}.
3771 @item @var{TIME}@tab The type shall be @code{REAL(4)}.
3774 @item @emph{Return value}:
3775 Elapsed time in seconds since the start of program execution.
3777 @item @emph{Example}:
3781 real, dimension(2) :: tarray
3783 call ETIME(tarray, result)
3787 do i=1,100000000 ! Just a delay
3790 call ETIME(tarray, result)
3794 end program test_etime
3797 @item @emph{See also}:
3805 @section @code{EXIT} --- Exit the program with status.
3807 @cindex program termination
3808 @cindex terminate program
3811 @item @emph{Description}:
3812 @code{EXIT} causes immediate termination of the program with status. If status
3813 is omitted it returns the canonical @emph{success} for the system. All Fortran
3814 I/O units are closed.
3816 @item @emph{Standard}:
3822 @item @emph{Syntax}:
3823 @code{CALL EXIT([STATUS])}
3825 @item @emph{Arguments}:
3826 @multitable @columnfractions .15 .70
3827 @item @var{STATUS} @tab Shall be an @code{INTEGER} of the default kind.
3830 @item @emph{Return value}:
3831 @code{STATUS} is passed to the parent process on exit.
3833 @item @emph{Example}:
3836 integer :: STATUS = 0
3837 print *, 'This program is going to exit.'
3839 end program test_exit
3842 @item @emph{See also}:
3843 @ref{ABORT}, @ref{KILL}
3849 @section @code{EXP} --- Exponential function
3855 @cindex exponential function
3856 @cindex logarithmic function, inverse
3859 @item @emph{Description}:
3860 @code{EXP(X)} computes the base @math{e} exponential of @var{X}.
3862 @item @emph{Standard}:
3863 Fortran 77 and later, has overloads that are GNU extensions
3868 @item @emph{Syntax}:
3869 @code{RESULT = EXP(X)}
3871 @item @emph{Arguments}:
3872 @multitable @columnfractions .15 .70
3873 @item @var{X} @tab The type shall be @code{REAL} or
3877 @item @emph{Return value}:
3878 The return value has same type and kind as @var{X}.
3880 @item @emph{Example}:
3885 end program test_exp
3888 @item @emph{Specific names}:
3889 @multitable @columnfractions .20 .20 .20 .25
3890 @item Name @tab Argument @tab Return type @tab Standard
3891 @item @code{DEXP(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab Fortran 77 and later
3892 @item @code{CEXP(X)} @tab @code{COMPLEX(4) X} @tab @code{COMPLEX(4)} @tab Fortran 77 and later
3893 @item @code{ZEXP(X)} @tab @code{COMPLEX(8) X} @tab @code{COMPLEX(8)} @tab GNU extension
3894 @item @code{CDEXP(X)} @tab @code{COMPLEX(8) X} @tab @code{COMPLEX(8)} @tab GNU extension
3901 @section @code{EXPONENT} --- Exponent function
3903 @cindex real number, exponent
3904 @cindex floating point, exponent
3907 @item @emph{Description}:
3908 @code{EXPONENT(X)} returns the value of the exponent part of @var{X}. If @var{X}
3909 is zero the value returned is zero.
3911 @item @emph{Standard}:
3912 Fortran 95 and later
3917 @item @emph{Syntax}:
3918 @code{RESULT = EXPONENT(X)}
3920 @item @emph{Arguments}:
3921 @multitable @columnfractions .15 .70
3922 @item @var{X} @tab The type shall be @code{REAL}.
3925 @item @emph{Return value}:
3926 The return value is of type default @code{INTEGER}.
3928 @item @emph{Example}:
3930 program test_exponent
3935 print *, exponent(0.0)
3936 end program test_exponent
3943 @section @code{FDATE} --- Get the current time as a string
3945 @cindex time, current
3946 @cindex current time
3947 @cindex date, current
3948 @cindex current date
3951 @item @emph{Description}:
3952 @code{FDATE(DATE)} returns the current date (using the same format as
3953 @code{CTIME}) in @var{DATE}. It is equivalent to @code{CALL CTIME(DATE,
3956 This intrinsic is provided in both subroutine and function forms; however,
3957 only one form can be used in any given program unit.
3959 @var{DATE} is an @code{INTENT(OUT)} @code{CHARACTER} variable of the
3962 @item @emph{Standard}:
3966 Subroutine, function
3968 @item @emph{Syntax}:
3969 @multitable @columnfractions .80
3970 @item @code{CALL FDATE(DATE)}.
3971 @item @code{DATE = FDATE()}, (not recommended).
3974 @item @emph{Arguments}:
3975 @multitable @columnfractions .15 .70
3976 @item @var{DATE}@tab The type shall be of type @code{CHARACTER} of the
3980 @item @emph{Return value}:
3981 The current date as a string.
3983 @item @emph{Example}:
3987 character(len=30) :: date
3989 print *, 'Program started on ', date
3990 do i = 1, 100000000 ! Just a delay
3994 print *, 'Program ended on ', date
3995 end program test_fdate
4002 @section @code{FLOAT} --- Convert integer to default real
4004 @cindex conversion, to real
4007 @item @emph{Description}:
4008 @code{FLOAT(A)} converts the integer @var{A} to a default real value.
4010 @item @emph{Standard}:
4011 Fortran 77 and later
4016 @item @emph{Syntax}:
4017 @code{RESULT = FLOAT(A)}
4019 @item @emph{Arguments}:
4020 @multitable @columnfractions .15 .70
4021 @item @var{A} @tab The type shall be @code{INTEGER}.
4024 @item @emph{Return value}:
4025 The return value is of type default @code{REAL}.
4027 @item @emph{Example}:
4031 if (float(i) /= 1.) call abort
4032 end program test_float
4035 @item @emph{See also}:
4036 @ref{DBLE}, @ref{DFLOAT}, @ref{REAL}
4042 @section @code{FGET} --- Read a single character in stream mode from stdin
4044 @cindex read character, stream mode
4045 @cindex stream mode, read character
4046 @cindex file operation, read character
4049 @item @emph{Description}:
4050 Read a single character in stream mode from stdin by bypassing normal
4051 formatted output. Stream I/O should not be mixed with normal record-oriented
4052 (formatted or unformatted) I/O on the same unit; the results are unpredictable.
4054 This intrinsic is provided in both subroutine and function forms; however,
4055 only one form can be used in any given program unit.
4057 Note that the @code{FGET} intrinsic is provided for backwards compatibility with
4058 @command{g77}. GNU Fortran provides the Fortran 2003 Stream facility.
4059 Programmers should consider the use of new stream IO feature in new code
4060 for future portability. See also @ref{Fortran 2003 status}.
4062 @item @emph{Standard}:
4066 Subroutine, function
4068 @item @emph{Syntax}:
4069 @code{CALL FGET(C [, STATUS])}
4071 @item @emph{Arguments}:
4072 @multitable @columnfractions .15 .70
4073 @item @var{C} @tab The type shall be @code{CHARACTER} and of default
4075 @item @var{STATUS} @tab (Optional) status flag of type @code{INTEGER}.
4076 Returns 0 on success, -1 on end-of-file, and a system specific positive
4077 error code otherwise.
4080 @item @emph{Example}:
4083 INTEGER, PARAMETER :: strlen = 100
4084 INTEGER :: status, i = 1
4085 CHARACTER(len=strlen) :: str = ""
4087 WRITE (*,*) 'Enter text:'
4089 CALL fget(str(i:i), status)
4090 if (status /= 0 .OR. i > strlen) exit
4093 WRITE (*,*) TRIM(str)
4097 @item @emph{See also}:
4098 @ref{FGETC}, @ref{FPUT}, @ref{FPUTC}
4104 @section @code{FGETC} --- Read a single character in stream mode
4106 @cindex read character, stream mode
4107 @cindex stream mode, read character
4108 @cindex file operation, read character
4111 @item @emph{Description}:
4112 Read a single character in stream mode by bypassing normal formatted output.
4113 Stream I/O should not be mixed with normal record-oriented (formatted or
4114 unformatted) I/O on the same unit; the results are unpredictable.
4116 This intrinsic is provided in both subroutine and function forms; however,
4117 only one form can be used in any given program unit.
4119 Note that the @code{FGET} intrinsic is provided for backwards compatibility
4120 with @command{g77}. GNU Fortran provides the Fortran 2003 Stream facility.
4121 Programmers should consider the use of new stream IO feature in new code
4122 for future portability. See also @ref{Fortran 2003 status}.
4124 @item @emph{Standard}:
4128 Subroutine, function
4130 @item @emph{Syntax}:
4131 @code{CALL FGETC(UNIT, C [, STATUS])}
4133 @item @emph{Arguments}:
4134 @multitable @columnfractions .15 .70
4135 @item @var{UNIT} @tab The type shall be @code{INTEGER}.
4136 @item @var{C} @tab The type shall be @code{CHARACTER} and of default
4138 @item @var{STATUS} @tab (Optional) status flag of type @code{INTEGER}.
4139 Returns 0 on success, -1 on end-of-file and a system specific positive
4140 error code otherwise.
4143 @item @emph{Example}:
4146 INTEGER :: fd = 42, status
4149 OPEN(UNIT=fd, FILE="/etc/passwd", ACTION="READ", STATUS = "OLD")
4151 CALL fgetc(fd, c, status)
4152 IF (status /= 0) EXIT
4159 @item @emph{See also}:
4160 @ref{FGET}, @ref{FPUT}, @ref{FPUTC}
4166 @section @code{FLOOR} --- Integer floor function
4169 @cindex rounding, floor
4172 @item @emph{Description}:
4173 @code{FLOOR(A)} returns the greatest integer less than or equal to @var{X}.
4175 @item @emph{Standard}:
4176 Fortran 95 and later
4181 @item @emph{Syntax}:
4182 @code{RESULT = FLOOR(A [, KIND])}
4184 @item @emph{Arguments}:
4185 @multitable @columnfractions .15 .70
4186 @item @var{A} @tab The type shall be @code{REAL}.
4187 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
4188 expression indicating the kind parameter of the result.
4191 @item @emph{Return value}:
4192 The return value is of type @code{INTEGER(KIND)} if @var{KIND} is present
4193 and of default-kind @code{INTEGER} otherwise.
4195 @item @emph{Example}:
4200 print *, floor(x) ! returns 63
4201 print *, floor(y) ! returns -64
4202 end program test_floor
4205 @item @emph{See also}:
4206 @ref{CEILING}, @ref{NINT}
4213 @section @code{FLUSH} --- Flush I/O unit(s)
4215 @cindex file operation, flush
4218 @item @emph{Description}:
4219 Flushes Fortran unit(s) currently open for output. Without the optional
4220 argument, all units are flushed, otherwise just the unit specified.
4222 @item @emph{Standard}:
4228 @item @emph{Syntax}:
4229 @code{CALL FLUSH(UNIT)}
4231 @item @emph{Arguments}:
4232 @multitable @columnfractions .15 .70
4233 @item @var{UNIT} @tab (Optional) The type shall be @code{INTEGER}.
4237 Beginning with the Fortran 2003 standard, there is a @code{FLUSH}
4238 statement that should be preferred over the @code{FLUSH} intrinsic.
4245 @section @code{FNUM} --- File number function
4247 @cindex file operation, file number
4250 @item @emph{Description}:
4251 @code{FNUM(UNIT)} returns the POSIX file descriptor number corresponding to the
4252 open Fortran I/O unit @code{UNIT}.
4254 @item @emph{Standard}:
4260 @item @emph{Syntax}:
4261 @code{RESULT = FNUM(UNIT)}
4263 @item @emph{Arguments}:
4264 @multitable @columnfractions .15 .70
4265 @item @var{UNIT} @tab The type shall be @code{INTEGER}.
4268 @item @emph{Return value}:
4269 The return value is of type @code{INTEGER}
4271 @item @emph{Example}:
4275 open (unit=10, status = "scratch")
4279 end program test_fnum
4286 @section @code{FPUT} --- Write a single character in stream mode to stdout
4288 @cindex write character, stream mode
4289 @cindex stream mode, write character
4290 @cindex file operation, write character
4293 @item @emph{Description}:
4294 Write a single character in stream mode to stdout by bypassing normal
4295 formatted output. Stream I/O should not be mixed with normal record-oriented
4296 (formatted or unformatted) I/O on the same unit; the results are unpredictable.
4298 This intrinsic is provided in both subroutine and function forms; however,
4299 only one form can be used in any given program unit.
4301 Note that the @code{FGET} intrinsic is provided for backwards compatibility with
4302 @command{g77}. GNU Fortran provides the Fortran 2003 Stream facility.
4303 Programmers should consider the use of new stream IO feature in new code
4304 for future portability. See also @ref{Fortran 2003 status}.
4306 @item @emph{Standard}:
4310 Subroutine, function
4312 @item @emph{Syntax}:
4313 @code{CALL FPUT(C [, STATUS])}
4315 @item @emph{Arguments}:
4316 @multitable @columnfractions .15 .70
4317 @item @var{C} @tab The type shall be @code{CHARACTER} and of default
4319 @item @var{STATUS} @tab (Optional) status flag of type @code{INTEGER}.
4320 Returns 0 on success, -1 on end-of-file and a system specific positive
4321 error code otherwise.
4324 @item @emph{Example}:
4327 CHARACTER(len=10) :: str = "gfortran"
4329 DO i = 1, len_trim(str)
4335 @item @emph{See also}:
4336 @ref{FPUTC}, @ref{FGET}, @ref{FGETC}
4342 @section @code{FPUTC} --- Write a single character in stream mode
4344 @cindex write character, stream mode
4345 @cindex stream mode, write character
4346 @cindex file operation, write character
4349 @item @emph{Description}:
4350 Write a single character in stream mode by bypassing normal formatted
4351 output. Stream I/O should not be mixed with normal record-oriented
4352 (formatted or unformatted) I/O on the same unit; the results are unpredictable.
4354 This intrinsic is provided in both subroutine and function forms; however,
4355 only one form can be used in any given program unit.
4357 Note that the @code{FGET} intrinsic is provided for backwards compatibility with
4358 @command{g77}. GNU Fortran provides the Fortran 2003 Stream facility.
4359 Programmers should consider the use of new stream IO feature in new code
4360 for future portability. See also @ref{Fortran 2003 status}.
4362 @item @emph{Standard}:
4366 Subroutine, function
4368 @item @emph{Syntax}:
4369 @code{CALL FPUTC(UNIT, C [, STATUS])}
4371 @item @emph{Arguments}:
4372 @multitable @columnfractions .15 .70
4373 @item @var{UNIT} @tab The type shall be @code{INTEGER}.
4374 @item @var{C} @tab The type shall be @code{CHARACTER} and of default
4376 @item @var{STATUS} @tab (Optional) status flag of type @code{INTEGER}.
4377 Returns 0 on success, -1 on end-of-file and a system specific positive
4378 error code otherwise.
4381 @item @emph{Example}:
4384 CHARACTER(len=10) :: str = "gfortran"
4385 INTEGER :: fd = 42, i
4387 OPEN(UNIT = fd, FILE = "out", ACTION = "WRITE", STATUS="NEW")
4388 DO i = 1, len_trim(str)
4389 CALL fputc(fd, str(i:i))
4395 @item @emph{See also}:
4396 @ref{FPUT}, @ref{FGET}, @ref{FGETC}
4402 @section @code{FRACTION} --- Fractional part of the model representation
4404 @cindex real number, fraction
4405 @cindex floating point, fraction
4408 @item @emph{Description}:
4409 @code{FRACTION(X)} returns the fractional part of the model
4410 representation of @code{X}.
4412 @item @emph{Standard}:
4413 Fortran 95 and later
4418 @item @emph{Syntax}:
4419 @code{Y = FRACTION(X)}
4421 @item @emph{Arguments}:
4422 @multitable @columnfractions .15 .70
4423 @item @var{X} @tab The type of the argument shall be a @code{REAL}.
4426 @item @emph{Return value}:
4427 The return value is of the same type and kind as the argument.
4428 The fractional part of the model representation of @code{X} is returned;
4429 it is @code{X * RADIX(X)**(-EXPONENT(X))}.
4431 @item @emph{Example}:
4433 program test_fraction
4436 print *, fraction(x), x * radix(x)**(-exponent(x))
4437 end program test_fraction
4445 @section @code{FREE} --- Frees memory
4447 @cindex pointer, cray
4450 @item @emph{Description}:
4451 Frees memory previously allocated by @code{MALLOC()}. The @code{FREE}
4452 intrinsic is an extension intended to be used with Cray pointers, and is
4453 provided in GNU Fortran to allow user to compile legacy code. For
4454 new code using Fortran 95 pointers, the memory de-allocation intrinsic is
4457 @item @emph{Standard}:
4463 @item @emph{Syntax}:
4464 @code{CALL FREE(PTR)}
4466 @item @emph{Arguments}:
4467 @multitable @columnfractions .15 .70
4468 @item @var{PTR} @tab The type shall be @code{INTEGER}. It represents the
4469 location of the memory that should be de-allocated.
4472 @item @emph{Return value}:
4475 @item @emph{Example}:
4476 See @code{MALLOC} for an example.
4478 @item @emph{See also}:
4485 @section @code{FSEEK} --- Low level file positioning subroutine
4487 @cindex file operation, seek
4488 @cindex file operation, position
4491 @item @emph{Description}:
4492 Moves @var{UNIT} to the specified @var{OFFSET}. If @var{WHENCE}
4493 is set to 0, the @var{OFFSET} is taken as an absolute value @code{SEEK_SET},
4494 if set to 1, @var{OFFSET} is taken to be relative to the current position
4495 @code{SEEK_CUR}, and if set to 2 relative to the end of the file @code{SEEK_END}.
4496 On error, @var{STATUS} is set to a nonzero value. If @var{STATUS} the seek
4499 This intrinsic routine is not fully backwards compatible with @command{g77}.
4500 In @command{g77}, the @code{FSEEK} takes a statement label instead of a
4501 @var{STATUS} variable. If FSEEK is used in old code, change
4503 CALL FSEEK(UNIT, OFFSET, WHENCE, *label)
4508 CALL FSEEK(UNIT, OFFSET, WHENCE, status)
4509 IF (status /= 0) GOTO label
4512 Please note that GNU Fortran provides the Fortran 2003 Stream facility.
4513 Programmers should consider the use of new stream IO feature in new code
4514 for future portability. See also @ref{Fortran 2003 status}.
4516 @item @emph{Standard}:
4522 @item @emph{Syntax}:
4523 @code{CALL FSEEK(UNIT, OFFSET, WHENCE[, STATUS])}
4525 @item @emph{Arguments}:
4526 @multitable @columnfractions .15 .70
4527 @item @var{UNIT} @tab Shall be a scalar of type @code{INTEGER}.
4528 @item @var{OFFSET} @tab Shall be a scalar of type @code{INTEGER}.
4529 @item @var{WHENCE} @tab Shall be a scalar of type @code{INTEGER}.
4530 Its value shall be either 0, 1 or 2.
4531 @item @var{STATUS} @tab (Optional) shall be a scalar of type
4535 @item @emph{Example}:
4538 INTEGER, PARAMETER :: SEEK_SET = 0, SEEK_CUR = 1, SEEK_END = 2
4539 INTEGER :: fd, offset, ierr
4545 OPEN(UNIT=fd, FILE="fseek.test")
4546 CALL FSEEK(fd, offset, SEEK_SET, ierr) ! move to OFFSET
4547 print *, FTELL(fd), ierr
4549 CALL FSEEK(fd, 0, SEEK_END, ierr) ! move to end
4550 print *, FTELL(fd), ierr
4552 CALL FSEEK(fd, 0, SEEK_SET, ierr) ! move to beginning
4553 print *, FTELL(fd), ierr
4559 @item @emph{See also}:
4566 @section @code{FSTAT} --- Get file status
4568 @cindex file system, file status
4571 @item @emph{Description}:
4572 @code{FSTAT} is identical to @ref{STAT}, except that information about an
4573 already opened file is obtained.
4575 The elements in @code{VALUES} are the same as described by @ref{STAT}.
4577 This intrinsic is provided in both subroutine and function forms; however,
4578 only one form can be used in any given program unit.
4580 @item @emph{Standard}:
4584 Subroutine, function
4586 @item @emph{Syntax}:
4587 @code{CALL FSTAT(UNIT, VALUES [, STATUS])}
4589 @item @emph{Arguments}:
4590 @multitable @columnfractions .15 .70
4591 @item @var{UNIT} @tab An open I/O unit number of type @code{INTEGER}.
4592 @item @var{VALUES} @tab The type shall be @code{INTEGER(4), DIMENSION(13)}.
4593 @item @var{STATUS} @tab (Optional) status flag of type @code{INTEGER(4)}. Returns 0
4594 on success and a system specific error code otherwise.
4597 @item @emph{Example}:
4598 See @ref{STAT} for an example.
4600 @item @emph{See also}:
4601 To stat a link: @ref{LSTAT}, to stat a file: @ref{STAT}
4607 @section @code{FTELL} --- Current stream position
4609 @cindex file operation, position
4612 @item @emph{Description}:
4613 Retrieves the current position within an open file.
4615 This intrinsic is provided in both subroutine and function forms; however,
4616 only one form can be used in any given program unit.
4618 @item @emph{Standard}:
4622 Subroutine, function
4624 @item @emph{Syntax}:
4625 @multitable @columnfractions .80
4626 @item @code{CALL FTELL(UNIT, OFFSET)}
4627 @item @code{OFFSET = FTELL(UNIT)}
4630 @item @emph{Arguments}:
4631 @multitable @columnfractions .15 .70
4632 @item @var{OFFSET} @tab Shall of type @code{INTEGER}.
4633 @item @var{UNIT} @tab Shall of type @code{INTEGER}.
4636 @item @emph{Return value}:
4637 In either syntax, @var{OFFSET} is set to the current offset of unit
4638 number @var{UNIT}, or to @math{-1} if the unit is not currently open.
4640 @item @emph{Example}:
4644 OPEN(10, FILE="temp.dat")
4650 @item @emph{See also}:
4657 @section @code{GAMMA} --- Gamma function
4660 @cindex Gamma function
4661 @cindex Factorial function
4664 @item @emph{Description}:
4665 @code{GAMMA(X)} computes Gamma (@math{\Gamma}) of @var{X}. For positive,
4666 integer values of @var{X} the Gamma function simplifies to the factorial
4667 function @math{\Gamma(x)=(x-1)!}.
4671 \Gamma(x) = \int_0^\infty t^{x-1}{\rm e}^{-t}\,{\rm d}t
4675 @item @emph{Standard}:
4676 Fortran 2008 and later
4681 @item @emph{Syntax}:
4684 @item @emph{Arguments}:
4685 @multitable @columnfractions .15 .70
4686 @item @var{X} @tab Shall be of type @code{REAL} and neither zero
4687 nor a negative integer.
4690 @item @emph{Return value}:
4691 The return value is of type @code{REAL} of the same kind as @var{X}.
4693 @item @emph{Example}:
4697 x = gamma(x) ! returns 1.0
4698 end program test_gamma
4701 @item @emph{Specific names}:
4702 @multitable @columnfractions .20 .20 .20 .25
4703 @item Name @tab Argument @tab Return type @tab Standard
4704 @item @code{GAMMA(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab GNU Extension
4705 @item @code{DGAMMA(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU Extension
4708 @item @emph{See also}:
4709 Logarithm of the Gamma function: @ref{LOG_GAMMA}
4716 @section @code{GERROR} --- Get last system error message
4718 @cindex system, error handling
4721 @item @emph{Description}:
4722 Returns the system error message corresponding to the last system error.
4723 This resembles the functionality of @code{strerror(3)} in C.
4725 @item @emph{Standard}:
4731 @item @emph{Syntax}:
4732 @code{CALL GERROR(RESULT)}
4734 @item @emph{Arguments}:
4735 @multitable @columnfractions .15 .70
4736 @item @var{RESULT} @tab Shall of type @code{CHARACTER} and of default
4739 @item @emph{Example}:
4742 CHARACTER(len=100) :: msg
4748 @item @emph{See also}:
4749 @ref{IERRNO}, @ref{PERROR}
4755 @section @code{GETARG} --- Get command line arguments
4757 @cindex command-line arguments
4758 @cindex arguments, to program
4761 @item @emph{Description}:
4762 Retrieve the @var{POS}-th argument that was passed on the
4763 command line when the containing program was invoked.
4765 This intrinsic routine is provided for backwards compatibility with
4766 GNU Fortran 77. In new code, programmers should consider the use of
4767 the @ref{GET_COMMAND_ARGUMENT} intrinsic defined by the Fortran 2003
4770 @item @emph{Standard}:
4776 @item @emph{Syntax}:
4777 @code{CALL GETARG(POS, VALUE)}
4779 @item @emph{Arguments}:
4780 @multitable @columnfractions .15 .70
4781 @item @var{POS} @tab Shall be of type @code{INTEGER} and not wider than
4782 the default integer kind; @math{@var{POS} \geq 0}
4783 @item @var{VALUE} @tab Shall be of type @code{CHARACTER} and of default
4785 @item @var{VALUE} @tab Shall be of type @code{CHARACTER}.
4788 @item @emph{Return value}:
4789 After @code{GETARG} returns, the @var{VALUE} argument holds the
4790 @var{POS}th command line argument. If @var{VALUE} can not hold the
4791 argument, it is truncated to fit the length of @var{VALUE}. If there are
4792 less than @var{POS} arguments specified at the command line, @var{VALUE}
4793 will be filled with blanks. If @math{@var{POS} = 0}, @var{VALUE} is set
4794 to the name of the program (on systems that support this feature).
4796 @item @emph{Example}:
4800 CHARACTER(len=32) :: arg
4809 @item @emph{See also}:
4810 GNU Fortran 77 compatibility function: @ref{IARGC}
4812 Fortran 2003 functions and subroutines: @ref{GET_COMMAND},
4813 @ref{GET_COMMAND_ARGUMENT}, @ref{COMMAND_ARGUMENT_COUNT}
4819 @section @code{GET_COMMAND} --- Get the entire command line
4820 @fnindex GET_COMMAND
4821 @cindex command-line arguments
4822 @cindex arguments, to program
4825 @item @emph{Description}:
4826 Retrieve the entire command line that was used to invoke the program.
4828 @item @emph{Standard}:
4829 Fortran 2003 and later
4834 @item @emph{Syntax}:
4835 @code{CALL GET_COMMAND([COMMAND, LENGTH, STATUS])}
4837 @item @emph{Arguments}:
4838 @multitable @columnfractions .15 .70
4839 @item @var{COMMAND} @tab (Optional) shall be of type @code{CHARACTER} and
4841 @item @var{LENGTH} @tab (Optional) Shall be of type @code{INTEGER} and of
4843 @item @var{STATUS} @tab (Optional) Shall be of type @code{INTEGER} and of
4847 @item @emph{Return value}:
4848 If @var{COMMAND} is present, stores the entire command line that was used
4849 to invoke the program in @var{COMMAND}. If @var{LENGTH} is present, it is
4850 assigned the length of the command line. If @var{STATUS} is present, it
4851 is assigned 0 upon success of the command, -1 if @var{COMMAND} is too
4852 short to store the command line, or a positive value in case of an error.
4854 @item @emph{Example}:
4856 PROGRAM test_get_command
4857 CHARACTER(len=255) :: cmd
4858 CALL get_command(cmd)
4859 WRITE (*,*) TRIM(cmd)
4863 @item @emph{See also}:
4864 @ref{GET_COMMAND_ARGUMENT}, @ref{COMMAND_ARGUMENT_COUNT}
4869 @node GET_COMMAND_ARGUMENT
4870 @section @code{GET_COMMAND_ARGUMENT} --- Get command line arguments
4871 @fnindex GET_COMMAND_ARGUMENT
4872 @cindex command-line arguments
4873 @cindex arguments, to program
4876 @item @emph{Description}:
4877 Retrieve the @var{NUMBER}-th argument that was passed on the
4878 command line when the containing program was invoked.
4880 @item @emph{Standard}:
4881 Fortran 2003 and later
4886 @item @emph{Syntax}:
4887 @code{CALL GET_COMMAND_ARGUMENT(NUMBER [, VALUE, LENGTH, STATUS])}
4889 @item @emph{Arguments}:
4890 @multitable @columnfractions .15 .70
4891 @item @var{NUMBER} @tab Shall be a scalar of type @code{INTEGER} and of
4892 default kind, @math{@var{NUMBER} \geq 0}
4893 @item @var{VALUE} @tab Shall be a scalar of type @code{CHARACTER}
4894 and of default kind.
4895 @item @var{LENGTH} @tab (Option) Shall be a scalar of type @code{INTEGER}
4896 and of default kind.
4897 @item @var{STATUS} @tab (Option) Shall be a scalar of type @code{INTEGER}
4898 and of default kind.
4901 @item @emph{Return value}:
4902 After @code{GET_COMMAND_ARGUMENT} returns, the @var{VALUE} argument holds the
4903 @var{NUMBER}-th command line argument. If @var{VALUE} can not hold the argument, it is
4904 truncated to fit the length of @var{VALUE}. If there are less than @var{NUMBER}
4905 arguments specified at the command line, @var{VALUE} will be filled with blanks.
4906 If @math{@var{NUMBER} = 0}, @var{VALUE} is set to the name of the program (on
4907 systems that support this feature). The @var{LENGTH} argument contains the
4908 length of the @var{NUMBER}-th command line argument. If the argument retrieval
4909 fails, @var{STATUS} is a positive number; if @var{VALUE} contains a truncated
4910 command line argument, @var{STATUS} is -1; and otherwise the @var{STATUS} is
4913 @item @emph{Example}:
4915 PROGRAM test_get_command_argument
4917 CHARACTER(len=32) :: arg
4921 CALL get_command_argument(i, arg)
4922 IF (LEN_TRIM(arg) == 0) EXIT
4924 WRITE (*,*) TRIM(arg)
4930 @item @emph{See also}:
4931 @ref{GET_COMMAND}, @ref{COMMAND_ARGUMENT_COUNT}
4937 @section @code{GETCWD} --- Get current working directory
4939 @cindex system, working directory
4942 @item @emph{Description}:
4943 Get current working directory.
4945 This intrinsic is provided in both subroutine and function forms; however,
4946 only one form can be used in any given program unit.
4948 @item @emph{Standard}:
4952 Subroutine, function
4954 @item @emph{Syntax}:
4955 @code{CALL GETCWD(C [, STATUS])}
4957 @item @emph{Arguments}:
4958 @multitable @columnfractions .15 .70
4959 @item @var{C} @tab The type shall be @code{CHARACTER} and of default kind.
4960 @item @var{STATUS} @tab (Optional) status flag. Returns 0 on success,
4961 a system specific and nonzero error code otherwise.
4964 @item @emph{Example}:
4967 CHARACTER(len=255) :: cwd
4969 WRITE(*,*) TRIM(cwd)
4973 @item @emph{See also}:
4980 @section @code{GETENV} --- Get an environmental variable
4982 @cindex environment variable
4985 @item @emph{Description}:
4986 Get the @var{VALUE} of the environmental variable @var{NAME}.
4988 This intrinsic routine is provided for backwards compatibility with
4989 GNU Fortran 77. In new code, programmers should consider the use of
4990 the @ref{GET_ENVIRONMENT_VARIABLE} intrinsic defined by the Fortran
4993 @item @emph{Standard}:
4999 @item @emph{Syntax}:
5000 @code{CALL GETENV(NAME, VALUE)}
5002 @item @emph{Arguments}:
5003 @multitable @columnfractions .15 .70
5004 @item @var{NAME} @tab Shall be of type @code{CHARACTER} and of default kind.
5005 @item @var{VALUE} @tab Shall be of type @code{CHARACTER} and of default kind.
5008 @item @emph{Return value}:
5009 Stores the value of @var{NAME} in @var{VALUE}. If @var{VALUE} is
5010 not large enough to hold the data, it is truncated. If @var{NAME}
5011 is not set, @var{VALUE} will be filled with blanks.
5013 @item @emph{Example}:
5016 CHARACTER(len=255) :: homedir
5017 CALL getenv("HOME", homedir)
5018 WRITE (*,*) TRIM(homedir)
5022 @item @emph{See also}:
5023 @ref{GET_ENVIRONMENT_VARIABLE}
5028 @node GET_ENVIRONMENT_VARIABLE
5029 @section @code{GET_ENVIRONMENT_VARIABLE} --- Get an environmental variable
5030 @fnindex GET_ENVIRONMENT_VARIABLE
5031 @cindex environment variable
5034 @item @emph{Description}:
5035 Get the @var{VALUE} of the environmental variable @var{NAME}.
5037 @item @emph{Standard}:
5038 Fortran 2003 and later
5043 @item @emph{Syntax}:
5044 @code{CALL GET_ENVIRONMENT_VARIABLE(NAME[, VALUE, LENGTH, STATUS, TRIM_NAME)}
5046 @item @emph{Arguments}:
5047 @multitable @columnfractions .15 .70
5048 @item @var{NAME} @tab Shall be a scalar of type @code{CHARACTER}
5049 and of default kind.
5050 @item @var{VALUE} @tab Shall be a scalar of type @code{CHARACTER}
5051 and of default kind.
5052 @item @var{LENGTH} @tab Shall be a scalar of type @code{INTEGER}
5053 and of default kind.
5054 @item @var{STATUS} @tab Shall be a scalar of type @code{INTEGER}
5055 and of default kind.
5056 @item @var{TRIM_NAME} @tab Shall be a scalar of type @code{LOGICAL}
5057 and of default kind.
5060 @item @emph{Return value}:
5061 Stores the value of @var{NAME} in @var{VALUE}. If @var{VALUE} is
5062 not large enough to hold the data, it is truncated. If @var{NAME}
5063 is not set, @var{VALUE} will be filled with blanks. Argument @var{LENGTH}
5064 contains the length needed for storing the environment variable @var{NAME}
5065 or zero if it is not present. @var{STATUS} is -1 if @var{VALUE} is present
5066 but too short for the environment variable; it is 1 if the environment
5067 variable does not exist and 2 if the processor does not support environment
5068 variables; in all other cases @var{STATUS} is zero. If @var{TRIM_NAME} is
5069 present with the value @code{.FALSE.}, the trailing blanks in @var{NAME}
5070 are significant; otherwise they are not part of the environment variable
5073 @item @emph{Example}:
5076 CHARACTER(len=255) :: homedir
5077 CALL get_environment_variable("HOME", homedir)
5078 WRITE (*,*) TRIM(homedir)
5086 @section @code{GETGID} --- Group ID function
5088 @cindex system, group id
5091 @item @emph{Description}:
5092 Returns the numerical group ID of the current process.
5094 @item @emph{Standard}:
5100 @item @emph{Syntax}:
5101 @code{RESULT = GETGID()}
5103 @item @emph{Return value}:
5104 The return value of @code{GETGID} is an @code{INTEGER} of the default
5108 @item @emph{Example}:
5109 See @code{GETPID} for an example.
5111 @item @emph{See also}:
5112 @ref{GETPID}, @ref{GETUID}
5118 @section @code{GETLOG} --- Get login name
5120 @cindex system, login name
5124 @item @emph{Description}:
5125 Gets the username under which the program is running.
5127 @item @emph{Standard}:
5133 @item @emph{Syntax}:
5134 @code{CALL GETLOG(C)}
5136 @item @emph{Arguments}:
5137 @multitable @columnfractions .15 .70
5138 @item @var{C} @tab Shall be of type @code{CHARACTER} and of default kind.
5141 @item @emph{Return value}:
5142 Stores the current user name in @var{LOGIN}. (On systems where POSIX
5143 functions @code{geteuid} and @code{getpwuid} are not available, and
5144 the @code{getlogin} function is not implemented either, this will
5145 return a blank string.)
5147 @item @emph{Example}:
5150 CHARACTER(32) :: login
5156 @item @emph{See also}:
5163 @section @code{GETPID} --- Process ID function
5165 @cindex system, process id
5169 @item @emph{Description}:
5170 Returns the numerical process identifier of the current process.
5172 @item @emph{Standard}:
5178 @item @emph{Syntax}:
5179 @code{RESULT = GETPID()}
5181 @item @emph{Return value}:
5182 The return value of @code{GETPID} is an @code{INTEGER} of the default
5186 @item @emph{Example}:
5189 print *, "The current process ID is ", getpid()
5190 print *, "Your numerical user ID is ", getuid()
5191 print *, "Your numerical group ID is ", getgid()
5195 @item @emph{See also}:
5196 @ref{GETGID}, @ref{GETUID}
5202 @section @code{GETUID} --- User ID function
5204 @cindex system, user id
5208 @item @emph{Description}:
5209 Returns the numerical user ID of the current process.
5211 @item @emph{Standard}:
5217 @item @emph{Syntax}:
5218 @code{RESULT = GETUID()}
5220 @item @emph{Return value}:
5221 The return value of @code{GETUID} is an @code{INTEGER} of the default
5225 @item @emph{Example}:
5226 See @code{GETPID} for an example.
5228 @item @emph{See also}:
5229 @ref{GETPID}, @ref{GETLOG}
5235 @section @code{GMTIME} --- Convert time to GMT info
5237 @cindex time, conversion to GMT info
5240 @item @emph{Description}:
5241 Given a system time value @var{TIME} (as provided by the @code{TIME8()}
5242 intrinsic), fills @var{VALUES} with values extracted from it appropriate
5243 to the UTC time zone (Universal Coordinated Time, also known in some
5244 countries as GMT, Greenwich Mean Time), using @code{gmtime(3)}.
5246 @item @emph{Standard}:
5252 @item @emph{Syntax}:
5253 @code{CALL GMTIME(TIME, VALUES)}
5255 @item @emph{Arguments}:
5256 @multitable @columnfractions .15 .70
5257 @item @var{TIME} @tab An @code{INTEGER} scalar expression
5258 corresponding to a system time, with @code{INTENT(IN)}.
5259 @item @var{VALUES} @tab A default @code{INTEGER} array with 9 elements,
5260 with @code{INTENT(OUT)}.
5263 @item @emph{Return value}:
5264 The elements of @var{VALUES} are assigned as follows:
5266 @item Seconds after the minute, range 0--59 or 0--61 to allow for leap
5268 @item Minutes after the hour, range 0--59
5269 @item Hours past midnight, range 0--23
5270 @item Day of month, range 0--31
5271 @item Number of months since January, range 0--12
5272 @item Years since 1900
5273 @item Number of days since Sunday, range 0--6
5274 @item Days since January 1
5275 @item Daylight savings indicator: positive if daylight savings is in
5276 effect, zero if not, and negative if the information is not available.
5279 @item @emph{See also}:
5280 @ref{CTIME}, @ref{LTIME}, @ref{TIME}, @ref{TIME8}
5287 @section @code{HOSTNM} --- Get system host name
5289 @cindex system, host name
5292 @item @emph{Description}:
5293 Retrieves the host name of the system on which the program is running.
5295 This intrinsic is provided in both subroutine and function forms; however,
5296 only one form can be used in any given program unit.
5298 @item @emph{Standard}:
5302 Subroutine, function
5304 @item @emph{Syntax}:
5305 @multitable @columnfractions .80
5306 @item @code{CALL HOSTNM(C [, STATUS])}
5307 @item @code{STATUS = HOSTNM(NAME)}
5310 @item @emph{Arguments}:
5311 @multitable @columnfractions .15 .70
5312 @item @var{C} @tab Shall of type @code{CHARACTER} and of default kind.
5313 @item @var{STATUS} @tab (Optional) status flag of type @code{INTEGER}.
5314 Returns 0 on success, or a system specific error code otherwise.
5317 @item @emph{Return value}:
5318 In either syntax, @var{NAME} is set to the current hostname if it can
5319 be obtained, or to a blank string otherwise.
5326 @section @code{HUGE} --- Largest number of a kind
5328 @cindex limits, largest number
5329 @cindex model representation, largest number
5332 @item @emph{Description}:
5333 @code{HUGE(X)} returns the largest number that is not an infinity in
5334 the model of the type of @code{X}.
5336 @item @emph{Standard}:
5337 Fortran 95 and later
5342 @item @emph{Syntax}:
5343 @code{RESULT = HUGE(X)}
5345 @item @emph{Arguments}:
5346 @multitable @columnfractions .15 .70
5347 @item @var{X} @tab Shall be of type @code{REAL} or @code{INTEGER}.
5350 @item @emph{Return value}:
5351 The return value is of the same type and kind as @var{X}
5353 @item @emph{Example}:
5355 program test_huge_tiny
5356 print *, huge(0), huge(0.0), huge(0.0d0)
5357 print *, tiny(0.0), tiny(0.0d0)
5358 end program test_huge_tiny
5365 @section @code{HYPOT} --- Euclidean distance function
5367 @cindex Euclidean distance
5370 @item @emph{Description}:
5371 @code{HYPOT(X,Y)} is the Euclidean distance function. It is equal to
5372 @math{\sqrt{X^2 + Y^2}}, without undue underflow or overflow.
5374 @item @emph{Standard}:
5375 Fortran 2008 and later
5380 @item @emph{Syntax}:
5381 @code{RESULT = HYPOT(X, Y)}
5383 @item @emph{Arguments}:
5384 @multitable @columnfractions .15 .70
5385 @item @var{X} @tab The type shall be @code{REAL}.
5386 @item @var{Y} @tab The type and kind type parameter shall be the same as
5390 @item @emph{Return value}:
5391 The return value has the same type and kind type parameter as @var{X}.
5393 @item @emph{Example}:
5396 real(4) :: x = 1.e0_4, y = 0.5e0_4
5398 end program test_hypot
5405 @section @code{IACHAR} --- Code in @acronym{ASCII} collating sequence
5407 @cindex @acronym{ASCII} collating sequence
5408 @cindex collating sequence, @acronym{ASCII}
5409 @cindex conversion, to integer
5412 @item @emph{Description}:
5413 @code{IACHAR(C)} returns the code for the @acronym{ASCII} character
5414 in the first character position of @code{C}.
5416 @item @emph{Standard}:
5417 Fortran 95 and later, with @var{KIND} argument Fortran 2003 and later
5422 @item @emph{Syntax}:
5423 @code{RESULT = IACHAR(C [, KIND])}
5425 @item @emph{Arguments}:
5426 @multitable @columnfractions .15 .70
5427 @item @var{C} @tab Shall be a scalar @code{CHARACTER}, with @code{INTENT(IN)}
5428 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
5429 expression indicating the kind parameter of the result.
5432 @item @emph{Return value}:
5433 The return value is of type @code{INTEGER} and of kind @var{KIND}. If
5434 @var{KIND} is absent, the return value is of default integer kind.
5436 @item @emph{Example}:
5441 end program test_iachar
5445 See @ref{ICHAR} for a discussion of converting between numerical values
5446 and formatted string representations.
5448 @item @emph{See also}:
5449 @ref{ACHAR}, @ref{CHAR}, @ref{ICHAR}
5456 @section @code{IAND} --- Bitwise logical and
5458 @cindex bitwise logical and
5459 @cindex logical and, bitwise
5462 @item @emph{Description}:
5463 Bitwise logical @code{AND}.
5465 @item @emph{Standard}:
5466 Fortran 95 and later
5471 @item @emph{Syntax}:
5472 @code{RESULT = IAND(I, J)}
5474 @item @emph{Arguments}:
5475 @multitable @columnfractions .15 .70
5476 @item @var{I} @tab The type shall be @code{INTEGER}.
5477 @item @var{J} @tab The type shall be @code{INTEGER}, of the same
5478 kind as @var{I}. (As a GNU extension, different kinds are also
5482 @item @emph{Return value}:
5483 The return type is @code{INTEGER}, of the same kind as the
5484 arguments. (If the argument kinds differ, it is of the same kind as
5485 the larger argument.)
5487 @item @emph{Example}:
5491 DATA a / Z'F' /, b / Z'3' /
5492 WRITE (*,*) IAND(a, b)
5496 @item @emph{See also}:
5497 @ref{IOR}, @ref{IEOR}, @ref{IBITS}, @ref{IBSET}, @ref{IBCLR}, @ref{NOT}
5504 @section @code{IARGC} --- Get the number of command line arguments
5506 @cindex command-line arguments
5507 @cindex command-line arguments, number of
5508 @cindex arguments, to program
5511 @item @emph{Description}:
5512 @code{IARGC()} returns the number of arguments passed on the
5513 command line when the containing program was invoked.
5515 This intrinsic routine is provided for backwards compatibility with
5516 GNU Fortran 77. In new code, programmers should consider the use of
5517 the @ref{COMMAND_ARGUMENT_COUNT} intrinsic defined by the Fortran 2003
5520 @item @emph{Standard}:
5526 @item @emph{Syntax}:
5527 @code{RESULT = IARGC()}
5529 @item @emph{Arguments}:
5532 @item @emph{Return value}:
5533 The number of command line arguments, type @code{INTEGER(4)}.
5535 @item @emph{Example}:
5538 @item @emph{See also}:
5539 GNU Fortran 77 compatibility subroutine: @ref{GETARG}
5541 Fortran 2003 functions and subroutines: @ref{GET_COMMAND},
5542 @ref{GET_COMMAND_ARGUMENT}, @ref{COMMAND_ARGUMENT_COUNT}
5548 @section @code{IBCLR} --- Clear bit
5554 @item @emph{Description}:
5555 @code{IBCLR} returns the value of @var{I} with the bit at position
5556 @var{POS} set to zero.
5558 @item @emph{Standard}:
5559 Fortran 95 and later
5564 @item @emph{Syntax}:
5565 @code{RESULT = IBCLR(I, POS)}
5567 @item @emph{Arguments}:
5568 @multitable @columnfractions .15 .70
5569 @item @var{I} @tab The type shall be @code{INTEGER}.
5570 @item @var{POS} @tab The type shall be @code{INTEGER}.
5573 @item @emph{Return value}:
5574 The return value is of type @code{INTEGER} and of the same kind as
5577 @item @emph{See also}:
5578 @ref{IBITS}, @ref{IBSET}, @ref{IAND}, @ref{IOR}, @ref{IEOR}, @ref{MVBITS}
5585 @section @code{IBITS} --- Bit extraction
5588 @cindex bits, extract
5591 @item @emph{Description}:
5592 @code{IBITS} extracts a field of length @var{LEN} from @var{I},
5593 starting from bit position @var{POS} and extending left for @var{LEN}
5594 bits. The result is right-justified and the remaining bits are
5595 zeroed. The value of @code{POS+LEN} must be less than or equal to the
5596 value @code{BIT_SIZE(I)}.
5598 @item @emph{Standard}:
5599 Fortran 95 and later
5604 @item @emph{Syntax}:
5605 @code{RESULT = IBITS(I, POS, LEN)}
5607 @item @emph{Arguments}:
5608 @multitable @columnfractions .15 .70
5609 @item @var{I} @tab The type shall be @code{INTEGER}.
5610 @item @var{POS} @tab The type shall be @code{INTEGER}.
5611 @item @var{LEN} @tab The type shall be @code{INTEGER}.
5614 @item @emph{Return value}:
5615 The return value is of type @code{INTEGER} and of the same kind as
5618 @item @emph{See also}:
5619 @ref{BIT_SIZE}, @ref{IBCLR}, @ref{IBSET}, @ref{IAND}, @ref{IOR}, @ref{IEOR}
5625 @section @code{IBSET} --- Set bit
5630 @item @emph{Description}:
5631 @code{IBSET} returns the value of @var{I} with the bit at position
5632 @var{POS} set to one.
5634 @item @emph{Standard}:
5635 Fortran 95 and later
5640 @item @emph{Syntax}:
5641 @code{RESULT = IBSET(I, POS)}
5643 @item @emph{Arguments}:
5644 @multitable @columnfractions .15 .70
5645 @item @var{I} @tab The type shall be @code{INTEGER}.
5646 @item @var{POS} @tab The type shall be @code{INTEGER}.
5649 @item @emph{Return value}:
5650 The return value is of type @code{INTEGER} and of the same kind as
5653 @item @emph{See also}:
5654 @ref{IBCLR}, @ref{IBITS}, @ref{IAND}, @ref{IOR}, @ref{IEOR}, @ref{MVBITS}
5661 @section @code{ICHAR} --- Character-to-integer conversion function
5663 @cindex conversion, to integer
5666 @item @emph{Description}:
5667 @code{ICHAR(C)} returns the code for the character in the first character
5668 position of @code{C} in the system's native character set.
5669 The correspondence between characters and their codes is not necessarily
5670 the same across different GNU Fortran implementations.
5672 @item @emph{Standard}:
5673 Fortan 95 and later, with @var{KIND} argument Fortran 2003 and later
5678 @item @emph{Syntax}:
5679 @code{RESULT = ICHAR(C [, KIND])}
5681 @item @emph{Arguments}:
5682 @multitable @columnfractions .15 .70
5683 @item @var{C} @tab Shall be a scalar @code{CHARACTER}, with @code{INTENT(IN)}
5684 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
5685 expression indicating the kind parameter of the result.
5688 @item @emph{Return value}:
5689 The return value is of type @code{INTEGER} and of kind @var{KIND}. If
5690 @var{KIND} is absent, the return value is of default integer kind.
5692 @item @emph{Example}:
5697 end program test_ichar
5701 No intrinsic exists to convert between a numeric value and a formatted
5702 character string representation -- for instance, given the
5703 @code{CHARACTER} value @code{'154'}, obtaining an @code{INTEGER} or
5704 @code{REAL} value with the value 154, or vice versa. Instead, this
5705 functionality is provided by internal-file I/O, as in the following
5710 character(len=10) string, string2
5713 ! Convert a string to a numeric value
5714 read (string,'(I10)') value
5717 ! Convert a value to a formatted string
5718 write (string2,'(I10)') value
5720 end program read_val
5723 @item @emph{See also}:
5724 @ref{ACHAR}, @ref{CHAR}, @ref{IACHAR}
5731 @section @code{IDATE} --- Get current local time subroutine (day/month/year)
5733 @cindex date, current
5734 @cindex current date
5737 @item @emph{Description}:
5738 @code{IDATE(VALUES)} Fills @var{VALUES} with the numerical values at the
5739 current local time. The day (in the range 1-31), month (in the range 1-12),
5740 and year appear in elements 1, 2, and 3 of @var{VALUES}, respectively.
5741 The year has four significant digits.
5743 @item @emph{Standard}:
5749 @item @emph{Syntax}:
5750 @code{CALL IDATE(VALUES)}
5752 @item @emph{Arguments}:
5753 @multitable @columnfractions .15 .70
5754 @item @var{VALUES} @tab The type shall be @code{INTEGER, DIMENSION(3)} and
5755 the kind shall be the default integer kind.
5758 @item @emph{Return value}:
5759 Does not return anything.
5761 @item @emph{Example}:
5764 integer, dimension(3) :: tarray
5769 end program test_idate
5776 @section @code{IEOR} --- Bitwise logical exclusive or
5778 @cindex bitwise logical exclusive or
5779 @cindex logical exclusive or, bitwise
5782 @item @emph{Description}:
5783 @code{IEOR} returns the bitwise boolean exclusive-OR of @var{I} and
5786 @item @emph{Standard}:
5787 Fortran 95 and later
5792 @item @emph{Syntax}:
5793 @code{RESULT = IEOR(I, J)}
5795 @item @emph{Arguments}:
5796 @multitable @columnfractions .15 .70
5797 @item @var{I} @tab The type shall be @code{INTEGER}.
5798 @item @var{J} @tab The type shall be @code{INTEGER}, of the same
5799 kind as @var{I}. (As a GNU extension, different kinds are also
5803 @item @emph{Return value}:
5804 The return type is @code{INTEGER}, of the same kind as the
5805 arguments. (If the argument kinds differ, it is of the same kind as
5806 the larger argument.)
5808 @item @emph{See also}:
5809 @ref{IOR}, @ref{IAND}, @ref{IBITS}, @ref{IBSET}, @ref{IBCLR}, @ref{NOT}
5815 @section @code{IERRNO} --- Get the last system error number
5817 @cindex system, error handling
5820 @item @emph{Description}:
5821 Returns the last system error number, as given by the C @code{errno()}
5824 @item @emph{Standard}:
5830 @item @emph{Syntax}:
5831 @code{RESULT = IERRNO()}
5833 @item @emph{Arguments}:
5836 @item @emph{Return value}:
5837 The return value is of type @code{INTEGER} and of the default integer
5840 @item @emph{See also}:
5846 @node INDEX intrinsic
5847 @section @code{INDEX} --- Position of a substring within a string
5849 @cindex substring position
5850 @cindex string, find substring
5853 @item @emph{Description}:
5854 Returns the position of the start of the first occurrence of string
5855 @var{SUBSTRING} as a substring in @var{STRING}, counting from one. If
5856 @var{SUBSTRING} is not present in @var{STRING}, zero is returned. If
5857 the @var{BACK} argument is present and true, the return value is the
5858 start of the last occurrence rather than the first.
5860 @item @emph{Standard}:
5861 Fortran 77 and later, with @var{KIND} argument Fortran 2003 and later
5866 @item @emph{Syntax}:
5867 @code{RESULT = INDEX(STRING, SUBSTRING [, BACK [, KIND]])}
5869 @item @emph{Arguments}:
5870 @multitable @columnfractions .15 .70
5871 @item @var{STRING} @tab Shall be a scalar @code{CHARACTER}, with
5873 @item @var{SUBSTRING} @tab Shall be a scalar @code{CHARACTER}, with
5875 @item @var{BACK} @tab (Optional) Shall be a scalar @code{LOGICAL}, with
5877 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
5878 expression indicating the kind parameter of the result.
5881 @item @emph{Return value}:
5882 The return value is of type @code{INTEGER} and of kind @var{KIND}. If
5883 @var{KIND} is absent, the return value is of default integer kind.
5885 @item @emph{See also}:
5886 @ref{SCAN}, @ref{VERIFY}
5892 @section @code{INT} --- Convert to integer type
5896 @cindex conversion, to integer
5899 @item @emph{Description}:
5900 Convert to integer type
5902 @item @emph{Standard}:
5903 Fortran 77 and later
5908 @item @emph{Syntax}:
5909 @code{RESULT = INT(A [, KIND))}
5911 @item @emph{Arguments}:
5912 @multitable @columnfractions .15 .70
5913 @item @var{A} @tab Shall be of type @code{INTEGER},
5914 @code{REAL}, or @code{COMPLEX}.
5915 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
5916 expression indicating the kind parameter of the result.
5919 @item @emph{Return value}:
5920 These functions return a @code{INTEGER} variable or array under
5921 the following rules:
5925 If @var{A} is of type @code{INTEGER}, @code{INT(A) = A}
5927 If @var{A} is of type @code{REAL} and @math{|A| < 1}, @code{INT(A)} equals @code{0}.
5928 If @math{|A| \geq 1}, then @code{INT(A)} equals the largest integer that does not exceed
5929 the range of @var{A} and whose sign is the same as the sign of @var{A}.
5931 If @var{A} is of type @code{COMPLEX}, rule B is applied to the real part of @var{A}.
5934 @item @emph{Example}:
5938 complex :: z = (-3.7, 1.0)
5940 print *, int(z), int(z,8)
5944 @item @emph{Specific names}:
5945 @multitable @columnfractions .20 .20 .20 .25
5946 @item Name @tab Argument @tab Return type @tab Standard
5947 @item @code{IFIX(A)} @tab @code{REAL(4) A} @tab @code{INTEGER} @tab Fortran 77 and later
5948 @item @code{IDINT(A)} @tab @code{REAL(8) A} @tab @code{INTEGER} @tab Fortran 77 and later
5956 @section @code{INT2} --- Convert to 16-bit integer type
5959 @cindex conversion, to integer
5962 @item @emph{Description}:
5963 Convert to a @code{KIND=2} integer type. This is equivalent to the
5964 standard @code{INT} intrinsic with an optional argument of
5965 @code{KIND=2}, and is only included for backwards compatibility.
5967 The @code{SHORT} intrinsic is equivalent to @code{INT2}.
5969 @item @emph{Standard}:
5975 @item @emph{Syntax}:
5976 @code{RESULT = INT2(A)}
5978 @item @emph{Arguments}:
5979 @multitable @columnfractions .15 .70
5980 @item @var{A} @tab Shall be of type @code{INTEGER},
5981 @code{REAL}, or @code{COMPLEX}.
5984 @item @emph{Return value}:
5985 The return value is a @code{INTEGER(2)} variable.
5987 @item @emph{See also}:
5988 @ref{INT}, @ref{INT8}, @ref{LONG}
5994 @section @code{INT8} --- Convert to 64-bit integer type
5996 @cindex conversion, to integer
5999 @item @emph{Description}:
6000 Convert to a @code{KIND=8} integer type. This is equivalent to the
6001 standard @code{INT} intrinsic with an optional argument of
6002 @code{KIND=8}, and is only included for backwards compatibility.
6004 @item @emph{Standard}:
6010 @item @emph{Syntax}:
6011 @code{RESULT = INT8(A)}
6013 @item @emph{Arguments}:
6014 @multitable @columnfractions .15 .70
6015 @item @var{A} @tab Shall be of type @code{INTEGER},
6016 @code{REAL}, or @code{COMPLEX}.
6019 @item @emph{Return value}:
6020 The return value is a @code{INTEGER(8)} variable.
6022 @item @emph{See also}:
6023 @ref{INT}, @ref{INT2}, @ref{LONG}
6029 @section @code{IOR} --- Bitwise logical or
6031 @cindex bitwise logical or
6032 @cindex logical or, bitwise
6035 @item @emph{Description}:
6036 @code{IOR} returns the bitwise boolean inclusive-OR of @var{I} and
6039 @item @emph{Standard}:
6040 Fortran 95 and later
6045 @item @emph{Syntax}:
6046 @code{RESULT = IOR(I, J)}
6048 @item @emph{Arguments}:
6049 @multitable @columnfractions .15 .70
6050 @item @var{I} @tab The type shall be @code{INTEGER}.
6051 @item @var{J} @tab The type shall be @code{INTEGER}, of the same
6052 kind as @var{I}. (As a GNU extension, different kinds are also
6056 @item @emph{Return value}:
6057 The return type is @code{INTEGER}, of the same kind as the
6058 arguments. (If the argument kinds differ, it is of the same kind as
6059 the larger argument.)
6061 @item @emph{See also}:
6062 @ref{IEOR}, @ref{IAND}, @ref{IBITS}, @ref{IBSET}, @ref{IBCLR}, @ref{NOT}
6068 @section @code{IRAND} --- Integer pseudo-random number
6070 @cindex random number generation
6073 @item @emph{Description}:
6074 @code{IRAND(FLAG)} returns a pseudo-random number from a uniform
6075 distribution between 0 and a system-dependent limit (which is in most
6076 cases 2147483647). If @var{FLAG} is 0, the next number
6077 in the current sequence is returned; if @var{FLAG} is 1, the generator
6078 is restarted by @code{CALL SRAND(0)}; if @var{FLAG} has any other value,
6079 it is used as a new seed with @code{SRAND}.
6081 This intrinsic routine is provided for backwards compatibility with
6082 GNU Fortran 77. It implements a simple modulo generator as provided
6083 by @command{g77}. For new code, one should consider the use of
6084 @ref{RANDOM_NUMBER} as it implements a superior algorithm.
6086 @item @emph{Standard}:
6092 @item @emph{Syntax}:
6093 @code{RESULT = IRAND(I)}
6095 @item @emph{Arguments}:
6096 @multitable @columnfractions .15 .70
6097 @item @var{I} @tab Shall be a scalar @code{INTEGER} of kind 4.
6100 @item @emph{Return value}:
6101 The return value is of @code{INTEGER(kind=4)} type.
6103 @item @emph{Example}:
6106 integer,parameter :: seed = 86456
6109 print *, irand(), irand(), irand(), irand()
6110 print *, irand(seed), irand(), irand(), irand()
6111 end program test_irand
6119 @section @code{IS_IOSTAT_END} --- Test for end-of-file value
6120 @fnindex IS_IOSTAT_END
6121 @cindex IOSTAT, end of file
6124 @item @emph{Description}:
6125 @code{IS_IOSTAT_END} tests whether an variable has the value of the I/O
6126 status ``end of file''. The function is equivalent to comparing the variable
6127 with the @code{IOSTAT_END} parameter of the intrinsic module
6128 @code{ISO_FORTRAN_ENV}.
6130 @item @emph{Standard}:
6131 Fortran 2003 and later
6136 @item @emph{Syntax}:
6137 @code{RESULT = IS_IOSTAT_END(I)}
6139 @item @emph{Arguments}:
6140 @multitable @columnfractions .15 .70
6141 @item @var{I} @tab Shall be of the type @code{INTEGER}.
6144 @item @emph{Return value}:
6145 Returns a @code{LOGICAL} of the default kind, which @code{.TRUE.} if
6146 @var{I} has the value which indicates an end of file condition for
6147 IOSTAT= specifiers, and is @code{.FALSE.} otherwise.
6149 @item @emph{Example}:
6154 OPEN(88, FILE='test.dat')
6155 READ(88, *, IOSTAT=stat) i
6156 IF(IS_IOSTAT_END(stat)) STOP 'END OF FILE'
6164 @section @code{IS_IOSTAT_EOR} --- Test for end-of-record value
6165 @fnindex IS_IOSTAT_EOR
6166 @cindex IOSTAT, end of record
6169 @item @emph{Description}:
6170 @code{IS_IOSTAT_EOR} tests whether an variable has the value of the I/O
6171 status ``end of record''. The function is equivalent to comparing the
6172 variable with the @code{IOSTAT_EOR} parameter of the intrinsic module
6173 @code{ISO_FORTRAN_ENV}.
6175 @item @emph{Standard}:
6176 Fortran 2003 and later
6181 @item @emph{Syntax}:
6182 @code{RESULT = IS_IOSTAT_EOR(I)}
6184 @item @emph{Arguments}:
6185 @multitable @columnfractions .15 .70
6186 @item @var{I} @tab Shall be of the type @code{INTEGER}.
6189 @item @emph{Return value}:
6190 Returns a @code{LOGICAL} of the default kind, which @code{.TRUE.} if
6191 @var{I} has the value which indicates an end of file condition for
6192 IOSTAT= specifiers, and is @code{.FALSE.} otherwise.
6194 @item @emph{Example}:
6198 INTEGER :: stat, i(50)
6199 OPEN(88, FILE='test.dat', FORM='UNFORMATTED')
6200 READ(88, IOSTAT=stat) i
6201 IF(IS_IOSTAT_EOR(stat)) STOP 'END OF RECORD'
6209 @section @code{ISATTY} --- Whether a unit is a terminal device.
6211 @cindex system, terminal
6214 @item @emph{Description}:
6215 Determine whether a unit is connected to a terminal device.
6217 @item @emph{Standard}:
6223 @item @emph{Syntax}:
6224 @code{RESULT = ISATTY(UNIT)}
6226 @item @emph{Arguments}:
6227 @multitable @columnfractions .15 .70
6228 @item @var{UNIT} @tab Shall be a scalar @code{INTEGER}.
6231 @item @emph{Return value}:
6232 Returns @code{.TRUE.} if the @var{UNIT} is connected to a terminal
6233 device, @code{.FALSE.} otherwise.
6235 @item @emph{Example}:
6238 INTEGER(kind=1) :: unit
6240 write(*,*) isatty(unit=unit)
6244 @item @emph{See also}:
6251 @section @code{ISHFT} --- Shift bits
6256 @item @emph{Description}:
6257 @code{ISHFT} returns a value corresponding to @var{I} with all of the
6258 bits shifted @var{SHIFT} places. A value of @var{SHIFT} greater than
6259 zero corresponds to a left shift, a value of zero corresponds to no
6260 shift, and a value less than zero corresponds to a right shift. If the
6261 absolute value of @var{SHIFT} is greater than @code{BIT_SIZE(I)}, the
6262 value is undefined. Bits shifted out from the left end or right end are
6263 lost; zeros are shifted in from the opposite end.
6265 @item @emph{Standard}:
6266 Fortran 95 and later
6271 @item @emph{Syntax}:
6272 @code{RESULT = ISHFT(I, SHIFT)}
6274 @item @emph{Arguments}:
6275 @multitable @columnfractions .15 .70
6276 @item @var{I} @tab The type shall be @code{INTEGER}.
6277 @item @var{SHIFT} @tab The type shall be @code{INTEGER}.
6280 @item @emph{Return value}:
6281 The return value is of type @code{INTEGER} and of the same kind as
6284 @item @emph{See also}:
6291 @section @code{ISHFTC} --- Shift bits circularly
6293 @cindex bits, shift circular
6296 @item @emph{Description}:
6297 @code{ISHFTC} returns a value corresponding to @var{I} with the
6298 rightmost @var{SIZE} bits shifted circularly @var{SHIFT} places; that
6299 is, bits shifted out one end are shifted into the opposite end. A value
6300 of @var{SHIFT} greater than zero corresponds to a left shift, a value of
6301 zero corresponds to no shift, and a value less than zero corresponds to
6302 a right shift. The absolute value of @var{SHIFT} must be less than
6303 @var{SIZE}. If the @var{SIZE} argument is omitted, it is taken to be
6304 equivalent to @code{BIT_SIZE(I)}.
6306 @item @emph{Standard}:
6307 Fortran 95 and later
6312 @item @emph{Syntax}:
6313 @code{RESULT = ISHFTC(I, SHIFT [, SIZE])}
6315 @item @emph{Arguments}:
6316 @multitable @columnfractions .15 .70
6317 @item @var{I} @tab The type shall be @code{INTEGER}.
6318 @item @var{SHIFT} @tab The type shall be @code{INTEGER}.
6319 @item @var{SIZE} @tab (Optional) The type shall be @code{INTEGER};
6320 the value must be greater than zero and less than or equal to
6324 @item @emph{Return value}:
6325 The return value is of type @code{INTEGER} and of the same kind as
6328 @item @emph{See also}:
6335 @section @code{ISNAN} --- Test for a NaN
6340 @item @emph{Description}:
6341 @code{ISNAN} tests whether a floating-point value is an IEEE
6343 @item @emph{Standard}:
6349 @item @emph{Syntax}:
6352 @item @emph{Arguments}:
6353 @multitable @columnfractions .15 .70
6354 @item @var{X} @tab Variable of the type @code{REAL}.
6358 @item @emph{Return value}:
6359 Returns a default-kind @code{LOGICAL}. The returned value is @code{TRUE}
6360 if @var{X} is a NaN and @code{FALSE} otherwise.
6362 @item @emph{Example}:
6369 if (isnan(x)) stop '"x" is a NaN'
6370 end program test_nan
6377 @section @code{ITIME} --- Get current local time subroutine (hour/minutes/seconds)
6379 @cindex time, current
6380 @cindex current time
6383 @item @emph{Description}:
6384 @code{IDATE(VALUES)} Fills @var{VALUES} with the numerical values at the
6385 current local time. The hour (in the range 1-24), minute (in the range 1-60),
6386 and seconds (in the range 1-60) appear in elements 1, 2, and 3 of @var{VALUES},
6389 @item @emph{Standard}:
6395 @item @emph{Syntax}:
6396 @code{CALL ITIME(VALUES)}
6398 @item @emph{Arguments}:
6399 @multitable @columnfractions .15 .70
6400 @item @var{VALUES} @tab The type shall be @code{INTEGER, DIMENSION(3)}
6401 and the kind shall be the default integer kind.
6404 @item @emph{Return value}:
6405 Does not return anything.
6408 @item @emph{Example}:
6411 integer, dimension(3) :: tarray
6416 end program test_itime
6423 @section @code{KILL} --- Send a signal to a process
6427 @item @emph{Description}:
6428 @item @emph{Standard}:
6429 Sends the signal specified by @var{SIGNAL} to the process @var{PID}.
6432 This intrinsic is provided in both subroutine and function forms; however,
6433 only one form can be used in any given program unit.
6436 Subroutine, function
6438 @item @emph{Syntax}:
6439 @code{CALL KILL(C, VALUE [, STATUS])}
6441 @item @emph{Arguments}:
6442 @multitable @columnfractions .15 .70
6443 @item @var{C} @tab Shall be a scalar @code{INTEGER}, with
6445 @item @var{VALUE} @tab Shall be a scalar @code{INTEGER}, with
6447 @item @var{STATUS} @tab (Optional) status flag of type @code{INTEGER(4)} or
6448 @code{INTEGER(8)}. Returns 0 on success, or a system-specific error code
6452 @item @emph{See also}:
6453 @ref{ABORT}, @ref{EXIT}
6459 @section @code{KIND} --- Kind of an entity
6464 @item @emph{Description}:
6465 @code{KIND(X)} returns the kind value of the entity @var{X}.
6467 @item @emph{Standard}:
6468 Fortran 95 and later
6473 @item @emph{Syntax}:
6476 @item @emph{Arguments}:
6477 @multitable @columnfractions .15 .70
6478 @item @var{X} @tab Shall be of type @code{LOGICAL}, @code{INTEGER},
6479 @code{REAL}, @code{COMPLEX} or @code{CHARACTER}.
6482 @item @emph{Return value}:
6483 The return value is a scalar of type @code{INTEGER} and of the default
6486 @item @emph{Example}:
6489 integer,parameter :: kc = kind(' ')
6490 integer,parameter :: kl = kind(.true.)
6492 print *, "The default character kind is ", kc
6493 print *, "The default logical kind is ", kl
6494 end program test_kind
6502 @section @code{LBOUND} --- Lower dimension bounds of an array
6504 @cindex array, lower bound
6507 @item @emph{Description}:
6508 Returns the lower bounds of an array, or a single lower bound
6509 along the @var{DIM} dimension.
6510 @item @emph{Standard}:
6511 Fortran 95 and later, with @var{KIND} argument Fortran 2003 and later
6516 @item @emph{Syntax}:
6517 @code{RESULT = LBOUND(ARRAY [, DIM [, KIND]])}
6519 @item @emph{Arguments}:
6520 @multitable @columnfractions .15 .70
6521 @item @var{ARRAY} @tab Shall be an array, of any type.
6522 @item @var{DIM} @tab (Optional) Shall be a scalar @code{INTEGER}.
6523 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
6524 expression indicating the kind parameter of the result.
6527 @item @emph{Return value}:
6528 The return value is of type @code{INTEGER} and of kind @var{KIND}. If
6529 @var{KIND} is absent, the return value is of default integer kind.
6530 If @var{DIM} is absent, the result is an array of the lower bounds of
6531 @var{ARRAY}. If @var{DIM} is present, the result is a scalar
6532 corresponding to the lower bound of the array along that dimension. If
6533 @var{ARRAY} is an expression rather than a whole array or array
6534 structure component, or if it has a zero extent along the relevant
6535 dimension, the lower bound is taken to be 1.
6537 @item @emph{See also}:
6544 @section @code{LEADZ} --- Number of leading zero bits of an integer
6549 @item @emph{Description}:
6550 @code{LEADZ} returns the number of leading zero bits of an integer.
6552 @item @emph{Standard}:
6553 Fortran 2008 and later
6558 @item @emph{Syntax}:
6559 @code{RESULT = LEADZ(I)}
6561 @item @emph{Arguments}:
6562 @multitable @columnfractions .15 .70
6563 @item @var{I} @tab Shall be of type @code{INTEGER}.
6566 @item @emph{Return value}:
6567 The type of the return value is the default @code{INTEGER}.
6568 If all the bits of @code{I} are zero, the result value is @code{BIT_SIZE(I)}.
6570 @item @emph{Example}:
6573 WRITE (*,*) LEADZ(1) ! prints 8 if BITSIZE(I) has the value 32
6577 @item @emph{See also}:
6578 @ref{BIT_SIZE}, @ref{TRAILZ}
6584 @section @code{LEN} --- Length of a character entity
6586 @cindex string, length
6589 @item @emph{Description}:
6590 Returns the length of a character string. If @var{STRING} is an array,
6591 the length of an element of @var{STRING} is returned. Note that
6592 @var{STRING} need not be defined when this intrinsic is invoked, since
6593 only the length, not the content, of @var{STRING} is needed.
6595 @item @emph{Standard}:
6596 Fortran 77 and later, with @var{KIND} argument Fortran 2003 and later
6601 @item @emph{Syntax}:
6602 @code{L = LEN(STRING [, KIND])}
6604 @item @emph{Arguments}:
6605 @multitable @columnfractions .15 .70
6606 @item @var{STRING} @tab Shall be a scalar or array of type
6607 @code{CHARACTER}, with @code{INTENT(IN)}
6608 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
6609 expression indicating the kind parameter of the result.
6612 @item @emph{Return value}:
6613 The return value is of type @code{INTEGER} and of kind @var{KIND}. If
6614 @var{KIND} is absent, the return value is of default integer kind.
6616 @item @emph{See also}:
6617 @ref{LEN_TRIM}, @ref{ADJUSTL}, @ref{ADJUSTR}
6623 @section @code{LEN_TRIM} --- Length of a character entity without trailing blank characters
6625 @cindex string, length, without trailing whitespace
6628 @item @emph{Description}:
6629 Returns the length of a character string, ignoring any trailing blanks.
6631 @item @emph{Standard}:
6632 Fortran 95 and later, with @var{KIND} argument Fortran 2003 and later
6637 @item @emph{Syntax}:
6638 @code{RESULT = LEN_TRIM(STRING [, KIND])}
6640 @item @emph{Arguments}:
6641 @multitable @columnfractions .15 .70
6642 @item @var{STRING} @tab Shall be a scalar of type @code{CHARACTER},
6643 with @code{INTENT(IN)}
6644 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
6645 expression indicating the kind parameter of the result.
6648 @item @emph{Return value}:
6649 The return value is of type @code{INTEGER} and of kind @var{KIND}. If
6650 @var{KIND} is absent, the return value is of default integer kind.
6652 @item @emph{See also}:
6653 @ref{LEN}, @ref{ADJUSTL}, @ref{ADJUSTR}
6659 @section @code{LGE} --- Lexical greater than or equal
6661 @cindex lexical comparison of strings
6662 @cindex string, comparison
6665 @item @emph{Description}:
6666 Determines whether one string is lexically greater than or equal to
6667 another string, where the two strings are interpreted as containing
6668 ASCII character codes. If the String A and String B are not the same
6669 length, the shorter is compared as if spaces were appended to it to form
6670 a value that has the same length as the longer.
6672 In general, the lexical comparison intrinsics @code{LGE}, @code{LGT},
6673 @code{LLE}, and @code{LLT} differ from the corresponding intrinsic
6674 operators @code{.GE.}, @code{.GT.}, @code{.LE.}, and @code{.LT.}, in
6675 that the latter use the processor's character ordering (which is not
6676 ASCII on some targets), whereas the former always use the ASCII
6679 @item @emph{Standard}:
6680 Fortran 77 and later
6685 @item @emph{Syntax}:
6686 @code{RESULT = LGE(STRING_A, STRING_B)}
6688 @item @emph{Arguments}:
6689 @multitable @columnfractions .15 .70
6690 @item @var{STRING_A} @tab Shall be of default @code{CHARACTER} type.
6691 @item @var{STRING_B} @tab Shall be of default @code{CHARACTER} type.
6694 @item @emph{Return value}:
6695 Returns @code{.TRUE.} if @code{STRING_A >= STRING_B}, and @code{.FALSE.}
6696 otherwise, based on the ASCII ordering.
6698 @item @emph{See also}:
6699 @ref{LGT}, @ref{LLE}, @ref{LLT}
6705 @section @code{LGT} --- Lexical greater than
6707 @cindex lexical comparison of strings
6708 @cindex string, comparison
6711 @item @emph{Description}:
6712 Determines whether one string is lexically greater than another string,
6713 where the two strings are interpreted as containing ASCII character
6714 codes. If the String A and String B are not the same length, the
6715 shorter is compared as if spaces were appended to it to form a value
6716 that has the same length as the longer.
6718 In general, the lexical comparison intrinsics @code{LGE}, @code{LGT},
6719 @code{LLE}, and @code{LLT} differ from the corresponding intrinsic
6720 operators @code{.GE.}, @code{.GT.}, @code{.LE.}, and @code{.LT.}, in
6721 that the latter use the processor's character ordering (which is not
6722 ASCII on some targets), whereas the former always use the ASCII
6725 @item @emph{Standard}:
6726 Fortran 77 and later
6731 @item @emph{Syntax}:
6732 @code{RESULT = LGT(STRING_A, STRING_B)}
6734 @item @emph{Arguments}:
6735 @multitable @columnfractions .15 .70
6736 @item @var{STRING_A} @tab Shall be of default @code{CHARACTER} type.
6737 @item @var{STRING_B} @tab Shall be of default @code{CHARACTER} type.
6740 @item @emph{Return value}:
6741 Returns @code{.TRUE.} if @code{STRING_A > STRING_B}, and @code{.FALSE.}
6742 otherwise, based on the ASCII ordering.
6744 @item @emph{See also}:
6745 @ref{LGE}, @ref{LLE}, @ref{LLT}
6751 @section @code{LINK} --- Create a hard link
6753 @cindex file system, create link
6754 @cindex file system, hard link
6757 @item @emph{Description}:
6758 Makes a (hard) link from file @var{PATH1} to @var{PATH2}. A null
6759 character (@code{CHAR(0)}) can be used to mark the end of the names in
6760 @var{PATH1} and @var{PATH2}; otherwise, trailing blanks in the file
6761 names are ignored. If the @var{STATUS} argument is supplied, it
6762 contains 0 on success or a nonzero error code upon return; see
6765 This intrinsic is provided in both subroutine and function forms;
6766 however, only one form can be used in any given program unit.
6768 @item @emph{Standard}:
6772 Subroutine, function
6774 @item @emph{Syntax}:
6775 @multitable @columnfractions .80
6776 @item @code{CALL LINK(PATH1, PATH2 [, STATUS])}
6777 @item @code{STATUS = LINK(PATH1, PATH2)}
6780 @item @emph{Arguments}:
6781 @multitable @columnfractions .15 .70
6782 @item @var{PATH1} @tab Shall be of default @code{CHARACTER} type.
6783 @item @var{PATH2} @tab Shall be of default @code{CHARACTER} type.
6784 @item @var{STATUS} @tab (Optional) Shall be of default @code{INTEGER} type.
6787 @item @emph{See also}:
6788 @ref{SYMLNK}, @ref{UNLINK}
6794 @section @code{LLE} --- Lexical less than or equal
6796 @cindex lexical comparison of strings
6797 @cindex string, comparison
6800 @item @emph{Description}:
6801 Determines whether one string is lexically less than or equal to another
6802 string, where the two strings are interpreted as containing ASCII
6803 character codes. If the String A and String B are not the same length,
6804 the shorter is compared as if spaces were appended to it to form a value
6805 that has the same length as the longer.
6807 In general, the lexical comparison intrinsics @code{LGE}, @code{LGT},
6808 @code{LLE}, and @code{LLT} differ from the corresponding intrinsic
6809 operators @code{.GE.}, @code{.GT.}, @code{.LE.}, and @code{.LT.}, in
6810 that the latter use the processor's character ordering (which is not
6811 ASCII on some targets), whereas the former always use the ASCII
6814 @item @emph{Standard}:
6815 Fortran 77 and later
6820 @item @emph{Syntax}:
6821 @code{RESULT = LLE(STRING_A, STRING_B)}
6823 @item @emph{Arguments}:
6824 @multitable @columnfractions .15 .70
6825 @item @var{STRING_A} @tab Shall be of default @code{CHARACTER} type.
6826 @item @var{STRING_B} @tab Shall be of default @code{CHARACTER} type.
6829 @item @emph{Return value}:
6830 Returns @code{.TRUE.} if @code{STRING_A <= STRING_B}, and @code{.FALSE.}
6831 otherwise, based on the ASCII ordering.
6833 @item @emph{See also}:
6834 @ref{LGE}, @ref{LGT}, @ref{LLT}
6840 @section @code{LLT} --- Lexical less than
6842 @cindex lexical comparison of strings
6843 @cindex string, comparison
6846 @item @emph{Description}:
6847 Determines whether one string is lexically less than another string,
6848 where the two strings are interpreted as containing ASCII character
6849 codes. If the String A and String B are not the same length, the
6850 shorter is compared as if spaces were appended to it to form a value
6851 that has the same length as the longer.
6853 In general, the lexical comparison intrinsics @code{LGE}, @code{LGT},
6854 @code{LLE}, and @code{LLT} differ from the corresponding intrinsic
6855 operators @code{.GE.}, @code{.GT.}, @code{.LE.}, and @code{.LT.}, in
6856 that the latter use the processor's character ordering (which is not
6857 ASCII on some targets), whereas the former always use the ASCII
6860 @item @emph{Standard}:
6861 Fortran 77 and later
6866 @item @emph{Syntax}:
6867 @code{RESULT = LLT(STRING_A, STRING_B)}
6869 @item @emph{Arguments}:
6870 @multitable @columnfractions .15 .70
6871 @item @var{STRING_A} @tab Shall be of default @code{CHARACTER} type.
6872 @item @var{STRING_B} @tab Shall be of default @code{CHARACTER} type.
6875 @item @emph{Return value}:
6876 Returns @code{.TRUE.} if @code{STRING_A < STRING_B}, and @code{.FALSE.}
6877 otherwise, based on the ASCII ordering.
6879 @item @emph{See also}:
6880 @ref{LGE}, @ref{LGT}, @ref{LLE}
6886 @section @code{LNBLNK} --- Index of the last non-blank character in a string
6888 @cindex string, find non-blank character
6891 @item @emph{Description}:
6892 Returns the length of a character string, ignoring any trailing blanks.
6893 This is identical to the standard @code{LEN_TRIM} intrinsic, and is only
6894 included for backwards compatibility.
6896 @item @emph{Standard}:
6902 @item @emph{Syntax}:
6903 @code{RESULT = LNBLNK(STRING)}
6905 @item @emph{Arguments}:
6906 @multitable @columnfractions .15 .70
6907 @item @var{STRING} @tab Shall be a scalar of type @code{CHARACTER},
6908 with @code{INTENT(IN)}
6911 @item @emph{Return value}:
6912 The return value is of @code{INTEGER(kind=4)} type.
6914 @item @emph{See also}:
6915 @ref{INDEX intrinsic}, @ref{LEN_TRIM}
6921 @section @code{LOC} --- Returns the address of a variable
6923 @cindex location of a variable in memory
6926 @item @emph{Description}:
6927 @code{LOC(X)} returns the address of @var{X} as an integer.
6929 @item @emph{Standard}:
6935 @item @emph{Syntax}:
6936 @code{RESULT = LOC(X)}
6938 @item @emph{Arguments}:
6939 @multitable @columnfractions .15 .70
6940 @item @var{X} @tab Variable of any type.
6943 @item @emph{Return value}:
6944 The return value is of type @code{INTEGER}, with a @code{KIND}
6945 corresponding to the size (in bytes) of a memory address on the target
6948 @item @emph{Example}:
6955 end program test_loc
6962 @section @code{LOG} --- Logarithm function
6969 @cindex exponential function, inverse
6970 @cindex logarithmic function
6973 @item @emph{Description}:
6974 @code{LOG(X)} computes the logarithm of @var{X}.
6976 @item @emph{Standard}:
6977 Fortran 77 and later
6982 @item @emph{Syntax}:
6983 @code{RESULT = LOG(X)}
6985 @item @emph{Arguments}:
6986 @multitable @columnfractions .15 .70
6987 @item @var{X} @tab The type shall be @code{REAL} or
6991 @item @emph{Return value}:
6992 The return value is of type @code{REAL} or @code{COMPLEX}.
6993 The kind type parameter is the same as @var{X}.
6994 If @var{X} is @code{COMPLEX}, the imaginary part @math{\omega} is in the range
6995 @math{-\pi \leq \omega \leq \pi}.
6997 @item @emph{Example}:
7000 real(8) :: x = 1.0_8
7001 complex :: z = (1.0, 2.0)
7004 end program test_log
7007 @item @emph{Specific names}:
7008 @multitable @columnfractions .20 .20 .20 .25
7009 @item Name @tab Argument @tab Return type @tab Standard
7010 @item @code{ALOG(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab f95, gnu
7011 @item @code{DLOG(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab f95, gnu
7012 @item @code{CLOG(X)} @tab @code{COMPLEX(4) X} @tab @code{COMPLEX(4)} @tab f95, gnu
7013 @item @code{ZLOG(X)} @tab @code{COMPLEX(8) X} @tab @code{COMPLEX(8)} @tab f95, gnu
7014 @item @code{CDLOG(X)} @tab @code{COMPLEX(8) X} @tab @code{COMPLEX(8)} @tab f95, gnu
7021 @section @code{LOG10} --- Base 10 logarithm function
7025 @cindex exponential function, inverse
7026 @cindex logarithmic function
7029 @item @emph{Description}:
7030 @code{LOG10(X)} computes the base 10 logarithm of @var{X}.
7032 @item @emph{Standard}:
7033 Fortran 77 and later
7038 @item @emph{Syntax}:
7039 @code{RESULT = LOG10(X)}
7041 @item @emph{Arguments}:
7042 @multitable @columnfractions .15 .70
7043 @item @var{X} @tab The type shall be @code{REAL}.
7046 @item @emph{Return value}:
7047 The return value is of type @code{REAL} or @code{COMPLEX}.
7048 The kind type parameter is the same as @var{X}.
7050 @item @emph{Example}:
7053 real(8) :: x = 10.0_8
7055 end program test_log10
7058 @item @emph{Specific names}:
7059 @multitable @columnfractions .20 .20 .20 .25
7060 @item Name @tab Argument @tab Return type @tab Standard
7061 @item @code{ALOG10(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab Fortran 95 and later
7062 @item @code{DLOG10(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab Fortran 95 and later
7069 @section @code{LOG_GAMMA} --- Logarithm of the Gamma function
7074 @cindex Gamma function, logarithm of
7077 @item @emph{Description}:
7078 @code{LOG_GAMMA(X)} computes the natural logarithm of the absolute value
7079 of the Gamma (@math{\Gamma}) function.
7081 @item @emph{Standard}:
7082 Fortran 2008 and later
7087 @item @emph{Syntax}:
7088 @code{X = LOG_GAMMA(X)}
7090 @item @emph{Arguments}:
7091 @multitable @columnfractions .15 .70
7092 @item @var{X} @tab Shall be of type @code{REAL} and neither zero
7093 nor a negative integer.
7096 @item @emph{Return value}:
7097 The return value is of type @code{REAL} of the same kind as @var{X}.
7099 @item @emph{Example}:
7101 program test_log_gamma
7103 x = lgamma(x) ! returns 0.0
7104 end program test_log_gamma
7107 @item @emph{Specific names}:
7108 @multitable @columnfractions .20 .20 .20 .25
7109 @item Name @tab Argument @tab Return type @tab Standard
7110 @item @code{LGAMMA(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab GNU Extension
7111 @item @code{ALGAMA(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab GNU Extension
7112 @item @code{DLGAMA(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU Extension
7115 @item @emph{See also}:
7116 Gamma function: @ref{GAMMA}
7123 @section @code{LOGICAL} --- Convert to logical type
7125 @cindex conversion, to logical
7128 @item @emph{Description}:
7129 Converts one kind of @code{LOGICAL} variable to another.
7131 @item @emph{Standard}:
7132 Fortran 95 and later
7137 @item @emph{Syntax}:
7138 @code{RESULT = LOGICAL(L [, KIND])}
7140 @item @emph{Arguments}:
7141 @multitable @columnfractions .15 .70
7142 @item @var{L} @tab The type shall be @code{LOGICAL}.
7143 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
7144 expression indicating the kind parameter of the result.
7147 @item @emph{Return value}:
7148 The return value is a @code{LOGICAL} value equal to @var{L}, with a
7149 kind corresponding to @var{KIND}, or of the default logical kind if
7150 @var{KIND} is not given.
7152 @item @emph{See also}:
7153 @ref{INT}, @ref{REAL}, @ref{CMPLX}
7159 @section @code{LONG} --- Convert to integer type
7161 @cindex conversion, to integer
7164 @item @emph{Description}:
7165 Convert to a @code{KIND=4} integer type, which is the same size as a C
7166 @code{long} integer. This is equivalent to the standard @code{INT}
7167 intrinsic with an optional argument of @code{KIND=4}, and is only
7168 included for backwards compatibility.
7170 @item @emph{Standard}:
7176 @item @emph{Syntax}:
7177 @code{RESULT = LONG(A)}
7179 @item @emph{Arguments}:
7180 @multitable @columnfractions .15 .70
7181 @item @var{A} @tab Shall be of type @code{INTEGER},
7182 @code{REAL}, or @code{COMPLEX}.
7185 @item @emph{Return value}:
7186 The return value is a @code{INTEGER(4)} variable.
7188 @item @emph{See also}:
7189 @ref{INT}, @ref{INT2}, @ref{INT8}
7195 @section @code{LSHIFT} --- Left shift bits
7197 @cindex bits, shift left
7200 @item @emph{Description}:
7201 @code{LSHIFT} returns a value corresponding to @var{I} with all of the
7202 bits shifted left by @var{SHIFT} places. If the absolute value of
7203 @var{SHIFT} is greater than @code{BIT_SIZE(I)}, the value is undefined.
7204 Bits shifted out from the left end are lost; zeros are shifted in from
7207 This function has been superseded by the @code{ISHFT} intrinsic, which
7208 is standard in Fortran 95 and later.
7210 @item @emph{Standard}:
7216 @item @emph{Syntax}:
7217 @code{RESULT = LSHIFT(I, SHIFT)}
7219 @item @emph{Arguments}:
7220 @multitable @columnfractions .15 .70
7221 @item @var{I} @tab The type shall be @code{INTEGER}.
7222 @item @var{SHIFT} @tab The type shall be @code{INTEGER}.
7225 @item @emph{Return value}:
7226 The return value is of type @code{INTEGER} and of the same kind as
7229 @item @emph{See also}:
7230 @ref{ISHFT}, @ref{ISHFTC}, @ref{RSHIFT}
7237 @section @code{LSTAT} --- Get file status
7239 @cindex file system, file status
7242 @item @emph{Description}:
7243 @code{LSTAT} is identical to @ref{STAT}, except that if path is a
7244 symbolic link, then the link itself is statted, not the file that it
7247 The elements in @code{VALUES} are the same as described by @ref{STAT}.
7249 This intrinsic is provided in both subroutine and function forms;
7250 however, only one form can be used in any given program unit.
7252 @item @emph{Standard}:
7256 Subroutine, function
7258 @item @emph{Syntax}:
7259 @code{CALL LSTAT(NAME, VALUES [, STATUS])}
7261 @item @emph{Arguments}:
7262 @multitable @columnfractions .15 .70
7263 @item @var{NAME} @tab The type shall be @code{CHARACTER} of the default
7264 kind, a valid path within the file system.
7265 @item @var{VALUES} @tab The type shall be @code{INTEGER(4), DIMENSION(13)}.
7266 @item @var{STATUS} @tab (Optional) status flag of type @code{INTEGER(4)}.
7267 Returns 0 on success and a system specific error code otherwise.
7270 @item @emph{Example}:
7271 See @ref{STAT} for an example.
7273 @item @emph{See also}:
7274 To stat an open file: @ref{FSTAT}, to stat a file: @ref{STAT}
7280 @section @code{LTIME} --- Convert time to local time info
7282 @cindex time, conversion to local time info
7285 @item @emph{Description}:
7286 Given a system time value @var{TIME} (as provided by the @code{TIME8()}
7287 intrinsic), fills @var{VALUES} with values extracted from it appropriate
7288 to the local time zone using @code{localtime(3)}.
7290 @item @emph{Standard}:
7296 @item @emph{Syntax}:
7297 @code{CALL LTIME(TIME, VALUES)}
7299 @item @emph{Arguments}:
7300 @multitable @columnfractions .15 .70
7301 @item @var{TIME} @tab An @code{INTEGER} scalar expression
7302 corresponding to a system time, with @code{INTENT(IN)}.
7303 @item @var{VALUES} @tab A default @code{INTEGER} array with 9 elements,
7304 with @code{INTENT(OUT)}.
7307 @item @emph{Return value}:
7308 The elements of @var{VALUES} are assigned as follows:
7310 @item Seconds after the minute, range 0--59 or 0--61 to allow for leap
7312 @item Minutes after the hour, range 0--59
7313 @item Hours past midnight, range 0--23
7314 @item Day of month, range 0--31
7315 @item Number of months since January, range 0--12
7316 @item Years since 1900
7317 @item Number of days since Sunday, range 0--6
7318 @item Days since January 1
7319 @item Daylight savings indicator: positive if daylight savings is in
7320 effect, zero if not, and negative if the information is not available.
7323 @item @emph{See also}:
7324 @ref{CTIME}, @ref{GMTIME}, @ref{TIME}, @ref{TIME8}
7331 @section @code{MALLOC} --- Allocate dynamic memory
7333 @cindex pointer, cray
7336 @item @emph{Description}:
7337 @code{MALLOC(SIZE)} allocates @var{SIZE} bytes of dynamic memory and
7338 returns the address of the allocated memory. The @code{MALLOC} intrinsic
7339 is an extension intended to be used with Cray pointers, and is provided
7340 in GNU Fortran to allow the user to compile legacy code. For new code
7341 using Fortran 95 pointers, the memory allocation intrinsic is
7344 @item @emph{Standard}:
7350 @item @emph{Syntax}:
7351 @code{PTR = MALLOC(SIZE)}
7353 @item @emph{Arguments}:
7354 @multitable @columnfractions .15 .70
7355 @item @var{SIZE} @tab The type shall be @code{INTEGER}.
7358 @item @emph{Return value}:
7359 The return value is of type @code{INTEGER(K)}, with @var{K} such that
7360 variables of type @code{INTEGER(K)} have the same size as
7361 C pointers (@code{sizeof(void *)}).
7363 @item @emph{Example}:
7364 The following example demonstrates the use of @code{MALLOC} and
7365 @code{FREE} with Cray pointers.
7374 ptr_x = malloc(20*8)
7376 x(i) = sqrt(1.0d0 / i)
7384 end program test_malloc
7387 @item @emph{See also}:
7394 @section @code{MATMUL} --- matrix multiplication
7396 @cindex matrix multiplication
7397 @cindex product, matrix
7400 @item @emph{Description}:
7401 Performs a matrix multiplication on numeric or logical arguments.
7403 @item @emph{Standard}:
7404 Fortran 95 and later
7407 Transformational function
7409 @item @emph{Syntax}:
7410 @code{RESULT = MATMUL(MATRIX_A, MATRIX_B)}
7412 @item @emph{Arguments}:
7413 @multitable @columnfractions .15 .70
7414 @item @var{MATRIX_A} @tab An array of @code{INTEGER},
7415 @code{REAL}, @code{COMPLEX}, or @code{LOGICAL} type, with a rank of
7417 @item @var{MATRIX_B} @tab An array of @code{INTEGER},
7418 @code{REAL}, or @code{COMPLEX} type if @var{MATRIX_A} is of a numeric
7419 type; otherwise, an array of @code{LOGICAL} type. The rank shall be one
7420 or two, and the first (or only) dimension of @var{MATRIX_B} shall be
7421 equal to the last (or only) dimension of @var{MATRIX_A}.
7424 @item @emph{Return value}:
7425 The matrix product of @var{MATRIX_A} and @var{MATRIX_B}. The type and
7426 kind of the result follow the usual type and kind promotion rules, as
7427 for the @code{*} or @code{.AND.} operators.
7429 @item @emph{See also}:
7435 @section @code{MAX} --- Maximum value of an argument list
7442 @cindex maximum value
7445 @item @emph{Description}:
7446 Returns the argument with the largest (most positive) value.
7448 @item @emph{Standard}:
7449 Fortran 77 and later
7454 @item @emph{Syntax}:
7455 @code{RESULT = MAX(A1, A2 [, A3 [, ...]])}
7457 @item @emph{Arguments}:
7458 @multitable @columnfractions .15 .70
7459 @item @var{A1} @tab The type shall be @code{INTEGER} or
7461 @item @var{A2}, @var{A3}, ... @tab An expression of the same type and kind
7462 as @var{A1}. (As a GNU extension, arguments of different kinds are
7466 @item @emph{Return value}:
7467 The return value corresponds to the maximum value among the arguments,
7468 and has the same type and kind as the first argument.
7470 @item @emph{Specific names}:
7471 @multitable @columnfractions .20 .20 .20 .25
7472 @item Name @tab Argument @tab Return type @tab Standard
7473 @item @code{MAX0(I)} @tab @code{INTEGER(4) I} @tab @code{INTEGER(4)} @tab Fortran 77 and later
7474 @item @code{AMAX0(I)} @tab @code{INTEGER(4) I} @tab @code{REAL(MAX(X))} @tab Fortran 77 and later
7475 @item @code{MAX1(X)} @tab @code{REAL X} @tab @code{INT(MAX(X))} @tab Fortran 77 and later
7476 @item @code{AMAX1(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab Fortran 77 and later
7477 @item @code{DMAX1(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab Fortran 77 and later
7480 @item @emph{See also}:
7481 @ref{MAXLOC} @ref{MAXVAL}, @ref{MIN}
7488 @section @code{MAXEXPONENT} --- Maximum exponent of a real kind
7489 @fnindex MAXEXPONENT
7490 @cindex model representation, maximum exponent
7493 @item @emph{Description}:
7494 @code{MAXEXPONENT(X)} returns the maximum exponent in the model of the
7497 @item @emph{Standard}:
7498 Fortran 95 and later
7503 @item @emph{Syntax}:
7504 @code{RESULT = MAXEXPONENT(X)}
7506 @item @emph{Arguments}:
7507 @multitable @columnfractions .15 .70
7508 @item @var{X} @tab Shall be of type @code{REAL}.
7511 @item @emph{Return value}:
7512 The return value is of type @code{INTEGER} and of the default integer
7515 @item @emph{Example}:
7521 print *, minexponent(x), maxexponent(x)
7522 print *, minexponent(y), maxexponent(y)
7523 end program exponents
7530 @section @code{MAXLOC} --- Location of the maximum value within an array
7532 @cindex array, location of maximum element
7535 @item @emph{Description}:
7536 Determines the location of the element in the array with the maximum
7537 value, or, if the @var{DIM} argument is supplied, determines the
7538 locations of the maximum element along each row of the array in the
7539 @var{DIM} direction. If @var{MASK} is present, only the elements for
7540 which @var{MASK} is @code{.TRUE.} are considered. If more than one
7541 element in the array has the maximum value, the location returned is
7542 that of the first such element in array element order. If the array has
7543 zero size, or all of the elements of @var{MASK} are @code{.FALSE.}, then
7544 the result is an array of zeroes. Similarly, if @var{DIM} is supplied
7545 and all of the elements of @var{MASK} along a given row are zero, the
7546 result value for that row is zero.
7548 @item @emph{Standard}:
7549 Fortran 95 and later
7552 Transformational function
7554 @item @emph{Syntax}:
7555 @multitable @columnfractions .80
7556 @item @code{RESULT = MAXLOC(ARRAY, DIM [, MASK])}
7557 @item @code{RESULT = MAXLOC(ARRAY [, MASK])}
7560 @item @emph{Arguments}:
7561 @multitable @columnfractions .15 .70
7562 @item @var{ARRAY} @tab Shall be an array of type @code{INTEGER} or
7564 @item @var{DIM} @tab (Optional) Shall be a scalar of type
7565 @code{INTEGER}, with a value between one and the rank of @var{ARRAY},
7566 inclusive. It may not be an optional dummy argument.
7567 @item @var{MASK} @tab Shall be an array of type @code{LOGICAL},
7568 and conformable with @var{ARRAY}.
7571 @item @emph{Return value}:
7572 If @var{DIM} is absent, the result is a rank-one array with a length
7573 equal to the rank of @var{ARRAY}. If @var{DIM} is present, the result
7574 is an array with a rank one less than the rank of @var{ARRAY}, and a
7575 size corresponding to the size of @var{ARRAY} with the @var{DIM}
7576 dimension removed. If @var{DIM} is present and @var{ARRAY} has a rank
7577 of one, the result is a scalar. In all cases, the result is of default
7578 @code{INTEGER} type.
7580 @item @emph{See also}:
7581 @ref{MAX}, @ref{MAXVAL}
7588 @section @code{MAXVAL} --- Maximum value of an array
7590 @cindex array, maximum value
7591 @cindex maximum value
7594 @item @emph{Description}:
7595 Determines the maximum value of the elements in an array value, or, if
7596 the @var{DIM} argument is supplied, determines the maximum value along
7597 each row of the array in the @var{DIM} direction. If @var{MASK} is
7598 present, only the elements for which @var{MASK} is @code{.TRUE.} are
7599 considered. If the array has zero size, or all of the elements of
7600 @var{MASK} are @code{.FALSE.}, then the result is @code{-HUGE(ARRAY)}
7601 if @var{ARRAY} is numeric, or a string of nulls if @var{ARRAY} is of character
7604 @item @emph{Standard}:
7605 Fortran 95 and later
7608 Transformational function
7610 @item @emph{Syntax}:
7611 @multitable @columnfractions .80
7612 @item @code{RESULT = MAXVAL(ARRAY, DIM [, MASK])}
7613 @item @code{RESULT = MAXVAL(ARRAY [, MASK])}
7616 @item @emph{Arguments}:
7617 @multitable @columnfractions .15 .70
7618 @item @var{ARRAY} @tab Shall be an array of type @code{INTEGER} or
7620 @item @var{DIM} @tab (Optional) Shall be a scalar of type
7621 @code{INTEGER}, with a value between one and the rank of @var{ARRAY},
7622 inclusive. It may not be an optional dummy argument.
7623 @item @var{MASK} @tab Shall be an array of type @code{LOGICAL},
7624 and conformable with @var{ARRAY}.
7627 @item @emph{Return value}:
7628 If @var{DIM} is absent, or if @var{ARRAY} has a rank of one, the result
7629 is a scalar. If @var{DIM} is present, the result is an array with a
7630 rank one less than the rank of @var{ARRAY}, and a size corresponding to
7631 the size of @var{ARRAY} with the @var{DIM} dimension removed. In all
7632 cases, the result is of the same type and kind as @var{ARRAY}.
7634 @item @emph{See also}:
7635 @ref{MAX}, @ref{MAXLOC}
7641 @section @code{MCLOCK} --- Time function
7643 @cindex time, clock ticks
7647 @item @emph{Description}:
7648 Returns the number of clock ticks since the start of the process, based
7649 on the UNIX function @code{clock(3)}.
7651 This intrinsic is not fully portable, such as to systems with 32-bit
7652 @code{INTEGER} types but supporting times wider than 32 bits. Therefore,
7653 the values returned by this intrinsic might be, or become, negative, or
7654 numerically less than previous values, during a single run of the
7657 @item @emph{Standard}:
7663 @item @emph{Syntax}:
7664 @code{RESULT = MCLOCK()}
7666 @item @emph{Return value}:
7667 The return value is a scalar of type @code{INTEGER(4)}, equal to the
7668 number of clock ticks since the start of the process, or @code{-1} if
7669 the system does not support @code{clock(3)}.
7671 @item @emph{See also}:
7672 @ref{CTIME}, @ref{GMTIME}, @ref{LTIME}, @ref{MCLOCK}, @ref{TIME}
7679 @section @code{MCLOCK8} --- Time function (64-bit)
7681 @cindex time, clock ticks
7685 @item @emph{Description}:
7686 Returns the number of clock ticks since the start of the process, based
7687 on the UNIX function @code{clock(3)}.
7689 @emph{Warning:} this intrinsic does not increase the range of the timing
7690 values over that returned by @code{clock(3)}. On a system with a 32-bit
7691 @code{clock(3)}, @code{MCLOCK8()} will return a 32-bit value, even though
7692 it is converted to a 64-bit @code{INTEGER(8)} value. That means
7693 overflows of the 32-bit value can still occur. Therefore, the values
7694 returned by this intrinsic might be or become negative or numerically
7695 less than previous values during a single run of the compiled program.
7697 @item @emph{Standard}:
7703 @item @emph{Syntax}:
7704 @code{RESULT = MCLOCK8()}
7706 @item @emph{Return value}:
7707 The return value is a scalar of type @code{INTEGER(8)}, equal to the
7708 number of clock ticks since the start of the process, or @code{-1} if
7709 the system does not support @code{clock(3)}.
7711 @item @emph{See also}:
7712 @ref{CTIME}, @ref{GMTIME}, @ref{LTIME}, @ref{MCLOCK}, @ref{TIME8}
7719 @section @code{MERGE} --- Merge variables
7721 @cindex array, merge arrays
7722 @cindex array, combine arrays
7725 @item @emph{Description}:
7726 Select values from two arrays according to a logical mask. The result
7727 is equal to @var{TSOURCE} if @var{MASK} is @code{.TRUE.}, or equal to
7728 @var{FSOURCE} if it is @code{.FALSE.}.
7730 @item @emph{Standard}:
7731 Fortran 95 and later
7736 @item @emph{Syntax}:
7737 @code{RESULT = MERGE(TSOURCE, FSOURCE, MASK)}
7739 @item @emph{Arguments}:
7740 @multitable @columnfractions .15 .70
7741 @item @var{TSOURCE} @tab May be of any type.
7742 @item @var{FSOURCE} @tab Shall be of the same type and type parameters
7744 @item @var{MASK} @tab Shall be of type @code{LOGICAL}.
7747 @item @emph{Return value}:
7748 The result is of the same type and type parameters as @var{TSOURCE}.
7755 @section @code{MIN} --- Minimum value of an argument list
7762 @cindex minimum value
7765 @item @emph{Description}:
7766 Returns the argument with the smallest (most negative) value.
7768 @item @emph{Standard}:
7769 Fortran 77 and later
7774 @item @emph{Syntax}:
7775 @code{RESULT = MIN(A1, A2 [, A3, ...])}
7777 @item @emph{Arguments}:
7778 @multitable @columnfractions .15 .70
7779 @item @var{A1} @tab The type shall be @code{INTEGER} or
7781 @item @var{A2}, @var{A3}, ... @tab An expression of the same type and kind
7782 as @var{A1}. (As a GNU extension, arguments of different kinds are
7786 @item @emph{Return value}:
7787 The return value corresponds to the maximum value among the arguments,
7788 and has the same type and kind as the first argument.
7790 @item @emph{Specific names}:
7791 @multitable @columnfractions .20 .20 .20 .25
7792 @item Name @tab Argument @tab Return type @tab Standard
7793 @item @code{MIN0(I)} @tab @code{INTEGER(4) I} @tab @code{INTEGER(4)} @tab Fortran 77 and later
7794 @item @code{AMIN0(I)} @tab @code{INTEGER(4) I} @tab @code{REAL(MIN(X))} @tab Fortran 77 and later
7795 @item @code{MIN1(X)} @tab @code{REAL X} @tab @code{INT(MIN(X))} @tab Fortran 77 and later
7796 @item @code{AMIN1(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab Fortran 77 and later
7797 @item @code{DMIN1(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab Fortran 77 and later
7800 @item @emph{See also}:
7801 @ref{MAX}, @ref{MINLOC}, @ref{MINVAL}
7807 @section @code{MINEXPONENT} --- Minimum exponent of a real kind
7808 @fnindex MINEXPONENT
7809 @cindex model representation, minimum exponent
7812 @item @emph{Description}:
7813 @code{MINEXPONENT(X)} returns the minimum exponent in the model of the
7816 @item @emph{Standard}:
7817 Fortran 95 and later
7822 @item @emph{Syntax}:
7823 @code{RESULT = MINEXPONENT(X)}
7825 @item @emph{Arguments}:
7826 @multitable @columnfractions .15 .70
7827 @item @var{X} @tab Shall be of type @code{REAL}.
7830 @item @emph{Return value}:
7831 The return value is of type @code{INTEGER} and of the default integer
7834 @item @emph{Example}:
7835 See @code{MAXEXPONENT} for an example.
7841 @section @code{MINLOC} --- Location of the minimum value within an array
7843 @cindex array, location of minimum element
7846 @item @emph{Description}:
7847 Determines the location of the element in the array with the minimum
7848 value, or, if the @var{DIM} argument is supplied, determines the
7849 locations of the minimum element along each row of the array in the
7850 @var{DIM} direction. If @var{MASK} is present, only the elements for
7851 which @var{MASK} is @code{.TRUE.} are considered. If more than one
7852 element in the array has the minimum value, the location returned is
7853 that of the first such element in array element order. If the array has
7854 zero size, or all of the elements of @var{MASK} are @code{.FALSE.}, then
7855 the result is an array of zeroes. Similarly, if @var{DIM} is supplied
7856 and all of the elements of @var{MASK} along a given row are zero, the
7857 result value for that row is zero.
7859 @item @emph{Standard}:
7860 Fortran 95 and later
7863 Transformational function
7865 @item @emph{Syntax}:
7866 @multitable @columnfractions .80
7867 @item @code{RESULT = MINLOC(ARRAY, DIM [, MASK])}
7868 @item @code{RESULT = MINLOC(ARRAY [, MASK])}
7871 @item @emph{Arguments}:
7872 @multitable @columnfractions .15 .70
7873 @item @var{ARRAY} @tab Shall be an array of type @code{INTEGER} or
7875 @item @var{DIM} @tab (Optional) Shall be a scalar of type
7876 @code{INTEGER}, with a value between one and the rank of @var{ARRAY},
7877 inclusive. It may not be an optional dummy argument.
7878 @item @var{MASK} @tab Shall be an array of type @code{LOGICAL},
7879 and conformable with @var{ARRAY}.
7882 @item @emph{Return value}:
7883 If @var{DIM} is absent, the result is a rank-one array with a length
7884 equal to the rank of @var{ARRAY}. If @var{DIM} is present, the result
7885 is an array with a rank one less than the rank of @var{ARRAY}, and a
7886 size corresponding to the size of @var{ARRAY} with the @var{DIM}
7887 dimension removed. If @var{DIM} is present and @var{ARRAY} has a rank
7888 of one, the result is a scalar. In all cases, the result is of default
7889 @code{INTEGER} type.
7891 @item @emph{See also}:
7892 @ref{MIN}, @ref{MINVAL}
7899 @section @code{MINVAL} --- Minimum value of an array
7901 @cindex array, minimum value
7902 @cindex minimum value
7905 @item @emph{Description}:
7906 Determines the minimum value of the elements in an array value, or, if
7907 the @var{DIM} argument is supplied, determines the minimum value along
7908 each row of the array in the @var{DIM} direction. If @var{MASK} is
7909 present, only the elements for which @var{MASK} is @code{.TRUE.} are
7910 considered. If the array has zero size, or all of the elements of
7911 @var{MASK} are @code{.FALSE.}, then the result is @code{HUGE(ARRAY)} if
7912 @var{ARRAY} is numeric, or a string of @code{CHAR(255)} characters if
7913 @var{ARRAY} is of character type.
7915 @item @emph{Standard}:
7916 Fortran 95 and later
7919 Transformational function
7921 @item @emph{Syntax}:
7922 @multitable @columnfractions .80
7923 @item @code{RESULT = MINVAL(ARRAY, DIM [, MASK])}
7924 @item @code{RESULT = MINVAL(ARRAY [, MASK])}
7927 @item @emph{Arguments}:
7928 @multitable @columnfractions .15 .70
7929 @item @var{ARRAY} @tab Shall be an array of type @code{INTEGER} or
7931 @item @var{DIM} @tab (Optional) Shall be a scalar of type
7932 @code{INTEGER}, with a value between one and the rank of @var{ARRAY},
7933 inclusive. It may not be an optional dummy argument.
7934 @item @var{MASK} @tab Shall be an array of type @code{LOGICAL},
7935 and conformable with @var{ARRAY}.
7938 @item @emph{Return value}:
7939 If @var{DIM} is absent, or if @var{ARRAY} has a rank of one, the result
7940 is a scalar. If @var{DIM} is present, the result is an array with a
7941 rank one less than the rank of @var{ARRAY}, and a size corresponding to
7942 the size of @var{ARRAY} with the @var{DIM} dimension removed. In all
7943 cases, the result is of the same type and kind as @var{ARRAY}.
7945 @item @emph{See also}:
7946 @ref{MIN}, @ref{MINLOC}
7953 @section @code{MOD} --- Remainder function
7958 @cindex division, remainder
7961 @item @emph{Description}:
7962 @code{MOD(A,P)} computes the remainder of the division of A by P@. It is
7963 calculated as @code{A - (INT(A/P) * P)}.
7965 @item @emph{Standard}:
7966 Fortran 77 and later
7971 @item @emph{Syntax}:
7972 @code{RESULT = MOD(A, P)}
7974 @item @emph{Arguments}:
7975 @multitable @columnfractions .15 .70
7976 @item @var{A} @tab Shall be a scalar of type @code{INTEGER} or @code{REAL}
7977 @item @var{P} @tab Shall be a scalar of the same type as @var{A} and not
7981 @item @emph{Return value}:
7982 The kind of the return value is the result of cross-promoting
7983 the kinds of the arguments.
7985 @item @emph{Example}:
7989 print *, mod(17.5,5.5)
7990 print *, mod(17.5d0,5.5)
7991 print *, mod(17.5,5.5d0)
7994 print *, mod(-17.5,5.5)
7995 print *, mod(-17.5d0,5.5)
7996 print *, mod(-17.5,5.5d0)
7999 print *, mod(17.5,-5.5)
8000 print *, mod(17.5d0,-5.5)
8001 print *, mod(17.5,-5.5d0)
8002 end program test_mod
8005 @item @emph{Specific names}:
8006 @multitable @columnfractions .20 .20 .20 .25
8007 @item Name @tab Arguments @tab Return type @tab Standard
8008 @item @code{AMOD(A,P)} @tab @code{REAL(4)} @tab @code{REAL(4)} @tab Fortran 95 and later
8009 @item @code{DMOD(A,P)} @tab @code{REAL(8)} @tab @code{REAL(8)} @tab Fortran 95 and later
8016 @section @code{MODULO} --- Modulo function
8019 @cindex division, modulo
8022 @item @emph{Description}:
8023 @code{MODULO(A,P)} computes the @var{A} modulo @var{P}.
8025 @item @emph{Standard}:
8026 Fortran 95 and later
8031 @item @emph{Syntax}:
8032 @code{RESULT = MODULO(A, P)}
8034 @item @emph{Arguments}:
8035 @multitable @columnfractions .15 .70
8036 @item @var{A} @tab Shall be a scalar of type @code{INTEGER} or @code{REAL}
8037 @item @var{P} @tab Shall be a scalar of the same type and kind as @var{A}
8040 @item @emph{Return value}:
8041 The type and kind of the result are those of the arguments.
8043 @item If @var{A} and @var{P} are of type @code{INTEGER}:
8044 @code{MODULO(A,P)} has the value @var{R} such that @code{A=Q*P+R}, where
8045 @var{Q} is an integer and @var{R} is between 0 (inclusive) and @var{P}
8047 @item If @var{A} and @var{P} are of type @code{REAL}:
8048 @code{MODULO(A,P)} has the value of @code{A - FLOOR (A / P) * P}.
8050 In all cases, if @var{P} is zero the result is processor-dependent.
8052 @item @emph{Example}:
8055 print *, modulo(17,3)
8056 print *, modulo(17.5,5.5)
8058 print *, modulo(-17,3)
8059 print *, modulo(-17.5,5.5)
8061 print *, modulo(17,-3)
8062 print *, modulo(17.5,-5.5)
8071 @section @code{MOVE_ALLOC} --- Move allocation from one object to another
8073 @cindex moving allocation
8074 @cindex allocation, moving
8077 @item @emph{Description}:
8078 @code{MOVE_ALLOC(FROM, TO)} moves the allocation from @var{FROM} to
8079 @var{TO}. @var{FROM} will become deallocated in the process.
8081 @item @emph{Standard}:
8082 Fortran 2003 and later
8087 @item @emph{Syntax}:
8088 @code{CALL MOVE_ALLOC(FROM, TO)}
8090 @item @emph{Arguments}:
8091 @multitable @columnfractions .15 .70
8092 @item @var{FROM} @tab @code{ALLOCATABLE}, @code{INTENT(INOUT)}, may be
8093 of any type and kind.
8094 @item @var{TO} @tab @code{ALLOCATABLE}, @code{INTENT(OUT)}, shall be
8095 of the same type, kind and rank as @var{FROM}.
8098 @item @emph{Return value}:
8101 @item @emph{Example}:
8103 program test_move_alloc
8104 integer, allocatable :: a(:), b(:)
8108 call move_alloc(a, b)
8109 print *, allocated(a), allocated(b)
8111 end program test_move_alloc
8118 @section @code{MVBITS} --- Move bits from one integer to another
8123 @item @emph{Description}:
8124 Moves @var{LEN} bits from positions @var{FROMPOS} through
8125 @code{FROMPOS+LEN-1} of @var{FROM} to positions @var{TOPOS} through
8126 @code{TOPOS+LEN-1} of @var{TO}. The portion of argument @var{TO} not
8127 affected by the movement of bits is unchanged. The values of
8128 @code{FROMPOS+LEN-1} and @code{TOPOS+LEN-1} must be less than
8129 @code{BIT_SIZE(FROM)}.
8131 @item @emph{Standard}:
8132 Fortran 95 and later
8135 Elemental subroutine
8137 @item @emph{Syntax}:
8138 @code{CALL MVBITS(FROM, FROMPOS, LEN, TO, TOPOS)}
8140 @item @emph{Arguments}:
8141 @multitable @columnfractions .15 .70
8142 @item @var{FROM} @tab The type shall be @code{INTEGER}.
8143 @item @var{FROMPOS} @tab The type shall be @code{INTEGER}.
8144 @item @var{LEN} @tab The type shall be @code{INTEGER}.
8145 @item @var{TO} @tab The type shall be @code{INTEGER}, of the
8146 same kind as @var{FROM}.
8147 @item @var{TOPOS} @tab The type shall be @code{INTEGER}.
8150 @item @emph{See also}:
8151 @ref{IBCLR}, @ref{IBSET}, @ref{IBITS}, @ref{IAND}, @ref{IOR}, @ref{IEOR}
8157 @section @code{NEAREST} --- Nearest representable number
8159 @cindex real number, nearest different
8160 @cindex floating point, nearest different
8163 @item @emph{Description}:
8164 @code{NEAREST(X, S)} returns the processor-representable number nearest
8165 to @code{X} in the direction indicated by the sign of @code{S}.
8167 @item @emph{Standard}:
8168 Fortran 95 and later
8173 @item @emph{Syntax}:
8174 @code{RESULT = NEAREST(X, S)}
8176 @item @emph{Arguments}:
8177 @multitable @columnfractions .15 .70
8178 @item @var{X} @tab Shall be of type @code{REAL}.
8179 @item @var{S} @tab (Optional) shall be of type @code{REAL} and
8183 @item @emph{Return value}:
8184 The return value is of the same type as @code{X}. If @code{S} is
8185 positive, @code{NEAREST} returns the processor-representable number
8186 greater than @code{X} and nearest to it. If @code{S} is negative,
8187 @code{NEAREST} returns the processor-representable number smaller than
8188 @code{X} and nearest to it.
8190 @item @emph{Example}:
8192 program test_nearest
8194 x = nearest(42.0, 1.0)
8195 y = nearest(42.0, -1.0)
8196 write (*,"(3(G20.15))") x, y, x - y
8197 end program test_nearest
8204 @section @code{NEW_LINE} --- New line character
8207 @cindex output, newline
8210 @item @emph{Description}:
8211 @code{NEW_LINE(C)} returns the new-line character.
8213 @item @emph{Standard}:
8214 Fortran 2003 and later
8219 @item @emph{Syntax}:
8220 @code{RESULT = NEW_LINE(C)}
8222 @item @emph{Arguments}:
8223 @multitable @columnfractions .15 .70
8224 @item @var{C} @tab The argument shall be a scalar or array of the
8225 type @code{CHARACTER}.
8228 @item @emph{Return value}:
8229 Returns a @var{CHARACTER} scalar of length one with the new-line character of
8230 the same kind as parameter @var{C}.
8232 @item @emph{Example}:
8236 write(*,'(A)') 'This is record 1.'//NEW_LINE('A')//'This is record 2.'
8244 @section @code{NINT} --- Nearest whole number
8247 @cindex rounding, nearest whole number
8250 @item @emph{Description}:
8251 @code{NINT(A)} rounds its argument to the nearest whole number.
8253 @item @emph{Standard}:
8254 Fortran 77 and later, with @var{KIND} argument Fortran 90 and later
8259 @item @emph{Syntax}:
8260 @code{RESULT = NINT(A [, KIND])}
8262 @item @emph{Arguments}:
8263 @multitable @columnfractions .15 .70
8264 @item @var{A} @tab The type of the argument shall be @code{REAL}.
8265 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
8266 expression indicating the kind parameter of the result.
8269 @item @emph{Return value}:
8270 Returns @var{A} with the fractional portion of its magnitude eliminated by
8271 rounding to the nearest whole number and with its sign preserved,
8272 converted to an @code{INTEGER} of the default kind.
8274 @item @emph{Example}:
8281 print *, nint(x4), idnint(x8)
8282 end program test_nint
8285 @item @emph{Specific names}:
8286 @multitable @columnfractions .25 .25 .25
8287 @item Name @tab Argument @tab Standard
8288 @item @code{IDNINT(X)} @tab @code{REAL(8)} @tab Fortran 95 and later
8291 @item @emph{See also}:
8292 @ref{CEILING}, @ref{FLOOR}
8299 @section @code{NOT} --- Logical negation
8301 @cindex bits, negate
8302 @cindex bitwise logical not
8303 @cindex logical not, bitwise
8306 @item @emph{Description}:
8307 @code{NOT} returns the bitwise boolean inverse of @var{I}.
8309 @item @emph{Standard}:
8310 Fortran 95 and later
8315 @item @emph{Syntax}:
8316 @code{RESULT = NOT(I)}
8318 @item @emph{Arguments}:
8319 @multitable @columnfractions .15 .70
8320 @item @var{I} @tab The type shall be @code{INTEGER}.
8323 @item @emph{Return value}:
8324 The return type is @code{INTEGER}, of the same kind as the
8327 @item @emph{See also}:
8328 @ref{IAND}, @ref{IEOR}, @ref{IOR}, @ref{IBITS}, @ref{IBSET}, @ref{IBCLR}
8335 @section @code{NULL} --- Function that returns an disassociated pointer
8337 @cindex pointer, status
8338 @cindex pointer, disassociated
8341 @item @emph{Description}:
8342 Returns a disassociated pointer.
8344 If @var{MOLD} is present, a dissassociated pointer of the same type is
8345 returned, otherwise the type is determined by context.
8347 In Fortran 95, @var{MOLD} is optional. Please note that Fortran 2003
8348 includes cases where it is required.
8350 @item @emph{Standard}:
8351 Fortran 95 and later
8354 Transformational function
8356 @item @emph{Syntax}:
8357 @code{PTR => NULL([MOLD])}
8359 @item @emph{Arguments}:
8360 @multitable @columnfractions .15 .70
8361 @item @var{MOLD} @tab (Optional) shall be a pointer of any association
8362 status and of any type.
8365 @item @emph{Return value}:
8366 A disassociated pointer.
8368 @item @emph{Example}:
8370 REAL, POINTER, DIMENSION(:) :: VEC => NULL ()
8373 @item @emph{See also}:
8380 @section @code{NUM_IMAGES} --- Function that returns the number of images
8382 @cindex coarray, NUM_IMAGES
8383 @cindex images, number of
8386 @item @emph{Description}:
8387 Returns the number of images.
8389 @item @emph{Standard}:
8390 Fortran 2008 and later
8393 Transformational function
8395 @item @emph{Syntax}:
8396 @code{RESULT = NUM_IMAGES()}
8398 @item @emph{Arguments}: None.
8400 @item @emph{Return value}:
8401 Scalar default-kind integer.
8403 @item @emph{Example}:
8407 value = THIS_IMAGE()
8409 IF (THIS_IMAGE() == 1) THEN
8410 DO i = 1, NUM_IMAGES()
8411 WRITE(*,'(2(a,i0))') 'value[', i, '] is ', value[i]
8416 @item @emph{See also}:
8417 @c FIXME: ref{THIS_IMAGE}
8423 @section @code{OR} --- Bitwise logical OR
8425 @cindex bitwise logical or
8426 @cindex logical or, bitwise
8429 @item @emph{Description}:
8430 Bitwise logical @code{OR}.
8432 This intrinsic routine is provided for backwards compatibility with
8433 GNU Fortran 77. For integer arguments, programmers should consider
8434 the use of the @ref{IOR} intrinsic defined by the Fortran standard.
8436 @item @emph{Standard}:
8442 @item @emph{Syntax}:
8443 @code{RESULT = OR(I, J)}
8445 @item @emph{Arguments}:
8446 @multitable @columnfractions .15 .70
8447 @item @var{I} @tab The type shall be either a scalar @code{INTEGER}
8448 type or a scalar @code{LOGICAL} type.
8449 @item @var{J} @tab The type shall be the same as the type of @var{J}.
8452 @item @emph{Return value}:
8453 The return type is either a scalar @code{INTEGER} or a scalar
8454 @code{LOGICAL}. If the kind type parameters differ, then the
8455 smaller kind type is implicitly converted to larger kind, and the
8456 return has the larger kind.
8458 @item @emph{Example}:
8461 LOGICAL :: T = .TRUE., F = .FALSE.
8463 DATA a / Z'F' /, b / Z'3' /
8465 WRITE (*,*) OR(T, T), OR(T, F), OR(F, T), OR(F, F)
8466 WRITE (*,*) OR(a, b)
8470 @item @emph{See also}:
8471 Fortran 95 elemental function: @ref{IOR}
8477 @section @code{PACK} --- Pack an array into an array of rank one
8479 @cindex array, packing
8480 @cindex array, reduce dimension
8481 @cindex array, gather elements
8484 @item @emph{Description}:
8485 Stores the elements of @var{ARRAY} in an array of rank one.
8487 The beginning of the resulting array is made up of elements whose @var{MASK}
8488 equals @code{TRUE}. Afterwards, positions are filled with elements taken from
8491 @item @emph{Standard}:
8492 Fortran 95 and later
8495 Transformational function
8497 @item @emph{Syntax}:
8498 @code{RESULT = PACK(ARRAY, MASK[,VECTOR]}
8500 @item @emph{Arguments}:
8501 @multitable @columnfractions .15 .70
8502 @item @var{ARRAY} @tab Shall be an array of any type.
8503 @item @var{MASK} @tab Shall be an array of type @code{LOGICAL} and
8504 of the same size as @var{ARRAY}. Alternatively, it may be a @code{LOGICAL}
8506 @item @var{VECTOR} @tab (Optional) shall be an array of the same type
8507 as @var{ARRAY} and of rank one. If present, the number of elements in
8508 @var{VECTOR} shall be equal to or greater than the number of true elements
8509 in @var{MASK}. If @var{MASK} is scalar, the number of elements in
8510 @var{VECTOR} shall be equal to or greater than the number of elements in
8514 @item @emph{Return value}:
8515 The result is an array of rank one and the same type as that of @var{ARRAY}.
8516 If @var{VECTOR} is present, the result size is that of @var{VECTOR}, the
8517 number of @code{TRUE} values in @var{MASK} otherwise.
8519 @item @emph{Example}:
8520 Gathering nonzero elements from an array:
8524 m = (/ 1, 0, 0, 0, 5, 0 /)
8525 WRITE(*, FMT="(6(I0, ' '))") pack(m, m /= 0) ! "1 5"
8529 Gathering nonzero elements from an array and appending elements from @var{VECTOR}:
8533 m = (/ 1, 0, 0, 2 /)
8534 WRITE(*, FMT="(4(I0, ' '))") pack(m, m /= 0, (/ 0, 0, 3, 4 /)) ! "1 2 3 4"
8538 @item @emph{See also}:
8545 @section @code{PERROR} --- Print system error message
8547 @cindex system, error handling
8550 @item @emph{Description}:
8551 Prints (on the C @code{stderr} stream) a newline-terminated error
8552 message corresponding to the last system error. This is prefixed by
8553 @var{STRING}, a colon and a space. See @code{perror(3)}.
8555 @item @emph{Standard}:
8561 @item @emph{Syntax}:
8562 @code{CALL PERROR(STRING)}
8564 @item @emph{Arguments}:
8565 @multitable @columnfractions .15 .70
8566 @item @var{STRING} @tab A scalar of type @code{CHARACTER} and of the
8570 @item @emph{See also}:
8577 @section @code{PRECISION} --- Decimal precision of a real kind
8579 @cindex model representation, precision
8582 @item @emph{Description}:
8583 @code{PRECISION(X)} returns the decimal precision in the model of the
8586 @item @emph{Standard}:
8587 Fortran 95 and later
8592 @item @emph{Syntax}:
8593 @code{RESULT = PRECISION(X)}
8595 @item @emph{Arguments}:
8596 @multitable @columnfractions .15 .70
8597 @item @var{X} @tab Shall be of type @code{REAL} or @code{COMPLEX}.
8600 @item @emph{Return value}:
8601 The return value is of type @code{INTEGER} and of the default integer
8604 @item @emph{Example}:
8606 program prec_and_range
8607 real(kind=4) :: x(2)
8608 complex(kind=8) :: y
8610 print *, precision(x), range(x)
8611 print *, precision(y), range(y)
8612 end program prec_and_range
8619 @section @code{PRESENT} --- Determine whether an optional dummy argument is specified
8623 @item @emph{Description}:
8624 Determines whether an optional dummy argument is present.
8626 @item @emph{Standard}:
8627 Fortran 95 and later
8632 @item @emph{Syntax}:
8633 @code{RESULT = PRESENT(A)}
8635 @item @emph{Arguments}:
8636 @multitable @columnfractions .15 .70
8637 @item @var{A} @tab May be of any type and may be a pointer, scalar or array
8638 value, or a dummy procedure. It shall be the name of an optional dummy argument
8639 accessible within the current subroutine or function.
8642 @item @emph{Return value}:
8643 Returns either @code{TRUE} if the optional argument @var{A} is present, or
8644 @code{FALSE} otherwise.
8646 @item @emph{Example}:
8648 PROGRAM test_present
8649 WRITE(*,*) f(), f(42) ! "F T"
8651 LOGICAL FUNCTION f(x)
8652 INTEGER, INTENT(IN), OPTIONAL :: x
8662 @section @code{PRODUCT} --- Product of array elements
8664 @cindex array, product
8665 @cindex array, multiply elements
8666 @cindex array, conditionally multiply elements
8667 @cindex multiply array elements
8670 @item @emph{Description}:
8671 Multiplies the elements of @var{ARRAY} along dimension @var{DIM} if
8672 the corresponding element in @var{MASK} is @code{TRUE}.
8674 @item @emph{Standard}:
8675 Fortran 95 and later
8678 Transformational function
8680 @item @emph{Syntax}:
8681 @multitable @columnfractions .80
8682 @item @code{RESULT = PRODUCT(ARRAY[, MASK])}
8683 @item @code{RESULT = PRODUCT(ARRAY, DIM[, MASK])}
8686 @item @emph{Arguments}:
8687 @multitable @columnfractions .15 .70
8688 @item @var{ARRAY} @tab Shall be an array of type @code{INTEGER},
8689 @code{REAL} or @code{COMPLEX}.
8690 @item @var{DIM} @tab (Optional) shall be a scalar of type
8691 @code{INTEGER} with a value in the range from 1 to n, where n
8692 equals the rank of @var{ARRAY}.
8693 @item @var{MASK} @tab (Optional) shall be of type @code{LOGICAL}
8694 and either be a scalar or an array of the same shape as @var{ARRAY}.
8697 @item @emph{Return value}:
8698 The result is of the same type as @var{ARRAY}.
8700 If @var{DIM} is absent, a scalar with the product of all elements in
8701 @var{ARRAY} is returned. Otherwise, an array of rank n-1, where n equals
8702 the rank of @var{ARRAY}, and a shape similar to that of @var{ARRAY} with
8703 dimension @var{DIM} dropped is returned.
8706 @item @emph{Example}:
8708 PROGRAM test_product
8709 INTEGER :: x(5) = (/ 1, 2, 3, 4 ,5 /)
8710 print *, PRODUCT(x) ! all elements, product = 120
8711 print *, PRODUCT(x, MASK=MOD(x, 2)==1) ! odd elements, product = 15
8715 @item @emph{See also}:
8722 @section @code{RADIX} --- Base of a model number
8724 @cindex model representation, base
8725 @cindex model representation, radix
8728 @item @emph{Description}:
8729 @code{RADIX(X)} returns the base of the model representing the entity @var{X}.
8731 @item @emph{Standard}:
8732 Fortran 95 and later
8737 @item @emph{Syntax}:
8738 @code{RESULT = RADIX(X)}
8740 @item @emph{Arguments}:
8741 @multitable @columnfractions .15 .70
8742 @item @var{X} @tab Shall be of type @code{INTEGER} or @code{REAL}
8745 @item @emph{Return value}:
8746 The return value is a scalar of type @code{INTEGER} and of the default
8749 @item @emph{Example}:
8752 print *, "The radix for the default integer kind is", radix(0)
8753 print *, "The radix for the default real kind is", radix(0.0)
8754 end program test_radix
8762 @section @code{RAN} --- Real pseudo-random number
8764 @cindex random number generation
8767 @item @emph{Description}:
8768 For compatibility with HP FORTRAN 77/iX, the @code{RAN} intrinsic is
8769 provided as an alias for @code{RAND}. See @ref{RAND} for complete
8772 @item @emph{Standard}:
8778 @item @emph{See also}:
8779 @ref{RAND}, @ref{RANDOM_NUMBER}
8785 @section @code{RAND} --- Real pseudo-random number
8787 @cindex random number generation
8790 @item @emph{Description}:
8791 @code{RAND(FLAG)} returns a pseudo-random number from a uniform
8792 distribution between 0 and 1. If @var{FLAG} is 0, the next number
8793 in the current sequence is returned; if @var{FLAG} is 1, the generator
8794 is restarted by @code{CALL SRAND(0)}; if @var{FLAG} has any other value,
8795 it is used as a new seed with @code{SRAND}.
8797 This intrinsic routine is provided for backwards compatibility with
8798 GNU Fortran 77. It implements a simple modulo generator as provided
8799 by @command{g77}. For new code, one should consider the use of
8800 @ref{RANDOM_NUMBER} as it implements a superior algorithm.
8802 @item @emph{Standard}:
8808 @item @emph{Syntax}:
8809 @code{RESULT = RAND(I)}
8811 @item @emph{Arguments}:
8812 @multitable @columnfractions .15 .70
8813 @item @var{I} @tab Shall be a scalar @code{INTEGER} of kind 4.
8816 @item @emph{Return value}:
8817 The return value is of @code{REAL} type and the default kind.
8819 @item @emph{Example}:
8822 integer,parameter :: seed = 86456
8825 print *, rand(), rand(), rand(), rand()
8826 print *, rand(seed), rand(), rand(), rand()
8827 end program test_rand
8830 @item @emph{See also}:
8831 @ref{SRAND}, @ref{RANDOM_NUMBER}
8838 @section @code{RANDOM_NUMBER} --- Pseudo-random number
8839 @fnindex RANDOM_NUMBER
8840 @cindex random number generation
8843 @item @emph{Description}:
8844 Returns a single pseudorandom number or an array of pseudorandom numbers
8845 from the uniform distribution over the range @math{ 0 \leq x < 1}.
8847 The runtime-library implements George Marsaglia's KISS (Keep It Simple
8848 Stupid) random number generator (RNG). This RNG combines:
8850 @item The congruential generator @math{x(n) = 69069 \cdot x(n-1) + 1327217885}
8851 with a period of @math{2^{32}},
8852 @item A 3-shift shift-register generator with a period of @math{2^{32} - 1},
8853 @item Two 16-bit multiply-with-carry generators with a period of
8854 @math{597273182964842497 > 2^{59}}.
8856 The overall period exceeds @math{2^{123}}.
8858 Please note, this RNG is thread safe if used within OpenMP directives,
8859 i.e., its state will be consistent while called from multiple threads.
8860 However, the KISS generator does not create random numbers in parallel
8861 from multiple sources, but in sequence from a single source. If an
8862 OpenMP-enabled application heavily relies on random numbers, one should
8863 consider employing a dedicated parallel random number generator instead.
8865 @item @emph{Standard}:
8866 Fortran 95 and later
8871 @item @emph{Syntax}:
8872 @code{RANDOM_NUMBER(HARVEST)}
8874 @item @emph{Arguments}:
8875 @multitable @columnfractions .15 .70
8876 @item @var{HARVEST} @tab Shall be a scalar or an array of type @code{REAL}.
8879 @item @emph{Example}:
8881 program test_random_number
8883 CALL init_random_seed() ! see example of RANDOM_SEED
8884 CALL RANDOM_NUMBER(r)
8888 @item @emph{See also}:
8895 @section @code{RANDOM_SEED} --- Initialize a pseudo-random number sequence
8896 @fnindex RANDOM_SEED
8897 @cindex random number generation, seeding
8898 @cindex seeding a random number generator
8901 @item @emph{Description}:
8902 Restarts or queries the state of the pseudorandom number generator used by
8903 @code{RANDOM_NUMBER}.
8905 If @code{RANDOM_SEED} is called without arguments, it is initialized to
8906 a default state. The example below shows how to initialize the random
8907 seed based on the system's time.
8909 @item @emph{Standard}:
8910 Fortran 95 and later
8915 @item @emph{Syntax}:
8916 @code{CALL RANDOM_SEED([SIZE, PUT, GET])}
8918 @item @emph{Arguments}:
8919 @multitable @columnfractions .15 .70
8920 @item @var{SIZE} @tab (Optional) Shall be a scalar and of type default
8921 @code{INTEGER}, with @code{INTENT(OUT)}. It specifies the minimum size
8922 of the arrays used with the @var{PUT} and @var{GET} arguments.
8923 @item @var{PUT} @tab (Optional) Shall be an array of type default
8924 @code{INTEGER} and rank one. It is @code{INTENT(IN)} and the size of
8925 the array must be larger than or equal to the number returned by the
8926 @var{SIZE} argument.
8927 @item @var{GET} @tab (Optional) Shall be an array of type default
8928 @code{INTEGER} and rank one. It is @code{INTENT(OUT)} and the size
8929 of the array must be larger than or equal to the number returned by
8930 the @var{SIZE} argument.
8933 @item @emph{Example}:
8935 SUBROUTINE init_random_seed()
8936 INTEGER :: i, n, clock
8937 INTEGER, DIMENSION(:), ALLOCATABLE :: seed
8939 CALL RANDOM_SEED(size = n)
8942 CALL SYSTEM_CLOCK(COUNT=clock)
8944 seed = clock + 37 * (/ (i - 1, i = 1, n) /)
8945 CALL RANDOM_SEED(PUT = seed)
8951 @item @emph{See also}:
8958 @section @code{RANGE} --- Decimal exponent range
8960 @cindex model representation, range
8963 @item @emph{Description}:
8964 @code{RANGE(X)} returns the decimal exponent range in the model of the
8967 @item @emph{Standard}:
8968 Fortran 95 and later
8973 @item @emph{Syntax}:
8974 @code{RESULT = RANGE(X)}
8976 @item @emph{Arguments}:
8977 @multitable @columnfractions .15 .70
8978 @item @var{X} @tab Shall be of type @code{INTEGER}, @code{REAL}
8982 @item @emph{Return value}:
8983 The return value is of type @code{INTEGER} and of the default integer
8986 @item @emph{Example}:
8987 See @code{PRECISION} for an example.
8993 @section @code{REAL} --- Convert to real type
8996 @cindex conversion, to real
8997 @cindex complex numbers, real part
9000 @item @emph{Description}:
9001 @code{REAL(A [, KIND])} converts its argument @var{A} to a real type. The
9002 @code{REALPART} function is provided for compatibility with @command{g77},
9003 and its use is strongly discouraged.
9005 @item @emph{Standard}:
9006 Fortran 77 and later
9011 @item @emph{Syntax}:
9012 @multitable @columnfractions .80
9013 @item @code{RESULT = REAL(A [, KIND])}
9014 @item @code{RESULT = REALPART(Z)}
9017 @item @emph{Arguments}:
9018 @multitable @columnfractions .15 .70
9019 @item @var{A} @tab Shall be @code{INTEGER}, @code{REAL}, or
9021 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
9022 expression indicating the kind parameter of the result.
9025 @item @emph{Return value}:
9026 These functions return a @code{REAL} variable or array under
9027 the following rules:
9031 @code{REAL(A)} is converted to a default real type if @var{A} is an
9032 integer or real variable.
9034 @code{REAL(A)} is converted to a real type with the kind type parameter
9035 of @var{A} if @var{A} is a complex variable.
9037 @code{REAL(A, KIND)} is converted to a real type with kind type
9038 parameter @var{KIND} if @var{A} is a complex, integer, or real
9042 @item @emph{Example}:
9045 complex :: x = (1.0, 2.0)
9046 print *, real(x), real(x,8), realpart(x)
9047 end program test_real
9050 @item @emph{See also}:
9051 @ref{DBLE}, @ref{DFLOAT}, @ref{FLOAT}
9058 @section @code{RENAME} --- Rename a file
9060 @cindex file system, rename file
9063 @item @emph{Description}:
9064 Renames a file from file @var{PATH1} to @var{PATH2}. A null
9065 character (@code{CHAR(0)}) can be used to mark the end of the names in
9066 @var{PATH1} and @var{PATH2}; otherwise, trailing blanks in the file
9067 names are ignored. If the @var{STATUS} argument is supplied, it
9068 contains 0 on success or a nonzero error code upon return; see
9071 This intrinsic is provided in both subroutine and function forms;
9072 however, only one form can be used in any given program unit.
9074 @item @emph{Standard}:
9078 Subroutine, function
9080 @item @emph{Syntax}:
9081 @multitable @columnfractions .80
9082 @item @code{CALL RENAME(PATH1, PATH2 [, STATUS])}
9083 @item @code{STATUS = RENAME(PATH1, PATH2)}
9086 @item @emph{Arguments}:
9087 @multitable @columnfractions .15 .70
9088 @item @var{PATH1} @tab Shall be of default @code{CHARACTER} type.
9089 @item @var{PATH2} @tab Shall be of default @code{CHARACTER} type.
9090 @item @var{STATUS} @tab (Optional) Shall be of default @code{INTEGER} type.
9093 @item @emph{See also}:
9101 @section @code{REPEAT} --- Repeated string concatenation
9103 @cindex string, repeat
9104 @cindex string, concatenate
9107 @item @emph{Description}:
9108 Concatenates @var{NCOPIES} copies of a string.
9110 @item @emph{Standard}:
9111 Fortran 95 and later
9114 Transformational function
9116 @item @emph{Syntax}:
9117 @code{RESULT = REPEAT(STRING, NCOPIES)}
9119 @item @emph{Arguments}:
9120 @multitable @columnfractions .15 .70
9121 @item @var{STRING} @tab Shall be scalar and of type @code{CHARACTER}.
9122 @item @var{NCOPIES} @tab Shall be scalar and of type @code{INTEGER}.
9125 @item @emph{Return value}:
9126 A new scalar of type @code{CHARACTER} built up from @var{NCOPIES} copies
9129 @item @emph{Example}:
9132 write(*,*) repeat("x", 5) ! "xxxxx"
9140 @section @code{RESHAPE} --- Function to reshape an array
9142 @cindex array, change dimensions
9143 @cindex array, transmogrify
9146 @item @emph{Description}:
9147 Reshapes @var{SOURCE} to correspond to @var{SHAPE}. If necessary,
9148 the new array may be padded with elements from @var{PAD} or permuted
9149 as defined by @var{ORDER}.
9151 @item @emph{Standard}:
9152 Fortran 95 and later
9155 Transformational function
9157 @item @emph{Syntax}:
9158 @code{RESULT = RESHAPE(SOURCE, SHAPE[, PAD, ORDER])}
9160 @item @emph{Arguments}:
9161 @multitable @columnfractions .15 .70
9162 @item @var{SOURCE} @tab Shall be an array of any type.
9163 @item @var{SHAPE} @tab Shall be of type @code{INTEGER} and an
9164 array of rank one. Its values must be positive or zero.
9165 @item @var{PAD} @tab (Optional) shall be an array of the same
9166 type as @var{SOURCE}.
9167 @item @var{ORDER} @tab (Optional) shall be of type @code{INTEGER}
9168 and an array of the same shape as @var{SHAPE}. Its values shall
9169 be a permutation of the numbers from 1 to n, where n is the size of
9170 @var{SHAPE}. If @var{ORDER} is absent, the natural ordering shall
9174 @item @emph{Return value}:
9175 The result is an array of shape @var{SHAPE} with the same type as
9178 @item @emph{Example}:
9180 PROGRAM test_reshape
9181 INTEGER, DIMENSION(4) :: x
9182 WRITE(*,*) SHAPE(x) ! prints "4"
9183 WRITE(*,*) SHAPE(RESHAPE(x, (/2, 2/))) ! prints "2 2"
9187 @item @emph{See also}:
9194 @section @code{RRSPACING} --- Reciprocal of the relative spacing
9196 @cindex real number, relative spacing
9197 @cindex floating point, relative spacing
9201 @item @emph{Description}:
9202 @code{RRSPACING(X)} returns the reciprocal of the relative spacing of
9203 model numbers near @var{X}.
9205 @item @emph{Standard}:
9206 Fortran 95 and later
9211 @item @emph{Syntax}:
9212 @code{RESULT = RRSPACING(X)}
9214 @item @emph{Arguments}:
9215 @multitable @columnfractions .15 .70
9216 @item @var{X} @tab Shall be of type @code{REAL}.
9219 @item @emph{Return value}:
9220 The return value is of the same type and kind as @var{X}.
9221 The value returned is equal to
9222 @code{ABS(FRACTION(X)) * FLOAT(RADIX(X))**DIGITS(X)}.
9224 @item @emph{See also}:
9231 @section @code{RSHIFT} --- Right shift bits
9233 @cindex bits, shift right
9236 @item @emph{Description}:
9237 @code{RSHIFT} returns a value corresponding to @var{I} with all of the
9238 bits shifted right by @var{SHIFT} places. If the absolute value of
9239 @var{SHIFT} is greater than @code{BIT_SIZE(I)}, the value is undefined.
9240 Bits shifted out from the left end are lost; zeros are shifted in from
9243 This function has been superseded by the @code{ISHFT} intrinsic, which
9244 is standard in Fortran 95 and later.
9246 @item @emph{Standard}:
9252 @item @emph{Syntax}:
9253 @code{RESULT = RSHIFT(I, SHIFT)}
9255 @item @emph{Arguments}:
9256 @multitable @columnfractions .15 .70
9257 @item @var{I} @tab The type shall be @code{INTEGER}.
9258 @item @var{SHIFT} @tab The type shall be @code{INTEGER}.
9261 @item @emph{Return value}:
9262 The return value is of type @code{INTEGER} and of the same kind as
9265 @item @emph{See also}:
9266 @ref{ISHFT}, @ref{ISHFTC}, @ref{LSHIFT}
9273 @section @code{SCALE} --- Scale a real value
9275 @cindex real number, scale
9276 @cindex floating point, scale
9279 @item @emph{Description}:
9280 @code{SCALE(X,I)} returns @code{X * RADIX(X)**I}.
9282 @item @emph{Standard}:
9283 Fortran 95 and later
9288 @item @emph{Syntax}:
9289 @code{RESULT = SCALE(X, I)}
9291 @item @emph{Arguments}:
9292 @multitable @columnfractions .15 .70
9293 @item @var{X} @tab The type of the argument shall be a @code{REAL}.
9294 @item @var{I} @tab The type of the argument shall be a @code{INTEGER}.
9297 @item @emph{Return value}:
9298 The return value is of the same type and kind as @var{X}.
9299 Its value is @code{X * RADIX(X)**I}.
9301 @item @emph{Example}:
9304 real :: x = 178.1387e-4
9306 print *, scale(x,i), x*radix(x)**i
9307 end program test_scale
9315 @section @code{SCAN} --- Scan a string for the presence of a set of characters
9317 @cindex string, find subset
9320 @item @emph{Description}:
9321 Scans a @var{STRING} for any of the characters in a @var{SET}
9324 If @var{BACK} is either absent or equals @code{FALSE}, this function
9325 returns the position of the leftmost character of @var{STRING} that is
9326 in @var{SET}. If @var{BACK} equals @code{TRUE}, the rightmost position
9327 is returned. If no character of @var{SET} is found in @var{STRING}, the
9330 @item @emph{Standard}:
9331 Fortran 95 and later, with @var{KIND} argument Fortran 2003 and later
9336 @item @emph{Syntax}:
9337 @code{RESULT = SCAN(STRING, SET[, BACK [, KIND]])}
9339 @item @emph{Arguments}:
9340 @multitable @columnfractions .15 .70
9341 @item @var{STRING} @tab Shall be of type @code{CHARACTER}.
9342 @item @var{SET} @tab Shall be of type @code{CHARACTER}.
9343 @item @var{BACK} @tab (Optional) shall be of type @code{LOGICAL}.
9344 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
9345 expression indicating the kind parameter of the result.
9348 @item @emph{Return value}:
9349 The return value is of type @code{INTEGER} and of kind @var{KIND}. If
9350 @var{KIND} is absent, the return value is of default integer kind.
9352 @item @emph{Example}:
9355 WRITE(*,*) SCAN("FORTRAN", "AO") ! 2, found 'O'
9356 WRITE(*,*) SCAN("FORTRAN", "AO", .TRUE.) ! 6, found 'A'
9357 WRITE(*,*) SCAN("FORTRAN", "C++") ! 0, found none
9361 @item @emph{See also}:
9362 @ref{INDEX intrinsic}, @ref{VERIFY}
9368 @section @code{SECNDS} --- Time function
9370 @cindex time, elapsed
9371 @cindex elapsed time
9374 @item @emph{Description}:
9375 @code{SECNDS(X)} gets the time in seconds from the real-time system clock.
9376 @var{X} is a reference time, also in seconds. If this is zero, the time in
9377 seconds from midnight is returned. This function is non-standard and its
9380 @item @emph{Standard}:
9386 @item @emph{Syntax}:
9387 @code{RESULT = SECNDS (X)}
9389 @item @emph{Arguments}:
9390 @multitable @columnfractions .15 .70
9391 @item @var{T} @tab Shall be of type @code{REAL(4)}.
9392 @item @var{X} @tab Shall be of type @code{REAL(4)}.
9395 @item @emph{Return value}:
9398 @item @emph{Example}:
9403 print *, secnds (0.0) ! seconds since midnight
9404 t1 = secnds (0.0) ! reference time
9405 do i = 1, 10000000 ! do something
9407 t2 = secnds (t1) ! elapsed time
9408 print *, "Something took ", t2, " seconds."
9409 end program test_secnds
9416 @section @code{SECOND} --- CPU time function
9418 @cindex time, elapsed
9419 @cindex elapsed time
9422 @item @emph{Description}:
9423 Returns a @code{REAL(4)} value representing the elapsed CPU time in
9424 seconds. This provides the same functionality as the standard
9425 @code{CPU_TIME} intrinsic, and is only included for backwards
9428 This intrinsic is provided in both subroutine and function forms;
9429 however, only one form can be used in any given program unit.
9431 @item @emph{Standard}:
9435 Subroutine, function
9437 @item @emph{Syntax}:
9438 @multitable @columnfractions .80
9439 @item @code{CALL SECOND(TIME)}
9440 @item @code{TIME = SECOND()}
9443 @item @emph{Arguments}:
9444 @multitable @columnfractions .15 .70
9445 @item @var{TIME} @tab Shall be of type @code{REAL(4)}.
9448 @item @emph{Return value}:
9449 In either syntax, @var{TIME} is set to the process's current runtime in
9452 @item @emph{See also}:
9459 @node SELECTED_CHAR_KIND
9460 @section @code{SELECTED_CHAR_KIND} --- Choose character kind
9461 @fnindex SELECTED_CHAR_KIND
9462 @cindex character kind
9463 @cindex kind, character
9466 @item @emph{Description}:
9468 @code{SELECTED_CHAR_KIND(NAME)} returns the kind value for the character
9469 set named @var{NAME}, if a character set with such a name is supported,
9470 or @math{-1} otherwise. Currently, supported character sets include
9471 ``ASCII'' and ``DEFAULT'', which are equivalent.
9473 @item @emph{Standard}:
9474 Fortran 2003 and later
9477 Transformational function
9479 @item @emph{Syntax}:
9480 @code{RESULT = SELECTED_CHAR_KIND(NAME)}
9482 @item @emph{Arguments}:
9483 @multitable @columnfractions .15 .70
9484 @item @var{NAME} @tab Shall be a scalar and of the default character type.
9487 @item @emph{Example}:
9490 integer,parameter :: ascii = selected_char_kind("ascii")
9491 character(kind=ascii, len=26) :: s
9493 s = ascii_"abcdefghijklmnopqrstuvwxyz"
9495 end program ascii_kind
9501 @node SELECTED_INT_KIND
9502 @section @code{SELECTED_INT_KIND} --- Choose integer kind
9503 @fnindex SELECTED_INT_KIND
9504 @cindex integer kind
9505 @cindex kind, integer
9508 @item @emph{Description}:
9509 @code{SELECTED_INT_KIND(R)} return the kind value of the smallest integer
9510 type that can represent all values ranging from @math{-10^R} (exclusive)
9511 to @math{10^R} (exclusive). If there is no integer kind that accommodates
9512 this range, @code{SELECTED_INT_KIND} returns @math{-1}.
9514 @item @emph{Standard}:
9515 Fortran 95 and later
9518 Transformational function
9520 @item @emph{Syntax}:
9521 @code{RESULT = SELECTED_INT_KIND(R)}
9523 @item @emph{Arguments}:
9524 @multitable @columnfractions .15 .70
9525 @item @var{R} @tab Shall be a scalar and of type @code{INTEGER}.
9528 @item @emph{Example}:
9530 program large_integers
9531 integer,parameter :: k5 = selected_int_kind(5)
9532 integer,parameter :: k15 = selected_int_kind(15)
9533 integer(kind=k5) :: i5
9534 integer(kind=k15) :: i15
9536 print *, huge(i5), huge(i15)
9538 ! The following inequalities are always true
9539 print *, huge(i5) >= 10_k5**5-1
9540 print *, huge(i15) >= 10_k15**15-1
9541 end program large_integers
9547 @node SELECTED_REAL_KIND
9548 @section @code{SELECTED_REAL_KIND} --- Choose real kind
9549 @fnindex SELECTED_REAL_KIND
9554 @item @emph{Description}:
9555 @code{SELECTED_REAL_KIND(P,R)} returns the kind value of a real data type
9556 with decimal precision of at least @code{P} digits and exponent
9557 range greater at least @code{R}.
9559 @item @emph{Standard}:
9560 Fortran 95 and later
9563 Transformational function
9565 @item @emph{Syntax}:
9566 @code{RESULT = SELECTED_REAL_KIND([P, R])}
9568 @item @emph{Arguments}:
9569 @multitable @columnfractions .15 .70
9570 @item @var{P} @tab (Optional) shall be a scalar and of type @code{INTEGER}.
9571 @item @var{R} @tab (Optional) shall be a scalar and of type @code{INTEGER}.
9573 At least one argument shall be present.
9575 @item @emph{Return value}:
9577 @code{SELECTED_REAL_KIND} returns the value of the kind type parameter of
9578 a real data type with decimal precision of at least @code{P} digits and a
9579 decimal exponent range of at least @code{R}. If more than one real data
9580 type meet the criteria, the kind of the data type with the smallest
9581 decimal precision is returned. If no real data type matches the criteria,
9584 @item -1 if the processor does not support a real data type with a
9585 precision greater than or equal to @code{P}
9586 @item -2 if the processor does not support a real type with an exponent
9587 range greater than or equal to @code{R}
9588 @item -3 if neither is supported.
9591 @item @emph{Example}:
9594 integer,parameter :: p6 = selected_real_kind(6)
9595 integer,parameter :: p10r100 = selected_real_kind(10,100)
9596 integer,parameter :: r400 = selected_real_kind(r=400)
9598 real(kind=p10r100) :: y
9599 real(kind=r400) :: z
9601 print *, precision(x), range(x)
9602 print *, precision(y), range(y)
9603 print *, precision(z), range(z)
9604 end program real_kinds
9611 @section @code{SET_EXPONENT} --- Set the exponent of the model
9612 @fnindex SET_EXPONENT
9613 @cindex real number, set exponent
9614 @cindex floating point, set exponent
9617 @item @emph{Description}:
9618 @code{SET_EXPONENT(X, I)} returns the real number whose fractional part
9619 is that that of @var{X} and whose exponent part is @var{I}.
9621 @item @emph{Standard}:
9622 Fortran 95 and later
9627 @item @emph{Syntax}:
9628 @code{RESULT = SET_EXPONENT(X, I)}
9630 @item @emph{Arguments}:
9631 @multitable @columnfractions .15 .70
9632 @item @var{X} @tab Shall be of type @code{REAL}.
9633 @item @var{I} @tab Shall be of type @code{INTEGER}.
9636 @item @emph{Return value}:
9637 The return value is of the same type and kind as @var{X}.
9638 The real number whose fractional part
9639 is that that of @var{X} and whose exponent part if @var{I} is returned;
9640 it is @code{FRACTION(X) * RADIX(X)**I}.
9642 @item @emph{Example}:
9645 REAL :: x = 178.1387e-4
9647 PRINT *, SET_EXPONENT(x, i), FRACTION(x) * RADIX(x)**i
9656 @section @code{SHAPE} --- Determine the shape of an array
9658 @cindex array, shape
9661 @item @emph{Description}:
9662 Determines the shape of an array.
9664 @item @emph{Standard}:
9665 Fortran 95 and later
9670 @item @emph{Syntax}:
9671 @code{RESULT = SHAPE(SOURCE)}
9673 @item @emph{Arguments}:
9674 @multitable @columnfractions .15 .70
9675 @item @var{SOURCE} @tab Shall be an array or scalar of any type.
9676 If @var{SOURCE} is a pointer it must be associated and allocatable
9677 arrays must be allocated.
9680 @item @emph{Return value}:
9681 An @code{INTEGER} array of rank one with as many elements as @var{SOURCE}
9682 has dimensions. The elements of the resulting array correspond to the extend
9683 of @var{SOURCE} along the respective dimensions. If @var{SOURCE} is a scalar,
9684 the result is the rank one array of size zero.
9686 @item @emph{Example}:
9689 INTEGER, DIMENSION(-1:1, -1:2) :: A
9690 WRITE(*,*) SHAPE(A) ! (/ 3, 4 /)
9691 WRITE(*,*) SIZE(SHAPE(42)) ! (/ /)
9695 @item @emph{See also}:
9696 @ref{RESHAPE}, @ref{SIZE}
9702 @section @code{SIGN} --- Sign copying function
9706 @cindex sign copying
9709 @item @emph{Description}:
9710 @code{SIGN(A,B)} returns the value of @var{A} with the sign of @var{B}.
9712 @item @emph{Standard}:
9713 Fortran 77 and later
9718 @item @emph{Syntax}:
9719 @code{RESULT = SIGN(A, B)}
9721 @item @emph{Arguments}:
9722 @multitable @columnfractions .15 .70
9723 @item @var{A} @tab Shall be of type @code{INTEGER} or @code{REAL}
9724 @item @var{B} @tab Shall be of the same type and kind as @var{A}
9727 @item @emph{Return value}:
9728 The kind of the return value is that of @var{A} and @var{B}.
9729 If @math{B\ge 0} then the result is @code{ABS(A)}, else
9730 it is @code{-ABS(A)}.
9732 @item @emph{Example}:
9735 print *, sign(-12,1)
9736 print *, sign(-12,0)
9737 print *, sign(-12,-1)
9739 print *, sign(-12.,1.)
9740 print *, sign(-12.,0.)
9741 print *, sign(-12.,-1.)
9742 end program test_sign
9745 @item @emph{Specific names}:
9746 @multitable @columnfractions .20 .20 .20 .25
9747 @item Name @tab Arguments @tab Return type @tab Standard
9748 @item @code{ISIGN(A,P)} @tab @code{INTEGER(4)} @tab @code{INTEGER(4)} @tab f95, gnu
9749 @item @code{DSIGN(A,P)} @tab @code{REAL(8)} @tab @code{REAL(8)} @tab f95, gnu
9756 @section @code{SIGNAL} --- Signal handling subroutine (or function)
9758 @cindex system, signal handling
9761 @item @emph{Description}:
9762 @code{SIGNAL(NUMBER, HANDLER [, STATUS])} causes external subroutine
9763 @var{HANDLER} to be executed with a single integer argument when signal
9764 @var{NUMBER} occurs. If @var{HANDLER} is an integer, it can be used to
9765 turn off handling of signal @var{NUMBER} or revert to its default
9766 action. See @code{signal(2)}.
9768 If @code{SIGNAL} is called as a subroutine and the @var{STATUS} argument
9769 is supplied, it is set to the value returned by @code{signal(2)}.
9771 @item @emph{Standard}:
9775 Subroutine, function
9777 @item @emph{Syntax}:
9778 @multitable @columnfractions .80
9779 @item @code{CALL SIGNAL(NUMBER, HANDLER [, STATUS])}
9780 @item @code{STATUS = SIGNAL(NUMBER, HANDLER)}
9783 @item @emph{Arguments}:
9784 @multitable @columnfractions .15 .70
9785 @item @var{NUMBER} @tab Shall be a scalar integer, with @code{INTENT(IN)}
9786 @item @var{HANDLER}@tab Signal handler (@code{INTEGER FUNCTION} or
9787 @code{SUBROUTINE}) or dummy/global @code{INTEGER} scalar.
9788 @code{INTEGER}. It is @code{INTENT(IN)}.
9789 @item @var{STATUS} @tab (Optional) @var{STATUS} shall be a scalar
9790 integer. It has @code{INTENT(OUT)}.
9792 @c TODO: What should the interface of the handler be? Does it take arguments?
9794 @item @emph{Return value}:
9795 The @code{SIGNAL} function returns the value returned by @code{signal(2)}.
9797 @item @emph{Example}:
9801 external handler_print
9803 call signal (12, handler_print)
9807 end program test_signal
9814 @section @code{SIN} --- Sine function
9820 @cindex trigonometric function, sine
9824 @item @emph{Description}:
9825 @code{SIN(X)} computes the sine of @var{X}.
9827 @item @emph{Standard}:
9828 Fortran 77 and later
9833 @item @emph{Syntax}:
9834 @code{RESULT = SIN(X)}
9836 @item @emph{Arguments}:
9837 @multitable @columnfractions .15 .70
9838 @item @var{X} @tab The type shall be @code{REAL} or
9842 @item @emph{Return value}:
9843 The return value has same type and kind as @var{X}.
9845 @item @emph{Example}:
9850 end program test_sin
9853 @item @emph{Specific names}:
9854 @multitable @columnfractions .20 .20 .20 .25
9855 @item Name @tab Argument @tab Return type @tab Standard
9856 @item @code{DSIN(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab f95, gnu
9857 @item @code{CSIN(X)} @tab @code{COMPLEX(4) X} @tab @code{COMPLEX(4)} @tab f95, gnu
9858 @item @code{ZSIN(X)} @tab @code{COMPLEX(8) X} @tab @code{COMPLEX(8)} @tab f95, gnu
9859 @item @code{CDSIN(X)} @tab @code{COMPLEX(8) X} @tab @code{COMPLEX(8)} @tab f95, gnu
9862 @item @emph{See also}:
9869 @section @code{SINH} --- Hyperbolic sine function
9872 @cindex hyperbolic sine
9873 @cindex hyperbolic function, sine
9874 @cindex sine, hyperbolic
9877 @item @emph{Description}:
9878 @code{SINH(X)} computes the hyperbolic sine of @var{X}.
9880 @item @emph{Standard}:
9881 Fortran 95 and later, for a complex argument Fortran 2008 or later
9886 @item @emph{Syntax}:
9887 @code{RESULT = SINH(X)}
9889 @item @emph{Arguments}:
9890 @multitable @columnfractions .15 .70
9891 @item @var{X} @tab The type shall be @code{REAL} or @code{COMPLEX}.
9894 @item @emph{Return value}:
9895 The return value has same type and kind as @var{X}.
9897 @item @emph{Example}:
9900 real(8) :: x = - 1.0_8
9902 end program test_sinh
9905 @item @emph{Specific names}:
9906 @multitable @columnfractions .20 .20 .20 .25
9907 @item Name @tab Argument @tab Return type @tab Standard
9908 @item @code{DSINH(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab Fortran 95 and later
9911 @item @emph{See also}:
9918 @section @code{SIZE} --- Determine the size of an array
9921 @cindex array, number of elements
9922 @cindex array, count elements
9925 @item @emph{Description}:
9926 Determine the extent of @var{ARRAY} along a specified dimension @var{DIM},
9927 or the total number of elements in @var{ARRAY} if @var{DIM} is absent.
9929 @item @emph{Standard}:
9930 Fortran 95 and later, with @var{KIND} argument Fortran 2003 and later
9935 @item @emph{Syntax}:
9936 @code{RESULT = SIZE(ARRAY[, DIM [, KIND]])}
9938 @item @emph{Arguments}:
9939 @multitable @columnfractions .15 .70
9940 @item @var{ARRAY} @tab Shall be an array of any type. If @var{ARRAY} is
9941 a pointer it must be associated and allocatable arrays must be allocated.
9942 @item @var{DIM} @tab (Optional) shall be a scalar of type @code{INTEGER}
9943 and its value shall be in the range from 1 to n, where n equals the rank
9945 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
9946 expression indicating the kind parameter of the result.
9949 @item @emph{Return value}:
9950 The return value is of type @code{INTEGER} and of kind @var{KIND}. If
9951 @var{KIND} is absent, the return value is of default integer kind.
9953 @item @emph{Example}:
9956 WRITE(*,*) SIZE((/ 1, 2 /)) ! 2
9960 @item @emph{See also}:
9961 @ref{SHAPE}, @ref{RESHAPE}
9966 @section @code{SIZEOF} --- Size in bytes of an expression
9968 @cindex expression size
9969 @cindex size of an expression
9972 @item @emph{Description}:
9973 @code{SIZEOF(X)} calculates the number of bytes of storage the
9974 expression @code{X} occupies.
9976 @item @emph{Standard}:
9982 @item @emph{Syntax}:
9983 @code{N = SIZEOF(X)}
9985 @item @emph{Arguments}:
9986 @multitable @columnfractions .15 .70
9987 @item @var{X} @tab The argument shall be of any type, rank or shape.
9990 @item @emph{Return value}:
9991 The return value is of type integer and of the system-dependent kind
9992 @var{C_SIZE_T} (from the @var{ISO_C_BINDING} module). Its value is the
9993 number of bytes occupied by the argument. If the argument has the
9994 @code{POINTER} attribute, the number of bytes of the storage area pointed
9995 to is returned. If the argument is of a derived type with @code{POINTER}
9996 or @code{ALLOCATABLE} components, the return value doesn't account for
9997 the sizes of the data pointed to by these components.
9999 @item @emph{Example}:
10003 print *, (sizeof(s)/sizeof(r) == 5)
10006 The example will print @code{.TRUE.} unless you are using a platform
10007 where default @code{REAL} variables are unusually padded.
10009 @item @emph{See also}:
10015 @section @code{SLEEP} --- Sleep for the specified number of seconds
10017 @cindex delayed execution
10020 @item @emph{Description}:
10021 Calling this subroutine causes the process to pause for @var{SECONDS} seconds.
10023 @item @emph{Standard}:
10026 @item @emph{Class}:
10029 @item @emph{Syntax}:
10030 @code{CALL SLEEP(SECONDS)}
10032 @item @emph{Arguments}:
10033 @multitable @columnfractions .15 .70
10034 @item @var{SECONDS} @tab The type shall be of default @code{INTEGER}.
10037 @item @emph{Example}:
10048 @section @code{SNGL} --- Convert double precision real to default real
10050 @cindex conversion, to real
10053 @item @emph{Description}:
10054 @code{SNGL(A)} converts the double precision real @var{A}
10055 to a default real value. This is an archaic form of @code{REAL}
10056 that is specific to one type for @var{A}.
10058 @item @emph{Standard}:
10059 Fortran 77 and later
10061 @item @emph{Class}:
10064 @item @emph{Syntax}:
10065 @code{RESULT = SNGL(A)}
10067 @item @emph{Arguments}:
10068 @multitable @columnfractions .15 .70
10069 @item @var{A} @tab The type shall be a double precision @code{REAL}.
10072 @item @emph{Return value}:
10073 The return value is of type default @code{REAL}.
10075 @item @emph{See also}:
10082 @section @code{SPACING} --- Smallest distance between two numbers of a given type
10084 @cindex real number, relative spacing
10085 @cindex floating point, relative spacing
10088 @item @emph{Description}:
10089 Determines the distance between the argument @var{X} and the nearest
10090 adjacent number of the same type.
10092 @item @emph{Standard}:
10093 Fortran 95 and later
10095 @item @emph{Class}:
10098 @item @emph{Syntax}:
10099 @code{RESULT = SPACING(X)}
10101 @item @emph{Arguments}:
10102 @multitable @columnfractions .15 .70
10103 @item @var{X} @tab Shall be of type @code{REAL}.
10106 @item @emph{Return value}:
10107 The result is of the same type as the input argument @var{X}.
10109 @item @emph{Example}:
10111 PROGRAM test_spacing
10112 INTEGER, PARAMETER :: SGL = SELECTED_REAL_KIND(p=6, r=37)
10113 INTEGER, PARAMETER :: DBL = SELECTED_REAL_KIND(p=13, r=200)
10115 WRITE(*,*) spacing(1.0_SGL) ! "1.1920929E-07" on i686
10116 WRITE(*,*) spacing(1.0_DBL) ! "2.220446049250313E-016" on i686
10120 @item @emph{See also}:
10127 @section @code{SPREAD} --- Add a dimension to an array
10129 @cindex array, increase dimension
10130 @cindex array, duplicate elements
10131 @cindex array, duplicate dimensions
10134 @item @emph{Description}:
10135 Replicates a @var{SOURCE} array @var{NCOPIES} times along a specified
10136 dimension @var{DIM}.
10138 @item @emph{Standard}:
10139 Fortran 95 and later
10141 @item @emph{Class}:
10142 Transformational function
10144 @item @emph{Syntax}:
10145 @code{RESULT = SPREAD(SOURCE, DIM, NCOPIES)}
10147 @item @emph{Arguments}:
10148 @multitable @columnfractions .15 .70
10149 @item @var{SOURCE} @tab Shall be a scalar or an array of any type and
10150 a rank less than seven.
10151 @item @var{DIM} @tab Shall be a scalar of type @code{INTEGER} with a
10152 value in the range from 1 to n+1, where n equals the rank of @var{SOURCE}.
10153 @item @var{NCOPIES} @tab Shall be a scalar of type @code{INTEGER}.
10156 @item @emph{Return value}:
10157 The result is an array of the same type as @var{SOURCE} and has rank n+1
10158 where n equals the rank of @var{SOURCE}.
10160 @item @emph{Example}:
10162 PROGRAM test_spread
10163 INTEGER :: a = 1, b(2) = (/ 1, 2 /)
10164 WRITE(*,*) SPREAD(A, 1, 2) ! "1 1"
10165 WRITE(*,*) SPREAD(B, 1, 2) ! "1 1 2 2"
10169 @item @emph{See also}:
10176 @section @code{SQRT} --- Square-root function
10183 @cindex square-root
10186 @item @emph{Description}:
10187 @code{SQRT(X)} computes the square root of @var{X}.
10189 @item @emph{Standard}:
10190 Fortran 77 and later
10192 @item @emph{Class}:
10195 @item @emph{Syntax}:
10196 @code{RESULT = SQRT(X)}
10198 @item @emph{Arguments}:
10199 @multitable @columnfractions .15 .70
10200 @item @var{X} @tab The type shall be @code{REAL} or
10204 @item @emph{Return value}:
10205 The return value is of type @code{REAL} or @code{COMPLEX}.
10206 The kind type parameter is the same as @var{X}.
10208 @item @emph{Example}:
10211 real(8) :: x = 2.0_8
10212 complex :: z = (1.0, 2.0)
10215 end program test_sqrt
10218 @item @emph{Specific names}:
10219 @multitable @columnfractions .20 .20 .20 .25
10220 @item Name @tab Argument @tab Return type @tab Standard
10221 @item @code{DSQRT(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab Fortran 95 and later
10222 @item @code{CSQRT(X)} @tab @code{COMPLEX(4) X} @tab @code{COMPLEX(4)} @tab Fortran 95 and later
10223 @item @code{ZSQRT(X)} @tab @code{COMPLEX(8) X} @tab @code{COMPLEX(8)} @tab GNU extension
10224 @item @code{CDSQRT(X)} @tab @code{COMPLEX(8) X} @tab @code{COMPLEX(8)} @tab GNU extension
10231 @section @code{SRAND} --- Reinitialize the random number generator
10233 @cindex random number generation, seeding
10234 @cindex seeding a random number generator
10237 @item @emph{Description}:
10238 @code{SRAND} reinitializes the pseudo-random number generator
10239 called by @code{RAND} and @code{IRAND}. The new seed used by the
10240 generator is specified by the required argument @var{SEED}.
10242 @item @emph{Standard}:
10245 @item @emph{Class}:
10248 @item @emph{Syntax}:
10249 @code{CALL SRAND(SEED)}
10251 @item @emph{Arguments}:
10252 @multitable @columnfractions .15 .70
10253 @item @var{SEED} @tab Shall be a scalar @code{INTEGER(kind=4)}.
10256 @item @emph{Return value}:
10257 Does not return anything.
10259 @item @emph{Example}:
10260 See @code{RAND} and @code{IRAND} for examples.
10262 @item @emph{Notes}:
10263 The Fortran 2003 standard specifies the intrinsic @code{RANDOM_SEED} to
10264 initialize the pseudo-random numbers generator and @code{RANDOM_NUMBER}
10265 to generate pseudo-random numbers. Please note that in
10266 GNU Fortran, these two sets of intrinsics (@code{RAND},
10267 @code{IRAND} and @code{SRAND} on the one hand, @code{RANDOM_NUMBER} and
10268 @code{RANDOM_SEED} on the other hand) access two independent
10269 pseudo-random number generators.
10271 @item @emph{See also}:
10272 @ref{RAND}, @ref{RANDOM_SEED}, @ref{RANDOM_NUMBER}
10279 @section @code{STAT} --- Get file status
10281 @cindex file system, file status
10284 @item @emph{Description}:
10285 This function returns information about a file. No permissions are required on
10286 the file itself, but execute (search) permission is required on all of the
10287 directories in path that lead to the file.
10289 The elements that are obtained and stored in the array @code{VALUES}:
10290 @multitable @columnfractions .15 .70
10291 @item @code{VALUES(1)} @tab Device ID
10292 @item @code{VALUES(2)} @tab Inode number
10293 @item @code{VALUES(3)} @tab File mode
10294 @item @code{VALUES(4)} @tab Number of links
10295 @item @code{VALUES(5)} @tab Owner's uid
10296 @item @code{VALUES(6)} @tab Owner's gid
10297 @item @code{VALUES(7)} @tab ID of device containing directory entry for file (0 if not available)
10298 @item @code{VALUES(8)} @tab File size (bytes)
10299 @item @code{VALUES(9)} @tab Last access time
10300 @item @code{VALUES(10)} @tab Last modification time
10301 @item @code{VALUES(11)} @tab Last file status change time
10302 @item @code{VALUES(12)} @tab Preferred I/O block size (-1 if not available)
10303 @item @code{VALUES(13)} @tab Number of blocks allocated (-1 if not available)
10306 Not all these elements are relevant on all systems.
10307 If an element is not relevant, it is returned as 0.
10309 This intrinsic is provided in both subroutine and function forms; however,
10310 only one form can be used in any given program unit.
10312 @item @emph{Standard}:
10315 @item @emph{Class}:
10316 Subroutine, function
10318 @item @emph{Syntax}:
10319 @code{CALL STAT(NAME, VALUES [, STATUS])}
10321 @item @emph{Arguments}:
10322 @multitable @columnfractions .15 .70
10323 @item @var{NAME} @tab The type shall be @code{CHARACTER}, of the
10324 default kind and a valid path within the file system.
10325 @item @var{VALUES} @tab The type shall be @code{INTEGER(4), DIMENSION(13)}.
10326 @item @var{STATUS} @tab (Optional) status flag of type @code{INTEGER(4)}. Returns 0
10327 on success and a system specific error code otherwise.
10330 @item @emph{Example}:
10333 INTEGER, DIMENSION(13) :: buff
10336 CALL STAT("/etc/passwd", buff, status)
10338 IF (status == 0) THEN
10339 WRITE (*, FMT="('Device ID:', T30, I19)") buff(1)
10340 WRITE (*, FMT="('Inode number:', T30, I19)") buff(2)
10341 WRITE (*, FMT="('File mode (octal):', T30, O19)") buff(3)
10342 WRITE (*, FMT="('Number of links:', T30, I19)") buff(4)
10343 WRITE (*, FMT="('Owner''s uid:', T30, I19)") buff(5)
10344 WRITE (*, FMT="('Owner''s gid:', T30, I19)") buff(6)
10345 WRITE (*, FMT="('Device where located:', T30, I19)") buff(7)
10346 WRITE (*, FMT="('File size:', T30, I19)") buff(8)
10347 WRITE (*, FMT="('Last access time:', T30, A19)") CTIME(buff(9))
10348 WRITE (*, FMT="('Last modification time', T30, A19)") CTIME(buff(10))
10349 WRITE (*, FMT="('Last status change time:', T30, A19)") CTIME(buff(11))
10350 WRITE (*, FMT="('Preferred block size:', T30, I19)") buff(12)
10351 WRITE (*, FMT="('No. of blocks allocated:', T30, I19)") buff(13)
10356 @item @emph{See also}:
10357 To stat an open file: @ref{FSTAT}, to stat a link: @ref{LSTAT}
10363 @section @code{SUM} --- Sum of array elements
10366 @cindex array, add elements
10367 @cindex array, conditionally add elements
10368 @cindex sum array elements
10371 @item @emph{Description}:
10372 Adds the elements of @var{ARRAY} along dimension @var{DIM} if
10373 the corresponding element in @var{MASK} is @code{TRUE}.
10375 @item @emph{Standard}:
10376 Fortran 95 and later
10378 @item @emph{Class}:
10379 Transformational function
10381 @item @emph{Syntax}:
10382 @multitable @columnfractions .80
10383 @item @code{RESULT = SUM(ARRAY[, MASK])}
10384 @item @code{RESULT = SUM(ARRAY, DIM[, MASK])}
10387 @item @emph{Arguments}:
10388 @multitable @columnfractions .15 .70
10389 @item @var{ARRAY} @tab Shall be an array of type @code{INTEGER},
10390 @code{REAL} or @code{COMPLEX}.
10391 @item @var{DIM} @tab (Optional) shall be a scalar of type
10392 @code{INTEGER} with a value in the range from 1 to n, where n
10393 equals the rank of @var{ARRAY}.
10394 @item @var{MASK} @tab (Optional) shall be of type @code{LOGICAL}
10395 and either be a scalar or an array of the same shape as @var{ARRAY}.
10398 @item @emph{Return value}:
10399 The result is of the same type as @var{ARRAY}.
10401 If @var{DIM} is absent, a scalar with the sum of all elements in @var{ARRAY}
10402 is returned. Otherwise, an array of rank n-1, where n equals the rank of
10403 @var{ARRAY},and a shape similar to that of @var{ARRAY} with dimension @var{DIM}
10404 dropped is returned.
10406 @item @emph{Example}:
10409 INTEGER :: x(5) = (/ 1, 2, 3, 4 ,5 /)
10410 print *, SUM(x) ! all elements, sum = 15
10411 print *, SUM(x, MASK=MOD(x, 2)==1) ! odd elements, sum = 9
10415 @item @emph{See also}:
10422 @section @code{SYMLNK} --- Create a symbolic link
10424 @cindex file system, create link
10425 @cindex file system, soft link
10428 @item @emph{Description}:
10429 Makes a symbolic link from file @var{PATH1} to @var{PATH2}. A null
10430 character (@code{CHAR(0)}) can be used to mark the end of the names in
10431 @var{PATH1} and @var{PATH2}; otherwise, trailing blanks in the file
10432 names are ignored. If the @var{STATUS} argument is supplied, it
10433 contains 0 on success or a nonzero error code upon return; see
10434 @code{symlink(2)}. If the system does not supply @code{symlink(2)},
10435 @code{ENOSYS} is returned.
10437 This intrinsic is provided in both subroutine and function forms;
10438 however, only one form can be used in any given program unit.
10440 @item @emph{Standard}:
10443 @item @emph{Class}:
10444 Subroutine, function
10446 @item @emph{Syntax}:
10447 @multitable @columnfractions .80
10448 @item @code{CALL SYMLNK(PATH1, PATH2 [, STATUS])}
10449 @item @code{STATUS = SYMLNK(PATH1, PATH2)}
10452 @item @emph{Arguments}:
10453 @multitable @columnfractions .15 .70
10454 @item @var{PATH1} @tab Shall be of default @code{CHARACTER} type.
10455 @item @var{PATH2} @tab Shall be of default @code{CHARACTER} type.
10456 @item @var{STATUS} @tab (Optional) Shall be of default @code{INTEGER} type.
10459 @item @emph{See also}:
10460 @ref{LINK}, @ref{UNLINK}
10467 @section @code{SYSTEM} --- Execute a shell command
10469 @cindex system, system call
10472 @item @emph{Description}:
10473 Passes the command @var{COMMAND} to a shell (see @code{system(3)}). If
10474 argument @var{STATUS} is present, it contains the value returned by
10475 @code{system(3)}, which is presumably 0 if the shell command succeeded.
10476 Note that which shell is used to invoke the command is system-dependent
10477 and environment-dependent.
10479 This intrinsic is provided in both subroutine and function forms;
10480 however, only one form can be used in any given program unit.
10482 @item @emph{Standard}:
10485 @item @emph{Class}:
10486 Subroutine, function
10488 @item @emph{Syntax}:
10489 @multitable @columnfractions .80
10490 @item @code{CALL SYSTEM(COMMAND [, STATUS])}
10491 @item @code{STATUS = SYSTEM(COMMAND)}
10494 @item @emph{Arguments}:
10495 @multitable @columnfractions .15 .70
10496 @item @var{COMMAND} @tab Shall be of default @code{CHARACTER} type.
10497 @item @var{STATUS} @tab (Optional) Shall be of default @code{INTEGER} type.
10500 @item @emph{See also}:
10506 @section @code{SYSTEM_CLOCK} --- Time function
10507 @fnindex SYSTEM_CLOCK
10508 @cindex time, clock ticks
10509 @cindex clock ticks
10512 @item @emph{Description}:
10513 Determines the @var{COUNT} of milliseconds of wall clock time since
10514 the Epoch (00:00:00 UTC, January 1, 1970) modulo @var{COUNT_MAX},
10515 @var{COUNT_RATE} determines the number of clock ticks per second.
10516 @var{COUNT_RATE} and @var{COUNT_MAX} are constant and specific to
10517 @command{gfortran}.
10519 If there is no clock, @var{COUNT} is set to @code{-HUGE(COUNT)}, and
10520 @var{COUNT_RATE} and @var{COUNT_MAX} are set to zero
10522 @item @emph{Standard}:
10523 Fortran 95 and later
10525 @item @emph{Class}:
10528 @item @emph{Syntax}:
10529 @code{CALL SYSTEM_CLOCK([COUNT, COUNT_RATE, COUNT_MAX])}
10531 @item @emph{Arguments}:
10532 @item @emph{Arguments}:
10533 @multitable @columnfractions .15 .70
10534 @item @var{COUNT} @tab (Optional) shall be a scalar of type default
10535 @code{INTEGER} with @code{INTENT(OUT)}.
10536 @item @var{COUNT_RATE} @tab (Optional) shall be a scalar of type default
10537 @code{INTEGER} with @code{INTENT(OUT)}.
10538 @item @var{COUNT_MAX} @tab (Optional) shall be a scalar of type default
10539 @code{INTEGER} with @code{INTENT(OUT)}.
10542 @item @emph{Example}:
10544 PROGRAM test_system_clock
10545 INTEGER :: count, count_rate, count_max
10546 CALL SYSTEM_CLOCK(count, count_rate, count_max)
10547 WRITE(*,*) count, count_rate, count_max
10551 @item @emph{See also}:
10552 @ref{DATE_AND_TIME}, @ref{CPU_TIME}
10558 @section @code{TAN} --- Tangent function
10561 @cindex trigonometric function, tangent
10565 @item @emph{Description}:
10566 @code{TAN(X)} computes the tangent of @var{X}.
10568 @item @emph{Standard}:
10569 Fortran 77 and later, for a complex argument Fortran 2008 or later
10571 @item @emph{Class}:
10574 @item @emph{Syntax}:
10575 @code{RESULT = TAN(X)}
10577 @item @emph{Arguments}:
10578 @multitable @columnfractions .15 .70
10579 @item @var{X} @tab The type shall be @code{REAL} or @code{COMPLEX}.
10582 @item @emph{Return value}:
10583 The return value has same type and kind as @var{X}.
10585 @item @emph{Example}:
10588 real(8) :: x = 0.165_8
10590 end program test_tan
10593 @item @emph{Specific names}:
10594 @multitable @columnfractions .20 .20 .20 .25
10595 @item Name @tab Argument @tab Return type @tab Standard
10596 @item @code{DTAN(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab Fortran 95 and later
10599 @item @emph{See also}:
10606 @section @code{TANH} --- Hyperbolic tangent function
10609 @cindex hyperbolic tangent
10610 @cindex hyperbolic function, tangent
10611 @cindex tangent, hyperbolic
10614 @item @emph{Description}:
10615 @code{TANH(X)} computes the hyperbolic tangent of @var{X}.
10617 @item @emph{Standard}:
10618 Fortran 77 and later, for a complex argument Fortran 2008 or later
10620 @item @emph{Class}:
10623 @item @emph{Syntax}:
10626 @item @emph{Arguments}:
10627 @multitable @columnfractions .15 .70
10628 @item @var{X} @tab The type shall be @code{REAL} or @code{COMPLEX}.
10631 @item @emph{Return value}:
10632 The return value has same type and kind as @var{X}. If @var{X} is
10633 complex, the imaginary part of the result is in radians. If @var{X}
10634 is @code{REAL}, the return value lies in the range
10635 @math{ - 1 \leq tanh(x) \leq 1 }.
10637 @item @emph{Example}:
10640 real(8) :: x = 2.1_8
10642 end program test_tanh
10645 @item @emph{Specific names}:
10646 @multitable @columnfractions .20 .20 .20 .25
10647 @item Name @tab Argument @tab Return type @tab Standard
10648 @item @code{DTANH(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab Fortran 95 and later
10651 @item @emph{See also}:
10658 @section @code{TIME} --- Time function
10660 @cindex time, current
10661 @cindex current time
10664 @item @emph{Description}:
10665 Returns the current time encoded as an integer (in the manner of the
10666 UNIX function @code{time(3)}). This value is suitable for passing to
10667 @code{CTIME()}, @code{GMTIME()}, and @code{LTIME()}.
10669 This intrinsic is not fully portable, such as to systems with 32-bit
10670 @code{INTEGER} types but supporting times wider than 32 bits. Therefore,
10671 the values returned by this intrinsic might be, or become, negative, or
10672 numerically less than previous values, during a single run of the
10675 See @ref{TIME8}, for information on a similar intrinsic that might be
10676 portable to more GNU Fortran implementations, though to fewer Fortran
10679 @item @emph{Standard}:
10682 @item @emph{Class}:
10685 @item @emph{Syntax}:
10686 @code{RESULT = TIME()}
10688 @item @emph{Return value}:
10689 The return value is a scalar of type @code{INTEGER(4)}.
10691 @item @emph{See also}:
10692 @ref{CTIME}, @ref{GMTIME}, @ref{LTIME}, @ref{MCLOCK}, @ref{TIME8}
10699 @section @code{TIME8} --- Time function (64-bit)
10701 @cindex time, current
10702 @cindex current time
10705 @item @emph{Description}:
10706 Returns the current time encoded as an integer (in the manner of the
10707 UNIX function @code{time(3)}). This value is suitable for passing to
10708 @code{CTIME()}, @code{GMTIME()}, and @code{LTIME()}.
10710 @emph{Warning:} this intrinsic does not increase the range of the timing
10711 values over that returned by @code{time(3)}. On a system with a 32-bit
10712 @code{time(3)}, @code{TIME8()} will return a 32-bit value, even though
10713 it is converted to a 64-bit @code{INTEGER(8)} value. That means
10714 overflows of the 32-bit value can still occur. Therefore, the values
10715 returned by this intrinsic might be or become negative or numerically
10716 less than previous values during a single run of the compiled program.
10718 @item @emph{Standard}:
10721 @item @emph{Class}:
10724 @item @emph{Syntax}:
10725 @code{RESULT = TIME8()}
10727 @item @emph{Return value}:
10728 The return value is a scalar of type @code{INTEGER(8)}.
10730 @item @emph{See also}:
10731 @ref{CTIME}, @ref{GMTIME}, @ref{LTIME}, @ref{MCLOCK8}, @ref{TIME}
10738 @section @code{TINY} --- Smallest positive number of a real kind
10740 @cindex limits, smallest number
10741 @cindex model representation, smallest number
10744 @item @emph{Description}:
10745 @code{TINY(X)} returns the smallest positive (non zero) number
10746 in the model of the type of @code{X}.
10748 @item @emph{Standard}:
10749 Fortran 95 and later
10751 @item @emph{Class}:
10754 @item @emph{Syntax}:
10755 @code{RESULT = TINY(X)}
10757 @item @emph{Arguments}:
10758 @multitable @columnfractions .15 .70
10759 @item @var{X} @tab Shall be of type @code{REAL}.
10762 @item @emph{Return value}:
10763 The return value is of the same type and kind as @var{X}
10765 @item @emph{Example}:
10766 See @code{HUGE} for an example.
10772 @section @code{TRAILZ} --- Number of trailing zero bits of an integer
10777 @item @emph{Description}:
10778 @code{TRAILZ} returns the number of trailing zero bits of an integer.
10780 @item @emph{Standard}:
10781 Fortran 2008 and later
10783 @item @emph{Class}:
10786 @item @emph{Syntax}:
10787 @code{RESULT = TRAILZ(I)}
10789 @item @emph{Arguments}:
10790 @multitable @columnfractions .15 .70
10791 @item @var{I} @tab Shall be of type @code{INTEGER}.
10794 @item @emph{Return value}:
10795 The type of the return value is the default @code{INTEGER}.
10796 If all the bits of @code{I} are zero, the result value is @code{BIT_SIZE(I)}.
10798 @item @emph{Example}:
10800 PROGRAM test_trailz
10801 WRITE (*,*) TRAILZ(8) ! prints 3
10805 @item @emph{See also}:
10806 @ref{BIT_SIZE}, @ref{LEADZ}
10812 @section @code{TRANSFER} --- Transfer bit patterns
10818 @item @emph{Description}:
10819 Interprets the bitwise representation of @var{SOURCE} in memory as if it
10820 is the representation of a variable or array of the same type and type
10821 parameters as @var{MOLD}.
10823 This is approximately equivalent to the C concept of @emph{casting} one
10826 @item @emph{Standard}:
10827 Fortran 95 and later
10829 @item @emph{Class}:
10830 Transformational function
10832 @item @emph{Syntax}:
10833 @code{RESULT = TRANSFER(SOURCE, MOLD[, SIZE])}
10835 @item @emph{Arguments}:
10836 @multitable @columnfractions .15 .70
10837 @item @var{SOURCE} @tab Shall be a scalar or an array of any type.
10838 @item @var{MOLD} @tab Shall be a scalar or an array of any type.
10839 @item @var{SIZE} @tab (Optional) shall be a scalar of type
10843 @item @emph{Return value}:
10844 The result has the same type as @var{MOLD}, with the bit level
10845 representation of @var{SOURCE}. If @var{SIZE} is present, the result is
10846 a one-dimensional array of length @var{SIZE}. If @var{SIZE} is absent
10847 but @var{MOLD} is an array (of any size or shape), the result is a one-
10848 dimensional array of the minimum length needed to contain the entirety
10849 of the bitwise representation of @var{SOURCE}. If @var{SIZE} is absent
10850 and @var{MOLD} is a scalar, the result is a scalar.
10852 If the bitwise representation of the result is longer than that of
10853 @var{SOURCE}, then the leading bits of the result correspond to those of
10854 @var{SOURCE} and any trailing bits are filled arbitrarily.
10856 When the resulting bit representation does not correspond to a valid
10857 representation of a variable of the same type as @var{MOLD}, the results
10858 are undefined, and subsequent operations on the result cannot be
10859 guaranteed to produce sensible behavior. For example, it is possible to
10860 create @code{LOGICAL} variables for which @code{@var{VAR}} and
10861 @code{.NOT.@var{VAR}} both appear to be true.
10863 @item @emph{Example}:
10865 PROGRAM test_transfer
10866 integer :: x = 2143289344
10867 print *, transfer(x, 1.0) ! prints "NaN" on i686
10875 @section @code{TRANSPOSE} --- Transpose an array of rank two
10877 @cindex array, transpose
10878 @cindex matrix, transpose
10882 @item @emph{Description}:
10883 Transpose an array of rank two. Element (i, j) of the result has the value
10884 @code{MATRIX(j, i)}, for all i, j.
10886 @item @emph{Standard}:
10887 Fortran 95 and later
10889 @item @emph{Class}:
10890 Transformational function
10892 @item @emph{Syntax}:
10893 @code{RESULT = TRANSPOSE(MATRIX)}
10895 @item @emph{Arguments}:
10896 @multitable @columnfractions .15 .70
10897 @item @var{MATRIX} @tab Shall be an array of any type and have a rank of two.
10900 @item @emph{Return value}:
10901 The result has the same type as @var{MATRIX}, and has shape
10902 @code{(/ m, n /)} if @var{MATRIX} has shape @code{(/ n, m /)}.
10908 @section @code{TRIM} --- Remove trailing blank characters of a string
10910 @cindex string, remove trailing whitespace
10913 @item @emph{Description}:
10914 Removes trailing blank characters of a string.
10916 @item @emph{Standard}:
10917 Fortran 95 and later
10919 @item @emph{Class}:
10920 Transformational function
10922 @item @emph{Syntax}:
10923 @code{RESULT = TRIM(STRING)}
10925 @item @emph{Arguments}:
10926 @multitable @columnfractions .15 .70
10927 @item @var{STRING} @tab Shall be a scalar of type @code{CHARACTER}.
10930 @item @emph{Return value}:
10931 A scalar of type @code{CHARACTER} which length is that of @var{STRING}
10932 less the number of trailing blanks.
10934 @item @emph{Example}:
10937 CHARACTER(len=10), PARAMETER :: s = "GFORTRAN "
10938 WRITE(*,*) LEN(s), LEN(TRIM(s)) ! "10 8", with/without trailing blanks
10942 @item @emph{See also}:
10943 @ref{ADJUSTL}, @ref{ADJUSTR}
10949 @section @code{TTYNAM} --- Get the name of a terminal device.
10951 @cindex system, terminal
10954 @item @emph{Description}:
10955 Get the name of a terminal device. For more information,
10956 see @code{ttyname(3)}.
10958 This intrinsic is provided in both subroutine and function forms;
10959 however, only one form can be used in any given program unit.
10961 @item @emph{Standard}:
10964 @item @emph{Class}:
10965 Subroutine, function
10967 @item @emph{Syntax}:
10968 @multitable @columnfractions .80
10969 @item @code{CALL TTYNAM(UNIT, NAME)}
10970 @item @code{NAME = TTYNAM(UNIT)}
10973 @item @emph{Arguments}:
10974 @multitable @columnfractions .15 .70
10975 @item @var{UNIT} @tab Shall be a scalar @code{INTEGER}.
10976 @item @var{NAME} @tab Shall be of type @code{CHARACTER}.
10979 @item @emph{Example}:
10981 PROGRAM test_ttynam
10984 IF (isatty(unit=unit)) write(*,*) ttynam(unit)
10989 @item @emph{See also}:
10996 @section @code{UBOUND} --- Upper dimension bounds of an array
10998 @cindex array, upper bound
11001 @item @emph{Description}:
11002 Returns the upper bounds of an array, or a single upper bound
11003 along the @var{DIM} dimension.
11004 @item @emph{Standard}:
11005 Fortran 95 and later, with @var{KIND} argument Fortran 2003 and later
11007 @item @emph{Class}:
11010 @item @emph{Syntax}:
11011 @code{RESULT = UBOUND(ARRAY [, DIM [, KIND]])}
11013 @item @emph{Arguments}:
11014 @multitable @columnfractions .15 .70
11015 @item @var{ARRAY} @tab Shall be an array, of any type.
11016 @item @var{DIM} @tab (Optional) Shall be a scalar @code{INTEGER}.
11017 @item @var{KIND}@tab (Optional) An @code{INTEGER} initialization
11018 expression indicating the kind parameter of the result.
11021 @item @emph{Return value}:
11022 The return value is of type @code{INTEGER} and of kind @var{KIND}. If
11023 @var{KIND} is absent, the return value is of default integer kind.
11024 If @var{DIM} is absent, the result is an array of the upper bounds of
11025 @var{ARRAY}. If @var{DIM} is present, the result is a scalar
11026 corresponding to the upper bound of the array along that dimension. If
11027 @var{ARRAY} is an expression rather than a whole array or array
11028 structure component, or if it has a zero extent along the relevant
11029 dimension, the upper bound is taken to be the number of elements along
11030 the relevant dimension.
11032 @item @emph{See also}:
11039 @section @code{UMASK} --- Set the file creation mask
11041 @cindex file system, file creation mask
11044 @item @emph{Description}:
11045 Sets the file creation mask to @var{MASK}. If called as a function, it
11046 returns the old value. If called as a subroutine and argument @var{OLD}
11047 if it is supplied, it is set to the old value. See @code{umask(2)}.
11049 @item @emph{Standard}:
11052 @item @emph{Class}:
11053 Subroutine, function
11055 @item @emph{Syntax}:
11056 @code{CALL UMASK(MASK [, OLD])}
11057 @code{OLD = UMASK(MASK)}
11059 @item @emph{Arguments}:
11060 @multitable @columnfractions .15 .70
11061 @item @var{MASK} @tab Shall be a scalar of type @code{INTEGER}.
11062 @item @var{OLD} @tab (Optional) Shall be a scalar of type
11071 @section @code{UNLINK} --- Remove a file from the file system
11073 @cindex file system, remove file
11076 @item @emph{Description}:
11077 Unlinks the file @var{PATH}. A null character (@code{CHAR(0)}) can be
11078 used to mark the end of the name in @var{PATH}; otherwise, trailing
11079 blanks in the file name are ignored. If the @var{STATUS} argument is
11080 supplied, it contains 0 on success or a nonzero error code upon return;
11081 see @code{unlink(2)}.
11083 This intrinsic is provided in both subroutine and function forms;
11084 however, only one form can be used in any given program unit.
11086 @item @emph{Standard}:
11089 @item @emph{Class}:
11090 Subroutine, function
11092 @item @emph{Syntax}:
11093 @multitable @columnfractions .80
11094 @item @code{CALL UNLINK(PATH [, STATUS])}
11095 @item @code{STATUS = UNLINK(PATH)}
11098 @item @emph{Arguments}:
11099 @multitable @columnfractions .15 .70
11100 @item @var{PATH} @tab Shall be of default @code{CHARACTER} type.
11101 @item @var{STATUS} @tab (Optional) Shall be of default @code{INTEGER} type.
11104 @item @emph{See also}:
11105 @ref{LINK}, @ref{SYMLNK}
11111 @section @code{UNPACK} --- Unpack an array of rank one into an array
11113 @cindex array, unpacking
11114 @cindex array, increase dimension
11115 @cindex array, scatter elements
11118 @item @emph{Description}:
11119 Store the elements of @var{VECTOR} in an array of higher rank.
11121 @item @emph{Standard}:
11122 Fortran 95 and later
11124 @item @emph{Class}:
11125 Transformational function
11127 @item @emph{Syntax}:
11128 @code{RESULT = UNPACK(VECTOR, MASK, FIELD)}
11130 @item @emph{Arguments}:
11131 @multitable @columnfractions .15 .70
11132 @item @var{VECTOR} @tab Shall be an array of any type and rank one. It
11133 shall have at least as many elements as @var{MASK} has @code{TRUE} values.
11134 @item @var{MASK} @tab Shall be an array of type @code{LOGICAL}.
11135 @item @var{FIELD} @tab Shall be of the same type as @var{VECTOR} and have
11136 the same shape as @var{MASK}.
11139 @item @emph{Return value}:
11140 The resulting array corresponds to @var{FIELD} with @code{TRUE} elements
11141 of @var{MASK} replaced by values from @var{VECTOR} in array element order.
11143 @item @emph{Example}:
11145 PROGRAM test_unpack
11146 integer :: vector(2) = (/1,1/)
11147 logical :: mask(4) = (/ .TRUE., .FALSE., .FALSE., .TRUE. /)
11148 integer :: field(2,2) = 0, unity(2,2)
11150 ! result: unity matrix
11151 unity = unpack(vector, reshape(mask, (/2,2/)), field)
11155 @item @emph{See also}:
11156 @ref{PACK}, @ref{SPREAD}
11162 @section @code{VERIFY} --- Scan a string for the absence of a set of characters
11164 @cindex string, find missing set
11167 @item @emph{Description}:
11168 Verifies that all the characters in a @var{SET} are present in a @var{STRING}.
11170 If @var{BACK} is either absent or equals @code{FALSE}, this function
11171 returns the position of the leftmost character of @var{STRING} that is
11172 not in @var{SET}. If @var{BACK} equals @code{TRUE}, the rightmost position
11173 is returned. If all characters of @var{SET} are found in @var{STRING}, the
11176 @item @emph{Standard}:
11177 Fortran 95 and later, with @var{KIND} argument Fortran 2003 and later
11179 @item @emph{Class}:
11182 @item @emph{Syntax}:
11183 @code{RESULT = VERIFY(STRING, SET[, BACK [, KIND]])}
11185 @item @emph{Arguments}:
11186 @multitable @columnfractions .15 .70
11187 @item @var{STRING} @tab Shall be of type @code{CHARACTER}.
11188 @item @var{SET} @tab Shall be of type @code{CHARACTER}.
11189 @item @var{BACK} @tab (Optional) shall be of type @code{LOGICAL}.
11190 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
11191 expression indicating the kind parameter of the result.
11194 @item @emph{Return value}:
11195 The return value is of type @code{INTEGER} and of kind @var{KIND}. If
11196 @var{KIND} is absent, the return value is of default integer kind.
11198 @item @emph{Example}:
11200 PROGRAM test_verify
11201 WRITE(*,*) VERIFY("FORTRAN", "AO") ! 1, found 'F'
11202 WRITE(*,*) VERIFY("FORTRAN", "FOO") ! 3, found 'R'
11203 WRITE(*,*) VERIFY("FORTRAN", "C++") ! 1, found 'F'
11204 WRITE(*,*) VERIFY("FORTRAN", "C++", .TRUE.) ! 7, found 'N'
11205 WRITE(*,*) VERIFY("FORTRAN", "FORTRAN") ! 0' found none
11209 @item @emph{See also}:
11210 @ref{SCAN}, @ref{INDEX intrinsic}
11216 @section @code{XOR} --- Bitwise logical exclusive OR
11218 @cindex bitwise logical exclusive or
11219 @cindex logical exclusive or, bitwise
11222 @item @emph{Description}:
11223 Bitwise logical exclusive or.
11225 This intrinsic routine is provided for backwards compatibility with
11226 GNU Fortran 77. For integer arguments, programmers should consider
11227 the use of the @ref{IEOR} intrinsic and for logical arguments the
11228 @code{.NEQV.} operator, which are both defined by the Fortran standard.
11230 @item @emph{Standard}:
11233 @item @emph{Class}:
11236 @item @emph{Syntax}:
11237 @code{RESULT = XOR(I, J)}
11239 @item @emph{Arguments}:
11240 @multitable @columnfractions .15 .70
11241 @item @var{I} @tab The type shall be either a scalar @code{INTEGER}
11242 type or a scalar @code{LOGICAL} type.
11243 @item @var{J} @tab The type shall be the same as the type of @var{I}.
11246 @item @emph{Return value}:
11247 The return type is either a scalar @code{INTEGER} or a scalar
11248 @code{LOGICAL}. If the kind type parameters differ, then the
11249 smaller kind type is implicitly converted to larger kind, and the
11250 return has the larger kind.
11252 @item @emph{Example}:
11255 LOGICAL :: T = .TRUE., F = .FALSE.
11257 DATA a / Z'F' /, b / Z'3' /
11259 WRITE (*,*) XOR(T, T), XOR(T, F), XOR(F, T), XOR(F, F)
11260 WRITE (*,*) XOR(a, b)
11264 @item @emph{See also}:
11265 Fortran 95 elemental function: @ref{IEOR}
11270 @node Intrinsic Modules
11271 @chapter Intrinsic Modules
11272 @cindex intrinsic Modules
11275 * ISO_FORTRAN_ENV::
11277 * OpenMP Modules OMP_LIB and OMP_LIB_KINDS::
11280 @node ISO_FORTRAN_ENV
11281 @section @code{ISO_FORTRAN_ENV}
11283 @item @emph{Standard}:
11284 Fortran 2003 and later, except when otherwise noted
11287 The @code{ISO_FORTRAN_ENV} module provides the following scalar default-integer
11291 @item @code{ATOMIC_INT_KIND}:
11292 Default-kind integer constant to be used as kind parameter when defining
11293 integer variables used in atomic operations. (Fortran 2008 or later.)
11295 @item @code{ATOMIC_LOGICAL_KIND}:
11296 Default-kind integer constant to be used as kind parameter when defining
11297 logical variables used in atomic operations. (Fortran 2008 or later.)
11299 @item @code{CHARACTER_STORAGE_SIZE}:
11300 Size in bits of the character storage unit.
11302 @item @code{ERROR_UNIT}:
11303 Identifies the preconnected unit used for error reporting.
11305 @item @code{FILE_STORAGE_SIZE}:
11306 Size in bits of the file-storage unit.
11308 @item @code{INPUT_UNIT}:
11309 Identifies the preconnected unit identified by the asterisk
11310 (@code{*}) in @code{READ} statement.
11312 @item @code{INT8}, @code{INT16}, @code{INT32}, @code{INT64}:
11313 Kind type parameters to specify an INTEGER type with a storage
11314 size of 16, 32, and 64 bits. It is negative if a target platform
11315 does not support the particular kind. (Fortran 2008 or later.)
11317 @item @code{IOSTAT_END}:
11318 The value assigned to the variable passed to the IOSTAT= specifier of
11319 an input/output statement if an end-of-file condition occurred.
11321 @item @code{IOSTAT_EOR}:
11322 The value assigned to the variable passed to the IOSTAT= specifier of
11323 an input/output statement if an end-of-record condition occurred.
11325 @item @code{IOSTAT_INQUIRE_INTERNAL_UNIT}:
11326 Scalar default-integer constant, used by @code{INQUIRE} for the
11327 IOSTAT= specifier to denote an that a unit number identifies an
11328 internal unit. (Fortran 2008 or later.)
11330 @item @code{NUMERIC_STORAGE_SIZE}:
11331 The size in bits of the numeric storage unit.
11333 @item @code{OUTPUT_UNIT}:
11334 Identifies the preconnected unit identified by the asterisk
11335 (@code{*}) in @code{WRITE} statement.
11337 @item @code{REAL32}, @code{REAL64}, @code{REAL128}:
11338 Kind type parameters to specify a REAL type with a storage
11339 size of 32, 64, and 128 bits. It is negative if a target platform
11340 does not support the particular kind. (Fortran 2008 or later.)
11342 @item @code{STAT_LOCKED}:
11343 Scalar default-integer constant used as STAT= return value by @code{LOCK} to
11344 denote that the lock variable is locked by the executing image. (Fortran 2008
11347 @item @code{STAT_LOCKED_OTHER_IMAGE}:
11348 Scalar default-integer constant used as STAT= return value by @code{UNLOCK} to
11349 denote that the lock variable is locked by another image. (Fortran 2008 or
11352 @item @code{STAT_STOPPED_IMAGE}:
11353 Positive, scalar default-integer constant used as STAT= return value if the
11354 argument in the statement requires synchronisation with an image, which has
11355 initiated the termination of the execution. (Fortran 2008 or later.)
11357 @item @code{STAT_UNLOCKED}:
11358 Scalar default-integer constant used as STAT= return value by @code{UNLOCK} to
11359 denote that the lock variable is unlocked. (Fortran 2008 or later.)
11364 @node ISO_C_BINDING
11365 @section @code{ISO_C_BINDING}
11367 @item @emph{Standard}:
11368 Fortran 2003 and later, GNU extensions
11371 The following intrinsic procedures are provided by the module; their
11372 definition can be found in the section Intrinsic Procedures of this
11376 @item @code{C_ASSOCIATED}
11377 @item @code{C_F_POINTER}
11378 @item @code{C_F_PROCPOINTER}
11379 @item @code{C_FUNLOC}
11382 @c TODO: Vertical spacing between C_FUNLOC and C_LOC wrong in PDF,
11383 @c don't really know why.
11385 The @code{ISO_C_BINDING} module provides the following named constants of
11386 type default integer, which can be used as KIND type parameters.
11388 In addition to the integer named constants required by the Fortran 2003
11389 standard, GNU Fortran provides as an extension named constants for the
11390 128-bit integer types supported by the C compiler: @code{C_INT128_T,
11391 C_INT_LEAST128_T, C_INT_FAST128_T}.
11393 @multitable @columnfractions .15 .35 .35 .35
11394 @item Fortran Type @tab Named constant @tab C type @tab Extension
11395 @item @code{INTEGER}@tab @code{C_INT} @tab @code{int}
11396 @item @code{INTEGER}@tab @code{C_SHORT} @tab @code{short int}
11397 @item @code{INTEGER}@tab @code{C_LONG} @tab @code{long int}
11398 @item @code{INTEGER}@tab @code{C_LONG_LONG} @tab @code{long long int}
11399 @item @code{INTEGER}@tab @code{C_SIGNED_CHAR} @tab @code{signed char}/@code{unsigned char}
11400 @item @code{INTEGER}@tab @code{C_SIZE_T} @tab @code{size_t}
11401 @item @code{INTEGER}@tab @code{C_INT8_T} @tab @code{int8_t}
11402 @item @code{INTEGER}@tab @code{C_INT16_T} @tab @code{int16_t}
11403 @item @code{INTEGER}@tab @code{C_INT32_T} @tab @code{int32_t}
11404 @item @code{INTEGER}@tab @code{C_INT64_T} @tab @code{int64_t}
11405 @item @code{INTEGER}@tab @code{C_INT128_T} @tab @code{int128_t} @tab Ext.
11406 @item @code{INTEGER}@tab @code{C_INT_LEAST8_T} @tab @code{int_least8_t}
11407 @item @code{INTEGER}@tab @code{C_INT_LEAST16_T} @tab @code{int_least16_t}
11408 @item @code{INTEGER}@tab @code{C_INT_LEAST32_T} @tab @code{int_least32_t}
11409 @item @code{INTEGER}@tab @code{C_INT_LEAST64_T} @tab @code{int_least64_t}
11410 @item @code{INTEGER}@tab @code{C_INT_LEAST128_T}@tab @code{int_least128_t} @tab Ext.
11411 @item @code{INTEGER}@tab @code{C_INT_FAST8_T} @tab @code{int_fast8_t}
11412 @item @code{INTEGER}@tab @code{C_INT_FAST16_T} @tab @code{int_fast16_t}
11413 @item @code{INTEGER}@tab @code{C_INT_FAST32_T} @tab @code{int_fast32_t}
11414 @item @code{INTEGER}@tab @code{C_INT_FAST64_T} @tab @code{int_fast64_t}
11415 @item @code{INTEGER}@tab @code{C_INT_FAST128_T} @tab @code{int_fast128_t} @tab Ext.
11416 @item @code{INTEGER}@tab @code{C_INTMAX_T} @tab @code{intmax_t}
11417 @item @code{INTEGER}@tab @code{C_INTPTR_T} @tab @code{intptr_t}
11418 @item @code{REAL} @tab @code{C_FLOAT} @tab @code{float}
11419 @item @code{REAL} @tab @code{C_DOUBLE} @tab @code{double}
11420 @item @code{REAL} @tab @code{C_LONG_DOUBLE} @tab @code{long double}
11421 @item @code{COMPLEX}@tab @code{C_FLOAT_COMPLEX} @tab @code{float _Complex}
11422 @item @code{COMPLEX}@tab @code{C_DOUBLE_COMPLEX}@tab @code{double _Complex}
11423 @item @code{COMPLEX}@tab @code{C_LONG_DOUBLE_COMPLEX}@tab @code{long double _Complex}
11424 @item @code{LOGICAL}@tab @code{C_BOOL} @tab @code{_Bool}
11425 @item @code{CHARACTER}@tab @code{C_CHAR} @tab @code{char}
11428 Additionally, the following parameters of type @code{CHARACTER(KIND=C_CHAR)}
11431 @multitable @columnfractions .20 .45 .15
11432 @item Name @tab C definition @tab Value
11433 @item @code{C_NULL_CHAR} @tab null character @tab @code{'\0'}
11434 @item @code{C_ALERT} @tab alert @tab @code{'\a'}
11435 @item @code{C_BACKSPACE} @tab backspace @tab @code{'\b'}
11436 @item @code{C_FORM_FEED} @tab form feed @tab @code{'\f'}
11437 @item @code{C_NEW_LINE} @tab new line @tab @code{'\n'}
11438 @item @code{C_CARRIAGE_RETURN} @tab carriage return @tab @code{'\r'}
11439 @item @code{C_HORIZONTAL_TAB} @tab horizontal tab @tab @code{'\t'}
11440 @item @code{C_VERTICAL_TAB} @tab vertical tab @tab @code{'\v'}
11443 @node OpenMP Modules OMP_LIB and OMP_LIB_KINDS
11444 @section OpenMP Modules @code{OMP_LIB} and @code{OMP_LIB_KINDS}
11446 @item @emph{Standard}:
11447 OpenMP Application Program Interface v3.0
11451 The OpenMP Fortran runtime library routines are provided both in
11452 a form of two Fortran 90 modules, named @code{OMP_LIB} and
11453 @code{OMP_LIB_KINDS}, and in a form of a Fortran @code{include} file named
11454 @file{omp_lib.h}. The procedures provided by @code{OMP_LIB} can be found
11455 in the @ref{Top,,Introduction,libgomp,GNU OpenMP runtime library} manual,
11456 the named constants defined in the @code{OMP_LIB_KINDS} module are listed
11459 For details refer to the actual
11460 @uref{http://www.openmp.org/mp-documents/spec30.pdf,
11461 OpenMP Application Program Interface v3.0}.
11463 @code{OMP_LIB_KINDS} provides the following scalar default-integer
11467 @item @code{omp_integer_kind}
11468 @item @code{omp_logical_kind}
11469 @item @code{omp_lock_kind}
11470 @item @code{omp_nest_lock_kind}
11471 @item @code{omp_sched_kind}