2 Copyright (C) 2005, 2006, 2007, 2008, 2009
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{OR}: OR, Bitwise logical OR
208 * @code{PACK}: PACK, Pack an array into an array of rank one
209 * @code{PERROR}: PERROR, Print system error message
210 * @code{PRECISION}: PRECISION, Decimal precision of a real kind
211 * @code{PRESENT}: PRESENT, Determine whether an optional dummy argument is specified
212 * @code{PRODUCT}: PRODUCT, Product of array elements
213 * @code{RADIX}: RADIX, Base of a data model
214 * @code{RANDOM_NUMBER}: RANDOM_NUMBER, Pseudo-random number
215 * @code{RANDOM_SEED}: RANDOM_SEED, Initialize a pseudo-random number sequence
216 * @code{RAND}: RAND, Real pseudo-random number
217 * @code{RANGE}: RANGE, Decimal exponent range
218 * @code{RAN}: RAN, Real pseudo-random number
219 * @code{REAL}: REAL, Convert to real type
220 * @code{RENAME}: RENAME, Rename a file
221 * @code{REPEAT}: REPEAT, Repeated string concatenation
222 * @code{RESHAPE}: RESHAPE, Function to reshape an array
223 * @code{RRSPACING}: RRSPACING, Reciprocal of the relative spacing
224 * @code{RSHIFT}: RSHIFT, Right shift bits
225 * @code{SCALE}: SCALE, Scale a real value
226 * @code{SCAN}: SCAN, Scan a string for the presence of a set of characters
227 * @code{SECNDS}: SECNDS, Time function
228 * @code{SECOND}: SECOND, CPU time function
229 * @code{SELECTED_CHAR_KIND}: SELECTED_CHAR_KIND, Choose character kind
230 * @code{SELECTED_INT_KIND}: SELECTED_INT_KIND, Choose integer kind
231 * @code{SELECTED_REAL_KIND}: SELECTED_REAL_KIND, Choose real kind
232 * @code{SET_EXPONENT}: SET_EXPONENT, Set the exponent of the model
233 * @code{SHAPE}: SHAPE, Determine the shape of an array
234 * @code{SIGN}: SIGN, Sign copying function
235 * @code{SIGNAL}: SIGNAL, Signal handling subroutine (or function)
236 * @code{SIN}: SIN, Sine function
237 * @code{SINH}: SINH, Hyperbolic sine function
238 * @code{SIZE}: SIZE, Function to determine the size of an array
239 * @code{SIZEOF}: SIZEOF, Determine the size in bytes of an expression
240 * @code{SLEEP}: SLEEP, Sleep for the specified number of seconds
241 * @code{SNGL}: SNGL, Convert double precision real to default real
242 * @code{SPACING}: SPACING, Smallest distance between two numbers of a given type
243 * @code{SPREAD}: SPREAD, Add a dimension to an array
244 * @code{SQRT}: SQRT, Square-root function
245 * @code{SRAND}: SRAND, Reinitialize the random number generator
246 * @code{STAT}: STAT, Get file status
247 * @code{SUM}: SUM, Sum of array elements
248 * @code{SYMLNK}: SYMLNK, Create a symbolic link
249 * @code{SYSTEM}: SYSTEM, Execute a shell command
250 * @code{SYSTEM_CLOCK}: SYSTEM_CLOCK, Time function
251 * @code{TAN}: TAN, Tangent function
252 * @code{TANH}: TANH, Hyperbolic tangent function
253 * @code{TIME}: TIME, Time function
254 * @code{TIME8}: TIME8, Time function (64-bit)
255 * @code{TINY}: TINY, Smallest positive number of a real kind
256 * @code{TRAILZ}: TRAILZ, Number of trailing zero bits of an integer
257 * @code{TRANSFER}: TRANSFER, Transfer bit patterns
258 * @code{TRANSPOSE}: TRANSPOSE, Transpose an array of rank two
259 * @code{TRIM}: TRIM, Remove trailing blank characters of a string
260 * @code{TTYNAM}: TTYNAM, Get the name of a terminal device.
261 * @code{UBOUND}: UBOUND, Upper dimension bounds of an array
262 * @code{UMASK}: UMASK, Set the file creation mask
263 * @code{UNLINK}: UNLINK, Remove a file from the file system
264 * @code{UNPACK}: UNPACK, Unpack an array of rank one into an array
265 * @code{VERIFY}: VERIFY, Scan a string for the absence of a set of characters
266 * @code{XOR}: XOR, Bitwise logical exclusive or
269 @node Introduction to Intrinsics
270 @section Introduction to intrinsic procedures
272 The intrinsic procedures provided by GNU Fortran include all of the
273 intrinsic procedures required by the Fortran 95 standard, a set of
274 intrinsic procedures for backwards compatibility with G77, and a
275 selection of intrinsic procedures from the Fortran 2003 and Fortran 2008
276 standards. Any conflict between a description here and a description in
277 either the Fortran 95 standard, the Fortran 2003 standard or the Fortran
278 2008 standard is unintentional, and the standard(s) should be considered
281 The enumeration of the @code{KIND} type parameter is processor defined in
282 the Fortran 95 standard. GNU Fortran defines the default integer type and
283 default real type by @code{INTEGER(KIND=4)} and @code{REAL(KIND=4)},
284 respectively. The standard mandates that both data types shall have
285 another kind, which have more precision. On typical target architectures
286 supported by @command{gfortran}, this kind type parameter is @code{KIND=8}.
287 Hence, @code{REAL(KIND=8)} and @code{DOUBLE PRECISION} are equivalent.
288 In the description of generic intrinsic procedures, the kind type parameter
289 will be specified by @code{KIND=*}, and in the description of specific
290 names for an intrinsic procedure the kind type parameter will be explicitly
291 given (e.g., @code{REAL(KIND=4)} or @code{REAL(KIND=8)}). Finally, for
292 brevity the optional @code{KIND=} syntax will be omitted.
294 Many of the intrinsic procedures take one or more optional arguments.
295 This document follows the convention used in the Fortran 95 standard,
296 and denotes such arguments by square brackets.
298 GNU Fortran offers the @option{-std=f95} and @option{-std=gnu} options,
299 which can be used to restrict the set of intrinsic procedures to a
300 given standard. By default, @command{gfortran} sets the @option{-std=gnu}
301 option, and so all intrinsic procedures described here are accepted. There
302 is one caveat. For a select group of intrinsic procedures, @command{g77}
303 implemented both a function and a subroutine. Both classes
304 have been implemented in @command{gfortran} for backwards compatibility
305 with @command{g77}. It is noted here that these functions and subroutines
306 cannot be intermixed in a given subprogram. In the descriptions that follow,
307 the applicable standard for each intrinsic procedure is noted.
312 @section @code{ABORT} --- Abort the program
314 @cindex program termination, with core dump
315 @cindex terminate program, with core dump
319 @item @emph{Description}:
320 @code{ABORT} causes immediate termination of the program. On operating
321 systems that support a core dump, @code{ABORT} will produce a core dump even if
322 the option @option{-fno-dump-core} is in effect, which is suitable for debugging
324 @c TODO: Check if this (with -fno-dump-core) is correct.
326 @item @emph{Standard}:
335 @item @emph{Return value}:
338 @item @emph{Example}:
341 integer :: i = 1, j = 2
342 if (i /= j) call abort
343 end program test_abort
346 @item @emph{See also}:
347 @ref{EXIT}, @ref{KILL}
354 @section @code{ABS} --- Absolute value
361 @cindex absolute value
364 @item @emph{Description}:
365 @code{ABS(A)} computes the absolute value of @code{A}.
367 @item @emph{Standard}:
368 Fortran 77 and later, has overloads that are GNU extensions
374 @code{RESULT = ABS(A)}
376 @item @emph{Arguments}:
377 @multitable @columnfractions .15 .70
378 @item @var{A} @tab The type of the argument shall be an @code{INTEGER},
379 @code{REAL}, or @code{COMPLEX}.
382 @item @emph{Return value}:
383 The return value is of the same type and
384 kind as the argument except the return value is @code{REAL} for a
385 @code{COMPLEX} argument.
387 @item @emph{Example}:
392 complex :: z = (-1.e0,0.e0)
399 @item @emph{Specific names}:
400 @multitable @columnfractions .20 .20 .20 .25
401 @item Name @tab Argument @tab Return type @tab Standard
402 @item @code{CABS(A)} @tab @code{COMPLEX(4) Z} @tab @code{REAL(4)} @tab Fortran 77 and later
403 @item @code{DABS(A)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab Fortran 77 and later
404 @item @code{IABS(A)} @tab @code{INTEGER(4) I} @tab @code{INTEGER(4)} @tab Fortran 77 and later
405 @item @code{ZABS(A)} @tab @code{COMPLEX(8) Z} @tab @code{COMPLEX(8)} @tab GNU extension
406 @item @code{CDABS(A)} @tab @code{COMPLEX(8) Z} @tab @code{COMPLEX(8)} @tab GNU extension
413 @section @code{ACCESS} --- Checks file access modes
415 @cindex file system, access mode
418 @item @emph{Description}:
419 @code{ACCESS(NAME, MODE)} checks whether the file @var{NAME}
420 exists, is readable, writable or executable. Except for the
421 executable check, @code{ACCESS} can be replaced by
422 Fortran 95's @code{INQUIRE}.
424 @item @emph{Standard}:
431 @code{RESULT = ACCESS(NAME, MODE)}
433 @item @emph{Arguments}:
434 @multitable @columnfractions .15 .70
435 @item @var{NAME} @tab Scalar @code{CHARACTER} of default kind with the
436 file name. Tailing blank are ignored unless the character @code{achar(0)}
437 is present, then all characters up to and excluding @code{achar(0)} are
439 @item @var{MODE} @tab Scalar @code{CHARACTER} of default kind with the
440 file access mode, may be any concatenation of @code{"r"} (readable),
441 @code{"w"} (writable) and @code{"x"} (executable), or @code{" "} to check
445 @item @emph{Return value}:
446 Returns a scalar @code{INTEGER}, which is @code{0} if the file is
447 accessible in the given mode; otherwise or if an invalid argument
448 has been given for @code{MODE} the value @code{1} is returned.
450 @item @emph{Example}:
454 character(len=*), parameter :: file = 'test.dat'
455 character(len=*), parameter :: file2 = 'test.dat '//achar(0)
456 if(access(file,' ') == 0) print *, trim(file),' is exists'
457 if(access(file,'r') == 0) print *, trim(file),' is readable'
458 if(access(file,'w') == 0) print *, trim(file),' is writable'
459 if(access(file,'x') == 0) print *, trim(file),' is executable'
460 if(access(file2,'rwx') == 0) &
461 print *, trim(file2),' is readable, writable and executable'
462 end program access_test
464 @item @emph{Specific names}:
465 @item @emph{See also}:
472 @section @code{ACHAR} --- Character in @acronym{ASCII} collating sequence
474 @cindex @acronym{ASCII} collating sequence
475 @cindex collating sequence, @acronym{ASCII}
478 @item @emph{Description}:
479 @code{ACHAR(I)} returns the character located at position @code{I}
480 in the @acronym{ASCII} collating sequence.
482 @item @emph{Standard}:
483 Fortran 77 and later, with @var{KIND} argument Fortran 2003 and later
489 @code{RESULT = ACHAR(I [, KIND])}
491 @item @emph{Arguments}:
492 @multitable @columnfractions .15 .70
493 @item @var{I} @tab The type shall be @code{INTEGER}.
494 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
495 expression indicating the kind parameter of the result.
498 @item @emph{Return value}:
499 The return value is of type @code{CHARACTER} with a length of one.
500 If the @var{KIND} argument is present, the return value is of the
501 specified kind and of the default kind otherwise.
503 @item @emph{Example}:
508 end program test_achar
512 See @ref{ICHAR} for a discussion of converting between numerical values
513 and formatted string representations.
515 @item @emph{See also}:
516 @ref{CHAR}, @ref{IACHAR}, @ref{ICHAR}
523 @section @code{ACOS} --- Arccosine function
526 @cindex trigonometric function, cosine, inverse
527 @cindex cosine, inverse
530 @item @emph{Description}:
531 @code{ACOS(X)} computes the arccosine of @var{X} (inverse of @code{COS(X)}).
533 @item @emph{Standard}:
534 Fortran 77 and later, for a complex argument Fortran 2008 or later
540 @code{RESULT = ACOS(X)}
542 @item @emph{Arguments}:
543 @multitable @columnfractions .15 .70
544 @item @var{X} @tab The type shall either be @code{REAL} with a magnitude that is
545 less than or equal to one - or the type shall be @code{COMPLEX}.
548 @item @emph{Return value}:
549 The return value is of the same type and kind as @var{X}.
550 The real part of the result is in radians and lies in the range
551 @math{0 \leq \Re \acos(x) \leq \pi}.
553 @item @emph{Example}:
556 real(8) :: x = 0.866_8
558 end program test_acos
561 @item @emph{Specific names}:
562 @multitable @columnfractions .20 .20 .20 .25
563 @item Name @tab Argument @tab Return type @tab Standard
564 @item @code{DACOS(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab Fortran 77 and later
567 @item @emph{See also}:
568 Inverse function: @ref{COS}
575 @section @code{ACOSH} --- Hyperbolic arccosine function
578 @cindex area hyperbolic cosine
579 @cindex hyperbolic arccosine
580 @cindex hyperbolic function, cosine, inverse
581 @cindex cosine, hyperbolic, inverse
584 @item @emph{Description}:
585 @code{ACOSH(X)} computes the hyperbolic arccosine of @var{X} (inverse of
588 @item @emph{Standard}:
589 Fortran 2008 and later
595 @code{RESULT = ACOSH(X)}
597 @item @emph{Arguments}:
598 @multitable @columnfractions .15 .70
599 @item @var{X} @tab The type shall be @code{REAL} or @code{COMPLEX}.
602 @item @emph{Return value}:
603 The return value has the same type and kind as @var{X}. If @var{X} is
604 complex, the imaginary part of the result is in radians and lies between
605 @math{ 0 \leq \Im \acosh(x) \leq \pi}.
607 @item @emph{Example}:
610 REAL(8), DIMENSION(3) :: x = (/ 1.0, 2.0, 3.0 /)
615 @item @emph{Specific names}:
616 @multitable @columnfractions .20 .20 .20 .25
617 @item Name @tab Argument @tab Return type @tab Standard
618 @item @code{DACOSH(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU extension
621 @item @emph{See also}:
622 Inverse function: @ref{COSH}
628 @section @code{ADJUSTL} --- Left adjust a string
630 @cindex string, adjust left
631 @cindex adjust string
634 @item @emph{Description}:
635 @code{ADJUSTL(STRING)} will left adjust a string by removing leading spaces.
636 Spaces are inserted at the end of the string as needed.
638 @item @emph{Standard}:
645 @code{RESULT = ADJUSTL(STRING)}
647 @item @emph{Arguments}:
648 @multitable @columnfractions .15 .70
649 @item @var{STRING} @tab The type shall be @code{CHARACTER}.
652 @item @emph{Return value}:
653 The return value is of type @code{CHARACTER} and of the same kind as
654 @var{STRING} where leading spaces are removed and the same number of
655 spaces are inserted on the end of @var{STRING}.
657 @item @emph{Example}:
660 character(len=20) :: str = ' gfortran'
663 end program test_adjustl
666 @item @emph{See also}:
667 @ref{ADJUSTR}, @ref{TRIM}
673 @section @code{ADJUSTR} --- Right adjust a string
675 @cindex string, adjust right
676 @cindex adjust string
679 @item @emph{Description}:
680 @code{ADJUSTR(STRING)} will right adjust a string by removing trailing spaces.
681 Spaces are inserted at the start of the string as needed.
683 @item @emph{Standard}:
690 @code{RESULT = ADJUSTR(STRING)}
692 @item @emph{Arguments}:
693 @multitable @columnfractions .15 .70
694 @item @var{STR} @tab The type shall be @code{CHARACTER}.
697 @item @emph{Return value}:
698 The return value is of type @code{CHARACTER} and of the same kind as
699 @var{STRING} where trailing spaces are removed and the same number of
700 spaces are inserted at the start of @var{STRING}.
702 @item @emph{Example}:
705 character(len=20) :: str = 'gfortran'
708 end program test_adjustr
711 @item @emph{See also}:
712 @ref{ADJUSTL}, @ref{TRIM}
718 @section @code{AIMAG} --- Imaginary part of complex number
723 @cindex complex numbers, imaginary part
726 @item @emph{Description}:
727 @code{AIMAG(Z)} yields the imaginary part of complex argument @code{Z}.
728 The @code{IMAG(Z)} and @code{IMAGPART(Z)} intrinsic functions are provided
729 for compatibility with @command{g77}, and their use in new code is
730 strongly discouraged.
732 @item @emph{Standard}:
733 Fortran 77 and later, has overloads that are GNU extensions
739 @code{RESULT = AIMAG(Z)}
741 @item @emph{Arguments}:
742 @multitable @columnfractions .15 .70
743 @item @var{Z} @tab The type of the argument shall be @code{COMPLEX}.
746 @item @emph{Return value}:
747 The return value is of type @code{REAL} with the
748 kind type parameter of the argument.
750 @item @emph{Example}:
755 z4 = cmplx(1.e0_4, 0.e0_4)
756 z8 = cmplx(0.e0_8, 1.e0_8)
757 print *, aimag(z4), dimag(z8)
758 end program test_aimag
761 @item @emph{Specific names}:
762 @multitable @columnfractions .20 .20 .20 .25
763 @item Name @tab Argument @tab Return type @tab Standard
764 @item @code{DIMAG(Z)} @tab @code{COMPLEX(8) Z} @tab @code{REAL(8)} @tab GNU extension
765 @item @code{IMAG(Z)} @tab @code{COMPLEX Z} @tab @code{REAL} @tab GNU extension
766 @item @code{IMAGPART(Z)} @tab @code{COMPLEX Z} @tab @code{REAL} @tab GNU extension
773 @section @code{AINT} --- Truncate to a whole number
777 @cindex rounding, floor
780 @item @emph{Description}:
781 @code{AINT(A [, KIND])} truncates its argument to a whole number.
783 @item @emph{Standard}:
790 @code{RESULT = AINT(A [, KIND])}
792 @item @emph{Arguments}:
793 @multitable @columnfractions .15 .70
794 @item @var{A} @tab The type of the argument shall be @code{REAL}.
795 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
796 expression indicating the kind parameter of the result.
799 @item @emph{Return value}:
800 The return value is of type @code{REAL} with the kind type parameter of the
801 argument if the optional @var{KIND} is absent; otherwise, the kind
802 type parameter will be given by @var{KIND}. If the magnitude of
803 @var{X} is less than one, @code{AINT(X)} returns zero. If the
804 magnitude is equal to or greater than one then it returns the largest
805 whole number that does not exceed its magnitude. The sign is the same
806 as the sign of @var{X}.
808 @item @emph{Example}:
815 print *, aint(x4), dint(x8)
817 end program test_aint
820 @item @emph{Specific names}:
821 @multitable @columnfractions .20 .20 .20 .25
822 @item Name @tab Argument @tab Return type @tab Standard
823 @item @code{DINT(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab Fortran 77 and later
830 @section @code{ALARM} --- Execute a routine after a given delay
832 @cindex delayed execution
835 @item @emph{Description}:
836 @code{ALARM(SECONDS, HANDLER [, STATUS])} causes external subroutine @var{HANDLER}
837 to be executed after a delay of @var{SECONDS} by using @code{alarm(2)} to
838 set up a signal and @code{signal(2)} to catch it. If @var{STATUS} is
839 supplied, it will be returned with the number of seconds remaining until
840 any previously scheduled alarm was due to be delivered, or zero if there
841 was no previously scheduled alarm.
843 @item @emph{Standard}:
850 @code{CALL ALARM(SECONDS, HANDLER [, STATUS])}
852 @item @emph{Arguments}:
853 @multitable @columnfractions .15 .70
854 @item @var{SECONDS} @tab The type of the argument shall be a scalar
855 @code{INTEGER}. It is @code{INTENT(IN)}.
856 @item @var{HANDLER} @tab Signal handler (@code{INTEGER FUNCTION} or
857 @code{SUBROUTINE}) or dummy/global @code{INTEGER} scalar. The scalar
858 values may be either @code{SIG_IGN=1} to ignore the alarm generated
859 or @code{SIG_DFL=0} to set the default action. It is @code{INTENT(IN)}.
860 @item @var{STATUS} @tab (Optional) @var{STATUS} shall be a scalar
861 variable of the default @code{INTEGER} kind. It is @code{INTENT(OUT)}.
864 @item @emph{Example}:
867 external handler_print
869 call alarm (3, handler_print, i)
872 end program test_alarm
874 This will cause the external routine @var{handler_print} to be called
881 @section @code{ALL} --- All values in @var{MASK} along @var{DIM} are true
883 @cindex array, apply condition
884 @cindex array, condition testing
887 @item @emph{Description}:
888 @code{ALL(MASK [, DIM])} determines if all the values are true in @var{MASK}
889 in the array along dimension @var{DIM}.
891 @item @emph{Standard}:
895 Transformational function
898 @code{RESULT = ALL(MASK [, DIM])}
900 @item @emph{Arguments}:
901 @multitable @columnfractions .15 .70
902 @item @var{MASK} @tab The type of the argument shall be @code{LOGICAL} and
903 it shall not be scalar.
904 @item @var{DIM} @tab (Optional) @var{DIM} shall be a scalar integer
905 with a value that lies between one and the rank of @var{MASK}.
908 @item @emph{Return value}:
909 @code{ALL(MASK)} returns a scalar value of type @code{LOGICAL} where
910 the kind type parameter is the same as the kind type parameter of
911 @var{MASK}. If @var{DIM} is present, then @code{ALL(MASK, DIM)} returns
912 an array with the rank of @var{MASK} minus 1. The shape is determined from
913 the shape of @var{MASK} where the @var{DIM} dimension is elided.
917 @code{ALL(MASK)} is true if all elements of @var{MASK} are true.
918 It also is true if @var{MASK} has zero size; otherwise, it is false.
920 If the rank of @var{MASK} is one, then @code{ALL(MASK,DIM)} is equivalent
921 to @code{ALL(MASK)}. If the rank is greater than one, then @code{ALL(MASK,DIM)}
922 is determined by applying @code{ALL} to the array sections.
925 @item @emph{Example}:
929 l = all((/.true., .true., .true./))
934 integer a(2,3), b(2,3)
938 print *, all(a .eq. b, 1)
939 print *, all(a .eq. b, 2)
940 end subroutine section
948 @section @code{ALLOCATED} --- Status of an allocatable entity
950 @cindex allocation, status
953 @item @emph{Description}:
954 @code{ALLOCATED(ARRAY)} checks the status of whether @var{X} is allocated.
956 @item @emph{Standard}:
963 @code{RESULT = ALLOCATED(ARRAY)}
965 @item @emph{Arguments}:
966 @multitable @columnfractions .15 .70
967 @item @var{ARRAY} @tab The argument shall be an @code{ALLOCATABLE} array.
970 @item @emph{Return value}:
971 The return value is a scalar @code{LOGICAL} with the default logical
972 kind type parameter. If @var{ARRAY} is allocated, @code{ALLOCATED(ARRAY)}
973 is @code{.TRUE.}; otherwise, it returns @code{.FALSE.}
975 @item @emph{Example}:
977 program test_allocated
979 real(4), allocatable :: x(:)
980 if (.not. allocated(x)) allocate(x(i))
981 end program test_allocated
988 @section @code{AND} --- Bitwise logical AND
990 @cindex bitwise logical and
991 @cindex logical and, bitwise
994 @item @emph{Description}:
995 Bitwise logical @code{AND}.
997 This intrinsic routine is provided for backwards compatibility with
998 GNU Fortran 77. For integer arguments, programmers should consider
999 the use of the @ref{IAND} intrinsic defined by the Fortran standard.
1001 @item @emph{Standard}:
1007 @item @emph{Syntax}:
1008 @code{RESULT = AND(I, J)}
1010 @item @emph{Arguments}:
1011 @multitable @columnfractions .15 .70
1012 @item @var{I} @tab The type shall be either a scalar @code{INTEGER}
1013 type or a scalar @code{LOGICAL} type.
1014 @item @var{J} @tab The type shall be the same as the type of @var{I}.
1017 @item @emph{Return value}:
1018 The return type is either a scalar @code{INTEGER} or a scalar
1019 @code{LOGICAL}. If the kind type parameters differ, then the
1020 smaller kind type is implicitly converted to larger kind, and the
1021 return has the larger kind.
1023 @item @emph{Example}:
1026 LOGICAL :: T = .TRUE., F = .FALSE.
1028 DATA a / Z'F' /, b / Z'3' /
1030 WRITE (*,*) AND(T, T), AND(T, F), AND(F, T), AND(F, F)
1031 WRITE (*,*) AND(a, b)
1035 @item @emph{See also}:
1036 Fortran 95 elemental function: @ref{IAND}
1042 @section @code{ANINT} --- Nearest whole number
1046 @cindex rounding, ceiling
1049 @item @emph{Description}:
1050 @code{ANINT(A [, KIND])} rounds its argument to the nearest whole number.
1052 @item @emph{Standard}:
1053 Fortran 77 and later
1058 @item @emph{Syntax}:
1059 @code{RESULT = ANINT(A [, KIND])}
1061 @item @emph{Arguments}:
1062 @multitable @columnfractions .15 .70
1063 @item @var{A} @tab The type of the argument shall be @code{REAL}.
1064 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
1065 expression indicating the kind parameter of the result.
1068 @item @emph{Return value}:
1069 The return value is of type real with the kind type parameter of the
1070 argument if the optional @var{KIND} is absent; otherwise, the kind
1071 type parameter will be given by @var{KIND}. If @var{A} is greater than
1072 zero, @code{ANINT(A)} returns @code{AINT(X+0.5)}. If @var{A} is
1073 less than or equal to zero then it returns @code{AINT(X-0.5)}.
1075 @item @emph{Example}:
1082 print *, anint(x4), dnint(x8)
1084 end program test_anint
1087 @item @emph{Specific names}:
1088 @multitable @columnfractions .20 .20 .20 .25
1089 @item Name @tab Argument @tab Return type @tab Standard
1090 @item @code{DNINT(A)} @tab @code{REAL(8) A} @tab @code{REAL(8)} @tab Fortran 77 and later
1097 @section @code{ANY} --- Any value in @var{MASK} along @var{DIM} is true
1099 @cindex array, apply condition
1100 @cindex array, condition testing
1103 @item @emph{Description}:
1104 @code{ANY(MASK [, DIM])} determines if any of the values in the logical array
1105 @var{MASK} along dimension @var{DIM} are @code{.TRUE.}.
1107 @item @emph{Standard}:
1108 Fortran 95 and later
1111 Transformational function
1113 @item @emph{Syntax}:
1114 @code{RESULT = ANY(MASK [, DIM])}
1116 @item @emph{Arguments}:
1117 @multitable @columnfractions .15 .70
1118 @item @var{MASK} @tab The type of the argument shall be @code{LOGICAL} and
1119 it shall not be scalar.
1120 @item @var{DIM} @tab (Optional) @var{DIM} shall be a scalar integer
1121 with a value that lies between one and the rank of @var{MASK}.
1124 @item @emph{Return value}:
1125 @code{ANY(MASK)} returns a scalar value of type @code{LOGICAL} where
1126 the kind type parameter is the same as the kind type parameter of
1127 @var{MASK}. If @var{DIM} is present, then @code{ANY(MASK, DIM)} returns
1128 an array with the rank of @var{MASK} minus 1. The shape is determined from
1129 the shape of @var{MASK} where the @var{DIM} dimension is elided.
1133 @code{ANY(MASK)} is true if any element of @var{MASK} is true;
1134 otherwise, it is false. It also is false if @var{MASK} has zero size.
1136 If the rank of @var{MASK} is one, then @code{ANY(MASK,DIM)} is equivalent
1137 to @code{ANY(MASK)}. If the rank is greater than one, then @code{ANY(MASK,DIM)}
1138 is determined by applying @code{ANY} to the array sections.
1141 @item @emph{Example}:
1145 l = any((/.true., .true., .true./))
1150 integer a(2,3), b(2,3)
1154 print *, any(a .eq. b, 1)
1155 print *, any(a .eq. b, 2)
1156 end subroutine section
1157 end program test_any
1164 @section @code{ASIN} --- Arcsine function
1167 @cindex trigonometric function, sine, inverse
1168 @cindex sine, inverse
1171 @item @emph{Description}:
1172 @code{ASIN(X)} computes the arcsine of its @var{X} (inverse of @code{SIN(X)}).
1174 @item @emph{Standard}:
1175 Fortran 77 and later, for a complex argument Fortran 2008 or later
1180 @item @emph{Syntax}:
1181 @code{RESULT = ASIN(X)}
1183 @item @emph{Arguments}:
1184 @multitable @columnfractions .15 .70
1185 @item @var{X} @tab The type shall be either @code{REAL} and a magnitude that is
1186 less than or equal to one - or be @code{COMPLEX}.
1189 @item @emph{Return value}:
1190 The return value is of the same type and kind as @var{X}.
1191 The real part of the result is in radians and lies in the range
1192 @math{-\pi/2 \leq \Re \asin(x) \leq \pi/2}.
1194 @item @emph{Example}:
1197 real(8) :: x = 0.866_8
1199 end program test_asin
1202 @item @emph{Specific names}:
1203 @multitable @columnfractions .20 .20 .20 .25
1204 @item Name @tab Argument @tab Return type @tab Standard
1205 @item @code{DASIN(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab Fortran 77 and later
1208 @item @emph{See also}:
1209 Inverse function: @ref{SIN}
1216 @section @code{ASINH} --- Hyperbolic arcsine function
1219 @cindex area hyperbolic sine
1220 @cindex hyperbolic arcsine
1221 @cindex hyperbolic function, sine, inverse
1222 @cindex sine, hyperbolic, inverse
1225 @item @emph{Description}:
1226 @code{ASINH(X)} computes the hyperbolic arcsine of @var{X} (inverse of @code{SINH(X)}).
1228 @item @emph{Standard}:
1229 Fortran 2008 and later
1234 @item @emph{Syntax}:
1235 @code{RESULT = ASINH(X)}
1237 @item @emph{Arguments}:
1238 @multitable @columnfractions .15 .70
1239 @item @var{X} @tab The type shall be @code{REAL} or @code{COMPLEX}.
1242 @item @emph{Return value}:
1243 The return value is of the same type and kind as @var{X}. If @var{X} is
1244 complex, the imaginary part of the result is in radians and lies between
1245 @math{-\pi/2 \leq \Im \asinh(x) \leq \pi/2}.
1247 @item @emph{Example}:
1250 REAL(8), DIMENSION(3) :: x = (/ -1.0, 0.0, 1.0 /)
1251 WRITE (*,*) ASINH(x)
1255 @item @emph{Specific names}:
1256 @multitable @columnfractions .20 .20 .20 .25
1257 @item Name @tab Argument @tab Return type @tab Standard
1258 @item @code{DASINH(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU extension.
1261 @item @emph{See also}:
1262 Inverse function: @ref{SINH}
1268 @section @code{ASSOCIATED} --- Status of a pointer or pointer/target pair
1270 @cindex pointer, status
1271 @cindex association status
1274 @item @emph{Description}:
1275 @code{ASSOCIATED(POINTER [, TARGET])} determines the status of the pointer
1276 @var{POINTER} or if @var{POINTER} is associated with the target @var{TARGET}.
1278 @item @emph{Standard}:
1279 Fortran 95 and later
1284 @item @emph{Syntax}:
1285 @code{RESULT = ASSOCIATED(POINTER [, TARGET])}
1287 @item @emph{Arguments}:
1288 @multitable @columnfractions .15 .70
1289 @item @var{POINTER} @tab @var{POINTER} shall have the @code{POINTER} attribute
1290 and it can be of any type.
1291 @item @var{TARGET} @tab (Optional) @var{TARGET} shall be a pointer or
1292 a target. It must have the same type, kind type parameter, and
1293 array rank as @var{POINTER}.
1295 The association status of neither @var{POINTER} nor @var{TARGET} shall be
1298 @item @emph{Return value}:
1299 @code{ASSOCIATED(POINTER)} returns a scalar value of type @code{LOGICAL(4)}.
1300 There are several cases:
1302 @item (A) When the optional @var{TARGET} is not present then
1303 @code{ASSOCIATED(POINTER)} is true if @var{POINTER} is associated with a target; otherwise, it returns false.
1304 @item (B) If @var{TARGET} is present and a scalar target, the result is true if
1305 @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
1306 disassociated, the result is false.
1307 @item (C) If @var{TARGET} is present and an array target, the result is true if
1308 @var{TARGET} and @var{POINTER} have the same shape, are not zero-sized arrays,
1309 are arrays whose elements are not zero-sized storage sequences, and
1310 @var{TARGET} and @var{POINTER} occupy the same storage units in array element
1312 As in case(B), the result is false, if @var{POINTER} is disassociated.
1313 @item (D) If @var{TARGET} is present and an scalar pointer, the result is true
1314 if @var{TARGET} is associated with @var{POINTER}, the target associated with
1315 @var{TARGET} are not zero-sized storage sequences and occupy the same storage
1317 The result is false, if either @var{TARGET} or @var{POINTER} is disassociated.
1318 @item (E) If @var{TARGET} is present and an array pointer, the result is true if
1319 target associated with @var{POINTER} and the target associated with @var{TARGET}
1320 have the same shape, are not zero-sized arrays, are arrays whose elements are
1321 not zero-sized storage sequences, and @var{TARGET} and @var{POINTER} occupy
1322 the same storage units in array element order.
1323 The result is false, if either @var{TARGET} or @var{POINTER} is disassociated.
1326 @item @emph{Example}:
1328 program test_associated
1330 real, target :: tgt(2) = (/1., 2./)
1331 real, pointer :: ptr(:)
1333 if (associated(ptr) .eqv. .false.) call abort
1334 if (associated(ptr,tgt) .eqv. .false.) call abort
1335 end program test_associated
1338 @item @emph{See also}:
1345 @section @code{ATAN} --- Arctangent function
1348 @cindex trigonometric function, tangent, inverse
1349 @cindex tangent, inverse
1352 @item @emph{Description}:
1353 @code{ATAN(X)} computes the arctangent of @var{X}.
1355 @item @emph{Standard}:
1356 Fortran 77 and later, for a complex argument and for two arguments
1357 Fortran 2008 or later
1362 @item @emph{Syntax}:
1363 @code{RESULT = ATAN(X)}
1364 @code{RESULT = ATAN(Y, X)}
1366 @item @emph{Arguments}:
1367 @multitable @columnfractions .15 .70
1368 @item @var{X} @tab The type shall be @code{REAL} or @code{COMPLEX};
1369 if @var{Y} is present, @var{X} shall be REAL.
1370 @item @var{Y} shall be of the same type and kind as @var{X}.
1373 @item @emph{Return value}:
1374 The return value is of the same type and kind as @var{X}.
1375 If @var{Y} is present, the result is identical to @code{ATAN2(Y,X)}.
1376 Otherwise, it the arcus tangent of @var{X}, where the real part of
1377 the result is in radians and lies in the range
1378 @math{-\pi/2 \leq \Re \atan(x) \leq \pi/2}.
1380 @item @emph{Example}:
1383 real(8) :: x = 2.866_8
1385 end program test_atan
1388 @item @emph{Specific names}:
1389 @multitable @columnfractions .20 .20 .20 .25
1390 @item Name @tab Argument @tab Return type @tab Standard
1391 @item @code{DATAN(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab Fortran 77 and later
1394 @item @emph{See also}:
1395 Inverse function: @ref{TAN}
1402 @section @code{ATAN2} --- Arctangent function
1405 @cindex trigonometric function, tangent, inverse
1406 @cindex tangent, inverse
1409 @item @emph{Description}:
1410 @code{ATAN2(Y, X)} computes the principal value of the argument
1411 function of the complex number @math{X + i Y}. This function can
1412 be used to transform from carthesian into polar coordinates and
1413 allows to determine the angle in the correct quadrant.
1415 @item @emph{Standard}:
1416 Fortran 77 and later
1421 @item @emph{Syntax}:
1422 @code{RESULT = ATAN2(Y, X)}
1424 @item @emph{Arguments}:
1425 @multitable @columnfractions .15 .70
1426 @item @var{Y} @tab The type shall be @code{REAL}.
1427 @item @var{X} @tab The type and kind type parameter shall be the same as @var{Y}.
1428 If @var{Y} is zero, then @var{X} must be nonzero.
1431 @item @emph{Return value}:
1432 The return value has the same type and kind type parameter as @var{Y}.
1433 It is the principal value of the complex number @math{X + i Y}. If
1434 @var{X} is nonzero, then it lies in the range @math{-\pi \le \atan (x) \leq \pi}.
1435 The sign is positive if @var{Y} is positive. If @var{Y} is zero, then
1436 the return value is zero if @var{X} is positive and @math{\pi} if @var{X}
1437 is negative. Finally, if @var{X} is zero, then the magnitude of the result
1440 @item @emph{Example}:
1443 real(4) :: x = 1.e0_4, y = 0.5e0_4
1445 end program test_atan2
1448 @item @emph{Specific names}:
1449 @multitable @columnfractions .20 .20 .20 .25
1450 @item Name @tab Argument @tab Return type @tab Standard
1451 @item @code{DATAN2(X, Y)} @tab @code{REAL(8) X}, @code{REAL(8) Y} @tab @code{REAL(8)} @tab Fortran 77 and later
1458 @section @code{ATANH} --- Hyperbolic arctangent function
1461 @cindex area hyperbolic tangent
1462 @cindex hyperbolic arctangent
1463 @cindex hyperbolic function, tangent, inverse
1464 @cindex tangent, hyperbolic, inverse
1467 @item @emph{Description}:
1468 @code{ATANH(X)} computes the hyperbolic arctangent of @var{X} (inverse
1471 @item @emph{Standard}:
1472 Fortran 2008 and later
1477 @item @emph{Syntax}:
1478 @code{RESULT = ATANH(X)}
1480 @item @emph{Arguments}:
1481 @multitable @columnfractions .15 .70
1482 @item @var{X} @tab The type shall be @code{REAL} or @code{COMPLEX}.
1485 @item @emph{Return value}:
1486 The return value has same type and kind as @var{X}. If @var{X} is
1487 complex, the imaginary part of the result is in radians and lies between
1488 @math{-\pi/2 \leq \Im \atanh(x) \leq \pi/2}.
1490 @item @emph{Example}:
1493 REAL, DIMENSION(3) :: x = (/ -1.0, 0.0, 1.0 /)
1494 WRITE (*,*) ATANH(x)
1498 @item @emph{Specific names}:
1499 @multitable @columnfractions .20 .20 .20 .25
1500 @item Name @tab Argument @tab Return type @tab Standard
1501 @item @code{DATANH(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU extension
1504 @item @emph{See also}:
1505 Inverse function: @ref{TANH}
1511 @section @code{BESSEL_J0} --- Bessel function of the first kind of order 0
1515 @cindex Bessel function, first kind
1518 @item @emph{Description}:
1519 @code{BESSEL_J0(X)} computes the Bessel function of the first kind of
1520 order 0 of @var{X}. This function is available under the name
1521 @code{BESJ0} as a GNU extension.
1523 @item @emph{Standard}:
1524 Fortran 2008 and later
1529 @item @emph{Syntax}:
1530 @code{RESULT = BESSEL_J0(X)}
1532 @item @emph{Arguments}:
1533 @multitable @columnfractions .15 .70
1534 @item @var{X} @tab The type shall be @code{REAL}, and it shall be scalar.
1537 @item @emph{Return value}:
1538 The return value is of type @code{REAL} and lies in the
1539 range @math{ - 0.4027... \leq Bessel (0,x) \leq 1}. It has the same
1542 @item @emph{Example}:
1545 real(8) :: x = 0.0_8
1547 end program test_besj0
1550 @item @emph{Specific names}:
1551 @multitable @columnfractions .20 .20 .20 .25
1552 @item Name @tab Argument @tab Return type @tab Standard
1553 @item @code{DBESJ0(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU extension
1560 @section @code{BESSEL_J1} --- Bessel function of the first kind of order 1
1564 @cindex Bessel function, first kind
1567 @item @emph{Description}:
1568 @code{BESSEL_J1(X)} computes the Bessel function of the first kind of
1569 order 1 of @var{X}. This function is available under the name
1570 @code{BESJ1} as a GNU extension.
1572 @item @emph{Standard}:
1578 @item @emph{Syntax}:
1579 @code{RESULT = BESSEL_J1(X)}
1581 @item @emph{Arguments}:
1582 @multitable @columnfractions .15 .70
1583 @item @var{X} @tab The type shall be @code{REAL}, and it shall be scalar.
1586 @item @emph{Return value}:
1587 The return value is of type @code{REAL} and it lies in the
1588 range @math{ - 0.5818... \leq Bessel (0,x) \leq 0.5818 }. It has the same
1591 @item @emph{Example}:
1594 real(8) :: x = 1.0_8
1596 end program test_besj1
1599 @item @emph{Specific names}:
1600 @multitable @columnfractions .20 .20 .20 .25
1601 @item Name @tab Argument @tab Return type @tab Standard
1602 @item @code{DBESJ1(X)}@tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU extension
1609 @section @code{BESSEL_JN} --- Bessel function of the first kind
1613 @cindex Bessel function, first kind
1616 @item @emph{Description}:
1617 @code{BESSEL_JN(N, X)} computes the Bessel function of the first kind of
1618 order @var{N} of @var{X}. This function is available under the name
1619 @code{BESJN} as a GNU extension.
1621 If both arguments are arrays, their ranks and shapes shall conform.
1623 @item @emph{Standard}:
1624 Fortran 2008 and later
1629 @item @emph{Syntax}:
1630 @code{RESULT = BESSEL_JN(N, X)}
1632 @item @emph{Arguments}:
1633 @multitable @columnfractions .15 .70
1634 @item @var{N} @tab Shall be a scalar or an array of type @code{INTEGER}.
1635 @item @var{X} @tab Shall be a scalar or an array of type @code{REAL}.
1638 @item @emph{Return value}:
1639 The return value is a scalar of type @code{REAL}. It has the same
1642 @item @emph{Example}:
1645 real(8) :: x = 1.0_8
1647 end program test_besjn
1650 @item @emph{Specific names}:
1651 @multitable @columnfractions .20 .20 .20 .25
1652 @item Name @tab Argument @tab Return type @tab Standard
1653 @item @code{DBESJN(N, X)} @tab @code{INTEGER N} @tab @code{REAL(8)} @tab GNU extension
1654 @item @tab @code{REAL(8) X} @tab @tab
1661 @section @code{BESSEL_Y0} --- Bessel function of the second kind of order 0
1665 @cindex Bessel function, second kind
1668 @item @emph{Description}:
1669 @code{BESSEL_Y0(X)} computes the Bessel function of the second kind of
1670 order 0 of @var{X}. This function is available under the name
1671 @code{BESY0} as a GNU extension.
1673 @item @emph{Standard}:
1674 Fortran 2008 and later
1679 @item @emph{Syntax}:
1680 @code{RESULT = BESSEL_Y0(X)}
1682 @item @emph{Arguments}:
1683 @multitable @columnfractions .15 .70
1684 @item @var{X} @tab The type shall be @code{REAL}, and it shall be scalar.
1687 @item @emph{Return value}:
1688 The return value is a scalar of type @code{REAL}. It has the same
1691 @item @emph{Example}:
1694 real(8) :: x = 0.0_8
1696 end program test_besy0
1699 @item @emph{Specific names}:
1700 @multitable @columnfractions .20 .20 .20 .25
1701 @item Name @tab Argument @tab Return type @tab Standard
1702 @item @code{DBESY0(X)}@tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU extension
1709 @section @code{BESSEL_Y1} --- Bessel function of the second kind of order 1
1713 @cindex Bessel function, second kind
1716 @item @emph{Description}:
1717 @code{BESSEL_Y1(X)} computes the Bessel function of the second kind of
1718 order 1 of @var{X}. This function is available under the name
1719 @code{BESY1} as a GNU extension.
1721 @item @emph{Standard}:
1722 Fortran 2008 and later
1727 @item @emph{Syntax}:
1728 @code{RESULT = BESSEL_Y1(X)}
1730 @item @emph{Arguments}:
1731 @multitable @columnfractions .15 .70
1732 @item @var{X} @tab The type shall be @code{REAL}, and it shall be scalar.
1735 @item @emph{Return value}:
1736 The return value is a scalar of type @code{REAL}. It has the same
1739 @item @emph{Example}:
1742 real(8) :: x = 1.0_8
1744 end program test_besy1
1747 @item @emph{Specific names}:
1748 @multitable @columnfractions .20 .20 .20 .25
1749 @item Name @tab Argument @tab Return type @tab Standard
1750 @item @code{DBESY1(X)}@tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU extension
1757 @section @code{BESSEL_YN} --- Bessel function of the second kind
1761 @cindex Bessel function, second kind
1764 @item @emph{Description}:
1765 @code{BESSEL_YN(N, X)} computes the Bessel function of the second kind of
1766 order @var{N} of @var{X}. This function is available under the name
1767 @code{BESYN} as a GNU extension.
1769 If both arguments are arrays, their ranks and shapes shall conform.
1771 @item @emph{Standard}:
1772 Fortran 2008 and later
1777 @item @emph{Syntax}:
1778 @code{RESULT = BESSEL_YN(N, X)}
1780 @item @emph{Arguments}:
1781 @multitable @columnfractions .15 .70
1782 @item @var{N} @tab Shall be a scalar or an array of type @code{INTEGER}.
1783 @item @var{X} @tab Shall be a scalar or an array of type @code{REAL}.
1786 @item @emph{Return value}:
1787 The return value is a scalar of type @code{REAL}. It has the same
1790 @item @emph{Example}:
1793 real(8) :: x = 1.0_8
1795 end program test_besyn
1798 @item @emph{Specific names}:
1799 @multitable @columnfractions .20 .20 .20 .25
1800 @item Name @tab Argument @tab Return type @tab Standard
1801 @item @code{DBESYN(N,X)} @tab @code{INTEGER N} @tab @code{REAL(8)} @tab GNU extension
1802 @item @tab @code{REAL(8) X} @tab @tab
1809 @section @code{BIT_SIZE} --- Bit size inquiry function
1811 @cindex bits, number of
1812 @cindex size of a variable, in bits
1815 @item @emph{Description}:
1816 @code{BIT_SIZE(I)} returns the number of bits (integer precision plus sign bit)
1817 represented by the type of @var{I}. The result of @code{BIT_SIZE(I)} is
1818 independent of the actual value of @var{I}.
1820 @item @emph{Standard}:
1821 Fortran 95 and later
1826 @item @emph{Syntax}:
1827 @code{RESULT = BIT_SIZE(I)}
1829 @item @emph{Arguments}:
1830 @multitable @columnfractions .15 .70
1831 @item @var{I} @tab The type shall be @code{INTEGER}.
1834 @item @emph{Return value}:
1835 The return value is of type @code{INTEGER}
1837 @item @emph{Example}:
1839 program test_bit_size
1844 end program test_bit_size
1851 @section @code{BTEST} --- Bit test function
1853 @cindex bits, testing
1856 @item @emph{Description}:
1857 @code{BTEST(I,POS)} returns logical @code{.TRUE.} if the bit at @var{POS}
1858 in @var{I} is set. The counting of the bits starts at 0.
1860 @item @emph{Standard}:
1861 Fortran 95 and later
1866 @item @emph{Syntax}:
1867 @code{RESULT = BTEST(I, POS)}
1869 @item @emph{Arguments}:
1870 @multitable @columnfractions .15 .70
1871 @item @var{I} @tab The type shall be @code{INTEGER}.
1872 @item @var{POS} @tab The type shall be @code{INTEGER}.
1875 @item @emph{Return value}:
1876 The return value is of type @code{LOGICAL}
1878 @item @emph{Example}:
1881 integer :: i = 32768 + 1024 + 64
1885 bool = btest(i, pos)
1888 end program test_btest
1894 @section @code{C_ASSOCIATED} --- Status of a C pointer
1895 @fnindex C_ASSOCIATED
1896 @cindex association status, C pointer
1897 @cindex pointer, C association status
1900 @item @emph{Description}:
1901 @code{C_ASSOCIATED(c_prt_1[, c_ptr_2])} determines the status of the C pointer
1902 @var{c_ptr_1} or if @var{c_ptr_1} is associated with the target @var{c_ptr_2}.
1904 @item @emph{Standard}:
1905 Fortran 2003 and later
1910 @item @emph{Syntax}:
1911 @code{RESULT = C_ASSOCIATED(c_prt_1[, c_ptr_2])}
1913 @item @emph{Arguments}:
1914 @multitable @columnfractions .15 .70
1915 @item @var{c_ptr_1} @tab Scalar of the type @code{C_PTR} or @code{C_FUNPTR}.
1916 @item @var{c_ptr_2} @tab (Optional) Scalar of the same type as @var{c_ptr_1}.
1919 @item @emph{Return value}:
1920 The return value is of type @code{LOGICAL}; it is @code{.false.} if either
1921 @var{c_ptr_1} is a C NULL pointer or if @var{c_ptr1} and @var{c_ptr_2}
1922 point to different addresses.
1924 @item @emph{Example}:
1926 subroutine association_test(a,b)
1927 use iso_c_binding, only: c_associated, c_loc, c_ptr
1931 if(c_associated(b, c_loc(a))) &
1932 stop 'b and a do not point to same target'
1933 end subroutine association_test
1936 @item @emph{See also}:
1937 @ref{C_LOC}, @ref{C_FUNLOC}
1942 @section @code{C_FUNLOC} --- Obtain the C address of a procedure
1944 @cindex pointer, C address of procedures
1947 @item @emph{Description}:
1948 @code{C_FUNLOC(x)} determines the C address of the argument.
1950 @item @emph{Standard}:
1951 Fortran 2003 and later
1956 @item @emph{Syntax}:
1957 @code{RESULT = C_FUNLOC(x)}
1959 @item @emph{Arguments}:
1960 @multitable @columnfractions .15 .70
1961 @item @var{x} @tab Interoperable function or pointer to such function.
1964 @item @emph{Return value}:
1965 The return value is of type @code{C_FUNPTR} and contains the C address
1968 @item @emph{Example}:
1974 subroutine sub(a) bind(c)
1984 subroutine my_routine(p) bind(c,name='myC_func')
1986 type(c_funptr), intent(in) :: p
1989 call my_routine(c_funloc(sub))
1993 @item @emph{See also}:
1994 @ref{C_ASSOCIATED}, @ref{C_LOC}, @ref{C_F_POINTER}, @ref{C_F_PROCPOINTER}
1998 @node C_F_PROCPOINTER
1999 @section @code{C_F_PROCPOINTER} --- Convert C into Fortran procedure pointer
2000 @fnindex C_F_PROCPOINTER
2001 @cindex pointer, C address of pointers
2004 @item @emph{Description}:
2005 @code{C_F_PROCPOINTER(CPTR, FPTR)} Assign the target of the C function pointer
2006 @var{CPTR} to the Fortran procedure pointer @var{FPTR}.
2008 @item @emph{Standard}:
2009 Fortran 2003 and later
2014 @item @emph{Syntax}:
2015 @code{CALL C_F_PROCPOINTER(cptr, fptr)}
2017 @item @emph{Arguments}:
2018 @multitable @columnfractions .15 .70
2019 @item @var{CPTR} @tab scalar of the type @code{C_FUNPTR}. It is
2021 @item @var{FPTR} @tab procedure pointer interoperable with @var{cptr}. It is
2025 @item @emph{Example}:
2033 real(c_float), intent(in) :: a
2034 real(c_float) :: func
2038 function getIterFunc() bind(c,name="getIterFunc")
2040 type(c_funptr) :: getIterFunc
2043 type(c_funptr) :: cfunptr
2044 procedure(func), pointer :: myFunc
2045 cfunptr = getIterFunc()
2046 call c_f_procpointer(cfunptr, myFunc)
2050 @item @emph{See also}:
2051 @ref{C_LOC}, @ref{C_F_POINTER}
2056 @section @code{C_F_POINTER} --- Convert C into Fortran pointer
2057 @fnindex C_F_POINTER
2058 @cindex pointer, convert C to Fortran
2061 @item @emph{Description}:
2062 @code{C_F_POINTER(CPTR, FPTR[, SHAPE])} Assign the target the C pointer
2063 @var{CPTR} to the Fortran pointer @var{FPTR} and specify its
2066 @item @emph{Standard}:
2067 Fortran 2003 and later
2072 @item @emph{Syntax}:
2073 @code{CALL C_F_POINTER(CPTR, FPTR[, SHAPE])}
2075 @item @emph{Arguments}:
2076 @multitable @columnfractions .15 .70
2077 @item @var{CPTR} @tab scalar of the type @code{C_PTR}. It is
2079 @item @var{FPTR} @tab pointer interoperable with @var{cptr}. It is
2081 @item @var{SHAPE} @tab (Optional) Rank-one array of type @code{INTEGER}
2082 with @code{INTENT(IN)}. It shall be present
2083 if and only if @var{fptr} is an array. The size
2084 must be equal to the rank of @var{fptr}.
2087 @item @emph{Example}:
2093 subroutine my_routine(p) bind(c,name='myC_func')
2095 type(c_ptr), intent(out) :: p
2099 real,pointer :: a(:)
2100 call my_routine(cptr)
2101 call c_f_pointer(cptr, a, [12])
2105 @item @emph{See also}:
2106 @ref{C_LOC}, @ref{C_F_PROCPOINTER}
2111 @section @code{C_LOC} --- Obtain the C address of an object
2113 @cindex procedure pointer, convert C to Fortran
2116 @item @emph{Description}:
2117 @code{C_LOC(X)} determines the C address of the argument.
2119 @item @emph{Standard}:
2120 Fortran 2003 and later
2125 @item @emph{Syntax}:
2126 @code{RESULT = C_LOC(X)}
2128 @item @emph{Arguments}:
2129 @multitable @columnfractions .15 .70
2130 @item @var{X} @tab Associated scalar pointer or interoperable scalar
2131 or allocated allocatable variable with @code{TARGET} attribute.
2134 @item @emph{Return value}:
2135 The return value is of type @code{C_PTR} and contains the C address
2138 @item @emph{Example}:
2140 subroutine association_test(a,b)
2141 use iso_c_binding, only: c_associated, c_loc, c_ptr
2145 if(c_associated(b, c_loc(a))) &
2146 stop 'b and a do not point to same target'
2147 end subroutine association_test
2150 @item @emph{See also}:
2151 @ref{C_ASSOCIATED}, @ref{C_FUNLOC}, @ref{C_F_POINTER}, @ref{C_F_PROCPOINTER}
2156 @section @code{C_SIZEOF} --- Size in bytes of an expression
2158 @cindex expression size
2159 @cindex size of an expression
2162 @item @emph{Description}:
2163 @code{C_SIZEOF(X)} calculates the number of bytes of storage the
2164 expression @code{X} occupies.
2166 @item @emph{Standard}:
2172 @item @emph{Syntax}:
2173 @code{N = C_SIZEOF(X)}
2175 @item @emph{Arguments}:
2176 @multitable @columnfractions .15 .70
2177 @item @var{X} @tab The argument shall be of any type, rank or shape.
2180 @item @emph{Return value}:
2181 The return value is of type integer and of the system-dependent kind
2182 @var{C_SIZE_T} (from the @var{ISO_C_BINDING} module). Its value is the
2183 number of bytes occupied by the argument. If the argument has the
2184 @code{POINTER} attribute, the number of bytes of the storage area pointed
2185 to is returned. If the argument is of a derived type with @code{POINTER}
2186 or @code{ALLOCATABLE} components, the return value doesn't account for
2187 the sizes of the data pointed to by these components.
2189 @item @emph{Example}:
2193 real(c_float) :: r, s(5)
2194 print *, (c_sizeof(s)/c_sizeof(r) == 5)
2197 The example will print @code{.TRUE.} unless you are using a platform
2198 where default @code{REAL} variables are unusually padded.
2200 @item @emph{See also}:
2206 @section @code{CEILING} --- Integer ceiling function
2209 @cindex rounding, ceiling
2212 @item @emph{Description}:
2213 @code{CEILING(A)} returns the least integer greater than or equal to @var{A}.
2215 @item @emph{Standard}:
2216 Fortran 95 and later
2221 @item @emph{Syntax}:
2222 @code{RESULT = CEILING(A [, KIND])}
2224 @item @emph{Arguments}:
2225 @multitable @columnfractions .15 .70
2226 @item @var{A} @tab The type shall be @code{REAL}.
2227 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
2228 expression indicating the kind parameter of the result.
2231 @item @emph{Return value}:
2232 The return value is of type @code{INTEGER(KIND)} if @var{KIND} is present
2233 and a default-kind @code{INTEGER} otherwise.
2235 @item @emph{Example}:
2237 program test_ceiling
2240 print *, ceiling(x) ! returns 64
2241 print *, ceiling(y) ! returns -63
2242 end program test_ceiling
2245 @item @emph{See also}:
2246 @ref{FLOOR}, @ref{NINT}
2253 @section @code{CHAR} --- Character conversion function
2255 @cindex conversion, to character
2258 @item @emph{Description}:
2259 @code{CHAR(I [, KIND])} returns the character represented by the integer @var{I}.
2261 @item @emph{Standard}:
2262 Fortran 77 and later
2267 @item @emph{Syntax}:
2268 @code{RESULT = CHAR(I [, KIND])}
2270 @item @emph{Arguments}:
2271 @multitable @columnfractions .15 .70
2272 @item @var{I} @tab The type shall be @code{INTEGER}.
2273 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
2274 expression indicating the kind parameter of the result.
2277 @item @emph{Return value}:
2278 The return value is of type @code{CHARACTER(1)}
2280 @item @emph{Example}:
2286 print *, i, c ! returns 'J'
2287 end program test_char
2291 See @ref{ICHAR} for a discussion of converting between numerical values
2292 and formatted string representations.
2294 @item @emph{See also}:
2295 @ref{ACHAR}, @ref{IACHAR}, @ref{ICHAR}
2302 @section @code{CHDIR} --- Change working directory
2304 @cindex system, working directory
2307 @item @emph{Description}:
2308 Change current working directory to a specified path.
2310 This intrinsic is provided in both subroutine and function forms; however,
2311 only one form can be used in any given program unit.
2313 @item @emph{Standard}:
2317 Subroutine, function
2319 @item @emph{Syntax}:
2320 @multitable @columnfractions .80
2321 @item @code{CALL CHDIR(NAME [, STATUS])}
2322 @item @code{STATUS = CHDIR(NAME)}
2325 @item @emph{Arguments}:
2326 @multitable @columnfractions .15 .70
2327 @item @var{NAME} @tab The type shall be @code{CHARACTER} of default
2328 kind and shall specify a valid path within the file system.
2329 @item @var{STATUS} @tab (Optional) @code{INTEGER} status flag of the default
2330 kind. Returns 0 on success, and a system specific and nonzero error code
2334 @item @emph{Example}:
2337 CHARACTER(len=255) :: path
2339 WRITE(*,*) TRIM(path)
2342 WRITE(*,*) TRIM(path)
2346 @item @emph{See also}:
2353 @section @code{CHMOD} --- Change access permissions of files
2355 @cindex file system, change access mode
2358 @item @emph{Description}:
2359 @code{CHMOD} changes the permissions of a file. This function invokes
2360 @code{/bin/chmod} and might therefore not work on all platforms.
2362 This intrinsic is provided in both subroutine and function forms; however,
2363 only one form can be used in any given program unit.
2365 @item @emph{Standard}:
2369 Subroutine, function
2371 @item @emph{Syntax}:
2372 @multitable @columnfractions .80
2373 @item @code{CALL CHMOD(NAME, MODE[, STATUS])}
2374 @item @code{STATUS = CHMOD(NAME, MODE)}
2377 @item @emph{Arguments}:
2378 @multitable @columnfractions .15 .70
2380 @item @var{NAME} @tab Scalar @code{CHARACTER} of default kind with the
2381 file name. Trailing blanks are ignored unless the character
2382 @code{achar(0)} is present, then all characters up to and excluding
2383 @code{achar(0)} are used as the file name.
2385 @item @var{MODE} @tab Scalar @code{CHARACTER} of default kind giving the
2386 file permission. @var{MODE} uses the same syntax as the @var{MODE}
2387 argument of @code{/bin/chmod}.
2389 @item @var{STATUS} @tab (optional) scalar @code{INTEGER}, which is
2390 @code{0} on success and nonzero otherwise.
2393 @item @emph{Return value}:
2394 In either syntax, @var{STATUS} is set to @code{0} on success and nonzero
2397 @item @emph{Example}:
2398 @code{CHMOD} as subroutine
2403 call chmod('test.dat','u+x',status)
2404 print *, 'Status: ', status
2405 end program chmod_test
2407 @code{CHMOD} as function:
2412 status = chmod('test.dat','u+x')
2413 print *, 'Status: ', status
2414 end program chmod_test
2422 @section @code{CMPLX} --- Complex conversion function
2424 @cindex complex numbers, conversion to
2425 @cindex conversion, to complex
2428 @item @emph{Description}:
2429 @code{CMPLX(X [, Y [, KIND]])} returns a complex number where @var{X} is converted to
2430 the real component. If @var{Y} is present it is converted to the imaginary
2431 component. If @var{Y} is not present then the imaginary component is set to
2432 0.0. If @var{X} is complex then @var{Y} must not be present.
2434 @item @emph{Standard}:
2435 Fortran 77 and later
2440 @item @emph{Syntax}:
2441 @code{RESULT = CMPLX(X [, Y [, KIND]])}
2443 @item @emph{Arguments}:
2444 @multitable @columnfractions .15 .70
2445 @item @var{X} @tab The type may be @code{INTEGER}, @code{REAL},
2447 @item @var{Y} @tab (Optional; only allowed if @var{X} is not
2448 @code{COMPLEX}.) May be @code{INTEGER} or @code{REAL}.
2449 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
2450 expression indicating the kind parameter of the result.
2453 @item @emph{Return value}:
2454 The return value is of @code{COMPLEX} type, with a kind equal to
2455 @var{KIND} if it is specified. If @var{KIND} is not specified, the
2456 result is of the default @code{COMPLEX} kind, regardless of the kinds of
2457 @var{X} and @var{Y}.
2459 @item @emph{Example}:
2466 print *, z, cmplx(x)
2467 end program test_cmplx
2470 @item @emph{See also}:
2476 @node COMMAND_ARGUMENT_COUNT
2477 @section @code{COMMAND_ARGUMENT_COUNT} --- Get number of command line arguments
2478 @fnindex COMMAND_ARGUMENT_COUNT
2479 @cindex command-line arguments
2480 @cindex command-line arguments, number of
2481 @cindex arguments, to program
2484 @item @emph{Description}:
2485 @code{COMMAND_ARGUMENT_COUNT()} returns the number of arguments passed on the
2486 command line when the containing program was invoked.
2488 @item @emph{Standard}:
2489 Fortran 2003 and later
2494 @item @emph{Syntax}:
2495 @code{RESULT = COMMAND_ARGUMENT_COUNT()}
2497 @item @emph{Arguments}:
2498 @multitable @columnfractions .15 .70
2502 @item @emph{Return value}:
2503 The return value is an @code{INTEGER} of default kind.
2505 @item @emph{Example}:
2507 program test_command_argument_count
2509 count = command_argument_count()
2511 end program test_command_argument_count
2514 @item @emph{See also}:
2515 @ref{GET_COMMAND}, @ref{GET_COMMAND_ARGUMENT}
2521 @section @code{COMPLEX} --- Complex conversion function
2523 @cindex complex numbers, conversion to
2524 @cindex conversion, to complex
2527 @item @emph{Description}:
2528 @code{COMPLEX(X, Y)} returns a complex number where @var{X} is converted
2529 to the real component and @var{Y} is converted to the imaginary
2532 @item @emph{Standard}:
2538 @item @emph{Syntax}:
2539 @code{RESULT = COMPLEX(X, Y)}
2541 @item @emph{Arguments}:
2542 @multitable @columnfractions .15 .70
2543 @item @var{X} @tab The type may be @code{INTEGER} or @code{REAL}.
2544 @item @var{Y} @tab The type may be @code{INTEGER} or @code{REAL}.
2547 @item @emph{Return value}:
2548 If @var{X} and @var{Y} are both of @code{INTEGER} type, then the return
2549 value is of default @code{COMPLEX} type.
2551 If @var{X} and @var{Y} are of @code{REAL} type, or one is of @code{REAL}
2552 type and one is of @code{INTEGER} type, then the return value is of
2553 @code{COMPLEX} type with a kind equal to that of the @code{REAL}
2554 argument with the highest precision.
2556 @item @emph{Example}:
2558 program test_complex
2561 print *, complex(i, x)
2562 end program test_complex
2565 @item @emph{See also}:
2572 @section @code{CONJG} --- Complex conjugate function
2575 @cindex complex conjugate
2578 @item @emph{Description}:
2579 @code{CONJG(Z)} returns the conjugate of @var{Z}. If @var{Z} is @code{(x, y)}
2580 then the result is @code{(x, -y)}
2582 @item @emph{Standard}:
2583 Fortran 77 and later, has overloads that are GNU extensions
2588 @item @emph{Syntax}:
2591 @item @emph{Arguments}:
2592 @multitable @columnfractions .15 .70
2593 @item @var{Z} @tab The type shall be @code{COMPLEX}.
2596 @item @emph{Return value}:
2597 The return value is of type @code{COMPLEX}.
2599 @item @emph{Example}:
2602 complex :: z = (2.0, 3.0)
2603 complex(8) :: dz = (2.71_8, -3.14_8)
2608 end program test_conjg
2611 @item @emph{Specific names}:
2612 @multitable @columnfractions .20 .20 .20 .25
2613 @item Name @tab Argument @tab Return type @tab Standard
2614 @item @code{DCONJG(Z)} @tab @code{COMPLEX(8) Z} @tab @code{COMPLEX(8)} @tab GNU extension
2621 @section @code{COS} --- Cosine function
2627 @cindex trigonometric function, cosine
2631 @item @emph{Description}:
2632 @code{COS(X)} computes the cosine of @var{X}.
2634 @item @emph{Standard}:
2635 Fortran 77 and later, has overloads that are GNU extensions
2640 @item @emph{Syntax}:
2641 @code{RESULT = COS(X)}
2643 @item @emph{Arguments}:
2644 @multitable @columnfractions .15 .70
2645 @item @var{X} @tab The type shall be @code{REAL} or
2649 @item @emph{Return value}:
2650 The return value is of the same type and kind as @var{X}. The real part
2651 of the result is in radians. If @var{X} is of the type @code{REAL},
2652 the return value lies in the range @math{ -1 \leq \cos (x) \leq 1}.
2654 @item @emph{Example}:
2659 end program test_cos
2662 @item @emph{Specific names}:
2663 @multitable @columnfractions .20 .20 .20 .25
2664 @item Name @tab Argument @tab Return type @tab Standard
2665 @item @code{DCOS(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab Fortran 77 and later
2666 @item @code{CCOS(X)} @tab @code{COMPLEX(4) X} @tab @code{COMPLEX(4)} @tab Fortran 77 and later
2667 @item @code{ZCOS(X)} @tab @code{COMPLEX(8) X} @tab @code{COMPLEX(8)} @tab GNU extension
2668 @item @code{CDCOS(X)} @tab @code{COMPLEX(8) X} @tab @code{COMPLEX(8)} @tab GNU extension
2671 @item @emph{See also}:
2672 Inverse function: @ref{ACOS}
2679 @section @code{COSH} --- Hyperbolic cosine function
2682 @cindex hyperbolic cosine
2683 @cindex hyperbolic function, cosine
2684 @cindex cosine, hyperbolic
2687 @item @emph{Description}:
2688 @code{COSH(X)} computes the hyperbolic cosine of @var{X}.
2690 @item @emph{Standard}:
2691 Fortran 77 and later, for a complex argument Fortran 2008 or later
2696 @item @emph{Syntax}:
2699 @item @emph{Arguments}:
2700 @multitable @columnfractions .15 .70
2701 @item @var{X} @tab The type shall be @code{REAL} or @code{COMPLEX}.
2704 @item @emph{Return value}:
2705 The return value has same type and kind as @var{X}. If @var{X} is
2706 complex, the imaginary part of the result is in radians. If @var{X}
2707 is @code{REAL}, the return value has a lower bound of one,
2708 @math{\cosh (x) \geq 1}.
2710 @item @emph{Example}:
2713 real(8) :: x = 1.0_8
2715 end program test_cosh
2718 @item @emph{Specific names}:
2719 @multitable @columnfractions .20 .20 .20 .25
2720 @item Name @tab Argument @tab Return type @tab Standard
2721 @item @code{DCOSH(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab Fortran 77 and later
2724 @item @emph{See also}:
2725 Inverse function: @ref{ACOSH}
2732 @section @code{COUNT} --- Count function
2734 @cindex array, conditionally count elements
2735 @cindex array, element counting
2736 @cindex array, number of elements
2739 @item @emph{Description}:
2741 @code{COUNT(MASK [, DIM [, KIND]])} counts the number of @code{.TRUE.}
2742 elements of @var{MASK} along the dimension of @var{DIM}. If @var{DIM} is
2743 omitted it is taken to be @code{1}. @var{DIM} is a scalar of type
2744 @code{INTEGER} in the range of @math{1 \leq DIM \leq n)} where @math{n}
2745 is the rank of @var{MASK}.
2747 @item @emph{Standard}:
2748 Fortran 95 and later, with @var{KIND} argument Fortran 2003 and later
2751 Transformational function
2753 @item @emph{Syntax}:
2754 @code{RESULT = COUNT(MASK [, DIM [, KIND]])}
2756 @item @emph{Arguments}:
2757 @multitable @columnfractions .15 .70
2758 @item @var{MASK} @tab The type shall be @code{LOGICAL}.
2759 @item @var{DIM} @tab (Optional) The type shall be @code{INTEGER}.
2760 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
2761 expression indicating the kind parameter of the result.
2764 @item @emph{Return value}:
2765 The return value is of type @code{INTEGER} and of kind @var{KIND}. If
2766 @var{KIND} is absent, the return value is of default integer kind.
2767 The result has a rank equal to that of @var{MASK}.
2769 @item @emph{Example}:
2772 integer, dimension(2,3) :: a, b
2773 logical, dimension(2,3) :: mask
2774 a = reshape( (/ 1, 2, 3, 4, 5, 6 /), (/ 2, 3 /))
2775 b = reshape( (/ 0, 7, 3, 4, 5, 8 /), (/ 2, 3 /))
2776 print '(3i3)', a(1,:)
2777 print '(3i3)', a(2,:)
2779 print '(3i3)', b(1,:)
2780 print '(3i3)', b(2,:)
2783 print '(3l3)', mask(1,:)
2784 print '(3l3)', mask(2,:)
2786 print '(3i3)', count(mask)
2788 print '(3i3)', count(mask, 1)
2790 print '(3i3)', count(mask, 2)
2791 end program test_count
2798 @section @code{CPU_TIME} --- CPU elapsed time in seconds
2800 @cindex time, elapsed
2803 @item @emph{Description}:
2804 Returns a @code{REAL} value representing the elapsed CPU time in
2805 seconds. This is useful for testing segments of code to determine
2808 If a time source is available, time will be reported with microsecond
2809 resolution. If no time source is available, @var{TIME} is set to
2812 Note that @var{TIME} may contain a, system dependent, arbitrary offset
2813 and may not start with @code{0.0}. For @code{CPU_TIME}, the absolute
2814 value is meaningless, only differences between subsequent calls to
2815 this subroutine, as shown in the example below, should be used.
2818 @item @emph{Standard}:
2819 Fortran 95 and later
2824 @item @emph{Syntax}:
2825 @code{CALL CPU_TIME(TIME)}
2827 @item @emph{Arguments}:
2828 @multitable @columnfractions .15 .70
2829 @item @var{TIME} @tab The type shall be @code{REAL} with @code{INTENT(OUT)}.
2832 @item @emph{Return value}:
2835 @item @emph{Example}:
2837 program test_cpu_time
2838 real :: start, finish
2839 call cpu_time(start)
2840 ! put code to test here
2841 call cpu_time(finish)
2842 print '("Time = ",f6.3," seconds.")',finish-start
2843 end program test_cpu_time
2846 @item @emph{See also}:
2847 @ref{SYSTEM_CLOCK}, @ref{DATE_AND_TIME}
2853 @section @code{CSHIFT} --- Circular shift elements of an array
2855 @cindex array, shift circularly
2856 @cindex array, permutation
2857 @cindex array, rotate
2860 @item @emph{Description}:
2861 @code{CSHIFT(ARRAY, SHIFT [, DIM])} performs a circular shift on elements of
2862 @var{ARRAY} along the dimension of @var{DIM}. If @var{DIM} is omitted it is
2863 taken to be @code{1}. @var{DIM} is a scalar of type @code{INTEGER} in the
2864 range of @math{1 \leq DIM \leq n)} where @math{n} is the rank of @var{ARRAY}.
2865 If the rank of @var{ARRAY} is one, then all elements of @var{ARRAY} are shifted
2866 by @var{SHIFT} places. If rank is greater than one, then all complete rank one
2867 sections of @var{ARRAY} along the given dimension are shifted. Elements
2868 shifted out one end of each rank one section are shifted back in the other end.
2870 @item @emph{Standard}:
2871 Fortran 95 and later
2874 Transformational function
2876 @item @emph{Syntax}:
2877 @code{RESULT = CSHIFT(ARRAY, SHIFT [, DIM])}
2879 @item @emph{Arguments}:
2880 @multitable @columnfractions .15 .70
2881 @item @var{ARRAY} @tab Shall be an array of any type.
2882 @item @var{SHIFT} @tab The type shall be @code{INTEGER}.
2883 @item @var{DIM} @tab The type shall be @code{INTEGER}.
2886 @item @emph{Return value}:
2887 Returns an array of same type and rank as the @var{ARRAY} argument.
2889 @item @emph{Example}:
2892 integer, dimension(3,3) :: a
2893 a = reshape( (/ 1, 2, 3, 4, 5, 6, 7, 8, 9 /), (/ 3, 3 /))
2894 print '(3i3)', a(1,:)
2895 print '(3i3)', a(2,:)
2896 print '(3i3)', a(3,:)
2897 a = cshift(a, SHIFT=(/1, 2, -1/), DIM=2)
2899 print '(3i3)', a(1,:)
2900 print '(3i3)', a(2,:)
2901 print '(3i3)', a(3,:)
2902 end program test_cshift
2909 @section @code{CTIME} --- Convert a time into a string
2911 @cindex time, conversion to string
2912 @cindex conversion, to string
2915 @item @emph{Description}:
2916 @code{CTIME} converts a system time value, such as returned by
2917 @code{TIME8()}, to a string of the form @samp{Sat Aug 19 18:13:14 1995}.
2919 This intrinsic is provided in both subroutine and function forms; however,
2920 only one form can be used in any given program unit.
2922 @item @emph{Standard}:
2926 Subroutine, function
2928 @item @emph{Syntax}:
2929 @multitable @columnfractions .80
2930 @item @code{CALL CTIME(TIME, RESULT)}.
2931 @item @code{RESULT = CTIME(TIME)}, (not recommended).
2934 @item @emph{Arguments}:
2935 @multitable @columnfractions .15 .70
2936 @item @var{TIME} @tab The type shall be of type @code{INTEGER(KIND=8)}.
2937 @item @var{RESULT} @tab The type shall be of type @code{CHARACTER} and
2941 @item @emph{Return value}:
2942 The converted date and time as a string.
2944 @item @emph{Example}:
2948 character(len=30) :: date
2951 ! Do something, main part of the program
2954 print *, 'Program was started on ', date
2955 end program test_ctime
2958 @item @emph{See Also}:
2959 @ref{GMTIME}, @ref{LTIME}, @ref{TIME}, @ref{TIME8}
2965 @section @code{DATE_AND_TIME} --- Date and time subroutine
2966 @fnindex DATE_AND_TIME
2967 @cindex date, current
2968 @cindex current date
2969 @cindex time, current
2970 @cindex current time
2973 @item @emph{Description}:
2974 @code{DATE_AND_TIME(DATE, TIME, ZONE, VALUES)} gets the corresponding date and
2975 time information from the real-time system clock. @var{DATE} is
2976 @code{INTENT(OUT)} and has form ccyymmdd. @var{TIME} is @code{INTENT(OUT)} and
2977 has form hhmmss.sss. @var{ZONE} is @code{INTENT(OUT)} and has form (+-)hhmm,
2978 representing the difference with respect to Coordinated Universal Time (UTC).
2979 Unavailable time and date parameters return blanks.
2981 @var{VALUES} is @code{INTENT(OUT)} and provides the following:
2983 @multitable @columnfractions .15 .30 .40
2984 @item @tab @code{VALUE(1)}: @tab The year
2985 @item @tab @code{VALUE(2)}: @tab The month
2986 @item @tab @code{VALUE(3)}: @tab The day of the month
2987 @item @tab @code{VALUE(4)}: @tab Time difference with UTC in minutes
2988 @item @tab @code{VALUE(5)}: @tab The hour of the day
2989 @item @tab @code{VALUE(6)}: @tab The minutes of the hour
2990 @item @tab @code{VALUE(7)}: @tab The seconds of the minute
2991 @item @tab @code{VALUE(8)}: @tab The milliseconds of the second
2994 @item @emph{Standard}:
2995 Fortran 95 and later
3000 @item @emph{Syntax}:
3001 @code{CALL DATE_AND_TIME([DATE, TIME, ZONE, VALUES])}
3003 @item @emph{Arguments}:
3004 @multitable @columnfractions .15 .70
3005 @item @var{DATE} @tab (Optional) The type shall be @code{CHARACTER(LEN=8)}
3006 or larger, and of default kind.
3007 @item @var{TIME} @tab (Optional) The type shall be @code{CHARACTER(LEN=10)}
3008 or larger, and of default kind.
3009 @item @var{ZONE} @tab (Optional) The type shall be @code{CHARACTER(LEN=5)}
3010 or larger, and of default kind.
3011 @item @var{VALUES}@tab (Optional) The type shall be @code{INTEGER(8)}.
3014 @item @emph{Return value}:
3017 @item @emph{Example}:
3019 program test_time_and_date
3020 character(8) :: date
3021 character(10) :: time
3022 character(5) :: zone
3023 integer,dimension(8) :: values
3024 ! using keyword arguments
3025 call date_and_time(date,time,zone,values)
3026 call date_and_time(DATE=date,ZONE=zone)
3027 call date_and_time(TIME=time)
3028 call date_and_time(VALUES=values)
3029 print '(a,2x,a,2x,a)', date, time, zone
3030 print '(8i5))', values
3031 end program test_time_and_date
3034 @item @emph{See also}:
3035 @ref{CPU_TIME}, @ref{SYSTEM_CLOCK}
3041 @section @code{DBLE} --- Double conversion function
3043 @cindex conversion, to real
3046 @item @emph{Description}:
3047 @code{DBLE(A)} Converts @var{A} to double precision real type.
3049 @item @emph{Standard}:
3050 Fortran 77 and later
3055 @item @emph{Syntax}:
3056 @code{RESULT = DBLE(A)}
3058 @item @emph{Arguments}:
3059 @multitable @columnfractions .15 .70
3060 @item @var{A} @tab The type shall be @code{INTEGER}, @code{REAL},
3064 @item @emph{Return value}:
3065 The return value is of type double precision real.
3067 @item @emph{Example}:
3072 complex :: z = (2.3,1.14)
3073 print *, dble(x), dble(i), dble(z)
3074 end program test_dble
3077 @item @emph{See also}:
3078 @ref{DFLOAT}, @ref{FLOAT}, @ref{REAL}
3084 @section @code{DCMPLX} --- Double complex conversion function
3086 @cindex complex numbers, conversion to
3087 @cindex conversion, to complex
3090 @item @emph{Description}:
3091 @code{DCMPLX(X [,Y])} returns a double complex number where @var{X} is
3092 converted to the real component. If @var{Y} is present it is converted to the
3093 imaginary component. If @var{Y} is not present then the imaginary component is
3094 set to 0.0. If @var{X} is complex then @var{Y} must not be present.
3096 @item @emph{Standard}:
3102 @item @emph{Syntax}:
3103 @code{RESULT = DCMPLX(X [, Y])}
3105 @item @emph{Arguments}:
3106 @multitable @columnfractions .15 .70
3107 @item @var{X} @tab The type may be @code{INTEGER}, @code{REAL},
3109 @item @var{Y} @tab (Optional if @var{X} is not @code{COMPLEX}.) May be
3110 @code{INTEGER} or @code{REAL}.
3113 @item @emph{Return value}:
3114 The return value is of type @code{COMPLEX(8)}
3116 @item @emph{Example}:
3126 print *, dcmplx(x,i)
3127 end program test_dcmplx
3134 @section @code{DFLOAT} --- Double conversion function
3136 @cindex conversion, to real
3139 @item @emph{Description}:
3140 @code{DFLOAT(A)} Converts @var{A} to double precision real type.
3142 @item @emph{Standard}:
3148 @item @emph{Syntax}:
3149 @code{RESULT = DFLOAT(A)}
3151 @item @emph{Arguments}:
3152 @multitable @columnfractions .15 .70
3153 @item @var{A} @tab The type shall be @code{INTEGER}.
3156 @item @emph{Return value}:
3157 The return value is of type double precision real.
3159 @item @emph{Example}:
3164 end program test_dfloat
3167 @item @emph{See also}:
3168 @ref{DBLE}, @ref{FLOAT}, @ref{REAL}
3174 @section @code{DIGITS} --- Significant binary digits function
3176 @cindex model representation, significant digits
3179 @item @emph{Description}:
3180 @code{DIGITS(X)} returns the number of significant binary digits of the internal
3181 model representation of @var{X}. For example, on a system using a 32-bit
3182 floating point representation, a default real number would likely return 24.
3184 @item @emph{Standard}:
3185 Fortran 95 and later
3190 @item @emph{Syntax}:
3191 @code{RESULT = DIGITS(X)}
3193 @item @emph{Arguments}:
3194 @multitable @columnfractions .15 .70
3195 @item @var{X} @tab The type may be @code{INTEGER} or @code{REAL}.
3198 @item @emph{Return value}:
3199 The return value is of type @code{INTEGER}.
3201 @item @emph{Example}:
3204 integer :: i = 12345
3210 end program test_digits
3217 @section @code{DIM} --- Positive difference
3221 @cindex positive difference
3224 @item @emph{Description}:
3225 @code{DIM(X,Y)} returns the difference @code{X-Y} if the result is positive;
3226 otherwise returns zero.
3228 @item @emph{Standard}:
3229 Fortran 77 and later
3234 @item @emph{Syntax}:
3235 @code{RESULT = DIM(X, Y)}
3237 @item @emph{Arguments}:
3238 @multitable @columnfractions .15 .70
3239 @item @var{X} @tab The type shall be @code{INTEGER} or @code{REAL}
3240 @item @var{Y} @tab The type shall be the same type and kind as @var{X}.
3243 @item @emph{Return value}:
3244 The return value is of type @code{INTEGER} or @code{REAL}.
3246 @item @emph{Example}:
3252 x = dim(4.345_8, 2.111_8)
3255 end program test_dim
3258 @item @emph{Specific names}:
3259 @multitable @columnfractions .20 .20 .20 .25
3260 @item Name @tab Argument @tab Return type @tab Standard
3261 @item @code{IDIM(X,Y)} @tab @code{INTEGER(4) X,Y} @tab @code{INTEGER(4)} @tab Fortran 77 and later
3262 @item @code{DDIM(X,Y)} @tab @code{REAL(8) X,Y} @tab @code{REAL(8)} @tab Fortran 77 and later
3269 @section @code{DOT_PRODUCT} --- Dot product function
3270 @fnindex DOT_PRODUCT
3272 @cindex vector product
3273 @cindex product, vector
3276 @item @emph{Description}:
3277 @code{DOT_PRODUCT(VECTOR_A, VECTOR_B)} computes the dot product multiplication
3278 of two vectors @var{VECTOR_A} and @var{VECTOR_B}. The two vectors may be
3279 either numeric or logical and must be arrays of rank one and of equal size. If
3280 the vectors are @code{INTEGER} or @code{REAL}, the result is
3281 @code{SUM(VECTOR_A*VECTOR_B)}. If the vectors are @code{COMPLEX}, the result
3282 is @code{SUM(CONJG(VECTOR_A)*VECTOR_B)}. If the vectors are @code{LOGICAL},
3283 the result is @code{ANY(VECTOR_A .AND. VECTOR_B)}.
3285 @item @emph{Standard}:
3286 Fortran 95 and later
3289 Transformational function
3291 @item @emph{Syntax}:
3292 @code{RESULT = DOT_PRODUCT(VECTOR_A, VECTOR_B)}
3294 @item @emph{Arguments}:
3295 @multitable @columnfractions .15 .70
3296 @item @var{VECTOR_A} @tab The type shall be numeric or @code{LOGICAL}, rank 1.
3297 @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.
3300 @item @emph{Return value}:
3301 If the arguments are numeric, the return value is a scalar of numeric type,
3302 @code{INTEGER}, @code{REAL}, or @code{COMPLEX}. If the arguments are
3303 @code{LOGICAL}, the return value is @code{.TRUE.} or @code{.FALSE.}.
3305 @item @emph{Example}:
3307 program test_dot_prod
3308 integer, dimension(3) :: a, b
3315 print *, dot_product(a,b)
3316 end program test_dot_prod
3323 @section @code{DPROD} --- Double product function
3325 @cindex product, double-precision
3328 @item @emph{Description}:
3329 @code{DPROD(X,Y)} returns the product @code{X*Y}.
3331 @item @emph{Standard}:
3332 Fortran 77 and later
3337 @item @emph{Syntax}:
3338 @code{RESULT = DPROD(X, Y)}
3340 @item @emph{Arguments}:
3341 @multitable @columnfractions .15 .70
3342 @item @var{X} @tab The type shall be @code{REAL}.
3343 @item @var{Y} @tab The type shall be @code{REAL}.
3346 @item @emph{Return value}:
3347 The return value is of type @code{REAL(8)}.
3349 @item @emph{Example}:
3357 end program test_dprod
3364 @section @code{DREAL} --- Double real part function
3366 @cindex complex numbers, real part
3369 @item @emph{Description}:
3370 @code{DREAL(Z)} returns the real part of complex variable @var{Z}.
3372 @item @emph{Standard}:
3378 @item @emph{Syntax}:
3379 @code{RESULT = DREAL(A)}
3381 @item @emph{Arguments}:
3382 @multitable @columnfractions .15 .70
3383 @item @var{A} @tab The type shall be @code{COMPLEX(8)}.
3386 @item @emph{Return value}:
3387 The return value is of type @code{REAL(8)}.
3389 @item @emph{Example}:
3392 complex(8) :: z = (1.3_8,7.2_8)
3394 end program test_dreal
3397 @item @emph{See also}:
3405 @section @code{DTIME} --- Execution time subroutine (or function)
3407 @cindex time, elapsed
3408 @cindex elapsed time
3411 @item @emph{Description}:
3412 @code{DTIME(VALUES, TIME)} initially returns the number of seconds of runtime
3413 since the start of the process's execution in @var{TIME}. @var{VALUES}
3414 returns the user and system components of this time in @code{VALUES(1)} and
3415 @code{VALUES(2)} respectively. @var{TIME} is equal to @code{VALUES(1) +
3418 Subsequent invocations of @code{DTIME} return values accumulated since the
3419 previous invocation.
3421 On some systems, the underlying timings are represented using types with
3422 sufficiently small limits that overflows (wrap around) are possible, such as
3423 32-bit types. Therefore, the values returned by this intrinsic might be, or
3424 become, negative, or numerically less than previous values, during a single
3425 run of the compiled program.
3427 Please note, that this implementation is thread safe if used within OpenMP
3428 directives, i.e., its state will be consistent while called from multiple
3429 threads. However, if @code{DTIME} is called from multiple threads, the result
3430 is still the time since the last invocation. This may not give the intended
3431 results. If possible, use @code{CPU_TIME} instead.
3433 This intrinsic is provided in both subroutine and function forms; however,
3434 only one form can be used in any given program unit.
3436 @var{VALUES} and @var{TIME} are @code{INTENT(OUT)} and provide the following:
3438 @multitable @columnfractions .15 .30 .40
3439 @item @tab @code{VALUES(1)}: @tab User time in seconds.
3440 @item @tab @code{VALUES(2)}: @tab System time in seconds.
3441 @item @tab @code{TIME}: @tab Run time since start in seconds.
3444 @item @emph{Standard}:
3448 Subroutine, function
3450 @item @emph{Syntax}:
3451 @multitable @columnfractions .80
3452 @item @code{CALL DTIME(VALUES, TIME)}.
3453 @item @code{TIME = DTIME(VALUES)}, (not recommended).
3456 @item @emph{Arguments}:
3457 @multitable @columnfractions .15 .70
3458 @item @var{VALUES}@tab The type shall be @code{REAL(4), DIMENSION(2)}.
3459 @item @var{TIME}@tab The type shall be @code{REAL(4)}.
3462 @item @emph{Return value}:
3463 Elapsed time in seconds since the last invocation or since the start of program
3464 execution if not called before.
3466 @item @emph{Example}:
3470 real, dimension(2) :: tarray
3472 call dtime(tarray, result)
3476 do i=1,100000000 ! Just a delay
3479 call dtime(tarray, result)
3483 end program test_dtime
3486 @item @emph{See also}:
3494 @section @code{EOSHIFT} --- End-off shift elements of an array
3496 @cindex array, shift
3499 @item @emph{Description}:
3500 @code{EOSHIFT(ARRAY, SHIFT[, BOUNDARY, DIM])} performs an end-off shift on
3501 elements of @var{ARRAY} along the dimension of @var{DIM}. If @var{DIM} is
3502 omitted it is taken to be @code{1}. @var{DIM} is a scalar of type
3503 @code{INTEGER} in the range of @math{1 \leq DIM \leq n)} where @math{n} is the
3504 rank of @var{ARRAY}. If the rank of @var{ARRAY} is one, then all elements of
3505 @var{ARRAY} are shifted by @var{SHIFT} places. If rank is greater than one,
3506 then all complete rank one sections of @var{ARRAY} along the given dimension are
3507 shifted. Elements shifted out one end of each rank one section are dropped. If
3508 @var{BOUNDARY} is present then the corresponding value of from @var{BOUNDARY}
3509 is copied back in the other end. If @var{BOUNDARY} is not present then the
3510 following are copied in depending on the type of @var{ARRAY}.
3512 @multitable @columnfractions .15 .80
3513 @item @emph{Array Type} @tab @emph{Boundary Value}
3514 @item Numeric @tab 0 of the type and kind of @var{ARRAY}.
3515 @item Logical @tab @code{.FALSE.}.
3516 @item Character(@var{len}) @tab @var{len} blanks.
3519 @item @emph{Standard}:
3520 Fortran 95 and later
3523 Transformational function
3525 @item @emph{Syntax}:
3526 @code{RESULT = EOSHIFT(ARRAY, SHIFT [, BOUNDARY, DIM])}
3528 @item @emph{Arguments}:
3529 @multitable @columnfractions .15 .70
3530 @item @var{ARRAY} @tab May be any type, not scalar.
3531 @item @var{SHIFT} @tab The type shall be @code{INTEGER}.
3532 @item @var{BOUNDARY} @tab Same type as @var{ARRAY}.
3533 @item @var{DIM} @tab The type shall be @code{INTEGER}.
3536 @item @emph{Return value}:
3537 Returns an array of same type and rank as the @var{ARRAY} argument.
3539 @item @emph{Example}:
3541 program test_eoshift
3542 integer, dimension(3,3) :: a
3543 a = reshape( (/ 1, 2, 3, 4, 5, 6, 7, 8, 9 /), (/ 3, 3 /))
3544 print '(3i3)', a(1,:)
3545 print '(3i3)', a(2,:)
3546 print '(3i3)', a(3,:)
3547 a = EOSHIFT(a, SHIFT=(/1, 2, 1/), BOUNDARY=-5, DIM=2)
3549 print '(3i3)', a(1,:)
3550 print '(3i3)', a(2,:)
3551 print '(3i3)', a(3,:)
3552 end program test_eoshift
3559 @section @code{EPSILON} --- Epsilon function
3561 @cindex model representation, epsilon
3564 @item @emph{Description}:
3565 @code{EPSILON(X)} returns the smallest number @var{E} of the same kind
3566 as @var{X} such that @math{1 + E > 1}.
3568 @item @emph{Standard}:
3569 Fortran 95 and later
3574 @item @emph{Syntax}:
3575 @code{RESULT = EPSILON(X)}
3577 @item @emph{Arguments}:
3578 @multitable @columnfractions .15 .70
3579 @item @var{X} @tab The type shall be @code{REAL}.
3582 @item @emph{Return value}:
3583 The return value is of same type as the argument.
3585 @item @emph{Example}:
3587 program test_epsilon
3592 end program test_epsilon
3599 @section @code{ERF} --- Error function
3601 @cindex error function
3604 @item @emph{Description}:
3605 @code{ERF(X)} computes the error function of @var{X}.
3607 @item @emph{Standard}:
3608 Fortran 2008 and later
3613 @item @emph{Syntax}:
3614 @code{RESULT = ERF(X)}
3616 @item @emph{Arguments}:
3617 @multitable @columnfractions .15 .70
3618 @item @var{X} @tab The type shall be @code{REAL}.
3621 @item @emph{Return value}:
3622 The return value is of type @code{REAL}, of the same kind as
3623 @var{X} and lies in the range @math{-1 \leq erf (x) \leq 1 }.
3625 @item @emph{Example}:
3628 real(8) :: x = 0.17_8
3630 end program test_erf
3633 @item @emph{Specific names}:
3634 @multitable @columnfractions .20 .20 .20 .25
3635 @item Name @tab Argument @tab Return type @tab Standard
3636 @item @code{DERF(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU extension
3643 @section @code{ERFC} --- Error function
3645 @cindex error function, complementary
3648 @item @emph{Description}:
3649 @code{ERFC(X)} computes the complementary error function of @var{X}.
3651 @item @emph{Standard}:
3652 Fortran 2008 and later
3657 @item @emph{Syntax}:
3658 @code{RESULT = ERFC(X)}
3660 @item @emph{Arguments}:
3661 @multitable @columnfractions .15 .70
3662 @item @var{X} @tab The type shall be @code{REAL}.
3665 @item @emph{Return value}:
3666 The return value is of type @code{REAL} and of the same kind as @var{X}.
3667 It lies in the range @math{ 0 \leq erfc (x) \leq 2 }.
3669 @item @emph{Example}:
3672 real(8) :: x = 0.17_8
3674 end program test_erfc
3677 @item @emph{Specific names}:
3678 @multitable @columnfractions .20 .20 .20 .25
3679 @item Name @tab Argument @tab Return type @tab Standard
3680 @item @code{DERFC(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU extension
3687 @section @code{ERFC_SCALED} --- Error function
3688 @fnindex ERFC_SCALED
3689 @cindex error function, complementary, exponentially-scaled
3692 @item @emph{Description}:
3693 @code{ERFC_SCALED(X)} computes the exponentially-scaled complementary
3694 error function of @var{X}.
3696 @item @emph{Standard}:
3697 Fortran 2008 and later
3702 @item @emph{Syntax}:
3703 @code{RESULT = ERFC_SCALED(X)}
3705 @item @emph{Arguments}:
3706 @multitable @columnfractions .15 .70
3707 @item @var{X} @tab The type shall be @code{REAL}.
3710 @item @emph{Return value}:
3711 The return value is of type @code{REAL} and of the same kind as @var{X}.
3713 @item @emph{Example}:
3715 program test_erfc_scaled
3716 real(8) :: x = 0.17_8
3718 end program test_erfc_scaled
3725 @section @code{ETIME} --- Execution time subroutine (or function)
3727 @cindex time, elapsed
3730 @item @emph{Description}:
3731 @code{ETIME(VALUES, TIME)} returns the number of seconds of runtime
3732 since the start of the process's execution in @var{TIME}. @var{VALUES}
3733 returns the user and system components of this time in @code{VALUES(1)} and
3734 @code{VALUES(2)} respectively. @var{TIME} is equal to @code{VALUES(1) + VALUES(2)}.
3736 On some systems, the underlying timings are represented using types with
3737 sufficiently small limits that overflows (wrap around) are possible, such as
3738 32-bit types. Therefore, the values returned by this intrinsic might be, or
3739 become, negative, or numerically less than previous values, during a single
3740 run of the compiled program.
3742 This intrinsic is provided in both subroutine and function forms; however,
3743 only one form can be used in any given program unit.
3745 @var{VALUES} and @var{TIME} are @code{INTENT(OUT)} and provide the following:
3747 @multitable @columnfractions .15 .30 .60
3748 @item @tab @code{VALUES(1)}: @tab User time in seconds.
3749 @item @tab @code{VALUES(2)}: @tab System time in seconds.
3750 @item @tab @code{TIME}: @tab Run time since start in seconds.
3753 @item @emph{Standard}:
3757 Subroutine, function
3759 @item @emph{Syntax}:
3760 @multitable @columnfractions .80
3761 @item @code{CALL ETIME(VALUES, TIME)}.
3762 @item @code{TIME = ETIME(VALUES)}, (not recommended).
3765 @item @emph{Arguments}:
3766 @multitable @columnfractions .15 .70
3767 @item @var{VALUES}@tab The type shall be @code{REAL(4), DIMENSION(2)}.
3768 @item @var{TIME}@tab The type shall be @code{REAL(4)}.
3771 @item @emph{Return value}:
3772 Elapsed time in seconds since the start of program execution.
3774 @item @emph{Example}:
3778 real, dimension(2) :: tarray
3780 call ETIME(tarray, result)
3784 do i=1,100000000 ! Just a delay
3787 call ETIME(tarray, result)
3791 end program test_etime
3794 @item @emph{See also}:
3802 @section @code{EXIT} --- Exit the program with status.
3804 @cindex program termination
3805 @cindex terminate program
3808 @item @emph{Description}:
3809 @code{EXIT} causes immediate termination of the program with status. If status
3810 is omitted it returns the canonical @emph{success} for the system. All Fortran
3811 I/O units are closed.
3813 @item @emph{Standard}:
3819 @item @emph{Syntax}:
3820 @code{CALL EXIT([STATUS])}
3822 @item @emph{Arguments}:
3823 @multitable @columnfractions .15 .70
3824 @item @var{STATUS} @tab Shall be an @code{INTEGER} of the default kind.
3827 @item @emph{Return value}:
3828 @code{STATUS} is passed to the parent process on exit.
3830 @item @emph{Example}:
3833 integer :: STATUS = 0
3834 print *, 'This program is going to exit.'
3836 end program test_exit
3839 @item @emph{See also}:
3840 @ref{ABORT}, @ref{KILL}
3846 @section @code{EXP} --- Exponential function
3852 @cindex exponential function
3853 @cindex logarithmic function, inverse
3856 @item @emph{Description}:
3857 @code{EXP(X)} computes the base @math{e} exponential of @var{X}.
3859 @item @emph{Standard}:
3860 Fortran 77 and later, has overloads that are GNU extensions
3865 @item @emph{Syntax}:
3866 @code{RESULT = EXP(X)}
3868 @item @emph{Arguments}:
3869 @multitable @columnfractions .15 .70
3870 @item @var{X} @tab The type shall be @code{REAL} or
3874 @item @emph{Return value}:
3875 The return value has same type and kind as @var{X}.
3877 @item @emph{Example}:
3882 end program test_exp
3885 @item @emph{Specific names}:
3886 @multitable @columnfractions .20 .20 .20 .25
3887 @item Name @tab Argument @tab Return type @tab Standard
3888 @item @code{DEXP(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab Fortran 77 and later
3889 @item @code{CEXP(X)} @tab @code{COMPLEX(4) X} @tab @code{COMPLEX(4)} @tab Fortran 77 and later
3890 @item @code{ZEXP(X)} @tab @code{COMPLEX(8) X} @tab @code{COMPLEX(8)} @tab GNU extension
3891 @item @code{CDEXP(X)} @tab @code{COMPLEX(8) X} @tab @code{COMPLEX(8)} @tab GNU extension
3898 @section @code{EXPONENT} --- Exponent function
3900 @cindex real number, exponent
3901 @cindex floating point, exponent
3904 @item @emph{Description}:
3905 @code{EXPONENT(X)} returns the value of the exponent part of @var{X}. If @var{X}
3906 is zero the value returned is zero.
3908 @item @emph{Standard}:
3909 Fortran 95 and later
3914 @item @emph{Syntax}:
3915 @code{RESULT = EXPONENT(X)}
3917 @item @emph{Arguments}:
3918 @multitable @columnfractions .15 .70
3919 @item @var{X} @tab The type shall be @code{REAL}.
3922 @item @emph{Return value}:
3923 The return value is of type default @code{INTEGER}.
3925 @item @emph{Example}:
3927 program test_exponent
3932 print *, exponent(0.0)
3933 end program test_exponent
3940 @section @code{FDATE} --- Get the current time as a string
3942 @cindex time, current
3943 @cindex current time
3944 @cindex date, current
3945 @cindex current date
3948 @item @emph{Description}:
3949 @code{FDATE(DATE)} returns the current date (using the same format as
3950 @code{CTIME}) in @var{DATE}. It is equivalent to @code{CALL CTIME(DATE,
3953 This intrinsic is provided in both subroutine and function forms; however,
3954 only one form can be used in any given program unit.
3956 @var{DATE} is an @code{INTENT(OUT)} @code{CHARACTER} variable of the
3959 @item @emph{Standard}:
3963 Subroutine, function
3965 @item @emph{Syntax}:
3966 @multitable @columnfractions .80
3967 @item @code{CALL FDATE(DATE)}.
3968 @item @code{DATE = FDATE()}, (not recommended).
3971 @item @emph{Arguments}:
3972 @multitable @columnfractions .15 .70
3973 @item @var{DATE}@tab The type shall be of type @code{CHARACTER} of the
3977 @item @emph{Return value}:
3978 The current date as a string.
3980 @item @emph{Example}:
3984 character(len=30) :: date
3986 print *, 'Program started on ', date
3987 do i = 1, 100000000 ! Just a delay
3991 print *, 'Program ended on ', date
3992 end program test_fdate
3999 @section @code{FLOAT} --- Convert integer to default real
4001 @cindex conversion, to real
4004 @item @emph{Description}:
4005 @code{FLOAT(A)} converts the integer @var{A} to a default real value.
4007 @item @emph{Standard}:
4008 Fortran 77 and later
4013 @item @emph{Syntax}:
4014 @code{RESULT = FLOAT(A)}
4016 @item @emph{Arguments}:
4017 @multitable @columnfractions .15 .70
4018 @item @var{A} @tab The type shall be @code{INTEGER}.
4021 @item @emph{Return value}:
4022 The return value is of type default @code{REAL}.
4024 @item @emph{Example}:
4028 if (float(i) /= 1.) call abort
4029 end program test_float
4032 @item @emph{See also}:
4033 @ref{DBLE}, @ref{DFLOAT}, @ref{REAL}
4039 @section @code{FGET} --- Read a single character in stream mode from stdin
4041 @cindex read character, stream mode
4042 @cindex stream mode, read character
4043 @cindex file operation, read character
4046 @item @emph{Description}:
4047 Read a single character in stream mode from stdin by bypassing normal
4048 formatted output. Stream I/O should not be mixed with normal record-oriented
4049 (formatted or unformatted) I/O on the same unit; the results are unpredictable.
4051 This intrinsic is provided in both subroutine and function forms; however,
4052 only one form can be used in any given program unit.
4054 Note that the @code{FGET} intrinsic is provided for backwards compatibility with
4055 @command{g77}. GNU Fortran provides the Fortran 2003 Stream facility.
4056 Programmers should consider the use of new stream IO feature in new code
4057 for future portability. See also @ref{Fortran 2003 status}.
4059 @item @emph{Standard}:
4063 Subroutine, function
4065 @item @emph{Syntax}:
4066 @code{CALL FGET(C [, STATUS])}
4068 @item @emph{Arguments}:
4069 @multitable @columnfractions .15 .70
4070 @item @var{C} @tab The type shall be @code{CHARACTER} and of default
4072 @item @var{STATUS} @tab (Optional) status flag of type @code{INTEGER}.
4073 Returns 0 on success, -1 on end-of-file, and a system specific positive
4074 error code otherwise.
4077 @item @emph{Example}:
4080 INTEGER, PARAMETER :: strlen = 100
4081 INTEGER :: status, i = 1
4082 CHARACTER(len=strlen) :: str = ""
4084 WRITE (*,*) 'Enter text:'
4086 CALL fget(str(i:i), status)
4087 if (status /= 0 .OR. i > strlen) exit
4090 WRITE (*,*) TRIM(str)
4094 @item @emph{See also}:
4095 @ref{FGETC}, @ref{FPUT}, @ref{FPUTC}
4101 @section @code{FGETC} --- Read a single character in stream mode
4103 @cindex read character, stream mode
4104 @cindex stream mode, read character
4105 @cindex file operation, read character
4108 @item @emph{Description}:
4109 Read a single character in stream mode by bypassing normal formatted output.
4110 Stream I/O should not be mixed with normal record-oriented (formatted or
4111 unformatted) I/O on the same unit; the results are unpredictable.
4113 This intrinsic is provided in both subroutine and function forms; however,
4114 only one form can be used in any given program unit.
4116 Note that the @code{FGET} intrinsic is provided for backwards compatibility
4117 with @command{g77}. GNU Fortran provides the Fortran 2003 Stream facility.
4118 Programmers should consider the use of new stream IO feature in new code
4119 for future portability. See also @ref{Fortran 2003 status}.
4121 @item @emph{Standard}:
4125 Subroutine, function
4127 @item @emph{Syntax}:
4128 @code{CALL FGETC(UNIT, C [, STATUS])}
4130 @item @emph{Arguments}:
4131 @multitable @columnfractions .15 .70
4132 @item @var{UNIT} @tab The type shall be @code{INTEGER}.
4133 @item @var{C} @tab The type shall be @code{CHARACTER} and of default
4135 @item @var{STATUS} @tab (Optional) status flag of type @code{INTEGER}.
4136 Returns 0 on success, -1 on end-of-file and a system specific positive
4137 error code otherwise.
4140 @item @emph{Example}:
4143 INTEGER :: fd = 42, status
4146 OPEN(UNIT=fd, FILE="/etc/passwd", ACTION="READ", STATUS = "OLD")
4148 CALL fgetc(fd, c, status)
4149 IF (status /= 0) EXIT
4156 @item @emph{See also}:
4157 @ref{FGET}, @ref{FPUT}, @ref{FPUTC}
4163 @section @code{FLOOR} --- Integer floor function
4166 @cindex rounding, floor
4169 @item @emph{Description}:
4170 @code{FLOOR(A)} returns the greatest integer less than or equal to @var{X}.
4172 @item @emph{Standard}:
4173 Fortran 95 and later
4178 @item @emph{Syntax}:
4179 @code{RESULT = FLOOR(A [, KIND])}
4181 @item @emph{Arguments}:
4182 @multitable @columnfractions .15 .70
4183 @item @var{A} @tab The type shall be @code{REAL}.
4184 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
4185 expression indicating the kind parameter of the result.
4188 @item @emph{Return value}:
4189 The return value is of type @code{INTEGER(KIND)} if @var{KIND} is present
4190 and of default-kind @code{INTEGER} otherwise.
4192 @item @emph{Example}:
4197 print *, floor(x) ! returns 63
4198 print *, floor(y) ! returns -64
4199 end program test_floor
4202 @item @emph{See also}:
4203 @ref{CEILING}, @ref{NINT}
4210 @section @code{FLUSH} --- Flush I/O unit(s)
4212 @cindex file operation, flush
4215 @item @emph{Description}:
4216 Flushes Fortran unit(s) currently open for output. Without the optional
4217 argument, all units are flushed, otherwise just the unit specified.
4219 @item @emph{Standard}:
4225 @item @emph{Syntax}:
4226 @code{CALL FLUSH(UNIT)}
4228 @item @emph{Arguments}:
4229 @multitable @columnfractions .15 .70
4230 @item @var{UNIT} @tab (Optional) The type shall be @code{INTEGER}.
4234 Beginning with the Fortran 2003 standard, there is a @code{FLUSH}
4235 statement that should be preferred over the @code{FLUSH} intrinsic.
4242 @section @code{FNUM} --- File number function
4244 @cindex file operation, file number
4247 @item @emph{Description}:
4248 @code{FNUM(UNIT)} returns the POSIX file descriptor number corresponding to the
4249 open Fortran I/O unit @code{UNIT}.
4251 @item @emph{Standard}:
4257 @item @emph{Syntax}:
4258 @code{RESULT = FNUM(UNIT)}
4260 @item @emph{Arguments}:
4261 @multitable @columnfractions .15 .70
4262 @item @var{UNIT} @tab The type shall be @code{INTEGER}.
4265 @item @emph{Return value}:
4266 The return value is of type @code{INTEGER}
4268 @item @emph{Example}:
4272 open (unit=10, status = "scratch")
4276 end program test_fnum
4283 @section @code{FPUT} --- Write a single character in stream mode to stdout
4285 @cindex write character, stream mode
4286 @cindex stream mode, write character
4287 @cindex file operation, write character
4290 @item @emph{Description}:
4291 Write a single character in stream mode to stdout by bypassing normal
4292 formatted output. Stream I/O should not be mixed with normal record-oriented
4293 (formatted or unformatted) I/O on the same unit; the results are unpredictable.
4295 This intrinsic is provided in both subroutine and function forms; however,
4296 only one form can be used in any given program unit.
4298 Note that the @code{FGET} intrinsic is provided for backwards compatibility with
4299 @command{g77}. GNU Fortran provides the Fortran 2003 Stream facility.
4300 Programmers should consider the use of new stream IO feature in new code
4301 for future portability. See also @ref{Fortran 2003 status}.
4303 @item @emph{Standard}:
4307 Subroutine, function
4309 @item @emph{Syntax}:
4310 @code{CALL FPUT(C [, STATUS])}
4312 @item @emph{Arguments}:
4313 @multitable @columnfractions .15 .70
4314 @item @var{C} @tab The type shall be @code{CHARACTER} and of default
4316 @item @var{STATUS} @tab (Optional) status flag of type @code{INTEGER}.
4317 Returns 0 on success, -1 on end-of-file and a system specific positive
4318 error code otherwise.
4321 @item @emph{Example}:
4324 CHARACTER(len=10) :: str = "gfortran"
4326 DO i = 1, len_trim(str)
4332 @item @emph{See also}:
4333 @ref{FPUTC}, @ref{FGET}, @ref{FGETC}
4339 @section @code{FPUTC} --- Write a single character in stream mode
4341 @cindex write character, stream mode
4342 @cindex stream mode, write character
4343 @cindex file operation, write character
4346 @item @emph{Description}:
4347 Write a single character in stream mode by bypassing normal formatted
4348 output. Stream I/O should not be mixed with normal record-oriented
4349 (formatted or unformatted) I/O on the same unit; the results are unpredictable.
4351 This intrinsic is provided in both subroutine and function forms; however,
4352 only one form can be used in any given program unit.
4354 Note that the @code{FGET} intrinsic is provided for backwards compatibility with
4355 @command{g77}. GNU Fortran provides the Fortran 2003 Stream facility.
4356 Programmers should consider the use of new stream IO feature in new code
4357 for future portability. See also @ref{Fortran 2003 status}.
4359 @item @emph{Standard}:
4363 Subroutine, function
4365 @item @emph{Syntax}:
4366 @code{CALL FPUTC(UNIT, C [, STATUS])}
4368 @item @emph{Arguments}:
4369 @multitable @columnfractions .15 .70
4370 @item @var{UNIT} @tab The type shall be @code{INTEGER}.
4371 @item @var{C} @tab The type shall be @code{CHARACTER} and of default
4373 @item @var{STATUS} @tab (Optional) status flag of type @code{INTEGER}.
4374 Returns 0 on success, -1 on end-of-file and a system specific positive
4375 error code otherwise.
4378 @item @emph{Example}:
4381 CHARACTER(len=10) :: str = "gfortran"
4382 INTEGER :: fd = 42, i
4384 OPEN(UNIT = fd, FILE = "out", ACTION = "WRITE", STATUS="NEW")
4385 DO i = 1, len_trim(str)
4386 CALL fputc(fd, str(i:i))
4392 @item @emph{See also}:
4393 @ref{FPUT}, @ref{FGET}, @ref{FGETC}
4399 @section @code{FRACTION} --- Fractional part of the model representation
4401 @cindex real number, fraction
4402 @cindex floating point, fraction
4405 @item @emph{Description}:
4406 @code{FRACTION(X)} returns the fractional part of the model
4407 representation of @code{X}.
4409 @item @emph{Standard}:
4410 Fortran 95 and later
4415 @item @emph{Syntax}:
4416 @code{Y = FRACTION(X)}
4418 @item @emph{Arguments}:
4419 @multitable @columnfractions .15 .70
4420 @item @var{X} @tab The type of the argument shall be a @code{REAL}.
4423 @item @emph{Return value}:
4424 The return value is of the same type and kind as the argument.
4425 The fractional part of the model representation of @code{X} is returned;
4426 it is @code{X * RADIX(X)**(-EXPONENT(X))}.
4428 @item @emph{Example}:
4430 program test_fraction
4433 print *, fraction(x), x * radix(x)**(-exponent(x))
4434 end program test_fraction
4442 @section @code{FREE} --- Frees memory
4444 @cindex pointer, cray
4447 @item @emph{Description}:
4448 Frees memory previously allocated by @code{MALLOC()}. The @code{FREE}
4449 intrinsic is an extension intended to be used with Cray pointers, and is
4450 provided in GNU Fortran to allow user to compile legacy code. For
4451 new code using Fortran 95 pointers, the memory de-allocation intrinsic is
4454 @item @emph{Standard}:
4460 @item @emph{Syntax}:
4461 @code{CALL FREE(PTR)}
4463 @item @emph{Arguments}:
4464 @multitable @columnfractions .15 .70
4465 @item @var{PTR} @tab The type shall be @code{INTEGER}. It represents the
4466 location of the memory that should be de-allocated.
4469 @item @emph{Return value}:
4472 @item @emph{Example}:
4473 See @code{MALLOC} for an example.
4475 @item @emph{See also}:
4482 @section @code{FSEEK} --- Low level file positioning subroutine
4484 @cindex file operation, seek
4485 @cindex file operation, position
4488 @item @emph{Description}:
4489 Moves @var{UNIT} to the specified @var{OFFSET}. If @var{WHENCE}
4490 is set to 0, the @var{OFFSET} is taken as an absolute value @code{SEEK_SET},
4491 if set to 1, @var{OFFSET} is taken to be relative to the current position
4492 @code{SEEK_CUR}, and if set to 2 relative to the end of the file @code{SEEK_END}.
4493 On error, @var{STATUS} is set to a nonzero value. If @var{STATUS} the seek
4496 This intrinsic routine is not fully backwards compatible with @command{g77}.
4497 In @command{g77}, the @code{FSEEK} takes a statement label instead of a
4498 @var{STATUS} variable. If FSEEK is used in old code, change
4500 CALL FSEEK(UNIT, OFFSET, WHENCE, *label)
4505 CALL FSEEK(UNIT, OFFSET, WHENCE, status)
4506 IF (status /= 0) GOTO label
4509 Please note that GNU Fortran provides the Fortran 2003 Stream facility.
4510 Programmers should consider the use of new stream IO feature in new code
4511 for future portability. See also @ref{Fortran 2003 status}.
4513 @item @emph{Standard}:
4519 @item @emph{Syntax}:
4520 @code{CALL FSEEK(UNIT, OFFSET, WHENCE[, STATUS])}
4522 @item @emph{Arguments}:
4523 @multitable @columnfractions .15 .70
4524 @item @var{UNIT} @tab Shall be a scalar of type @code{INTEGER}.
4525 @item @var{OFFSET} @tab Shall be a scalar of type @code{INTEGER}.
4526 @item @var{WHENCE} @tab Shall be a scalar of type @code{INTEGER}.
4527 Its value shall be either 0, 1 or 2.
4528 @item @var{STATUS} @tab (Optional) shall be a scalar of type
4532 @item @emph{Example}:
4535 INTEGER, PARAMETER :: SEEK_SET = 0, SEEK_CUR = 1, SEEK_END = 2
4536 INTEGER :: fd, offset, ierr
4542 OPEN(UNIT=fd, FILE="fseek.test")
4543 CALL FSEEK(fd, offset, SEEK_SET, ierr) ! move to OFFSET
4544 print *, FTELL(fd), ierr
4546 CALL FSEEK(fd, 0, SEEK_END, ierr) ! move to end
4547 print *, FTELL(fd), ierr
4549 CALL FSEEK(fd, 0, SEEK_SET, ierr) ! move to beginning
4550 print *, FTELL(fd), ierr
4556 @item @emph{See also}:
4563 @section @code{FSTAT} --- Get file status
4565 @cindex file system, file status
4568 @item @emph{Description}:
4569 @code{FSTAT} is identical to @ref{STAT}, except that information about an
4570 already opened file is obtained.
4572 The elements in @code{VALUES} are the same as described by @ref{STAT}.
4574 This intrinsic is provided in both subroutine and function forms; however,
4575 only one form can be used in any given program unit.
4577 @item @emph{Standard}:
4581 Subroutine, function
4583 @item @emph{Syntax}:
4584 @code{CALL FSTAT(UNIT, VALUES [, STATUS])}
4586 @item @emph{Arguments}:
4587 @multitable @columnfractions .15 .70
4588 @item @var{UNIT} @tab An open I/O unit number of type @code{INTEGER}.
4589 @item @var{VALUES} @tab The type shall be @code{INTEGER(4), DIMENSION(13)}.
4590 @item @var{STATUS} @tab (Optional) status flag of type @code{INTEGER(4)}. Returns 0
4591 on success and a system specific error code otherwise.
4594 @item @emph{Example}:
4595 See @ref{STAT} for an example.
4597 @item @emph{See also}:
4598 To stat a link: @ref{LSTAT}, to stat a file: @ref{STAT}
4604 @section @code{FTELL} --- Current stream position
4606 @cindex file operation, position
4609 @item @emph{Description}:
4610 Retrieves the current position within an open file.
4612 This intrinsic is provided in both subroutine and function forms; however,
4613 only one form can be used in any given program unit.
4615 @item @emph{Standard}:
4619 Subroutine, function
4621 @item @emph{Syntax}:
4622 @multitable @columnfractions .80
4623 @item @code{CALL FTELL(UNIT, OFFSET)}
4624 @item @code{OFFSET = FTELL(UNIT)}
4627 @item @emph{Arguments}:
4628 @multitable @columnfractions .15 .70
4629 @item @var{OFFSET} @tab Shall of type @code{INTEGER}.
4630 @item @var{UNIT} @tab Shall of type @code{INTEGER}.
4633 @item @emph{Return value}:
4634 In either syntax, @var{OFFSET} is set to the current offset of unit
4635 number @var{UNIT}, or to @math{-1} if the unit is not currently open.
4637 @item @emph{Example}:
4641 OPEN(10, FILE="temp.dat")
4647 @item @emph{See also}:
4654 @section @code{GAMMA} --- Gamma function
4657 @cindex Gamma function
4658 @cindex Factorial function
4661 @item @emph{Description}:
4662 @code{GAMMA(X)} computes Gamma (@math{\Gamma}) of @var{X}. For positive,
4663 integer values of @var{X} the Gamma function simplifies to the factorial
4664 function @math{\Gamma(x)=(x-1)!}.
4668 \Gamma(x) = \int_0^\infty t^{x-1}{\rm e}^{-t}\,{\rm d}t
4672 @item @emph{Standard}:
4673 Fortran 2008 and later
4678 @item @emph{Syntax}:
4681 @item @emph{Arguments}:
4682 @multitable @columnfractions .15 .70
4683 @item @var{X} @tab Shall be of type @code{REAL} and neither zero
4684 nor a negative integer.
4687 @item @emph{Return value}:
4688 The return value is of type @code{REAL} of the same kind as @var{X}.
4690 @item @emph{Example}:
4694 x = gamma(x) ! returns 1.0
4695 end program test_gamma
4698 @item @emph{Specific names}:
4699 @multitable @columnfractions .20 .20 .20 .25
4700 @item Name @tab Argument @tab Return type @tab Standard
4701 @item @code{GAMMA(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab GNU Extension
4702 @item @code{DGAMMA(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU Extension
4705 @item @emph{See also}:
4706 Logarithm of the Gamma function: @ref{LOG_GAMMA}
4713 @section @code{GERROR} --- Get last system error message
4715 @cindex system, error handling
4718 @item @emph{Description}:
4719 Returns the system error message corresponding to the last system error.
4720 This resembles the functionality of @code{strerror(3)} in C.
4722 @item @emph{Standard}:
4728 @item @emph{Syntax}:
4729 @code{CALL GERROR(RESULT)}
4731 @item @emph{Arguments}:
4732 @multitable @columnfractions .15 .70
4733 @item @var{RESULT} @tab Shall of type @code{CHARACTER} and of default
4736 @item @emph{Example}:
4739 CHARACTER(len=100) :: msg
4745 @item @emph{See also}:
4746 @ref{IERRNO}, @ref{PERROR}
4752 @section @code{GETARG} --- Get command line arguments
4754 @cindex command-line arguments
4755 @cindex arguments, to program
4758 @item @emph{Description}:
4759 Retrieve the @var{POS}-th argument that was passed on the
4760 command line when the containing program was invoked.
4762 This intrinsic routine is provided for backwards compatibility with
4763 GNU Fortran 77. In new code, programmers should consider the use of
4764 the @ref{GET_COMMAND_ARGUMENT} intrinsic defined by the Fortran 2003
4767 @item @emph{Standard}:
4773 @item @emph{Syntax}:
4774 @code{CALL GETARG(POS, VALUE)}
4776 @item @emph{Arguments}:
4777 @multitable @columnfractions .15 .70
4778 @item @var{POS} @tab Shall be of type @code{INTEGER} and not wider than
4779 the default integer kind; @math{@var{POS} \geq 0}
4780 @item @var{VALUE} @tab Shall be of type @code{CHARACTER} and of default
4782 @item @var{VALUE} @tab Shall be of type @code{CHARACTER}.
4785 @item @emph{Return value}:
4786 After @code{GETARG} returns, the @var{VALUE} argument holds the
4787 @var{POS}th command line argument. If @var{VALUE} can not hold the
4788 argument, it is truncated to fit the length of @var{VALUE}. If there are
4789 less than @var{POS} arguments specified at the command line, @var{VALUE}
4790 will be filled with blanks. If @math{@var{POS} = 0}, @var{VALUE} is set
4791 to the name of the program (on systems that support this feature).
4793 @item @emph{Example}:
4797 CHARACTER(len=32) :: arg
4806 @item @emph{See also}:
4807 GNU Fortran 77 compatibility function: @ref{IARGC}
4809 Fortran 2003 functions and subroutines: @ref{GET_COMMAND},
4810 @ref{GET_COMMAND_ARGUMENT}, @ref{COMMAND_ARGUMENT_COUNT}
4816 @section @code{GET_COMMAND} --- Get the entire command line
4817 @fnindex GET_COMMAND
4818 @cindex command-line arguments
4819 @cindex arguments, to program
4822 @item @emph{Description}:
4823 Retrieve the entire command line that was used to invoke the program.
4825 @item @emph{Standard}:
4826 Fortran 2003 and later
4831 @item @emph{Syntax}:
4832 @code{CALL GET_COMMAND([COMMAND, LENGTH, STATUS])}
4834 @item @emph{Arguments}:
4835 @multitable @columnfractions .15 .70
4836 @item @var{COMMAND} @tab (Optional) shall be of type @code{CHARACTER} and
4838 @item @var{LENGTH} @tab (Optional) Shall be of type @code{INTEGER} and of
4840 @item @var{STATUS} @tab (Optional) Shall be of type @code{INTEGER} and of
4844 @item @emph{Return value}:
4845 If @var{COMMAND} is present, stores the entire command line that was used
4846 to invoke the program in @var{COMMAND}. If @var{LENGTH} is present, it is
4847 assigned the length of the command line. If @var{STATUS} is present, it
4848 is assigned 0 upon success of the command, -1 if @var{COMMAND} is too
4849 short to store the command line, or a positive value in case of an error.
4851 @item @emph{Example}:
4853 PROGRAM test_get_command
4854 CHARACTER(len=255) :: cmd
4855 CALL get_command(cmd)
4856 WRITE (*,*) TRIM(cmd)
4860 @item @emph{See also}:
4861 @ref{GET_COMMAND_ARGUMENT}, @ref{COMMAND_ARGUMENT_COUNT}
4866 @node GET_COMMAND_ARGUMENT
4867 @section @code{GET_COMMAND_ARGUMENT} --- Get command line arguments
4868 @fnindex GET_COMMAND_ARGUMENT
4869 @cindex command-line arguments
4870 @cindex arguments, to program
4873 @item @emph{Description}:
4874 Retrieve the @var{NUMBER}-th argument that was passed on the
4875 command line when the containing program was invoked.
4877 @item @emph{Standard}:
4878 Fortran 2003 and later
4883 @item @emph{Syntax}:
4884 @code{CALL GET_COMMAND_ARGUMENT(NUMBER [, VALUE, LENGTH, STATUS])}
4886 @item @emph{Arguments}:
4887 @multitable @columnfractions .15 .70
4888 @item @var{NUMBER} @tab Shall be a scalar of type @code{INTEGER} and of
4889 default kind, @math{@var{NUMBER} \geq 0}
4890 @item @var{VALUE} @tab Shall be a scalar of type @code{CHARACTER}
4891 and of default kind.
4892 @item @var{LENGTH} @tab (Option) Shall be a scalar of type @code{INTEGER}
4893 and of default kind.
4894 @item @var{STATUS} @tab (Option) Shall be a scalar of type @code{INTEGER}
4895 and of default kind.
4898 @item @emph{Return value}:
4899 After @code{GET_COMMAND_ARGUMENT} returns, the @var{VALUE} argument holds the
4900 @var{NUMBER}-th command line argument. If @var{VALUE} can not hold the argument, it is
4901 truncated to fit the length of @var{VALUE}. If there are less than @var{NUMBER}
4902 arguments specified at the command line, @var{VALUE} will be filled with blanks.
4903 If @math{@var{NUMBER} = 0}, @var{VALUE} is set to the name of the program (on
4904 systems that support this feature). The @var{LENGTH} argument contains the
4905 length of the @var{NUMBER}-th command line argument. If the argument retrieval
4906 fails, @var{STATUS} is a positive number; if @var{VALUE} contains a truncated
4907 command line argument, @var{STATUS} is -1; and otherwise the @var{STATUS} is
4910 @item @emph{Example}:
4912 PROGRAM test_get_command_argument
4914 CHARACTER(len=32) :: arg
4918 CALL get_command_argument(i, arg)
4919 IF (LEN_TRIM(arg) == 0) EXIT
4921 WRITE (*,*) TRIM(arg)
4927 @item @emph{See also}:
4928 @ref{GET_COMMAND}, @ref{COMMAND_ARGUMENT_COUNT}
4934 @section @code{GETCWD} --- Get current working directory
4936 @cindex system, working directory
4939 @item @emph{Description}:
4940 Get current working directory.
4942 This intrinsic is provided in both subroutine and function forms; however,
4943 only one form can be used in any given program unit.
4945 @item @emph{Standard}:
4949 Subroutine, function
4951 @item @emph{Syntax}:
4952 @code{CALL GETCWD(C [, STATUS])}
4954 @item @emph{Arguments}:
4955 @multitable @columnfractions .15 .70
4956 @item @var{C} @tab The type shall be @code{CHARACTER} and of default kind.
4957 @item @var{STATUS} @tab (Optional) status flag. Returns 0 on success,
4958 a system specific and nonzero error code otherwise.
4961 @item @emph{Example}:
4964 CHARACTER(len=255) :: cwd
4966 WRITE(*,*) TRIM(cwd)
4970 @item @emph{See also}:
4977 @section @code{GETENV} --- Get an environmental variable
4979 @cindex environment variable
4982 @item @emph{Description}:
4983 Get the @var{VALUE} of the environmental variable @var{NAME}.
4985 This intrinsic routine is provided for backwards compatibility with
4986 GNU Fortran 77. In new code, programmers should consider the use of
4987 the @ref{GET_ENVIRONMENT_VARIABLE} intrinsic defined by the Fortran
4990 @item @emph{Standard}:
4996 @item @emph{Syntax}:
4997 @code{CALL GETENV(NAME, VALUE)}
4999 @item @emph{Arguments}:
5000 @multitable @columnfractions .15 .70
5001 @item @var{NAME} @tab Shall be of type @code{CHARACTER} and of default kind.
5002 @item @var{VALUE} @tab Shall be of type @code{CHARACTER} and of default kind.
5005 @item @emph{Return value}:
5006 Stores the value of @var{NAME} in @var{VALUE}. If @var{VALUE} is
5007 not large enough to hold the data, it is truncated. If @var{NAME}
5008 is not set, @var{VALUE} will be filled with blanks.
5010 @item @emph{Example}:
5013 CHARACTER(len=255) :: homedir
5014 CALL getenv("HOME", homedir)
5015 WRITE (*,*) TRIM(homedir)
5019 @item @emph{See also}:
5020 @ref{GET_ENVIRONMENT_VARIABLE}
5025 @node GET_ENVIRONMENT_VARIABLE
5026 @section @code{GET_ENVIRONMENT_VARIABLE} --- Get an environmental variable
5027 @fnindex GET_ENVIRONMENT_VARIABLE
5028 @cindex environment variable
5031 @item @emph{Description}:
5032 Get the @var{VALUE} of the environmental variable @var{NAME}.
5034 @item @emph{Standard}:
5035 Fortran 2003 and later
5040 @item @emph{Syntax}:
5041 @code{CALL GET_ENVIRONMENT_VARIABLE(NAME[, VALUE, LENGTH, STATUS, TRIM_NAME)}
5043 @item @emph{Arguments}:
5044 @multitable @columnfractions .15 .70
5045 @item @var{NAME} @tab Shall be a scalar of type @code{CHARACTER}
5046 and of default kind.
5047 @item @var{VALUE} @tab Shall be a scalar of type @code{CHARACTER}
5048 and of default kind.
5049 @item @var{LENGTH} @tab Shall be a scalar of type @code{INTEGER}
5050 and of default kind.
5051 @item @var{STATUS} @tab Shall be a scalar of type @code{INTEGER}
5052 and of default kind.
5053 @item @var{TRIM_NAME} @tab Shall be a scalar of type @code{LOGICAL}
5054 and of default kind.
5057 @item @emph{Return value}:
5058 Stores the value of @var{NAME} in @var{VALUE}. If @var{VALUE} is
5059 not large enough to hold the data, it is truncated. If @var{NAME}
5060 is not set, @var{VALUE} will be filled with blanks. Argument @var{LENGTH}
5061 contains the length needed for storing the environment variable @var{NAME}
5062 or zero if it is not present. @var{STATUS} is -1 if @var{VALUE} is present
5063 but too short for the environment variable; it is 1 if the environment
5064 variable does not exist and 2 if the processor does not support environment
5065 variables; in all other cases @var{STATUS} is zero. If @var{TRIM_NAME} is
5066 present with the value @code{.FALSE.}, the trailing blanks in @var{NAME}
5067 are significant; otherwise they are not part of the environment variable
5070 @item @emph{Example}:
5073 CHARACTER(len=255) :: homedir
5074 CALL get_environment_variable("HOME", homedir)
5075 WRITE (*,*) TRIM(homedir)
5083 @section @code{GETGID} --- Group ID function
5085 @cindex system, group id
5088 @item @emph{Description}:
5089 Returns the numerical group ID of the current process.
5091 @item @emph{Standard}:
5097 @item @emph{Syntax}:
5098 @code{RESULT = GETGID()}
5100 @item @emph{Return value}:
5101 The return value of @code{GETGID} is an @code{INTEGER} of the default
5105 @item @emph{Example}:
5106 See @code{GETPID} for an example.
5108 @item @emph{See also}:
5109 @ref{GETPID}, @ref{GETUID}
5115 @section @code{GETLOG} --- Get login name
5117 @cindex system, login name
5121 @item @emph{Description}:
5122 Gets the username under which the program is running.
5124 @item @emph{Standard}:
5130 @item @emph{Syntax}:
5131 @code{CALL GETLOG(C)}
5133 @item @emph{Arguments}:
5134 @multitable @columnfractions .15 .70
5135 @item @var{C} @tab Shall be of type @code{CHARACTER} and of default kind.
5138 @item @emph{Return value}:
5139 Stores the current user name in @var{LOGIN}. (On systems where POSIX
5140 functions @code{geteuid} and @code{getpwuid} are not available, and
5141 the @code{getlogin} function is not implemented either, this will
5142 return a blank string.)
5144 @item @emph{Example}:
5147 CHARACTER(32) :: login
5153 @item @emph{See also}:
5160 @section @code{GETPID} --- Process ID function
5162 @cindex system, process id
5166 @item @emph{Description}:
5167 Returns the numerical process identifier of the current process.
5169 @item @emph{Standard}:
5175 @item @emph{Syntax}:
5176 @code{RESULT = GETPID()}
5178 @item @emph{Return value}:
5179 The return value of @code{GETPID} is an @code{INTEGER} of the default
5183 @item @emph{Example}:
5186 print *, "The current process ID is ", getpid()
5187 print *, "Your numerical user ID is ", getuid()
5188 print *, "Your numerical group ID is ", getgid()
5192 @item @emph{See also}:
5193 @ref{GETGID}, @ref{GETUID}
5199 @section @code{GETUID} --- User ID function
5201 @cindex system, user id
5205 @item @emph{Description}:
5206 Returns the numerical user ID of the current process.
5208 @item @emph{Standard}:
5214 @item @emph{Syntax}:
5215 @code{RESULT = GETUID()}
5217 @item @emph{Return value}:
5218 The return value of @code{GETUID} is an @code{INTEGER} of the default
5222 @item @emph{Example}:
5223 See @code{GETPID} for an example.
5225 @item @emph{See also}:
5226 @ref{GETPID}, @ref{GETLOG}
5232 @section @code{GMTIME} --- Convert time to GMT info
5234 @cindex time, conversion to GMT info
5237 @item @emph{Description}:
5238 Given a system time value @var{TIME} (as provided by the @code{TIME8()}
5239 intrinsic), fills @var{VALUES} with values extracted from it appropriate
5240 to the UTC time zone (Universal Coordinated Time, also known in some
5241 countries as GMT, Greenwich Mean Time), using @code{gmtime(3)}.
5243 @item @emph{Standard}:
5249 @item @emph{Syntax}:
5250 @code{CALL GMTIME(TIME, VALUES)}
5252 @item @emph{Arguments}:
5253 @multitable @columnfractions .15 .70
5254 @item @var{TIME} @tab An @code{INTEGER} scalar expression
5255 corresponding to a system time, with @code{INTENT(IN)}.
5256 @item @var{VALUES} @tab A default @code{INTEGER} array with 9 elements,
5257 with @code{INTENT(OUT)}.
5260 @item @emph{Return value}:
5261 The elements of @var{VALUES} are assigned as follows:
5263 @item Seconds after the minute, range 0--59 or 0--61 to allow for leap
5265 @item Minutes after the hour, range 0--59
5266 @item Hours past midnight, range 0--23
5267 @item Day of month, range 0--31
5268 @item Number of months since January, range 0--12
5269 @item Years since 1900
5270 @item Number of days since Sunday, range 0--6
5271 @item Days since January 1
5272 @item Daylight savings indicator: positive if daylight savings is in
5273 effect, zero if not, and negative if the information is not available.
5276 @item @emph{See also}:
5277 @ref{CTIME}, @ref{LTIME}, @ref{TIME}, @ref{TIME8}
5284 @section @code{HOSTNM} --- Get system host name
5286 @cindex system, host name
5289 @item @emph{Description}:
5290 Retrieves the host name of the system on which the program is running.
5292 This intrinsic is provided in both subroutine and function forms; however,
5293 only one form can be used in any given program unit.
5295 @item @emph{Standard}:
5299 Subroutine, function
5301 @item @emph{Syntax}:
5302 @multitable @columnfractions .80
5303 @item @code{CALL HOSTNM(C [, STATUS])}
5304 @item @code{STATUS = HOSTNM(NAME)}
5307 @item @emph{Arguments}:
5308 @multitable @columnfractions .15 .70
5309 @item @var{C} @tab Shall of type @code{CHARACTER} and of default kind.
5310 @item @var{STATUS} @tab (Optional) status flag of type @code{INTEGER}.
5311 Returns 0 on success, or a system specific error code otherwise.
5314 @item @emph{Return value}:
5315 In either syntax, @var{NAME} is set to the current hostname if it can
5316 be obtained, or to a blank string otherwise.
5323 @section @code{HUGE} --- Largest number of a kind
5325 @cindex limits, largest number
5326 @cindex model representation, largest number
5329 @item @emph{Description}:
5330 @code{HUGE(X)} returns the largest number that is not an infinity in
5331 the model of the type of @code{X}.
5333 @item @emph{Standard}:
5334 Fortran 95 and later
5339 @item @emph{Syntax}:
5340 @code{RESULT = HUGE(X)}
5342 @item @emph{Arguments}:
5343 @multitable @columnfractions .15 .70
5344 @item @var{X} @tab Shall be of type @code{REAL} or @code{INTEGER}.
5347 @item @emph{Return value}:
5348 The return value is of the same type and kind as @var{X}
5350 @item @emph{Example}:
5352 program test_huge_tiny
5353 print *, huge(0), huge(0.0), huge(0.0d0)
5354 print *, tiny(0.0), tiny(0.0d0)
5355 end program test_huge_tiny
5362 @section @code{HYPOT} --- Euclidean distance function
5364 @cindex Euclidean distance
5367 @item @emph{Description}:
5368 @code{HYPOT(X,Y)} is the Euclidean distance function. It is equal to
5369 @math{\sqrt{X^2 + Y^2}}, without undue underflow or overflow.
5371 @item @emph{Standard}:
5372 Fortran 2008 and later
5377 @item @emph{Syntax}:
5378 @code{RESULT = HYPOT(X, Y)}
5380 @item @emph{Arguments}:
5381 @multitable @columnfractions .15 .70
5382 @item @var{X} @tab The type shall be @code{REAL}.
5383 @item @var{Y} @tab The type and kind type parameter shall be the same as
5387 @item @emph{Return value}:
5388 The return value has the same type and kind type parameter as @var{X}.
5390 @item @emph{Example}:
5393 real(4) :: x = 1.e0_4, y = 0.5e0_4
5395 end program test_hypot
5402 @section @code{IACHAR} --- Code in @acronym{ASCII} collating sequence
5404 @cindex @acronym{ASCII} collating sequence
5405 @cindex collating sequence, @acronym{ASCII}
5406 @cindex conversion, to integer
5409 @item @emph{Description}:
5410 @code{IACHAR(C)} returns the code for the @acronym{ASCII} character
5411 in the first character position of @code{C}.
5413 @item @emph{Standard}:
5414 Fortran 95 and later, with @var{KIND} argument Fortran 2003 and later
5419 @item @emph{Syntax}:
5420 @code{RESULT = IACHAR(C [, KIND])}
5422 @item @emph{Arguments}:
5423 @multitable @columnfractions .15 .70
5424 @item @var{C} @tab Shall be a scalar @code{CHARACTER}, with @code{INTENT(IN)}
5425 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
5426 expression indicating the kind parameter of the result.
5429 @item @emph{Return value}:
5430 The return value is of type @code{INTEGER} and of kind @var{KIND}. If
5431 @var{KIND} is absent, the return value is of default integer kind.
5433 @item @emph{Example}:
5438 end program test_iachar
5442 See @ref{ICHAR} for a discussion of converting between numerical values
5443 and formatted string representations.
5445 @item @emph{See also}:
5446 @ref{ACHAR}, @ref{CHAR}, @ref{ICHAR}
5453 @section @code{IAND} --- Bitwise logical and
5455 @cindex bitwise logical and
5456 @cindex logical and, bitwise
5459 @item @emph{Description}:
5460 Bitwise logical @code{AND}.
5462 @item @emph{Standard}:
5463 Fortran 95 and later
5468 @item @emph{Syntax}:
5469 @code{RESULT = IAND(I, J)}
5471 @item @emph{Arguments}:
5472 @multitable @columnfractions .15 .70
5473 @item @var{I} @tab The type shall be @code{INTEGER}.
5474 @item @var{J} @tab The type shall be @code{INTEGER}, of the same
5475 kind as @var{I}. (As a GNU extension, different kinds are also
5479 @item @emph{Return value}:
5480 The return type is @code{INTEGER}, of the same kind as the
5481 arguments. (If the argument kinds differ, it is of the same kind as
5482 the larger argument.)
5484 @item @emph{Example}:
5488 DATA a / Z'F' /, b / Z'3' /
5489 WRITE (*,*) IAND(a, b)
5493 @item @emph{See also}:
5494 @ref{IOR}, @ref{IEOR}, @ref{IBITS}, @ref{IBSET}, @ref{IBCLR}, @ref{NOT}
5501 @section @code{IARGC} --- Get the number of command line arguments
5503 @cindex command-line arguments
5504 @cindex command-line arguments, number of
5505 @cindex arguments, to program
5508 @item @emph{Description}:
5509 @code{IARGC()} returns the number of arguments passed on the
5510 command line when the containing program was invoked.
5512 This intrinsic routine is provided for backwards compatibility with
5513 GNU Fortran 77. In new code, programmers should consider the use of
5514 the @ref{COMMAND_ARGUMENT_COUNT} intrinsic defined by the Fortran 2003
5517 @item @emph{Standard}:
5523 @item @emph{Syntax}:
5524 @code{RESULT = IARGC()}
5526 @item @emph{Arguments}:
5529 @item @emph{Return value}:
5530 The number of command line arguments, type @code{INTEGER(4)}.
5532 @item @emph{Example}:
5535 @item @emph{See also}:
5536 GNU Fortran 77 compatibility subroutine: @ref{GETARG}
5538 Fortran 2003 functions and subroutines: @ref{GET_COMMAND},
5539 @ref{GET_COMMAND_ARGUMENT}, @ref{COMMAND_ARGUMENT_COUNT}
5545 @section @code{IBCLR} --- Clear bit
5551 @item @emph{Description}:
5552 @code{IBCLR} returns the value of @var{I} with the bit at position
5553 @var{POS} set to zero.
5555 @item @emph{Standard}:
5556 Fortran 95 and later
5561 @item @emph{Syntax}:
5562 @code{RESULT = IBCLR(I, POS)}
5564 @item @emph{Arguments}:
5565 @multitable @columnfractions .15 .70
5566 @item @var{I} @tab The type shall be @code{INTEGER}.
5567 @item @var{POS} @tab The type shall be @code{INTEGER}.
5570 @item @emph{Return value}:
5571 The return value is of type @code{INTEGER} and of the same kind as
5574 @item @emph{See also}:
5575 @ref{IBITS}, @ref{IBSET}, @ref{IAND}, @ref{IOR}, @ref{IEOR}, @ref{MVBITS}
5582 @section @code{IBITS} --- Bit extraction
5585 @cindex bits, extract
5588 @item @emph{Description}:
5589 @code{IBITS} extracts a field of length @var{LEN} from @var{I},
5590 starting from bit position @var{POS} and extending left for @var{LEN}
5591 bits. The result is right-justified and the remaining bits are
5592 zeroed. The value of @code{POS+LEN} must be less than or equal to the
5593 value @code{BIT_SIZE(I)}.
5595 @item @emph{Standard}:
5596 Fortran 95 and later
5601 @item @emph{Syntax}:
5602 @code{RESULT = IBITS(I, POS, LEN)}
5604 @item @emph{Arguments}:
5605 @multitable @columnfractions .15 .70
5606 @item @var{I} @tab The type shall be @code{INTEGER}.
5607 @item @var{POS} @tab The type shall be @code{INTEGER}.
5608 @item @var{LEN} @tab The type shall be @code{INTEGER}.
5611 @item @emph{Return value}:
5612 The return value is of type @code{INTEGER} and of the same kind as
5615 @item @emph{See also}:
5616 @ref{BIT_SIZE}, @ref{IBCLR}, @ref{IBSET}, @ref{IAND}, @ref{IOR}, @ref{IEOR}
5622 @section @code{IBSET} --- Set bit
5627 @item @emph{Description}:
5628 @code{IBSET} returns the value of @var{I} with the bit at position
5629 @var{POS} set to one.
5631 @item @emph{Standard}:
5632 Fortran 95 and later
5637 @item @emph{Syntax}:
5638 @code{RESULT = IBSET(I, POS)}
5640 @item @emph{Arguments}:
5641 @multitable @columnfractions .15 .70
5642 @item @var{I} @tab The type shall be @code{INTEGER}.
5643 @item @var{POS} @tab The type shall be @code{INTEGER}.
5646 @item @emph{Return value}:
5647 The return value is of type @code{INTEGER} and of the same kind as
5650 @item @emph{See also}:
5651 @ref{IBCLR}, @ref{IBITS}, @ref{IAND}, @ref{IOR}, @ref{IEOR}, @ref{MVBITS}
5658 @section @code{ICHAR} --- Character-to-integer conversion function
5660 @cindex conversion, to integer
5663 @item @emph{Description}:
5664 @code{ICHAR(C)} returns the code for the character in the first character
5665 position of @code{C} in the system's native character set.
5666 The correspondence between characters and their codes is not necessarily
5667 the same across different GNU Fortran implementations.
5669 @item @emph{Standard}:
5670 Fortan 95 and later, with @var{KIND} argument Fortran 2003 and later
5675 @item @emph{Syntax}:
5676 @code{RESULT = ICHAR(C [, KIND])}
5678 @item @emph{Arguments}:
5679 @multitable @columnfractions .15 .70
5680 @item @var{C} @tab Shall be a scalar @code{CHARACTER}, with @code{INTENT(IN)}
5681 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
5682 expression indicating the kind parameter of the result.
5685 @item @emph{Return value}:
5686 The return value is of type @code{INTEGER} and of kind @var{KIND}. If
5687 @var{KIND} is absent, the return value is of default integer kind.
5689 @item @emph{Example}:
5694 end program test_ichar
5698 No intrinsic exists to convert between a numeric value and a formatted
5699 character string representation -- for instance, given the
5700 @code{CHARACTER} value @code{'154'}, obtaining an @code{INTEGER} or
5701 @code{REAL} value with the value 154, or vice versa. Instead, this
5702 functionality is provided by internal-file I/O, as in the following
5707 character(len=10) string, string2
5710 ! Convert a string to a numeric value
5711 read (string,'(I10)') value
5714 ! Convert a value to a formatted string
5715 write (string2,'(I10)') value
5717 end program read_val
5720 @item @emph{See also}:
5721 @ref{ACHAR}, @ref{CHAR}, @ref{IACHAR}
5728 @section @code{IDATE} --- Get current local time subroutine (day/month/year)
5730 @cindex date, current
5731 @cindex current date
5734 @item @emph{Description}:
5735 @code{IDATE(VALUES)} Fills @var{VALUES} with the numerical values at the
5736 current local time. The day (in the range 1-31), month (in the range 1-12),
5737 and year appear in elements 1, 2, and 3 of @var{VALUES}, respectively.
5738 The year has four significant digits.
5740 @item @emph{Standard}:
5746 @item @emph{Syntax}:
5747 @code{CALL IDATE(VALUES)}
5749 @item @emph{Arguments}:
5750 @multitable @columnfractions .15 .70
5751 @item @var{VALUES} @tab The type shall be @code{INTEGER, DIMENSION(3)} and
5752 the kind shall be the default integer kind.
5755 @item @emph{Return value}:
5756 Does not return anything.
5758 @item @emph{Example}:
5761 integer, dimension(3) :: tarray
5766 end program test_idate
5773 @section @code{IEOR} --- Bitwise logical exclusive or
5775 @cindex bitwise logical exclusive or
5776 @cindex logical exclusive or, bitwise
5779 @item @emph{Description}:
5780 @code{IEOR} returns the bitwise boolean exclusive-OR of @var{I} and
5783 @item @emph{Standard}:
5784 Fortran 95 and later
5789 @item @emph{Syntax}:
5790 @code{RESULT = IEOR(I, J)}
5792 @item @emph{Arguments}:
5793 @multitable @columnfractions .15 .70
5794 @item @var{I} @tab The type shall be @code{INTEGER}.
5795 @item @var{J} @tab The type shall be @code{INTEGER}, of the same
5796 kind as @var{I}. (As a GNU extension, different kinds are also
5800 @item @emph{Return value}:
5801 The return type is @code{INTEGER}, of the same kind as the
5802 arguments. (If the argument kinds differ, it is of the same kind as
5803 the larger argument.)
5805 @item @emph{See also}:
5806 @ref{IOR}, @ref{IAND}, @ref{IBITS}, @ref{IBSET}, @ref{IBCLR}, @ref{NOT}
5812 @section @code{IERRNO} --- Get the last system error number
5814 @cindex system, error handling
5817 @item @emph{Description}:
5818 Returns the last system error number, as given by the C @code{errno()}
5821 @item @emph{Standard}:
5827 @item @emph{Syntax}:
5828 @code{RESULT = IERRNO()}
5830 @item @emph{Arguments}:
5833 @item @emph{Return value}:
5834 The return value is of type @code{INTEGER} and of the default integer
5837 @item @emph{See also}:
5843 @node INDEX intrinsic
5844 @section @code{INDEX} --- Position of a substring within a string
5846 @cindex substring position
5847 @cindex string, find substring
5850 @item @emph{Description}:
5851 Returns the position of the start of the first occurrence of string
5852 @var{SUBSTRING} as a substring in @var{STRING}, counting from one. If
5853 @var{SUBSTRING} is not present in @var{STRING}, zero is returned. If
5854 the @var{BACK} argument is present and true, the return value is the
5855 start of the last occurrence rather than the first.
5857 @item @emph{Standard}:
5858 Fortran 77 and later, with @var{KIND} argument Fortran 2003 and later
5863 @item @emph{Syntax}:
5864 @code{RESULT = INDEX(STRING, SUBSTRING [, BACK [, KIND]])}
5866 @item @emph{Arguments}:
5867 @multitable @columnfractions .15 .70
5868 @item @var{STRING} @tab Shall be a scalar @code{CHARACTER}, with
5870 @item @var{SUBSTRING} @tab Shall be a scalar @code{CHARACTER}, with
5872 @item @var{BACK} @tab (Optional) Shall be a scalar @code{LOGICAL}, with
5874 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
5875 expression indicating the kind parameter of the result.
5878 @item @emph{Return value}:
5879 The return value is of type @code{INTEGER} and of kind @var{KIND}. If
5880 @var{KIND} is absent, the return value is of default integer kind.
5882 @item @emph{See also}:
5883 @ref{SCAN}, @ref{VERIFY}
5889 @section @code{INT} --- Convert to integer type
5893 @cindex conversion, to integer
5896 @item @emph{Description}:
5897 Convert to integer type
5899 @item @emph{Standard}:
5900 Fortran 77 and later
5905 @item @emph{Syntax}:
5906 @code{RESULT = INT(A [, KIND))}
5908 @item @emph{Arguments}:
5909 @multitable @columnfractions .15 .70
5910 @item @var{A} @tab Shall be of type @code{INTEGER},
5911 @code{REAL}, or @code{COMPLEX}.
5912 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
5913 expression indicating the kind parameter of the result.
5916 @item @emph{Return value}:
5917 These functions return a @code{INTEGER} variable or array under
5918 the following rules:
5922 If @var{A} is of type @code{INTEGER}, @code{INT(A) = A}
5924 If @var{A} is of type @code{REAL} and @math{|A| < 1}, @code{INT(A)} equals @code{0}.
5925 If @math{|A| \geq 1}, then @code{INT(A)} equals the largest integer that does not exceed
5926 the range of @var{A} and whose sign is the same as the sign of @var{A}.
5928 If @var{A} is of type @code{COMPLEX}, rule B is applied to the real part of @var{A}.
5931 @item @emph{Example}:
5935 complex :: z = (-3.7, 1.0)
5937 print *, int(z), int(z,8)
5941 @item @emph{Specific names}:
5942 @multitable @columnfractions .20 .20 .20 .25
5943 @item Name @tab Argument @tab Return type @tab Standard
5944 @item @code{IFIX(A)} @tab @code{REAL(4) A} @tab @code{INTEGER} @tab Fortran 77 and later
5945 @item @code{IDINT(A)} @tab @code{REAL(8) A} @tab @code{INTEGER} @tab Fortran 77 and later
5953 @section @code{INT2} --- Convert to 16-bit integer type
5956 @cindex conversion, to integer
5959 @item @emph{Description}:
5960 Convert to a @code{KIND=2} integer type. This is equivalent to the
5961 standard @code{INT} intrinsic with an optional argument of
5962 @code{KIND=2}, and is only included for backwards compatibility.
5964 The @code{SHORT} intrinsic is equivalent to @code{INT2}.
5966 @item @emph{Standard}:
5972 @item @emph{Syntax}:
5973 @code{RESULT = INT2(A)}
5975 @item @emph{Arguments}:
5976 @multitable @columnfractions .15 .70
5977 @item @var{A} @tab Shall be of type @code{INTEGER},
5978 @code{REAL}, or @code{COMPLEX}.
5981 @item @emph{Return value}:
5982 The return value is a @code{INTEGER(2)} variable.
5984 @item @emph{See also}:
5985 @ref{INT}, @ref{INT8}, @ref{LONG}
5991 @section @code{INT8} --- Convert to 64-bit integer type
5993 @cindex conversion, to integer
5996 @item @emph{Description}:
5997 Convert to a @code{KIND=8} integer type. This is equivalent to the
5998 standard @code{INT} intrinsic with an optional argument of
5999 @code{KIND=8}, and is only included for backwards compatibility.
6001 @item @emph{Standard}:
6007 @item @emph{Syntax}:
6008 @code{RESULT = INT8(A)}
6010 @item @emph{Arguments}:
6011 @multitable @columnfractions .15 .70
6012 @item @var{A} @tab Shall be of type @code{INTEGER},
6013 @code{REAL}, or @code{COMPLEX}.
6016 @item @emph{Return value}:
6017 The return value is a @code{INTEGER(8)} variable.
6019 @item @emph{See also}:
6020 @ref{INT}, @ref{INT2}, @ref{LONG}
6026 @section @code{IOR} --- Bitwise logical or
6028 @cindex bitwise logical or
6029 @cindex logical or, bitwise
6032 @item @emph{Description}:
6033 @code{IOR} returns the bitwise boolean inclusive-OR of @var{I} and
6036 @item @emph{Standard}:
6037 Fortran 95 and later
6042 @item @emph{Syntax}:
6043 @code{RESULT = IOR(I, J)}
6045 @item @emph{Arguments}:
6046 @multitable @columnfractions .15 .70
6047 @item @var{I} @tab The type shall be @code{INTEGER}.
6048 @item @var{J} @tab The type shall be @code{INTEGER}, of the same
6049 kind as @var{I}. (As a GNU extension, different kinds are also
6053 @item @emph{Return value}:
6054 The return type is @code{INTEGER}, of the same kind as the
6055 arguments. (If the argument kinds differ, it is of the same kind as
6056 the larger argument.)
6058 @item @emph{See also}:
6059 @ref{IEOR}, @ref{IAND}, @ref{IBITS}, @ref{IBSET}, @ref{IBCLR}, @ref{NOT}
6065 @section @code{IRAND} --- Integer pseudo-random number
6067 @cindex random number generation
6070 @item @emph{Description}:
6071 @code{IRAND(FLAG)} returns a pseudo-random number from a uniform
6072 distribution between 0 and a system-dependent limit (which is in most
6073 cases 2147483647). If @var{FLAG} is 0, the next number
6074 in the current sequence is returned; if @var{FLAG} is 1, the generator
6075 is restarted by @code{CALL SRAND(0)}; if @var{FLAG} has any other value,
6076 it is used as a new seed with @code{SRAND}.
6078 This intrinsic routine is provided for backwards compatibility with
6079 GNU Fortran 77. It implements a simple modulo generator as provided
6080 by @command{g77}. For new code, one should consider the use of
6081 @ref{RANDOM_NUMBER} as it implements a superior algorithm.
6083 @item @emph{Standard}:
6089 @item @emph{Syntax}:
6090 @code{RESULT = IRAND(I)}
6092 @item @emph{Arguments}:
6093 @multitable @columnfractions .15 .70
6094 @item @var{I} @tab Shall be a scalar @code{INTEGER} of kind 4.
6097 @item @emph{Return value}:
6098 The return value is of @code{INTEGER(kind=4)} type.
6100 @item @emph{Example}:
6103 integer,parameter :: seed = 86456
6106 print *, irand(), irand(), irand(), irand()
6107 print *, irand(seed), irand(), irand(), irand()
6108 end program test_irand
6116 @section @code{IS_IOSTAT_END} --- Test for end-of-file value
6117 @fnindex IS_IOSTAT_END
6118 @cindex IOSTAT, end of file
6121 @item @emph{Description}:
6122 @code{IS_IOSTAT_END} tests whether an variable has the value of the I/O
6123 status ``end of file''. The function is equivalent to comparing the variable
6124 with the @code{IOSTAT_END} parameter of the intrinsic module
6125 @code{ISO_FORTRAN_ENV}.
6127 @item @emph{Standard}:
6128 Fortran 2003 and later
6133 @item @emph{Syntax}:
6134 @code{RESULT = IS_IOSTAT_END(I)}
6136 @item @emph{Arguments}:
6137 @multitable @columnfractions .15 .70
6138 @item @var{I} @tab Shall be of the type @code{INTEGER}.
6141 @item @emph{Return value}:
6142 Returns a @code{LOGICAL} of the default kind, which @code{.TRUE.} if
6143 @var{I} has the value which indicates an end of file condition for
6144 IOSTAT= specifiers, and is @code{.FALSE.} otherwise.
6146 @item @emph{Example}:
6151 OPEN(88, FILE='test.dat')
6152 READ(88, *, IOSTAT=stat) i
6153 IF(IS_IOSTAT_END(stat)) STOP 'END OF FILE'
6161 @section @code{IS_IOSTAT_EOR} --- Test for end-of-record value
6162 @fnindex IS_IOSTAT_EOR
6163 @cindex IOSTAT, end of record
6166 @item @emph{Description}:
6167 @code{IS_IOSTAT_EOR} tests whether an variable has the value of the I/O
6168 status ``end of record''. The function is equivalent to comparing the
6169 variable with the @code{IOSTAT_EOR} parameter of the intrinsic module
6170 @code{ISO_FORTRAN_ENV}.
6172 @item @emph{Standard}:
6173 Fortran 2003 and later
6178 @item @emph{Syntax}:
6179 @code{RESULT = IS_IOSTAT_EOR(I)}
6181 @item @emph{Arguments}:
6182 @multitable @columnfractions .15 .70
6183 @item @var{I} @tab Shall be of the type @code{INTEGER}.
6186 @item @emph{Return value}:
6187 Returns a @code{LOGICAL} of the default kind, which @code{.TRUE.} if
6188 @var{I} has the value which indicates an end of file condition for
6189 IOSTAT= specifiers, and is @code{.FALSE.} otherwise.
6191 @item @emph{Example}:
6195 INTEGER :: stat, i(50)
6196 OPEN(88, FILE='test.dat', FORM='UNFORMATTED')
6197 READ(88, IOSTAT=stat) i
6198 IF(IS_IOSTAT_EOR(stat)) STOP 'END OF RECORD'
6206 @section @code{ISATTY} --- Whether a unit is a terminal device.
6208 @cindex system, terminal
6211 @item @emph{Description}:
6212 Determine whether a unit is connected to a terminal device.
6214 @item @emph{Standard}:
6220 @item @emph{Syntax}:
6221 @code{RESULT = ISATTY(UNIT)}
6223 @item @emph{Arguments}:
6224 @multitable @columnfractions .15 .70
6225 @item @var{UNIT} @tab Shall be a scalar @code{INTEGER}.
6228 @item @emph{Return value}:
6229 Returns @code{.TRUE.} if the @var{UNIT} is connected to a terminal
6230 device, @code{.FALSE.} otherwise.
6232 @item @emph{Example}:
6235 INTEGER(kind=1) :: unit
6237 write(*,*) isatty(unit=unit)
6241 @item @emph{See also}:
6248 @section @code{ISHFT} --- Shift bits
6253 @item @emph{Description}:
6254 @code{ISHFT} returns a value corresponding to @var{I} with all of the
6255 bits shifted @var{SHIFT} places. A value of @var{SHIFT} greater than
6256 zero corresponds to a left shift, a value of zero corresponds to no
6257 shift, and a value less than zero corresponds to a right shift. If the
6258 absolute value of @var{SHIFT} is greater than @code{BIT_SIZE(I)}, the
6259 value is undefined. Bits shifted out from the left end or right end are
6260 lost; zeros are shifted in from the opposite end.
6262 @item @emph{Standard}:
6263 Fortran 95 and later
6268 @item @emph{Syntax}:
6269 @code{RESULT = ISHFT(I, SHIFT)}
6271 @item @emph{Arguments}:
6272 @multitable @columnfractions .15 .70
6273 @item @var{I} @tab The type shall be @code{INTEGER}.
6274 @item @var{SHIFT} @tab The type shall be @code{INTEGER}.
6277 @item @emph{Return value}:
6278 The return value is of type @code{INTEGER} and of the same kind as
6281 @item @emph{See also}:
6288 @section @code{ISHFTC} --- Shift bits circularly
6290 @cindex bits, shift circular
6293 @item @emph{Description}:
6294 @code{ISHFTC} returns a value corresponding to @var{I} with the
6295 rightmost @var{SIZE} bits shifted circularly @var{SHIFT} places; that
6296 is, bits shifted out one end are shifted into the opposite end. A value
6297 of @var{SHIFT} greater than zero corresponds to a left shift, a value of
6298 zero corresponds to no shift, and a value less than zero corresponds to
6299 a right shift. The absolute value of @var{SHIFT} must be less than
6300 @var{SIZE}. If the @var{SIZE} argument is omitted, it is taken to be
6301 equivalent to @code{BIT_SIZE(I)}.
6303 @item @emph{Standard}:
6304 Fortran 95 and later
6309 @item @emph{Syntax}:
6310 @code{RESULT = ISHFTC(I, SHIFT [, SIZE])}
6312 @item @emph{Arguments}:
6313 @multitable @columnfractions .15 .70
6314 @item @var{I} @tab The type shall be @code{INTEGER}.
6315 @item @var{SHIFT} @tab The type shall be @code{INTEGER}.
6316 @item @var{SIZE} @tab (Optional) The type shall be @code{INTEGER};
6317 the value must be greater than zero and less than or equal to
6321 @item @emph{Return value}:
6322 The return value is of type @code{INTEGER} and of the same kind as
6325 @item @emph{See also}:
6332 @section @code{ISNAN} --- Test for a NaN
6337 @item @emph{Description}:
6338 @code{ISNAN} tests whether a floating-point value is an IEEE
6340 @item @emph{Standard}:
6346 @item @emph{Syntax}:
6349 @item @emph{Arguments}:
6350 @multitable @columnfractions .15 .70
6351 @item @var{X} @tab Variable of the type @code{REAL}.
6355 @item @emph{Return value}:
6356 Returns a default-kind @code{LOGICAL}. The returned value is @code{TRUE}
6357 if @var{X} is a NaN and @code{FALSE} otherwise.
6359 @item @emph{Example}:
6366 if (isnan(x)) stop '"x" is a NaN'
6367 end program test_nan
6374 @section @code{ITIME} --- Get current local time subroutine (hour/minutes/seconds)
6376 @cindex time, current
6377 @cindex current time
6380 @item @emph{Description}:
6381 @code{IDATE(VALUES)} Fills @var{VALUES} with the numerical values at the
6382 current local time. The hour (in the range 1-24), minute (in the range 1-60),
6383 and seconds (in the range 1-60) appear in elements 1, 2, and 3 of @var{VALUES},
6386 @item @emph{Standard}:
6392 @item @emph{Syntax}:
6393 @code{CALL ITIME(VALUES)}
6395 @item @emph{Arguments}:
6396 @multitable @columnfractions .15 .70
6397 @item @var{VALUES} @tab The type shall be @code{INTEGER, DIMENSION(3)}
6398 and the kind shall be the default integer kind.
6401 @item @emph{Return value}:
6402 Does not return anything.
6405 @item @emph{Example}:
6408 integer, dimension(3) :: tarray
6413 end program test_itime
6420 @section @code{KILL} --- Send a signal to a process
6424 @item @emph{Description}:
6425 @item @emph{Standard}:
6426 Sends the signal specified by @var{SIGNAL} to the process @var{PID}.
6429 This intrinsic is provided in both subroutine and function forms; however,
6430 only one form can be used in any given program unit.
6433 Subroutine, function
6435 @item @emph{Syntax}:
6436 @code{CALL KILL(C, VALUE [, STATUS])}
6438 @item @emph{Arguments}:
6439 @multitable @columnfractions .15 .70
6440 @item @var{C} @tab Shall be a scalar @code{INTEGER}, with
6442 @item @var{VALUE} @tab Shall be a scalar @code{INTEGER}, with
6444 @item @var{STATUS} @tab (Optional) status flag of type @code{INTEGER(4)} or
6445 @code{INTEGER(8)}. Returns 0 on success, or a system-specific error code
6449 @item @emph{See also}:
6450 @ref{ABORT}, @ref{EXIT}
6456 @section @code{KIND} --- Kind of an entity
6461 @item @emph{Description}:
6462 @code{KIND(X)} returns the kind value of the entity @var{X}.
6464 @item @emph{Standard}:
6465 Fortran 95 and later
6470 @item @emph{Syntax}:
6473 @item @emph{Arguments}:
6474 @multitable @columnfractions .15 .70
6475 @item @var{X} @tab Shall be of type @code{LOGICAL}, @code{INTEGER},
6476 @code{REAL}, @code{COMPLEX} or @code{CHARACTER}.
6479 @item @emph{Return value}:
6480 The return value is a scalar of type @code{INTEGER} and of the default
6483 @item @emph{Example}:
6486 integer,parameter :: kc = kind(' ')
6487 integer,parameter :: kl = kind(.true.)
6489 print *, "The default character kind is ", kc
6490 print *, "The default logical kind is ", kl
6491 end program test_kind
6499 @section @code{LBOUND} --- Lower dimension bounds of an array
6501 @cindex array, lower bound
6504 @item @emph{Description}:
6505 Returns the lower bounds of an array, or a single lower bound
6506 along the @var{DIM} dimension.
6507 @item @emph{Standard}:
6508 Fortran 95 and later, with @var{KIND} argument Fortran 2003 and later
6513 @item @emph{Syntax}:
6514 @code{RESULT = LBOUND(ARRAY [, DIM [, KIND]])}
6516 @item @emph{Arguments}:
6517 @multitable @columnfractions .15 .70
6518 @item @var{ARRAY} @tab Shall be an array, of any type.
6519 @item @var{DIM} @tab (Optional) Shall be a scalar @code{INTEGER}.
6520 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
6521 expression indicating the kind parameter of the result.
6524 @item @emph{Return value}:
6525 The return value is of type @code{INTEGER} and of kind @var{KIND}. If
6526 @var{KIND} is absent, the return value is of default integer kind.
6527 If @var{DIM} is absent, the result is an array of the lower bounds of
6528 @var{ARRAY}. If @var{DIM} is present, the result is a scalar
6529 corresponding to the lower bound of the array along that dimension. If
6530 @var{ARRAY} is an expression rather than a whole array or array
6531 structure component, or if it has a zero extent along the relevant
6532 dimension, the lower bound is taken to be 1.
6534 @item @emph{See also}:
6541 @section @code{LEADZ} --- Number of leading zero bits of an integer
6546 @item @emph{Description}:
6547 @code{LEADZ} returns the number of leading zero bits of an integer.
6549 @item @emph{Standard}:
6550 Fortran 2008 and later
6555 @item @emph{Syntax}:
6556 @code{RESULT = LEADZ(I)}
6558 @item @emph{Arguments}:
6559 @multitable @columnfractions .15 .70
6560 @item @var{I} @tab Shall be of type @code{INTEGER}.
6563 @item @emph{Return value}:
6564 The type of the return value is the default @code{INTEGER}.
6565 If all the bits of @code{I} are zero, the result value is @code{BIT_SIZE(I)}.
6567 @item @emph{Example}:
6570 WRITE (*,*) LEADZ(1) ! prints 8 if BITSIZE(I) has the value 32
6574 @item @emph{See also}:
6575 @ref{BIT_SIZE}, @ref{TRAILZ}
6581 @section @code{LEN} --- Length of a character entity
6583 @cindex string, length
6586 @item @emph{Description}:
6587 Returns the length of a character string. If @var{STRING} is an array,
6588 the length of an element of @var{STRING} is returned. Note that
6589 @var{STRING} need not be defined when this intrinsic is invoked, since
6590 only the length, not the content, of @var{STRING} is needed.
6592 @item @emph{Standard}:
6593 Fortran 77 and later, with @var{KIND} argument Fortran 2003 and later
6598 @item @emph{Syntax}:
6599 @code{L = LEN(STRING [, KIND])}
6601 @item @emph{Arguments}:
6602 @multitable @columnfractions .15 .70
6603 @item @var{STRING} @tab Shall be a scalar or array of type
6604 @code{CHARACTER}, with @code{INTENT(IN)}
6605 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
6606 expression indicating the kind parameter of the result.
6609 @item @emph{Return value}:
6610 The return value is of type @code{INTEGER} and of kind @var{KIND}. If
6611 @var{KIND} is absent, the return value is of default integer kind.
6613 @item @emph{See also}:
6614 @ref{LEN_TRIM}, @ref{ADJUSTL}, @ref{ADJUSTR}
6620 @section @code{LEN_TRIM} --- Length of a character entity without trailing blank characters
6622 @cindex string, length, without trailing whitespace
6625 @item @emph{Description}:
6626 Returns the length of a character string, ignoring any trailing blanks.
6628 @item @emph{Standard}:
6629 Fortran 95 and later, with @var{KIND} argument Fortran 2003 and later
6634 @item @emph{Syntax}:
6635 @code{RESULT = LEN_TRIM(STRING [, KIND])}
6637 @item @emph{Arguments}:
6638 @multitable @columnfractions .15 .70
6639 @item @var{STRING} @tab Shall be a scalar of type @code{CHARACTER},
6640 with @code{INTENT(IN)}
6641 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
6642 expression indicating the kind parameter of the result.
6645 @item @emph{Return value}:
6646 The return value is of type @code{INTEGER} and of kind @var{KIND}. If
6647 @var{KIND} is absent, the return value is of default integer kind.
6649 @item @emph{See also}:
6650 @ref{LEN}, @ref{ADJUSTL}, @ref{ADJUSTR}
6656 @section @code{LGE} --- Lexical greater than or equal
6658 @cindex lexical comparison of strings
6659 @cindex string, comparison
6662 @item @emph{Description}:
6663 Determines whether one string is lexically greater than or equal to
6664 another string, where the two strings are interpreted as containing
6665 ASCII character codes. If the String A and String B are not the same
6666 length, the shorter is compared as if spaces were appended to it to form
6667 a value that has the same length as the longer.
6669 In general, the lexical comparison intrinsics @code{LGE}, @code{LGT},
6670 @code{LLE}, and @code{LLT} differ from the corresponding intrinsic
6671 operators @code{.GE.}, @code{.GT.}, @code{.LE.}, and @code{.LT.}, in
6672 that the latter use the processor's character ordering (which is not
6673 ASCII on some targets), whereas the former always use the ASCII
6676 @item @emph{Standard}:
6677 Fortran 77 and later
6682 @item @emph{Syntax}:
6683 @code{RESULT = LGE(STRING_A, STRING_B)}
6685 @item @emph{Arguments}:
6686 @multitable @columnfractions .15 .70
6687 @item @var{STRING_A} @tab Shall be of default @code{CHARACTER} type.
6688 @item @var{STRING_B} @tab Shall be of default @code{CHARACTER} type.
6691 @item @emph{Return value}:
6692 Returns @code{.TRUE.} if @code{STRING_A >= STRING_B}, and @code{.FALSE.}
6693 otherwise, based on the ASCII ordering.
6695 @item @emph{See also}:
6696 @ref{LGT}, @ref{LLE}, @ref{LLT}
6702 @section @code{LGT} --- Lexical greater than
6704 @cindex lexical comparison of strings
6705 @cindex string, comparison
6708 @item @emph{Description}:
6709 Determines whether one string is lexically greater than another string,
6710 where the two strings are interpreted as containing ASCII character
6711 codes. If the String A and String B are not the same length, the
6712 shorter is compared as if spaces were appended to it to form a value
6713 that has the same length as the longer.
6715 In general, the lexical comparison intrinsics @code{LGE}, @code{LGT},
6716 @code{LLE}, and @code{LLT} differ from the corresponding intrinsic
6717 operators @code{.GE.}, @code{.GT.}, @code{.LE.}, and @code{.LT.}, in
6718 that the latter use the processor's character ordering (which is not
6719 ASCII on some targets), whereas the former always use the ASCII
6722 @item @emph{Standard}:
6723 Fortran 77 and later
6728 @item @emph{Syntax}:
6729 @code{RESULT = LGT(STRING_A, STRING_B)}
6731 @item @emph{Arguments}:
6732 @multitable @columnfractions .15 .70
6733 @item @var{STRING_A} @tab Shall be of default @code{CHARACTER} type.
6734 @item @var{STRING_B} @tab Shall be of default @code{CHARACTER} type.
6737 @item @emph{Return value}:
6738 Returns @code{.TRUE.} if @code{STRING_A > STRING_B}, and @code{.FALSE.}
6739 otherwise, based on the ASCII ordering.
6741 @item @emph{See also}:
6742 @ref{LGE}, @ref{LLE}, @ref{LLT}
6748 @section @code{LINK} --- Create a hard link
6750 @cindex file system, create link
6751 @cindex file system, hard link
6754 @item @emph{Description}:
6755 Makes a (hard) link from file @var{PATH1} to @var{PATH2}. A null
6756 character (@code{CHAR(0)}) can be used to mark the end of the names in
6757 @var{PATH1} and @var{PATH2}; otherwise, trailing blanks in the file
6758 names are ignored. If the @var{STATUS} argument is supplied, it
6759 contains 0 on success or a nonzero error code upon return; see
6762 This intrinsic is provided in both subroutine and function forms;
6763 however, only one form can be used in any given program unit.
6765 @item @emph{Standard}:
6769 Subroutine, function
6771 @item @emph{Syntax}:
6772 @multitable @columnfractions .80
6773 @item @code{CALL LINK(PATH1, PATH2 [, STATUS])}
6774 @item @code{STATUS = LINK(PATH1, PATH2)}
6777 @item @emph{Arguments}:
6778 @multitable @columnfractions .15 .70
6779 @item @var{PATH1} @tab Shall be of default @code{CHARACTER} type.
6780 @item @var{PATH2} @tab Shall be of default @code{CHARACTER} type.
6781 @item @var{STATUS} @tab (Optional) Shall be of default @code{INTEGER} type.
6784 @item @emph{See also}:
6785 @ref{SYMLNK}, @ref{UNLINK}
6791 @section @code{LLE} --- Lexical less than or equal
6793 @cindex lexical comparison of strings
6794 @cindex string, comparison
6797 @item @emph{Description}:
6798 Determines whether one string is lexically less than or equal to another
6799 string, where the two strings are interpreted as containing ASCII
6800 character codes. If the String A and String B are not the same length,
6801 the shorter is compared as if spaces were appended to it to form a value
6802 that has the same length as the longer.
6804 In general, the lexical comparison intrinsics @code{LGE}, @code{LGT},
6805 @code{LLE}, and @code{LLT} differ from the corresponding intrinsic
6806 operators @code{.GE.}, @code{.GT.}, @code{.LE.}, and @code{.LT.}, in
6807 that the latter use the processor's character ordering (which is not
6808 ASCII on some targets), whereas the former always use the ASCII
6811 @item @emph{Standard}:
6812 Fortran 77 and later
6817 @item @emph{Syntax}:
6818 @code{RESULT = LLE(STRING_A, STRING_B)}
6820 @item @emph{Arguments}:
6821 @multitable @columnfractions .15 .70
6822 @item @var{STRING_A} @tab Shall be of default @code{CHARACTER} type.
6823 @item @var{STRING_B} @tab Shall be of default @code{CHARACTER} type.
6826 @item @emph{Return value}:
6827 Returns @code{.TRUE.} if @code{STRING_A <= STRING_B}, and @code{.FALSE.}
6828 otherwise, based on the ASCII ordering.
6830 @item @emph{See also}:
6831 @ref{LGE}, @ref{LGT}, @ref{LLT}
6837 @section @code{LLT} --- Lexical less than
6839 @cindex lexical comparison of strings
6840 @cindex string, comparison
6843 @item @emph{Description}:
6844 Determines whether one string is lexically less than another string,
6845 where the two strings are interpreted as containing ASCII character
6846 codes. If the String A and String B are not the same length, the
6847 shorter is compared as if spaces were appended to it to form a value
6848 that has the same length as the longer.
6850 In general, the lexical comparison intrinsics @code{LGE}, @code{LGT},
6851 @code{LLE}, and @code{LLT} differ from the corresponding intrinsic
6852 operators @code{.GE.}, @code{.GT.}, @code{.LE.}, and @code{.LT.}, in
6853 that the latter use the processor's character ordering (which is not
6854 ASCII on some targets), whereas the former always use the ASCII
6857 @item @emph{Standard}:
6858 Fortran 77 and later
6863 @item @emph{Syntax}:
6864 @code{RESULT = LLT(STRING_A, STRING_B)}
6866 @item @emph{Arguments}:
6867 @multitable @columnfractions .15 .70
6868 @item @var{STRING_A} @tab Shall be of default @code{CHARACTER} type.
6869 @item @var{STRING_B} @tab Shall be of default @code{CHARACTER} type.
6872 @item @emph{Return value}:
6873 Returns @code{.TRUE.} if @code{STRING_A < STRING_B}, and @code{.FALSE.}
6874 otherwise, based on the ASCII ordering.
6876 @item @emph{See also}:
6877 @ref{LGE}, @ref{LGT}, @ref{LLE}
6883 @section @code{LNBLNK} --- Index of the last non-blank character in a string
6885 @cindex string, find non-blank character
6888 @item @emph{Description}:
6889 Returns the length of a character string, ignoring any trailing blanks.
6890 This is identical to the standard @code{LEN_TRIM} intrinsic, and is only
6891 included for backwards compatibility.
6893 @item @emph{Standard}:
6899 @item @emph{Syntax}:
6900 @code{RESULT = LNBLNK(STRING)}
6902 @item @emph{Arguments}:
6903 @multitable @columnfractions .15 .70
6904 @item @var{STRING} @tab Shall be a scalar of type @code{CHARACTER},
6905 with @code{INTENT(IN)}
6908 @item @emph{Return value}:
6909 The return value is of @code{INTEGER(kind=4)} type.
6911 @item @emph{See also}:
6912 @ref{INDEX intrinsic}, @ref{LEN_TRIM}
6918 @section @code{LOC} --- Returns the address of a variable
6920 @cindex location of a variable in memory
6923 @item @emph{Description}:
6924 @code{LOC(X)} returns the address of @var{X} as an integer.
6926 @item @emph{Standard}:
6932 @item @emph{Syntax}:
6933 @code{RESULT = LOC(X)}
6935 @item @emph{Arguments}:
6936 @multitable @columnfractions .15 .70
6937 @item @var{X} @tab Variable of any type.
6940 @item @emph{Return value}:
6941 The return value is of type @code{INTEGER}, with a @code{KIND}
6942 corresponding to the size (in bytes) of a memory address on the target
6945 @item @emph{Example}:
6952 end program test_loc
6959 @section @code{LOG} --- Logarithm function
6966 @cindex exponential function, inverse
6967 @cindex logarithmic function
6970 @item @emph{Description}:
6971 @code{LOG(X)} computes the logarithm of @var{X}.
6973 @item @emph{Standard}:
6974 Fortran 77 and later
6979 @item @emph{Syntax}:
6980 @code{RESULT = LOG(X)}
6982 @item @emph{Arguments}:
6983 @multitable @columnfractions .15 .70
6984 @item @var{X} @tab The type shall be @code{REAL} or
6988 @item @emph{Return value}:
6989 The return value is of type @code{REAL} or @code{COMPLEX}.
6990 The kind type parameter is the same as @var{X}.
6991 If @var{X} is @code{COMPLEX}, the imaginary part @math{\omega} is in the range
6992 @math{-\pi \leq \omega \leq \pi}.
6994 @item @emph{Example}:
6997 real(8) :: x = 1.0_8
6998 complex :: z = (1.0, 2.0)
7001 end program test_log
7004 @item @emph{Specific names}:
7005 @multitable @columnfractions .20 .20 .20 .25
7006 @item Name @tab Argument @tab Return type @tab Standard
7007 @item @code{ALOG(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab f95, gnu
7008 @item @code{DLOG(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab f95, gnu
7009 @item @code{CLOG(X)} @tab @code{COMPLEX(4) X} @tab @code{COMPLEX(4)} @tab f95, gnu
7010 @item @code{ZLOG(X)} @tab @code{COMPLEX(8) X} @tab @code{COMPLEX(8)} @tab f95, gnu
7011 @item @code{CDLOG(X)} @tab @code{COMPLEX(8) X} @tab @code{COMPLEX(8)} @tab f95, gnu
7018 @section @code{LOG10} --- Base 10 logarithm function
7022 @cindex exponential function, inverse
7023 @cindex logarithmic function
7026 @item @emph{Description}:
7027 @code{LOG10(X)} computes the base 10 logarithm of @var{X}.
7029 @item @emph{Standard}:
7030 Fortran 77 and later
7035 @item @emph{Syntax}:
7036 @code{RESULT = LOG10(X)}
7038 @item @emph{Arguments}:
7039 @multitable @columnfractions .15 .70
7040 @item @var{X} @tab The type shall be @code{REAL}.
7043 @item @emph{Return value}:
7044 The return value is of type @code{REAL} or @code{COMPLEX}.
7045 The kind type parameter is the same as @var{X}.
7047 @item @emph{Example}:
7050 real(8) :: x = 10.0_8
7052 end program test_log10
7055 @item @emph{Specific names}:
7056 @multitable @columnfractions .20 .20 .20 .25
7057 @item Name @tab Argument @tab Return type @tab Standard
7058 @item @code{ALOG10(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab Fortran 95 and later
7059 @item @code{DLOG10(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab Fortran 95 and later
7066 @section @code{LOG_GAMMA} --- Logarithm of the Gamma function
7071 @cindex Gamma function, logarithm of
7074 @item @emph{Description}:
7075 @code{LOG_GAMMA(X)} computes the natural logarithm of the absolute value
7076 of the Gamma (@math{\Gamma}) function.
7078 @item @emph{Standard}:
7079 Fortran 2008 and later
7084 @item @emph{Syntax}:
7085 @code{X = LOG_GAMMA(X)}
7087 @item @emph{Arguments}:
7088 @multitable @columnfractions .15 .70
7089 @item @var{X} @tab Shall be of type @code{REAL} and neither zero
7090 nor a negative integer.
7093 @item @emph{Return value}:
7094 The return value is of type @code{REAL} of the same kind as @var{X}.
7096 @item @emph{Example}:
7098 program test_log_gamma
7100 x = lgamma(x) ! returns 0.0
7101 end program test_log_gamma
7104 @item @emph{Specific names}:
7105 @multitable @columnfractions .20 .20 .20 .25
7106 @item Name @tab Argument @tab Return type @tab Standard
7107 @item @code{LGAMMA(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab GNU Extension
7108 @item @code{ALGAMA(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab GNU Extension
7109 @item @code{DLGAMA(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU Extension
7112 @item @emph{See also}:
7113 Gamma function: @ref{GAMMA}
7120 @section @code{LOGICAL} --- Convert to logical type
7122 @cindex conversion, to logical
7125 @item @emph{Description}:
7126 Converts one kind of @code{LOGICAL} variable to another.
7128 @item @emph{Standard}:
7129 Fortran 95 and later
7134 @item @emph{Syntax}:
7135 @code{RESULT = LOGICAL(L [, KIND])}
7137 @item @emph{Arguments}:
7138 @multitable @columnfractions .15 .70
7139 @item @var{L} @tab The type shall be @code{LOGICAL}.
7140 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
7141 expression indicating the kind parameter of the result.
7144 @item @emph{Return value}:
7145 The return value is a @code{LOGICAL} value equal to @var{L}, with a
7146 kind corresponding to @var{KIND}, or of the default logical kind if
7147 @var{KIND} is not given.
7149 @item @emph{See also}:
7150 @ref{INT}, @ref{REAL}, @ref{CMPLX}
7156 @section @code{LONG} --- Convert to integer type
7158 @cindex conversion, to integer
7161 @item @emph{Description}:
7162 Convert to a @code{KIND=4} integer type, which is the same size as a C
7163 @code{long} integer. This is equivalent to the standard @code{INT}
7164 intrinsic with an optional argument of @code{KIND=4}, and is only
7165 included for backwards compatibility.
7167 @item @emph{Standard}:
7173 @item @emph{Syntax}:
7174 @code{RESULT = LONG(A)}
7176 @item @emph{Arguments}:
7177 @multitable @columnfractions .15 .70
7178 @item @var{A} @tab Shall be of type @code{INTEGER},
7179 @code{REAL}, or @code{COMPLEX}.
7182 @item @emph{Return value}:
7183 The return value is a @code{INTEGER(4)} variable.
7185 @item @emph{See also}:
7186 @ref{INT}, @ref{INT2}, @ref{INT8}
7192 @section @code{LSHIFT} --- Left shift bits
7194 @cindex bits, shift left
7197 @item @emph{Description}:
7198 @code{LSHIFT} returns a value corresponding to @var{I} with all of the
7199 bits shifted left by @var{SHIFT} places. If the absolute value of
7200 @var{SHIFT} is greater than @code{BIT_SIZE(I)}, the value is undefined.
7201 Bits shifted out from the left end are lost; zeros are shifted in from
7204 This function has been superseded by the @code{ISHFT} intrinsic, which
7205 is standard in Fortran 95 and later.
7207 @item @emph{Standard}:
7213 @item @emph{Syntax}:
7214 @code{RESULT = LSHIFT(I, SHIFT)}
7216 @item @emph{Arguments}:
7217 @multitable @columnfractions .15 .70
7218 @item @var{I} @tab The type shall be @code{INTEGER}.
7219 @item @var{SHIFT} @tab The type shall be @code{INTEGER}.
7222 @item @emph{Return value}:
7223 The return value is of type @code{INTEGER} and of the same kind as
7226 @item @emph{See also}:
7227 @ref{ISHFT}, @ref{ISHFTC}, @ref{RSHIFT}
7234 @section @code{LSTAT} --- Get file status
7236 @cindex file system, file status
7239 @item @emph{Description}:
7240 @code{LSTAT} is identical to @ref{STAT}, except that if path is a
7241 symbolic link, then the link itself is statted, not the file that it
7244 The elements in @code{VALUES} are the same as described by @ref{STAT}.
7246 This intrinsic is provided in both subroutine and function forms;
7247 however, only one form can be used in any given program unit.
7249 @item @emph{Standard}:
7253 Subroutine, function
7255 @item @emph{Syntax}:
7256 @code{CALL LSTAT(NAME, VALUES [, STATUS])}
7258 @item @emph{Arguments}:
7259 @multitable @columnfractions .15 .70
7260 @item @var{NAME} @tab The type shall be @code{CHARACTER} of the default
7261 kind, a valid path within the file system.
7262 @item @var{VALUES} @tab The type shall be @code{INTEGER(4), DIMENSION(13)}.
7263 @item @var{STATUS} @tab (Optional) status flag of type @code{INTEGER(4)}.
7264 Returns 0 on success and a system specific error code otherwise.
7267 @item @emph{Example}:
7268 See @ref{STAT} for an example.
7270 @item @emph{See also}:
7271 To stat an open file: @ref{FSTAT}, to stat a file: @ref{STAT}
7277 @section @code{LTIME} --- Convert time to local time info
7279 @cindex time, conversion to local time info
7282 @item @emph{Description}:
7283 Given a system time value @var{TIME} (as provided by the @code{TIME8()}
7284 intrinsic), fills @var{VALUES} with values extracted from it appropriate
7285 to the local time zone using @code{localtime(3)}.
7287 @item @emph{Standard}:
7293 @item @emph{Syntax}:
7294 @code{CALL LTIME(TIME, VALUES)}
7296 @item @emph{Arguments}:
7297 @multitable @columnfractions .15 .70
7298 @item @var{TIME} @tab An @code{INTEGER} scalar expression
7299 corresponding to a system time, with @code{INTENT(IN)}.
7300 @item @var{VALUES} @tab A default @code{INTEGER} array with 9 elements,
7301 with @code{INTENT(OUT)}.
7304 @item @emph{Return value}:
7305 The elements of @var{VALUES} are assigned as follows:
7307 @item Seconds after the minute, range 0--59 or 0--61 to allow for leap
7309 @item Minutes after the hour, range 0--59
7310 @item Hours past midnight, range 0--23
7311 @item Day of month, range 0--31
7312 @item Number of months since January, range 0--12
7313 @item Years since 1900
7314 @item Number of days since Sunday, range 0--6
7315 @item Days since January 1
7316 @item Daylight savings indicator: positive if daylight savings is in
7317 effect, zero if not, and negative if the information is not available.
7320 @item @emph{See also}:
7321 @ref{CTIME}, @ref{GMTIME}, @ref{TIME}, @ref{TIME8}
7328 @section @code{MALLOC} --- Allocate dynamic memory
7330 @cindex pointer, cray
7333 @item @emph{Description}:
7334 @code{MALLOC(SIZE)} allocates @var{SIZE} bytes of dynamic memory and
7335 returns the address of the allocated memory. The @code{MALLOC} intrinsic
7336 is an extension intended to be used with Cray pointers, and is provided
7337 in GNU Fortran to allow the user to compile legacy code. For new code
7338 using Fortran 95 pointers, the memory allocation intrinsic is
7341 @item @emph{Standard}:
7347 @item @emph{Syntax}:
7348 @code{PTR = MALLOC(SIZE)}
7350 @item @emph{Arguments}:
7351 @multitable @columnfractions .15 .70
7352 @item @var{SIZE} @tab The type shall be @code{INTEGER}.
7355 @item @emph{Return value}:
7356 The return value is of type @code{INTEGER(K)}, with @var{K} such that
7357 variables of type @code{INTEGER(K)} have the same size as
7358 C pointers (@code{sizeof(void *)}).
7360 @item @emph{Example}:
7361 The following example demonstrates the use of @code{MALLOC} and
7362 @code{FREE} with Cray pointers.
7371 ptr_x = malloc(20*8)
7373 x(i) = sqrt(1.0d0 / i)
7381 end program test_malloc
7384 @item @emph{See also}:
7391 @section @code{MATMUL} --- matrix multiplication
7393 @cindex matrix multiplication
7394 @cindex product, matrix
7397 @item @emph{Description}:
7398 Performs a matrix multiplication on numeric or logical arguments.
7400 @item @emph{Standard}:
7401 Fortran 95 and later
7404 Transformational function
7406 @item @emph{Syntax}:
7407 @code{RESULT = MATMUL(MATRIX_A, MATRIX_B)}
7409 @item @emph{Arguments}:
7410 @multitable @columnfractions .15 .70
7411 @item @var{MATRIX_A} @tab An array of @code{INTEGER},
7412 @code{REAL}, @code{COMPLEX}, or @code{LOGICAL} type, with a rank of
7414 @item @var{MATRIX_B} @tab An array of @code{INTEGER},
7415 @code{REAL}, or @code{COMPLEX} type if @var{MATRIX_A} is of a numeric
7416 type; otherwise, an array of @code{LOGICAL} type. The rank shall be one
7417 or two, and the first (or only) dimension of @var{MATRIX_B} shall be
7418 equal to the last (or only) dimension of @var{MATRIX_A}.
7421 @item @emph{Return value}:
7422 The matrix product of @var{MATRIX_A} and @var{MATRIX_B}. The type and
7423 kind of the result follow the usual type and kind promotion rules, as
7424 for the @code{*} or @code{.AND.} operators.
7426 @item @emph{See also}:
7432 @section @code{MAX} --- Maximum value of an argument list
7439 @cindex maximum value
7442 @item @emph{Description}:
7443 Returns the argument with the largest (most positive) value.
7445 @item @emph{Standard}:
7446 Fortran 77 and later
7451 @item @emph{Syntax}:
7452 @code{RESULT = MAX(A1, A2 [, A3 [, ...]])}
7454 @item @emph{Arguments}:
7455 @multitable @columnfractions .15 .70
7456 @item @var{A1} @tab The type shall be @code{INTEGER} or
7458 @item @var{A2}, @var{A3}, ... @tab An expression of the same type and kind
7459 as @var{A1}. (As a GNU extension, arguments of different kinds are
7463 @item @emph{Return value}:
7464 The return value corresponds to the maximum value among the arguments,
7465 and has the same type and kind as the first argument.
7467 @item @emph{Specific names}:
7468 @multitable @columnfractions .20 .20 .20 .25
7469 @item Name @tab Argument @tab Return type @tab Standard
7470 @item @code{MAX0(I)} @tab @code{INTEGER(4) I} @tab @code{INTEGER(4)} @tab Fortran 77 and later
7471 @item @code{AMAX0(I)} @tab @code{INTEGER(4) I} @tab @code{REAL(MAX(X))} @tab Fortran 77 and later
7472 @item @code{MAX1(X)} @tab @code{REAL X} @tab @code{INT(MAX(X))} @tab Fortran 77 and later
7473 @item @code{AMAX1(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab Fortran 77 and later
7474 @item @code{DMAX1(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab Fortran 77 and later
7477 @item @emph{See also}:
7478 @ref{MAXLOC} @ref{MAXVAL}, @ref{MIN}
7485 @section @code{MAXEXPONENT} --- Maximum exponent of a real kind
7486 @fnindex MAXEXPONENT
7487 @cindex model representation, maximum exponent
7490 @item @emph{Description}:
7491 @code{MAXEXPONENT(X)} returns the maximum exponent in the model of the
7494 @item @emph{Standard}:
7495 Fortran 95 and later
7500 @item @emph{Syntax}:
7501 @code{RESULT = MAXEXPONENT(X)}
7503 @item @emph{Arguments}:
7504 @multitable @columnfractions .15 .70
7505 @item @var{X} @tab Shall be of type @code{REAL}.
7508 @item @emph{Return value}:
7509 The return value is of type @code{INTEGER} and of the default integer
7512 @item @emph{Example}:
7518 print *, minexponent(x), maxexponent(x)
7519 print *, minexponent(y), maxexponent(y)
7520 end program exponents
7527 @section @code{MAXLOC} --- Location of the maximum value within an array
7529 @cindex array, location of maximum element
7532 @item @emph{Description}:
7533 Determines the location of the element in the array with the maximum
7534 value, or, if the @var{DIM} argument is supplied, determines the
7535 locations of the maximum element along each row of the array in the
7536 @var{DIM} direction. If @var{MASK} is present, only the elements for
7537 which @var{MASK} is @code{.TRUE.} are considered. If more than one
7538 element in the array has the maximum value, the location returned is
7539 that of the first such element in array element order. If the array has
7540 zero size, or all of the elements of @var{MASK} are @code{.FALSE.}, then
7541 the result is an array of zeroes. Similarly, if @var{DIM} is supplied
7542 and all of the elements of @var{MASK} along a given row are zero, the
7543 result value for that row is zero.
7545 @item @emph{Standard}:
7546 Fortran 95 and later
7549 Transformational function
7551 @item @emph{Syntax}:
7552 @multitable @columnfractions .80
7553 @item @code{RESULT = MAXLOC(ARRAY, DIM [, MASK])}
7554 @item @code{RESULT = MAXLOC(ARRAY [, MASK])}
7557 @item @emph{Arguments}:
7558 @multitable @columnfractions .15 .70
7559 @item @var{ARRAY} @tab Shall be an array of type @code{INTEGER},
7560 @code{REAL}, or @code{CHARACTER}.
7561 @item @var{DIM} @tab (Optional) Shall be a scalar of type
7562 @code{INTEGER}, with a value between one and the rank of @var{ARRAY},
7563 inclusive. It may not be an optional dummy argument.
7564 @item @var{MASK} @tab Shall be an array of type @code{LOGICAL},
7565 and conformable with @var{ARRAY}.
7568 @item @emph{Return value}:
7569 If @var{DIM} is absent, the result is a rank-one array with a length
7570 equal to the rank of @var{ARRAY}. If @var{DIM} is present, the result
7571 is an array with a rank one less than the rank of @var{ARRAY}, and a
7572 size corresponding to the size of @var{ARRAY} with the @var{DIM}
7573 dimension removed. If @var{DIM} is present and @var{ARRAY} has a rank
7574 of one, the result is a scalar. In all cases, the result is of default
7575 @code{INTEGER} type.
7577 @item @emph{See also}:
7578 @ref{MAX}, @ref{MAXVAL}
7585 @section @code{MAXVAL} --- Maximum value of an array
7587 @cindex array, maximum value
7588 @cindex maximum value
7591 @item @emph{Description}:
7592 Determines the maximum value of the elements in an array value, or, if
7593 the @var{DIM} argument is supplied, determines the maximum value along
7594 each row of the array in the @var{DIM} direction. If @var{MASK} is
7595 present, only the elements for which @var{MASK} is @code{.TRUE.} are
7596 considered. If the array has zero size, or all of the elements of
7597 @var{MASK} are @code{.FALSE.}, then the result is @code{-HUGE(ARRAY)}
7598 if @var{ARRAY} is numeric, or a string of nulls if @var{ARRAY} is of character
7601 @item @emph{Standard}:
7602 Fortran 95 and later
7605 Transformational function
7607 @item @emph{Syntax}:
7608 @multitable @columnfractions .80
7609 @item @code{RESULT = MAXVAL(ARRAY, DIM [, MASK])}
7610 @item @code{RESULT = MAXVAL(ARRAY [, MASK])}
7613 @item @emph{Arguments}:
7614 @multitable @columnfractions .15 .70
7615 @item @var{ARRAY} @tab Shall be an array of type @code{INTEGER},
7616 @code{REAL}, or @code{CHARACTER}.
7617 @item @var{DIM} @tab (Optional) Shall be a scalar of type
7618 @code{INTEGER}, with a value between one and the rank of @var{ARRAY},
7619 inclusive. It may not be an optional dummy argument.
7620 @item @var{MASK} @tab Shall be an array of type @code{LOGICAL},
7621 and conformable with @var{ARRAY}.
7624 @item @emph{Return value}:
7625 If @var{DIM} is absent, or if @var{ARRAY} has a rank of one, the result
7626 is a scalar. If @var{DIM} is present, the result is an array with a
7627 rank one less than the rank of @var{ARRAY}, and a size corresponding to
7628 the size of @var{ARRAY} with the @var{DIM} dimension removed. In all
7629 cases, the result is of the same type and kind as @var{ARRAY}.
7631 @item @emph{See also}:
7632 @ref{MAX}, @ref{MAXLOC}
7638 @section @code{MCLOCK} --- Time function
7640 @cindex time, clock ticks
7644 @item @emph{Description}:
7645 Returns the number of clock ticks since the start of the process, based
7646 on the UNIX function @code{clock(3)}.
7648 This intrinsic is not fully portable, such as to systems with 32-bit
7649 @code{INTEGER} types but supporting times wider than 32 bits. Therefore,
7650 the values returned by this intrinsic might be, or become, negative, or
7651 numerically less than previous values, during a single run of the
7654 @item @emph{Standard}:
7660 @item @emph{Syntax}:
7661 @code{RESULT = MCLOCK()}
7663 @item @emph{Return value}:
7664 The return value is a scalar of type @code{INTEGER(4)}, equal to the
7665 number of clock ticks since the start of the process, or @code{-1} if
7666 the system does not support @code{clock(3)}.
7668 @item @emph{See also}:
7669 @ref{CTIME}, @ref{GMTIME}, @ref{LTIME}, @ref{MCLOCK}, @ref{TIME}
7676 @section @code{MCLOCK8} --- Time function (64-bit)
7678 @cindex time, clock ticks
7682 @item @emph{Description}:
7683 Returns the number of clock ticks since the start of the process, based
7684 on the UNIX function @code{clock(3)}.
7686 @emph{Warning:} this intrinsic does not increase the range of the timing
7687 values over that returned by @code{clock(3)}. On a system with a 32-bit
7688 @code{clock(3)}, @code{MCLOCK8()} will return a 32-bit value, even though
7689 it is converted to a 64-bit @code{INTEGER(8)} value. That means
7690 overflows of the 32-bit value can still occur. Therefore, the values
7691 returned by this intrinsic might be or become negative or numerically
7692 less than previous values during a single run of the compiled program.
7694 @item @emph{Standard}:
7700 @item @emph{Syntax}:
7701 @code{RESULT = MCLOCK8()}
7703 @item @emph{Return value}:
7704 The return value is a scalar of type @code{INTEGER(8)}, equal to the
7705 number of clock ticks since the start of the process, or @code{-1} if
7706 the system does not support @code{clock(3)}.
7708 @item @emph{See also}:
7709 @ref{CTIME}, @ref{GMTIME}, @ref{LTIME}, @ref{MCLOCK}, @ref{TIME8}
7716 @section @code{MERGE} --- Merge variables
7718 @cindex array, merge arrays
7719 @cindex array, combine arrays
7722 @item @emph{Description}:
7723 Select values from two arrays according to a logical mask. The result
7724 is equal to @var{TSOURCE} if @var{MASK} is @code{.TRUE.}, or equal to
7725 @var{FSOURCE} if it is @code{.FALSE.}.
7727 @item @emph{Standard}:
7728 Fortran 95 and later
7733 @item @emph{Syntax}:
7734 @code{RESULT = MERGE(TSOURCE, FSOURCE, MASK)}
7736 @item @emph{Arguments}:
7737 @multitable @columnfractions .15 .70
7738 @item @var{TSOURCE} @tab May be of any type.
7739 @item @var{FSOURCE} @tab Shall be of the same type and type parameters
7741 @item @var{MASK} @tab Shall be of type @code{LOGICAL}.
7744 @item @emph{Return value}:
7745 The result is of the same type and type parameters as @var{TSOURCE}.
7752 @section @code{MIN} --- Minimum value of an argument list
7759 @cindex minimum value
7762 @item @emph{Description}:
7763 Returns the argument with the smallest (most negative) value.
7765 @item @emph{Standard}:
7766 Fortran 77 and later
7771 @item @emph{Syntax}:
7772 @code{RESULT = MIN(A1, A2 [, A3, ...])}
7774 @item @emph{Arguments}:
7775 @multitable @columnfractions .15 .70
7776 @item @var{A1} @tab The type shall be @code{INTEGER} or
7778 @item @var{A2}, @var{A3}, ... @tab An expression of the same type and kind
7779 as @var{A1}. (As a GNU extension, arguments of different kinds are
7783 @item @emph{Return value}:
7784 The return value corresponds to the maximum value among the arguments,
7785 and has the same type and kind as the first argument.
7787 @item @emph{Specific names}:
7788 @multitable @columnfractions .20 .20 .20 .25
7789 @item Name @tab Argument @tab Return type @tab Standard
7790 @item @code{MIN0(I)} @tab @code{INTEGER(4) I} @tab @code{INTEGER(4)} @tab Fortran 77 and later
7791 @item @code{AMIN0(I)} @tab @code{INTEGER(4) I} @tab @code{REAL(MIN(X))} @tab Fortran 77 and later
7792 @item @code{MIN1(X)} @tab @code{REAL X} @tab @code{INT(MIN(X))} @tab Fortran 77 and later
7793 @item @code{AMIN1(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab Fortran 77 and later
7794 @item @code{DMIN1(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab Fortran 77 and later
7797 @item @emph{See also}:
7798 @ref{MAX}, @ref{MINLOC}, @ref{MINVAL}
7804 @section @code{MINEXPONENT} --- Minimum exponent of a real kind
7805 @fnindex MINEXPONENT
7806 @cindex model representation, minimum exponent
7809 @item @emph{Description}:
7810 @code{MINEXPONENT(X)} returns the minimum exponent in the model of the
7813 @item @emph{Standard}:
7814 Fortran 95 and later
7819 @item @emph{Syntax}:
7820 @code{RESULT = MINEXPONENT(X)}
7822 @item @emph{Arguments}:
7823 @multitable @columnfractions .15 .70
7824 @item @var{X} @tab Shall be of type @code{REAL}.
7827 @item @emph{Return value}:
7828 The return value is of type @code{INTEGER} and of the default integer
7831 @item @emph{Example}:
7832 See @code{MAXEXPONENT} for an example.
7838 @section @code{MINLOC} --- Location of the minimum value within an array
7840 @cindex array, location of minimum element
7843 @item @emph{Description}:
7844 Determines the location of the element in the array with the minimum
7845 value, or, if the @var{DIM} argument is supplied, determines the
7846 locations of the minimum element along each row of the array in the
7847 @var{DIM} direction. If @var{MASK} is present, only the elements for
7848 which @var{MASK} is @code{.TRUE.} are considered. If more than one
7849 element in the array has the minimum value, the location returned is
7850 that of the first such element in array element order. If the array has
7851 zero size, or all of the elements of @var{MASK} are @code{.FALSE.}, then
7852 the result is an array of zeroes. Similarly, if @var{DIM} is supplied
7853 and all of the elements of @var{MASK} along a given row are zero, the
7854 result value for that row is zero.
7856 @item @emph{Standard}:
7857 Fortran 95 and later
7860 Transformational function
7862 @item @emph{Syntax}:
7863 @multitable @columnfractions .80
7864 @item @code{RESULT = MINLOC(ARRAY, DIM [, MASK])}
7865 @item @code{RESULT = MINLOC(ARRAY [, MASK])}
7868 @item @emph{Arguments}:
7869 @multitable @columnfractions .15 .70
7870 @item @var{ARRAY} @tab Shall be an array of type @code{INTEGER},
7871 @code{REAL}, or @code{CHARACTER}.
7872 @item @var{DIM} @tab (Optional) Shall be a scalar of type
7873 @code{INTEGER}, with a value between one and the rank of @var{ARRAY},
7874 inclusive. It may not be an optional dummy argument.
7875 @item @var{MASK} @tab Shall be an array of type @code{LOGICAL},
7876 and conformable with @var{ARRAY}.
7879 @item @emph{Return value}:
7880 If @var{DIM} is absent, the result is a rank-one array with a length
7881 equal to the rank of @var{ARRAY}. If @var{DIM} is present, the result
7882 is an array with a rank one less than the rank of @var{ARRAY}, and a
7883 size corresponding to the size of @var{ARRAY} with the @var{DIM}
7884 dimension removed. If @var{DIM} is present and @var{ARRAY} has a rank
7885 of one, the result is a scalar. In all cases, the result is of default
7886 @code{INTEGER} type.
7888 @item @emph{See also}:
7889 @ref{MIN}, @ref{MINVAL}
7896 @section @code{MINVAL} --- Minimum value of an array
7898 @cindex array, minimum value
7899 @cindex minimum value
7902 @item @emph{Description}:
7903 Determines the minimum value of the elements in an array value, or, if
7904 the @var{DIM} argument is supplied, determines the minimum value along
7905 each row of the array in the @var{DIM} direction. If @var{MASK} is
7906 present, only the elements for which @var{MASK} is @code{.TRUE.} are
7907 considered. If the array has zero size, or all of the elements of
7908 @var{MASK} are @code{.FALSE.}, then the result is @code{HUGE(ARRAY)} if
7909 @var{ARRAY} is numeric, or a string of @code{CHAR(255)} characters if
7910 @var{ARRAY} is of character type.
7912 @item @emph{Standard}:
7913 Fortran 95 and later
7916 Transformational function
7918 @item @emph{Syntax}:
7919 @multitable @columnfractions .80
7920 @item @code{RESULT = MINVAL(ARRAY, DIM [, MASK])}
7921 @item @code{RESULT = MINVAL(ARRAY [, MASK])}
7924 @item @emph{Arguments}:
7925 @multitable @columnfractions .15 .70
7926 @item @var{ARRAY} @tab Shall be an array of type @code{INTEGER},
7927 @code{REAL}, or @code{CHARACTER}.
7928 @item @var{DIM} @tab (Optional) Shall be a scalar of type
7929 @code{INTEGER}, with a value between one and the rank of @var{ARRAY},
7930 inclusive. It may not be an optional dummy argument.
7931 @item @var{MASK} @tab Shall be an array of type @code{LOGICAL},
7932 and conformable with @var{ARRAY}.
7935 @item @emph{Return value}:
7936 If @var{DIM} is absent, or if @var{ARRAY} has a rank of one, the result
7937 is a scalar. If @var{DIM} is present, the result is an array with a
7938 rank one less than the rank of @var{ARRAY}, and a size corresponding to
7939 the size of @var{ARRAY} with the @var{DIM} dimension removed. In all
7940 cases, the result is of the same type and kind as @var{ARRAY}.
7942 @item @emph{See also}:
7943 @ref{MIN}, @ref{MINLOC}
7950 @section @code{MOD} --- Remainder function
7955 @cindex division, remainder
7958 @item @emph{Description}:
7959 @code{MOD(A,P)} computes the remainder of the division of A by P@. It is
7960 calculated as @code{A - (INT(A/P) * P)}.
7962 @item @emph{Standard}:
7963 Fortran 77 and later
7968 @item @emph{Syntax}:
7969 @code{RESULT = MOD(A, P)}
7971 @item @emph{Arguments}:
7972 @multitable @columnfractions .15 .70
7973 @item @var{A} @tab Shall be a scalar of type @code{INTEGER} or @code{REAL}
7974 @item @var{P} @tab Shall be a scalar of the same type as @var{A} and not
7978 @item @emph{Return value}:
7979 The kind of the return value is the result of cross-promoting
7980 the kinds of the arguments.
7982 @item @emph{Example}:
7986 print *, mod(17.5,5.5)
7987 print *, mod(17.5d0,5.5)
7988 print *, mod(17.5,5.5d0)
7991 print *, mod(-17.5,5.5)
7992 print *, mod(-17.5d0,5.5)
7993 print *, mod(-17.5,5.5d0)
7996 print *, mod(17.5,-5.5)
7997 print *, mod(17.5d0,-5.5)
7998 print *, mod(17.5,-5.5d0)
7999 end program test_mod
8002 @item @emph{Specific names}:
8003 @multitable @columnfractions .20 .20 .20 .25
8004 @item Name @tab Arguments @tab Return type @tab Standard
8005 @item @code{AMOD(A,P)} @tab @code{REAL(4)} @tab @code{REAL(4)} @tab Fortran 95 and later
8006 @item @code{DMOD(A,P)} @tab @code{REAL(8)} @tab @code{REAL(8)} @tab Fortran 95 and later
8013 @section @code{MODULO} --- Modulo function
8016 @cindex division, modulo
8019 @item @emph{Description}:
8020 @code{MODULO(A,P)} computes the @var{A} modulo @var{P}.
8022 @item @emph{Standard}:
8023 Fortran 95 and later
8028 @item @emph{Syntax}:
8029 @code{RESULT = MODULO(A, P)}
8031 @item @emph{Arguments}:
8032 @multitable @columnfractions .15 .70
8033 @item @var{A} @tab Shall be a scalar of type @code{INTEGER} or @code{REAL}
8034 @item @var{P} @tab Shall be a scalar of the same type and kind as @var{A}
8037 @item @emph{Return value}:
8038 The type and kind of the result are those of the arguments.
8040 @item If @var{A} and @var{P} are of type @code{INTEGER}:
8041 @code{MODULO(A,P)} has the value @var{R} such that @code{A=Q*P+R}, where
8042 @var{Q} is an integer and @var{R} is between 0 (inclusive) and @var{P}
8044 @item If @var{A} and @var{P} are of type @code{REAL}:
8045 @code{MODULO(A,P)} has the value of @code{A - FLOOR (A / P) * P}.
8047 In all cases, if @var{P} is zero the result is processor-dependent.
8049 @item @emph{Example}:
8052 print *, modulo(17,3)
8053 print *, modulo(17.5,5.5)
8055 print *, modulo(-17,3)
8056 print *, modulo(-17.5,5.5)
8058 print *, modulo(17,-3)
8059 print *, modulo(17.5,-5.5)
8068 @section @code{MOVE_ALLOC} --- Move allocation from one object to another
8070 @cindex moving allocation
8071 @cindex allocation, moving
8074 @item @emph{Description}:
8075 @code{MOVE_ALLOC(FROM, TO)} moves the allocation from @var{FROM} to
8076 @var{TO}. @var{FROM} will become deallocated in the process.
8078 @item @emph{Standard}:
8079 Fortran 2003 and later
8084 @item @emph{Syntax}:
8085 @code{CALL MOVE_ALLOC(FROM, TO)}
8087 @item @emph{Arguments}:
8088 @multitable @columnfractions .15 .70
8089 @item @var{FROM} @tab @code{ALLOCATABLE}, @code{INTENT(INOUT)}, may be
8090 of any type and kind.
8091 @item @var{TO} @tab @code{ALLOCATABLE}, @code{INTENT(OUT)}, shall be
8092 of the same type, kind and rank as @var{FROM}.
8095 @item @emph{Return value}:
8098 @item @emph{Example}:
8100 program test_move_alloc
8101 integer, allocatable :: a(:), b(:)
8105 call move_alloc(a, b)
8106 print *, allocated(a), allocated(b)
8108 end program test_move_alloc
8115 @section @code{MVBITS} --- Move bits from one integer to another
8120 @item @emph{Description}:
8121 Moves @var{LEN} bits from positions @var{FROMPOS} through
8122 @code{FROMPOS+LEN-1} of @var{FROM} to positions @var{TOPOS} through
8123 @code{TOPOS+LEN-1} of @var{TO}. The portion of argument @var{TO} not
8124 affected by the movement of bits is unchanged. The values of
8125 @code{FROMPOS+LEN-1} and @code{TOPOS+LEN-1} must be less than
8126 @code{BIT_SIZE(FROM)}.
8128 @item @emph{Standard}:
8129 Fortran 95 and later
8132 Elemental subroutine
8134 @item @emph{Syntax}:
8135 @code{CALL MVBITS(FROM, FROMPOS, LEN, TO, TOPOS)}
8137 @item @emph{Arguments}:
8138 @multitable @columnfractions .15 .70
8139 @item @var{FROM} @tab The type shall be @code{INTEGER}.
8140 @item @var{FROMPOS} @tab The type shall be @code{INTEGER}.
8141 @item @var{LEN} @tab The type shall be @code{INTEGER}.
8142 @item @var{TO} @tab The type shall be @code{INTEGER}, of the
8143 same kind as @var{FROM}.
8144 @item @var{TOPOS} @tab The type shall be @code{INTEGER}.
8147 @item @emph{See also}:
8148 @ref{IBCLR}, @ref{IBSET}, @ref{IBITS}, @ref{IAND}, @ref{IOR}, @ref{IEOR}
8154 @section @code{NEAREST} --- Nearest representable number
8156 @cindex real number, nearest different
8157 @cindex floating point, nearest different
8160 @item @emph{Description}:
8161 @code{NEAREST(X, S)} returns the processor-representable number nearest
8162 to @code{X} in the direction indicated by the sign of @code{S}.
8164 @item @emph{Standard}:
8165 Fortran 95 and later
8170 @item @emph{Syntax}:
8171 @code{RESULT = NEAREST(X, S)}
8173 @item @emph{Arguments}:
8174 @multitable @columnfractions .15 .70
8175 @item @var{X} @tab Shall be of type @code{REAL}.
8176 @item @var{S} @tab (Optional) shall be of type @code{REAL} and
8180 @item @emph{Return value}:
8181 The return value is of the same type as @code{X}. If @code{S} is
8182 positive, @code{NEAREST} returns the processor-representable number
8183 greater than @code{X} and nearest to it. If @code{S} is negative,
8184 @code{NEAREST} returns the processor-representable number smaller than
8185 @code{X} and nearest to it.
8187 @item @emph{Example}:
8189 program test_nearest
8191 x = nearest(42.0, 1.0)
8192 y = nearest(42.0, -1.0)
8193 write (*,"(3(G20.15))") x, y, x - y
8194 end program test_nearest
8201 @section @code{NEW_LINE} --- New line character
8204 @cindex output, newline
8207 @item @emph{Description}:
8208 @code{NEW_LINE(C)} returns the new-line character.
8210 @item @emph{Standard}:
8211 Fortran 2003 and later
8216 @item @emph{Syntax}:
8217 @code{RESULT = NEW_LINE(C)}
8219 @item @emph{Arguments}:
8220 @multitable @columnfractions .15 .70
8221 @item @var{C} @tab The argument shall be a scalar or array of the
8222 type @code{CHARACTER}.
8225 @item @emph{Return value}:
8226 Returns a @var{CHARACTER} scalar of length one with the new-line character of
8227 the same kind as parameter @var{C}.
8229 @item @emph{Example}:
8233 write(*,'(A)') 'This is record 1.'//NEW_LINE('A')//'This is record 2.'
8241 @section @code{NINT} --- Nearest whole number
8244 @cindex rounding, nearest whole number
8247 @item @emph{Description}:
8248 @code{NINT(A)} rounds its argument to the nearest whole number.
8250 @item @emph{Standard}:
8251 Fortran 77 and later, with @var{KIND} argument Fortran 90 and later
8256 @item @emph{Syntax}:
8257 @code{RESULT = NINT(A [, KIND])}
8259 @item @emph{Arguments}:
8260 @multitable @columnfractions .15 .70
8261 @item @var{A} @tab The type of the argument shall be @code{REAL}.
8262 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
8263 expression indicating the kind parameter of the result.
8266 @item @emph{Return value}:
8267 Returns @var{A} with the fractional portion of its magnitude eliminated by
8268 rounding to the nearest whole number and with its sign preserved,
8269 converted to an @code{INTEGER} of the default kind.
8271 @item @emph{Example}:
8278 print *, nint(x4), idnint(x8)
8279 end program test_nint
8282 @item @emph{Specific names}:
8283 @multitable @columnfractions .25 .25 .25
8284 @item Name @tab Argument @tab Standard
8285 @item @code{IDNINT(X)} @tab @code{REAL(8)} @tab Fortran 95 and later
8288 @item @emph{See also}:
8289 @ref{CEILING}, @ref{FLOOR}
8296 @section @code{NOT} --- Logical negation
8298 @cindex bits, negate
8299 @cindex bitwise logical not
8300 @cindex logical not, bitwise
8303 @item @emph{Description}:
8304 @code{NOT} returns the bitwise boolean inverse of @var{I}.
8306 @item @emph{Standard}:
8307 Fortran 95 and later
8312 @item @emph{Syntax}:
8313 @code{RESULT = NOT(I)}
8315 @item @emph{Arguments}:
8316 @multitable @columnfractions .15 .70
8317 @item @var{I} @tab The type shall be @code{INTEGER}.
8320 @item @emph{Return value}:
8321 The return type is @code{INTEGER}, of the same kind as the
8324 @item @emph{See also}:
8325 @ref{IAND}, @ref{IEOR}, @ref{IOR}, @ref{IBITS}, @ref{IBSET}, @ref{IBCLR}
8332 @section @code{NULL} --- Function that returns an disassociated pointer
8334 @cindex pointer, status
8335 @cindex pointer, disassociated
8338 @item @emph{Description}:
8339 Returns a disassociated pointer.
8341 If @var{MOLD} is present, a dissassociated pointer of the same type is
8342 returned, otherwise the type is determined by context.
8344 In Fortran 95, @var{MOLD} is optional. Please note that Fortran 2003
8345 includes cases where it is required.
8347 @item @emph{Standard}:
8348 Fortran 95 and later
8351 Transformational function
8353 @item @emph{Syntax}:
8354 @code{PTR => NULL([MOLD])}
8356 @item @emph{Arguments}:
8357 @multitable @columnfractions .15 .70
8358 @item @var{MOLD} @tab (Optional) shall be a pointer of any association
8359 status and of any type.
8362 @item @emph{Return value}:
8363 A disassociated pointer.
8365 @item @emph{Example}:
8367 REAL, POINTER, DIMENSION(:) :: VEC => NULL ()
8370 @item @emph{See also}:
8377 @section @code{OR} --- Bitwise logical OR
8379 @cindex bitwise logical or
8380 @cindex logical or, bitwise
8383 @item @emph{Description}:
8384 Bitwise logical @code{OR}.
8386 This intrinsic routine is provided for backwards compatibility with
8387 GNU Fortran 77. For integer arguments, programmers should consider
8388 the use of the @ref{IOR} intrinsic defined by the Fortran standard.
8390 @item @emph{Standard}:
8396 @item @emph{Syntax}:
8397 @code{RESULT = OR(I, J)}
8399 @item @emph{Arguments}:
8400 @multitable @columnfractions .15 .70
8401 @item @var{I} @tab The type shall be either a scalar @code{INTEGER}
8402 type or a scalar @code{LOGICAL} type.
8403 @item @var{J} @tab The type shall be the same as the type of @var{J}.
8406 @item @emph{Return value}:
8407 The return type is either a scalar @code{INTEGER} or a scalar
8408 @code{LOGICAL}. If the kind type parameters differ, then the
8409 smaller kind type is implicitly converted to larger kind, and the
8410 return has the larger kind.
8412 @item @emph{Example}:
8415 LOGICAL :: T = .TRUE., F = .FALSE.
8417 DATA a / Z'F' /, b / Z'3' /
8419 WRITE (*,*) OR(T, T), OR(T, F), OR(F, T), OR(F, F)
8420 WRITE (*,*) OR(a, b)
8424 @item @emph{See also}:
8425 Fortran 95 elemental function: @ref{IOR}
8431 @section @code{PACK} --- Pack an array into an array of rank one
8433 @cindex array, packing
8434 @cindex array, reduce dimension
8435 @cindex array, gather elements
8438 @item @emph{Description}:
8439 Stores the elements of @var{ARRAY} in an array of rank one.
8441 The beginning of the resulting array is made up of elements whose @var{MASK}
8442 equals @code{TRUE}. Afterwards, positions are filled with elements taken from
8445 @item @emph{Standard}:
8446 Fortran 95 and later
8449 Transformational function
8451 @item @emph{Syntax}:
8452 @code{RESULT = PACK(ARRAY, MASK[,VECTOR]}
8454 @item @emph{Arguments}:
8455 @multitable @columnfractions .15 .70
8456 @item @var{ARRAY} @tab Shall be an array of any type.
8457 @item @var{MASK} @tab Shall be an array of type @code{LOGICAL} and
8458 of the same size as @var{ARRAY}. Alternatively, it may be a @code{LOGICAL}
8460 @item @var{VECTOR} @tab (Optional) shall be an array of the same type
8461 as @var{ARRAY} and of rank one. If present, the number of elements in
8462 @var{VECTOR} shall be equal to or greater than the number of true elements
8463 in @var{MASK}. If @var{MASK} is scalar, the number of elements in
8464 @var{VECTOR} shall be equal to or greater than the number of elements in
8468 @item @emph{Return value}:
8469 The result is an array of rank one and the same type as that of @var{ARRAY}.
8470 If @var{VECTOR} is present, the result size is that of @var{VECTOR}, the
8471 number of @code{TRUE} values in @var{MASK} otherwise.
8473 @item @emph{Example}:
8474 Gathering nonzero elements from an array:
8478 m = (/ 1, 0, 0, 0, 5, 0 /)
8479 WRITE(*, FMT="(6(I0, ' '))") pack(m, m /= 0) ! "1 5"
8483 Gathering nonzero elements from an array and appending elements from @var{VECTOR}:
8487 m = (/ 1, 0, 0, 2 /)
8488 WRITE(*, FMT="(4(I0, ' '))") pack(m, m /= 0, (/ 0, 0, 3, 4 /)) ! "1 2 3 4"
8492 @item @emph{See also}:
8499 @section @code{PERROR} --- Print system error message
8501 @cindex system, error handling
8504 @item @emph{Description}:
8505 Prints (on the C @code{stderr} stream) a newline-terminated error
8506 message corresponding to the last system error. This is prefixed by
8507 @var{STRING}, a colon and a space. See @code{perror(3)}.
8509 @item @emph{Standard}:
8515 @item @emph{Syntax}:
8516 @code{CALL PERROR(STRING)}
8518 @item @emph{Arguments}:
8519 @multitable @columnfractions .15 .70
8520 @item @var{STRING} @tab A scalar of type @code{CHARACTER} and of the
8524 @item @emph{See also}:
8531 @section @code{PRECISION} --- Decimal precision of a real kind
8533 @cindex model representation, precision
8536 @item @emph{Description}:
8537 @code{PRECISION(X)} returns the decimal precision in the model of the
8540 @item @emph{Standard}:
8541 Fortran 95 and later
8546 @item @emph{Syntax}:
8547 @code{RESULT = PRECISION(X)}
8549 @item @emph{Arguments}:
8550 @multitable @columnfractions .15 .70
8551 @item @var{X} @tab Shall be of type @code{REAL} or @code{COMPLEX}.
8554 @item @emph{Return value}:
8555 The return value is of type @code{INTEGER} and of the default integer
8558 @item @emph{Example}:
8560 program prec_and_range
8561 real(kind=4) :: x(2)
8562 complex(kind=8) :: y
8564 print *, precision(x), range(x)
8565 print *, precision(y), range(y)
8566 end program prec_and_range
8573 @section @code{PRESENT} --- Determine whether an optional dummy argument is specified
8577 @item @emph{Description}:
8578 Determines whether an optional dummy argument is present.
8580 @item @emph{Standard}:
8581 Fortran 95 and later
8586 @item @emph{Syntax}:
8587 @code{RESULT = PRESENT(A)}
8589 @item @emph{Arguments}:
8590 @multitable @columnfractions .15 .70
8591 @item @var{A} @tab May be of any type and may be a pointer, scalar or array
8592 value, or a dummy procedure. It shall be the name of an optional dummy argument
8593 accessible within the current subroutine or function.
8596 @item @emph{Return value}:
8597 Returns either @code{TRUE} if the optional argument @var{A} is present, or
8598 @code{FALSE} otherwise.
8600 @item @emph{Example}:
8602 PROGRAM test_present
8603 WRITE(*,*) f(), f(42) ! "F T"
8605 LOGICAL FUNCTION f(x)
8606 INTEGER, INTENT(IN), OPTIONAL :: x
8616 @section @code{PRODUCT} --- Product of array elements
8618 @cindex array, product
8619 @cindex array, multiply elements
8620 @cindex array, conditionally multiply elements
8621 @cindex multiply array elements
8624 @item @emph{Description}:
8625 Multiplies the elements of @var{ARRAY} along dimension @var{DIM} if
8626 the corresponding element in @var{MASK} is @code{TRUE}.
8628 @item @emph{Standard}:
8629 Fortran 95 and later
8632 Transformational function
8634 @item @emph{Syntax}:
8635 @multitable @columnfractions .80
8636 @item @code{RESULT = PRODUCT(ARRAY[, MASK])}
8637 @item @code{RESULT = PRODUCT(ARRAY, DIM[, MASK])}
8640 @item @emph{Arguments}:
8641 @multitable @columnfractions .15 .70
8642 @item @var{ARRAY} @tab Shall be an array of type @code{INTEGER},
8643 @code{REAL} or @code{COMPLEX}.
8644 @item @var{DIM} @tab (Optional) shall be a scalar of type
8645 @code{INTEGER} with a value in the range from 1 to n, where n
8646 equals the rank of @var{ARRAY}.
8647 @item @var{MASK} @tab (Optional) shall be of type @code{LOGICAL}
8648 and either be a scalar or an array of the same shape as @var{ARRAY}.
8651 @item @emph{Return value}:
8652 The result is of the same type as @var{ARRAY}.
8654 If @var{DIM} is absent, a scalar with the product of all elements in
8655 @var{ARRAY} is returned. Otherwise, an array of rank n-1, where n equals
8656 the rank of @var{ARRAY}, and a shape similar to that of @var{ARRAY} with
8657 dimension @var{DIM} dropped is returned.
8660 @item @emph{Example}:
8662 PROGRAM test_product
8663 INTEGER :: x(5) = (/ 1, 2, 3, 4 ,5 /)
8664 print *, PRODUCT(x) ! all elements, product = 120
8665 print *, PRODUCT(x, MASK=MOD(x, 2)==1) ! odd elements, product = 15
8669 @item @emph{See also}:
8676 @section @code{RADIX} --- Base of a model number
8678 @cindex model representation, base
8679 @cindex model representation, radix
8682 @item @emph{Description}:
8683 @code{RADIX(X)} returns the base of the model representing the entity @var{X}.
8685 @item @emph{Standard}:
8686 Fortran 95 and later
8691 @item @emph{Syntax}:
8692 @code{RESULT = RADIX(X)}
8694 @item @emph{Arguments}:
8695 @multitable @columnfractions .15 .70
8696 @item @var{X} @tab Shall be of type @code{INTEGER} or @code{REAL}
8699 @item @emph{Return value}:
8700 The return value is a scalar of type @code{INTEGER} and of the default
8703 @item @emph{Example}:
8706 print *, "The radix for the default integer kind is", radix(0)
8707 print *, "The radix for the default real kind is", radix(0.0)
8708 end program test_radix
8716 @section @code{RAN} --- Real pseudo-random number
8718 @cindex random number generation
8721 @item @emph{Description}:
8722 For compatibility with HP FORTRAN 77/iX, the @code{RAN} intrinsic is
8723 provided as an alias for @code{RAND}. See @ref{RAND} for complete
8726 @item @emph{Standard}:
8732 @item @emph{See also}:
8733 @ref{RAND}, @ref{RANDOM_NUMBER}
8739 @section @code{RAND} --- Real pseudo-random number
8741 @cindex random number generation
8744 @item @emph{Description}:
8745 @code{RAND(FLAG)} returns a pseudo-random number from a uniform
8746 distribution between 0 and 1. If @var{FLAG} is 0, the next number
8747 in the current sequence is returned; if @var{FLAG} is 1, the generator
8748 is restarted by @code{CALL SRAND(0)}; if @var{FLAG} has any other value,
8749 it is used as a new seed with @code{SRAND}.
8751 This intrinsic routine is provided for backwards compatibility with
8752 GNU Fortran 77. It implements a simple modulo generator as provided
8753 by @command{g77}. For new code, one should consider the use of
8754 @ref{RANDOM_NUMBER} as it implements a superior algorithm.
8756 @item @emph{Standard}:
8762 @item @emph{Syntax}:
8763 @code{RESULT = RAND(I)}
8765 @item @emph{Arguments}:
8766 @multitable @columnfractions .15 .70
8767 @item @var{I} @tab Shall be a scalar @code{INTEGER} of kind 4.
8770 @item @emph{Return value}:
8771 The return value is of @code{REAL} type and the default kind.
8773 @item @emph{Example}:
8776 integer,parameter :: seed = 86456
8779 print *, rand(), rand(), rand(), rand()
8780 print *, rand(seed), rand(), rand(), rand()
8781 end program test_rand
8784 @item @emph{See also}:
8785 @ref{SRAND}, @ref{RANDOM_NUMBER}
8792 @section @code{RANDOM_NUMBER} --- Pseudo-random number
8793 @fnindex RANDOM_NUMBER
8794 @cindex random number generation
8797 @item @emph{Description}:
8798 Returns a single pseudorandom number or an array of pseudorandom numbers
8799 from the uniform distribution over the range @math{ 0 \leq x < 1}.
8801 The runtime-library implements George Marsaglia's KISS (Keep It Simple
8802 Stupid) random number generator (RNG). This RNG combines:
8804 @item The congruential generator @math{x(n) = 69069 \cdot x(n-1) + 1327217885}
8805 with a period of @math{2^{32}},
8806 @item A 3-shift shift-register generator with a period of @math{2^{32} - 1},
8807 @item Two 16-bit multiply-with-carry generators with a period of
8808 @math{597273182964842497 > 2^{59}}.
8810 The overall period exceeds @math{2^{123}}.
8812 Please note, this RNG is thread safe if used within OpenMP directives,
8813 i.e., its state will be consistent while called from multiple threads.
8814 However, the KISS generator does not create random numbers in parallel
8815 from multiple sources, but in sequence from a single source. If an
8816 OpenMP-enabled application heavily relies on random numbers, one should
8817 consider employing a dedicated parallel random number generator instead.
8819 @item @emph{Standard}:
8820 Fortran 95 and later
8825 @item @emph{Syntax}:
8826 @code{RANDOM_NUMBER(HARVEST)}
8828 @item @emph{Arguments}:
8829 @multitable @columnfractions .15 .70
8830 @item @var{HARVEST} @tab Shall be a scalar or an array of type @code{REAL}.
8833 @item @emph{Example}:
8835 program test_random_number
8837 CALL init_random_seed() ! see example of RANDOM_SEED
8838 CALL RANDOM_NUMBER(r)
8842 @item @emph{See also}:
8849 @section @code{RANDOM_SEED} --- Initialize a pseudo-random number sequence
8850 @fnindex RANDOM_SEED
8851 @cindex random number generation, seeding
8852 @cindex seeding a random number generator
8855 @item @emph{Description}:
8856 Restarts or queries the state of the pseudorandom number generator used by
8857 @code{RANDOM_NUMBER}.
8859 If @code{RANDOM_SEED} is called without arguments, it is initialized to
8860 a default state. The example below shows how to initialize the random
8861 seed based on the system's time.
8863 @item @emph{Standard}:
8864 Fortran 95 and later
8869 @item @emph{Syntax}:
8870 @code{CALL RANDOM_SEED([SIZE, PUT, GET])}
8872 @item @emph{Arguments}:
8873 @multitable @columnfractions .15 .70
8874 @item @var{SIZE} @tab (Optional) Shall be a scalar and of type default
8875 @code{INTEGER}, with @code{INTENT(OUT)}. It specifies the minimum size
8876 of the arrays used with the @var{PUT} and @var{GET} arguments.
8877 @item @var{PUT} @tab (Optional) Shall be an array of type default
8878 @code{INTEGER} and rank one. It is @code{INTENT(IN)} and the size of
8879 the array must be larger than or equal to the number returned by the
8880 @var{SIZE} argument.
8881 @item @var{GET} @tab (Optional) Shall be an array of type default
8882 @code{INTEGER} and rank one. It is @code{INTENT(OUT)} and the size
8883 of the array must be larger than or equal to the number returned by
8884 the @var{SIZE} argument.
8887 @item @emph{Example}:
8889 SUBROUTINE init_random_seed()
8890 INTEGER :: i, n, clock
8891 INTEGER, DIMENSION(:), ALLOCATABLE :: seed
8893 CALL RANDOM_SEED(size = n)
8896 CALL SYSTEM_CLOCK(COUNT=clock)
8898 seed = clock + 37 * (/ (i - 1, i = 1, n) /)
8899 CALL RANDOM_SEED(PUT = seed)
8905 @item @emph{See also}:
8912 @section @code{RANGE} --- Decimal exponent range
8914 @cindex model representation, range
8917 @item @emph{Description}:
8918 @code{RANGE(X)} returns the decimal exponent range in the model of the
8921 @item @emph{Standard}:
8922 Fortran 95 and later
8927 @item @emph{Syntax}:
8928 @code{RESULT = RANGE(X)}
8930 @item @emph{Arguments}:
8931 @multitable @columnfractions .15 .70
8932 @item @var{X} @tab Shall be of type @code{INTEGER}, @code{REAL}
8936 @item @emph{Return value}:
8937 The return value is of type @code{INTEGER} and of the default integer
8940 @item @emph{Example}:
8941 See @code{PRECISION} for an example.
8947 @section @code{REAL} --- Convert to real type
8950 @cindex conversion, to real
8951 @cindex complex numbers, real part
8954 @item @emph{Description}:
8955 @code{REAL(A [, KIND])} converts its argument @var{A} to a real type. The
8956 @code{REALPART} function is provided for compatibility with @command{g77},
8957 and its use is strongly discouraged.
8959 @item @emph{Standard}:
8960 Fortran 77 and later
8965 @item @emph{Syntax}:
8966 @multitable @columnfractions .80
8967 @item @code{RESULT = REAL(A [, KIND])}
8968 @item @code{RESULT = REALPART(Z)}
8971 @item @emph{Arguments}:
8972 @multitable @columnfractions .15 .70
8973 @item @var{A} @tab Shall be @code{INTEGER}, @code{REAL}, or
8975 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
8976 expression indicating the kind parameter of the result.
8979 @item @emph{Return value}:
8980 These functions return a @code{REAL} variable or array under
8981 the following rules:
8985 @code{REAL(A)} is converted to a default real type if @var{A} is an
8986 integer or real variable.
8988 @code{REAL(A)} is converted to a real type with the kind type parameter
8989 of @var{A} if @var{A} is a complex variable.
8991 @code{REAL(A, KIND)} is converted to a real type with kind type
8992 parameter @var{KIND} if @var{A} is a complex, integer, or real
8996 @item @emph{Example}:
8999 complex :: x = (1.0, 2.0)
9000 print *, real(x), real(x,8), realpart(x)
9001 end program test_real
9004 @item @emph{See also}:
9005 @ref{DBLE}, @ref{DFLOAT}, @ref{FLOAT}
9012 @section @code{RENAME} --- Rename a file
9014 @cindex file system, rename file
9017 @item @emph{Description}:
9018 Renames a file from file @var{PATH1} to @var{PATH2}. A null
9019 character (@code{CHAR(0)}) can be used to mark the end of the names in
9020 @var{PATH1} and @var{PATH2}; otherwise, trailing blanks in the file
9021 names are ignored. If the @var{STATUS} argument is supplied, it
9022 contains 0 on success or a nonzero error code upon return; see
9025 This intrinsic is provided in both subroutine and function forms;
9026 however, only one form can be used in any given program unit.
9028 @item @emph{Standard}:
9032 Subroutine, function
9034 @item @emph{Syntax}:
9035 @multitable @columnfractions .80
9036 @item @code{CALL RENAME(PATH1, PATH2 [, STATUS])}
9037 @item @code{STATUS = RENAME(PATH1, PATH2)}
9040 @item @emph{Arguments}:
9041 @multitable @columnfractions .15 .70
9042 @item @var{PATH1} @tab Shall be of default @code{CHARACTER} type.
9043 @item @var{PATH2} @tab Shall be of default @code{CHARACTER} type.
9044 @item @var{STATUS} @tab (Optional) Shall be of default @code{INTEGER} type.
9047 @item @emph{See also}:
9055 @section @code{REPEAT} --- Repeated string concatenation
9057 @cindex string, repeat
9058 @cindex string, concatenate
9061 @item @emph{Description}:
9062 Concatenates @var{NCOPIES} copies of a string.
9064 @item @emph{Standard}:
9065 Fortran 95 and later
9068 Transformational function
9070 @item @emph{Syntax}:
9071 @code{RESULT = REPEAT(STRING, NCOPIES)}
9073 @item @emph{Arguments}:
9074 @multitable @columnfractions .15 .70
9075 @item @var{STRING} @tab Shall be scalar and of type @code{CHARACTER}.
9076 @item @var{NCOPIES} @tab Shall be scalar and of type @code{INTEGER}.
9079 @item @emph{Return value}:
9080 A new scalar of type @code{CHARACTER} built up from @var{NCOPIES} copies
9083 @item @emph{Example}:
9086 write(*,*) repeat("x", 5) ! "xxxxx"
9094 @section @code{RESHAPE} --- Function to reshape an array
9096 @cindex array, change dimensions
9097 @cindex array, transmogrify
9100 @item @emph{Description}:
9101 Reshapes @var{SOURCE} to correspond to @var{SHAPE}. If necessary,
9102 the new array may be padded with elements from @var{PAD} or permuted
9103 as defined by @var{ORDER}.
9105 @item @emph{Standard}:
9106 Fortran 95 and later
9109 Transformational function
9111 @item @emph{Syntax}:
9112 @code{RESULT = RESHAPE(SOURCE, SHAPE[, PAD, ORDER])}
9114 @item @emph{Arguments}:
9115 @multitable @columnfractions .15 .70
9116 @item @var{SOURCE} @tab Shall be an array of any type.
9117 @item @var{SHAPE} @tab Shall be of type @code{INTEGER} and an
9118 array of rank one. Its values must be positive or zero.
9119 @item @var{PAD} @tab (Optional) shall be an array of the same
9120 type as @var{SOURCE}.
9121 @item @var{ORDER} @tab (Optional) shall be of type @code{INTEGER}
9122 and an array of the same shape as @var{SHAPE}. Its values shall
9123 be a permutation of the numbers from 1 to n, where n is the size of
9124 @var{SHAPE}. If @var{ORDER} is absent, the natural ordering shall
9128 @item @emph{Return value}:
9129 The result is an array of shape @var{SHAPE} with the same type as
9132 @item @emph{Example}:
9134 PROGRAM test_reshape
9135 INTEGER, DIMENSION(4) :: x
9136 WRITE(*,*) SHAPE(x) ! prints "4"
9137 WRITE(*,*) SHAPE(RESHAPE(x, (/2, 2/))) ! prints "2 2"
9141 @item @emph{See also}:
9148 @section @code{RRSPACING} --- Reciprocal of the relative spacing
9150 @cindex real number, relative spacing
9151 @cindex floating point, relative spacing
9155 @item @emph{Description}:
9156 @code{RRSPACING(X)} returns the reciprocal of the relative spacing of
9157 model numbers near @var{X}.
9159 @item @emph{Standard}:
9160 Fortran 95 and later
9165 @item @emph{Syntax}:
9166 @code{RESULT = RRSPACING(X)}
9168 @item @emph{Arguments}:
9169 @multitable @columnfractions .15 .70
9170 @item @var{X} @tab Shall be of type @code{REAL}.
9173 @item @emph{Return value}:
9174 The return value is of the same type and kind as @var{X}.
9175 The value returned is equal to
9176 @code{ABS(FRACTION(X)) * FLOAT(RADIX(X))**DIGITS(X)}.
9178 @item @emph{See also}:
9185 @section @code{RSHIFT} --- Right shift bits
9187 @cindex bits, shift right
9190 @item @emph{Description}:
9191 @code{RSHIFT} returns a value corresponding to @var{I} with all of the
9192 bits shifted right by @var{SHIFT} places. If the absolute value of
9193 @var{SHIFT} is greater than @code{BIT_SIZE(I)}, the value is undefined.
9194 Bits shifted out from the left end are lost; zeros are shifted in from
9197 This function has been superseded by the @code{ISHFT} intrinsic, which
9198 is standard in Fortran 95 and later.
9200 @item @emph{Standard}:
9206 @item @emph{Syntax}:
9207 @code{RESULT = RSHIFT(I, SHIFT)}
9209 @item @emph{Arguments}:
9210 @multitable @columnfractions .15 .70
9211 @item @var{I} @tab The type shall be @code{INTEGER}.
9212 @item @var{SHIFT} @tab The type shall be @code{INTEGER}.
9215 @item @emph{Return value}:
9216 The return value is of type @code{INTEGER} and of the same kind as
9219 @item @emph{See also}:
9220 @ref{ISHFT}, @ref{ISHFTC}, @ref{LSHIFT}
9227 @section @code{SCALE} --- Scale a real value
9229 @cindex real number, scale
9230 @cindex floating point, scale
9233 @item @emph{Description}:
9234 @code{SCALE(X,I)} returns @code{X * RADIX(X)**I}.
9236 @item @emph{Standard}:
9237 Fortran 95 and later
9242 @item @emph{Syntax}:
9243 @code{RESULT = SCALE(X, I)}
9245 @item @emph{Arguments}:
9246 @multitable @columnfractions .15 .70
9247 @item @var{X} @tab The type of the argument shall be a @code{REAL}.
9248 @item @var{I} @tab The type of the argument shall be a @code{INTEGER}.
9251 @item @emph{Return value}:
9252 The return value is of the same type and kind as @var{X}.
9253 Its value is @code{X * RADIX(X)**I}.
9255 @item @emph{Example}:
9258 real :: x = 178.1387e-4
9260 print *, scale(x,i), x*radix(x)**i
9261 end program test_scale
9269 @section @code{SCAN} --- Scan a string for the presence of a set of characters
9271 @cindex string, find subset
9274 @item @emph{Description}:
9275 Scans a @var{STRING} for any of the characters in a @var{SET}
9278 If @var{BACK} is either absent or equals @code{FALSE}, this function
9279 returns the position of the leftmost character of @var{STRING} that is
9280 in @var{SET}. If @var{BACK} equals @code{TRUE}, the rightmost position
9281 is returned. If no character of @var{SET} is found in @var{STRING}, the
9284 @item @emph{Standard}:
9285 Fortran 95 and later, with @var{KIND} argument Fortran 2003 and later
9290 @item @emph{Syntax}:
9291 @code{RESULT = SCAN(STRING, SET[, BACK [, KIND]])}
9293 @item @emph{Arguments}:
9294 @multitable @columnfractions .15 .70
9295 @item @var{STRING} @tab Shall be of type @code{CHARACTER}.
9296 @item @var{SET} @tab Shall be of type @code{CHARACTER}.
9297 @item @var{BACK} @tab (Optional) shall be of type @code{LOGICAL}.
9298 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
9299 expression indicating the kind parameter of the result.
9302 @item @emph{Return value}:
9303 The return value is of type @code{INTEGER} and of kind @var{KIND}. If
9304 @var{KIND} is absent, the return value is of default integer kind.
9306 @item @emph{Example}:
9309 WRITE(*,*) SCAN("FORTRAN", "AO") ! 2, found 'O'
9310 WRITE(*,*) SCAN("FORTRAN", "AO", .TRUE.) ! 6, found 'A'
9311 WRITE(*,*) SCAN("FORTRAN", "C++") ! 0, found none
9315 @item @emph{See also}:
9316 @ref{INDEX intrinsic}, @ref{VERIFY}
9322 @section @code{SECNDS} --- Time function
9324 @cindex time, elapsed
9325 @cindex elapsed time
9328 @item @emph{Description}:
9329 @code{SECNDS(X)} gets the time in seconds from the real-time system clock.
9330 @var{X} is a reference time, also in seconds. If this is zero, the time in
9331 seconds from midnight is returned. This function is non-standard and its
9334 @item @emph{Standard}:
9340 @item @emph{Syntax}:
9341 @code{RESULT = SECNDS (X)}
9343 @item @emph{Arguments}:
9344 @multitable @columnfractions .15 .70
9345 @item @var{T} @tab Shall be of type @code{REAL(4)}.
9346 @item @var{X} @tab Shall be of type @code{REAL(4)}.
9349 @item @emph{Return value}:
9352 @item @emph{Example}:
9357 print *, secnds (0.0) ! seconds since midnight
9358 t1 = secnds (0.0) ! reference time
9359 do i = 1, 10000000 ! do something
9361 t2 = secnds (t1) ! elapsed time
9362 print *, "Something took ", t2, " seconds."
9363 end program test_secnds
9370 @section @code{SECOND} --- CPU time function
9372 @cindex time, elapsed
9373 @cindex elapsed time
9376 @item @emph{Description}:
9377 Returns a @code{REAL(4)} value representing the elapsed CPU time in
9378 seconds. This provides the same functionality as the standard
9379 @code{CPU_TIME} intrinsic, and is only included for backwards
9382 This intrinsic is provided in both subroutine and function forms;
9383 however, only one form can be used in any given program unit.
9385 @item @emph{Standard}:
9389 Subroutine, function
9391 @item @emph{Syntax}:
9392 @multitable @columnfractions .80
9393 @item @code{CALL SECOND(TIME)}
9394 @item @code{TIME = SECOND()}
9397 @item @emph{Arguments}:
9398 @multitable @columnfractions .15 .70
9399 @item @var{TIME} @tab Shall be of type @code{REAL(4)}.
9402 @item @emph{Return value}:
9403 In either syntax, @var{TIME} is set to the process's current runtime in
9406 @item @emph{See also}:
9413 @node SELECTED_CHAR_KIND
9414 @section @code{SELECTED_CHAR_KIND} --- Choose character kind
9415 @fnindex SELECTED_CHAR_KIND
9416 @cindex character kind
9417 @cindex kind, character
9420 @item @emph{Description}:
9422 @code{SELECTED_CHAR_KIND(NAME)} returns the kind value for the character
9423 set named @var{NAME}, if a character set with such a name is supported,
9424 or @math{-1} otherwise. Currently, supported character sets include
9425 ``ASCII'' and ``DEFAULT'', which are equivalent.
9427 @item @emph{Standard}:
9428 Fortran 2003 and later
9431 Transformational function
9433 @item @emph{Syntax}:
9434 @code{RESULT = SELECTED_CHAR_KIND(NAME)}
9436 @item @emph{Arguments}:
9437 @multitable @columnfractions .15 .70
9438 @item @var{NAME} @tab Shall be a scalar and of the default character type.
9441 @item @emph{Example}:
9444 integer,parameter :: ascii = selected_char_kind("ascii")
9445 character(kind=ascii, len=26) :: s
9447 s = ascii_"abcdefghijklmnopqrstuvwxyz"
9449 end program ascii_kind
9455 @node SELECTED_INT_KIND
9456 @section @code{SELECTED_INT_KIND} --- Choose integer kind
9457 @fnindex SELECTED_INT_KIND
9458 @cindex integer kind
9459 @cindex kind, integer
9462 @item @emph{Description}:
9463 @code{SELECTED_INT_KIND(R)} return the kind value of the smallest integer
9464 type that can represent all values ranging from @math{-10^R} (exclusive)
9465 to @math{10^R} (exclusive). If there is no integer kind that accommodates
9466 this range, @code{SELECTED_INT_KIND} returns @math{-1}.
9468 @item @emph{Standard}:
9469 Fortran 95 and later
9472 Transformational function
9474 @item @emph{Syntax}:
9475 @code{RESULT = SELECTED_INT_KIND(R)}
9477 @item @emph{Arguments}:
9478 @multitable @columnfractions .15 .70
9479 @item @var{R} @tab Shall be a scalar and of type @code{INTEGER}.
9482 @item @emph{Example}:
9484 program large_integers
9485 integer,parameter :: k5 = selected_int_kind(5)
9486 integer,parameter :: k15 = selected_int_kind(15)
9487 integer(kind=k5) :: i5
9488 integer(kind=k15) :: i15
9490 print *, huge(i5), huge(i15)
9492 ! The following inequalities are always true
9493 print *, huge(i5) >= 10_k5**5-1
9494 print *, huge(i15) >= 10_k15**15-1
9495 end program large_integers
9501 @node SELECTED_REAL_KIND
9502 @section @code{SELECTED_REAL_KIND} --- Choose real kind
9503 @fnindex SELECTED_REAL_KIND
9508 @item @emph{Description}:
9509 @code{SELECTED_REAL_KIND(P,R)} returns the kind value of a real data type
9510 with decimal precision of at least @code{P} digits and exponent
9511 range greater at least @code{R}.
9513 @item @emph{Standard}:
9514 Fortran 95 and later
9517 Transformational function
9519 @item @emph{Syntax}:
9520 @code{RESULT = SELECTED_REAL_KIND([P, R])}
9522 @item @emph{Arguments}:
9523 @multitable @columnfractions .15 .70
9524 @item @var{P} @tab (Optional) shall be a scalar and of type @code{INTEGER}.
9525 @item @var{R} @tab (Optional) shall be a scalar and of type @code{INTEGER}.
9527 At least one argument shall be present.
9529 @item @emph{Return value}:
9531 @code{SELECTED_REAL_KIND} returns the value of the kind type parameter of
9532 a real data type with decimal precision of at least @code{P} digits and a
9533 decimal exponent range of at least @code{R}. If more than one real data
9534 type meet the criteria, the kind of the data type with the smallest
9535 decimal precision is returned. If no real data type matches the criteria,
9538 @item -1 if the processor does not support a real data type with a
9539 precision greater than or equal to @code{P}
9540 @item -2 if the processor does not support a real type with an exponent
9541 range greater than or equal to @code{R}
9542 @item -3 if neither is supported.
9545 @item @emph{Example}:
9548 integer,parameter :: p6 = selected_real_kind(6)
9549 integer,parameter :: p10r100 = selected_real_kind(10,100)
9550 integer,parameter :: r400 = selected_real_kind(r=400)
9552 real(kind=p10r100) :: y
9553 real(kind=r400) :: z
9555 print *, precision(x), range(x)
9556 print *, precision(y), range(y)
9557 print *, precision(z), range(z)
9558 end program real_kinds
9565 @section @code{SET_EXPONENT} --- Set the exponent of the model
9566 @fnindex SET_EXPONENT
9567 @cindex real number, set exponent
9568 @cindex floating point, set exponent
9571 @item @emph{Description}:
9572 @code{SET_EXPONENT(X, I)} returns the real number whose fractional part
9573 is that that of @var{X} and whose exponent part is @var{I}.
9575 @item @emph{Standard}:
9576 Fortran 95 and later
9581 @item @emph{Syntax}:
9582 @code{RESULT = SET_EXPONENT(X, I)}
9584 @item @emph{Arguments}:
9585 @multitable @columnfractions .15 .70
9586 @item @var{X} @tab Shall be of type @code{REAL}.
9587 @item @var{I} @tab Shall be of type @code{INTEGER}.
9590 @item @emph{Return value}:
9591 The return value is of the same type and kind as @var{X}.
9592 The real number whose fractional part
9593 is that that of @var{X} and whose exponent part if @var{I} is returned;
9594 it is @code{FRACTION(X) * RADIX(X)**I}.
9596 @item @emph{Example}:
9599 REAL :: x = 178.1387e-4
9601 PRINT *, SET_EXPONENT(x, i), FRACTION(x) * RADIX(x)**i
9610 @section @code{SHAPE} --- Determine the shape of an array
9612 @cindex array, shape
9615 @item @emph{Description}:
9616 Determines the shape of an array.
9618 @item @emph{Standard}:
9619 Fortran 95 and later
9624 @item @emph{Syntax}:
9625 @code{RESULT = SHAPE(SOURCE)}
9627 @item @emph{Arguments}:
9628 @multitable @columnfractions .15 .70
9629 @item @var{SOURCE} @tab Shall be an array or scalar of any type.
9630 If @var{SOURCE} is a pointer it must be associated and allocatable
9631 arrays must be allocated.
9634 @item @emph{Return value}:
9635 An @code{INTEGER} array of rank one with as many elements as @var{SOURCE}
9636 has dimensions. The elements of the resulting array correspond to the extend
9637 of @var{SOURCE} along the respective dimensions. If @var{SOURCE} is a scalar,
9638 the result is the rank one array of size zero.
9640 @item @emph{Example}:
9643 INTEGER, DIMENSION(-1:1, -1:2) :: A
9644 WRITE(*,*) SHAPE(A) ! (/ 3, 4 /)
9645 WRITE(*,*) SIZE(SHAPE(42)) ! (/ /)
9649 @item @emph{See also}:
9650 @ref{RESHAPE}, @ref{SIZE}
9656 @section @code{SIGN} --- Sign copying function
9660 @cindex sign copying
9663 @item @emph{Description}:
9664 @code{SIGN(A,B)} returns the value of @var{A} with the sign of @var{B}.
9666 @item @emph{Standard}:
9667 Fortran 77 and later
9672 @item @emph{Syntax}:
9673 @code{RESULT = SIGN(A, B)}
9675 @item @emph{Arguments}:
9676 @multitable @columnfractions .15 .70
9677 @item @var{A} @tab Shall be of type @code{INTEGER} or @code{REAL}
9678 @item @var{B} @tab Shall be of the same type and kind as @var{A}
9681 @item @emph{Return value}:
9682 The kind of the return value is that of @var{A} and @var{B}.
9683 If @math{B\ge 0} then the result is @code{ABS(A)}, else
9684 it is @code{-ABS(A)}.
9686 @item @emph{Example}:
9689 print *, sign(-12,1)
9690 print *, sign(-12,0)
9691 print *, sign(-12,-1)
9693 print *, sign(-12.,1.)
9694 print *, sign(-12.,0.)
9695 print *, sign(-12.,-1.)
9696 end program test_sign
9699 @item @emph{Specific names}:
9700 @multitable @columnfractions .20 .20 .20 .25
9701 @item Name @tab Arguments @tab Return type @tab Standard
9702 @item @code{ISIGN(A,P)} @tab @code{INTEGER(4)} @tab @code{INTEGER(4)} @tab f95, gnu
9703 @item @code{DSIGN(A,P)} @tab @code{REAL(8)} @tab @code{REAL(8)} @tab f95, gnu
9710 @section @code{SIGNAL} --- Signal handling subroutine (or function)
9712 @cindex system, signal handling
9715 @item @emph{Description}:
9716 @code{SIGNAL(NUMBER, HANDLER [, STATUS])} causes external subroutine
9717 @var{HANDLER} to be executed with a single integer argument when signal
9718 @var{NUMBER} occurs. If @var{HANDLER} is an integer, it can be used to
9719 turn off handling of signal @var{NUMBER} or revert to its default
9720 action. See @code{signal(2)}.
9722 If @code{SIGNAL} is called as a subroutine and the @var{STATUS} argument
9723 is supplied, it is set to the value returned by @code{signal(2)}.
9725 @item @emph{Standard}:
9729 Subroutine, function
9731 @item @emph{Syntax}:
9732 @multitable @columnfractions .80
9733 @item @code{CALL SIGNAL(NUMBER, HANDLER [, STATUS])}
9734 @item @code{STATUS = SIGNAL(NUMBER, HANDLER)}
9737 @item @emph{Arguments}:
9738 @multitable @columnfractions .15 .70
9739 @item @var{NUMBER} @tab Shall be a scalar integer, with @code{INTENT(IN)}
9740 @item @var{HANDLER}@tab Signal handler (@code{INTEGER FUNCTION} or
9741 @code{SUBROUTINE}) or dummy/global @code{INTEGER} scalar.
9742 @code{INTEGER}. It is @code{INTENT(IN)}.
9743 @item @var{STATUS} @tab (Optional) @var{STATUS} shall be a scalar
9744 integer. It has @code{INTENT(OUT)}.
9746 @c TODO: What should the interface of the handler be? Does it take arguments?
9748 @item @emph{Return value}:
9749 The @code{SIGNAL} function returns the value returned by @code{signal(2)}.
9751 @item @emph{Example}:
9755 external handler_print
9757 call signal (12, handler_print)
9761 end program test_signal
9768 @section @code{SIN} --- Sine function
9774 @cindex trigonometric function, sine
9778 @item @emph{Description}:
9779 @code{SIN(X)} computes the sine of @var{X}.
9781 @item @emph{Standard}:
9782 Fortran 77 and later
9787 @item @emph{Syntax}:
9788 @code{RESULT = SIN(X)}
9790 @item @emph{Arguments}:
9791 @multitable @columnfractions .15 .70
9792 @item @var{X} @tab The type shall be @code{REAL} or
9796 @item @emph{Return value}:
9797 The return value has same type and kind as @var{X}.
9799 @item @emph{Example}:
9804 end program test_sin
9807 @item @emph{Specific names}:
9808 @multitable @columnfractions .20 .20 .20 .25
9809 @item Name @tab Argument @tab Return type @tab Standard
9810 @item @code{DSIN(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab f95, gnu
9811 @item @code{CSIN(X)} @tab @code{COMPLEX(4) X} @tab @code{COMPLEX(4)} @tab f95, gnu
9812 @item @code{ZSIN(X)} @tab @code{COMPLEX(8) X} @tab @code{COMPLEX(8)} @tab f95, gnu
9813 @item @code{CDSIN(X)} @tab @code{COMPLEX(8) X} @tab @code{COMPLEX(8)} @tab f95, gnu
9816 @item @emph{See also}:
9823 @section @code{SINH} --- Hyperbolic sine function
9826 @cindex hyperbolic sine
9827 @cindex hyperbolic function, sine
9828 @cindex sine, hyperbolic
9831 @item @emph{Description}:
9832 @code{SINH(X)} computes the hyperbolic sine of @var{X}.
9834 @item @emph{Standard}:
9835 Fortran 95 and later, for a complex argument Fortran 2008 or later
9840 @item @emph{Syntax}:
9841 @code{RESULT = SINH(X)}
9843 @item @emph{Arguments}:
9844 @multitable @columnfractions .15 .70
9845 @item @var{X} @tab The type shall be @code{REAL} or @code{COMPLEX}.
9848 @item @emph{Return value}:
9849 The return value has same type and kind as @var{X}.
9851 @item @emph{Example}:
9854 real(8) :: x = - 1.0_8
9856 end program test_sinh
9859 @item @emph{Specific names}:
9860 @multitable @columnfractions .20 .20 .20 .25
9861 @item Name @tab Argument @tab Return type @tab Standard
9862 @item @code{DSINH(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab Fortran 95 and later
9865 @item @emph{See also}:
9872 @section @code{SIZE} --- Determine the size of an array
9875 @cindex array, number of elements
9876 @cindex array, count elements
9879 @item @emph{Description}:
9880 Determine the extent of @var{ARRAY} along a specified dimension @var{DIM},
9881 or the total number of elements in @var{ARRAY} if @var{DIM} is absent.
9883 @item @emph{Standard}:
9884 Fortran 95 and later, with @var{KIND} argument Fortran 2003 and later
9889 @item @emph{Syntax}:
9890 @code{RESULT = SIZE(ARRAY[, DIM [, KIND]])}
9892 @item @emph{Arguments}:
9893 @multitable @columnfractions .15 .70
9894 @item @var{ARRAY} @tab Shall be an array of any type. If @var{ARRAY} is
9895 a pointer it must be associated and allocatable arrays must be allocated.
9896 @item @var{DIM} @tab (Optional) shall be a scalar of type @code{INTEGER}
9897 and its value shall be in the range from 1 to n, where n equals the rank
9899 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
9900 expression indicating the kind parameter of the result.
9903 @item @emph{Return value}:
9904 The return value is of type @code{INTEGER} and of kind @var{KIND}. If
9905 @var{KIND} is absent, the return value is of default integer kind.
9907 @item @emph{Example}:
9910 WRITE(*,*) SIZE((/ 1, 2 /)) ! 2
9914 @item @emph{See also}:
9915 @ref{SHAPE}, @ref{RESHAPE}
9920 @section @code{SIZEOF} --- Size in bytes of an expression
9922 @cindex expression size
9923 @cindex size of an expression
9926 @item @emph{Description}:
9927 @code{SIZEOF(X)} calculates the number of bytes of storage the
9928 expression @code{X} occupies.
9930 @item @emph{Standard}:
9936 @item @emph{Syntax}:
9937 @code{N = SIZEOF(X)}
9939 @item @emph{Arguments}:
9940 @multitable @columnfractions .15 .70
9941 @item @var{X} @tab The argument shall be of any type, rank or shape.
9944 @item @emph{Return value}:
9945 The return value is of type integer and of the system-dependent kind
9946 @var{C_SIZE_T} (from the @var{ISO_C_BINDING} module). Its value is the
9947 number of bytes occupied by the argument. If the argument has the
9948 @code{POINTER} attribute, the number of bytes of the storage area pointed
9949 to is returned. If the argument is of a derived type with @code{POINTER}
9950 or @code{ALLOCATABLE} components, the return value doesn't account for
9951 the sizes of the data pointed to by these components.
9953 @item @emph{Example}:
9957 print *, (sizeof(s)/sizeof(r) == 5)
9960 The example will print @code{.TRUE.} unless you are using a platform
9961 where default @code{REAL} variables are unusually padded.
9963 @item @emph{See also}:
9969 @section @code{SLEEP} --- Sleep for the specified number of seconds
9971 @cindex delayed execution
9974 @item @emph{Description}:
9975 Calling this subroutine causes the process to pause for @var{SECONDS} seconds.
9977 @item @emph{Standard}:
9983 @item @emph{Syntax}:
9984 @code{CALL SLEEP(SECONDS)}
9986 @item @emph{Arguments}:
9987 @multitable @columnfractions .15 .70
9988 @item @var{SECONDS} @tab The type shall be of default @code{INTEGER}.
9991 @item @emph{Example}:
10002 @section @code{SNGL} --- Convert double precision real to default real
10004 @cindex conversion, to real
10007 @item @emph{Description}:
10008 @code{SNGL(A)} converts the double precision real @var{A}
10009 to a default real value. This is an archaic form of @code{REAL}
10010 that is specific to one type for @var{A}.
10012 @item @emph{Standard}:
10013 Fortran 77 and later
10015 @item @emph{Class}:
10018 @item @emph{Syntax}:
10019 @code{RESULT = SNGL(A)}
10021 @item @emph{Arguments}:
10022 @multitable @columnfractions .15 .70
10023 @item @var{A} @tab The type shall be a double precision @code{REAL}.
10026 @item @emph{Return value}:
10027 The return value is of type default @code{REAL}.
10029 @item @emph{See also}:
10036 @section @code{SPACING} --- Smallest distance between two numbers of a given type
10038 @cindex real number, relative spacing
10039 @cindex floating point, relative spacing
10042 @item @emph{Description}:
10043 Determines the distance between the argument @var{X} and the nearest
10044 adjacent number of the same type.
10046 @item @emph{Standard}:
10047 Fortran 95 and later
10049 @item @emph{Class}:
10052 @item @emph{Syntax}:
10053 @code{RESULT = SPACING(X)}
10055 @item @emph{Arguments}:
10056 @multitable @columnfractions .15 .70
10057 @item @var{X} @tab Shall be of type @code{REAL}.
10060 @item @emph{Return value}:
10061 The result is of the same type as the input argument @var{X}.
10063 @item @emph{Example}:
10065 PROGRAM test_spacing
10066 INTEGER, PARAMETER :: SGL = SELECTED_REAL_KIND(p=6, r=37)
10067 INTEGER, PARAMETER :: DBL = SELECTED_REAL_KIND(p=13, r=200)
10069 WRITE(*,*) spacing(1.0_SGL) ! "1.1920929E-07" on i686
10070 WRITE(*,*) spacing(1.0_DBL) ! "2.220446049250313E-016" on i686
10074 @item @emph{See also}:
10081 @section @code{SPREAD} --- Add a dimension to an array
10083 @cindex array, increase dimension
10084 @cindex array, duplicate elements
10085 @cindex array, duplicate dimensions
10088 @item @emph{Description}:
10089 Replicates a @var{SOURCE} array @var{NCOPIES} times along a specified
10090 dimension @var{DIM}.
10092 @item @emph{Standard}:
10093 Fortran 95 and later
10095 @item @emph{Class}:
10096 Transformational function
10098 @item @emph{Syntax}:
10099 @code{RESULT = SPREAD(SOURCE, DIM, NCOPIES)}
10101 @item @emph{Arguments}:
10102 @multitable @columnfractions .15 .70
10103 @item @var{SOURCE} @tab Shall be a scalar or an array of any type and
10104 a rank less than seven.
10105 @item @var{DIM} @tab Shall be a scalar of type @code{INTEGER} with a
10106 value in the range from 1 to n+1, where n equals the rank of @var{SOURCE}.
10107 @item @var{NCOPIES} @tab Shall be a scalar of type @code{INTEGER}.
10110 @item @emph{Return value}:
10111 The result is an array of the same type as @var{SOURCE} and has rank n+1
10112 where n equals the rank of @var{SOURCE}.
10114 @item @emph{Example}:
10116 PROGRAM test_spread
10117 INTEGER :: a = 1, b(2) = (/ 1, 2 /)
10118 WRITE(*,*) SPREAD(A, 1, 2) ! "1 1"
10119 WRITE(*,*) SPREAD(B, 1, 2) ! "1 1 2 2"
10123 @item @emph{See also}:
10130 @section @code{SQRT} --- Square-root function
10137 @cindex square-root
10140 @item @emph{Description}:
10141 @code{SQRT(X)} computes the square root of @var{X}.
10143 @item @emph{Standard}:
10144 Fortran 77 and later
10146 @item @emph{Class}:
10149 @item @emph{Syntax}:
10150 @code{RESULT = SQRT(X)}
10152 @item @emph{Arguments}:
10153 @multitable @columnfractions .15 .70
10154 @item @var{X} @tab The type shall be @code{REAL} or
10158 @item @emph{Return value}:
10159 The return value is of type @code{REAL} or @code{COMPLEX}.
10160 The kind type parameter is the same as @var{X}.
10162 @item @emph{Example}:
10165 real(8) :: x = 2.0_8
10166 complex :: z = (1.0, 2.0)
10169 end program test_sqrt
10172 @item @emph{Specific names}:
10173 @multitable @columnfractions .20 .20 .20 .25
10174 @item Name @tab Argument @tab Return type @tab Standard
10175 @item @code{DSQRT(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab Fortran 95 and later
10176 @item @code{CSQRT(X)} @tab @code{COMPLEX(4) X} @tab @code{COMPLEX(4)} @tab Fortran 95 and later
10177 @item @code{ZSQRT(X)} @tab @code{COMPLEX(8) X} @tab @code{COMPLEX(8)} @tab GNU extension
10178 @item @code{CDSQRT(X)} @tab @code{COMPLEX(8) X} @tab @code{COMPLEX(8)} @tab GNU extension
10185 @section @code{SRAND} --- Reinitialize the random number generator
10187 @cindex random number generation, seeding
10188 @cindex seeding a random number generator
10191 @item @emph{Description}:
10192 @code{SRAND} reinitializes the pseudo-random number generator
10193 called by @code{RAND} and @code{IRAND}. The new seed used by the
10194 generator is specified by the required argument @var{SEED}.
10196 @item @emph{Standard}:
10199 @item @emph{Class}:
10202 @item @emph{Syntax}:
10203 @code{CALL SRAND(SEED)}
10205 @item @emph{Arguments}:
10206 @multitable @columnfractions .15 .70
10207 @item @var{SEED} @tab Shall be a scalar @code{INTEGER(kind=4)}.
10210 @item @emph{Return value}:
10211 Does not return anything.
10213 @item @emph{Example}:
10214 See @code{RAND} and @code{IRAND} for examples.
10216 @item @emph{Notes}:
10217 The Fortran 2003 standard specifies the intrinsic @code{RANDOM_SEED} to
10218 initialize the pseudo-random numbers generator and @code{RANDOM_NUMBER}
10219 to generate pseudo-random numbers. Please note that in
10220 GNU Fortran, these two sets of intrinsics (@code{RAND},
10221 @code{IRAND} and @code{SRAND} on the one hand, @code{RANDOM_NUMBER} and
10222 @code{RANDOM_SEED} on the other hand) access two independent
10223 pseudo-random number generators.
10225 @item @emph{See also}:
10226 @ref{RAND}, @ref{RANDOM_SEED}, @ref{RANDOM_NUMBER}
10233 @section @code{STAT} --- Get file status
10235 @cindex file system, file status
10238 @item @emph{Description}:
10239 This function returns information about a file. No permissions are required on
10240 the file itself, but execute (search) permission is required on all of the
10241 directories in path that lead to the file.
10243 The elements that are obtained and stored in the array @code{VALUES}:
10244 @multitable @columnfractions .15 .70
10245 @item @code{VALUES(1)} @tab Device ID
10246 @item @code{VALUES(2)} @tab Inode number
10247 @item @code{VALUES(3)} @tab File mode
10248 @item @code{VALUES(4)} @tab Number of links
10249 @item @code{VALUES(5)} @tab Owner's uid
10250 @item @code{VALUES(6)} @tab Owner's gid
10251 @item @code{VALUES(7)} @tab ID of device containing directory entry for file (0 if not available)
10252 @item @code{VALUES(8)} @tab File size (bytes)
10253 @item @code{VALUES(9)} @tab Last access time
10254 @item @code{VALUES(10)} @tab Last modification time
10255 @item @code{VALUES(11)} @tab Last file status change time
10256 @item @code{VALUES(12)} @tab Preferred I/O block size (-1 if not available)
10257 @item @code{VALUES(13)} @tab Number of blocks allocated (-1 if not available)
10260 Not all these elements are relevant on all systems.
10261 If an element is not relevant, it is returned as 0.
10263 This intrinsic is provided in both subroutine and function forms; however,
10264 only one form can be used in any given program unit.
10266 @item @emph{Standard}:
10269 @item @emph{Class}:
10270 Subroutine, function
10272 @item @emph{Syntax}:
10273 @code{CALL STAT(NAME, VALUES [, STATUS])}
10275 @item @emph{Arguments}:
10276 @multitable @columnfractions .15 .70
10277 @item @var{NAME} @tab The type shall be @code{CHARACTER}, of the
10278 default kind and a valid path within the file system.
10279 @item @var{VALUES} @tab The type shall be @code{INTEGER(4), DIMENSION(13)}.
10280 @item @var{STATUS} @tab (Optional) status flag of type @code{INTEGER(4)}. Returns 0
10281 on success and a system specific error code otherwise.
10284 @item @emph{Example}:
10287 INTEGER, DIMENSION(13) :: buff
10290 CALL STAT("/etc/passwd", buff, status)
10292 IF (status == 0) THEN
10293 WRITE (*, FMT="('Device ID:', T30, I19)") buff(1)
10294 WRITE (*, FMT="('Inode number:', T30, I19)") buff(2)
10295 WRITE (*, FMT="('File mode (octal):', T30, O19)") buff(3)
10296 WRITE (*, FMT="('Number of links:', T30, I19)") buff(4)
10297 WRITE (*, FMT="('Owner''s uid:', T30, I19)") buff(5)
10298 WRITE (*, FMT="('Owner''s gid:', T30, I19)") buff(6)
10299 WRITE (*, FMT="('Device where located:', T30, I19)") buff(7)
10300 WRITE (*, FMT="('File size:', T30, I19)") buff(8)
10301 WRITE (*, FMT="('Last access time:', T30, A19)") CTIME(buff(9))
10302 WRITE (*, FMT="('Last modification time', T30, A19)") CTIME(buff(10))
10303 WRITE (*, FMT="('Last status change time:', T30, A19)") CTIME(buff(11))
10304 WRITE (*, FMT="('Preferred block size:', T30, I19)") buff(12)
10305 WRITE (*, FMT="('No. of blocks allocated:', T30, I19)") buff(13)
10310 @item @emph{See also}:
10311 To stat an open file: @ref{FSTAT}, to stat a link: @ref{LSTAT}
10317 @section @code{SUM} --- Sum of array elements
10320 @cindex array, add elements
10321 @cindex array, conditionally add elements
10322 @cindex sum array elements
10325 @item @emph{Description}:
10326 Adds the elements of @var{ARRAY} along dimension @var{DIM} if
10327 the corresponding element in @var{MASK} is @code{TRUE}.
10329 @item @emph{Standard}:
10330 Fortran 95 and later
10332 @item @emph{Class}:
10333 Transformational function
10335 @item @emph{Syntax}:
10336 @multitable @columnfractions .80
10337 @item @code{RESULT = SUM(ARRAY[, MASK])}
10338 @item @code{RESULT = SUM(ARRAY, DIM[, MASK])}
10341 @item @emph{Arguments}:
10342 @multitable @columnfractions .15 .70
10343 @item @var{ARRAY} @tab Shall be an array of type @code{INTEGER},
10344 @code{REAL} or @code{COMPLEX}.
10345 @item @var{DIM} @tab (Optional) shall be a scalar of type
10346 @code{INTEGER} with a value in the range from 1 to n, where n
10347 equals the rank of @var{ARRAY}.
10348 @item @var{MASK} @tab (Optional) shall be of type @code{LOGICAL}
10349 and either be a scalar or an array of the same shape as @var{ARRAY}.
10352 @item @emph{Return value}:
10353 The result is of the same type as @var{ARRAY}.
10355 If @var{DIM} is absent, a scalar with the sum of all elements in @var{ARRAY}
10356 is returned. Otherwise, an array of rank n-1, where n equals the rank of
10357 @var{ARRAY},and a shape similar to that of @var{ARRAY} with dimension @var{DIM}
10358 dropped is returned.
10360 @item @emph{Example}:
10363 INTEGER :: x(5) = (/ 1, 2, 3, 4 ,5 /)
10364 print *, SUM(x) ! all elements, sum = 15
10365 print *, SUM(x, MASK=MOD(x, 2)==1) ! odd elements, sum = 9
10369 @item @emph{See also}:
10376 @section @code{SYMLNK} --- Create a symbolic link
10378 @cindex file system, create link
10379 @cindex file system, soft link
10382 @item @emph{Description}:
10383 Makes a symbolic link from file @var{PATH1} to @var{PATH2}. A null
10384 character (@code{CHAR(0)}) can be used to mark the end of the names in
10385 @var{PATH1} and @var{PATH2}; otherwise, trailing blanks in the file
10386 names are ignored. If the @var{STATUS} argument is supplied, it
10387 contains 0 on success or a nonzero error code upon return; see
10388 @code{symlink(2)}. If the system does not supply @code{symlink(2)},
10389 @code{ENOSYS} is returned.
10391 This intrinsic is provided in both subroutine and function forms;
10392 however, only one form can be used in any given program unit.
10394 @item @emph{Standard}:
10397 @item @emph{Class}:
10398 Subroutine, function
10400 @item @emph{Syntax}:
10401 @multitable @columnfractions .80
10402 @item @code{CALL SYMLNK(PATH1, PATH2 [, STATUS])}
10403 @item @code{STATUS = SYMLNK(PATH1, PATH2)}
10406 @item @emph{Arguments}:
10407 @multitable @columnfractions .15 .70
10408 @item @var{PATH1} @tab Shall be of default @code{CHARACTER} type.
10409 @item @var{PATH2} @tab Shall be of default @code{CHARACTER} type.
10410 @item @var{STATUS} @tab (Optional) Shall be of default @code{INTEGER} type.
10413 @item @emph{See also}:
10414 @ref{LINK}, @ref{UNLINK}
10421 @section @code{SYSTEM} --- Execute a shell command
10423 @cindex system, system call
10426 @item @emph{Description}:
10427 Passes the command @var{COMMAND} to a shell (see @code{system(3)}). If
10428 argument @var{STATUS} is present, it contains the value returned by
10429 @code{system(3)}, which is presumably 0 if the shell command succeeded.
10430 Note that which shell is used to invoke the command is system-dependent
10431 and environment-dependent.
10433 This intrinsic is provided in both subroutine and function forms;
10434 however, only one form can be used in any given program unit.
10436 @item @emph{Standard}:
10439 @item @emph{Class}:
10440 Subroutine, function
10442 @item @emph{Syntax}:
10443 @multitable @columnfractions .80
10444 @item @code{CALL SYSTEM(COMMAND [, STATUS])}
10445 @item @code{STATUS = SYSTEM(COMMAND)}
10448 @item @emph{Arguments}:
10449 @multitable @columnfractions .15 .70
10450 @item @var{COMMAND} @tab Shall be of default @code{CHARACTER} type.
10451 @item @var{STATUS} @tab (Optional) Shall be of default @code{INTEGER} type.
10454 @item @emph{See also}:
10460 @section @code{SYSTEM_CLOCK} --- Time function
10461 @fnindex SYSTEM_CLOCK
10462 @cindex time, clock ticks
10463 @cindex clock ticks
10466 @item @emph{Description}:
10467 Determines the @var{COUNT} of milliseconds of wall clock time since
10468 the Epoch (00:00:00 UTC, January 1, 1970) modulo @var{COUNT_MAX},
10469 @var{COUNT_RATE} determines the number of clock ticks per second.
10470 @var{COUNT_RATE} and @var{COUNT_MAX} are constant and specific to
10471 @command{gfortran}.
10473 If there is no clock, @var{COUNT} is set to @code{-HUGE(COUNT)}, and
10474 @var{COUNT_RATE} and @var{COUNT_MAX} are set to zero
10476 @item @emph{Standard}:
10477 Fortran 95 and later
10479 @item @emph{Class}:
10482 @item @emph{Syntax}:
10483 @code{CALL SYSTEM_CLOCK([COUNT, COUNT_RATE, COUNT_MAX])}
10485 @item @emph{Arguments}:
10486 @item @emph{Arguments}:
10487 @multitable @columnfractions .15 .70
10488 @item @var{COUNT} @tab (Optional) shall be a scalar of type default
10489 @code{INTEGER} with @code{INTENT(OUT)}.
10490 @item @var{COUNT_RATE} @tab (Optional) shall be a scalar of type default
10491 @code{INTEGER} with @code{INTENT(OUT)}.
10492 @item @var{COUNT_MAX} @tab (Optional) shall be a scalar of type default
10493 @code{INTEGER} with @code{INTENT(OUT)}.
10496 @item @emph{Example}:
10498 PROGRAM test_system_clock
10499 INTEGER :: count, count_rate, count_max
10500 CALL SYSTEM_CLOCK(count, count_rate, count_max)
10501 WRITE(*,*) count, count_rate, count_max
10505 @item @emph{See also}:
10506 @ref{DATE_AND_TIME}, @ref{CPU_TIME}
10512 @section @code{TAN} --- Tangent function
10515 @cindex trigonometric function, tangent
10519 @item @emph{Description}:
10520 @code{TAN(X)} computes the tangent of @var{X}.
10522 @item @emph{Standard}:
10523 Fortran 77 and later, for a complex argument Fortran 2008 or later
10525 @item @emph{Class}:
10528 @item @emph{Syntax}:
10529 @code{RESULT = TAN(X)}
10531 @item @emph{Arguments}:
10532 @multitable @columnfractions .15 .70
10533 @item @var{X} @tab The type shall be @code{REAL} or @code{COMPLEX}.
10536 @item @emph{Return value}:
10537 The return value has same type and kind as @var{X}.
10539 @item @emph{Example}:
10542 real(8) :: x = 0.165_8
10544 end program test_tan
10547 @item @emph{Specific names}:
10548 @multitable @columnfractions .20 .20 .20 .25
10549 @item Name @tab Argument @tab Return type @tab Standard
10550 @item @code{DTAN(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab Fortran 95 and later
10553 @item @emph{See also}:
10560 @section @code{TANH} --- Hyperbolic tangent function
10563 @cindex hyperbolic tangent
10564 @cindex hyperbolic function, tangent
10565 @cindex tangent, hyperbolic
10568 @item @emph{Description}:
10569 @code{TANH(X)} computes the hyperbolic tangent of @var{X}.
10571 @item @emph{Standard}:
10572 Fortran 77 and later, for a complex argument Fortran 2008 or later
10574 @item @emph{Class}:
10577 @item @emph{Syntax}:
10580 @item @emph{Arguments}:
10581 @multitable @columnfractions .15 .70
10582 @item @var{X} @tab The type shall be @code{REAL} or @code{COMPLEX}.
10585 @item @emph{Return value}:
10586 The return value has same type and kind as @var{X}. If @var{X} is
10587 complex, the imaginary part of the result is in radians. If @var{X}
10588 is @code{REAL}, the return value lies in the range
10589 @math{ - 1 \leq tanh(x) \leq 1 }.
10591 @item @emph{Example}:
10594 real(8) :: x = 2.1_8
10596 end program test_tanh
10599 @item @emph{Specific names}:
10600 @multitable @columnfractions .20 .20 .20 .25
10601 @item Name @tab Argument @tab Return type @tab Standard
10602 @item @code{DTANH(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab Fortran 95 and later
10605 @item @emph{See also}:
10612 @section @code{TIME} --- Time function
10614 @cindex time, current
10615 @cindex current time
10618 @item @emph{Description}:
10619 Returns the current time encoded as an integer (in the manner of the
10620 UNIX function @code{time(3)}). This value is suitable for passing to
10621 @code{CTIME()}, @code{GMTIME()}, and @code{LTIME()}.
10623 This intrinsic is not fully portable, such as to systems with 32-bit
10624 @code{INTEGER} types but supporting times wider than 32 bits. Therefore,
10625 the values returned by this intrinsic might be, or become, negative, or
10626 numerically less than previous values, during a single run of the
10629 See @ref{TIME8}, for information on a similar intrinsic that might be
10630 portable to more GNU Fortran implementations, though to fewer Fortran
10633 @item @emph{Standard}:
10636 @item @emph{Class}:
10639 @item @emph{Syntax}:
10640 @code{RESULT = TIME()}
10642 @item @emph{Return value}:
10643 The return value is a scalar of type @code{INTEGER(4)}.
10645 @item @emph{See also}:
10646 @ref{CTIME}, @ref{GMTIME}, @ref{LTIME}, @ref{MCLOCK}, @ref{TIME8}
10653 @section @code{TIME8} --- Time function (64-bit)
10655 @cindex time, current
10656 @cindex current time
10659 @item @emph{Description}:
10660 Returns the current time encoded as an integer (in the manner of the
10661 UNIX function @code{time(3)}). This value is suitable for passing to
10662 @code{CTIME()}, @code{GMTIME()}, and @code{LTIME()}.
10664 @emph{Warning:} this intrinsic does not increase the range of the timing
10665 values over that returned by @code{time(3)}. On a system with a 32-bit
10666 @code{time(3)}, @code{TIME8()} will return a 32-bit value, even though
10667 it is converted to a 64-bit @code{INTEGER(8)} value. That means
10668 overflows of the 32-bit value can still occur. Therefore, the values
10669 returned by this intrinsic might be or become negative or numerically
10670 less than previous values during a single run of the compiled program.
10672 @item @emph{Standard}:
10675 @item @emph{Class}:
10678 @item @emph{Syntax}:
10679 @code{RESULT = TIME8()}
10681 @item @emph{Return value}:
10682 The return value is a scalar of type @code{INTEGER(8)}.
10684 @item @emph{See also}:
10685 @ref{CTIME}, @ref{GMTIME}, @ref{LTIME}, @ref{MCLOCK8}, @ref{TIME}
10692 @section @code{TINY} --- Smallest positive number of a real kind
10694 @cindex limits, smallest number
10695 @cindex model representation, smallest number
10698 @item @emph{Description}:
10699 @code{TINY(X)} returns the smallest positive (non zero) number
10700 in the model of the type of @code{X}.
10702 @item @emph{Standard}:
10703 Fortran 95 and later
10705 @item @emph{Class}:
10708 @item @emph{Syntax}:
10709 @code{RESULT = TINY(X)}
10711 @item @emph{Arguments}:
10712 @multitable @columnfractions .15 .70
10713 @item @var{X} @tab Shall be of type @code{REAL}.
10716 @item @emph{Return value}:
10717 The return value is of the same type and kind as @var{X}
10719 @item @emph{Example}:
10720 See @code{HUGE} for an example.
10726 @section @code{TRAILZ} --- Number of trailing zero bits of an integer
10731 @item @emph{Description}:
10732 @code{TRAILZ} returns the number of trailing zero bits of an integer.
10734 @item @emph{Standard}:
10735 Fortran 2008 and later
10737 @item @emph{Class}:
10740 @item @emph{Syntax}:
10741 @code{RESULT = TRAILZ(I)}
10743 @item @emph{Arguments}:
10744 @multitable @columnfractions .15 .70
10745 @item @var{I} @tab Shall be of type @code{INTEGER}.
10748 @item @emph{Return value}:
10749 The type of the return value is the default @code{INTEGER}.
10750 If all the bits of @code{I} are zero, the result value is @code{BIT_SIZE(I)}.
10752 @item @emph{Example}:
10754 PROGRAM test_trailz
10755 WRITE (*,*) TRAILZ(8) ! prints 3
10759 @item @emph{See also}:
10760 @ref{BIT_SIZE}, @ref{LEADZ}
10766 @section @code{TRANSFER} --- Transfer bit patterns
10772 @item @emph{Description}:
10773 Interprets the bitwise representation of @var{SOURCE} in memory as if it
10774 is the representation of a variable or array of the same type and type
10775 parameters as @var{MOLD}.
10777 This is approximately equivalent to the C concept of @emph{casting} one
10780 @item @emph{Standard}:
10781 Fortran 95 and later
10783 @item @emph{Class}:
10784 Transformational function
10786 @item @emph{Syntax}:
10787 @code{RESULT = TRANSFER(SOURCE, MOLD[, SIZE])}
10789 @item @emph{Arguments}:
10790 @multitable @columnfractions .15 .70
10791 @item @var{SOURCE} @tab Shall be a scalar or an array of any type.
10792 @item @var{MOLD} @tab Shall be a scalar or an array of any type.
10793 @item @var{SIZE} @tab (Optional) shall be a scalar of type
10797 @item @emph{Return value}:
10798 The result has the same type as @var{MOLD}, with the bit level
10799 representation of @var{SOURCE}. If @var{SIZE} is present, the result is
10800 a one-dimensional array of length @var{SIZE}. If @var{SIZE} is absent
10801 but @var{MOLD} is an array (of any size or shape), the result is a one-
10802 dimensional array of the minimum length needed to contain the entirety
10803 of the bitwise representation of @var{SOURCE}. If @var{SIZE} is absent
10804 and @var{MOLD} is a scalar, the result is a scalar.
10806 If the bitwise representation of the result is longer than that of
10807 @var{SOURCE}, then the leading bits of the result correspond to those of
10808 @var{SOURCE} and any trailing bits are filled arbitrarily.
10810 When the resulting bit representation does not correspond to a valid
10811 representation of a variable of the same type as @var{MOLD}, the results
10812 are undefined, and subsequent operations on the result cannot be
10813 guaranteed to produce sensible behavior. For example, it is possible to
10814 create @code{LOGICAL} variables for which @code{@var{VAR}} and
10815 @code{.NOT.@var{VAR}} both appear to be true.
10817 @item @emph{Example}:
10819 PROGRAM test_transfer
10820 integer :: x = 2143289344
10821 print *, transfer(x, 1.0) ! prints "NaN" on i686
10829 @section @code{TRANSPOSE} --- Transpose an array of rank two
10831 @cindex array, transpose
10832 @cindex matrix, transpose
10836 @item @emph{Description}:
10837 Transpose an array of rank two. Element (i, j) of the result has the value
10838 @code{MATRIX(j, i)}, for all i, j.
10840 @item @emph{Standard}:
10841 Fortran 95 and later
10843 @item @emph{Class}:
10844 Transformational function
10846 @item @emph{Syntax}:
10847 @code{RESULT = TRANSPOSE(MATRIX)}
10849 @item @emph{Arguments}:
10850 @multitable @columnfractions .15 .70
10851 @item @var{MATRIX} @tab Shall be an array of any type and have a rank of two.
10854 @item @emph{Return value}:
10855 The result has the same type as @var{MATRIX}, and has shape
10856 @code{(/ m, n /)} if @var{MATRIX} has shape @code{(/ n, m /)}.
10862 @section @code{TRIM} --- Remove trailing blank characters of a string
10864 @cindex string, remove trailing whitespace
10867 @item @emph{Description}:
10868 Removes trailing blank characters of a string.
10870 @item @emph{Standard}:
10871 Fortran 95 and later
10873 @item @emph{Class}:
10874 Transformational function
10876 @item @emph{Syntax}:
10877 @code{RESULT = TRIM(STRING)}
10879 @item @emph{Arguments}:
10880 @multitable @columnfractions .15 .70
10881 @item @var{STRING} @tab Shall be a scalar of type @code{CHARACTER}.
10884 @item @emph{Return value}:
10885 A scalar of type @code{CHARACTER} which length is that of @var{STRING}
10886 less the number of trailing blanks.
10888 @item @emph{Example}:
10891 CHARACTER(len=10), PARAMETER :: s = "GFORTRAN "
10892 WRITE(*,*) LEN(s), LEN(TRIM(s)) ! "10 8", with/without trailing blanks
10896 @item @emph{See also}:
10897 @ref{ADJUSTL}, @ref{ADJUSTR}
10903 @section @code{TTYNAM} --- Get the name of a terminal device.
10905 @cindex system, terminal
10908 @item @emph{Description}:
10909 Get the name of a terminal device. For more information,
10910 see @code{ttyname(3)}.
10912 This intrinsic is provided in both subroutine and function forms;
10913 however, only one form can be used in any given program unit.
10915 @item @emph{Standard}:
10918 @item @emph{Class}:
10919 Subroutine, function
10921 @item @emph{Syntax}:
10922 @multitable @columnfractions .80
10923 @item @code{CALL TTYNAM(UNIT, NAME)}
10924 @item @code{NAME = TTYNAM(UNIT)}
10927 @item @emph{Arguments}:
10928 @multitable @columnfractions .15 .70
10929 @item @var{UNIT} @tab Shall be a scalar @code{INTEGER}.
10930 @item @var{NAME} @tab Shall be of type @code{CHARACTER}.
10933 @item @emph{Example}:
10935 PROGRAM test_ttynam
10938 IF (isatty(unit=unit)) write(*,*) ttynam(unit)
10943 @item @emph{See also}:
10950 @section @code{UBOUND} --- Upper dimension bounds of an array
10952 @cindex array, upper bound
10955 @item @emph{Description}:
10956 Returns the upper bounds of an array, or a single upper bound
10957 along the @var{DIM} dimension.
10958 @item @emph{Standard}:
10959 Fortran 95 and later, with @var{KIND} argument Fortran 2003 and later
10961 @item @emph{Class}:
10964 @item @emph{Syntax}:
10965 @code{RESULT = UBOUND(ARRAY [, DIM [, KIND]])}
10967 @item @emph{Arguments}:
10968 @multitable @columnfractions .15 .70
10969 @item @var{ARRAY} @tab Shall be an array, of any type.
10970 @item @var{DIM} @tab (Optional) Shall be a scalar @code{INTEGER}.
10971 @item @var{KIND}@tab (Optional) An @code{INTEGER} initialization
10972 expression indicating the kind parameter of the result.
10975 @item @emph{Return value}:
10976 The return value is of type @code{INTEGER} and of kind @var{KIND}. If
10977 @var{KIND} is absent, the return value is of default integer kind.
10978 If @var{DIM} is absent, the result is an array of the upper bounds of
10979 @var{ARRAY}. If @var{DIM} is present, the result is a scalar
10980 corresponding to the upper bound of the array along that dimension. If
10981 @var{ARRAY} is an expression rather than a whole array or array
10982 structure component, or if it has a zero extent along the relevant
10983 dimension, the upper bound is taken to be the number of elements along
10984 the relevant dimension.
10986 @item @emph{See also}:
10993 @section @code{UMASK} --- Set the file creation mask
10995 @cindex file system, file creation mask
10998 @item @emph{Description}:
10999 Sets the file creation mask to @var{MASK}. If called as a function, it
11000 returns the old value. If called as a subroutine and argument @var{OLD}
11001 if it is supplied, it is set to the old value. See @code{umask(2)}.
11003 @item @emph{Standard}:
11006 @item @emph{Class}:
11007 Subroutine, function
11009 @item @emph{Syntax}:
11010 @code{CALL UMASK(MASK [, OLD])}
11011 @code{OLD = UMASK(MASK)}
11013 @item @emph{Arguments}:
11014 @multitable @columnfractions .15 .70
11015 @item @var{MASK} @tab Shall be a scalar of type @code{INTEGER}.
11016 @item @var{OLD} @tab (Optional) Shall be a scalar of type
11025 @section @code{UNLINK} --- Remove a file from the file system
11027 @cindex file system, remove file
11030 @item @emph{Description}:
11031 Unlinks the file @var{PATH}. A null character (@code{CHAR(0)}) can be
11032 used to mark the end of the name in @var{PATH}; otherwise, trailing
11033 blanks in the file name are ignored. If the @var{STATUS} argument is
11034 supplied, it contains 0 on success or a nonzero error code upon return;
11035 see @code{unlink(2)}.
11037 This intrinsic is provided in both subroutine and function forms;
11038 however, only one form can be used in any given program unit.
11040 @item @emph{Standard}:
11043 @item @emph{Class}:
11044 Subroutine, function
11046 @item @emph{Syntax}:
11047 @multitable @columnfractions .80
11048 @item @code{CALL UNLINK(PATH [, STATUS])}
11049 @item @code{STATUS = UNLINK(PATH)}
11052 @item @emph{Arguments}:
11053 @multitable @columnfractions .15 .70
11054 @item @var{PATH} @tab Shall be of default @code{CHARACTER} type.
11055 @item @var{STATUS} @tab (Optional) Shall be of default @code{INTEGER} type.
11058 @item @emph{See also}:
11059 @ref{LINK}, @ref{SYMLNK}
11065 @section @code{UNPACK} --- Unpack an array of rank one into an array
11067 @cindex array, unpacking
11068 @cindex array, increase dimension
11069 @cindex array, scatter elements
11072 @item @emph{Description}:
11073 Store the elements of @var{VECTOR} in an array of higher rank.
11075 @item @emph{Standard}:
11076 Fortran 95 and later
11078 @item @emph{Class}:
11079 Transformational function
11081 @item @emph{Syntax}:
11082 @code{RESULT = UNPACK(VECTOR, MASK, FIELD)}
11084 @item @emph{Arguments}:
11085 @multitable @columnfractions .15 .70
11086 @item @var{VECTOR} @tab Shall be an array of any type and rank one. It
11087 shall have at least as many elements as @var{MASK} has @code{TRUE} values.
11088 @item @var{MASK} @tab Shall be an array of type @code{LOGICAL}.
11089 @item @var{FIELD} @tab Shall be of the same type as @var{VECTOR} and have
11090 the same shape as @var{MASK}.
11093 @item @emph{Return value}:
11094 The resulting array corresponds to @var{FIELD} with @code{TRUE} elements
11095 of @var{MASK} replaced by values from @var{VECTOR} in array element order.
11097 @item @emph{Example}:
11099 PROGRAM test_unpack
11100 integer :: vector(2) = (/1,1/)
11101 logical :: mask(4) = (/ .TRUE., .FALSE., .FALSE., .TRUE. /)
11102 integer :: field(2,2) = 0, unity(2,2)
11104 ! result: unity matrix
11105 unity = unpack(vector, reshape(mask, (/2,2/)), field)
11109 @item @emph{See also}:
11110 @ref{PACK}, @ref{SPREAD}
11116 @section @code{VERIFY} --- Scan a string for the absence of a set of characters
11118 @cindex string, find missing set
11121 @item @emph{Description}:
11122 Verifies that all the characters in a @var{SET} are present in a @var{STRING}.
11124 If @var{BACK} is either absent or equals @code{FALSE}, this function
11125 returns the position of the leftmost character of @var{STRING} that is
11126 not in @var{SET}. If @var{BACK} equals @code{TRUE}, the rightmost position
11127 is returned. If all characters of @var{SET} are found in @var{STRING}, the
11130 @item @emph{Standard}:
11131 Fortran 95 and later, with @var{KIND} argument Fortran 2003 and later
11133 @item @emph{Class}:
11136 @item @emph{Syntax}:
11137 @code{RESULT = VERIFY(STRING, SET[, BACK [, KIND]])}
11139 @item @emph{Arguments}:
11140 @multitable @columnfractions .15 .70
11141 @item @var{STRING} @tab Shall be of type @code{CHARACTER}.
11142 @item @var{SET} @tab Shall be of type @code{CHARACTER}.
11143 @item @var{BACK} @tab (Optional) shall be of type @code{LOGICAL}.
11144 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
11145 expression indicating the kind parameter of the result.
11148 @item @emph{Return value}:
11149 The return value is of type @code{INTEGER} and of kind @var{KIND}. If
11150 @var{KIND} is absent, the return value is of default integer kind.
11152 @item @emph{Example}:
11154 PROGRAM test_verify
11155 WRITE(*,*) VERIFY("FORTRAN", "AO") ! 1, found 'F'
11156 WRITE(*,*) VERIFY("FORTRAN", "FOO") ! 3, found 'R'
11157 WRITE(*,*) VERIFY("FORTRAN", "C++") ! 1, found 'F'
11158 WRITE(*,*) VERIFY("FORTRAN", "C++", .TRUE.) ! 7, found 'N'
11159 WRITE(*,*) VERIFY("FORTRAN", "FORTRAN") ! 0' found none
11163 @item @emph{See also}:
11164 @ref{SCAN}, @ref{INDEX intrinsic}
11170 @section @code{XOR} --- Bitwise logical exclusive OR
11172 @cindex bitwise logical exclusive or
11173 @cindex logical exclusive or, bitwise
11176 @item @emph{Description}:
11177 Bitwise logical exclusive or.
11179 This intrinsic routine is provided for backwards compatibility with
11180 GNU Fortran 77. For integer arguments, programmers should consider
11181 the use of the @ref{IEOR} intrinsic and for logical arguments the
11182 @code{.NEQV.} operator, which are both defined by the Fortran standard.
11184 @item @emph{Standard}:
11187 @item @emph{Class}:
11190 @item @emph{Syntax}:
11191 @code{RESULT = XOR(I, J)}
11193 @item @emph{Arguments}:
11194 @multitable @columnfractions .15 .70
11195 @item @var{I} @tab The type shall be either a scalar @code{INTEGER}
11196 type or a scalar @code{LOGICAL} type.
11197 @item @var{J} @tab The type shall be the same as the type of @var{I}.
11200 @item @emph{Return value}:
11201 The return type is either a scalar @code{INTEGER} or a scalar
11202 @code{LOGICAL}. If the kind type parameters differ, then the
11203 smaller kind type is implicitly converted to larger kind, and the
11204 return has the larger kind.
11206 @item @emph{Example}:
11209 LOGICAL :: T = .TRUE., F = .FALSE.
11211 DATA a / Z'F' /, b / Z'3' /
11213 WRITE (*,*) XOR(T, T), XOR(T, F), XOR(F, T), XOR(F, F)
11214 WRITE (*,*) XOR(a, b)
11218 @item @emph{See also}:
11219 Fortran 95 elemental function: @ref{IEOR}
11224 @node Intrinsic Modules
11225 @chapter Intrinsic Modules
11226 @cindex intrinsic Modules
11229 * ISO_FORTRAN_ENV::
11231 * OpenMP Modules OMP_LIB and OMP_LIB_KINDS::
11234 @node ISO_FORTRAN_ENV
11235 @section @code{ISO_FORTRAN_ENV}
11237 @item @emph{Standard}:
11238 Fortran 2003 and later; @code{INT8}, @code{INT16}, @code{INT32}, @code{INT64},
11239 @code{REAL32}, @code{REAL64}, @code{REAL128} are Fortran 2008 or later
11242 The @code{ISO_FORTRAN_ENV} module provides the following scalar default-integer
11246 @item @code{CHARACTER_STORAGE_SIZE}:
11247 Size in bits of the character storage unit.
11249 @item @code{ERROR_UNIT}:
11250 Identifies the preconnected unit used for error reporting.
11252 @item @code{FILE_STORAGE_SIZE}:
11253 Size in bits of the file-storage unit.
11255 @item @code{INPUT_UNIT}:
11256 Identifies the preconnected unit identified by the asterisk
11257 (@code{*}) in @code{READ} statement.
11259 @item @code{INT8}, @code{INT16}, @code{INT32}, @code{INT64}
11260 Kind type parameters to specify an INTEGER type with a storage
11261 size of 16, 32, and 64 bits. It is negative if a target platform
11262 does not support the particular kind.
11264 @item @code{IOSTAT_END}:
11265 The value assigned to the variable passed to the IOSTAT= specifier of
11266 an input/output statement if an end-of-file condition occurred.
11268 @item @code{IOSTAT_EOR}:
11269 The value assigned to the variable passed to the IOSTAT= specifier of
11270 an input/output statement if an end-of-record condition occurred.
11272 @item @code{NUMERIC_STORAGE_SIZE}:
11273 The size in bits of the numeric storage unit.
11275 @item @code{OUTPUT_UNIT}:
11276 Identifies the preconnected unit identified by the asterisk
11277 (@code{*}) in @code{WRITE} statement.
11279 @item @code{REAL32}, @code{REAL64}, @code{REAL128}
11280 Kind type parameters to specify a REAL type with a storage
11281 size of 32, 64, and 128 bits. It is negative if a target platform
11282 does not support the particular kind.
11287 @node ISO_C_BINDING
11288 @section @code{ISO_C_BINDING}
11290 @item @emph{Standard}:
11291 Fortran 2003 and later, GNU extensions
11294 The following intrinsic procedures are provided by the module; their
11295 definition can be found in the section Intrinsic Procedures of this
11299 @item @code{C_ASSOCIATED}
11300 @item @code{C_F_POINTER}
11301 @item @code{C_F_PROCPOINTER}
11302 @item @code{C_FUNLOC}
11305 @c TODO: Vertical spacing between C_FUNLOC and C_LOC wrong in PDF,
11306 @c don't really know why.
11308 The @code{ISO_C_BINDING} module provides the following named constants of
11309 type default integer, which can be used as KIND type parameters.
11311 In addition to the integer named constants required by the Fortran 2003
11312 standard, GNU Fortran provides as an extension named constants for the
11313 128-bit integer types supported by the C compiler: @code{C_INT128_T,
11314 C_INT_LEAST128_T, C_INT_FAST128_T}.
11316 @multitable @columnfractions .15 .35 .35 .35
11317 @item Fortran Type @tab Named constant @tab C type @tab Extension
11318 @item @code{INTEGER}@tab @code{C_INT} @tab @code{int}
11319 @item @code{INTEGER}@tab @code{C_SHORT} @tab @code{short int}
11320 @item @code{INTEGER}@tab @code{C_LONG} @tab @code{long int}
11321 @item @code{INTEGER}@tab @code{C_LONG_LONG} @tab @code{long long int}
11322 @item @code{INTEGER}@tab @code{C_SIGNED_CHAR} @tab @code{signed char}/@code{unsigned char}
11323 @item @code{INTEGER}@tab @code{C_SIZE_T} @tab @code{size_t}
11324 @item @code{INTEGER}@tab @code{C_INT8_T} @tab @code{int8_t}
11325 @item @code{INTEGER}@tab @code{C_INT16_T} @tab @code{int16_t}
11326 @item @code{INTEGER}@tab @code{C_INT32_T} @tab @code{int32_t}
11327 @item @code{INTEGER}@tab @code{C_INT64_T} @tab @code{int64_t}
11328 @item @code{INTEGER}@tab @code{C_INT128_T} @tab @code{int128_t} @tab Ext.
11329 @item @code{INTEGER}@tab @code{C_INT_LEAST8_T} @tab @code{int_least8_t}
11330 @item @code{INTEGER}@tab @code{C_INT_LEAST16_T} @tab @code{int_least16_t}
11331 @item @code{INTEGER}@tab @code{C_INT_LEAST32_T} @tab @code{int_least32_t}
11332 @item @code{INTEGER}@tab @code{C_INT_LEAST64_T} @tab @code{int_least64_t}
11333 @item @code{INTEGER}@tab @code{C_INT_LEAST128_T}@tab @code{int_least128_t} @tab Ext.
11334 @item @code{INTEGER}@tab @code{C_INT_FAST8_T} @tab @code{int_fast8_t}
11335 @item @code{INTEGER}@tab @code{C_INT_FAST16_T} @tab @code{int_fast16_t}
11336 @item @code{INTEGER}@tab @code{C_INT_FAST32_T} @tab @code{int_fast32_t}
11337 @item @code{INTEGER}@tab @code{C_INT_FAST64_T} @tab @code{int_fast64_t}
11338 @item @code{INTEGER}@tab @code{C_INT_FAST128_T} @tab @code{int_fast128_t} @tab Ext.
11339 @item @code{INTEGER}@tab @code{C_INTMAX_T} @tab @code{intmax_t}
11340 @item @code{INTEGER}@tab @code{C_INTPTR_T} @tab @code{intptr_t}
11341 @item @code{REAL} @tab @code{C_FLOAT} @tab @code{float}
11342 @item @code{REAL} @tab @code{C_DOUBLE} @tab @code{double}
11343 @item @code{REAL} @tab @code{C_LONG_DOUBLE} @tab @code{long double}
11344 @item @code{COMPLEX}@tab @code{C_FLOAT_COMPLEX} @tab @code{float _Complex}
11345 @item @code{COMPLEX}@tab @code{C_DOUBLE_COMPLEX}@tab @code{double _Complex}
11346 @item @code{COMPLEX}@tab @code{C_LONG_DOUBLE_COMPLEX}@tab @code{long double _Complex}
11347 @item @code{LOGICAL}@tab @code{C_BOOL} @tab @code{_Bool}
11348 @item @code{CHARACTER}@tab @code{C_CHAR} @tab @code{char}
11351 Additionally, the following @code{(CHARACTER(KIND=C_CHAR))} are
11354 @multitable @columnfractions .20 .45 .15
11355 @item Name @tab C definition @tab Value
11356 @item @code{C_NULL_CHAR} @tab null character @tab @code{'\0'}
11357 @item @code{C_ALERT} @tab alert @tab @code{'\a'}
11358 @item @code{C_BACKSPACE} @tab backspace @tab @code{'\b'}
11359 @item @code{C_FORM_FEED} @tab form feed @tab @code{'\f'}
11360 @item @code{C_NEW_LINE} @tab new line @tab @code{'\n'}
11361 @item @code{C_CARRIAGE_RETURN} @tab carriage return @tab @code{'\r'}
11362 @item @code{C_HORIZONTAL_TAB} @tab horizontal tab @tab @code{'\t'}
11363 @item @code{C_VERTICAL_TAB} @tab vertical tab @tab @code{'\v'}
11366 @node OpenMP Modules OMP_LIB and OMP_LIB_KINDS
11367 @section OpenMP Modules @code{OMP_LIB} and @code{OMP_LIB_KINDS}
11369 @item @emph{Standard}:
11370 OpenMP Application Program Interface v3.0
11374 The OpenMP Fortran runtime library routines are provided both in
11375 a form of two Fortran 90 modules, named @code{OMP_LIB} and
11376 @code{OMP_LIB_KINDS}, and in a form of a Fortran @code{include} file named
11377 @file{omp_lib.h}. The procedures provided by @code{OMP_LIB} can be found
11378 in the @ref{Top,,Introduction,libgomp,GNU OpenMP runtime library} manual,
11379 the named constants defined in the @code{OMP_LIB_KINDS} module are listed
11382 For details refer to the actual
11383 @uref{http://www.openmp.org/mp-documents/spec30.pdf,
11384 OpenMP Application Program Interface v3.0}.
11386 @code{OMP_LIB_KINDS} provides the following scalar default-integer
11390 @item @code{omp_integer_kind}
11391 @item @code{omp_logical_kind}
11392 @item @code{omp_lock_kind}
11393 @item @code{omp_nest_lock_kind}
11394 @item @code{omp_sched_kind}