2 Copyright (C) 2005, 2006, 2007, 2008, 2009, 2010
3 Free Software Foundation, Inc.
4 This is part of the GNU Fortran manual.
5 For copying conditions, see the file gfortran.texi.
7 Permission is granted to copy, distribute and/or modify this document
8 under the terms of the GNU Free Documentation License, Version 1.3 or
9 any later version published by the Free Software Foundation; with the
10 Invariant Sections being ``Funding Free Software'', the Front-Cover
11 Texts being (a) (see below), and with the Back-Cover Texts being (b)
12 (see below). A copy of the license is included in the gfdl(7) man page.
15 Some basic guidelines for editing this document:
17 (1) The intrinsic procedures are to be listed in alphabetical order.
18 (2) The generic name is to be used.
19 (3) The specific names are included in the function index and in a
20 table at the end of the node (See ABS entry).
21 (4) Try to maintain the same style for each entry.
27 \gdef\acos{\mathop{\rm acos}\nolimits}
28 \gdef\asin{\mathop{\rm asin}\nolimits}
29 \gdef\atan{\mathop{\rm atan}\nolimits}
30 \gdef\acosh{\mathop{\rm acosh}\nolimits}
31 \gdef\asinh{\mathop{\rm asinh}\nolimits}
32 \gdef\atanh{\mathop{\rm atanh}\nolimits}
36 @node Intrinsic Procedures
37 @chapter Intrinsic Procedures
38 @cindex intrinsic procedures
41 * Introduction: Introduction to Intrinsics
42 * @code{ABORT}: ABORT, Abort the program
43 * @code{ABS}: ABS, Absolute value
44 * @code{ACCESS}: ACCESS, Checks file access modes
45 * @code{ACHAR}: ACHAR, Character in @acronym{ASCII} collating sequence
46 * @code{ACOS}: ACOS, Arccosine function
47 * @code{ACOSH}: ACOSH, Hyperbolic arccosine function
48 * @code{ADJUSTL}: ADJUSTL, Left adjust a string
49 * @code{ADJUSTR}: ADJUSTR, Right adjust a string
50 * @code{AIMAG}: AIMAG, Imaginary part of complex number
51 * @code{AINT}: AINT, Truncate to a whole number
52 * @code{ALARM}: ALARM, Set an alarm clock
53 * @code{ALL}: ALL, Determine if all values are true
54 * @code{ALLOCATED}: ALLOCATED, Status of allocatable entity
55 * @code{AND}: AND, Bitwise logical AND
56 * @code{ANINT}: ANINT, Nearest whole number
57 * @code{ANY}: ANY, Determine if any values are true
58 * @code{ASIN}: ASIN, Arcsine function
59 * @code{ASINH}: ASINH, Hyperbolic arcsine function
60 * @code{ASSOCIATED}: ASSOCIATED, Status of a pointer or pointer/target pair
61 * @code{ATAN}: ATAN, Arctangent function
62 * @code{ATAN2}: ATAN2, Arctangent function
63 * @code{ATANH}: ATANH, Hyperbolic arctangent function
64 * @code{BESSEL_J0}: BESSEL_J0, Bessel function of the first kind of order 0
65 * @code{BESSEL_J1}: BESSEL_J1, Bessel function of the first kind of order 1
66 * @code{BESSEL_JN}: BESSEL_JN, Bessel function of the first kind
67 * @code{BESSEL_Y0}: BESSEL_Y0, Bessel function of the second kind of order 0
68 * @code{BESSEL_Y1}: BESSEL_Y1, Bessel function of the second kind of order 1
69 * @code{BESSEL_YN}: BESSEL_YN, Bessel function of the second kind
70 * @code{BIT_SIZE}: BIT_SIZE, Bit size inquiry function
71 * @code{BTEST}: BTEST, Bit test function
72 * @code{C_ASSOCIATED}: C_ASSOCIATED, Status of a C pointer
73 * @code{C_F_POINTER}: C_F_POINTER, Convert C into Fortran pointer
74 * @code{C_F_PROCPOINTER}: C_F_PROCPOINTER, Convert C into Fortran procedure pointer
75 * @code{C_FUNLOC}: C_FUNLOC, Obtain the C address of a procedure
76 * @code{C_LOC}: C_LOC, Obtain the C address of an object
77 * @code{C_SIZEOF}: C_SIZEOF, Size in bytes of an expression
78 * @code{CEILING}: CEILING, Integer ceiling function
79 * @code{CHAR}: CHAR, Integer-to-character conversion function
80 * @code{CHDIR}: CHDIR, Change working directory
81 * @code{CHMOD}: CHMOD, Change access permissions of files
82 * @code{CMPLX}: CMPLX, Complex conversion function
83 * @code{COMMAND_ARGUMENT_COUNT}: COMMAND_ARGUMENT_COUNT, Get number of command line arguments
84 * @code{COMPLEX}: COMPLEX, Complex conversion function
85 * @code{CONJG}: CONJG, Complex conjugate function
86 * @code{COS}: COS, Cosine function
87 * @code{COSH}: COSH, Hyperbolic cosine function
88 * @code{COUNT}: COUNT, Count occurrences of TRUE in an array
89 * @code{CPU_TIME}: CPU_TIME, CPU time subroutine
90 * @code{CSHIFT}: CSHIFT, Circular shift elements of an array
91 * @code{CTIME}: CTIME, Subroutine (or function) to convert a time into a string
92 * @code{DATE_AND_TIME}: DATE_AND_TIME, Date and time subroutine
93 * @code{DBLE}: DBLE, Double precision conversion function
94 * @code{DCMPLX}: DCMPLX, Double complex conversion function
95 * @code{DIGITS}: DIGITS, Significant digits function
96 * @code{DIM}: DIM, Positive difference
97 * @code{DOT_PRODUCT}: DOT_PRODUCT, Dot product function
98 * @code{DPROD}: DPROD, Double product function
99 * @code{DREAL}: DREAL, Double real part function
100 * @code{DTIME}: DTIME, Execution time subroutine (or function)
101 * @code{EOSHIFT}: EOSHIFT, End-off shift elements of an array
102 * @code{EPSILON}: EPSILON, Epsilon function
103 * @code{ERF}: ERF, Error function
104 * @code{ERFC}: ERFC, Complementary error function
105 * @code{ERFC_SCALED}: ERFC_SCALED, Exponentially-scaled complementary error function
106 * @code{ETIME}: ETIME, Execution time subroutine (or function)
107 * @code{EXIT}: EXIT, Exit the program with status.
108 * @code{EXP}: EXP, Exponential function
109 * @code{EXPONENT}: EXPONENT, Exponent function
110 * @code{EXTENDS_TYPE_OF}: EXTENDS_TYPE_OF, Query dynamic type for extension
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{FLOOR}: FLOOR, Integer floor function
115 * @code{FLUSH}: FLUSH, Flush I/O unit(s)
116 * @code{FNUM}: FNUM, File number function
117 * @code{FPUT}: FPUT, Write a single character in stream mode to stdout
118 * @code{FPUTC}: FPUTC, Write a single character in stream mode
119 * @code{FRACTION}: FRACTION, Fractional part of the model representation
120 * @code{FREE}: FREE, Memory de-allocation subroutine
121 * @code{FSEEK}: FSEEK, Low level file positioning subroutine
122 * @code{FSTAT}: FSTAT, Get file status
123 * @code{FTELL}: FTELL, Current stream position
124 * @code{GAMMA}: GAMMA, Gamma function
125 * @code{GERROR}: GERROR, Get last system error message
126 * @code{GETARG}: GETARG, Get command line arguments
127 * @code{GET_COMMAND}: GET_COMMAND, Get the entire command line
128 * @code{GET_COMMAND_ARGUMENT}: GET_COMMAND_ARGUMENT, Get command line arguments
129 * @code{GETCWD}: GETCWD, Get current working directory
130 * @code{GETENV}: GETENV, Get an environmental variable
131 * @code{GET_ENVIRONMENT_VARIABLE}: GET_ENVIRONMENT_VARIABLE, Get an environmental variable
132 * @code{GETGID}: GETGID, Group ID function
133 * @code{GETLOG}: GETLOG, Get login name
134 * @code{GETPID}: GETPID, Process ID function
135 * @code{GETUID}: GETUID, User ID function
136 * @code{GMTIME}: GMTIME, Convert time to GMT info
137 * @code{HOSTNM}: HOSTNM, Get system host name
138 * @code{HUGE}: HUGE, Largest number of a kind
139 * @code{HYPOT}: HYPOT, Euclidian distance function
140 * @code{IACHAR}: IACHAR, Code in @acronym{ASCII} collating sequence
141 * @code{IAND}: IAND, Bitwise logical and
142 * @code{IARGC}: IARGC, Get the number of command line arguments
143 * @code{IBCLR}: IBCLR, Clear bit
144 * @code{IBITS}: IBITS, Bit extraction
145 * @code{IBSET}: IBSET, Set bit
146 * @code{ICHAR}: ICHAR, Character-to-integer conversion function
147 * @code{IDATE}: IDATE, Current local time (day/month/year)
148 * @code{IEOR}: IEOR, Bitwise logical exclusive or
149 * @code{IERRNO}: IERRNO, Function to get the last system error number
150 * @code{INDEX}: INDEX intrinsic, Position of a substring within a string
151 * @code{INT}: INT, Convert to integer type
152 * @code{INT2}: INT2, Convert to 16-bit integer type
153 * @code{INT8}: INT8, Convert to 64-bit integer type
154 * @code{IOR}: IOR, Bitwise logical or
155 * @code{IRAND}: IRAND, Integer pseudo-random number
156 * @code{IMAGE_INDEX}: IMAGE_INDEX, Cosubscript to image index convertion
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{LCOBOUND}: LCOBOUND, Lower codimension bounds of an array
168 * @code{LEADZ}: LEADZ, Number of leading zero bits of an integer
169 * @code{LEN}: LEN, Length of a character entity
170 * @code{LEN_TRIM}: LEN_TRIM, Length of a character entity without trailing blank characters
171 * @code{LGE}: LGE, Lexical greater than or equal
172 * @code{LGT}: LGT, Lexical greater than
173 * @code{LINK}: LINK, Create a hard link
174 * @code{LLE}: LLE, Lexical less than or equal
175 * @code{LLT}: LLT, Lexical less than
176 * @code{LNBLNK}: LNBLNK, Index of the last non-blank character in a string
177 * @code{LOC}: LOC, Returns the address of a variable
178 * @code{LOG}: LOG, Logarithm function
179 * @code{LOG10}: LOG10, Base 10 logarithm function
180 * @code{LOG_GAMMA}: LOG_GAMMA, Logarithm of the Gamma function
181 * @code{LOGICAL}: LOGICAL, Convert to logical type
182 * @code{LONG}: LONG, Convert to integer type
183 * @code{LSHIFT}: LSHIFT, Left shift bits
184 * @code{LSTAT}: LSTAT, Get file status
185 * @code{LTIME}: LTIME, Convert time to local time info
186 * @code{MALLOC}: MALLOC, Dynamic memory allocation function
187 * @code{MATMUL}: MATMUL, matrix multiplication
188 * @code{MAX}: MAX, Maximum value of an argument list
189 * @code{MAXEXPONENT}: MAXEXPONENT, Maximum exponent of a real kind
190 * @code{MAXLOC}: MAXLOC, Location of the maximum value within an array
191 * @code{MAXVAL}: MAXVAL, Maximum value of an array
192 * @code{MCLOCK}: MCLOCK, Time function
193 * @code{MCLOCK8}: MCLOCK8, Time function (64-bit)
194 * @code{MERGE}: MERGE, Merge arrays
195 * @code{MIN}: MIN, Minimum value of an argument list
196 * @code{MINEXPONENT}: MINEXPONENT, Minimum exponent of a real kind
197 * @code{MINLOC}: MINLOC, Location of the minimum value within an array
198 * @code{MINVAL}: MINVAL, Minimum value of an array
199 * @code{MOD}: MOD, Remainder function
200 * @code{MODULO}: MODULO, Modulo function
201 * @code{MOVE_ALLOC}: MOVE_ALLOC, Move allocation from one object to another
202 * @code{MVBITS}: MVBITS, Move bits from one integer to another
203 * @code{NEAREST}: NEAREST, Nearest representable number
204 * @code{NEW_LINE}: NEW_LINE, New line character
205 * @code{NINT}: NINT, Nearest whole number
206 * @code{NOT}: NOT, Logical negation
207 * @code{NULL}: NULL, Function that returns an disassociated pointer
208 * @code{NUM_IMAGES}: NUM_IMAGES, Number of images
209 * @code{OR}: OR, Bitwise logical OR
210 * @code{PACK}: PACK, Pack an array into an array of rank one
211 * @code{PERROR}: PERROR, Print system error message
212 * @code{PRECISION}: PRECISION, Decimal precision of a real kind
213 * @code{PRESENT}: PRESENT, Determine whether an optional dummy argument is specified
214 * @code{PRODUCT}: PRODUCT, Product of array elements
215 * @code{RADIX}: RADIX, Base of a data model
216 * @code{RANDOM_NUMBER}: RANDOM_NUMBER, Pseudo-random number
217 * @code{RANDOM_SEED}: RANDOM_SEED, Initialize a pseudo-random number sequence
218 * @code{RAND}: RAND, Real pseudo-random number
219 * @code{RANGE}: RANGE, Decimal exponent range
220 * @code{RAN}: RAN, Real pseudo-random number
221 * @code{REAL}: REAL, Convert to real type
222 * @code{RENAME}: RENAME, Rename a file
223 * @code{REPEAT}: REPEAT, Repeated string concatenation
224 * @code{RESHAPE}: RESHAPE, Function to reshape an array
225 * @code{RRSPACING}: RRSPACING, Reciprocal of the relative spacing
226 * @code{RSHIFT}: RSHIFT, Right shift bits
227 * @code{SAME_TYPE_AS}: SAME_TYPE_AS, Query dynamic types for equality
228 * @code{SCALE}: SCALE, Scale a real value
229 * @code{SCAN}: SCAN, Scan a string for the presence of a set of characters
230 * @code{SECNDS}: SECNDS, Time function
231 * @code{SECOND}: SECOND, CPU time function
232 * @code{SELECTED_CHAR_KIND}: SELECTED_CHAR_KIND, Choose character kind
233 * @code{SELECTED_INT_KIND}: SELECTED_INT_KIND, Choose integer kind
234 * @code{SELECTED_REAL_KIND}: SELECTED_REAL_KIND, Choose real kind
235 * @code{SET_EXPONENT}: SET_EXPONENT, Set the exponent of the model
236 * @code{SHAPE}: SHAPE, Determine the shape of an array
237 * @code{SIGN}: SIGN, Sign copying function
238 * @code{SIGNAL}: SIGNAL, Signal handling subroutine (or function)
239 * @code{SIN}: SIN, Sine function
240 * @code{SINH}: SINH, Hyperbolic sine function
241 * @code{SIZE}: SIZE, Function to determine the size of an array
242 * @code{SIZEOF}: SIZEOF, Determine the size in bytes of an expression
243 * @code{SLEEP}: SLEEP, Sleep for the specified number of seconds
244 * @code{SPACING}: SPACING, Smallest distance between two numbers of a given type
245 * @code{SPREAD}: SPREAD, Add a dimension to an array
246 * @code{SQRT}: SQRT, Square-root function
247 * @code{SRAND}: SRAND, Reinitialize the random number generator
248 * @code{STAT}: STAT, Get file status
249 * @code{STORAGE_SIZE}: STORAGE_SIZE, Storage size in bits
250 * @code{SUM}: SUM, Sum of array elements
251 * @code{SYMLNK}: SYMLNK, Create a symbolic link
252 * @code{SYSTEM}: SYSTEM, Execute a shell command
253 * @code{SYSTEM_CLOCK}: SYSTEM_CLOCK, Time function
254 * @code{TAN}: TAN, Tangent function
255 * @code{TANH}: TANH, Hyperbolic tangent function
256 * @code{THIS_IMAGE}: THIS_IMAGE, Cosubscript index of this image
257 * @code{TIME}: TIME, Time function
258 * @code{TIME8}: TIME8, Time function (64-bit)
259 * @code{TINY}: TINY, Smallest positive number of a real kind
260 * @code{TRAILZ}: TRAILZ, Number of trailing zero bits of an integer
261 * @code{TRANSFER}: TRANSFER, Transfer bit patterns
262 * @code{TRANSPOSE}: TRANSPOSE, Transpose an array of rank two
263 * @code{TRIM}: TRIM, Remove trailing blank characters of a string
264 * @code{TTYNAM}: TTYNAM, Get the name of a terminal device.
265 * @code{UBOUND}: UBOUND, Upper dimension bounds of an array
266 * @code{UCOBOUND}: UCOBOUND, Upper codimension bounds of an array
267 * @code{UMASK}: UMASK, Set the file creation mask
268 * @code{UNLINK}: UNLINK, Remove a file from the file system
269 * @code{UNPACK}: UNPACK, Unpack an array of rank one into an array
270 * @code{VERIFY}: VERIFY, Scan a string for the absence of a set of characters
271 * @code{XOR}: XOR, Bitwise logical exclusive or
274 @node Introduction to Intrinsics
275 @section Introduction to intrinsic procedures
277 The intrinsic procedures provided by GNU Fortran include all of the
278 intrinsic procedures required by the Fortran 95 standard, a set of
279 intrinsic procedures for backwards compatibility with G77, and a
280 selection of intrinsic procedures from the Fortran 2003 and Fortran 2008
281 standards. Any conflict between a description here and a description in
282 either the Fortran 95 standard, the Fortran 2003 standard or the Fortran
283 2008 standard is unintentional, and the standard(s) should be considered
286 The enumeration of the @code{KIND} type parameter is processor defined in
287 the Fortran 95 standard. GNU Fortran defines the default integer type and
288 default real type by @code{INTEGER(KIND=4)} and @code{REAL(KIND=4)},
289 respectively. The standard mandates that both data types shall have
290 another kind, which have more precision. On typical target architectures
291 supported by @command{gfortran}, this kind type parameter is @code{KIND=8}.
292 Hence, @code{REAL(KIND=8)} and @code{DOUBLE PRECISION} are equivalent.
293 In the description of generic intrinsic procedures, the kind type parameter
294 will be specified by @code{KIND=*}, and in the description of specific
295 names for an intrinsic procedure the kind type parameter will be explicitly
296 given (e.g., @code{REAL(KIND=4)} or @code{REAL(KIND=8)}). Finally, for
297 brevity the optional @code{KIND=} syntax will be omitted.
299 Many of the intrinsic procedures take one or more optional arguments.
300 This document follows the convention used in the Fortran 95 standard,
301 and denotes such arguments by square brackets.
303 GNU Fortran offers the @option{-std=f95} and @option{-std=gnu} options,
304 which can be used to restrict the set of intrinsic procedures to a
305 given standard. By default, @command{gfortran} sets the @option{-std=gnu}
306 option, and so all intrinsic procedures described here are accepted. There
307 is one caveat. For a select group of intrinsic procedures, @command{g77}
308 implemented both a function and a subroutine. Both classes
309 have been implemented in @command{gfortran} for backwards compatibility
310 with @command{g77}. It is noted here that these functions and subroutines
311 cannot be intermixed in a given subprogram. In the descriptions that follow,
312 the applicable standard for each intrinsic procedure is noted.
317 @section @code{ABORT} --- Abort the program
319 @cindex program termination, with core dump
320 @cindex terminate program, with core dump
324 @item @emph{Description}:
325 @code{ABORT} causes immediate termination of the program. On operating
326 systems that support a core dump, @code{ABORT} will produce a core dump even if
327 the option @option{-fno-dump-core} is in effect, which is suitable for debugging
329 @c TODO: Check if this (with -fno-dump-core) is correct.
331 @item @emph{Standard}:
340 @item @emph{Return value}:
343 @item @emph{Example}:
346 integer :: i = 1, j = 2
347 if (i /= j) call abort
348 end program test_abort
351 @item @emph{See also}:
352 @ref{EXIT}, @ref{KILL}
359 @section @code{ABS} --- Absolute value
366 @cindex absolute value
369 @item @emph{Description}:
370 @code{ABS(A)} computes the absolute value of @code{A}.
372 @item @emph{Standard}:
373 Fortran 77 and later, has overloads that are GNU extensions
379 @code{RESULT = ABS(A)}
381 @item @emph{Arguments}:
382 @multitable @columnfractions .15 .70
383 @item @var{A} @tab The type of the argument shall be an @code{INTEGER},
384 @code{REAL}, or @code{COMPLEX}.
387 @item @emph{Return value}:
388 The return value is of the same type and
389 kind as the argument except the return value is @code{REAL} for a
390 @code{COMPLEX} argument.
392 @item @emph{Example}:
397 complex :: z = (-1.e0,0.e0)
404 @item @emph{Specific names}:
405 @multitable @columnfractions .20 .20 .20 .25
406 @item Name @tab Argument @tab Return type @tab Standard
407 @item @code{ABS(A)} @tab @code{REAL(4) A} @tab @code{REAL(4)} @tab Fortran 77 and later
408 @item @code{CABS(A)} @tab @code{COMPLEX(4) A} @tab @code{REAL(4)} @tab Fortran 77 and later
409 @item @code{DABS(A)} @tab @code{REAL(8) A} @tab @code{REAL(8)} @tab Fortran 77 and later
410 @item @code{IABS(A)} @tab @code{INTEGER(4) A} @tab @code{INTEGER(4)} @tab Fortran 77 and later
411 @item @code{ZABS(A)} @tab @code{COMPLEX(8) A} @tab @code{COMPLEX(8)} @tab GNU extension
412 @item @code{CDABS(A)} @tab @code{COMPLEX(8) A} @tab @code{COMPLEX(8)} @tab GNU extension
419 @section @code{ACCESS} --- Checks file access modes
421 @cindex file system, access mode
424 @item @emph{Description}:
425 @code{ACCESS(NAME, MODE)} checks whether the file @var{NAME}
426 exists, is readable, writable or executable. Except for the
427 executable check, @code{ACCESS} can be replaced by
428 Fortran 95's @code{INQUIRE}.
430 @item @emph{Standard}:
437 @code{RESULT = ACCESS(NAME, MODE)}
439 @item @emph{Arguments}:
440 @multitable @columnfractions .15 .70
441 @item @var{NAME} @tab Scalar @code{CHARACTER} of default kind with the
442 file name. Tailing blank are ignored unless the character @code{achar(0)}
443 is present, then all characters up to and excluding @code{achar(0)} are
445 @item @var{MODE} @tab Scalar @code{CHARACTER} of default kind with the
446 file access mode, may be any concatenation of @code{"r"} (readable),
447 @code{"w"} (writable) and @code{"x"} (executable), or @code{" "} to check
451 @item @emph{Return value}:
452 Returns a scalar @code{INTEGER}, which is @code{0} if the file is
453 accessible in the given mode; otherwise or if an invalid argument
454 has been given for @code{MODE} the value @code{1} is returned.
456 @item @emph{Example}:
460 character(len=*), parameter :: file = 'test.dat'
461 character(len=*), parameter :: file2 = 'test.dat '//achar(0)
462 if(access(file,' ') == 0) print *, trim(file),' is exists'
463 if(access(file,'r') == 0) print *, trim(file),' is readable'
464 if(access(file,'w') == 0) print *, trim(file),' is writable'
465 if(access(file,'x') == 0) print *, trim(file),' is executable'
466 if(access(file2,'rwx') == 0) &
467 print *, trim(file2),' is readable, writable and executable'
468 end program access_test
470 @item @emph{Specific names}:
471 @item @emph{See also}:
478 @section @code{ACHAR} --- Character in @acronym{ASCII} collating sequence
480 @cindex @acronym{ASCII} collating sequence
481 @cindex collating sequence, @acronym{ASCII}
484 @item @emph{Description}:
485 @code{ACHAR(I)} returns the character located at position @code{I}
486 in the @acronym{ASCII} collating sequence.
488 @item @emph{Standard}:
489 Fortran 77 and later, with @var{KIND} argument Fortran 2003 and later
495 @code{RESULT = ACHAR(I [, KIND])}
497 @item @emph{Arguments}:
498 @multitable @columnfractions .15 .70
499 @item @var{I} @tab The type shall be @code{INTEGER}.
500 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
501 expression indicating the kind parameter of the result.
504 @item @emph{Return value}:
505 The return value is of type @code{CHARACTER} with a length of one.
506 If the @var{KIND} argument is present, the return value is of the
507 specified kind and of the default kind otherwise.
509 @item @emph{Example}:
514 end program test_achar
518 See @ref{ICHAR} for a discussion of converting between numerical values
519 and formatted string representations.
521 @item @emph{See also}:
522 @ref{CHAR}, @ref{IACHAR}, @ref{ICHAR}
529 @section @code{ACOS} --- Arccosine function
532 @cindex trigonometric function, cosine, inverse
533 @cindex cosine, inverse
536 @item @emph{Description}:
537 @code{ACOS(X)} computes the arccosine of @var{X} (inverse of @code{COS(X)}).
539 @item @emph{Standard}:
540 Fortran 77 and later, for a complex argument Fortran 2008 or later
546 @code{RESULT = ACOS(X)}
548 @item @emph{Arguments}:
549 @multitable @columnfractions .15 .70
550 @item @var{X} @tab The type shall either be @code{REAL} with a magnitude that is
551 less than or equal to one - or the type shall be @code{COMPLEX}.
554 @item @emph{Return value}:
555 The return value is of the same type and kind as @var{X}.
556 The real part of the result is in radians and lies in the range
557 @math{0 \leq \Re \acos(x) \leq \pi}.
559 @item @emph{Example}:
562 real(8) :: x = 0.866_8
564 end program test_acos
567 @item @emph{Specific names}:
568 @multitable @columnfractions .20 .20 .20 .25
569 @item Name @tab Argument @tab Return type @tab Standard
570 @item @code{ACOS(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab Fortran 77 and later
571 @item @code{DACOS(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab Fortran 77 and later
574 @item @emph{See also}:
575 Inverse function: @ref{COS}
582 @section @code{ACOSH} --- Hyperbolic arccosine function
585 @cindex area hyperbolic cosine
586 @cindex hyperbolic arccosine
587 @cindex hyperbolic function, cosine, inverse
588 @cindex cosine, hyperbolic, inverse
591 @item @emph{Description}:
592 @code{ACOSH(X)} computes the hyperbolic arccosine of @var{X} (inverse of
595 @item @emph{Standard}:
596 Fortran 2008 and later
602 @code{RESULT = ACOSH(X)}
604 @item @emph{Arguments}:
605 @multitable @columnfractions .15 .70
606 @item @var{X} @tab The type shall be @code{REAL} or @code{COMPLEX}.
609 @item @emph{Return value}:
610 The return value has the same type and kind as @var{X}. If @var{X} is
611 complex, the imaginary part of the result is in radians and lies between
612 @math{ 0 \leq \Im \acosh(x) \leq \pi}.
614 @item @emph{Example}:
617 REAL(8), DIMENSION(3) :: x = (/ 1.0, 2.0, 3.0 /)
622 @item @emph{Specific names}:
623 @multitable @columnfractions .20 .20 .20 .25
624 @item Name @tab Argument @tab Return type @tab Standard
625 @item @code{DACOSH(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU extension
628 @item @emph{See also}:
629 Inverse function: @ref{COSH}
635 @section @code{ADJUSTL} --- Left adjust a string
637 @cindex string, adjust left
638 @cindex adjust string
641 @item @emph{Description}:
642 @code{ADJUSTL(STRING)} will left adjust a string by removing leading spaces.
643 Spaces are inserted at the end of the string as needed.
645 @item @emph{Standard}:
652 @code{RESULT = ADJUSTL(STRING)}
654 @item @emph{Arguments}:
655 @multitable @columnfractions .15 .70
656 @item @var{STRING} @tab The type shall be @code{CHARACTER}.
659 @item @emph{Return value}:
660 The return value is of type @code{CHARACTER} and of the same kind as
661 @var{STRING} where leading spaces are removed and the same number of
662 spaces are inserted on the end of @var{STRING}.
664 @item @emph{Example}:
667 character(len=20) :: str = ' gfortran'
670 end program test_adjustl
673 @item @emph{See also}:
674 @ref{ADJUSTR}, @ref{TRIM}
680 @section @code{ADJUSTR} --- Right adjust a string
682 @cindex string, adjust right
683 @cindex adjust string
686 @item @emph{Description}:
687 @code{ADJUSTR(STRING)} will right adjust a string by removing trailing spaces.
688 Spaces are inserted at the start of the string as needed.
690 @item @emph{Standard}:
697 @code{RESULT = ADJUSTR(STRING)}
699 @item @emph{Arguments}:
700 @multitable @columnfractions .15 .70
701 @item @var{STR} @tab The type shall be @code{CHARACTER}.
704 @item @emph{Return value}:
705 The return value is of type @code{CHARACTER} and of the same kind as
706 @var{STRING} where trailing spaces are removed and the same number of
707 spaces are inserted at the start of @var{STRING}.
709 @item @emph{Example}:
712 character(len=20) :: str = 'gfortran'
715 end program test_adjustr
718 @item @emph{See also}:
719 @ref{ADJUSTL}, @ref{TRIM}
725 @section @code{AIMAG} --- Imaginary part of complex number
730 @cindex complex numbers, imaginary part
733 @item @emph{Description}:
734 @code{AIMAG(Z)} yields the imaginary part of complex argument @code{Z}.
735 The @code{IMAG(Z)} and @code{IMAGPART(Z)} intrinsic functions are provided
736 for compatibility with @command{g77}, and their use in new code is
737 strongly discouraged.
739 @item @emph{Standard}:
740 Fortran 77 and later, has overloads that are GNU extensions
746 @code{RESULT = AIMAG(Z)}
748 @item @emph{Arguments}:
749 @multitable @columnfractions .15 .70
750 @item @var{Z} @tab The type of the argument shall be @code{COMPLEX}.
753 @item @emph{Return value}:
754 The return value is of type @code{REAL} with the
755 kind type parameter of the argument.
757 @item @emph{Example}:
762 z4 = cmplx(1.e0_4, 0.e0_4)
763 z8 = cmplx(0.e0_8, 1.e0_8)
764 print *, aimag(z4), dimag(z8)
765 end program test_aimag
768 @item @emph{Specific names}:
769 @multitable @columnfractions .20 .20 .20 .25
770 @item Name @tab Argument @tab Return type @tab Standard
771 @item @code{AIMAG(Z)} @tab @code{COMPLEX Z} @tab @code{REAL} @tab GNU extension
772 @item @code{DIMAG(Z)} @tab @code{COMPLEX(8) Z} @tab @code{REAL(8)} @tab GNU extension
773 @item @code{IMAG(Z)} @tab @code{COMPLEX Z} @tab @code{REAL} @tab GNU extension
774 @item @code{IMAGPART(Z)} @tab @code{COMPLEX Z} @tab @code{REAL} @tab GNU extension
781 @section @code{AINT} --- Truncate to a whole number
785 @cindex rounding, floor
788 @item @emph{Description}:
789 @code{AINT(A [, KIND])} truncates its argument to a whole number.
791 @item @emph{Standard}:
798 @code{RESULT = AINT(A [, KIND])}
800 @item @emph{Arguments}:
801 @multitable @columnfractions .15 .70
802 @item @var{A} @tab The type of the argument shall be @code{REAL}.
803 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
804 expression indicating the kind parameter of the result.
807 @item @emph{Return value}:
808 The return value is of type @code{REAL} with the kind type parameter of the
809 argument if the optional @var{KIND} is absent; otherwise, the kind
810 type parameter will be given by @var{KIND}. If the magnitude of
811 @var{X} is less than one, @code{AINT(X)} returns zero. If the
812 magnitude is equal to or greater than one then it returns the largest
813 whole number that does not exceed its magnitude. The sign is the same
814 as the sign of @var{X}.
816 @item @emph{Example}:
823 print *, aint(x4), dint(x8)
825 end program test_aint
828 @item @emph{Specific names}:
829 @multitable @columnfractions .20 .20 .20 .25
830 @item Name @tab Argument @tab Return type @tab Standard
831 @item @code{AINT(A)} @tab @code{REAL(4) A} @tab @code{REAL(4)} @tab Fortran 77 and later
832 @item @code{DINT(A)} @tab @code{REAL(8) A} @tab @code{REAL(8)} @tab Fortran 77 and later
839 @section @code{ALARM} --- Execute a routine after a given delay
841 @cindex delayed execution
844 @item @emph{Description}:
845 @code{ALARM(SECONDS, HANDLER [, STATUS])} causes external subroutine @var{HANDLER}
846 to be executed after a delay of @var{SECONDS} by using @code{alarm(2)} to
847 set up a signal and @code{signal(2)} to catch it. If @var{STATUS} is
848 supplied, it will be returned with the number of seconds remaining until
849 any previously scheduled alarm was due to be delivered, or zero if there
850 was no previously scheduled alarm.
852 @item @emph{Standard}:
859 @code{CALL ALARM(SECONDS, HANDLER [, STATUS])}
861 @item @emph{Arguments}:
862 @multitable @columnfractions .15 .70
863 @item @var{SECONDS} @tab The type of the argument shall be a scalar
864 @code{INTEGER}. It is @code{INTENT(IN)}.
865 @item @var{HANDLER} @tab Signal handler (@code{INTEGER FUNCTION} or
866 @code{SUBROUTINE}) or dummy/global @code{INTEGER} scalar. The scalar
867 values may be either @code{SIG_IGN=1} to ignore the alarm generated
868 or @code{SIG_DFL=0} to set the default action. It is @code{INTENT(IN)}.
869 @item @var{STATUS} @tab (Optional) @var{STATUS} shall be a scalar
870 variable of the default @code{INTEGER} kind. It is @code{INTENT(OUT)}.
873 @item @emph{Example}:
876 external handler_print
878 call alarm (3, handler_print, i)
881 end program test_alarm
883 This will cause the external routine @var{handler_print} to be called
890 @section @code{ALL} --- All values in @var{MASK} along @var{DIM} are true
892 @cindex array, apply condition
893 @cindex array, condition testing
896 @item @emph{Description}:
897 @code{ALL(MASK [, DIM])} determines if all the values are true in @var{MASK}
898 in the array along dimension @var{DIM}.
900 @item @emph{Standard}:
904 Transformational function
907 @code{RESULT = ALL(MASK [, DIM])}
909 @item @emph{Arguments}:
910 @multitable @columnfractions .15 .70
911 @item @var{MASK} @tab The type of the argument shall be @code{LOGICAL} and
912 it shall not be scalar.
913 @item @var{DIM} @tab (Optional) @var{DIM} shall be a scalar integer
914 with a value that lies between one and the rank of @var{MASK}.
917 @item @emph{Return value}:
918 @code{ALL(MASK)} returns a scalar value of type @code{LOGICAL} where
919 the kind type parameter is the same as the kind type parameter of
920 @var{MASK}. If @var{DIM} is present, then @code{ALL(MASK, DIM)} returns
921 an array with the rank of @var{MASK} minus 1. The shape is determined from
922 the shape of @var{MASK} where the @var{DIM} dimension is elided.
926 @code{ALL(MASK)} is true if all elements of @var{MASK} are true.
927 It also is true if @var{MASK} has zero size; otherwise, it is false.
929 If the rank of @var{MASK} is one, then @code{ALL(MASK,DIM)} is equivalent
930 to @code{ALL(MASK)}. If the rank is greater than one, then @code{ALL(MASK,DIM)}
931 is determined by applying @code{ALL} to the array sections.
934 @item @emph{Example}:
938 l = all((/.true., .true., .true./))
943 integer a(2,3), b(2,3)
947 print *, all(a .eq. b, 1)
948 print *, all(a .eq. b, 2)
949 end subroutine section
957 @section @code{ALLOCATED} --- Status of an allocatable entity
959 @cindex allocation, status
962 @item @emph{Description}:
963 @code{ALLOCATED(ARRAY)} and @code{ALLOCATED(SCALAR)} check the allocation
964 status of @var{ARRAY} and @var{SCALAR}, respectively.
966 @item @emph{Standard}:
967 Fortran 95 and later. Note, the @code{SCALAR=} keyword and allocatable
968 scalar entities are available in Fortran 2003 and later.
974 @code{RESULT = ALLOCATED(ARRAY)} or @code{RESULT = ALLOCATED(SCALAR)}
976 @item @emph{Arguments}:
977 @multitable @columnfractions .15 .70
978 @item @var{ARRAY} @tab The argument shall be an @code{ALLOCATABLE} array.
979 @item @var{SCALAR} @tab The argument shall be an @code{ALLOCATABLE} scalar.
982 @item @emph{Return value}:
983 The return value is a scalar @code{LOGICAL} with the default logical
984 kind type parameter. If the argument is allocated, then the result is
985 @code{.TRUE.}; otherwise, it returns @code{.FALSE.}
987 @item @emph{Example}:
989 program test_allocated
991 real(4), allocatable :: x(:)
992 if (.not. allocated(x)) allocate(x(i))
993 end program test_allocated
1000 @section @code{AND} --- Bitwise logical AND
1002 @cindex bitwise logical and
1003 @cindex logical and, bitwise
1006 @item @emph{Description}:
1007 Bitwise logical @code{AND}.
1009 This intrinsic routine is provided for backwards compatibility with
1010 GNU Fortran 77. For integer arguments, programmers should consider
1011 the use of the @ref{IAND} intrinsic defined by the Fortran standard.
1013 @item @emph{Standard}:
1019 @item @emph{Syntax}:
1020 @code{RESULT = AND(I, J)}
1022 @item @emph{Arguments}:
1023 @multitable @columnfractions .15 .70
1024 @item @var{I} @tab The type shall be either a scalar @code{INTEGER}
1025 type or a scalar @code{LOGICAL} type.
1026 @item @var{J} @tab The type shall be the same as the type of @var{I}.
1029 @item @emph{Return value}:
1030 The return type is either a scalar @code{INTEGER} or a scalar
1031 @code{LOGICAL}. If the kind type parameters differ, then the
1032 smaller kind type is implicitly converted to larger kind, and the
1033 return has the larger kind.
1035 @item @emph{Example}:
1038 LOGICAL :: T = .TRUE., F = .FALSE.
1040 DATA a / Z'F' /, b / Z'3' /
1042 WRITE (*,*) AND(T, T), AND(T, F), AND(F, T), AND(F, F)
1043 WRITE (*,*) AND(a, b)
1047 @item @emph{See also}:
1048 Fortran 95 elemental function: @ref{IAND}
1054 @section @code{ANINT} --- Nearest whole number
1058 @cindex rounding, ceiling
1061 @item @emph{Description}:
1062 @code{ANINT(A [, KIND])} rounds its argument to the nearest whole number.
1064 @item @emph{Standard}:
1065 Fortran 77 and later
1070 @item @emph{Syntax}:
1071 @code{RESULT = ANINT(A [, KIND])}
1073 @item @emph{Arguments}:
1074 @multitable @columnfractions .15 .70
1075 @item @var{A} @tab The type of the argument shall be @code{REAL}.
1076 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
1077 expression indicating the kind parameter of the result.
1080 @item @emph{Return value}:
1081 The return value is of type real with the kind type parameter of the
1082 argument if the optional @var{KIND} is absent; otherwise, the kind
1083 type parameter will be given by @var{KIND}. If @var{A} is greater than
1084 zero, @code{ANINT(A)} returns @code{AINT(X+0.5)}. If @var{A} is
1085 less than or equal to zero then it returns @code{AINT(X-0.5)}.
1087 @item @emph{Example}:
1094 print *, anint(x4), dnint(x8)
1096 end program test_anint
1099 @item @emph{Specific names}:
1100 @multitable @columnfractions .20 .20 .20 .25
1101 @item Name @tab Argument @tab Return type @tab Standard
1102 @item @code{AINT(A)} @tab @code{REAL(4) A} @tab @code{REAL(4)} @tab Fortran 77 and later
1103 @item @code{DNINT(A)} @tab @code{REAL(8) A} @tab @code{REAL(8)} @tab Fortran 77 and later
1110 @section @code{ANY} --- Any value in @var{MASK} along @var{DIM} is true
1112 @cindex array, apply condition
1113 @cindex array, condition testing
1116 @item @emph{Description}:
1117 @code{ANY(MASK [, DIM])} determines if any of the values in the logical array
1118 @var{MASK} along dimension @var{DIM} are @code{.TRUE.}.
1120 @item @emph{Standard}:
1121 Fortran 95 and later
1124 Transformational function
1126 @item @emph{Syntax}:
1127 @code{RESULT = ANY(MASK [, DIM])}
1129 @item @emph{Arguments}:
1130 @multitable @columnfractions .15 .70
1131 @item @var{MASK} @tab The type of the argument shall be @code{LOGICAL} and
1132 it shall not be scalar.
1133 @item @var{DIM} @tab (Optional) @var{DIM} shall be a scalar integer
1134 with a value that lies between one and the rank of @var{MASK}.
1137 @item @emph{Return value}:
1138 @code{ANY(MASK)} returns a scalar value of type @code{LOGICAL} where
1139 the kind type parameter is the same as the kind type parameter of
1140 @var{MASK}. If @var{DIM} is present, then @code{ANY(MASK, DIM)} returns
1141 an array with the rank of @var{MASK} minus 1. The shape is determined from
1142 the shape of @var{MASK} where the @var{DIM} dimension is elided.
1146 @code{ANY(MASK)} is true if any element of @var{MASK} is true;
1147 otherwise, it is false. It also is false if @var{MASK} has zero size.
1149 If the rank of @var{MASK} is one, then @code{ANY(MASK,DIM)} is equivalent
1150 to @code{ANY(MASK)}. If the rank is greater than one, then @code{ANY(MASK,DIM)}
1151 is determined by applying @code{ANY} to the array sections.
1154 @item @emph{Example}:
1158 l = any((/.true., .true., .true./))
1163 integer a(2,3), b(2,3)
1167 print *, any(a .eq. b, 1)
1168 print *, any(a .eq. b, 2)
1169 end subroutine section
1170 end program test_any
1177 @section @code{ASIN} --- Arcsine function
1180 @cindex trigonometric function, sine, inverse
1181 @cindex sine, inverse
1184 @item @emph{Description}:
1185 @code{ASIN(X)} computes the arcsine of its @var{X} (inverse of @code{SIN(X)}).
1187 @item @emph{Standard}:
1188 Fortran 77 and later, for a complex argument Fortran 2008 or later
1193 @item @emph{Syntax}:
1194 @code{RESULT = ASIN(X)}
1196 @item @emph{Arguments}:
1197 @multitable @columnfractions .15 .70
1198 @item @var{X} @tab The type shall be either @code{REAL} and a magnitude that is
1199 less than or equal to one - or be @code{COMPLEX}.
1202 @item @emph{Return value}:
1203 The return value is of the same type and kind as @var{X}.
1204 The real part of the result is in radians and lies in the range
1205 @math{-\pi/2 \leq \Re \asin(x) \leq \pi/2}.
1207 @item @emph{Example}:
1210 real(8) :: x = 0.866_8
1212 end program test_asin
1215 @item @emph{Specific names}:
1216 @multitable @columnfractions .20 .20 .20 .25
1217 @item Name @tab Argument @tab Return type @tab Standard
1218 @item @code{ASIN(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab Fortran 77 and later
1219 @item @code{DASIN(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab Fortran 77 and later
1222 @item @emph{See also}:
1223 Inverse function: @ref{SIN}
1230 @section @code{ASINH} --- Hyperbolic arcsine function
1233 @cindex area hyperbolic sine
1234 @cindex hyperbolic arcsine
1235 @cindex hyperbolic function, sine, inverse
1236 @cindex sine, hyperbolic, inverse
1239 @item @emph{Description}:
1240 @code{ASINH(X)} computes the hyperbolic arcsine of @var{X} (inverse of @code{SINH(X)}).
1242 @item @emph{Standard}:
1243 Fortran 2008 and later
1248 @item @emph{Syntax}:
1249 @code{RESULT = ASINH(X)}
1251 @item @emph{Arguments}:
1252 @multitable @columnfractions .15 .70
1253 @item @var{X} @tab The type shall be @code{REAL} or @code{COMPLEX}.
1256 @item @emph{Return value}:
1257 The return value is of the same type and kind as @var{X}. If @var{X} is
1258 complex, the imaginary part of the result is in radians and lies between
1259 @math{-\pi/2 \leq \Im \asinh(x) \leq \pi/2}.
1261 @item @emph{Example}:
1264 REAL(8), DIMENSION(3) :: x = (/ -1.0, 0.0, 1.0 /)
1265 WRITE (*,*) ASINH(x)
1269 @item @emph{Specific names}:
1270 @multitable @columnfractions .20 .20 .20 .25
1271 @item Name @tab Argument @tab Return type @tab Standard
1272 @item @code{DASINH(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU extension.
1275 @item @emph{See also}:
1276 Inverse function: @ref{SINH}
1282 @section @code{ASSOCIATED} --- Status of a pointer or pointer/target pair
1284 @cindex pointer, status
1285 @cindex association status
1288 @item @emph{Description}:
1289 @code{ASSOCIATED(POINTER [, TARGET])} determines the status of the pointer
1290 @var{POINTER} or if @var{POINTER} is associated with the target @var{TARGET}.
1292 @item @emph{Standard}:
1293 Fortran 95 and later
1298 @item @emph{Syntax}:
1299 @code{RESULT = ASSOCIATED(POINTER [, TARGET])}
1301 @item @emph{Arguments}:
1302 @multitable @columnfractions .15 .70
1303 @item @var{POINTER} @tab @var{POINTER} shall have the @code{POINTER} attribute
1304 and it can be of any type.
1305 @item @var{TARGET} @tab (Optional) @var{TARGET} shall be a pointer or
1306 a target. It must have the same type, kind type parameter, and
1307 array rank as @var{POINTER}.
1309 The association status of neither @var{POINTER} nor @var{TARGET} shall be
1312 @item @emph{Return value}:
1313 @code{ASSOCIATED(POINTER)} returns a scalar value of type @code{LOGICAL(4)}.
1314 There are several cases:
1316 @item (A) When the optional @var{TARGET} is not present then
1317 @code{ASSOCIATED(POINTER)} is true if @var{POINTER} is associated with a target; otherwise, it returns false.
1318 @item (B) If @var{TARGET} is present and a scalar target, the result is true if
1319 @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
1320 disassociated, the result is false.
1321 @item (C) If @var{TARGET} is present and an array target, the result is true if
1322 @var{TARGET} and @var{POINTER} have the same shape, are not zero-sized arrays,
1323 are arrays whose elements are not zero-sized storage sequences, and
1324 @var{TARGET} and @var{POINTER} occupy the same storage units in array element
1326 As in case(B), the result is false, if @var{POINTER} is disassociated.
1327 @item (D) If @var{TARGET} is present and an scalar pointer, the result is true
1328 if @var{TARGET} is associated with @var{POINTER}, the target associated with
1329 @var{TARGET} are not zero-sized storage sequences and occupy the same storage
1331 The result is false, if either @var{TARGET} or @var{POINTER} is disassociated.
1332 @item (E) If @var{TARGET} is present and an array pointer, the result is true if
1333 target associated with @var{POINTER} and the target associated with @var{TARGET}
1334 have the same shape, are not zero-sized arrays, are arrays whose elements are
1335 not zero-sized storage sequences, and @var{TARGET} and @var{POINTER} occupy
1336 the same storage units in array element order.
1337 The result is false, if either @var{TARGET} or @var{POINTER} is disassociated.
1340 @item @emph{Example}:
1342 program test_associated
1344 real, target :: tgt(2) = (/1., 2./)
1345 real, pointer :: ptr(:)
1347 if (associated(ptr) .eqv. .false.) call abort
1348 if (associated(ptr,tgt) .eqv. .false.) call abort
1349 end program test_associated
1352 @item @emph{See also}:
1359 @section @code{ATAN} --- Arctangent function
1362 @cindex trigonometric function, tangent, inverse
1363 @cindex tangent, inverse
1366 @item @emph{Description}:
1367 @code{ATAN(X)} computes the arctangent of @var{X}.
1369 @item @emph{Standard}:
1370 Fortran 77 and later, for a complex argument and for two arguments
1371 Fortran 2008 or later
1376 @item @emph{Syntax}:
1377 @code{RESULT = ATAN(X)}
1378 @code{RESULT = ATAN(Y, X)}
1380 @item @emph{Arguments}:
1381 @multitable @columnfractions .15 .70
1382 @item @var{X} @tab The type shall be @code{REAL} or @code{COMPLEX};
1383 if @var{Y} is present, @var{X} shall be REAL.
1384 @item @var{Y} shall be of the same type and kind as @var{X}.
1387 @item @emph{Return value}:
1388 The return value is of the same type and kind as @var{X}.
1389 If @var{Y} is present, the result is identical to @code{ATAN2(Y,X)}.
1390 Otherwise, it the arcus tangent of @var{X}, where the real part of
1391 the result is in radians and lies in the range
1392 @math{-\pi/2 \leq \Re \atan(x) \leq \pi/2}.
1394 @item @emph{Example}:
1397 real(8) :: x = 2.866_8
1399 end program test_atan
1402 @item @emph{Specific names}:
1403 @multitable @columnfractions .20 .20 .20 .25
1404 @item Name @tab Argument @tab Return type @tab Standard
1405 @item @code{ATAN(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab Fortran 77 and later
1406 @item @code{DATAN(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab Fortran 77 and later
1409 @item @emph{See also}:
1410 Inverse function: @ref{TAN}
1417 @section @code{ATAN2} --- Arctangent function
1420 @cindex trigonometric function, tangent, inverse
1421 @cindex tangent, inverse
1424 @item @emph{Description}:
1425 @code{ATAN2(Y, X)} computes the principal value of the argument
1426 function of the complex number @math{X + i Y}. This function can
1427 be used to transform from carthesian into polar coordinates and
1428 allows to determine the angle in the correct quadrant.
1430 @item @emph{Standard}:
1431 Fortran 77 and later
1436 @item @emph{Syntax}:
1437 @code{RESULT = ATAN2(Y, X)}
1439 @item @emph{Arguments}:
1440 @multitable @columnfractions .15 .70
1441 @item @var{Y} @tab The type shall be @code{REAL}.
1442 @item @var{X} @tab The type and kind type parameter shall be the same as @var{Y}.
1443 If @var{Y} is zero, then @var{X} must be nonzero.
1446 @item @emph{Return value}:
1447 The return value has the same type and kind type parameter as @var{Y}.
1448 It is the principal value of the complex number @math{X + i Y}. If
1449 @var{X} is nonzero, then it lies in the range @math{-\pi \le \atan (x) \leq \pi}.
1450 The sign is positive if @var{Y} is positive. If @var{Y} is zero, then
1451 the return value is zero if @var{X} is positive and @math{\pi} if @var{X}
1452 is negative. Finally, if @var{X} is zero, then the magnitude of the result
1455 @item @emph{Example}:
1458 real(4) :: x = 1.e0_4, y = 0.5e0_4
1460 end program test_atan2
1463 @item @emph{Specific names}:
1464 @multitable @columnfractions .20 .20 .20 .25
1465 @item Name @tab Argument @tab Return type @tab Standard
1466 @item @code{ATAN2(X, Y)} @tab @code{REAL(4) X, Y} @tab @code{REAL(4)} @tab Fortran 77 and later
1467 @item @code{DATAN2(X, Y)} @tab @code{REAL(8) X, Y} @tab @code{REAL(8)} @tab Fortran 77 and later
1474 @section @code{ATANH} --- Hyperbolic arctangent function
1477 @cindex area hyperbolic tangent
1478 @cindex hyperbolic arctangent
1479 @cindex hyperbolic function, tangent, inverse
1480 @cindex tangent, hyperbolic, inverse
1483 @item @emph{Description}:
1484 @code{ATANH(X)} computes the hyperbolic arctangent of @var{X} (inverse
1487 @item @emph{Standard}:
1488 Fortran 2008 and later
1493 @item @emph{Syntax}:
1494 @code{RESULT = ATANH(X)}
1496 @item @emph{Arguments}:
1497 @multitable @columnfractions .15 .70
1498 @item @var{X} @tab The type shall be @code{REAL} or @code{COMPLEX}.
1501 @item @emph{Return value}:
1502 The return value has same type and kind as @var{X}. If @var{X} is
1503 complex, the imaginary part of the result is in radians and lies between
1504 @math{-\pi/2 \leq \Im \atanh(x) \leq \pi/2}.
1506 @item @emph{Example}:
1509 REAL, DIMENSION(3) :: x = (/ -1.0, 0.0, 1.0 /)
1510 WRITE (*,*) ATANH(x)
1514 @item @emph{Specific names}:
1515 @multitable @columnfractions .20 .20 .20 .25
1516 @item Name @tab Argument @tab Return type @tab Standard
1517 @item @code{DATANH(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU extension
1520 @item @emph{See also}:
1521 Inverse function: @ref{TANH}
1527 @section @code{BESSEL_J0} --- Bessel function of the first kind of order 0
1531 @cindex Bessel function, first kind
1534 @item @emph{Description}:
1535 @code{BESSEL_J0(X)} computes the Bessel function of the first kind of
1536 order 0 of @var{X}. This function is available under the name
1537 @code{BESJ0} as a GNU extension.
1539 @item @emph{Standard}:
1540 Fortran 2008 and later
1545 @item @emph{Syntax}:
1546 @code{RESULT = BESSEL_J0(X)}
1548 @item @emph{Arguments}:
1549 @multitable @columnfractions .15 .70
1550 @item @var{X} @tab The type shall be @code{REAL}, and it shall be scalar.
1553 @item @emph{Return value}:
1554 The return value is of type @code{REAL} and lies in the
1555 range @math{ - 0.4027... \leq Bessel (0,x) \leq 1}. It has the same
1558 @item @emph{Example}:
1561 real(8) :: x = 0.0_8
1563 end program test_besj0
1566 @item @emph{Specific names}:
1567 @multitable @columnfractions .20 .20 .20 .25
1568 @item Name @tab Argument @tab Return type @tab Standard
1569 @item @code{DBESJ0(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU extension
1576 @section @code{BESSEL_J1} --- Bessel function of the first kind of order 1
1580 @cindex Bessel function, first kind
1583 @item @emph{Description}:
1584 @code{BESSEL_J1(X)} computes the Bessel function of the first kind of
1585 order 1 of @var{X}. This function is available under the name
1586 @code{BESJ1} as a GNU extension.
1588 @item @emph{Standard}:
1594 @item @emph{Syntax}:
1595 @code{RESULT = BESSEL_J1(X)}
1597 @item @emph{Arguments}:
1598 @multitable @columnfractions .15 .70
1599 @item @var{X} @tab The type shall be @code{REAL}, and it shall be scalar.
1602 @item @emph{Return value}:
1603 The return value is of type @code{REAL} and it lies in the
1604 range @math{ - 0.5818... \leq Bessel (0,x) \leq 0.5818 }. It has the same
1607 @item @emph{Example}:
1610 real(8) :: x = 1.0_8
1612 end program test_besj1
1615 @item @emph{Specific names}:
1616 @multitable @columnfractions .20 .20 .20 .25
1617 @item Name @tab Argument @tab Return type @tab Standard
1618 @item @code{DBESJ1(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU extension
1625 @section @code{BESSEL_JN} --- Bessel function of the first kind
1629 @cindex Bessel function, first kind
1632 @item @emph{Description}:
1633 @code{BESSEL_JN(N, X)} computes the Bessel function of the first kind of
1634 order @var{N} of @var{X}. This function is available under the name
1635 @code{BESJN} as a GNU extension.
1637 If both arguments are arrays, their ranks and shapes shall conform.
1639 @item @emph{Standard}:
1640 Fortran 2008 and later
1645 @item @emph{Syntax}:
1646 @code{RESULT = BESSEL_JN(N, X)}
1648 @item @emph{Arguments}:
1649 @multitable @columnfractions .15 .70
1650 @item @var{N} @tab Shall be a scalar or an array of type @code{INTEGER}.
1651 @item @var{X} @tab Shall be a scalar or an array of type @code{REAL}.
1654 @item @emph{Return value}:
1655 The return value is a scalar of type @code{REAL}. It has the same
1658 @item @emph{Example}:
1661 real(8) :: x = 1.0_8
1663 end program test_besjn
1666 @item @emph{Specific names}:
1667 @multitable @columnfractions .20 .20 .20 .25
1668 @item Name @tab Argument @tab Return type @tab Standard
1669 @item @code{DBESJN(N, X)} @tab @code{INTEGER N} @tab @code{REAL(8)} @tab GNU extension
1670 @item @tab @code{REAL(8) X} @tab @tab
1677 @section @code{BESSEL_Y0} --- Bessel function of the second kind of order 0
1681 @cindex Bessel function, second kind
1684 @item @emph{Description}:
1685 @code{BESSEL_Y0(X)} computes the Bessel function of the second kind of
1686 order 0 of @var{X}. This function is available under the name
1687 @code{BESY0} as a GNU extension.
1689 @item @emph{Standard}:
1690 Fortran 2008 and later
1695 @item @emph{Syntax}:
1696 @code{RESULT = BESSEL_Y0(X)}
1698 @item @emph{Arguments}:
1699 @multitable @columnfractions .15 .70
1700 @item @var{X} @tab The type shall be @code{REAL}, and it shall be scalar.
1703 @item @emph{Return value}:
1704 The return value is a scalar of type @code{REAL}. It has the same
1707 @item @emph{Example}:
1710 real(8) :: x = 0.0_8
1712 end program test_besy0
1715 @item @emph{Specific names}:
1716 @multitable @columnfractions .20 .20 .20 .25
1717 @item Name @tab Argument @tab Return type @tab Standard
1718 @item @code{DBESY0(X)}@tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU extension
1725 @section @code{BESSEL_Y1} --- Bessel function of the second kind of order 1
1729 @cindex Bessel function, second kind
1732 @item @emph{Description}:
1733 @code{BESSEL_Y1(X)} computes the Bessel function of the second kind of
1734 order 1 of @var{X}. This function is available under the name
1735 @code{BESY1} as a GNU extension.
1737 @item @emph{Standard}:
1738 Fortran 2008 and later
1743 @item @emph{Syntax}:
1744 @code{RESULT = BESSEL_Y1(X)}
1746 @item @emph{Arguments}:
1747 @multitable @columnfractions .15 .70
1748 @item @var{X} @tab The type shall be @code{REAL}, and it shall be scalar.
1751 @item @emph{Return value}:
1752 The return value is a scalar of type @code{REAL}. It has the same
1755 @item @emph{Example}:
1758 real(8) :: x = 1.0_8
1760 end program test_besy1
1763 @item @emph{Specific names}:
1764 @multitable @columnfractions .20 .20 .20 .25
1765 @item Name @tab Argument @tab Return type @tab Standard
1766 @item @code{DBESY1(X)}@tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU extension
1773 @section @code{BESSEL_YN} --- Bessel function of the second kind
1777 @cindex Bessel function, second kind
1780 @item @emph{Description}:
1781 @code{BESSEL_YN(N, X)} computes the Bessel function of the second kind of
1782 order @var{N} of @var{X}. This function is available under the name
1783 @code{BESYN} as a GNU extension.
1785 If both arguments are arrays, their ranks and shapes shall conform.
1787 @item @emph{Standard}:
1788 Fortran 2008 and later
1793 @item @emph{Syntax}:
1794 @code{RESULT = BESSEL_YN(N, X)}
1796 @item @emph{Arguments}:
1797 @multitable @columnfractions .15 .70
1798 @item @var{N} @tab Shall be a scalar or an array of type @code{INTEGER}.
1799 @item @var{X} @tab Shall be a scalar or an array of type @code{REAL}.
1802 @item @emph{Return value}:
1803 The return value is a scalar of type @code{REAL}. It has the same
1806 @item @emph{Example}:
1809 real(8) :: x = 1.0_8
1811 end program test_besyn
1814 @item @emph{Specific names}:
1815 @multitable @columnfractions .20 .20 .20 .25
1816 @item Name @tab Argument @tab Return type @tab Standard
1817 @item @code{DBESYN(N,X)} @tab @code{INTEGER N} @tab @code{REAL(8)} @tab GNU extension
1818 @item @tab @code{REAL(8) X} @tab @tab
1825 @section @code{BIT_SIZE} --- Bit size inquiry function
1827 @cindex bits, number of
1828 @cindex size of a variable, in bits
1831 @item @emph{Description}:
1832 @code{BIT_SIZE(I)} returns the number of bits (integer precision plus sign bit)
1833 represented by the type of @var{I}. The result of @code{BIT_SIZE(I)} is
1834 independent of the actual value of @var{I}.
1836 @item @emph{Standard}:
1837 Fortran 95 and later
1842 @item @emph{Syntax}:
1843 @code{RESULT = BIT_SIZE(I)}
1845 @item @emph{Arguments}:
1846 @multitable @columnfractions .15 .70
1847 @item @var{I} @tab The type shall be @code{INTEGER}.
1850 @item @emph{Return value}:
1851 The return value is of type @code{INTEGER}
1853 @item @emph{Example}:
1855 program test_bit_size
1860 end program test_bit_size
1867 @section @code{BTEST} --- Bit test function
1869 @cindex bits, testing
1872 @item @emph{Description}:
1873 @code{BTEST(I,POS)} returns logical @code{.TRUE.} if the bit at @var{POS}
1874 in @var{I} is set. The counting of the bits starts at 0.
1876 @item @emph{Standard}:
1877 Fortran 95 and later
1882 @item @emph{Syntax}:
1883 @code{RESULT = BTEST(I, POS)}
1885 @item @emph{Arguments}:
1886 @multitable @columnfractions .15 .70
1887 @item @var{I} @tab The type shall be @code{INTEGER}.
1888 @item @var{POS} @tab The type shall be @code{INTEGER}.
1891 @item @emph{Return value}:
1892 The return value is of type @code{LOGICAL}
1894 @item @emph{Example}:
1897 integer :: i = 32768 + 1024 + 64
1901 bool = btest(i, pos)
1904 end program test_btest
1910 @section @code{C_ASSOCIATED} --- Status of a C pointer
1911 @fnindex C_ASSOCIATED
1912 @cindex association status, C pointer
1913 @cindex pointer, C association status
1916 @item @emph{Description}:
1917 @code{C_ASSOCIATED(c_prt_1[, c_ptr_2])} determines the status of the C pointer
1918 @var{c_ptr_1} or if @var{c_ptr_1} is associated with the target @var{c_ptr_2}.
1920 @item @emph{Standard}:
1921 Fortran 2003 and later
1926 @item @emph{Syntax}:
1927 @code{RESULT = C_ASSOCIATED(c_prt_1[, c_ptr_2])}
1929 @item @emph{Arguments}:
1930 @multitable @columnfractions .15 .70
1931 @item @var{c_ptr_1} @tab Scalar of the type @code{C_PTR} or @code{C_FUNPTR}.
1932 @item @var{c_ptr_2} @tab (Optional) Scalar of the same type as @var{c_ptr_1}.
1935 @item @emph{Return value}:
1936 The return value is of type @code{LOGICAL}; it is @code{.false.} if either
1937 @var{c_ptr_1} is a C NULL pointer or if @var{c_ptr1} and @var{c_ptr_2}
1938 point to different addresses.
1940 @item @emph{Example}:
1942 subroutine association_test(a,b)
1943 use iso_c_binding, only: c_associated, c_loc, c_ptr
1947 if(c_associated(b, c_loc(a))) &
1948 stop 'b and a do not point to same target'
1949 end subroutine association_test
1952 @item @emph{See also}:
1953 @ref{C_LOC}, @ref{C_FUNLOC}
1958 @section @code{C_FUNLOC} --- Obtain the C address of a procedure
1960 @cindex pointer, C address of procedures
1963 @item @emph{Description}:
1964 @code{C_FUNLOC(x)} determines the C address of the argument.
1966 @item @emph{Standard}:
1967 Fortran 2003 and later
1972 @item @emph{Syntax}:
1973 @code{RESULT = C_FUNLOC(x)}
1975 @item @emph{Arguments}:
1976 @multitable @columnfractions .15 .70
1977 @item @var{x} @tab Interoperable function or pointer to such function.
1980 @item @emph{Return value}:
1981 The return value is of type @code{C_FUNPTR} and contains the C address
1984 @item @emph{Example}:
1990 subroutine sub(a) bind(c)
2000 subroutine my_routine(p) bind(c,name='myC_func')
2002 type(c_funptr), intent(in) :: p
2005 call my_routine(c_funloc(sub))
2009 @item @emph{See also}:
2010 @ref{C_ASSOCIATED}, @ref{C_LOC}, @ref{C_F_POINTER}, @ref{C_F_PROCPOINTER}
2014 @node C_F_PROCPOINTER
2015 @section @code{C_F_PROCPOINTER} --- Convert C into Fortran procedure pointer
2016 @fnindex C_F_PROCPOINTER
2017 @cindex pointer, C address of pointers
2020 @item @emph{Description}:
2021 @code{C_F_PROCPOINTER(CPTR, FPTR)} Assign the target of the C function pointer
2022 @var{CPTR} to the Fortran procedure pointer @var{FPTR}.
2024 @item @emph{Standard}:
2025 Fortran 2003 and later
2030 @item @emph{Syntax}:
2031 @code{CALL C_F_PROCPOINTER(cptr, fptr)}
2033 @item @emph{Arguments}:
2034 @multitable @columnfractions .15 .70
2035 @item @var{CPTR} @tab scalar of the type @code{C_FUNPTR}. It is
2037 @item @var{FPTR} @tab procedure pointer interoperable with @var{cptr}. It is
2041 @item @emph{Example}:
2049 real(c_float), intent(in) :: a
2050 real(c_float) :: func
2054 function getIterFunc() bind(c,name="getIterFunc")
2056 type(c_funptr) :: getIterFunc
2059 type(c_funptr) :: cfunptr
2060 procedure(func), pointer :: myFunc
2061 cfunptr = getIterFunc()
2062 call c_f_procpointer(cfunptr, myFunc)
2066 @item @emph{See also}:
2067 @ref{C_LOC}, @ref{C_F_POINTER}
2072 @section @code{C_F_POINTER} --- Convert C into Fortran pointer
2073 @fnindex C_F_POINTER
2074 @cindex pointer, convert C to Fortran
2077 @item @emph{Description}:
2078 @code{C_F_POINTER(CPTR, FPTR[, SHAPE])} Assign the target the C pointer
2079 @var{CPTR} to the Fortran pointer @var{FPTR} and specify its
2082 @item @emph{Standard}:
2083 Fortran 2003 and later
2088 @item @emph{Syntax}:
2089 @code{CALL C_F_POINTER(CPTR, FPTR[, SHAPE])}
2091 @item @emph{Arguments}:
2092 @multitable @columnfractions .15 .70
2093 @item @var{CPTR} @tab scalar of the type @code{C_PTR}. It is
2095 @item @var{FPTR} @tab pointer interoperable with @var{cptr}. It is
2097 @item @var{SHAPE} @tab (Optional) Rank-one array of type @code{INTEGER}
2098 with @code{INTENT(IN)}. It shall be present
2099 if and only if @var{fptr} is an array. The size
2100 must be equal to the rank of @var{fptr}.
2103 @item @emph{Example}:
2109 subroutine my_routine(p) bind(c,name='myC_func')
2111 type(c_ptr), intent(out) :: p
2115 real,pointer :: a(:)
2116 call my_routine(cptr)
2117 call c_f_pointer(cptr, a, [12])
2121 @item @emph{See also}:
2122 @ref{C_LOC}, @ref{C_F_PROCPOINTER}
2127 @section @code{C_LOC} --- Obtain the C address of an object
2129 @cindex procedure pointer, convert C to Fortran
2132 @item @emph{Description}:
2133 @code{C_LOC(X)} determines the C address of the argument.
2135 @item @emph{Standard}:
2136 Fortran 2003 and later
2141 @item @emph{Syntax}:
2142 @code{RESULT = C_LOC(X)}
2144 @item @emph{Arguments}:
2145 @multitable @columnfractions .10 .75
2146 @item @var{X} @tab Shall have either the POINTER or TARGET attribute. It shall not be a coindexed object. It shall either be a variable with interoperable type and kind type parameters, or be a scalar, nonpolymorphic variable with no length type parameters.
2150 @item @emph{Return value}:
2151 The return value is of type @code{C_PTR} and contains the C address
2154 @item @emph{Example}:
2156 subroutine association_test(a,b)
2157 use iso_c_binding, only: c_associated, c_loc, c_ptr
2161 if(c_associated(b, c_loc(a))) &
2162 stop 'b and a do not point to same target'
2163 end subroutine association_test
2166 @item @emph{See also}:
2167 @ref{C_ASSOCIATED}, @ref{C_FUNLOC}, @ref{C_F_POINTER}, @ref{C_F_PROCPOINTER}
2172 @section @code{C_SIZEOF} --- Size in bytes of an expression
2174 @cindex expression size
2175 @cindex size of an expression
2178 @item @emph{Description}:
2179 @code{C_SIZEOF(X)} calculates the number of bytes of storage the
2180 expression @code{X} occupies.
2182 @item @emph{Standard}:
2188 @item @emph{Syntax}:
2189 @code{N = C_SIZEOF(X)}
2191 @item @emph{Arguments}:
2192 @multitable @columnfractions .15 .70
2193 @item @var{X} @tab The argument shall be an interoperable data entity.
2196 @item @emph{Return value}:
2197 The return value is of type integer and of the system-dependent kind
2198 @var{C_SIZE_T} (from the @var{ISO_C_BINDING} module). Its value is the
2199 number of bytes occupied by the argument. If the argument has the
2200 @code{POINTER} attribute, the number of bytes of the storage area pointed
2201 to is returned. If the argument is of a derived type with @code{POINTER}
2202 or @code{ALLOCATABLE} components, the return value doesn't account for
2203 the sizes of the data pointed to by these components.
2205 @item @emph{Example}:
2209 real(c_float) :: r, s(5)
2210 print *, (c_sizeof(s)/c_sizeof(r) == 5)
2213 The example will print @code{.TRUE.} unless you are using a platform
2214 where default @code{REAL} variables are unusually padded.
2216 @item @emph{See also}:
2217 @ref{SIZEOF}, @ref{STORAGE_SIZE}
2222 @section @code{CEILING} --- Integer ceiling function
2225 @cindex rounding, ceiling
2228 @item @emph{Description}:
2229 @code{CEILING(A)} returns the least integer greater than or equal to @var{A}.
2231 @item @emph{Standard}:
2232 Fortran 95 and later
2237 @item @emph{Syntax}:
2238 @code{RESULT = CEILING(A [, KIND])}
2240 @item @emph{Arguments}:
2241 @multitable @columnfractions .15 .70
2242 @item @var{A} @tab The type shall be @code{REAL}.
2243 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
2244 expression indicating the kind parameter of the result.
2247 @item @emph{Return value}:
2248 The return value is of type @code{INTEGER(KIND)} if @var{KIND} is present
2249 and a default-kind @code{INTEGER} otherwise.
2251 @item @emph{Example}:
2253 program test_ceiling
2256 print *, ceiling(x) ! returns 64
2257 print *, ceiling(y) ! returns -63
2258 end program test_ceiling
2261 @item @emph{See also}:
2262 @ref{FLOOR}, @ref{NINT}
2269 @section @code{CHAR} --- Character conversion function
2271 @cindex conversion, to character
2274 @item @emph{Description}:
2275 @code{CHAR(I [, KIND])} returns the character represented by the integer @var{I}.
2277 @item @emph{Standard}:
2278 Fortran 77 and later
2283 @item @emph{Syntax}:
2284 @code{RESULT = CHAR(I [, KIND])}
2286 @item @emph{Arguments}:
2287 @multitable @columnfractions .15 .70
2288 @item @var{I} @tab The type shall be @code{INTEGER}.
2289 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
2290 expression indicating the kind parameter of the result.
2293 @item @emph{Return value}:
2294 The return value is of type @code{CHARACTER(1)}
2296 @item @emph{Example}:
2302 print *, i, c ! returns 'J'
2303 end program test_char
2306 @item @emph{Specific names}:
2307 @multitable @columnfractions .20 .20 .20 .25
2308 @item Name @tab Argument @tab Return type @tab Standard
2309 @item @code{CHAR(I)} @tab @code{INTEGER I} @tab @code{CHARACTER(LEN=1)} @tab F77 and later
2313 See @ref{ICHAR} for a discussion of converting between numerical values
2314 and formatted string representations.
2316 @item @emph{See also}:
2317 @ref{ACHAR}, @ref{IACHAR}, @ref{ICHAR}
2324 @section @code{CHDIR} --- Change working directory
2326 @cindex system, working directory
2329 @item @emph{Description}:
2330 Change current working directory to a specified path.
2332 This intrinsic is provided in both subroutine and function forms; however,
2333 only one form can be used in any given program unit.
2335 @item @emph{Standard}:
2339 Subroutine, function
2341 @item @emph{Syntax}:
2342 @multitable @columnfractions .80
2343 @item @code{CALL CHDIR(NAME [, STATUS])}
2344 @item @code{STATUS = CHDIR(NAME)}
2347 @item @emph{Arguments}:
2348 @multitable @columnfractions .15 .70
2349 @item @var{NAME} @tab The type shall be @code{CHARACTER} of default
2350 kind and shall specify a valid path within the file system.
2351 @item @var{STATUS} @tab (Optional) @code{INTEGER} status flag of the default
2352 kind. Returns 0 on success, and a system specific and nonzero error code
2356 @item @emph{Example}:
2359 CHARACTER(len=255) :: path
2361 WRITE(*,*) TRIM(path)
2364 WRITE(*,*) TRIM(path)
2368 @item @emph{See also}:
2375 @section @code{CHMOD} --- Change access permissions of files
2377 @cindex file system, change access mode
2380 @item @emph{Description}:
2381 @code{CHMOD} changes the permissions of a file. This function invokes
2382 @code{/bin/chmod} and might therefore not work on all platforms.
2384 This intrinsic is provided in both subroutine and function forms; however,
2385 only one form can be used in any given program unit.
2387 @item @emph{Standard}:
2391 Subroutine, function
2393 @item @emph{Syntax}:
2394 @multitable @columnfractions .80
2395 @item @code{CALL CHMOD(NAME, MODE[, STATUS])}
2396 @item @code{STATUS = CHMOD(NAME, MODE)}
2399 @item @emph{Arguments}:
2400 @multitable @columnfractions .15 .70
2402 @item @var{NAME} @tab Scalar @code{CHARACTER} of default kind with the
2403 file name. Trailing blanks are ignored unless the character
2404 @code{achar(0)} is present, then all characters up to and excluding
2405 @code{achar(0)} are used as the file name.
2407 @item @var{MODE} @tab Scalar @code{CHARACTER} of default kind giving the
2408 file permission. @var{MODE} uses the same syntax as the @var{MODE}
2409 argument of @code{/bin/chmod}.
2411 @item @var{STATUS} @tab (optional) scalar @code{INTEGER}, which is
2412 @code{0} on success and nonzero otherwise.
2415 @item @emph{Return value}:
2416 In either syntax, @var{STATUS} is set to @code{0} on success and nonzero
2419 @item @emph{Example}:
2420 @code{CHMOD} as subroutine
2425 call chmod('test.dat','u+x',status)
2426 print *, 'Status: ', status
2427 end program chmod_test
2429 @code{CHMOD} as function:
2434 status = chmod('test.dat','u+x')
2435 print *, 'Status: ', status
2436 end program chmod_test
2444 @section @code{CMPLX} --- Complex conversion function
2446 @cindex complex numbers, conversion to
2447 @cindex conversion, to complex
2450 @item @emph{Description}:
2451 @code{CMPLX(X [, Y [, KIND]])} returns a complex number where @var{X} is converted to
2452 the real component. If @var{Y} is present it is converted to the imaginary
2453 component. If @var{Y} is not present then the imaginary component is set to
2454 0.0. If @var{X} is complex then @var{Y} must not be present.
2456 @item @emph{Standard}:
2457 Fortran 77 and later
2462 @item @emph{Syntax}:
2463 @code{RESULT = CMPLX(X [, Y [, KIND]])}
2465 @item @emph{Arguments}:
2466 @multitable @columnfractions .15 .70
2467 @item @var{X} @tab The type may be @code{INTEGER}, @code{REAL},
2469 @item @var{Y} @tab (Optional; only allowed if @var{X} is not
2470 @code{COMPLEX}.) May be @code{INTEGER} or @code{REAL}.
2471 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
2472 expression indicating the kind parameter of the result.
2475 @item @emph{Return value}:
2476 The return value is of @code{COMPLEX} type, with a kind equal to
2477 @var{KIND} if it is specified. If @var{KIND} is not specified, the
2478 result is of the default @code{COMPLEX} kind, regardless of the kinds of
2479 @var{X} and @var{Y}.
2481 @item @emph{Example}:
2488 print *, z, cmplx(x)
2489 end program test_cmplx
2492 @item @emph{See also}:
2498 @node COMMAND_ARGUMENT_COUNT
2499 @section @code{COMMAND_ARGUMENT_COUNT} --- Get number of command line arguments
2500 @fnindex COMMAND_ARGUMENT_COUNT
2501 @cindex command-line arguments
2502 @cindex command-line arguments, number of
2503 @cindex arguments, to program
2506 @item @emph{Description}:
2507 @code{COMMAND_ARGUMENT_COUNT()} returns the number of arguments passed on the
2508 command line when the containing program was invoked.
2510 @item @emph{Standard}:
2511 Fortran 2003 and later
2516 @item @emph{Syntax}:
2517 @code{RESULT = COMMAND_ARGUMENT_COUNT()}
2519 @item @emph{Arguments}:
2520 @multitable @columnfractions .15 .70
2524 @item @emph{Return value}:
2525 The return value is an @code{INTEGER} of default kind.
2527 @item @emph{Example}:
2529 program test_command_argument_count
2531 count = command_argument_count()
2533 end program test_command_argument_count
2536 @item @emph{See also}:
2537 @ref{GET_COMMAND}, @ref{GET_COMMAND_ARGUMENT}
2543 @section @code{COMPLEX} --- Complex conversion function
2545 @cindex complex numbers, conversion to
2546 @cindex conversion, to complex
2549 @item @emph{Description}:
2550 @code{COMPLEX(X, Y)} returns a complex number where @var{X} is converted
2551 to the real component and @var{Y} is converted to the imaginary
2554 @item @emph{Standard}:
2560 @item @emph{Syntax}:
2561 @code{RESULT = COMPLEX(X, Y)}
2563 @item @emph{Arguments}:
2564 @multitable @columnfractions .15 .70
2565 @item @var{X} @tab The type may be @code{INTEGER} or @code{REAL}.
2566 @item @var{Y} @tab The type may be @code{INTEGER} or @code{REAL}.
2569 @item @emph{Return value}:
2570 If @var{X} and @var{Y} are both of @code{INTEGER} type, then the return
2571 value is of default @code{COMPLEX} type.
2573 If @var{X} and @var{Y} are of @code{REAL} type, or one is of @code{REAL}
2574 type and one is of @code{INTEGER} type, then the return value is of
2575 @code{COMPLEX} type with a kind equal to that of the @code{REAL}
2576 argument with the highest precision.
2578 @item @emph{Example}:
2580 program test_complex
2583 print *, complex(i, x)
2584 end program test_complex
2587 @item @emph{See also}:
2594 @section @code{CONJG} --- Complex conjugate function
2597 @cindex complex conjugate
2600 @item @emph{Description}:
2601 @code{CONJG(Z)} returns the conjugate of @var{Z}. If @var{Z} is @code{(x, y)}
2602 then the result is @code{(x, -y)}
2604 @item @emph{Standard}:
2605 Fortran 77 and later, has overloads that are GNU extensions
2610 @item @emph{Syntax}:
2613 @item @emph{Arguments}:
2614 @multitable @columnfractions .15 .70
2615 @item @var{Z} @tab The type shall be @code{COMPLEX}.
2618 @item @emph{Return value}:
2619 The return value is of type @code{COMPLEX}.
2621 @item @emph{Example}:
2624 complex :: z = (2.0, 3.0)
2625 complex(8) :: dz = (2.71_8, -3.14_8)
2630 end program test_conjg
2633 @item @emph{Specific names}:
2634 @multitable @columnfractions .20 .20 .20 .25
2635 @item Name @tab Argument @tab Return type @tab Standard
2636 @item @code{CONJG(Z)} @tab @code{COMPLEX Z} @tab @code{COMPLEX} @tab GNU extension
2637 @item @code{DCONJG(Z)} @tab @code{COMPLEX(8) Z} @tab @code{COMPLEX(8)} @tab GNU extension
2644 @section @code{COS} --- Cosine function
2650 @cindex trigonometric function, cosine
2654 @item @emph{Description}:
2655 @code{COS(X)} computes the cosine of @var{X}.
2657 @item @emph{Standard}:
2658 Fortran 77 and later, has overloads that are GNU extensions
2663 @item @emph{Syntax}:
2664 @code{RESULT = COS(X)}
2666 @item @emph{Arguments}:
2667 @multitable @columnfractions .15 .70
2668 @item @var{X} @tab The type shall be @code{REAL} or
2672 @item @emph{Return value}:
2673 The return value is of the same type and kind as @var{X}. The real part
2674 of the result is in radians. If @var{X} is of the type @code{REAL},
2675 the return value lies in the range @math{ -1 \leq \cos (x) \leq 1}.
2677 @item @emph{Example}:
2682 end program test_cos
2685 @item @emph{Specific names}:
2686 @multitable @columnfractions .20 .20 .20 .25
2687 @item Name @tab Argument @tab Return type @tab Standard
2688 @item @code{COS(X)} n@tab @code{REAL(4) X} @tab @code{REAL(4)} @tab Fortran 77 and later
2689 @item @code{DCOS(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab Fortran 77 and later
2690 @item @code{CCOS(X)} @tab @code{COMPLEX(4) X} @tab @code{COMPLEX(4)} @tab Fortran 77 and later
2691 @item @code{ZCOS(X)} @tab @code{COMPLEX(8) X} @tab @code{COMPLEX(8)} @tab GNU extension
2692 @item @code{CDCOS(X)} @tab @code{COMPLEX(8) X} @tab @code{COMPLEX(8)} @tab GNU extension
2695 @item @emph{See also}:
2696 Inverse function: @ref{ACOS}
2703 @section @code{COSH} --- Hyperbolic cosine function
2706 @cindex hyperbolic cosine
2707 @cindex hyperbolic function, cosine
2708 @cindex cosine, hyperbolic
2711 @item @emph{Description}:
2712 @code{COSH(X)} computes the hyperbolic cosine of @var{X}.
2714 @item @emph{Standard}:
2715 Fortran 77 and later, for a complex argument Fortran 2008 or later
2720 @item @emph{Syntax}:
2723 @item @emph{Arguments}:
2724 @multitable @columnfractions .15 .70
2725 @item @var{X} @tab The type shall be @code{REAL} or @code{COMPLEX}.
2728 @item @emph{Return value}:
2729 The return value has same type and kind as @var{X}. If @var{X} is
2730 complex, the imaginary part of the result is in radians. If @var{X}
2731 is @code{REAL}, the return value has a lower bound of one,
2732 @math{\cosh (x) \geq 1}.
2734 @item @emph{Example}:
2737 real(8) :: x = 1.0_8
2739 end program test_cosh
2742 @item @emph{Specific names}:
2743 @multitable @columnfractions .20 .20 .20 .25
2744 @item Name @tab Argument @tab Return type @tab Standard
2745 @item @code{COSH(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab Fortran 77 and later
2746 @item @code{DCOSH(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab Fortran 77 and later
2749 @item @emph{See also}:
2750 Inverse function: @ref{ACOSH}
2757 @section @code{COUNT} --- Count function
2759 @cindex array, conditionally count elements
2760 @cindex array, element counting
2761 @cindex array, number of elements
2764 @item @emph{Description}:
2766 Counts the number of @code{.TRUE.} elements in a logical @var{MASK},
2767 or, if the @var{DIM} argument is supplied, counts the number of
2768 elements along each row of the array in the @var{DIM} direction.
2769 If the array has zero size, or all of the elements of @var{MASK} are
2770 @code{.FALSE.}, then the result is @code{0}.
2772 @item @emph{Standard}:
2773 Fortran 95 and later, with @var{KIND} argument Fortran 2003 and later
2776 Transformational function
2778 @item @emph{Syntax}:
2779 @code{RESULT = COUNT(MASK [, DIM, KIND])}
2781 @item @emph{Arguments}:
2782 @multitable @columnfractions .15 .70
2783 @item @var{MASK} @tab The type shall be @code{LOGICAL}.
2784 @item @var{DIM} @tab (Optional) The type shall be @code{INTEGER}.
2785 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
2786 expression indicating the kind parameter of the result.
2789 @item @emph{Return value}:
2790 The return value is of type @code{INTEGER} and of kind @var{KIND}. If
2791 @var{KIND} is absent, the return value is of default integer kind.
2792 If @var{DIM} is present, the result is an array with a rank one less
2793 than the rank of @var{ARRAY}, and a size corresponding to the shape
2794 of @var{ARRAY} with the @var{DIM} dimension removed.
2796 @item @emph{Example}:
2799 integer, dimension(2,3) :: a, b
2800 logical, dimension(2,3) :: mask
2801 a = reshape( (/ 1, 2, 3, 4, 5, 6 /), (/ 2, 3 /))
2802 b = reshape( (/ 0, 7, 3, 4, 5, 8 /), (/ 2, 3 /))
2803 print '(3i3)', a(1,:)
2804 print '(3i3)', a(2,:)
2806 print '(3i3)', b(1,:)
2807 print '(3i3)', b(2,:)
2810 print '(3l3)', mask(1,:)
2811 print '(3l3)', mask(2,:)
2813 print '(3i3)', count(mask)
2815 print '(3i3)', count(mask, 1)
2817 print '(3i3)', count(mask, 2)
2818 end program test_count
2825 @section @code{CPU_TIME} --- CPU elapsed time in seconds
2827 @cindex time, elapsed
2830 @item @emph{Description}:
2831 Returns a @code{REAL} value representing the elapsed CPU time in
2832 seconds. This is useful for testing segments of code to determine
2835 If a time source is available, time will be reported with microsecond
2836 resolution. If no time source is available, @var{TIME} is set to
2839 Note that @var{TIME} may contain a, system dependent, arbitrary offset
2840 and may not start with @code{0.0}. For @code{CPU_TIME}, the absolute
2841 value is meaningless, only differences between subsequent calls to
2842 this subroutine, as shown in the example below, should be used.
2845 @item @emph{Standard}:
2846 Fortran 95 and later
2851 @item @emph{Syntax}:
2852 @code{CALL CPU_TIME(TIME)}
2854 @item @emph{Arguments}:
2855 @multitable @columnfractions .15 .70
2856 @item @var{TIME} @tab The type shall be @code{REAL} with @code{INTENT(OUT)}.
2859 @item @emph{Return value}:
2862 @item @emph{Example}:
2864 program test_cpu_time
2865 real :: start, finish
2866 call cpu_time(start)
2867 ! put code to test here
2868 call cpu_time(finish)
2869 print '("Time = ",f6.3," seconds.")',finish-start
2870 end program test_cpu_time
2873 @item @emph{See also}:
2874 @ref{SYSTEM_CLOCK}, @ref{DATE_AND_TIME}
2880 @section @code{CSHIFT} --- Circular shift elements of an array
2882 @cindex array, shift circularly
2883 @cindex array, permutation
2884 @cindex array, rotate
2887 @item @emph{Description}:
2888 @code{CSHIFT(ARRAY, SHIFT [, DIM])} performs a circular shift on elements of
2889 @var{ARRAY} along the dimension of @var{DIM}. If @var{DIM} is omitted it is
2890 taken to be @code{1}. @var{DIM} is a scalar of type @code{INTEGER} in the
2891 range of @math{1 \leq DIM \leq n)} where @math{n} is the rank of @var{ARRAY}.
2892 If the rank of @var{ARRAY} is one, then all elements of @var{ARRAY} are shifted
2893 by @var{SHIFT} places. If rank is greater than one, then all complete rank one
2894 sections of @var{ARRAY} along the given dimension are shifted. Elements
2895 shifted out one end of each rank one section are shifted back in the other end.
2897 @item @emph{Standard}:
2898 Fortran 95 and later
2901 Transformational function
2903 @item @emph{Syntax}:
2904 @code{RESULT = CSHIFT(ARRAY, SHIFT [, DIM])}
2906 @item @emph{Arguments}:
2907 @multitable @columnfractions .15 .70
2908 @item @var{ARRAY} @tab Shall be an array of any type.
2909 @item @var{SHIFT} @tab The type shall be @code{INTEGER}.
2910 @item @var{DIM} @tab The type shall be @code{INTEGER}.
2913 @item @emph{Return value}:
2914 Returns an array of same type and rank as the @var{ARRAY} argument.
2916 @item @emph{Example}:
2919 integer, dimension(3,3) :: a
2920 a = reshape( (/ 1, 2, 3, 4, 5, 6, 7, 8, 9 /), (/ 3, 3 /))
2921 print '(3i3)', a(1,:)
2922 print '(3i3)', a(2,:)
2923 print '(3i3)', a(3,:)
2924 a = cshift(a, SHIFT=(/1, 2, -1/), DIM=2)
2926 print '(3i3)', a(1,:)
2927 print '(3i3)', a(2,:)
2928 print '(3i3)', a(3,:)
2929 end program test_cshift
2936 @section @code{CTIME} --- Convert a time into a string
2938 @cindex time, conversion to string
2939 @cindex conversion, to string
2942 @item @emph{Description}:
2943 @code{CTIME} converts a system time value, such as returned by
2944 @code{TIME8()}, to a string of the form @samp{Sat Aug 19 18:13:14 1995}.
2946 This intrinsic is provided in both subroutine and function forms; however,
2947 only one form can be used in any given program unit.
2949 @item @emph{Standard}:
2953 Subroutine, function
2955 @item @emph{Syntax}:
2956 @multitable @columnfractions .80
2957 @item @code{CALL CTIME(TIME, RESULT)}.
2958 @item @code{RESULT = CTIME(TIME)}, (not recommended).
2961 @item @emph{Arguments}:
2962 @multitable @columnfractions .15 .70
2963 @item @var{TIME} @tab The type shall be of type @code{INTEGER(KIND=8)}.
2964 @item @var{RESULT} @tab The type shall be of type @code{CHARACTER} and
2968 @item @emph{Return value}:
2969 The converted date and time as a string.
2971 @item @emph{Example}:
2975 character(len=30) :: date
2978 ! Do something, main part of the program
2981 print *, 'Program was started on ', date
2982 end program test_ctime
2985 @item @emph{See Also}:
2986 @ref{GMTIME}, @ref{LTIME}, @ref{TIME}, @ref{TIME8}
2992 @section @code{DATE_AND_TIME} --- Date and time subroutine
2993 @fnindex DATE_AND_TIME
2994 @cindex date, current
2995 @cindex current date
2996 @cindex time, current
2997 @cindex current time
3000 @item @emph{Description}:
3001 @code{DATE_AND_TIME(DATE, TIME, ZONE, VALUES)} gets the corresponding date and
3002 time information from the real-time system clock. @var{DATE} is
3003 @code{INTENT(OUT)} and has form ccyymmdd. @var{TIME} is @code{INTENT(OUT)} and
3004 has form hhmmss.sss. @var{ZONE} is @code{INTENT(OUT)} and has form (+-)hhmm,
3005 representing the difference with respect to Coordinated Universal Time (UTC).
3006 Unavailable time and date parameters return blanks.
3008 @var{VALUES} is @code{INTENT(OUT)} and provides the following:
3010 @multitable @columnfractions .15 .30 .40
3011 @item @tab @code{VALUE(1)}: @tab The year
3012 @item @tab @code{VALUE(2)}: @tab The month
3013 @item @tab @code{VALUE(3)}: @tab The day of the month
3014 @item @tab @code{VALUE(4)}: @tab Time difference with UTC in minutes
3015 @item @tab @code{VALUE(5)}: @tab The hour of the day
3016 @item @tab @code{VALUE(6)}: @tab The minutes of the hour
3017 @item @tab @code{VALUE(7)}: @tab The seconds of the minute
3018 @item @tab @code{VALUE(8)}: @tab The milliseconds of the second
3021 @item @emph{Standard}:
3022 Fortran 95 and later
3027 @item @emph{Syntax}:
3028 @code{CALL DATE_AND_TIME([DATE, TIME, ZONE, VALUES])}
3030 @item @emph{Arguments}:
3031 @multitable @columnfractions .15 .70
3032 @item @var{DATE} @tab (Optional) The type shall be @code{CHARACTER(LEN=8)}
3033 or larger, and of default kind.
3034 @item @var{TIME} @tab (Optional) The type shall be @code{CHARACTER(LEN=10)}
3035 or larger, and of default kind.
3036 @item @var{ZONE} @tab (Optional) The type shall be @code{CHARACTER(LEN=5)}
3037 or larger, and of default kind.
3038 @item @var{VALUES}@tab (Optional) The type shall be @code{INTEGER(8)}.
3041 @item @emph{Return value}:
3044 @item @emph{Example}:
3046 program test_time_and_date
3047 character(8) :: date
3048 character(10) :: time
3049 character(5) :: zone
3050 integer,dimension(8) :: values
3051 ! using keyword arguments
3052 call date_and_time(date,time,zone,values)
3053 call date_and_time(DATE=date,ZONE=zone)
3054 call date_and_time(TIME=time)
3055 call date_and_time(VALUES=values)
3056 print '(a,2x,a,2x,a)', date, time, zone
3057 print '(8i5))', values
3058 end program test_time_and_date
3061 @item @emph{See also}:
3062 @ref{CPU_TIME}, @ref{SYSTEM_CLOCK}
3068 @section @code{DBLE} --- Double conversion function
3070 @cindex conversion, to real
3073 @item @emph{Description}:
3074 @code{DBLE(A)} Converts @var{A} to double precision real type.
3076 @item @emph{Standard}:
3077 Fortran 77 and later
3082 @item @emph{Syntax}:
3083 @code{RESULT = DBLE(A)}
3085 @item @emph{Arguments}:
3086 @multitable @columnfractions .15 .70
3087 @item @var{A} @tab The type shall be @code{INTEGER}, @code{REAL},
3091 @item @emph{Return value}:
3092 The return value is of type double precision real.
3094 @item @emph{Example}:
3099 complex :: z = (2.3,1.14)
3100 print *, dble(x), dble(i), dble(z)
3101 end program test_dble
3104 @item @emph{See also}:
3111 @section @code{DCMPLX} --- Double complex conversion function
3113 @cindex complex numbers, conversion to
3114 @cindex conversion, to complex
3117 @item @emph{Description}:
3118 @code{DCMPLX(X [,Y])} returns a double complex number where @var{X} is
3119 converted to the real component. If @var{Y} is present it is converted to the
3120 imaginary component. If @var{Y} is not present then the imaginary component is
3121 set to 0.0. If @var{X} is complex then @var{Y} must not be present.
3123 @item @emph{Standard}:
3129 @item @emph{Syntax}:
3130 @code{RESULT = DCMPLX(X [, Y])}
3132 @item @emph{Arguments}:
3133 @multitable @columnfractions .15 .70
3134 @item @var{X} @tab The type may be @code{INTEGER}, @code{REAL},
3136 @item @var{Y} @tab (Optional if @var{X} is not @code{COMPLEX}.) May be
3137 @code{INTEGER} or @code{REAL}.
3140 @item @emph{Return value}:
3141 The return value is of type @code{COMPLEX(8)}
3143 @item @emph{Example}:
3153 print *, dcmplx(x,i)
3154 end program test_dcmplx
3160 @section @code{DIGITS} --- Significant binary digits function
3162 @cindex model representation, significant digits
3165 @item @emph{Description}:
3166 @code{DIGITS(X)} returns the number of significant binary digits of the internal
3167 model representation of @var{X}. For example, on a system using a 32-bit
3168 floating point representation, a default real number would likely return 24.
3170 @item @emph{Standard}:
3171 Fortran 95 and later
3176 @item @emph{Syntax}:
3177 @code{RESULT = DIGITS(X)}
3179 @item @emph{Arguments}:
3180 @multitable @columnfractions .15 .70
3181 @item @var{X} @tab The type may be @code{INTEGER} or @code{REAL}.
3184 @item @emph{Return value}:
3185 The return value is of type @code{INTEGER}.
3187 @item @emph{Example}:
3190 integer :: i = 12345
3196 end program test_digits
3203 @section @code{DIM} --- Positive difference
3207 @cindex positive difference
3210 @item @emph{Description}:
3211 @code{DIM(X,Y)} returns the difference @code{X-Y} if the result is positive;
3212 otherwise returns zero.
3214 @item @emph{Standard}:
3215 Fortran 77 and later
3220 @item @emph{Syntax}:
3221 @code{RESULT = DIM(X, Y)}
3223 @item @emph{Arguments}:
3224 @multitable @columnfractions .15 .70
3225 @item @var{X} @tab The type shall be @code{INTEGER} or @code{REAL}
3226 @item @var{Y} @tab The type shall be the same type and kind as @var{X}.
3229 @item @emph{Return value}:
3230 The return value is of type @code{INTEGER} or @code{REAL}.
3232 @item @emph{Example}:
3238 x = dim(4.345_8, 2.111_8)
3241 end program test_dim
3244 @item @emph{Specific names}:
3245 @multitable @columnfractions .20 .20 .20 .25
3246 @item Name @tab Argument @tab Return type @tab Standard
3247 @item @code{DIM(X,Y)} @tab @code{REAL(4) X, Y} @tab @code{REAL(4)} @tab Fortran 77 and later
3248 @item @code{IDIM(X,Y)} @tab @code{INTEGER(4) X, Y} @tab @code{INTEGER(4)} @tab Fortran 77 and later
3249 @item @code{DDIM(X,Y)} @tab @code{REAL(8) X, Y} @tab @code{REAL(8)} @tab Fortran 77 and later
3256 @section @code{DOT_PRODUCT} --- Dot product function
3257 @fnindex DOT_PRODUCT
3259 @cindex vector product
3260 @cindex product, vector
3263 @item @emph{Description}:
3264 @code{DOT_PRODUCT(VECTOR_A, VECTOR_B)} computes the dot product multiplication
3265 of two vectors @var{VECTOR_A} and @var{VECTOR_B}. The two vectors may be
3266 either numeric or logical and must be arrays of rank one and of equal size. If
3267 the vectors are @code{INTEGER} or @code{REAL}, the result is
3268 @code{SUM(VECTOR_A*VECTOR_B)}. If the vectors are @code{COMPLEX}, the result
3269 is @code{SUM(CONJG(VECTOR_A)*VECTOR_B)}. If the vectors are @code{LOGICAL},
3270 the result is @code{ANY(VECTOR_A .AND. VECTOR_B)}.
3272 @item @emph{Standard}:
3273 Fortran 95 and later
3276 Transformational function
3278 @item @emph{Syntax}:
3279 @code{RESULT = DOT_PRODUCT(VECTOR_A, VECTOR_B)}
3281 @item @emph{Arguments}:
3282 @multitable @columnfractions .15 .70
3283 @item @var{VECTOR_A} @tab The type shall be numeric or @code{LOGICAL}, rank 1.
3284 @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.
3287 @item @emph{Return value}:
3288 If the arguments are numeric, the return value is a scalar of numeric type,
3289 @code{INTEGER}, @code{REAL}, or @code{COMPLEX}. If the arguments are
3290 @code{LOGICAL}, the return value is @code{.TRUE.} or @code{.FALSE.}.
3292 @item @emph{Example}:
3294 program test_dot_prod
3295 integer, dimension(3) :: a, b
3302 print *, dot_product(a,b)
3303 end program test_dot_prod
3310 @section @code{DPROD} --- Double product function
3312 @cindex product, double-precision
3315 @item @emph{Description}:
3316 @code{DPROD(X,Y)} returns the product @code{X*Y}.
3318 @item @emph{Standard}:
3319 Fortran 77 and later
3324 @item @emph{Syntax}:
3325 @code{RESULT = DPROD(X, Y)}
3327 @item @emph{Arguments}:
3328 @multitable @columnfractions .15 .70
3329 @item @var{X} @tab The type shall be @code{REAL}.
3330 @item @var{Y} @tab The type shall be @code{REAL}.
3333 @item @emph{Return value}:
3334 The return value is of type @code{REAL(8)}.
3336 @item @emph{Example}:
3344 end program test_dprod
3347 @item @emph{Specific names}:
3348 @multitable @columnfractions .20 .20 .20 .25
3349 @item Name @tab Argument @tab Return type @tab Standard
3350 @item @code{DPROD(X,Y)} @tab @code{REAL(4) X, Y} @tab @code{REAL(4)} @tab Fortran 77 and later
3357 @section @code{DREAL} --- Double real part function
3359 @cindex complex numbers, real part
3362 @item @emph{Description}:
3363 @code{DREAL(Z)} returns the real part of complex variable @var{Z}.
3365 @item @emph{Standard}:
3371 @item @emph{Syntax}:
3372 @code{RESULT = DREAL(A)}
3374 @item @emph{Arguments}:
3375 @multitable @columnfractions .15 .70
3376 @item @var{A} @tab The type shall be @code{COMPLEX(8)}.
3379 @item @emph{Return value}:
3380 The return value is of type @code{REAL(8)}.
3382 @item @emph{Example}:
3385 complex(8) :: z = (1.3_8,7.2_8)
3387 end program test_dreal
3390 @item @emph{See also}:
3398 @section @code{DTIME} --- Execution time subroutine (or function)
3400 @cindex time, elapsed
3401 @cindex elapsed time
3404 @item @emph{Description}:
3405 @code{DTIME(VALUES, TIME)} initially returns the number of seconds of runtime
3406 since the start of the process's execution in @var{TIME}. @var{VALUES}
3407 returns the user and system components of this time in @code{VALUES(1)} and
3408 @code{VALUES(2)} respectively. @var{TIME} is equal to @code{VALUES(1) +
3411 Subsequent invocations of @code{DTIME} return values accumulated since the
3412 previous invocation.
3414 On some systems, the underlying timings are represented using types with
3415 sufficiently small limits that overflows (wrap around) are possible, such as
3416 32-bit types. Therefore, the values returned by this intrinsic might be, or
3417 become, negative, or numerically less than previous values, during a single
3418 run of the compiled program.
3420 Please note, that this implementation is thread safe if used within OpenMP
3421 directives, i.e., its state will be consistent while called from multiple
3422 threads. However, if @code{DTIME} is called from multiple threads, the result
3423 is still the time since the last invocation. This may not give the intended
3424 results. If possible, use @code{CPU_TIME} instead.
3426 This intrinsic is provided in both subroutine and function forms; however,
3427 only one form can be used in any given program unit.
3429 @var{VALUES} and @var{TIME} are @code{INTENT(OUT)} and provide the following:
3431 @multitable @columnfractions .15 .30 .40
3432 @item @tab @code{VALUES(1)}: @tab User time in seconds.
3433 @item @tab @code{VALUES(2)}: @tab System time in seconds.
3434 @item @tab @code{TIME}: @tab Run time since start in seconds.
3437 @item @emph{Standard}:
3441 Subroutine, function
3443 @item @emph{Syntax}:
3444 @multitable @columnfractions .80
3445 @item @code{CALL DTIME(VALUES, TIME)}.
3446 @item @code{TIME = DTIME(VALUES)}, (not recommended).
3449 @item @emph{Arguments}:
3450 @multitable @columnfractions .15 .70
3451 @item @var{VALUES}@tab The type shall be @code{REAL(4), DIMENSION(2)}.
3452 @item @var{TIME}@tab The type shall be @code{REAL(4)}.
3455 @item @emph{Return value}:
3456 Elapsed time in seconds since the last invocation or since the start of program
3457 execution if not called before.
3459 @item @emph{Example}:
3463 real, dimension(2) :: tarray
3465 call dtime(tarray, result)
3469 do i=1,100000000 ! Just a delay
3472 call dtime(tarray, result)
3476 end program test_dtime
3479 @item @emph{See also}:
3487 @section @code{EOSHIFT} --- End-off shift elements of an array
3489 @cindex array, shift
3492 @item @emph{Description}:
3493 @code{EOSHIFT(ARRAY, SHIFT[, BOUNDARY, DIM])} performs an end-off shift on
3494 elements of @var{ARRAY} along the dimension of @var{DIM}. If @var{DIM} is
3495 omitted it is taken to be @code{1}. @var{DIM} is a scalar of type
3496 @code{INTEGER} in the range of @math{1 \leq DIM \leq n)} where @math{n} is the
3497 rank of @var{ARRAY}. If the rank of @var{ARRAY} is one, then all elements of
3498 @var{ARRAY} are shifted by @var{SHIFT} places. If rank is greater than one,
3499 then all complete rank one sections of @var{ARRAY} along the given dimension are
3500 shifted. Elements shifted out one end of each rank one section are dropped. If
3501 @var{BOUNDARY} is present then the corresponding value of from @var{BOUNDARY}
3502 is copied back in the other end. If @var{BOUNDARY} is not present then the
3503 following are copied in depending on the type of @var{ARRAY}.
3505 @multitable @columnfractions .15 .80
3506 @item @emph{Array Type} @tab @emph{Boundary Value}
3507 @item Numeric @tab 0 of the type and kind of @var{ARRAY}.
3508 @item Logical @tab @code{.FALSE.}.
3509 @item Character(@var{len}) @tab @var{len} blanks.
3512 @item @emph{Standard}:
3513 Fortran 95 and later
3516 Transformational function
3518 @item @emph{Syntax}:
3519 @code{RESULT = EOSHIFT(ARRAY, SHIFT [, BOUNDARY, DIM])}
3521 @item @emph{Arguments}:
3522 @multitable @columnfractions .15 .70
3523 @item @var{ARRAY} @tab May be any type, not scalar.
3524 @item @var{SHIFT} @tab The type shall be @code{INTEGER}.
3525 @item @var{BOUNDARY} @tab Same type as @var{ARRAY}.
3526 @item @var{DIM} @tab The type shall be @code{INTEGER}.
3529 @item @emph{Return value}:
3530 Returns an array of same type and rank as the @var{ARRAY} argument.
3532 @item @emph{Example}:
3534 program test_eoshift
3535 integer, dimension(3,3) :: a
3536 a = reshape( (/ 1, 2, 3, 4, 5, 6, 7, 8, 9 /), (/ 3, 3 /))
3537 print '(3i3)', a(1,:)
3538 print '(3i3)', a(2,:)
3539 print '(3i3)', a(3,:)
3540 a = EOSHIFT(a, SHIFT=(/1, 2, 1/), BOUNDARY=-5, DIM=2)
3542 print '(3i3)', a(1,:)
3543 print '(3i3)', a(2,:)
3544 print '(3i3)', a(3,:)
3545 end program test_eoshift
3552 @section @code{EPSILON} --- Epsilon function
3554 @cindex model representation, epsilon
3557 @item @emph{Description}:
3558 @code{EPSILON(X)} returns the smallest number @var{E} of the same kind
3559 as @var{X} such that @math{1 + E > 1}.
3561 @item @emph{Standard}:
3562 Fortran 95 and later
3567 @item @emph{Syntax}:
3568 @code{RESULT = EPSILON(X)}
3570 @item @emph{Arguments}:
3571 @multitable @columnfractions .15 .70
3572 @item @var{X} @tab The type shall be @code{REAL}.
3575 @item @emph{Return value}:
3576 The return value is of same type as the argument.
3578 @item @emph{Example}:
3580 program test_epsilon
3585 end program test_epsilon
3592 @section @code{ERF} --- Error function
3594 @cindex error function
3597 @item @emph{Description}:
3598 @code{ERF(X)} computes the error function of @var{X}.
3600 @item @emph{Standard}:
3601 Fortran 2008 and later
3606 @item @emph{Syntax}:
3607 @code{RESULT = ERF(X)}
3609 @item @emph{Arguments}:
3610 @multitable @columnfractions .15 .70
3611 @item @var{X} @tab The type shall be @code{REAL}.
3614 @item @emph{Return value}:
3615 The return value is of type @code{REAL}, of the same kind as
3616 @var{X} and lies in the range @math{-1 \leq erf (x) \leq 1 }.
3618 @item @emph{Example}:
3621 real(8) :: x = 0.17_8
3623 end program test_erf
3626 @item @emph{Specific names}:
3627 @multitable @columnfractions .20 .20 .20 .25
3628 @item Name @tab Argument @tab Return type @tab Standard
3629 @item @code{DERF(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU extension
3636 @section @code{ERFC} --- Error function
3638 @cindex error function, complementary
3641 @item @emph{Description}:
3642 @code{ERFC(X)} computes the complementary error function of @var{X}.
3644 @item @emph{Standard}:
3645 Fortran 2008 and later
3650 @item @emph{Syntax}:
3651 @code{RESULT = ERFC(X)}
3653 @item @emph{Arguments}:
3654 @multitable @columnfractions .15 .70
3655 @item @var{X} @tab The type shall be @code{REAL}.
3658 @item @emph{Return value}:
3659 The return value is of type @code{REAL} and of the same kind as @var{X}.
3660 It lies in the range @math{ 0 \leq erfc (x) \leq 2 }.
3662 @item @emph{Example}:
3665 real(8) :: x = 0.17_8
3667 end program test_erfc
3670 @item @emph{Specific names}:
3671 @multitable @columnfractions .20 .20 .20 .25
3672 @item Name @tab Argument @tab Return type @tab Standard
3673 @item @code{DERFC(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU extension
3680 @section @code{ERFC_SCALED} --- Error function
3681 @fnindex ERFC_SCALED
3682 @cindex error function, complementary, exponentially-scaled
3685 @item @emph{Description}:
3686 @code{ERFC_SCALED(X)} computes the exponentially-scaled complementary
3687 error function of @var{X}.
3689 @item @emph{Standard}:
3690 Fortran 2008 and later
3695 @item @emph{Syntax}:
3696 @code{RESULT = ERFC_SCALED(X)}
3698 @item @emph{Arguments}:
3699 @multitable @columnfractions .15 .70
3700 @item @var{X} @tab The type shall be @code{REAL}.
3703 @item @emph{Return value}:
3704 The return value is of type @code{REAL} and of the same kind as @var{X}.
3706 @item @emph{Example}:
3708 program test_erfc_scaled
3709 real(8) :: x = 0.17_8
3711 end program test_erfc_scaled
3718 @section @code{ETIME} --- Execution time subroutine (or function)
3720 @cindex time, elapsed
3723 @item @emph{Description}:
3724 @code{ETIME(VALUES, TIME)} returns the number of seconds of runtime
3725 since the start of the process's execution in @var{TIME}. @var{VALUES}
3726 returns the user and system components of this time in @code{VALUES(1)} and
3727 @code{VALUES(2)} respectively. @var{TIME} is equal to @code{VALUES(1) + VALUES(2)}.
3729 On some systems, the underlying timings are represented using types with
3730 sufficiently small limits that overflows (wrap around) are possible, such as
3731 32-bit types. Therefore, the values returned by this intrinsic might be, or
3732 become, negative, or numerically less than previous values, during a single
3733 run of the compiled program.
3735 This intrinsic is provided in both subroutine and function forms; however,
3736 only one form can be used in any given program unit.
3738 @var{VALUES} and @var{TIME} are @code{INTENT(OUT)} and provide the following:
3740 @multitable @columnfractions .15 .30 .60
3741 @item @tab @code{VALUES(1)}: @tab User time in seconds.
3742 @item @tab @code{VALUES(2)}: @tab System time in seconds.
3743 @item @tab @code{TIME}: @tab Run time since start in seconds.
3746 @item @emph{Standard}:
3750 Subroutine, function
3752 @item @emph{Syntax}:
3753 @multitable @columnfractions .80
3754 @item @code{CALL ETIME(VALUES, TIME)}.
3755 @item @code{TIME = ETIME(VALUES)}, (not recommended).
3758 @item @emph{Arguments}:
3759 @multitable @columnfractions .15 .70
3760 @item @var{VALUES}@tab The type shall be @code{REAL(4), DIMENSION(2)}.
3761 @item @var{TIME}@tab The type shall be @code{REAL(4)}.
3764 @item @emph{Return value}:
3765 Elapsed time in seconds since the start of program execution.
3767 @item @emph{Example}:
3771 real, dimension(2) :: tarray
3773 call ETIME(tarray, result)
3777 do i=1,100000000 ! Just a delay
3780 call ETIME(tarray, result)
3784 end program test_etime
3787 @item @emph{See also}:
3795 @section @code{EXIT} --- Exit the program with status.
3797 @cindex program termination
3798 @cindex terminate program
3801 @item @emph{Description}:
3802 @code{EXIT} causes immediate termination of the program with status. If status
3803 is omitted it returns the canonical @emph{success} for the system. All Fortran
3804 I/O units are closed.
3806 @item @emph{Standard}:
3812 @item @emph{Syntax}:
3813 @code{CALL EXIT([STATUS])}
3815 @item @emph{Arguments}:
3816 @multitable @columnfractions .15 .70
3817 @item @var{STATUS} @tab Shall be an @code{INTEGER} of the default kind.
3820 @item @emph{Return value}:
3821 @code{STATUS} is passed to the parent process on exit.
3823 @item @emph{Example}:
3826 integer :: STATUS = 0
3827 print *, 'This program is going to exit.'
3829 end program test_exit
3832 @item @emph{See also}:
3833 @ref{ABORT}, @ref{KILL}
3839 @section @code{EXP} --- Exponential function
3845 @cindex exponential function
3846 @cindex logarithmic function, inverse
3849 @item @emph{Description}:
3850 @code{EXP(X)} computes the base @math{e} exponential of @var{X}.
3852 @item @emph{Standard}:
3853 Fortran 77 and later, has overloads that are GNU extensions
3858 @item @emph{Syntax}:
3859 @code{RESULT = EXP(X)}
3861 @item @emph{Arguments}:
3862 @multitable @columnfractions .15 .70
3863 @item @var{X} @tab The type shall be @code{REAL} or
3867 @item @emph{Return value}:
3868 The return value has same type and kind as @var{X}.
3870 @item @emph{Example}:
3875 end program test_exp
3878 @item @emph{Specific names}:
3879 @multitable @columnfractions .20 .20 .20 .25
3880 @item Name @tab Argument @tab Return type @tab Standard
3881 @item @code{EXP(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab Fortran 77 and later
3882 @item @code{DEXP(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab Fortran 77 and later
3883 @item @code{CEXP(X)} @tab @code{COMPLEX(4) X} @tab @code{COMPLEX(4)} @tab Fortran 77 and later
3884 @item @code{ZEXP(X)} @tab @code{COMPLEX(8) X} @tab @code{COMPLEX(8)} @tab GNU extension
3885 @item @code{CDEXP(X)} @tab @code{COMPLEX(8) X} @tab @code{COMPLEX(8)} @tab GNU extension
3892 @section @code{EXPONENT} --- Exponent function
3894 @cindex real number, exponent
3895 @cindex floating point, exponent
3898 @item @emph{Description}:
3899 @code{EXPONENT(X)} returns the value of the exponent part of @var{X}. If @var{X}
3900 is zero the value returned is zero.
3902 @item @emph{Standard}:
3903 Fortran 95 and later
3908 @item @emph{Syntax}:
3909 @code{RESULT = EXPONENT(X)}
3911 @item @emph{Arguments}:
3912 @multitable @columnfractions .15 .70
3913 @item @var{X} @tab The type shall be @code{REAL}.
3916 @item @emph{Return value}:
3917 The return value is of type default @code{INTEGER}.
3919 @item @emph{Example}:
3921 program test_exponent
3926 print *, exponent(0.0)
3927 end program test_exponent
3933 @node EXTENDS_TYPE_OF
3934 @section @code{EXTENDS_TYPE_OF} --- Query dynamic type for extension
3935 @fnindex EXTENDS_TYPE_OF
3938 @item @emph{Description}:
3939 Query dynamic type for extension.
3941 @item @emph{Standard}:
3942 Fortran 2003 and later
3947 @item @emph{Syntax}:
3948 @code{RESULT = EXTENDS_TYPE_OF(A, MOLD)}
3950 @item @emph{Arguments}:
3951 @multitable @columnfractions .15 .70
3952 @item @var{A} @tab Shall be an object of extensible declared type or
3953 unlimited polymorphic.
3954 @item @var{MOLD} @tab Shall be an object of extensible declared type or
3955 unlimited polymorphic.
3958 @item @emph{Return value}:
3959 The return value is a scalar of type default logical. It is true if and only if
3960 the dynamic type of A is an extension type of the dynamic type of MOLD.
3963 @item @emph{See also}:
3970 @section @code{FDATE} --- Get the current time as a string
3972 @cindex time, current
3973 @cindex current time
3974 @cindex date, current
3975 @cindex current date
3978 @item @emph{Description}:
3979 @code{FDATE(DATE)} returns the current date (using the same format as
3980 @code{CTIME}) in @var{DATE}. It is equivalent to @code{CALL CTIME(DATE,
3983 This intrinsic is provided in both subroutine and function forms; however,
3984 only one form can be used in any given program unit.
3986 @var{DATE} is an @code{INTENT(OUT)} @code{CHARACTER} variable of the
3989 @item @emph{Standard}:
3993 Subroutine, function
3995 @item @emph{Syntax}:
3996 @multitable @columnfractions .80
3997 @item @code{CALL FDATE(DATE)}.
3998 @item @code{DATE = FDATE()}, (not recommended).
4001 @item @emph{Arguments}:
4002 @multitable @columnfractions .15 .70
4003 @item @var{DATE}@tab The type shall be of type @code{CHARACTER} of the
4007 @item @emph{Return value}:
4008 The current date as a string.
4010 @item @emph{Example}:
4014 character(len=30) :: date
4016 print *, 'Program started on ', date
4017 do i = 1, 100000000 ! Just a delay
4021 print *, 'Program ended on ', date
4022 end program test_fdate
4029 @section @code{FGET} --- Read a single character in stream mode from stdin
4031 @cindex read character, stream mode
4032 @cindex stream mode, read character
4033 @cindex file operation, read character
4036 @item @emph{Description}:
4037 Read a single character in stream mode from stdin by bypassing normal
4038 formatted output. Stream I/O should not be mixed with normal record-oriented
4039 (formatted or unformatted) I/O on the same unit; the results are unpredictable.
4041 This intrinsic is provided in both subroutine and function forms; however,
4042 only one form can be used in any given program unit.
4044 Note that the @code{FGET} intrinsic is provided for backwards compatibility with
4045 @command{g77}. GNU Fortran provides the Fortran 2003 Stream facility.
4046 Programmers should consider the use of new stream IO feature in new code
4047 for future portability. See also @ref{Fortran 2003 status}.
4049 @item @emph{Standard}:
4053 Subroutine, function
4055 @item @emph{Syntax}:
4056 @code{CALL FGET(C [, STATUS])}
4058 @item @emph{Arguments}:
4059 @multitable @columnfractions .15 .70
4060 @item @var{C} @tab The type shall be @code{CHARACTER} and of default
4062 @item @var{STATUS} @tab (Optional) status flag of type @code{INTEGER}.
4063 Returns 0 on success, -1 on end-of-file, and a system specific positive
4064 error code otherwise.
4067 @item @emph{Example}:
4070 INTEGER, PARAMETER :: strlen = 100
4071 INTEGER :: status, i = 1
4072 CHARACTER(len=strlen) :: str = ""
4074 WRITE (*,*) 'Enter text:'
4076 CALL fget(str(i:i), status)
4077 if (status /= 0 .OR. i > strlen) exit
4080 WRITE (*,*) TRIM(str)
4084 @item @emph{See also}:
4085 @ref{FGETC}, @ref{FPUT}, @ref{FPUTC}
4091 @section @code{FGETC} --- Read a single character in stream mode
4093 @cindex read character, stream mode
4094 @cindex stream mode, read character
4095 @cindex file operation, read character
4098 @item @emph{Description}:
4099 Read a single character in stream mode by bypassing normal formatted output.
4100 Stream I/O should not be mixed with normal record-oriented (formatted or
4101 unformatted) I/O on the same unit; the results are unpredictable.
4103 This intrinsic is provided in both subroutine and function forms; however,
4104 only one form can be used in any given program unit.
4106 Note that the @code{FGET} intrinsic is provided for backwards compatibility
4107 with @command{g77}. GNU Fortran provides the Fortran 2003 Stream facility.
4108 Programmers should consider the use of new stream IO feature in new code
4109 for future portability. See also @ref{Fortran 2003 status}.
4111 @item @emph{Standard}:
4115 Subroutine, function
4117 @item @emph{Syntax}:
4118 @code{CALL FGETC(UNIT, C [, STATUS])}
4120 @item @emph{Arguments}:
4121 @multitable @columnfractions .15 .70
4122 @item @var{UNIT} @tab The type shall be @code{INTEGER}.
4123 @item @var{C} @tab The type shall be @code{CHARACTER} and of default
4125 @item @var{STATUS} @tab (Optional) status flag of type @code{INTEGER}.
4126 Returns 0 on success, -1 on end-of-file and a system specific positive
4127 error code otherwise.
4130 @item @emph{Example}:
4133 INTEGER :: fd = 42, status
4136 OPEN(UNIT=fd, FILE="/etc/passwd", ACTION="READ", STATUS = "OLD")
4138 CALL fgetc(fd, c, status)
4139 IF (status /= 0) EXIT
4146 @item @emph{See also}:
4147 @ref{FGET}, @ref{FPUT}, @ref{FPUTC}
4153 @section @code{FLOOR} --- Integer floor function
4156 @cindex rounding, floor
4159 @item @emph{Description}:
4160 @code{FLOOR(A)} returns the greatest integer less than or equal to @var{X}.
4162 @item @emph{Standard}:
4163 Fortran 95 and later
4168 @item @emph{Syntax}:
4169 @code{RESULT = FLOOR(A [, KIND])}
4171 @item @emph{Arguments}:
4172 @multitable @columnfractions .15 .70
4173 @item @var{A} @tab The type shall be @code{REAL}.
4174 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
4175 expression indicating the kind parameter of the result.
4178 @item @emph{Return value}:
4179 The return value is of type @code{INTEGER(KIND)} if @var{KIND} is present
4180 and of default-kind @code{INTEGER} otherwise.
4182 @item @emph{Example}:
4187 print *, floor(x) ! returns 63
4188 print *, floor(y) ! returns -64
4189 end program test_floor
4192 @item @emph{See also}:
4193 @ref{CEILING}, @ref{NINT}
4200 @section @code{FLUSH} --- Flush I/O unit(s)
4202 @cindex file operation, flush
4205 @item @emph{Description}:
4206 Flushes Fortran unit(s) currently open for output. Without the optional
4207 argument, all units are flushed, otherwise just the unit specified.
4209 @item @emph{Standard}:
4215 @item @emph{Syntax}:
4216 @code{CALL FLUSH(UNIT)}
4218 @item @emph{Arguments}:
4219 @multitable @columnfractions .15 .70
4220 @item @var{UNIT} @tab (Optional) The type shall be @code{INTEGER}.
4224 Beginning with the Fortran 2003 standard, there is a @code{FLUSH}
4225 statement that should be preferred over the @code{FLUSH} intrinsic.
4227 The @code{FLUSH} intrinsic and the Fortran 2003 @code{FLUSH} statement
4228 have identical effect: they flush the runtime library's I/O buffer so
4229 that the data becomes visible to other processes. This does not guarantee
4230 that the data is committed to disk.
4232 On POSIX systems, you can request that all data is transferred to the
4233 storage device by calling the @code{fsync} function, with the POSIX file
4234 descriptor of the I/O unit as argument (retrieved with GNU intrinsic
4235 @code{FNUM}). The following example shows how:
4238 ! Declare the interface for POSIX fsync function
4240 function fsync (fd) bind(c,name="fsync")
4241 use iso_c_binding, only: c_int
4242 integer(c_int), value :: fd
4243 integer(c_int) :: fsync
4247 ! Variable declaration
4251 open (10,file="foo")
4254 ! Perform I/O on unit 10
4259 ret = fsync(fnum(10))
4261 ! Handle possible error
4262 if (ret /= 0) stop "Error calling FSYNC"
4270 @section @code{FNUM} --- File number function
4272 @cindex file operation, file number
4275 @item @emph{Description}:
4276 @code{FNUM(UNIT)} returns the POSIX file descriptor number corresponding to the
4277 open Fortran I/O unit @code{UNIT}.
4279 @item @emph{Standard}:
4285 @item @emph{Syntax}:
4286 @code{RESULT = FNUM(UNIT)}
4288 @item @emph{Arguments}:
4289 @multitable @columnfractions .15 .70
4290 @item @var{UNIT} @tab The type shall be @code{INTEGER}.
4293 @item @emph{Return value}:
4294 The return value is of type @code{INTEGER}
4296 @item @emph{Example}:
4300 open (unit=10, status = "scratch")
4304 end program test_fnum
4311 @section @code{FPUT} --- Write a single character in stream mode to stdout
4313 @cindex write character, stream mode
4314 @cindex stream mode, write character
4315 @cindex file operation, write character
4318 @item @emph{Description}:
4319 Write a single character in stream mode to stdout by bypassing normal
4320 formatted output. Stream I/O should not be mixed with normal record-oriented
4321 (formatted or unformatted) I/O on the same unit; the results are unpredictable.
4323 This intrinsic is provided in both subroutine and function forms; however,
4324 only one form can be used in any given program unit.
4326 Note that the @code{FGET} intrinsic is provided for backwards compatibility with
4327 @command{g77}. GNU Fortran provides the Fortran 2003 Stream facility.
4328 Programmers should consider the use of new stream IO feature in new code
4329 for future portability. See also @ref{Fortran 2003 status}.
4331 @item @emph{Standard}:
4335 Subroutine, function
4337 @item @emph{Syntax}:
4338 @code{CALL FPUT(C [, STATUS])}
4340 @item @emph{Arguments}:
4341 @multitable @columnfractions .15 .70
4342 @item @var{C} @tab The type shall be @code{CHARACTER} and of default
4344 @item @var{STATUS} @tab (Optional) status flag of type @code{INTEGER}.
4345 Returns 0 on success, -1 on end-of-file and a system specific positive
4346 error code otherwise.
4349 @item @emph{Example}:
4352 CHARACTER(len=10) :: str = "gfortran"
4354 DO i = 1, len_trim(str)
4360 @item @emph{See also}:
4361 @ref{FPUTC}, @ref{FGET}, @ref{FGETC}
4367 @section @code{FPUTC} --- Write a single character in stream mode
4369 @cindex write character, stream mode
4370 @cindex stream mode, write character
4371 @cindex file operation, write character
4374 @item @emph{Description}:
4375 Write a single character in stream mode by bypassing normal formatted
4376 output. Stream I/O should not be mixed with normal record-oriented
4377 (formatted or unformatted) I/O on the same unit; the results are unpredictable.
4379 This intrinsic is provided in both subroutine and function forms; however,
4380 only one form can be used in any given program unit.
4382 Note that the @code{FGET} intrinsic is provided for backwards compatibility with
4383 @command{g77}. GNU Fortran provides the Fortran 2003 Stream facility.
4384 Programmers should consider the use of new stream IO feature in new code
4385 for future portability. See also @ref{Fortran 2003 status}.
4387 @item @emph{Standard}:
4391 Subroutine, function
4393 @item @emph{Syntax}:
4394 @code{CALL FPUTC(UNIT, C [, STATUS])}
4396 @item @emph{Arguments}:
4397 @multitable @columnfractions .15 .70
4398 @item @var{UNIT} @tab The type shall be @code{INTEGER}.
4399 @item @var{C} @tab The type shall be @code{CHARACTER} and of default
4401 @item @var{STATUS} @tab (Optional) status flag of type @code{INTEGER}.
4402 Returns 0 on success, -1 on end-of-file and a system specific positive
4403 error code otherwise.
4406 @item @emph{Example}:
4409 CHARACTER(len=10) :: str = "gfortran"
4410 INTEGER :: fd = 42, i
4412 OPEN(UNIT = fd, FILE = "out", ACTION = "WRITE", STATUS="NEW")
4413 DO i = 1, len_trim(str)
4414 CALL fputc(fd, str(i:i))
4420 @item @emph{See also}:
4421 @ref{FPUT}, @ref{FGET}, @ref{FGETC}
4427 @section @code{FRACTION} --- Fractional part of the model representation
4429 @cindex real number, fraction
4430 @cindex floating point, fraction
4433 @item @emph{Description}:
4434 @code{FRACTION(X)} returns the fractional part of the model
4435 representation of @code{X}.
4437 @item @emph{Standard}:
4438 Fortran 95 and later
4443 @item @emph{Syntax}:
4444 @code{Y = FRACTION(X)}
4446 @item @emph{Arguments}:
4447 @multitable @columnfractions .15 .70
4448 @item @var{X} @tab The type of the argument shall be a @code{REAL}.
4451 @item @emph{Return value}:
4452 The return value is of the same type and kind as the argument.
4453 The fractional part of the model representation of @code{X} is returned;
4454 it is @code{X * RADIX(X)**(-EXPONENT(X))}.
4456 @item @emph{Example}:
4458 program test_fraction
4461 print *, fraction(x), x * radix(x)**(-exponent(x))
4462 end program test_fraction
4470 @section @code{FREE} --- Frees memory
4472 @cindex pointer, cray
4475 @item @emph{Description}:
4476 Frees memory previously allocated by @code{MALLOC()}. The @code{FREE}
4477 intrinsic is an extension intended to be used with Cray pointers, and is
4478 provided in GNU Fortran to allow user to compile legacy code. For
4479 new code using Fortran 95 pointers, the memory de-allocation intrinsic is
4482 @item @emph{Standard}:
4488 @item @emph{Syntax}:
4489 @code{CALL FREE(PTR)}
4491 @item @emph{Arguments}:
4492 @multitable @columnfractions .15 .70
4493 @item @var{PTR} @tab The type shall be @code{INTEGER}. It represents the
4494 location of the memory that should be de-allocated.
4497 @item @emph{Return value}:
4500 @item @emph{Example}:
4501 See @code{MALLOC} for an example.
4503 @item @emph{See also}:
4510 @section @code{FSEEK} --- Low level file positioning subroutine
4512 @cindex file operation, seek
4513 @cindex file operation, position
4516 @item @emph{Description}:
4517 Moves @var{UNIT} to the specified @var{OFFSET}. If @var{WHENCE}
4518 is set to 0, the @var{OFFSET} is taken as an absolute value @code{SEEK_SET},
4519 if set to 1, @var{OFFSET} is taken to be relative to the current position
4520 @code{SEEK_CUR}, and if set to 2 relative to the end of the file @code{SEEK_END}.
4521 On error, @var{STATUS} is set to a nonzero value. If @var{STATUS} the seek
4524 This intrinsic routine is not fully backwards compatible with @command{g77}.
4525 In @command{g77}, the @code{FSEEK} takes a statement label instead of a
4526 @var{STATUS} variable. If FSEEK is used in old code, change
4528 CALL FSEEK(UNIT, OFFSET, WHENCE, *label)
4533 CALL FSEEK(UNIT, OFFSET, WHENCE, status)
4534 IF (status /= 0) GOTO label
4537 Please note that GNU Fortran provides the Fortran 2003 Stream facility.
4538 Programmers should consider the use of new stream IO feature in new code
4539 for future portability. See also @ref{Fortran 2003 status}.
4541 @item @emph{Standard}:
4547 @item @emph{Syntax}:
4548 @code{CALL FSEEK(UNIT, OFFSET, WHENCE[, STATUS])}
4550 @item @emph{Arguments}:
4551 @multitable @columnfractions .15 .70
4552 @item @var{UNIT} @tab Shall be a scalar of type @code{INTEGER}.
4553 @item @var{OFFSET} @tab Shall be a scalar of type @code{INTEGER}.
4554 @item @var{WHENCE} @tab Shall be a scalar of type @code{INTEGER}.
4555 Its value shall be either 0, 1 or 2.
4556 @item @var{STATUS} @tab (Optional) shall be a scalar of type
4560 @item @emph{Example}:
4563 INTEGER, PARAMETER :: SEEK_SET = 0, SEEK_CUR = 1, SEEK_END = 2
4564 INTEGER :: fd, offset, ierr
4570 OPEN(UNIT=fd, FILE="fseek.test")
4571 CALL FSEEK(fd, offset, SEEK_SET, ierr) ! move to OFFSET
4572 print *, FTELL(fd), ierr
4574 CALL FSEEK(fd, 0, SEEK_END, ierr) ! move to end
4575 print *, FTELL(fd), ierr
4577 CALL FSEEK(fd, 0, SEEK_SET, ierr) ! move to beginning
4578 print *, FTELL(fd), ierr
4584 @item @emph{See also}:
4591 @section @code{FSTAT} --- Get file status
4593 @cindex file system, file status
4596 @item @emph{Description}:
4597 @code{FSTAT} is identical to @ref{STAT}, except that information about an
4598 already opened file is obtained.
4600 The elements in @code{VALUES} are the same as described by @ref{STAT}.
4602 This intrinsic is provided in both subroutine and function forms; however,
4603 only one form can be used in any given program unit.
4605 @item @emph{Standard}:
4609 Subroutine, function
4611 @item @emph{Syntax}:
4612 @code{CALL FSTAT(UNIT, VALUES [, STATUS])}
4614 @item @emph{Arguments}:
4615 @multitable @columnfractions .15 .70
4616 @item @var{UNIT} @tab An open I/O unit number of type @code{INTEGER}.
4617 @item @var{VALUES} @tab The type shall be @code{INTEGER(4), DIMENSION(13)}.
4618 @item @var{STATUS} @tab (Optional) status flag of type @code{INTEGER(4)}. Returns 0
4619 on success and a system specific error code otherwise.
4622 @item @emph{Example}:
4623 See @ref{STAT} for an example.
4625 @item @emph{See also}:
4626 To stat a link: @ref{LSTAT}, to stat a file: @ref{STAT}
4632 @section @code{FTELL} --- Current stream position
4634 @cindex file operation, position
4637 @item @emph{Description}:
4638 Retrieves the current position within an open file.
4640 This intrinsic is provided in both subroutine and function forms; however,
4641 only one form can be used in any given program unit.
4643 @item @emph{Standard}:
4647 Subroutine, function
4649 @item @emph{Syntax}:
4650 @multitable @columnfractions .80
4651 @item @code{CALL FTELL(UNIT, OFFSET)}
4652 @item @code{OFFSET = FTELL(UNIT)}
4655 @item @emph{Arguments}:
4656 @multitable @columnfractions .15 .70
4657 @item @var{OFFSET} @tab Shall of type @code{INTEGER}.
4658 @item @var{UNIT} @tab Shall of type @code{INTEGER}.
4661 @item @emph{Return value}:
4662 In either syntax, @var{OFFSET} is set to the current offset of unit
4663 number @var{UNIT}, or to @math{-1} if the unit is not currently open.
4665 @item @emph{Example}:
4669 OPEN(10, FILE="temp.dat")
4675 @item @emph{See also}:
4682 @section @code{GAMMA} --- Gamma function
4685 @cindex Gamma function
4686 @cindex Factorial function
4689 @item @emph{Description}:
4690 @code{GAMMA(X)} computes Gamma (@math{\Gamma}) of @var{X}. For positive,
4691 integer values of @var{X} the Gamma function simplifies to the factorial
4692 function @math{\Gamma(x)=(x-1)!}.
4696 \Gamma(x) = \int_0^\infty t^{x-1}{\rm e}^{-t}\,{\rm d}t
4700 @item @emph{Standard}:
4701 Fortran 2008 and later
4706 @item @emph{Syntax}:
4709 @item @emph{Arguments}:
4710 @multitable @columnfractions .15 .70
4711 @item @var{X} @tab Shall be of type @code{REAL} and neither zero
4712 nor a negative integer.
4715 @item @emph{Return value}:
4716 The return value is of type @code{REAL} of the same kind as @var{X}.
4718 @item @emph{Example}:
4722 x = gamma(x) ! returns 1.0
4723 end program test_gamma
4726 @item @emph{Specific names}:
4727 @multitable @columnfractions .20 .20 .20 .25
4728 @item Name @tab Argument @tab Return type @tab Standard
4729 @item @code{GAMMA(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab GNU Extension
4730 @item @code{DGAMMA(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU Extension
4733 @item @emph{See also}:
4734 Logarithm of the Gamma function: @ref{LOG_GAMMA}
4741 @section @code{GERROR} --- Get last system error message
4743 @cindex system, error handling
4746 @item @emph{Description}:
4747 Returns the system error message corresponding to the last system error.
4748 This resembles the functionality of @code{strerror(3)} in C.
4750 @item @emph{Standard}:
4756 @item @emph{Syntax}:
4757 @code{CALL GERROR(RESULT)}
4759 @item @emph{Arguments}:
4760 @multitable @columnfractions .15 .70
4761 @item @var{RESULT} @tab Shall of type @code{CHARACTER} and of default
4764 @item @emph{Example}:
4767 CHARACTER(len=100) :: msg
4773 @item @emph{See also}:
4774 @ref{IERRNO}, @ref{PERROR}
4780 @section @code{GETARG} --- Get command line arguments
4782 @cindex command-line arguments
4783 @cindex arguments, to program
4786 @item @emph{Description}:
4787 Retrieve the @var{POS}-th argument that was passed on the
4788 command line when the containing program was invoked.
4790 This intrinsic routine is provided for backwards compatibility with
4791 GNU Fortran 77. In new code, programmers should consider the use of
4792 the @ref{GET_COMMAND_ARGUMENT} intrinsic defined by the Fortran 2003
4795 @item @emph{Standard}:
4801 @item @emph{Syntax}:
4802 @code{CALL GETARG(POS, VALUE)}
4804 @item @emph{Arguments}:
4805 @multitable @columnfractions .15 .70
4806 @item @var{POS} @tab Shall be of type @code{INTEGER} and not wider than
4807 the default integer kind; @math{@var{POS} \geq 0}
4808 @item @var{VALUE} @tab Shall be of type @code{CHARACTER} and of default
4810 @item @var{VALUE} @tab Shall be of type @code{CHARACTER}.
4813 @item @emph{Return value}:
4814 After @code{GETARG} returns, the @var{VALUE} argument holds the
4815 @var{POS}th command line argument. If @var{VALUE} can not hold the
4816 argument, it is truncated to fit the length of @var{VALUE}. If there are
4817 less than @var{POS} arguments specified at the command line, @var{VALUE}
4818 will be filled with blanks. If @math{@var{POS} = 0}, @var{VALUE} is set
4819 to the name of the program (on systems that support this feature).
4821 @item @emph{Example}:
4825 CHARACTER(len=32) :: arg
4834 @item @emph{See also}:
4835 GNU Fortran 77 compatibility function: @ref{IARGC}
4837 Fortran 2003 functions and subroutines: @ref{GET_COMMAND},
4838 @ref{GET_COMMAND_ARGUMENT}, @ref{COMMAND_ARGUMENT_COUNT}
4844 @section @code{GET_COMMAND} --- Get the entire command line
4845 @fnindex GET_COMMAND
4846 @cindex command-line arguments
4847 @cindex arguments, to program
4850 @item @emph{Description}:
4851 Retrieve the entire command line that was used to invoke the program.
4853 @item @emph{Standard}:
4854 Fortran 2003 and later
4859 @item @emph{Syntax}:
4860 @code{CALL GET_COMMAND([COMMAND, LENGTH, STATUS])}
4862 @item @emph{Arguments}:
4863 @multitable @columnfractions .15 .70
4864 @item @var{COMMAND} @tab (Optional) shall be of type @code{CHARACTER} and
4866 @item @var{LENGTH} @tab (Optional) Shall be of type @code{INTEGER} and of
4868 @item @var{STATUS} @tab (Optional) Shall be of type @code{INTEGER} and of
4872 @item @emph{Return value}:
4873 If @var{COMMAND} is present, stores the entire command line that was used
4874 to invoke the program in @var{COMMAND}. If @var{LENGTH} is present, it is
4875 assigned the length of the command line. If @var{STATUS} is present, it
4876 is assigned 0 upon success of the command, -1 if @var{COMMAND} is too
4877 short to store the command line, or a positive value in case of an error.
4879 @item @emph{Example}:
4881 PROGRAM test_get_command
4882 CHARACTER(len=255) :: cmd
4883 CALL get_command(cmd)
4884 WRITE (*,*) TRIM(cmd)
4888 @item @emph{See also}:
4889 @ref{GET_COMMAND_ARGUMENT}, @ref{COMMAND_ARGUMENT_COUNT}
4894 @node GET_COMMAND_ARGUMENT
4895 @section @code{GET_COMMAND_ARGUMENT} --- Get command line arguments
4896 @fnindex GET_COMMAND_ARGUMENT
4897 @cindex command-line arguments
4898 @cindex arguments, to program
4901 @item @emph{Description}:
4902 Retrieve the @var{NUMBER}-th argument that was passed on the
4903 command line when the containing program was invoked.
4905 @item @emph{Standard}:
4906 Fortran 2003 and later
4911 @item @emph{Syntax}:
4912 @code{CALL GET_COMMAND_ARGUMENT(NUMBER [, VALUE, LENGTH, STATUS])}
4914 @item @emph{Arguments}:
4915 @multitable @columnfractions .15 .70
4916 @item @var{NUMBER} @tab Shall be a scalar of type @code{INTEGER} and of
4917 default kind, @math{@var{NUMBER} \geq 0}
4918 @item @var{VALUE} @tab Shall be a scalar of type @code{CHARACTER}
4919 and of default kind.
4920 @item @var{LENGTH} @tab (Option) Shall be a scalar of type @code{INTEGER}
4921 and of default kind.
4922 @item @var{STATUS} @tab (Option) Shall be a scalar of type @code{INTEGER}
4923 and of default kind.
4926 @item @emph{Return value}:
4927 After @code{GET_COMMAND_ARGUMENT} returns, the @var{VALUE} argument holds the
4928 @var{NUMBER}-th command line argument. If @var{VALUE} can not hold the argument, it is
4929 truncated to fit the length of @var{VALUE}. If there are less than @var{NUMBER}
4930 arguments specified at the command line, @var{VALUE} will be filled with blanks.
4931 If @math{@var{NUMBER} = 0}, @var{VALUE} is set to the name of the program (on
4932 systems that support this feature). The @var{LENGTH} argument contains the
4933 length of the @var{NUMBER}-th command line argument. If the argument retrieval
4934 fails, @var{STATUS} is a positive number; if @var{VALUE} contains a truncated
4935 command line argument, @var{STATUS} is -1; and otherwise the @var{STATUS} is
4938 @item @emph{Example}:
4940 PROGRAM test_get_command_argument
4942 CHARACTER(len=32) :: arg
4946 CALL get_command_argument(i, arg)
4947 IF (LEN_TRIM(arg) == 0) EXIT
4949 WRITE (*,*) TRIM(arg)
4955 @item @emph{See also}:
4956 @ref{GET_COMMAND}, @ref{COMMAND_ARGUMENT_COUNT}
4962 @section @code{GETCWD} --- Get current working directory
4964 @cindex system, working directory
4967 @item @emph{Description}:
4968 Get current working directory.
4970 This intrinsic is provided in both subroutine and function forms; however,
4971 only one form can be used in any given program unit.
4973 @item @emph{Standard}:
4977 Subroutine, function
4979 @item @emph{Syntax}:
4980 @code{CALL GETCWD(C [, STATUS])}
4982 @item @emph{Arguments}:
4983 @multitable @columnfractions .15 .70
4984 @item @var{C} @tab The type shall be @code{CHARACTER} and of default kind.
4985 @item @var{STATUS} @tab (Optional) status flag. Returns 0 on success,
4986 a system specific and nonzero error code otherwise.
4989 @item @emph{Example}:
4992 CHARACTER(len=255) :: cwd
4994 WRITE(*,*) TRIM(cwd)
4998 @item @emph{See also}:
5005 @section @code{GETENV} --- Get an environmental variable
5007 @cindex environment variable
5010 @item @emph{Description}:
5011 Get the @var{VALUE} of the environmental variable @var{NAME}.
5013 This intrinsic routine is provided for backwards compatibility with
5014 GNU Fortran 77. In new code, programmers should consider the use of
5015 the @ref{GET_ENVIRONMENT_VARIABLE} intrinsic defined by the Fortran
5018 @item @emph{Standard}:
5024 @item @emph{Syntax}:
5025 @code{CALL GETENV(NAME, VALUE)}
5027 @item @emph{Arguments}:
5028 @multitable @columnfractions .15 .70
5029 @item @var{NAME} @tab Shall be of type @code{CHARACTER} and of default kind.
5030 @item @var{VALUE} @tab Shall be of type @code{CHARACTER} and of default kind.
5033 @item @emph{Return value}:
5034 Stores the value of @var{NAME} in @var{VALUE}. If @var{VALUE} is
5035 not large enough to hold the data, it is truncated. If @var{NAME}
5036 is not set, @var{VALUE} will be filled with blanks.
5038 @item @emph{Example}:
5041 CHARACTER(len=255) :: homedir
5042 CALL getenv("HOME", homedir)
5043 WRITE (*,*) TRIM(homedir)
5047 @item @emph{See also}:
5048 @ref{GET_ENVIRONMENT_VARIABLE}
5053 @node GET_ENVIRONMENT_VARIABLE
5054 @section @code{GET_ENVIRONMENT_VARIABLE} --- Get an environmental variable
5055 @fnindex GET_ENVIRONMENT_VARIABLE
5056 @cindex environment variable
5059 @item @emph{Description}:
5060 Get the @var{VALUE} of the environmental variable @var{NAME}.
5062 @item @emph{Standard}:
5063 Fortran 2003 and later
5068 @item @emph{Syntax}:
5069 @code{CALL GET_ENVIRONMENT_VARIABLE(NAME[, VALUE, LENGTH, STATUS, TRIM_NAME)}
5071 @item @emph{Arguments}:
5072 @multitable @columnfractions .15 .70
5073 @item @var{NAME} @tab Shall be a scalar of type @code{CHARACTER}
5074 and of default kind.
5075 @item @var{VALUE} @tab Shall be a scalar of type @code{CHARACTER}
5076 and of default kind.
5077 @item @var{LENGTH} @tab Shall be a scalar of type @code{INTEGER}
5078 and of default kind.
5079 @item @var{STATUS} @tab Shall be a scalar of type @code{INTEGER}
5080 and of default kind.
5081 @item @var{TRIM_NAME} @tab Shall be a scalar of type @code{LOGICAL}
5082 and of default kind.
5085 @item @emph{Return value}:
5086 Stores the value of @var{NAME} in @var{VALUE}. If @var{VALUE} is
5087 not large enough to hold the data, it is truncated. If @var{NAME}
5088 is not set, @var{VALUE} will be filled with blanks. Argument @var{LENGTH}
5089 contains the length needed for storing the environment variable @var{NAME}
5090 or zero if it is not present. @var{STATUS} is -1 if @var{VALUE} is present
5091 but too short for the environment variable; it is 1 if the environment
5092 variable does not exist and 2 if the processor does not support environment
5093 variables; in all other cases @var{STATUS} is zero. If @var{TRIM_NAME} is
5094 present with the value @code{.FALSE.}, the trailing blanks in @var{NAME}
5095 are significant; otherwise they are not part of the environment variable
5098 @item @emph{Example}:
5101 CHARACTER(len=255) :: homedir
5102 CALL get_environment_variable("HOME", homedir)
5103 WRITE (*,*) TRIM(homedir)
5111 @section @code{GETGID} --- Group ID function
5113 @cindex system, group id
5116 @item @emph{Description}:
5117 Returns the numerical group ID of the current process.
5119 @item @emph{Standard}:
5125 @item @emph{Syntax}:
5126 @code{RESULT = GETGID()}
5128 @item @emph{Return value}:
5129 The return value of @code{GETGID} is an @code{INTEGER} of the default
5133 @item @emph{Example}:
5134 See @code{GETPID} for an example.
5136 @item @emph{See also}:
5137 @ref{GETPID}, @ref{GETUID}
5143 @section @code{GETLOG} --- Get login name
5145 @cindex system, login name
5149 @item @emph{Description}:
5150 Gets the username under which the program is running.
5152 @item @emph{Standard}:
5158 @item @emph{Syntax}:
5159 @code{CALL GETLOG(C)}
5161 @item @emph{Arguments}:
5162 @multitable @columnfractions .15 .70
5163 @item @var{C} @tab Shall be of type @code{CHARACTER} and of default kind.
5166 @item @emph{Return value}:
5167 Stores the current user name in @var{LOGIN}. (On systems where POSIX
5168 functions @code{geteuid} and @code{getpwuid} are not available, and
5169 the @code{getlogin} function is not implemented either, this will
5170 return a blank string.)
5172 @item @emph{Example}:
5175 CHARACTER(32) :: login
5181 @item @emph{See also}:
5188 @section @code{GETPID} --- Process ID function
5190 @cindex system, process id
5194 @item @emph{Description}:
5195 Returns the numerical process identifier of the current process.
5197 @item @emph{Standard}:
5203 @item @emph{Syntax}:
5204 @code{RESULT = GETPID()}
5206 @item @emph{Return value}:
5207 The return value of @code{GETPID} is an @code{INTEGER} of the default
5211 @item @emph{Example}:
5214 print *, "The current process ID is ", getpid()
5215 print *, "Your numerical user ID is ", getuid()
5216 print *, "Your numerical group ID is ", getgid()
5220 @item @emph{See also}:
5221 @ref{GETGID}, @ref{GETUID}
5227 @section @code{GETUID} --- User ID function
5229 @cindex system, user id
5233 @item @emph{Description}:
5234 Returns the numerical user ID of the current process.
5236 @item @emph{Standard}:
5242 @item @emph{Syntax}:
5243 @code{RESULT = GETUID()}
5245 @item @emph{Return value}:
5246 The return value of @code{GETUID} is an @code{INTEGER} of the default
5250 @item @emph{Example}:
5251 See @code{GETPID} for an example.
5253 @item @emph{See also}:
5254 @ref{GETPID}, @ref{GETLOG}
5260 @section @code{GMTIME} --- Convert time to GMT info
5262 @cindex time, conversion to GMT info
5265 @item @emph{Description}:
5266 Given a system time value @var{TIME} (as provided by the @code{TIME8()}
5267 intrinsic), fills @var{VALUES} with values extracted from it appropriate
5268 to the UTC time zone (Universal Coordinated Time, also known in some
5269 countries as GMT, Greenwich Mean Time), using @code{gmtime(3)}.
5271 @item @emph{Standard}:
5277 @item @emph{Syntax}:
5278 @code{CALL GMTIME(TIME, VALUES)}
5280 @item @emph{Arguments}:
5281 @multitable @columnfractions .15 .70
5282 @item @var{TIME} @tab An @code{INTEGER} scalar expression
5283 corresponding to a system time, with @code{INTENT(IN)}.
5284 @item @var{VALUES} @tab A default @code{INTEGER} array with 9 elements,
5285 with @code{INTENT(OUT)}.
5288 @item @emph{Return value}:
5289 The elements of @var{VALUES} are assigned as follows:
5291 @item Seconds after the minute, range 0--59 or 0--61 to allow for leap
5293 @item Minutes after the hour, range 0--59
5294 @item Hours past midnight, range 0--23
5295 @item Day of month, range 0--31
5296 @item Number of months since January, range 0--12
5297 @item Years since 1900
5298 @item Number of days since Sunday, range 0--6
5299 @item Days since January 1
5300 @item Daylight savings indicator: positive if daylight savings is in
5301 effect, zero if not, and negative if the information is not available.
5304 @item @emph{See also}:
5305 @ref{CTIME}, @ref{LTIME}, @ref{TIME}, @ref{TIME8}
5312 @section @code{HOSTNM} --- Get system host name
5314 @cindex system, host name
5317 @item @emph{Description}:
5318 Retrieves the host name of the system on which the program is running.
5320 This intrinsic is provided in both subroutine and function forms; however,
5321 only one form can be used in any given program unit.
5323 @item @emph{Standard}:
5327 Subroutine, function
5329 @item @emph{Syntax}:
5330 @multitable @columnfractions .80
5331 @item @code{CALL HOSTNM(C [, STATUS])}
5332 @item @code{STATUS = HOSTNM(NAME)}
5335 @item @emph{Arguments}:
5336 @multitable @columnfractions .15 .70
5337 @item @var{C} @tab Shall of type @code{CHARACTER} and of default kind.
5338 @item @var{STATUS} @tab (Optional) status flag of type @code{INTEGER}.
5339 Returns 0 on success, or a system specific error code otherwise.
5342 @item @emph{Return value}:
5343 In either syntax, @var{NAME} is set to the current hostname if it can
5344 be obtained, or to a blank string otherwise.
5351 @section @code{HUGE} --- Largest number of a kind
5353 @cindex limits, largest number
5354 @cindex model representation, largest number
5357 @item @emph{Description}:
5358 @code{HUGE(X)} returns the largest number that is not an infinity in
5359 the model of the type of @code{X}.
5361 @item @emph{Standard}:
5362 Fortran 95 and later
5367 @item @emph{Syntax}:
5368 @code{RESULT = HUGE(X)}
5370 @item @emph{Arguments}:
5371 @multitable @columnfractions .15 .70
5372 @item @var{X} @tab Shall be of type @code{REAL} or @code{INTEGER}.
5375 @item @emph{Return value}:
5376 The return value is of the same type and kind as @var{X}
5378 @item @emph{Example}:
5380 program test_huge_tiny
5381 print *, huge(0), huge(0.0), huge(0.0d0)
5382 print *, tiny(0.0), tiny(0.0d0)
5383 end program test_huge_tiny
5390 @section @code{HYPOT} --- Euclidean distance function
5392 @cindex Euclidean distance
5395 @item @emph{Description}:
5396 @code{HYPOT(X,Y)} is the Euclidean distance function. It is equal to
5397 @math{\sqrt{X^2 + Y^2}}, without undue underflow or overflow.
5399 @item @emph{Standard}:
5400 Fortran 2008 and later
5405 @item @emph{Syntax}:
5406 @code{RESULT = HYPOT(X, Y)}
5408 @item @emph{Arguments}:
5409 @multitable @columnfractions .15 .70
5410 @item @var{X} @tab The type shall be @code{REAL}.
5411 @item @var{Y} @tab The type and kind type parameter shall be the same as
5415 @item @emph{Return value}:
5416 The return value has the same type and kind type parameter as @var{X}.
5418 @item @emph{Example}:
5421 real(4) :: x = 1.e0_4, y = 0.5e0_4
5423 end program test_hypot
5430 @section @code{IACHAR} --- Code in @acronym{ASCII} collating sequence
5432 @cindex @acronym{ASCII} collating sequence
5433 @cindex collating sequence, @acronym{ASCII}
5434 @cindex conversion, to integer
5437 @item @emph{Description}:
5438 @code{IACHAR(C)} returns the code for the @acronym{ASCII} character
5439 in the first character position of @code{C}.
5441 @item @emph{Standard}:
5442 Fortran 95 and later, with @var{KIND} argument Fortran 2003 and later
5447 @item @emph{Syntax}:
5448 @code{RESULT = IACHAR(C [, KIND])}
5450 @item @emph{Arguments}:
5451 @multitable @columnfractions .15 .70
5452 @item @var{C} @tab Shall be a scalar @code{CHARACTER}, with @code{INTENT(IN)}
5453 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
5454 expression indicating the kind parameter of the result.
5457 @item @emph{Return value}:
5458 The return value is of type @code{INTEGER} and of kind @var{KIND}. If
5459 @var{KIND} is absent, the return value is of default integer kind.
5461 @item @emph{Example}:
5466 end program test_iachar
5470 See @ref{ICHAR} for a discussion of converting between numerical values
5471 and formatted string representations.
5473 @item @emph{See also}:
5474 @ref{ACHAR}, @ref{CHAR}, @ref{ICHAR}
5481 @section @code{IAND} --- Bitwise logical and
5483 @cindex bitwise logical and
5484 @cindex logical and, bitwise
5487 @item @emph{Description}:
5488 Bitwise logical @code{AND}.
5490 @item @emph{Standard}:
5491 Fortran 95 and later
5496 @item @emph{Syntax}:
5497 @code{RESULT = IAND(I, J)}
5499 @item @emph{Arguments}:
5500 @multitable @columnfractions .15 .70
5501 @item @var{I} @tab The type shall be @code{INTEGER}.
5502 @item @var{J} @tab The type shall be @code{INTEGER}, of the same
5503 kind as @var{I}. (As a GNU extension, different kinds are also
5507 @item @emph{Return value}:
5508 The return type is @code{INTEGER}, of the same kind as the
5509 arguments. (If the argument kinds differ, it is of the same kind as
5510 the larger argument.)
5512 @item @emph{Example}:
5516 DATA a / Z'F' /, b / Z'3' /
5517 WRITE (*,*) IAND(a, b)
5521 @item @emph{See also}:
5522 @ref{IOR}, @ref{IEOR}, @ref{IBITS}, @ref{IBSET}, @ref{IBCLR}, @ref{NOT}
5529 @section @code{IARGC} --- Get the number of command line arguments
5531 @cindex command-line arguments
5532 @cindex command-line arguments, number of
5533 @cindex arguments, to program
5536 @item @emph{Description}:
5537 @code{IARGC()} returns the number of arguments passed on the
5538 command line when the containing program was invoked.
5540 This intrinsic routine is provided for backwards compatibility with
5541 GNU Fortran 77. In new code, programmers should consider the use of
5542 the @ref{COMMAND_ARGUMENT_COUNT} intrinsic defined by the Fortran 2003
5545 @item @emph{Standard}:
5551 @item @emph{Syntax}:
5552 @code{RESULT = IARGC()}
5554 @item @emph{Arguments}:
5557 @item @emph{Return value}:
5558 The number of command line arguments, type @code{INTEGER(4)}.
5560 @item @emph{Example}:
5563 @item @emph{See also}:
5564 GNU Fortran 77 compatibility subroutine: @ref{GETARG}
5566 Fortran 2003 functions and subroutines: @ref{GET_COMMAND},
5567 @ref{GET_COMMAND_ARGUMENT}, @ref{COMMAND_ARGUMENT_COUNT}
5573 @section @code{IBCLR} --- Clear bit
5579 @item @emph{Description}:
5580 @code{IBCLR} returns the value of @var{I} with the bit at position
5581 @var{POS} set to zero.
5583 @item @emph{Standard}:
5584 Fortran 95 and later
5589 @item @emph{Syntax}:
5590 @code{RESULT = IBCLR(I, POS)}
5592 @item @emph{Arguments}:
5593 @multitable @columnfractions .15 .70
5594 @item @var{I} @tab The type shall be @code{INTEGER}.
5595 @item @var{POS} @tab The type shall be @code{INTEGER}.
5598 @item @emph{Return value}:
5599 The return value is of type @code{INTEGER} and of the same kind as
5602 @item @emph{See also}:
5603 @ref{IBITS}, @ref{IBSET}, @ref{IAND}, @ref{IOR}, @ref{IEOR}, @ref{MVBITS}
5610 @section @code{IBITS} --- Bit extraction
5613 @cindex bits, extract
5616 @item @emph{Description}:
5617 @code{IBITS} extracts a field of length @var{LEN} from @var{I},
5618 starting from bit position @var{POS} and extending left for @var{LEN}
5619 bits. The result is right-justified and the remaining bits are
5620 zeroed. The value of @code{POS+LEN} must be less than or equal to the
5621 value @code{BIT_SIZE(I)}.
5623 @item @emph{Standard}:
5624 Fortran 95 and later
5629 @item @emph{Syntax}:
5630 @code{RESULT = IBITS(I, POS, LEN)}
5632 @item @emph{Arguments}:
5633 @multitable @columnfractions .15 .70
5634 @item @var{I} @tab The type shall be @code{INTEGER}.
5635 @item @var{POS} @tab The type shall be @code{INTEGER}.
5636 @item @var{LEN} @tab The type shall be @code{INTEGER}.
5639 @item @emph{Return value}:
5640 The return value is of type @code{INTEGER} and of the same kind as
5643 @item @emph{See also}:
5644 @ref{BIT_SIZE}, @ref{IBCLR}, @ref{IBSET}, @ref{IAND}, @ref{IOR}, @ref{IEOR}
5650 @section @code{IBSET} --- Set bit
5655 @item @emph{Description}:
5656 @code{IBSET} returns the value of @var{I} with the bit at position
5657 @var{POS} set to one.
5659 @item @emph{Standard}:
5660 Fortran 95 and later
5665 @item @emph{Syntax}:
5666 @code{RESULT = IBSET(I, POS)}
5668 @item @emph{Arguments}:
5669 @multitable @columnfractions .15 .70
5670 @item @var{I} @tab The type shall be @code{INTEGER}.
5671 @item @var{POS} @tab The type shall be @code{INTEGER}.
5674 @item @emph{Return value}:
5675 The return value is of type @code{INTEGER} and of the same kind as
5678 @item @emph{See also}:
5679 @ref{IBCLR}, @ref{IBITS}, @ref{IAND}, @ref{IOR}, @ref{IEOR}, @ref{MVBITS}
5686 @section @code{ICHAR} --- Character-to-integer conversion function
5688 @cindex conversion, to integer
5691 @item @emph{Description}:
5692 @code{ICHAR(C)} returns the code for the character in the first character
5693 position of @code{C} in the system's native character set.
5694 The correspondence between characters and their codes is not necessarily
5695 the same across different GNU Fortran implementations.
5697 @item @emph{Standard}:
5698 Fortan 95 and later, with @var{KIND} argument Fortran 2003 and later
5703 @item @emph{Syntax}:
5704 @code{RESULT = ICHAR(C [, KIND])}
5706 @item @emph{Arguments}:
5707 @multitable @columnfractions .15 .70
5708 @item @var{C} @tab Shall be a scalar @code{CHARACTER}, with @code{INTENT(IN)}
5709 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
5710 expression indicating the kind parameter of the result.
5713 @item @emph{Return value}:
5714 The return value is of type @code{INTEGER} and of kind @var{KIND}. If
5715 @var{KIND} is absent, the return value is of default integer kind.
5717 @item @emph{Example}:
5722 end program test_ichar
5725 @item @emph{Specific names}:
5726 @multitable @columnfractions .20 .20 .20 .25
5727 @item Name @tab Argument @tab Return type @tab Standard
5728 @item @code{ICHAR(C)} @tab @code{CHARACTER C} @tab @code{INTEGER(4)} @tab Fortran 77 and later
5732 No intrinsic exists to convert between a numeric value and a formatted
5733 character string representation -- for instance, given the
5734 @code{CHARACTER} value @code{'154'}, obtaining an @code{INTEGER} or
5735 @code{REAL} value with the value 154, or vice versa. Instead, this
5736 functionality is provided by internal-file I/O, as in the following
5741 character(len=10) string, string2
5744 ! Convert a string to a numeric value
5745 read (string,'(I10)') value
5748 ! Convert a value to a formatted string
5749 write (string2,'(I10)') value
5751 end program read_val
5754 @item @emph{See also}:
5755 @ref{ACHAR}, @ref{CHAR}, @ref{IACHAR}
5762 @section @code{IDATE} --- Get current local time subroutine (day/month/year)
5764 @cindex date, current
5765 @cindex current date
5768 @item @emph{Description}:
5769 @code{IDATE(VALUES)} Fills @var{VALUES} with the numerical values at the
5770 current local time. The day (in the range 1-31), month (in the range 1-12),
5771 and year appear in elements 1, 2, and 3 of @var{VALUES}, respectively.
5772 The year has four significant digits.
5774 @item @emph{Standard}:
5780 @item @emph{Syntax}:
5781 @code{CALL IDATE(VALUES)}
5783 @item @emph{Arguments}:
5784 @multitable @columnfractions .15 .70
5785 @item @var{VALUES} @tab The type shall be @code{INTEGER, DIMENSION(3)} and
5786 the kind shall be the default integer kind.
5789 @item @emph{Return value}:
5790 Does not return anything.
5792 @item @emph{Example}:
5795 integer, dimension(3) :: tarray
5800 end program test_idate
5807 @section @code{IEOR} --- Bitwise logical exclusive or
5809 @cindex bitwise logical exclusive or
5810 @cindex logical exclusive or, bitwise
5813 @item @emph{Description}:
5814 @code{IEOR} returns the bitwise boolean exclusive-OR of @var{I} and
5817 @item @emph{Standard}:
5818 Fortran 95 and later
5823 @item @emph{Syntax}:
5824 @code{RESULT = IEOR(I, J)}
5826 @item @emph{Arguments}:
5827 @multitable @columnfractions .15 .70
5828 @item @var{I} @tab The type shall be @code{INTEGER}.
5829 @item @var{J} @tab The type shall be @code{INTEGER}, of the same
5830 kind as @var{I}. (As a GNU extension, different kinds are also
5834 @item @emph{Return value}:
5835 The return type is @code{INTEGER}, of the same kind as the
5836 arguments. (If the argument kinds differ, it is of the same kind as
5837 the larger argument.)
5839 @item @emph{See also}:
5840 @ref{IOR}, @ref{IAND}, @ref{IBITS}, @ref{IBSET}, @ref{IBCLR}, @ref{NOT}
5846 @section @code{IERRNO} --- Get the last system error number
5848 @cindex system, error handling
5851 @item @emph{Description}:
5852 Returns the last system error number, as given by the C @code{errno()}
5855 @item @emph{Standard}:
5861 @item @emph{Syntax}:
5862 @code{RESULT = IERRNO()}
5864 @item @emph{Arguments}:
5867 @item @emph{Return value}:
5868 The return value is of type @code{INTEGER} and of the default integer
5871 @item @emph{See also}:
5877 @node INDEX intrinsic
5878 @section @code{INDEX} --- Position of a substring within a string
5880 @cindex substring position
5881 @cindex string, find substring
5884 @item @emph{Description}:
5885 Returns the position of the start of the first occurrence of string
5886 @var{SUBSTRING} as a substring in @var{STRING}, counting from one. If
5887 @var{SUBSTRING} is not present in @var{STRING}, zero is returned. If
5888 the @var{BACK} argument is present and true, the return value is the
5889 start of the last occurrence rather than the first.
5891 @item @emph{Standard}:
5892 Fortran 77 and later, with @var{KIND} argument Fortran 2003 and later
5897 @item @emph{Syntax}:
5898 @code{RESULT = INDEX(STRING, SUBSTRING [, BACK [, KIND]])}
5900 @item @emph{Arguments}:
5901 @multitable @columnfractions .15 .70
5902 @item @var{STRING} @tab Shall be a scalar @code{CHARACTER}, with
5904 @item @var{SUBSTRING} @tab Shall be a scalar @code{CHARACTER}, with
5906 @item @var{BACK} @tab (Optional) Shall be a scalar @code{LOGICAL}, with
5908 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
5909 expression indicating the kind parameter of the result.
5912 @item @emph{Return value}:
5913 The return value is of type @code{INTEGER} and of kind @var{KIND}. If
5914 @var{KIND} is absent, the return value is of default integer kind.
5916 @item @emph{Specific names}:
5917 @multitable @columnfractions .20 .20 .20 .25
5918 @item Name @tab Argument @tab Return type @tab Standard
5919 @item @code{INDEX(STRING, SUBSTRING)} @tab @code{CHARACTER} @tab @code{INTEGER(4)} @tab Fortran 77 and later
5922 @item @emph{See also}:
5923 @ref{SCAN}, @ref{VERIFY}
5929 @section @code{INT} --- Convert to integer type
5933 @cindex conversion, to integer
5936 @item @emph{Description}:
5937 Convert to integer type
5939 @item @emph{Standard}:
5940 Fortran 77 and later
5945 @item @emph{Syntax}:
5946 @code{RESULT = INT(A [, KIND))}
5948 @item @emph{Arguments}:
5949 @multitable @columnfractions .15 .70
5950 @item @var{A} @tab Shall be of type @code{INTEGER},
5951 @code{REAL}, or @code{COMPLEX}.
5952 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
5953 expression indicating the kind parameter of the result.
5956 @item @emph{Return value}:
5957 These functions return a @code{INTEGER} variable or array under
5958 the following rules:
5962 If @var{A} is of type @code{INTEGER}, @code{INT(A) = A}
5964 If @var{A} is of type @code{REAL} and @math{|A| < 1}, @code{INT(A)} equals @code{0}.
5965 If @math{|A| \geq 1}, then @code{INT(A)} equals the largest integer that does not exceed
5966 the range of @var{A} and whose sign is the same as the sign of @var{A}.
5968 If @var{A} is of type @code{COMPLEX}, rule B is applied to the real part of @var{A}.
5971 @item @emph{Example}:
5975 complex :: z = (-3.7, 1.0)
5977 print *, int(z), int(z,8)
5981 @item @emph{Specific names}:
5982 @multitable @columnfractions .20 .20 .20 .25
5983 @item Name @tab Argument @tab Return type @tab Standard
5984 @item @code{INT(A)} @tab @code{REAL(4) A} @tab @code{INTEGER} @tab Fortran 77 and later
5985 @item @code{IFIX(A)} @tab @code{REAL(4) A} @tab @code{INTEGER} @tab Fortran 77 and later
5986 @item @code{IDINT(A)} @tab @code{REAL(8) A} @tab @code{INTEGER} @tab Fortran 77 and later
5993 @section @code{INT2} --- Convert to 16-bit integer type
5996 @cindex conversion, to integer
5999 @item @emph{Description}:
6000 Convert to a @code{KIND=2} integer type. This is equivalent to the
6001 standard @code{INT} intrinsic with an optional argument of
6002 @code{KIND=2}, and is only included for backwards compatibility.
6004 The @code{SHORT} intrinsic is equivalent to @code{INT2}.
6006 @item @emph{Standard}:
6012 @item @emph{Syntax}:
6013 @code{RESULT = INT2(A)}
6015 @item @emph{Arguments}:
6016 @multitable @columnfractions .15 .70
6017 @item @var{A} @tab Shall be of type @code{INTEGER},
6018 @code{REAL}, or @code{COMPLEX}.
6021 @item @emph{Return value}:
6022 The return value is a @code{INTEGER(2)} variable.
6024 @item @emph{See also}:
6025 @ref{INT}, @ref{INT8}, @ref{LONG}
6031 @section @code{INT8} --- Convert to 64-bit integer type
6033 @cindex conversion, to integer
6036 @item @emph{Description}:
6037 Convert to a @code{KIND=8} integer type. This is equivalent to the
6038 standard @code{INT} intrinsic with an optional argument of
6039 @code{KIND=8}, and is only included for backwards compatibility.
6041 @item @emph{Standard}:
6047 @item @emph{Syntax}:
6048 @code{RESULT = INT8(A)}
6050 @item @emph{Arguments}:
6051 @multitable @columnfractions .15 .70
6052 @item @var{A} @tab Shall be of type @code{INTEGER},
6053 @code{REAL}, or @code{COMPLEX}.
6056 @item @emph{Return value}:
6057 The return value is a @code{INTEGER(8)} variable.
6059 @item @emph{See also}:
6060 @ref{INT}, @ref{INT2}, @ref{LONG}
6066 @section @code{IOR} --- Bitwise logical or
6068 @cindex bitwise logical or
6069 @cindex logical or, bitwise
6072 @item @emph{Description}:
6073 @code{IOR} returns the bitwise boolean inclusive-OR of @var{I} and
6076 @item @emph{Standard}:
6077 Fortran 95 and later
6082 @item @emph{Syntax}:
6083 @code{RESULT = IOR(I, J)}
6085 @item @emph{Arguments}:
6086 @multitable @columnfractions .15 .70
6087 @item @var{I} @tab The type shall be @code{INTEGER}.
6088 @item @var{J} @tab The type shall be @code{INTEGER}, of the same
6089 kind as @var{I}. (As a GNU extension, different kinds are also
6093 @item @emph{Return value}:
6094 The return type is @code{INTEGER}, of the same kind as the
6095 arguments. (If the argument kinds differ, it is of the same kind as
6096 the larger argument.)
6098 @item @emph{See also}:
6099 @ref{IEOR}, @ref{IAND}, @ref{IBITS}, @ref{IBSET}, @ref{IBCLR}, @ref{NOT}
6105 @section @code{IRAND} --- Integer pseudo-random number
6107 @cindex random number generation
6110 @item @emph{Description}:
6111 @code{IRAND(FLAG)} returns a pseudo-random number from a uniform
6112 distribution between 0 and a system-dependent limit (which is in most
6113 cases 2147483647). If @var{FLAG} is 0, the next number
6114 in the current sequence is returned; if @var{FLAG} is 1, the generator
6115 is restarted by @code{CALL SRAND(0)}; if @var{FLAG} has any other value,
6116 it is used as a new seed with @code{SRAND}.
6118 This intrinsic routine is provided for backwards compatibility with
6119 GNU Fortran 77. It implements a simple modulo generator as provided
6120 by @command{g77}. For new code, one should consider the use of
6121 @ref{RANDOM_NUMBER} as it implements a superior algorithm.
6123 @item @emph{Standard}:
6129 @item @emph{Syntax}:
6130 @code{RESULT = IRAND(I)}
6132 @item @emph{Arguments}:
6133 @multitable @columnfractions .15 .70
6134 @item @var{I} @tab Shall be a scalar @code{INTEGER} of kind 4.
6137 @item @emph{Return value}:
6138 The return value is of @code{INTEGER(kind=4)} type.
6140 @item @emph{Example}:
6143 integer,parameter :: seed = 86456
6146 print *, irand(), irand(), irand(), irand()
6147 print *, irand(seed), irand(), irand(), irand()
6148 end program test_irand
6156 @section @code{IMAGE_INDEX} --- Function that converts a cosubscript to an image index
6157 @fnindex IMAGE_INDEX
6158 @cindex coarray, IMAGE_INDEX
6159 @cindex images, cosubscript to image index conversion
6162 @item @emph{Description}:
6163 Returns the image index belonging to a cosubscript.
6165 @item @emph{Standard}:
6166 Fortran 2008 and later
6171 @item @emph{Syntax}:
6172 @code{RESULT = IMAGE_INDEX(COARRAY, SUB)}
6174 @item @emph{Arguments}: None.
6175 @multitable @columnfractions .15 .70
6176 @item @var{COARRAY} @tab Coarray of any type.
6177 @item @var{SUB} @tab default integer rank-1 array of a size equal to
6178 the corank of @var{COARRAY}.
6182 @item @emph{Return value}:
6183 Scalar default integer with the value of the image index which corresponds
6184 to the cosubscripts. For invalid cosubscripts the result is zero.
6186 @item @emph{Example}:
6188 INTEGER :: array[2,-1:4,8,*]
6189 ! Writes 28 (or 0 if there are fewer than 28 images)
6190 WRITE (*,*) IMAGE_INDEX (array, [2,0,3,1])
6193 @item @emph{See also}:
6194 @ref{THIS_IMAGE}, @ref{NUM_IMAGES}
6200 @section @code{IS_IOSTAT_END} --- Test for end-of-file value
6201 @fnindex IS_IOSTAT_END
6202 @cindex IOSTAT, end of file
6205 @item @emph{Description}:
6206 @code{IS_IOSTAT_END} tests whether an variable has the value of the I/O
6207 status ``end of file''. The function is equivalent to comparing the variable
6208 with the @code{IOSTAT_END} parameter of the intrinsic module
6209 @code{ISO_FORTRAN_ENV}.
6211 @item @emph{Standard}:
6212 Fortran 2003 and later
6217 @item @emph{Syntax}:
6218 @code{RESULT = IS_IOSTAT_END(I)}
6220 @item @emph{Arguments}:
6221 @multitable @columnfractions .15 .70
6222 @item @var{I} @tab Shall be of the type @code{INTEGER}.
6225 @item @emph{Return value}:
6226 Returns a @code{LOGICAL} of the default kind, which @code{.TRUE.} if
6227 @var{I} has the value which indicates an end of file condition for
6228 IOSTAT= specifiers, and is @code{.FALSE.} otherwise.
6230 @item @emph{Example}:
6235 OPEN(88, FILE='test.dat')
6236 READ(88, *, IOSTAT=stat) i
6237 IF(IS_IOSTAT_END(stat)) STOP 'END OF FILE'
6245 @section @code{IS_IOSTAT_EOR} --- Test for end-of-record value
6246 @fnindex IS_IOSTAT_EOR
6247 @cindex IOSTAT, end of record
6250 @item @emph{Description}:
6251 @code{IS_IOSTAT_EOR} tests whether an variable has the value of the I/O
6252 status ``end of record''. The function is equivalent to comparing the
6253 variable with the @code{IOSTAT_EOR} parameter of the intrinsic module
6254 @code{ISO_FORTRAN_ENV}.
6256 @item @emph{Standard}:
6257 Fortran 2003 and later
6262 @item @emph{Syntax}:
6263 @code{RESULT = IS_IOSTAT_EOR(I)}
6265 @item @emph{Arguments}:
6266 @multitable @columnfractions .15 .70
6267 @item @var{I} @tab Shall be of the type @code{INTEGER}.
6270 @item @emph{Return value}:
6271 Returns a @code{LOGICAL} of the default kind, which @code{.TRUE.} if
6272 @var{I} has the value which indicates an end of file condition for
6273 IOSTAT= specifiers, and is @code{.FALSE.} otherwise.
6275 @item @emph{Example}:
6279 INTEGER :: stat, i(50)
6280 OPEN(88, FILE='test.dat', FORM='UNFORMATTED')
6281 READ(88, IOSTAT=stat) i
6282 IF(IS_IOSTAT_EOR(stat)) STOP 'END OF RECORD'
6290 @section @code{ISATTY} --- Whether a unit is a terminal device.
6292 @cindex system, terminal
6295 @item @emph{Description}:
6296 Determine whether a unit is connected to a terminal device.
6298 @item @emph{Standard}:
6304 @item @emph{Syntax}:
6305 @code{RESULT = ISATTY(UNIT)}
6307 @item @emph{Arguments}:
6308 @multitable @columnfractions .15 .70
6309 @item @var{UNIT} @tab Shall be a scalar @code{INTEGER}.
6312 @item @emph{Return value}:
6313 Returns @code{.TRUE.} if the @var{UNIT} is connected to a terminal
6314 device, @code{.FALSE.} otherwise.
6316 @item @emph{Example}:
6319 INTEGER(kind=1) :: unit
6321 write(*,*) isatty(unit=unit)
6325 @item @emph{See also}:
6332 @section @code{ISHFT} --- Shift bits
6337 @item @emph{Description}:
6338 @code{ISHFT} returns a value corresponding to @var{I} with all of the
6339 bits shifted @var{SHIFT} places. A value of @var{SHIFT} greater than
6340 zero corresponds to a left shift, a value of zero corresponds to no
6341 shift, and a value less than zero corresponds to a right shift. If the
6342 absolute value of @var{SHIFT} is greater than @code{BIT_SIZE(I)}, the
6343 value is undefined. Bits shifted out from the left end or right end are
6344 lost; zeros are shifted in from the opposite end.
6346 @item @emph{Standard}:
6347 Fortran 95 and later
6352 @item @emph{Syntax}:
6353 @code{RESULT = ISHFT(I, SHIFT)}
6355 @item @emph{Arguments}:
6356 @multitable @columnfractions .15 .70
6357 @item @var{I} @tab The type shall be @code{INTEGER}.
6358 @item @var{SHIFT} @tab The type shall be @code{INTEGER}.
6361 @item @emph{Return value}:
6362 The return value is of type @code{INTEGER} and of the same kind as
6365 @item @emph{See also}:
6372 @section @code{ISHFTC} --- Shift bits circularly
6374 @cindex bits, shift circular
6377 @item @emph{Description}:
6378 @code{ISHFTC} returns a value corresponding to @var{I} with the
6379 rightmost @var{SIZE} bits shifted circularly @var{SHIFT} places; that
6380 is, bits shifted out one end are shifted into the opposite end. A value
6381 of @var{SHIFT} greater than zero corresponds to a left shift, a value of
6382 zero corresponds to no shift, and a value less than zero corresponds to
6383 a right shift. The absolute value of @var{SHIFT} must be less than
6384 @var{SIZE}. If the @var{SIZE} argument is omitted, it is taken to be
6385 equivalent to @code{BIT_SIZE(I)}.
6387 @item @emph{Standard}:
6388 Fortran 95 and later
6393 @item @emph{Syntax}:
6394 @code{RESULT = ISHFTC(I, SHIFT [, SIZE])}
6396 @item @emph{Arguments}:
6397 @multitable @columnfractions .15 .70
6398 @item @var{I} @tab The type shall be @code{INTEGER}.
6399 @item @var{SHIFT} @tab The type shall be @code{INTEGER}.
6400 @item @var{SIZE} @tab (Optional) The type shall be @code{INTEGER};
6401 the value must be greater than zero and less than or equal to
6405 @item @emph{Return value}:
6406 The return value is of type @code{INTEGER} and of the same kind as
6409 @item @emph{See also}:
6416 @section @code{ISNAN} --- Test for a NaN
6421 @item @emph{Description}:
6422 @code{ISNAN} tests whether a floating-point value is an IEEE
6424 @item @emph{Standard}:
6430 @item @emph{Syntax}:
6433 @item @emph{Arguments}:
6434 @multitable @columnfractions .15 .70
6435 @item @var{X} @tab Variable of the type @code{REAL}.
6439 @item @emph{Return value}:
6440 Returns a default-kind @code{LOGICAL}. The returned value is @code{TRUE}
6441 if @var{X} is a NaN and @code{FALSE} otherwise.
6443 @item @emph{Example}:
6450 if (isnan(x)) stop '"x" is a NaN'
6451 end program test_nan
6458 @section @code{ITIME} --- Get current local time subroutine (hour/minutes/seconds)
6460 @cindex time, current
6461 @cindex current time
6464 @item @emph{Description}:
6465 @code{IDATE(VALUES)} Fills @var{VALUES} with the numerical values at the
6466 current local time. The hour (in the range 1-24), minute (in the range 1-60),
6467 and seconds (in the range 1-60) appear in elements 1, 2, and 3 of @var{VALUES},
6470 @item @emph{Standard}:
6476 @item @emph{Syntax}:
6477 @code{CALL ITIME(VALUES)}
6479 @item @emph{Arguments}:
6480 @multitable @columnfractions .15 .70
6481 @item @var{VALUES} @tab The type shall be @code{INTEGER, DIMENSION(3)}
6482 and the kind shall be the default integer kind.
6485 @item @emph{Return value}:
6486 Does not return anything.
6489 @item @emph{Example}:
6492 integer, dimension(3) :: tarray
6497 end program test_itime
6504 @section @code{KILL} --- Send a signal to a process
6508 @item @emph{Description}:
6509 @item @emph{Standard}:
6510 Sends the signal specified by @var{SIGNAL} to the process @var{PID}.
6513 This intrinsic is provided in both subroutine and function forms; however,
6514 only one form can be used in any given program unit.
6517 Subroutine, function
6519 @item @emph{Syntax}:
6520 @code{CALL KILL(C, VALUE [, STATUS])}
6522 @item @emph{Arguments}:
6523 @multitable @columnfractions .15 .70
6524 @item @var{C} @tab Shall be a scalar @code{INTEGER}, with
6526 @item @var{VALUE} @tab Shall be a scalar @code{INTEGER}, with
6528 @item @var{STATUS} @tab (Optional) status flag of type @code{INTEGER(4)} or
6529 @code{INTEGER(8)}. Returns 0 on success, or a system-specific error code
6533 @item @emph{See also}:
6534 @ref{ABORT}, @ref{EXIT}
6540 @section @code{KIND} --- Kind of an entity
6545 @item @emph{Description}:
6546 @code{KIND(X)} returns the kind value of the entity @var{X}.
6548 @item @emph{Standard}:
6549 Fortran 95 and later
6554 @item @emph{Syntax}:
6557 @item @emph{Arguments}:
6558 @multitable @columnfractions .15 .70
6559 @item @var{X} @tab Shall be of type @code{LOGICAL}, @code{INTEGER},
6560 @code{REAL}, @code{COMPLEX} or @code{CHARACTER}.
6563 @item @emph{Return value}:
6564 The return value is a scalar of type @code{INTEGER} and of the default
6567 @item @emph{Example}:
6570 integer,parameter :: kc = kind(' ')
6571 integer,parameter :: kl = kind(.true.)
6573 print *, "The default character kind is ", kc
6574 print *, "The default logical kind is ", kl
6575 end program test_kind
6583 @section @code{LBOUND} --- Lower dimension bounds of an array
6585 @cindex array, lower bound
6588 @item @emph{Description}:
6589 Returns the lower bounds of an array, or a single lower bound
6590 along the @var{DIM} dimension.
6591 @item @emph{Standard}:
6592 Fortran 95 and later, with @var{KIND} argument Fortran 2003 and later
6597 @item @emph{Syntax}:
6598 @code{RESULT = LBOUND(ARRAY [, DIM [, KIND]])}
6600 @item @emph{Arguments}:
6601 @multitable @columnfractions .15 .70
6602 @item @var{ARRAY} @tab Shall be an array, of any type.
6603 @item @var{DIM} @tab (Optional) Shall be a scalar @code{INTEGER}.
6604 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
6605 expression indicating the kind parameter of the result.
6608 @item @emph{Return value}:
6609 The return value is of type @code{INTEGER} and of kind @var{KIND}. If
6610 @var{KIND} is absent, the return value is of default integer kind.
6611 If @var{DIM} is absent, the result is an array of the lower bounds of
6612 @var{ARRAY}. If @var{DIM} is present, the result is a scalar
6613 corresponding to the lower bound of the array along that dimension. If
6614 @var{ARRAY} is an expression rather than a whole array or array
6615 structure component, or if it has a zero extent along the relevant
6616 dimension, the lower bound is taken to be 1.
6618 @item @emph{See also}:
6619 @ref{UBOUND}, @ref{LCOBOUND}
6625 @section @code{LCOBOUND} --- Lower codimension bounds of an array
6627 @cindex coarray, lower bound
6630 @item @emph{Description}:
6631 Returns the lower bounds of a coarray, or a single lower cobound
6632 along the @var{DIM} codimension.
6633 @item @emph{Standard}:
6634 Fortran 2008 and later
6639 @item @emph{Syntax}:
6640 @code{RESULT = LCOBOUND(COARRAY [, DIM [, KIND]])}
6642 @item @emph{Arguments}:
6643 @multitable @columnfractions .15 .70
6644 @item @var{ARRAY} @tab Shall be an coarray, of any type.
6645 @item @var{DIM} @tab (Optional) Shall be a scalar @code{INTEGER}.
6646 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
6647 expression indicating the kind parameter of the result.
6650 @item @emph{Return value}:
6651 The return value is of type @code{INTEGER} and of kind @var{KIND}. If
6652 @var{KIND} is absent, the return value is of default integer kind.
6653 If @var{DIM} is absent, the result is an array of the lower cobounds of
6654 @var{COARRAY}. If @var{DIM} is present, the result is a scalar
6655 corresponding to the lower cobound of the array along that codimension.
6657 @item @emph{See also}:
6658 @ref{UCOBOUND}, @ref{LBOUND}
6664 @section @code{LEADZ} --- Number of leading zero bits of an integer
6669 @item @emph{Description}:
6670 @code{LEADZ} returns the number of leading zero bits of an integer.
6672 @item @emph{Standard}:
6673 Fortran 2008 and later
6678 @item @emph{Syntax}:
6679 @code{RESULT = LEADZ(I)}
6681 @item @emph{Arguments}:
6682 @multitable @columnfractions .15 .70
6683 @item @var{I} @tab Shall be of type @code{INTEGER}.
6686 @item @emph{Return value}:
6687 The type of the return value is the default @code{INTEGER}.
6688 If all the bits of @code{I} are zero, the result value is @code{BIT_SIZE(I)}.
6690 @item @emph{Example}:
6693 WRITE (*,*) LEADZ(1) ! prints 8 if BITSIZE(I) has the value 32
6697 @item @emph{See also}:
6698 @ref{BIT_SIZE}, @ref{TRAILZ}
6704 @section @code{LEN} --- Length of a character entity
6706 @cindex string, length
6709 @item @emph{Description}:
6710 Returns the length of a character string. If @var{STRING} is an array,
6711 the length of an element of @var{STRING} is returned. Note that
6712 @var{STRING} need not be defined when this intrinsic is invoked, since
6713 only the length, not the content, of @var{STRING} is needed.
6715 @item @emph{Standard}:
6716 Fortran 77 and later, with @var{KIND} argument Fortran 2003 and later
6721 @item @emph{Syntax}:
6722 @code{L = LEN(STRING [, KIND])}
6724 @item @emph{Arguments}:
6725 @multitable @columnfractions .15 .70
6726 @item @var{STRING} @tab Shall be a scalar or array of type
6727 @code{CHARACTER}, with @code{INTENT(IN)}
6728 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
6729 expression indicating the kind parameter of the result.
6732 @item @emph{Return value}:
6733 The return value is of type @code{INTEGER} and of kind @var{KIND}. If
6734 @var{KIND} is absent, the return value is of default integer kind.
6737 @item @emph{Specific names}:
6738 @multitable @columnfractions .20 .20 .20 .25
6739 @item Name @tab Argument @tab Return type @tab Standard
6740 @item @code{LEN(STRING)} @tab @code{CHARACTER} @tab @code{INTEGER} @tab Fortran 77 and later
6744 @item @emph{See also}:
6745 @ref{LEN_TRIM}, @ref{ADJUSTL}, @ref{ADJUSTR}
6751 @section @code{LEN_TRIM} --- Length of a character entity without trailing blank characters
6753 @cindex string, length, without trailing whitespace
6756 @item @emph{Description}:
6757 Returns the length of a character string, ignoring any trailing blanks.
6759 @item @emph{Standard}:
6760 Fortran 95 and later, with @var{KIND} argument Fortran 2003 and later
6765 @item @emph{Syntax}:
6766 @code{RESULT = LEN_TRIM(STRING [, KIND])}
6768 @item @emph{Arguments}:
6769 @multitable @columnfractions .15 .70
6770 @item @var{STRING} @tab Shall be a scalar of type @code{CHARACTER},
6771 with @code{INTENT(IN)}
6772 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
6773 expression indicating the kind parameter of the result.
6776 @item @emph{Return value}:
6777 The return value is of type @code{INTEGER} and of kind @var{KIND}. If
6778 @var{KIND} is absent, the return value is of default integer kind.
6780 @item @emph{See also}:
6781 @ref{LEN}, @ref{ADJUSTL}, @ref{ADJUSTR}
6787 @section @code{LGE} --- Lexical greater than or equal
6789 @cindex lexical comparison of strings
6790 @cindex string, comparison
6793 @item @emph{Description}:
6794 Determines whether one string is lexically greater than or equal to
6795 another string, where the two strings are interpreted as containing
6796 ASCII character codes. If the String A and String B are not the same
6797 length, the shorter is compared as if spaces were appended to it to form
6798 a value that has the same length as the longer.
6800 In general, the lexical comparison intrinsics @code{LGE}, @code{LGT},
6801 @code{LLE}, and @code{LLT} differ from the corresponding intrinsic
6802 operators @code{.GE.}, @code{.GT.}, @code{.LE.}, and @code{.LT.}, in
6803 that the latter use the processor's character ordering (which is not
6804 ASCII on some targets), whereas the former always use the ASCII
6807 @item @emph{Standard}:
6808 Fortran 77 and later
6813 @item @emph{Syntax}:
6814 @code{RESULT = LGE(STRING_A, STRING_B)}
6816 @item @emph{Arguments}:
6817 @multitable @columnfractions .15 .70
6818 @item @var{STRING_A} @tab Shall be of default @code{CHARACTER} type.
6819 @item @var{STRING_B} @tab Shall be of default @code{CHARACTER} type.
6822 @item @emph{Return value}:
6823 Returns @code{.TRUE.} if @code{STRING_A >= STRING_B}, and @code{.FALSE.}
6824 otherwise, based on the ASCII ordering.
6826 @item @emph{Specific names}:
6827 @multitable @columnfractions .20 .20 .20 .25
6828 @item Name @tab Argument @tab Return type @tab Standard
6829 @item @code{LGE(STRING_A, STRING_B)} @tab @code{CHARACTER} @tab @code{LOGICAL} @tab Fortran 77 and later
6832 @item @emph{See also}:
6833 @ref{LGT}, @ref{LLE}, @ref{LLT}
6839 @section @code{LGT} --- Lexical greater than
6841 @cindex lexical comparison of strings
6842 @cindex string, comparison
6845 @item @emph{Description}:
6846 Determines whether one string is lexically greater 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 = LGT(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{Specific names}:
6879 @multitable @columnfractions .20 .20 .20 .25
6880 @item Name @tab Argument @tab Return type @tab Standard
6881 @item @code{LGT(STRING_A, STRING_B)} @tab @code{CHARACTER} @tab @code{LOGICAL} @tab Fortran 77 and later
6884 @item @emph{See also}:
6885 @ref{LGE}, @ref{LLE}, @ref{LLT}
6891 @section @code{LINK} --- Create a hard link
6893 @cindex file system, create link
6894 @cindex file system, hard link
6897 @item @emph{Description}:
6898 Makes a (hard) link from file @var{PATH1} to @var{PATH2}. A null
6899 character (@code{CHAR(0)}) can be used to mark the end of the names in
6900 @var{PATH1} and @var{PATH2}; otherwise, trailing blanks in the file
6901 names are ignored. If the @var{STATUS} argument is supplied, it
6902 contains 0 on success or a nonzero error code upon return; see
6905 This intrinsic is provided in both subroutine and function forms;
6906 however, only one form can be used in any given program unit.
6908 @item @emph{Standard}:
6912 Subroutine, function
6914 @item @emph{Syntax}:
6915 @multitable @columnfractions .80
6916 @item @code{CALL LINK(PATH1, PATH2 [, STATUS])}
6917 @item @code{STATUS = LINK(PATH1, PATH2)}
6920 @item @emph{Arguments}:
6921 @multitable @columnfractions .15 .70
6922 @item @var{PATH1} @tab Shall be of default @code{CHARACTER} type.
6923 @item @var{PATH2} @tab Shall be of default @code{CHARACTER} type.
6924 @item @var{STATUS} @tab (Optional) Shall be of default @code{INTEGER} type.
6927 @item @emph{See also}:
6928 @ref{SYMLNK}, @ref{UNLINK}
6934 @section @code{LLE} --- Lexical less than or equal
6936 @cindex lexical comparison of strings
6937 @cindex string, comparison
6940 @item @emph{Description}:
6941 Determines whether one string is lexically less than or equal to another
6942 string, where the two strings are interpreted as containing ASCII
6943 character codes. If the String A and String B are not the same length,
6944 the shorter is compared as if spaces were appended to it to form a value
6945 that has the same length as the longer.
6947 In general, the lexical comparison intrinsics @code{LGE}, @code{LGT},
6948 @code{LLE}, and @code{LLT} differ from the corresponding intrinsic
6949 operators @code{.GE.}, @code{.GT.}, @code{.LE.}, and @code{.LT.}, in
6950 that the latter use the processor's character ordering (which is not
6951 ASCII on some targets), whereas the former always use the ASCII
6954 @item @emph{Standard}:
6955 Fortran 77 and later
6960 @item @emph{Syntax}:
6961 @code{RESULT = LLE(STRING_A, STRING_B)}
6963 @item @emph{Arguments}:
6964 @multitable @columnfractions .15 .70
6965 @item @var{STRING_A} @tab Shall be of default @code{CHARACTER} type.
6966 @item @var{STRING_B} @tab Shall be of default @code{CHARACTER} type.
6969 @item @emph{Return value}:
6970 Returns @code{.TRUE.} if @code{STRING_A <= STRING_B}, and @code{.FALSE.}
6971 otherwise, based on the ASCII ordering.
6973 @item @emph{Specific names}:
6974 @multitable @columnfractions .20 .20 .20 .25
6975 @item Name @tab Argument @tab Return type @tab Standard
6976 @item @code{LLE(STRING_A, STRING_B)} @tab @code{CHARACTER} @tab @code{LOGICAL} @tab Fortran 77 and later
6979 @item @emph{See also}:
6980 @ref{LGE}, @ref{LGT}, @ref{LLT}
6986 @section @code{LLT} --- Lexical less than
6988 @cindex lexical comparison of strings
6989 @cindex string, comparison
6992 @item @emph{Description}:
6993 Determines whether one string is lexically less than another string,
6994 where the two strings are interpreted as containing ASCII character
6995 codes. If the String A and String B are not the same length, the
6996 shorter is compared as if spaces were appended to it to form a value
6997 that has the same length as the longer.
6999 In general, the lexical comparison intrinsics @code{LGE}, @code{LGT},
7000 @code{LLE}, and @code{LLT} differ from the corresponding intrinsic
7001 operators @code{.GE.}, @code{.GT.}, @code{.LE.}, and @code{.LT.}, in
7002 that the latter use the processor's character ordering (which is not
7003 ASCII on some targets), whereas the former always use the ASCII
7006 @item @emph{Standard}:
7007 Fortran 77 and later
7012 @item @emph{Syntax}:
7013 @code{RESULT = LLT(STRING_A, STRING_B)}
7015 @item @emph{Arguments}:
7016 @multitable @columnfractions .15 .70
7017 @item @var{STRING_A} @tab Shall be of default @code{CHARACTER} type.
7018 @item @var{STRING_B} @tab Shall be of default @code{CHARACTER} type.
7021 @item @emph{Return value}:
7022 Returns @code{.TRUE.} if @code{STRING_A < STRING_B}, and @code{.FALSE.}
7023 otherwise, based on the ASCII ordering.
7025 @item @emph{Specific names}:
7026 @multitable @columnfractions .20 .20 .20 .25
7027 @item Name @tab Argument @tab Return type @tab Standard
7028 @item @code{LLT(STRING_A, STRING_B)} @tab @code{CHARACTER} @tab @code{LOGICAL} @tab Fortran 77 and later
7031 @item @emph{See also}:
7032 @ref{LGE}, @ref{LGT}, @ref{LLE}
7038 @section @code{LNBLNK} --- Index of the last non-blank character in a string
7040 @cindex string, find non-blank character
7043 @item @emph{Description}:
7044 Returns the length of a character string, ignoring any trailing blanks.
7045 This is identical to the standard @code{LEN_TRIM} intrinsic, and is only
7046 included for backwards compatibility.
7048 @item @emph{Standard}:
7054 @item @emph{Syntax}:
7055 @code{RESULT = LNBLNK(STRING)}
7057 @item @emph{Arguments}:
7058 @multitable @columnfractions .15 .70
7059 @item @var{STRING} @tab Shall be a scalar of type @code{CHARACTER},
7060 with @code{INTENT(IN)}
7063 @item @emph{Return value}:
7064 The return value is of @code{INTEGER(kind=4)} type.
7066 @item @emph{See also}:
7067 @ref{INDEX intrinsic}, @ref{LEN_TRIM}
7073 @section @code{LOC} --- Returns the address of a variable
7075 @cindex location of a variable in memory
7078 @item @emph{Description}:
7079 @code{LOC(X)} returns the address of @var{X} as an integer.
7081 @item @emph{Standard}:
7087 @item @emph{Syntax}:
7088 @code{RESULT = LOC(X)}
7090 @item @emph{Arguments}:
7091 @multitable @columnfractions .15 .70
7092 @item @var{X} @tab Variable of any type.
7095 @item @emph{Return value}:
7096 The return value is of type @code{INTEGER}, with a @code{KIND}
7097 corresponding to the size (in bytes) of a memory address on the target
7100 @item @emph{Example}:
7107 end program test_loc
7114 @section @code{LOG} --- Logarithm function
7121 @cindex exponential function, inverse
7122 @cindex logarithmic function
7125 @item @emph{Description}:
7126 @code{LOG(X)} computes the logarithm of @var{X}.
7128 @item @emph{Standard}:
7129 Fortran 77 and later
7134 @item @emph{Syntax}:
7135 @code{RESULT = LOG(X)}
7137 @item @emph{Arguments}:
7138 @multitable @columnfractions .15 .70
7139 @item @var{X} @tab The type shall be @code{REAL} or
7143 @item @emph{Return value}:
7144 The return value is of type @code{REAL} or @code{COMPLEX}.
7145 The kind type parameter is the same as @var{X}.
7146 If @var{X} is @code{COMPLEX}, the imaginary part @math{\omega} is in the range
7147 @math{-\pi \leq \omega \leq \pi}.
7149 @item @emph{Example}:
7152 real(8) :: x = 1.0_8
7153 complex :: z = (1.0, 2.0)
7156 end program test_log
7159 @item @emph{Specific names}:
7160 @multitable @columnfractions .20 .20 .20 .25
7161 @item Name @tab Argument @tab Return type @tab Standard
7162 @item @code{ALOG(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab f95, gnu
7163 @item @code{DLOG(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab f95, gnu
7164 @item @code{CLOG(X)} @tab @code{COMPLEX(4) X} @tab @code{COMPLEX(4)} @tab f95, gnu
7165 @item @code{ZLOG(X)} @tab @code{COMPLEX(8) X} @tab @code{COMPLEX(8)} @tab f95, gnu
7166 @item @code{CDLOG(X)} @tab @code{COMPLEX(8) X} @tab @code{COMPLEX(8)} @tab f95, gnu
7173 @section @code{LOG10} --- Base 10 logarithm function
7177 @cindex exponential function, inverse
7178 @cindex logarithmic function
7181 @item @emph{Description}:
7182 @code{LOG10(X)} computes the base 10 logarithm of @var{X}.
7184 @item @emph{Standard}:
7185 Fortran 77 and later
7190 @item @emph{Syntax}:
7191 @code{RESULT = LOG10(X)}
7193 @item @emph{Arguments}:
7194 @multitable @columnfractions .15 .70
7195 @item @var{X} @tab The type shall be @code{REAL}.
7198 @item @emph{Return value}:
7199 The return value is of type @code{REAL} or @code{COMPLEX}.
7200 The kind type parameter is the same as @var{X}.
7202 @item @emph{Example}:
7205 real(8) :: x = 10.0_8
7207 end program test_log10
7210 @item @emph{Specific names}:
7211 @multitable @columnfractions .20 .20 .20 .25
7212 @item Name @tab Argument @tab Return type @tab Standard
7213 @item @code{ALOG10(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab Fortran 95 and later
7214 @item @code{DLOG10(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab Fortran 95 and later
7221 @section @code{LOG_GAMMA} --- Logarithm of the Gamma function
7226 @cindex Gamma function, logarithm of
7229 @item @emph{Description}:
7230 @code{LOG_GAMMA(X)} computes the natural logarithm of the absolute value
7231 of the Gamma (@math{\Gamma}) function.
7233 @item @emph{Standard}:
7234 Fortran 2008 and later
7239 @item @emph{Syntax}:
7240 @code{X = LOG_GAMMA(X)}
7242 @item @emph{Arguments}:
7243 @multitable @columnfractions .15 .70
7244 @item @var{X} @tab Shall be of type @code{REAL} and neither zero
7245 nor a negative integer.
7248 @item @emph{Return value}:
7249 The return value is of type @code{REAL} of the same kind as @var{X}.
7251 @item @emph{Example}:
7253 program test_log_gamma
7255 x = lgamma(x) ! returns 0.0
7256 end program test_log_gamma
7259 @item @emph{Specific names}:
7260 @multitable @columnfractions .20 .20 .20 .25
7261 @item Name @tab Argument @tab Return type @tab Standard
7262 @item @code{LGAMMA(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab GNU Extension
7263 @item @code{ALGAMA(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab GNU Extension
7264 @item @code{DLGAMA(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU Extension
7267 @item @emph{See also}:
7268 Gamma function: @ref{GAMMA}
7275 @section @code{LOGICAL} --- Convert to logical type
7277 @cindex conversion, to logical
7280 @item @emph{Description}:
7281 Converts one kind of @code{LOGICAL} variable to another.
7283 @item @emph{Standard}:
7284 Fortran 95 and later
7289 @item @emph{Syntax}:
7290 @code{RESULT = LOGICAL(L [, KIND])}
7292 @item @emph{Arguments}:
7293 @multitable @columnfractions .15 .70
7294 @item @var{L} @tab The type shall be @code{LOGICAL}.
7295 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
7296 expression indicating the kind parameter of the result.
7299 @item @emph{Return value}:
7300 The return value is a @code{LOGICAL} value equal to @var{L}, with a
7301 kind corresponding to @var{KIND}, or of the default logical kind if
7302 @var{KIND} is not given.
7304 @item @emph{See also}:
7305 @ref{INT}, @ref{REAL}, @ref{CMPLX}
7311 @section @code{LONG} --- Convert to integer type
7313 @cindex conversion, to integer
7316 @item @emph{Description}:
7317 Convert to a @code{KIND=4} integer type, which is the same size as a C
7318 @code{long} integer. This is equivalent to the standard @code{INT}
7319 intrinsic with an optional argument of @code{KIND=4}, and is only
7320 included for backwards compatibility.
7322 @item @emph{Standard}:
7328 @item @emph{Syntax}:
7329 @code{RESULT = LONG(A)}
7331 @item @emph{Arguments}:
7332 @multitable @columnfractions .15 .70
7333 @item @var{A} @tab Shall be of type @code{INTEGER},
7334 @code{REAL}, or @code{COMPLEX}.
7337 @item @emph{Return value}:
7338 The return value is a @code{INTEGER(4)} variable.
7340 @item @emph{See also}:
7341 @ref{INT}, @ref{INT2}, @ref{INT8}
7347 @section @code{LSHIFT} --- Left shift bits
7349 @cindex bits, shift left
7352 @item @emph{Description}:
7353 @code{LSHIFT} returns a value corresponding to @var{I} with all of the
7354 bits shifted left by @var{SHIFT} places. If the absolute value of
7355 @var{SHIFT} is greater than @code{BIT_SIZE(I)}, the value is undefined.
7356 Bits shifted out from the left end are lost; zeros are shifted in from
7359 This function has been superseded by the @code{ISHFT} intrinsic, which
7360 is standard in Fortran 95 and later.
7362 @item @emph{Standard}:
7368 @item @emph{Syntax}:
7369 @code{RESULT = LSHIFT(I, SHIFT)}
7371 @item @emph{Arguments}:
7372 @multitable @columnfractions .15 .70
7373 @item @var{I} @tab The type shall be @code{INTEGER}.
7374 @item @var{SHIFT} @tab The type shall be @code{INTEGER}.
7377 @item @emph{Return value}:
7378 The return value is of type @code{INTEGER} and of the same kind as
7381 @item @emph{See also}:
7382 @ref{ISHFT}, @ref{ISHFTC}, @ref{RSHIFT}
7389 @section @code{LSTAT} --- Get file status
7391 @cindex file system, file status
7394 @item @emph{Description}:
7395 @code{LSTAT} is identical to @ref{STAT}, except that if path is a
7396 symbolic link, then the link itself is statted, not the file that it
7399 The elements in @code{VALUES} are the same as described by @ref{STAT}.
7401 This intrinsic is provided in both subroutine and function forms;
7402 however, only one form can be used in any given program unit.
7404 @item @emph{Standard}:
7408 Subroutine, function
7410 @item @emph{Syntax}:
7411 @code{CALL LSTAT(NAME, VALUES [, STATUS])}
7413 @item @emph{Arguments}:
7414 @multitable @columnfractions .15 .70
7415 @item @var{NAME} @tab The type shall be @code{CHARACTER} of the default
7416 kind, a valid path within the file system.
7417 @item @var{VALUES} @tab The type shall be @code{INTEGER(4), DIMENSION(13)}.
7418 @item @var{STATUS} @tab (Optional) status flag of type @code{INTEGER(4)}.
7419 Returns 0 on success and a system specific error code otherwise.
7422 @item @emph{Example}:
7423 See @ref{STAT} for an example.
7425 @item @emph{See also}:
7426 To stat an open file: @ref{FSTAT}, to stat a file: @ref{STAT}
7432 @section @code{LTIME} --- Convert time to local time info
7434 @cindex time, conversion to local time info
7437 @item @emph{Description}:
7438 Given a system time value @var{TIME} (as provided by the @code{TIME8()}
7439 intrinsic), fills @var{VALUES} with values extracted from it appropriate
7440 to the local time zone using @code{localtime(3)}.
7442 @item @emph{Standard}:
7448 @item @emph{Syntax}:
7449 @code{CALL LTIME(TIME, VALUES)}
7451 @item @emph{Arguments}:
7452 @multitable @columnfractions .15 .70
7453 @item @var{TIME} @tab An @code{INTEGER} scalar expression
7454 corresponding to a system time, with @code{INTENT(IN)}.
7455 @item @var{VALUES} @tab A default @code{INTEGER} array with 9 elements,
7456 with @code{INTENT(OUT)}.
7459 @item @emph{Return value}:
7460 The elements of @var{VALUES} are assigned as follows:
7462 @item Seconds after the minute, range 0--59 or 0--61 to allow for leap
7464 @item Minutes after the hour, range 0--59
7465 @item Hours past midnight, range 0--23
7466 @item Day of month, range 0--31
7467 @item Number of months since January, range 0--12
7468 @item Years since 1900
7469 @item Number of days since Sunday, range 0--6
7470 @item Days since January 1
7471 @item Daylight savings indicator: positive if daylight savings is in
7472 effect, zero if not, and negative if the information is not available.
7475 @item @emph{See also}:
7476 @ref{CTIME}, @ref{GMTIME}, @ref{TIME}, @ref{TIME8}
7483 @section @code{MALLOC} --- Allocate dynamic memory
7485 @cindex pointer, cray
7488 @item @emph{Description}:
7489 @code{MALLOC(SIZE)} allocates @var{SIZE} bytes of dynamic memory and
7490 returns the address of the allocated memory. The @code{MALLOC} intrinsic
7491 is an extension intended to be used with Cray pointers, and is provided
7492 in GNU Fortran to allow the user to compile legacy code. For new code
7493 using Fortran 95 pointers, the memory allocation intrinsic is
7496 @item @emph{Standard}:
7502 @item @emph{Syntax}:
7503 @code{PTR = MALLOC(SIZE)}
7505 @item @emph{Arguments}:
7506 @multitable @columnfractions .15 .70
7507 @item @var{SIZE} @tab The type shall be @code{INTEGER}.
7510 @item @emph{Return value}:
7511 The return value is of type @code{INTEGER(K)}, with @var{K} such that
7512 variables of type @code{INTEGER(K)} have the same size as
7513 C pointers (@code{sizeof(void *)}).
7515 @item @emph{Example}:
7516 The following example demonstrates the use of @code{MALLOC} and
7517 @code{FREE} with Cray pointers.
7526 ptr_x = malloc(20*8)
7528 x(i) = sqrt(1.0d0 / i)
7536 end program test_malloc
7539 @item @emph{See also}:
7546 @section @code{MATMUL} --- matrix multiplication
7548 @cindex matrix multiplication
7549 @cindex product, matrix
7552 @item @emph{Description}:
7553 Performs a matrix multiplication on numeric or logical arguments.
7555 @item @emph{Standard}:
7556 Fortran 95 and later
7559 Transformational function
7561 @item @emph{Syntax}:
7562 @code{RESULT = MATMUL(MATRIX_A, MATRIX_B)}
7564 @item @emph{Arguments}:
7565 @multitable @columnfractions .15 .70
7566 @item @var{MATRIX_A} @tab An array of @code{INTEGER},
7567 @code{REAL}, @code{COMPLEX}, or @code{LOGICAL} type, with a rank of
7569 @item @var{MATRIX_B} @tab An array of @code{INTEGER},
7570 @code{REAL}, or @code{COMPLEX} type if @var{MATRIX_A} is of a numeric
7571 type; otherwise, an array of @code{LOGICAL} type. The rank shall be one
7572 or two, and the first (or only) dimension of @var{MATRIX_B} shall be
7573 equal to the last (or only) dimension of @var{MATRIX_A}.
7576 @item @emph{Return value}:
7577 The matrix product of @var{MATRIX_A} and @var{MATRIX_B}. The type and
7578 kind of the result follow the usual type and kind promotion rules, as
7579 for the @code{*} or @code{.AND.} operators.
7581 @item @emph{See also}:
7587 @section @code{MAX} --- Maximum value of an argument list
7594 @cindex maximum value
7597 @item @emph{Description}:
7598 Returns the argument with the largest (most positive) value.
7600 @item @emph{Standard}:
7601 Fortran 77 and later
7606 @item @emph{Syntax}:
7607 @code{RESULT = MAX(A1, A2 [, A3 [, ...]])}
7609 @item @emph{Arguments}:
7610 @multitable @columnfractions .15 .70
7611 @item @var{A1} @tab The type shall be @code{INTEGER} or
7613 @item @var{A2}, @var{A3}, ... @tab An expression of the same type and kind
7614 as @var{A1}. (As a GNU extension, arguments of different kinds are
7618 @item @emph{Return value}:
7619 The return value corresponds to the maximum value among the arguments,
7620 and has the same type and kind as the first argument.
7622 @item @emph{Specific names}:
7623 @multitable @columnfractions .20 .20 .20 .25
7624 @item Name @tab Argument @tab Return type @tab Standard
7625 @item @code{MAX0(A1)} @tab @code{INTEGER(4) A1} @tab @code{INTEGER(4)} @tab Fortran 77 and later
7626 @item @code{AMAX0(A1)} @tab @code{INTEGER(4) A1} @tab @code{REAL(MAX(X))} @tab Fortran 77 and later
7627 @item @code{MAX1(A1)} @tab @code{REAL A1} @tab @code{INT(MAX(X))} @tab Fortran 77 and later
7628 @item @code{AMAX1(A1)} @tab @code{REAL(4) A1} @tab @code{REAL(4)} @tab Fortran 77 and later
7629 @item @code{DMAX1(A1)} @tab @code{REAL(8) A1} @tab @code{REAL(8)} @tab Fortran 77 and later
7632 @item @emph{See also}:
7633 @ref{MAXLOC} @ref{MAXVAL}, @ref{MIN}
7640 @section @code{MAXEXPONENT} --- Maximum exponent of a real kind
7641 @fnindex MAXEXPONENT
7642 @cindex model representation, maximum exponent
7645 @item @emph{Description}:
7646 @code{MAXEXPONENT(X)} returns the maximum exponent in the model of the
7649 @item @emph{Standard}:
7650 Fortran 95 and later
7655 @item @emph{Syntax}:
7656 @code{RESULT = MAXEXPONENT(X)}
7658 @item @emph{Arguments}:
7659 @multitable @columnfractions .15 .70
7660 @item @var{X} @tab Shall be of type @code{REAL}.
7663 @item @emph{Return value}:
7664 The return value is of type @code{INTEGER} and of the default integer
7667 @item @emph{Example}:
7673 print *, minexponent(x), maxexponent(x)
7674 print *, minexponent(y), maxexponent(y)
7675 end program exponents
7682 @section @code{MAXLOC} --- Location of the maximum value within an array
7684 @cindex array, location of maximum element
7687 @item @emph{Description}:
7688 Determines the location of the element in the array with the maximum
7689 value, or, if the @var{DIM} argument is supplied, determines the
7690 locations of the maximum element along each row of the array in the
7691 @var{DIM} direction. If @var{MASK} is present, only the elements for
7692 which @var{MASK} is @code{.TRUE.} are considered. If more than one
7693 element in the array has the maximum value, the location returned is
7694 that of the first such element in array element order. If the array has
7695 zero size, or all of the elements of @var{MASK} are @code{.FALSE.}, then
7696 the result is an array of zeroes. Similarly, if @var{DIM} is supplied
7697 and all of the elements of @var{MASK} along a given row are zero, the
7698 result value for that row is zero.
7700 @item @emph{Standard}:
7701 Fortran 95 and later
7704 Transformational function
7706 @item @emph{Syntax}:
7707 @multitable @columnfractions .80
7708 @item @code{RESULT = MAXLOC(ARRAY, DIM [, MASK])}
7709 @item @code{RESULT = MAXLOC(ARRAY [, MASK])}
7712 @item @emph{Arguments}:
7713 @multitable @columnfractions .15 .70
7714 @item @var{ARRAY} @tab Shall be an array of type @code{INTEGER} or
7716 @item @var{DIM} @tab (Optional) Shall be a scalar of type
7717 @code{INTEGER}, with a value between one and the rank of @var{ARRAY},
7718 inclusive. It may not be an optional dummy argument.
7719 @item @var{MASK} @tab Shall be an array of type @code{LOGICAL},
7720 and conformable with @var{ARRAY}.
7723 @item @emph{Return value}:
7724 If @var{DIM} is absent, the result is a rank-one array with a length
7725 equal to the rank of @var{ARRAY}. If @var{DIM} is present, the result
7726 is an array with a rank one less than the rank of @var{ARRAY}, and a
7727 size corresponding to the size of @var{ARRAY} with the @var{DIM}
7728 dimension removed. If @var{DIM} is present and @var{ARRAY} has a rank
7729 of one, the result is a scalar. In all cases, the result is of default
7730 @code{INTEGER} type.
7732 @item @emph{See also}:
7733 @ref{MAX}, @ref{MAXVAL}
7740 @section @code{MAXVAL} --- Maximum value of an array
7742 @cindex array, maximum value
7743 @cindex maximum value
7746 @item @emph{Description}:
7747 Determines the maximum value of the elements in an array value, or, if
7748 the @var{DIM} argument is supplied, determines the maximum value along
7749 each row of the array in the @var{DIM} direction. If @var{MASK} is
7750 present, only the elements for which @var{MASK} is @code{.TRUE.} are
7751 considered. If the array has zero size, or all of the elements of
7752 @var{MASK} are @code{.FALSE.}, then the result is @code{-HUGE(ARRAY)}
7753 if @var{ARRAY} is numeric, or a string of nulls if @var{ARRAY} is of character
7756 @item @emph{Standard}:
7757 Fortran 95 and later
7760 Transformational function
7762 @item @emph{Syntax}:
7763 @multitable @columnfractions .80
7764 @item @code{RESULT = MAXVAL(ARRAY, DIM [, MASK])}
7765 @item @code{RESULT = MAXVAL(ARRAY [, MASK])}
7768 @item @emph{Arguments}:
7769 @multitable @columnfractions .15 .70
7770 @item @var{ARRAY} @tab Shall be an array of type @code{INTEGER} or
7772 @item @var{DIM} @tab (Optional) Shall be a scalar of type
7773 @code{INTEGER}, with a value between one and the rank of @var{ARRAY},
7774 inclusive. It may not be an optional dummy argument.
7775 @item @var{MASK} @tab Shall be an array of type @code{LOGICAL},
7776 and conformable with @var{ARRAY}.
7779 @item @emph{Return value}:
7780 If @var{DIM} is absent, or if @var{ARRAY} has a rank of one, the result
7781 is a scalar. If @var{DIM} is present, the result is an array with a
7782 rank one less than the rank of @var{ARRAY}, and a size corresponding to
7783 the size of @var{ARRAY} with the @var{DIM} dimension removed. In all
7784 cases, the result is of the same type and kind as @var{ARRAY}.
7786 @item @emph{See also}:
7787 @ref{MAX}, @ref{MAXLOC}
7793 @section @code{MCLOCK} --- Time function
7795 @cindex time, clock ticks
7799 @item @emph{Description}:
7800 Returns the number of clock ticks since the start of the process, based
7801 on the UNIX function @code{clock(3)}.
7803 This intrinsic is not fully portable, such as to systems with 32-bit
7804 @code{INTEGER} types but supporting times wider than 32 bits. Therefore,
7805 the values returned by this intrinsic might be, or become, negative, or
7806 numerically less than previous values, during a single run of the
7809 @item @emph{Standard}:
7815 @item @emph{Syntax}:
7816 @code{RESULT = MCLOCK()}
7818 @item @emph{Return value}:
7819 The return value is a scalar of type @code{INTEGER(4)}, equal to the
7820 number of clock ticks since the start of the process, or @code{-1} if
7821 the system does not support @code{clock(3)}.
7823 @item @emph{See also}:
7824 @ref{CTIME}, @ref{GMTIME}, @ref{LTIME}, @ref{MCLOCK}, @ref{TIME}
7831 @section @code{MCLOCK8} --- Time function (64-bit)
7833 @cindex time, clock ticks
7837 @item @emph{Description}:
7838 Returns the number of clock ticks since the start of the process, based
7839 on the UNIX function @code{clock(3)}.
7841 @emph{Warning:} this intrinsic does not increase the range of the timing
7842 values over that returned by @code{clock(3)}. On a system with a 32-bit
7843 @code{clock(3)}, @code{MCLOCK8()} will return a 32-bit value, even though
7844 it is converted to a 64-bit @code{INTEGER(8)} value. That means
7845 overflows of the 32-bit value can still occur. Therefore, the values
7846 returned by this intrinsic might be or become negative or numerically
7847 less than previous values during a single run of the compiled program.
7849 @item @emph{Standard}:
7855 @item @emph{Syntax}:
7856 @code{RESULT = MCLOCK8()}
7858 @item @emph{Return value}:
7859 The return value is a scalar of type @code{INTEGER(8)}, equal to the
7860 number of clock ticks since the start of the process, or @code{-1} if
7861 the system does not support @code{clock(3)}.
7863 @item @emph{See also}:
7864 @ref{CTIME}, @ref{GMTIME}, @ref{LTIME}, @ref{MCLOCK}, @ref{TIME8}
7871 @section @code{MERGE} --- Merge variables
7873 @cindex array, merge arrays
7874 @cindex array, combine arrays
7877 @item @emph{Description}:
7878 Select values from two arrays according to a logical mask. The result
7879 is equal to @var{TSOURCE} if @var{MASK} is @code{.TRUE.}, or equal to
7880 @var{FSOURCE} if it is @code{.FALSE.}.
7882 @item @emph{Standard}:
7883 Fortran 95 and later
7888 @item @emph{Syntax}:
7889 @code{RESULT = MERGE(TSOURCE, FSOURCE, MASK)}
7891 @item @emph{Arguments}:
7892 @multitable @columnfractions .15 .70
7893 @item @var{TSOURCE} @tab May be of any type.
7894 @item @var{FSOURCE} @tab Shall be of the same type and type parameters
7896 @item @var{MASK} @tab Shall be of type @code{LOGICAL}.
7899 @item @emph{Return value}:
7900 The result is of the same type and type parameters as @var{TSOURCE}.
7907 @section @code{MIN} --- Minimum value of an argument list
7914 @cindex minimum value
7917 @item @emph{Description}:
7918 Returns the argument with the smallest (most negative) value.
7920 @item @emph{Standard}:
7921 Fortran 77 and later
7926 @item @emph{Syntax}:
7927 @code{RESULT = MIN(A1, A2 [, A3, ...])}
7929 @item @emph{Arguments}:
7930 @multitable @columnfractions .15 .70
7931 @item @var{A1} @tab The type shall be @code{INTEGER} or
7933 @item @var{A2}, @var{A3}, ... @tab An expression of the same type and kind
7934 as @var{A1}. (As a GNU extension, arguments of different kinds are
7938 @item @emph{Return value}:
7939 The return value corresponds to the maximum value among the arguments,
7940 and has the same type and kind as the first argument.
7942 @item @emph{Specific names}:
7943 @multitable @columnfractions .20 .20 .20 .25
7944 @item Name @tab Argument @tab Return type @tab Standard
7945 @item @code{MIN0(A1)} @tab @code{INTEGER(4) A1} @tab @code{INTEGER(4)} @tab Fortran 77 and later
7946 @item @code{AMIN0(A1)} @tab @code{INTEGER(4) A1} @tab @code{REAL(4)} @tab Fortran 77 and later
7947 @item @code{MIN1(A1)} @tab @code{REAL A1} @tab @code{INTEGER(4)} @tab Fortran 77 and later
7948 @item @code{AMIN1(A1)} @tab @code{REAL(4) A1} @tab @code{REAL(4)} @tab Fortran 77 and later
7949 @item @code{DMIN1(A1)} @tab @code{REAL(8) A1} @tab @code{REAL(8)} @tab Fortran 77 and later
7952 @item @emph{See also}:
7953 @ref{MAX}, @ref{MINLOC}, @ref{MINVAL}
7959 @section @code{MINEXPONENT} --- Minimum exponent of a real kind
7960 @fnindex MINEXPONENT
7961 @cindex model representation, minimum exponent
7964 @item @emph{Description}:
7965 @code{MINEXPONENT(X)} returns the minimum exponent in the model of the
7968 @item @emph{Standard}:
7969 Fortran 95 and later
7974 @item @emph{Syntax}:
7975 @code{RESULT = MINEXPONENT(X)}
7977 @item @emph{Arguments}:
7978 @multitable @columnfractions .15 .70
7979 @item @var{X} @tab Shall be of type @code{REAL}.
7982 @item @emph{Return value}:
7983 The return value is of type @code{INTEGER} and of the default integer
7986 @item @emph{Example}:
7987 See @code{MAXEXPONENT} for an example.
7993 @section @code{MINLOC} --- Location of the minimum value within an array
7995 @cindex array, location of minimum element
7998 @item @emph{Description}:
7999 Determines the location of the element in the array with the minimum
8000 value, or, if the @var{DIM} argument is supplied, determines the
8001 locations of the minimum element along each row of the array in the
8002 @var{DIM} direction. If @var{MASK} is present, only the elements for
8003 which @var{MASK} is @code{.TRUE.} are considered. If more than one
8004 element in the array has the minimum value, the location returned is
8005 that of the first such element in array element order. If the array has
8006 zero size, or all of the elements of @var{MASK} are @code{.FALSE.}, then
8007 the result is an array of zeroes. Similarly, if @var{DIM} is supplied
8008 and all of the elements of @var{MASK} along a given row are zero, the
8009 result value for that row is zero.
8011 @item @emph{Standard}:
8012 Fortran 95 and later
8015 Transformational function
8017 @item @emph{Syntax}:
8018 @multitable @columnfractions .80
8019 @item @code{RESULT = MINLOC(ARRAY, DIM [, MASK])}
8020 @item @code{RESULT = MINLOC(ARRAY [, MASK])}
8023 @item @emph{Arguments}:
8024 @multitable @columnfractions .15 .70
8025 @item @var{ARRAY} @tab Shall be an array of type @code{INTEGER} or
8027 @item @var{DIM} @tab (Optional) Shall be a scalar of type
8028 @code{INTEGER}, with a value between one and the rank of @var{ARRAY},
8029 inclusive. It may not be an optional dummy argument.
8030 @item @var{MASK} @tab Shall be an array of type @code{LOGICAL},
8031 and conformable with @var{ARRAY}.
8034 @item @emph{Return value}:
8035 If @var{DIM} is absent, the result is a rank-one array with a length
8036 equal to the rank of @var{ARRAY}. If @var{DIM} is present, the result
8037 is an array with a rank one less than the rank of @var{ARRAY}, and a
8038 size corresponding to the size of @var{ARRAY} with the @var{DIM}
8039 dimension removed. If @var{DIM} is present and @var{ARRAY} has a rank
8040 of one, the result is a scalar. In all cases, the result is of default
8041 @code{INTEGER} type.
8043 @item @emph{See also}:
8044 @ref{MIN}, @ref{MINVAL}
8051 @section @code{MINVAL} --- Minimum value of an array
8053 @cindex array, minimum value
8054 @cindex minimum value
8057 @item @emph{Description}:
8058 Determines the minimum value of the elements in an array value, or, if
8059 the @var{DIM} argument is supplied, determines the minimum value along
8060 each row of the array in the @var{DIM} direction. If @var{MASK} is
8061 present, only the elements for which @var{MASK} is @code{.TRUE.} are
8062 considered. If the array has zero size, or all of the elements of
8063 @var{MASK} are @code{.FALSE.}, then the result is @code{HUGE(ARRAY)} if
8064 @var{ARRAY} is numeric, or a string of @code{CHAR(255)} characters if
8065 @var{ARRAY} is of character type.
8067 @item @emph{Standard}:
8068 Fortran 95 and later
8071 Transformational function
8073 @item @emph{Syntax}:
8074 @multitable @columnfractions .80
8075 @item @code{RESULT = MINVAL(ARRAY, DIM [, MASK])}
8076 @item @code{RESULT = MINVAL(ARRAY [, MASK])}
8079 @item @emph{Arguments}:
8080 @multitable @columnfractions .15 .70
8081 @item @var{ARRAY} @tab Shall be an array of type @code{INTEGER} or
8083 @item @var{DIM} @tab (Optional) Shall be a scalar of type
8084 @code{INTEGER}, with a value between one and the rank of @var{ARRAY},
8085 inclusive. It may not be an optional dummy argument.
8086 @item @var{MASK} @tab Shall be an array of type @code{LOGICAL},
8087 and conformable with @var{ARRAY}.
8090 @item @emph{Return value}:
8091 If @var{DIM} is absent, or if @var{ARRAY} has a rank of one, the result
8092 is a scalar. If @var{DIM} is present, the result is an array with a
8093 rank one less than the rank of @var{ARRAY}, and a size corresponding to
8094 the size of @var{ARRAY} with the @var{DIM} dimension removed. In all
8095 cases, the result is of the same type and kind as @var{ARRAY}.
8097 @item @emph{See also}:
8098 @ref{MIN}, @ref{MINLOC}
8105 @section @code{MOD} --- Remainder function
8110 @cindex division, remainder
8113 @item @emph{Description}:
8114 @code{MOD(A,P)} computes the remainder of the division of A by P@. It is
8115 calculated as @code{A - (INT(A/P) * P)}.
8117 @item @emph{Standard}:
8118 Fortran 77 and later
8123 @item @emph{Syntax}:
8124 @code{RESULT = MOD(A, P)}
8126 @item @emph{Arguments}:
8127 @multitable @columnfractions .15 .70
8128 @item @var{A} @tab Shall be a scalar of type @code{INTEGER} or @code{REAL}
8129 @item @var{P} @tab Shall be a scalar of the same type as @var{A} and not
8133 @item @emph{Return value}:
8134 The kind of the return value is the result of cross-promoting
8135 the kinds of the arguments.
8137 @item @emph{Example}:
8141 print *, mod(17.5,5.5)
8142 print *, mod(17.5d0,5.5)
8143 print *, mod(17.5,5.5d0)
8146 print *, mod(-17.5,5.5)
8147 print *, mod(-17.5d0,5.5)
8148 print *, mod(-17.5,5.5d0)
8151 print *, mod(17.5,-5.5)
8152 print *, mod(17.5d0,-5.5)
8153 print *, mod(17.5,-5.5d0)
8154 end program test_mod
8157 @item @emph{Specific names}:
8158 @multitable @columnfractions .20 .20 .20 .25
8159 @item Name @tab Arguments @tab Return type @tab Standard
8160 @item @code{MOD(A,P)} @tab @code{INTEGER A,P} @tab @code{INTEGER} @tab Fortran 95 and later
8161 @item @code{AMOD(A,P)} @tab @code{REAL(4) A,P} @tab @code{REAL(4)} @tab Fortran 95 and later
8162 @item @code{DMOD(A,P)} @tab @code{REAL(8) A,P} @tab @code{REAL(8)} @tab Fortran 95 and later
8169 @section @code{MODULO} --- Modulo function
8172 @cindex division, modulo
8175 @item @emph{Description}:
8176 @code{MODULO(A,P)} computes the @var{A} modulo @var{P}.
8178 @item @emph{Standard}:
8179 Fortran 95 and later
8184 @item @emph{Syntax}:
8185 @code{RESULT = MODULO(A, P)}
8187 @item @emph{Arguments}:
8188 @multitable @columnfractions .15 .70
8189 @item @var{A} @tab Shall be a scalar of type @code{INTEGER} or @code{REAL}
8190 @item @var{P} @tab Shall be a scalar of the same type and kind as @var{A}
8193 @item @emph{Return value}:
8194 The type and kind of the result are those of the arguments.
8196 @item If @var{A} and @var{P} are of type @code{INTEGER}:
8197 @code{MODULO(A,P)} has the value @var{R} such that @code{A=Q*P+R}, where
8198 @var{Q} is an integer and @var{R} is between 0 (inclusive) and @var{P}
8200 @item If @var{A} and @var{P} are of type @code{REAL}:
8201 @code{MODULO(A,P)} has the value of @code{A - FLOOR (A / P) * P}.
8203 In all cases, if @var{P} is zero the result is processor-dependent.
8205 @item @emph{Example}:
8208 print *, modulo(17,3)
8209 print *, modulo(17.5,5.5)
8211 print *, modulo(-17,3)
8212 print *, modulo(-17.5,5.5)
8214 print *, modulo(17,-3)
8215 print *, modulo(17.5,-5.5)
8224 @section @code{MOVE_ALLOC} --- Move allocation from one object to another
8226 @cindex moving allocation
8227 @cindex allocation, moving
8230 @item @emph{Description}:
8231 @code{MOVE_ALLOC(FROM, TO)} moves the allocation from @var{FROM} to
8232 @var{TO}. @var{FROM} will become deallocated in the process.
8234 @item @emph{Standard}:
8235 Fortran 2003 and later
8240 @item @emph{Syntax}:
8241 @code{CALL MOVE_ALLOC(FROM, TO)}
8243 @item @emph{Arguments}:
8244 @multitable @columnfractions .15 .70
8245 @item @var{FROM} @tab @code{ALLOCATABLE}, @code{INTENT(INOUT)}, may be
8246 of any type and kind.
8247 @item @var{TO} @tab @code{ALLOCATABLE}, @code{INTENT(OUT)}, shall be
8248 of the same type, kind and rank as @var{FROM}.
8251 @item @emph{Return value}:
8254 @item @emph{Example}:
8256 program test_move_alloc
8257 integer, allocatable :: a(:), b(:)
8261 call move_alloc(a, b)
8262 print *, allocated(a), allocated(b)
8264 end program test_move_alloc
8271 @section @code{MVBITS} --- Move bits from one integer to another
8276 @item @emph{Description}:
8277 Moves @var{LEN} bits from positions @var{FROMPOS} through
8278 @code{FROMPOS+LEN-1} of @var{FROM} to positions @var{TOPOS} through
8279 @code{TOPOS+LEN-1} of @var{TO}. The portion of argument @var{TO} not
8280 affected by the movement of bits is unchanged. The values of
8281 @code{FROMPOS+LEN-1} and @code{TOPOS+LEN-1} must be less than
8282 @code{BIT_SIZE(FROM)}.
8284 @item @emph{Standard}:
8285 Fortran 95 and later
8288 Elemental subroutine
8290 @item @emph{Syntax}:
8291 @code{CALL MVBITS(FROM, FROMPOS, LEN, TO, TOPOS)}
8293 @item @emph{Arguments}:
8294 @multitable @columnfractions .15 .70
8295 @item @var{FROM} @tab The type shall be @code{INTEGER}.
8296 @item @var{FROMPOS} @tab The type shall be @code{INTEGER}.
8297 @item @var{LEN} @tab The type shall be @code{INTEGER}.
8298 @item @var{TO} @tab The type shall be @code{INTEGER}, of the
8299 same kind as @var{FROM}.
8300 @item @var{TOPOS} @tab The type shall be @code{INTEGER}.
8303 @item @emph{See also}:
8304 @ref{IBCLR}, @ref{IBSET}, @ref{IBITS}, @ref{IAND}, @ref{IOR}, @ref{IEOR}
8310 @section @code{NEAREST} --- Nearest representable number
8312 @cindex real number, nearest different
8313 @cindex floating point, nearest different
8316 @item @emph{Description}:
8317 @code{NEAREST(X, S)} returns the processor-representable number nearest
8318 to @code{X} in the direction indicated by the sign of @code{S}.
8320 @item @emph{Standard}:
8321 Fortran 95 and later
8326 @item @emph{Syntax}:
8327 @code{RESULT = NEAREST(X, S)}
8329 @item @emph{Arguments}:
8330 @multitable @columnfractions .15 .70
8331 @item @var{X} @tab Shall be of type @code{REAL}.
8332 @item @var{S} @tab (Optional) shall be of type @code{REAL} and
8336 @item @emph{Return value}:
8337 The return value is of the same type as @code{X}. If @code{S} is
8338 positive, @code{NEAREST} returns the processor-representable number
8339 greater than @code{X} and nearest to it. If @code{S} is negative,
8340 @code{NEAREST} returns the processor-representable number smaller than
8341 @code{X} and nearest to it.
8343 @item @emph{Example}:
8345 program test_nearest
8347 x = nearest(42.0, 1.0)
8348 y = nearest(42.0, -1.0)
8349 write (*,"(3(G20.15))") x, y, x - y
8350 end program test_nearest
8357 @section @code{NEW_LINE} --- New line character
8360 @cindex output, newline
8363 @item @emph{Description}:
8364 @code{NEW_LINE(C)} returns the new-line character.
8366 @item @emph{Standard}:
8367 Fortran 2003 and later
8372 @item @emph{Syntax}:
8373 @code{RESULT = NEW_LINE(C)}
8375 @item @emph{Arguments}:
8376 @multitable @columnfractions .15 .70
8377 @item @var{C} @tab The argument shall be a scalar or array of the
8378 type @code{CHARACTER}.
8381 @item @emph{Return value}:
8382 Returns a @var{CHARACTER} scalar of length one with the new-line character of
8383 the same kind as parameter @var{C}.
8385 @item @emph{Example}:
8389 write(*,'(A)') 'This is record 1.'//NEW_LINE('A')//'This is record 2.'
8397 @section @code{NINT} --- Nearest whole number
8400 @cindex rounding, nearest whole number
8403 @item @emph{Description}:
8404 @code{NINT(A)} rounds its argument to the nearest whole number.
8406 @item @emph{Standard}:
8407 Fortran 77 and later, with @var{KIND} argument Fortran 90 and later
8412 @item @emph{Syntax}:
8413 @code{RESULT = NINT(A [, KIND])}
8415 @item @emph{Arguments}:
8416 @multitable @columnfractions .15 .70
8417 @item @var{A} @tab The type of the argument shall be @code{REAL}.
8418 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
8419 expression indicating the kind parameter of the result.
8422 @item @emph{Return value}:
8423 Returns @var{A} with the fractional portion of its magnitude eliminated by
8424 rounding to the nearest whole number and with its sign preserved,
8425 converted to an @code{INTEGER} of the default kind.
8427 @item @emph{Example}:
8434 print *, nint(x4), idnint(x8)
8435 end program test_nint
8438 @item @emph{Specific names}:
8439 @multitable @columnfractions .20 .20 .20 .25
8440 @item Name @tab Argument @tab Return Type @tab Standard
8441 @item @code{NINT(A)} @tab @code{REAL(4) A} @tab @code{INTEGER} @tab Fortran 95 and later
8442 @item @code{IDNINT(A)} @tab @code{REAL(8) A} @tab @code{INTEGER} @tab Fortran 95 and later
8445 @item @emph{See also}:
8446 @ref{CEILING}, @ref{FLOOR}
8453 @section @code{NOT} --- Logical negation
8455 @cindex bits, negate
8456 @cindex bitwise logical not
8457 @cindex logical not, bitwise
8460 @item @emph{Description}:
8461 @code{NOT} returns the bitwise boolean inverse of @var{I}.
8463 @item @emph{Standard}:
8464 Fortran 95 and later
8469 @item @emph{Syntax}:
8470 @code{RESULT = NOT(I)}
8472 @item @emph{Arguments}:
8473 @multitable @columnfractions .15 .70
8474 @item @var{I} @tab The type shall be @code{INTEGER}.
8477 @item @emph{Return value}:
8478 The return type is @code{INTEGER}, of the same kind as the
8481 @item @emph{See also}:
8482 @ref{IAND}, @ref{IEOR}, @ref{IOR}, @ref{IBITS}, @ref{IBSET}, @ref{IBCLR}
8489 @section @code{NULL} --- Function that returns an disassociated pointer
8491 @cindex pointer, status
8492 @cindex pointer, disassociated
8495 @item @emph{Description}:
8496 Returns a disassociated pointer.
8498 If @var{MOLD} is present, a dissassociated pointer of the same type is
8499 returned, otherwise the type is determined by context.
8501 In Fortran 95, @var{MOLD} is optional. Please note that Fortran 2003
8502 includes cases where it is required.
8504 @item @emph{Standard}:
8505 Fortran 95 and later
8508 Transformational function
8510 @item @emph{Syntax}:
8511 @code{PTR => NULL([MOLD])}
8513 @item @emph{Arguments}:
8514 @multitable @columnfractions .15 .70
8515 @item @var{MOLD} @tab (Optional) shall be a pointer of any association
8516 status and of any type.
8519 @item @emph{Return value}:
8520 A disassociated pointer.
8522 @item @emph{Example}:
8524 REAL, POINTER, DIMENSION(:) :: VEC => NULL ()
8527 @item @emph{See also}:
8534 @section @code{NUM_IMAGES} --- Function that returns the number of images
8536 @cindex coarray, NUM_IMAGES
8537 @cindex images, number of
8540 @item @emph{Description}:
8541 Returns the number of images.
8543 @item @emph{Standard}:
8544 Fortran 2008 and later
8547 Transformational function
8549 @item @emph{Syntax}:
8550 @code{RESULT = NUM_IMAGES()}
8552 @item @emph{Arguments}: None.
8554 @item @emph{Return value}:
8555 Scalar default-kind integer.
8557 @item @emph{Example}:
8561 value = THIS_IMAGE()
8563 IF (THIS_IMAGE() == 1) THEN
8564 DO i = 1, NUM_IMAGES()
8565 WRITE(*,'(2(a,i0))') 'value[', i, '] is ', value[i]
8570 @item @emph{See also}:
8571 @ref{THIS_IMAGE}, @ref{IMAGE_INDEX}
8577 @section @code{OR} --- Bitwise logical OR
8579 @cindex bitwise logical or
8580 @cindex logical or, bitwise
8583 @item @emph{Description}:
8584 Bitwise logical @code{OR}.
8586 This intrinsic routine is provided for backwards compatibility with
8587 GNU Fortran 77. For integer arguments, programmers should consider
8588 the use of the @ref{IOR} intrinsic defined by the Fortran standard.
8590 @item @emph{Standard}:
8596 @item @emph{Syntax}:
8597 @code{RESULT = OR(I, J)}
8599 @item @emph{Arguments}:
8600 @multitable @columnfractions .15 .70
8601 @item @var{I} @tab The type shall be either a scalar @code{INTEGER}
8602 type or a scalar @code{LOGICAL} type.
8603 @item @var{J} @tab The type shall be the same as the type of @var{J}.
8606 @item @emph{Return value}:
8607 The return type is either a scalar @code{INTEGER} or a scalar
8608 @code{LOGICAL}. If the kind type parameters differ, then the
8609 smaller kind type is implicitly converted to larger kind, and the
8610 return has the larger kind.
8612 @item @emph{Example}:
8615 LOGICAL :: T = .TRUE., F = .FALSE.
8617 DATA a / Z'F' /, b / Z'3' /
8619 WRITE (*,*) OR(T, T), OR(T, F), OR(F, T), OR(F, F)
8620 WRITE (*,*) OR(a, b)
8624 @item @emph{See also}:
8625 Fortran 95 elemental function: @ref{IOR}
8631 @section @code{PACK} --- Pack an array into an array of rank one
8633 @cindex array, packing
8634 @cindex array, reduce dimension
8635 @cindex array, gather elements
8638 @item @emph{Description}:
8639 Stores the elements of @var{ARRAY} in an array of rank one.
8641 The beginning of the resulting array is made up of elements whose @var{MASK}
8642 equals @code{TRUE}. Afterwards, positions are filled with elements taken from
8645 @item @emph{Standard}:
8646 Fortran 95 and later
8649 Transformational function
8651 @item @emph{Syntax}:
8652 @code{RESULT = PACK(ARRAY, MASK[,VECTOR]}
8654 @item @emph{Arguments}:
8655 @multitable @columnfractions .15 .70
8656 @item @var{ARRAY} @tab Shall be an array of any type.
8657 @item @var{MASK} @tab Shall be an array of type @code{LOGICAL} and
8658 of the same size as @var{ARRAY}. Alternatively, it may be a @code{LOGICAL}
8660 @item @var{VECTOR} @tab (Optional) shall be an array of the same type
8661 as @var{ARRAY} and of rank one. If present, the number of elements in
8662 @var{VECTOR} shall be equal to or greater than the number of true elements
8663 in @var{MASK}. If @var{MASK} is scalar, the number of elements in
8664 @var{VECTOR} shall be equal to or greater than the number of elements in
8668 @item @emph{Return value}:
8669 The result is an array of rank one and the same type as that of @var{ARRAY}.
8670 If @var{VECTOR} is present, the result size is that of @var{VECTOR}, the
8671 number of @code{TRUE} values in @var{MASK} otherwise.
8673 @item @emph{Example}:
8674 Gathering nonzero elements from an array:
8678 m = (/ 1, 0, 0, 0, 5, 0 /)
8679 WRITE(*, FMT="(6(I0, ' '))") pack(m, m /= 0) ! "1 5"
8683 Gathering nonzero elements from an array and appending elements from @var{VECTOR}:
8687 m = (/ 1, 0, 0, 2 /)
8688 WRITE(*, FMT="(4(I0, ' '))") pack(m, m /= 0, (/ 0, 0, 3, 4 /)) ! "1 2 3 4"
8692 @item @emph{See also}:
8699 @section @code{PERROR} --- Print system error message
8701 @cindex system, error handling
8704 @item @emph{Description}:
8705 Prints (on the C @code{stderr} stream) a newline-terminated error
8706 message corresponding to the last system error. This is prefixed by
8707 @var{STRING}, a colon and a space. See @code{perror(3)}.
8709 @item @emph{Standard}:
8715 @item @emph{Syntax}:
8716 @code{CALL PERROR(STRING)}
8718 @item @emph{Arguments}:
8719 @multitable @columnfractions .15 .70
8720 @item @var{STRING} @tab A scalar of type @code{CHARACTER} and of the
8724 @item @emph{See also}:
8731 @section @code{PRECISION} --- Decimal precision of a real kind
8733 @cindex model representation, precision
8736 @item @emph{Description}:
8737 @code{PRECISION(X)} returns the decimal precision in the model of the
8740 @item @emph{Standard}:
8741 Fortran 95 and later
8746 @item @emph{Syntax}:
8747 @code{RESULT = PRECISION(X)}
8749 @item @emph{Arguments}:
8750 @multitable @columnfractions .15 .70
8751 @item @var{X} @tab Shall be of type @code{REAL} or @code{COMPLEX}.
8754 @item @emph{Return value}:
8755 The return value is of type @code{INTEGER} and of the default integer
8758 @item @emph{See also}:
8759 @ref{SELECTED_REAL_KIND}, @ref{RANGE}
8761 @item @emph{Example}:
8763 program prec_and_range
8764 real(kind=4) :: x(2)
8765 complex(kind=8) :: y
8767 print *, precision(x), range(x)
8768 print *, precision(y), range(y)
8769 end program prec_and_range
8776 @section @code{PRESENT} --- Determine whether an optional dummy argument is specified
8780 @item @emph{Description}:
8781 Determines whether an optional dummy argument is present.
8783 @item @emph{Standard}:
8784 Fortran 95 and later
8789 @item @emph{Syntax}:
8790 @code{RESULT = PRESENT(A)}
8792 @item @emph{Arguments}:
8793 @multitable @columnfractions .15 .70
8794 @item @var{A} @tab May be of any type and may be a pointer, scalar or array
8795 value, or a dummy procedure. It shall be the name of an optional dummy argument
8796 accessible within the current subroutine or function.
8799 @item @emph{Return value}:
8800 Returns either @code{TRUE} if the optional argument @var{A} is present, or
8801 @code{FALSE} otherwise.
8803 @item @emph{Example}:
8805 PROGRAM test_present
8806 WRITE(*,*) f(), f(42) ! "F T"
8808 LOGICAL FUNCTION f(x)
8809 INTEGER, INTENT(IN), OPTIONAL :: x
8819 @section @code{PRODUCT} --- Product of array elements
8821 @cindex array, product
8822 @cindex array, multiply elements
8823 @cindex array, conditionally multiply elements
8824 @cindex multiply array elements
8827 @item @emph{Description}:
8828 Multiplies the elements of @var{ARRAY} along dimension @var{DIM} if
8829 the corresponding element in @var{MASK} is @code{TRUE}.
8831 @item @emph{Standard}:
8832 Fortran 95 and later
8835 Transformational function
8837 @item @emph{Syntax}:
8838 @multitable @columnfractions .80
8839 @item @code{RESULT = PRODUCT(ARRAY[, MASK])}
8840 @item @code{RESULT = PRODUCT(ARRAY, DIM[, MASK])}
8843 @item @emph{Arguments}:
8844 @multitable @columnfractions .15 .70
8845 @item @var{ARRAY} @tab Shall be an array of type @code{INTEGER},
8846 @code{REAL} or @code{COMPLEX}.
8847 @item @var{DIM} @tab (Optional) shall be a scalar of type
8848 @code{INTEGER} with a value in the range from 1 to n, where n
8849 equals the rank of @var{ARRAY}.
8850 @item @var{MASK} @tab (Optional) shall be of type @code{LOGICAL}
8851 and either be a scalar or an array of the same shape as @var{ARRAY}.
8854 @item @emph{Return value}:
8855 The result is of the same type as @var{ARRAY}.
8857 If @var{DIM} is absent, a scalar with the product of all elements in
8858 @var{ARRAY} is returned. Otherwise, an array of rank n-1, where n equals
8859 the rank of @var{ARRAY}, and a shape similar to that of @var{ARRAY} with
8860 dimension @var{DIM} dropped is returned.
8863 @item @emph{Example}:
8865 PROGRAM test_product
8866 INTEGER :: x(5) = (/ 1, 2, 3, 4 ,5 /)
8867 print *, PRODUCT(x) ! all elements, product = 120
8868 print *, PRODUCT(x, MASK=MOD(x, 2)==1) ! odd elements, product = 15
8872 @item @emph{See also}:
8879 @section @code{RADIX} --- Base of a model number
8881 @cindex model representation, base
8882 @cindex model representation, radix
8885 @item @emph{Description}:
8886 @code{RADIX(X)} returns the base of the model representing the entity @var{X}.
8888 @item @emph{Standard}:
8889 Fortran 95 and later
8894 @item @emph{Syntax}:
8895 @code{RESULT = RADIX(X)}
8897 @item @emph{Arguments}:
8898 @multitable @columnfractions .15 .70
8899 @item @var{X} @tab Shall be of type @code{INTEGER} or @code{REAL}
8902 @item @emph{Return value}:
8903 The return value is a scalar of type @code{INTEGER} and of the default
8906 @item @emph{See also}:
8907 @ref{SELECTED_REAL_KIND}
8909 @item @emph{Example}:
8912 print *, "The radix for the default integer kind is", radix(0)
8913 print *, "The radix for the default real kind is", radix(0.0)
8914 end program test_radix
8922 @section @code{RAN} --- Real pseudo-random number
8924 @cindex random number generation
8927 @item @emph{Description}:
8928 For compatibility with HP FORTRAN 77/iX, the @code{RAN} intrinsic is
8929 provided as an alias for @code{RAND}. See @ref{RAND} for complete
8932 @item @emph{Standard}:
8938 @item @emph{See also}:
8939 @ref{RAND}, @ref{RANDOM_NUMBER}
8945 @section @code{RAND} --- Real pseudo-random number
8947 @cindex random number generation
8950 @item @emph{Description}:
8951 @code{RAND(FLAG)} returns a pseudo-random number from a uniform
8952 distribution between 0 and 1. If @var{FLAG} is 0, the next number
8953 in the current sequence is returned; if @var{FLAG} is 1, the generator
8954 is restarted by @code{CALL SRAND(0)}; if @var{FLAG} has any other value,
8955 it is used as a new seed with @code{SRAND}.
8957 This intrinsic routine is provided for backwards compatibility with
8958 GNU Fortran 77. It implements a simple modulo generator as provided
8959 by @command{g77}. For new code, one should consider the use of
8960 @ref{RANDOM_NUMBER} as it implements a superior algorithm.
8962 @item @emph{Standard}:
8968 @item @emph{Syntax}:
8969 @code{RESULT = RAND(I)}
8971 @item @emph{Arguments}:
8972 @multitable @columnfractions .15 .70
8973 @item @var{I} @tab Shall be a scalar @code{INTEGER} of kind 4.
8976 @item @emph{Return value}:
8977 The return value is of @code{REAL} type and the default kind.
8979 @item @emph{Example}:
8982 integer,parameter :: seed = 86456
8985 print *, rand(), rand(), rand(), rand()
8986 print *, rand(seed), rand(), rand(), rand()
8987 end program test_rand
8990 @item @emph{See also}:
8991 @ref{SRAND}, @ref{RANDOM_NUMBER}
8998 @section @code{RANDOM_NUMBER} --- Pseudo-random number
8999 @fnindex RANDOM_NUMBER
9000 @cindex random number generation
9003 @item @emph{Description}:
9004 Returns a single pseudorandom number or an array of pseudorandom numbers
9005 from the uniform distribution over the range @math{ 0 \leq x < 1}.
9007 The runtime-library implements George Marsaglia's KISS (Keep It Simple
9008 Stupid) random number generator (RNG). This RNG combines:
9010 @item The congruential generator @math{x(n) = 69069 \cdot x(n-1) + 1327217885}
9011 with a period of @math{2^{32}},
9012 @item A 3-shift shift-register generator with a period of @math{2^{32} - 1},
9013 @item Two 16-bit multiply-with-carry generators with a period of
9014 @math{597273182964842497 > 2^{59}}.
9016 The overall period exceeds @math{2^{123}}.
9018 Please note, this RNG is thread safe if used within OpenMP directives,
9019 i.e., its state will be consistent while called from multiple threads.
9020 However, the KISS generator does not create random numbers in parallel
9021 from multiple sources, but in sequence from a single source. If an
9022 OpenMP-enabled application heavily relies on random numbers, one should
9023 consider employing a dedicated parallel random number generator instead.
9025 @item @emph{Standard}:
9026 Fortran 95 and later
9031 @item @emph{Syntax}:
9032 @code{RANDOM_NUMBER(HARVEST)}
9034 @item @emph{Arguments}:
9035 @multitable @columnfractions .15 .70
9036 @item @var{HARVEST} @tab Shall be a scalar or an array of type @code{REAL}.
9039 @item @emph{Example}:
9041 program test_random_number
9043 CALL init_random_seed() ! see example of RANDOM_SEED
9044 CALL RANDOM_NUMBER(r)
9048 @item @emph{See also}:
9055 @section @code{RANDOM_SEED} --- Initialize a pseudo-random number sequence
9056 @fnindex RANDOM_SEED
9057 @cindex random number generation, seeding
9058 @cindex seeding a random number generator
9061 @item @emph{Description}:
9062 Restarts or queries the state of the pseudorandom number generator used by
9063 @code{RANDOM_NUMBER}.
9065 If @code{RANDOM_SEED} is called without arguments, it is initialized to
9066 a default state. The example below shows how to initialize the random
9067 seed based on the system's time.
9069 @item @emph{Standard}:
9070 Fortran 95 and later
9075 @item @emph{Syntax}:
9076 @code{CALL RANDOM_SEED([SIZE, PUT, GET])}
9078 @item @emph{Arguments}:
9079 @multitable @columnfractions .15 .70
9080 @item @var{SIZE} @tab (Optional) Shall be a scalar and of type default
9081 @code{INTEGER}, with @code{INTENT(OUT)}. It specifies the minimum size
9082 of the arrays used with the @var{PUT} and @var{GET} arguments.
9083 @item @var{PUT} @tab (Optional) Shall be an array of type default
9084 @code{INTEGER} and rank one. It is @code{INTENT(IN)} and the size of
9085 the array must be larger than or equal to the number returned by the
9086 @var{SIZE} argument.
9087 @item @var{GET} @tab (Optional) Shall be an array of type default
9088 @code{INTEGER} and rank one. It is @code{INTENT(OUT)} and the size
9089 of the array must be larger than or equal to the number returned by
9090 the @var{SIZE} argument.
9093 @item @emph{Example}:
9095 SUBROUTINE init_random_seed()
9096 INTEGER :: i, n, clock
9097 INTEGER, DIMENSION(:), ALLOCATABLE :: seed
9099 CALL RANDOM_SEED(size = n)
9102 CALL SYSTEM_CLOCK(COUNT=clock)
9104 seed = clock + 37 * (/ (i - 1, i = 1, n) /)
9105 CALL RANDOM_SEED(PUT = seed)
9111 @item @emph{See also}:
9118 @section @code{RANGE} --- Decimal exponent range
9120 @cindex model representation, range
9123 @item @emph{Description}:
9124 @code{RANGE(X)} returns the decimal exponent range in the model of the
9127 @item @emph{Standard}:
9128 Fortran 95 and later
9133 @item @emph{Syntax}:
9134 @code{RESULT = RANGE(X)}
9136 @item @emph{Arguments}:
9137 @multitable @columnfractions .15 .70
9138 @item @var{X} @tab Shall be of type @code{INTEGER}, @code{REAL}
9142 @item @emph{Return value}:
9143 The return value is of type @code{INTEGER} and of the default integer
9146 @item @emph{See also}:
9147 @ref{SELECTED_REAL_KIND}, @ref{PRECISION}
9149 @item @emph{Example}:
9150 See @code{PRECISION} for an example.
9156 @section @code{REAL} --- Convert to real type
9162 @cindex conversion, to real
9163 @cindex complex numbers, real part
9166 @item @emph{Description}:
9167 @code{REAL(A [, KIND])} converts its argument @var{A} to a real type. The
9168 @code{REALPART} function is provided for compatibility with @command{g77},
9169 and its use is strongly discouraged.
9171 @item @emph{Standard}:
9172 Fortran 77 and later
9177 @item @emph{Syntax}:
9178 @multitable @columnfractions .80
9179 @item @code{RESULT = REAL(A [, KIND])}
9180 @item @code{RESULT = REALPART(Z)}
9183 @item @emph{Arguments}:
9184 @multitable @columnfractions .15 .70
9185 @item @var{A} @tab Shall be @code{INTEGER}, @code{REAL}, or
9187 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
9188 expression indicating the kind parameter of the result.
9191 @item @emph{Return value}:
9192 These functions return a @code{REAL} variable or array under
9193 the following rules:
9197 @code{REAL(A)} is converted to a default real type if @var{A} is an
9198 integer or real variable.
9200 @code{REAL(A)} is converted to a real type with the kind type parameter
9201 of @var{A} if @var{A} is a complex variable.
9203 @code{REAL(A, KIND)} is converted to a real type with kind type
9204 parameter @var{KIND} if @var{A} is a complex, integer, or real
9208 @item @emph{Example}:
9211 complex :: x = (1.0, 2.0)
9212 print *, real(x), real(x,8), realpart(x)
9213 end program test_real
9216 @item @emph{Specific names}:
9217 @multitable @columnfractions .20 .20 .20 .25
9218 @item Name @tab Argument @tab Return type @tab Standard
9219 @item @code{FLOAT(A)} @tab @code{INTEGER(4)} @tab @code{REAL(4)} @tab Fortran 77 and later
9220 @item @code{DFLOAT(A)} @tab @code{INTEGER(4)} @tab @code{REAL(8)} @tab GNU extension
9221 @item @code{SNGL(A)} @tab @code{INTEGER(8)} @tab @code{REAL(4)} @tab Fortran 77 and later
9225 @item @emph{See also}:
9233 @section @code{RENAME} --- Rename a file
9235 @cindex file system, rename file
9238 @item @emph{Description}:
9239 Renames a file from file @var{PATH1} to @var{PATH2}. A null
9240 character (@code{CHAR(0)}) can be used to mark the end of the names in
9241 @var{PATH1} and @var{PATH2}; otherwise, trailing blanks in the file
9242 names are ignored. If the @var{STATUS} argument is supplied, it
9243 contains 0 on success or a nonzero error code upon return; see
9246 This intrinsic is provided in both subroutine and function forms;
9247 however, only one form can be used in any given program unit.
9249 @item @emph{Standard}:
9253 Subroutine, function
9255 @item @emph{Syntax}:
9256 @multitable @columnfractions .80
9257 @item @code{CALL RENAME(PATH1, PATH2 [, STATUS])}
9258 @item @code{STATUS = RENAME(PATH1, PATH2)}
9261 @item @emph{Arguments}:
9262 @multitable @columnfractions .15 .70
9263 @item @var{PATH1} @tab Shall be of default @code{CHARACTER} type.
9264 @item @var{PATH2} @tab Shall be of default @code{CHARACTER} type.
9265 @item @var{STATUS} @tab (Optional) Shall be of default @code{INTEGER} type.
9268 @item @emph{See also}:
9276 @section @code{REPEAT} --- Repeated string concatenation
9278 @cindex string, repeat
9279 @cindex string, concatenate
9282 @item @emph{Description}:
9283 Concatenates @var{NCOPIES} copies of a string.
9285 @item @emph{Standard}:
9286 Fortran 95 and later
9289 Transformational function
9291 @item @emph{Syntax}:
9292 @code{RESULT = REPEAT(STRING, NCOPIES)}
9294 @item @emph{Arguments}:
9295 @multitable @columnfractions .15 .70
9296 @item @var{STRING} @tab Shall be scalar and of type @code{CHARACTER}.
9297 @item @var{NCOPIES} @tab Shall be scalar and of type @code{INTEGER}.
9300 @item @emph{Return value}:
9301 A new scalar of type @code{CHARACTER} built up from @var{NCOPIES} copies
9304 @item @emph{Example}:
9307 write(*,*) repeat("x", 5) ! "xxxxx"
9315 @section @code{RESHAPE} --- Function to reshape an array
9317 @cindex array, change dimensions
9318 @cindex array, transmogrify
9321 @item @emph{Description}:
9322 Reshapes @var{SOURCE} to correspond to @var{SHAPE}. If necessary,
9323 the new array may be padded with elements from @var{PAD} or permuted
9324 as defined by @var{ORDER}.
9326 @item @emph{Standard}:
9327 Fortran 95 and later
9330 Transformational function
9332 @item @emph{Syntax}:
9333 @code{RESULT = RESHAPE(SOURCE, SHAPE[, PAD, ORDER])}
9335 @item @emph{Arguments}:
9336 @multitable @columnfractions .15 .70
9337 @item @var{SOURCE} @tab Shall be an array of any type.
9338 @item @var{SHAPE} @tab Shall be of type @code{INTEGER} and an
9339 array of rank one. Its values must be positive or zero.
9340 @item @var{PAD} @tab (Optional) shall be an array of the same
9341 type as @var{SOURCE}.
9342 @item @var{ORDER} @tab (Optional) shall be of type @code{INTEGER}
9343 and an array of the same shape as @var{SHAPE}. Its values shall
9344 be a permutation of the numbers from 1 to n, where n is the size of
9345 @var{SHAPE}. If @var{ORDER} is absent, the natural ordering shall
9349 @item @emph{Return value}:
9350 The result is an array of shape @var{SHAPE} with the same type as
9353 @item @emph{Example}:
9355 PROGRAM test_reshape
9356 INTEGER, DIMENSION(4) :: x
9357 WRITE(*,*) SHAPE(x) ! prints "4"
9358 WRITE(*,*) SHAPE(RESHAPE(x, (/2, 2/))) ! prints "2 2"
9362 @item @emph{See also}:
9369 @section @code{RRSPACING} --- Reciprocal of the relative spacing
9371 @cindex real number, relative spacing
9372 @cindex floating point, relative spacing
9376 @item @emph{Description}:
9377 @code{RRSPACING(X)} returns the reciprocal of the relative spacing of
9378 model numbers near @var{X}.
9380 @item @emph{Standard}:
9381 Fortran 95 and later
9386 @item @emph{Syntax}:
9387 @code{RESULT = RRSPACING(X)}
9389 @item @emph{Arguments}:
9390 @multitable @columnfractions .15 .70
9391 @item @var{X} @tab Shall be of type @code{REAL}.
9394 @item @emph{Return value}:
9395 The return value is of the same type and kind as @var{X}.
9396 The value returned is equal to
9397 @code{ABS(FRACTION(X)) * FLOAT(RADIX(X))**DIGITS(X)}.
9399 @item @emph{See also}:
9406 @section @code{RSHIFT} --- Right shift bits
9408 @cindex bits, shift right
9411 @item @emph{Description}:
9412 @code{RSHIFT} returns a value corresponding to @var{I} with all of the
9413 bits shifted right by @var{SHIFT} places. If the absolute value of
9414 @var{SHIFT} is greater than @code{BIT_SIZE(I)}, the value is undefined.
9415 Bits shifted out from the left end are lost; zeros are shifted in from
9418 This function has been superseded by the @code{ISHFT} intrinsic, which
9419 is standard in Fortran 95 and later.
9421 @item @emph{Standard}:
9427 @item @emph{Syntax}:
9428 @code{RESULT = RSHIFT(I, SHIFT)}
9430 @item @emph{Arguments}:
9431 @multitable @columnfractions .15 .70
9432 @item @var{I} @tab The type shall be @code{INTEGER}.
9433 @item @var{SHIFT} @tab The type shall be @code{INTEGER}.
9436 @item @emph{Return value}:
9437 The return value is of type @code{INTEGER} and of the same kind as
9440 @item @emph{See also}:
9441 @ref{ISHFT}, @ref{ISHFTC}, @ref{LSHIFT}
9448 @section @code{SAME_TYPE_AS} --- Query dynamic types for equality
9449 @fnindex SAME_TYPE_AS
9452 @item @emph{Description}:
9453 Query dynamic types for equality.
9455 @item @emph{Standard}:
9456 Fortran 2003 and later
9461 @item @emph{Syntax}:
9462 @code{RESULT = SAME_TYPE_AS(A, B)}
9464 @item @emph{Arguments}:
9465 @multitable @columnfractions .15 .70
9466 @item @var{A} @tab Shall be an object of extensible declared type or
9467 unlimited polymorphic.
9468 @item @var{B} @tab Shall be an object of extensible declared type or
9469 unlimited polymorphic.
9472 @item @emph{Return value}:
9473 The return value is a scalar of type default logical. It is true if and
9474 only if the dynamic type of A is the same as the dynamic type of B.
9476 @item @emph{See also}:
9477 @ref{EXTENDS_TYPE_OF}
9484 @section @code{SCALE} --- Scale a real value
9486 @cindex real number, scale
9487 @cindex floating point, scale
9490 @item @emph{Description}:
9491 @code{SCALE(X,I)} returns @code{X * RADIX(X)**I}.
9493 @item @emph{Standard}:
9494 Fortran 95 and later
9499 @item @emph{Syntax}:
9500 @code{RESULT = SCALE(X, I)}
9502 @item @emph{Arguments}:
9503 @multitable @columnfractions .15 .70
9504 @item @var{X} @tab The type of the argument shall be a @code{REAL}.
9505 @item @var{I} @tab The type of the argument shall be a @code{INTEGER}.
9508 @item @emph{Return value}:
9509 The return value is of the same type and kind as @var{X}.
9510 Its value is @code{X * RADIX(X)**I}.
9512 @item @emph{Example}:
9515 real :: x = 178.1387e-4
9517 print *, scale(x,i), x*radix(x)**i
9518 end program test_scale
9526 @section @code{SCAN} --- Scan a string for the presence of a set of characters
9528 @cindex string, find subset
9531 @item @emph{Description}:
9532 Scans a @var{STRING} for any of the characters in a @var{SET}
9535 If @var{BACK} is either absent or equals @code{FALSE}, this function
9536 returns the position of the leftmost character of @var{STRING} that is
9537 in @var{SET}. If @var{BACK} equals @code{TRUE}, the rightmost position
9538 is returned. If no character of @var{SET} is found in @var{STRING}, the
9541 @item @emph{Standard}:
9542 Fortran 95 and later, with @var{KIND} argument Fortran 2003 and later
9547 @item @emph{Syntax}:
9548 @code{RESULT = SCAN(STRING, SET[, BACK [, KIND]])}
9550 @item @emph{Arguments}:
9551 @multitable @columnfractions .15 .70
9552 @item @var{STRING} @tab Shall be of type @code{CHARACTER}.
9553 @item @var{SET} @tab Shall be of type @code{CHARACTER}.
9554 @item @var{BACK} @tab (Optional) shall be of type @code{LOGICAL}.
9555 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
9556 expression indicating the kind parameter of the result.
9559 @item @emph{Return value}:
9560 The return value is of type @code{INTEGER} and of kind @var{KIND}. If
9561 @var{KIND} is absent, the return value is of default integer kind.
9563 @item @emph{Example}:
9566 WRITE(*,*) SCAN("FORTRAN", "AO") ! 2, found 'O'
9567 WRITE(*,*) SCAN("FORTRAN", "AO", .TRUE.) ! 6, found 'A'
9568 WRITE(*,*) SCAN("FORTRAN", "C++") ! 0, found none
9572 @item @emph{See also}:
9573 @ref{INDEX intrinsic}, @ref{VERIFY}
9579 @section @code{SECNDS} --- Time function
9581 @cindex time, elapsed
9582 @cindex elapsed time
9585 @item @emph{Description}:
9586 @code{SECNDS(X)} gets the time in seconds from the real-time system clock.
9587 @var{X} is a reference time, also in seconds. If this is zero, the time in
9588 seconds from midnight is returned. This function is non-standard and its
9591 @item @emph{Standard}:
9597 @item @emph{Syntax}:
9598 @code{RESULT = SECNDS (X)}
9600 @item @emph{Arguments}:
9601 @multitable @columnfractions .15 .70
9602 @item @var{T} @tab Shall be of type @code{REAL(4)}.
9603 @item @var{X} @tab Shall be of type @code{REAL(4)}.
9606 @item @emph{Return value}:
9609 @item @emph{Example}:
9614 print *, secnds (0.0) ! seconds since midnight
9615 t1 = secnds (0.0) ! reference time
9616 do i = 1, 10000000 ! do something
9618 t2 = secnds (t1) ! elapsed time
9619 print *, "Something took ", t2, " seconds."
9620 end program test_secnds
9627 @section @code{SECOND} --- CPU time function
9629 @cindex time, elapsed
9630 @cindex elapsed time
9633 @item @emph{Description}:
9634 Returns a @code{REAL(4)} value representing the elapsed CPU time in
9635 seconds. This provides the same functionality as the standard
9636 @code{CPU_TIME} intrinsic, and is only included for backwards
9639 This intrinsic is provided in both subroutine and function forms;
9640 however, only one form can be used in any given program unit.
9642 @item @emph{Standard}:
9646 Subroutine, function
9648 @item @emph{Syntax}:
9649 @multitable @columnfractions .80
9650 @item @code{CALL SECOND(TIME)}
9651 @item @code{TIME = SECOND()}
9654 @item @emph{Arguments}:
9655 @multitable @columnfractions .15 .70
9656 @item @var{TIME} @tab Shall be of type @code{REAL(4)}.
9659 @item @emph{Return value}:
9660 In either syntax, @var{TIME} is set to the process's current runtime in
9663 @item @emph{See also}:
9670 @node SELECTED_CHAR_KIND
9671 @section @code{SELECTED_CHAR_KIND} --- Choose character kind
9672 @fnindex SELECTED_CHAR_KIND
9673 @cindex character kind
9674 @cindex kind, character
9677 @item @emph{Description}:
9679 @code{SELECTED_CHAR_KIND(NAME)} returns the kind value for the character
9680 set named @var{NAME}, if a character set with such a name is supported,
9681 or @math{-1} otherwise. Currently, supported character sets include
9682 ``ASCII'' and ``DEFAULT'', which are equivalent.
9684 @item @emph{Standard}:
9685 Fortran 2003 and later
9688 Transformational function
9690 @item @emph{Syntax}:
9691 @code{RESULT = SELECTED_CHAR_KIND(NAME)}
9693 @item @emph{Arguments}:
9694 @multitable @columnfractions .15 .70
9695 @item @var{NAME} @tab Shall be a scalar and of the default character type.
9698 @item @emph{Example}:
9701 integer,parameter :: ascii = selected_char_kind("ascii")
9702 character(kind=ascii, len=26) :: s
9704 s = ascii_"abcdefghijklmnopqrstuvwxyz"
9706 end program ascii_kind
9712 @node SELECTED_INT_KIND
9713 @section @code{SELECTED_INT_KIND} --- Choose integer kind
9714 @fnindex SELECTED_INT_KIND
9715 @cindex integer kind
9716 @cindex kind, integer
9719 @item @emph{Description}:
9720 @code{SELECTED_INT_KIND(R)} return the kind value of the smallest integer
9721 type that can represent all values ranging from @math{-10^R} (exclusive)
9722 to @math{10^R} (exclusive). If there is no integer kind that accommodates
9723 this range, @code{SELECTED_INT_KIND} returns @math{-1}.
9725 @item @emph{Standard}:
9726 Fortran 95 and later
9729 Transformational function
9731 @item @emph{Syntax}:
9732 @code{RESULT = SELECTED_INT_KIND(R)}
9734 @item @emph{Arguments}:
9735 @multitable @columnfractions .15 .70
9736 @item @var{R} @tab Shall be a scalar and of type @code{INTEGER}.
9739 @item @emph{Example}:
9741 program large_integers
9742 integer,parameter :: k5 = selected_int_kind(5)
9743 integer,parameter :: k15 = selected_int_kind(15)
9744 integer(kind=k5) :: i5
9745 integer(kind=k15) :: i15
9747 print *, huge(i5), huge(i15)
9749 ! The following inequalities are always true
9750 print *, huge(i5) >= 10_k5**5-1
9751 print *, huge(i15) >= 10_k15**15-1
9752 end program large_integers
9758 @node SELECTED_REAL_KIND
9759 @section @code{SELECTED_REAL_KIND} --- Choose real kind
9760 @fnindex SELECTED_REAL_KIND
9766 @item @emph{Description}:
9767 @code{SELECTED_REAL_KIND(P,R)} returns the kind value of a real data type
9768 with decimal precision of at least @code{P} digits, exponent range of
9769 at least @code{R}, and with a radix of @code{RADIX}.
9771 @item @emph{Standard}:
9772 Fortran 95 and later, with @code{RADIX} Fortran 2008 or later
9775 Transformational function
9777 @item @emph{Syntax}:
9778 @code{RESULT = SELECTED_REAL_KIND([P, R, RADIX])}
9780 @item @emph{Arguments}:
9781 @multitable @columnfractions .15 .70
9782 @item @var{P} @tab (Optional) shall be a scalar and of type @code{INTEGER}.
9783 @item @var{R} @tab (Optional) shall be a scalar and of type @code{INTEGER}.
9784 @item @var{RADIX} @tab (Optional) shall be a scalar and of type @code{INTEGER}.
9786 Before Fortran 2008, at least one of the arguments @var{R} or @var{P} shall
9787 be present; since Fortran 2008, they are assumed to be zero if absent.
9789 @item @emph{Return value}:
9791 @code{SELECTED_REAL_KIND} returns the value of the kind type parameter of
9792 a real data type with decimal precision of at least @code{P} digits, a
9793 decimal exponent range of at least @code{R}, and with the requested
9794 @code{RADIX}. If the @code{RADIX} parameter is absent, real kinds with
9795 any radix can be returned. If more than one real data type meet the
9796 criteria, the kind of the data type with the smallest decimal precision
9797 is returned. If no real data type matches the criteria, the result is
9799 @item -1 if the processor does not support a real data type with a
9800 precision greater than or equal to @code{P}, but the @code{R} and
9801 @code{RADIX} requirements can be fulfilled
9802 @item -2 if the processor does not support a real type with an exponent
9803 range greater than or equal to @code{R}, but @code{P} and @code{RADIX}
9805 @item -3 if @code{RADIX} but not @code{P} and @code{R} requirements
9807 @item -4 if @code{RADIX} and either @code{P} or @code{R} requirements
9809 @item -5 if there is no real type with the given @code{RADIX}
9812 @item @emph{See also}:
9813 @ref{PRECISION}, @ref{RANGE}, @ref{RADIX}
9815 @item @emph{Example}:
9818 integer,parameter :: p6 = selected_real_kind(6)
9819 integer,parameter :: p10r100 = selected_real_kind(10,100)
9820 integer,parameter :: r400 = selected_real_kind(r=400)
9822 real(kind=p10r100) :: y
9823 real(kind=r400) :: z
9825 print *, precision(x), range(x)
9826 print *, precision(y), range(y)
9827 print *, precision(z), range(z)
9828 end program real_kinds
9835 @section @code{SET_EXPONENT} --- Set the exponent of the model
9836 @fnindex SET_EXPONENT
9837 @cindex real number, set exponent
9838 @cindex floating point, set exponent
9841 @item @emph{Description}:
9842 @code{SET_EXPONENT(X, I)} returns the real number whose fractional part
9843 is that that of @var{X} and whose exponent part is @var{I}.
9845 @item @emph{Standard}:
9846 Fortran 95 and later
9851 @item @emph{Syntax}:
9852 @code{RESULT = SET_EXPONENT(X, I)}
9854 @item @emph{Arguments}:
9855 @multitable @columnfractions .15 .70
9856 @item @var{X} @tab Shall be of type @code{REAL}.
9857 @item @var{I} @tab Shall be of type @code{INTEGER}.
9860 @item @emph{Return value}:
9861 The return value is of the same type and kind as @var{X}.
9862 The real number whose fractional part
9863 is that that of @var{X} and whose exponent part if @var{I} is returned;
9864 it is @code{FRACTION(X) * RADIX(X)**I}.
9866 @item @emph{Example}:
9869 REAL :: x = 178.1387e-4
9871 PRINT *, SET_EXPONENT(x, i), FRACTION(x) * RADIX(x)**i
9880 @section @code{SHAPE} --- Determine the shape of an array
9882 @cindex array, shape
9885 @item @emph{Description}:
9886 Determines the shape of an array.
9888 @item @emph{Standard}:
9889 Fortran 95 and later
9894 @item @emph{Syntax}:
9895 @code{RESULT = SHAPE(SOURCE)}
9897 @item @emph{Arguments}:
9898 @multitable @columnfractions .15 .70
9899 @item @var{SOURCE} @tab Shall be an array or scalar of any type.
9900 If @var{SOURCE} is a pointer it must be associated and allocatable
9901 arrays must be allocated.
9904 @item @emph{Return value}:
9905 An @code{INTEGER} array of rank one with as many elements as @var{SOURCE}
9906 has dimensions. The elements of the resulting array correspond to the extend
9907 of @var{SOURCE} along the respective dimensions. If @var{SOURCE} is a scalar,
9908 the result is the rank one array of size zero.
9910 @item @emph{Example}:
9913 INTEGER, DIMENSION(-1:1, -1:2) :: A
9914 WRITE(*,*) SHAPE(A) ! (/ 3, 4 /)
9915 WRITE(*,*) SIZE(SHAPE(42)) ! (/ /)
9919 @item @emph{See also}:
9920 @ref{RESHAPE}, @ref{SIZE}
9926 @section @code{SIGN} --- Sign copying function
9930 @cindex sign copying
9933 @item @emph{Description}:
9934 @code{SIGN(A,B)} returns the value of @var{A} with the sign of @var{B}.
9936 @item @emph{Standard}:
9937 Fortran 77 and later
9942 @item @emph{Syntax}:
9943 @code{RESULT = SIGN(A, B)}
9945 @item @emph{Arguments}:
9946 @multitable @columnfractions .15 .70
9947 @item @var{A} @tab Shall be of type @code{INTEGER} or @code{REAL}
9948 @item @var{B} @tab Shall be of the same type and kind as @var{A}
9951 @item @emph{Return value}:
9952 The kind of the return value is that of @var{A} and @var{B}.
9953 If @math{B\ge 0} then the result is @code{ABS(A)}, else
9954 it is @code{-ABS(A)}.
9956 @item @emph{Example}:
9959 print *, sign(-12,1)
9960 print *, sign(-12,0)
9961 print *, sign(-12,-1)
9963 print *, sign(-12.,1.)
9964 print *, sign(-12.,0.)
9965 print *, sign(-12.,-1.)
9966 end program test_sign
9969 @item @emph{Specific names}:
9970 @multitable @columnfractions .20 .20 .20 .25
9971 @item Name @tab Arguments @tab Return type @tab Standard
9972 @item @code{SIGN(A,B)} @tab @code{REAL(4) A, B} @tab @code{REAL(4)} @tab f77, gnu
9973 @item @code{ISIGN(A,B)} @tab @code{INTEGER(4) A, B} @tab @code{INTEGER(4)} @tab f77, gnu
9974 @item @code{DSIGN(A,B)} @tab @code{REAL(8) A, B} @tab @code{REAL(8)} @tab f77, gnu
9981 @section @code{SIGNAL} --- Signal handling subroutine (or function)
9983 @cindex system, signal handling
9986 @item @emph{Description}:
9987 @code{SIGNAL(NUMBER, HANDLER [, STATUS])} causes external subroutine
9988 @var{HANDLER} to be executed with a single integer argument when signal
9989 @var{NUMBER} occurs. If @var{HANDLER} is an integer, it can be used to
9990 turn off handling of signal @var{NUMBER} or revert to its default
9991 action. See @code{signal(2)}.
9993 If @code{SIGNAL} is called as a subroutine and the @var{STATUS} argument
9994 is supplied, it is set to the value returned by @code{signal(2)}.
9996 @item @emph{Standard}:
10000 Subroutine, function
10002 @item @emph{Syntax}:
10003 @multitable @columnfractions .80
10004 @item @code{CALL SIGNAL(NUMBER, HANDLER [, STATUS])}
10005 @item @code{STATUS = SIGNAL(NUMBER, HANDLER)}
10008 @item @emph{Arguments}:
10009 @multitable @columnfractions .15 .70
10010 @item @var{NUMBER} @tab Shall be a scalar integer, with @code{INTENT(IN)}
10011 @item @var{HANDLER}@tab Signal handler (@code{INTEGER FUNCTION} or
10012 @code{SUBROUTINE}) or dummy/global @code{INTEGER} scalar.
10013 @code{INTEGER}. It is @code{INTENT(IN)}.
10014 @item @var{STATUS} @tab (Optional) @var{STATUS} shall be a scalar
10015 integer. It has @code{INTENT(OUT)}.
10017 @c TODO: What should the interface of the handler be? Does it take arguments?
10019 @item @emph{Return value}:
10020 The @code{SIGNAL} function returns the value returned by @code{signal(2)}.
10022 @item @emph{Example}:
10024 program test_signal
10026 external handler_print
10028 call signal (12, handler_print)
10029 call signal (10, 1)
10032 end program test_signal
10039 @section @code{SIN} --- Sine function
10045 @cindex trigonometric function, sine
10049 @item @emph{Description}:
10050 @code{SIN(X)} computes the sine of @var{X}.
10052 @item @emph{Standard}:
10053 Fortran 77 and later
10055 @item @emph{Class}:
10058 @item @emph{Syntax}:
10059 @code{RESULT = SIN(X)}
10061 @item @emph{Arguments}:
10062 @multitable @columnfractions .15 .70
10063 @item @var{X} @tab The type shall be @code{REAL} or
10067 @item @emph{Return value}:
10068 The return value has same type and kind as @var{X}.
10070 @item @emph{Example}:
10075 end program test_sin
10078 @item @emph{Specific names}:
10079 @multitable @columnfractions .20 .20 .20 .25
10080 @item Name @tab Argument @tab Return type @tab Standard
10081 @item @code{SIN(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab f77, gnu
10082 @item @code{DSIN(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab f95, gnu
10083 @item @code{CSIN(X)} @tab @code{COMPLEX(4) X} @tab @code{COMPLEX(4)} @tab f95, gnu
10084 @item @code{ZSIN(X)} @tab @code{COMPLEX(8) X} @tab @code{COMPLEX(8)} @tab f95, gnu
10085 @item @code{CDSIN(X)} @tab @code{COMPLEX(8) X} @tab @code{COMPLEX(8)} @tab f95, gnu
10088 @item @emph{See also}:
10095 @section @code{SINH} --- Hyperbolic sine function
10098 @cindex hyperbolic sine
10099 @cindex hyperbolic function, sine
10100 @cindex sine, hyperbolic
10103 @item @emph{Description}:
10104 @code{SINH(X)} computes the hyperbolic sine of @var{X}.
10106 @item @emph{Standard}:
10107 Fortran 95 and later, for a complex argument Fortran 2008 or later
10109 @item @emph{Class}:
10112 @item @emph{Syntax}:
10113 @code{RESULT = SINH(X)}
10115 @item @emph{Arguments}:
10116 @multitable @columnfractions .15 .70
10117 @item @var{X} @tab The type shall be @code{REAL} or @code{COMPLEX}.
10120 @item @emph{Return value}:
10121 The return value has same type and kind as @var{X}.
10123 @item @emph{Example}:
10126 real(8) :: x = - 1.0_8
10128 end program test_sinh
10131 @item @emph{Specific names}:
10132 @multitable @columnfractions .20 .20 .20 .25
10133 @item Name @tab Argument @tab Return type @tab Standard
10134 @item @code{SINH(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab Fortran 95 and later
10135 @item @code{DSINH(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab Fortran 95 and later
10138 @item @emph{See also}:
10145 @section @code{SIZE} --- Determine the size of an array
10147 @cindex array, size
10148 @cindex array, number of elements
10149 @cindex array, count elements
10152 @item @emph{Description}:
10153 Determine the extent of @var{ARRAY} along a specified dimension @var{DIM},
10154 or the total number of elements in @var{ARRAY} if @var{DIM} is absent.
10156 @item @emph{Standard}:
10157 Fortran 95 and later, with @var{KIND} argument Fortran 2003 and later
10159 @item @emph{Class}:
10162 @item @emph{Syntax}:
10163 @code{RESULT = SIZE(ARRAY[, DIM [, KIND]])}
10165 @item @emph{Arguments}:
10166 @multitable @columnfractions .15 .70
10167 @item @var{ARRAY} @tab Shall be an array of any type. If @var{ARRAY} is
10168 a pointer it must be associated and allocatable arrays must be allocated.
10169 @item @var{DIM} @tab (Optional) shall be a scalar of type @code{INTEGER}
10170 and its value shall be in the range from 1 to n, where n equals the rank
10172 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
10173 expression indicating the kind parameter of the result.
10176 @item @emph{Return value}:
10177 The return value is of type @code{INTEGER} and of kind @var{KIND}. If
10178 @var{KIND} is absent, the return value is of default integer kind.
10180 @item @emph{Example}:
10183 WRITE(*,*) SIZE((/ 1, 2 /)) ! 2
10187 @item @emph{See also}:
10188 @ref{SHAPE}, @ref{RESHAPE}
10193 @section @code{SIZEOF} --- Size in bytes of an expression
10195 @cindex expression size
10196 @cindex size of an expression
10199 @item @emph{Description}:
10200 @code{SIZEOF(X)} calculates the number of bytes of storage the
10201 expression @code{X} occupies.
10203 @item @emph{Standard}:
10206 @item @emph{Class}:
10209 @item @emph{Syntax}:
10210 @code{N = SIZEOF(X)}
10212 @item @emph{Arguments}:
10213 @multitable @columnfractions .15 .70
10214 @item @var{X} @tab The argument shall be of any type, rank or shape.
10217 @item @emph{Return value}:
10218 The return value is of type integer and of the system-dependent kind
10219 @var{C_SIZE_T} (from the @var{ISO_C_BINDING} module). Its value is the
10220 number of bytes occupied by the argument. If the argument has the
10221 @code{POINTER} attribute, the number of bytes of the storage area pointed
10222 to is returned. If the argument is of a derived type with @code{POINTER}
10223 or @code{ALLOCATABLE} components, the return value doesn't account for
10224 the sizes of the data pointed to by these components. If the argument is
10225 polymorphic, the size according to the declared type is returned.
10227 @item @emph{Example}:
10231 print *, (sizeof(s)/sizeof(r) == 5)
10234 The example will print @code{.TRUE.} unless you are using a platform
10235 where default @code{REAL} variables are unusually padded.
10237 @item @emph{See also}:
10238 @ref{C_SIZEOF}, @ref{STORAGE_SIZE}
10243 @section @code{SLEEP} --- Sleep for the specified number of seconds
10245 @cindex delayed execution
10248 @item @emph{Description}:
10249 Calling this subroutine causes the process to pause for @var{SECONDS} seconds.
10251 @item @emph{Standard}:
10254 @item @emph{Class}:
10257 @item @emph{Syntax}:
10258 @code{CALL SLEEP(SECONDS)}
10260 @item @emph{Arguments}:
10261 @multitable @columnfractions .15 .70
10262 @item @var{SECONDS} @tab The type shall be of default @code{INTEGER}.
10265 @item @emph{Example}:
10276 @section @code{SPACING} --- Smallest distance between two numbers of a given type
10278 @cindex real number, relative spacing
10279 @cindex floating point, relative spacing
10282 @item @emph{Description}:
10283 Determines the distance between the argument @var{X} and the nearest
10284 adjacent number of the same type.
10286 @item @emph{Standard}:
10287 Fortran 95 and later
10289 @item @emph{Class}:
10292 @item @emph{Syntax}:
10293 @code{RESULT = SPACING(X)}
10295 @item @emph{Arguments}:
10296 @multitable @columnfractions .15 .70
10297 @item @var{X} @tab Shall be of type @code{REAL}.
10300 @item @emph{Return value}:
10301 The result is of the same type as the input argument @var{X}.
10303 @item @emph{Example}:
10305 PROGRAM test_spacing
10306 INTEGER, PARAMETER :: SGL = SELECTED_REAL_KIND(p=6, r=37)
10307 INTEGER, PARAMETER :: DBL = SELECTED_REAL_KIND(p=13, r=200)
10309 WRITE(*,*) spacing(1.0_SGL) ! "1.1920929E-07" on i686
10310 WRITE(*,*) spacing(1.0_DBL) ! "2.220446049250313E-016" on i686
10314 @item @emph{See also}:
10321 @section @code{SPREAD} --- Add a dimension to an array
10323 @cindex array, increase dimension
10324 @cindex array, duplicate elements
10325 @cindex array, duplicate dimensions
10328 @item @emph{Description}:
10329 Replicates a @var{SOURCE} array @var{NCOPIES} times along a specified
10330 dimension @var{DIM}.
10332 @item @emph{Standard}:
10333 Fortran 95 and later
10335 @item @emph{Class}:
10336 Transformational function
10338 @item @emph{Syntax}:
10339 @code{RESULT = SPREAD(SOURCE, DIM, NCOPIES)}
10341 @item @emph{Arguments}:
10342 @multitable @columnfractions .15 .70
10343 @item @var{SOURCE} @tab Shall be a scalar or an array of any type and
10344 a rank less than seven.
10345 @item @var{DIM} @tab Shall be a scalar of type @code{INTEGER} with a
10346 value in the range from 1 to n+1, where n equals the rank of @var{SOURCE}.
10347 @item @var{NCOPIES} @tab Shall be a scalar of type @code{INTEGER}.
10350 @item @emph{Return value}:
10351 The result is an array of the same type as @var{SOURCE} and has rank n+1
10352 where n equals the rank of @var{SOURCE}.
10354 @item @emph{Example}:
10356 PROGRAM test_spread
10357 INTEGER :: a = 1, b(2) = (/ 1, 2 /)
10358 WRITE(*,*) SPREAD(A, 1, 2) ! "1 1"
10359 WRITE(*,*) SPREAD(B, 1, 2) ! "1 1 2 2"
10363 @item @emph{See also}:
10370 @section @code{SQRT} --- Square-root function
10377 @cindex square-root
10380 @item @emph{Description}:
10381 @code{SQRT(X)} computes the square root of @var{X}.
10383 @item @emph{Standard}:
10384 Fortran 77 and later
10386 @item @emph{Class}:
10389 @item @emph{Syntax}:
10390 @code{RESULT = SQRT(X)}
10392 @item @emph{Arguments}:
10393 @multitable @columnfractions .15 .70
10394 @item @var{X} @tab The type shall be @code{REAL} or
10398 @item @emph{Return value}:
10399 The return value is of type @code{REAL} or @code{COMPLEX}.
10400 The kind type parameter is the same as @var{X}.
10402 @item @emph{Example}:
10405 real(8) :: x = 2.0_8
10406 complex :: z = (1.0, 2.0)
10409 end program test_sqrt
10412 @item @emph{Specific names}:
10413 @multitable @columnfractions .20 .20 .20 .25
10414 @item Name @tab Argument @tab Return type @tab Standard
10415 @item @code{SQRT(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab Fortran 95 and later
10416 @item @code{DSQRT(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab Fortran 95 and later
10417 @item @code{CSQRT(X)} @tab @code{COMPLEX(4) X} @tab @code{COMPLEX(4)} @tab Fortran 95 and later
10418 @item @code{ZSQRT(X)} @tab @code{COMPLEX(8) X} @tab @code{COMPLEX(8)} @tab GNU extension
10419 @item @code{CDSQRT(X)} @tab @code{COMPLEX(8) X} @tab @code{COMPLEX(8)} @tab GNU extension
10426 @section @code{SRAND} --- Reinitialize the random number generator
10428 @cindex random number generation, seeding
10429 @cindex seeding a random number generator
10432 @item @emph{Description}:
10433 @code{SRAND} reinitializes the pseudo-random number generator
10434 called by @code{RAND} and @code{IRAND}. The new seed used by the
10435 generator is specified by the required argument @var{SEED}.
10437 @item @emph{Standard}:
10440 @item @emph{Class}:
10443 @item @emph{Syntax}:
10444 @code{CALL SRAND(SEED)}
10446 @item @emph{Arguments}:
10447 @multitable @columnfractions .15 .70
10448 @item @var{SEED} @tab Shall be a scalar @code{INTEGER(kind=4)}.
10451 @item @emph{Return value}:
10452 Does not return anything.
10454 @item @emph{Example}:
10455 See @code{RAND} and @code{IRAND} for examples.
10457 @item @emph{Notes}:
10458 The Fortran 2003 standard specifies the intrinsic @code{RANDOM_SEED} to
10459 initialize the pseudo-random numbers generator and @code{RANDOM_NUMBER}
10460 to generate pseudo-random numbers. Please note that in
10461 GNU Fortran, these two sets of intrinsics (@code{RAND},
10462 @code{IRAND} and @code{SRAND} on the one hand, @code{RANDOM_NUMBER} and
10463 @code{RANDOM_SEED} on the other hand) access two independent
10464 pseudo-random number generators.
10466 @item @emph{See also}:
10467 @ref{RAND}, @ref{RANDOM_SEED}, @ref{RANDOM_NUMBER}
10474 @section @code{STAT} --- Get file status
10476 @cindex file system, file status
10479 @item @emph{Description}:
10480 This function returns information about a file. No permissions are required on
10481 the file itself, but execute (search) permission is required on all of the
10482 directories in path that lead to the file.
10484 The elements that are obtained and stored in the array @code{VALUES}:
10485 @multitable @columnfractions .15 .70
10486 @item @code{VALUES(1)} @tab Device ID
10487 @item @code{VALUES(2)} @tab Inode number
10488 @item @code{VALUES(3)} @tab File mode
10489 @item @code{VALUES(4)} @tab Number of links
10490 @item @code{VALUES(5)} @tab Owner's uid
10491 @item @code{VALUES(6)} @tab Owner's gid
10492 @item @code{VALUES(7)} @tab ID of device containing directory entry for file (0 if not available)
10493 @item @code{VALUES(8)} @tab File size (bytes)
10494 @item @code{VALUES(9)} @tab Last access time
10495 @item @code{VALUES(10)} @tab Last modification time
10496 @item @code{VALUES(11)} @tab Last file status change time
10497 @item @code{VALUES(12)} @tab Preferred I/O block size (-1 if not available)
10498 @item @code{VALUES(13)} @tab Number of blocks allocated (-1 if not available)
10501 Not all these elements are relevant on all systems.
10502 If an element is not relevant, it is returned as 0.
10504 This intrinsic is provided in both subroutine and function forms; however,
10505 only one form can be used in any given program unit.
10507 @item @emph{Standard}:
10510 @item @emph{Class}:
10511 Subroutine, function
10513 @item @emph{Syntax}:
10514 @code{CALL STAT(NAME, VALUES [, STATUS])}
10516 @item @emph{Arguments}:
10517 @multitable @columnfractions .15 .70
10518 @item @var{NAME} @tab The type shall be @code{CHARACTER}, of the
10519 default kind and a valid path within the file system.
10520 @item @var{VALUES} @tab The type shall be @code{INTEGER(4), DIMENSION(13)}.
10521 @item @var{STATUS} @tab (Optional) status flag of type @code{INTEGER(4)}. Returns 0
10522 on success and a system specific error code otherwise.
10525 @item @emph{Example}:
10528 INTEGER, DIMENSION(13) :: buff
10531 CALL STAT("/etc/passwd", buff, status)
10533 IF (status == 0) THEN
10534 WRITE (*, FMT="('Device ID:', T30, I19)") buff(1)
10535 WRITE (*, FMT="('Inode number:', T30, I19)") buff(2)
10536 WRITE (*, FMT="('File mode (octal):', T30, O19)") buff(3)
10537 WRITE (*, FMT="('Number of links:', T30, I19)") buff(4)
10538 WRITE (*, FMT="('Owner''s uid:', T30, I19)") buff(5)
10539 WRITE (*, FMT="('Owner''s gid:', T30, I19)") buff(6)
10540 WRITE (*, FMT="('Device where located:', T30, I19)") buff(7)
10541 WRITE (*, FMT="('File size:', T30, I19)") buff(8)
10542 WRITE (*, FMT="('Last access time:', T30, A19)") CTIME(buff(9))
10543 WRITE (*, FMT="('Last modification time', T30, A19)") CTIME(buff(10))
10544 WRITE (*, FMT="('Last status change time:', T30, A19)") CTIME(buff(11))
10545 WRITE (*, FMT="('Preferred block size:', T30, I19)") buff(12)
10546 WRITE (*, FMT="('No. of blocks allocated:', T30, I19)") buff(13)
10551 @item @emph{See also}:
10552 To stat an open file: @ref{FSTAT}, to stat a link: @ref{LSTAT}
10558 @section @code{STORAGE_SIZE} --- Storage size in bits
10559 @fnindex STORAGE_SIZE
10560 @cindex storage size
10563 @item @emph{Description}:
10564 Returns the storage size of argument @var{A} in bits.
10565 @item @emph{Standard}:
10566 Fortran 2008 and later
10567 @item @emph{Class}:
10569 @item @emph{Syntax}:
10570 @code{RESULT = STORAGE_SIZE(A [, KIND])}
10572 @item @emph{Arguments}:
10573 @multitable @columnfractions .15 .70
10574 @item @var{A} @tab Shall be a scalar or array of any type.
10575 @item @var{KIND} @tab (Optional) shall be a scalar integer constant expression.
10578 @item @emph{Return Value}:
10579 The result is a scalar integer with the kind type parameter specified by KIND (or default integer type if KIND is missing). The result value is the size expressed in bits for an element of an array that
10580 has the dynamic type and type parameters of A.
10582 @item @emph{See also}:
10583 @ref{C_SIZEOF}, @ref{SIZEOF}
10589 @section @code{SUM} --- Sum of array elements
10592 @cindex array, add elements
10593 @cindex array, conditionally add elements
10594 @cindex sum array elements
10597 @item @emph{Description}:
10598 Adds the elements of @var{ARRAY} along dimension @var{DIM} if
10599 the corresponding element in @var{MASK} is @code{TRUE}.
10601 @item @emph{Standard}:
10602 Fortran 95 and later
10604 @item @emph{Class}:
10605 Transformational function
10607 @item @emph{Syntax}:
10608 @multitable @columnfractions .80
10609 @item @code{RESULT = SUM(ARRAY[, MASK])}
10610 @item @code{RESULT = SUM(ARRAY, DIM[, MASK])}
10613 @item @emph{Arguments}:
10614 @multitable @columnfractions .15 .70
10615 @item @var{ARRAY} @tab Shall be an array of type @code{INTEGER},
10616 @code{REAL} or @code{COMPLEX}.
10617 @item @var{DIM} @tab (Optional) shall be a scalar of type
10618 @code{INTEGER} with a value in the range from 1 to n, where n
10619 equals the rank of @var{ARRAY}.
10620 @item @var{MASK} @tab (Optional) shall be of type @code{LOGICAL}
10621 and either be a scalar or an array of the same shape as @var{ARRAY}.
10624 @item @emph{Return value}:
10625 The result is of the same type as @var{ARRAY}.
10627 If @var{DIM} is absent, a scalar with the sum of all elements in @var{ARRAY}
10628 is returned. Otherwise, an array of rank n-1, where n equals the rank of
10629 @var{ARRAY}, and a shape similar to that of @var{ARRAY} with dimension @var{DIM}
10630 dropped is returned.
10632 @item @emph{Example}:
10635 INTEGER :: x(5) = (/ 1, 2, 3, 4 ,5 /)
10636 print *, SUM(x) ! all elements, sum = 15
10637 print *, SUM(x, MASK=MOD(x, 2)==1) ! odd elements, sum = 9
10641 @item @emph{See also}:
10648 @section @code{SYMLNK} --- Create a symbolic link
10650 @cindex file system, create link
10651 @cindex file system, soft link
10654 @item @emph{Description}:
10655 Makes a symbolic link from file @var{PATH1} to @var{PATH2}. A null
10656 character (@code{CHAR(0)}) can be used to mark the end of the names in
10657 @var{PATH1} and @var{PATH2}; otherwise, trailing blanks in the file
10658 names are ignored. If the @var{STATUS} argument is supplied, it
10659 contains 0 on success or a nonzero error code upon return; see
10660 @code{symlink(2)}. If the system does not supply @code{symlink(2)},
10661 @code{ENOSYS} is returned.
10663 This intrinsic is provided in both subroutine and function forms;
10664 however, only one form can be used in any given program unit.
10666 @item @emph{Standard}:
10669 @item @emph{Class}:
10670 Subroutine, function
10672 @item @emph{Syntax}:
10673 @multitable @columnfractions .80
10674 @item @code{CALL SYMLNK(PATH1, PATH2 [, STATUS])}
10675 @item @code{STATUS = SYMLNK(PATH1, PATH2)}
10678 @item @emph{Arguments}:
10679 @multitable @columnfractions .15 .70
10680 @item @var{PATH1} @tab Shall be of default @code{CHARACTER} type.
10681 @item @var{PATH2} @tab Shall be of default @code{CHARACTER} type.
10682 @item @var{STATUS} @tab (Optional) Shall be of default @code{INTEGER} type.
10685 @item @emph{See also}:
10686 @ref{LINK}, @ref{UNLINK}
10693 @section @code{SYSTEM} --- Execute a shell command
10695 @cindex system, system call
10698 @item @emph{Description}:
10699 Passes the command @var{COMMAND} to a shell (see @code{system(3)}). If
10700 argument @var{STATUS} is present, it contains the value returned by
10701 @code{system(3)}, which is presumably 0 if the shell command succeeded.
10702 Note that which shell is used to invoke the command is system-dependent
10703 and environment-dependent.
10705 This intrinsic is provided in both subroutine and function forms;
10706 however, only one form can be used in any given program unit.
10708 @item @emph{Standard}:
10711 @item @emph{Class}:
10712 Subroutine, function
10714 @item @emph{Syntax}:
10715 @multitable @columnfractions .80
10716 @item @code{CALL SYSTEM(COMMAND [, STATUS])}
10717 @item @code{STATUS = SYSTEM(COMMAND)}
10720 @item @emph{Arguments}:
10721 @multitable @columnfractions .15 .70
10722 @item @var{COMMAND} @tab Shall be of default @code{CHARACTER} type.
10723 @item @var{STATUS} @tab (Optional) Shall be of default @code{INTEGER} type.
10726 @item @emph{See also}:
10732 @section @code{SYSTEM_CLOCK} --- Time function
10733 @fnindex SYSTEM_CLOCK
10734 @cindex time, clock ticks
10735 @cindex clock ticks
10738 @item @emph{Description}:
10739 Determines the @var{COUNT} of milliseconds of wall clock time since
10740 the Epoch (00:00:00 UTC, January 1, 1970) modulo @var{COUNT_MAX},
10741 @var{COUNT_RATE} determines the number of clock ticks per second.
10742 @var{COUNT_RATE} and @var{COUNT_MAX} are constant and specific to
10743 @command{gfortran}.
10745 If there is no clock, @var{COUNT} is set to @code{-HUGE(COUNT)}, and
10746 @var{COUNT_RATE} and @var{COUNT_MAX} are set to zero
10748 @item @emph{Standard}:
10749 Fortran 95 and later
10751 @item @emph{Class}:
10754 @item @emph{Syntax}:
10755 @code{CALL SYSTEM_CLOCK([COUNT, COUNT_RATE, COUNT_MAX])}
10757 @item @emph{Arguments}:
10758 @multitable @columnfractions .15 .70
10759 @item @var{COUNT} @tab (Optional) shall be a scalar of type default
10760 @code{INTEGER} with @code{INTENT(OUT)}.
10761 @item @var{COUNT_RATE} @tab (Optional) shall be a scalar of type default
10762 @code{INTEGER} with @code{INTENT(OUT)}.
10763 @item @var{COUNT_MAX} @tab (Optional) shall be a scalar of type default
10764 @code{INTEGER} with @code{INTENT(OUT)}.
10767 @item @emph{Example}:
10769 PROGRAM test_system_clock
10770 INTEGER :: count, count_rate, count_max
10771 CALL SYSTEM_CLOCK(count, count_rate, count_max)
10772 WRITE(*,*) count, count_rate, count_max
10776 @item @emph{See also}:
10777 @ref{DATE_AND_TIME}, @ref{CPU_TIME}
10783 @section @code{TAN} --- Tangent function
10786 @cindex trigonometric function, tangent
10790 @item @emph{Description}:
10791 @code{TAN(X)} computes the tangent of @var{X}.
10793 @item @emph{Standard}:
10794 Fortran 77 and later, for a complex argument Fortran 2008 or later
10796 @item @emph{Class}:
10799 @item @emph{Syntax}:
10800 @code{RESULT = TAN(X)}
10802 @item @emph{Arguments}:
10803 @multitable @columnfractions .15 .70
10804 @item @var{X} @tab The type shall be @code{REAL} or @code{COMPLEX}.
10807 @item @emph{Return value}:
10808 The return value has same type and kind as @var{X}.
10810 @item @emph{Example}:
10813 real(8) :: x = 0.165_8
10815 end program test_tan
10818 @item @emph{Specific names}:
10819 @multitable @columnfractions .20 .20 .20 .25
10820 @item Name @tab Argument @tab Return type @tab Standard
10821 @item @code{TAN(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab Fortran 95 and later
10822 @item @code{DTAN(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab Fortran 95 and later
10825 @item @emph{See also}:
10832 @section @code{TANH} --- Hyperbolic tangent function
10835 @cindex hyperbolic tangent
10836 @cindex hyperbolic function, tangent
10837 @cindex tangent, hyperbolic
10840 @item @emph{Description}:
10841 @code{TANH(X)} computes the hyperbolic tangent of @var{X}.
10843 @item @emph{Standard}:
10844 Fortran 77 and later, for a complex argument Fortran 2008 or later
10846 @item @emph{Class}:
10849 @item @emph{Syntax}:
10852 @item @emph{Arguments}:
10853 @multitable @columnfractions .15 .70
10854 @item @var{X} @tab The type shall be @code{REAL} or @code{COMPLEX}.
10857 @item @emph{Return value}:
10858 The return value has same type and kind as @var{X}. If @var{X} is
10859 complex, the imaginary part of the result is in radians. If @var{X}
10860 is @code{REAL}, the return value lies in the range
10861 @math{ - 1 \leq tanh(x) \leq 1 }.
10863 @item @emph{Example}:
10866 real(8) :: x = 2.1_8
10868 end program test_tanh
10871 @item @emph{Specific names}:
10872 @multitable @columnfractions .20 .20 .20 .25
10873 @item Name @tab Argument @tab Return type @tab Standard
10874 @item @code{TANH(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab Fortran 95 and later
10875 @item @code{DTANH(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab Fortran 95 and later
10878 @item @emph{See also}:
10885 @section @code{THIS_IMAGE} --- Function that returns the cosubscript index of this image
10886 @fnindex THIS_IMAGE
10887 @cindex coarray, THIS_IMAGE
10888 @cindex images, index of this image
10891 @item @emph{Description}:
10892 Returns the cosubscript for this image.
10894 @item @emph{Standard}:
10895 Fortran 2008 and later
10897 @item @emph{Class}:
10898 Transformational function
10900 @item @emph{Syntax}:
10901 @multitable @columnfractions .80
10902 @item @code{RESULT = THIS_IMAGE()}
10903 @item @code{RESULT = THIS_IMAGE(COARRAY [, DIM])}
10906 @item @emph{Arguments}:
10907 @multitable @columnfractions .15 .70
10908 @item @var{COARRAY} @tab Coarray of any type (optional; if @var{DIM}
10909 present, required).
10910 @item @var{DIM} @tab default integer scalar (optional). If present,
10911 @var{DIM} shall be between one and the corank of @var{COARRAY}.
10915 @item @emph{Return value}:
10916 Default integer. If @var{COARRAY} is not present, it is scalar and its value
10917 is the index of the invoking image. Otherwise, if @var{DIM} is not present,
10918 a rank-1 array with corank elements is returned, containing the cosubscripts
10919 for @var{COARRAY} specifying the invoking image. If @var{DIM} is present,
10920 a scalar is returned, with the value of the @var{DIM} element of
10921 @code{THIS_IMAGE(COARRAY)}.
10923 @item @emph{Example}:
10925 INTEGER :: value[*]
10927 value = THIS_IMAGE()
10929 IF (THIS_IMAGE() == 1) THEN
10930 DO i = 1, NUM_IMAGES()
10931 WRITE(*,'(2(a,i0))') 'value[', i, '] is ', value[i]
10936 @item @emph{See also}:
10937 @ref{NUM_IMAGES}, @ref{IMAGE_INDEX}
10943 @section @code{TIME} --- Time function
10945 @cindex time, current
10946 @cindex current time
10949 @item @emph{Description}:
10950 Returns the current time encoded as an integer (in the manner of the
10951 UNIX function @code{time(3)}). This value is suitable for passing to
10952 @code{CTIME()}, @code{GMTIME()}, and @code{LTIME()}.
10954 This intrinsic is not fully portable, such as to systems with 32-bit
10955 @code{INTEGER} types but supporting times wider than 32 bits. Therefore,
10956 the values returned by this intrinsic might be, or become, negative, or
10957 numerically less than previous values, during a single run of the
10960 See @ref{TIME8}, for information on a similar intrinsic that might be
10961 portable to more GNU Fortran implementations, though to fewer Fortran
10964 @item @emph{Standard}:
10967 @item @emph{Class}:
10970 @item @emph{Syntax}:
10971 @code{RESULT = TIME()}
10973 @item @emph{Return value}:
10974 The return value is a scalar of type @code{INTEGER(4)}.
10976 @item @emph{See also}:
10977 @ref{CTIME}, @ref{GMTIME}, @ref{LTIME}, @ref{MCLOCK}, @ref{TIME8}
10984 @section @code{TIME8} --- Time function (64-bit)
10986 @cindex time, current
10987 @cindex current time
10990 @item @emph{Description}:
10991 Returns the current time encoded as an integer (in the manner of the
10992 UNIX function @code{time(3)}). This value is suitable for passing to
10993 @code{CTIME()}, @code{GMTIME()}, and @code{LTIME()}.
10995 @emph{Warning:} this intrinsic does not increase the range of the timing
10996 values over that returned by @code{time(3)}. On a system with a 32-bit
10997 @code{time(3)}, @code{TIME8()} will return a 32-bit value, even though
10998 it is converted to a 64-bit @code{INTEGER(8)} value. That means
10999 overflows of the 32-bit value can still occur. Therefore, the values
11000 returned by this intrinsic might be or become negative or numerically
11001 less than previous values during a single run of the compiled program.
11003 @item @emph{Standard}:
11006 @item @emph{Class}:
11009 @item @emph{Syntax}:
11010 @code{RESULT = TIME8()}
11012 @item @emph{Return value}:
11013 The return value is a scalar of type @code{INTEGER(8)}.
11015 @item @emph{See also}:
11016 @ref{CTIME}, @ref{GMTIME}, @ref{LTIME}, @ref{MCLOCK8}, @ref{TIME}
11023 @section @code{TINY} --- Smallest positive number of a real kind
11025 @cindex limits, smallest number
11026 @cindex model representation, smallest number
11029 @item @emph{Description}:
11030 @code{TINY(X)} returns the smallest positive (non zero) number
11031 in the model of the type of @code{X}.
11033 @item @emph{Standard}:
11034 Fortran 95 and later
11036 @item @emph{Class}:
11039 @item @emph{Syntax}:
11040 @code{RESULT = TINY(X)}
11042 @item @emph{Arguments}:
11043 @multitable @columnfractions .15 .70
11044 @item @var{X} @tab Shall be of type @code{REAL}.
11047 @item @emph{Return value}:
11048 The return value is of the same type and kind as @var{X}
11050 @item @emph{Example}:
11051 See @code{HUGE} for an example.
11057 @section @code{TRAILZ} --- Number of trailing zero bits of an integer
11062 @item @emph{Description}:
11063 @code{TRAILZ} returns the number of trailing zero bits of an integer.
11065 @item @emph{Standard}:
11066 Fortran 2008 and later
11068 @item @emph{Class}:
11071 @item @emph{Syntax}:
11072 @code{RESULT = TRAILZ(I)}
11074 @item @emph{Arguments}:
11075 @multitable @columnfractions .15 .70
11076 @item @var{I} @tab Shall be of type @code{INTEGER}.
11079 @item @emph{Return value}:
11080 The type of the return value is the default @code{INTEGER}.
11081 If all the bits of @code{I} are zero, the result value is @code{BIT_SIZE(I)}.
11083 @item @emph{Example}:
11085 PROGRAM test_trailz
11086 WRITE (*,*) TRAILZ(8) ! prints 3
11090 @item @emph{See also}:
11091 @ref{BIT_SIZE}, @ref{LEADZ}
11097 @section @code{TRANSFER} --- Transfer bit patterns
11103 @item @emph{Description}:
11104 Interprets the bitwise representation of @var{SOURCE} in memory as if it
11105 is the representation of a variable or array of the same type and type
11106 parameters as @var{MOLD}.
11108 This is approximately equivalent to the C concept of @emph{casting} one
11111 @item @emph{Standard}:
11112 Fortran 95 and later
11114 @item @emph{Class}:
11115 Transformational function
11117 @item @emph{Syntax}:
11118 @code{RESULT = TRANSFER(SOURCE, MOLD[, SIZE])}
11120 @item @emph{Arguments}:
11121 @multitable @columnfractions .15 .70
11122 @item @var{SOURCE} @tab Shall be a scalar or an array of any type.
11123 @item @var{MOLD} @tab Shall be a scalar or an array of any type.
11124 @item @var{SIZE} @tab (Optional) shall be a scalar of type
11128 @item @emph{Return value}:
11129 The result has the same type as @var{MOLD}, with the bit level
11130 representation of @var{SOURCE}. If @var{SIZE} is present, the result is
11131 a one-dimensional array of length @var{SIZE}. If @var{SIZE} is absent
11132 but @var{MOLD} is an array (of any size or shape), the result is a one-
11133 dimensional array of the minimum length needed to contain the entirety
11134 of the bitwise representation of @var{SOURCE}. If @var{SIZE} is absent
11135 and @var{MOLD} is a scalar, the result is a scalar.
11137 If the bitwise representation of the result is longer than that of
11138 @var{SOURCE}, then the leading bits of the result correspond to those of
11139 @var{SOURCE} and any trailing bits are filled arbitrarily.
11141 When the resulting bit representation does not correspond to a valid
11142 representation of a variable of the same type as @var{MOLD}, the results
11143 are undefined, and subsequent operations on the result cannot be
11144 guaranteed to produce sensible behavior. For example, it is possible to
11145 create @code{LOGICAL} variables for which @code{@var{VAR}} and
11146 @code{.NOT.@var{VAR}} both appear to be true.
11148 @item @emph{Example}:
11150 PROGRAM test_transfer
11151 integer :: x = 2143289344
11152 print *, transfer(x, 1.0) ! prints "NaN" on i686
11160 @section @code{TRANSPOSE} --- Transpose an array of rank two
11162 @cindex array, transpose
11163 @cindex matrix, transpose
11167 @item @emph{Description}:
11168 Transpose an array of rank two. Element (i, j) of the result has the value
11169 @code{MATRIX(j, i)}, for all i, j.
11171 @item @emph{Standard}:
11172 Fortran 95 and later
11174 @item @emph{Class}:
11175 Transformational function
11177 @item @emph{Syntax}:
11178 @code{RESULT = TRANSPOSE(MATRIX)}
11180 @item @emph{Arguments}:
11181 @multitable @columnfractions .15 .70
11182 @item @var{MATRIX} @tab Shall be an array of any type and have a rank of two.
11185 @item @emph{Return value}:
11186 The result has the same type as @var{MATRIX}, and has shape
11187 @code{(/ m, n /)} if @var{MATRIX} has shape @code{(/ n, m /)}.
11193 @section @code{TRIM} --- Remove trailing blank characters of a string
11195 @cindex string, remove trailing whitespace
11198 @item @emph{Description}:
11199 Removes trailing blank characters of a string.
11201 @item @emph{Standard}:
11202 Fortran 95 and later
11204 @item @emph{Class}:
11205 Transformational function
11207 @item @emph{Syntax}:
11208 @code{RESULT = TRIM(STRING)}
11210 @item @emph{Arguments}:
11211 @multitable @columnfractions .15 .70
11212 @item @var{STRING} @tab Shall be a scalar of type @code{CHARACTER}.
11215 @item @emph{Return value}:
11216 A scalar of type @code{CHARACTER} which length is that of @var{STRING}
11217 less the number of trailing blanks.
11219 @item @emph{Example}:
11222 CHARACTER(len=10), PARAMETER :: s = "GFORTRAN "
11223 WRITE(*,*) LEN(s), LEN(TRIM(s)) ! "10 8", with/without trailing blanks
11227 @item @emph{See also}:
11228 @ref{ADJUSTL}, @ref{ADJUSTR}
11234 @section @code{TTYNAM} --- Get the name of a terminal device.
11236 @cindex system, terminal
11239 @item @emph{Description}:
11240 Get the name of a terminal device. For more information,
11241 see @code{ttyname(3)}.
11243 This intrinsic is provided in both subroutine and function forms;
11244 however, only one form can be used in any given program unit.
11246 @item @emph{Standard}:
11249 @item @emph{Class}:
11250 Subroutine, function
11252 @item @emph{Syntax}:
11253 @multitable @columnfractions .80
11254 @item @code{CALL TTYNAM(UNIT, NAME)}
11255 @item @code{NAME = TTYNAM(UNIT)}
11258 @item @emph{Arguments}:
11259 @multitable @columnfractions .15 .70
11260 @item @var{UNIT} @tab Shall be a scalar @code{INTEGER}.
11261 @item @var{NAME} @tab Shall be of type @code{CHARACTER}.
11264 @item @emph{Example}:
11266 PROGRAM test_ttynam
11269 IF (isatty(unit=unit)) write(*,*) ttynam(unit)
11274 @item @emph{See also}:
11281 @section @code{UBOUND} --- Upper dimension bounds of an array
11283 @cindex array, upper bound
11286 @item @emph{Description}:
11287 Returns the upper bounds of an array, or a single upper bound
11288 along the @var{DIM} dimension.
11289 @item @emph{Standard}:
11290 Fortran 95 and later, with @var{KIND} argument Fortran 2003 and later
11292 @item @emph{Class}:
11295 @item @emph{Syntax}:
11296 @code{RESULT = UBOUND(ARRAY [, DIM [, KIND]])}
11298 @item @emph{Arguments}:
11299 @multitable @columnfractions .15 .70
11300 @item @var{ARRAY} @tab Shall be an array, of any type.
11301 @item @var{DIM} @tab (Optional) Shall be a scalar @code{INTEGER}.
11302 @item @var{KIND}@tab (Optional) An @code{INTEGER} initialization
11303 expression indicating the kind parameter of the result.
11306 @item @emph{Return value}:
11307 The return value is of type @code{INTEGER} and of kind @var{KIND}. If
11308 @var{KIND} is absent, the return value is of default integer kind.
11309 If @var{DIM} is absent, the result is an array of the upper bounds of
11310 @var{ARRAY}. If @var{DIM} is present, the result is a scalar
11311 corresponding to the upper bound of the array along that dimension. If
11312 @var{ARRAY} is an expression rather than a whole array or array
11313 structure component, or if it has a zero extent along the relevant
11314 dimension, the upper bound is taken to be the number of elements along
11315 the relevant dimension.
11317 @item @emph{See also}:
11318 @ref{LBOUND}, @ref{LCOBOUND}
11324 @section @code{UCOBOUND} --- Upper codimension bounds of an array
11326 @cindex coarray, upper bound
11329 @item @emph{Description}:
11330 Returns the upper cobounds of a coarray, or a single upper cobound
11331 along the @var{DIM} codimension.
11332 @item @emph{Standard}:
11333 Fortran 2008 and later
11335 @item @emph{Class}:
11338 @item @emph{Syntax}:
11339 @code{RESULT = UCOBOUND(COARRAY [, DIM [, KIND]])}
11341 @item @emph{Arguments}:
11342 @multitable @columnfractions .15 .70
11343 @item @var{ARRAY} @tab Shall be an coarray, of any type.
11344 @item @var{DIM} @tab (Optional) Shall be a scalar @code{INTEGER}.
11345 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
11346 expression indicating the kind parameter of the result.
11349 @item @emph{Return value}:
11350 The return value is of type @code{INTEGER} and of kind @var{KIND}. If
11351 @var{KIND} is absent, the return value is of default integer kind.
11352 If @var{DIM} is absent, the result is an array of the lower cobounds of
11353 @var{COARRAY}. If @var{DIM} is present, the result is a scalar
11354 corresponding to the lower cobound of the array along that codimension.
11356 @item @emph{See also}:
11357 @ref{LCOBOUND}, @ref{LBOUND}
11363 @section @code{UMASK} --- Set the file creation mask
11365 @cindex file system, file creation mask
11368 @item @emph{Description}:
11369 Sets the file creation mask to @var{MASK}. If called as a function, it
11370 returns the old value. If called as a subroutine and argument @var{OLD}
11371 if it is supplied, it is set to the old value. See @code{umask(2)}.
11373 @item @emph{Standard}:
11376 @item @emph{Class}:
11377 Subroutine, function
11379 @item @emph{Syntax}:
11380 @code{CALL UMASK(MASK [, OLD])}
11381 @code{OLD = UMASK(MASK)}
11383 @item @emph{Arguments}:
11384 @multitable @columnfractions .15 .70
11385 @item @var{MASK} @tab Shall be a scalar of type @code{INTEGER}.
11386 @item @var{OLD} @tab (Optional) Shall be a scalar of type
11395 @section @code{UNLINK} --- Remove a file from the file system
11397 @cindex file system, remove file
11400 @item @emph{Description}:
11401 Unlinks the file @var{PATH}. A null character (@code{CHAR(0)}) can be
11402 used to mark the end of the name in @var{PATH}; otherwise, trailing
11403 blanks in the file name are ignored. If the @var{STATUS} argument is
11404 supplied, it contains 0 on success or a nonzero error code upon return;
11405 see @code{unlink(2)}.
11407 This intrinsic is provided in both subroutine and function forms;
11408 however, only one form can be used in any given program unit.
11410 @item @emph{Standard}:
11413 @item @emph{Class}:
11414 Subroutine, function
11416 @item @emph{Syntax}:
11417 @multitable @columnfractions .80
11418 @item @code{CALL UNLINK(PATH [, STATUS])}
11419 @item @code{STATUS = UNLINK(PATH)}
11422 @item @emph{Arguments}:
11423 @multitable @columnfractions .15 .70
11424 @item @var{PATH} @tab Shall be of default @code{CHARACTER} type.
11425 @item @var{STATUS} @tab (Optional) Shall be of default @code{INTEGER} type.
11428 @item @emph{See also}:
11429 @ref{LINK}, @ref{SYMLNK}
11435 @section @code{UNPACK} --- Unpack an array of rank one into an array
11437 @cindex array, unpacking
11438 @cindex array, increase dimension
11439 @cindex array, scatter elements
11442 @item @emph{Description}:
11443 Store the elements of @var{VECTOR} in an array of higher rank.
11445 @item @emph{Standard}:
11446 Fortran 95 and later
11448 @item @emph{Class}:
11449 Transformational function
11451 @item @emph{Syntax}:
11452 @code{RESULT = UNPACK(VECTOR, MASK, FIELD)}
11454 @item @emph{Arguments}:
11455 @multitable @columnfractions .15 .70
11456 @item @var{VECTOR} @tab Shall be an array of any type and rank one. It
11457 shall have at least as many elements as @var{MASK} has @code{TRUE} values.
11458 @item @var{MASK} @tab Shall be an array of type @code{LOGICAL}.
11459 @item @var{FIELD} @tab Shall be of the same type as @var{VECTOR} and have
11460 the same shape as @var{MASK}.
11463 @item @emph{Return value}:
11464 The resulting array corresponds to @var{FIELD} with @code{TRUE} elements
11465 of @var{MASK} replaced by values from @var{VECTOR} in array element order.
11467 @item @emph{Example}:
11469 PROGRAM test_unpack
11470 integer :: vector(2) = (/1,1/)
11471 logical :: mask(4) = (/ .TRUE., .FALSE., .FALSE., .TRUE. /)
11472 integer :: field(2,2) = 0, unity(2,2)
11474 ! result: unity matrix
11475 unity = unpack(vector, reshape(mask, (/2,2/)), field)
11479 @item @emph{See also}:
11480 @ref{PACK}, @ref{SPREAD}
11486 @section @code{VERIFY} --- Scan a string for the absence of a set of characters
11488 @cindex string, find missing set
11491 @item @emph{Description}:
11492 Verifies that all the characters in a @var{SET} are present in a @var{STRING}.
11494 If @var{BACK} is either absent or equals @code{FALSE}, this function
11495 returns the position of the leftmost character of @var{STRING} that is
11496 not in @var{SET}. If @var{BACK} equals @code{TRUE}, the rightmost position
11497 is returned. If all characters of @var{SET} are found in @var{STRING}, the
11500 @item @emph{Standard}:
11501 Fortran 95 and later, with @var{KIND} argument Fortran 2003 and later
11503 @item @emph{Class}:
11506 @item @emph{Syntax}:
11507 @code{RESULT = VERIFY(STRING, SET[, BACK [, KIND]])}
11509 @item @emph{Arguments}:
11510 @multitable @columnfractions .15 .70
11511 @item @var{STRING} @tab Shall be of type @code{CHARACTER}.
11512 @item @var{SET} @tab Shall be of type @code{CHARACTER}.
11513 @item @var{BACK} @tab (Optional) shall be of type @code{LOGICAL}.
11514 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
11515 expression indicating the kind parameter of the result.
11518 @item @emph{Return value}:
11519 The return value is of type @code{INTEGER} and of kind @var{KIND}. If
11520 @var{KIND} is absent, the return value is of default integer kind.
11522 @item @emph{Example}:
11524 PROGRAM test_verify
11525 WRITE(*,*) VERIFY("FORTRAN", "AO") ! 1, found 'F'
11526 WRITE(*,*) VERIFY("FORTRAN", "FOO") ! 3, found 'R'
11527 WRITE(*,*) VERIFY("FORTRAN", "C++") ! 1, found 'F'
11528 WRITE(*,*) VERIFY("FORTRAN", "C++", .TRUE.) ! 7, found 'N'
11529 WRITE(*,*) VERIFY("FORTRAN", "FORTRAN") ! 0' found none
11533 @item @emph{See also}:
11534 @ref{SCAN}, @ref{INDEX intrinsic}
11540 @section @code{XOR} --- Bitwise logical exclusive OR
11542 @cindex bitwise logical exclusive or
11543 @cindex logical exclusive or, bitwise
11546 @item @emph{Description}:
11547 Bitwise logical exclusive or.
11549 This intrinsic routine is provided for backwards compatibility with
11550 GNU Fortran 77. For integer arguments, programmers should consider
11551 the use of the @ref{IEOR} intrinsic and for logical arguments the
11552 @code{.NEQV.} operator, which are both defined by the Fortran standard.
11554 @item @emph{Standard}:
11557 @item @emph{Class}:
11560 @item @emph{Syntax}:
11561 @code{RESULT = XOR(I, J)}
11563 @item @emph{Arguments}:
11564 @multitable @columnfractions .15 .70
11565 @item @var{I} @tab The type shall be either a scalar @code{INTEGER}
11566 type or a scalar @code{LOGICAL} type.
11567 @item @var{J} @tab The type shall be the same as the type of @var{I}.
11570 @item @emph{Return value}:
11571 The return type is either a scalar @code{INTEGER} or a scalar
11572 @code{LOGICAL}. If the kind type parameters differ, then the
11573 smaller kind type is implicitly converted to larger kind, and the
11574 return has the larger kind.
11576 @item @emph{Example}:
11579 LOGICAL :: T = .TRUE., F = .FALSE.
11581 DATA a / Z'F' /, b / Z'3' /
11583 WRITE (*,*) XOR(T, T), XOR(T, F), XOR(F, T), XOR(F, F)
11584 WRITE (*,*) XOR(a, b)
11588 @item @emph{See also}:
11589 Fortran 95 elemental function: @ref{IEOR}
11594 @node Intrinsic Modules
11595 @chapter Intrinsic Modules
11596 @cindex intrinsic Modules
11599 * ISO_FORTRAN_ENV::
11601 * OpenMP Modules OMP_LIB and OMP_LIB_KINDS::
11604 @node ISO_FORTRAN_ENV
11605 @section @code{ISO_FORTRAN_ENV}
11607 @item @emph{Standard}:
11608 Fortran 2003 and later, except when otherwise noted
11611 The @code{ISO_FORTRAN_ENV} module provides the following scalar default-integer
11615 @item @code{ATOMIC_INT_KIND}:
11616 Default-kind integer constant to be used as kind parameter when defining
11617 integer variables used in atomic operations. (Fortran 2008 or later.)
11619 @item @code{ATOMIC_LOGICAL_KIND}:
11620 Default-kind integer constant to be used as kind parameter when defining
11621 logical variables used in atomic operations. (Fortran 2008 or later.)
11623 @item @code{CHARACTER_STORAGE_SIZE}:
11624 Size in bits of the character storage unit.
11626 @item @code{ERROR_UNIT}:
11627 Identifies the preconnected unit used for error reporting.
11629 @item @code{FILE_STORAGE_SIZE}:
11630 Size in bits of the file-storage unit.
11632 @item @code{INPUT_UNIT}:
11633 Identifies the preconnected unit identified by the asterisk
11634 (@code{*}) in @code{READ} statement.
11636 @item @code{INT8}, @code{INT16}, @code{INT32}, @code{INT64}:
11637 Kind type parameters to specify an INTEGER type with a storage
11638 size of 16, 32, and 64 bits. It is negative if a target platform
11639 does not support the particular kind. (Fortran 2008 or later.)
11641 @item @code{IOSTAT_END}:
11642 The value assigned to the variable passed to the IOSTAT= specifier of
11643 an input/output statement if an end-of-file condition occurred.
11645 @item @code{IOSTAT_EOR}:
11646 The value assigned to the variable passed to the IOSTAT= specifier of
11647 an input/output statement if an end-of-record condition occurred.
11649 @item @code{IOSTAT_INQUIRE_INTERNAL_UNIT}:
11650 Scalar default-integer constant, used by @code{INQUIRE} for the
11651 IOSTAT= specifier to denote an that a unit number identifies an
11652 internal unit. (Fortran 2008 or later.)
11654 @item @code{NUMERIC_STORAGE_SIZE}:
11655 The size in bits of the numeric storage unit.
11657 @item @code{OUTPUT_UNIT}:
11658 Identifies the preconnected unit identified by the asterisk
11659 (@code{*}) in @code{WRITE} statement.
11661 @item @code{REAL32}, @code{REAL64}, @code{REAL128}:
11662 Kind type parameters to specify a REAL type with a storage
11663 size of 32, 64, and 128 bits. It is negative if a target platform
11664 does not support the particular kind. (Fortran 2008 or later.)
11666 @item @code{STAT_LOCKED}:
11667 Scalar default-integer constant used as STAT= return value by @code{LOCK} to
11668 denote that the lock variable is locked by the executing image. (Fortran 2008
11671 @item @code{STAT_LOCKED_OTHER_IMAGE}:
11672 Scalar default-integer constant used as STAT= return value by @code{UNLOCK} to
11673 denote that the lock variable is locked by another image. (Fortran 2008 or
11676 @item @code{STAT_STOPPED_IMAGE}:
11677 Positive, scalar default-integer constant used as STAT= return value if the
11678 argument in the statement requires synchronisation with an image, which has
11679 initiated the termination of the execution. (Fortran 2008 or later.)
11681 @item @code{STAT_UNLOCKED}:
11682 Scalar default-integer constant used as STAT= return value by @code{UNLOCK} to
11683 denote that the lock variable is unlocked. (Fortran 2008 or later.)
11688 @node ISO_C_BINDING
11689 @section @code{ISO_C_BINDING}
11691 @item @emph{Standard}:
11692 Fortran 2003 and later, GNU extensions
11695 The following intrinsic procedures are provided by the module; their
11696 definition can be found in the section Intrinsic Procedures of this
11700 @item @code{C_ASSOCIATED}
11701 @item @code{C_F_POINTER}
11702 @item @code{C_F_PROCPOINTER}
11703 @item @code{C_FUNLOC}
11706 @c TODO: Vertical spacing between C_FUNLOC and C_LOC wrong in PDF,
11707 @c don't really know why.
11709 The @code{ISO_C_BINDING} module provides the following named constants of
11710 type default integer, which can be used as KIND type parameters.
11712 In addition to the integer named constants required by the Fortran 2003
11713 standard, GNU Fortran provides as an extension named constants for the
11714 128-bit integer types supported by the C compiler: @code{C_INT128_T,
11715 C_INT_LEAST128_T, C_INT_FAST128_T}.
11717 @multitable @columnfractions .15 .35 .35 .35
11718 @item Fortran Type @tab Named constant @tab C type @tab Extension
11719 @item @code{INTEGER}@tab @code{C_INT} @tab @code{int}
11720 @item @code{INTEGER}@tab @code{C_SHORT} @tab @code{short int}
11721 @item @code{INTEGER}@tab @code{C_LONG} @tab @code{long int}
11722 @item @code{INTEGER}@tab @code{C_LONG_LONG} @tab @code{long long int}
11723 @item @code{INTEGER}@tab @code{C_SIGNED_CHAR} @tab @code{signed char}/@code{unsigned char}
11724 @item @code{INTEGER}@tab @code{C_SIZE_T} @tab @code{size_t}
11725 @item @code{INTEGER}@tab @code{C_INT8_T} @tab @code{int8_t}
11726 @item @code{INTEGER}@tab @code{C_INT16_T} @tab @code{int16_t}
11727 @item @code{INTEGER}@tab @code{C_INT32_T} @tab @code{int32_t}
11728 @item @code{INTEGER}@tab @code{C_INT64_T} @tab @code{int64_t}
11729 @item @code{INTEGER}@tab @code{C_INT128_T} @tab @code{int128_t} @tab Ext.
11730 @item @code{INTEGER}@tab @code{C_INT_LEAST8_T} @tab @code{int_least8_t}
11731 @item @code{INTEGER}@tab @code{C_INT_LEAST16_T} @tab @code{int_least16_t}
11732 @item @code{INTEGER}@tab @code{C_INT_LEAST32_T} @tab @code{int_least32_t}
11733 @item @code{INTEGER}@tab @code{C_INT_LEAST64_T} @tab @code{int_least64_t}
11734 @item @code{INTEGER}@tab @code{C_INT_LEAST128_T}@tab @code{int_least128_t} @tab Ext.
11735 @item @code{INTEGER}@tab @code{C_INT_FAST8_T} @tab @code{int_fast8_t}
11736 @item @code{INTEGER}@tab @code{C_INT_FAST16_T} @tab @code{int_fast16_t}
11737 @item @code{INTEGER}@tab @code{C_INT_FAST32_T} @tab @code{int_fast32_t}
11738 @item @code{INTEGER}@tab @code{C_INT_FAST64_T} @tab @code{int_fast64_t}
11739 @item @code{INTEGER}@tab @code{C_INT_FAST128_T} @tab @code{int_fast128_t} @tab Ext.
11740 @item @code{INTEGER}@tab @code{C_INTMAX_T} @tab @code{intmax_t}
11741 @item @code{INTEGER}@tab @code{C_INTPTR_T} @tab @code{intptr_t}
11742 @item @code{REAL} @tab @code{C_FLOAT} @tab @code{float}
11743 @item @code{REAL} @tab @code{C_DOUBLE} @tab @code{double}
11744 @item @code{REAL} @tab @code{C_LONG_DOUBLE} @tab @code{long double}
11745 @item @code{COMPLEX}@tab @code{C_FLOAT_COMPLEX} @tab @code{float _Complex}
11746 @item @code{COMPLEX}@tab @code{C_DOUBLE_COMPLEX}@tab @code{double _Complex}
11747 @item @code{COMPLEX}@tab @code{C_LONG_DOUBLE_COMPLEX}@tab @code{long double _Complex}
11748 @item @code{LOGICAL}@tab @code{C_BOOL} @tab @code{_Bool}
11749 @item @code{CHARACTER}@tab @code{C_CHAR} @tab @code{char}
11752 Additionally, the following parameters of type @code{CHARACTER(KIND=C_CHAR)}
11755 @multitable @columnfractions .20 .45 .15
11756 @item Name @tab C definition @tab Value
11757 @item @code{C_NULL_CHAR} @tab null character @tab @code{'\0'}
11758 @item @code{C_ALERT} @tab alert @tab @code{'\a'}
11759 @item @code{C_BACKSPACE} @tab backspace @tab @code{'\b'}
11760 @item @code{C_FORM_FEED} @tab form feed @tab @code{'\f'}
11761 @item @code{C_NEW_LINE} @tab new line @tab @code{'\n'}
11762 @item @code{C_CARRIAGE_RETURN} @tab carriage return @tab @code{'\r'}
11763 @item @code{C_HORIZONTAL_TAB} @tab horizontal tab @tab @code{'\t'}
11764 @item @code{C_VERTICAL_TAB} @tab vertical tab @tab @code{'\v'}
11767 Moreover, the following two named constants are defined:
11769 @multitable @columnfractions .20 .80
11770 @item Name @tab Type
11771 @item @code{C_NULL_PTR} @tab @code{C_PTR}
11772 @item @code{C_NULL_FUNPTR} @tab @code{C_FUNPTR}
11775 Both are equivalent to the value @code{NULL} in C.
11777 @node OpenMP Modules OMP_LIB and OMP_LIB_KINDS
11778 @section OpenMP Modules @code{OMP_LIB} and @code{OMP_LIB_KINDS}
11780 @item @emph{Standard}:
11781 OpenMP Application Program Interface v3.0
11785 The OpenMP Fortran runtime library routines are provided both in
11786 a form of two Fortran 90 modules, named @code{OMP_LIB} and
11787 @code{OMP_LIB_KINDS}, and in a form of a Fortran @code{include} file named
11788 @file{omp_lib.h}. The procedures provided by @code{OMP_LIB} can be found
11789 in the @ref{Top,,Introduction,libgomp,GNU OpenMP runtime library} manual,
11790 the named constants defined in the @code{OMP_LIB_KINDS} module are listed
11793 For details refer to the actual
11794 @uref{http://www.openmp.org/mp-documents/spec30.pdf,
11795 OpenMP Application Program Interface v3.0}.
11797 @code{OMP_LIB_KINDS} provides the following scalar default-integer
11801 @item @code{omp_integer_kind}
11802 @item @code{omp_logical_kind}
11803 @item @code{omp_lock_kind}
11804 @item @code{omp_nest_lock_kind}
11805 @item @code{omp_sched_kind}