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, Inverse hyperbolic cosine 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, Inverse hyperbolic sine 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, Inverse hyperbolic tangent 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} --- Inverse hyperbolic cosine function
585 @cindex area hyperbolic cosine
586 @cindex inverse hyperbolic cosine
587 @cindex hyperbolic function, cosine, inverse
588 @cindex cosine, hyperbolic, inverse
591 @item @emph{Description}:
592 @code{ACOSH(X)} computes the inverse hyperbolic cosine of @var{X}.
594 @item @emph{Standard}:
595 Fortran 2008 and later
601 @code{RESULT = ACOSH(X)}
603 @item @emph{Arguments}:
604 @multitable @columnfractions .15 .70
605 @item @var{X} @tab The type shall be @code{REAL} or @code{COMPLEX}.
608 @item @emph{Return value}:
609 The return value has the same type and kind as @var{X}. If @var{X} is
610 complex, the imaginary part of the result is in radians and lies between
611 @math{ 0 \leq \Im \acosh(x) \leq \pi}.
613 @item @emph{Example}:
616 REAL(8), DIMENSION(3) :: x = (/ 1.0, 2.0, 3.0 /)
621 @item @emph{Specific names}:
622 @multitable @columnfractions .20 .20 .20 .25
623 @item Name @tab Argument @tab Return type @tab Standard
624 @item @code{DACOSH(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU extension
627 @item @emph{See also}:
628 Inverse function: @ref{COSH}
634 @section @code{ADJUSTL} --- Left adjust a string
636 @cindex string, adjust left
637 @cindex adjust string
640 @item @emph{Description}:
641 @code{ADJUSTL(STRING)} will left adjust a string by removing leading spaces.
642 Spaces are inserted at the end of the string as needed.
644 @item @emph{Standard}:
651 @code{RESULT = ADJUSTL(STRING)}
653 @item @emph{Arguments}:
654 @multitable @columnfractions .15 .70
655 @item @var{STRING} @tab The type shall be @code{CHARACTER}.
658 @item @emph{Return value}:
659 The return value is of type @code{CHARACTER} and of the same kind as
660 @var{STRING} where leading spaces are removed and the same number of
661 spaces are inserted on the end of @var{STRING}.
663 @item @emph{Example}:
666 character(len=20) :: str = ' gfortran'
669 end program test_adjustl
672 @item @emph{See also}:
673 @ref{ADJUSTR}, @ref{TRIM}
679 @section @code{ADJUSTR} --- Right adjust a string
681 @cindex string, adjust right
682 @cindex adjust string
685 @item @emph{Description}:
686 @code{ADJUSTR(STRING)} will right adjust a string by removing trailing spaces.
687 Spaces are inserted at the start of the string as needed.
689 @item @emph{Standard}:
696 @code{RESULT = ADJUSTR(STRING)}
698 @item @emph{Arguments}:
699 @multitable @columnfractions .15 .70
700 @item @var{STR} @tab The type shall be @code{CHARACTER}.
703 @item @emph{Return value}:
704 The return value is of type @code{CHARACTER} and of the same kind as
705 @var{STRING} where trailing spaces are removed and the same number of
706 spaces are inserted at the start of @var{STRING}.
708 @item @emph{Example}:
711 character(len=20) :: str = 'gfortran'
714 end program test_adjustr
717 @item @emph{See also}:
718 @ref{ADJUSTL}, @ref{TRIM}
724 @section @code{AIMAG} --- Imaginary part of complex number
729 @cindex complex numbers, imaginary part
732 @item @emph{Description}:
733 @code{AIMAG(Z)} yields the imaginary part of complex argument @code{Z}.
734 The @code{IMAG(Z)} and @code{IMAGPART(Z)} intrinsic functions are provided
735 for compatibility with @command{g77}, and their use in new code is
736 strongly discouraged.
738 @item @emph{Standard}:
739 Fortran 77 and later, has overloads that are GNU extensions
745 @code{RESULT = AIMAG(Z)}
747 @item @emph{Arguments}:
748 @multitable @columnfractions .15 .70
749 @item @var{Z} @tab The type of the argument shall be @code{COMPLEX}.
752 @item @emph{Return value}:
753 The return value is of type @code{REAL} with the
754 kind type parameter of the argument.
756 @item @emph{Example}:
761 z4 = cmplx(1.e0_4, 0.e0_4)
762 z8 = cmplx(0.e0_8, 1.e0_8)
763 print *, aimag(z4), dimag(z8)
764 end program test_aimag
767 @item @emph{Specific names}:
768 @multitable @columnfractions .20 .20 .20 .25
769 @item Name @tab Argument @tab Return type @tab Standard
770 @item @code{AIMAG(Z)} @tab @code{COMPLEX Z} @tab @code{REAL} @tab GNU extension
771 @item @code{DIMAG(Z)} @tab @code{COMPLEX(8) Z} @tab @code{REAL(8)} @tab GNU extension
772 @item @code{IMAG(Z)} @tab @code{COMPLEX Z} @tab @code{REAL} @tab GNU extension
773 @item @code{IMAGPART(Z)} @tab @code{COMPLEX Z} @tab @code{REAL} @tab GNU extension
780 @section @code{AINT} --- Truncate to a whole number
784 @cindex rounding, floor
787 @item @emph{Description}:
788 @code{AINT(A [, KIND])} truncates its argument to a whole number.
790 @item @emph{Standard}:
797 @code{RESULT = AINT(A [, KIND])}
799 @item @emph{Arguments}:
800 @multitable @columnfractions .15 .70
801 @item @var{A} @tab The type of the argument shall be @code{REAL}.
802 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
803 expression indicating the kind parameter of the result.
806 @item @emph{Return value}:
807 The return value is of type @code{REAL} with the kind type parameter of the
808 argument if the optional @var{KIND} is absent; otherwise, the kind
809 type parameter will be given by @var{KIND}. If the magnitude of
810 @var{X} is less than one, @code{AINT(X)} returns zero. If the
811 magnitude is equal to or greater than one then it returns the largest
812 whole number that does not exceed its magnitude. The sign is the same
813 as the sign of @var{X}.
815 @item @emph{Example}:
822 print *, aint(x4), dint(x8)
824 end program test_aint
827 @item @emph{Specific names}:
828 @multitable @columnfractions .20 .20 .20 .25
829 @item Name @tab Argument @tab Return type @tab Standard
830 @item @code{AINT(A)} @tab @code{REAL(4) A} @tab @code{REAL(4)} @tab Fortran 77 and later
831 @item @code{DINT(A)} @tab @code{REAL(8) A} @tab @code{REAL(8)} @tab Fortran 77 and later
838 @section @code{ALARM} --- Execute a routine after a given delay
840 @cindex delayed execution
843 @item @emph{Description}:
844 @code{ALARM(SECONDS, HANDLER [, STATUS])} causes external subroutine @var{HANDLER}
845 to be executed after a delay of @var{SECONDS} by using @code{alarm(2)} to
846 set up a signal and @code{signal(2)} to catch it. If @var{STATUS} is
847 supplied, it will be returned with the number of seconds remaining until
848 any previously scheduled alarm was due to be delivered, or zero if there
849 was no previously scheduled alarm.
851 @item @emph{Standard}:
858 @code{CALL ALARM(SECONDS, HANDLER [, STATUS])}
860 @item @emph{Arguments}:
861 @multitable @columnfractions .15 .70
862 @item @var{SECONDS} @tab The type of the argument shall be a scalar
863 @code{INTEGER}. It is @code{INTENT(IN)}.
864 @item @var{HANDLER} @tab Signal handler (@code{INTEGER FUNCTION} or
865 @code{SUBROUTINE}) or dummy/global @code{INTEGER} scalar. The scalar
866 values may be either @code{SIG_IGN=1} to ignore the alarm generated
867 or @code{SIG_DFL=0} to set the default action. It is @code{INTENT(IN)}.
868 @item @var{STATUS} @tab (Optional) @var{STATUS} shall be a scalar
869 variable of the default @code{INTEGER} kind. It is @code{INTENT(OUT)}.
872 @item @emph{Example}:
875 external handler_print
877 call alarm (3, handler_print, i)
880 end program test_alarm
882 This will cause the external routine @var{handler_print} to be called
889 @section @code{ALL} --- All values in @var{MASK} along @var{DIM} are true
891 @cindex array, apply condition
892 @cindex array, condition testing
895 @item @emph{Description}:
896 @code{ALL(MASK [, DIM])} determines if all the values are true in @var{MASK}
897 in the array along dimension @var{DIM}.
899 @item @emph{Standard}:
903 Transformational function
906 @code{RESULT = ALL(MASK [, DIM])}
908 @item @emph{Arguments}:
909 @multitable @columnfractions .15 .70
910 @item @var{MASK} @tab The type of the argument shall be @code{LOGICAL} and
911 it shall not be scalar.
912 @item @var{DIM} @tab (Optional) @var{DIM} shall be a scalar integer
913 with a value that lies between one and the rank of @var{MASK}.
916 @item @emph{Return value}:
917 @code{ALL(MASK)} returns a scalar value of type @code{LOGICAL} where
918 the kind type parameter is the same as the kind type parameter of
919 @var{MASK}. If @var{DIM} is present, then @code{ALL(MASK, DIM)} returns
920 an array with the rank of @var{MASK} minus 1. The shape is determined from
921 the shape of @var{MASK} where the @var{DIM} dimension is elided.
925 @code{ALL(MASK)} is true if all elements of @var{MASK} are true.
926 It also is true if @var{MASK} has zero size; otherwise, it is false.
928 If the rank of @var{MASK} is one, then @code{ALL(MASK,DIM)} is equivalent
929 to @code{ALL(MASK)}. If the rank is greater than one, then @code{ALL(MASK,DIM)}
930 is determined by applying @code{ALL} to the array sections.
933 @item @emph{Example}:
937 l = all((/.true., .true., .true./))
942 integer a(2,3), b(2,3)
946 print *, all(a .eq. b, 1)
947 print *, all(a .eq. b, 2)
948 end subroutine section
956 @section @code{ALLOCATED} --- Status of an allocatable entity
958 @cindex allocation, status
961 @item @emph{Description}:
962 @code{ALLOCATED(ARRAY)} and @code{ALLOCATED(SCALAR)} check the allocation
963 status of @var{ARRAY} and @var{SCALAR}, respectively.
965 @item @emph{Standard}:
966 Fortran 95 and later. Note, the @code{SCALAR=} keyword and allocatable
967 scalar entities are available in Fortran 2003 and later.
973 @code{RESULT = ALLOCATED(ARRAY)} or @code{RESULT = ALLOCATED(SCALAR)}
975 @item @emph{Arguments}:
976 @multitable @columnfractions .15 .70
977 @item @var{ARRAY} @tab The argument shall be an @code{ALLOCATABLE} array.
978 @item @var{SCALAR} @tab The argument shall be an @code{ALLOCATABLE} scalar.
981 @item @emph{Return value}:
982 The return value is a scalar @code{LOGICAL} with the default logical
983 kind type parameter. If the argument is allocated, then the result is
984 @code{.TRUE.}; otherwise, it returns @code{.FALSE.}
986 @item @emph{Example}:
988 program test_allocated
990 real(4), allocatable :: x(:)
991 if (.not. allocated(x)) allocate(x(i))
992 end program test_allocated
999 @section @code{AND} --- Bitwise logical AND
1001 @cindex bitwise logical and
1002 @cindex logical and, bitwise
1005 @item @emph{Description}:
1006 Bitwise logical @code{AND}.
1008 This intrinsic routine is provided for backwards compatibility with
1009 GNU Fortran 77. For integer arguments, programmers should consider
1010 the use of the @ref{IAND} intrinsic defined by the Fortran standard.
1012 @item @emph{Standard}:
1018 @item @emph{Syntax}:
1019 @code{RESULT = AND(I, J)}
1021 @item @emph{Arguments}:
1022 @multitable @columnfractions .15 .70
1023 @item @var{I} @tab The type shall be either a scalar @code{INTEGER}
1024 type or a scalar @code{LOGICAL} type.
1025 @item @var{J} @tab The type shall be the same as the type of @var{I}.
1028 @item @emph{Return value}:
1029 The return type is either a scalar @code{INTEGER} or a scalar
1030 @code{LOGICAL}. If the kind type parameters differ, then the
1031 smaller kind type is implicitly converted to larger kind, and the
1032 return has the larger kind.
1034 @item @emph{Example}:
1037 LOGICAL :: T = .TRUE., F = .FALSE.
1039 DATA a / Z'F' /, b / Z'3' /
1041 WRITE (*,*) AND(T, T), AND(T, F), AND(F, T), AND(F, F)
1042 WRITE (*,*) AND(a, b)
1046 @item @emph{See also}:
1047 Fortran 95 elemental function: @ref{IAND}
1053 @section @code{ANINT} --- Nearest whole number
1057 @cindex rounding, ceiling
1060 @item @emph{Description}:
1061 @code{ANINT(A [, KIND])} rounds its argument to the nearest whole number.
1063 @item @emph{Standard}:
1064 Fortran 77 and later
1069 @item @emph{Syntax}:
1070 @code{RESULT = ANINT(A [, KIND])}
1072 @item @emph{Arguments}:
1073 @multitable @columnfractions .15 .70
1074 @item @var{A} @tab The type of the argument shall be @code{REAL}.
1075 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
1076 expression indicating the kind parameter of the result.
1079 @item @emph{Return value}:
1080 The return value is of type real with the kind type parameter of the
1081 argument if the optional @var{KIND} is absent; otherwise, the kind
1082 type parameter will be given by @var{KIND}. If @var{A} is greater than
1083 zero, @code{ANINT(A)} returns @code{AINT(X+0.5)}. If @var{A} is
1084 less than or equal to zero then it returns @code{AINT(X-0.5)}.
1086 @item @emph{Example}:
1093 print *, anint(x4), dnint(x8)
1095 end program test_anint
1098 @item @emph{Specific names}:
1099 @multitable @columnfractions .20 .20 .20 .25
1100 @item Name @tab Argument @tab Return type @tab Standard
1101 @item @code{AINT(A)} @tab @code{REAL(4) A} @tab @code{REAL(4)} @tab Fortran 77 and later
1102 @item @code{DNINT(A)} @tab @code{REAL(8) A} @tab @code{REAL(8)} @tab Fortran 77 and later
1109 @section @code{ANY} --- Any value in @var{MASK} along @var{DIM} is true
1111 @cindex array, apply condition
1112 @cindex array, condition testing
1115 @item @emph{Description}:
1116 @code{ANY(MASK [, DIM])} determines if any of the values in the logical array
1117 @var{MASK} along dimension @var{DIM} are @code{.TRUE.}.
1119 @item @emph{Standard}:
1120 Fortran 95 and later
1123 Transformational function
1125 @item @emph{Syntax}:
1126 @code{RESULT = ANY(MASK [, DIM])}
1128 @item @emph{Arguments}:
1129 @multitable @columnfractions .15 .70
1130 @item @var{MASK} @tab The type of the argument shall be @code{LOGICAL} and
1131 it shall not be scalar.
1132 @item @var{DIM} @tab (Optional) @var{DIM} shall be a scalar integer
1133 with a value that lies between one and the rank of @var{MASK}.
1136 @item @emph{Return value}:
1137 @code{ANY(MASK)} returns a scalar value of type @code{LOGICAL} where
1138 the kind type parameter is the same as the kind type parameter of
1139 @var{MASK}. If @var{DIM} is present, then @code{ANY(MASK, DIM)} returns
1140 an array with the rank of @var{MASK} minus 1. The shape is determined from
1141 the shape of @var{MASK} where the @var{DIM} dimension is elided.
1145 @code{ANY(MASK)} is true if any element of @var{MASK} is true;
1146 otherwise, it is false. It also is false if @var{MASK} has zero size.
1148 If the rank of @var{MASK} is one, then @code{ANY(MASK,DIM)} is equivalent
1149 to @code{ANY(MASK)}. If the rank is greater than one, then @code{ANY(MASK,DIM)}
1150 is determined by applying @code{ANY} to the array sections.
1153 @item @emph{Example}:
1157 l = any((/.true., .true., .true./))
1162 integer a(2,3), b(2,3)
1166 print *, any(a .eq. b, 1)
1167 print *, any(a .eq. b, 2)
1168 end subroutine section
1169 end program test_any
1176 @section @code{ASIN} --- Arcsine function
1179 @cindex trigonometric function, sine, inverse
1180 @cindex sine, inverse
1183 @item @emph{Description}:
1184 @code{ASIN(X)} computes the arcsine of its @var{X} (inverse of @code{SIN(X)}).
1186 @item @emph{Standard}:
1187 Fortran 77 and later, for a complex argument Fortran 2008 or later
1192 @item @emph{Syntax}:
1193 @code{RESULT = ASIN(X)}
1195 @item @emph{Arguments}:
1196 @multitable @columnfractions .15 .70
1197 @item @var{X} @tab The type shall be either @code{REAL} and a magnitude that is
1198 less than or equal to one - or be @code{COMPLEX}.
1201 @item @emph{Return value}:
1202 The return value is of the same type and kind as @var{X}.
1203 The real part of the result is in radians and lies in the range
1204 @math{-\pi/2 \leq \Re \asin(x) \leq \pi/2}.
1206 @item @emph{Example}:
1209 real(8) :: x = 0.866_8
1211 end program test_asin
1214 @item @emph{Specific names}:
1215 @multitable @columnfractions .20 .20 .20 .25
1216 @item Name @tab Argument @tab Return type @tab Standard
1217 @item @code{ASIN(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab Fortran 77 and later
1218 @item @code{DASIN(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab Fortran 77 and later
1221 @item @emph{See also}:
1222 Inverse function: @ref{SIN}
1229 @section @code{ASINH} --- Inverse hyperbolic sine function
1232 @cindex area hyperbolic sine
1233 @cindex inverse hyperbolic sine
1234 @cindex hyperbolic function, sine, inverse
1235 @cindex sine, hyperbolic, inverse
1238 @item @emph{Description}:
1239 @code{ASINH(X)} computes the inverse hyperbolic sine of @var{X}.
1241 @item @emph{Standard}:
1242 Fortran 2008 and later
1247 @item @emph{Syntax}:
1248 @code{RESULT = ASINH(X)}
1250 @item @emph{Arguments}:
1251 @multitable @columnfractions .15 .70
1252 @item @var{X} @tab The type shall be @code{REAL} or @code{COMPLEX}.
1255 @item @emph{Return value}:
1256 The return value is of the same type and kind as @var{X}. If @var{X} is
1257 complex, the imaginary part of the result is in radians and lies between
1258 @math{-\pi/2 \leq \Im \asinh(x) \leq \pi/2}.
1260 @item @emph{Example}:
1263 REAL(8), DIMENSION(3) :: x = (/ -1.0, 0.0, 1.0 /)
1264 WRITE (*,*) ASINH(x)
1268 @item @emph{Specific names}:
1269 @multitable @columnfractions .20 .20 .20 .25
1270 @item Name @tab Argument @tab Return type @tab Standard
1271 @item @code{DASINH(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU extension.
1274 @item @emph{See also}:
1275 Inverse function: @ref{SINH}
1281 @section @code{ASSOCIATED} --- Status of a pointer or pointer/target pair
1283 @cindex pointer, status
1284 @cindex association status
1287 @item @emph{Description}:
1288 @code{ASSOCIATED(POINTER [, TARGET])} determines the status of the pointer
1289 @var{POINTER} or if @var{POINTER} is associated with the target @var{TARGET}.
1291 @item @emph{Standard}:
1292 Fortran 95 and later
1297 @item @emph{Syntax}:
1298 @code{RESULT = ASSOCIATED(POINTER [, TARGET])}
1300 @item @emph{Arguments}:
1301 @multitable @columnfractions .15 .70
1302 @item @var{POINTER} @tab @var{POINTER} shall have the @code{POINTER} attribute
1303 and it can be of any type.
1304 @item @var{TARGET} @tab (Optional) @var{TARGET} shall be a pointer or
1305 a target. It must have the same type, kind type parameter, and
1306 array rank as @var{POINTER}.
1308 The association status of neither @var{POINTER} nor @var{TARGET} shall be
1311 @item @emph{Return value}:
1312 @code{ASSOCIATED(POINTER)} returns a scalar value of type @code{LOGICAL(4)}.
1313 There are several cases:
1315 @item (A) When the optional @var{TARGET} is not present then
1316 @code{ASSOCIATED(POINTER)} is true if @var{POINTER} is associated with a target; otherwise, it returns false.
1317 @item (B) If @var{TARGET} is present and a scalar target, the result is true if
1318 @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
1319 disassociated, the result is false.
1320 @item (C) If @var{TARGET} is present and an array target, the result is true if
1321 @var{TARGET} and @var{POINTER} have the same shape, are not zero-sized arrays,
1322 are arrays whose elements are not zero-sized storage sequences, and
1323 @var{TARGET} and @var{POINTER} occupy the same storage units in array element
1325 As in case(B), the result is false, if @var{POINTER} is disassociated.
1326 @item (D) If @var{TARGET} is present and an scalar pointer, the result is true
1327 if @var{TARGET} is associated with @var{POINTER}, the target associated with
1328 @var{TARGET} are not zero-sized storage sequences and occupy the same storage
1330 The result is false, if either @var{TARGET} or @var{POINTER} is disassociated.
1331 @item (E) If @var{TARGET} is present and an array pointer, the result is true if
1332 target associated with @var{POINTER} and the target associated with @var{TARGET}
1333 have the same shape, are not zero-sized arrays, are arrays whose elements are
1334 not zero-sized storage sequences, and @var{TARGET} and @var{POINTER} occupy
1335 the same storage units in array element order.
1336 The result is false, if either @var{TARGET} or @var{POINTER} is disassociated.
1339 @item @emph{Example}:
1341 program test_associated
1343 real, target :: tgt(2) = (/1., 2./)
1344 real, pointer :: ptr(:)
1346 if (associated(ptr) .eqv. .false.) call abort
1347 if (associated(ptr,tgt) .eqv. .false.) call abort
1348 end program test_associated
1351 @item @emph{See also}:
1358 @section @code{ATAN} --- Arctangent function
1361 @cindex trigonometric function, tangent, inverse
1362 @cindex tangent, inverse
1365 @item @emph{Description}:
1366 @code{ATAN(X)} computes the arctangent of @var{X}.
1368 @item @emph{Standard}:
1369 Fortran 77 and later, for a complex argument and for two arguments
1370 Fortran 2008 or later
1375 @item @emph{Syntax}:
1376 @code{RESULT = ATAN(X)}
1377 @code{RESULT = ATAN(Y, X)}
1379 @item @emph{Arguments}:
1380 @multitable @columnfractions .15 .70
1381 @item @var{X} @tab The type shall be @code{REAL} or @code{COMPLEX};
1382 if @var{Y} is present, @var{X} shall be REAL.
1383 @item @var{Y} shall be of the same type and kind as @var{X}.
1386 @item @emph{Return value}:
1387 The return value is of the same type and kind as @var{X}.
1388 If @var{Y} is present, the result is identical to @code{ATAN2(Y,X)}.
1389 Otherwise, it the arcus tangent of @var{X}, where the real part of
1390 the result is in radians and lies in the range
1391 @math{-\pi/2 \leq \Re \atan(x) \leq \pi/2}.
1393 @item @emph{Example}:
1396 real(8) :: x = 2.866_8
1398 end program test_atan
1401 @item @emph{Specific names}:
1402 @multitable @columnfractions .20 .20 .20 .25
1403 @item Name @tab Argument @tab Return type @tab Standard
1404 @item @code{ATAN(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab Fortran 77 and later
1405 @item @code{DATAN(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab Fortran 77 and later
1408 @item @emph{See also}:
1409 Inverse function: @ref{TAN}
1416 @section @code{ATAN2} --- Arctangent function
1419 @cindex trigonometric function, tangent, inverse
1420 @cindex tangent, inverse
1423 @item @emph{Description}:
1424 @code{ATAN2(Y, X)} computes the principal value of the argument
1425 function of the complex number @math{X + i Y}. This function can
1426 be used to transform from carthesian into polar coordinates and
1427 allows to determine the angle in the correct quadrant.
1429 @item @emph{Standard}:
1430 Fortran 77 and later
1435 @item @emph{Syntax}:
1436 @code{RESULT = ATAN2(Y, X)}
1438 @item @emph{Arguments}:
1439 @multitable @columnfractions .15 .70
1440 @item @var{Y} @tab The type shall be @code{REAL}.
1441 @item @var{X} @tab The type and kind type parameter shall be the same as @var{Y}.
1442 If @var{Y} is zero, then @var{X} must be nonzero.
1445 @item @emph{Return value}:
1446 The return value has the same type and kind type parameter as @var{Y}.
1447 It is the principal value of the complex number @math{X + i Y}. If
1448 @var{X} is nonzero, then it lies in the range @math{-\pi \le \atan (x) \leq \pi}.
1449 The sign is positive if @var{Y} is positive. If @var{Y} is zero, then
1450 the return value is zero if @var{X} is positive and @math{\pi} if @var{X}
1451 is negative. Finally, if @var{X} is zero, then the magnitude of the result
1454 @item @emph{Example}:
1457 real(4) :: x = 1.e0_4, y = 0.5e0_4
1459 end program test_atan2
1462 @item @emph{Specific names}:
1463 @multitable @columnfractions .20 .20 .20 .25
1464 @item Name @tab Argument @tab Return type @tab Standard
1465 @item @code{ATAN2(X, Y)} @tab @code{REAL(4) X, Y} @tab @code{REAL(4)} @tab Fortran 77 and later
1466 @item @code{DATAN2(X, Y)} @tab @code{REAL(8) X, Y} @tab @code{REAL(8)} @tab Fortran 77 and later
1473 @section @code{ATANH} --- Inverse hyperbolic tangent function
1476 @cindex area hyperbolic tangent
1477 @cindex inverse hyperbolic tangent
1478 @cindex hyperbolic function, tangent, inverse
1479 @cindex tangent, hyperbolic, inverse
1482 @item @emph{Description}:
1483 @code{ATANH(X)} computes the inverse hyperbolic tangent of @var{X}.
1485 @item @emph{Standard}:
1486 Fortran 2008 and later
1491 @item @emph{Syntax}:
1492 @code{RESULT = ATANH(X)}
1494 @item @emph{Arguments}:
1495 @multitable @columnfractions .15 .70
1496 @item @var{X} @tab The type shall be @code{REAL} or @code{COMPLEX}.
1499 @item @emph{Return value}:
1500 The return value has same type and kind as @var{X}. If @var{X} is
1501 complex, the imaginary part of the result is in radians and lies between
1502 @math{-\pi/2 \leq \Im \atanh(x) \leq \pi/2}.
1504 @item @emph{Example}:
1507 REAL, DIMENSION(3) :: x = (/ -1.0, 0.0, 1.0 /)
1508 WRITE (*,*) ATANH(x)
1512 @item @emph{Specific names}:
1513 @multitable @columnfractions .20 .20 .20 .25
1514 @item Name @tab Argument @tab Return type @tab Standard
1515 @item @code{DATANH(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU extension
1518 @item @emph{See also}:
1519 Inverse function: @ref{TANH}
1525 @section @code{BESSEL_J0} --- Bessel function of the first kind of order 0
1529 @cindex Bessel function, first kind
1532 @item @emph{Description}:
1533 @code{BESSEL_J0(X)} computes the Bessel function of the first kind of
1534 order 0 of @var{X}. This function is available under the name
1535 @code{BESJ0} as a GNU extension.
1537 @item @emph{Standard}:
1538 Fortran 2008 and later
1543 @item @emph{Syntax}:
1544 @code{RESULT = BESSEL_J0(X)}
1546 @item @emph{Arguments}:
1547 @multitable @columnfractions .15 .70
1548 @item @var{X} @tab The type shall be @code{REAL}, and it shall be scalar.
1551 @item @emph{Return value}:
1552 The return value is of type @code{REAL} and lies in the
1553 range @math{ - 0.4027... \leq Bessel (0,x) \leq 1}. It has the same
1556 @item @emph{Example}:
1559 real(8) :: x = 0.0_8
1561 end program test_besj0
1564 @item @emph{Specific names}:
1565 @multitable @columnfractions .20 .20 .20 .25
1566 @item Name @tab Argument @tab Return type @tab Standard
1567 @item @code{DBESJ0(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU extension
1574 @section @code{BESSEL_J1} --- Bessel function of the first kind of order 1
1578 @cindex Bessel function, first kind
1581 @item @emph{Description}:
1582 @code{BESSEL_J1(X)} computes the Bessel function of the first kind of
1583 order 1 of @var{X}. This function is available under the name
1584 @code{BESJ1} as a GNU extension.
1586 @item @emph{Standard}:
1592 @item @emph{Syntax}:
1593 @code{RESULT = BESSEL_J1(X)}
1595 @item @emph{Arguments}:
1596 @multitable @columnfractions .15 .70
1597 @item @var{X} @tab The type shall be @code{REAL}, and it shall be scalar.
1600 @item @emph{Return value}:
1601 The return value is of type @code{REAL} and it lies in the
1602 range @math{ - 0.5818... \leq Bessel (0,x) \leq 0.5818 }. It has the same
1605 @item @emph{Example}:
1608 real(8) :: x = 1.0_8
1610 end program test_besj1
1613 @item @emph{Specific names}:
1614 @multitable @columnfractions .20 .20 .20 .25
1615 @item Name @tab Argument @tab Return type @tab Standard
1616 @item @code{DBESJ1(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU extension
1623 @section @code{BESSEL_JN} --- Bessel function of the first kind
1627 @cindex Bessel function, first kind
1630 @item @emph{Description}:
1631 @code{BESSEL_JN(N, X)} computes the Bessel function of the first kind of
1632 order @var{N} of @var{X}. This function is available under the name
1633 @code{BESJN} as a GNU extension. If @var{N} and @var{X} are arrays,
1634 their ranks and shapes shall conform.
1636 @code{BESSEL_JN(N1, N2, X)} returns an array with the Bessel functions
1637 of the first kind of the orders @var{N1} to @var{N2}.
1639 @item @emph{Standard}:
1640 Fortran 2008 and later, negative @var{N} is allowed as GNU extension
1643 Elemental function, except for the tranformational function
1644 @code{BESSEL_JN(N1, N2, X)}
1646 @item @emph{Syntax}:
1647 @code{RESULT = BESSEL_JN(N, X)}
1648 @code{RESULT = BESSEL_JN(N1, N2, X)}
1650 @item @emph{Arguments}:
1651 @multitable @columnfractions .15 .70
1652 @item @var{N} @tab Shall be a scalar or an array of type @code{INTEGER}.
1653 @item @var{N1} @tab Shall be a non-negative scalar of type @code{INTEGER}.
1654 @item @var{N2} @tab Shall be a non-negative scalar of type @code{INTEGER}.
1655 @item @var{X} @tab Shall be a scalar or an array of type @code{REAL};
1656 for @code{BESSEL_JN(N1, N2, X)} it shall be scalar.
1659 @item @emph{Return value}:
1660 The return value is a scalar of type @code{REAL}. It has the same
1664 The transformational function uses a recurrance algorithm which might,
1665 for some values of @var{X}, lead to different results than calls to
1666 the elemental function.
1668 @item @emph{Example}:
1671 real(8) :: x = 1.0_8
1673 end program test_besjn
1676 @item @emph{Specific names}:
1677 @multitable @columnfractions .20 .20 .20 .25
1678 @item Name @tab Argument @tab Return type @tab Standard
1679 @item @code{DBESJN(N, X)} @tab @code{INTEGER N} @tab @code{REAL(8)} @tab GNU extension
1680 @item @tab @code{REAL(8) X} @tab @tab
1687 @section @code{BESSEL_Y0} --- Bessel function of the second kind of order 0
1691 @cindex Bessel function, second kind
1694 @item @emph{Description}:
1695 @code{BESSEL_Y0(X)} computes the Bessel function of the second kind of
1696 order 0 of @var{X}. This function is available under the name
1697 @code{BESY0} as a GNU extension.
1699 @item @emph{Standard}:
1700 Fortran 2008 and later
1705 @item @emph{Syntax}:
1706 @code{RESULT = BESSEL_Y0(X)}
1708 @item @emph{Arguments}:
1709 @multitable @columnfractions .15 .70
1710 @item @var{X} @tab The type shall be @code{REAL}, and it shall be scalar.
1713 @item @emph{Return value}:
1714 The return value is a scalar of type @code{REAL}. It has the same
1717 @item @emph{Example}:
1720 real(8) :: x = 0.0_8
1722 end program test_besy0
1725 @item @emph{Specific names}:
1726 @multitable @columnfractions .20 .20 .20 .25
1727 @item Name @tab Argument @tab Return type @tab Standard
1728 @item @code{DBESY0(X)}@tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU extension
1735 @section @code{BESSEL_Y1} --- Bessel function of the second kind of order 1
1739 @cindex Bessel function, second kind
1742 @item @emph{Description}:
1743 @code{BESSEL_Y1(X)} computes the Bessel function of the second kind of
1744 order 1 of @var{X}. This function is available under the name
1745 @code{BESY1} as a GNU extension.
1747 @item @emph{Standard}:
1748 Fortran 2008 and later
1753 @item @emph{Syntax}:
1754 @code{RESULT = BESSEL_Y1(X)}
1756 @item @emph{Arguments}:
1757 @multitable @columnfractions .15 .70
1758 @item @var{X} @tab The type shall be @code{REAL}, and it shall be scalar.
1761 @item @emph{Return value}:
1762 The return value is a scalar of type @code{REAL}. It has the same
1765 @item @emph{Example}:
1768 real(8) :: x = 1.0_8
1770 end program test_besy1
1773 @item @emph{Specific names}:
1774 @multitable @columnfractions .20 .20 .20 .25
1775 @item Name @tab Argument @tab Return type @tab Standard
1776 @item @code{DBESY1(X)}@tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU extension
1783 @section @code{BESSEL_YN} --- Bessel function of the second kind
1787 @cindex Bessel function, second kind
1790 @item @emph{Description}:
1791 @code{BESSEL_YN(N, X)} computes the Bessel function of the second kind of
1792 order @var{N} of @var{X}. This function is available under the name
1793 @code{BESYN} as a GNU extension. If @var{N} and @var{X} are arrays,
1794 their ranks and shapes shall conform.
1796 @code{BESSEL_YN(N1, N2, X)} returns an array with the Bessel functions
1797 of the first kind of the orders @var{N1} to @var{N2}.
1799 @item @emph{Standard}:
1800 Fortran 2008 and later, negative @var{N} is allowed as GNU extension
1803 Elemental function, except for the tranformational function
1804 @code{BESSEL_YN(N1, N2, X)}
1806 @item @emph{Syntax}:
1807 @code{RESULT = BESSEL_YN(N, X)}
1808 @code{RESULT = BESSEL_YN(N1, N2, X)}
1810 @item @emph{Arguments}:
1811 @multitable @columnfractions .15 .70
1812 @item @var{N} @tab Shall be a scalar or an array of type @code{INTEGER} .
1813 @item @var{N1} @tab Shall be a non-negative scalar of type @code{INTEGER}.
1814 @item @var{N2} @tab Shall be a non-negative scalar of type @code{INTEGER}.
1815 @item @var{X} @tab Shall be a scalar or an array of type @code{REAL};
1816 for @code{BESSEL_YN(N1, N2, X)} it shall be scalar.
1819 @item @emph{Return value}:
1820 The return value is a scalar of type @code{REAL}. It has the same
1824 The transformational function uses a recurrance algorithm which might,
1825 for some values of @var{X}, lead to different results than calls to
1826 the elemental function.
1828 @item @emph{Example}:
1831 real(8) :: x = 1.0_8
1833 end program test_besyn
1836 @item @emph{Specific names}:
1837 @multitable @columnfractions .20 .20 .20 .25
1838 @item Name @tab Argument @tab Return type @tab Standard
1839 @item @code{DBESYN(N,X)} @tab @code{INTEGER N} @tab @code{REAL(8)} @tab GNU extension
1840 @item @tab @code{REAL(8) X} @tab @tab
1847 @section @code{BIT_SIZE} --- Bit size inquiry function
1849 @cindex bits, number of
1850 @cindex size of a variable, in bits
1853 @item @emph{Description}:
1854 @code{BIT_SIZE(I)} returns the number of bits (integer precision plus sign bit)
1855 represented by the type of @var{I}. The result of @code{BIT_SIZE(I)} is
1856 independent of the actual value of @var{I}.
1858 @item @emph{Standard}:
1859 Fortran 95 and later
1864 @item @emph{Syntax}:
1865 @code{RESULT = BIT_SIZE(I)}
1867 @item @emph{Arguments}:
1868 @multitable @columnfractions .15 .70
1869 @item @var{I} @tab The type shall be @code{INTEGER}.
1872 @item @emph{Return value}:
1873 The return value is of type @code{INTEGER}
1875 @item @emph{Example}:
1877 program test_bit_size
1882 end program test_bit_size
1889 @section @code{BTEST} --- Bit test function
1891 @cindex bits, testing
1894 @item @emph{Description}:
1895 @code{BTEST(I,POS)} returns logical @code{.TRUE.} if the bit at @var{POS}
1896 in @var{I} is set. The counting of the bits starts at 0.
1898 @item @emph{Standard}:
1899 Fortran 95 and later
1904 @item @emph{Syntax}:
1905 @code{RESULT = BTEST(I, POS)}
1907 @item @emph{Arguments}:
1908 @multitable @columnfractions .15 .70
1909 @item @var{I} @tab The type shall be @code{INTEGER}.
1910 @item @var{POS} @tab The type shall be @code{INTEGER}.
1913 @item @emph{Return value}:
1914 The return value is of type @code{LOGICAL}
1916 @item @emph{Example}:
1919 integer :: i = 32768 + 1024 + 64
1923 bool = btest(i, pos)
1926 end program test_btest
1932 @section @code{C_ASSOCIATED} --- Status of a C pointer
1933 @fnindex C_ASSOCIATED
1934 @cindex association status, C pointer
1935 @cindex pointer, C association status
1938 @item @emph{Description}:
1939 @code{C_ASSOCIATED(c_prt_1[, c_ptr_2])} determines the status of the C pointer
1940 @var{c_ptr_1} or if @var{c_ptr_1} is associated with the target @var{c_ptr_2}.
1942 @item @emph{Standard}:
1943 Fortran 2003 and later
1948 @item @emph{Syntax}:
1949 @code{RESULT = C_ASSOCIATED(c_prt_1[, c_ptr_2])}
1951 @item @emph{Arguments}:
1952 @multitable @columnfractions .15 .70
1953 @item @var{c_ptr_1} @tab Scalar of the type @code{C_PTR} or @code{C_FUNPTR}.
1954 @item @var{c_ptr_2} @tab (Optional) Scalar of the same type as @var{c_ptr_1}.
1957 @item @emph{Return value}:
1958 The return value is of type @code{LOGICAL}; it is @code{.false.} if either
1959 @var{c_ptr_1} is a C NULL pointer or if @var{c_ptr1} and @var{c_ptr_2}
1960 point to different addresses.
1962 @item @emph{Example}:
1964 subroutine association_test(a,b)
1965 use iso_c_binding, only: c_associated, c_loc, c_ptr
1969 if(c_associated(b, c_loc(a))) &
1970 stop 'b and a do not point to same target'
1971 end subroutine association_test
1974 @item @emph{See also}:
1975 @ref{C_LOC}, @ref{C_FUNLOC}
1980 @section @code{C_FUNLOC} --- Obtain the C address of a procedure
1982 @cindex pointer, C address of procedures
1985 @item @emph{Description}:
1986 @code{C_FUNLOC(x)} determines the C address of the argument.
1988 @item @emph{Standard}:
1989 Fortran 2003 and later
1994 @item @emph{Syntax}:
1995 @code{RESULT = C_FUNLOC(x)}
1997 @item @emph{Arguments}:
1998 @multitable @columnfractions .15 .70
1999 @item @var{x} @tab Interoperable function or pointer to such function.
2002 @item @emph{Return value}:
2003 The return value is of type @code{C_FUNPTR} and contains the C address
2006 @item @emph{Example}:
2012 subroutine sub(a) bind(c)
2022 subroutine my_routine(p) bind(c,name='myC_func')
2024 type(c_funptr), intent(in) :: p
2027 call my_routine(c_funloc(sub))
2031 @item @emph{See also}:
2032 @ref{C_ASSOCIATED}, @ref{C_LOC}, @ref{C_F_POINTER}, @ref{C_F_PROCPOINTER}
2036 @node C_F_PROCPOINTER
2037 @section @code{C_F_PROCPOINTER} --- Convert C into Fortran procedure pointer
2038 @fnindex C_F_PROCPOINTER
2039 @cindex pointer, C address of pointers
2042 @item @emph{Description}:
2043 @code{C_F_PROCPOINTER(CPTR, FPTR)} Assign the target of the C function pointer
2044 @var{CPTR} to the Fortran procedure pointer @var{FPTR}.
2046 @item @emph{Standard}:
2047 Fortran 2003 and later
2052 @item @emph{Syntax}:
2053 @code{CALL C_F_PROCPOINTER(cptr, fptr)}
2055 @item @emph{Arguments}:
2056 @multitable @columnfractions .15 .70
2057 @item @var{CPTR} @tab scalar of the type @code{C_FUNPTR}. It is
2059 @item @var{FPTR} @tab procedure pointer interoperable with @var{cptr}. It is
2063 @item @emph{Example}:
2071 real(c_float), intent(in) :: a
2072 real(c_float) :: func
2076 function getIterFunc() bind(c,name="getIterFunc")
2078 type(c_funptr) :: getIterFunc
2081 type(c_funptr) :: cfunptr
2082 procedure(func), pointer :: myFunc
2083 cfunptr = getIterFunc()
2084 call c_f_procpointer(cfunptr, myFunc)
2088 @item @emph{See also}:
2089 @ref{C_LOC}, @ref{C_F_POINTER}
2094 @section @code{C_F_POINTER} --- Convert C into Fortran pointer
2095 @fnindex C_F_POINTER
2096 @cindex pointer, convert C to Fortran
2099 @item @emph{Description}:
2100 @code{C_F_POINTER(CPTR, FPTR[, SHAPE])} Assign the target the C pointer
2101 @var{CPTR} to the Fortran pointer @var{FPTR} and specify its
2104 @item @emph{Standard}:
2105 Fortran 2003 and later
2110 @item @emph{Syntax}:
2111 @code{CALL C_F_POINTER(CPTR, FPTR[, SHAPE])}
2113 @item @emph{Arguments}:
2114 @multitable @columnfractions .15 .70
2115 @item @var{CPTR} @tab scalar of the type @code{C_PTR}. It is
2117 @item @var{FPTR} @tab pointer interoperable with @var{cptr}. It is
2119 @item @var{SHAPE} @tab (Optional) Rank-one array of type @code{INTEGER}
2120 with @code{INTENT(IN)}. It shall be present
2121 if and only if @var{fptr} is an array. The size
2122 must be equal to the rank of @var{fptr}.
2125 @item @emph{Example}:
2131 subroutine my_routine(p) bind(c,name='myC_func')
2133 type(c_ptr), intent(out) :: p
2137 real,pointer :: a(:)
2138 call my_routine(cptr)
2139 call c_f_pointer(cptr, a, [12])
2143 @item @emph{See also}:
2144 @ref{C_LOC}, @ref{C_F_PROCPOINTER}
2149 @section @code{C_LOC} --- Obtain the C address of an object
2151 @cindex procedure pointer, convert C to Fortran
2154 @item @emph{Description}:
2155 @code{C_LOC(X)} determines the C address of the argument.
2157 @item @emph{Standard}:
2158 Fortran 2003 and later
2163 @item @emph{Syntax}:
2164 @code{RESULT = C_LOC(X)}
2166 @item @emph{Arguments}:
2167 @multitable @columnfractions .10 .75
2168 @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.
2172 @item @emph{Return value}:
2173 The return value is of type @code{C_PTR} and contains the C address
2176 @item @emph{Example}:
2178 subroutine association_test(a,b)
2179 use iso_c_binding, only: c_associated, c_loc, c_ptr
2183 if(c_associated(b, c_loc(a))) &
2184 stop 'b and a do not point to same target'
2185 end subroutine association_test
2188 @item @emph{See also}:
2189 @ref{C_ASSOCIATED}, @ref{C_FUNLOC}, @ref{C_F_POINTER}, @ref{C_F_PROCPOINTER}
2194 @section @code{C_SIZEOF} --- Size in bytes of an expression
2196 @cindex expression size
2197 @cindex size of an expression
2200 @item @emph{Description}:
2201 @code{C_SIZEOF(X)} calculates the number of bytes of storage the
2202 expression @code{X} occupies.
2204 @item @emph{Standard}:
2210 @item @emph{Syntax}:
2211 @code{N = C_SIZEOF(X)}
2213 @item @emph{Arguments}:
2214 @multitable @columnfractions .15 .70
2215 @item @var{X} @tab The argument shall be an interoperable data entity.
2218 @item @emph{Return value}:
2219 The return value is of type integer and of the system-dependent kind
2220 @var{C_SIZE_T} (from the @var{ISO_C_BINDING} module). Its value is the
2221 number of bytes occupied by the argument. If the argument has the
2222 @code{POINTER} attribute, the number of bytes of the storage area pointed
2223 to is returned. If the argument is of a derived type with @code{POINTER}
2224 or @code{ALLOCATABLE} components, the return value doesn't account for
2225 the sizes of the data pointed to by these components.
2227 @item @emph{Example}:
2231 real(c_float) :: r, s(5)
2232 print *, (c_sizeof(s)/c_sizeof(r) == 5)
2235 The example will print @code{.TRUE.} unless you are using a platform
2236 where default @code{REAL} variables are unusually padded.
2238 @item @emph{See also}:
2239 @ref{SIZEOF}, @ref{STORAGE_SIZE}
2244 @section @code{CEILING} --- Integer ceiling function
2247 @cindex rounding, ceiling
2250 @item @emph{Description}:
2251 @code{CEILING(A)} returns the least integer greater than or equal to @var{A}.
2253 @item @emph{Standard}:
2254 Fortran 95 and later
2259 @item @emph{Syntax}:
2260 @code{RESULT = CEILING(A [, KIND])}
2262 @item @emph{Arguments}:
2263 @multitable @columnfractions .15 .70
2264 @item @var{A} @tab The type shall be @code{REAL}.
2265 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
2266 expression indicating the kind parameter of the result.
2269 @item @emph{Return value}:
2270 The return value is of type @code{INTEGER(KIND)} if @var{KIND} is present
2271 and a default-kind @code{INTEGER} otherwise.
2273 @item @emph{Example}:
2275 program test_ceiling
2278 print *, ceiling(x) ! returns 64
2279 print *, ceiling(y) ! returns -63
2280 end program test_ceiling
2283 @item @emph{See also}:
2284 @ref{FLOOR}, @ref{NINT}
2291 @section @code{CHAR} --- Character conversion function
2293 @cindex conversion, to character
2296 @item @emph{Description}:
2297 @code{CHAR(I [, KIND])} returns the character represented by the integer @var{I}.
2299 @item @emph{Standard}:
2300 Fortran 77 and later
2305 @item @emph{Syntax}:
2306 @code{RESULT = CHAR(I [, KIND])}
2308 @item @emph{Arguments}:
2309 @multitable @columnfractions .15 .70
2310 @item @var{I} @tab The type shall be @code{INTEGER}.
2311 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
2312 expression indicating the kind parameter of the result.
2315 @item @emph{Return value}:
2316 The return value is of type @code{CHARACTER(1)}
2318 @item @emph{Example}:
2324 print *, i, c ! returns 'J'
2325 end program test_char
2328 @item @emph{Specific names}:
2329 @multitable @columnfractions .20 .20 .20 .25
2330 @item Name @tab Argument @tab Return type @tab Standard
2331 @item @code{CHAR(I)} @tab @code{INTEGER I} @tab @code{CHARACTER(LEN=1)} @tab F77 and later
2335 See @ref{ICHAR} for a discussion of converting between numerical values
2336 and formatted string representations.
2338 @item @emph{See also}:
2339 @ref{ACHAR}, @ref{IACHAR}, @ref{ICHAR}
2346 @section @code{CHDIR} --- Change working directory
2348 @cindex system, working directory
2351 @item @emph{Description}:
2352 Change current working directory to a specified path.
2354 This intrinsic is provided in both subroutine and function forms; however,
2355 only one form can be used in any given program unit.
2357 @item @emph{Standard}:
2361 Subroutine, function
2363 @item @emph{Syntax}:
2364 @multitable @columnfractions .80
2365 @item @code{CALL CHDIR(NAME [, STATUS])}
2366 @item @code{STATUS = CHDIR(NAME)}
2369 @item @emph{Arguments}:
2370 @multitable @columnfractions .15 .70
2371 @item @var{NAME} @tab The type shall be @code{CHARACTER} of default
2372 kind and shall specify a valid path within the file system.
2373 @item @var{STATUS} @tab (Optional) @code{INTEGER} status flag of the default
2374 kind. Returns 0 on success, and a system specific and nonzero error code
2378 @item @emph{Example}:
2381 CHARACTER(len=255) :: path
2383 WRITE(*,*) TRIM(path)
2386 WRITE(*,*) TRIM(path)
2390 @item @emph{See also}:
2397 @section @code{CHMOD} --- Change access permissions of files
2399 @cindex file system, change access mode
2402 @item @emph{Description}:
2403 @code{CHMOD} changes the permissions of a file. This function invokes
2404 @code{/bin/chmod} and might therefore not work on all platforms.
2406 This intrinsic is provided in both subroutine and function forms; however,
2407 only one form can be used in any given program unit.
2409 @item @emph{Standard}:
2413 Subroutine, function
2415 @item @emph{Syntax}:
2416 @multitable @columnfractions .80
2417 @item @code{CALL CHMOD(NAME, MODE[, STATUS])}
2418 @item @code{STATUS = CHMOD(NAME, MODE)}
2421 @item @emph{Arguments}:
2422 @multitable @columnfractions .15 .70
2424 @item @var{NAME} @tab Scalar @code{CHARACTER} of default kind with the
2425 file name. Trailing blanks are ignored unless the character
2426 @code{achar(0)} is present, then all characters up to and excluding
2427 @code{achar(0)} are used as the file name.
2429 @item @var{MODE} @tab Scalar @code{CHARACTER} of default kind giving the
2430 file permission. @var{MODE} uses the same syntax as the @var{MODE}
2431 argument of @code{/bin/chmod}.
2433 @item @var{STATUS} @tab (optional) scalar @code{INTEGER}, which is
2434 @code{0} on success and nonzero otherwise.
2437 @item @emph{Return value}:
2438 In either syntax, @var{STATUS} is set to @code{0} on success and nonzero
2441 @item @emph{Example}:
2442 @code{CHMOD} as subroutine
2447 call chmod('test.dat','u+x',status)
2448 print *, 'Status: ', status
2449 end program chmod_test
2451 @code{CHMOD} as function:
2456 status = chmod('test.dat','u+x')
2457 print *, 'Status: ', status
2458 end program chmod_test
2466 @section @code{CMPLX} --- Complex conversion function
2468 @cindex complex numbers, conversion to
2469 @cindex conversion, to complex
2472 @item @emph{Description}:
2473 @code{CMPLX(X [, Y [, KIND]])} returns a complex number where @var{X} is converted to
2474 the real component. If @var{Y} is present it is converted to the imaginary
2475 component. If @var{Y} is not present then the imaginary component is set to
2476 0.0. If @var{X} is complex then @var{Y} must not be present.
2478 @item @emph{Standard}:
2479 Fortran 77 and later
2484 @item @emph{Syntax}:
2485 @code{RESULT = CMPLX(X [, Y [, KIND]])}
2487 @item @emph{Arguments}:
2488 @multitable @columnfractions .15 .70
2489 @item @var{X} @tab The type may be @code{INTEGER}, @code{REAL},
2491 @item @var{Y} @tab (Optional; only allowed if @var{X} is not
2492 @code{COMPLEX}.) May be @code{INTEGER} or @code{REAL}.
2493 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
2494 expression indicating the kind parameter of the result.
2497 @item @emph{Return value}:
2498 The return value is of @code{COMPLEX} type, with a kind equal to
2499 @var{KIND} if it is specified. If @var{KIND} is not specified, the
2500 result is of the default @code{COMPLEX} kind, regardless of the kinds of
2501 @var{X} and @var{Y}.
2503 @item @emph{Example}:
2510 print *, z, cmplx(x)
2511 end program test_cmplx
2514 @item @emph{See also}:
2520 @node COMMAND_ARGUMENT_COUNT
2521 @section @code{COMMAND_ARGUMENT_COUNT} --- Get number of command line arguments
2522 @fnindex COMMAND_ARGUMENT_COUNT
2523 @cindex command-line arguments
2524 @cindex command-line arguments, number of
2525 @cindex arguments, to program
2528 @item @emph{Description}:
2529 @code{COMMAND_ARGUMENT_COUNT()} returns the number of arguments passed on the
2530 command line when the containing program was invoked.
2532 @item @emph{Standard}:
2533 Fortran 2003 and later
2538 @item @emph{Syntax}:
2539 @code{RESULT = COMMAND_ARGUMENT_COUNT()}
2541 @item @emph{Arguments}:
2542 @multitable @columnfractions .15 .70
2546 @item @emph{Return value}:
2547 The return value is an @code{INTEGER} of default kind.
2549 @item @emph{Example}:
2551 program test_command_argument_count
2553 count = command_argument_count()
2555 end program test_command_argument_count
2558 @item @emph{See also}:
2559 @ref{GET_COMMAND}, @ref{GET_COMMAND_ARGUMENT}
2565 @section @code{COMPLEX} --- Complex conversion function
2567 @cindex complex numbers, conversion to
2568 @cindex conversion, to complex
2571 @item @emph{Description}:
2572 @code{COMPLEX(X, Y)} returns a complex number where @var{X} is converted
2573 to the real component and @var{Y} is converted to the imaginary
2576 @item @emph{Standard}:
2582 @item @emph{Syntax}:
2583 @code{RESULT = COMPLEX(X, Y)}
2585 @item @emph{Arguments}:
2586 @multitable @columnfractions .15 .70
2587 @item @var{X} @tab The type may be @code{INTEGER} or @code{REAL}.
2588 @item @var{Y} @tab The type may be @code{INTEGER} or @code{REAL}.
2591 @item @emph{Return value}:
2592 If @var{X} and @var{Y} are both of @code{INTEGER} type, then the return
2593 value is of default @code{COMPLEX} type.
2595 If @var{X} and @var{Y} are of @code{REAL} type, or one is of @code{REAL}
2596 type and one is of @code{INTEGER} type, then the return value is of
2597 @code{COMPLEX} type with a kind equal to that of the @code{REAL}
2598 argument with the highest precision.
2600 @item @emph{Example}:
2602 program test_complex
2605 print *, complex(i, x)
2606 end program test_complex
2609 @item @emph{See also}:
2616 @section @code{CONJG} --- Complex conjugate function
2619 @cindex complex conjugate
2622 @item @emph{Description}:
2623 @code{CONJG(Z)} returns the conjugate of @var{Z}. If @var{Z} is @code{(x, y)}
2624 then the result is @code{(x, -y)}
2626 @item @emph{Standard}:
2627 Fortran 77 and later, has overloads that are GNU extensions
2632 @item @emph{Syntax}:
2635 @item @emph{Arguments}:
2636 @multitable @columnfractions .15 .70
2637 @item @var{Z} @tab The type shall be @code{COMPLEX}.
2640 @item @emph{Return value}:
2641 The return value is of type @code{COMPLEX}.
2643 @item @emph{Example}:
2646 complex :: z = (2.0, 3.0)
2647 complex(8) :: dz = (2.71_8, -3.14_8)
2652 end program test_conjg
2655 @item @emph{Specific names}:
2656 @multitable @columnfractions .20 .20 .20 .25
2657 @item Name @tab Argument @tab Return type @tab Standard
2658 @item @code{CONJG(Z)} @tab @code{COMPLEX Z} @tab @code{COMPLEX} @tab GNU extension
2659 @item @code{DCONJG(Z)} @tab @code{COMPLEX(8) Z} @tab @code{COMPLEX(8)} @tab GNU extension
2666 @section @code{COS} --- Cosine function
2672 @cindex trigonometric function, cosine
2676 @item @emph{Description}:
2677 @code{COS(X)} computes the cosine of @var{X}.
2679 @item @emph{Standard}:
2680 Fortran 77 and later, has overloads that are GNU extensions
2685 @item @emph{Syntax}:
2686 @code{RESULT = COS(X)}
2688 @item @emph{Arguments}:
2689 @multitable @columnfractions .15 .70
2690 @item @var{X} @tab The type shall be @code{REAL} or
2694 @item @emph{Return value}:
2695 The return value is of the same type and kind as @var{X}. The real part
2696 of the result is in radians. If @var{X} is of the type @code{REAL},
2697 the return value lies in the range @math{ -1 \leq \cos (x) \leq 1}.
2699 @item @emph{Example}:
2704 end program test_cos
2707 @item @emph{Specific names}:
2708 @multitable @columnfractions .20 .20 .20 .25
2709 @item Name @tab Argument @tab Return type @tab Standard
2710 @item @code{COS(X)} n@tab @code{REAL(4) X} @tab @code{REAL(4)} @tab Fortran 77 and later
2711 @item @code{DCOS(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab Fortran 77 and later
2712 @item @code{CCOS(X)} @tab @code{COMPLEX(4) X} @tab @code{COMPLEX(4)} @tab Fortran 77 and later
2713 @item @code{ZCOS(X)} @tab @code{COMPLEX(8) X} @tab @code{COMPLEX(8)} @tab GNU extension
2714 @item @code{CDCOS(X)} @tab @code{COMPLEX(8) X} @tab @code{COMPLEX(8)} @tab GNU extension
2717 @item @emph{See also}:
2718 Inverse function: @ref{ACOS}
2725 @section @code{COSH} --- Hyperbolic cosine function
2728 @cindex hyperbolic cosine
2729 @cindex hyperbolic function, cosine
2730 @cindex cosine, hyperbolic
2733 @item @emph{Description}:
2734 @code{COSH(X)} computes the hyperbolic cosine of @var{X}.
2736 @item @emph{Standard}:
2737 Fortran 77 and later, for a complex argument Fortran 2008 or later
2742 @item @emph{Syntax}:
2745 @item @emph{Arguments}:
2746 @multitable @columnfractions .15 .70
2747 @item @var{X} @tab The type shall be @code{REAL} or @code{COMPLEX}.
2750 @item @emph{Return value}:
2751 The return value has same type and kind as @var{X}. If @var{X} is
2752 complex, the imaginary part of the result is in radians. If @var{X}
2753 is @code{REAL}, the return value has a lower bound of one,
2754 @math{\cosh (x) \geq 1}.
2756 @item @emph{Example}:
2759 real(8) :: x = 1.0_8
2761 end program test_cosh
2764 @item @emph{Specific names}:
2765 @multitable @columnfractions .20 .20 .20 .25
2766 @item Name @tab Argument @tab Return type @tab Standard
2767 @item @code{COSH(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab Fortran 77 and later
2768 @item @code{DCOSH(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab Fortran 77 and later
2771 @item @emph{See also}:
2772 Inverse function: @ref{ACOSH}
2779 @section @code{COUNT} --- Count function
2781 @cindex array, conditionally count elements
2782 @cindex array, element counting
2783 @cindex array, number of elements
2786 @item @emph{Description}:
2788 Counts the number of @code{.TRUE.} elements in a logical @var{MASK},
2789 or, if the @var{DIM} argument is supplied, counts the number of
2790 elements along each row of the array in the @var{DIM} direction.
2791 If the array has zero size, or all of the elements of @var{MASK} are
2792 @code{.FALSE.}, then the result is @code{0}.
2794 @item @emph{Standard}:
2795 Fortran 95 and later, with @var{KIND} argument Fortran 2003 and later
2798 Transformational function
2800 @item @emph{Syntax}:
2801 @code{RESULT = COUNT(MASK [, DIM, KIND])}
2803 @item @emph{Arguments}:
2804 @multitable @columnfractions .15 .70
2805 @item @var{MASK} @tab The type shall be @code{LOGICAL}.
2806 @item @var{DIM} @tab (Optional) The type shall be @code{INTEGER}.
2807 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
2808 expression indicating the kind parameter of the result.
2811 @item @emph{Return value}:
2812 The return value is of type @code{INTEGER} and of kind @var{KIND}. If
2813 @var{KIND} is absent, the return value is of default integer kind.
2814 If @var{DIM} is present, the result is an array with a rank one less
2815 than the rank of @var{ARRAY}, and a size corresponding to the shape
2816 of @var{ARRAY} with the @var{DIM} dimension removed.
2818 @item @emph{Example}:
2821 integer, dimension(2,3) :: a, b
2822 logical, dimension(2,3) :: mask
2823 a = reshape( (/ 1, 2, 3, 4, 5, 6 /), (/ 2, 3 /))
2824 b = reshape( (/ 0, 7, 3, 4, 5, 8 /), (/ 2, 3 /))
2825 print '(3i3)', a(1,:)
2826 print '(3i3)', a(2,:)
2828 print '(3i3)', b(1,:)
2829 print '(3i3)', b(2,:)
2832 print '(3l3)', mask(1,:)
2833 print '(3l3)', mask(2,:)
2835 print '(3i3)', count(mask)
2837 print '(3i3)', count(mask, 1)
2839 print '(3i3)', count(mask, 2)
2840 end program test_count
2847 @section @code{CPU_TIME} --- CPU elapsed time in seconds
2849 @cindex time, elapsed
2852 @item @emph{Description}:
2853 Returns a @code{REAL} value representing the elapsed CPU time in
2854 seconds. This is useful for testing segments of code to determine
2857 If a time source is available, time will be reported with microsecond
2858 resolution. If no time source is available, @var{TIME} is set to
2861 Note that @var{TIME} may contain a, system dependent, arbitrary offset
2862 and may not start with @code{0.0}. For @code{CPU_TIME}, the absolute
2863 value is meaningless, only differences between subsequent calls to
2864 this subroutine, as shown in the example below, should be used.
2867 @item @emph{Standard}:
2868 Fortran 95 and later
2873 @item @emph{Syntax}:
2874 @code{CALL CPU_TIME(TIME)}
2876 @item @emph{Arguments}:
2877 @multitable @columnfractions .15 .70
2878 @item @var{TIME} @tab The type shall be @code{REAL} with @code{INTENT(OUT)}.
2881 @item @emph{Return value}:
2884 @item @emph{Example}:
2886 program test_cpu_time
2887 real :: start, finish
2888 call cpu_time(start)
2889 ! put code to test here
2890 call cpu_time(finish)
2891 print '("Time = ",f6.3," seconds.")',finish-start
2892 end program test_cpu_time
2895 @item @emph{See also}:
2896 @ref{SYSTEM_CLOCK}, @ref{DATE_AND_TIME}
2902 @section @code{CSHIFT} --- Circular shift elements of an array
2904 @cindex array, shift circularly
2905 @cindex array, permutation
2906 @cindex array, rotate
2909 @item @emph{Description}:
2910 @code{CSHIFT(ARRAY, SHIFT [, DIM])} performs a circular shift on elements of
2911 @var{ARRAY} along the dimension of @var{DIM}. If @var{DIM} is omitted it is
2912 taken to be @code{1}. @var{DIM} is a scalar of type @code{INTEGER} in the
2913 range of @math{1 \leq DIM \leq n)} where @math{n} is the rank of @var{ARRAY}.
2914 If the rank of @var{ARRAY} is one, then all elements of @var{ARRAY} are shifted
2915 by @var{SHIFT} places. If rank is greater than one, then all complete rank one
2916 sections of @var{ARRAY} along the given dimension are shifted. Elements
2917 shifted out one end of each rank one section are shifted back in the other end.
2919 @item @emph{Standard}:
2920 Fortran 95 and later
2923 Transformational function
2925 @item @emph{Syntax}:
2926 @code{RESULT = CSHIFT(ARRAY, SHIFT [, DIM])}
2928 @item @emph{Arguments}:
2929 @multitable @columnfractions .15 .70
2930 @item @var{ARRAY} @tab Shall be an array of any type.
2931 @item @var{SHIFT} @tab The type shall be @code{INTEGER}.
2932 @item @var{DIM} @tab The type shall be @code{INTEGER}.
2935 @item @emph{Return value}:
2936 Returns an array of same type and rank as the @var{ARRAY} argument.
2938 @item @emph{Example}:
2941 integer, dimension(3,3) :: a
2942 a = reshape( (/ 1, 2, 3, 4, 5, 6, 7, 8, 9 /), (/ 3, 3 /))
2943 print '(3i3)', a(1,:)
2944 print '(3i3)', a(2,:)
2945 print '(3i3)', a(3,:)
2946 a = cshift(a, SHIFT=(/1, 2, -1/), DIM=2)
2948 print '(3i3)', a(1,:)
2949 print '(3i3)', a(2,:)
2950 print '(3i3)', a(3,:)
2951 end program test_cshift
2958 @section @code{CTIME} --- Convert a time into a string
2960 @cindex time, conversion to string
2961 @cindex conversion, to string
2964 @item @emph{Description}:
2965 @code{CTIME} converts a system time value, such as returned by
2966 @code{TIME8()}, to a string of the form @samp{Sat Aug 19 18:13:14 1995}.
2968 This intrinsic is provided in both subroutine and function forms; however,
2969 only one form can be used in any given program unit.
2971 @item @emph{Standard}:
2975 Subroutine, function
2977 @item @emph{Syntax}:
2978 @multitable @columnfractions .80
2979 @item @code{CALL CTIME(TIME, RESULT)}.
2980 @item @code{RESULT = CTIME(TIME)}, (not recommended).
2983 @item @emph{Arguments}:
2984 @multitable @columnfractions .15 .70
2985 @item @var{TIME} @tab The type shall be of type @code{INTEGER(KIND=8)}.
2986 @item @var{RESULT} @tab The type shall be of type @code{CHARACTER} and
2990 @item @emph{Return value}:
2991 The converted date and time as a string.
2993 @item @emph{Example}:
2997 character(len=30) :: date
3000 ! Do something, main part of the program
3003 print *, 'Program was started on ', date
3004 end program test_ctime
3007 @item @emph{See Also}:
3008 @ref{GMTIME}, @ref{LTIME}, @ref{TIME}, @ref{TIME8}
3014 @section @code{DATE_AND_TIME} --- Date and time subroutine
3015 @fnindex DATE_AND_TIME
3016 @cindex date, current
3017 @cindex current date
3018 @cindex time, current
3019 @cindex current time
3022 @item @emph{Description}:
3023 @code{DATE_AND_TIME(DATE, TIME, ZONE, VALUES)} gets the corresponding date and
3024 time information from the real-time system clock. @var{DATE} is
3025 @code{INTENT(OUT)} and has form ccyymmdd. @var{TIME} is @code{INTENT(OUT)} and
3026 has form hhmmss.sss. @var{ZONE} is @code{INTENT(OUT)} and has form (+-)hhmm,
3027 representing the difference with respect to Coordinated Universal Time (UTC).
3028 Unavailable time and date parameters return blanks.
3030 @var{VALUES} is @code{INTENT(OUT)} and provides the following:
3032 @multitable @columnfractions .15 .30 .40
3033 @item @tab @code{VALUE(1)}: @tab The year
3034 @item @tab @code{VALUE(2)}: @tab The month
3035 @item @tab @code{VALUE(3)}: @tab The day of the month
3036 @item @tab @code{VALUE(4)}: @tab Time difference with UTC in minutes
3037 @item @tab @code{VALUE(5)}: @tab The hour of the day
3038 @item @tab @code{VALUE(6)}: @tab The minutes of the hour
3039 @item @tab @code{VALUE(7)}: @tab The seconds of the minute
3040 @item @tab @code{VALUE(8)}: @tab The milliseconds of the second
3043 @item @emph{Standard}:
3044 Fortran 95 and later
3049 @item @emph{Syntax}:
3050 @code{CALL DATE_AND_TIME([DATE, TIME, ZONE, VALUES])}
3052 @item @emph{Arguments}:
3053 @multitable @columnfractions .15 .70
3054 @item @var{DATE} @tab (Optional) The type shall be @code{CHARACTER(LEN=8)}
3055 or larger, and of default kind.
3056 @item @var{TIME} @tab (Optional) The type shall be @code{CHARACTER(LEN=10)}
3057 or larger, and of default kind.
3058 @item @var{ZONE} @tab (Optional) The type shall be @code{CHARACTER(LEN=5)}
3059 or larger, and of default kind.
3060 @item @var{VALUES}@tab (Optional) The type shall be @code{INTEGER(8)}.
3063 @item @emph{Return value}:
3066 @item @emph{Example}:
3068 program test_time_and_date
3069 character(8) :: date
3070 character(10) :: time
3071 character(5) :: zone
3072 integer,dimension(8) :: values
3073 ! using keyword arguments
3074 call date_and_time(date,time,zone,values)
3075 call date_and_time(DATE=date,ZONE=zone)
3076 call date_and_time(TIME=time)
3077 call date_and_time(VALUES=values)
3078 print '(a,2x,a,2x,a)', date, time, zone
3079 print '(8i5))', values
3080 end program test_time_and_date
3083 @item @emph{See also}:
3084 @ref{CPU_TIME}, @ref{SYSTEM_CLOCK}
3090 @section @code{DBLE} --- Double conversion function
3092 @cindex conversion, to real
3095 @item @emph{Description}:
3096 @code{DBLE(A)} Converts @var{A} to double precision real type.
3098 @item @emph{Standard}:
3099 Fortran 77 and later
3104 @item @emph{Syntax}:
3105 @code{RESULT = DBLE(A)}
3107 @item @emph{Arguments}:
3108 @multitable @columnfractions .15 .70
3109 @item @var{A} @tab The type shall be @code{INTEGER}, @code{REAL},
3113 @item @emph{Return value}:
3114 The return value is of type double precision real.
3116 @item @emph{Example}:
3121 complex :: z = (2.3,1.14)
3122 print *, dble(x), dble(i), dble(z)
3123 end program test_dble
3126 @item @emph{See also}:
3133 @section @code{DCMPLX} --- Double complex conversion function
3135 @cindex complex numbers, conversion to
3136 @cindex conversion, to complex
3139 @item @emph{Description}:
3140 @code{DCMPLX(X [,Y])} returns a double complex number where @var{X} is
3141 converted to the real component. If @var{Y} is present it is converted to the
3142 imaginary component. If @var{Y} is not present then the imaginary component is
3143 set to 0.0. If @var{X} is complex then @var{Y} must not be present.
3145 @item @emph{Standard}:
3151 @item @emph{Syntax}:
3152 @code{RESULT = DCMPLX(X [, Y])}
3154 @item @emph{Arguments}:
3155 @multitable @columnfractions .15 .70
3156 @item @var{X} @tab The type may be @code{INTEGER}, @code{REAL},
3158 @item @var{Y} @tab (Optional if @var{X} is not @code{COMPLEX}.) May be
3159 @code{INTEGER} or @code{REAL}.
3162 @item @emph{Return value}:
3163 The return value is of type @code{COMPLEX(8)}
3165 @item @emph{Example}:
3175 print *, dcmplx(x,i)
3176 end program test_dcmplx
3182 @section @code{DIGITS} --- Significant binary digits function
3184 @cindex model representation, significant digits
3187 @item @emph{Description}:
3188 @code{DIGITS(X)} returns the number of significant binary digits of the internal
3189 model representation of @var{X}. For example, on a system using a 32-bit
3190 floating point representation, a default real number would likely return 24.
3192 @item @emph{Standard}:
3193 Fortran 95 and later
3198 @item @emph{Syntax}:
3199 @code{RESULT = DIGITS(X)}
3201 @item @emph{Arguments}:
3202 @multitable @columnfractions .15 .70
3203 @item @var{X} @tab The type may be @code{INTEGER} or @code{REAL}.
3206 @item @emph{Return value}:
3207 The return value is of type @code{INTEGER}.
3209 @item @emph{Example}:
3212 integer :: i = 12345
3218 end program test_digits
3225 @section @code{DIM} --- Positive difference
3229 @cindex positive difference
3232 @item @emph{Description}:
3233 @code{DIM(X,Y)} returns the difference @code{X-Y} if the result is positive;
3234 otherwise returns zero.
3236 @item @emph{Standard}:
3237 Fortran 77 and later
3242 @item @emph{Syntax}:
3243 @code{RESULT = DIM(X, Y)}
3245 @item @emph{Arguments}:
3246 @multitable @columnfractions .15 .70
3247 @item @var{X} @tab The type shall be @code{INTEGER} or @code{REAL}
3248 @item @var{Y} @tab The type shall be the same type and kind as @var{X}.
3251 @item @emph{Return value}:
3252 The return value is of type @code{INTEGER} or @code{REAL}.
3254 @item @emph{Example}:
3260 x = dim(4.345_8, 2.111_8)
3263 end program test_dim
3266 @item @emph{Specific names}:
3267 @multitable @columnfractions .20 .20 .20 .25
3268 @item Name @tab Argument @tab Return type @tab Standard
3269 @item @code{DIM(X,Y)} @tab @code{REAL(4) X, Y} @tab @code{REAL(4)} @tab Fortran 77 and later
3270 @item @code{IDIM(X,Y)} @tab @code{INTEGER(4) X, Y} @tab @code{INTEGER(4)} @tab Fortran 77 and later
3271 @item @code{DDIM(X,Y)} @tab @code{REAL(8) X, Y} @tab @code{REAL(8)} @tab Fortran 77 and later
3278 @section @code{DOT_PRODUCT} --- Dot product function
3279 @fnindex DOT_PRODUCT
3281 @cindex vector product
3282 @cindex product, vector
3285 @item @emph{Description}:
3286 @code{DOT_PRODUCT(VECTOR_A, VECTOR_B)} computes the dot product multiplication
3287 of two vectors @var{VECTOR_A} and @var{VECTOR_B}. The two vectors may be
3288 either numeric or logical and must be arrays of rank one and of equal size. If
3289 the vectors are @code{INTEGER} or @code{REAL}, the result is
3290 @code{SUM(VECTOR_A*VECTOR_B)}. If the vectors are @code{COMPLEX}, the result
3291 is @code{SUM(CONJG(VECTOR_A)*VECTOR_B)}. If the vectors are @code{LOGICAL},
3292 the result is @code{ANY(VECTOR_A .AND. VECTOR_B)}.
3294 @item @emph{Standard}:
3295 Fortran 95 and later
3298 Transformational function
3300 @item @emph{Syntax}:
3301 @code{RESULT = DOT_PRODUCT(VECTOR_A, VECTOR_B)}
3303 @item @emph{Arguments}:
3304 @multitable @columnfractions .15 .70
3305 @item @var{VECTOR_A} @tab The type shall be numeric or @code{LOGICAL}, rank 1.
3306 @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.
3309 @item @emph{Return value}:
3310 If the arguments are numeric, the return value is a scalar of numeric type,
3311 @code{INTEGER}, @code{REAL}, or @code{COMPLEX}. If the arguments are
3312 @code{LOGICAL}, the return value is @code{.TRUE.} or @code{.FALSE.}.
3314 @item @emph{Example}:
3316 program test_dot_prod
3317 integer, dimension(3) :: a, b
3324 print *, dot_product(a,b)
3325 end program test_dot_prod
3332 @section @code{DPROD} --- Double product function
3334 @cindex product, double-precision
3337 @item @emph{Description}:
3338 @code{DPROD(X,Y)} returns the product @code{X*Y}.
3340 @item @emph{Standard}:
3341 Fortran 77 and later
3346 @item @emph{Syntax}:
3347 @code{RESULT = DPROD(X, Y)}
3349 @item @emph{Arguments}:
3350 @multitable @columnfractions .15 .70
3351 @item @var{X} @tab The type shall be @code{REAL}.
3352 @item @var{Y} @tab The type shall be @code{REAL}.
3355 @item @emph{Return value}:
3356 The return value is of type @code{REAL(8)}.
3358 @item @emph{Example}:
3366 end program test_dprod
3369 @item @emph{Specific names}:
3370 @multitable @columnfractions .20 .20 .20 .25
3371 @item Name @tab Argument @tab Return type @tab Standard
3372 @item @code{DPROD(X,Y)} @tab @code{REAL(4) X, Y} @tab @code{REAL(4)} @tab Fortran 77 and later
3379 @section @code{DREAL} --- Double real part function
3381 @cindex complex numbers, real part
3384 @item @emph{Description}:
3385 @code{DREAL(Z)} returns the real part of complex variable @var{Z}.
3387 @item @emph{Standard}:
3393 @item @emph{Syntax}:
3394 @code{RESULT = DREAL(A)}
3396 @item @emph{Arguments}:
3397 @multitable @columnfractions .15 .70
3398 @item @var{A} @tab The type shall be @code{COMPLEX(8)}.
3401 @item @emph{Return value}:
3402 The return value is of type @code{REAL(8)}.
3404 @item @emph{Example}:
3407 complex(8) :: z = (1.3_8,7.2_8)
3409 end program test_dreal
3412 @item @emph{See also}:
3420 @section @code{DTIME} --- Execution time subroutine (or function)
3422 @cindex time, elapsed
3423 @cindex elapsed time
3426 @item @emph{Description}:
3427 @code{DTIME(VALUES, TIME)} initially returns the number of seconds of runtime
3428 since the start of the process's execution in @var{TIME}. @var{VALUES}
3429 returns the user and system components of this time in @code{VALUES(1)} and
3430 @code{VALUES(2)} respectively. @var{TIME} is equal to @code{VALUES(1) +
3433 Subsequent invocations of @code{DTIME} return values accumulated since the
3434 previous invocation.
3436 On some systems, the underlying timings are represented using types with
3437 sufficiently small limits that overflows (wrap around) are possible, such as
3438 32-bit types. Therefore, the values returned by this intrinsic might be, or
3439 become, negative, or numerically less than previous values, during a single
3440 run of the compiled program.
3442 Please note, that this implementation is thread safe if used within OpenMP
3443 directives, i.e., its state will be consistent while called from multiple
3444 threads. However, if @code{DTIME} is called from multiple threads, the result
3445 is still the time since the last invocation. This may not give the intended
3446 results. If possible, use @code{CPU_TIME} instead.
3448 This intrinsic is provided in both subroutine and function forms; however,
3449 only one form can be used in any given program unit.
3451 @var{VALUES} and @var{TIME} are @code{INTENT(OUT)} and provide the following:
3453 @multitable @columnfractions .15 .30 .40
3454 @item @tab @code{VALUES(1)}: @tab User time in seconds.
3455 @item @tab @code{VALUES(2)}: @tab System time in seconds.
3456 @item @tab @code{TIME}: @tab Run time since start in seconds.
3459 @item @emph{Standard}:
3463 Subroutine, function
3465 @item @emph{Syntax}:
3466 @multitable @columnfractions .80
3467 @item @code{CALL DTIME(VALUES, TIME)}.
3468 @item @code{TIME = DTIME(VALUES)}, (not recommended).
3471 @item @emph{Arguments}:
3472 @multitable @columnfractions .15 .70
3473 @item @var{VALUES}@tab The type shall be @code{REAL(4), DIMENSION(2)}.
3474 @item @var{TIME}@tab The type shall be @code{REAL(4)}.
3477 @item @emph{Return value}:
3478 Elapsed time in seconds since the last invocation or since the start of program
3479 execution if not called before.
3481 @item @emph{Example}:
3485 real, dimension(2) :: tarray
3487 call dtime(tarray, result)
3491 do i=1,100000000 ! Just a delay
3494 call dtime(tarray, result)
3498 end program test_dtime
3501 @item @emph{See also}:
3509 @section @code{EOSHIFT} --- End-off shift elements of an array
3511 @cindex array, shift
3514 @item @emph{Description}:
3515 @code{EOSHIFT(ARRAY, SHIFT[, BOUNDARY, DIM])} performs an end-off shift on
3516 elements of @var{ARRAY} along the dimension of @var{DIM}. If @var{DIM} is
3517 omitted it is taken to be @code{1}. @var{DIM} is a scalar of type
3518 @code{INTEGER} in the range of @math{1 \leq DIM \leq n)} where @math{n} is the
3519 rank of @var{ARRAY}. If the rank of @var{ARRAY} is one, then all elements of
3520 @var{ARRAY} are shifted by @var{SHIFT} places. If rank is greater than one,
3521 then all complete rank one sections of @var{ARRAY} along the given dimension are
3522 shifted. Elements shifted out one end of each rank one section are dropped. If
3523 @var{BOUNDARY} is present then the corresponding value of from @var{BOUNDARY}
3524 is copied back in the other end. If @var{BOUNDARY} is not present then the
3525 following are copied in depending on the type of @var{ARRAY}.
3527 @multitable @columnfractions .15 .80
3528 @item @emph{Array Type} @tab @emph{Boundary Value}
3529 @item Numeric @tab 0 of the type and kind of @var{ARRAY}.
3530 @item Logical @tab @code{.FALSE.}.
3531 @item Character(@var{len}) @tab @var{len} blanks.
3534 @item @emph{Standard}:
3535 Fortran 95 and later
3538 Transformational function
3540 @item @emph{Syntax}:
3541 @code{RESULT = EOSHIFT(ARRAY, SHIFT [, BOUNDARY, DIM])}
3543 @item @emph{Arguments}:
3544 @multitable @columnfractions .15 .70
3545 @item @var{ARRAY} @tab May be any type, not scalar.
3546 @item @var{SHIFT} @tab The type shall be @code{INTEGER}.
3547 @item @var{BOUNDARY} @tab Same type as @var{ARRAY}.
3548 @item @var{DIM} @tab The type shall be @code{INTEGER}.
3551 @item @emph{Return value}:
3552 Returns an array of same type and rank as the @var{ARRAY} argument.
3554 @item @emph{Example}:
3556 program test_eoshift
3557 integer, dimension(3,3) :: a
3558 a = reshape( (/ 1, 2, 3, 4, 5, 6, 7, 8, 9 /), (/ 3, 3 /))
3559 print '(3i3)', a(1,:)
3560 print '(3i3)', a(2,:)
3561 print '(3i3)', a(3,:)
3562 a = EOSHIFT(a, SHIFT=(/1, 2, 1/), BOUNDARY=-5, DIM=2)
3564 print '(3i3)', a(1,:)
3565 print '(3i3)', a(2,:)
3566 print '(3i3)', a(3,:)
3567 end program test_eoshift
3574 @section @code{EPSILON} --- Epsilon function
3576 @cindex model representation, epsilon
3579 @item @emph{Description}:
3580 @code{EPSILON(X)} returns the smallest number @var{E} of the same kind
3581 as @var{X} such that @math{1 + E > 1}.
3583 @item @emph{Standard}:
3584 Fortran 95 and later
3589 @item @emph{Syntax}:
3590 @code{RESULT = EPSILON(X)}
3592 @item @emph{Arguments}:
3593 @multitable @columnfractions .15 .70
3594 @item @var{X} @tab The type shall be @code{REAL}.
3597 @item @emph{Return value}:
3598 The return value is of same type as the argument.
3600 @item @emph{Example}:
3602 program test_epsilon
3607 end program test_epsilon
3614 @section @code{ERF} --- Error function
3616 @cindex error function
3619 @item @emph{Description}:
3620 @code{ERF(X)} computes the error function of @var{X}.
3622 @item @emph{Standard}:
3623 Fortran 2008 and later
3628 @item @emph{Syntax}:
3629 @code{RESULT = ERF(X)}
3631 @item @emph{Arguments}:
3632 @multitable @columnfractions .15 .70
3633 @item @var{X} @tab The type shall be @code{REAL}.
3636 @item @emph{Return value}:
3637 The return value is of type @code{REAL}, of the same kind as
3638 @var{X} and lies in the range @math{-1 \leq erf (x) \leq 1 }.
3640 @item @emph{Example}:
3643 real(8) :: x = 0.17_8
3645 end program test_erf
3648 @item @emph{Specific names}:
3649 @multitable @columnfractions .20 .20 .20 .25
3650 @item Name @tab Argument @tab Return type @tab Standard
3651 @item @code{DERF(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU extension
3658 @section @code{ERFC} --- Error function
3660 @cindex error function, complementary
3663 @item @emph{Description}:
3664 @code{ERFC(X)} computes the complementary error function of @var{X}.
3666 @item @emph{Standard}:
3667 Fortran 2008 and later
3672 @item @emph{Syntax}:
3673 @code{RESULT = ERFC(X)}
3675 @item @emph{Arguments}:
3676 @multitable @columnfractions .15 .70
3677 @item @var{X} @tab The type shall be @code{REAL}.
3680 @item @emph{Return value}:
3681 The return value is of type @code{REAL} and of the same kind as @var{X}.
3682 It lies in the range @math{ 0 \leq erfc (x) \leq 2 }.
3684 @item @emph{Example}:
3687 real(8) :: x = 0.17_8
3689 end program test_erfc
3692 @item @emph{Specific names}:
3693 @multitable @columnfractions .20 .20 .20 .25
3694 @item Name @tab Argument @tab Return type @tab Standard
3695 @item @code{DERFC(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU extension
3702 @section @code{ERFC_SCALED} --- Error function
3703 @fnindex ERFC_SCALED
3704 @cindex error function, complementary, exponentially-scaled
3707 @item @emph{Description}:
3708 @code{ERFC_SCALED(X)} computes the exponentially-scaled complementary
3709 error function of @var{X}.
3711 @item @emph{Standard}:
3712 Fortran 2008 and later
3717 @item @emph{Syntax}:
3718 @code{RESULT = ERFC_SCALED(X)}
3720 @item @emph{Arguments}:
3721 @multitable @columnfractions .15 .70
3722 @item @var{X} @tab The type shall be @code{REAL}.
3725 @item @emph{Return value}:
3726 The return value is of type @code{REAL} and of the same kind as @var{X}.
3728 @item @emph{Example}:
3730 program test_erfc_scaled
3731 real(8) :: x = 0.17_8
3733 end program test_erfc_scaled
3740 @section @code{ETIME} --- Execution time subroutine (or function)
3742 @cindex time, elapsed
3745 @item @emph{Description}:
3746 @code{ETIME(VALUES, TIME)} returns the number of seconds of runtime
3747 since the start of the process's execution in @var{TIME}. @var{VALUES}
3748 returns the user and system components of this time in @code{VALUES(1)} and
3749 @code{VALUES(2)} respectively. @var{TIME} is equal to @code{VALUES(1) + VALUES(2)}.
3751 On some systems, the underlying timings are represented using types with
3752 sufficiently small limits that overflows (wrap around) are possible, such as
3753 32-bit types. Therefore, the values returned by this intrinsic might be, or
3754 become, negative, or numerically less than previous values, during a single
3755 run of the compiled program.
3757 This intrinsic is provided in both subroutine and function forms; however,
3758 only one form can be used in any given program unit.
3760 @var{VALUES} and @var{TIME} are @code{INTENT(OUT)} and provide the following:
3762 @multitable @columnfractions .15 .30 .60
3763 @item @tab @code{VALUES(1)}: @tab User time in seconds.
3764 @item @tab @code{VALUES(2)}: @tab System time in seconds.
3765 @item @tab @code{TIME}: @tab Run time since start in seconds.
3768 @item @emph{Standard}:
3772 Subroutine, function
3774 @item @emph{Syntax}:
3775 @multitable @columnfractions .80
3776 @item @code{CALL ETIME(VALUES, TIME)}.
3777 @item @code{TIME = ETIME(VALUES)}, (not recommended).
3780 @item @emph{Arguments}:
3781 @multitable @columnfractions .15 .70
3782 @item @var{VALUES}@tab The type shall be @code{REAL(4), DIMENSION(2)}.
3783 @item @var{TIME}@tab The type shall be @code{REAL(4)}.
3786 @item @emph{Return value}:
3787 Elapsed time in seconds since the start of program execution.
3789 @item @emph{Example}:
3793 real, dimension(2) :: tarray
3795 call ETIME(tarray, result)
3799 do i=1,100000000 ! Just a delay
3802 call ETIME(tarray, result)
3806 end program test_etime
3809 @item @emph{See also}:
3817 @section @code{EXIT} --- Exit the program with status.
3819 @cindex program termination
3820 @cindex terminate program
3823 @item @emph{Description}:
3824 @code{EXIT} causes immediate termination of the program with status. If status
3825 is omitted it returns the canonical @emph{success} for the system. All Fortran
3826 I/O units are closed.
3828 @item @emph{Standard}:
3834 @item @emph{Syntax}:
3835 @code{CALL EXIT([STATUS])}
3837 @item @emph{Arguments}:
3838 @multitable @columnfractions .15 .70
3839 @item @var{STATUS} @tab Shall be an @code{INTEGER} of the default kind.
3842 @item @emph{Return value}:
3843 @code{STATUS} is passed to the parent process on exit.
3845 @item @emph{Example}:
3848 integer :: STATUS = 0
3849 print *, 'This program is going to exit.'
3851 end program test_exit
3854 @item @emph{See also}:
3855 @ref{ABORT}, @ref{KILL}
3861 @section @code{EXP} --- Exponential function
3867 @cindex exponential function
3868 @cindex logarithmic function, inverse
3871 @item @emph{Description}:
3872 @code{EXP(X)} computes the base @math{e} exponential of @var{X}.
3874 @item @emph{Standard}:
3875 Fortran 77 and later, has overloads that are GNU extensions
3880 @item @emph{Syntax}:
3881 @code{RESULT = EXP(X)}
3883 @item @emph{Arguments}:
3884 @multitable @columnfractions .15 .70
3885 @item @var{X} @tab The type shall be @code{REAL} or
3889 @item @emph{Return value}:
3890 The return value has same type and kind as @var{X}.
3892 @item @emph{Example}:
3897 end program test_exp
3900 @item @emph{Specific names}:
3901 @multitable @columnfractions .20 .20 .20 .25
3902 @item Name @tab Argument @tab Return type @tab Standard
3903 @item @code{EXP(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab Fortran 77 and later
3904 @item @code{DEXP(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab Fortran 77 and later
3905 @item @code{CEXP(X)} @tab @code{COMPLEX(4) X} @tab @code{COMPLEX(4)} @tab Fortran 77 and later
3906 @item @code{ZEXP(X)} @tab @code{COMPLEX(8) X} @tab @code{COMPLEX(8)} @tab GNU extension
3907 @item @code{CDEXP(X)} @tab @code{COMPLEX(8) X} @tab @code{COMPLEX(8)} @tab GNU extension
3914 @section @code{EXPONENT} --- Exponent function
3916 @cindex real number, exponent
3917 @cindex floating point, exponent
3920 @item @emph{Description}:
3921 @code{EXPONENT(X)} returns the value of the exponent part of @var{X}. If @var{X}
3922 is zero the value returned is zero.
3924 @item @emph{Standard}:
3925 Fortran 95 and later
3930 @item @emph{Syntax}:
3931 @code{RESULT = EXPONENT(X)}
3933 @item @emph{Arguments}:
3934 @multitable @columnfractions .15 .70
3935 @item @var{X} @tab The type shall be @code{REAL}.
3938 @item @emph{Return value}:
3939 The return value is of type default @code{INTEGER}.
3941 @item @emph{Example}:
3943 program test_exponent
3948 print *, exponent(0.0)
3949 end program test_exponent
3955 @node EXTENDS_TYPE_OF
3956 @section @code{EXTENDS_TYPE_OF} --- Query dynamic type for extension
3957 @fnindex EXTENDS_TYPE_OF
3960 @item @emph{Description}:
3961 Query dynamic type for extension.
3963 @item @emph{Standard}:
3964 Fortran 2003 and later
3969 @item @emph{Syntax}:
3970 @code{RESULT = EXTENDS_TYPE_OF(A, MOLD)}
3972 @item @emph{Arguments}:
3973 @multitable @columnfractions .15 .70
3974 @item @var{A} @tab Shall be an object of extensible declared type or
3975 unlimited polymorphic.
3976 @item @var{MOLD} @tab Shall be an object of extensible declared type or
3977 unlimited polymorphic.
3980 @item @emph{Return value}:
3981 The return value is a scalar of type default logical. It is true if and only if
3982 the dynamic type of A is an extension type of the dynamic type of MOLD.
3985 @item @emph{See also}:
3992 @section @code{FDATE} --- Get the current time as a string
3994 @cindex time, current
3995 @cindex current time
3996 @cindex date, current
3997 @cindex current date
4000 @item @emph{Description}:
4001 @code{FDATE(DATE)} returns the current date (using the same format as
4002 @code{CTIME}) in @var{DATE}. It is equivalent to @code{CALL CTIME(DATE,
4005 This intrinsic is provided in both subroutine and function forms; however,
4006 only one form can be used in any given program unit.
4008 @var{DATE} is an @code{INTENT(OUT)} @code{CHARACTER} variable of the
4011 @item @emph{Standard}:
4015 Subroutine, function
4017 @item @emph{Syntax}:
4018 @multitable @columnfractions .80
4019 @item @code{CALL FDATE(DATE)}.
4020 @item @code{DATE = FDATE()}, (not recommended).
4023 @item @emph{Arguments}:
4024 @multitable @columnfractions .15 .70
4025 @item @var{DATE}@tab The type shall be of type @code{CHARACTER} of the
4029 @item @emph{Return value}:
4030 The current date as a string.
4032 @item @emph{Example}:
4036 character(len=30) :: date
4038 print *, 'Program started on ', date
4039 do i = 1, 100000000 ! Just a delay
4043 print *, 'Program ended on ', date
4044 end program test_fdate
4051 @section @code{FGET} --- Read a single character in stream mode from stdin
4053 @cindex read character, stream mode
4054 @cindex stream mode, read character
4055 @cindex file operation, read character
4058 @item @emph{Description}:
4059 Read a single character in stream mode from stdin by bypassing normal
4060 formatted output. Stream I/O should not be mixed with normal record-oriented
4061 (formatted or unformatted) I/O on the same unit; the results are unpredictable.
4063 This intrinsic is provided in both subroutine and function forms; however,
4064 only one form can be used in any given program unit.
4066 Note that the @code{FGET} intrinsic is provided for backwards compatibility with
4067 @command{g77}. GNU Fortran provides the Fortran 2003 Stream facility.
4068 Programmers should consider the use of new stream IO feature in new code
4069 for future portability. See also @ref{Fortran 2003 status}.
4071 @item @emph{Standard}:
4075 Subroutine, function
4077 @item @emph{Syntax}:
4078 @code{CALL FGET(C [, STATUS])}
4080 @item @emph{Arguments}:
4081 @multitable @columnfractions .15 .70
4082 @item @var{C} @tab The type shall be @code{CHARACTER} and of default
4084 @item @var{STATUS} @tab (Optional) status flag of type @code{INTEGER}.
4085 Returns 0 on success, -1 on end-of-file, and a system specific positive
4086 error code otherwise.
4089 @item @emph{Example}:
4092 INTEGER, PARAMETER :: strlen = 100
4093 INTEGER :: status, i = 1
4094 CHARACTER(len=strlen) :: str = ""
4096 WRITE (*,*) 'Enter text:'
4098 CALL fget(str(i:i), status)
4099 if (status /= 0 .OR. i > strlen) exit
4102 WRITE (*,*) TRIM(str)
4106 @item @emph{See also}:
4107 @ref{FGETC}, @ref{FPUT}, @ref{FPUTC}
4113 @section @code{FGETC} --- Read a single character in stream mode
4115 @cindex read character, stream mode
4116 @cindex stream mode, read character
4117 @cindex file operation, read character
4120 @item @emph{Description}:
4121 Read a single character in stream mode by bypassing normal formatted output.
4122 Stream I/O should not be mixed with normal record-oriented (formatted or
4123 unformatted) I/O on the same unit; the results are unpredictable.
4125 This intrinsic is provided in both subroutine and function forms; however,
4126 only one form can be used in any given program unit.
4128 Note that the @code{FGET} intrinsic is provided for backwards compatibility
4129 with @command{g77}. GNU Fortran provides the Fortran 2003 Stream facility.
4130 Programmers should consider the use of new stream IO feature in new code
4131 for future portability. See also @ref{Fortran 2003 status}.
4133 @item @emph{Standard}:
4137 Subroutine, function
4139 @item @emph{Syntax}:
4140 @code{CALL FGETC(UNIT, C [, STATUS])}
4142 @item @emph{Arguments}:
4143 @multitable @columnfractions .15 .70
4144 @item @var{UNIT} @tab The type shall be @code{INTEGER}.
4145 @item @var{C} @tab The type shall be @code{CHARACTER} and of default
4147 @item @var{STATUS} @tab (Optional) status flag of type @code{INTEGER}.
4148 Returns 0 on success, -1 on end-of-file and a system specific positive
4149 error code otherwise.
4152 @item @emph{Example}:
4155 INTEGER :: fd = 42, status
4158 OPEN(UNIT=fd, FILE="/etc/passwd", ACTION="READ", STATUS = "OLD")
4160 CALL fgetc(fd, c, status)
4161 IF (status /= 0) EXIT
4168 @item @emph{See also}:
4169 @ref{FGET}, @ref{FPUT}, @ref{FPUTC}
4175 @section @code{FLOOR} --- Integer floor function
4178 @cindex rounding, floor
4181 @item @emph{Description}:
4182 @code{FLOOR(A)} returns the greatest integer less than or equal to @var{X}.
4184 @item @emph{Standard}:
4185 Fortran 95 and later
4190 @item @emph{Syntax}:
4191 @code{RESULT = FLOOR(A [, KIND])}
4193 @item @emph{Arguments}:
4194 @multitable @columnfractions .15 .70
4195 @item @var{A} @tab The type shall be @code{REAL}.
4196 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
4197 expression indicating the kind parameter of the result.
4200 @item @emph{Return value}:
4201 The return value is of type @code{INTEGER(KIND)} if @var{KIND} is present
4202 and of default-kind @code{INTEGER} otherwise.
4204 @item @emph{Example}:
4209 print *, floor(x) ! returns 63
4210 print *, floor(y) ! returns -64
4211 end program test_floor
4214 @item @emph{See also}:
4215 @ref{CEILING}, @ref{NINT}
4222 @section @code{FLUSH} --- Flush I/O unit(s)
4224 @cindex file operation, flush
4227 @item @emph{Description}:
4228 Flushes Fortran unit(s) currently open for output. Without the optional
4229 argument, all units are flushed, otherwise just the unit specified.
4231 @item @emph{Standard}:
4237 @item @emph{Syntax}:
4238 @code{CALL FLUSH(UNIT)}
4240 @item @emph{Arguments}:
4241 @multitable @columnfractions .15 .70
4242 @item @var{UNIT} @tab (Optional) The type shall be @code{INTEGER}.
4246 Beginning with the Fortran 2003 standard, there is a @code{FLUSH}
4247 statement that should be preferred over the @code{FLUSH} intrinsic.
4249 The @code{FLUSH} intrinsic and the Fortran 2003 @code{FLUSH} statement
4250 have identical effect: they flush the runtime library's I/O buffer so
4251 that the data becomes visible to other processes. This does not guarantee
4252 that the data is committed to disk.
4254 On POSIX systems, you can request that all data is transferred to the
4255 storage device by calling the @code{fsync} function, with the POSIX file
4256 descriptor of the I/O unit as argument (retrieved with GNU intrinsic
4257 @code{FNUM}). The following example shows how:
4260 ! Declare the interface for POSIX fsync function
4262 function fsync (fd) bind(c,name="fsync")
4263 use iso_c_binding, only: c_int
4264 integer(c_int), value :: fd
4265 integer(c_int) :: fsync
4269 ! Variable declaration
4273 open (10,file="foo")
4276 ! Perform I/O on unit 10
4281 ret = fsync(fnum(10))
4283 ! Handle possible error
4284 if (ret /= 0) stop "Error calling FSYNC"
4292 @section @code{FNUM} --- File number function
4294 @cindex file operation, file number
4297 @item @emph{Description}:
4298 @code{FNUM(UNIT)} returns the POSIX file descriptor number corresponding to the
4299 open Fortran I/O unit @code{UNIT}.
4301 @item @emph{Standard}:
4307 @item @emph{Syntax}:
4308 @code{RESULT = FNUM(UNIT)}
4310 @item @emph{Arguments}:
4311 @multitable @columnfractions .15 .70
4312 @item @var{UNIT} @tab The type shall be @code{INTEGER}.
4315 @item @emph{Return value}:
4316 The return value is of type @code{INTEGER}
4318 @item @emph{Example}:
4322 open (unit=10, status = "scratch")
4326 end program test_fnum
4333 @section @code{FPUT} --- Write a single character in stream mode to stdout
4335 @cindex write character, stream mode
4336 @cindex stream mode, write character
4337 @cindex file operation, write character
4340 @item @emph{Description}:
4341 Write a single character in stream mode to stdout by bypassing normal
4342 formatted output. Stream I/O should not be mixed with normal record-oriented
4343 (formatted or unformatted) I/O on the same unit; the results are unpredictable.
4345 This intrinsic is provided in both subroutine and function forms; however,
4346 only one form can be used in any given program unit.
4348 Note that the @code{FGET} intrinsic is provided for backwards compatibility with
4349 @command{g77}. GNU Fortran provides the Fortran 2003 Stream facility.
4350 Programmers should consider the use of new stream IO feature in new code
4351 for future portability. See also @ref{Fortran 2003 status}.
4353 @item @emph{Standard}:
4357 Subroutine, function
4359 @item @emph{Syntax}:
4360 @code{CALL FPUT(C [, STATUS])}
4362 @item @emph{Arguments}:
4363 @multitable @columnfractions .15 .70
4364 @item @var{C} @tab The type shall be @code{CHARACTER} and of default
4366 @item @var{STATUS} @tab (Optional) status flag of type @code{INTEGER}.
4367 Returns 0 on success, -1 on end-of-file and a system specific positive
4368 error code otherwise.
4371 @item @emph{Example}:
4374 CHARACTER(len=10) :: str = "gfortran"
4376 DO i = 1, len_trim(str)
4382 @item @emph{See also}:
4383 @ref{FPUTC}, @ref{FGET}, @ref{FGETC}
4389 @section @code{FPUTC} --- Write a single character in stream mode
4391 @cindex write character, stream mode
4392 @cindex stream mode, write character
4393 @cindex file operation, write character
4396 @item @emph{Description}:
4397 Write a single character in stream mode by bypassing normal formatted
4398 output. Stream I/O should not be mixed with normal record-oriented
4399 (formatted or unformatted) I/O on the same unit; the results are unpredictable.
4401 This intrinsic is provided in both subroutine and function forms; however,
4402 only one form can be used in any given program unit.
4404 Note that the @code{FGET} intrinsic is provided for backwards compatibility with
4405 @command{g77}. GNU Fortran provides the Fortran 2003 Stream facility.
4406 Programmers should consider the use of new stream IO feature in new code
4407 for future portability. See also @ref{Fortran 2003 status}.
4409 @item @emph{Standard}:
4413 Subroutine, function
4415 @item @emph{Syntax}:
4416 @code{CALL FPUTC(UNIT, C [, STATUS])}
4418 @item @emph{Arguments}:
4419 @multitable @columnfractions .15 .70
4420 @item @var{UNIT} @tab The type shall be @code{INTEGER}.
4421 @item @var{C} @tab The type shall be @code{CHARACTER} and of default
4423 @item @var{STATUS} @tab (Optional) status flag of type @code{INTEGER}.
4424 Returns 0 on success, -1 on end-of-file and a system specific positive
4425 error code otherwise.
4428 @item @emph{Example}:
4431 CHARACTER(len=10) :: str = "gfortran"
4432 INTEGER :: fd = 42, i
4434 OPEN(UNIT = fd, FILE = "out", ACTION = "WRITE", STATUS="NEW")
4435 DO i = 1, len_trim(str)
4436 CALL fputc(fd, str(i:i))
4442 @item @emph{See also}:
4443 @ref{FPUT}, @ref{FGET}, @ref{FGETC}
4449 @section @code{FRACTION} --- Fractional part of the model representation
4451 @cindex real number, fraction
4452 @cindex floating point, fraction
4455 @item @emph{Description}:
4456 @code{FRACTION(X)} returns the fractional part of the model
4457 representation of @code{X}.
4459 @item @emph{Standard}:
4460 Fortran 95 and later
4465 @item @emph{Syntax}:
4466 @code{Y = FRACTION(X)}
4468 @item @emph{Arguments}:
4469 @multitable @columnfractions .15 .70
4470 @item @var{X} @tab The type of the argument shall be a @code{REAL}.
4473 @item @emph{Return value}:
4474 The return value is of the same type and kind as the argument.
4475 The fractional part of the model representation of @code{X} is returned;
4476 it is @code{X * RADIX(X)**(-EXPONENT(X))}.
4478 @item @emph{Example}:
4480 program test_fraction
4483 print *, fraction(x), x * radix(x)**(-exponent(x))
4484 end program test_fraction
4492 @section @code{FREE} --- Frees memory
4494 @cindex pointer, cray
4497 @item @emph{Description}:
4498 Frees memory previously allocated by @code{MALLOC()}. The @code{FREE}
4499 intrinsic is an extension intended to be used with Cray pointers, and is
4500 provided in GNU Fortran to allow user to compile legacy code. For
4501 new code using Fortran 95 pointers, the memory de-allocation intrinsic is
4504 @item @emph{Standard}:
4510 @item @emph{Syntax}:
4511 @code{CALL FREE(PTR)}
4513 @item @emph{Arguments}:
4514 @multitable @columnfractions .15 .70
4515 @item @var{PTR} @tab The type shall be @code{INTEGER}. It represents the
4516 location of the memory that should be de-allocated.
4519 @item @emph{Return value}:
4522 @item @emph{Example}:
4523 See @code{MALLOC} for an example.
4525 @item @emph{See also}:
4532 @section @code{FSEEK} --- Low level file positioning subroutine
4534 @cindex file operation, seek
4535 @cindex file operation, position
4538 @item @emph{Description}:
4539 Moves @var{UNIT} to the specified @var{OFFSET}. If @var{WHENCE}
4540 is set to 0, the @var{OFFSET} is taken as an absolute value @code{SEEK_SET},
4541 if set to 1, @var{OFFSET} is taken to be relative to the current position
4542 @code{SEEK_CUR}, and if set to 2 relative to the end of the file @code{SEEK_END}.
4543 On error, @var{STATUS} is set to a nonzero value. If @var{STATUS} the seek
4546 This intrinsic routine is not fully backwards compatible with @command{g77}.
4547 In @command{g77}, the @code{FSEEK} takes a statement label instead of a
4548 @var{STATUS} variable. If FSEEK is used in old code, change
4550 CALL FSEEK(UNIT, OFFSET, WHENCE, *label)
4555 CALL FSEEK(UNIT, OFFSET, WHENCE, status)
4556 IF (status /= 0) GOTO label
4559 Please note that GNU Fortran provides the Fortran 2003 Stream facility.
4560 Programmers should consider the use of new stream IO feature in new code
4561 for future portability. See also @ref{Fortran 2003 status}.
4563 @item @emph{Standard}:
4569 @item @emph{Syntax}:
4570 @code{CALL FSEEK(UNIT, OFFSET, WHENCE[, STATUS])}
4572 @item @emph{Arguments}:
4573 @multitable @columnfractions .15 .70
4574 @item @var{UNIT} @tab Shall be a scalar of type @code{INTEGER}.
4575 @item @var{OFFSET} @tab Shall be a scalar of type @code{INTEGER}.
4576 @item @var{WHENCE} @tab Shall be a scalar of type @code{INTEGER}.
4577 Its value shall be either 0, 1 or 2.
4578 @item @var{STATUS} @tab (Optional) shall be a scalar of type
4582 @item @emph{Example}:
4585 INTEGER, PARAMETER :: SEEK_SET = 0, SEEK_CUR = 1, SEEK_END = 2
4586 INTEGER :: fd, offset, ierr
4592 OPEN(UNIT=fd, FILE="fseek.test")
4593 CALL FSEEK(fd, offset, SEEK_SET, ierr) ! move to OFFSET
4594 print *, FTELL(fd), ierr
4596 CALL FSEEK(fd, 0, SEEK_END, ierr) ! move to end
4597 print *, FTELL(fd), ierr
4599 CALL FSEEK(fd, 0, SEEK_SET, ierr) ! move to beginning
4600 print *, FTELL(fd), ierr
4606 @item @emph{See also}:
4613 @section @code{FSTAT} --- Get file status
4615 @cindex file system, file status
4618 @item @emph{Description}:
4619 @code{FSTAT} is identical to @ref{STAT}, except that information about an
4620 already opened file is obtained.
4622 The elements in @code{VALUES} are the same as described by @ref{STAT}.
4624 This intrinsic is provided in both subroutine and function forms; however,
4625 only one form can be used in any given program unit.
4627 @item @emph{Standard}:
4631 Subroutine, function
4633 @item @emph{Syntax}:
4634 @code{CALL FSTAT(UNIT, VALUES [, STATUS])}
4636 @item @emph{Arguments}:
4637 @multitable @columnfractions .15 .70
4638 @item @var{UNIT} @tab An open I/O unit number of type @code{INTEGER}.
4639 @item @var{VALUES} @tab The type shall be @code{INTEGER(4), DIMENSION(13)}.
4640 @item @var{STATUS} @tab (Optional) status flag of type @code{INTEGER(4)}. Returns 0
4641 on success and a system specific error code otherwise.
4644 @item @emph{Example}:
4645 See @ref{STAT} for an example.
4647 @item @emph{See also}:
4648 To stat a link: @ref{LSTAT}, to stat a file: @ref{STAT}
4654 @section @code{FTELL} --- Current stream position
4656 @cindex file operation, position
4659 @item @emph{Description}:
4660 Retrieves the current position within an open file.
4662 This intrinsic is provided in both subroutine and function forms; however,
4663 only one form can be used in any given program unit.
4665 @item @emph{Standard}:
4669 Subroutine, function
4671 @item @emph{Syntax}:
4672 @multitable @columnfractions .80
4673 @item @code{CALL FTELL(UNIT, OFFSET)}
4674 @item @code{OFFSET = FTELL(UNIT)}
4677 @item @emph{Arguments}:
4678 @multitable @columnfractions .15 .70
4679 @item @var{OFFSET} @tab Shall of type @code{INTEGER}.
4680 @item @var{UNIT} @tab Shall of type @code{INTEGER}.
4683 @item @emph{Return value}:
4684 In either syntax, @var{OFFSET} is set to the current offset of unit
4685 number @var{UNIT}, or to @math{-1} if the unit is not currently open.
4687 @item @emph{Example}:
4691 OPEN(10, FILE="temp.dat")
4697 @item @emph{See also}:
4704 @section @code{GAMMA} --- Gamma function
4707 @cindex Gamma function
4708 @cindex Factorial function
4711 @item @emph{Description}:
4712 @code{GAMMA(X)} computes Gamma (@math{\Gamma}) of @var{X}. For positive,
4713 integer values of @var{X} the Gamma function simplifies to the factorial
4714 function @math{\Gamma(x)=(x-1)!}.
4718 \Gamma(x) = \int_0^\infty t^{x-1}{\rm e}^{-t}\,{\rm d}t
4722 @item @emph{Standard}:
4723 Fortran 2008 and later
4728 @item @emph{Syntax}:
4731 @item @emph{Arguments}:
4732 @multitable @columnfractions .15 .70
4733 @item @var{X} @tab Shall be of type @code{REAL} and neither zero
4734 nor a negative integer.
4737 @item @emph{Return value}:
4738 The return value is of type @code{REAL} of the same kind as @var{X}.
4740 @item @emph{Example}:
4744 x = gamma(x) ! returns 1.0
4745 end program test_gamma
4748 @item @emph{Specific names}:
4749 @multitable @columnfractions .20 .20 .20 .25
4750 @item Name @tab Argument @tab Return type @tab Standard
4751 @item @code{GAMMA(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab GNU Extension
4752 @item @code{DGAMMA(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU Extension
4755 @item @emph{See also}:
4756 Logarithm of the Gamma function: @ref{LOG_GAMMA}
4763 @section @code{GERROR} --- Get last system error message
4765 @cindex system, error handling
4768 @item @emph{Description}:
4769 Returns the system error message corresponding to the last system error.
4770 This resembles the functionality of @code{strerror(3)} in C.
4772 @item @emph{Standard}:
4778 @item @emph{Syntax}:
4779 @code{CALL GERROR(RESULT)}
4781 @item @emph{Arguments}:
4782 @multitable @columnfractions .15 .70
4783 @item @var{RESULT} @tab Shall of type @code{CHARACTER} and of default
4786 @item @emph{Example}:
4789 CHARACTER(len=100) :: msg
4795 @item @emph{See also}:
4796 @ref{IERRNO}, @ref{PERROR}
4802 @section @code{GETARG} --- Get command line arguments
4804 @cindex command-line arguments
4805 @cindex arguments, to program
4808 @item @emph{Description}:
4809 Retrieve the @var{POS}-th argument that was passed on the
4810 command line when the containing program was invoked.
4812 This intrinsic routine is provided for backwards compatibility with
4813 GNU Fortran 77. In new code, programmers should consider the use of
4814 the @ref{GET_COMMAND_ARGUMENT} intrinsic defined by the Fortran 2003
4817 @item @emph{Standard}:
4823 @item @emph{Syntax}:
4824 @code{CALL GETARG(POS, VALUE)}
4826 @item @emph{Arguments}:
4827 @multitable @columnfractions .15 .70
4828 @item @var{POS} @tab Shall be of type @code{INTEGER} and not wider than
4829 the default integer kind; @math{@var{POS} \geq 0}
4830 @item @var{VALUE} @tab Shall be of type @code{CHARACTER} and of default
4832 @item @var{VALUE} @tab Shall be of type @code{CHARACTER}.
4835 @item @emph{Return value}:
4836 After @code{GETARG} returns, the @var{VALUE} argument holds the
4837 @var{POS}th command line argument. If @var{VALUE} can not hold the
4838 argument, it is truncated to fit the length of @var{VALUE}. If there are
4839 less than @var{POS} arguments specified at the command line, @var{VALUE}
4840 will be filled with blanks. If @math{@var{POS} = 0}, @var{VALUE} is set
4841 to the name of the program (on systems that support this feature).
4843 @item @emph{Example}:
4847 CHARACTER(len=32) :: arg
4856 @item @emph{See also}:
4857 GNU Fortran 77 compatibility function: @ref{IARGC}
4859 Fortran 2003 functions and subroutines: @ref{GET_COMMAND},
4860 @ref{GET_COMMAND_ARGUMENT}, @ref{COMMAND_ARGUMENT_COUNT}
4866 @section @code{GET_COMMAND} --- Get the entire command line
4867 @fnindex GET_COMMAND
4868 @cindex command-line arguments
4869 @cindex arguments, to program
4872 @item @emph{Description}:
4873 Retrieve the entire command line that was used to invoke the program.
4875 @item @emph{Standard}:
4876 Fortran 2003 and later
4881 @item @emph{Syntax}:
4882 @code{CALL GET_COMMAND([COMMAND, LENGTH, STATUS])}
4884 @item @emph{Arguments}:
4885 @multitable @columnfractions .15 .70
4886 @item @var{COMMAND} @tab (Optional) shall be of type @code{CHARACTER} and
4888 @item @var{LENGTH} @tab (Optional) Shall be of type @code{INTEGER} and of
4890 @item @var{STATUS} @tab (Optional) Shall be of type @code{INTEGER} and of
4894 @item @emph{Return value}:
4895 If @var{COMMAND} is present, stores the entire command line that was used
4896 to invoke the program in @var{COMMAND}. If @var{LENGTH} is present, it is
4897 assigned the length of the command line. If @var{STATUS} is present, it
4898 is assigned 0 upon success of the command, -1 if @var{COMMAND} is too
4899 short to store the command line, or a positive value in case of an error.
4901 @item @emph{Example}:
4903 PROGRAM test_get_command
4904 CHARACTER(len=255) :: cmd
4905 CALL get_command(cmd)
4906 WRITE (*,*) TRIM(cmd)
4910 @item @emph{See also}:
4911 @ref{GET_COMMAND_ARGUMENT}, @ref{COMMAND_ARGUMENT_COUNT}
4916 @node GET_COMMAND_ARGUMENT
4917 @section @code{GET_COMMAND_ARGUMENT} --- Get command line arguments
4918 @fnindex GET_COMMAND_ARGUMENT
4919 @cindex command-line arguments
4920 @cindex arguments, to program
4923 @item @emph{Description}:
4924 Retrieve the @var{NUMBER}-th argument that was passed on the
4925 command line when the containing program was invoked.
4927 @item @emph{Standard}:
4928 Fortran 2003 and later
4933 @item @emph{Syntax}:
4934 @code{CALL GET_COMMAND_ARGUMENT(NUMBER [, VALUE, LENGTH, STATUS])}
4936 @item @emph{Arguments}:
4937 @multitable @columnfractions .15 .70
4938 @item @var{NUMBER} @tab Shall be a scalar of type @code{INTEGER} and of
4939 default kind, @math{@var{NUMBER} \geq 0}
4940 @item @var{VALUE} @tab Shall be a scalar of type @code{CHARACTER}
4941 and of default kind.
4942 @item @var{LENGTH} @tab (Option) Shall be a scalar of type @code{INTEGER}
4943 and of default kind.
4944 @item @var{STATUS} @tab (Option) Shall be a scalar of type @code{INTEGER}
4945 and of default kind.
4948 @item @emph{Return value}:
4949 After @code{GET_COMMAND_ARGUMENT} returns, the @var{VALUE} argument holds the
4950 @var{NUMBER}-th command line argument. If @var{VALUE} can not hold the argument, it is
4951 truncated to fit the length of @var{VALUE}. If there are less than @var{NUMBER}
4952 arguments specified at the command line, @var{VALUE} will be filled with blanks.
4953 If @math{@var{NUMBER} = 0}, @var{VALUE} is set to the name of the program (on
4954 systems that support this feature). The @var{LENGTH} argument contains the
4955 length of the @var{NUMBER}-th command line argument. If the argument retrieval
4956 fails, @var{STATUS} is a positive number; if @var{VALUE} contains a truncated
4957 command line argument, @var{STATUS} is -1; and otherwise the @var{STATUS} is
4960 @item @emph{Example}:
4962 PROGRAM test_get_command_argument
4964 CHARACTER(len=32) :: arg
4968 CALL get_command_argument(i, arg)
4969 IF (LEN_TRIM(arg) == 0) EXIT
4971 WRITE (*,*) TRIM(arg)
4977 @item @emph{See also}:
4978 @ref{GET_COMMAND}, @ref{COMMAND_ARGUMENT_COUNT}
4984 @section @code{GETCWD} --- Get current working directory
4986 @cindex system, working directory
4989 @item @emph{Description}:
4990 Get current working directory.
4992 This intrinsic is provided in both subroutine and function forms; however,
4993 only one form can be used in any given program unit.
4995 @item @emph{Standard}:
4999 Subroutine, function
5001 @item @emph{Syntax}:
5002 @code{CALL GETCWD(C [, STATUS])}
5004 @item @emph{Arguments}:
5005 @multitable @columnfractions .15 .70
5006 @item @var{C} @tab The type shall be @code{CHARACTER} and of default kind.
5007 @item @var{STATUS} @tab (Optional) status flag. Returns 0 on success,
5008 a system specific and nonzero error code otherwise.
5011 @item @emph{Example}:
5014 CHARACTER(len=255) :: cwd
5016 WRITE(*,*) TRIM(cwd)
5020 @item @emph{See also}:
5027 @section @code{GETENV} --- Get an environmental variable
5029 @cindex environment variable
5032 @item @emph{Description}:
5033 Get the @var{VALUE} of the environmental variable @var{NAME}.
5035 This intrinsic routine is provided for backwards compatibility with
5036 GNU Fortran 77. In new code, programmers should consider the use of
5037 the @ref{GET_ENVIRONMENT_VARIABLE} intrinsic defined by the Fortran
5040 @item @emph{Standard}:
5046 @item @emph{Syntax}:
5047 @code{CALL GETENV(NAME, VALUE)}
5049 @item @emph{Arguments}:
5050 @multitable @columnfractions .15 .70
5051 @item @var{NAME} @tab Shall be of type @code{CHARACTER} and of default kind.
5052 @item @var{VALUE} @tab Shall be of type @code{CHARACTER} and of default kind.
5055 @item @emph{Return value}:
5056 Stores the value of @var{NAME} in @var{VALUE}. If @var{VALUE} is
5057 not large enough to hold the data, it is truncated. If @var{NAME}
5058 is not set, @var{VALUE} will be filled with blanks.
5060 @item @emph{Example}:
5063 CHARACTER(len=255) :: homedir
5064 CALL getenv("HOME", homedir)
5065 WRITE (*,*) TRIM(homedir)
5069 @item @emph{See also}:
5070 @ref{GET_ENVIRONMENT_VARIABLE}
5075 @node GET_ENVIRONMENT_VARIABLE
5076 @section @code{GET_ENVIRONMENT_VARIABLE} --- Get an environmental variable
5077 @fnindex GET_ENVIRONMENT_VARIABLE
5078 @cindex environment variable
5081 @item @emph{Description}:
5082 Get the @var{VALUE} of the environmental variable @var{NAME}.
5084 @item @emph{Standard}:
5085 Fortran 2003 and later
5090 @item @emph{Syntax}:
5091 @code{CALL GET_ENVIRONMENT_VARIABLE(NAME[, VALUE, LENGTH, STATUS, TRIM_NAME)}
5093 @item @emph{Arguments}:
5094 @multitable @columnfractions .15 .70
5095 @item @var{NAME} @tab Shall be a scalar of type @code{CHARACTER}
5096 and of default kind.
5097 @item @var{VALUE} @tab Shall be a scalar of type @code{CHARACTER}
5098 and of default kind.
5099 @item @var{LENGTH} @tab Shall be a scalar of type @code{INTEGER}
5100 and of default kind.
5101 @item @var{STATUS} @tab Shall be a scalar of type @code{INTEGER}
5102 and of default kind.
5103 @item @var{TRIM_NAME} @tab Shall be a scalar of type @code{LOGICAL}
5104 and of default kind.
5107 @item @emph{Return value}:
5108 Stores the value of @var{NAME} in @var{VALUE}. If @var{VALUE} is
5109 not large enough to hold the data, it is truncated. If @var{NAME}
5110 is not set, @var{VALUE} will be filled with blanks. Argument @var{LENGTH}
5111 contains the length needed for storing the environment variable @var{NAME}
5112 or zero if it is not present. @var{STATUS} is -1 if @var{VALUE} is present
5113 but too short for the environment variable; it is 1 if the environment
5114 variable does not exist and 2 if the processor does not support environment
5115 variables; in all other cases @var{STATUS} is zero. If @var{TRIM_NAME} is
5116 present with the value @code{.FALSE.}, the trailing blanks in @var{NAME}
5117 are significant; otherwise they are not part of the environment variable
5120 @item @emph{Example}:
5123 CHARACTER(len=255) :: homedir
5124 CALL get_environment_variable("HOME", homedir)
5125 WRITE (*,*) TRIM(homedir)
5133 @section @code{GETGID} --- Group ID function
5135 @cindex system, group id
5138 @item @emph{Description}:
5139 Returns the numerical group ID of the current process.
5141 @item @emph{Standard}:
5147 @item @emph{Syntax}:
5148 @code{RESULT = GETGID()}
5150 @item @emph{Return value}:
5151 The return value of @code{GETGID} is an @code{INTEGER} of the default
5155 @item @emph{Example}:
5156 See @code{GETPID} for an example.
5158 @item @emph{See also}:
5159 @ref{GETPID}, @ref{GETUID}
5165 @section @code{GETLOG} --- Get login name
5167 @cindex system, login name
5171 @item @emph{Description}:
5172 Gets the username under which the program is running.
5174 @item @emph{Standard}:
5180 @item @emph{Syntax}:
5181 @code{CALL GETLOG(C)}
5183 @item @emph{Arguments}:
5184 @multitable @columnfractions .15 .70
5185 @item @var{C} @tab Shall be of type @code{CHARACTER} and of default kind.
5188 @item @emph{Return value}:
5189 Stores the current user name in @var{LOGIN}. (On systems where POSIX
5190 functions @code{geteuid} and @code{getpwuid} are not available, and
5191 the @code{getlogin} function is not implemented either, this will
5192 return a blank string.)
5194 @item @emph{Example}:
5197 CHARACTER(32) :: login
5203 @item @emph{See also}:
5210 @section @code{GETPID} --- Process ID function
5212 @cindex system, process id
5216 @item @emph{Description}:
5217 Returns the numerical process identifier of the current process.
5219 @item @emph{Standard}:
5225 @item @emph{Syntax}:
5226 @code{RESULT = GETPID()}
5228 @item @emph{Return value}:
5229 The return value of @code{GETPID} is an @code{INTEGER} of the default
5233 @item @emph{Example}:
5236 print *, "The current process ID is ", getpid()
5237 print *, "Your numerical user ID is ", getuid()
5238 print *, "Your numerical group ID is ", getgid()
5242 @item @emph{See also}:
5243 @ref{GETGID}, @ref{GETUID}
5249 @section @code{GETUID} --- User ID function
5251 @cindex system, user id
5255 @item @emph{Description}:
5256 Returns the numerical user ID of the current process.
5258 @item @emph{Standard}:
5264 @item @emph{Syntax}:
5265 @code{RESULT = GETUID()}
5267 @item @emph{Return value}:
5268 The return value of @code{GETUID} is an @code{INTEGER} of the default
5272 @item @emph{Example}:
5273 See @code{GETPID} for an example.
5275 @item @emph{See also}:
5276 @ref{GETPID}, @ref{GETLOG}
5282 @section @code{GMTIME} --- Convert time to GMT info
5284 @cindex time, conversion to GMT info
5287 @item @emph{Description}:
5288 Given a system time value @var{TIME} (as provided by the @code{TIME8()}
5289 intrinsic), fills @var{VALUES} with values extracted from it appropriate
5290 to the UTC time zone (Universal Coordinated Time, also known in some
5291 countries as GMT, Greenwich Mean Time), using @code{gmtime(3)}.
5293 @item @emph{Standard}:
5299 @item @emph{Syntax}:
5300 @code{CALL GMTIME(TIME, VALUES)}
5302 @item @emph{Arguments}:
5303 @multitable @columnfractions .15 .70
5304 @item @var{TIME} @tab An @code{INTEGER} scalar expression
5305 corresponding to a system time, with @code{INTENT(IN)}.
5306 @item @var{VALUES} @tab A default @code{INTEGER} array with 9 elements,
5307 with @code{INTENT(OUT)}.
5310 @item @emph{Return value}:
5311 The elements of @var{VALUES} are assigned as follows:
5313 @item Seconds after the minute, range 0--59 or 0--61 to allow for leap
5315 @item Minutes after the hour, range 0--59
5316 @item Hours past midnight, range 0--23
5317 @item Day of month, range 0--31
5318 @item Number of months since January, range 0--12
5319 @item Years since 1900
5320 @item Number of days since Sunday, range 0--6
5321 @item Days since January 1
5322 @item Daylight savings indicator: positive if daylight savings is in
5323 effect, zero if not, and negative if the information is not available.
5326 @item @emph{See also}:
5327 @ref{CTIME}, @ref{LTIME}, @ref{TIME}, @ref{TIME8}
5334 @section @code{HOSTNM} --- Get system host name
5336 @cindex system, host name
5339 @item @emph{Description}:
5340 Retrieves the host name of the system on which the program is running.
5342 This intrinsic is provided in both subroutine and function forms; however,
5343 only one form can be used in any given program unit.
5345 @item @emph{Standard}:
5349 Subroutine, function
5351 @item @emph{Syntax}:
5352 @multitable @columnfractions .80
5353 @item @code{CALL HOSTNM(C [, STATUS])}
5354 @item @code{STATUS = HOSTNM(NAME)}
5357 @item @emph{Arguments}:
5358 @multitable @columnfractions .15 .70
5359 @item @var{C} @tab Shall of type @code{CHARACTER} and of default kind.
5360 @item @var{STATUS} @tab (Optional) status flag of type @code{INTEGER}.
5361 Returns 0 on success, or a system specific error code otherwise.
5364 @item @emph{Return value}:
5365 In either syntax, @var{NAME} is set to the current hostname if it can
5366 be obtained, or to a blank string otherwise.
5373 @section @code{HUGE} --- Largest number of a kind
5375 @cindex limits, largest number
5376 @cindex model representation, largest number
5379 @item @emph{Description}:
5380 @code{HUGE(X)} returns the largest number that is not an infinity in
5381 the model of the type of @code{X}.
5383 @item @emph{Standard}:
5384 Fortran 95 and later
5389 @item @emph{Syntax}:
5390 @code{RESULT = HUGE(X)}
5392 @item @emph{Arguments}:
5393 @multitable @columnfractions .15 .70
5394 @item @var{X} @tab Shall be of type @code{REAL} or @code{INTEGER}.
5397 @item @emph{Return value}:
5398 The return value is of the same type and kind as @var{X}
5400 @item @emph{Example}:
5402 program test_huge_tiny
5403 print *, huge(0), huge(0.0), huge(0.0d0)
5404 print *, tiny(0.0), tiny(0.0d0)
5405 end program test_huge_tiny
5412 @section @code{HYPOT} --- Euclidean distance function
5414 @cindex Euclidean distance
5417 @item @emph{Description}:
5418 @code{HYPOT(X,Y)} is the Euclidean distance function. It is equal to
5419 @math{\sqrt{X^2 + Y^2}}, without undue underflow or overflow.
5421 @item @emph{Standard}:
5422 Fortran 2008 and later
5427 @item @emph{Syntax}:
5428 @code{RESULT = HYPOT(X, Y)}
5430 @item @emph{Arguments}:
5431 @multitable @columnfractions .15 .70
5432 @item @var{X} @tab The type shall be @code{REAL}.
5433 @item @var{Y} @tab The type and kind type parameter shall be the same as
5437 @item @emph{Return value}:
5438 The return value has the same type and kind type parameter as @var{X}.
5440 @item @emph{Example}:
5443 real(4) :: x = 1.e0_4, y = 0.5e0_4
5445 end program test_hypot
5452 @section @code{IACHAR} --- Code in @acronym{ASCII} collating sequence
5454 @cindex @acronym{ASCII} collating sequence
5455 @cindex collating sequence, @acronym{ASCII}
5456 @cindex conversion, to integer
5459 @item @emph{Description}:
5460 @code{IACHAR(C)} returns the code for the @acronym{ASCII} character
5461 in the first character position of @code{C}.
5463 @item @emph{Standard}:
5464 Fortran 95 and later, with @var{KIND} argument Fortran 2003 and later
5469 @item @emph{Syntax}:
5470 @code{RESULT = IACHAR(C [, KIND])}
5472 @item @emph{Arguments}:
5473 @multitable @columnfractions .15 .70
5474 @item @var{C} @tab Shall be a scalar @code{CHARACTER}, with @code{INTENT(IN)}
5475 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
5476 expression indicating the kind parameter of the result.
5479 @item @emph{Return value}:
5480 The return value is of type @code{INTEGER} and of kind @var{KIND}. If
5481 @var{KIND} is absent, the return value is of default integer kind.
5483 @item @emph{Example}:
5488 end program test_iachar
5492 See @ref{ICHAR} for a discussion of converting between numerical values
5493 and formatted string representations.
5495 @item @emph{See also}:
5496 @ref{ACHAR}, @ref{CHAR}, @ref{ICHAR}
5503 @section @code{IAND} --- Bitwise logical and
5505 @cindex bitwise logical and
5506 @cindex logical and, bitwise
5509 @item @emph{Description}:
5510 Bitwise logical @code{AND}.
5512 @item @emph{Standard}:
5513 Fortran 95 and later
5518 @item @emph{Syntax}:
5519 @code{RESULT = IAND(I, J)}
5521 @item @emph{Arguments}:
5522 @multitable @columnfractions .15 .70
5523 @item @var{I} @tab The type shall be @code{INTEGER}.
5524 @item @var{J} @tab The type shall be @code{INTEGER}, of the same
5525 kind as @var{I}. (As a GNU extension, different kinds are also
5529 @item @emph{Return value}:
5530 The return type is @code{INTEGER}, of the same kind as the
5531 arguments. (If the argument kinds differ, it is of the same kind as
5532 the larger argument.)
5534 @item @emph{Example}:
5538 DATA a / Z'F' /, b / Z'3' /
5539 WRITE (*,*) IAND(a, b)
5543 @item @emph{See also}:
5544 @ref{IOR}, @ref{IEOR}, @ref{IBITS}, @ref{IBSET}, @ref{IBCLR}, @ref{NOT}
5551 @section @code{IARGC} --- Get the number of command line arguments
5553 @cindex command-line arguments
5554 @cindex command-line arguments, number of
5555 @cindex arguments, to program
5558 @item @emph{Description}:
5559 @code{IARGC()} returns the number of arguments passed on the
5560 command line when the containing program was invoked.
5562 This intrinsic routine is provided for backwards compatibility with
5563 GNU Fortran 77. In new code, programmers should consider the use of
5564 the @ref{COMMAND_ARGUMENT_COUNT} intrinsic defined by the Fortran 2003
5567 @item @emph{Standard}:
5573 @item @emph{Syntax}:
5574 @code{RESULT = IARGC()}
5576 @item @emph{Arguments}:
5579 @item @emph{Return value}:
5580 The number of command line arguments, type @code{INTEGER(4)}.
5582 @item @emph{Example}:
5585 @item @emph{See also}:
5586 GNU Fortran 77 compatibility subroutine: @ref{GETARG}
5588 Fortran 2003 functions and subroutines: @ref{GET_COMMAND},
5589 @ref{GET_COMMAND_ARGUMENT}, @ref{COMMAND_ARGUMENT_COUNT}
5595 @section @code{IBCLR} --- Clear bit
5601 @item @emph{Description}:
5602 @code{IBCLR} returns the value of @var{I} with the bit at position
5603 @var{POS} set to zero.
5605 @item @emph{Standard}:
5606 Fortran 95 and later
5611 @item @emph{Syntax}:
5612 @code{RESULT = IBCLR(I, POS)}
5614 @item @emph{Arguments}:
5615 @multitable @columnfractions .15 .70
5616 @item @var{I} @tab The type shall be @code{INTEGER}.
5617 @item @var{POS} @tab The type shall be @code{INTEGER}.
5620 @item @emph{Return value}:
5621 The return value is of type @code{INTEGER} and of the same kind as
5624 @item @emph{See also}:
5625 @ref{IBITS}, @ref{IBSET}, @ref{IAND}, @ref{IOR}, @ref{IEOR}, @ref{MVBITS}
5632 @section @code{IBITS} --- Bit extraction
5635 @cindex bits, extract
5638 @item @emph{Description}:
5639 @code{IBITS} extracts a field of length @var{LEN} from @var{I},
5640 starting from bit position @var{POS} and extending left for @var{LEN}
5641 bits. The result is right-justified and the remaining bits are
5642 zeroed. The value of @code{POS+LEN} must be less than or equal to the
5643 value @code{BIT_SIZE(I)}.
5645 @item @emph{Standard}:
5646 Fortran 95 and later
5651 @item @emph{Syntax}:
5652 @code{RESULT = IBITS(I, POS, LEN)}
5654 @item @emph{Arguments}:
5655 @multitable @columnfractions .15 .70
5656 @item @var{I} @tab The type shall be @code{INTEGER}.
5657 @item @var{POS} @tab The type shall be @code{INTEGER}.
5658 @item @var{LEN} @tab The type shall be @code{INTEGER}.
5661 @item @emph{Return value}:
5662 The return value is of type @code{INTEGER} and of the same kind as
5665 @item @emph{See also}:
5666 @ref{BIT_SIZE}, @ref{IBCLR}, @ref{IBSET}, @ref{IAND}, @ref{IOR}, @ref{IEOR}
5672 @section @code{IBSET} --- Set bit
5677 @item @emph{Description}:
5678 @code{IBSET} returns the value of @var{I} with the bit at position
5679 @var{POS} set to one.
5681 @item @emph{Standard}:
5682 Fortran 95 and later
5687 @item @emph{Syntax}:
5688 @code{RESULT = IBSET(I, POS)}
5690 @item @emph{Arguments}:
5691 @multitable @columnfractions .15 .70
5692 @item @var{I} @tab The type shall be @code{INTEGER}.
5693 @item @var{POS} @tab The type shall be @code{INTEGER}.
5696 @item @emph{Return value}:
5697 The return value is of type @code{INTEGER} and of the same kind as
5700 @item @emph{See also}:
5701 @ref{IBCLR}, @ref{IBITS}, @ref{IAND}, @ref{IOR}, @ref{IEOR}, @ref{MVBITS}
5708 @section @code{ICHAR} --- Character-to-integer conversion function
5710 @cindex conversion, to integer
5713 @item @emph{Description}:
5714 @code{ICHAR(C)} returns the code for the character in the first character
5715 position of @code{C} in the system's native character set.
5716 The correspondence between characters and their codes is not necessarily
5717 the same across different GNU Fortran implementations.
5719 @item @emph{Standard}:
5720 Fortan 95 and later, with @var{KIND} argument Fortran 2003 and later
5725 @item @emph{Syntax}:
5726 @code{RESULT = ICHAR(C [, KIND])}
5728 @item @emph{Arguments}:
5729 @multitable @columnfractions .15 .70
5730 @item @var{C} @tab Shall be a scalar @code{CHARACTER}, with @code{INTENT(IN)}
5731 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
5732 expression indicating the kind parameter of the result.
5735 @item @emph{Return value}:
5736 The return value is of type @code{INTEGER} and of kind @var{KIND}. If
5737 @var{KIND} is absent, the return value is of default integer kind.
5739 @item @emph{Example}:
5744 end program test_ichar
5747 @item @emph{Specific names}:
5748 @multitable @columnfractions .20 .20 .20 .25
5749 @item Name @tab Argument @tab Return type @tab Standard
5750 @item @code{ICHAR(C)} @tab @code{CHARACTER C} @tab @code{INTEGER(4)} @tab Fortran 77 and later
5754 No intrinsic exists to convert between a numeric value and a formatted
5755 character string representation -- for instance, given the
5756 @code{CHARACTER} value @code{'154'}, obtaining an @code{INTEGER} or
5757 @code{REAL} value with the value 154, or vice versa. Instead, this
5758 functionality is provided by internal-file I/O, as in the following
5763 character(len=10) string, string2
5766 ! Convert a string to a numeric value
5767 read (string,'(I10)') value
5770 ! Convert a value to a formatted string
5771 write (string2,'(I10)') value
5773 end program read_val
5776 @item @emph{See also}:
5777 @ref{ACHAR}, @ref{CHAR}, @ref{IACHAR}
5784 @section @code{IDATE} --- Get current local time subroutine (day/month/year)
5786 @cindex date, current
5787 @cindex current date
5790 @item @emph{Description}:
5791 @code{IDATE(VALUES)} Fills @var{VALUES} with the numerical values at the
5792 current local time. The day (in the range 1-31), month (in the range 1-12),
5793 and year appear in elements 1, 2, and 3 of @var{VALUES}, respectively.
5794 The year has four significant digits.
5796 @item @emph{Standard}:
5802 @item @emph{Syntax}:
5803 @code{CALL IDATE(VALUES)}
5805 @item @emph{Arguments}:
5806 @multitable @columnfractions .15 .70
5807 @item @var{VALUES} @tab The type shall be @code{INTEGER, DIMENSION(3)} and
5808 the kind shall be the default integer kind.
5811 @item @emph{Return value}:
5812 Does not return anything.
5814 @item @emph{Example}:
5817 integer, dimension(3) :: tarray
5822 end program test_idate
5829 @section @code{IEOR} --- Bitwise logical exclusive or
5831 @cindex bitwise logical exclusive or
5832 @cindex logical exclusive or, bitwise
5835 @item @emph{Description}:
5836 @code{IEOR} returns the bitwise boolean exclusive-OR of @var{I} and
5839 @item @emph{Standard}:
5840 Fortran 95 and later
5845 @item @emph{Syntax}:
5846 @code{RESULT = IEOR(I, J)}
5848 @item @emph{Arguments}:
5849 @multitable @columnfractions .15 .70
5850 @item @var{I} @tab The type shall be @code{INTEGER}.
5851 @item @var{J} @tab The type shall be @code{INTEGER}, of the same
5852 kind as @var{I}. (As a GNU extension, different kinds are also
5856 @item @emph{Return value}:
5857 The return type is @code{INTEGER}, of the same kind as the
5858 arguments. (If the argument kinds differ, it is of the same kind as
5859 the larger argument.)
5861 @item @emph{See also}:
5862 @ref{IOR}, @ref{IAND}, @ref{IBITS}, @ref{IBSET}, @ref{IBCLR}, @ref{NOT}
5868 @section @code{IERRNO} --- Get the last system error number
5870 @cindex system, error handling
5873 @item @emph{Description}:
5874 Returns the last system error number, as given by the C @code{errno()}
5877 @item @emph{Standard}:
5883 @item @emph{Syntax}:
5884 @code{RESULT = IERRNO()}
5886 @item @emph{Arguments}:
5889 @item @emph{Return value}:
5890 The return value is of type @code{INTEGER} and of the default integer
5893 @item @emph{See also}:
5899 @node INDEX intrinsic
5900 @section @code{INDEX} --- Position of a substring within a string
5902 @cindex substring position
5903 @cindex string, find substring
5906 @item @emph{Description}:
5907 Returns the position of the start of the first occurrence of string
5908 @var{SUBSTRING} as a substring in @var{STRING}, counting from one. If
5909 @var{SUBSTRING} is not present in @var{STRING}, zero is returned. If
5910 the @var{BACK} argument is present and true, the return value is the
5911 start of the last occurrence rather than the first.
5913 @item @emph{Standard}:
5914 Fortran 77 and later, with @var{KIND} argument Fortran 2003 and later
5919 @item @emph{Syntax}:
5920 @code{RESULT = INDEX(STRING, SUBSTRING [, BACK [, KIND]])}
5922 @item @emph{Arguments}:
5923 @multitable @columnfractions .15 .70
5924 @item @var{STRING} @tab Shall be a scalar @code{CHARACTER}, with
5926 @item @var{SUBSTRING} @tab Shall be a scalar @code{CHARACTER}, with
5928 @item @var{BACK} @tab (Optional) Shall be a scalar @code{LOGICAL}, with
5930 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
5931 expression indicating the kind parameter of the result.
5934 @item @emph{Return value}:
5935 The return value is of type @code{INTEGER} and of kind @var{KIND}. If
5936 @var{KIND} is absent, the return value is of default integer kind.
5938 @item @emph{Specific names}:
5939 @multitable @columnfractions .20 .20 .20 .25
5940 @item Name @tab Argument @tab Return type @tab Standard
5941 @item @code{INDEX(STRING, SUBSTRING)} @tab @code{CHARACTER} @tab @code{INTEGER(4)} @tab Fortran 77 and later
5944 @item @emph{See also}:
5945 @ref{SCAN}, @ref{VERIFY}
5951 @section @code{INT} --- Convert to integer type
5955 @cindex conversion, to integer
5958 @item @emph{Description}:
5959 Convert to integer type
5961 @item @emph{Standard}:
5962 Fortran 77 and later
5967 @item @emph{Syntax}:
5968 @code{RESULT = INT(A [, KIND))}
5970 @item @emph{Arguments}:
5971 @multitable @columnfractions .15 .70
5972 @item @var{A} @tab Shall be of type @code{INTEGER},
5973 @code{REAL}, or @code{COMPLEX}.
5974 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
5975 expression indicating the kind parameter of the result.
5978 @item @emph{Return value}:
5979 These functions return a @code{INTEGER} variable or array under
5980 the following rules:
5984 If @var{A} is of type @code{INTEGER}, @code{INT(A) = A}
5986 If @var{A} is of type @code{REAL} and @math{|A| < 1}, @code{INT(A)} equals @code{0}.
5987 If @math{|A| \geq 1}, then @code{INT(A)} equals the largest integer that does not exceed
5988 the range of @var{A} and whose sign is the same as the sign of @var{A}.
5990 If @var{A} is of type @code{COMPLEX}, rule B is applied to the real part of @var{A}.
5993 @item @emph{Example}:
5997 complex :: z = (-3.7, 1.0)
5999 print *, int(z), int(z,8)
6003 @item @emph{Specific names}:
6004 @multitable @columnfractions .20 .20 .20 .25
6005 @item Name @tab Argument @tab Return type @tab Standard
6006 @item @code{INT(A)} @tab @code{REAL(4) A} @tab @code{INTEGER} @tab Fortran 77 and later
6007 @item @code{IFIX(A)} @tab @code{REAL(4) A} @tab @code{INTEGER} @tab Fortran 77 and later
6008 @item @code{IDINT(A)} @tab @code{REAL(8) A} @tab @code{INTEGER} @tab Fortran 77 and later
6015 @section @code{INT2} --- Convert to 16-bit integer type
6018 @cindex conversion, to integer
6021 @item @emph{Description}:
6022 Convert to a @code{KIND=2} integer type. This is equivalent to the
6023 standard @code{INT} intrinsic with an optional argument of
6024 @code{KIND=2}, and is only included for backwards compatibility.
6026 The @code{SHORT} intrinsic is equivalent to @code{INT2}.
6028 @item @emph{Standard}:
6034 @item @emph{Syntax}:
6035 @code{RESULT = INT2(A)}
6037 @item @emph{Arguments}:
6038 @multitable @columnfractions .15 .70
6039 @item @var{A} @tab Shall be of type @code{INTEGER},
6040 @code{REAL}, or @code{COMPLEX}.
6043 @item @emph{Return value}:
6044 The return value is a @code{INTEGER(2)} variable.
6046 @item @emph{See also}:
6047 @ref{INT}, @ref{INT8}, @ref{LONG}
6053 @section @code{INT8} --- Convert to 64-bit integer type
6055 @cindex conversion, to integer
6058 @item @emph{Description}:
6059 Convert to a @code{KIND=8} integer type. This is equivalent to the
6060 standard @code{INT} intrinsic with an optional argument of
6061 @code{KIND=8}, and is only included for backwards compatibility.
6063 @item @emph{Standard}:
6069 @item @emph{Syntax}:
6070 @code{RESULT = INT8(A)}
6072 @item @emph{Arguments}:
6073 @multitable @columnfractions .15 .70
6074 @item @var{A} @tab Shall be of type @code{INTEGER},
6075 @code{REAL}, or @code{COMPLEX}.
6078 @item @emph{Return value}:
6079 The return value is a @code{INTEGER(8)} variable.
6081 @item @emph{See also}:
6082 @ref{INT}, @ref{INT2}, @ref{LONG}
6088 @section @code{IOR} --- Bitwise logical or
6090 @cindex bitwise logical or
6091 @cindex logical or, bitwise
6094 @item @emph{Description}:
6095 @code{IOR} returns the bitwise boolean inclusive-OR of @var{I} and
6098 @item @emph{Standard}:
6099 Fortran 95 and later
6104 @item @emph{Syntax}:
6105 @code{RESULT = IOR(I, J)}
6107 @item @emph{Arguments}:
6108 @multitable @columnfractions .15 .70
6109 @item @var{I} @tab The type shall be @code{INTEGER}.
6110 @item @var{J} @tab The type shall be @code{INTEGER}, of the same
6111 kind as @var{I}. (As a GNU extension, different kinds are also
6115 @item @emph{Return value}:
6116 The return type is @code{INTEGER}, of the same kind as the
6117 arguments. (If the argument kinds differ, it is of the same kind as
6118 the larger argument.)
6120 @item @emph{See also}:
6121 @ref{IEOR}, @ref{IAND}, @ref{IBITS}, @ref{IBSET}, @ref{IBCLR}, @ref{NOT}
6127 @section @code{IRAND} --- Integer pseudo-random number
6129 @cindex random number generation
6132 @item @emph{Description}:
6133 @code{IRAND(FLAG)} returns a pseudo-random number from a uniform
6134 distribution between 0 and a system-dependent limit (which is in most
6135 cases 2147483647). If @var{FLAG} is 0, the next number
6136 in the current sequence is returned; if @var{FLAG} is 1, the generator
6137 is restarted by @code{CALL SRAND(0)}; if @var{FLAG} has any other value,
6138 it is used as a new seed with @code{SRAND}.
6140 This intrinsic routine is provided for backwards compatibility with
6141 GNU Fortran 77. It implements a simple modulo generator as provided
6142 by @command{g77}. For new code, one should consider the use of
6143 @ref{RANDOM_NUMBER} as it implements a superior algorithm.
6145 @item @emph{Standard}:
6151 @item @emph{Syntax}:
6152 @code{RESULT = IRAND(I)}
6154 @item @emph{Arguments}:
6155 @multitable @columnfractions .15 .70
6156 @item @var{I} @tab Shall be a scalar @code{INTEGER} of kind 4.
6159 @item @emph{Return value}:
6160 The return value is of @code{INTEGER(kind=4)} type.
6162 @item @emph{Example}:
6165 integer,parameter :: seed = 86456
6168 print *, irand(), irand(), irand(), irand()
6169 print *, irand(seed), irand(), irand(), irand()
6170 end program test_irand
6178 @section @code{IMAGE_INDEX} --- Function that converts a cosubscript to an image index
6179 @fnindex IMAGE_INDEX
6180 @cindex coarray, IMAGE_INDEX
6181 @cindex images, cosubscript to image index conversion
6184 @item @emph{Description}:
6185 Returns the image index belonging to a cosubscript.
6187 @item @emph{Standard}:
6188 Fortran 2008 and later
6193 @item @emph{Syntax}:
6194 @code{RESULT = IMAGE_INDEX(COARRAY, SUB)}
6196 @item @emph{Arguments}: None.
6197 @multitable @columnfractions .15 .70
6198 @item @var{COARRAY} @tab Coarray of any type.
6199 @item @var{SUB} @tab default integer rank-1 array of a size equal to
6200 the corank of @var{COARRAY}.
6204 @item @emph{Return value}:
6205 Scalar default integer with the value of the image index which corresponds
6206 to the cosubscripts. For invalid cosubscripts the result is zero.
6208 @item @emph{Example}:
6210 INTEGER :: array[2,-1:4,8,*]
6211 ! Writes 28 (or 0 if there are fewer than 28 images)
6212 WRITE (*,*) IMAGE_INDEX (array, [2,0,3,1])
6215 @item @emph{See also}:
6216 @ref{THIS_IMAGE}, @ref{NUM_IMAGES}
6222 @section @code{IS_IOSTAT_END} --- Test for end-of-file value
6223 @fnindex IS_IOSTAT_END
6224 @cindex IOSTAT, end of file
6227 @item @emph{Description}:
6228 @code{IS_IOSTAT_END} tests whether an variable has the value of the I/O
6229 status ``end of file''. The function is equivalent to comparing the variable
6230 with the @code{IOSTAT_END} parameter of the intrinsic module
6231 @code{ISO_FORTRAN_ENV}.
6233 @item @emph{Standard}:
6234 Fortran 2003 and later
6239 @item @emph{Syntax}:
6240 @code{RESULT = IS_IOSTAT_END(I)}
6242 @item @emph{Arguments}:
6243 @multitable @columnfractions .15 .70
6244 @item @var{I} @tab Shall be of the type @code{INTEGER}.
6247 @item @emph{Return value}:
6248 Returns a @code{LOGICAL} of the default kind, which @code{.TRUE.} if
6249 @var{I} has the value which indicates an end of file condition for
6250 IOSTAT= specifiers, and is @code{.FALSE.} otherwise.
6252 @item @emph{Example}:
6257 OPEN(88, FILE='test.dat')
6258 READ(88, *, IOSTAT=stat) i
6259 IF(IS_IOSTAT_END(stat)) STOP 'END OF FILE'
6267 @section @code{IS_IOSTAT_EOR} --- Test for end-of-record value
6268 @fnindex IS_IOSTAT_EOR
6269 @cindex IOSTAT, end of record
6272 @item @emph{Description}:
6273 @code{IS_IOSTAT_EOR} tests whether an variable has the value of the I/O
6274 status ``end of record''. The function is equivalent to comparing the
6275 variable with the @code{IOSTAT_EOR} parameter of the intrinsic module
6276 @code{ISO_FORTRAN_ENV}.
6278 @item @emph{Standard}:
6279 Fortran 2003 and later
6284 @item @emph{Syntax}:
6285 @code{RESULT = IS_IOSTAT_EOR(I)}
6287 @item @emph{Arguments}:
6288 @multitable @columnfractions .15 .70
6289 @item @var{I} @tab Shall be of the type @code{INTEGER}.
6292 @item @emph{Return value}:
6293 Returns a @code{LOGICAL} of the default kind, which @code{.TRUE.} if
6294 @var{I} has the value which indicates an end of file condition for
6295 IOSTAT= specifiers, and is @code{.FALSE.} otherwise.
6297 @item @emph{Example}:
6301 INTEGER :: stat, i(50)
6302 OPEN(88, FILE='test.dat', FORM='UNFORMATTED')
6303 READ(88, IOSTAT=stat) i
6304 IF(IS_IOSTAT_EOR(stat)) STOP 'END OF RECORD'
6312 @section @code{ISATTY} --- Whether a unit is a terminal device.
6314 @cindex system, terminal
6317 @item @emph{Description}:
6318 Determine whether a unit is connected to a terminal device.
6320 @item @emph{Standard}:
6326 @item @emph{Syntax}:
6327 @code{RESULT = ISATTY(UNIT)}
6329 @item @emph{Arguments}:
6330 @multitable @columnfractions .15 .70
6331 @item @var{UNIT} @tab Shall be a scalar @code{INTEGER}.
6334 @item @emph{Return value}:
6335 Returns @code{.TRUE.} if the @var{UNIT} is connected to a terminal
6336 device, @code{.FALSE.} otherwise.
6338 @item @emph{Example}:
6341 INTEGER(kind=1) :: unit
6343 write(*,*) isatty(unit=unit)
6347 @item @emph{See also}:
6354 @section @code{ISHFT} --- Shift bits
6359 @item @emph{Description}:
6360 @code{ISHFT} returns a value corresponding to @var{I} with all of the
6361 bits shifted @var{SHIFT} places. A value of @var{SHIFT} greater than
6362 zero corresponds to a left shift, a value of zero corresponds to no
6363 shift, and a value less than zero corresponds to a right shift. If the
6364 absolute value of @var{SHIFT} is greater than @code{BIT_SIZE(I)}, the
6365 value is undefined. Bits shifted out from the left end or right end are
6366 lost; zeros are shifted in from the opposite end.
6368 @item @emph{Standard}:
6369 Fortran 95 and later
6374 @item @emph{Syntax}:
6375 @code{RESULT = ISHFT(I, SHIFT)}
6377 @item @emph{Arguments}:
6378 @multitable @columnfractions .15 .70
6379 @item @var{I} @tab The type shall be @code{INTEGER}.
6380 @item @var{SHIFT} @tab The type shall be @code{INTEGER}.
6383 @item @emph{Return value}:
6384 The return value is of type @code{INTEGER} and of the same kind as
6387 @item @emph{See also}:
6394 @section @code{ISHFTC} --- Shift bits circularly
6396 @cindex bits, shift circular
6399 @item @emph{Description}:
6400 @code{ISHFTC} returns a value corresponding to @var{I} with the
6401 rightmost @var{SIZE} bits shifted circularly @var{SHIFT} places; that
6402 is, bits shifted out one end are shifted into the opposite end. A value
6403 of @var{SHIFT} greater than zero corresponds to a left shift, a value of
6404 zero corresponds to no shift, and a value less than zero corresponds to
6405 a right shift. The absolute value of @var{SHIFT} must be less than
6406 @var{SIZE}. If the @var{SIZE} argument is omitted, it is taken to be
6407 equivalent to @code{BIT_SIZE(I)}.
6409 @item @emph{Standard}:
6410 Fortran 95 and later
6415 @item @emph{Syntax}:
6416 @code{RESULT = ISHFTC(I, SHIFT [, SIZE])}
6418 @item @emph{Arguments}:
6419 @multitable @columnfractions .15 .70
6420 @item @var{I} @tab The type shall be @code{INTEGER}.
6421 @item @var{SHIFT} @tab The type shall be @code{INTEGER}.
6422 @item @var{SIZE} @tab (Optional) The type shall be @code{INTEGER};
6423 the value must be greater than zero and less than or equal to
6427 @item @emph{Return value}:
6428 The return value is of type @code{INTEGER} and of the same kind as
6431 @item @emph{See also}:
6438 @section @code{ISNAN} --- Test for a NaN
6443 @item @emph{Description}:
6444 @code{ISNAN} tests whether a floating-point value is an IEEE
6446 @item @emph{Standard}:
6452 @item @emph{Syntax}:
6455 @item @emph{Arguments}:
6456 @multitable @columnfractions .15 .70
6457 @item @var{X} @tab Variable of the type @code{REAL}.
6461 @item @emph{Return value}:
6462 Returns a default-kind @code{LOGICAL}. The returned value is @code{TRUE}
6463 if @var{X} is a NaN and @code{FALSE} otherwise.
6465 @item @emph{Example}:
6472 if (isnan(x)) stop '"x" is a NaN'
6473 end program test_nan
6480 @section @code{ITIME} --- Get current local time subroutine (hour/minutes/seconds)
6482 @cindex time, current
6483 @cindex current time
6486 @item @emph{Description}:
6487 @code{IDATE(VALUES)} Fills @var{VALUES} with the numerical values at the
6488 current local time. The hour (in the range 1-24), minute (in the range 1-60),
6489 and seconds (in the range 1-60) appear in elements 1, 2, and 3 of @var{VALUES},
6492 @item @emph{Standard}:
6498 @item @emph{Syntax}:
6499 @code{CALL ITIME(VALUES)}
6501 @item @emph{Arguments}:
6502 @multitable @columnfractions .15 .70
6503 @item @var{VALUES} @tab The type shall be @code{INTEGER, DIMENSION(3)}
6504 and the kind shall be the default integer kind.
6507 @item @emph{Return value}:
6508 Does not return anything.
6511 @item @emph{Example}:
6514 integer, dimension(3) :: tarray
6519 end program test_itime
6526 @section @code{KILL} --- Send a signal to a process
6530 @item @emph{Description}:
6531 @item @emph{Standard}:
6532 Sends the signal specified by @var{SIGNAL} to the process @var{PID}.
6535 This intrinsic is provided in both subroutine and function forms; however,
6536 only one form can be used in any given program unit.
6539 Subroutine, function
6541 @item @emph{Syntax}:
6542 @code{CALL KILL(C, VALUE [, STATUS])}
6544 @item @emph{Arguments}:
6545 @multitable @columnfractions .15 .70
6546 @item @var{C} @tab Shall be a scalar @code{INTEGER}, with
6548 @item @var{VALUE} @tab Shall be a scalar @code{INTEGER}, with
6550 @item @var{STATUS} @tab (Optional) status flag of type @code{INTEGER(4)} or
6551 @code{INTEGER(8)}. Returns 0 on success, or a system-specific error code
6555 @item @emph{See also}:
6556 @ref{ABORT}, @ref{EXIT}
6562 @section @code{KIND} --- Kind of an entity
6567 @item @emph{Description}:
6568 @code{KIND(X)} returns the kind value of the entity @var{X}.
6570 @item @emph{Standard}:
6571 Fortran 95 and later
6576 @item @emph{Syntax}:
6579 @item @emph{Arguments}:
6580 @multitable @columnfractions .15 .70
6581 @item @var{X} @tab Shall be of type @code{LOGICAL}, @code{INTEGER},
6582 @code{REAL}, @code{COMPLEX} or @code{CHARACTER}.
6585 @item @emph{Return value}:
6586 The return value is a scalar of type @code{INTEGER} and of the default
6589 @item @emph{Example}:
6592 integer,parameter :: kc = kind(' ')
6593 integer,parameter :: kl = kind(.true.)
6595 print *, "The default character kind is ", kc
6596 print *, "The default logical kind is ", kl
6597 end program test_kind
6605 @section @code{LBOUND} --- Lower dimension bounds of an array
6607 @cindex array, lower bound
6610 @item @emph{Description}:
6611 Returns the lower bounds of an array, or a single lower bound
6612 along the @var{DIM} dimension.
6613 @item @emph{Standard}:
6614 Fortran 95 and later, with @var{KIND} argument Fortran 2003 and later
6619 @item @emph{Syntax}:
6620 @code{RESULT = LBOUND(ARRAY [, DIM [, KIND]])}
6622 @item @emph{Arguments}:
6623 @multitable @columnfractions .15 .70
6624 @item @var{ARRAY} @tab Shall be an array, of any type.
6625 @item @var{DIM} @tab (Optional) Shall be a scalar @code{INTEGER}.
6626 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
6627 expression indicating the kind parameter of the result.
6630 @item @emph{Return value}:
6631 The return value is of type @code{INTEGER} and of kind @var{KIND}. If
6632 @var{KIND} is absent, the return value is of default integer kind.
6633 If @var{DIM} is absent, the result is an array of the lower bounds of
6634 @var{ARRAY}. If @var{DIM} is present, the result is a scalar
6635 corresponding to the lower bound of the array along that dimension. If
6636 @var{ARRAY} is an expression rather than a whole array or array
6637 structure component, or if it has a zero extent along the relevant
6638 dimension, the lower bound is taken to be 1.
6640 @item @emph{See also}:
6641 @ref{UBOUND}, @ref{LCOBOUND}
6647 @section @code{LCOBOUND} --- Lower codimension bounds of an array
6649 @cindex coarray, lower bound
6652 @item @emph{Description}:
6653 Returns the lower bounds of a coarray, or a single lower cobound
6654 along the @var{DIM} codimension.
6655 @item @emph{Standard}:
6656 Fortran 2008 and later
6661 @item @emph{Syntax}:
6662 @code{RESULT = LCOBOUND(COARRAY [, DIM [, KIND]])}
6664 @item @emph{Arguments}:
6665 @multitable @columnfractions .15 .70
6666 @item @var{ARRAY} @tab Shall be an coarray, of any type.
6667 @item @var{DIM} @tab (Optional) Shall be a scalar @code{INTEGER}.
6668 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
6669 expression indicating the kind parameter of the result.
6672 @item @emph{Return value}:
6673 The return value is of type @code{INTEGER} and of kind @var{KIND}. If
6674 @var{KIND} is absent, the return value is of default integer kind.
6675 If @var{DIM} is absent, the result is an array of the lower cobounds of
6676 @var{COARRAY}. If @var{DIM} is present, the result is a scalar
6677 corresponding to the lower cobound of the array along that codimension.
6679 @item @emph{See also}:
6680 @ref{UCOBOUND}, @ref{LBOUND}
6686 @section @code{LEADZ} --- Number of leading zero bits of an integer
6691 @item @emph{Description}:
6692 @code{LEADZ} returns the number of leading zero bits of an integer.
6694 @item @emph{Standard}:
6695 Fortran 2008 and later
6700 @item @emph{Syntax}:
6701 @code{RESULT = LEADZ(I)}
6703 @item @emph{Arguments}:
6704 @multitable @columnfractions .15 .70
6705 @item @var{I} @tab Shall be of type @code{INTEGER}.
6708 @item @emph{Return value}:
6709 The type of the return value is the default @code{INTEGER}.
6710 If all the bits of @code{I} are zero, the result value is @code{BIT_SIZE(I)}.
6712 @item @emph{Example}:
6715 WRITE (*,*) LEADZ(1) ! prints 8 if BITSIZE(I) has the value 32
6719 @item @emph{See also}:
6720 @ref{BIT_SIZE}, @ref{TRAILZ}
6726 @section @code{LEN} --- Length of a character entity
6728 @cindex string, length
6731 @item @emph{Description}:
6732 Returns the length of a character string. If @var{STRING} is an array,
6733 the length of an element of @var{STRING} is returned. Note that
6734 @var{STRING} need not be defined when this intrinsic is invoked, since
6735 only the length, not the content, of @var{STRING} is needed.
6737 @item @emph{Standard}:
6738 Fortran 77 and later, with @var{KIND} argument Fortran 2003 and later
6743 @item @emph{Syntax}:
6744 @code{L = LEN(STRING [, KIND])}
6746 @item @emph{Arguments}:
6747 @multitable @columnfractions .15 .70
6748 @item @var{STRING} @tab Shall be a scalar or array of type
6749 @code{CHARACTER}, with @code{INTENT(IN)}
6750 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
6751 expression indicating the kind parameter of the result.
6754 @item @emph{Return value}:
6755 The return value is of type @code{INTEGER} and of kind @var{KIND}. If
6756 @var{KIND} is absent, the return value is of default integer kind.
6759 @item @emph{Specific names}:
6760 @multitable @columnfractions .20 .20 .20 .25
6761 @item Name @tab Argument @tab Return type @tab Standard
6762 @item @code{LEN(STRING)} @tab @code{CHARACTER} @tab @code{INTEGER} @tab Fortran 77 and later
6766 @item @emph{See also}:
6767 @ref{LEN_TRIM}, @ref{ADJUSTL}, @ref{ADJUSTR}
6773 @section @code{LEN_TRIM} --- Length of a character entity without trailing blank characters
6775 @cindex string, length, without trailing whitespace
6778 @item @emph{Description}:
6779 Returns the length of a character string, ignoring any trailing blanks.
6781 @item @emph{Standard}:
6782 Fortran 95 and later, with @var{KIND} argument Fortran 2003 and later
6787 @item @emph{Syntax}:
6788 @code{RESULT = LEN_TRIM(STRING [, KIND])}
6790 @item @emph{Arguments}:
6791 @multitable @columnfractions .15 .70
6792 @item @var{STRING} @tab Shall be a scalar of type @code{CHARACTER},
6793 with @code{INTENT(IN)}
6794 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
6795 expression indicating the kind parameter of the result.
6798 @item @emph{Return value}:
6799 The return value is of type @code{INTEGER} and of kind @var{KIND}. If
6800 @var{KIND} is absent, the return value is of default integer kind.
6802 @item @emph{See also}:
6803 @ref{LEN}, @ref{ADJUSTL}, @ref{ADJUSTR}
6809 @section @code{LGE} --- Lexical greater than or equal
6811 @cindex lexical comparison of strings
6812 @cindex string, comparison
6815 @item @emph{Description}:
6816 Determines whether one string is lexically greater than or equal to
6817 another string, where the two strings are interpreted as containing
6818 ASCII character codes. If the String A and String B are not the same
6819 length, the shorter is compared as if spaces were appended to it to form
6820 a value that has the same length as the longer.
6822 In general, the lexical comparison intrinsics @code{LGE}, @code{LGT},
6823 @code{LLE}, and @code{LLT} differ from the corresponding intrinsic
6824 operators @code{.GE.}, @code{.GT.}, @code{.LE.}, and @code{.LT.}, in
6825 that the latter use the processor's character ordering (which is not
6826 ASCII on some targets), whereas the former always use the ASCII
6829 @item @emph{Standard}:
6830 Fortran 77 and later
6835 @item @emph{Syntax}:
6836 @code{RESULT = LGE(STRING_A, STRING_B)}
6838 @item @emph{Arguments}:
6839 @multitable @columnfractions .15 .70
6840 @item @var{STRING_A} @tab Shall be of default @code{CHARACTER} type.
6841 @item @var{STRING_B} @tab Shall be of default @code{CHARACTER} type.
6844 @item @emph{Return value}:
6845 Returns @code{.TRUE.} if @code{STRING_A >= STRING_B}, and @code{.FALSE.}
6846 otherwise, based on the ASCII ordering.
6848 @item @emph{Specific names}:
6849 @multitable @columnfractions .20 .20 .20 .25
6850 @item Name @tab Argument @tab Return type @tab Standard
6851 @item @code{LGE(STRING_A, STRING_B)} @tab @code{CHARACTER} @tab @code{LOGICAL} @tab Fortran 77 and later
6854 @item @emph{See also}:
6855 @ref{LGT}, @ref{LLE}, @ref{LLT}
6861 @section @code{LGT} --- Lexical greater than
6863 @cindex lexical comparison of strings
6864 @cindex string, comparison
6867 @item @emph{Description}:
6868 Determines whether one string is lexically greater than another string,
6869 where the two strings are interpreted as containing ASCII character
6870 codes. If the String A and String B are not the same length, the
6871 shorter is compared as if spaces were appended to it to form a value
6872 that has the same length as the longer.
6874 In general, the lexical comparison intrinsics @code{LGE}, @code{LGT},
6875 @code{LLE}, and @code{LLT} differ from the corresponding intrinsic
6876 operators @code{.GE.}, @code{.GT.}, @code{.LE.}, and @code{.LT.}, in
6877 that the latter use the processor's character ordering (which is not
6878 ASCII on some targets), whereas the former always use the ASCII
6881 @item @emph{Standard}:
6882 Fortran 77 and later
6887 @item @emph{Syntax}:
6888 @code{RESULT = LGT(STRING_A, STRING_B)}
6890 @item @emph{Arguments}:
6891 @multitable @columnfractions .15 .70
6892 @item @var{STRING_A} @tab Shall be of default @code{CHARACTER} type.
6893 @item @var{STRING_B} @tab Shall be of default @code{CHARACTER} type.
6896 @item @emph{Return value}:
6897 Returns @code{.TRUE.} if @code{STRING_A > STRING_B}, and @code{.FALSE.}
6898 otherwise, based on the ASCII ordering.
6900 @item @emph{Specific names}:
6901 @multitable @columnfractions .20 .20 .20 .25
6902 @item Name @tab Argument @tab Return type @tab Standard
6903 @item @code{LGT(STRING_A, STRING_B)} @tab @code{CHARACTER} @tab @code{LOGICAL} @tab Fortran 77 and later
6906 @item @emph{See also}:
6907 @ref{LGE}, @ref{LLE}, @ref{LLT}
6913 @section @code{LINK} --- Create a hard link
6915 @cindex file system, create link
6916 @cindex file system, hard link
6919 @item @emph{Description}:
6920 Makes a (hard) link from file @var{PATH1} to @var{PATH2}. A null
6921 character (@code{CHAR(0)}) can be used to mark the end of the names in
6922 @var{PATH1} and @var{PATH2}; otherwise, trailing blanks in the file
6923 names are ignored. If the @var{STATUS} argument is supplied, it
6924 contains 0 on success or a nonzero error code upon return; see
6927 This intrinsic is provided in both subroutine and function forms;
6928 however, only one form can be used in any given program unit.
6930 @item @emph{Standard}:
6934 Subroutine, function
6936 @item @emph{Syntax}:
6937 @multitable @columnfractions .80
6938 @item @code{CALL LINK(PATH1, PATH2 [, STATUS])}
6939 @item @code{STATUS = LINK(PATH1, PATH2)}
6942 @item @emph{Arguments}:
6943 @multitable @columnfractions .15 .70
6944 @item @var{PATH1} @tab Shall be of default @code{CHARACTER} type.
6945 @item @var{PATH2} @tab Shall be of default @code{CHARACTER} type.
6946 @item @var{STATUS} @tab (Optional) Shall be of default @code{INTEGER} type.
6949 @item @emph{See also}:
6950 @ref{SYMLNK}, @ref{UNLINK}
6956 @section @code{LLE} --- Lexical less than or equal
6958 @cindex lexical comparison of strings
6959 @cindex string, comparison
6962 @item @emph{Description}:
6963 Determines whether one string is lexically less than or equal to another
6964 string, where the two strings are interpreted as containing ASCII
6965 character codes. If the String A and String B are not the same length,
6966 the shorter is compared as if spaces were appended to it to form a value
6967 that has the same length as the longer.
6969 In general, the lexical comparison intrinsics @code{LGE}, @code{LGT},
6970 @code{LLE}, and @code{LLT} differ from the corresponding intrinsic
6971 operators @code{.GE.}, @code{.GT.}, @code{.LE.}, and @code{.LT.}, in
6972 that the latter use the processor's character ordering (which is not
6973 ASCII on some targets), whereas the former always use the ASCII
6976 @item @emph{Standard}:
6977 Fortran 77 and later
6982 @item @emph{Syntax}:
6983 @code{RESULT = LLE(STRING_A, STRING_B)}
6985 @item @emph{Arguments}:
6986 @multitable @columnfractions .15 .70
6987 @item @var{STRING_A} @tab Shall be of default @code{CHARACTER} type.
6988 @item @var{STRING_B} @tab Shall be of default @code{CHARACTER} type.
6991 @item @emph{Return value}:
6992 Returns @code{.TRUE.} if @code{STRING_A <= STRING_B}, and @code{.FALSE.}
6993 otherwise, based on the ASCII ordering.
6995 @item @emph{Specific names}:
6996 @multitable @columnfractions .20 .20 .20 .25
6997 @item Name @tab Argument @tab Return type @tab Standard
6998 @item @code{LLE(STRING_A, STRING_B)} @tab @code{CHARACTER} @tab @code{LOGICAL} @tab Fortran 77 and later
7001 @item @emph{See also}:
7002 @ref{LGE}, @ref{LGT}, @ref{LLT}
7008 @section @code{LLT} --- Lexical less than
7010 @cindex lexical comparison of strings
7011 @cindex string, comparison
7014 @item @emph{Description}:
7015 Determines whether one string is lexically less than another string,
7016 where the two strings are interpreted as containing ASCII character
7017 codes. If the String A and String B are not the same length, the
7018 shorter is compared as if spaces were appended to it to form a value
7019 that has the same length as the longer.
7021 In general, the lexical comparison intrinsics @code{LGE}, @code{LGT},
7022 @code{LLE}, and @code{LLT} differ from the corresponding intrinsic
7023 operators @code{.GE.}, @code{.GT.}, @code{.LE.}, and @code{.LT.}, in
7024 that the latter use the processor's character ordering (which is not
7025 ASCII on some targets), whereas the former always use the ASCII
7028 @item @emph{Standard}:
7029 Fortran 77 and later
7034 @item @emph{Syntax}:
7035 @code{RESULT = LLT(STRING_A, STRING_B)}
7037 @item @emph{Arguments}:
7038 @multitable @columnfractions .15 .70
7039 @item @var{STRING_A} @tab Shall be of default @code{CHARACTER} type.
7040 @item @var{STRING_B} @tab Shall be of default @code{CHARACTER} type.
7043 @item @emph{Return value}:
7044 Returns @code{.TRUE.} if @code{STRING_A < STRING_B}, and @code{.FALSE.}
7045 otherwise, based on the ASCII ordering.
7047 @item @emph{Specific names}:
7048 @multitable @columnfractions .20 .20 .20 .25
7049 @item Name @tab Argument @tab Return type @tab Standard
7050 @item @code{LLT(STRING_A, STRING_B)} @tab @code{CHARACTER} @tab @code{LOGICAL} @tab Fortran 77 and later
7053 @item @emph{See also}:
7054 @ref{LGE}, @ref{LGT}, @ref{LLE}
7060 @section @code{LNBLNK} --- Index of the last non-blank character in a string
7062 @cindex string, find non-blank character
7065 @item @emph{Description}:
7066 Returns the length of a character string, ignoring any trailing blanks.
7067 This is identical to the standard @code{LEN_TRIM} intrinsic, and is only
7068 included for backwards compatibility.
7070 @item @emph{Standard}:
7076 @item @emph{Syntax}:
7077 @code{RESULT = LNBLNK(STRING)}
7079 @item @emph{Arguments}:
7080 @multitable @columnfractions .15 .70
7081 @item @var{STRING} @tab Shall be a scalar of type @code{CHARACTER},
7082 with @code{INTENT(IN)}
7085 @item @emph{Return value}:
7086 The return value is of @code{INTEGER(kind=4)} type.
7088 @item @emph{See also}:
7089 @ref{INDEX intrinsic}, @ref{LEN_TRIM}
7095 @section @code{LOC} --- Returns the address of a variable
7097 @cindex location of a variable in memory
7100 @item @emph{Description}:
7101 @code{LOC(X)} returns the address of @var{X} as an integer.
7103 @item @emph{Standard}:
7109 @item @emph{Syntax}:
7110 @code{RESULT = LOC(X)}
7112 @item @emph{Arguments}:
7113 @multitable @columnfractions .15 .70
7114 @item @var{X} @tab Variable of any type.
7117 @item @emph{Return value}:
7118 The return value is of type @code{INTEGER}, with a @code{KIND}
7119 corresponding to the size (in bytes) of a memory address on the target
7122 @item @emph{Example}:
7129 end program test_loc
7136 @section @code{LOG} --- Logarithm function
7143 @cindex exponential function, inverse
7144 @cindex logarithmic function
7147 @item @emph{Description}:
7148 @code{LOG(X)} computes the logarithm of @var{X}.
7150 @item @emph{Standard}:
7151 Fortran 77 and later
7156 @item @emph{Syntax}:
7157 @code{RESULT = LOG(X)}
7159 @item @emph{Arguments}:
7160 @multitable @columnfractions .15 .70
7161 @item @var{X} @tab The type shall be @code{REAL} or
7165 @item @emph{Return value}:
7166 The return value is of type @code{REAL} or @code{COMPLEX}.
7167 The kind type parameter is the same as @var{X}.
7168 If @var{X} is @code{COMPLEX}, the imaginary part @math{\omega} is in the range
7169 @math{-\pi \leq \omega \leq \pi}.
7171 @item @emph{Example}:
7174 real(8) :: x = 1.0_8
7175 complex :: z = (1.0, 2.0)
7178 end program test_log
7181 @item @emph{Specific names}:
7182 @multitable @columnfractions .20 .20 .20 .25
7183 @item Name @tab Argument @tab Return type @tab Standard
7184 @item @code{ALOG(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab f95, gnu
7185 @item @code{DLOG(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab f95, gnu
7186 @item @code{CLOG(X)} @tab @code{COMPLEX(4) X} @tab @code{COMPLEX(4)} @tab f95, gnu
7187 @item @code{ZLOG(X)} @tab @code{COMPLEX(8) X} @tab @code{COMPLEX(8)} @tab f95, gnu
7188 @item @code{CDLOG(X)} @tab @code{COMPLEX(8) X} @tab @code{COMPLEX(8)} @tab f95, gnu
7195 @section @code{LOG10} --- Base 10 logarithm function
7199 @cindex exponential function, inverse
7200 @cindex logarithmic function
7203 @item @emph{Description}:
7204 @code{LOG10(X)} computes the base 10 logarithm of @var{X}.
7206 @item @emph{Standard}:
7207 Fortran 77 and later
7212 @item @emph{Syntax}:
7213 @code{RESULT = LOG10(X)}
7215 @item @emph{Arguments}:
7216 @multitable @columnfractions .15 .70
7217 @item @var{X} @tab The type shall be @code{REAL}.
7220 @item @emph{Return value}:
7221 The return value is of type @code{REAL} or @code{COMPLEX}.
7222 The kind type parameter is the same as @var{X}.
7224 @item @emph{Example}:
7227 real(8) :: x = 10.0_8
7229 end program test_log10
7232 @item @emph{Specific names}:
7233 @multitable @columnfractions .20 .20 .20 .25
7234 @item Name @tab Argument @tab Return type @tab Standard
7235 @item @code{ALOG10(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab Fortran 95 and later
7236 @item @code{DLOG10(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab Fortran 95 and later
7243 @section @code{LOG_GAMMA} --- Logarithm of the Gamma function
7248 @cindex Gamma function, logarithm of
7251 @item @emph{Description}:
7252 @code{LOG_GAMMA(X)} computes the natural logarithm of the absolute value
7253 of the Gamma (@math{\Gamma}) function.
7255 @item @emph{Standard}:
7256 Fortran 2008 and later
7261 @item @emph{Syntax}:
7262 @code{X = LOG_GAMMA(X)}
7264 @item @emph{Arguments}:
7265 @multitable @columnfractions .15 .70
7266 @item @var{X} @tab Shall be of type @code{REAL} and neither zero
7267 nor a negative integer.
7270 @item @emph{Return value}:
7271 The return value is of type @code{REAL} of the same kind as @var{X}.
7273 @item @emph{Example}:
7275 program test_log_gamma
7277 x = lgamma(x) ! returns 0.0
7278 end program test_log_gamma
7281 @item @emph{Specific names}:
7282 @multitable @columnfractions .20 .20 .20 .25
7283 @item Name @tab Argument @tab Return type @tab Standard
7284 @item @code{LGAMMA(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab GNU Extension
7285 @item @code{ALGAMA(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab GNU Extension
7286 @item @code{DLGAMA(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU Extension
7289 @item @emph{See also}:
7290 Gamma function: @ref{GAMMA}
7297 @section @code{LOGICAL} --- Convert to logical type
7299 @cindex conversion, to logical
7302 @item @emph{Description}:
7303 Converts one kind of @code{LOGICAL} variable to another.
7305 @item @emph{Standard}:
7306 Fortran 95 and later
7311 @item @emph{Syntax}:
7312 @code{RESULT = LOGICAL(L [, KIND])}
7314 @item @emph{Arguments}:
7315 @multitable @columnfractions .15 .70
7316 @item @var{L} @tab The type shall be @code{LOGICAL}.
7317 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
7318 expression indicating the kind parameter of the result.
7321 @item @emph{Return value}:
7322 The return value is a @code{LOGICAL} value equal to @var{L}, with a
7323 kind corresponding to @var{KIND}, or of the default logical kind if
7324 @var{KIND} is not given.
7326 @item @emph{See also}:
7327 @ref{INT}, @ref{REAL}, @ref{CMPLX}
7333 @section @code{LONG} --- Convert to integer type
7335 @cindex conversion, to integer
7338 @item @emph{Description}:
7339 Convert to a @code{KIND=4} integer type, which is the same size as a C
7340 @code{long} integer. This is equivalent to the standard @code{INT}
7341 intrinsic with an optional argument of @code{KIND=4}, and is only
7342 included for backwards compatibility.
7344 @item @emph{Standard}:
7350 @item @emph{Syntax}:
7351 @code{RESULT = LONG(A)}
7353 @item @emph{Arguments}:
7354 @multitable @columnfractions .15 .70
7355 @item @var{A} @tab Shall be of type @code{INTEGER},
7356 @code{REAL}, or @code{COMPLEX}.
7359 @item @emph{Return value}:
7360 The return value is a @code{INTEGER(4)} variable.
7362 @item @emph{See also}:
7363 @ref{INT}, @ref{INT2}, @ref{INT8}
7369 @section @code{LSHIFT} --- Left shift bits
7371 @cindex bits, shift left
7374 @item @emph{Description}:
7375 @code{LSHIFT} returns a value corresponding to @var{I} with all of the
7376 bits shifted left by @var{SHIFT} places. If the absolute value of
7377 @var{SHIFT} is greater than @code{BIT_SIZE(I)}, the value is undefined.
7378 Bits shifted out from the left end are lost; zeros are shifted in from
7381 This function has been superseded by the @code{ISHFT} intrinsic, which
7382 is standard in Fortran 95 and later.
7384 @item @emph{Standard}:
7390 @item @emph{Syntax}:
7391 @code{RESULT = LSHIFT(I, SHIFT)}
7393 @item @emph{Arguments}:
7394 @multitable @columnfractions .15 .70
7395 @item @var{I} @tab The type shall be @code{INTEGER}.
7396 @item @var{SHIFT} @tab The type shall be @code{INTEGER}.
7399 @item @emph{Return value}:
7400 The return value is of type @code{INTEGER} and of the same kind as
7403 @item @emph{See also}:
7404 @ref{ISHFT}, @ref{ISHFTC}, @ref{RSHIFT}
7411 @section @code{LSTAT} --- Get file status
7413 @cindex file system, file status
7416 @item @emph{Description}:
7417 @code{LSTAT} is identical to @ref{STAT}, except that if path is a
7418 symbolic link, then the link itself is statted, not the file that it
7421 The elements in @code{VALUES} are the same as described by @ref{STAT}.
7423 This intrinsic is provided in both subroutine and function forms;
7424 however, only one form can be used in any given program unit.
7426 @item @emph{Standard}:
7430 Subroutine, function
7432 @item @emph{Syntax}:
7433 @code{CALL LSTAT(NAME, VALUES [, STATUS])}
7435 @item @emph{Arguments}:
7436 @multitable @columnfractions .15 .70
7437 @item @var{NAME} @tab The type shall be @code{CHARACTER} of the default
7438 kind, a valid path within the file system.
7439 @item @var{VALUES} @tab The type shall be @code{INTEGER(4), DIMENSION(13)}.
7440 @item @var{STATUS} @tab (Optional) status flag of type @code{INTEGER(4)}.
7441 Returns 0 on success and a system specific error code otherwise.
7444 @item @emph{Example}:
7445 See @ref{STAT} for an example.
7447 @item @emph{See also}:
7448 To stat an open file: @ref{FSTAT}, to stat a file: @ref{STAT}
7454 @section @code{LTIME} --- Convert time to local time info
7456 @cindex time, conversion to local time info
7459 @item @emph{Description}:
7460 Given a system time value @var{TIME} (as provided by the @code{TIME8()}
7461 intrinsic), fills @var{VALUES} with values extracted from it appropriate
7462 to the local time zone using @code{localtime(3)}.
7464 @item @emph{Standard}:
7470 @item @emph{Syntax}:
7471 @code{CALL LTIME(TIME, VALUES)}
7473 @item @emph{Arguments}:
7474 @multitable @columnfractions .15 .70
7475 @item @var{TIME} @tab An @code{INTEGER} scalar expression
7476 corresponding to a system time, with @code{INTENT(IN)}.
7477 @item @var{VALUES} @tab A default @code{INTEGER} array with 9 elements,
7478 with @code{INTENT(OUT)}.
7481 @item @emph{Return value}:
7482 The elements of @var{VALUES} are assigned as follows:
7484 @item Seconds after the minute, range 0--59 or 0--61 to allow for leap
7486 @item Minutes after the hour, range 0--59
7487 @item Hours past midnight, range 0--23
7488 @item Day of month, range 0--31
7489 @item Number of months since January, range 0--12
7490 @item Years since 1900
7491 @item Number of days since Sunday, range 0--6
7492 @item Days since January 1
7493 @item Daylight savings indicator: positive if daylight savings is in
7494 effect, zero if not, and negative if the information is not available.
7497 @item @emph{See also}:
7498 @ref{CTIME}, @ref{GMTIME}, @ref{TIME}, @ref{TIME8}
7505 @section @code{MALLOC} --- Allocate dynamic memory
7507 @cindex pointer, cray
7510 @item @emph{Description}:
7511 @code{MALLOC(SIZE)} allocates @var{SIZE} bytes of dynamic memory and
7512 returns the address of the allocated memory. The @code{MALLOC} intrinsic
7513 is an extension intended to be used with Cray pointers, and is provided
7514 in GNU Fortran to allow the user to compile legacy code. For new code
7515 using Fortran 95 pointers, the memory allocation intrinsic is
7518 @item @emph{Standard}:
7524 @item @emph{Syntax}:
7525 @code{PTR = MALLOC(SIZE)}
7527 @item @emph{Arguments}:
7528 @multitable @columnfractions .15 .70
7529 @item @var{SIZE} @tab The type shall be @code{INTEGER}.
7532 @item @emph{Return value}:
7533 The return value is of type @code{INTEGER(K)}, with @var{K} such that
7534 variables of type @code{INTEGER(K)} have the same size as
7535 C pointers (@code{sizeof(void *)}).
7537 @item @emph{Example}:
7538 The following example demonstrates the use of @code{MALLOC} and
7539 @code{FREE} with Cray pointers.
7548 ptr_x = malloc(20*8)
7550 x(i) = sqrt(1.0d0 / i)
7558 end program test_malloc
7561 @item @emph{See also}:
7568 @section @code{MATMUL} --- matrix multiplication
7570 @cindex matrix multiplication
7571 @cindex product, matrix
7574 @item @emph{Description}:
7575 Performs a matrix multiplication on numeric or logical arguments.
7577 @item @emph{Standard}:
7578 Fortran 95 and later
7581 Transformational function
7583 @item @emph{Syntax}:
7584 @code{RESULT = MATMUL(MATRIX_A, MATRIX_B)}
7586 @item @emph{Arguments}:
7587 @multitable @columnfractions .15 .70
7588 @item @var{MATRIX_A} @tab An array of @code{INTEGER},
7589 @code{REAL}, @code{COMPLEX}, or @code{LOGICAL} type, with a rank of
7591 @item @var{MATRIX_B} @tab An array of @code{INTEGER},
7592 @code{REAL}, or @code{COMPLEX} type if @var{MATRIX_A} is of a numeric
7593 type; otherwise, an array of @code{LOGICAL} type. The rank shall be one
7594 or two, and the first (or only) dimension of @var{MATRIX_B} shall be
7595 equal to the last (or only) dimension of @var{MATRIX_A}.
7598 @item @emph{Return value}:
7599 The matrix product of @var{MATRIX_A} and @var{MATRIX_B}. The type and
7600 kind of the result follow the usual type and kind promotion rules, as
7601 for the @code{*} or @code{.AND.} operators.
7603 @item @emph{See also}:
7609 @section @code{MAX} --- Maximum value of an argument list
7616 @cindex maximum value
7619 @item @emph{Description}:
7620 Returns the argument with the largest (most positive) value.
7622 @item @emph{Standard}:
7623 Fortran 77 and later
7628 @item @emph{Syntax}:
7629 @code{RESULT = MAX(A1, A2 [, A3 [, ...]])}
7631 @item @emph{Arguments}:
7632 @multitable @columnfractions .15 .70
7633 @item @var{A1} @tab The type shall be @code{INTEGER} or
7635 @item @var{A2}, @var{A3}, ... @tab An expression of the same type and kind
7636 as @var{A1}. (As a GNU extension, arguments of different kinds are
7640 @item @emph{Return value}:
7641 The return value corresponds to the maximum value among the arguments,
7642 and has the same type and kind as the first argument.
7644 @item @emph{Specific names}:
7645 @multitable @columnfractions .20 .20 .20 .25
7646 @item Name @tab Argument @tab Return type @tab Standard
7647 @item @code{MAX0(A1)} @tab @code{INTEGER(4) A1} @tab @code{INTEGER(4)} @tab Fortran 77 and later
7648 @item @code{AMAX0(A1)} @tab @code{INTEGER(4) A1} @tab @code{REAL(MAX(X))} @tab Fortran 77 and later
7649 @item @code{MAX1(A1)} @tab @code{REAL A1} @tab @code{INT(MAX(X))} @tab Fortran 77 and later
7650 @item @code{AMAX1(A1)} @tab @code{REAL(4) A1} @tab @code{REAL(4)} @tab Fortran 77 and later
7651 @item @code{DMAX1(A1)} @tab @code{REAL(8) A1} @tab @code{REAL(8)} @tab Fortran 77 and later
7654 @item @emph{See also}:
7655 @ref{MAXLOC} @ref{MAXVAL}, @ref{MIN}
7662 @section @code{MAXEXPONENT} --- Maximum exponent of a real kind
7663 @fnindex MAXEXPONENT
7664 @cindex model representation, maximum exponent
7667 @item @emph{Description}:
7668 @code{MAXEXPONENT(X)} returns the maximum exponent in the model of the
7671 @item @emph{Standard}:
7672 Fortran 95 and later
7677 @item @emph{Syntax}:
7678 @code{RESULT = MAXEXPONENT(X)}
7680 @item @emph{Arguments}:
7681 @multitable @columnfractions .15 .70
7682 @item @var{X} @tab Shall be of type @code{REAL}.
7685 @item @emph{Return value}:
7686 The return value is of type @code{INTEGER} and of the default integer
7689 @item @emph{Example}:
7695 print *, minexponent(x), maxexponent(x)
7696 print *, minexponent(y), maxexponent(y)
7697 end program exponents
7704 @section @code{MAXLOC} --- Location of the maximum value within an array
7706 @cindex array, location of maximum element
7709 @item @emph{Description}:
7710 Determines the location of the element in the array with the maximum
7711 value, or, if the @var{DIM} argument is supplied, determines the
7712 locations of the maximum element along each row of the array in the
7713 @var{DIM} direction. If @var{MASK} is present, only the elements for
7714 which @var{MASK} is @code{.TRUE.} are considered. If more than one
7715 element in the array has the maximum value, the location returned is
7716 that of the first such element in array element order. If the array has
7717 zero size, or all of the elements of @var{MASK} are @code{.FALSE.}, then
7718 the result is an array of zeroes. Similarly, if @var{DIM} is supplied
7719 and all of the elements of @var{MASK} along a given row are zero, the
7720 result value for that row is zero.
7722 @item @emph{Standard}:
7723 Fortran 95 and later
7726 Transformational function
7728 @item @emph{Syntax}:
7729 @multitable @columnfractions .80
7730 @item @code{RESULT = MAXLOC(ARRAY, DIM [, MASK])}
7731 @item @code{RESULT = MAXLOC(ARRAY [, MASK])}
7734 @item @emph{Arguments}:
7735 @multitable @columnfractions .15 .70
7736 @item @var{ARRAY} @tab Shall be an array of type @code{INTEGER} or
7738 @item @var{DIM} @tab (Optional) Shall be a scalar of type
7739 @code{INTEGER}, with a value between one and the rank of @var{ARRAY},
7740 inclusive. It may not be an optional dummy argument.
7741 @item @var{MASK} @tab Shall be an array of type @code{LOGICAL},
7742 and conformable with @var{ARRAY}.
7745 @item @emph{Return value}:
7746 If @var{DIM} is absent, the result is a rank-one array with a length
7747 equal to the rank of @var{ARRAY}. If @var{DIM} is present, the result
7748 is an array with a rank one less than the rank of @var{ARRAY}, and a
7749 size corresponding to the size of @var{ARRAY} with the @var{DIM}
7750 dimension removed. If @var{DIM} is present and @var{ARRAY} has a rank
7751 of one, the result is a scalar. In all cases, the result is of default
7752 @code{INTEGER} type.
7754 @item @emph{See also}:
7755 @ref{MAX}, @ref{MAXVAL}
7762 @section @code{MAXVAL} --- Maximum value of an array
7764 @cindex array, maximum value
7765 @cindex maximum value
7768 @item @emph{Description}:
7769 Determines the maximum value of the elements in an array value, or, if
7770 the @var{DIM} argument is supplied, determines the maximum value along
7771 each row of the array in the @var{DIM} direction. If @var{MASK} is
7772 present, only the elements for which @var{MASK} is @code{.TRUE.} are
7773 considered. If the array has zero size, or all of the elements of
7774 @var{MASK} are @code{.FALSE.}, then the result is @code{-HUGE(ARRAY)}
7775 if @var{ARRAY} is numeric, or a string of nulls if @var{ARRAY} is of character
7778 @item @emph{Standard}:
7779 Fortran 95 and later
7782 Transformational function
7784 @item @emph{Syntax}:
7785 @multitable @columnfractions .80
7786 @item @code{RESULT = MAXVAL(ARRAY, DIM [, MASK])}
7787 @item @code{RESULT = MAXVAL(ARRAY [, MASK])}
7790 @item @emph{Arguments}:
7791 @multitable @columnfractions .15 .70
7792 @item @var{ARRAY} @tab Shall be an array of type @code{INTEGER} or
7794 @item @var{DIM} @tab (Optional) Shall be a scalar of type
7795 @code{INTEGER}, with a value between one and the rank of @var{ARRAY},
7796 inclusive. It may not be an optional dummy argument.
7797 @item @var{MASK} @tab Shall be an array of type @code{LOGICAL},
7798 and conformable with @var{ARRAY}.
7801 @item @emph{Return value}:
7802 If @var{DIM} is absent, or if @var{ARRAY} has a rank of one, the result
7803 is a scalar. If @var{DIM} is present, the result is an array with a
7804 rank one less than the rank of @var{ARRAY}, and a size corresponding to
7805 the size of @var{ARRAY} with the @var{DIM} dimension removed. In all
7806 cases, the result is of the same type and kind as @var{ARRAY}.
7808 @item @emph{See also}:
7809 @ref{MAX}, @ref{MAXLOC}
7815 @section @code{MCLOCK} --- Time function
7817 @cindex time, clock ticks
7821 @item @emph{Description}:
7822 Returns the number of clock ticks since the start of the process, based
7823 on the UNIX function @code{clock(3)}.
7825 This intrinsic is not fully portable, such as to systems with 32-bit
7826 @code{INTEGER} types but supporting times wider than 32 bits. Therefore,
7827 the values returned by this intrinsic might be, or become, negative, or
7828 numerically less than previous values, during a single run of the
7831 @item @emph{Standard}:
7837 @item @emph{Syntax}:
7838 @code{RESULT = MCLOCK()}
7840 @item @emph{Return value}:
7841 The return value is a scalar of type @code{INTEGER(4)}, equal to the
7842 number of clock ticks since the start of the process, or @code{-1} if
7843 the system does not support @code{clock(3)}.
7845 @item @emph{See also}:
7846 @ref{CTIME}, @ref{GMTIME}, @ref{LTIME}, @ref{MCLOCK}, @ref{TIME}
7853 @section @code{MCLOCK8} --- Time function (64-bit)
7855 @cindex time, clock ticks
7859 @item @emph{Description}:
7860 Returns the number of clock ticks since the start of the process, based
7861 on the UNIX function @code{clock(3)}.
7863 @emph{Warning:} this intrinsic does not increase the range of the timing
7864 values over that returned by @code{clock(3)}. On a system with a 32-bit
7865 @code{clock(3)}, @code{MCLOCK8()} will return a 32-bit value, even though
7866 it is converted to a 64-bit @code{INTEGER(8)} value. That means
7867 overflows of the 32-bit value can still occur. Therefore, the values
7868 returned by this intrinsic might be or become negative or numerically
7869 less than previous values during a single run of the compiled program.
7871 @item @emph{Standard}:
7877 @item @emph{Syntax}:
7878 @code{RESULT = MCLOCK8()}
7880 @item @emph{Return value}:
7881 The return value is a scalar of type @code{INTEGER(8)}, equal to the
7882 number of clock ticks since the start of the process, or @code{-1} if
7883 the system does not support @code{clock(3)}.
7885 @item @emph{See also}:
7886 @ref{CTIME}, @ref{GMTIME}, @ref{LTIME}, @ref{MCLOCK}, @ref{TIME8}
7893 @section @code{MERGE} --- Merge variables
7895 @cindex array, merge arrays
7896 @cindex array, combine arrays
7899 @item @emph{Description}:
7900 Select values from two arrays according to a logical mask. The result
7901 is equal to @var{TSOURCE} if @var{MASK} is @code{.TRUE.}, or equal to
7902 @var{FSOURCE} if it is @code{.FALSE.}.
7904 @item @emph{Standard}:
7905 Fortran 95 and later
7910 @item @emph{Syntax}:
7911 @code{RESULT = MERGE(TSOURCE, FSOURCE, MASK)}
7913 @item @emph{Arguments}:
7914 @multitable @columnfractions .15 .70
7915 @item @var{TSOURCE} @tab May be of any type.
7916 @item @var{FSOURCE} @tab Shall be of the same type and type parameters
7918 @item @var{MASK} @tab Shall be of type @code{LOGICAL}.
7921 @item @emph{Return value}:
7922 The result is of the same type and type parameters as @var{TSOURCE}.
7929 @section @code{MIN} --- Minimum value of an argument list
7936 @cindex minimum value
7939 @item @emph{Description}:
7940 Returns the argument with the smallest (most negative) value.
7942 @item @emph{Standard}:
7943 Fortran 77 and later
7948 @item @emph{Syntax}:
7949 @code{RESULT = MIN(A1, A2 [, A3, ...])}
7951 @item @emph{Arguments}:
7952 @multitable @columnfractions .15 .70
7953 @item @var{A1} @tab The type shall be @code{INTEGER} or
7955 @item @var{A2}, @var{A3}, ... @tab An expression of the same type and kind
7956 as @var{A1}. (As a GNU extension, arguments of different kinds are
7960 @item @emph{Return value}:
7961 The return value corresponds to the maximum value among the arguments,
7962 and has the same type and kind as the first argument.
7964 @item @emph{Specific names}:
7965 @multitable @columnfractions .20 .20 .20 .25
7966 @item Name @tab Argument @tab Return type @tab Standard
7967 @item @code{MIN0(A1)} @tab @code{INTEGER(4) A1} @tab @code{INTEGER(4)} @tab Fortran 77 and later
7968 @item @code{AMIN0(A1)} @tab @code{INTEGER(4) A1} @tab @code{REAL(4)} @tab Fortran 77 and later
7969 @item @code{MIN1(A1)} @tab @code{REAL A1} @tab @code{INTEGER(4)} @tab Fortran 77 and later
7970 @item @code{AMIN1(A1)} @tab @code{REAL(4) A1} @tab @code{REAL(4)} @tab Fortran 77 and later
7971 @item @code{DMIN1(A1)} @tab @code{REAL(8) A1} @tab @code{REAL(8)} @tab Fortran 77 and later
7974 @item @emph{See also}:
7975 @ref{MAX}, @ref{MINLOC}, @ref{MINVAL}
7981 @section @code{MINEXPONENT} --- Minimum exponent of a real kind
7982 @fnindex MINEXPONENT
7983 @cindex model representation, minimum exponent
7986 @item @emph{Description}:
7987 @code{MINEXPONENT(X)} returns the minimum exponent in the model of the
7990 @item @emph{Standard}:
7991 Fortran 95 and later
7996 @item @emph{Syntax}:
7997 @code{RESULT = MINEXPONENT(X)}
7999 @item @emph{Arguments}:
8000 @multitable @columnfractions .15 .70
8001 @item @var{X} @tab Shall be of type @code{REAL}.
8004 @item @emph{Return value}:
8005 The return value is of type @code{INTEGER} and of the default integer
8008 @item @emph{Example}:
8009 See @code{MAXEXPONENT} for an example.
8015 @section @code{MINLOC} --- Location of the minimum value within an array
8017 @cindex array, location of minimum element
8020 @item @emph{Description}:
8021 Determines the location of the element in the array with the minimum
8022 value, or, if the @var{DIM} argument is supplied, determines the
8023 locations of the minimum element along each row of the array in the
8024 @var{DIM} direction. If @var{MASK} is present, only the elements for
8025 which @var{MASK} is @code{.TRUE.} are considered. If more than one
8026 element in the array has the minimum value, the location returned is
8027 that of the first such element in array element order. If the array has
8028 zero size, or all of the elements of @var{MASK} are @code{.FALSE.}, then
8029 the result is an array of zeroes. Similarly, if @var{DIM} is supplied
8030 and all of the elements of @var{MASK} along a given row are zero, the
8031 result value for that row is zero.
8033 @item @emph{Standard}:
8034 Fortran 95 and later
8037 Transformational function
8039 @item @emph{Syntax}:
8040 @multitable @columnfractions .80
8041 @item @code{RESULT = MINLOC(ARRAY, DIM [, MASK])}
8042 @item @code{RESULT = MINLOC(ARRAY [, MASK])}
8045 @item @emph{Arguments}:
8046 @multitable @columnfractions .15 .70
8047 @item @var{ARRAY} @tab Shall be an array of type @code{INTEGER} or
8049 @item @var{DIM} @tab (Optional) Shall be a scalar of type
8050 @code{INTEGER}, with a value between one and the rank of @var{ARRAY},
8051 inclusive. It may not be an optional dummy argument.
8052 @item @var{MASK} @tab Shall be an array of type @code{LOGICAL},
8053 and conformable with @var{ARRAY}.
8056 @item @emph{Return value}:
8057 If @var{DIM} is absent, the result is a rank-one array with a length
8058 equal to the rank of @var{ARRAY}. If @var{DIM} is present, the result
8059 is an array with a rank one less than the rank of @var{ARRAY}, and a
8060 size corresponding to the size of @var{ARRAY} with the @var{DIM}
8061 dimension removed. If @var{DIM} is present and @var{ARRAY} has a rank
8062 of one, the result is a scalar. In all cases, the result is of default
8063 @code{INTEGER} type.
8065 @item @emph{See also}:
8066 @ref{MIN}, @ref{MINVAL}
8073 @section @code{MINVAL} --- Minimum value of an array
8075 @cindex array, minimum value
8076 @cindex minimum value
8079 @item @emph{Description}:
8080 Determines the minimum value of the elements in an array value, or, if
8081 the @var{DIM} argument is supplied, determines the minimum value along
8082 each row of the array in the @var{DIM} direction. If @var{MASK} is
8083 present, only the elements for which @var{MASK} is @code{.TRUE.} are
8084 considered. If the array has zero size, or all of the elements of
8085 @var{MASK} are @code{.FALSE.}, then the result is @code{HUGE(ARRAY)} if
8086 @var{ARRAY} is numeric, or a string of @code{CHAR(255)} characters if
8087 @var{ARRAY} is of character type.
8089 @item @emph{Standard}:
8090 Fortran 95 and later
8093 Transformational function
8095 @item @emph{Syntax}:
8096 @multitable @columnfractions .80
8097 @item @code{RESULT = MINVAL(ARRAY, DIM [, MASK])}
8098 @item @code{RESULT = MINVAL(ARRAY [, MASK])}
8101 @item @emph{Arguments}:
8102 @multitable @columnfractions .15 .70
8103 @item @var{ARRAY} @tab Shall be an array of type @code{INTEGER} or
8105 @item @var{DIM} @tab (Optional) Shall be a scalar of type
8106 @code{INTEGER}, with a value between one and the rank of @var{ARRAY},
8107 inclusive. It may not be an optional dummy argument.
8108 @item @var{MASK} @tab Shall be an array of type @code{LOGICAL},
8109 and conformable with @var{ARRAY}.
8112 @item @emph{Return value}:
8113 If @var{DIM} is absent, or if @var{ARRAY} has a rank of one, the result
8114 is a scalar. If @var{DIM} is present, the result is an array with a
8115 rank one less than the rank of @var{ARRAY}, and a size corresponding to
8116 the size of @var{ARRAY} with the @var{DIM} dimension removed. In all
8117 cases, the result is of the same type and kind as @var{ARRAY}.
8119 @item @emph{See also}:
8120 @ref{MIN}, @ref{MINLOC}
8127 @section @code{MOD} --- Remainder function
8132 @cindex division, remainder
8135 @item @emph{Description}:
8136 @code{MOD(A,P)} computes the remainder of the division of A by P@. It is
8137 calculated as @code{A - (INT(A/P) * P)}.
8139 @item @emph{Standard}:
8140 Fortran 77 and later
8145 @item @emph{Syntax}:
8146 @code{RESULT = MOD(A, P)}
8148 @item @emph{Arguments}:
8149 @multitable @columnfractions .15 .70
8150 @item @var{A} @tab Shall be a scalar of type @code{INTEGER} or @code{REAL}
8151 @item @var{P} @tab Shall be a scalar of the same type as @var{A} and not
8155 @item @emph{Return value}:
8156 The kind of the return value is the result of cross-promoting
8157 the kinds of the arguments.
8159 @item @emph{Example}:
8163 print *, mod(17.5,5.5)
8164 print *, mod(17.5d0,5.5)
8165 print *, mod(17.5,5.5d0)
8168 print *, mod(-17.5,5.5)
8169 print *, mod(-17.5d0,5.5)
8170 print *, mod(-17.5,5.5d0)
8173 print *, mod(17.5,-5.5)
8174 print *, mod(17.5d0,-5.5)
8175 print *, mod(17.5,-5.5d0)
8176 end program test_mod
8179 @item @emph{Specific names}:
8180 @multitable @columnfractions .20 .20 .20 .25
8181 @item Name @tab Arguments @tab Return type @tab Standard
8182 @item @code{MOD(A,P)} @tab @code{INTEGER A,P} @tab @code{INTEGER} @tab Fortran 95 and later
8183 @item @code{AMOD(A,P)} @tab @code{REAL(4) A,P} @tab @code{REAL(4)} @tab Fortran 95 and later
8184 @item @code{DMOD(A,P)} @tab @code{REAL(8) A,P} @tab @code{REAL(8)} @tab Fortran 95 and later
8191 @section @code{MODULO} --- Modulo function
8194 @cindex division, modulo
8197 @item @emph{Description}:
8198 @code{MODULO(A,P)} computes the @var{A} modulo @var{P}.
8200 @item @emph{Standard}:
8201 Fortran 95 and later
8206 @item @emph{Syntax}:
8207 @code{RESULT = MODULO(A, P)}
8209 @item @emph{Arguments}:
8210 @multitable @columnfractions .15 .70
8211 @item @var{A} @tab Shall be a scalar of type @code{INTEGER} or @code{REAL}
8212 @item @var{P} @tab Shall be a scalar of the same type and kind as @var{A}
8215 @item @emph{Return value}:
8216 The type and kind of the result are those of the arguments.
8218 @item If @var{A} and @var{P} are of type @code{INTEGER}:
8219 @code{MODULO(A,P)} has the value @var{R} such that @code{A=Q*P+R}, where
8220 @var{Q} is an integer and @var{R} is between 0 (inclusive) and @var{P}
8222 @item If @var{A} and @var{P} are of type @code{REAL}:
8223 @code{MODULO(A,P)} has the value of @code{A - FLOOR (A / P) * P}.
8225 In all cases, if @var{P} is zero the result is processor-dependent.
8227 @item @emph{Example}:
8230 print *, modulo(17,3)
8231 print *, modulo(17.5,5.5)
8233 print *, modulo(-17,3)
8234 print *, modulo(-17.5,5.5)
8236 print *, modulo(17,-3)
8237 print *, modulo(17.5,-5.5)
8246 @section @code{MOVE_ALLOC} --- Move allocation from one object to another
8248 @cindex moving allocation
8249 @cindex allocation, moving
8252 @item @emph{Description}:
8253 @code{MOVE_ALLOC(FROM, TO)} moves the allocation from @var{FROM} to
8254 @var{TO}. @var{FROM} will become deallocated in the process.
8256 @item @emph{Standard}:
8257 Fortran 2003 and later
8262 @item @emph{Syntax}:
8263 @code{CALL MOVE_ALLOC(FROM, TO)}
8265 @item @emph{Arguments}:
8266 @multitable @columnfractions .15 .70
8267 @item @var{FROM} @tab @code{ALLOCATABLE}, @code{INTENT(INOUT)}, may be
8268 of any type and kind.
8269 @item @var{TO} @tab @code{ALLOCATABLE}, @code{INTENT(OUT)}, shall be
8270 of the same type, kind and rank as @var{FROM}.
8273 @item @emph{Return value}:
8276 @item @emph{Example}:
8278 program test_move_alloc
8279 integer, allocatable :: a(:), b(:)
8283 call move_alloc(a, b)
8284 print *, allocated(a), allocated(b)
8286 end program test_move_alloc
8293 @section @code{MVBITS} --- Move bits from one integer to another
8298 @item @emph{Description}:
8299 Moves @var{LEN} bits from positions @var{FROMPOS} through
8300 @code{FROMPOS+LEN-1} of @var{FROM} to positions @var{TOPOS} through
8301 @code{TOPOS+LEN-1} of @var{TO}. The portion of argument @var{TO} not
8302 affected by the movement of bits is unchanged. The values of
8303 @code{FROMPOS+LEN-1} and @code{TOPOS+LEN-1} must be less than
8304 @code{BIT_SIZE(FROM)}.
8306 @item @emph{Standard}:
8307 Fortran 95 and later
8310 Elemental subroutine
8312 @item @emph{Syntax}:
8313 @code{CALL MVBITS(FROM, FROMPOS, LEN, TO, TOPOS)}
8315 @item @emph{Arguments}:
8316 @multitable @columnfractions .15 .70
8317 @item @var{FROM} @tab The type shall be @code{INTEGER}.
8318 @item @var{FROMPOS} @tab The type shall be @code{INTEGER}.
8319 @item @var{LEN} @tab The type shall be @code{INTEGER}.
8320 @item @var{TO} @tab The type shall be @code{INTEGER}, of the
8321 same kind as @var{FROM}.
8322 @item @var{TOPOS} @tab The type shall be @code{INTEGER}.
8325 @item @emph{See also}:
8326 @ref{IBCLR}, @ref{IBSET}, @ref{IBITS}, @ref{IAND}, @ref{IOR}, @ref{IEOR}
8332 @section @code{NEAREST} --- Nearest representable number
8334 @cindex real number, nearest different
8335 @cindex floating point, nearest different
8338 @item @emph{Description}:
8339 @code{NEAREST(X, S)} returns the processor-representable number nearest
8340 to @code{X} in the direction indicated by the sign of @code{S}.
8342 @item @emph{Standard}:
8343 Fortran 95 and later
8348 @item @emph{Syntax}:
8349 @code{RESULT = NEAREST(X, S)}
8351 @item @emph{Arguments}:
8352 @multitable @columnfractions .15 .70
8353 @item @var{X} @tab Shall be of type @code{REAL}.
8354 @item @var{S} @tab (Optional) shall be of type @code{REAL} and
8358 @item @emph{Return value}:
8359 The return value is of the same type as @code{X}. If @code{S} is
8360 positive, @code{NEAREST} returns the processor-representable number
8361 greater than @code{X} and nearest to it. If @code{S} is negative,
8362 @code{NEAREST} returns the processor-representable number smaller than
8363 @code{X} and nearest to it.
8365 @item @emph{Example}:
8367 program test_nearest
8369 x = nearest(42.0, 1.0)
8370 y = nearest(42.0, -1.0)
8371 write (*,"(3(G20.15))") x, y, x - y
8372 end program test_nearest
8379 @section @code{NEW_LINE} --- New line character
8382 @cindex output, newline
8385 @item @emph{Description}:
8386 @code{NEW_LINE(C)} returns the new-line character.
8388 @item @emph{Standard}:
8389 Fortran 2003 and later
8394 @item @emph{Syntax}:
8395 @code{RESULT = NEW_LINE(C)}
8397 @item @emph{Arguments}:
8398 @multitable @columnfractions .15 .70
8399 @item @var{C} @tab The argument shall be a scalar or array of the
8400 type @code{CHARACTER}.
8403 @item @emph{Return value}:
8404 Returns a @var{CHARACTER} scalar of length one with the new-line character of
8405 the same kind as parameter @var{C}.
8407 @item @emph{Example}:
8411 write(*,'(A)') 'This is record 1.'//NEW_LINE('A')//'This is record 2.'
8419 @section @code{NINT} --- Nearest whole number
8422 @cindex rounding, nearest whole number
8425 @item @emph{Description}:
8426 @code{NINT(A)} rounds its argument to the nearest whole number.
8428 @item @emph{Standard}:
8429 Fortran 77 and later, with @var{KIND} argument Fortran 90 and later
8434 @item @emph{Syntax}:
8435 @code{RESULT = NINT(A [, KIND])}
8437 @item @emph{Arguments}:
8438 @multitable @columnfractions .15 .70
8439 @item @var{A} @tab The type of the argument shall be @code{REAL}.
8440 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
8441 expression indicating the kind parameter of the result.
8444 @item @emph{Return value}:
8445 Returns @var{A} with the fractional portion of its magnitude eliminated by
8446 rounding to the nearest whole number and with its sign preserved,
8447 converted to an @code{INTEGER} of the default kind.
8449 @item @emph{Example}:
8456 print *, nint(x4), idnint(x8)
8457 end program test_nint
8460 @item @emph{Specific names}:
8461 @multitable @columnfractions .20 .20 .20 .25
8462 @item Name @tab Argument @tab Return Type @tab Standard
8463 @item @code{NINT(A)} @tab @code{REAL(4) A} @tab @code{INTEGER} @tab Fortran 95 and later
8464 @item @code{IDNINT(A)} @tab @code{REAL(8) A} @tab @code{INTEGER} @tab Fortran 95 and later
8467 @item @emph{See also}:
8468 @ref{CEILING}, @ref{FLOOR}
8475 @section @code{NOT} --- Logical negation
8477 @cindex bits, negate
8478 @cindex bitwise logical not
8479 @cindex logical not, bitwise
8482 @item @emph{Description}:
8483 @code{NOT} returns the bitwise boolean inverse of @var{I}.
8485 @item @emph{Standard}:
8486 Fortran 95 and later
8491 @item @emph{Syntax}:
8492 @code{RESULT = NOT(I)}
8494 @item @emph{Arguments}:
8495 @multitable @columnfractions .15 .70
8496 @item @var{I} @tab The type shall be @code{INTEGER}.
8499 @item @emph{Return value}:
8500 The return type is @code{INTEGER}, of the same kind as the
8503 @item @emph{See also}:
8504 @ref{IAND}, @ref{IEOR}, @ref{IOR}, @ref{IBITS}, @ref{IBSET}, @ref{IBCLR}
8511 @section @code{NULL} --- Function that returns an disassociated pointer
8513 @cindex pointer, status
8514 @cindex pointer, disassociated
8517 @item @emph{Description}:
8518 Returns a disassociated pointer.
8520 If @var{MOLD} is present, a dissassociated pointer of the same type is
8521 returned, otherwise the type is determined by context.
8523 In Fortran 95, @var{MOLD} is optional. Please note that Fortran 2003
8524 includes cases where it is required.
8526 @item @emph{Standard}:
8527 Fortran 95 and later
8530 Transformational function
8532 @item @emph{Syntax}:
8533 @code{PTR => NULL([MOLD])}
8535 @item @emph{Arguments}:
8536 @multitable @columnfractions .15 .70
8537 @item @var{MOLD} @tab (Optional) shall be a pointer of any association
8538 status and of any type.
8541 @item @emph{Return value}:
8542 A disassociated pointer.
8544 @item @emph{Example}:
8546 REAL, POINTER, DIMENSION(:) :: VEC => NULL ()
8549 @item @emph{See also}:
8556 @section @code{NUM_IMAGES} --- Function that returns the number of images
8558 @cindex coarray, NUM_IMAGES
8559 @cindex images, number of
8562 @item @emph{Description}:
8563 Returns the number of images.
8565 @item @emph{Standard}:
8566 Fortran 2008 and later
8569 Transformational function
8571 @item @emph{Syntax}:
8572 @code{RESULT = NUM_IMAGES()}
8574 @item @emph{Arguments}: None.
8576 @item @emph{Return value}:
8577 Scalar default-kind integer.
8579 @item @emph{Example}:
8583 value = THIS_IMAGE()
8585 IF (THIS_IMAGE() == 1) THEN
8586 DO i = 1, NUM_IMAGES()
8587 WRITE(*,'(2(a,i0))') 'value[', i, '] is ', value[i]
8592 @item @emph{See also}:
8593 @ref{THIS_IMAGE}, @ref{IMAGE_INDEX}
8599 @section @code{OR} --- Bitwise logical OR
8601 @cindex bitwise logical or
8602 @cindex logical or, bitwise
8605 @item @emph{Description}:
8606 Bitwise logical @code{OR}.
8608 This intrinsic routine is provided for backwards compatibility with
8609 GNU Fortran 77. For integer arguments, programmers should consider
8610 the use of the @ref{IOR} intrinsic defined by the Fortran standard.
8612 @item @emph{Standard}:
8618 @item @emph{Syntax}:
8619 @code{RESULT = OR(I, J)}
8621 @item @emph{Arguments}:
8622 @multitable @columnfractions .15 .70
8623 @item @var{I} @tab The type shall be either a scalar @code{INTEGER}
8624 type or a scalar @code{LOGICAL} type.
8625 @item @var{J} @tab The type shall be the same as the type of @var{J}.
8628 @item @emph{Return value}:
8629 The return type is either a scalar @code{INTEGER} or a scalar
8630 @code{LOGICAL}. If the kind type parameters differ, then the
8631 smaller kind type is implicitly converted to larger kind, and the
8632 return has the larger kind.
8634 @item @emph{Example}:
8637 LOGICAL :: T = .TRUE., F = .FALSE.
8639 DATA a / Z'F' /, b / Z'3' /
8641 WRITE (*,*) OR(T, T), OR(T, F), OR(F, T), OR(F, F)
8642 WRITE (*,*) OR(a, b)
8646 @item @emph{See also}:
8647 Fortran 95 elemental function: @ref{IOR}
8653 @section @code{PACK} --- Pack an array into an array of rank one
8655 @cindex array, packing
8656 @cindex array, reduce dimension
8657 @cindex array, gather elements
8660 @item @emph{Description}:
8661 Stores the elements of @var{ARRAY} in an array of rank one.
8663 The beginning of the resulting array is made up of elements whose @var{MASK}
8664 equals @code{TRUE}. Afterwards, positions are filled with elements taken from
8667 @item @emph{Standard}:
8668 Fortran 95 and later
8671 Transformational function
8673 @item @emph{Syntax}:
8674 @code{RESULT = PACK(ARRAY, MASK[,VECTOR]}
8676 @item @emph{Arguments}:
8677 @multitable @columnfractions .15 .70
8678 @item @var{ARRAY} @tab Shall be an array of any type.
8679 @item @var{MASK} @tab Shall be an array of type @code{LOGICAL} and
8680 of the same size as @var{ARRAY}. Alternatively, it may be a @code{LOGICAL}
8682 @item @var{VECTOR} @tab (Optional) shall be an array of the same type
8683 as @var{ARRAY} and of rank one. If present, the number of elements in
8684 @var{VECTOR} shall be equal to or greater than the number of true elements
8685 in @var{MASK}. If @var{MASK} is scalar, the number of elements in
8686 @var{VECTOR} shall be equal to or greater than the number of elements in
8690 @item @emph{Return value}:
8691 The result is an array of rank one and the same type as that of @var{ARRAY}.
8692 If @var{VECTOR} is present, the result size is that of @var{VECTOR}, the
8693 number of @code{TRUE} values in @var{MASK} otherwise.
8695 @item @emph{Example}:
8696 Gathering nonzero elements from an array:
8700 m = (/ 1, 0, 0, 0, 5, 0 /)
8701 WRITE(*, FMT="(6(I0, ' '))") pack(m, m /= 0) ! "1 5"
8705 Gathering nonzero elements from an array and appending elements from @var{VECTOR}:
8709 m = (/ 1, 0, 0, 2 /)
8710 WRITE(*, FMT="(4(I0, ' '))") pack(m, m /= 0, (/ 0, 0, 3, 4 /)) ! "1 2 3 4"
8714 @item @emph{See also}:
8721 @section @code{PERROR} --- Print system error message
8723 @cindex system, error handling
8726 @item @emph{Description}:
8727 Prints (on the C @code{stderr} stream) a newline-terminated error
8728 message corresponding to the last system error. This is prefixed by
8729 @var{STRING}, a colon and a space. See @code{perror(3)}.
8731 @item @emph{Standard}:
8737 @item @emph{Syntax}:
8738 @code{CALL PERROR(STRING)}
8740 @item @emph{Arguments}:
8741 @multitable @columnfractions .15 .70
8742 @item @var{STRING} @tab A scalar of type @code{CHARACTER} and of the
8746 @item @emph{See also}:
8753 @section @code{PRECISION} --- Decimal precision of a real kind
8755 @cindex model representation, precision
8758 @item @emph{Description}:
8759 @code{PRECISION(X)} returns the decimal precision in the model of the
8762 @item @emph{Standard}:
8763 Fortran 95 and later
8768 @item @emph{Syntax}:
8769 @code{RESULT = PRECISION(X)}
8771 @item @emph{Arguments}:
8772 @multitable @columnfractions .15 .70
8773 @item @var{X} @tab Shall be of type @code{REAL} or @code{COMPLEX}.
8776 @item @emph{Return value}:
8777 The return value is of type @code{INTEGER} and of the default integer
8780 @item @emph{See also}:
8781 @ref{SELECTED_REAL_KIND}, @ref{RANGE}
8783 @item @emph{Example}:
8785 program prec_and_range
8786 real(kind=4) :: x(2)
8787 complex(kind=8) :: y
8789 print *, precision(x), range(x)
8790 print *, precision(y), range(y)
8791 end program prec_and_range
8798 @section @code{PRESENT} --- Determine whether an optional dummy argument is specified
8802 @item @emph{Description}:
8803 Determines whether an optional dummy argument is present.
8805 @item @emph{Standard}:
8806 Fortran 95 and later
8811 @item @emph{Syntax}:
8812 @code{RESULT = PRESENT(A)}
8814 @item @emph{Arguments}:
8815 @multitable @columnfractions .15 .70
8816 @item @var{A} @tab May be of any type and may be a pointer, scalar or array
8817 value, or a dummy procedure. It shall be the name of an optional dummy argument
8818 accessible within the current subroutine or function.
8821 @item @emph{Return value}:
8822 Returns either @code{TRUE} if the optional argument @var{A} is present, or
8823 @code{FALSE} otherwise.
8825 @item @emph{Example}:
8827 PROGRAM test_present
8828 WRITE(*,*) f(), f(42) ! "F T"
8830 LOGICAL FUNCTION f(x)
8831 INTEGER, INTENT(IN), OPTIONAL :: x
8841 @section @code{PRODUCT} --- Product of array elements
8843 @cindex array, product
8844 @cindex array, multiply elements
8845 @cindex array, conditionally multiply elements
8846 @cindex multiply array elements
8849 @item @emph{Description}:
8850 Multiplies the elements of @var{ARRAY} along dimension @var{DIM} if
8851 the corresponding element in @var{MASK} is @code{TRUE}.
8853 @item @emph{Standard}:
8854 Fortran 95 and later
8857 Transformational function
8859 @item @emph{Syntax}:
8860 @multitable @columnfractions .80
8861 @item @code{RESULT = PRODUCT(ARRAY[, MASK])}
8862 @item @code{RESULT = PRODUCT(ARRAY, DIM[, MASK])}
8865 @item @emph{Arguments}:
8866 @multitable @columnfractions .15 .70
8867 @item @var{ARRAY} @tab Shall be an array of type @code{INTEGER},
8868 @code{REAL} or @code{COMPLEX}.
8869 @item @var{DIM} @tab (Optional) shall be a scalar of type
8870 @code{INTEGER} with a value in the range from 1 to n, where n
8871 equals the rank of @var{ARRAY}.
8872 @item @var{MASK} @tab (Optional) shall be of type @code{LOGICAL}
8873 and either be a scalar or an array of the same shape as @var{ARRAY}.
8876 @item @emph{Return value}:
8877 The result is of the same type as @var{ARRAY}.
8879 If @var{DIM} is absent, a scalar with the product of all elements in
8880 @var{ARRAY} is returned. Otherwise, an array of rank n-1, where n equals
8881 the rank of @var{ARRAY}, and a shape similar to that of @var{ARRAY} with
8882 dimension @var{DIM} dropped is returned.
8885 @item @emph{Example}:
8887 PROGRAM test_product
8888 INTEGER :: x(5) = (/ 1, 2, 3, 4 ,5 /)
8889 print *, PRODUCT(x) ! all elements, product = 120
8890 print *, PRODUCT(x, MASK=MOD(x, 2)==1) ! odd elements, product = 15
8894 @item @emph{See also}:
8901 @section @code{RADIX} --- Base of a model number
8903 @cindex model representation, base
8904 @cindex model representation, radix
8907 @item @emph{Description}:
8908 @code{RADIX(X)} returns the base of the model representing the entity @var{X}.
8910 @item @emph{Standard}:
8911 Fortran 95 and later
8916 @item @emph{Syntax}:
8917 @code{RESULT = RADIX(X)}
8919 @item @emph{Arguments}:
8920 @multitable @columnfractions .15 .70
8921 @item @var{X} @tab Shall be of type @code{INTEGER} or @code{REAL}
8924 @item @emph{Return value}:
8925 The return value is a scalar of type @code{INTEGER} and of the default
8928 @item @emph{See also}:
8929 @ref{SELECTED_REAL_KIND}
8931 @item @emph{Example}:
8934 print *, "The radix for the default integer kind is", radix(0)
8935 print *, "The radix for the default real kind is", radix(0.0)
8936 end program test_radix
8944 @section @code{RAN} --- Real pseudo-random number
8946 @cindex random number generation
8949 @item @emph{Description}:
8950 For compatibility with HP FORTRAN 77/iX, the @code{RAN} intrinsic is
8951 provided as an alias for @code{RAND}. See @ref{RAND} for complete
8954 @item @emph{Standard}:
8960 @item @emph{See also}:
8961 @ref{RAND}, @ref{RANDOM_NUMBER}
8967 @section @code{RAND} --- Real pseudo-random number
8969 @cindex random number generation
8972 @item @emph{Description}:
8973 @code{RAND(FLAG)} returns a pseudo-random number from a uniform
8974 distribution between 0 and 1. If @var{FLAG} is 0, the next number
8975 in the current sequence is returned; if @var{FLAG} is 1, the generator
8976 is restarted by @code{CALL SRAND(0)}; if @var{FLAG} has any other value,
8977 it is used as a new seed with @code{SRAND}.
8979 This intrinsic routine is provided for backwards compatibility with
8980 GNU Fortran 77. It implements a simple modulo generator as provided
8981 by @command{g77}. For new code, one should consider the use of
8982 @ref{RANDOM_NUMBER} as it implements a superior algorithm.
8984 @item @emph{Standard}:
8990 @item @emph{Syntax}:
8991 @code{RESULT = RAND(I)}
8993 @item @emph{Arguments}:
8994 @multitable @columnfractions .15 .70
8995 @item @var{I} @tab Shall be a scalar @code{INTEGER} of kind 4.
8998 @item @emph{Return value}:
8999 The return value is of @code{REAL} type and the default kind.
9001 @item @emph{Example}:
9004 integer,parameter :: seed = 86456
9007 print *, rand(), rand(), rand(), rand()
9008 print *, rand(seed), rand(), rand(), rand()
9009 end program test_rand
9012 @item @emph{See also}:
9013 @ref{SRAND}, @ref{RANDOM_NUMBER}
9020 @section @code{RANDOM_NUMBER} --- Pseudo-random number
9021 @fnindex RANDOM_NUMBER
9022 @cindex random number generation
9025 @item @emph{Description}:
9026 Returns a single pseudorandom number or an array of pseudorandom numbers
9027 from the uniform distribution over the range @math{ 0 \leq x < 1}.
9029 The runtime-library implements George Marsaglia's KISS (Keep It Simple
9030 Stupid) random number generator (RNG). This RNG combines:
9032 @item The congruential generator @math{x(n) = 69069 \cdot x(n-1) + 1327217885}
9033 with a period of @math{2^{32}},
9034 @item A 3-shift shift-register generator with a period of @math{2^{32} - 1},
9035 @item Two 16-bit multiply-with-carry generators with a period of
9036 @math{597273182964842497 > 2^{59}}.
9038 The overall period exceeds @math{2^{123}}.
9040 Please note, this RNG is thread safe if used within OpenMP directives,
9041 i.e., its state will be consistent while called from multiple threads.
9042 However, the KISS generator does not create random numbers in parallel
9043 from multiple sources, but in sequence from a single source. If an
9044 OpenMP-enabled application heavily relies on random numbers, one should
9045 consider employing a dedicated parallel random number generator instead.
9047 @item @emph{Standard}:
9048 Fortran 95 and later
9053 @item @emph{Syntax}:
9054 @code{RANDOM_NUMBER(HARVEST)}
9056 @item @emph{Arguments}:
9057 @multitable @columnfractions .15 .70
9058 @item @var{HARVEST} @tab Shall be a scalar or an array of type @code{REAL}.
9061 @item @emph{Example}:
9063 program test_random_number
9065 CALL init_random_seed() ! see example of RANDOM_SEED
9066 CALL RANDOM_NUMBER(r)
9070 @item @emph{See also}:
9077 @section @code{RANDOM_SEED} --- Initialize a pseudo-random number sequence
9078 @fnindex RANDOM_SEED
9079 @cindex random number generation, seeding
9080 @cindex seeding a random number generator
9083 @item @emph{Description}:
9084 Restarts or queries the state of the pseudorandom number generator used by
9085 @code{RANDOM_NUMBER}.
9087 If @code{RANDOM_SEED} is called without arguments, it is initialized to
9088 a default state. The example below shows how to initialize the random
9089 seed based on the system's time.
9091 @item @emph{Standard}:
9092 Fortran 95 and later
9097 @item @emph{Syntax}:
9098 @code{CALL RANDOM_SEED([SIZE, PUT, GET])}
9100 @item @emph{Arguments}:
9101 @multitable @columnfractions .15 .70
9102 @item @var{SIZE} @tab (Optional) Shall be a scalar and of type default
9103 @code{INTEGER}, with @code{INTENT(OUT)}. It specifies the minimum size
9104 of the arrays used with the @var{PUT} and @var{GET} arguments.
9105 @item @var{PUT} @tab (Optional) Shall be an array of type default
9106 @code{INTEGER} and rank one. It is @code{INTENT(IN)} and the size of
9107 the array must be larger than or equal to the number returned by the
9108 @var{SIZE} argument.
9109 @item @var{GET} @tab (Optional) Shall be an array of type default
9110 @code{INTEGER} and rank one. It is @code{INTENT(OUT)} and the size
9111 of the array must be larger than or equal to the number returned by
9112 the @var{SIZE} argument.
9115 @item @emph{Example}:
9117 SUBROUTINE init_random_seed()
9118 INTEGER :: i, n, clock
9119 INTEGER, DIMENSION(:), ALLOCATABLE :: seed
9121 CALL RANDOM_SEED(size = n)
9124 CALL SYSTEM_CLOCK(COUNT=clock)
9126 seed = clock + 37 * (/ (i - 1, i = 1, n) /)
9127 CALL RANDOM_SEED(PUT = seed)
9133 @item @emph{See also}:
9140 @section @code{RANGE} --- Decimal exponent range
9142 @cindex model representation, range
9145 @item @emph{Description}:
9146 @code{RANGE(X)} returns the decimal exponent range in the model of the
9149 @item @emph{Standard}:
9150 Fortran 95 and later
9155 @item @emph{Syntax}:
9156 @code{RESULT = RANGE(X)}
9158 @item @emph{Arguments}:
9159 @multitable @columnfractions .15 .70
9160 @item @var{X} @tab Shall be of type @code{INTEGER}, @code{REAL}
9164 @item @emph{Return value}:
9165 The return value is of type @code{INTEGER} and of the default integer
9168 @item @emph{See also}:
9169 @ref{SELECTED_REAL_KIND}, @ref{PRECISION}
9171 @item @emph{Example}:
9172 See @code{PRECISION} for an example.
9178 @section @code{REAL} --- Convert to real type
9184 @cindex conversion, to real
9185 @cindex complex numbers, real part
9188 @item @emph{Description}:
9189 @code{REAL(A [, KIND])} converts its argument @var{A} to a real type. The
9190 @code{REALPART} function is provided for compatibility with @command{g77},
9191 and its use is strongly discouraged.
9193 @item @emph{Standard}:
9194 Fortran 77 and later
9199 @item @emph{Syntax}:
9200 @multitable @columnfractions .80
9201 @item @code{RESULT = REAL(A [, KIND])}
9202 @item @code{RESULT = REALPART(Z)}
9205 @item @emph{Arguments}:
9206 @multitable @columnfractions .15 .70
9207 @item @var{A} @tab Shall be @code{INTEGER}, @code{REAL}, or
9209 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
9210 expression indicating the kind parameter of the result.
9213 @item @emph{Return value}:
9214 These functions return a @code{REAL} variable or array under
9215 the following rules:
9219 @code{REAL(A)} is converted to a default real type if @var{A} is an
9220 integer or real variable.
9222 @code{REAL(A)} is converted to a real type with the kind type parameter
9223 of @var{A} if @var{A} is a complex variable.
9225 @code{REAL(A, KIND)} is converted to a real type with kind type
9226 parameter @var{KIND} if @var{A} is a complex, integer, or real
9230 @item @emph{Example}:
9233 complex :: x = (1.0, 2.0)
9234 print *, real(x), real(x,8), realpart(x)
9235 end program test_real
9238 @item @emph{Specific names}:
9239 @multitable @columnfractions .20 .20 .20 .25
9240 @item Name @tab Argument @tab Return type @tab Standard
9241 @item @code{FLOAT(A)} @tab @code{INTEGER(4)} @tab @code{REAL(4)} @tab Fortran 77 and later
9242 @item @code{DFLOAT(A)} @tab @code{INTEGER(4)} @tab @code{REAL(8)} @tab GNU extension
9243 @item @code{SNGL(A)} @tab @code{INTEGER(8)} @tab @code{REAL(4)} @tab Fortran 77 and later
9247 @item @emph{See also}:
9255 @section @code{RENAME} --- Rename a file
9257 @cindex file system, rename file
9260 @item @emph{Description}:
9261 Renames a file from file @var{PATH1} to @var{PATH2}. A null
9262 character (@code{CHAR(0)}) can be used to mark the end of the names in
9263 @var{PATH1} and @var{PATH2}; otherwise, trailing blanks in the file
9264 names are ignored. If the @var{STATUS} argument is supplied, it
9265 contains 0 on success or a nonzero error code upon return; see
9268 This intrinsic is provided in both subroutine and function forms;
9269 however, only one form can be used in any given program unit.
9271 @item @emph{Standard}:
9275 Subroutine, function
9277 @item @emph{Syntax}:
9278 @multitable @columnfractions .80
9279 @item @code{CALL RENAME(PATH1, PATH2 [, STATUS])}
9280 @item @code{STATUS = RENAME(PATH1, PATH2)}
9283 @item @emph{Arguments}:
9284 @multitable @columnfractions .15 .70
9285 @item @var{PATH1} @tab Shall be of default @code{CHARACTER} type.
9286 @item @var{PATH2} @tab Shall be of default @code{CHARACTER} type.
9287 @item @var{STATUS} @tab (Optional) Shall be of default @code{INTEGER} type.
9290 @item @emph{See also}:
9298 @section @code{REPEAT} --- Repeated string concatenation
9300 @cindex string, repeat
9301 @cindex string, concatenate
9304 @item @emph{Description}:
9305 Concatenates @var{NCOPIES} copies of a string.
9307 @item @emph{Standard}:
9308 Fortran 95 and later
9311 Transformational function
9313 @item @emph{Syntax}:
9314 @code{RESULT = REPEAT(STRING, NCOPIES)}
9316 @item @emph{Arguments}:
9317 @multitable @columnfractions .15 .70
9318 @item @var{STRING} @tab Shall be scalar and of type @code{CHARACTER}.
9319 @item @var{NCOPIES} @tab Shall be scalar and of type @code{INTEGER}.
9322 @item @emph{Return value}:
9323 A new scalar of type @code{CHARACTER} built up from @var{NCOPIES} copies
9326 @item @emph{Example}:
9329 write(*,*) repeat("x", 5) ! "xxxxx"
9337 @section @code{RESHAPE} --- Function to reshape an array
9339 @cindex array, change dimensions
9340 @cindex array, transmogrify
9343 @item @emph{Description}:
9344 Reshapes @var{SOURCE} to correspond to @var{SHAPE}. If necessary,
9345 the new array may be padded with elements from @var{PAD} or permuted
9346 as defined by @var{ORDER}.
9348 @item @emph{Standard}:
9349 Fortran 95 and later
9352 Transformational function
9354 @item @emph{Syntax}:
9355 @code{RESULT = RESHAPE(SOURCE, SHAPE[, PAD, ORDER])}
9357 @item @emph{Arguments}:
9358 @multitable @columnfractions .15 .70
9359 @item @var{SOURCE} @tab Shall be an array of any type.
9360 @item @var{SHAPE} @tab Shall be of type @code{INTEGER} and an
9361 array of rank one. Its values must be positive or zero.
9362 @item @var{PAD} @tab (Optional) shall be an array of the same
9363 type as @var{SOURCE}.
9364 @item @var{ORDER} @tab (Optional) shall be of type @code{INTEGER}
9365 and an array of the same shape as @var{SHAPE}. Its values shall
9366 be a permutation of the numbers from 1 to n, where n is the size of
9367 @var{SHAPE}. If @var{ORDER} is absent, the natural ordering shall
9371 @item @emph{Return value}:
9372 The result is an array of shape @var{SHAPE} with the same type as
9375 @item @emph{Example}:
9377 PROGRAM test_reshape
9378 INTEGER, DIMENSION(4) :: x
9379 WRITE(*,*) SHAPE(x) ! prints "4"
9380 WRITE(*,*) SHAPE(RESHAPE(x, (/2, 2/))) ! prints "2 2"
9384 @item @emph{See also}:
9391 @section @code{RRSPACING} --- Reciprocal of the relative spacing
9393 @cindex real number, relative spacing
9394 @cindex floating point, relative spacing
9398 @item @emph{Description}:
9399 @code{RRSPACING(X)} returns the reciprocal of the relative spacing of
9400 model numbers near @var{X}.
9402 @item @emph{Standard}:
9403 Fortran 95 and later
9408 @item @emph{Syntax}:
9409 @code{RESULT = RRSPACING(X)}
9411 @item @emph{Arguments}:
9412 @multitable @columnfractions .15 .70
9413 @item @var{X} @tab Shall be of type @code{REAL}.
9416 @item @emph{Return value}:
9417 The return value is of the same type and kind as @var{X}.
9418 The value returned is equal to
9419 @code{ABS(FRACTION(X)) * FLOAT(RADIX(X))**DIGITS(X)}.
9421 @item @emph{See also}:
9428 @section @code{RSHIFT} --- Right shift bits
9430 @cindex bits, shift right
9433 @item @emph{Description}:
9434 @code{RSHIFT} returns a value corresponding to @var{I} with all of the
9435 bits shifted right by @var{SHIFT} places. If the absolute value of
9436 @var{SHIFT} is greater than @code{BIT_SIZE(I)}, the value is undefined.
9437 Bits shifted out from the left end are lost; zeros are shifted in from
9440 This function has been superseded by the @code{ISHFT} intrinsic, which
9441 is standard in Fortran 95 and later.
9443 @item @emph{Standard}:
9449 @item @emph{Syntax}:
9450 @code{RESULT = RSHIFT(I, SHIFT)}
9452 @item @emph{Arguments}:
9453 @multitable @columnfractions .15 .70
9454 @item @var{I} @tab The type shall be @code{INTEGER}.
9455 @item @var{SHIFT} @tab The type shall be @code{INTEGER}.
9458 @item @emph{Return value}:
9459 The return value is of type @code{INTEGER} and of the same kind as
9462 @item @emph{See also}:
9463 @ref{ISHFT}, @ref{ISHFTC}, @ref{LSHIFT}
9470 @section @code{SAME_TYPE_AS} --- Query dynamic types for equality
9471 @fnindex SAME_TYPE_AS
9474 @item @emph{Description}:
9475 Query dynamic types for equality.
9477 @item @emph{Standard}:
9478 Fortran 2003 and later
9483 @item @emph{Syntax}:
9484 @code{RESULT = SAME_TYPE_AS(A, B)}
9486 @item @emph{Arguments}:
9487 @multitable @columnfractions .15 .70
9488 @item @var{A} @tab Shall be an object of extensible declared type or
9489 unlimited polymorphic.
9490 @item @var{B} @tab Shall be an object of extensible declared type or
9491 unlimited polymorphic.
9494 @item @emph{Return value}:
9495 The return value is a scalar of type default logical. It is true if and
9496 only if the dynamic type of A is the same as the dynamic type of B.
9498 @item @emph{See also}:
9499 @ref{EXTENDS_TYPE_OF}
9506 @section @code{SCALE} --- Scale a real value
9508 @cindex real number, scale
9509 @cindex floating point, scale
9512 @item @emph{Description}:
9513 @code{SCALE(X,I)} returns @code{X * RADIX(X)**I}.
9515 @item @emph{Standard}:
9516 Fortran 95 and later
9521 @item @emph{Syntax}:
9522 @code{RESULT = SCALE(X, I)}
9524 @item @emph{Arguments}:
9525 @multitable @columnfractions .15 .70
9526 @item @var{X} @tab The type of the argument shall be a @code{REAL}.
9527 @item @var{I} @tab The type of the argument shall be a @code{INTEGER}.
9530 @item @emph{Return value}:
9531 The return value is of the same type and kind as @var{X}.
9532 Its value is @code{X * RADIX(X)**I}.
9534 @item @emph{Example}:
9537 real :: x = 178.1387e-4
9539 print *, scale(x,i), x*radix(x)**i
9540 end program test_scale
9548 @section @code{SCAN} --- Scan a string for the presence of a set of characters
9550 @cindex string, find subset
9553 @item @emph{Description}:
9554 Scans a @var{STRING} for any of the characters in a @var{SET}
9557 If @var{BACK} is either absent or equals @code{FALSE}, this function
9558 returns the position of the leftmost character of @var{STRING} that is
9559 in @var{SET}. If @var{BACK} equals @code{TRUE}, the rightmost position
9560 is returned. If no character of @var{SET} is found in @var{STRING}, the
9563 @item @emph{Standard}:
9564 Fortran 95 and later, with @var{KIND} argument Fortran 2003 and later
9569 @item @emph{Syntax}:
9570 @code{RESULT = SCAN(STRING, SET[, BACK [, KIND]])}
9572 @item @emph{Arguments}:
9573 @multitable @columnfractions .15 .70
9574 @item @var{STRING} @tab Shall be of type @code{CHARACTER}.
9575 @item @var{SET} @tab Shall be of type @code{CHARACTER}.
9576 @item @var{BACK} @tab (Optional) shall be of type @code{LOGICAL}.
9577 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
9578 expression indicating the kind parameter of the result.
9581 @item @emph{Return value}:
9582 The return value is of type @code{INTEGER} and of kind @var{KIND}. If
9583 @var{KIND} is absent, the return value is of default integer kind.
9585 @item @emph{Example}:
9588 WRITE(*,*) SCAN("FORTRAN", "AO") ! 2, found 'O'
9589 WRITE(*,*) SCAN("FORTRAN", "AO", .TRUE.) ! 6, found 'A'
9590 WRITE(*,*) SCAN("FORTRAN", "C++") ! 0, found none
9594 @item @emph{See also}:
9595 @ref{INDEX intrinsic}, @ref{VERIFY}
9601 @section @code{SECNDS} --- Time function
9603 @cindex time, elapsed
9604 @cindex elapsed time
9607 @item @emph{Description}:
9608 @code{SECNDS(X)} gets the time in seconds from the real-time system clock.
9609 @var{X} is a reference time, also in seconds. If this is zero, the time in
9610 seconds from midnight is returned. This function is non-standard and its
9613 @item @emph{Standard}:
9619 @item @emph{Syntax}:
9620 @code{RESULT = SECNDS (X)}
9622 @item @emph{Arguments}:
9623 @multitable @columnfractions .15 .70
9624 @item @var{T} @tab Shall be of type @code{REAL(4)}.
9625 @item @var{X} @tab Shall be of type @code{REAL(4)}.
9628 @item @emph{Return value}:
9631 @item @emph{Example}:
9636 print *, secnds (0.0) ! seconds since midnight
9637 t1 = secnds (0.0) ! reference time
9638 do i = 1, 10000000 ! do something
9640 t2 = secnds (t1) ! elapsed time
9641 print *, "Something took ", t2, " seconds."
9642 end program test_secnds
9649 @section @code{SECOND} --- CPU time function
9651 @cindex time, elapsed
9652 @cindex elapsed time
9655 @item @emph{Description}:
9656 Returns a @code{REAL(4)} value representing the elapsed CPU time in
9657 seconds. This provides the same functionality as the standard
9658 @code{CPU_TIME} intrinsic, and is only included for backwards
9661 This intrinsic is provided in both subroutine and function forms;
9662 however, only one form can be used in any given program unit.
9664 @item @emph{Standard}:
9668 Subroutine, function
9670 @item @emph{Syntax}:
9671 @multitable @columnfractions .80
9672 @item @code{CALL SECOND(TIME)}
9673 @item @code{TIME = SECOND()}
9676 @item @emph{Arguments}:
9677 @multitable @columnfractions .15 .70
9678 @item @var{TIME} @tab Shall be of type @code{REAL(4)}.
9681 @item @emph{Return value}:
9682 In either syntax, @var{TIME} is set to the process's current runtime in
9685 @item @emph{See also}:
9692 @node SELECTED_CHAR_KIND
9693 @section @code{SELECTED_CHAR_KIND} --- Choose character kind
9694 @fnindex SELECTED_CHAR_KIND
9695 @cindex character kind
9696 @cindex kind, character
9699 @item @emph{Description}:
9701 @code{SELECTED_CHAR_KIND(NAME)} returns the kind value for the character
9702 set named @var{NAME}, if a character set with such a name is supported,
9703 or @math{-1} otherwise. Currently, supported character sets include
9704 ``ASCII'' and ``DEFAULT'', which are equivalent, and ``ISO_10646''
9705 (Universal Character Set, UCS-4) which is commonly known as Unicode.
9707 @item @emph{Standard}:
9708 Fortran 2003 and later
9711 Transformational function
9713 @item @emph{Syntax}:
9714 @code{RESULT = SELECTED_CHAR_KIND(NAME)}
9716 @item @emph{Arguments}:
9717 @multitable @columnfractions .15 .70
9718 @item @var{NAME} @tab Shall be a scalar and of the default character type.
9721 @item @emph{Example}:
9723 program character_kind
9726 integer, parameter :: ascii = selected_char_kind ("ascii")
9727 integer, parameter :: ucs4 = selected_char_kind ('ISO_10646')
9729 character(kind=ascii, len=26) :: alphabet
9730 character(kind=ucs4, len=30) :: hello_world
9732 alphabet = ascii_"abcdefghijklmnopqrstuvwxyz"
9733 hello_world = ucs4_'Hello World and Ni Hao -- ' &
9734 // char (int (z'4F60'), ucs4) &
9735 // char (int (z'597D'), ucs4)
9737 write (*,*) alphabet
9739 open (output_unit, encoding='UTF-8')
9740 write (*,*) trim (hello_world)
9741 end program character_kind
9747 @node SELECTED_INT_KIND
9748 @section @code{SELECTED_INT_KIND} --- Choose integer kind
9749 @fnindex SELECTED_INT_KIND
9750 @cindex integer kind
9751 @cindex kind, integer
9754 @item @emph{Description}:
9755 @code{SELECTED_INT_KIND(R)} return the kind value of the smallest integer
9756 type that can represent all values ranging from @math{-10^R} (exclusive)
9757 to @math{10^R} (exclusive). If there is no integer kind that accommodates
9758 this range, @code{SELECTED_INT_KIND} returns @math{-1}.
9760 @item @emph{Standard}:
9761 Fortran 95 and later
9764 Transformational function
9766 @item @emph{Syntax}:
9767 @code{RESULT = SELECTED_INT_KIND(R)}
9769 @item @emph{Arguments}:
9770 @multitable @columnfractions .15 .70
9771 @item @var{R} @tab Shall be a scalar and of type @code{INTEGER}.
9774 @item @emph{Example}:
9776 program large_integers
9777 integer,parameter :: k5 = selected_int_kind(5)
9778 integer,parameter :: k15 = selected_int_kind(15)
9779 integer(kind=k5) :: i5
9780 integer(kind=k15) :: i15
9782 print *, huge(i5), huge(i15)
9784 ! The following inequalities are always true
9785 print *, huge(i5) >= 10_k5**5-1
9786 print *, huge(i15) >= 10_k15**15-1
9787 end program large_integers
9793 @node SELECTED_REAL_KIND
9794 @section @code{SELECTED_REAL_KIND} --- Choose real kind
9795 @fnindex SELECTED_REAL_KIND
9801 @item @emph{Description}:
9802 @code{SELECTED_REAL_KIND(P,R)} returns the kind value of a real data type
9803 with decimal precision of at least @code{P} digits, exponent range of
9804 at least @code{R}, and with a radix of @code{RADIX}.
9806 @item @emph{Standard}:
9807 Fortran 95 and later, with @code{RADIX} Fortran 2008 or later
9810 Transformational function
9812 @item @emph{Syntax}:
9813 @code{RESULT = SELECTED_REAL_KIND([P, R, RADIX])}
9815 @item @emph{Arguments}:
9816 @multitable @columnfractions .15 .70
9817 @item @var{P} @tab (Optional) shall be a scalar and of type @code{INTEGER}.
9818 @item @var{R} @tab (Optional) shall be a scalar and of type @code{INTEGER}.
9819 @item @var{RADIX} @tab (Optional) shall be a scalar and of type @code{INTEGER}.
9821 Before Fortran 2008, at least one of the arguments @var{R} or @var{P} shall
9822 be present; since Fortran 2008, they are assumed to be zero if absent.
9824 @item @emph{Return value}:
9826 @code{SELECTED_REAL_KIND} returns the value of the kind type parameter of
9827 a real data type with decimal precision of at least @code{P} digits, a
9828 decimal exponent range of at least @code{R}, and with the requested
9829 @code{RADIX}. If the @code{RADIX} parameter is absent, real kinds with
9830 any radix can be returned. If more than one real data type meet the
9831 criteria, the kind of the data type with the smallest decimal precision
9832 is returned. If no real data type matches the criteria, the result is
9834 @item -1 if the processor does not support a real data type with a
9835 precision greater than or equal to @code{P}, but the @code{R} and
9836 @code{RADIX} requirements can be fulfilled
9837 @item -2 if the processor does not support a real type with an exponent
9838 range greater than or equal to @code{R}, but @code{P} and @code{RADIX}
9840 @item -3 if @code{RADIX} but not @code{P} and @code{R} requirements
9842 @item -4 if @code{RADIX} and either @code{P} or @code{R} requirements
9844 @item -5 if there is no real type with the given @code{RADIX}
9847 @item @emph{See also}:
9848 @ref{PRECISION}, @ref{RANGE}, @ref{RADIX}
9850 @item @emph{Example}:
9853 integer,parameter :: p6 = selected_real_kind(6)
9854 integer,parameter :: p10r100 = selected_real_kind(10,100)
9855 integer,parameter :: r400 = selected_real_kind(r=400)
9857 real(kind=p10r100) :: y
9858 real(kind=r400) :: z
9860 print *, precision(x), range(x)
9861 print *, precision(y), range(y)
9862 print *, precision(z), range(z)
9863 end program real_kinds
9870 @section @code{SET_EXPONENT} --- Set the exponent of the model
9871 @fnindex SET_EXPONENT
9872 @cindex real number, set exponent
9873 @cindex floating point, set exponent
9876 @item @emph{Description}:
9877 @code{SET_EXPONENT(X, I)} returns the real number whose fractional part
9878 is that that of @var{X} and whose exponent part is @var{I}.
9880 @item @emph{Standard}:
9881 Fortran 95 and later
9886 @item @emph{Syntax}:
9887 @code{RESULT = SET_EXPONENT(X, I)}
9889 @item @emph{Arguments}:
9890 @multitable @columnfractions .15 .70
9891 @item @var{X} @tab Shall be of type @code{REAL}.
9892 @item @var{I} @tab Shall be of type @code{INTEGER}.
9895 @item @emph{Return value}:
9896 The return value is of the same type and kind as @var{X}.
9897 The real number whose fractional part
9898 is that that of @var{X} and whose exponent part if @var{I} is returned;
9899 it is @code{FRACTION(X) * RADIX(X)**I}.
9901 @item @emph{Example}:
9904 REAL :: x = 178.1387e-4
9906 PRINT *, SET_EXPONENT(x, i), FRACTION(x) * RADIX(x)**i
9915 @section @code{SHAPE} --- Determine the shape of an array
9917 @cindex array, shape
9920 @item @emph{Description}:
9921 Determines the shape of an array.
9923 @item @emph{Standard}:
9924 Fortran 95 and later
9929 @item @emph{Syntax}:
9930 @code{RESULT = SHAPE(SOURCE)}
9932 @item @emph{Arguments}:
9933 @multitable @columnfractions .15 .70
9934 @item @var{SOURCE} @tab Shall be an array or scalar of any type.
9935 If @var{SOURCE} is a pointer it must be associated and allocatable
9936 arrays must be allocated.
9939 @item @emph{Return value}:
9940 An @code{INTEGER} array of rank one with as many elements as @var{SOURCE}
9941 has dimensions. The elements of the resulting array correspond to the extend
9942 of @var{SOURCE} along the respective dimensions. If @var{SOURCE} is a scalar,
9943 the result is the rank one array of size zero.
9945 @item @emph{Example}:
9948 INTEGER, DIMENSION(-1:1, -1:2) :: A
9949 WRITE(*,*) SHAPE(A) ! (/ 3, 4 /)
9950 WRITE(*,*) SIZE(SHAPE(42)) ! (/ /)
9954 @item @emph{See also}:
9955 @ref{RESHAPE}, @ref{SIZE}
9961 @section @code{SIGN} --- Sign copying function
9965 @cindex sign copying
9968 @item @emph{Description}:
9969 @code{SIGN(A,B)} returns the value of @var{A} with the sign of @var{B}.
9971 @item @emph{Standard}:
9972 Fortran 77 and later
9977 @item @emph{Syntax}:
9978 @code{RESULT = SIGN(A, B)}
9980 @item @emph{Arguments}:
9981 @multitable @columnfractions .15 .70
9982 @item @var{A} @tab Shall be of type @code{INTEGER} or @code{REAL}
9983 @item @var{B} @tab Shall be of the same type and kind as @var{A}
9986 @item @emph{Return value}:
9987 The kind of the return value is that of @var{A} and @var{B}.
9988 If @math{B\ge 0} then the result is @code{ABS(A)}, else
9989 it is @code{-ABS(A)}.
9991 @item @emph{Example}:
9994 print *, sign(-12,1)
9995 print *, sign(-12,0)
9996 print *, sign(-12,-1)
9998 print *, sign(-12.,1.)
9999 print *, sign(-12.,0.)
10000 print *, sign(-12.,-1.)
10001 end program test_sign
10004 @item @emph{Specific names}:
10005 @multitable @columnfractions .20 .20 .20 .25
10006 @item Name @tab Arguments @tab Return type @tab Standard
10007 @item @code{SIGN(A,B)} @tab @code{REAL(4) A, B} @tab @code{REAL(4)} @tab f77, gnu
10008 @item @code{ISIGN(A,B)} @tab @code{INTEGER(4) A, B} @tab @code{INTEGER(4)} @tab f77, gnu
10009 @item @code{DSIGN(A,B)} @tab @code{REAL(8) A, B} @tab @code{REAL(8)} @tab f77, gnu
10016 @section @code{SIGNAL} --- Signal handling subroutine (or function)
10018 @cindex system, signal handling
10021 @item @emph{Description}:
10022 @code{SIGNAL(NUMBER, HANDLER [, STATUS])} causes external subroutine
10023 @var{HANDLER} to be executed with a single integer argument when signal
10024 @var{NUMBER} occurs. If @var{HANDLER} is an integer, it can be used to
10025 turn off handling of signal @var{NUMBER} or revert to its default
10026 action. See @code{signal(2)}.
10028 If @code{SIGNAL} is called as a subroutine and the @var{STATUS} argument
10029 is supplied, it is set to the value returned by @code{signal(2)}.
10031 @item @emph{Standard}:
10034 @item @emph{Class}:
10035 Subroutine, function
10037 @item @emph{Syntax}:
10038 @multitable @columnfractions .80
10039 @item @code{CALL SIGNAL(NUMBER, HANDLER [, STATUS])}
10040 @item @code{STATUS = SIGNAL(NUMBER, HANDLER)}
10043 @item @emph{Arguments}:
10044 @multitable @columnfractions .15 .70
10045 @item @var{NUMBER} @tab Shall be a scalar integer, with @code{INTENT(IN)}
10046 @item @var{HANDLER}@tab Signal handler (@code{INTEGER FUNCTION} or
10047 @code{SUBROUTINE}) or dummy/global @code{INTEGER} scalar.
10048 @code{INTEGER}. It is @code{INTENT(IN)}.
10049 @item @var{STATUS} @tab (Optional) @var{STATUS} shall be a scalar
10050 integer. It has @code{INTENT(OUT)}.
10052 @c TODO: What should the interface of the handler be? Does it take arguments?
10054 @item @emph{Return value}:
10055 The @code{SIGNAL} function returns the value returned by @code{signal(2)}.
10057 @item @emph{Example}:
10059 program test_signal
10061 external handler_print
10063 call signal (12, handler_print)
10064 call signal (10, 1)
10067 end program test_signal
10074 @section @code{SIN} --- Sine function
10080 @cindex trigonometric function, sine
10084 @item @emph{Description}:
10085 @code{SIN(X)} computes the sine of @var{X}.
10087 @item @emph{Standard}:
10088 Fortran 77 and later
10090 @item @emph{Class}:
10093 @item @emph{Syntax}:
10094 @code{RESULT = SIN(X)}
10096 @item @emph{Arguments}:
10097 @multitable @columnfractions .15 .70
10098 @item @var{X} @tab The type shall be @code{REAL} or
10102 @item @emph{Return value}:
10103 The return value has same type and kind as @var{X}.
10105 @item @emph{Example}:
10110 end program test_sin
10113 @item @emph{Specific names}:
10114 @multitable @columnfractions .20 .20 .20 .25
10115 @item Name @tab Argument @tab Return type @tab Standard
10116 @item @code{SIN(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab f77, gnu
10117 @item @code{DSIN(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab f95, gnu
10118 @item @code{CSIN(X)} @tab @code{COMPLEX(4) X} @tab @code{COMPLEX(4)} @tab f95, gnu
10119 @item @code{ZSIN(X)} @tab @code{COMPLEX(8) X} @tab @code{COMPLEX(8)} @tab f95, gnu
10120 @item @code{CDSIN(X)} @tab @code{COMPLEX(8) X} @tab @code{COMPLEX(8)} @tab f95, gnu
10123 @item @emph{See also}:
10130 @section @code{SINH} --- Hyperbolic sine function
10133 @cindex hyperbolic sine
10134 @cindex hyperbolic function, sine
10135 @cindex sine, hyperbolic
10138 @item @emph{Description}:
10139 @code{SINH(X)} computes the hyperbolic sine of @var{X}.
10141 @item @emph{Standard}:
10142 Fortran 95 and later, for a complex argument Fortran 2008 or later
10144 @item @emph{Class}:
10147 @item @emph{Syntax}:
10148 @code{RESULT = SINH(X)}
10150 @item @emph{Arguments}:
10151 @multitable @columnfractions .15 .70
10152 @item @var{X} @tab The type shall be @code{REAL} or @code{COMPLEX}.
10155 @item @emph{Return value}:
10156 The return value has same type and kind as @var{X}.
10158 @item @emph{Example}:
10161 real(8) :: x = - 1.0_8
10163 end program test_sinh
10166 @item @emph{Specific names}:
10167 @multitable @columnfractions .20 .20 .20 .25
10168 @item Name @tab Argument @tab Return type @tab Standard
10169 @item @code{SINH(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab Fortran 95 and later
10170 @item @code{DSINH(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab Fortran 95 and later
10173 @item @emph{See also}:
10180 @section @code{SIZE} --- Determine the size of an array
10182 @cindex array, size
10183 @cindex array, number of elements
10184 @cindex array, count elements
10187 @item @emph{Description}:
10188 Determine the extent of @var{ARRAY} along a specified dimension @var{DIM},
10189 or the total number of elements in @var{ARRAY} if @var{DIM} is absent.
10191 @item @emph{Standard}:
10192 Fortran 95 and later, with @var{KIND} argument Fortran 2003 and later
10194 @item @emph{Class}:
10197 @item @emph{Syntax}:
10198 @code{RESULT = SIZE(ARRAY[, DIM [, KIND]])}
10200 @item @emph{Arguments}:
10201 @multitable @columnfractions .15 .70
10202 @item @var{ARRAY} @tab Shall be an array of any type. If @var{ARRAY} is
10203 a pointer it must be associated and allocatable arrays must be allocated.
10204 @item @var{DIM} @tab (Optional) shall be a scalar of type @code{INTEGER}
10205 and its value shall be in the range from 1 to n, where n equals the rank
10207 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
10208 expression indicating the kind parameter of the result.
10211 @item @emph{Return value}:
10212 The return value is of type @code{INTEGER} and of kind @var{KIND}. If
10213 @var{KIND} is absent, the return value is of default integer kind.
10215 @item @emph{Example}:
10218 WRITE(*,*) SIZE((/ 1, 2 /)) ! 2
10222 @item @emph{See also}:
10223 @ref{SHAPE}, @ref{RESHAPE}
10228 @section @code{SIZEOF} --- Size in bytes of an expression
10230 @cindex expression size
10231 @cindex size of an expression
10234 @item @emph{Description}:
10235 @code{SIZEOF(X)} calculates the number of bytes of storage the
10236 expression @code{X} occupies.
10238 @item @emph{Standard}:
10241 @item @emph{Class}:
10244 @item @emph{Syntax}:
10245 @code{N = SIZEOF(X)}
10247 @item @emph{Arguments}:
10248 @multitable @columnfractions .15 .70
10249 @item @var{X} @tab The argument shall be of any type, rank or shape.
10252 @item @emph{Return value}:
10253 The return value is of type integer and of the system-dependent kind
10254 @var{C_SIZE_T} (from the @var{ISO_C_BINDING} module). Its value is the
10255 number of bytes occupied by the argument. If the argument has the
10256 @code{POINTER} attribute, the number of bytes of the storage area pointed
10257 to is returned. If the argument is of a derived type with @code{POINTER}
10258 or @code{ALLOCATABLE} components, the return value doesn't account for
10259 the sizes of the data pointed to by these components. If the argument is
10260 polymorphic, the size according to the declared type is returned.
10262 @item @emph{Example}:
10266 print *, (sizeof(s)/sizeof(r) == 5)
10269 The example will print @code{.TRUE.} unless you are using a platform
10270 where default @code{REAL} variables are unusually padded.
10272 @item @emph{See also}:
10273 @ref{C_SIZEOF}, @ref{STORAGE_SIZE}
10278 @section @code{SLEEP} --- Sleep for the specified number of seconds
10280 @cindex delayed execution
10283 @item @emph{Description}:
10284 Calling this subroutine causes the process to pause for @var{SECONDS} seconds.
10286 @item @emph{Standard}:
10289 @item @emph{Class}:
10292 @item @emph{Syntax}:
10293 @code{CALL SLEEP(SECONDS)}
10295 @item @emph{Arguments}:
10296 @multitable @columnfractions .15 .70
10297 @item @var{SECONDS} @tab The type shall be of default @code{INTEGER}.
10300 @item @emph{Example}:
10311 @section @code{SPACING} --- Smallest distance between two numbers of a given type
10313 @cindex real number, relative spacing
10314 @cindex floating point, relative spacing
10317 @item @emph{Description}:
10318 Determines the distance between the argument @var{X} and the nearest
10319 adjacent number of the same type.
10321 @item @emph{Standard}:
10322 Fortran 95 and later
10324 @item @emph{Class}:
10327 @item @emph{Syntax}:
10328 @code{RESULT = SPACING(X)}
10330 @item @emph{Arguments}:
10331 @multitable @columnfractions .15 .70
10332 @item @var{X} @tab Shall be of type @code{REAL}.
10335 @item @emph{Return value}:
10336 The result is of the same type as the input argument @var{X}.
10338 @item @emph{Example}:
10340 PROGRAM test_spacing
10341 INTEGER, PARAMETER :: SGL = SELECTED_REAL_KIND(p=6, r=37)
10342 INTEGER, PARAMETER :: DBL = SELECTED_REAL_KIND(p=13, r=200)
10344 WRITE(*,*) spacing(1.0_SGL) ! "1.1920929E-07" on i686
10345 WRITE(*,*) spacing(1.0_DBL) ! "2.220446049250313E-016" on i686
10349 @item @emph{See also}:
10356 @section @code{SPREAD} --- Add a dimension to an array
10358 @cindex array, increase dimension
10359 @cindex array, duplicate elements
10360 @cindex array, duplicate dimensions
10363 @item @emph{Description}:
10364 Replicates a @var{SOURCE} array @var{NCOPIES} times along a specified
10365 dimension @var{DIM}.
10367 @item @emph{Standard}:
10368 Fortran 95 and later
10370 @item @emph{Class}:
10371 Transformational function
10373 @item @emph{Syntax}:
10374 @code{RESULT = SPREAD(SOURCE, DIM, NCOPIES)}
10376 @item @emph{Arguments}:
10377 @multitable @columnfractions .15 .70
10378 @item @var{SOURCE} @tab Shall be a scalar or an array of any type and
10379 a rank less than seven.
10380 @item @var{DIM} @tab Shall be a scalar of type @code{INTEGER} with a
10381 value in the range from 1 to n+1, where n equals the rank of @var{SOURCE}.
10382 @item @var{NCOPIES} @tab Shall be a scalar of type @code{INTEGER}.
10385 @item @emph{Return value}:
10386 The result is an array of the same type as @var{SOURCE} and has rank n+1
10387 where n equals the rank of @var{SOURCE}.
10389 @item @emph{Example}:
10391 PROGRAM test_spread
10392 INTEGER :: a = 1, b(2) = (/ 1, 2 /)
10393 WRITE(*,*) SPREAD(A, 1, 2) ! "1 1"
10394 WRITE(*,*) SPREAD(B, 1, 2) ! "1 1 2 2"
10398 @item @emph{See also}:
10405 @section @code{SQRT} --- Square-root function
10412 @cindex square-root
10415 @item @emph{Description}:
10416 @code{SQRT(X)} computes the square root of @var{X}.
10418 @item @emph{Standard}:
10419 Fortran 77 and later
10421 @item @emph{Class}:
10424 @item @emph{Syntax}:
10425 @code{RESULT = SQRT(X)}
10427 @item @emph{Arguments}:
10428 @multitable @columnfractions .15 .70
10429 @item @var{X} @tab The type shall be @code{REAL} or
10433 @item @emph{Return value}:
10434 The return value is of type @code{REAL} or @code{COMPLEX}.
10435 The kind type parameter is the same as @var{X}.
10437 @item @emph{Example}:
10440 real(8) :: x = 2.0_8
10441 complex :: z = (1.0, 2.0)
10444 end program test_sqrt
10447 @item @emph{Specific names}:
10448 @multitable @columnfractions .20 .20 .20 .25
10449 @item Name @tab Argument @tab Return type @tab Standard
10450 @item @code{SQRT(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab Fortran 95 and later
10451 @item @code{DSQRT(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab Fortran 95 and later
10452 @item @code{CSQRT(X)} @tab @code{COMPLEX(4) X} @tab @code{COMPLEX(4)} @tab Fortran 95 and later
10453 @item @code{ZSQRT(X)} @tab @code{COMPLEX(8) X} @tab @code{COMPLEX(8)} @tab GNU extension
10454 @item @code{CDSQRT(X)} @tab @code{COMPLEX(8) X} @tab @code{COMPLEX(8)} @tab GNU extension
10461 @section @code{SRAND} --- Reinitialize the random number generator
10463 @cindex random number generation, seeding
10464 @cindex seeding a random number generator
10467 @item @emph{Description}:
10468 @code{SRAND} reinitializes the pseudo-random number generator
10469 called by @code{RAND} and @code{IRAND}. The new seed used by the
10470 generator is specified by the required argument @var{SEED}.
10472 @item @emph{Standard}:
10475 @item @emph{Class}:
10478 @item @emph{Syntax}:
10479 @code{CALL SRAND(SEED)}
10481 @item @emph{Arguments}:
10482 @multitable @columnfractions .15 .70
10483 @item @var{SEED} @tab Shall be a scalar @code{INTEGER(kind=4)}.
10486 @item @emph{Return value}:
10487 Does not return anything.
10489 @item @emph{Example}:
10490 See @code{RAND} and @code{IRAND} for examples.
10492 @item @emph{Notes}:
10493 The Fortran 2003 standard specifies the intrinsic @code{RANDOM_SEED} to
10494 initialize the pseudo-random numbers generator and @code{RANDOM_NUMBER}
10495 to generate pseudo-random numbers. Please note that in
10496 GNU Fortran, these two sets of intrinsics (@code{RAND},
10497 @code{IRAND} and @code{SRAND} on the one hand, @code{RANDOM_NUMBER} and
10498 @code{RANDOM_SEED} on the other hand) access two independent
10499 pseudo-random number generators.
10501 @item @emph{See also}:
10502 @ref{RAND}, @ref{RANDOM_SEED}, @ref{RANDOM_NUMBER}
10509 @section @code{STAT} --- Get file status
10511 @cindex file system, file status
10514 @item @emph{Description}:
10515 This function returns information about a file. No permissions are required on
10516 the file itself, but execute (search) permission is required on all of the
10517 directories in path that lead to the file.
10519 The elements that are obtained and stored in the array @code{VALUES}:
10520 @multitable @columnfractions .15 .70
10521 @item @code{VALUES(1)} @tab Device ID
10522 @item @code{VALUES(2)} @tab Inode number
10523 @item @code{VALUES(3)} @tab File mode
10524 @item @code{VALUES(4)} @tab Number of links
10525 @item @code{VALUES(5)} @tab Owner's uid
10526 @item @code{VALUES(6)} @tab Owner's gid
10527 @item @code{VALUES(7)} @tab ID of device containing directory entry for file (0 if not available)
10528 @item @code{VALUES(8)} @tab File size (bytes)
10529 @item @code{VALUES(9)} @tab Last access time
10530 @item @code{VALUES(10)} @tab Last modification time
10531 @item @code{VALUES(11)} @tab Last file status change time
10532 @item @code{VALUES(12)} @tab Preferred I/O block size (-1 if not available)
10533 @item @code{VALUES(13)} @tab Number of blocks allocated (-1 if not available)
10536 Not all these elements are relevant on all systems.
10537 If an element is not relevant, it is returned as 0.
10539 This intrinsic is provided in both subroutine and function forms; however,
10540 only one form can be used in any given program unit.
10542 @item @emph{Standard}:
10545 @item @emph{Class}:
10546 Subroutine, function
10548 @item @emph{Syntax}:
10549 @code{CALL STAT(NAME, VALUES [, STATUS])}
10551 @item @emph{Arguments}:
10552 @multitable @columnfractions .15 .70
10553 @item @var{NAME} @tab The type shall be @code{CHARACTER}, of the
10554 default kind and a valid path within the file system.
10555 @item @var{VALUES} @tab The type shall be @code{INTEGER(4), DIMENSION(13)}.
10556 @item @var{STATUS} @tab (Optional) status flag of type @code{INTEGER(4)}. Returns 0
10557 on success and a system specific error code otherwise.
10560 @item @emph{Example}:
10563 INTEGER, DIMENSION(13) :: buff
10566 CALL STAT("/etc/passwd", buff, status)
10568 IF (status == 0) THEN
10569 WRITE (*, FMT="('Device ID:', T30, I19)") buff(1)
10570 WRITE (*, FMT="('Inode number:', T30, I19)") buff(2)
10571 WRITE (*, FMT="('File mode (octal):', T30, O19)") buff(3)
10572 WRITE (*, FMT="('Number of links:', T30, I19)") buff(4)
10573 WRITE (*, FMT="('Owner''s uid:', T30, I19)") buff(5)
10574 WRITE (*, FMT="('Owner''s gid:', T30, I19)") buff(6)
10575 WRITE (*, FMT="('Device where located:', T30, I19)") buff(7)
10576 WRITE (*, FMT="('File size:', T30, I19)") buff(8)
10577 WRITE (*, FMT="('Last access time:', T30, A19)") CTIME(buff(9))
10578 WRITE (*, FMT="('Last modification time', T30, A19)") CTIME(buff(10))
10579 WRITE (*, FMT="('Last status change time:', T30, A19)") CTIME(buff(11))
10580 WRITE (*, FMT="('Preferred block size:', T30, I19)") buff(12)
10581 WRITE (*, FMT="('No. of blocks allocated:', T30, I19)") buff(13)
10586 @item @emph{See also}:
10587 To stat an open file: @ref{FSTAT}, to stat a link: @ref{LSTAT}
10593 @section @code{STORAGE_SIZE} --- Storage size in bits
10594 @fnindex STORAGE_SIZE
10595 @cindex storage size
10598 @item @emph{Description}:
10599 Returns the storage size of argument @var{A} in bits.
10600 @item @emph{Standard}:
10601 Fortran 2008 and later
10602 @item @emph{Class}:
10604 @item @emph{Syntax}:
10605 @code{RESULT = STORAGE_SIZE(A [, KIND])}
10607 @item @emph{Arguments}:
10608 @multitable @columnfractions .15 .70
10609 @item @var{A} @tab Shall be a scalar or array of any type.
10610 @item @var{KIND} @tab (Optional) shall be a scalar integer constant expression.
10613 @item @emph{Return Value}:
10614 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
10615 has the dynamic type and type parameters of A.
10617 @item @emph{See also}:
10618 @ref{C_SIZEOF}, @ref{SIZEOF}
10624 @section @code{SUM} --- Sum of array elements
10627 @cindex array, add elements
10628 @cindex array, conditionally add elements
10629 @cindex sum array elements
10632 @item @emph{Description}:
10633 Adds the elements of @var{ARRAY} along dimension @var{DIM} if
10634 the corresponding element in @var{MASK} is @code{TRUE}.
10636 @item @emph{Standard}:
10637 Fortran 95 and later
10639 @item @emph{Class}:
10640 Transformational function
10642 @item @emph{Syntax}:
10643 @multitable @columnfractions .80
10644 @item @code{RESULT = SUM(ARRAY[, MASK])}
10645 @item @code{RESULT = SUM(ARRAY, DIM[, MASK])}
10648 @item @emph{Arguments}:
10649 @multitable @columnfractions .15 .70
10650 @item @var{ARRAY} @tab Shall be an array of type @code{INTEGER},
10651 @code{REAL} or @code{COMPLEX}.
10652 @item @var{DIM} @tab (Optional) shall be a scalar of type
10653 @code{INTEGER} with a value in the range from 1 to n, where n
10654 equals the rank of @var{ARRAY}.
10655 @item @var{MASK} @tab (Optional) shall be of type @code{LOGICAL}
10656 and either be a scalar or an array of the same shape as @var{ARRAY}.
10659 @item @emph{Return value}:
10660 The result is of the same type as @var{ARRAY}.
10662 If @var{DIM} is absent, a scalar with the sum of all elements in @var{ARRAY}
10663 is returned. Otherwise, an array of rank n-1, where n equals the rank of
10664 @var{ARRAY}, and a shape similar to that of @var{ARRAY} with dimension @var{DIM}
10665 dropped is returned.
10667 @item @emph{Example}:
10670 INTEGER :: x(5) = (/ 1, 2, 3, 4 ,5 /)
10671 print *, SUM(x) ! all elements, sum = 15
10672 print *, SUM(x, MASK=MOD(x, 2)==1) ! odd elements, sum = 9
10676 @item @emph{See also}:
10683 @section @code{SYMLNK} --- Create a symbolic link
10685 @cindex file system, create link
10686 @cindex file system, soft link
10689 @item @emph{Description}:
10690 Makes a symbolic link from file @var{PATH1} to @var{PATH2}. A null
10691 character (@code{CHAR(0)}) can be used to mark the end of the names in
10692 @var{PATH1} and @var{PATH2}; otherwise, trailing blanks in the file
10693 names are ignored. If the @var{STATUS} argument is supplied, it
10694 contains 0 on success or a nonzero error code upon return; see
10695 @code{symlink(2)}. If the system does not supply @code{symlink(2)},
10696 @code{ENOSYS} is returned.
10698 This intrinsic is provided in both subroutine and function forms;
10699 however, only one form can be used in any given program unit.
10701 @item @emph{Standard}:
10704 @item @emph{Class}:
10705 Subroutine, function
10707 @item @emph{Syntax}:
10708 @multitable @columnfractions .80
10709 @item @code{CALL SYMLNK(PATH1, PATH2 [, STATUS])}
10710 @item @code{STATUS = SYMLNK(PATH1, PATH2)}
10713 @item @emph{Arguments}:
10714 @multitable @columnfractions .15 .70
10715 @item @var{PATH1} @tab Shall be of default @code{CHARACTER} type.
10716 @item @var{PATH2} @tab Shall be of default @code{CHARACTER} type.
10717 @item @var{STATUS} @tab (Optional) Shall be of default @code{INTEGER} type.
10720 @item @emph{See also}:
10721 @ref{LINK}, @ref{UNLINK}
10728 @section @code{SYSTEM} --- Execute a shell command
10730 @cindex system, system call
10733 @item @emph{Description}:
10734 Passes the command @var{COMMAND} to a shell (see @code{system(3)}). If
10735 argument @var{STATUS} is present, it contains the value returned by
10736 @code{system(3)}, which is presumably 0 if the shell command succeeded.
10737 Note that which shell is used to invoke the command is system-dependent
10738 and environment-dependent.
10740 This intrinsic is provided in both subroutine and function forms;
10741 however, only one form can be used in any given program unit.
10743 @item @emph{Standard}:
10746 @item @emph{Class}:
10747 Subroutine, function
10749 @item @emph{Syntax}:
10750 @multitable @columnfractions .80
10751 @item @code{CALL SYSTEM(COMMAND [, STATUS])}
10752 @item @code{STATUS = SYSTEM(COMMAND)}
10755 @item @emph{Arguments}:
10756 @multitable @columnfractions .15 .70
10757 @item @var{COMMAND} @tab Shall be of default @code{CHARACTER} type.
10758 @item @var{STATUS} @tab (Optional) Shall be of default @code{INTEGER} type.
10761 @item @emph{See also}:
10767 @section @code{SYSTEM_CLOCK} --- Time function
10768 @fnindex SYSTEM_CLOCK
10769 @cindex time, clock ticks
10770 @cindex clock ticks
10773 @item @emph{Description}:
10774 Determines the @var{COUNT} of milliseconds of wall clock time since
10775 the Epoch (00:00:00 UTC, January 1, 1970) modulo @var{COUNT_MAX},
10776 @var{COUNT_RATE} determines the number of clock ticks per second.
10777 @var{COUNT_RATE} and @var{COUNT_MAX} are constant and specific to
10778 @command{gfortran}.
10780 If there is no clock, @var{COUNT} is set to @code{-HUGE(COUNT)}, and
10781 @var{COUNT_RATE} and @var{COUNT_MAX} are set to zero
10783 @item @emph{Standard}:
10784 Fortran 95 and later
10786 @item @emph{Class}:
10789 @item @emph{Syntax}:
10790 @code{CALL SYSTEM_CLOCK([COUNT, COUNT_RATE, COUNT_MAX])}
10792 @item @emph{Arguments}:
10793 @multitable @columnfractions .15 .70
10794 @item @var{COUNT} @tab (Optional) shall be a scalar of type default
10795 @code{INTEGER} with @code{INTENT(OUT)}.
10796 @item @var{COUNT_RATE} @tab (Optional) shall be a scalar of type default
10797 @code{INTEGER} with @code{INTENT(OUT)}.
10798 @item @var{COUNT_MAX} @tab (Optional) shall be a scalar of type default
10799 @code{INTEGER} with @code{INTENT(OUT)}.
10802 @item @emph{Example}:
10804 PROGRAM test_system_clock
10805 INTEGER :: count, count_rate, count_max
10806 CALL SYSTEM_CLOCK(count, count_rate, count_max)
10807 WRITE(*,*) count, count_rate, count_max
10811 @item @emph{See also}:
10812 @ref{DATE_AND_TIME}, @ref{CPU_TIME}
10818 @section @code{TAN} --- Tangent function
10821 @cindex trigonometric function, tangent
10825 @item @emph{Description}:
10826 @code{TAN(X)} computes the tangent of @var{X}.
10828 @item @emph{Standard}:
10829 Fortran 77 and later, for a complex argument Fortran 2008 or later
10831 @item @emph{Class}:
10834 @item @emph{Syntax}:
10835 @code{RESULT = TAN(X)}
10837 @item @emph{Arguments}:
10838 @multitable @columnfractions .15 .70
10839 @item @var{X} @tab The type shall be @code{REAL} or @code{COMPLEX}.
10842 @item @emph{Return value}:
10843 The return value has same type and kind as @var{X}.
10845 @item @emph{Example}:
10848 real(8) :: x = 0.165_8
10850 end program test_tan
10853 @item @emph{Specific names}:
10854 @multitable @columnfractions .20 .20 .20 .25
10855 @item Name @tab Argument @tab Return type @tab Standard
10856 @item @code{TAN(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab Fortran 95 and later
10857 @item @code{DTAN(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab Fortran 95 and later
10860 @item @emph{See also}:
10867 @section @code{TANH} --- Hyperbolic tangent function
10870 @cindex hyperbolic tangent
10871 @cindex hyperbolic function, tangent
10872 @cindex tangent, hyperbolic
10875 @item @emph{Description}:
10876 @code{TANH(X)} computes the hyperbolic tangent of @var{X}.
10878 @item @emph{Standard}:
10879 Fortran 77 and later, for a complex argument Fortran 2008 or later
10881 @item @emph{Class}:
10884 @item @emph{Syntax}:
10887 @item @emph{Arguments}:
10888 @multitable @columnfractions .15 .70
10889 @item @var{X} @tab The type shall be @code{REAL} or @code{COMPLEX}.
10892 @item @emph{Return value}:
10893 The return value has same type and kind as @var{X}. If @var{X} is
10894 complex, the imaginary part of the result is in radians. If @var{X}
10895 is @code{REAL}, the return value lies in the range
10896 @math{ - 1 \leq tanh(x) \leq 1 }.
10898 @item @emph{Example}:
10901 real(8) :: x = 2.1_8
10903 end program test_tanh
10906 @item @emph{Specific names}:
10907 @multitable @columnfractions .20 .20 .20 .25
10908 @item Name @tab Argument @tab Return type @tab Standard
10909 @item @code{TANH(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab Fortran 95 and later
10910 @item @code{DTANH(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab Fortran 95 and later
10913 @item @emph{See also}:
10920 @section @code{THIS_IMAGE} --- Function that returns the cosubscript index of this image
10921 @fnindex THIS_IMAGE
10922 @cindex coarray, THIS_IMAGE
10923 @cindex images, index of this image
10926 @item @emph{Description}:
10927 Returns the cosubscript for this image.
10929 @item @emph{Standard}:
10930 Fortran 2008 and later
10932 @item @emph{Class}:
10933 Transformational function
10935 @item @emph{Syntax}:
10936 @multitable @columnfractions .80
10937 @item @code{RESULT = THIS_IMAGE()}
10938 @item @code{RESULT = THIS_IMAGE(COARRAY [, DIM])}
10941 @item @emph{Arguments}:
10942 @multitable @columnfractions .15 .70
10943 @item @var{COARRAY} @tab Coarray of any type (optional; if @var{DIM}
10944 present, required).
10945 @item @var{DIM} @tab default integer scalar (optional). If present,
10946 @var{DIM} shall be between one and the corank of @var{COARRAY}.
10950 @item @emph{Return value}:
10951 Default integer. If @var{COARRAY} is not present, it is scalar and its value
10952 is the index of the invoking image. Otherwise, if @var{DIM} is not present,
10953 a rank-1 array with corank elements is returned, containing the cosubscripts
10954 for @var{COARRAY} specifying the invoking image. If @var{DIM} is present,
10955 a scalar is returned, with the value of the @var{DIM} element of
10956 @code{THIS_IMAGE(COARRAY)}.
10958 @item @emph{Example}:
10960 INTEGER :: value[*]
10962 value = THIS_IMAGE()
10964 IF (THIS_IMAGE() == 1) THEN
10965 DO i = 1, NUM_IMAGES()
10966 WRITE(*,'(2(a,i0))') 'value[', i, '] is ', value[i]
10971 @item @emph{See also}:
10972 @ref{NUM_IMAGES}, @ref{IMAGE_INDEX}
10978 @section @code{TIME} --- Time function
10980 @cindex time, current
10981 @cindex current time
10984 @item @emph{Description}:
10985 Returns the current time encoded as an integer (in the manner of the
10986 UNIX function @code{time(3)}). This value is suitable for passing to
10987 @code{CTIME()}, @code{GMTIME()}, and @code{LTIME()}.
10989 This intrinsic is not fully portable, such as to systems with 32-bit
10990 @code{INTEGER} types but supporting times wider than 32 bits. Therefore,
10991 the values returned by this intrinsic might be, or become, negative, or
10992 numerically less than previous values, during a single run of the
10995 See @ref{TIME8}, for information on a similar intrinsic that might be
10996 portable to more GNU Fortran implementations, though to fewer Fortran
10999 @item @emph{Standard}:
11002 @item @emph{Class}:
11005 @item @emph{Syntax}:
11006 @code{RESULT = TIME()}
11008 @item @emph{Return value}:
11009 The return value is a scalar of type @code{INTEGER(4)}.
11011 @item @emph{See also}:
11012 @ref{CTIME}, @ref{GMTIME}, @ref{LTIME}, @ref{MCLOCK}, @ref{TIME8}
11019 @section @code{TIME8} --- Time function (64-bit)
11021 @cindex time, current
11022 @cindex current time
11025 @item @emph{Description}:
11026 Returns the current time encoded as an integer (in the manner of the
11027 UNIX function @code{time(3)}). This value is suitable for passing to
11028 @code{CTIME()}, @code{GMTIME()}, and @code{LTIME()}.
11030 @emph{Warning:} this intrinsic does not increase the range of the timing
11031 values over that returned by @code{time(3)}. On a system with a 32-bit
11032 @code{time(3)}, @code{TIME8()} will return a 32-bit value, even though
11033 it is converted to a 64-bit @code{INTEGER(8)} value. That means
11034 overflows of the 32-bit value can still occur. Therefore, the values
11035 returned by this intrinsic might be or become negative or numerically
11036 less than previous values during a single run of the compiled program.
11038 @item @emph{Standard}:
11041 @item @emph{Class}:
11044 @item @emph{Syntax}:
11045 @code{RESULT = TIME8()}
11047 @item @emph{Return value}:
11048 The return value is a scalar of type @code{INTEGER(8)}.
11050 @item @emph{See also}:
11051 @ref{CTIME}, @ref{GMTIME}, @ref{LTIME}, @ref{MCLOCK8}, @ref{TIME}
11058 @section @code{TINY} --- Smallest positive number of a real kind
11060 @cindex limits, smallest number
11061 @cindex model representation, smallest number
11064 @item @emph{Description}:
11065 @code{TINY(X)} returns the smallest positive (non zero) number
11066 in the model of the type of @code{X}.
11068 @item @emph{Standard}:
11069 Fortran 95 and later
11071 @item @emph{Class}:
11074 @item @emph{Syntax}:
11075 @code{RESULT = TINY(X)}
11077 @item @emph{Arguments}:
11078 @multitable @columnfractions .15 .70
11079 @item @var{X} @tab Shall be of type @code{REAL}.
11082 @item @emph{Return value}:
11083 The return value is of the same type and kind as @var{X}
11085 @item @emph{Example}:
11086 See @code{HUGE} for an example.
11092 @section @code{TRAILZ} --- Number of trailing zero bits of an integer
11097 @item @emph{Description}:
11098 @code{TRAILZ} returns the number of trailing zero bits of an integer.
11100 @item @emph{Standard}:
11101 Fortran 2008 and later
11103 @item @emph{Class}:
11106 @item @emph{Syntax}:
11107 @code{RESULT = TRAILZ(I)}
11109 @item @emph{Arguments}:
11110 @multitable @columnfractions .15 .70
11111 @item @var{I} @tab Shall be of type @code{INTEGER}.
11114 @item @emph{Return value}:
11115 The type of the return value is the default @code{INTEGER}.
11116 If all the bits of @code{I} are zero, the result value is @code{BIT_SIZE(I)}.
11118 @item @emph{Example}:
11120 PROGRAM test_trailz
11121 WRITE (*,*) TRAILZ(8) ! prints 3
11125 @item @emph{See also}:
11126 @ref{BIT_SIZE}, @ref{LEADZ}
11132 @section @code{TRANSFER} --- Transfer bit patterns
11138 @item @emph{Description}:
11139 Interprets the bitwise representation of @var{SOURCE} in memory as if it
11140 is the representation of a variable or array of the same type and type
11141 parameters as @var{MOLD}.
11143 This is approximately equivalent to the C concept of @emph{casting} one
11146 @item @emph{Standard}:
11147 Fortran 95 and later
11149 @item @emph{Class}:
11150 Transformational function
11152 @item @emph{Syntax}:
11153 @code{RESULT = TRANSFER(SOURCE, MOLD[, SIZE])}
11155 @item @emph{Arguments}:
11156 @multitable @columnfractions .15 .70
11157 @item @var{SOURCE} @tab Shall be a scalar or an array of any type.
11158 @item @var{MOLD} @tab Shall be a scalar or an array of any type.
11159 @item @var{SIZE} @tab (Optional) shall be a scalar of type
11163 @item @emph{Return value}:
11164 The result has the same type as @var{MOLD}, with the bit level
11165 representation of @var{SOURCE}. If @var{SIZE} is present, the result is
11166 a one-dimensional array of length @var{SIZE}. If @var{SIZE} is absent
11167 but @var{MOLD} is an array (of any size or shape), the result is a one-
11168 dimensional array of the minimum length needed to contain the entirety
11169 of the bitwise representation of @var{SOURCE}. If @var{SIZE} is absent
11170 and @var{MOLD} is a scalar, the result is a scalar.
11172 If the bitwise representation of the result is longer than that of
11173 @var{SOURCE}, then the leading bits of the result correspond to those of
11174 @var{SOURCE} and any trailing bits are filled arbitrarily.
11176 When the resulting bit representation does not correspond to a valid
11177 representation of a variable of the same type as @var{MOLD}, the results
11178 are undefined, and subsequent operations on the result cannot be
11179 guaranteed to produce sensible behavior. For example, it is possible to
11180 create @code{LOGICAL} variables for which @code{@var{VAR}} and
11181 @code{.NOT.@var{VAR}} both appear to be true.
11183 @item @emph{Example}:
11185 PROGRAM test_transfer
11186 integer :: x = 2143289344
11187 print *, transfer(x, 1.0) ! prints "NaN" on i686
11195 @section @code{TRANSPOSE} --- Transpose an array of rank two
11197 @cindex array, transpose
11198 @cindex matrix, transpose
11202 @item @emph{Description}:
11203 Transpose an array of rank two. Element (i, j) of the result has the value
11204 @code{MATRIX(j, i)}, for all i, j.
11206 @item @emph{Standard}:
11207 Fortran 95 and later
11209 @item @emph{Class}:
11210 Transformational function
11212 @item @emph{Syntax}:
11213 @code{RESULT = TRANSPOSE(MATRIX)}
11215 @item @emph{Arguments}:
11216 @multitable @columnfractions .15 .70
11217 @item @var{MATRIX} @tab Shall be an array of any type and have a rank of two.
11220 @item @emph{Return value}:
11221 The result has the same type as @var{MATRIX}, and has shape
11222 @code{(/ m, n /)} if @var{MATRIX} has shape @code{(/ n, m /)}.
11228 @section @code{TRIM} --- Remove trailing blank characters of a string
11230 @cindex string, remove trailing whitespace
11233 @item @emph{Description}:
11234 Removes trailing blank characters of a string.
11236 @item @emph{Standard}:
11237 Fortran 95 and later
11239 @item @emph{Class}:
11240 Transformational function
11242 @item @emph{Syntax}:
11243 @code{RESULT = TRIM(STRING)}
11245 @item @emph{Arguments}:
11246 @multitable @columnfractions .15 .70
11247 @item @var{STRING} @tab Shall be a scalar of type @code{CHARACTER}.
11250 @item @emph{Return value}:
11251 A scalar of type @code{CHARACTER} which length is that of @var{STRING}
11252 less the number of trailing blanks.
11254 @item @emph{Example}:
11257 CHARACTER(len=10), PARAMETER :: s = "GFORTRAN "
11258 WRITE(*,*) LEN(s), LEN(TRIM(s)) ! "10 8", with/without trailing blanks
11262 @item @emph{See also}:
11263 @ref{ADJUSTL}, @ref{ADJUSTR}
11269 @section @code{TTYNAM} --- Get the name of a terminal device.
11271 @cindex system, terminal
11274 @item @emph{Description}:
11275 Get the name of a terminal device. For more information,
11276 see @code{ttyname(3)}.
11278 This intrinsic is provided in both subroutine and function forms;
11279 however, only one form can be used in any given program unit.
11281 @item @emph{Standard}:
11284 @item @emph{Class}:
11285 Subroutine, function
11287 @item @emph{Syntax}:
11288 @multitable @columnfractions .80
11289 @item @code{CALL TTYNAM(UNIT, NAME)}
11290 @item @code{NAME = TTYNAM(UNIT)}
11293 @item @emph{Arguments}:
11294 @multitable @columnfractions .15 .70
11295 @item @var{UNIT} @tab Shall be a scalar @code{INTEGER}.
11296 @item @var{NAME} @tab Shall be of type @code{CHARACTER}.
11299 @item @emph{Example}:
11301 PROGRAM test_ttynam
11304 IF (isatty(unit=unit)) write(*,*) ttynam(unit)
11309 @item @emph{See also}:
11316 @section @code{UBOUND} --- Upper dimension bounds of an array
11318 @cindex array, upper bound
11321 @item @emph{Description}:
11322 Returns the upper bounds of an array, or a single upper bound
11323 along the @var{DIM} dimension.
11324 @item @emph{Standard}:
11325 Fortran 95 and later, with @var{KIND} argument Fortran 2003 and later
11327 @item @emph{Class}:
11330 @item @emph{Syntax}:
11331 @code{RESULT = UBOUND(ARRAY [, DIM [, KIND]])}
11333 @item @emph{Arguments}:
11334 @multitable @columnfractions .15 .70
11335 @item @var{ARRAY} @tab Shall be an array, of any type.
11336 @item @var{DIM} @tab (Optional) Shall be a scalar @code{INTEGER}.
11337 @item @var{KIND}@tab (Optional) An @code{INTEGER} initialization
11338 expression indicating the kind parameter of the result.
11341 @item @emph{Return value}:
11342 The return value is of type @code{INTEGER} and of kind @var{KIND}. If
11343 @var{KIND} is absent, the return value is of default integer kind.
11344 If @var{DIM} is absent, the result is an array of the upper bounds of
11345 @var{ARRAY}. If @var{DIM} is present, the result is a scalar
11346 corresponding to the upper bound of the array along that dimension. If
11347 @var{ARRAY} is an expression rather than a whole array or array
11348 structure component, or if it has a zero extent along the relevant
11349 dimension, the upper bound is taken to be the number of elements along
11350 the relevant dimension.
11352 @item @emph{See also}:
11353 @ref{LBOUND}, @ref{LCOBOUND}
11359 @section @code{UCOBOUND} --- Upper codimension bounds of an array
11361 @cindex coarray, upper bound
11364 @item @emph{Description}:
11365 Returns the upper cobounds of a coarray, or a single upper cobound
11366 along the @var{DIM} codimension.
11367 @item @emph{Standard}:
11368 Fortran 2008 and later
11370 @item @emph{Class}:
11373 @item @emph{Syntax}:
11374 @code{RESULT = UCOBOUND(COARRAY [, DIM [, KIND]])}
11376 @item @emph{Arguments}:
11377 @multitable @columnfractions .15 .70
11378 @item @var{ARRAY} @tab Shall be an coarray, of any type.
11379 @item @var{DIM} @tab (Optional) Shall be a scalar @code{INTEGER}.
11380 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
11381 expression indicating the kind parameter of the result.
11384 @item @emph{Return value}:
11385 The return value is of type @code{INTEGER} and of kind @var{KIND}. If
11386 @var{KIND} is absent, the return value is of default integer kind.
11387 If @var{DIM} is absent, the result is an array of the lower cobounds of
11388 @var{COARRAY}. If @var{DIM} is present, the result is a scalar
11389 corresponding to the lower cobound of the array along that codimension.
11391 @item @emph{See also}:
11392 @ref{LCOBOUND}, @ref{LBOUND}
11398 @section @code{UMASK} --- Set the file creation mask
11400 @cindex file system, file creation mask
11403 @item @emph{Description}:
11404 Sets the file creation mask to @var{MASK}. If called as a function, it
11405 returns the old value. If called as a subroutine and argument @var{OLD}
11406 if it is supplied, it is set to the old value. See @code{umask(2)}.
11408 @item @emph{Standard}:
11411 @item @emph{Class}:
11412 Subroutine, function
11414 @item @emph{Syntax}:
11415 @code{CALL UMASK(MASK [, OLD])}
11416 @code{OLD = UMASK(MASK)}
11418 @item @emph{Arguments}:
11419 @multitable @columnfractions .15 .70
11420 @item @var{MASK} @tab Shall be a scalar of type @code{INTEGER}.
11421 @item @var{OLD} @tab (Optional) Shall be a scalar of type
11430 @section @code{UNLINK} --- Remove a file from the file system
11432 @cindex file system, remove file
11435 @item @emph{Description}:
11436 Unlinks the file @var{PATH}. A null character (@code{CHAR(0)}) can be
11437 used to mark the end of the name in @var{PATH}; otherwise, trailing
11438 blanks in the file name are ignored. If the @var{STATUS} argument is
11439 supplied, it contains 0 on success or a nonzero error code upon return;
11440 see @code{unlink(2)}.
11442 This intrinsic is provided in both subroutine and function forms;
11443 however, only one form can be used in any given program unit.
11445 @item @emph{Standard}:
11448 @item @emph{Class}:
11449 Subroutine, function
11451 @item @emph{Syntax}:
11452 @multitable @columnfractions .80
11453 @item @code{CALL UNLINK(PATH [, STATUS])}
11454 @item @code{STATUS = UNLINK(PATH)}
11457 @item @emph{Arguments}:
11458 @multitable @columnfractions .15 .70
11459 @item @var{PATH} @tab Shall be of default @code{CHARACTER} type.
11460 @item @var{STATUS} @tab (Optional) Shall be of default @code{INTEGER} type.
11463 @item @emph{See also}:
11464 @ref{LINK}, @ref{SYMLNK}
11470 @section @code{UNPACK} --- Unpack an array of rank one into an array
11472 @cindex array, unpacking
11473 @cindex array, increase dimension
11474 @cindex array, scatter elements
11477 @item @emph{Description}:
11478 Store the elements of @var{VECTOR} in an array of higher rank.
11480 @item @emph{Standard}:
11481 Fortran 95 and later
11483 @item @emph{Class}:
11484 Transformational function
11486 @item @emph{Syntax}:
11487 @code{RESULT = UNPACK(VECTOR, MASK, FIELD)}
11489 @item @emph{Arguments}:
11490 @multitable @columnfractions .15 .70
11491 @item @var{VECTOR} @tab Shall be an array of any type and rank one. It
11492 shall have at least as many elements as @var{MASK} has @code{TRUE} values.
11493 @item @var{MASK} @tab Shall be an array of type @code{LOGICAL}.
11494 @item @var{FIELD} @tab Shall be of the same type as @var{VECTOR} and have
11495 the same shape as @var{MASK}.
11498 @item @emph{Return value}:
11499 The resulting array corresponds to @var{FIELD} with @code{TRUE} elements
11500 of @var{MASK} replaced by values from @var{VECTOR} in array element order.
11502 @item @emph{Example}:
11504 PROGRAM test_unpack
11505 integer :: vector(2) = (/1,1/)
11506 logical :: mask(4) = (/ .TRUE., .FALSE., .FALSE., .TRUE. /)
11507 integer :: field(2,2) = 0, unity(2,2)
11509 ! result: unity matrix
11510 unity = unpack(vector, reshape(mask, (/2,2/)), field)
11514 @item @emph{See also}:
11515 @ref{PACK}, @ref{SPREAD}
11521 @section @code{VERIFY} --- Scan a string for the absence of a set of characters
11523 @cindex string, find missing set
11526 @item @emph{Description}:
11527 Verifies that all the characters in a @var{SET} are present in a @var{STRING}.
11529 If @var{BACK} is either absent or equals @code{FALSE}, this function
11530 returns the position of the leftmost character of @var{STRING} that is
11531 not in @var{SET}. If @var{BACK} equals @code{TRUE}, the rightmost position
11532 is returned. If all characters of @var{SET} are found in @var{STRING}, the
11535 @item @emph{Standard}:
11536 Fortran 95 and later, with @var{KIND} argument Fortran 2003 and later
11538 @item @emph{Class}:
11541 @item @emph{Syntax}:
11542 @code{RESULT = VERIFY(STRING, SET[, BACK [, KIND]])}
11544 @item @emph{Arguments}:
11545 @multitable @columnfractions .15 .70
11546 @item @var{STRING} @tab Shall be of type @code{CHARACTER}.
11547 @item @var{SET} @tab Shall be of type @code{CHARACTER}.
11548 @item @var{BACK} @tab (Optional) shall be of type @code{LOGICAL}.
11549 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
11550 expression indicating the kind parameter of the result.
11553 @item @emph{Return value}:
11554 The return value is of type @code{INTEGER} and of kind @var{KIND}. If
11555 @var{KIND} is absent, the return value is of default integer kind.
11557 @item @emph{Example}:
11559 PROGRAM test_verify
11560 WRITE(*,*) VERIFY("FORTRAN", "AO") ! 1, found 'F'
11561 WRITE(*,*) VERIFY("FORTRAN", "FOO") ! 3, found 'R'
11562 WRITE(*,*) VERIFY("FORTRAN", "C++") ! 1, found 'F'
11563 WRITE(*,*) VERIFY("FORTRAN", "C++", .TRUE.) ! 7, found 'N'
11564 WRITE(*,*) VERIFY("FORTRAN", "FORTRAN") ! 0' found none
11568 @item @emph{See also}:
11569 @ref{SCAN}, @ref{INDEX intrinsic}
11575 @section @code{XOR} --- Bitwise logical exclusive OR
11577 @cindex bitwise logical exclusive or
11578 @cindex logical exclusive or, bitwise
11581 @item @emph{Description}:
11582 Bitwise logical exclusive or.
11584 This intrinsic routine is provided for backwards compatibility with
11585 GNU Fortran 77. For integer arguments, programmers should consider
11586 the use of the @ref{IEOR} intrinsic and for logical arguments the
11587 @code{.NEQV.} operator, which are both defined by the Fortran standard.
11589 @item @emph{Standard}:
11592 @item @emph{Class}:
11595 @item @emph{Syntax}:
11596 @code{RESULT = XOR(I, J)}
11598 @item @emph{Arguments}:
11599 @multitable @columnfractions .15 .70
11600 @item @var{I} @tab The type shall be either a scalar @code{INTEGER}
11601 type or a scalar @code{LOGICAL} type.
11602 @item @var{J} @tab The type shall be the same as the type of @var{I}.
11605 @item @emph{Return value}:
11606 The return type is either a scalar @code{INTEGER} or a scalar
11607 @code{LOGICAL}. If the kind type parameters differ, then the
11608 smaller kind type is implicitly converted to larger kind, and the
11609 return has the larger kind.
11611 @item @emph{Example}:
11614 LOGICAL :: T = .TRUE., F = .FALSE.
11616 DATA a / Z'F' /, b / Z'3' /
11618 WRITE (*,*) XOR(T, T), XOR(T, F), XOR(F, T), XOR(F, F)
11619 WRITE (*,*) XOR(a, b)
11623 @item @emph{See also}:
11624 Fortran 95 elemental function: @ref{IEOR}
11629 @node Intrinsic Modules
11630 @chapter Intrinsic Modules
11631 @cindex intrinsic Modules
11634 * ISO_FORTRAN_ENV::
11636 * OpenMP Modules OMP_LIB and OMP_LIB_KINDS::
11639 @node ISO_FORTRAN_ENV
11640 @section @code{ISO_FORTRAN_ENV}
11642 @item @emph{Standard}:
11643 Fortran 2003 and later, except when otherwise noted
11646 The @code{ISO_FORTRAN_ENV} module provides the following scalar default-integer
11650 @item @code{ATOMIC_INT_KIND}:
11651 Default-kind integer constant to be used as kind parameter when defining
11652 integer variables used in atomic operations. (Fortran 2008 or later.)
11654 @item @code{ATOMIC_LOGICAL_KIND}:
11655 Default-kind integer constant to be used as kind parameter when defining
11656 logical variables used in atomic operations. (Fortran 2008 or later.)
11658 @item @code{CHARACTER_STORAGE_SIZE}:
11659 Size in bits of the character storage unit.
11661 @item @code{ERROR_UNIT}:
11662 Identifies the preconnected unit used for error reporting.
11664 @item @code{FILE_STORAGE_SIZE}:
11665 Size in bits of the file-storage unit.
11667 @item @code{INPUT_UNIT}:
11668 Identifies the preconnected unit identified by the asterisk
11669 (@code{*}) in @code{READ} statement.
11671 @item @code{INT8}, @code{INT16}, @code{INT32}, @code{INT64}:
11672 Kind type parameters to specify an INTEGER type with a storage
11673 size of 16, 32, and 64 bits. It is negative if a target platform
11674 does not support the particular kind. (Fortran 2008 or later.)
11676 @item @code{IOSTAT_END}:
11677 The value assigned to the variable passed to the IOSTAT= specifier of
11678 an input/output statement if an end-of-file condition occurred.
11680 @item @code{IOSTAT_EOR}:
11681 The value assigned to the variable passed to the IOSTAT= specifier of
11682 an input/output statement if an end-of-record condition occurred.
11684 @item @code{IOSTAT_INQUIRE_INTERNAL_UNIT}:
11685 Scalar default-integer constant, used by @code{INQUIRE} for the
11686 IOSTAT= specifier to denote an that a unit number identifies an
11687 internal unit. (Fortran 2008 or later.)
11689 @item @code{NUMERIC_STORAGE_SIZE}:
11690 The size in bits of the numeric storage unit.
11692 @item @code{OUTPUT_UNIT}:
11693 Identifies the preconnected unit identified by the asterisk
11694 (@code{*}) in @code{WRITE} statement.
11696 @item @code{REAL32}, @code{REAL64}, @code{REAL128}:
11697 Kind type parameters to specify a REAL type with a storage
11698 size of 32, 64, and 128 bits. It is negative if a target platform
11699 does not support the particular kind. (Fortran 2008 or later.)
11701 @item @code{STAT_LOCKED}:
11702 Scalar default-integer constant used as STAT= return value by @code{LOCK} to
11703 denote that the lock variable is locked by the executing image. (Fortran 2008
11706 @item @code{STAT_LOCKED_OTHER_IMAGE}:
11707 Scalar default-integer constant used as STAT= return value by @code{UNLOCK} to
11708 denote that the lock variable is locked by another image. (Fortran 2008 or
11711 @item @code{STAT_STOPPED_IMAGE}:
11712 Positive, scalar default-integer constant used as STAT= return value if the
11713 argument in the statement requires synchronisation with an image, which has
11714 initiated the termination of the execution. (Fortran 2008 or later.)
11716 @item @code{STAT_UNLOCKED}:
11717 Scalar default-integer constant used as STAT= return value by @code{UNLOCK} to
11718 denote that the lock variable is unlocked. (Fortran 2008 or later.)
11723 @node ISO_C_BINDING
11724 @section @code{ISO_C_BINDING}
11726 @item @emph{Standard}:
11727 Fortran 2003 and later, GNU extensions
11730 The following intrinsic procedures are provided by the module; their
11731 definition can be found in the section Intrinsic Procedures of this
11735 @item @code{C_ASSOCIATED}
11736 @item @code{C_F_POINTER}
11737 @item @code{C_F_PROCPOINTER}
11738 @item @code{C_FUNLOC}
11741 @c TODO: Vertical spacing between C_FUNLOC and C_LOC wrong in PDF,
11742 @c don't really know why.
11744 The @code{ISO_C_BINDING} module provides the following named constants of
11745 type default integer, which can be used as KIND type parameters.
11747 In addition to the integer named constants required by the Fortran 2003
11748 standard, GNU Fortran provides as an extension named constants for the
11749 128-bit integer types supported by the C compiler: @code{C_INT128_T,
11750 C_INT_LEAST128_T, C_INT_FAST128_T}.
11752 @multitable @columnfractions .15 .35 .35 .35
11753 @item Fortran Type @tab Named constant @tab C type @tab Extension
11754 @item @code{INTEGER}@tab @code{C_INT} @tab @code{int}
11755 @item @code{INTEGER}@tab @code{C_SHORT} @tab @code{short int}
11756 @item @code{INTEGER}@tab @code{C_LONG} @tab @code{long int}
11757 @item @code{INTEGER}@tab @code{C_LONG_LONG} @tab @code{long long int}
11758 @item @code{INTEGER}@tab @code{C_SIGNED_CHAR} @tab @code{signed char}/@code{unsigned char}
11759 @item @code{INTEGER}@tab @code{C_SIZE_T} @tab @code{size_t}
11760 @item @code{INTEGER}@tab @code{C_INT8_T} @tab @code{int8_t}
11761 @item @code{INTEGER}@tab @code{C_INT16_T} @tab @code{int16_t}
11762 @item @code{INTEGER}@tab @code{C_INT32_T} @tab @code{int32_t}
11763 @item @code{INTEGER}@tab @code{C_INT64_T} @tab @code{int64_t}
11764 @item @code{INTEGER}@tab @code{C_INT128_T} @tab @code{int128_t} @tab Ext.
11765 @item @code{INTEGER}@tab @code{C_INT_LEAST8_T} @tab @code{int_least8_t}
11766 @item @code{INTEGER}@tab @code{C_INT_LEAST16_T} @tab @code{int_least16_t}
11767 @item @code{INTEGER}@tab @code{C_INT_LEAST32_T} @tab @code{int_least32_t}
11768 @item @code{INTEGER}@tab @code{C_INT_LEAST64_T} @tab @code{int_least64_t}
11769 @item @code{INTEGER}@tab @code{C_INT_LEAST128_T}@tab @code{int_least128_t} @tab Ext.
11770 @item @code{INTEGER}@tab @code{C_INT_FAST8_T} @tab @code{int_fast8_t}
11771 @item @code{INTEGER}@tab @code{C_INT_FAST16_T} @tab @code{int_fast16_t}
11772 @item @code{INTEGER}@tab @code{C_INT_FAST32_T} @tab @code{int_fast32_t}
11773 @item @code{INTEGER}@tab @code{C_INT_FAST64_T} @tab @code{int_fast64_t}
11774 @item @code{INTEGER}@tab @code{C_INT_FAST128_T} @tab @code{int_fast128_t} @tab Ext.
11775 @item @code{INTEGER}@tab @code{C_INTMAX_T} @tab @code{intmax_t}
11776 @item @code{INTEGER}@tab @code{C_INTPTR_T} @tab @code{intptr_t}
11777 @item @code{REAL} @tab @code{C_FLOAT} @tab @code{float}
11778 @item @code{REAL} @tab @code{C_DOUBLE} @tab @code{double}
11779 @item @code{REAL} @tab @code{C_LONG_DOUBLE} @tab @code{long double}
11780 @item @code{COMPLEX}@tab @code{C_FLOAT_COMPLEX} @tab @code{float _Complex}
11781 @item @code{COMPLEX}@tab @code{C_DOUBLE_COMPLEX}@tab @code{double _Complex}
11782 @item @code{COMPLEX}@tab @code{C_LONG_DOUBLE_COMPLEX}@tab @code{long double _Complex}
11783 @item @code{LOGICAL}@tab @code{C_BOOL} @tab @code{_Bool}
11784 @item @code{CHARACTER}@tab @code{C_CHAR} @tab @code{char}
11787 Additionally, the following parameters of type @code{CHARACTER(KIND=C_CHAR)}
11790 @multitable @columnfractions .20 .45 .15
11791 @item Name @tab C definition @tab Value
11792 @item @code{C_NULL_CHAR} @tab null character @tab @code{'\0'}
11793 @item @code{C_ALERT} @tab alert @tab @code{'\a'}
11794 @item @code{C_BACKSPACE} @tab backspace @tab @code{'\b'}
11795 @item @code{C_FORM_FEED} @tab form feed @tab @code{'\f'}
11796 @item @code{C_NEW_LINE} @tab new line @tab @code{'\n'}
11797 @item @code{C_CARRIAGE_RETURN} @tab carriage return @tab @code{'\r'}
11798 @item @code{C_HORIZONTAL_TAB} @tab horizontal tab @tab @code{'\t'}
11799 @item @code{C_VERTICAL_TAB} @tab vertical tab @tab @code{'\v'}
11802 Moreover, the following two named constants are defined:
11804 @multitable @columnfractions .20 .80
11805 @item Name @tab Type
11806 @item @code{C_NULL_PTR} @tab @code{C_PTR}
11807 @item @code{C_NULL_FUNPTR} @tab @code{C_FUNPTR}
11810 Both are equivalent to the value @code{NULL} in C.
11812 @node OpenMP Modules OMP_LIB and OMP_LIB_KINDS
11813 @section OpenMP Modules @code{OMP_LIB} and @code{OMP_LIB_KINDS}
11815 @item @emph{Standard}:
11816 OpenMP Application Program Interface v3.0
11820 The OpenMP Fortran runtime library routines are provided both in
11821 a form of two Fortran 90 modules, named @code{OMP_LIB} and
11822 @code{OMP_LIB_KINDS}, and in a form of a Fortran @code{include} file named
11823 @file{omp_lib.h}. The procedures provided by @code{OMP_LIB} can be found
11824 in the @ref{Top,,Introduction,libgomp,GNU OpenMP runtime library} manual,
11825 the named constants defined in the @code{OMP_LIB_KINDS} module are listed
11828 For details refer to the actual
11829 @uref{http://www.openmp.org/mp-documents/spec30.pdf,
11830 OpenMP Application Program Interface v3.0}.
11832 @code{OMP_LIB_KINDS} provides the following scalar default-integer
11836 @item @code{omp_integer_kind}
11837 @item @code{omp_logical_kind}
11838 @item @code{omp_lock_kind}
11839 @item @code{omp_nest_lock_kind}
11840 @item @code{omp_sched_kind}