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 Counts the number of @code{.TRUE.} elements in a logical @var{MASK},
2742 or, if the @var{DIM} argument is supplied, counts the number of
2743 elements along each row of the array in the @var{DIM} direction.
2744 If the array has zero size, or all of the elements of @var{MASK} are
2745 @code{.FALSE.}, then the result is @code{0}.
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 If @var{DIM} is present, the result is an array with a rank one less
2768 than the rank of @var{ARRAY}, and a size corresponding to the shape
2769 of @var{ARRAY} with the @var{DIM} dimension removed.
2771 @item @emph{Example}:
2774 integer, dimension(2,3) :: a, b
2775 logical, dimension(2,3) :: mask
2776 a = reshape( (/ 1, 2, 3, 4, 5, 6 /), (/ 2, 3 /))
2777 b = reshape( (/ 0, 7, 3, 4, 5, 8 /), (/ 2, 3 /))
2778 print '(3i3)', a(1,:)
2779 print '(3i3)', a(2,:)
2781 print '(3i3)', b(1,:)
2782 print '(3i3)', b(2,:)
2785 print '(3l3)', mask(1,:)
2786 print '(3l3)', mask(2,:)
2788 print '(3i3)', count(mask)
2790 print '(3i3)', count(mask, 1)
2792 print '(3i3)', count(mask, 2)
2793 end program test_count
2800 @section @code{CPU_TIME} --- CPU elapsed time in seconds
2802 @cindex time, elapsed
2805 @item @emph{Description}:
2806 Returns a @code{REAL} value representing the elapsed CPU time in
2807 seconds. This is useful for testing segments of code to determine
2810 If a time source is available, time will be reported with microsecond
2811 resolution. If no time source is available, @var{TIME} is set to
2814 Note that @var{TIME} may contain a, system dependent, arbitrary offset
2815 and may not start with @code{0.0}. For @code{CPU_TIME}, the absolute
2816 value is meaningless, only differences between subsequent calls to
2817 this subroutine, as shown in the example below, should be used.
2820 @item @emph{Standard}:
2821 Fortran 95 and later
2826 @item @emph{Syntax}:
2827 @code{CALL CPU_TIME(TIME)}
2829 @item @emph{Arguments}:
2830 @multitable @columnfractions .15 .70
2831 @item @var{TIME} @tab The type shall be @code{REAL} with @code{INTENT(OUT)}.
2834 @item @emph{Return value}:
2837 @item @emph{Example}:
2839 program test_cpu_time
2840 real :: start, finish
2841 call cpu_time(start)
2842 ! put code to test here
2843 call cpu_time(finish)
2844 print '("Time = ",f6.3," seconds.")',finish-start
2845 end program test_cpu_time
2848 @item @emph{See also}:
2849 @ref{SYSTEM_CLOCK}, @ref{DATE_AND_TIME}
2855 @section @code{CSHIFT} --- Circular shift elements of an array
2857 @cindex array, shift circularly
2858 @cindex array, permutation
2859 @cindex array, rotate
2862 @item @emph{Description}:
2863 @code{CSHIFT(ARRAY, SHIFT [, DIM])} performs a circular shift on elements of
2864 @var{ARRAY} along the dimension of @var{DIM}. If @var{DIM} is omitted it is
2865 taken to be @code{1}. @var{DIM} is a scalar of type @code{INTEGER} in the
2866 range of @math{1 \leq DIM \leq n)} where @math{n} is the rank of @var{ARRAY}.
2867 If the rank of @var{ARRAY} is one, then all elements of @var{ARRAY} are shifted
2868 by @var{SHIFT} places. If rank is greater than one, then all complete rank one
2869 sections of @var{ARRAY} along the given dimension are shifted. Elements
2870 shifted out one end of each rank one section are shifted back in the other end.
2872 @item @emph{Standard}:
2873 Fortran 95 and later
2876 Transformational function
2878 @item @emph{Syntax}:
2879 @code{RESULT = CSHIFT(ARRAY, SHIFT [, DIM])}
2881 @item @emph{Arguments}:
2882 @multitable @columnfractions .15 .70
2883 @item @var{ARRAY} @tab Shall be an array of any type.
2884 @item @var{SHIFT} @tab The type shall be @code{INTEGER}.
2885 @item @var{DIM} @tab The type shall be @code{INTEGER}.
2888 @item @emph{Return value}:
2889 Returns an array of same type and rank as the @var{ARRAY} argument.
2891 @item @emph{Example}:
2894 integer, dimension(3,3) :: a
2895 a = reshape( (/ 1, 2, 3, 4, 5, 6, 7, 8, 9 /), (/ 3, 3 /))
2896 print '(3i3)', a(1,:)
2897 print '(3i3)', a(2,:)
2898 print '(3i3)', a(3,:)
2899 a = cshift(a, SHIFT=(/1, 2, -1/), DIM=2)
2901 print '(3i3)', a(1,:)
2902 print '(3i3)', a(2,:)
2903 print '(3i3)', a(3,:)
2904 end program test_cshift
2911 @section @code{CTIME} --- Convert a time into a string
2913 @cindex time, conversion to string
2914 @cindex conversion, to string
2917 @item @emph{Description}:
2918 @code{CTIME} converts a system time value, such as returned by
2919 @code{TIME8()}, to a string of the form @samp{Sat Aug 19 18:13:14 1995}.
2921 This intrinsic is provided in both subroutine and function forms; however,
2922 only one form can be used in any given program unit.
2924 @item @emph{Standard}:
2928 Subroutine, function
2930 @item @emph{Syntax}:
2931 @multitable @columnfractions .80
2932 @item @code{CALL CTIME(TIME, RESULT)}.
2933 @item @code{RESULT = CTIME(TIME)}, (not recommended).
2936 @item @emph{Arguments}:
2937 @multitable @columnfractions .15 .70
2938 @item @var{TIME} @tab The type shall be of type @code{INTEGER(KIND=8)}.
2939 @item @var{RESULT} @tab The type shall be of type @code{CHARACTER} and
2943 @item @emph{Return value}:
2944 The converted date and time as a string.
2946 @item @emph{Example}:
2950 character(len=30) :: date
2953 ! Do something, main part of the program
2956 print *, 'Program was started on ', date
2957 end program test_ctime
2960 @item @emph{See Also}:
2961 @ref{GMTIME}, @ref{LTIME}, @ref{TIME}, @ref{TIME8}
2967 @section @code{DATE_AND_TIME} --- Date and time subroutine
2968 @fnindex DATE_AND_TIME
2969 @cindex date, current
2970 @cindex current date
2971 @cindex time, current
2972 @cindex current time
2975 @item @emph{Description}:
2976 @code{DATE_AND_TIME(DATE, TIME, ZONE, VALUES)} gets the corresponding date and
2977 time information from the real-time system clock. @var{DATE} is
2978 @code{INTENT(OUT)} and has form ccyymmdd. @var{TIME} is @code{INTENT(OUT)} and
2979 has form hhmmss.sss. @var{ZONE} is @code{INTENT(OUT)} and has form (+-)hhmm,
2980 representing the difference with respect to Coordinated Universal Time (UTC).
2981 Unavailable time and date parameters return blanks.
2983 @var{VALUES} is @code{INTENT(OUT)} and provides the following:
2985 @multitable @columnfractions .15 .30 .40
2986 @item @tab @code{VALUE(1)}: @tab The year
2987 @item @tab @code{VALUE(2)}: @tab The month
2988 @item @tab @code{VALUE(3)}: @tab The day of the month
2989 @item @tab @code{VALUE(4)}: @tab Time difference with UTC in minutes
2990 @item @tab @code{VALUE(5)}: @tab The hour of the day
2991 @item @tab @code{VALUE(6)}: @tab The minutes of the hour
2992 @item @tab @code{VALUE(7)}: @tab The seconds of the minute
2993 @item @tab @code{VALUE(8)}: @tab The milliseconds of the second
2996 @item @emph{Standard}:
2997 Fortran 95 and later
3002 @item @emph{Syntax}:
3003 @code{CALL DATE_AND_TIME([DATE, TIME, ZONE, VALUES])}
3005 @item @emph{Arguments}:
3006 @multitable @columnfractions .15 .70
3007 @item @var{DATE} @tab (Optional) The type shall be @code{CHARACTER(LEN=8)}
3008 or larger, and of default kind.
3009 @item @var{TIME} @tab (Optional) The type shall be @code{CHARACTER(LEN=10)}
3010 or larger, and of default kind.
3011 @item @var{ZONE} @tab (Optional) The type shall be @code{CHARACTER(LEN=5)}
3012 or larger, and of default kind.
3013 @item @var{VALUES}@tab (Optional) The type shall be @code{INTEGER(8)}.
3016 @item @emph{Return value}:
3019 @item @emph{Example}:
3021 program test_time_and_date
3022 character(8) :: date
3023 character(10) :: time
3024 character(5) :: zone
3025 integer,dimension(8) :: values
3026 ! using keyword arguments
3027 call date_and_time(date,time,zone,values)
3028 call date_and_time(DATE=date,ZONE=zone)
3029 call date_and_time(TIME=time)
3030 call date_and_time(VALUES=values)
3031 print '(a,2x,a,2x,a)', date, time, zone
3032 print '(8i5))', values
3033 end program test_time_and_date
3036 @item @emph{See also}:
3037 @ref{CPU_TIME}, @ref{SYSTEM_CLOCK}
3043 @section @code{DBLE} --- Double conversion function
3045 @cindex conversion, to real
3048 @item @emph{Description}:
3049 @code{DBLE(A)} Converts @var{A} to double precision real type.
3051 @item @emph{Standard}:
3052 Fortran 77 and later
3057 @item @emph{Syntax}:
3058 @code{RESULT = DBLE(A)}
3060 @item @emph{Arguments}:
3061 @multitable @columnfractions .15 .70
3062 @item @var{A} @tab The type shall be @code{INTEGER}, @code{REAL},
3066 @item @emph{Return value}:
3067 The return value is of type double precision real.
3069 @item @emph{Example}:
3074 complex :: z = (2.3,1.14)
3075 print *, dble(x), dble(i), dble(z)
3076 end program test_dble
3079 @item @emph{See also}:
3080 @ref{DFLOAT}, @ref{FLOAT}, @ref{REAL}
3086 @section @code{DCMPLX} --- Double complex conversion function
3088 @cindex complex numbers, conversion to
3089 @cindex conversion, to complex
3092 @item @emph{Description}:
3093 @code{DCMPLX(X [,Y])} returns a double complex number where @var{X} is
3094 converted to the real component. If @var{Y} is present it is converted to the
3095 imaginary component. If @var{Y} is not present then the imaginary component is
3096 set to 0.0. If @var{X} is complex then @var{Y} must not be present.
3098 @item @emph{Standard}:
3104 @item @emph{Syntax}:
3105 @code{RESULT = DCMPLX(X [, Y])}
3107 @item @emph{Arguments}:
3108 @multitable @columnfractions .15 .70
3109 @item @var{X} @tab The type may be @code{INTEGER}, @code{REAL},
3111 @item @var{Y} @tab (Optional if @var{X} is not @code{COMPLEX}.) May be
3112 @code{INTEGER} or @code{REAL}.
3115 @item @emph{Return value}:
3116 The return value is of type @code{COMPLEX(8)}
3118 @item @emph{Example}:
3128 print *, dcmplx(x,i)
3129 end program test_dcmplx
3136 @section @code{DFLOAT} --- Double conversion function
3138 @cindex conversion, to real
3141 @item @emph{Description}:
3142 @code{DFLOAT(A)} Converts @var{A} to double precision real type.
3144 @item @emph{Standard}:
3150 @item @emph{Syntax}:
3151 @code{RESULT = DFLOAT(A)}
3153 @item @emph{Arguments}:
3154 @multitable @columnfractions .15 .70
3155 @item @var{A} @tab The type shall be @code{INTEGER}.
3158 @item @emph{Return value}:
3159 The return value is of type double precision real.
3161 @item @emph{Example}:
3166 end program test_dfloat
3169 @item @emph{See also}:
3170 @ref{DBLE}, @ref{FLOAT}, @ref{REAL}
3176 @section @code{DIGITS} --- Significant binary digits function
3178 @cindex model representation, significant digits
3181 @item @emph{Description}:
3182 @code{DIGITS(X)} returns the number of significant binary digits of the internal
3183 model representation of @var{X}. For example, on a system using a 32-bit
3184 floating point representation, a default real number would likely return 24.
3186 @item @emph{Standard}:
3187 Fortran 95 and later
3192 @item @emph{Syntax}:
3193 @code{RESULT = DIGITS(X)}
3195 @item @emph{Arguments}:
3196 @multitable @columnfractions .15 .70
3197 @item @var{X} @tab The type may be @code{INTEGER} or @code{REAL}.
3200 @item @emph{Return value}:
3201 The return value is of type @code{INTEGER}.
3203 @item @emph{Example}:
3206 integer :: i = 12345
3212 end program test_digits
3219 @section @code{DIM} --- Positive difference
3223 @cindex positive difference
3226 @item @emph{Description}:
3227 @code{DIM(X,Y)} returns the difference @code{X-Y} if the result is positive;
3228 otherwise returns zero.
3230 @item @emph{Standard}:
3231 Fortran 77 and later
3236 @item @emph{Syntax}:
3237 @code{RESULT = DIM(X, Y)}
3239 @item @emph{Arguments}:
3240 @multitable @columnfractions .15 .70
3241 @item @var{X} @tab The type shall be @code{INTEGER} or @code{REAL}
3242 @item @var{Y} @tab The type shall be the same type and kind as @var{X}.
3245 @item @emph{Return value}:
3246 The return value is of type @code{INTEGER} or @code{REAL}.
3248 @item @emph{Example}:
3254 x = dim(4.345_8, 2.111_8)
3257 end program test_dim
3260 @item @emph{Specific names}:
3261 @multitable @columnfractions .20 .20 .20 .25
3262 @item Name @tab Argument @tab Return type @tab Standard
3263 @item @code{IDIM(X,Y)} @tab @code{INTEGER(4) X,Y} @tab @code{INTEGER(4)} @tab Fortran 77 and later
3264 @item @code{DDIM(X,Y)} @tab @code{REAL(8) X,Y} @tab @code{REAL(8)} @tab Fortran 77 and later
3271 @section @code{DOT_PRODUCT} --- Dot product function
3272 @fnindex DOT_PRODUCT
3274 @cindex vector product
3275 @cindex product, vector
3278 @item @emph{Description}:
3279 @code{DOT_PRODUCT(VECTOR_A, VECTOR_B)} computes the dot product multiplication
3280 of two vectors @var{VECTOR_A} and @var{VECTOR_B}. The two vectors may be
3281 either numeric or logical and must be arrays of rank one and of equal size. If
3282 the vectors are @code{INTEGER} or @code{REAL}, the result is
3283 @code{SUM(VECTOR_A*VECTOR_B)}. If the vectors are @code{COMPLEX}, the result
3284 is @code{SUM(CONJG(VECTOR_A)*VECTOR_B)}. If the vectors are @code{LOGICAL},
3285 the result is @code{ANY(VECTOR_A .AND. VECTOR_B)}.
3287 @item @emph{Standard}:
3288 Fortran 95 and later
3291 Transformational function
3293 @item @emph{Syntax}:
3294 @code{RESULT = DOT_PRODUCT(VECTOR_A, VECTOR_B)}
3296 @item @emph{Arguments}:
3297 @multitable @columnfractions .15 .70
3298 @item @var{VECTOR_A} @tab The type shall be numeric or @code{LOGICAL}, rank 1.
3299 @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.
3302 @item @emph{Return value}:
3303 If the arguments are numeric, the return value is a scalar of numeric type,
3304 @code{INTEGER}, @code{REAL}, or @code{COMPLEX}. If the arguments are
3305 @code{LOGICAL}, the return value is @code{.TRUE.} or @code{.FALSE.}.
3307 @item @emph{Example}:
3309 program test_dot_prod
3310 integer, dimension(3) :: a, b
3317 print *, dot_product(a,b)
3318 end program test_dot_prod
3325 @section @code{DPROD} --- Double product function
3327 @cindex product, double-precision
3330 @item @emph{Description}:
3331 @code{DPROD(X,Y)} returns the product @code{X*Y}.
3333 @item @emph{Standard}:
3334 Fortran 77 and later
3339 @item @emph{Syntax}:
3340 @code{RESULT = DPROD(X, Y)}
3342 @item @emph{Arguments}:
3343 @multitable @columnfractions .15 .70
3344 @item @var{X} @tab The type shall be @code{REAL}.
3345 @item @var{Y} @tab The type shall be @code{REAL}.
3348 @item @emph{Return value}:
3349 The return value is of type @code{REAL(8)}.
3351 @item @emph{Example}:
3359 end program test_dprod
3366 @section @code{DREAL} --- Double real part function
3368 @cindex complex numbers, real part
3371 @item @emph{Description}:
3372 @code{DREAL(Z)} returns the real part of complex variable @var{Z}.
3374 @item @emph{Standard}:
3380 @item @emph{Syntax}:
3381 @code{RESULT = DREAL(A)}
3383 @item @emph{Arguments}:
3384 @multitable @columnfractions .15 .70
3385 @item @var{A} @tab The type shall be @code{COMPLEX(8)}.
3388 @item @emph{Return value}:
3389 The return value is of type @code{REAL(8)}.
3391 @item @emph{Example}:
3394 complex(8) :: z = (1.3_8,7.2_8)
3396 end program test_dreal
3399 @item @emph{See also}:
3407 @section @code{DTIME} --- Execution time subroutine (or function)
3409 @cindex time, elapsed
3410 @cindex elapsed time
3413 @item @emph{Description}:
3414 @code{DTIME(VALUES, TIME)} initially returns the number of seconds of runtime
3415 since the start of the process's execution in @var{TIME}. @var{VALUES}
3416 returns the user and system components of this time in @code{VALUES(1)} and
3417 @code{VALUES(2)} respectively. @var{TIME} is equal to @code{VALUES(1) +
3420 Subsequent invocations of @code{DTIME} return values accumulated since the
3421 previous invocation.
3423 On some systems, the underlying timings are represented using types with
3424 sufficiently small limits that overflows (wrap around) are possible, such as
3425 32-bit types. Therefore, the values returned by this intrinsic might be, or
3426 become, negative, or numerically less than previous values, during a single
3427 run of the compiled program.
3429 Please note, that this implementation is thread safe if used within OpenMP
3430 directives, i.e., its state will be consistent while called from multiple
3431 threads. However, if @code{DTIME} is called from multiple threads, the result
3432 is still the time since the last invocation. This may not give the intended
3433 results. If possible, use @code{CPU_TIME} instead.
3435 This intrinsic is provided in both subroutine and function forms; however,
3436 only one form can be used in any given program unit.
3438 @var{VALUES} and @var{TIME} are @code{INTENT(OUT)} and provide the following:
3440 @multitable @columnfractions .15 .30 .40
3441 @item @tab @code{VALUES(1)}: @tab User time in seconds.
3442 @item @tab @code{VALUES(2)}: @tab System time in seconds.
3443 @item @tab @code{TIME}: @tab Run time since start in seconds.
3446 @item @emph{Standard}:
3450 Subroutine, function
3452 @item @emph{Syntax}:
3453 @multitable @columnfractions .80
3454 @item @code{CALL DTIME(VALUES, TIME)}.
3455 @item @code{TIME = DTIME(VALUES)}, (not recommended).
3458 @item @emph{Arguments}:
3459 @multitable @columnfractions .15 .70
3460 @item @var{VALUES}@tab The type shall be @code{REAL(4), DIMENSION(2)}.
3461 @item @var{TIME}@tab The type shall be @code{REAL(4)}.
3464 @item @emph{Return value}:
3465 Elapsed time in seconds since the last invocation or since the start of program
3466 execution if not called before.
3468 @item @emph{Example}:
3472 real, dimension(2) :: tarray
3474 call dtime(tarray, result)
3478 do i=1,100000000 ! Just a delay
3481 call dtime(tarray, result)
3485 end program test_dtime
3488 @item @emph{See also}:
3496 @section @code{EOSHIFT} --- End-off shift elements of an array
3498 @cindex array, shift
3501 @item @emph{Description}:
3502 @code{EOSHIFT(ARRAY, SHIFT[, BOUNDARY, DIM])} performs an end-off shift on
3503 elements of @var{ARRAY} along the dimension of @var{DIM}. If @var{DIM} is
3504 omitted it is taken to be @code{1}. @var{DIM} is a scalar of type
3505 @code{INTEGER} in the range of @math{1 \leq DIM \leq n)} where @math{n} is the
3506 rank of @var{ARRAY}. If the rank of @var{ARRAY} is one, then all elements of
3507 @var{ARRAY} are shifted by @var{SHIFT} places. If rank is greater than one,
3508 then all complete rank one sections of @var{ARRAY} along the given dimension are
3509 shifted. Elements shifted out one end of each rank one section are dropped. If
3510 @var{BOUNDARY} is present then the corresponding value of from @var{BOUNDARY}
3511 is copied back in the other end. If @var{BOUNDARY} is not present then the
3512 following are copied in depending on the type of @var{ARRAY}.
3514 @multitable @columnfractions .15 .80
3515 @item @emph{Array Type} @tab @emph{Boundary Value}
3516 @item Numeric @tab 0 of the type and kind of @var{ARRAY}.
3517 @item Logical @tab @code{.FALSE.}.
3518 @item Character(@var{len}) @tab @var{len} blanks.
3521 @item @emph{Standard}:
3522 Fortran 95 and later
3525 Transformational function
3527 @item @emph{Syntax}:
3528 @code{RESULT = EOSHIFT(ARRAY, SHIFT [, BOUNDARY, DIM])}
3530 @item @emph{Arguments}:
3531 @multitable @columnfractions .15 .70
3532 @item @var{ARRAY} @tab May be any type, not scalar.
3533 @item @var{SHIFT} @tab The type shall be @code{INTEGER}.
3534 @item @var{BOUNDARY} @tab Same type as @var{ARRAY}.
3535 @item @var{DIM} @tab The type shall be @code{INTEGER}.
3538 @item @emph{Return value}:
3539 Returns an array of same type and rank as the @var{ARRAY} argument.
3541 @item @emph{Example}:
3543 program test_eoshift
3544 integer, dimension(3,3) :: a
3545 a = reshape( (/ 1, 2, 3, 4, 5, 6, 7, 8, 9 /), (/ 3, 3 /))
3546 print '(3i3)', a(1,:)
3547 print '(3i3)', a(2,:)
3548 print '(3i3)', a(3,:)
3549 a = EOSHIFT(a, SHIFT=(/1, 2, 1/), BOUNDARY=-5, DIM=2)
3551 print '(3i3)', a(1,:)
3552 print '(3i3)', a(2,:)
3553 print '(3i3)', a(3,:)
3554 end program test_eoshift
3561 @section @code{EPSILON} --- Epsilon function
3563 @cindex model representation, epsilon
3566 @item @emph{Description}:
3567 @code{EPSILON(X)} returns the smallest number @var{E} of the same kind
3568 as @var{X} such that @math{1 + E > 1}.
3570 @item @emph{Standard}:
3571 Fortran 95 and later
3576 @item @emph{Syntax}:
3577 @code{RESULT = EPSILON(X)}
3579 @item @emph{Arguments}:
3580 @multitable @columnfractions .15 .70
3581 @item @var{X} @tab The type shall be @code{REAL}.
3584 @item @emph{Return value}:
3585 The return value is of same type as the argument.
3587 @item @emph{Example}:
3589 program test_epsilon
3594 end program test_epsilon
3601 @section @code{ERF} --- Error function
3603 @cindex error function
3606 @item @emph{Description}:
3607 @code{ERF(X)} computes the error function of @var{X}.
3609 @item @emph{Standard}:
3610 Fortran 2008 and later
3615 @item @emph{Syntax}:
3616 @code{RESULT = ERF(X)}
3618 @item @emph{Arguments}:
3619 @multitable @columnfractions .15 .70
3620 @item @var{X} @tab The type shall be @code{REAL}.
3623 @item @emph{Return value}:
3624 The return value is of type @code{REAL}, of the same kind as
3625 @var{X} and lies in the range @math{-1 \leq erf (x) \leq 1 }.
3627 @item @emph{Example}:
3630 real(8) :: x = 0.17_8
3632 end program test_erf
3635 @item @emph{Specific names}:
3636 @multitable @columnfractions .20 .20 .20 .25
3637 @item Name @tab Argument @tab Return type @tab Standard
3638 @item @code{DERF(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU extension
3645 @section @code{ERFC} --- Error function
3647 @cindex error function, complementary
3650 @item @emph{Description}:
3651 @code{ERFC(X)} computes the complementary error function of @var{X}.
3653 @item @emph{Standard}:
3654 Fortran 2008 and later
3659 @item @emph{Syntax}:
3660 @code{RESULT = ERFC(X)}
3662 @item @emph{Arguments}:
3663 @multitable @columnfractions .15 .70
3664 @item @var{X} @tab The type shall be @code{REAL}.
3667 @item @emph{Return value}:
3668 The return value is of type @code{REAL} and of the same kind as @var{X}.
3669 It lies in the range @math{ 0 \leq erfc (x) \leq 2 }.
3671 @item @emph{Example}:
3674 real(8) :: x = 0.17_8
3676 end program test_erfc
3679 @item @emph{Specific names}:
3680 @multitable @columnfractions .20 .20 .20 .25
3681 @item Name @tab Argument @tab Return type @tab Standard
3682 @item @code{DERFC(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU extension
3689 @section @code{ERFC_SCALED} --- Error function
3690 @fnindex ERFC_SCALED
3691 @cindex error function, complementary, exponentially-scaled
3694 @item @emph{Description}:
3695 @code{ERFC_SCALED(X)} computes the exponentially-scaled complementary
3696 error function of @var{X}.
3698 @item @emph{Standard}:
3699 Fortran 2008 and later
3704 @item @emph{Syntax}:
3705 @code{RESULT = ERFC_SCALED(X)}
3707 @item @emph{Arguments}:
3708 @multitable @columnfractions .15 .70
3709 @item @var{X} @tab The type shall be @code{REAL}.
3712 @item @emph{Return value}:
3713 The return value is of type @code{REAL} and of the same kind as @var{X}.
3715 @item @emph{Example}:
3717 program test_erfc_scaled
3718 real(8) :: x = 0.17_8
3720 end program test_erfc_scaled
3727 @section @code{ETIME} --- Execution time subroutine (or function)
3729 @cindex time, elapsed
3732 @item @emph{Description}:
3733 @code{ETIME(VALUES, TIME)} returns the number of seconds of runtime
3734 since the start of the process's execution in @var{TIME}. @var{VALUES}
3735 returns the user and system components of this time in @code{VALUES(1)} and
3736 @code{VALUES(2)} respectively. @var{TIME} is equal to @code{VALUES(1) + VALUES(2)}.
3738 On some systems, the underlying timings are represented using types with
3739 sufficiently small limits that overflows (wrap around) are possible, such as
3740 32-bit types. Therefore, the values returned by this intrinsic might be, or
3741 become, negative, or numerically less than previous values, during a single
3742 run of the compiled program.
3744 This intrinsic is provided in both subroutine and function forms; however,
3745 only one form can be used in any given program unit.
3747 @var{VALUES} and @var{TIME} are @code{INTENT(OUT)} and provide the following:
3749 @multitable @columnfractions .15 .30 .60
3750 @item @tab @code{VALUES(1)}: @tab User time in seconds.
3751 @item @tab @code{VALUES(2)}: @tab System time in seconds.
3752 @item @tab @code{TIME}: @tab Run time since start in seconds.
3755 @item @emph{Standard}:
3759 Subroutine, function
3761 @item @emph{Syntax}:
3762 @multitable @columnfractions .80
3763 @item @code{CALL ETIME(VALUES, TIME)}.
3764 @item @code{TIME = ETIME(VALUES)}, (not recommended).
3767 @item @emph{Arguments}:
3768 @multitable @columnfractions .15 .70
3769 @item @var{VALUES}@tab The type shall be @code{REAL(4), DIMENSION(2)}.
3770 @item @var{TIME}@tab The type shall be @code{REAL(4)}.
3773 @item @emph{Return value}:
3774 Elapsed time in seconds since the start of program execution.
3776 @item @emph{Example}:
3780 real, dimension(2) :: tarray
3782 call ETIME(tarray, result)
3786 do i=1,100000000 ! Just a delay
3789 call ETIME(tarray, result)
3793 end program test_etime
3796 @item @emph{See also}:
3804 @section @code{EXIT} --- Exit the program with status.
3806 @cindex program termination
3807 @cindex terminate program
3810 @item @emph{Description}:
3811 @code{EXIT} causes immediate termination of the program with status. If status
3812 is omitted it returns the canonical @emph{success} for the system. All Fortran
3813 I/O units are closed.
3815 @item @emph{Standard}:
3821 @item @emph{Syntax}:
3822 @code{CALL EXIT([STATUS])}
3824 @item @emph{Arguments}:
3825 @multitable @columnfractions .15 .70
3826 @item @var{STATUS} @tab Shall be an @code{INTEGER} of the default kind.
3829 @item @emph{Return value}:
3830 @code{STATUS} is passed to the parent process on exit.
3832 @item @emph{Example}:
3835 integer :: STATUS = 0
3836 print *, 'This program is going to exit.'
3838 end program test_exit
3841 @item @emph{See also}:
3842 @ref{ABORT}, @ref{KILL}
3848 @section @code{EXP} --- Exponential function
3854 @cindex exponential function
3855 @cindex logarithmic function, inverse
3858 @item @emph{Description}:
3859 @code{EXP(X)} computes the base @math{e} exponential of @var{X}.
3861 @item @emph{Standard}:
3862 Fortran 77 and later, has overloads that are GNU extensions
3867 @item @emph{Syntax}:
3868 @code{RESULT = EXP(X)}
3870 @item @emph{Arguments}:
3871 @multitable @columnfractions .15 .70
3872 @item @var{X} @tab The type shall be @code{REAL} or
3876 @item @emph{Return value}:
3877 The return value has same type and kind as @var{X}.
3879 @item @emph{Example}:
3884 end program test_exp
3887 @item @emph{Specific names}:
3888 @multitable @columnfractions .20 .20 .20 .25
3889 @item Name @tab Argument @tab Return type @tab Standard
3890 @item @code{DEXP(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab Fortran 77 and later
3891 @item @code{CEXP(X)} @tab @code{COMPLEX(4) X} @tab @code{COMPLEX(4)} @tab Fortran 77 and later
3892 @item @code{ZEXP(X)} @tab @code{COMPLEX(8) X} @tab @code{COMPLEX(8)} @tab GNU extension
3893 @item @code{CDEXP(X)} @tab @code{COMPLEX(8) X} @tab @code{COMPLEX(8)} @tab GNU extension
3900 @section @code{EXPONENT} --- Exponent function
3902 @cindex real number, exponent
3903 @cindex floating point, exponent
3906 @item @emph{Description}:
3907 @code{EXPONENT(X)} returns the value of the exponent part of @var{X}. If @var{X}
3908 is zero the value returned is zero.
3910 @item @emph{Standard}:
3911 Fortran 95 and later
3916 @item @emph{Syntax}:
3917 @code{RESULT = EXPONENT(X)}
3919 @item @emph{Arguments}:
3920 @multitable @columnfractions .15 .70
3921 @item @var{X} @tab The type shall be @code{REAL}.
3924 @item @emph{Return value}:
3925 The return value is of type default @code{INTEGER}.
3927 @item @emph{Example}:
3929 program test_exponent
3934 print *, exponent(0.0)
3935 end program test_exponent
3942 @section @code{FDATE} --- Get the current time as a string
3944 @cindex time, current
3945 @cindex current time
3946 @cindex date, current
3947 @cindex current date
3950 @item @emph{Description}:
3951 @code{FDATE(DATE)} returns the current date (using the same format as
3952 @code{CTIME}) in @var{DATE}. It is equivalent to @code{CALL CTIME(DATE,
3955 This intrinsic is provided in both subroutine and function forms; however,
3956 only one form can be used in any given program unit.
3958 @var{DATE} is an @code{INTENT(OUT)} @code{CHARACTER} variable of the
3961 @item @emph{Standard}:
3965 Subroutine, function
3967 @item @emph{Syntax}:
3968 @multitable @columnfractions .80
3969 @item @code{CALL FDATE(DATE)}.
3970 @item @code{DATE = FDATE()}, (not recommended).
3973 @item @emph{Arguments}:
3974 @multitable @columnfractions .15 .70
3975 @item @var{DATE}@tab The type shall be of type @code{CHARACTER} of the
3979 @item @emph{Return value}:
3980 The current date as a string.
3982 @item @emph{Example}:
3986 character(len=30) :: date
3988 print *, 'Program started on ', date
3989 do i = 1, 100000000 ! Just a delay
3993 print *, 'Program ended on ', date
3994 end program test_fdate
4001 @section @code{FLOAT} --- Convert integer to default real
4003 @cindex conversion, to real
4006 @item @emph{Description}:
4007 @code{FLOAT(A)} converts the integer @var{A} to a default real value.
4009 @item @emph{Standard}:
4010 Fortran 77 and later
4015 @item @emph{Syntax}:
4016 @code{RESULT = FLOAT(A)}
4018 @item @emph{Arguments}:
4019 @multitable @columnfractions .15 .70
4020 @item @var{A} @tab The type shall be @code{INTEGER}.
4023 @item @emph{Return value}:
4024 The return value is of type default @code{REAL}.
4026 @item @emph{Example}:
4030 if (float(i) /= 1.) call abort
4031 end program test_float
4034 @item @emph{See also}:
4035 @ref{DBLE}, @ref{DFLOAT}, @ref{REAL}
4041 @section @code{FGET} --- Read a single character in stream mode from stdin
4043 @cindex read character, stream mode
4044 @cindex stream mode, read character
4045 @cindex file operation, read character
4048 @item @emph{Description}:
4049 Read a single character in stream mode from stdin by bypassing normal
4050 formatted output. Stream I/O should not be mixed with normal record-oriented
4051 (formatted or unformatted) I/O on the same unit; the results are unpredictable.
4053 This intrinsic is provided in both subroutine and function forms; however,
4054 only one form can be used in any given program unit.
4056 Note that the @code{FGET} intrinsic is provided for backwards compatibility with
4057 @command{g77}. GNU Fortran provides the Fortran 2003 Stream facility.
4058 Programmers should consider the use of new stream IO feature in new code
4059 for future portability. See also @ref{Fortran 2003 status}.
4061 @item @emph{Standard}:
4065 Subroutine, function
4067 @item @emph{Syntax}:
4068 @code{CALL FGET(C [, STATUS])}
4070 @item @emph{Arguments}:
4071 @multitable @columnfractions .15 .70
4072 @item @var{C} @tab The type shall be @code{CHARACTER} and of default
4074 @item @var{STATUS} @tab (Optional) status flag of type @code{INTEGER}.
4075 Returns 0 on success, -1 on end-of-file, and a system specific positive
4076 error code otherwise.
4079 @item @emph{Example}:
4082 INTEGER, PARAMETER :: strlen = 100
4083 INTEGER :: status, i = 1
4084 CHARACTER(len=strlen) :: str = ""
4086 WRITE (*,*) 'Enter text:'
4088 CALL fget(str(i:i), status)
4089 if (status /= 0 .OR. i > strlen) exit
4092 WRITE (*,*) TRIM(str)
4096 @item @emph{See also}:
4097 @ref{FGETC}, @ref{FPUT}, @ref{FPUTC}
4103 @section @code{FGETC} --- Read a single character in stream mode
4105 @cindex read character, stream mode
4106 @cindex stream mode, read character
4107 @cindex file operation, read character
4110 @item @emph{Description}:
4111 Read a single character in stream mode by bypassing normal formatted output.
4112 Stream I/O should not be mixed with normal record-oriented (formatted or
4113 unformatted) I/O on the same unit; the results are unpredictable.
4115 This intrinsic is provided in both subroutine and function forms; however,
4116 only one form can be used in any given program unit.
4118 Note that the @code{FGET} intrinsic is provided for backwards compatibility
4119 with @command{g77}. GNU Fortran provides the Fortran 2003 Stream facility.
4120 Programmers should consider the use of new stream IO feature in new code
4121 for future portability. See also @ref{Fortran 2003 status}.
4123 @item @emph{Standard}:
4127 Subroutine, function
4129 @item @emph{Syntax}:
4130 @code{CALL FGETC(UNIT, C [, STATUS])}
4132 @item @emph{Arguments}:
4133 @multitable @columnfractions .15 .70
4134 @item @var{UNIT} @tab The type shall be @code{INTEGER}.
4135 @item @var{C} @tab The type shall be @code{CHARACTER} and of default
4137 @item @var{STATUS} @tab (Optional) status flag of type @code{INTEGER}.
4138 Returns 0 on success, -1 on end-of-file and a system specific positive
4139 error code otherwise.
4142 @item @emph{Example}:
4145 INTEGER :: fd = 42, status
4148 OPEN(UNIT=fd, FILE="/etc/passwd", ACTION="READ", STATUS = "OLD")
4150 CALL fgetc(fd, c, status)
4151 IF (status /= 0) EXIT
4158 @item @emph{See also}:
4159 @ref{FGET}, @ref{FPUT}, @ref{FPUTC}
4165 @section @code{FLOOR} --- Integer floor function
4168 @cindex rounding, floor
4171 @item @emph{Description}:
4172 @code{FLOOR(A)} returns the greatest integer less than or equal to @var{X}.
4174 @item @emph{Standard}:
4175 Fortran 95 and later
4180 @item @emph{Syntax}:
4181 @code{RESULT = FLOOR(A [, KIND])}
4183 @item @emph{Arguments}:
4184 @multitable @columnfractions .15 .70
4185 @item @var{A} @tab The type shall be @code{REAL}.
4186 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
4187 expression indicating the kind parameter of the result.
4190 @item @emph{Return value}:
4191 The return value is of type @code{INTEGER(KIND)} if @var{KIND} is present
4192 and of default-kind @code{INTEGER} otherwise.
4194 @item @emph{Example}:
4199 print *, floor(x) ! returns 63
4200 print *, floor(y) ! returns -64
4201 end program test_floor
4204 @item @emph{See also}:
4205 @ref{CEILING}, @ref{NINT}
4212 @section @code{FLUSH} --- Flush I/O unit(s)
4214 @cindex file operation, flush
4217 @item @emph{Description}:
4218 Flushes Fortran unit(s) currently open for output. Without the optional
4219 argument, all units are flushed, otherwise just the unit specified.
4221 @item @emph{Standard}:
4227 @item @emph{Syntax}:
4228 @code{CALL FLUSH(UNIT)}
4230 @item @emph{Arguments}:
4231 @multitable @columnfractions .15 .70
4232 @item @var{UNIT} @tab (Optional) The type shall be @code{INTEGER}.
4236 Beginning with the Fortran 2003 standard, there is a @code{FLUSH}
4237 statement that should be preferred over the @code{FLUSH} intrinsic.
4244 @section @code{FNUM} --- File number function
4246 @cindex file operation, file number
4249 @item @emph{Description}:
4250 @code{FNUM(UNIT)} returns the POSIX file descriptor number corresponding to the
4251 open Fortran I/O unit @code{UNIT}.
4253 @item @emph{Standard}:
4259 @item @emph{Syntax}:
4260 @code{RESULT = FNUM(UNIT)}
4262 @item @emph{Arguments}:
4263 @multitable @columnfractions .15 .70
4264 @item @var{UNIT} @tab The type shall be @code{INTEGER}.
4267 @item @emph{Return value}:
4268 The return value is of type @code{INTEGER}
4270 @item @emph{Example}:
4274 open (unit=10, status = "scratch")
4278 end program test_fnum
4285 @section @code{FPUT} --- Write a single character in stream mode to stdout
4287 @cindex write character, stream mode
4288 @cindex stream mode, write character
4289 @cindex file operation, write character
4292 @item @emph{Description}:
4293 Write a single character in stream mode to stdout by bypassing normal
4294 formatted output. Stream I/O should not be mixed with normal record-oriented
4295 (formatted or unformatted) I/O on the same unit; the results are unpredictable.
4297 This intrinsic is provided in both subroutine and function forms; however,
4298 only one form can be used in any given program unit.
4300 Note that the @code{FGET} intrinsic is provided for backwards compatibility with
4301 @command{g77}. GNU Fortran provides the Fortran 2003 Stream facility.
4302 Programmers should consider the use of new stream IO feature in new code
4303 for future portability. See also @ref{Fortran 2003 status}.
4305 @item @emph{Standard}:
4309 Subroutine, function
4311 @item @emph{Syntax}:
4312 @code{CALL FPUT(C [, STATUS])}
4314 @item @emph{Arguments}:
4315 @multitable @columnfractions .15 .70
4316 @item @var{C} @tab The type shall be @code{CHARACTER} and of default
4318 @item @var{STATUS} @tab (Optional) status flag of type @code{INTEGER}.
4319 Returns 0 on success, -1 on end-of-file and a system specific positive
4320 error code otherwise.
4323 @item @emph{Example}:
4326 CHARACTER(len=10) :: str = "gfortran"
4328 DO i = 1, len_trim(str)
4334 @item @emph{See also}:
4335 @ref{FPUTC}, @ref{FGET}, @ref{FGETC}
4341 @section @code{FPUTC} --- Write a single character in stream mode
4343 @cindex write character, stream mode
4344 @cindex stream mode, write character
4345 @cindex file operation, write character
4348 @item @emph{Description}:
4349 Write a single character in stream mode by bypassing normal formatted
4350 output. Stream I/O should not be mixed with normal record-oriented
4351 (formatted or unformatted) I/O on the same unit; the results are unpredictable.
4353 This intrinsic is provided in both subroutine and function forms; however,
4354 only one form can be used in any given program unit.
4356 Note that the @code{FGET} intrinsic is provided for backwards compatibility with
4357 @command{g77}. GNU Fortran provides the Fortran 2003 Stream facility.
4358 Programmers should consider the use of new stream IO feature in new code
4359 for future portability. See also @ref{Fortran 2003 status}.
4361 @item @emph{Standard}:
4365 Subroutine, function
4367 @item @emph{Syntax}:
4368 @code{CALL FPUTC(UNIT, C [, STATUS])}
4370 @item @emph{Arguments}:
4371 @multitable @columnfractions .15 .70
4372 @item @var{UNIT} @tab The type shall be @code{INTEGER}.
4373 @item @var{C} @tab The type shall be @code{CHARACTER} and of default
4375 @item @var{STATUS} @tab (Optional) status flag of type @code{INTEGER}.
4376 Returns 0 on success, -1 on end-of-file and a system specific positive
4377 error code otherwise.
4380 @item @emph{Example}:
4383 CHARACTER(len=10) :: str = "gfortran"
4384 INTEGER :: fd = 42, i
4386 OPEN(UNIT = fd, FILE = "out", ACTION = "WRITE", STATUS="NEW")
4387 DO i = 1, len_trim(str)
4388 CALL fputc(fd, str(i:i))
4394 @item @emph{See also}:
4395 @ref{FPUT}, @ref{FGET}, @ref{FGETC}
4401 @section @code{FRACTION} --- Fractional part of the model representation
4403 @cindex real number, fraction
4404 @cindex floating point, fraction
4407 @item @emph{Description}:
4408 @code{FRACTION(X)} returns the fractional part of the model
4409 representation of @code{X}.
4411 @item @emph{Standard}:
4412 Fortran 95 and later
4417 @item @emph{Syntax}:
4418 @code{Y = FRACTION(X)}
4420 @item @emph{Arguments}:
4421 @multitable @columnfractions .15 .70
4422 @item @var{X} @tab The type of the argument shall be a @code{REAL}.
4425 @item @emph{Return value}:
4426 The return value is of the same type and kind as the argument.
4427 The fractional part of the model representation of @code{X} is returned;
4428 it is @code{X * RADIX(X)**(-EXPONENT(X))}.
4430 @item @emph{Example}:
4432 program test_fraction
4435 print *, fraction(x), x * radix(x)**(-exponent(x))
4436 end program test_fraction
4444 @section @code{FREE} --- Frees memory
4446 @cindex pointer, cray
4449 @item @emph{Description}:
4450 Frees memory previously allocated by @code{MALLOC()}. The @code{FREE}
4451 intrinsic is an extension intended to be used with Cray pointers, and is
4452 provided in GNU Fortran to allow user to compile legacy code. For
4453 new code using Fortran 95 pointers, the memory de-allocation intrinsic is
4456 @item @emph{Standard}:
4462 @item @emph{Syntax}:
4463 @code{CALL FREE(PTR)}
4465 @item @emph{Arguments}:
4466 @multitable @columnfractions .15 .70
4467 @item @var{PTR} @tab The type shall be @code{INTEGER}. It represents the
4468 location of the memory that should be de-allocated.
4471 @item @emph{Return value}:
4474 @item @emph{Example}:
4475 See @code{MALLOC} for an example.
4477 @item @emph{See also}:
4484 @section @code{FSEEK} --- Low level file positioning subroutine
4486 @cindex file operation, seek
4487 @cindex file operation, position
4490 @item @emph{Description}:
4491 Moves @var{UNIT} to the specified @var{OFFSET}. If @var{WHENCE}
4492 is set to 0, the @var{OFFSET} is taken as an absolute value @code{SEEK_SET},
4493 if set to 1, @var{OFFSET} is taken to be relative to the current position
4494 @code{SEEK_CUR}, and if set to 2 relative to the end of the file @code{SEEK_END}.
4495 On error, @var{STATUS} is set to a nonzero value. If @var{STATUS} the seek
4498 This intrinsic routine is not fully backwards compatible with @command{g77}.
4499 In @command{g77}, the @code{FSEEK} takes a statement label instead of a
4500 @var{STATUS} variable. If FSEEK is used in old code, change
4502 CALL FSEEK(UNIT, OFFSET, WHENCE, *label)
4507 CALL FSEEK(UNIT, OFFSET, WHENCE, status)
4508 IF (status /= 0) GOTO label
4511 Please note that GNU Fortran provides the Fortran 2003 Stream facility.
4512 Programmers should consider the use of new stream IO feature in new code
4513 for future portability. See also @ref{Fortran 2003 status}.
4515 @item @emph{Standard}:
4521 @item @emph{Syntax}:
4522 @code{CALL FSEEK(UNIT, OFFSET, WHENCE[, STATUS])}
4524 @item @emph{Arguments}:
4525 @multitable @columnfractions .15 .70
4526 @item @var{UNIT} @tab Shall be a scalar of type @code{INTEGER}.
4527 @item @var{OFFSET} @tab Shall be a scalar of type @code{INTEGER}.
4528 @item @var{WHENCE} @tab Shall be a scalar of type @code{INTEGER}.
4529 Its value shall be either 0, 1 or 2.
4530 @item @var{STATUS} @tab (Optional) shall be a scalar of type
4534 @item @emph{Example}:
4537 INTEGER, PARAMETER :: SEEK_SET = 0, SEEK_CUR = 1, SEEK_END = 2
4538 INTEGER :: fd, offset, ierr
4544 OPEN(UNIT=fd, FILE="fseek.test")
4545 CALL FSEEK(fd, offset, SEEK_SET, ierr) ! move to OFFSET
4546 print *, FTELL(fd), ierr
4548 CALL FSEEK(fd, 0, SEEK_END, ierr) ! move to end
4549 print *, FTELL(fd), ierr
4551 CALL FSEEK(fd, 0, SEEK_SET, ierr) ! move to beginning
4552 print *, FTELL(fd), ierr
4558 @item @emph{See also}:
4565 @section @code{FSTAT} --- Get file status
4567 @cindex file system, file status
4570 @item @emph{Description}:
4571 @code{FSTAT} is identical to @ref{STAT}, except that information about an
4572 already opened file is obtained.
4574 The elements in @code{VALUES} are the same as described by @ref{STAT}.
4576 This intrinsic is provided in both subroutine and function forms; however,
4577 only one form can be used in any given program unit.
4579 @item @emph{Standard}:
4583 Subroutine, function
4585 @item @emph{Syntax}:
4586 @code{CALL FSTAT(UNIT, VALUES [, STATUS])}
4588 @item @emph{Arguments}:
4589 @multitable @columnfractions .15 .70
4590 @item @var{UNIT} @tab An open I/O unit number of type @code{INTEGER}.
4591 @item @var{VALUES} @tab The type shall be @code{INTEGER(4), DIMENSION(13)}.
4592 @item @var{STATUS} @tab (Optional) status flag of type @code{INTEGER(4)}. Returns 0
4593 on success and a system specific error code otherwise.
4596 @item @emph{Example}:
4597 See @ref{STAT} for an example.
4599 @item @emph{See also}:
4600 To stat a link: @ref{LSTAT}, to stat a file: @ref{STAT}
4606 @section @code{FTELL} --- Current stream position
4608 @cindex file operation, position
4611 @item @emph{Description}:
4612 Retrieves the current position within an open file.
4614 This intrinsic is provided in both subroutine and function forms; however,
4615 only one form can be used in any given program unit.
4617 @item @emph{Standard}:
4621 Subroutine, function
4623 @item @emph{Syntax}:
4624 @multitable @columnfractions .80
4625 @item @code{CALL FTELL(UNIT, OFFSET)}
4626 @item @code{OFFSET = FTELL(UNIT)}
4629 @item @emph{Arguments}:
4630 @multitable @columnfractions .15 .70
4631 @item @var{OFFSET} @tab Shall of type @code{INTEGER}.
4632 @item @var{UNIT} @tab Shall of type @code{INTEGER}.
4635 @item @emph{Return value}:
4636 In either syntax, @var{OFFSET} is set to the current offset of unit
4637 number @var{UNIT}, or to @math{-1} if the unit is not currently open.
4639 @item @emph{Example}:
4643 OPEN(10, FILE="temp.dat")
4649 @item @emph{See also}:
4656 @section @code{GAMMA} --- Gamma function
4659 @cindex Gamma function
4660 @cindex Factorial function
4663 @item @emph{Description}:
4664 @code{GAMMA(X)} computes Gamma (@math{\Gamma}) of @var{X}. For positive,
4665 integer values of @var{X} the Gamma function simplifies to the factorial
4666 function @math{\Gamma(x)=(x-1)!}.
4670 \Gamma(x) = \int_0^\infty t^{x-1}{\rm e}^{-t}\,{\rm d}t
4674 @item @emph{Standard}:
4675 Fortran 2008 and later
4680 @item @emph{Syntax}:
4683 @item @emph{Arguments}:
4684 @multitable @columnfractions .15 .70
4685 @item @var{X} @tab Shall be of type @code{REAL} and neither zero
4686 nor a negative integer.
4689 @item @emph{Return value}:
4690 The return value is of type @code{REAL} of the same kind as @var{X}.
4692 @item @emph{Example}:
4696 x = gamma(x) ! returns 1.0
4697 end program test_gamma
4700 @item @emph{Specific names}:
4701 @multitable @columnfractions .20 .20 .20 .25
4702 @item Name @tab Argument @tab Return type @tab Standard
4703 @item @code{GAMMA(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab GNU Extension
4704 @item @code{DGAMMA(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU Extension
4707 @item @emph{See also}:
4708 Logarithm of the Gamma function: @ref{LOG_GAMMA}
4715 @section @code{GERROR} --- Get last system error message
4717 @cindex system, error handling
4720 @item @emph{Description}:
4721 Returns the system error message corresponding to the last system error.
4722 This resembles the functionality of @code{strerror(3)} in C.
4724 @item @emph{Standard}:
4730 @item @emph{Syntax}:
4731 @code{CALL GERROR(RESULT)}
4733 @item @emph{Arguments}:
4734 @multitable @columnfractions .15 .70
4735 @item @var{RESULT} @tab Shall of type @code{CHARACTER} and of default
4738 @item @emph{Example}:
4741 CHARACTER(len=100) :: msg
4747 @item @emph{See also}:
4748 @ref{IERRNO}, @ref{PERROR}
4754 @section @code{GETARG} --- Get command line arguments
4756 @cindex command-line arguments
4757 @cindex arguments, to program
4760 @item @emph{Description}:
4761 Retrieve the @var{POS}-th argument that was passed on the
4762 command line when the containing program was invoked.
4764 This intrinsic routine is provided for backwards compatibility with
4765 GNU Fortran 77. In new code, programmers should consider the use of
4766 the @ref{GET_COMMAND_ARGUMENT} intrinsic defined by the Fortran 2003
4769 @item @emph{Standard}:
4775 @item @emph{Syntax}:
4776 @code{CALL GETARG(POS, VALUE)}
4778 @item @emph{Arguments}:
4779 @multitable @columnfractions .15 .70
4780 @item @var{POS} @tab Shall be of type @code{INTEGER} and not wider than
4781 the default integer kind; @math{@var{POS} \geq 0}
4782 @item @var{VALUE} @tab Shall be of type @code{CHARACTER} and of default
4784 @item @var{VALUE} @tab Shall be of type @code{CHARACTER}.
4787 @item @emph{Return value}:
4788 After @code{GETARG} returns, the @var{VALUE} argument holds the
4789 @var{POS}th command line argument. If @var{VALUE} can not hold the
4790 argument, it is truncated to fit the length of @var{VALUE}. If there are
4791 less than @var{POS} arguments specified at the command line, @var{VALUE}
4792 will be filled with blanks. If @math{@var{POS} = 0}, @var{VALUE} is set
4793 to the name of the program (on systems that support this feature).
4795 @item @emph{Example}:
4799 CHARACTER(len=32) :: arg
4808 @item @emph{See also}:
4809 GNU Fortran 77 compatibility function: @ref{IARGC}
4811 Fortran 2003 functions and subroutines: @ref{GET_COMMAND},
4812 @ref{GET_COMMAND_ARGUMENT}, @ref{COMMAND_ARGUMENT_COUNT}
4818 @section @code{GET_COMMAND} --- Get the entire command line
4819 @fnindex GET_COMMAND
4820 @cindex command-line arguments
4821 @cindex arguments, to program
4824 @item @emph{Description}:
4825 Retrieve the entire command line that was used to invoke the program.
4827 @item @emph{Standard}:
4828 Fortran 2003 and later
4833 @item @emph{Syntax}:
4834 @code{CALL GET_COMMAND([COMMAND, LENGTH, STATUS])}
4836 @item @emph{Arguments}:
4837 @multitable @columnfractions .15 .70
4838 @item @var{COMMAND} @tab (Optional) shall be of type @code{CHARACTER} and
4840 @item @var{LENGTH} @tab (Optional) Shall be of type @code{INTEGER} and of
4842 @item @var{STATUS} @tab (Optional) Shall be of type @code{INTEGER} and of
4846 @item @emph{Return value}:
4847 If @var{COMMAND} is present, stores the entire command line that was used
4848 to invoke the program in @var{COMMAND}. If @var{LENGTH} is present, it is
4849 assigned the length of the command line. If @var{STATUS} is present, it
4850 is assigned 0 upon success of the command, -1 if @var{COMMAND} is too
4851 short to store the command line, or a positive value in case of an error.
4853 @item @emph{Example}:
4855 PROGRAM test_get_command
4856 CHARACTER(len=255) :: cmd
4857 CALL get_command(cmd)
4858 WRITE (*,*) TRIM(cmd)
4862 @item @emph{See also}:
4863 @ref{GET_COMMAND_ARGUMENT}, @ref{COMMAND_ARGUMENT_COUNT}
4868 @node GET_COMMAND_ARGUMENT
4869 @section @code{GET_COMMAND_ARGUMENT} --- Get command line arguments
4870 @fnindex GET_COMMAND_ARGUMENT
4871 @cindex command-line arguments
4872 @cindex arguments, to program
4875 @item @emph{Description}:
4876 Retrieve the @var{NUMBER}-th argument that was passed on the
4877 command line when the containing program was invoked.
4879 @item @emph{Standard}:
4880 Fortran 2003 and later
4885 @item @emph{Syntax}:
4886 @code{CALL GET_COMMAND_ARGUMENT(NUMBER [, VALUE, LENGTH, STATUS])}
4888 @item @emph{Arguments}:
4889 @multitable @columnfractions .15 .70
4890 @item @var{NUMBER} @tab Shall be a scalar of type @code{INTEGER} and of
4891 default kind, @math{@var{NUMBER} \geq 0}
4892 @item @var{VALUE} @tab Shall be a scalar of type @code{CHARACTER}
4893 and of default kind.
4894 @item @var{LENGTH} @tab (Option) Shall be a scalar of type @code{INTEGER}
4895 and of default kind.
4896 @item @var{STATUS} @tab (Option) Shall be a scalar of type @code{INTEGER}
4897 and of default kind.
4900 @item @emph{Return value}:
4901 After @code{GET_COMMAND_ARGUMENT} returns, the @var{VALUE} argument holds the
4902 @var{NUMBER}-th command line argument. If @var{VALUE} can not hold the argument, it is
4903 truncated to fit the length of @var{VALUE}. If there are less than @var{NUMBER}
4904 arguments specified at the command line, @var{VALUE} will be filled with blanks.
4905 If @math{@var{NUMBER} = 0}, @var{VALUE} is set to the name of the program (on
4906 systems that support this feature). The @var{LENGTH} argument contains the
4907 length of the @var{NUMBER}-th command line argument. If the argument retrieval
4908 fails, @var{STATUS} is a positive number; if @var{VALUE} contains a truncated
4909 command line argument, @var{STATUS} is -1; and otherwise the @var{STATUS} is
4912 @item @emph{Example}:
4914 PROGRAM test_get_command_argument
4916 CHARACTER(len=32) :: arg
4920 CALL get_command_argument(i, arg)
4921 IF (LEN_TRIM(arg) == 0) EXIT
4923 WRITE (*,*) TRIM(arg)
4929 @item @emph{See also}:
4930 @ref{GET_COMMAND}, @ref{COMMAND_ARGUMENT_COUNT}
4936 @section @code{GETCWD} --- Get current working directory
4938 @cindex system, working directory
4941 @item @emph{Description}:
4942 Get current working directory.
4944 This intrinsic is provided in both subroutine and function forms; however,
4945 only one form can be used in any given program unit.
4947 @item @emph{Standard}:
4951 Subroutine, function
4953 @item @emph{Syntax}:
4954 @code{CALL GETCWD(C [, STATUS])}
4956 @item @emph{Arguments}:
4957 @multitable @columnfractions .15 .70
4958 @item @var{C} @tab The type shall be @code{CHARACTER} and of default kind.
4959 @item @var{STATUS} @tab (Optional) status flag. Returns 0 on success,
4960 a system specific and nonzero error code otherwise.
4963 @item @emph{Example}:
4966 CHARACTER(len=255) :: cwd
4968 WRITE(*,*) TRIM(cwd)
4972 @item @emph{See also}:
4979 @section @code{GETENV} --- Get an environmental variable
4981 @cindex environment variable
4984 @item @emph{Description}:
4985 Get the @var{VALUE} of the environmental variable @var{NAME}.
4987 This intrinsic routine is provided for backwards compatibility with
4988 GNU Fortran 77. In new code, programmers should consider the use of
4989 the @ref{GET_ENVIRONMENT_VARIABLE} intrinsic defined by the Fortran
4992 @item @emph{Standard}:
4998 @item @emph{Syntax}:
4999 @code{CALL GETENV(NAME, VALUE)}
5001 @item @emph{Arguments}:
5002 @multitable @columnfractions .15 .70
5003 @item @var{NAME} @tab Shall be of type @code{CHARACTER} and of default kind.
5004 @item @var{VALUE} @tab Shall be of type @code{CHARACTER} and of default kind.
5007 @item @emph{Return value}:
5008 Stores the value of @var{NAME} in @var{VALUE}. If @var{VALUE} is
5009 not large enough to hold the data, it is truncated. If @var{NAME}
5010 is not set, @var{VALUE} will be filled with blanks.
5012 @item @emph{Example}:
5015 CHARACTER(len=255) :: homedir
5016 CALL getenv("HOME", homedir)
5017 WRITE (*,*) TRIM(homedir)
5021 @item @emph{See also}:
5022 @ref{GET_ENVIRONMENT_VARIABLE}
5027 @node GET_ENVIRONMENT_VARIABLE
5028 @section @code{GET_ENVIRONMENT_VARIABLE} --- Get an environmental variable
5029 @fnindex GET_ENVIRONMENT_VARIABLE
5030 @cindex environment variable
5033 @item @emph{Description}:
5034 Get the @var{VALUE} of the environmental variable @var{NAME}.
5036 @item @emph{Standard}:
5037 Fortran 2003 and later
5042 @item @emph{Syntax}:
5043 @code{CALL GET_ENVIRONMENT_VARIABLE(NAME[, VALUE, LENGTH, STATUS, TRIM_NAME)}
5045 @item @emph{Arguments}:
5046 @multitable @columnfractions .15 .70
5047 @item @var{NAME} @tab Shall be a scalar of type @code{CHARACTER}
5048 and of default kind.
5049 @item @var{VALUE} @tab Shall be a scalar of type @code{CHARACTER}
5050 and of default kind.
5051 @item @var{LENGTH} @tab Shall be a scalar of type @code{INTEGER}
5052 and of default kind.
5053 @item @var{STATUS} @tab Shall be a scalar of type @code{INTEGER}
5054 and of default kind.
5055 @item @var{TRIM_NAME} @tab Shall be a scalar of type @code{LOGICAL}
5056 and of default kind.
5059 @item @emph{Return value}:
5060 Stores the value of @var{NAME} in @var{VALUE}. If @var{VALUE} is
5061 not large enough to hold the data, it is truncated. If @var{NAME}
5062 is not set, @var{VALUE} will be filled with blanks. Argument @var{LENGTH}
5063 contains the length needed for storing the environment variable @var{NAME}
5064 or zero if it is not present. @var{STATUS} is -1 if @var{VALUE} is present
5065 but too short for the environment variable; it is 1 if the environment
5066 variable does not exist and 2 if the processor does not support environment
5067 variables; in all other cases @var{STATUS} is zero. If @var{TRIM_NAME} is
5068 present with the value @code{.FALSE.}, the trailing blanks in @var{NAME}
5069 are significant; otherwise they are not part of the environment variable
5072 @item @emph{Example}:
5075 CHARACTER(len=255) :: homedir
5076 CALL get_environment_variable("HOME", homedir)
5077 WRITE (*,*) TRIM(homedir)
5085 @section @code{GETGID} --- Group ID function
5087 @cindex system, group id
5090 @item @emph{Description}:
5091 Returns the numerical group ID of the current process.
5093 @item @emph{Standard}:
5099 @item @emph{Syntax}:
5100 @code{RESULT = GETGID()}
5102 @item @emph{Return value}:
5103 The return value of @code{GETGID} is an @code{INTEGER} of the default
5107 @item @emph{Example}:
5108 See @code{GETPID} for an example.
5110 @item @emph{See also}:
5111 @ref{GETPID}, @ref{GETUID}
5117 @section @code{GETLOG} --- Get login name
5119 @cindex system, login name
5123 @item @emph{Description}:
5124 Gets the username under which the program is running.
5126 @item @emph{Standard}:
5132 @item @emph{Syntax}:
5133 @code{CALL GETLOG(C)}
5135 @item @emph{Arguments}:
5136 @multitable @columnfractions .15 .70
5137 @item @var{C} @tab Shall be of type @code{CHARACTER} and of default kind.
5140 @item @emph{Return value}:
5141 Stores the current user name in @var{LOGIN}. (On systems where POSIX
5142 functions @code{geteuid} and @code{getpwuid} are not available, and
5143 the @code{getlogin} function is not implemented either, this will
5144 return a blank string.)
5146 @item @emph{Example}:
5149 CHARACTER(32) :: login
5155 @item @emph{See also}:
5162 @section @code{GETPID} --- Process ID function
5164 @cindex system, process id
5168 @item @emph{Description}:
5169 Returns the numerical process identifier of the current process.
5171 @item @emph{Standard}:
5177 @item @emph{Syntax}:
5178 @code{RESULT = GETPID()}
5180 @item @emph{Return value}:
5181 The return value of @code{GETPID} is an @code{INTEGER} of the default
5185 @item @emph{Example}:
5188 print *, "The current process ID is ", getpid()
5189 print *, "Your numerical user ID is ", getuid()
5190 print *, "Your numerical group ID is ", getgid()
5194 @item @emph{See also}:
5195 @ref{GETGID}, @ref{GETUID}
5201 @section @code{GETUID} --- User ID function
5203 @cindex system, user id
5207 @item @emph{Description}:
5208 Returns the numerical user ID of the current process.
5210 @item @emph{Standard}:
5216 @item @emph{Syntax}:
5217 @code{RESULT = GETUID()}
5219 @item @emph{Return value}:
5220 The return value of @code{GETUID} is an @code{INTEGER} of the default
5224 @item @emph{Example}:
5225 See @code{GETPID} for an example.
5227 @item @emph{See also}:
5228 @ref{GETPID}, @ref{GETLOG}
5234 @section @code{GMTIME} --- Convert time to GMT info
5236 @cindex time, conversion to GMT info
5239 @item @emph{Description}:
5240 Given a system time value @var{TIME} (as provided by the @code{TIME8()}
5241 intrinsic), fills @var{VALUES} with values extracted from it appropriate
5242 to the UTC time zone (Universal Coordinated Time, also known in some
5243 countries as GMT, Greenwich Mean Time), using @code{gmtime(3)}.
5245 @item @emph{Standard}:
5251 @item @emph{Syntax}:
5252 @code{CALL GMTIME(TIME, VALUES)}
5254 @item @emph{Arguments}:
5255 @multitable @columnfractions .15 .70
5256 @item @var{TIME} @tab An @code{INTEGER} scalar expression
5257 corresponding to a system time, with @code{INTENT(IN)}.
5258 @item @var{VALUES} @tab A default @code{INTEGER} array with 9 elements,
5259 with @code{INTENT(OUT)}.
5262 @item @emph{Return value}:
5263 The elements of @var{VALUES} are assigned as follows:
5265 @item Seconds after the minute, range 0--59 or 0--61 to allow for leap
5267 @item Minutes after the hour, range 0--59
5268 @item Hours past midnight, range 0--23
5269 @item Day of month, range 0--31
5270 @item Number of months since January, range 0--12
5271 @item Years since 1900
5272 @item Number of days since Sunday, range 0--6
5273 @item Days since January 1
5274 @item Daylight savings indicator: positive if daylight savings is in
5275 effect, zero if not, and negative if the information is not available.
5278 @item @emph{See also}:
5279 @ref{CTIME}, @ref{LTIME}, @ref{TIME}, @ref{TIME8}
5286 @section @code{HOSTNM} --- Get system host name
5288 @cindex system, host name
5291 @item @emph{Description}:
5292 Retrieves the host name of the system on which the program is running.
5294 This intrinsic is provided in both subroutine and function forms; however,
5295 only one form can be used in any given program unit.
5297 @item @emph{Standard}:
5301 Subroutine, function
5303 @item @emph{Syntax}:
5304 @multitable @columnfractions .80
5305 @item @code{CALL HOSTNM(C [, STATUS])}
5306 @item @code{STATUS = HOSTNM(NAME)}
5309 @item @emph{Arguments}:
5310 @multitable @columnfractions .15 .70
5311 @item @var{C} @tab Shall of type @code{CHARACTER} and of default kind.
5312 @item @var{STATUS} @tab (Optional) status flag of type @code{INTEGER}.
5313 Returns 0 on success, or a system specific error code otherwise.
5316 @item @emph{Return value}:
5317 In either syntax, @var{NAME} is set to the current hostname if it can
5318 be obtained, or to a blank string otherwise.
5325 @section @code{HUGE} --- Largest number of a kind
5327 @cindex limits, largest number
5328 @cindex model representation, largest number
5331 @item @emph{Description}:
5332 @code{HUGE(X)} returns the largest number that is not an infinity in
5333 the model of the type of @code{X}.
5335 @item @emph{Standard}:
5336 Fortran 95 and later
5341 @item @emph{Syntax}:
5342 @code{RESULT = HUGE(X)}
5344 @item @emph{Arguments}:
5345 @multitable @columnfractions .15 .70
5346 @item @var{X} @tab Shall be of type @code{REAL} or @code{INTEGER}.
5349 @item @emph{Return value}:
5350 The return value is of the same type and kind as @var{X}
5352 @item @emph{Example}:
5354 program test_huge_tiny
5355 print *, huge(0), huge(0.0), huge(0.0d0)
5356 print *, tiny(0.0), tiny(0.0d0)
5357 end program test_huge_tiny
5364 @section @code{HYPOT} --- Euclidean distance function
5366 @cindex Euclidean distance
5369 @item @emph{Description}:
5370 @code{HYPOT(X,Y)} is the Euclidean distance function. It is equal to
5371 @math{\sqrt{X^2 + Y^2}}, without undue underflow or overflow.
5373 @item @emph{Standard}:
5374 Fortran 2008 and later
5379 @item @emph{Syntax}:
5380 @code{RESULT = HYPOT(X, Y)}
5382 @item @emph{Arguments}:
5383 @multitable @columnfractions .15 .70
5384 @item @var{X} @tab The type shall be @code{REAL}.
5385 @item @var{Y} @tab The type and kind type parameter shall be the same as
5389 @item @emph{Return value}:
5390 The return value has the same type and kind type parameter as @var{X}.
5392 @item @emph{Example}:
5395 real(4) :: x = 1.e0_4, y = 0.5e0_4
5397 end program test_hypot
5404 @section @code{IACHAR} --- Code in @acronym{ASCII} collating sequence
5406 @cindex @acronym{ASCII} collating sequence
5407 @cindex collating sequence, @acronym{ASCII}
5408 @cindex conversion, to integer
5411 @item @emph{Description}:
5412 @code{IACHAR(C)} returns the code for the @acronym{ASCII} character
5413 in the first character position of @code{C}.
5415 @item @emph{Standard}:
5416 Fortran 95 and later, with @var{KIND} argument Fortran 2003 and later
5421 @item @emph{Syntax}:
5422 @code{RESULT = IACHAR(C [, KIND])}
5424 @item @emph{Arguments}:
5425 @multitable @columnfractions .15 .70
5426 @item @var{C} @tab Shall be a scalar @code{CHARACTER}, with @code{INTENT(IN)}
5427 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
5428 expression indicating the kind parameter of the result.
5431 @item @emph{Return value}:
5432 The return value is of type @code{INTEGER} and of kind @var{KIND}. If
5433 @var{KIND} is absent, the return value is of default integer kind.
5435 @item @emph{Example}:
5440 end program test_iachar
5444 See @ref{ICHAR} for a discussion of converting between numerical values
5445 and formatted string representations.
5447 @item @emph{See also}:
5448 @ref{ACHAR}, @ref{CHAR}, @ref{ICHAR}
5455 @section @code{IAND} --- Bitwise logical and
5457 @cindex bitwise logical and
5458 @cindex logical and, bitwise
5461 @item @emph{Description}:
5462 Bitwise logical @code{AND}.
5464 @item @emph{Standard}:
5465 Fortran 95 and later
5470 @item @emph{Syntax}:
5471 @code{RESULT = IAND(I, J)}
5473 @item @emph{Arguments}:
5474 @multitable @columnfractions .15 .70
5475 @item @var{I} @tab The type shall be @code{INTEGER}.
5476 @item @var{J} @tab The type shall be @code{INTEGER}, of the same
5477 kind as @var{I}. (As a GNU extension, different kinds are also
5481 @item @emph{Return value}:
5482 The return type is @code{INTEGER}, of the same kind as the
5483 arguments. (If the argument kinds differ, it is of the same kind as
5484 the larger argument.)
5486 @item @emph{Example}:
5490 DATA a / Z'F' /, b / Z'3' /
5491 WRITE (*,*) IAND(a, b)
5495 @item @emph{See also}:
5496 @ref{IOR}, @ref{IEOR}, @ref{IBITS}, @ref{IBSET}, @ref{IBCLR}, @ref{NOT}
5503 @section @code{IARGC} --- Get the number of command line arguments
5505 @cindex command-line arguments
5506 @cindex command-line arguments, number of
5507 @cindex arguments, to program
5510 @item @emph{Description}:
5511 @code{IARGC()} returns the number of arguments passed on the
5512 command line when the containing program was invoked.
5514 This intrinsic routine is provided for backwards compatibility with
5515 GNU Fortran 77. In new code, programmers should consider the use of
5516 the @ref{COMMAND_ARGUMENT_COUNT} intrinsic defined by the Fortran 2003
5519 @item @emph{Standard}:
5525 @item @emph{Syntax}:
5526 @code{RESULT = IARGC()}
5528 @item @emph{Arguments}:
5531 @item @emph{Return value}:
5532 The number of command line arguments, type @code{INTEGER(4)}.
5534 @item @emph{Example}:
5537 @item @emph{See also}:
5538 GNU Fortran 77 compatibility subroutine: @ref{GETARG}
5540 Fortran 2003 functions and subroutines: @ref{GET_COMMAND},
5541 @ref{GET_COMMAND_ARGUMENT}, @ref{COMMAND_ARGUMENT_COUNT}
5547 @section @code{IBCLR} --- Clear bit
5553 @item @emph{Description}:
5554 @code{IBCLR} returns the value of @var{I} with the bit at position
5555 @var{POS} set to zero.
5557 @item @emph{Standard}:
5558 Fortran 95 and later
5563 @item @emph{Syntax}:
5564 @code{RESULT = IBCLR(I, POS)}
5566 @item @emph{Arguments}:
5567 @multitable @columnfractions .15 .70
5568 @item @var{I} @tab The type shall be @code{INTEGER}.
5569 @item @var{POS} @tab The type shall be @code{INTEGER}.
5572 @item @emph{Return value}:
5573 The return value is of type @code{INTEGER} and of the same kind as
5576 @item @emph{See also}:
5577 @ref{IBITS}, @ref{IBSET}, @ref{IAND}, @ref{IOR}, @ref{IEOR}, @ref{MVBITS}
5584 @section @code{IBITS} --- Bit extraction
5587 @cindex bits, extract
5590 @item @emph{Description}:
5591 @code{IBITS} extracts a field of length @var{LEN} from @var{I},
5592 starting from bit position @var{POS} and extending left for @var{LEN}
5593 bits. The result is right-justified and the remaining bits are
5594 zeroed. The value of @code{POS+LEN} must be less than or equal to the
5595 value @code{BIT_SIZE(I)}.
5597 @item @emph{Standard}:
5598 Fortran 95 and later
5603 @item @emph{Syntax}:
5604 @code{RESULT = IBITS(I, POS, LEN)}
5606 @item @emph{Arguments}:
5607 @multitable @columnfractions .15 .70
5608 @item @var{I} @tab The type shall be @code{INTEGER}.
5609 @item @var{POS} @tab The type shall be @code{INTEGER}.
5610 @item @var{LEN} @tab The type shall be @code{INTEGER}.
5613 @item @emph{Return value}:
5614 The return value is of type @code{INTEGER} and of the same kind as
5617 @item @emph{See also}:
5618 @ref{BIT_SIZE}, @ref{IBCLR}, @ref{IBSET}, @ref{IAND}, @ref{IOR}, @ref{IEOR}
5624 @section @code{IBSET} --- Set bit
5629 @item @emph{Description}:
5630 @code{IBSET} returns the value of @var{I} with the bit at position
5631 @var{POS} set to one.
5633 @item @emph{Standard}:
5634 Fortran 95 and later
5639 @item @emph{Syntax}:
5640 @code{RESULT = IBSET(I, POS)}
5642 @item @emph{Arguments}:
5643 @multitable @columnfractions .15 .70
5644 @item @var{I} @tab The type shall be @code{INTEGER}.
5645 @item @var{POS} @tab The type shall be @code{INTEGER}.
5648 @item @emph{Return value}:
5649 The return value is of type @code{INTEGER} and of the same kind as
5652 @item @emph{See also}:
5653 @ref{IBCLR}, @ref{IBITS}, @ref{IAND}, @ref{IOR}, @ref{IEOR}, @ref{MVBITS}
5660 @section @code{ICHAR} --- Character-to-integer conversion function
5662 @cindex conversion, to integer
5665 @item @emph{Description}:
5666 @code{ICHAR(C)} returns the code for the character in the first character
5667 position of @code{C} in the system's native character set.
5668 The correspondence between characters and their codes is not necessarily
5669 the same across different GNU Fortran implementations.
5671 @item @emph{Standard}:
5672 Fortan 95 and later, with @var{KIND} argument Fortran 2003 and later
5677 @item @emph{Syntax}:
5678 @code{RESULT = ICHAR(C [, KIND])}
5680 @item @emph{Arguments}:
5681 @multitable @columnfractions .15 .70
5682 @item @var{C} @tab Shall be a scalar @code{CHARACTER}, with @code{INTENT(IN)}
5683 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
5684 expression indicating the kind parameter of the result.
5687 @item @emph{Return value}:
5688 The return value is of type @code{INTEGER} and of kind @var{KIND}. If
5689 @var{KIND} is absent, the return value is of default integer kind.
5691 @item @emph{Example}:
5696 end program test_ichar
5700 No intrinsic exists to convert between a numeric value and a formatted
5701 character string representation -- for instance, given the
5702 @code{CHARACTER} value @code{'154'}, obtaining an @code{INTEGER} or
5703 @code{REAL} value with the value 154, or vice versa. Instead, this
5704 functionality is provided by internal-file I/O, as in the following
5709 character(len=10) string, string2
5712 ! Convert a string to a numeric value
5713 read (string,'(I10)') value
5716 ! Convert a value to a formatted string
5717 write (string2,'(I10)') value
5719 end program read_val
5722 @item @emph{See also}:
5723 @ref{ACHAR}, @ref{CHAR}, @ref{IACHAR}
5730 @section @code{IDATE} --- Get current local time subroutine (day/month/year)
5732 @cindex date, current
5733 @cindex current date
5736 @item @emph{Description}:
5737 @code{IDATE(VALUES)} Fills @var{VALUES} with the numerical values at the
5738 current local time. The day (in the range 1-31), month (in the range 1-12),
5739 and year appear in elements 1, 2, and 3 of @var{VALUES}, respectively.
5740 The year has four significant digits.
5742 @item @emph{Standard}:
5748 @item @emph{Syntax}:
5749 @code{CALL IDATE(VALUES)}
5751 @item @emph{Arguments}:
5752 @multitable @columnfractions .15 .70
5753 @item @var{VALUES} @tab The type shall be @code{INTEGER, DIMENSION(3)} and
5754 the kind shall be the default integer kind.
5757 @item @emph{Return value}:
5758 Does not return anything.
5760 @item @emph{Example}:
5763 integer, dimension(3) :: tarray
5768 end program test_idate
5775 @section @code{IEOR} --- Bitwise logical exclusive or
5777 @cindex bitwise logical exclusive or
5778 @cindex logical exclusive or, bitwise
5781 @item @emph{Description}:
5782 @code{IEOR} returns the bitwise boolean exclusive-OR of @var{I} and
5785 @item @emph{Standard}:
5786 Fortran 95 and later
5791 @item @emph{Syntax}:
5792 @code{RESULT = IEOR(I, J)}
5794 @item @emph{Arguments}:
5795 @multitable @columnfractions .15 .70
5796 @item @var{I} @tab The type shall be @code{INTEGER}.
5797 @item @var{J} @tab The type shall be @code{INTEGER}, of the same
5798 kind as @var{I}. (As a GNU extension, different kinds are also
5802 @item @emph{Return value}:
5803 The return type is @code{INTEGER}, of the same kind as the
5804 arguments. (If the argument kinds differ, it is of the same kind as
5805 the larger argument.)
5807 @item @emph{See also}:
5808 @ref{IOR}, @ref{IAND}, @ref{IBITS}, @ref{IBSET}, @ref{IBCLR}, @ref{NOT}
5814 @section @code{IERRNO} --- Get the last system error number
5816 @cindex system, error handling
5819 @item @emph{Description}:
5820 Returns the last system error number, as given by the C @code{errno()}
5823 @item @emph{Standard}:
5829 @item @emph{Syntax}:
5830 @code{RESULT = IERRNO()}
5832 @item @emph{Arguments}:
5835 @item @emph{Return value}:
5836 The return value is of type @code{INTEGER} and of the default integer
5839 @item @emph{See also}:
5845 @node INDEX intrinsic
5846 @section @code{INDEX} --- Position of a substring within a string
5848 @cindex substring position
5849 @cindex string, find substring
5852 @item @emph{Description}:
5853 Returns the position of the start of the first occurrence of string
5854 @var{SUBSTRING} as a substring in @var{STRING}, counting from one. If
5855 @var{SUBSTRING} is not present in @var{STRING}, zero is returned. If
5856 the @var{BACK} argument is present and true, the return value is the
5857 start of the last occurrence rather than the first.
5859 @item @emph{Standard}:
5860 Fortran 77 and later, with @var{KIND} argument Fortran 2003 and later
5865 @item @emph{Syntax}:
5866 @code{RESULT = INDEX(STRING, SUBSTRING [, BACK [, KIND]])}
5868 @item @emph{Arguments}:
5869 @multitable @columnfractions .15 .70
5870 @item @var{STRING} @tab Shall be a scalar @code{CHARACTER}, with
5872 @item @var{SUBSTRING} @tab Shall be a scalar @code{CHARACTER}, with
5874 @item @var{BACK} @tab (Optional) Shall be a scalar @code{LOGICAL}, with
5876 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
5877 expression indicating the kind parameter of the result.
5880 @item @emph{Return value}:
5881 The return value is of type @code{INTEGER} and of kind @var{KIND}. If
5882 @var{KIND} is absent, the return value is of default integer kind.
5884 @item @emph{See also}:
5885 @ref{SCAN}, @ref{VERIFY}
5891 @section @code{INT} --- Convert to integer type
5895 @cindex conversion, to integer
5898 @item @emph{Description}:
5899 Convert to integer type
5901 @item @emph{Standard}:
5902 Fortran 77 and later
5907 @item @emph{Syntax}:
5908 @code{RESULT = INT(A [, KIND))}
5910 @item @emph{Arguments}:
5911 @multitable @columnfractions .15 .70
5912 @item @var{A} @tab Shall be of type @code{INTEGER},
5913 @code{REAL}, or @code{COMPLEX}.
5914 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
5915 expression indicating the kind parameter of the result.
5918 @item @emph{Return value}:
5919 These functions return a @code{INTEGER} variable or array under
5920 the following rules:
5924 If @var{A} is of type @code{INTEGER}, @code{INT(A) = A}
5926 If @var{A} is of type @code{REAL} and @math{|A| < 1}, @code{INT(A)} equals @code{0}.
5927 If @math{|A| \geq 1}, then @code{INT(A)} equals the largest integer that does not exceed
5928 the range of @var{A} and whose sign is the same as the sign of @var{A}.
5930 If @var{A} is of type @code{COMPLEX}, rule B is applied to the real part of @var{A}.
5933 @item @emph{Example}:
5937 complex :: z = (-3.7, 1.0)
5939 print *, int(z), int(z,8)
5943 @item @emph{Specific names}:
5944 @multitable @columnfractions .20 .20 .20 .25
5945 @item Name @tab Argument @tab Return type @tab Standard
5946 @item @code{IFIX(A)} @tab @code{REAL(4) A} @tab @code{INTEGER} @tab Fortran 77 and later
5947 @item @code{IDINT(A)} @tab @code{REAL(8) A} @tab @code{INTEGER} @tab Fortran 77 and later
5955 @section @code{INT2} --- Convert to 16-bit integer type
5958 @cindex conversion, to integer
5961 @item @emph{Description}:
5962 Convert to a @code{KIND=2} integer type. This is equivalent to the
5963 standard @code{INT} intrinsic with an optional argument of
5964 @code{KIND=2}, and is only included for backwards compatibility.
5966 The @code{SHORT} intrinsic is equivalent to @code{INT2}.
5968 @item @emph{Standard}:
5974 @item @emph{Syntax}:
5975 @code{RESULT = INT2(A)}
5977 @item @emph{Arguments}:
5978 @multitable @columnfractions .15 .70
5979 @item @var{A} @tab Shall be of type @code{INTEGER},
5980 @code{REAL}, or @code{COMPLEX}.
5983 @item @emph{Return value}:
5984 The return value is a @code{INTEGER(2)} variable.
5986 @item @emph{See also}:
5987 @ref{INT}, @ref{INT8}, @ref{LONG}
5993 @section @code{INT8} --- Convert to 64-bit integer type
5995 @cindex conversion, to integer
5998 @item @emph{Description}:
5999 Convert to a @code{KIND=8} integer type. This is equivalent to the
6000 standard @code{INT} intrinsic with an optional argument of
6001 @code{KIND=8}, and is only included for backwards compatibility.
6003 @item @emph{Standard}:
6009 @item @emph{Syntax}:
6010 @code{RESULT = INT8(A)}
6012 @item @emph{Arguments}:
6013 @multitable @columnfractions .15 .70
6014 @item @var{A} @tab Shall be of type @code{INTEGER},
6015 @code{REAL}, or @code{COMPLEX}.
6018 @item @emph{Return value}:
6019 The return value is a @code{INTEGER(8)} variable.
6021 @item @emph{See also}:
6022 @ref{INT}, @ref{INT2}, @ref{LONG}
6028 @section @code{IOR} --- Bitwise logical or
6030 @cindex bitwise logical or
6031 @cindex logical or, bitwise
6034 @item @emph{Description}:
6035 @code{IOR} returns the bitwise boolean inclusive-OR of @var{I} and
6038 @item @emph{Standard}:
6039 Fortran 95 and later
6044 @item @emph{Syntax}:
6045 @code{RESULT = IOR(I, J)}
6047 @item @emph{Arguments}:
6048 @multitable @columnfractions .15 .70
6049 @item @var{I} @tab The type shall be @code{INTEGER}.
6050 @item @var{J} @tab The type shall be @code{INTEGER}, of the same
6051 kind as @var{I}. (As a GNU extension, different kinds are also
6055 @item @emph{Return value}:
6056 The return type is @code{INTEGER}, of the same kind as the
6057 arguments. (If the argument kinds differ, it is of the same kind as
6058 the larger argument.)
6060 @item @emph{See also}:
6061 @ref{IEOR}, @ref{IAND}, @ref{IBITS}, @ref{IBSET}, @ref{IBCLR}, @ref{NOT}
6067 @section @code{IRAND} --- Integer pseudo-random number
6069 @cindex random number generation
6072 @item @emph{Description}:
6073 @code{IRAND(FLAG)} returns a pseudo-random number from a uniform
6074 distribution between 0 and a system-dependent limit (which is in most
6075 cases 2147483647). If @var{FLAG} is 0, the next number
6076 in the current sequence is returned; if @var{FLAG} is 1, the generator
6077 is restarted by @code{CALL SRAND(0)}; if @var{FLAG} has any other value,
6078 it is used as a new seed with @code{SRAND}.
6080 This intrinsic routine is provided for backwards compatibility with
6081 GNU Fortran 77. It implements a simple modulo generator as provided
6082 by @command{g77}. For new code, one should consider the use of
6083 @ref{RANDOM_NUMBER} as it implements a superior algorithm.
6085 @item @emph{Standard}:
6091 @item @emph{Syntax}:
6092 @code{RESULT = IRAND(I)}
6094 @item @emph{Arguments}:
6095 @multitable @columnfractions .15 .70
6096 @item @var{I} @tab Shall be a scalar @code{INTEGER} of kind 4.
6099 @item @emph{Return value}:
6100 The return value is of @code{INTEGER(kind=4)} type.
6102 @item @emph{Example}:
6105 integer,parameter :: seed = 86456
6108 print *, irand(), irand(), irand(), irand()
6109 print *, irand(seed), irand(), irand(), irand()
6110 end program test_irand
6118 @section @code{IS_IOSTAT_END} --- Test for end-of-file value
6119 @fnindex IS_IOSTAT_END
6120 @cindex IOSTAT, end of file
6123 @item @emph{Description}:
6124 @code{IS_IOSTAT_END} tests whether an variable has the value of the I/O
6125 status ``end of file''. The function is equivalent to comparing the variable
6126 with the @code{IOSTAT_END} parameter of the intrinsic module
6127 @code{ISO_FORTRAN_ENV}.
6129 @item @emph{Standard}:
6130 Fortran 2003 and later
6135 @item @emph{Syntax}:
6136 @code{RESULT = IS_IOSTAT_END(I)}
6138 @item @emph{Arguments}:
6139 @multitable @columnfractions .15 .70
6140 @item @var{I} @tab Shall be of the type @code{INTEGER}.
6143 @item @emph{Return value}:
6144 Returns a @code{LOGICAL} of the default kind, which @code{.TRUE.} if
6145 @var{I} has the value which indicates an end of file condition for
6146 IOSTAT= specifiers, and is @code{.FALSE.} otherwise.
6148 @item @emph{Example}:
6153 OPEN(88, FILE='test.dat')
6154 READ(88, *, IOSTAT=stat) i
6155 IF(IS_IOSTAT_END(stat)) STOP 'END OF FILE'
6163 @section @code{IS_IOSTAT_EOR} --- Test for end-of-record value
6164 @fnindex IS_IOSTAT_EOR
6165 @cindex IOSTAT, end of record
6168 @item @emph{Description}:
6169 @code{IS_IOSTAT_EOR} tests whether an variable has the value of the I/O
6170 status ``end of record''. The function is equivalent to comparing the
6171 variable with the @code{IOSTAT_EOR} parameter of the intrinsic module
6172 @code{ISO_FORTRAN_ENV}.
6174 @item @emph{Standard}:
6175 Fortran 2003 and later
6180 @item @emph{Syntax}:
6181 @code{RESULT = IS_IOSTAT_EOR(I)}
6183 @item @emph{Arguments}:
6184 @multitable @columnfractions .15 .70
6185 @item @var{I} @tab Shall be of the type @code{INTEGER}.
6188 @item @emph{Return value}:
6189 Returns a @code{LOGICAL} of the default kind, which @code{.TRUE.} if
6190 @var{I} has the value which indicates an end of file condition for
6191 IOSTAT= specifiers, and is @code{.FALSE.} otherwise.
6193 @item @emph{Example}:
6197 INTEGER :: stat, i(50)
6198 OPEN(88, FILE='test.dat', FORM='UNFORMATTED')
6199 READ(88, IOSTAT=stat) i
6200 IF(IS_IOSTAT_EOR(stat)) STOP 'END OF RECORD'
6208 @section @code{ISATTY} --- Whether a unit is a terminal device.
6210 @cindex system, terminal
6213 @item @emph{Description}:
6214 Determine whether a unit is connected to a terminal device.
6216 @item @emph{Standard}:
6222 @item @emph{Syntax}:
6223 @code{RESULT = ISATTY(UNIT)}
6225 @item @emph{Arguments}:
6226 @multitable @columnfractions .15 .70
6227 @item @var{UNIT} @tab Shall be a scalar @code{INTEGER}.
6230 @item @emph{Return value}:
6231 Returns @code{.TRUE.} if the @var{UNIT} is connected to a terminal
6232 device, @code{.FALSE.} otherwise.
6234 @item @emph{Example}:
6237 INTEGER(kind=1) :: unit
6239 write(*,*) isatty(unit=unit)
6243 @item @emph{See also}:
6250 @section @code{ISHFT} --- Shift bits
6255 @item @emph{Description}:
6256 @code{ISHFT} returns a value corresponding to @var{I} with all of the
6257 bits shifted @var{SHIFT} places. A value of @var{SHIFT} greater than
6258 zero corresponds to a left shift, a value of zero corresponds to no
6259 shift, and a value less than zero corresponds to a right shift. If the
6260 absolute value of @var{SHIFT} is greater than @code{BIT_SIZE(I)}, the
6261 value is undefined. Bits shifted out from the left end or right end are
6262 lost; zeros are shifted in from the opposite end.
6264 @item @emph{Standard}:
6265 Fortran 95 and later
6270 @item @emph{Syntax}:
6271 @code{RESULT = ISHFT(I, SHIFT)}
6273 @item @emph{Arguments}:
6274 @multitable @columnfractions .15 .70
6275 @item @var{I} @tab The type shall be @code{INTEGER}.
6276 @item @var{SHIFT} @tab The type shall be @code{INTEGER}.
6279 @item @emph{Return value}:
6280 The return value is of type @code{INTEGER} and of the same kind as
6283 @item @emph{See also}:
6290 @section @code{ISHFTC} --- Shift bits circularly
6292 @cindex bits, shift circular
6295 @item @emph{Description}:
6296 @code{ISHFTC} returns a value corresponding to @var{I} with the
6297 rightmost @var{SIZE} bits shifted circularly @var{SHIFT} places; that
6298 is, bits shifted out one end are shifted into the opposite end. A value
6299 of @var{SHIFT} greater than zero corresponds to a left shift, a value of
6300 zero corresponds to no shift, and a value less than zero corresponds to
6301 a right shift. The absolute value of @var{SHIFT} must be less than
6302 @var{SIZE}. If the @var{SIZE} argument is omitted, it is taken to be
6303 equivalent to @code{BIT_SIZE(I)}.
6305 @item @emph{Standard}:
6306 Fortran 95 and later
6311 @item @emph{Syntax}:
6312 @code{RESULT = ISHFTC(I, SHIFT [, SIZE])}
6314 @item @emph{Arguments}:
6315 @multitable @columnfractions .15 .70
6316 @item @var{I} @tab The type shall be @code{INTEGER}.
6317 @item @var{SHIFT} @tab The type shall be @code{INTEGER}.
6318 @item @var{SIZE} @tab (Optional) The type shall be @code{INTEGER};
6319 the value must be greater than zero and less than or equal to
6323 @item @emph{Return value}:
6324 The return value is of type @code{INTEGER} and of the same kind as
6327 @item @emph{See also}:
6334 @section @code{ISNAN} --- Test for a NaN
6339 @item @emph{Description}:
6340 @code{ISNAN} tests whether a floating-point value is an IEEE
6342 @item @emph{Standard}:
6348 @item @emph{Syntax}:
6351 @item @emph{Arguments}:
6352 @multitable @columnfractions .15 .70
6353 @item @var{X} @tab Variable of the type @code{REAL}.
6357 @item @emph{Return value}:
6358 Returns a default-kind @code{LOGICAL}. The returned value is @code{TRUE}
6359 if @var{X} is a NaN and @code{FALSE} otherwise.
6361 @item @emph{Example}:
6368 if (isnan(x)) stop '"x" is a NaN'
6369 end program test_nan
6376 @section @code{ITIME} --- Get current local time subroutine (hour/minutes/seconds)
6378 @cindex time, current
6379 @cindex current time
6382 @item @emph{Description}:
6383 @code{IDATE(VALUES)} Fills @var{VALUES} with the numerical values at the
6384 current local time. The hour (in the range 1-24), minute (in the range 1-60),
6385 and seconds (in the range 1-60) appear in elements 1, 2, and 3 of @var{VALUES},
6388 @item @emph{Standard}:
6394 @item @emph{Syntax}:
6395 @code{CALL ITIME(VALUES)}
6397 @item @emph{Arguments}:
6398 @multitable @columnfractions .15 .70
6399 @item @var{VALUES} @tab The type shall be @code{INTEGER, DIMENSION(3)}
6400 and the kind shall be the default integer kind.
6403 @item @emph{Return value}:
6404 Does not return anything.
6407 @item @emph{Example}:
6410 integer, dimension(3) :: tarray
6415 end program test_itime
6422 @section @code{KILL} --- Send a signal to a process
6426 @item @emph{Description}:
6427 @item @emph{Standard}:
6428 Sends the signal specified by @var{SIGNAL} to the process @var{PID}.
6431 This intrinsic is provided in both subroutine and function forms; however,
6432 only one form can be used in any given program unit.
6435 Subroutine, function
6437 @item @emph{Syntax}:
6438 @code{CALL KILL(C, VALUE [, STATUS])}
6440 @item @emph{Arguments}:
6441 @multitable @columnfractions .15 .70
6442 @item @var{C} @tab Shall be a scalar @code{INTEGER}, with
6444 @item @var{VALUE} @tab Shall be a scalar @code{INTEGER}, with
6446 @item @var{STATUS} @tab (Optional) status flag of type @code{INTEGER(4)} or
6447 @code{INTEGER(8)}. Returns 0 on success, or a system-specific error code
6451 @item @emph{See also}:
6452 @ref{ABORT}, @ref{EXIT}
6458 @section @code{KIND} --- Kind of an entity
6463 @item @emph{Description}:
6464 @code{KIND(X)} returns the kind value of the entity @var{X}.
6466 @item @emph{Standard}:
6467 Fortran 95 and later
6472 @item @emph{Syntax}:
6475 @item @emph{Arguments}:
6476 @multitable @columnfractions .15 .70
6477 @item @var{X} @tab Shall be of type @code{LOGICAL}, @code{INTEGER},
6478 @code{REAL}, @code{COMPLEX} or @code{CHARACTER}.
6481 @item @emph{Return value}:
6482 The return value is a scalar of type @code{INTEGER} and of the default
6485 @item @emph{Example}:
6488 integer,parameter :: kc = kind(' ')
6489 integer,parameter :: kl = kind(.true.)
6491 print *, "The default character kind is ", kc
6492 print *, "The default logical kind is ", kl
6493 end program test_kind
6501 @section @code{LBOUND} --- Lower dimension bounds of an array
6503 @cindex array, lower bound
6506 @item @emph{Description}:
6507 Returns the lower bounds of an array, or a single lower bound
6508 along the @var{DIM} dimension.
6509 @item @emph{Standard}:
6510 Fortran 95 and later, with @var{KIND} argument Fortran 2003 and later
6515 @item @emph{Syntax}:
6516 @code{RESULT = LBOUND(ARRAY [, DIM [, KIND]])}
6518 @item @emph{Arguments}:
6519 @multitable @columnfractions .15 .70
6520 @item @var{ARRAY} @tab Shall be an array, of any type.
6521 @item @var{DIM} @tab (Optional) Shall be a scalar @code{INTEGER}.
6522 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
6523 expression indicating the kind parameter of the result.
6526 @item @emph{Return value}:
6527 The return value is of type @code{INTEGER} and of kind @var{KIND}. If
6528 @var{KIND} is absent, the return value is of default integer kind.
6529 If @var{DIM} is absent, the result is an array of the lower bounds of
6530 @var{ARRAY}. If @var{DIM} is present, the result is a scalar
6531 corresponding to the lower bound of the array along that dimension. If
6532 @var{ARRAY} is an expression rather than a whole array or array
6533 structure component, or if it has a zero extent along the relevant
6534 dimension, the lower bound is taken to be 1.
6536 @item @emph{See also}:
6543 @section @code{LEADZ} --- Number of leading zero bits of an integer
6548 @item @emph{Description}:
6549 @code{LEADZ} returns the number of leading zero bits of an integer.
6551 @item @emph{Standard}:
6552 Fortran 2008 and later
6557 @item @emph{Syntax}:
6558 @code{RESULT = LEADZ(I)}
6560 @item @emph{Arguments}:
6561 @multitable @columnfractions .15 .70
6562 @item @var{I} @tab Shall be of type @code{INTEGER}.
6565 @item @emph{Return value}:
6566 The type of the return value is the default @code{INTEGER}.
6567 If all the bits of @code{I} are zero, the result value is @code{BIT_SIZE(I)}.
6569 @item @emph{Example}:
6572 WRITE (*,*) LEADZ(1) ! prints 8 if BITSIZE(I) has the value 32
6576 @item @emph{See also}:
6577 @ref{BIT_SIZE}, @ref{TRAILZ}
6583 @section @code{LEN} --- Length of a character entity
6585 @cindex string, length
6588 @item @emph{Description}:
6589 Returns the length of a character string. If @var{STRING} is an array,
6590 the length of an element of @var{STRING} is returned. Note that
6591 @var{STRING} need not be defined when this intrinsic is invoked, since
6592 only the length, not the content, of @var{STRING} is needed.
6594 @item @emph{Standard}:
6595 Fortran 77 and later, with @var{KIND} argument Fortran 2003 and later
6600 @item @emph{Syntax}:
6601 @code{L = LEN(STRING [, KIND])}
6603 @item @emph{Arguments}:
6604 @multitable @columnfractions .15 .70
6605 @item @var{STRING} @tab Shall be a scalar or array of type
6606 @code{CHARACTER}, with @code{INTENT(IN)}
6607 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
6608 expression indicating the kind parameter of the result.
6611 @item @emph{Return value}:
6612 The return value is of type @code{INTEGER} and of kind @var{KIND}. If
6613 @var{KIND} is absent, the return value is of default integer kind.
6615 @item @emph{See also}:
6616 @ref{LEN_TRIM}, @ref{ADJUSTL}, @ref{ADJUSTR}
6622 @section @code{LEN_TRIM} --- Length of a character entity without trailing blank characters
6624 @cindex string, length, without trailing whitespace
6627 @item @emph{Description}:
6628 Returns the length of a character string, ignoring any trailing blanks.
6630 @item @emph{Standard}:
6631 Fortran 95 and later, with @var{KIND} argument Fortran 2003 and later
6636 @item @emph{Syntax}:
6637 @code{RESULT = LEN_TRIM(STRING [, KIND])}
6639 @item @emph{Arguments}:
6640 @multitable @columnfractions .15 .70
6641 @item @var{STRING} @tab Shall be a scalar of type @code{CHARACTER},
6642 with @code{INTENT(IN)}
6643 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
6644 expression indicating the kind parameter of the result.
6647 @item @emph{Return value}:
6648 The return value is of type @code{INTEGER} and of kind @var{KIND}. If
6649 @var{KIND} is absent, the return value is of default integer kind.
6651 @item @emph{See also}:
6652 @ref{LEN}, @ref{ADJUSTL}, @ref{ADJUSTR}
6658 @section @code{LGE} --- Lexical greater than or equal
6660 @cindex lexical comparison of strings
6661 @cindex string, comparison
6664 @item @emph{Description}:
6665 Determines whether one string is lexically greater than or equal to
6666 another string, where the two strings are interpreted as containing
6667 ASCII character codes. If the String A and String B are not the same
6668 length, the shorter is compared as if spaces were appended to it to form
6669 a value that has the same length as the longer.
6671 In general, the lexical comparison intrinsics @code{LGE}, @code{LGT},
6672 @code{LLE}, and @code{LLT} differ from the corresponding intrinsic
6673 operators @code{.GE.}, @code{.GT.}, @code{.LE.}, and @code{.LT.}, in
6674 that the latter use the processor's character ordering (which is not
6675 ASCII on some targets), whereas the former always use the ASCII
6678 @item @emph{Standard}:
6679 Fortran 77 and later
6684 @item @emph{Syntax}:
6685 @code{RESULT = LGE(STRING_A, STRING_B)}
6687 @item @emph{Arguments}:
6688 @multitable @columnfractions .15 .70
6689 @item @var{STRING_A} @tab Shall be of default @code{CHARACTER} type.
6690 @item @var{STRING_B} @tab Shall be of default @code{CHARACTER} type.
6693 @item @emph{Return value}:
6694 Returns @code{.TRUE.} if @code{STRING_A >= STRING_B}, and @code{.FALSE.}
6695 otherwise, based on the ASCII ordering.
6697 @item @emph{See also}:
6698 @ref{LGT}, @ref{LLE}, @ref{LLT}
6704 @section @code{LGT} --- Lexical greater than
6706 @cindex lexical comparison of strings
6707 @cindex string, comparison
6710 @item @emph{Description}:
6711 Determines whether one string is lexically greater than another string,
6712 where the two strings are interpreted as containing ASCII character
6713 codes. If the String A and String B are not the same length, the
6714 shorter is compared as if spaces were appended to it to form a value
6715 that has the same length as the longer.
6717 In general, the lexical comparison intrinsics @code{LGE}, @code{LGT},
6718 @code{LLE}, and @code{LLT} differ from the corresponding intrinsic
6719 operators @code{.GE.}, @code{.GT.}, @code{.LE.}, and @code{.LT.}, in
6720 that the latter use the processor's character ordering (which is not
6721 ASCII on some targets), whereas the former always use the ASCII
6724 @item @emph{Standard}:
6725 Fortran 77 and later
6730 @item @emph{Syntax}:
6731 @code{RESULT = LGT(STRING_A, STRING_B)}
6733 @item @emph{Arguments}:
6734 @multitable @columnfractions .15 .70
6735 @item @var{STRING_A} @tab Shall be of default @code{CHARACTER} type.
6736 @item @var{STRING_B} @tab Shall be of default @code{CHARACTER} type.
6739 @item @emph{Return value}:
6740 Returns @code{.TRUE.} if @code{STRING_A > STRING_B}, and @code{.FALSE.}
6741 otherwise, based on the ASCII ordering.
6743 @item @emph{See also}:
6744 @ref{LGE}, @ref{LLE}, @ref{LLT}
6750 @section @code{LINK} --- Create a hard link
6752 @cindex file system, create link
6753 @cindex file system, hard link
6756 @item @emph{Description}:
6757 Makes a (hard) link from file @var{PATH1} to @var{PATH2}. A null
6758 character (@code{CHAR(0)}) can be used to mark the end of the names in
6759 @var{PATH1} and @var{PATH2}; otherwise, trailing blanks in the file
6760 names are ignored. If the @var{STATUS} argument is supplied, it
6761 contains 0 on success or a nonzero error code upon return; see
6764 This intrinsic is provided in both subroutine and function forms;
6765 however, only one form can be used in any given program unit.
6767 @item @emph{Standard}:
6771 Subroutine, function
6773 @item @emph{Syntax}:
6774 @multitable @columnfractions .80
6775 @item @code{CALL LINK(PATH1, PATH2 [, STATUS])}
6776 @item @code{STATUS = LINK(PATH1, PATH2)}
6779 @item @emph{Arguments}:
6780 @multitable @columnfractions .15 .70
6781 @item @var{PATH1} @tab Shall be of default @code{CHARACTER} type.
6782 @item @var{PATH2} @tab Shall be of default @code{CHARACTER} type.
6783 @item @var{STATUS} @tab (Optional) Shall be of default @code{INTEGER} type.
6786 @item @emph{See also}:
6787 @ref{SYMLNK}, @ref{UNLINK}
6793 @section @code{LLE} --- Lexical less than or equal
6795 @cindex lexical comparison of strings
6796 @cindex string, comparison
6799 @item @emph{Description}:
6800 Determines whether one string is lexically less than or equal to another
6801 string, where the two strings are interpreted as containing ASCII
6802 character codes. If the String A and String B are not the same length,
6803 the shorter is compared as if spaces were appended to it to form a value
6804 that has the same length as the longer.
6806 In general, the lexical comparison intrinsics @code{LGE}, @code{LGT},
6807 @code{LLE}, and @code{LLT} differ from the corresponding intrinsic
6808 operators @code{.GE.}, @code{.GT.}, @code{.LE.}, and @code{.LT.}, in
6809 that the latter use the processor's character ordering (which is not
6810 ASCII on some targets), whereas the former always use the ASCII
6813 @item @emph{Standard}:
6814 Fortran 77 and later
6819 @item @emph{Syntax}:
6820 @code{RESULT = LLE(STRING_A, STRING_B)}
6822 @item @emph{Arguments}:
6823 @multitable @columnfractions .15 .70
6824 @item @var{STRING_A} @tab Shall be of default @code{CHARACTER} type.
6825 @item @var{STRING_B} @tab Shall be of default @code{CHARACTER} type.
6828 @item @emph{Return value}:
6829 Returns @code{.TRUE.} if @code{STRING_A <= STRING_B}, and @code{.FALSE.}
6830 otherwise, based on the ASCII ordering.
6832 @item @emph{See also}:
6833 @ref{LGE}, @ref{LGT}, @ref{LLT}
6839 @section @code{LLT} --- Lexical less than
6841 @cindex lexical comparison of strings
6842 @cindex string, comparison
6845 @item @emph{Description}:
6846 Determines whether one string is lexically less than another string,
6847 where the two strings are interpreted as containing ASCII character
6848 codes. If the String A and String B are not the same length, the
6849 shorter is compared as if spaces were appended to it to form a value
6850 that has the same length as the longer.
6852 In general, the lexical comparison intrinsics @code{LGE}, @code{LGT},
6853 @code{LLE}, and @code{LLT} differ from the corresponding intrinsic
6854 operators @code{.GE.}, @code{.GT.}, @code{.LE.}, and @code{.LT.}, in
6855 that the latter use the processor's character ordering (which is not
6856 ASCII on some targets), whereas the former always use the ASCII
6859 @item @emph{Standard}:
6860 Fortran 77 and later
6865 @item @emph{Syntax}:
6866 @code{RESULT = LLT(STRING_A, STRING_B)}
6868 @item @emph{Arguments}:
6869 @multitable @columnfractions .15 .70
6870 @item @var{STRING_A} @tab Shall be of default @code{CHARACTER} type.
6871 @item @var{STRING_B} @tab Shall be of default @code{CHARACTER} type.
6874 @item @emph{Return value}:
6875 Returns @code{.TRUE.} if @code{STRING_A < STRING_B}, and @code{.FALSE.}
6876 otherwise, based on the ASCII ordering.
6878 @item @emph{See also}:
6879 @ref{LGE}, @ref{LGT}, @ref{LLE}
6885 @section @code{LNBLNK} --- Index of the last non-blank character in a string
6887 @cindex string, find non-blank character
6890 @item @emph{Description}:
6891 Returns the length of a character string, ignoring any trailing blanks.
6892 This is identical to the standard @code{LEN_TRIM} intrinsic, and is only
6893 included for backwards compatibility.
6895 @item @emph{Standard}:
6901 @item @emph{Syntax}:
6902 @code{RESULT = LNBLNK(STRING)}
6904 @item @emph{Arguments}:
6905 @multitable @columnfractions .15 .70
6906 @item @var{STRING} @tab Shall be a scalar of type @code{CHARACTER},
6907 with @code{INTENT(IN)}
6910 @item @emph{Return value}:
6911 The return value is of @code{INTEGER(kind=4)} type.
6913 @item @emph{See also}:
6914 @ref{INDEX intrinsic}, @ref{LEN_TRIM}
6920 @section @code{LOC} --- Returns the address of a variable
6922 @cindex location of a variable in memory
6925 @item @emph{Description}:
6926 @code{LOC(X)} returns the address of @var{X} as an integer.
6928 @item @emph{Standard}:
6934 @item @emph{Syntax}:
6935 @code{RESULT = LOC(X)}
6937 @item @emph{Arguments}:
6938 @multitable @columnfractions .15 .70
6939 @item @var{X} @tab Variable of any type.
6942 @item @emph{Return value}:
6943 The return value is of type @code{INTEGER}, with a @code{KIND}
6944 corresponding to the size (in bytes) of a memory address on the target
6947 @item @emph{Example}:
6954 end program test_loc
6961 @section @code{LOG} --- Logarithm function
6968 @cindex exponential function, inverse
6969 @cindex logarithmic function
6972 @item @emph{Description}:
6973 @code{LOG(X)} computes the logarithm of @var{X}.
6975 @item @emph{Standard}:
6976 Fortran 77 and later
6981 @item @emph{Syntax}:
6982 @code{RESULT = LOG(X)}
6984 @item @emph{Arguments}:
6985 @multitable @columnfractions .15 .70
6986 @item @var{X} @tab The type shall be @code{REAL} or
6990 @item @emph{Return value}:
6991 The return value is of type @code{REAL} or @code{COMPLEX}.
6992 The kind type parameter is the same as @var{X}.
6993 If @var{X} is @code{COMPLEX}, the imaginary part @math{\omega} is in the range
6994 @math{-\pi \leq \omega \leq \pi}.
6996 @item @emph{Example}:
6999 real(8) :: x = 1.0_8
7000 complex :: z = (1.0, 2.0)
7003 end program test_log
7006 @item @emph{Specific names}:
7007 @multitable @columnfractions .20 .20 .20 .25
7008 @item Name @tab Argument @tab Return type @tab Standard
7009 @item @code{ALOG(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab f95, gnu
7010 @item @code{DLOG(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab f95, gnu
7011 @item @code{CLOG(X)} @tab @code{COMPLEX(4) X} @tab @code{COMPLEX(4)} @tab f95, gnu
7012 @item @code{ZLOG(X)} @tab @code{COMPLEX(8) X} @tab @code{COMPLEX(8)} @tab f95, gnu
7013 @item @code{CDLOG(X)} @tab @code{COMPLEX(8) X} @tab @code{COMPLEX(8)} @tab f95, gnu
7020 @section @code{LOG10} --- Base 10 logarithm function
7024 @cindex exponential function, inverse
7025 @cindex logarithmic function
7028 @item @emph{Description}:
7029 @code{LOG10(X)} computes the base 10 logarithm of @var{X}.
7031 @item @emph{Standard}:
7032 Fortran 77 and later
7037 @item @emph{Syntax}:
7038 @code{RESULT = LOG10(X)}
7040 @item @emph{Arguments}:
7041 @multitable @columnfractions .15 .70
7042 @item @var{X} @tab The type shall be @code{REAL}.
7045 @item @emph{Return value}:
7046 The return value is of type @code{REAL} or @code{COMPLEX}.
7047 The kind type parameter is the same as @var{X}.
7049 @item @emph{Example}:
7052 real(8) :: x = 10.0_8
7054 end program test_log10
7057 @item @emph{Specific names}:
7058 @multitable @columnfractions .20 .20 .20 .25
7059 @item Name @tab Argument @tab Return type @tab Standard
7060 @item @code{ALOG10(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab Fortran 95 and later
7061 @item @code{DLOG10(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab Fortran 95 and later
7068 @section @code{LOG_GAMMA} --- Logarithm of the Gamma function
7073 @cindex Gamma function, logarithm of
7076 @item @emph{Description}:
7077 @code{LOG_GAMMA(X)} computes the natural logarithm of the absolute value
7078 of the Gamma (@math{\Gamma}) function.
7080 @item @emph{Standard}:
7081 Fortran 2008 and later
7086 @item @emph{Syntax}:
7087 @code{X = LOG_GAMMA(X)}
7089 @item @emph{Arguments}:
7090 @multitable @columnfractions .15 .70
7091 @item @var{X} @tab Shall be of type @code{REAL} and neither zero
7092 nor a negative integer.
7095 @item @emph{Return value}:
7096 The return value is of type @code{REAL} of the same kind as @var{X}.
7098 @item @emph{Example}:
7100 program test_log_gamma
7102 x = lgamma(x) ! returns 0.0
7103 end program test_log_gamma
7106 @item @emph{Specific names}:
7107 @multitable @columnfractions .20 .20 .20 .25
7108 @item Name @tab Argument @tab Return type @tab Standard
7109 @item @code{LGAMMA(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab GNU Extension
7110 @item @code{ALGAMA(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab GNU Extension
7111 @item @code{DLGAMA(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU Extension
7114 @item @emph{See also}:
7115 Gamma function: @ref{GAMMA}
7122 @section @code{LOGICAL} --- Convert to logical type
7124 @cindex conversion, to logical
7127 @item @emph{Description}:
7128 Converts one kind of @code{LOGICAL} variable to another.
7130 @item @emph{Standard}:
7131 Fortran 95 and later
7136 @item @emph{Syntax}:
7137 @code{RESULT = LOGICAL(L [, KIND])}
7139 @item @emph{Arguments}:
7140 @multitable @columnfractions .15 .70
7141 @item @var{L} @tab The type shall be @code{LOGICAL}.
7142 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
7143 expression indicating the kind parameter of the result.
7146 @item @emph{Return value}:
7147 The return value is a @code{LOGICAL} value equal to @var{L}, with a
7148 kind corresponding to @var{KIND}, or of the default logical kind if
7149 @var{KIND} is not given.
7151 @item @emph{See also}:
7152 @ref{INT}, @ref{REAL}, @ref{CMPLX}
7158 @section @code{LONG} --- Convert to integer type
7160 @cindex conversion, to integer
7163 @item @emph{Description}:
7164 Convert to a @code{KIND=4} integer type, which is the same size as a C
7165 @code{long} integer. This is equivalent to the standard @code{INT}
7166 intrinsic with an optional argument of @code{KIND=4}, and is only
7167 included for backwards compatibility.
7169 @item @emph{Standard}:
7175 @item @emph{Syntax}:
7176 @code{RESULT = LONG(A)}
7178 @item @emph{Arguments}:
7179 @multitable @columnfractions .15 .70
7180 @item @var{A} @tab Shall be of type @code{INTEGER},
7181 @code{REAL}, or @code{COMPLEX}.
7184 @item @emph{Return value}:
7185 The return value is a @code{INTEGER(4)} variable.
7187 @item @emph{See also}:
7188 @ref{INT}, @ref{INT2}, @ref{INT8}
7194 @section @code{LSHIFT} --- Left shift bits
7196 @cindex bits, shift left
7199 @item @emph{Description}:
7200 @code{LSHIFT} returns a value corresponding to @var{I} with all of the
7201 bits shifted left by @var{SHIFT} places. If the absolute value of
7202 @var{SHIFT} is greater than @code{BIT_SIZE(I)}, the value is undefined.
7203 Bits shifted out from the left end are lost; zeros are shifted in from
7206 This function has been superseded by the @code{ISHFT} intrinsic, which
7207 is standard in Fortran 95 and later.
7209 @item @emph{Standard}:
7215 @item @emph{Syntax}:
7216 @code{RESULT = LSHIFT(I, SHIFT)}
7218 @item @emph{Arguments}:
7219 @multitable @columnfractions .15 .70
7220 @item @var{I} @tab The type shall be @code{INTEGER}.
7221 @item @var{SHIFT} @tab The type shall be @code{INTEGER}.
7224 @item @emph{Return value}:
7225 The return value is of type @code{INTEGER} and of the same kind as
7228 @item @emph{See also}:
7229 @ref{ISHFT}, @ref{ISHFTC}, @ref{RSHIFT}
7236 @section @code{LSTAT} --- Get file status
7238 @cindex file system, file status
7241 @item @emph{Description}:
7242 @code{LSTAT} is identical to @ref{STAT}, except that if path is a
7243 symbolic link, then the link itself is statted, not the file that it
7246 The elements in @code{VALUES} are the same as described by @ref{STAT}.
7248 This intrinsic is provided in both subroutine and function forms;
7249 however, only one form can be used in any given program unit.
7251 @item @emph{Standard}:
7255 Subroutine, function
7257 @item @emph{Syntax}:
7258 @code{CALL LSTAT(NAME, VALUES [, STATUS])}
7260 @item @emph{Arguments}:
7261 @multitable @columnfractions .15 .70
7262 @item @var{NAME} @tab The type shall be @code{CHARACTER} of the default
7263 kind, a valid path within the file system.
7264 @item @var{VALUES} @tab The type shall be @code{INTEGER(4), DIMENSION(13)}.
7265 @item @var{STATUS} @tab (Optional) status flag of type @code{INTEGER(4)}.
7266 Returns 0 on success and a system specific error code otherwise.
7269 @item @emph{Example}:
7270 See @ref{STAT} for an example.
7272 @item @emph{See also}:
7273 To stat an open file: @ref{FSTAT}, to stat a file: @ref{STAT}
7279 @section @code{LTIME} --- Convert time to local time info
7281 @cindex time, conversion to local time info
7284 @item @emph{Description}:
7285 Given a system time value @var{TIME} (as provided by the @code{TIME8()}
7286 intrinsic), fills @var{VALUES} with values extracted from it appropriate
7287 to the local time zone using @code{localtime(3)}.
7289 @item @emph{Standard}:
7295 @item @emph{Syntax}:
7296 @code{CALL LTIME(TIME, VALUES)}
7298 @item @emph{Arguments}:
7299 @multitable @columnfractions .15 .70
7300 @item @var{TIME} @tab An @code{INTEGER} scalar expression
7301 corresponding to a system time, with @code{INTENT(IN)}.
7302 @item @var{VALUES} @tab A default @code{INTEGER} array with 9 elements,
7303 with @code{INTENT(OUT)}.
7306 @item @emph{Return value}:
7307 The elements of @var{VALUES} are assigned as follows:
7309 @item Seconds after the minute, range 0--59 or 0--61 to allow for leap
7311 @item Minutes after the hour, range 0--59
7312 @item Hours past midnight, range 0--23
7313 @item Day of month, range 0--31
7314 @item Number of months since January, range 0--12
7315 @item Years since 1900
7316 @item Number of days since Sunday, range 0--6
7317 @item Days since January 1
7318 @item Daylight savings indicator: positive if daylight savings is in
7319 effect, zero if not, and negative if the information is not available.
7322 @item @emph{See also}:
7323 @ref{CTIME}, @ref{GMTIME}, @ref{TIME}, @ref{TIME8}
7330 @section @code{MALLOC} --- Allocate dynamic memory
7332 @cindex pointer, cray
7335 @item @emph{Description}:
7336 @code{MALLOC(SIZE)} allocates @var{SIZE} bytes of dynamic memory and
7337 returns the address of the allocated memory. The @code{MALLOC} intrinsic
7338 is an extension intended to be used with Cray pointers, and is provided
7339 in GNU Fortran to allow the user to compile legacy code. For new code
7340 using Fortran 95 pointers, the memory allocation intrinsic is
7343 @item @emph{Standard}:
7349 @item @emph{Syntax}:
7350 @code{PTR = MALLOC(SIZE)}
7352 @item @emph{Arguments}:
7353 @multitable @columnfractions .15 .70
7354 @item @var{SIZE} @tab The type shall be @code{INTEGER}.
7357 @item @emph{Return value}:
7358 The return value is of type @code{INTEGER(K)}, with @var{K} such that
7359 variables of type @code{INTEGER(K)} have the same size as
7360 C pointers (@code{sizeof(void *)}).
7362 @item @emph{Example}:
7363 The following example demonstrates the use of @code{MALLOC} and
7364 @code{FREE} with Cray pointers.
7373 ptr_x = malloc(20*8)
7375 x(i) = sqrt(1.0d0 / i)
7383 end program test_malloc
7386 @item @emph{See also}:
7393 @section @code{MATMUL} --- matrix multiplication
7395 @cindex matrix multiplication
7396 @cindex product, matrix
7399 @item @emph{Description}:
7400 Performs a matrix multiplication on numeric or logical arguments.
7402 @item @emph{Standard}:
7403 Fortran 95 and later
7406 Transformational function
7408 @item @emph{Syntax}:
7409 @code{RESULT = MATMUL(MATRIX_A, MATRIX_B)}
7411 @item @emph{Arguments}:
7412 @multitable @columnfractions .15 .70
7413 @item @var{MATRIX_A} @tab An array of @code{INTEGER},
7414 @code{REAL}, @code{COMPLEX}, or @code{LOGICAL} type, with a rank of
7416 @item @var{MATRIX_B} @tab An array of @code{INTEGER},
7417 @code{REAL}, or @code{COMPLEX} type if @var{MATRIX_A} is of a numeric
7418 type; otherwise, an array of @code{LOGICAL} type. The rank shall be one
7419 or two, and the first (or only) dimension of @var{MATRIX_B} shall be
7420 equal to the last (or only) dimension of @var{MATRIX_A}.
7423 @item @emph{Return value}:
7424 The matrix product of @var{MATRIX_A} and @var{MATRIX_B}. The type and
7425 kind of the result follow the usual type and kind promotion rules, as
7426 for the @code{*} or @code{.AND.} operators.
7428 @item @emph{See also}:
7434 @section @code{MAX} --- Maximum value of an argument list
7441 @cindex maximum value
7444 @item @emph{Description}:
7445 Returns the argument with the largest (most positive) value.
7447 @item @emph{Standard}:
7448 Fortran 77 and later
7453 @item @emph{Syntax}:
7454 @code{RESULT = MAX(A1, A2 [, A3 [, ...]])}
7456 @item @emph{Arguments}:
7457 @multitable @columnfractions .15 .70
7458 @item @var{A1} @tab The type shall be @code{INTEGER} or
7460 @item @var{A2}, @var{A3}, ... @tab An expression of the same type and kind
7461 as @var{A1}. (As a GNU extension, arguments of different kinds are
7465 @item @emph{Return value}:
7466 The return value corresponds to the maximum value among the arguments,
7467 and has the same type and kind as the first argument.
7469 @item @emph{Specific names}:
7470 @multitable @columnfractions .20 .20 .20 .25
7471 @item Name @tab Argument @tab Return type @tab Standard
7472 @item @code{MAX0(I)} @tab @code{INTEGER(4) I} @tab @code{INTEGER(4)} @tab Fortran 77 and later
7473 @item @code{AMAX0(I)} @tab @code{INTEGER(4) I} @tab @code{REAL(MAX(X))} @tab Fortran 77 and later
7474 @item @code{MAX1(X)} @tab @code{REAL X} @tab @code{INT(MAX(X))} @tab Fortran 77 and later
7475 @item @code{AMAX1(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab Fortran 77 and later
7476 @item @code{DMAX1(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab Fortran 77 and later
7479 @item @emph{See also}:
7480 @ref{MAXLOC} @ref{MAXVAL}, @ref{MIN}
7487 @section @code{MAXEXPONENT} --- Maximum exponent of a real kind
7488 @fnindex MAXEXPONENT
7489 @cindex model representation, maximum exponent
7492 @item @emph{Description}:
7493 @code{MAXEXPONENT(X)} returns the maximum exponent in the model of the
7496 @item @emph{Standard}:
7497 Fortran 95 and later
7502 @item @emph{Syntax}:
7503 @code{RESULT = MAXEXPONENT(X)}
7505 @item @emph{Arguments}:
7506 @multitable @columnfractions .15 .70
7507 @item @var{X} @tab Shall be of type @code{REAL}.
7510 @item @emph{Return value}:
7511 The return value is of type @code{INTEGER} and of the default integer
7514 @item @emph{Example}:
7520 print *, minexponent(x), maxexponent(x)
7521 print *, minexponent(y), maxexponent(y)
7522 end program exponents
7529 @section @code{MAXLOC} --- Location of the maximum value within an array
7531 @cindex array, location of maximum element
7534 @item @emph{Description}:
7535 Determines the location of the element in the array with the maximum
7536 value, or, if the @var{DIM} argument is supplied, determines the
7537 locations of the maximum element along each row of the array in the
7538 @var{DIM} direction. If @var{MASK} is present, only the elements for
7539 which @var{MASK} is @code{.TRUE.} are considered. If more than one
7540 element in the array has the maximum value, the location returned is
7541 that of the first such element in array element order. If the array has
7542 zero size, or all of the elements of @var{MASK} are @code{.FALSE.}, then
7543 the result is an array of zeroes. Similarly, if @var{DIM} is supplied
7544 and all of the elements of @var{MASK} along a given row are zero, the
7545 result value for that row is zero.
7547 @item @emph{Standard}:
7548 Fortran 95 and later
7551 Transformational function
7553 @item @emph{Syntax}:
7554 @multitable @columnfractions .80
7555 @item @code{RESULT = MAXLOC(ARRAY, DIM [, MASK])}
7556 @item @code{RESULT = MAXLOC(ARRAY [, MASK])}
7559 @item @emph{Arguments}:
7560 @multitable @columnfractions .15 .70
7561 @item @var{ARRAY} @tab Shall be an array of type @code{INTEGER},
7562 @code{REAL}, or @code{CHARACTER}.
7563 @item @var{DIM} @tab (Optional) Shall be a scalar of type
7564 @code{INTEGER}, with a value between one and the rank of @var{ARRAY},
7565 inclusive. It may not be an optional dummy argument.
7566 @item @var{MASK} @tab Shall be an array of type @code{LOGICAL},
7567 and conformable with @var{ARRAY}.
7570 @item @emph{Return value}:
7571 If @var{DIM} is absent, the result is a rank-one array with a length
7572 equal to the rank of @var{ARRAY}. If @var{DIM} is present, the result
7573 is an array with a rank one less than the rank of @var{ARRAY}, and a
7574 size corresponding to the size of @var{ARRAY} with the @var{DIM}
7575 dimension removed. If @var{DIM} is present and @var{ARRAY} has a rank
7576 of one, the result is a scalar. In all cases, the result is of default
7577 @code{INTEGER} type.
7579 @item @emph{See also}:
7580 @ref{MAX}, @ref{MAXVAL}
7587 @section @code{MAXVAL} --- Maximum value of an array
7589 @cindex array, maximum value
7590 @cindex maximum value
7593 @item @emph{Description}:
7594 Determines the maximum value of the elements in an array value, or, if
7595 the @var{DIM} argument is supplied, determines the maximum value along
7596 each row of the array in the @var{DIM} direction. If @var{MASK} is
7597 present, only the elements for which @var{MASK} is @code{.TRUE.} are
7598 considered. If the array has zero size, or all of the elements of
7599 @var{MASK} are @code{.FALSE.}, then the result is @code{-HUGE(ARRAY)}
7600 if @var{ARRAY} is numeric, or a string of nulls if @var{ARRAY} is of character
7603 @item @emph{Standard}:
7604 Fortran 95 and later
7607 Transformational function
7609 @item @emph{Syntax}:
7610 @multitable @columnfractions .80
7611 @item @code{RESULT = MAXVAL(ARRAY, DIM [, MASK])}
7612 @item @code{RESULT = MAXVAL(ARRAY [, MASK])}
7615 @item @emph{Arguments}:
7616 @multitable @columnfractions .15 .70
7617 @item @var{ARRAY} @tab Shall be an array of type @code{INTEGER},
7618 @code{REAL}, or @code{CHARACTER}.
7619 @item @var{DIM} @tab (Optional) Shall be a scalar of type
7620 @code{INTEGER}, with a value between one and the rank of @var{ARRAY},
7621 inclusive. It may not be an optional dummy argument.
7622 @item @var{MASK} @tab Shall be an array of type @code{LOGICAL},
7623 and conformable with @var{ARRAY}.
7626 @item @emph{Return value}:
7627 If @var{DIM} is absent, or if @var{ARRAY} has a rank of one, the result
7628 is a scalar. If @var{DIM} is present, the result is an array with a
7629 rank one less than the rank of @var{ARRAY}, and a size corresponding to
7630 the size of @var{ARRAY} with the @var{DIM} dimension removed. In all
7631 cases, the result is of the same type and kind as @var{ARRAY}.
7633 @item @emph{See also}:
7634 @ref{MAX}, @ref{MAXLOC}
7640 @section @code{MCLOCK} --- Time function
7642 @cindex time, clock ticks
7646 @item @emph{Description}:
7647 Returns the number of clock ticks since the start of the process, based
7648 on the UNIX function @code{clock(3)}.
7650 This intrinsic is not fully portable, such as to systems with 32-bit
7651 @code{INTEGER} types but supporting times wider than 32 bits. Therefore,
7652 the values returned by this intrinsic might be, or become, negative, or
7653 numerically less than previous values, during a single run of the
7656 @item @emph{Standard}:
7662 @item @emph{Syntax}:
7663 @code{RESULT = MCLOCK()}
7665 @item @emph{Return value}:
7666 The return value is a scalar of type @code{INTEGER(4)}, equal to the
7667 number of clock ticks since the start of the process, or @code{-1} if
7668 the system does not support @code{clock(3)}.
7670 @item @emph{See also}:
7671 @ref{CTIME}, @ref{GMTIME}, @ref{LTIME}, @ref{MCLOCK}, @ref{TIME}
7678 @section @code{MCLOCK8} --- Time function (64-bit)
7680 @cindex time, clock ticks
7684 @item @emph{Description}:
7685 Returns the number of clock ticks since the start of the process, based
7686 on the UNIX function @code{clock(3)}.
7688 @emph{Warning:} this intrinsic does not increase the range of the timing
7689 values over that returned by @code{clock(3)}. On a system with a 32-bit
7690 @code{clock(3)}, @code{MCLOCK8()} will return a 32-bit value, even though
7691 it is converted to a 64-bit @code{INTEGER(8)} value. That means
7692 overflows of the 32-bit value can still occur. Therefore, the values
7693 returned by this intrinsic might be or become negative or numerically
7694 less than previous values during a single run of the compiled program.
7696 @item @emph{Standard}:
7702 @item @emph{Syntax}:
7703 @code{RESULT = MCLOCK8()}
7705 @item @emph{Return value}:
7706 The return value is a scalar of type @code{INTEGER(8)}, equal to the
7707 number of clock ticks since the start of the process, or @code{-1} if
7708 the system does not support @code{clock(3)}.
7710 @item @emph{See also}:
7711 @ref{CTIME}, @ref{GMTIME}, @ref{LTIME}, @ref{MCLOCK}, @ref{TIME8}
7718 @section @code{MERGE} --- Merge variables
7720 @cindex array, merge arrays
7721 @cindex array, combine arrays
7724 @item @emph{Description}:
7725 Select values from two arrays according to a logical mask. The result
7726 is equal to @var{TSOURCE} if @var{MASK} is @code{.TRUE.}, or equal to
7727 @var{FSOURCE} if it is @code{.FALSE.}.
7729 @item @emph{Standard}:
7730 Fortran 95 and later
7735 @item @emph{Syntax}:
7736 @code{RESULT = MERGE(TSOURCE, FSOURCE, MASK)}
7738 @item @emph{Arguments}:
7739 @multitable @columnfractions .15 .70
7740 @item @var{TSOURCE} @tab May be of any type.
7741 @item @var{FSOURCE} @tab Shall be of the same type and type parameters
7743 @item @var{MASK} @tab Shall be of type @code{LOGICAL}.
7746 @item @emph{Return value}:
7747 The result is of the same type and type parameters as @var{TSOURCE}.
7754 @section @code{MIN} --- Minimum value of an argument list
7761 @cindex minimum value
7764 @item @emph{Description}:
7765 Returns the argument with the smallest (most negative) value.
7767 @item @emph{Standard}:
7768 Fortran 77 and later
7773 @item @emph{Syntax}:
7774 @code{RESULT = MIN(A1, A2 [, A3, ...])}
7776 @item @emph{Arguments}:
7777 @multitable @columnfractions .15 .70
7778 @item @var{A1} @tab The type shall be @code{INTEGER} or
7780 @item @var{A2}, @var{A3}, ... @tab An expression of the same type and kind
7781 as @var{A1}. (As a GNU extension, arguments of different kinds are
7785 @item @emph{Return value}:
7786 The return value corresponds to the maximum value among the arguments,
7787 and has the same type and kind as the first argument.
7789 @item @emph{Specific names}:
7790 @multitable @columnfractions .20 .20 .20 .25
7791 @item Name @tab Argument @tab Return type @tab Standard
7792 @item @code{MIN0(I)} @tab @code{INTEGER(4) I} @tab @code{INTEGER(4)} @tab Fortran 77 and later
7793 @item @code{AMIN0(I)} @tab @code{INTEGER(4) I} @tab @code{REAL(MIN(X))} @tab Fortran 77 and later
7794 @item @code{MIN1(X)} @tab @code{REAL X} @tab @code{INT(MIN(X))} @tab Fortran 77 and later
7795 @item @code{AMIN1(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab Fortran 77 and later
7796 @item @code{DMIN1(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab Fortran 77 and later
7799 @item @emph{See also}:
7800 @ref{MAX}, @ref{MINLOC}, @ref{MINVAL}
7806 @section @code{MINEXPONENT} --- Minimum exponent of a real kind
7807 @fnindex MINEXPONENT
7808 @cindex model representation, minimum exponent
7811 @item @emph{Description}:
7812 @code{MINEXPONENT(X)} returns the minimum exponent in the model of the
7815 @item @emph{Standard}:
7816 Fortran 95 and later
7821 @item @emph{Syntax}:
7822 @code{RESULT = MINEXPONENT(X)}
7824 @item @emph{Arguments}:
7825 @multitable @columnfractions .15 .70
7826 @item @var{X} @tab Shall be of type @code{REAL}.
7829 @item @emph{Return value}:
7830 The return value is of type @code{INTEGER} and of the default integer
7833 @item @emph{Example}:
7834 See @code{MAXEXPONENT} for an example.
7840 @section @code{MINLOC} --- Location of the minimum value within an array
7842 @cindex array, location of minimum element
7845 @item @emph{Description}:
7846 Determines the location of the element in the array with the minimum
7847 value, or, if the @var{DIM} argument is supplied, determines the
7848 locations of the minimum element along each row of the array in the
7849 @var{DIM} direction. If @var{MASK} is present, only the elements for
7850 which @var{MASK} is @code{.TRUE.} are considered. If more than one
7851 element in the array has the minimum value, the location returned is
7852 that of the first such element in array element order. If the array has
7853 zero size, or all of the elements of @var{MASK} are @code{.FALSE.}, then
7854 the result is an array of zeroes. Similarly, if @var{DIM} is supplied
7855 and all of the elements of @var{MASK} along a given row are zero, the
7856 result value for that row is zero.
7858 @item @emph{Standard}:
7859 Fortran 95 and later
7862 Transformational function
7864 @item @emph{Syntax}:
7865 @multitable @columnfractions .80
7866 @item @code{RESULT = MINLOC(ARRAY, DIM [, MASK])}
7867 @item @code{RESULT = MINLOC(ARRAY [, MASK])}
7870 @item @emph{Arguments}:
7871 @multitable @columnfractions .15 .70
7872 @item @var{ARRAY} @tab Shall be an array of type @code{INTEGER},
7873 @code{REAL}, or @code{CHARACTER}.
7874 @item @var{DIM} @tab (Optional) Shall be a scalar of type
7875 @code{INTEGER}, with a value between one and the rank of @var{ARRAY},
7876 inclusive. It may not be an optional dummy argument.
7877 @item @var{MASK} @tab Shall be an array of type @code{LOGICAL},
7878 and conformable with @var{ARRAY}.
7881 @item @emph{Return value}:
7882 If @var{DIM} is absent, the result is a rank-one array with a length
7883 equal to the rank of @var{ARRAY}. If @var{DIM} is present, the result
7884 is an array with a rank one less than the rank of @var{ARRAY}, and a
7885 size corresponding to the size of @var{ARRAY} with the @var{DIM}
7886 dimension removed. If @var{DIM} is present and @var{ARRAY} has a rank
7887 of one, the result is a scalar. In all cases, the result is of default
7888 @code{INTEGER} type.
7890 @item @emph{See also}:
7891 @ref{MIN}, @ref{MINVAL}
7898 @section @code{MINVAL} --- Minimum value of an array
7900 @cindex array, minimum value
7901 @cindex minimum value
7904 @item @emph{Description}:
7905 Determines the minimum value of the elements in an array value, or, if
7906 the @var{DIM} argument is supplied, determines the minimum value along
7907 each row of the array in the @var{DIM} direction. If @var{MASK} is
7908 present, only the elements for which @var{MASK} is @code{.TRUE.} are
7909 considered. If the array has zero size, or all of the elements of
7910 @var{MASK} are @code{.FALSE.}, then the result is @code{HUGE(ARRAY)} if
7911 @var{ARRAY} is numeric, or a string of @code{CHAR(255)} characters if
7912 @var{ARRAY} is of character type.
7914 @item @emph{Standard}:
7915 Fortran 95 and later
7918 Transformational function
7920 @item @emph{Syntax}:
7921 @multitable @columnfractions .80
7922 @item @code{RESULT = MINVAL(ARRAY, DIM [, MASK])}
7923 @item @code{RESULT = MINVAL(ARRAY [, MASK])}
7926 @item @emph{Arguments}:
7927 @multitable @columnfractions .15 .70
7928 @item @var{ARRAY} @tab Shall be an array of type @code{INTEGER},
7929 @code{REAL}, or @code{CHARACTER}.
7930 @item @var{DIM} @tab (Optional) Shall be a scalar of type
7931 @code{INTEGER}, with a value between one and the rank of @var{ARRAY},
7932 inclusive. It may not be an optional dummy argument.
7933 @item @var{MASK} @tab Shall be an array of type @code{LOGICAL},
7934 and conformable with @var{ARRAY}.
7937 @item @emph{Return value}:
7938 If @var{DIM} is absent, or if @var{ARRAY} has a rank of one, the result
7939 is a scalar. If @var{DIM} is present, the result is an array with a
7940 rank one less than the rank of @var{ARRAY}, and a size corresponding to
7941 the size of @var{ARRAY} with the @var{DIM} dimension removed. In all
7942 cases, the result is of the same type and kind as @var{ARRAY}.
7944 @item @emph{See also}:
7945 @ref{MIN}, @ref{MINLOC}
7952 @section @code{MOD} --- Remainder function
7957 @cindex division, remainder
7960 @item @emph{Description}:
7961 @code{MOD(A,P)} computes the remainder of the division of A by P@. It is
7962 calculated as @code{A - (INT(A/P) * P)}.
7964 @item @emph{Standard}:
7965 Fortran 77 and later
7970 @item @emph{Syntax}:
7971 @code{RESULT = MOD(A, P)}
7973 @item @emph{Arguments}:
7974 @multitable @columnfractions .15 .70
7975 @item @var{A} @tab Shall be a scalar of type @code{INTEGER} or @code{REAL}
7976 @item @var{P} @tab Shall be a scalar of the same type as @var{A} and not
7980 @item @emph{Return value}:
7981 The kind of the return value is the result of cross-promoting
7982 the kinds of the arguments.
7984 @item @emph{Example}:
7988 print *, mod(17.5,5.5)
7989 print *, mod(17.5d0,5.5)
7990 print *, mod(17.5,5.5d0)
7993 print *, mod(-17.5,5.5)
7994 print *, mod(-17.5d0,5.5)
7995 print *, mod(-17.5,5.5d0)
7998 print *, mod(17.5,-5.5)
7999 print *, mod(17.5d0,-5.5)
8000 print *, mod(17.5,-5.5d0)
8001 end program test_mod
8004 @item @emph{Specific names}:
8005 @multitable @columnfractions .20 .20 .20 .25
8006 @item Name @tab Arguments @tab Return type @tab Standard
8007 @item @code{AMOD(A,P)} @tab @code{REAL(4)} @tab @code{REAL(4)} @tab Fortran 95 and later
8008 @item @code{DMOD(A,P)} @tab @code{REAL(8)} @tab @code{REAL(8)} @tab Fortran 95 and later
8015 @section @code{MODULO} --- Modulo function
8018 @cindex division, modulo
8021 @item @emph{Description}:
8022 @code{MODULO(A,P)} computes the @var{A} modulo @var{P}.
8024 @item @emph{Standard}:
8025 Fortran 95 and later
8030 @item @emph{Syntax}:
8031 @code{RESULT = MODULO(A, P)}
8033 @item @emph{Arguments}:
8034 @multitable @columnfractions .15 .70
8035 @item @var{A} @tab Shall be a scalar of type @code{INTEGER} or @code{REAL}
8036 @item @var{P} @tab Shall be a scalar of the same type and kind as @var{A}
8039 @item @emph{Return value}:
8040 The type and kind of the result are those of the arguments.
8042 @item If @var{A} and @var{P} are of type @code{INTEGER}:
8043 @code{MODULO(A,P)} has the value @var{R} such that @code{A=Q*P+R}, where
8044 @var{Q} is an integer and @var{R} is between 0 (inclusive) and @var{P}
8046 @item If @var{A} and @var{P} are of type @code{REAL}:
8047 @code{MODULO(A,P)} has the value of @code{A - FLOOR (A / P) * P}.
8049 In all cases, if @var{P} is zero the result is processor-dependent.
8051 @item @emph{Example}:
8054 print *, modulo(17,3)
8055 print *, modulo(17.5,5.5)
8057 print *, modulo(-17,3)
8058 print *, modulo(-17.5,5.5)
8060 print *, modulo(17,-3)
8061 print *, modulo(17.5,-5.5)
8070 @section @code{MOVE_ALLOC} --- Move allocation from one object to another
8072 @cindex moving allocation
8073 @cindex allocation, moving
8076 @item @emph{Description}:
8077 @code{MOVE_ALLOC(FROM, TO)} moves the allocation from @var{FROM} to
8078 @var{TO}. @var{FROM} will become deallocated in the process.
8080 @item @emph{Standard}:
8081 Fortran 2003 and later
8086 @item @emph{Syntax}:
8087 @code{CALL MOVE_ALLOC(FROM, TO)}
8089 @item @emph{Arguments}:
8090 @multitable @columnfractions .15 .70
8091 @item @var{FROM} @tab @code{ALLOCATABLE}, @code{INTENT(INOUT)}, may be
8092 of any type and kind.
8093 @item @var{TO} @tab @code{ALLOCATABLE}, @code{INTENT(OUT)}, shall be
8094 of the same type, kind and rank as @var{FROM}.
8097 @item @emph{Return value}:
8100 @item @emph{Example}:
8102 program test_move_alloc
8103 integer, allocatable :: a(:), b(:)
8107 call move_alloc(a, b)
8108 print *, allocated(a), allocated(b)
8110 end program test_move_alloc
8117 @section @code{MVBITS} --- Move bits from one integer to another
8122 @item @emph{Description}:
8123 Moves @var{LEN} bits from positions @var{FROMPOS} through
8124 @code{FROMPOS+LEN-1} of @var{FROM} to positions @var{TOPOS} through
8125 @code{TOPOS+LEN-1} of @var{TO}. The portion of argument @var{TO} not
8126 affected by the movement of bits is unchanged. The values of
8127 @code{FROMPOS+LEN-1} and @code{TOPOS+LEN-1} must be less than
8128 @code{BIT_SIZE(FROM)}.
8130 @item @emph{Standard}:
8131 Fortran 95 and later
8134 Elemental subroutine
8136 @item @emph{Syntax}:
8137 @code{CALL MVBITS(FROM, FROMPOS, LEN, TO, TOPOS)}
8139 @item @emph{Arguments}:
8140 @multitable @columnfractions .15 .70
8141 @item @var{FROM} @tab The type shall be @code{INTEGER}.
8142 @item @var{FROMPOS} @tab The type shall be @code{INTEGER}.
8143 @item @var{LEN} @tab The type shall be @code{INTEGER}.
8144 @item @var{TO} @tab The type shall be @code{INTEGER}, of the
8145 same kind as @var{FROM}.
8146 @item @var{TOPOS} @tab The type shall be @code{INTEGER}.
8149 @item @emph{See also}:
8150 @ref{IBCLR}, @ref{IBSET}, @ref{IBITS}, @ref{IAND}, @ref{IOR}, @ref{IEOR}
8156 @section @code{NEAREST} --- Nearest representable number
8158 @cindex real number, nearest different
8159 @cindex floating point, nearest different
8162 @item @emph{Description}:
8163 @code{NEAREST(X, S)} returns the processor-representable number nearest
8164 to @code{X} in the direction indicated by the sign of @code{S}.
8166 @item @emph{Standard}:
8167 Fortran 95 and later
8172 @item @emph{Syntax}:
8173 @code{RESULT = NEAREST(X, S)}
8175 @item @emph{Arguments}:
8176 @multitable @columnfractions .15 .70
8177 @item @var{X} @tab Shall be of type @code{REAL}.
8178 @item @var{S} @tab (Optional) shall be of type @code{REAL} and
8182 @item @emph{Return value}:
8183 The return value is of the same type as @code{X}. If @code{S} is
8184 positive, @code{NEAREST} returns the processor-representable number
8185 greater than @code{X} and nearest to it. If @code{S} is negative,
8186 @code{NEAREST} returns the processor-representable number smaller than
8187 @code{X} and nearest to it.
8189 @item @emph{Example}:
8191 program test_nearest
8193 x = nearest(42.0, 1.0)
8194 y = nearest(42.0, -1.0)
8195 write (*,"(3(G20.15))") x, y, x - y
8196 end program test_nearest
8203 @section @code{NEW_LINE} --- New line character
8206 @cindex output, newline
8209 @item @emph{Description}:
8210 @code{NEW_LINE(C)} returns the new-line character.
8212 @item @emph{Standard}:
8213 Fortran 2003 and later
8218 @item @emph{Syntax}:
8219 @code{RESULT = NEW_LINE(C)}
8221 @item @emph{Arguments}:
8222 @multitable @columnfractions .15 .70
8223 @item @var{C} @tab The argument shall be a scalar or array of the
8224 type @code{CHARACTER}.
8227 @item @emph{Return value}:
8228 Returns a @var{CHARACTER} scalar of length one with the new-line character of
8229 the same kind as parameter @var{C}.
8231 @item @emph{Example}:
8235 write(*,'(A)') 'This is record 1.'//NEW_LINE('A')//'This is record 2.'
8243 @section @code{NINT} --- Nearest whole number
8246 @cindex rounding, nearest whole number
8249 @item @emph{Description}:
8250 @code{NINT(A)} rounds its argument to the nearest whole number.
8252 @item @emph{Standard}:
8253 Fortran 77 and later, with @var{KIND} argument Fortran 90 and later
8258 @item @emph{Syntax}:
8259 @code{RESULT = NINT(A [, KIND])}
8261 @item @emph{Arguments}:
8262 @multitable @columnfractions .15 .70
8263 @item @var{A} @tab The type of the argument shall be @code{REAL}.
8264 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
8265 expression indicating the kind parameter of the result.
8268 @item @emph{Return value}:
8269 Returns @var{A} with the fractional portion of its magnitude eliminated by
8270 rounding to the nearest whole number and with its sign preserved,
8271 converted to an @code{INTEGER} of the default kind.
8273 @item @emph{Example}:
8280 print *, nint(x4), idnint(x8)
8281 end program test_nint
8284 @item @emph{Specific names}:
8285 @multitable @columnfractions .25 .25 .25
8286 @item Name @tab Argument @tab Standard
8287 @item @code{IDNINT(X)} @tab @code{REAL(8)} @tab Fortran 95 and later
8290 @item @emph{See also}:
8291 @ref{CEILING}, @ref{FLOOR}
8298 @section @code{NOT} --- Logical negation
8300 @cindex bits, negate
8301 @cindex bitwise logical not
8302 @cindex logical not, bitwise
8305 @item @emph{Description}:
8306 @code{NOT} returns the bitwise boolean inverse of @var{I}.
8308 @item @emph{Standard}:
8309 Fortran 95 and later
8314 @item @emph{Syntax}:
8315 @code{RESULT = NOT(I)}
8317 @item @emph{Arguments}:
8318 @multitable @columnfractions .15 .70
8319 @item @var{I} @tab The type shall be @code{INTEGER}.
8322 @item @emph{Return value}:
8323 The return type is @code{INTEGER}, of the same kind as the
8326 @item @emph{See also}:
8327 @ref{IAND}, @ref{IEOR}, @ref{IOR}, @ref{IBITS}, @ref{IBSET}, @ref{IBCLR}
8334 @section @code{NULL} --- Function that returns an disassociated pointer
8336 @cindex pointer, status
8337 @cindex pointer, disassociated
8340 @item @emph{Description}:
8341 Returns a disassociated pointer.
8343 If @var{MOLD} is present, a dissassociated pointer of the same type is
8344 returned, otherwise the type is determined by context.
8346 In Fortran 95, @var{MOLD} is optional. Please note that Fortran 2003
8347 includes cases where it is required.
8349 @item @emph{Standard}:
8350 Fortran 95 and later
8353 Transformational function
8355 @item @emph{Syntax}:
8356 @code{PTR => NULL([MOLD])}
8358 @item @emph{Arguments}:
8359 @multitable @columnfractions .15 .70
8360 @item @var{MOLD} @tab (Optional) shall be a pointer of any association
8361 status and of any type.
8364 @item @emph{Return value}:
8365 A disassociated pointer.
8367 @item @emph{Example}:
8369 REAL, POINTER, DIMENSION(:) :: VEC => NULL ()
8372 @item @emph{See also}:
8379 @section @code{OR} --- Bitwise logical OR
8381 @cindex bitwise logical or
8382 @cindex logical or, bitwise
8385 @item @emph{Description}:
8386 Bitwise logical @code{OR}.
8388 This intrinsic routine is provided for backwards compatibility with
8389 GNU Fortran 77. For integer arguments, programmers should consider
8390 the use of the @ref{IOR} intrinsic defined by the Fortran standard.
8392 @item @emph{Standard}:
8398 @item @emph{Syntax}:
8399 @code{RESULT = OR(I, J)}
8401 @item @emph{Arguments}:
8402 @multitable @columnfractions .15 .70
8403 @item @var{I} @tab The type shall be either a scalar @code{INTEGER}
8404 type or a scalar @code{LOGICAL} type.
8405 @item @var{J} @tab The type shall be the same as the type of @var{J}.
8408 @item @emph{Return value}:
8409 The return type is either a scalar @code{INTEGER} or a scalar
8410 @code{LOGICAL}. If the kind type parameters differ, then the
8411 smaller kind type is implicitly converted to larger kind, and the
8412 return has the larger kind.
8414 @item @emph{Example}:
8417 LOGICAL :: T = .TRUE., F = .FALSE.
8419 DATA a / Z'F' /, b / Z'3' /
8421 WRITE (*,*) OR(T, T), OR(T, F), OR(F, T), OR(F, F)
8422 WRITE (*,*) OR(a, b)
8426 @item @emph{See also}:
8427 Fortran 95 elemental function: @ref{IOR}
8433 @section @code{PACK} --- Pack an array into an array of rank one
8435 @cindex array, packing
8436 @cindex array, reduce dimension
8437 @cindex array, gather elements
8440 @item @emph{Description}:
8441 Stores the elements of @var{ARRAY} in an array of rank one.
8443 The beginning of the resulting array is made up of elements whose @var{MASK}
8444 equals @code{TRUE}. Afterwards, positions are filled with elements taken from
8447 @item @emph{Standard}:
8448 Fortran 95 and later
8451 Transformational function
8453 @item @emph{Syntax}:
8454 @code{RESULT = PACK(ARRAY, MASK[,VECTOR]}
8456 @item @emph{Arguments}:
8457 @multitable @columnfractions .15 .70
8458 @item @var{ARRAY} @tab Shall be an array of any type.
8459 @item @var{MASK} @tab Shall be an array of type @code{LOGICAL} and
8460 of the same size as @var{ARRAY}. Alternatively, it may be a @code{LOGICAL}
8462 @item @var{VECTOR} @tab (Optional) shall be an array of the same type
8463 as @var{ARRAY} and of rank one. If present, the number of elements in
8464 @var{VECTOR} shall be equal to or greater than the number of true elements
8465 in @var{MASK}. If @var{MASK} is scalar, the number of elements in
8466 @var{VECTOR} shall be equal to or greater than the number of elements in
8470 @item @emph{Return value}:
8471 The result is an array of rank one and the same type as that of @var{ARRAY}.
8472 If @var{VECTOR} is present, the result size is that of @var{VECTOR}, the
8473 number of @code{TRUE} values in @var{MASK} otherwise.
8475 @item @emph{Example}:
8476 Gathering nonzero elements from an array:
8480 m = (/ 1, 0, 0, 0, 5, 0 /)
8481 WRITE(*, FMT="(6(I0, ' '))") pack(m, m /= 0) ! "1 5"
8485 Gathering nonzero elements from an array and appending elements from @var{VECTOR}:
8489 m = (/ 1, 0, 0, 2 /)
8490 WRITE(*, FMT="(4(I0, ' '))") pack(m, m /= 0, (/ 0, 0, 3, 4 /)) ! "1 2 3 4"
8494 @item @emph{See also}:
8501 @section @code{PERROR} --- Print system error message
8503 @cindex system, error handling
8506 @item @emph{Description}:
8507 Prints (on the C @code{stderr} stream) a newline-terminated error
8508 message corresponding to the last system error. This is prefixed by
8509 @var{STRING}, a colon and a space. See @code{perror(3)}.
8511 @item @emph{Standard}:
8517 @item @emph{Syntax}:
8518 @code{CALL PERROR(STRING)}
8520 @item @emph{Arguments}:
8521 @multitable @columnfractions .15 .70
8522 @item @var{STRING} @tab A scalar of type @code{CHARACTER} and of the
8526 @item @emph{See also}:
8533 @section @code{PRECISION} --- Decimal precision of a real kind
8535 @cindex model representation, precision
8538 @item @emph{Description}:
8539 @code{PRECISION(X)} returns the decimal precision in the model of the
8542 @item @emph{Standard}:
8543 Fortran 95 and later
8548 @item @emph{Syntax}:
8549 @code{RESULT = PRECISION(X)}
8551 @item @emph{Arguments}:
8552 @multitable @columnfractions .15 .70
8553 @item @var{X} @tab Shall be of type @code{REAL} or @code{COMPLEX}.
8556 @item @emph{Return value}:
8557 The return value is of type @code{INTEGER} and of the default integer
8560 @item @emph{Example}:
8562 program prec_and_range
8563 real(kind=4) :: x(2)
8564 complex(kind=8) :: y
8566 print *, precision(x), range(x)
8567 print *, precision(y), range(y)
8568 end program prec_and_range
8575 @section @code{PRESENT} --- Determine whether an optional dummy argument is specified
8579 @item @emph{Description}:
8580 Determines whether an optional dummy argument is present.
8582 @item @emph{Standard}:
8583 Fortran 95 and later
8588 @item @emph{Syntax}:
8589 @code{RESULT = PRESENT(A)}
8591 @item @emph{Arguments}:
8592 @multitable @columnfractions .15 .70
8593 @item @var{A} @tab May be of any type and may be a pointer, scalar or array
8594 value, or a dummy procedure. It shall be the name of an optional dummy argument
8595 accessible within the current subroutine or function.
8598 @item @emph{Return value}:
8599 Returns either @code{TRUE} if the optional argument @var{A} is present, or
8600 @code{FALSE} otherwise.
8602 @item @emph{Example}:
8604 PROGRAM test_present
8605 WRITE(*,*) f(), f(42) ! "F T"
8607 LOGICAL FUNCTION f(x)
8608 INTEGER, INTENT(IN), OPTIONAL :: x
8618 @section @code{PRODUCT} --- Product of array elements
8620 @cindex array, product
8621 @cindex array, multiply elements
8622 @cindex array, conditionally multiply elements
8623 @cindex multiply array elements
8626 @item @emph{Description}:
8627 Multiplies the elements of @var{ARRAY} along dimension @var{DIM} if
8628 the corresponding element in @var{MASK} is @code{TRUE}.
8630 @item @emph{Standard}:
8631 Fortran 95 and later
8634 Transformational function
8636 @item @emph{Syntax}:
8637 @multitable @columnfractions .80
8638 @item @code{RESULT = PRODUCT(ARRAY[, MASK])}
8639 @item @code{RESULT = PRODUCT(ARRAY, DIM[, MASK])}
8642 @item @emph{Arguments}:
8643 @multitable @columnfractions .15 .70
8644 @item @var{ARRAY} @tab Shall be an array of type @code{INTEGER},
8645 @code{REAL} or @code{COMPLEX}.
8646 @item @var{DIM} @tab (Optional) shall be a scalar of type
8647 @code{INTEGER} with a value in the range from 1 to n, where n
8648 equals the rank of @var{ARRAY}.
8649 @item @var{MASK} @tab (Optional) shall be of type @code{LOGICAL}
8650 and either be a scalar or an array of the same shape as @var{ARRAY}.
8653 @item @emph{Return value}:
8654 The result is of the same type as @var{ARRAY}.
8656 If @var{DIM} is absent, a scalar with the product of all elements in
8657 @var{ARRAY} is returned. Otherwise, an array of rank n-1, where n equals
8658 the rank of @var{ARRAY}, and a shape similar to that of @var{ARRAY} with
8659 dimension @var{DIM} dropped is returned.
8662 @item @emph{Example}:
8664 PROGRAM test_product
8665 INTEGER :: x(5) = (/ 1, 2, 3, 4 ,5 /)
8666 print *, PRODUCT(x) ! all elements, product = 120
8667 print *, PRODUCT(x, MASK=MOD(x, 2)==1) ! odd elements, product = 15
8671 @item @emph{See also}:
8678 @section @code{RADIX} --- Base of a model number
8680 @cindex model representation, base
8681 @cindex model representation, radix
8684 @item @emph{Description}:
8685 @code{RADIX(X)} returns the base of the model representing the entity @var{X}.
8687 @item @emph{Standard}:
8688 Fortran 95 and later
8693 @item @emph{Syntax}:
8694 @code{RESULT = RADIX(X)}
8696 @item @emph{Arguments}:
8697 @multitable @columnfractions .15 .70
8698 @item @var{X} @tab Shall be of type @code{INTEGER} or @code{REAL}
8701 @item @emph{Return value}:
8702 The return value is a scalar of type @code{INTEGER} and of the default
8705 @item @emph{Example}:
8708 print *, "The radix for the default integer kind is", radix(0)
8709 print *, "The radix for the default real kind is", radix(0.0)
8710 end program test_radix
8718 @section @code{RAN} --- Real pseudo-random number
8720 @cindex random number generation
8723 @item @emph{Description}:
8724 For compatibility with HP FORTRAN 77/iX, the @code{RAN} intrinsic is
8725 provided as an alias for @code{RAND}. See @ref{RAND} for complete
8728 @item @emph{Standard}:
8734 @item @emph{See also}:
8735 @ref{RAND}, @ref{RANDOM_NUMBER}
8741 @section @code{RAND} --- Real pseudo-random number
8743 @cindex random number generation
8746 @item @emph{Description}:
8747 @code{RAND(FLAG)} returns a pseudo-random number from a uniform
8748 distribution between 0 and 1. If @var{FLAG} is 0, the next number
8749 in the current sequence is returned; if @var{FLAG} is 1, the generator
8750 is restarted by @code{CALL SRAND(0)}; if @var{FLAG} has any other value,
8751 it is used as a new seed with @code{SRAND}.
8753 This intrinsic routine is provided for backwards compatibility with
8754 GNU Fortran 77. It implements a simple modulo generator as provided
8755 by @command{g77}. For new code, one should consider the use of
8756 @ref{RANDOM_NUMBER} as it implements a superior algorithm.
8758 @item @emph{Standard}:
8764 @item @emph{Syntax}:
8765 @code{RESULT = RAND(I)}
8767 @item @emph{Arguments}:
8768 @multitable @columnfractions .15 .70
8769 @item @var{I} @tab Shall be a scalar @code{INTEGER} of kind 4.
8772 @item @emph{Return value}:
8773 The return value is of @code{REAL} type and the default kind.
8775 @item @emph{Example}:
8778 integer,parameter :: seed = 86456
8781 print *, rand(), rand(), rand(), rand()
8782 print *, rand(seed), rand(), rand(), rand()
8783 end program test_rand
8786 @item @emph{See also}:
8787 @ref{SRAND}, @ref{RANDOM_NUMBER}
8794 @section @code{RANDOM_NUMBER} --- Pseudo-random number
8795 @fnindex RANDOM_NUMBER
8796 @cindex random number generation
8799 @item @emph{Description}:
8800 Returns a single pseudorandom number or an array of pseudorandom numbers
8801 from the uniform distribution over the range @math{ 0 \leq x < 1}.
8803 The runtime-library implements George Marsaglia's KISS (Keep It Simple
8804 Stupid) random number generator (RNG). This RNG combines:
8806 @item The congruential generator @math{x(n) = 69069 \cdot x(n-1) + 1327217885}
8807 with a period of @math{2^{32}},
8808 @item A 3-shift shift-register generator with a period of @math{2^{32} - 1},
8809 @item Two 16-bit multiply-with-carry generators with a period of
8810 @math{597273182964842497 > 2^{59}}.
8812 The overall period exceeds @math{2^{123}}.
8814 Please note, this RNG is thread safe if used within OpenMP directives,
8815 i.e., its state will be consistent while called from multiple threads.
8816 However, the KISS generator does not create random numbers in parallel
8817 from multiple sources, but in sequence from a single source. If an
8818 OpenMP-enabled application heavily relies on random numbers, one should
8819 consider employing a dedicated parallel random number generator instead.
8821 @item @emph{Standard}:
8822 Fortran 95 and later
8827 @item @emph{Syntax}:
8828 @code{RANDOM_NUMBER(HARVEST)}
8830 @item @emph{Arguments}:
8831 @multitable @columnfractions .15 .70
8832 @item @var{HARVEST} @tab Shall be a scalar or an array of type @code{REAL}.
8835 @item @emph{Example}:
8837 program test_random_number
8839 CALL init_random_seed() ! see example of RANDOM_SEED
8840 CALL RANDOM_NUMBER(r)
8844 @item @emph{See also}:
8851 @section @code{RANDOM_SEED} --- Initialize a pseudo-random number sequence
8852 @fnindex RANDOM_SEED
8853 @cindex random number generation, seeding
8854 @cindex seeding a random number generator
8857 @item @emph{Description}:
8858 Restarts or queries the state of the pseudorandom number generator used by
8859 @code{RANDOM_NUMBER}.
8861 If @code{RANDOM_SEED} is called without arguments, it is initialized to
8862 a default state. The example below shows how to initialize the random
8863 seed based on the system's time.
8865 @item @emph{Standard}:
8866 Fortran 95 and later
8871 @item @emph{Syntax}:
8872 @code{CALL RANDOM_SEED([SIZE, PUT, GET])}
8874 @item @emph{Arguments}:
8875 @multitable @columnfractions .15 .70
8876 @item @var{SIZE} @tab (Optional) Shall be a scalar and of type default
8877 @code{INTEGER}, with @code{INTENT(OUT)}. It specifies the minimum size
8878 of the arrays used with the @var{PUT} and @var{GET} arguments.
8879 @item @var{PUT} @tab (Optional) Shall be an array of type default
8880 @code{INTEGER} and rank one. It is @code{INTENT(IN)} and the size of
8881 the array must be larger than or equal to the number returned by the
8882 @var{SIZE} argument.
8883 @item @var{GET} @tab (Optional) Shall be an array of type default
8884 @code{INTEGER} and rank one. It is @code{INTENT(OUT)} and the size
8885 of the array must be larger than or equal to the number returned by
8886 the @var{SIZE} argument.
8889 @item @emph{Example}:
8891 SUBROUTINE init_random_seed()
8892 INTEGER :: i, n, clock
8893 INTEGER, DIMENSION(:), ALLOCATABLE :: seed
8895 CALL RANDOM_SEED(size = n)
8898 CALL SYSTEM_CLOCK(COUNT=clock)
8900 seed = clock + 37 * (/ (i - 1, i = 1, n) /)
8901 CALL RANDOM_SEED(PUT = seed)
8907 @item @emph{See also}:
8914 @section @code{RANGE} --- Decimal exponent range
8916 @cindex model representation, range
8919 @item @emph{Description}:
8920 @code{RANGE(X)} returns the decimal exponent range in the model of the
8923 @item @emph{Standard}:
8924 Fortran 95 and later
8929 @item @emph{Syntax}:
8930 @code{RESULT = RANGE(X)}
8932 @item @emph{Arguments}:
8933 @multitable @columnfractions .15 .70
8934 @item @var{X} @tab Shall be of type @code{INTEGER}, @code{REAL}
8938 @item @emph{Return value}:
8939 The return value is of type @code{INTEGER} and of the default integer
8942 @item @emph{Example}:
8943 See @code{PRECISION} for an example.
8949 @section @code{REAL} --- Convert to real type
8952 @cindex conversion, to real
8953 @cindex complex numbers, real part
8956 @item @emph{Description}:
8957 @code{REAL(A [, KIND])} converts its argument @var{A} to a real type. The
8958 @code{REALPART} function is provided for compatibility with @command{g77},
8959 and its use is strongly discouraged.
8961 @item @emph{Standard}:
8962 Fortran 77 and later
8967 @item @emph{Syntax}:
8968 @multitable @columnfractions .80
8969 @item @code{RESULT = REAL(A [, KIND])}
8970 @item @code{RESULT = REALPART(Z)}
8973 @item @emph{Arguments}:
8974 @multitable @columnfractions .15 .70
8975 @item @var{A} @tab Shall be @code{INTEGER}, @code{REAL}, or
8977 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
8978 expression indicating the kind parameter of the result.
8981 @item @emph{Return value}:
8982 These functions return a @code{REAL} variable or array under
8983 the following rules:
8987 @code{REAL(A)} is converted to a default real type if @var{A} is an
8988 integer or real variable.
8990 @code{REAL(A)} is converted to a real type with the kind type parameter
8991 of @var{A} if @var{A} is a complex variable.
8993 @code{REAL(A, KIND)} is converted to a real type with kind type
8994 parameter @var{KIND} if @var{A} is a complex, integer, or real
8998 @item @emph{Example}:
9001 complex :: x = (1.0, 2.0)
9002 print *, real(x), real(x,8), realpart(x)
9003 end program test_real
9006 @item @emph{See also}:
9007 @ref{DBLE}, @ref{DFLOAT}, @ref{FLOAT}
9014 @section @code{RENAME} --- Rename a file
9016 @cindex file system, rename file
9019 @item @emph{Description}:
9020 Renames a file from file @var{PATH1} to @var{PATH2}. A null
9021 character (@code{CHAR(0)}) can be used to mark the end of the names in
9022 @var{PATH1} and @var{PATH2}; otherwise, trailing blanks in the file
9023 names are ignored. If the @var{STATUS} argument is supplied, it
9024 contains 0 on success or a nonzero error code upon return; see
9027 This intrinsic is provided in both subroutine and function forms;
9028 however, only one form can be used in any given program unit.
9030 @item @emph{Standard}:
9034 Subroutine, function
9036 @item @emph{Syntax}:
9037 @multitable @columnfractions .80
9038 @item @code{CALL RENAME(PATH1, PATH2 [, STATUS])}
9039 @item @code{STATUS = RENAME(PATH1, PATH2)}
9042 @item @emph{Arguments}:
9043 @multitable @columnfractions .15 .70
9044 @item @var{PATH1} @tab Shall be of default @code{CHARACTER} type.
9045 @item @var{PATH2} @tab Shall be of default @code{CHARACTER} type.
9046 @item @var{STATUS} @tab (Optional) Shall be of default @code{INTEGER} type.
9049 @item @emph{See also}:
9057 @section @code{REPEAT} --- Repeated string concatenation
9059 @cindex string, repeat
9060 @cindex string, concatenate
9063 @item @emph{Description}:
9064 Concatenates @var{NCOPIES} copies of a string.
9066 @item @emph{Standard}:
9067 Fortran 95 and later
9070 Transformational function
9072 @item @emph{Syntax}:
9073 @code{RESULT = REPEAT(STRING, NCOPIES)}
9075 @item @emph{Arguments}:
9076 @multitable @columnfractions .15 .70
9077 @item @var{STRING} @tab Shall be scalar and of type @code{CHARACTER}.
9078 @item @var{NCOPIES} @tab Shall be scalar and of type @code{INTEGER}.
9081 @item @emph{Return value}:
9082 A new scalar of type @code{CHARACTER} built up from @var{NCOPIES} copies
9085 @item @emph{Example}:
9088 write(*,*) repeat("x", 5) ! "xxxxx"
9096 @section @code{RESHAPE} --- Function to reshape an array
9098 @cindex array, change dimensions
9099 @cindex array, transmogrify
9102 @item @emph{Description}:
9103 Reshapes @var{SOURCE} to correspond to @var{SHAPE}. If necessary,
9104 the new array may be padded with elements from @var{PAD} or permuted
9105 as defined by @var{ORDER}.
9107 @item @emph{Standard}:
9108 Fortran 95 and later
9111 Transformational function
9113 @item @emph{Syntax}:
9114 @code{RESULT = RESHAPE(SOURCE, SHAPE[, PAD, ORDER])}
9116 @item @emph{Arguments}:
9117 @multitable @columnfractions .15 .70
9118 @item @var{SOURCE} @tab Shall be an array of any type.
9119 @item @var{SHAPE} @tab Shall be of type @code{INTEGER} and an
9120 array of rank one. Its values must be positive or zero.
9121 @item @var{PAD} @tab (Optional) shall be an array of the same
9122 type as @var{SOURCE}.
9123 @item @var{ORDER} @tab (Optional) shall be of type @code{INTEGER}
9124 and an array of the same shape as @var{SHAPE}. Its values shall
9125 be a permutation of the numbers from 1 to n, where n is the size of
9126 @var{SHAPE}. If @var{ORDER} is absent, the natural ordering shall
9130 @item @emph{Return value}:
9131 The result is an array of shape @var{SHAPE} with the same type as
9134 @item @emph{Example}:
9136 PROGRAM test_reshape
9137 INTEGER, DIMENSION(4) :: x
9138 WRITE(*,*) SHAPE(x) ! prints "4"
9139 WRITE(*,*) SHAPE(RESHAPE(x, (/2, 2/))) ! prints "2 2"
9143 @item @emph{See also}:
9150 @section @code{RRSPACING} --- Reciprocal of the relative spacing
9152 @cindex real number, relative spacing
9153 @cindex floating point, relative spacing
9157 @item @emph{Description}:
9158 @code{RRSPACING(X)} returns the reciprocal of the relative spacing of
9159 model numbers near @var{X}.
9161 @item @emph{Standard}:
9162 Fortran 95 and later
9167 @item @emph{Syntax}:
9168 @code{RESULT = RRSPACING(X)}
9170 @item @emph{Arguments}:
9171 @multitable @columnfractions .15 .70
9172 @item @var{X} @tab Shall be of type @code{REAL}.
9175 @item @emph{Return value}:
9176 The return value is of the same type and kind as @var{X}.
9177 The value returned is equal to
9178 @code{ABS(FRACTION(X)) * FLOAT(RADIX(X))**DIGITS(X)}.
9180 @item @emph{See also}:
9187 @section @code{RSHIFT} --- Right shift bits
9189 @cindex bits, shift right
9192 @item @emph{Description}:
9193 @code{RSHIFT} returns a value corresponding to @var{I} with all of the
9194 bits shifted right by @var{SHIFT} places. If the absolute value of
9195 @var{SHIFT} is greater than @code{BIT_SIZE(I)}, the value is undefined.
9196 Bits shifted out from the left end are lost; zeros are shifted in from
9199 This function has been superseded by the @code{ISHFT} intrinsic, which
9200 is standard in Fortran 95 and later.
9202 @item @emph{Standard}:
9208 @item @emph{Syntax}:
9209 @code{RESULT = RSHIFT(I, SHIFT)}
9211 @item @emph{Arguments}:
9212 @multitable @columnfractions .15 .70
9213 @item @var{I} @tab The type shall be @code{INTEGER}.
9214 @item @var{SHIFT} @tab The type shall be @code{INTEGER}.
9217 @item @emph{Return value}:
9218 The return value is of type @code{INTEGER} and of the same kind as
9221 @item @emph{See also}:
9222 @ref{ISHFT}, @ref{ISHFTC}, @ref{LSHIFT}
9229 @section @code{SCALE} --- Scale a real value
9231 @cindex real number, scale
9232 @cindex floating point, scale
9235 @item @emph{Description}:
9236 @code{SCALE(X,I)} returns @code{X * RADIX(X)**I}.
9238 @item @emph{Standard}:
9239 Fortran 95 and later
9244 @item @emph{Syntax}:
9245 @code{RESULT = SCALE(X, I)}
9247 @item @emph{Arguments}:
9248 @multitable @columnfractions .15 .70
9249 @item @var{X} @tab The type of the argument shall be a @code{REAL}.
9250 @item @var{I} @tab The type of the argument shall be a @code{INTEGER}.
9253 @item @emph{Return value}:
9254 The return value is of the same type and kind as @var{X}.
9255 Its value is @code{X * RADIX(X)**I}.
9257 @item @emph{Example}:
9260 real :: x = 178.1387e-4
9262 print *, scale(x,i), x*radix(x)**i
9263 end program test_scale
9271 @section @code{SCAN} --- Scan a string for the presence of a set of characters
9273 @cindex string, find subset
9276 @item @emph{Description}:
9277 Scans a @var{STRING} for any of the characters in a @var{SET}
9280 If @var{BACK} is either absent or equals @code{FALSE}, this function
9281 returns the position of the leftmost character of @var{STRING} that is
9282 in @var{SET}. If @var{BACK} equals @code{TRUE}, the rightmost position
9283 is returned. If no character of @var{SET} is found in @var{STRING}, the
9286 @item @emph{Standard}:
9287 Fortran 95 and later, with @var{KIND} argument Fortran 2003 and later
9292 @item @emph{Syntax}:
9293 @code{RESULT = SCAN(STRING, SET[, BACK [, KIND]])}
9295 @item @emph{Arguments}:
9296 @multitable @columnfractions .15 .70
9297 @item @var{STRING} @tab Shall be of type @code{CHARACTER}.
9298 @item @var{SET} @tab Shall be of type @code{CHARACTER}.
9299 @item @var{BACK} @tab (Optional) shall be of type @code{LOGICAL}.
9300 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
9301 expression indicating the kind parameter of the result.
9304 @item @emph{Return value}:
9305 The return value is of type @code{INTEGER} and of kind @var{KIND}. If
9306 @var{KIND} is absent, the return value is of default integer kind.
9308 @item @emph{Example}:
9311 WRITE(*,*) SCAN("FORTRAN", "AO") ! 2, found 'O'
9312 WRITE(*,*) SCAN("FORTRAN", "AO", .TRUE.) ! 6, found 'A'
9313 WRITE(*,*) SCAN("FORTRAN", "C++") ! 0, found none
9317 @item @emph{See also}:
9318 @ref{INDEX intrinsic}, @ref{VERIFY}
9324 @section @code{SECNDS} --- Time function
9326 @cindex time, elapsed
9327 @cindex elapsed time
9330 @item @emph{Description}:
9331 @code{SECNDS(X)} gets the time in seconds from the real-time system clock.
9332 @var{X} is a reference time, also in seconds. If this is zero, the time in
9333 seconds from midnight is returned. This function is non-standard and its
9336 @item @emph{Standard}:
9342 @item @emph{Syntax}:
9343 @code{RESULT = SECNDS (X)}
9345 @item @emph{Arguments}:
9346 @multitable @columnfractions .15 .70
9347 @item @var{T} @tab Shall be of type @code{REAL(4)}.
9348 @item @var{X} @tab Shall be of type @code{REAL(4)}.
9351 @item @emph{Return value}:
9354 @item @emph{Example}:
9359 print *, secnds (0.0) ! seconds since midnight
9360 t1 = secnds (0.0) ! reference time
9361 do i = 1, 10000000 ! do something
9363 t2 = secnds (t1) ! elapsed time
9364 print *, "Something took ", t2, " seconds."
9365 end program test_secnds
9372 @section @code{SECOND} --- CPU time function
9374 @cindex time, elapsed
9375 @cindex elapsed time
9378 @item @emph{Description}:
9379 Returns a @code{REAL(4)} value representing the elapsed CPU time in
9380 seconds. This provides the same functionality as the standard
9381 @code{CPU_TIME} intrinsic, and is only included for backwards
9384 This intrinsic is provided in both subroutine and function forms;
9385 however, only one form can be used in any given program unit.
9387 @item @emph{Standard}:
9391 Subroutine, function
9393 @item @emph{Syntax}:
9394 @multitable @columnfractions .80
9395 @item @code{CALL SECOND(TIME)}
9396 @item @code{TIME = SECOND()}
9399 @item @emph{Arguments}:
9400 @multitable @columnfractions .15 .70
9401 @item @var{TIME} @tab Shall be of type @code{REAL(4)}.
9404 @item @emph{Return value}:
9405 In either syntax, @var{TIME} is set to the process's current runtime in
9408 @item @emph{See also}:
9415 @node SELECTED_CHAR_KIND
9416 @section @code{SELECTED_CHAR_KIND} --- Choose character kind
9417 @fnindex SELECTED_CHAR_KIND
9418 @cindex character kind
9419 @cindex kind, character
9422 @item @emph{Description}:
9424 @code{SELECTED_CHAR_KIND(NAME)} returns the kind value for the character
9425 set named @var{NAME}, if a character set with such a name is supported,
9426 or @math{-1} otherwise. Currently, supported character sets include
9427 ``ASCII'' and ``DEFAULT'', which are equivalent.
9429 @item @emph{Standard}:
9430 Fortran 2003 and later
9433 Transformational function
9435 @item @emph{Syntax}:
9436 @code{RESULT = SELECTED_CHAR_KIND(NAME)}
9438 @item @emph{Arguments}:
9439 @multitable @columnfractions .15 .70
9440 @item @var{NAME} @tab Shall be a scalar and of the default character type.
9443 @item @emph{Example}:
9446 integer,parameter :: ascii = selected_char_kind("ascii")
9447 character(kind=ascii, len=26) :: s
9449 s = ascii_"abcdefghijklmnopqrstuvwxyz"
9451 end program ascii_kind
9457 @node SELECTED_INT_KIND
9458 @section @code{SELECTED_INT_KIND} --- Choose integer kind
9459 @fnindex SELECTED_INT_KIND
9460 @cindex integer kind
9461 @cindex kind, integer
9464 @item @emph{Description}:
9465 @code{SELECTED_INT_KIND(R)} return the kind value of the smallest integer
9466 type that can represent all values ranging from @math{-10^R} (exclusive)
9467 to @math{10^R} (exclusive). If there is no integer kind that accommodates
9468 this range, @code{SELECTED_INT_KIND} returns @math{-1}.
9470 @item @emph{Standard}:
9471 Fortran 95 and later
9474 Transformational function
9476 @item @emph{Syntax}:
9477 @code{RESULT = SELECTED_INT_KIND(R)}
9479 @item @emph{Arguments}:
9480 @multitable @columnfractions .15 .70
9481 @item @var{R} @tab Shall be a scalar and of type @code{INTEGER}.
9484 @item @emph{Example}:
9486 program large_integers
9487 integer,parameter :: k5 = selected_int_kind(5)
9488 integer,parameter :: k15 = selected_int_kind(15)
9489 integer(kind=k5) :: i5
9490 integer(kind=k15) :: i15
9492 print *, huge(i5), huge(i15)
9494 ! The following inequalities are always true
9495 print *, huge(i5) >= 10_k5**5-1
9496 print *, huge(i15) >= 10_k15**15-1
9497 end program large_integers
9503 @node SELECTED_REAL_KIND
9504 @section @code{SELECTED_REAL_KIND} --- Choose real kind
9505 @fnindex SELECTED_REAL_KIND
9510 @item @emph{Description}:
9511 @code{SELECTED_REAL_KIND(P,R)} returns the kind value of a real data type
9512 with decimal precision of at least @code{P} digits and exponent
9513 range greater at least @code{R}.
9515 @item @emph{Standard}:
9516 Fortran 95 and later
9519 Transformational function
9521 @item @emph{Syntax}:
9522 @code{RESULT = SELECTED_REAL_KIND([P, R])}
9524 @item @emph{Arguments}:
9525 @multitable @columnfractions .15 .70
9526 @item @var{P} @tab (Optional) shall be a scalar and of type @code{INTEGER}.
9527 @item @var{R} @tab (Optional) shall be a scalar and of type @code{INTEGER}.
9529 At least one argument shall be present.
9531 @item @emph{Return value}:
9533 @code{SELECTED_REAL_KIND} returns the value of the kind type parameter of
9534 a real data type with decimal precision of at least @code{P} digits and a
9535 decimal exponent range of at least @code{R}. If more than one real data
9536 type meet the criteria, the kind of the data type with the smallest
9537 decimal precision is returned. If no real data type matches the criteria,
9540 @item -1 if the processor does not support a real data type with a
9541 precision greater than or equal to @code{P}
9542 @item -2 if the processor does not support a real type with an exponent
9543 range greater than or equal to @code{R}
9544 @item -3 if neither is supported.
9547 @item @emph{Example}:
9550 integer,parameter :: p6 = selected_real_kind(6)
9551 integer,parameter :: p10r100 = selected_real_kind(10,100)
9552 integer,parameter :: r400 = selected_real_kind(r=400)
9554 real(kind=p10r100) :: y
9555 real(kind=r400) :: z
9557 print *, precision(x), range(x)
9558 print *, precision(y), range(y)
9559 print *, precision(z), range(z)
9560 end program real_kinds
9567 @section @code{SET_EXPONENT} --- Set the exponent of the model
9568 @fnindex SET_EXPONENT
9569 @cindex real number, set exponent
9570 @cindex floating point, set exponent
9573 @item @emph{Description}:
9574 @code{SET_EXPONENT(X, I)} returns the real number whose fractional part
9575 is that that of @var{X} and whose exponent part is @var{I}.
9577 @item @emph{Standard}:
9578 Fortran 95 and later
9583 @item @emph{Syntax}:
9584 @code{RESULT = SET_EXPONENT(X, I)}
9586 @item @emph{Arguments}:
9587 @multitable @columnfractions .15 .70
9588 @item @var{X} @tab Shall be of type @code{REAL}.
9589 @item @var{I} @tab Shall be of type @code{INTEGER}.
9592 @item @emph{Return value}:
9593 The return value is of the same type and kind as @var{X}.
9594 The real number whose fractional part
9595 is that that of @var{X} and whose exponent part if @var{I} is returned;
9596 it is @code{FRACTION(X) * RADIX(X)**I}.
9598 @item @emph{Example}:
9601 REAL :: x = 178.1387e-4
9603 PRINT *, SET_EXPONENT(x, i), FRACTION(x) * RADIX(x)**i
9612 @section @code{SHAPE} --- Determine the shape of an array
9614 @cindex array, shape
9617 @item @emph{Description}:
9618 Determines the shape of an array.
9620 @item @emph{Standard}:
9621 Fortran 95 and later
9626 @item @emph{Syntax}:
9627 @code{RESULT = SHAPE(SOURCE)}
9629 @item @emph{Arguments}:
9630 @multitable @columnfractions .15 .70
9631 @item @var{SOURCE} @tab Shall be an array or scalar of any type.
9632 If @var{SOURCE} is a pointer it must be associated and allocatable
9633 arrays must be allocated.
9636 @item @emph{Return value}:
9637 An @code{INTEGER} array of rank one with as many elements as @var{SOURCE}
9638 has dimensions. The elements of the resulting array correspond to the extend
9639 of @var{SOURCE} along the respective dimensions. If @var{SOURCE} is a scalar,
9640 the result is the rank one array of size zero.
9642 @item @emph{Example}:
9645 INTEGER, DIMENSION(-1:1, -1:2) :: A
9646 WRITE(*,*) SHAPE(A) ! (/ 3, 4 /)
9647 WRITE(*,*) SIZE(SHAPE(42)) ! (/ /)
9651 @item @emph{See also}:
9652 @ref{RESHAPE}, @ref{SIZE}
9658 @section @code{SIGN} --- Sign copying function
9662 @cindex sign copying
9665 @item @emph{Description}:
9666 @code{SIGN(A,B)} returns the value of @var{A} with the sign of @var{B}.
9668 @item @emph{Standard}:
9669 Fortran 77 and later
9674 @item @emph{Syntax}:
9675 @code{RESULT = SIGN(A, B)}
9677 @item @emph{Arguments}:
9678 @multitable @columnfractions .15 .70
9679 @item @var{A} @tab Shall be of type @code{INTEGER} or @code{REAL}
9680 @item @var{B} @tab Shall be of the same type and kind as @var{A}
9683 @item @emph{Return value}:
9684 The kind of the return value is that of @var{A} and @var{B}.
9685 If @math{B\ge 0} then the result is @code{ABS(A)}, else
9686 it is @code{-ABS(A)}.
9688 @item @emph{Example}:
9691 print *, sign(-12,1)
9692 print *, sign(-12,0)
9693 print *, sign(-12,-1)
9695 print *, sign(-12.,1.)
9696 print *, sign(-12.,0.)
9697 print *, sign(-12.,-1.)
9698 end program test_sign
9701 @item @emph{Specific names}:
9702 @multitable @columnfractions .20 .20 .20 .25
9703 @item Name @tab Arguments @tab Return type @tab Standard
9704 @item @code{ISIGN(A,P)} @tab @code{INTEGER(4)} @tab @code{INTEGER(4)} @tab f95, gnu
9705 @item @code{DSIGN(A,P)} @tab @code{REAL(8)} @tab @code{REAL(8)} @tab f95, gnu
9712 @section @code{SIGNAL} --- Signal handling subroutine (or function)
9714 @cindex system, signal handling
9717 @item @emph{Description}:
9718 @code{SIGNAL(NUMBER, HANDLER [, STATUS])} causes external subroutine
9719 @var{HANDLER} to be executed with a single integer argument when signal
9720 @var{NUMBER} occurs. If @var{HANDLER} is an integer, it can be used to
9721 turn off handling of signal @var{NUMBER} or revert to its default
9722 action. See @code{signal(2)}.
9724 If @code{SIGNAL} is called as a subroutine and the @var{STATUS} argument
9725 is supplied, it is set to the value returned by @code{signal(2)}.
9727 @item @emph{Standard}:
9731 Subroutine, function
9733 @item @emph{Syntax}:
9734 @multitable @columnfractions .80
9735 @item @code{CALL SIGNAL(NUMBER, HANDLER [, STATUS])}
9736 @item @code{STATUS = SIGNAL(NUMBER, HANDLER)}
9739 @item @emph{Arguments}:
9740 @multitable @columnfractions .15 .70
9741 @item @var{NUMBER} @tab Shall be a scalar integer, with @code{INTENT(IN)}
9742 @item @var{HANDLER}@tab Signal handler (@code{INTEGER FUNCTION} or
9743 @code{SUBROUTINE}) or dummy/global @code{INTEGER} scalar.
9744 @code{INTEGER}. It is @code{INTENT(IN)}.
9745 @item @var{STATUS} @tab (Optional) @var{STATUS} shall be a scalar
9746 integer. It has @code{INTENT(OUT)}.
9748 @c TODO: What should the interface of the handler be? Does it take arguments?
9750 @item @emph{Return value}:
9751 The @code{SIGNAL} function returns the value returned by @code{signal(2)}.
9753 @item @emph{Example}:
9757 external handler_print
9759 call signal (12, handler_print)
9763 end program test_signal
9770 @section @code{SIN} --- Sine function
9776 @cindex trigonometric function, sine
9780 @item @emph{Description}:
9781 @code{SIN(X)} computes the sine of @var{X}.
9783 @item @emph{Standard}:
9784 Fortran 77 and later
9789 @item @emph{Syntax}:
9790 @code{RESULT = SIN(X)}
9792 @item @emph{Arguments}:
9793 @multitable @columnfractions .15 .70
9794 @item @var{X} @tab The type shall be @code{REAL} or
9798 @item @emph{Return value}:
9799 The return value has same type and kind as @var{X}.
9801 @item @emph{Example}:
9806 end program test_sin
9809 @item @emph{Specific names}:
9810 @multitable @columnfractions .20 .20 .20 .25
9811 @item Name @tab Argument @tab Return type @tab Standard
9812 @item @code{DSIN(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab f95, gnu
9813 @item @code{CSIN(X)} @tab @code{COMPLEX(4) X} @tab @code{COMPLEX(4)} @tab f95, gnu
9814 @item @code{ZSIN(X)} @tab @code{COMPLEX(8) X} @tab @code{COMPLEX(8)} @tab f95, gnu
9815 @item @code{CDSIN(X)} @tab @code{COMPLEX(8) X} @tab @code{COMPLEX(8)} @tab f95, gnu
9818 @item @emph{See also}:
9825 @section @code{SINH} --- Hyperbolic sine function
9828 @cindex hyperbolic sine
9829 @cindex hyperbolic function, sine
9830 @cindex sine, hyperbolic
9833 @item @emph{Description}:
9834 @code{SINH(X)} computes the hyperbolic sine of @var{X}.
9836 @item @emph{Standard}:
9837 Fortran 95 and later, for a complex argument Fortran 2008 or later
9842 @item @emph{Syntax}:
9843 @code{RESULT = SINH(X)}
9845 @item @emph{Arguments}:
9846 @multitable @columnfractions .15 .70
9847 @item @var{X} @tab The type shall be @code{REAL} or @code{COMPLEX}.
9850 @item @emph{Return value}:
9851 The return value has same type and kind as @var{X}.
9853 @item @emph{Example}:
9856 real(8) :: x = - 1.0_8
9858 end program test_sinh
9861 @item @emph{Specific names}:
9862 @multitable @columnfractions .20 .20 .20 .25
9863 @item Name @tab Argument @tab Return type @tab Standard
9864 @item @code{DSINH(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab Fortran 95 and later
9867 @item @emph{See also}:
9874 @section @code{SIZE} --- Determine the size of an array
9877 @cindex array, number of elements
9878 @cindex array, count elements
9881 @item @emph{Description}:
9882 Determine the extent of @var{ARRAY} along a specified dimension @var{DIM},
9883 or the total number of elements in @var{ARRAY} if @var{DIM} is absent.
9885 @item @emph{Standard}:
9886 Fortran 95 and later, with @var{KIND} argument Fortran 2003 and later
9891 @item @emph{Syntax}:
9892 @code{RESULT = SIZE(ARRAY[, DIM [, KIND]])}
9894 @item @emph{Arguments}:
9895 @multitable @columnfractions .15 .70
9896 @item @var{ARRAY} @tab Shall be an array of any type. If @var{ARRAY} is
9897 a pointer it must be associated and allocatable arrays must be allocated.
9898 @item @var{DIM} @tab (Optional) shall be a scalar of type @code{INTEGER}
9899 and its value shall be in the range from 1 to n, where n equals the rank
9901 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
9902 expression indicating the kind parameter of the result.
9905 @item @emph{Return value}:
9906 The return value is of type @code{INTEGER} and of kind @var{KIND}. If
9907 @var{KIND} is absent, the return value is of default integer kind.
9909 @item @emph{Example}:
9912 WRITE(*,*) SIZE((/ 1, 2 /)) ! 2
9916 @item @emph{See also}:
9917 @ref{SHAPE}, @ref{RESHAPE}
9922 @section @code{SIZEOF} --- Size in bytes of an expression
9924 @cindex expression size
9925 @cindex size of an expression
9928 @item @emph{Description}:
9929 @code{SIZEOF(X)} calculates the number of bytes of storage the
9930 expression @code{X} occupies.
9932 @item @emph{Standard}:
9938 @item @emph{Syntax}:
9939 @code{N = SIZEOF(X)}
9941 @item @emph{Arguments}:
9942 @multitable @columnfractions .15 .70
9943 @item @var{X} @tab The argument shall be of any type, rank or shape.
9946 @item @emph{Return value}:
9947 The return value is of type integer and of the system-dependent kind
9948 @var{C_SIZE_T} (from the @var{ISO_C_BINDING} module). Its value is the
9949 number of bytes occupied by the argument. If the argument has the
9950 @code{POINTER} attribute, the number of bytes of the storage area pointed
9951 to is returned. If the argument is of a derived type with @code{POINTER}
9952 or @code{ALLOCATABLE} components, the return value doesn't account for
9953 the sizes of the data pointed to by these components.
9955 @item @emph{Example}:
9959 print *, (sizeof(s)/sizeof(r) == 5)
9962 The example will print @code{.TRUE.} unless you are using a platform
9963 where default @code{REAL} variables are unusually padded.
9965 @item @emph{See also}:
9971 @section @code{SLEEP} --- Sleep for the specified number of seconds
9973 @cindex delayed execution
9976 @item @emph{Description}:
9977 Calling this subroutine causes the process to pause for @var{SECONDS} seconds.
9979 @item @emph{Standard}:
9985 @item @emph{Syntax}:
9986 @code{CALL SLEEP(SECONDS)}
9988 @item @emph{Arguments}:
9989 @multitable @columnfractions .15 .70
9990 @item @var{SECONDS} @tab The type shall be of default @code{INTEGER}.
9993 @item @emph{Example}:
10004 @section @code{SNGL} --- Convert double precision real to default real
10006 @cindex conversion, to real
10009 @item @emph{Description}:
10010 @code{SNGL(A)} converts the double precision real @var{A}
10011 to a default real value. This is an archaic form of @code{REAL}
10012 that is specific to one type for @var{A}.
10014 @item @emph{Standard}:
10015 Fortran 77 and later
10017 @item @emph{Class}:
10020 @item @emph{Syntax}:
10021 @code{RESULT = SNGL(A)}
10023 @item @emph{Arguments}:
10024 @multitable @columnfractions .15 .70
10025 @item @var{A} @tab The type shall be a double precision @code{REAL}.
10028 @item @emph{Return value}:
10029 The return value is of type default @code{REAL}.
10031 @item @emph{See also}:
10038 @section @code{SPACING} --- Smallest distance between two numbers of a given type
10040 @cindex real number, relative spacing
10041 @cindex floating point, relative spacing
10044 @item @emph{Description}:
10045 Determines the distance between the argument @var{X} and the nearest
10046 adjacent number of the same type.
10048 @item @emph{Standard}:
10049 Fortran 95 and later
10051 @item @emph{Class}:
10054 @item @emph{Syntax}:
10055 @code{RESULT = SPACING(X)}
10057 @item @emph{Arguments}:
10058 @multitable @columnfractions .15 .70
10059 @item @var{X} @tab Shall be of type @code{REAL}.
10062 @item @emph{Return value}:
10063 The result is of the same type as the input argument @var{X}.
10065 @item @emph{Example}:
10067 PROGRAM test_spacing
10068 INTEGER, PARAMETER :: SGL = SELECTED_REAL_KIND(p=6, r=37)
10069 INTEGER, PARAMETER :: DBL = SELECTED_REAL_KIND(p=13, r=200)
10071 WRITE(*,*) spacing(1.0_SGL) ! "1.1920929E-07" on i686
10072 WRITE(*,*) spacing(1.0_DBL) ! "2.220446049250313E-016" on i686
10076 @item @emph{See also}:
10083 @section @code{SPREAD} --- Add a dimension to an array
10085 @cindex array, increase dimension
10086 @cindex array, duplicate elements
10087 @cindex array, duplicate dimensions
10090 @item @emph{Description}:
10091 Replicates a @var{SOURCE} array @var{NCOPIES} times along a specified
10092 dimension @var{DIM}.
10094 @item @emph{Standard}:
10095 Fortran 95 and later
10097 @item @emph{Class}:
10098 Transformational function
10100 @item @emph{Syntax}:
10101 @code{RESULT = SPREAD(SOURCE, DIM, NCOPIES)}
10103 @item @emph{Arguments}:
10104 @multitable @columnfractions .15 .70
10105 @item @var{SOURCE} @tab Shall be a scalar or an array of any type and
10106 a rank less than seven.
10107 @item @var{DIM} @tab Shall be a scalar of type @code{INTEGER} with a
10108 value in the range from 1 to n+1, where n equals the rank of @var{SOURCE}.
10109 @item @var{NCOPIES} @tab Shall be a scalar of type @code{INTEGER}.
10112 @item @emph{Return value}:
10113 The result is an array of the same type as @var{SOURCE} and has rank n+1
10114 where n equals the rank of @var{SOURCE}.
10116 @item @emph{Example}:
10118 PROGRAM test_spread
10119 INTEGER :: a = 1, b(2) = (/ 1, 2 /)
10120 WRITE(*,*) SPREAD(A, 1, 2) ! "1 1"
10121 WRITE(*,*) SPREAD(B, 1, 2) ! "1 1 2 2"
10125 @item @emph{See also}:
10132 @section @code{SQRT} --- Square-root function
10139 @cindex square-root
10142 @item @emph{Description}:
10143 @code{SQRT(X)} computes the square root of @var{X}.
10145 @item @emph{Standard}:
10146 Fortran 77 and later
10148 @item @emph{Class}:
10151 @item @emph{Syntax}:
10152 @code{RESULT = SQRT(X)}
10154 @item @emph{Arguments}:
10155 @multitable @columnfractions .15 .70
10156 @item @var{X} @tab The type shall be @code{REAL} or
10160 @item @emph{Return value}:
10161 The return value is of type @code{REAL} or @code{COMPLEX}.
10162 The kind type parameter is the same as @var{X}.
10164 @item @emph{Example}:
10167 real(8) :: x = 2.0_8
10168 complex :: z = (1.0, 2.0)
10171 end program test_sqrt
10174 @item @emph{Specific names}:
10175 @multitable @columnfractions .20 .20 .20 .25
10176 @item Name @tab Argument @tab Return type @tab Standard
10177 @item @code{DSQRT(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab Fortran 95 and later
10178 @item @code{CSQRT(X)} @tab @code{COMPLEX(4) X} @tab @code{COMPLEX(4)} @tab Fortran 95 and later
10179 @item @code{ZSQRT(X)} @tab @code{COMPLEX(8) X} @tab @code{COMPLEX(8)} @tab GNU extension
10180 @item @code{CDSQRT(X)} @tab @code{COMPLEX(8) X} @tab @code{COMPLEX(8)} @tab GNU extension
10187 @section @code{SRAND} --- Reinitialize the random number generator
10189 @cindex random number generation, seeding
10190 @cindex seeding a random number generator
10193 @item @emph{Description}:
10194 @code{SRAND} reinitializes the pseudo-random number generator
10195 called by @code{RAND} and @code{IRAND}. The new seed used by the
10196 generator is specified by the required argument @var{SEED}.
10198 @item @emph{Standard}:
10201 @item @emph{Class}:
10204 @item @emph{Syntax}:
10205 @code{CALL SRAND(SEED)}
10207 @item @emph{Arguments}:
10208 @multitable @columnfractions .15 .70
10209 @item @var{SEED} @tab Shall be a scalar @code{INTEGER(kind=4)}.
10212 @item @emph{Return value}:
10213 Does not return anything.
10215 @item @emph{Example}:
10216 See @code{RAND} and @code{IRAND} for examples.
10218 @item @emph{Notes}:
10219 The Fortran 2003 standard specifies the intrinsic @code{RANDOM_SEED} to
10220 initialize the pseudo-random numbers generator and @code{RANDOM_NUMBER}
10221 to generate pseudo-random numbers. Please note that in
10222 GNU Fortran, these two sets of intrinsics (@code{RAND},
10223 @code{IRAND} and @code{SRAND} on the one hand, @code{RANDOM_NUMBER} and
10224 @code{RANDOM_SEED} on the other hand) access two independent
10225 pseudo-random number generators.
10227 @item @emph{See also}:
10228 @ref{RAND}, @ref{RANDOM_SEED}, @ref{RANDOM_NUMBER}
10235 @section @code{STAT} --- Get file status
10237 @cindex file system, file status
10240 @item @emph{Description}:
10241 This function returns information about a file. No permissions are required on
10242 the file itself, but execute (search) permission is required on all of the
10243 directories in path that lead to the file.
10245 The elements that are obtained and stored in the array @code{VALUES}:
10246 @multitable @columnfractions .15 .70
10247 @item @code{VALUES(1)} @tab Device ID
10248 @item @code{VALUES(2)} @tab Inode number
10249 @item @code{VALUES(3)} @tab File mode
10250 @item @code{VALUES(4)} @tab Number of links
10251 @item @code{VALUES(5)} @tab Owner's uid
10252 @item @code{VALUES(6)} @tab Owner's gid
10253 @item @code{VALUES(7)} @tab ID of device containing directory entry for file (0 if not available)
10254 @item @code{VALUES(8)} @tab File size (bytes)
10255 @item @code{VALUES(9)} @tab Last access time
10256 @item @code{VALUES(10)} @tab Last modification time
10257 @item @code{VALUES(11)} @tab Last file status change time
10258 @item @code{VALUES(12)} @tab Preferred I/O block size (-1 if not available)
10259 @item @code{VALUES(13)} @tab Number of blocks allocated (-1 if not available)
10262 Not all these elements are relevant on all systems.
10263 If an element is not relevant, it is returned as 0.
10265 This intrinsic is provided in both subroutine and function forms; however,
10266 only one form can be used in any given program unit.
10268 @item @emph{Standard}:
10271 @item @emph{Class}:
10272 Subroutine, function
10274 @item @emph{Syntax}:
10275 @code{CALL STAT(NAME, VALUES [, STATUS])}
10277 @item @emph{Arguments}:
10278 @multitable @columnfractions .15 .70
10279 @item @var{NAME} @tab The type shall be @code{CHARACTER}, of the
10280 default kind and a valid path within the file system.
10281 @item @var{VALUES} @tab The type shall be @code{INTEGER(4), DIMENSION(13)}.
10282 @item @var{STATUS} @tab (Optional) status flag of type @code{INTEGER(4)}. Returns 0
10283 on success and a system specific error code otherwise.
10286 @item @emph{Example}:
10289 INTEGER, DIMENSION(13) :: buff
10292 CALL STAT("/etc/passwd", buff, status)
10294 IF (status == 0) THEN
10295 WRITE (*, FMT="('Device ID:', T30, I19)") buff(1)
10296 WRITE (*, FMT="('Inode number:', T30, I19)") buff(2)
10297 WRITE (*, FMT="('File mode (octal):', T30, O19)") buff(3)
10298 WRITE (*, FMT="('Number of links:', T30, I19)") buff(4)
10299 WRITE (*, FMT="('Owner''s uid:', T30, I19)") buff(5)
10300 WRITE (*, FMT="('Owner''s gid:', T30, I19)") buff(6)
10301 WRITE (*, FMT="('Device where located:', T30, I19)") buff(7)
10302 WRITE (*, FMT="('File size:', T30, I19)") buff(8)
10303 WRITE (*, FMT="('Last access time:', T30, A19)") CTIME(buff(9))
10304 WRITE (*, FMT="('Last modification time', T30, A19)") CTIME(buff(10))
10305 WRITE (*, FMT="('Last status change time:', T30, A19)") CTIME(buff(11))
10306 WRITE (*, FMT="('Preferred block size:', T30, I19)") buff(12)
10307 WRITE (*, FMT="('No. of blocks allocated:', T30, I19)") buff(13)
10312 @item @emph{See also}:
10313 To stat an open file: @ref{FSTAT}, to stat a link: @ref{LSTAT}
10319 @section @code{SUM} --- Sum of array elements
10322 @cindex array, add elements
10323 @cindex array, conditionally add elements
10324 @cindex sum array elements
10327 @item @emph{Description}:
10328 Adds the elements of @var{ARRAY} along dimension @var{DIM} if
10329 the corresponding element in @var{MASK} is @code{TRUE}.
10331 @item @emph{Standard}:
10332 Fortran 95 and later
10334 @item @emph{Class}:
10335 Transformational function
10337 @item @emph{Syntax}:
10338 @multitable @columnfractions .80
10339 @item @code{RESULT = SUM(ARRAY[, MASK])}
10340 @item @code{RESULT = SUM(ARRAY, DIM[, MASK])}
10343 @item @emph{Arguments}:
10344 @multitable @columnfractions .15 .70
10345 @item @var{ARRAY} @tab Shall be an array of type @code{INTEGER},
10346 @code{REAL} or @code{COMPLEX}.
10347 @item @var{DIM} @tab (Optional) shall be a scalar of type
10348 @code{INTEGER} with a value in the range from 1 to n, where n
10349 equals the rank of @var{ARRAY}.
10350 @item @var{MASK} @tab (Optional) shall be of type @code{LOGICAL}
10351 and either be a scalar or an array of the same shape as @var{ARRAY}.
10354 @item @emph{Return value}:
10355 The result is of the same type as @var{ARRAY}.
10357 If @var{DIM} is absent, a scalar with the sum of all elements in @var{ARRAY}
10358 is returned. Otherwise, an array of rank n-1, where n equals the rank of
10359 @var{ARRAY},and a shape similar to that of @var{ARRAY} with dimension @var{DIM}
10360 dropped is returned.
10362 @item @emph{Example}:
10365 INTEGER :: x(5) = (/ 1, 2, 3, 4 ,5 /)
10366 print *, SUM(x) ! all elements, sum = 15
10367 print *, SUM(x, MASK=MOD(x, 2)==1) ! odd elements, sum = 9
10371 @item @emph{See also}:
10378 @section @code{SYMLNK} --- Create a symbolic link
10380 @cindex file system, create link
10381 @cindex file system, soft link
10384 @item @emph{Description}:
10385 Makes a symbolic link from file @var{PATH1} to @var{PATH2}. A null
10386 character (@code{CHAR(0)}) can be used to mark the end of the names in
10387 @var{PATH1} and @var{PATH2}; otherwise, trailing blanks in the file
10388 names are ignored. If the @var{STATUS} argument is supplied, it
10389 contains 0 on success or a nonzero error code upon return; see
10390 @code{symlink(2)}. If the system does not supply @code{symlink(2)},
10391 @code{ENOSYS} is returned.
10393 This intrinsic is provided in both subroutine and function forms;
10394 however, only one form can be used in any given program unit.
10396 @item @emph{Standard}:
10399 @item @emph{Class}:
10400 Subroutine, function
10402 @item @emph{Syntax}:
10403 @multitable @columnfractions .80
10404 @item @code{CALL SYMLNK(PATH1, PATH2 [, STATUS])}
10405 @item @code{STATUS = SYMLNK(PATH1, PATH2)}
10408 @item @emph{Arguments}:
10409 @multitable @columnfractions .15 .70
10410 @item @var{PATH1} @tab Shall be of default @code{CHARACTER} type.
10411 @item @var{PATH2} @tab Shall be of default @code{CHARACTER} type.
10412 @item @var{STATUS} @tab (Optional) Shall be of default @code{INTEGER} type.
10415 @item @emph{See also}:
10416 @ref{LINK}, @ref{UNLINK}
10423 @section @code{SYSTEM} --- Execute a shell command
10425 @cindex system, system call
10428 @item @emph{Description}:
10429 Passes the command @var{COMMAND} to a shell (see @code{system(3)}). If
10430 argument @var{STATUS} is present, it contains the value returned by
10431 @code{system(3)}, which is presumably 0 if the shell command succeeded.
10432 Note that which shell is used to invoke the command is system-dependent
10433 and environment-dependent.
10435 This intrinsic is provided in both subroutine and function forms;
10436 however, only one form can be used in any given program unit.
10438 @item @emph{Standard}:
10441 @item @emph{Class}:
10442 Subroutine, function
10444 @item @emph{Syntax}:
10445 @multitable @columnfractions .80
10446 @item @code{CALL SYSTEM(COMMAND [, STATUS])}
10447 @item @code{STATUS = SYSTEM(COMMAND)}
10450 @item @emph{Arguments}:
10451 @multitable @columnfractions .15 .70
10452 @item @var{COMMAND} @tab Shall be of default @code{CHARACTER} type.
10453 @item @var{STATUS} @tab (Optional) Shall be of default @code{INTEGER} type.
10456 @item @emph{See also}:
10462 @section @code{SYSTEM_CLOCK} --- Time function
10463 @fnindex SYSTEM_CLOCK
10464 @cindex time, clock ticks
10465 @cindex clock ticks
10468 @item @emph{Description}:
10469 Determines the @var{COUNT} of milliseconds of wall clock time since
10470 the Epoch (00:00:00 UTC, January 1, 1970) modulo @var{COUNT_MAX},
10471 @var{COUNT_RATE} determines the number of clock ticks per second.
10472 @var{COUNT_RATE} and @var{COUNT_MAX} are constant and specific to
10473 @command{gfortran}.
10475 If there is no clock, @var{COUNT} is set to @code{-HUGE(COUNT)}, and
10476 @var{COUNT_RATE} and @var{COUNT_MAX} are set to zero
10478 @item @emph{Standard}:
10479 Fortran 95 and later
10481 @item @emph{Class}:
10484 @item @emph{Syntax}:
10485 @code{CALL SYSTEM_CLOCK([COUNT, COUNT_RATE, COUNT_MAX])}
10487 @item @emph{Arguments}:
10488 @item @emph{Arguments}:
10489 @multitable @columnfractions .15 .70
10490 @item @var{COUNT} @tab (Optional) shall be a scalar of type default
10491 @code{INTEGER} with @code{INTENT(OUT)}.
10492 @item @var{COUNT_RATE} @tab (Optional) shall be a scalar of type default
10493 @code{INTEGER} with @code{INTENT(OUT)}.
10494 @item @var{COUNT_MAX} @tab (Optional) shall be a scalar of type default
10495 @code{INTEGER} with @code{INTENT(OUT)}.
10498 @item @emph{Example}:
10500 PROGRAM test_system_clock
10501 INTEGER :: count, count_rate, count_max
10502 CALL SYSTEM_CLOCK(count, count_rate, count_max)
10503 WRITE(*,*) count, count_rate, count_max
10507 @item @emph{See also}:
10508 @ref{DATE_AND_TIME}, @ref{CPU_TIME}
10514 @section @code{TAN} --- Tangent function
10517 @cindex trigonometric function, tangent
10521 @item @emph{Description}:
10522 @code{TAN(X)} computes the tangent of @var{X}.
10524 @item @emph{Standard}:
10525 Fortran 77 and later, for a complex argument Fortran 2008 or later
10527 @item @emph{Class}:
10530 @item @emph{Syntax}:
10531 @code{RESULT = TAN(X)}
10533 @item @emph{Arguments}:
10534 @multitable @columnfractions .15 .70
10535 @item @var{X} @tab The type shall be @code{REAL} or @code{COMPLEX}.
10538 @item @emph{Return value}:
10539 The return value has same type and kind as @var{X}.
10541 @item @emph{Example}:
10544 real(8) :: x = 0.165_8
10546 end program test_tan
10549 @item @emph{Specific names}:
10550 @multitable @columnfractions .20 .20 .20 .25
10551 @item Name @tab Argument @tab Return type @tab Standard
10552 @item @code{DTAN(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab Fortran 95 and later
10555 @item @emph{See also}:
10562 @section @code{TANH} --- Hyperbolic tangent function
10565 @cindex hyperbolic tangent
10566 @cindex hyperbolic function, tangent
10567 @cindex tangent, hyperbolic
10570 @item @emph{Description}:
10571 @code{TANH(X)} computes the hyperbolic tangent of @var{X}.
10573 @item @emph{Standard}:
10574 Fortran 77 and later, for a complex argument Fortran 2008 or later
10576 @item @emph{Class}:
10579 @item @emph{Syntax}:
10582 @item @emph{Arguments}:
10583 @multitable @columnfractions .15 .70
10584 @item @var{X} @tab The type shall be @code{REAL} or @code{COMPLEX}.
10587 @item @emph{Return value}:
10588 The return value has same type and kind as @var{X}. If @var{X} is
10589 complex, the imaginary part of the result is in radians. If @var{X}
10590 is @code{REAL}, the return value lies in the range
10591 @math{ - 1 \leq tanh(x) \leq 1 }.
10593 @item @emph{Example}:
10596 real(8) :: x = 2.1_8
10598 end program test_tanh
10601 @item @emph{Specific names}:
10602 @multitable @columnfractions .20 .20 .20 .25
10603 @item Name @tab Argument @tab Return type @tab Standard
10604 @item @code{DTANH(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab Fortran 95 and later
10607 @item @emph{See also}:
10614 @section @code{TIME} --- Time function
10616 @cindex time, current
10617 @cindex current time
10620 @item @emph{Description}:
10621 Returns the current time encoded as an integer (in the manner of the
10622 UNIX function @code{time(3)}). This value is suitable for passing to
10623 @code{CTIME()}, @code{GMTIME()}, and @code{LTIME()}.
10625 This intrinsic is not fully portable, such as to systems with 32-bit
10626 @code{INTEGER} types but supporting times wider than 32 bits. Therefore,
10627 the values returned by this intrinsic might be, or become, negative, or
10628 numerically less than previous values, during a single run of the
10631 See @ref{TIME8}, for information on a similar intrinsic that might be
10632 portable to more GNU Fortran implementations, though to fewer Fortran
10635 @item @emph{Standard}:
10638 @item @emph{Class}:
10641 @item @emph{Syntax}:
10642 @code{RESULT = TIME()}
10644 @item @emph{Return value}:
10645 The return value is a scalar of type @code{INTEGER(4)}.
10647 @item @emph{See also}:
10648 @ref{CTIME}, @ref{GMTIME}, @ref{LTIME}, @ref{MCLOCK}, @ref{TIME8}
10655 @section @code{TIME8} --- Time function (64-bit)
10657 @cindex time, current
10658 @cindex current time
10661 @item @emph{Description}:
10662 Returns the current time encoded as an integer (in the manner of the
10663 UNIX function @code{time(3)}). This value is suitable for passing to
10664 @code{CTIME()}, @code{GMTIME()}, and @code{LTIME()}.
10666 @emph{Warning:} this intrinsic does not increase the range of the timing
10667 values over that returned by @code{time(3)}. On a system with a 32-bit
10668 @code{time(3)}, @code{TIME8()} will return a 32-bit value, even though
10669 it is converted to a 64-bit @code{INTEGER(8)} value. That means
10670 overflows of the 32-bit value can still occur. Therefore, the values
10671 returned by this intrinsic might be or become negative or numerically
10672 less than previous values during a single run of the compiled program.
10674 @item @emph{Standard}:
10677 @item @emph{Class}:
10680 @item @emph{Syntax}:
10681 @code{RESULT = TIME8()}
10683 @item @emph{Return value}:
10684 The return value is a scalar of type @code{INTEGER(8)}.
10686 @item @emph{See also}:
10687 @ref{CTIME}, @ref{GMTIME}, @ref{LTIME}, @ref{MCLOCK8}, @ref{TIME}
10694 @section @code{TINY} --- Smallest positive number of a real kind
10696 @cindex limits, smallest number
10697 @cindex model representation, smallest number
10700 @item @emph{Description}:
10701 @code{TINY(X)} returns the smallest positive (non zero) number
10702 in the model of the type of @code{X}.
10704 @item @emph{Standard}:
10705 Fortran 95 and later
10707 @item @emph{Class}:
10710 @item @emph{Syntax}:
10711 @code{RESULT = TINY(X)}
10713 @item @emph{Arguments}:
10714 @multitable @columnfractions .15 .70
10715 @item @var{X} @tab Shall be of type @code{REAL}.
10718 @item @emph{Return value}:
10719 The return value is of the same type and kind as @var{X}
10721 @item @emph{Example}:
10722 See @code{HUGE} for an example.
10728 @section @code{TRAILZ} --- Number of trailing zero bits of an integer
10733 @item @emph{Description}:
10734 @code{TRAILZ} returns the number of trailing zero bits of an integer.
10736 @item @emph{Standard}:
10737 Fortran 2008 and later
10739 @item @emph{Class}:
10742 @item @emph{Syntax}:
10743 @code{RESULT = TRAILZ(I)}
10745 @item @emph{Arguments}:
10746 @multitable @columnfractions .15 .70
10747 @item @var{I} @tab Shall be of type @code{INTEGER}.
10750 @item @emph{Return value}:
10751 The type of the return value is the default @code{INTEGER}.
10752 If all the bits of @code{I} are zero, the result value is @code{BIT_SIZE(I)}.
10754 @item @emph{Example}:
10756 PROGRAM test_trailz
10757 WRITE (*,*) TRAILZ(8) ! prints 3
10761 @item @emph{See also}:
10762 @ref{BIT_SIZE}, @ref{LEADZ}
10768 @section @code{TRANSFER} --- Transfer bit patterns
10774 @item @emph{Description}:
10775 Interprets the bitwise representation of @var{SOURCE} in memory as if it
10776 is the representation of a variable or array of the same type and type
10777 parameters as @var{MOLD}.
10779 This is approximately equivalent to the C concept of @emph{casting} one
10782 @item @emph{Standard}:
10783 Fortran 95 and later
10785 @item @emph{Class}:
10786 Transformational function
10788 @item @emph{Syntax}:
10789 @code{RESULT = TRANSFER(SOURCE, MOLD[, SIZE])}
10791 @item @emph{Arguments}:
10792 @multitable @columnfractions .15 .70
10793 @item @var{SOURCE} @tab Shall be a scalar or an array of any type.
10794 @item @var{MOLD} @tab Shall be a scalar or an array of any type.
10795 @item @var{SIZE} @tab (Optional) shall be a scalar of type
10799 @item @emph{Return value}:
10800 The result has the same type as @var{MOLD}, with the bit level
10801 representation of @var{SOURCE}. If @var{SIZE} is present, the result is
10802 a one-dimensional array of length @var{SIZE}. If @var{SIZE} is absent
10803 but @var{MOLD} is an array (of any size or shape), the result is a one-
10804 dimensional array of the minimum length needed to contain the entirety
10805 of the bitwise representation of @var{SOURCE}. If @var{SIZE} is absent
10806 and @var{MOLD} is a scalar, the result is a scalar.
10808 If the bitwise representation of the result is longer than that of
10809 @var{SOURCE}, then the leading bits of the result correspond to those of
10810 @var{SOURCE} and any trailing bits are filled arbitrarily.
10812 When the resulting bit representation does not correspond to a valid
10813 representation of a variable of the same type as @var{MOLD}, the results
10814 are undefined, and subsequent operations on the result cannot be
10815 guaranteed to produce sensible behavior. For example, it is possible to
10816 create @code{LOGICAL} variables for which @code{@var{VAR}} and
10817 @code{.NOT.@var{VAR}} both appear to be true.
10819 @item @emph{Example}:
10821 PROGRAM test_transfer
10822 integer :: x = 2143289344
10823 print *, transfer(x, 1.0) ! prints "NaN" on i686
10831 @section @code{TRANSPOSE} --- Transpose an array of rank two
10833 @cindex array, transpose
10834 @cindex matrix, transpose
10838 @item @emph{Description}:
10839 Transpose an array of rank two. Element (i, j) of the result has the value
10840 @code{MATRIX(j, i)}, for all i, j.
10842 @item @emph{Standard}:
10843 Fortran 95 and later
10845 @item @emph{Class}:
10846 Transformational function
10848 @item @emph{Syntax}:
10849 @code{RESULT = TRANSPOSE(MATRIX)}
10851 @item @emph{Arguments}:
10852 @multitable @columnfractions .15 .70
10853 @item @var{MATRIX} @tab Shall be an array of any type and have a rank of two.
10856 @item @emph{Return value}:
10857 The result has the same type as @var{MATRIX}, and has shape
10858 @code{(/ m, n /)} if @var{MATRIX} has shape @code{(/ n, m /)}.
10864 @section @code{TRIM} --- Remove trailing blank characters of a string
10866 @cindex string, remove trailing whitespace
10869 @item @emph{Description}:
10870 Removes trailing blank characters of a string.
10872 @item @emph{Standard}:
10873 Fortran 95 and later
10875 @item @emph{Class}:
10876 Transformational function
10878 @item @emph{Syntax}:
10879 @code{RESULT = TRIM(STRING)}
10881 @item @emph{Arguments}:
10882 @multitable @columnfractions .15 .70
10883 @item @var{STRING} @tab Shall be a scalar of type @code{CHARACTER}.
10886 @item @emph{Return value}:
10887 A scalar of type @code{CHARACTER} which length is that of @var{STRING}
10888 less the number of trailing blanks.
10890 @item @emph{Example}:
10893 CHARACTER(len=10), PARAMETER :: s = "GFORTRAN "
10894 WRITE(*,*) LEN(s), LEN(TRIM(s)) ! "10 8", with/without trailing blanks
10898 @item @emph{See also}:
10899 @ref{ADJUSTL}, @ref{ADJUSTR}
10905 @section @code{TTYNAM} --- Get the name of a terminal device.
10907 @cindex system, terminal
10910 @item @emph{Description}:
10911 Get the name of a terminal device. For more information,
10912 see @code{ttyname(3)}.
10914 This intrinsic is provided in both subroutine and function forms;
10915 however, only one form can be used in any given program unit.
10917 @item @emph{Standard}:
10920 @item @emph{Class}:
10921 Subroutine, function
10923 @item @emph{Syntax}:
10924 @multitable @columnfractions .80
10925 @item @code{CALL TTYNAM(UNIT, NAME)}
10926 @item @code{NAME = TTYNAM(UNIT)}
10929 @item @emph{Arguments}:
10930 @multitable @columnfractions .15 .70
10931 @item @var{UNIT} @tab Shall be a scalar @code{INTEGER}.
10932 @item @var{NAME} @tab Shall be of type @code{CHARACTER}.
10935 @item @emph{Example}:
10937 PROGRAM test_ttynam
10940 IF (isatty(unit=unit)) write(*,*) ttynam(unit)
10945 @item @emph{See also}:
10952 @section @code{UBOUND} --- Upper dimension bounds of an array
10954 @cindex array, upper bound
10957 @item @emph{Description}:
10958 Returns the upper bounds of an array, or a single upper bound
10959 along the @var{DIM} dimension.
10960 @item @emph{Standard}:
10961 Fortran 95 and later, with @var{KIND} argument Fortran 2003 and later
10963 @item @emph{Class}:
10966 @item @emph{Syntax}:
10967 @code{RESULT = UBOUND(ARRAY [, DIM [, KIND]])}
10969 @item @emph{Arguments}:
10970 @multitable @columnfractions .15 .70
10971 @item @var{ARRAY} @tab Shall be an array, of any type.
10972 @item @var{DIM} @tab (Optional) Shall be a scalar @code{INTEGER}.
10973 @item @var{KIND}@tab (Optional) An @code{INTEGER} initialization
10974 expression indicating the kind parameter of the result.
10977 @item @emph{Return value}:
10978 The return value is of type @code{INTEGER} and of kind @var{KIND}. If
10979 @var{KIND} is absent, the return value is of default integer kind.
10980 If @var{DIM} is absent, the result is an array of the upper bounds of
10981 @var{ARRAY}. If @var{DIM} is present, the result is a scalar
10982 corresponding to the upper bound of the array along that dimension. If
10983 @var{ARRAY} is an expression rather than a whole array or array
10984 structure component, or if it has a zero extent along the relevant
10985 dimension, the upper bound is taken to be the number of elements along
10986 the relevant dimension.
10988 @item @emph{See also}:
10995 @section @code{UMASK} --- Set the file creation mask
10997 @cindex file system, file creation mask
11000 @item @emph{Description}:
11001 Sets the file creation mask to @var{MASK}. If called as a function, it
11002 returns the old value. If called as a subroutine and argument @var{OLD}
11003 if it is supplied, it is set to the old value. See @code{umask(2)}.
11005 @item @emph{Standard}:
11008 @item @emph{Class}:
11009 Subroutine, function
11011 @item @emph{Syntax}:
11012 @code{CALL UMASK(MASK [, OLD])}
11013 @code{OLD = UMASK(MASK)}
11015 @item @emph{Arguments}:
11016 @multitable @columnfractions .15 .70
11017 @item @var{MASK} @tab Shall be a scalar of type @code{INTEGER}.
11018 @item @var{OLD} @tab (Optional) Shall be a scalar of type
11027 @section @code{UNLINK} --- Remove a file from the file system
11029 @cindex file system, remove file
11032 @item @emph{Description}:
11033 Unlinks the file @var{PATH}. A null character (@code{CHAR(0)}) can be
11034 used to mark the end of the name in @var{PATH}; otherwise, trailing
11035 blanks in the file name are ignored. If the @var{STATUS} argument is
11036 supplied, it contains 0 on success or a nonzero error code upon return;
11037 see @code{unlink(2)}.
11039 This intrinsic is provided in both subroutine and function forms;
11040 however, only one form can be used in any given program unit.
11042 @item @emph{Standard}:
11045 @item @emph{Class}:
11046 Subroutine, function
11048 @item @emph{Syntax}:
11049 @multitable @columnfractions .80
11050 @item @code{CALL UNLINK(PATH [, STATUS])}
11051 @item @code{STATUS = UNLINK(PATH)}
11054 @item @emph{Arguments}:
11055 @multitable @columnfractions .15 .70
11056 @item @var{PATH} @tab Shall be of default @code{CHARACTER} type.
11057 @item @var{STATUS} @tab (Optional) Shall be of default @code{INTEGER} type.
11060 @item @emph{See also}:
11061 @ref{LINK}, @ref{SYMLNK}
11067 @section @code{UNPACK} --- Unpack an array of rank one into an array
11069 @cindex array, unpacking
11070 @cindex array, increase dimension
11071 @cindex array, scatter elements
11074 @item @emph{Description}:
11075 Store the elements of @var{VECTOR} in an array of higher rank.
11077 @item @emph{Standard}:
11078 Fortran 95 and later
11080 @item @emph{Class}:
11081 Transformational function
11083 @item @emph{Syntax}:
11084 @code{RESULT = UNPACK(VECTOR, MASK, FIELD)}
11086 @item @emph{Arguments}:
11087 @multitable @columnfractions .15 .70
11088 @item @var{VECTOR} @tab Shall be an array of any type and rank one. It
11089 shall have at least as many elements as @var{MASK} has @code{TRUE} values.
11090 @item @var{MASK} @tab Shall be an array of type @code{LOGICAL}.
11091 @item @var{FIELD} @tab Shall be of the same type as @var{VECTOR} and have
11092 the same shape as @var{MASK}.
11095 @item @emph{Return value}:
11096 The resulting array corresponds to @var{FIELD} with @code{TRUE} elements
11097 of @var{MASK} replaced by values from @var{VECTOR} in array element order.
11099 @item @emph{Example}:
11101 PROGRAM test_unpack
11102 integer :: vector(2) = (/1,1/)
11103 logical :: mask(4) = (/ .TRUE., .FALSE., .FALSE., .TRUE. /)
11104 integer :: field(2,2) = 0, unity(2,2)
11106 ! result: unity matrix
11107 unity = unpack(vector, reshape(mask, (/2,2/)), field)
11111 @item @emph{See also}:
11112 @ref{PACK}, @ref{SPREAD}
11118 @section @code{VERIFY} --- Scan a string for the absence of a set of characters
11120 @cindex string, find missing set
11123 @item @emph{Description}:
11124 Verifies that all the characters in a @var{SET} are present in a @var{STRING}.
11126 If @var{BACK} is either absent or equals @code{FALSE}, this function
11127 returns the position of the leftmost character of @var{STRING} that is
11128 not in @var{SET}. If @var{BACK} equals @code{TRUE}, the rightmost position
11129 is returned. If all characters of @var{SET} are found in @var{STRING}, the
11132 @item @emph{Standard}:
11133 Fortran 95 and later, with @var{KIND} argument Fortran 2003 and later
11135 @item @emph{Class}:
11138 @item @emph{Syntax}:
11139 @code{RESULT = VERIFY(STRING, SET[, BACK [, KIND]])}
11141 @item @emph{Arguments}:
11142 @multitable @columnfractions .15 .70
11143 @item @var{STRING} @tab Shall be of type @code{CHARACTER}.
11144 @item @var{SET} @tab Shall be of type @code{CHARACTER}.
11145 @item @var{BACK} @tab (Optional) shall be of type @code{LOGICAL}.
11146 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
11147 expression indicating the kind parameter of the result.
11150 @item @emph{Return value}:
11151 The return value is of type @code{INTEGER} and of kind @var{KIND}. If
11152 @var{KIND} is absent, the return value is of default integer kind.
11154 @item @emph{Example}:
11156 PROGRAM test_verify
11157 WRITE(*,*) VERIFY("FORTRAN", "AO") ! 1, found 'F'
11158 WRITE(*,*) VERIFY("FORTRAN", "FOO") ! 3, found 'R'
11159 WRITE(*,*) VERIFY("FORTRAN", "C++") ! 1, found 'F'
11160 WRITE(*,*) VERIFY("FORTRAN", "C++", .TRUE.) ! 7, found 'N'
11161 WRITE(*,*) VERIFY("FORTRAN", "FORTRAN") ! 0' found none
11165 @item @emph{See also}:
11166 @ref{SCAN}, @ref{INDEX intrinsic}
11172 @section @code{XOR} --- Bitwise logical exclusive OR
11174 @cindex bitwise logical exclusive or
11175 @cindex logical exclusive or, bitwise
11178 @item @emph{Description}:
11179 Bitwise logical exclusive or.
11181 This intrinsic routine is provided for backwards compatibility with
11182 GNU Fortran 77. For integer arguments, programmers should consider
11183 the use of the @ref{IEOR} intrinsic and for logical arguments the
11184 @code{.NEQV.} operator, which are both defined by the Fortran standard.
11186 @item @emph{Standard}:
11189 @item @emph{Class}:
11192 @item @emph{Syntax}:
11193 @code{RESULT = XOR(I, J)}
11195 @item @emph{Arguments}:
11196 @multitable @columnfractions .15 .70
11197 @item @var{I} @tab The type shall be either a scalar @code{INTEGER}
11198 type or a scalar @code{LOGICAL} type.
11199 @item @var{J} @tab The type shall be the same as the type of @var{I}.
11202 @item @emph{Return value}:
11203 The return type is either a scalar @code{INTEGER} or a scalar
11204 @code{LOGICAL}. If the kind type parameters differ, then the
11205 smaller kind type is implicitly converted to larger kind, and the
11206 return has the larger kind.
11208 @item @emph{Example}:
11211 LOGICAL :: T = .TRUE., F = .FALSE.
11213 DATA a / Z'F' /, b / Z'3' /
11215 WRITE (*,*) XOR(T, T), XOR(T, F), XOR(F, T), XOR(F, F)
11216 WRITE (*,*) XOR(a, b)
11220 @item @emph{See also}:
11221 Fortran 95 elemental function: @ref{IEOR}
11226 @node Intrinsic Modules
11227 @chapter Intrinsic Modules
11228 @cindex intrinsic Modules
11231 * ISO_FORTRAN_ENV::
11233 * OpenMP Modules OMP_LIB and OMP_LIB_KINDS::
11236 @node ISO_FORTRAN_ENV
11237 @section @code{ISO_FORTRAN_ENV}
11239 @item @emph{Standard}:
11240 Fortran 2003 and later; @code{INT8}, @code{INT16}, @code{INT32}, @code{INT64},
11241 @code{REAL32}, @code{REAL64}, @code{REAL128} are Fortran 2008 or later
11244 The @code{ISO_FORTRAN_ENV} module provides the following scalar default-integer
11248 @item @code{CHARACTER_STORAGE_SIZE}:
11249 Size in bits of the character storage unit.
11251 @item @code{ERROR_UNIT}:
11252 Identifies the preconnected unit used for error reporting.
11254 @item @code{FILE_STORAGE_SIZE}:
11255 Size in bits of the file-storage unit.
11257 @item @code{INPUT_UNIT}:
11258 Identifies the preconnected unit identified by the asterisk
11259 (@code{*}) in @code{READ} statement.
11261 @item @code{INT8}, @code{INT16}, @code{INT32}, @code{INT64}
11262 Kind type parameters to specify an INTEGER type with a storage
11263 size of 16, 32, and 64 bits. It is negative if a target platform
11264 does not support the particular kind.
11266 @item @code{IOSTAT_END}:
11267 The value assigned to the variable passed to the IOSTAT= specifier of
11268 an input/output statement if an end-of-file condition occurred.
11270 @item @code{IOSTAT_EOR}:
11271 The value assigned to the variable passed to the IOSTAT= specifier of
11272 an input/output statement if an end-of-record condition occurred.
11274 @item @code{NUMERIC_STORAGE_SIZE}:
11275 The size in bits of the numeric storage unit.
11277 @item @code{OUTPUT_UNIT}:
11278 Identifies the preconnected unit identified by the asterisk
11279 (@code{*}) in @code{WRITE} statement.
11281 @item @code{REAL32}, @code{REAL64}, @code{REAL128}
11282 Kind type parameters to specify a REAL type with a storage
11283 size of 32, 64, and 128 bits. It is negative if a target platform
11284 does not support the particular kind.
11289 @node ISO_C_BINDING
11290 @section @code{ISO_C_BINDING}
11292 @item @emph{Standard}:
11293 Fortran 2003 and later, GNU extensions
11296 The following intrinsic procedures are provided by the module; their
11297 definition can be found in the section Intrinsic Procedures of this
11301 @item @code{C_ASSOCIATED}
11302 @item @code{C_F_POINTER}
11303 @item @code{C_F_PROCPOINTER}
11304 @item @code{C_FUNLOC}
11307 @c TODO: Vertical spacing between C_FUNLOC and C_LOC wrong in PDF,
11308 @c don't really know why.
11310 The @code{ISO_C_BINDING} module provides the following named constants of
11311 type default integer, which can be used as KIND type parameters.
11313 In addition to the integer named constants required by the Fortran 2003
11314 standard, GNU Fortran provides as an extension named constants for the
11315 128-bit integer types supported by the C compiler: @code{C_INT128_T,
11316 C_INT_LEAST128_T, C_INT_FAST128_T}.
11318 @multitable @columnfractions .15 .35 .35 .35
11319 @item Fortran Type @tab Named constant @tab C type @tab Extension
11320 @item @code{INTEGER}@tab @code{C_INT} @tab @code{int}
11321 @item @code{INTEGER}@tab @code{C_SHORT} @tab @code{short int}
11322 @item @code{INTEGER}@tab @code{C_LONG} @tab @code{long int}
11323 @item @code{INTEGER}@tab @code{C_LONG_LONG} @tab @code{long long int}
11324 @item @code{INTEGER}@tab @code{C_SIGNED_CHAR} @tab @code{signed char}/@code{unsigned char}
11325 @item @code{INTEGER}@tab @code{C_SIZE_T} @tab @code{size_t}
11326 @item @code{INTEGER}@tab @code{C_INT8_T} @tab @code{int8_t}
11327 @item @code{INTEGER}@tab @code{C_INT16_T} @tab @code{int16_t}
11328 @item @code{INTEGER}@tab @code{C_INT32_T} @tab @code{int32_t}
11329 @item @code{INTEGER}@tab @code{C_INT64_T} @tab @code{int64_t}
11330 @item @code{INTEGER}@tab @code{C_INT128_T} @tab @code{int128_t} @tab Ext.
11331 @item @code{INTEGER}@tab @code{C_INT_LEAST8_T} @tab @code{int_least8_t}
11332 @item @code{INTEGER}@tab @code{C_INT_LEAST16_T} @tab @code{int_least16_t}
11333 @item @code{INTEGER}@tab @code{C_INT_LEAST32_T} @tab @code{int_least32_t}
11334 @item @code{INTEGER}@tab @code{C_INT_LEAST64_T} @tab @code{int_least64_t}
11335 @item @code{INTEGER}@tab @code{C_INT_LEAST128_T}@tab @code{int_least128_t} @tab Ext.
11336 @item @code{INTEGER}@tab @code{C_INT_FAST8_T} @tab @code{int_fast8_t}
11337 @item @code{INTEGER}@tab @code{C_INT_FAST16_T} @tab @code{int_fast16_t}
11338 @item @code{INTEGER}@tab @code{C_INT_FAST32_T} @tab @code{int_fast32_t}
11339 @item @code{INTEGER}@tab @code{C_INT_FAST64_T} @tab @code{int_fast64_t}
11340 @item @code{INTEGER}@tab @code{C_INT_FAST128_T} @tab @code{int_fast128_t} @tab Ext.
11341 @item @code{INTEGER}@tab @code{C_INTMAX_T} @tab @code{intmax_t}
11342 @item @code{INTEGER}@tab @code{C_INTPTR_T} @tab @code{intptr_t}
11343 @item @code{REAL} @tab @code{C_FLOAT} @tab @code{float}
11344 @item @code{REAL} @tab @code{C_DOUBLE} @tab @code{double}
11345 @item @code{REAL} @tab @code{C_LONG_DOUBLE} @tab @code{long double}
11346 @item @code{COMPLEX}@tab @code{C_FLOAT_COMPLEX} @tab @code{float _Complex}
11347 @item @code{COMPLEX}@tab @code{C_DOUBLE_COMPLEX}@tab @code{double _Complex}
11348 @item @code{COMPLEX}@tab @code{C_LONG_DOUBLE_COMPLEX}@tab @code{long double _Complex}
11349 @item @code{LOGICAL}@tab @code{C_BOOL} @tab @code{_Bool}
11350 @item @code{CHARACTER}@tab @code{C_CHAR} @tab @code{char}
11353 Additionally, the following parameters of type @code{CHARACTER(KIND=C_CHAR)}
11356 @multitable @columnfractions .20 .45 .15
11357 @item Name @tab C definition @tab Value
11358 @item @code{C_NULL_CHAR} @tab null character @tab @code{'\0'}
11359 @item @code{C_ALERT} @tab alert @tab @code{'\a'}
11360 @item @code{C_BACKSPACE} @tab backspace @tab @code{'\b'}
11361 @item @code{C_FORM_FEED} @tab form feed @tab @code{'\f'}
11362 @item @code{C_NEW_LINE} @tab new line @tab @code{'\n'}
11363 @item @code{C_CARRIAGE_RETURN} @tab carriage return @tab @code{'\r'}
11364 @item @code{C_HORIZONTAL_TAB} @tab horizontal tab @tab @code{'\t'}
11365 @item @code{C_VERTICAL_TAB} @tab vertical tab @tab @code{'\v'}
11368 @node OpenMP Modules OMP_LIB and OMP_LIB_KINDS
11369 @section OpenMP Modules @code{OMP_LIB} and @code{OMP_LIB_KINDS}
11371 @item @emph{Standard}:
11372 OpenMP Application Program Interface v3.0
11376 The OpenMP Fortran runtime library routines are provided both in
11377 a form of two Fortran 90 modules, named @code{OMP_LIB} and
11378 @code{OMP_LIB_KINDS}, and in a form of a Fortran @code{include} file named
11379 @file{omp_lib.h}. The procedures provided by @code{OMP_LIB} can be found
11380 in the @ref{Top,,Introduction,libgomp,GNU OpenMP runtime library} manual,
11381 the named constants defined in the @code{OMP_LIB_KINDS} module are listed
11384 For details refer to the actual
11385 @uref{http://www.openmp.org/mp-documents/spec30.pdf,
11386 OpenMP Application Program Interface v3.0}.
11388 @code{OMP_LIB_KINDS} provides the following scalar default-integer
11392 @item @code{omp_integer_kind}
11393 @item @code{omp_logical_kind}
11394 @item @code{omp_lock_kind}
11395 @item @code{omp_nest_lock_kind}
11396 @item @code{omp_sched_kind}