2 Copyright (C) 2005, 2006, 2007, 2008, 2009, 2010
3 Free Software Foundation, Inc.
4 This is part of the GNU Fortran manual.
5 For copying conditions, see the file gfortran.texi.
7 Permission is granted to copy, distribute and/or modify this document
8 under the terms of the GNU Free Documentation License, Version 1.2 or
9 any later version published by the Free Software Foundation; with the
10 Invariant Sections being ``Funding Free Software'', the Front-Cover
11 Texts being (a) (see below), and with the Back-Cover Texts being (b)
12 (see below). A copy of the license is included in the gfdl(7) man page.
15 Some basic guidelines for editing this document:
17 (1) The intrinsic procedures are to be listed in alphabetical order.
18 (2) The generic name is to be used.
19 (3) The specific names are included in the function index and in a
20 table at the end of the node (See ABS entry).
21 (4) Try to maintain the same style for each entry.
27 \gdef\acos{\mathop{\rm acos}\nolimits}
28 \gdef\asin{\mathop{\rm asin}\nolimits}
29 \gdef\atan{\mathop{\rm atan}\nolimits}
30 \gdef\acosh{\mathop{\rm acosh}\nolimits}
31 \gdef\asinh{\mathop{\rm asinh}\nolimits}
32 \gdef\atanh{\mathop{\rm atanh}\nolimits}
36 @node Intrinsic Procedures
37 @chapter Intrinsic Procedures
38 @cindex intrinsic procedures
41 * Introduction: Introduction to Intrinsics
42 * @code{ABORT}: ABORT, Abort the program
43 * @code{ABS}: ABS, Absolute value
44 * @code{ACCESS}: ACCESS, Checks file access modes
45 * @code{ACHAR}: ACHAR, Character in @acronym{ASCII} collating sequence
46 * @code{ACOS}: ACOS, Arccosine function
47 * @code{ACOSH}: ACOSH, Hyperbolic arccosine function
48 * @code{ADJUSTL}: ADJUSTL, Left adjust a string
49 * @code{ADJUSTR}: ADJUSTR, Right adjust a string
50 * @code{AIMAG}: AIMAG, Imaginary part of complex number
51 * @code{AINT}: AINT, Truncate to a whole number
52 * @code{ALARM}: ALARM, Set an alarm clock
53 * @code{ALL}: ALL, Determine if all values are true
54 * @code{ALLOCATED}: ALLOCATED, Status of allocatable entity
55 * @code{AND}: AND, Bitwise logical AND
56 * @code{ANINT}: ANINT, Nearest whole number
57 * @code{ANY}: ANY, Determine if any values are true
58 * @code{ASIN}: ASIN, Arcsine function
59 * @code{ASINH}: ASINH, Hyperbolic arcsine function
60 * @code{ASSOCIATED}: ASSOCIATED, Status of a pointer or pointer/target pair
61 * @code{ATAN}: ATAN, Arctangent function
62 * @code{ATAN2}: ATAN2, Arctangent function
63 * @code{ATANH}: ATANH, Hyperbolic arctangent function
64 * @code{BESSEL_J0}: BESSEL_J0, Bessel function of the first kind of order 0
65 * @code{BESSEL_J1}: BESSEL_J1, Bessel function of the first kind of order 1
66 * @code{BESSEL_JN}: BESSEL_JN, Bessel function of the first kind
67 * @code{BESSEL_Y0}: BESSEL_Y0, Bessel function of the second kind of order 0
68 * @code{BESSEL_Y1}: BESSEL_Y1, Bessel function of the second kind of order 1
69 * @code{BESSEL_YN}: BESSEL_YN, Bessel function of the second kind
70 * @code{BIT_SIZE}: BIT_SIZE, Bit size inquiry function
71 * @code{BTEST}: BTEST, Bit test function
72 * @code{C_ASSOCIATED}: C_ASSOCIATED, Status of a C pointer
73 * @code{C_F_POINTER}: C_F_POINTER, Convert C into Fortran pointer
74 * @code{C_F_PROCPOINTER}: C_F_PROCPOINTER, Convert C into Fortran procedure pointer
75 * @code{C_FUNLOC}: C_FUNLOC, Obtain the C address of a procedure
76 * @code{C_LOC}: C_LOC, Obtain the C address of an object
77 * @code{C_SIZEOF}: C_SIZEOF, Size in bytes of an expression
78 * @code{CEILING}: CEILING, Integer ceiling function
79 * @code{CHAR}: CHAR, Integer-to-character conversion function
80 * @code{CHDIR}: CHDIR, Change working directory
81 * @code{CHMOD}: CHMOD, Change access permissions of files
82 * @code{CMPLX}: CMPLX, Complex conversion function
83 * @code{COMMAND_ARGUMENT_COUNT}: COMMAND_ARGUMENT_COUNT, Get number of command line arguments
84 * @code{COMPLEX}: COMPLEX, Complex conversion function
85 * @code{CONJG}: CONJG, Complex conjugate function
86 * @code{COS}: COS, Cosine function
87 * @code{COSH}: COSH, Hyperbolic cosine function
88 * @code{COUNT}: COUNT, Count occurrences of TRUE in an array
89 * @code{CPU_TIME}: CPU_TIME, CPU time subroutine
90 * @code{CSHIFT}: CSHIFT, Circular shift elements of an array
91 * @code{CTIME}: CTIME, Subroutine (or function) to convert a time into a string
92 * @code{DATE_AND_TIME}: DATE_AND_TIME, Date and time subroutine
93 * @code{DBLE}: DBLE, Double precision conversion function
94 * @code{DCMPLX}: DCMPLX, Double complex conversion function
95 * @code{DFLOAT}: DFLOAT, Double precision conversion function
96 * @code{DIGITS}: DIGITS, Significant digits function
97 * @code{DIM}: DIM, Positive difference
98 * @code{DOT_PRODUCT}: DOT_PRODUCT, Dot product function
99 * @code{DPROD}: DPROD, Double product function
100 * @code{DREAL}: DREAL, Double real part function
101 * @code{DTIME}: DTIME, Execution time subroutine (or function)
102 * @code{EOSHIFT}: EOSHIFT, End-off shift elements of an array
103 * @code{EPSILON}: EPSILON, Epsilon function
104 * @code{ERF}: ERF, Error function
105 * @code{ERFC}: ERFC, Complementary error function
106 * @code{ERFC_SCALED}: ERFC_SCALED, Exponentially-scaled complementary error function
107 * @code{ETIME}: ETIME, Execution time subroutine (or function)
108 * @code{EXIT}: EXIT, Exit the program with status.
109 * @code{EXP}: EXP, Exponential function
110 * @code{EXPONENT}: EXPONENT, Exponent function
111 * @code{FDATE}: FDATE, Subroutine (or function) to get the current time as a string
112 * @code{FGET}: FGET, Read a single character in stream mode from stdin
113 * @code{FGETC}: FGETC, Read a single character in stream mode
114 * @code{FLOAT}: FLOAT, Convert integer to default real
115 * @code{FLOOR}: FLOOR, Integer floor function
116 * @code{FLUSH}: FLUSH, Flush I/O unit(s)
117 * @code{FNUM}: FNUM, File number function
118 * @code{FPUT}: FPUT, Write a single character in stream mode to stdout
119 * @code{FPUTC}: FPUTC, Write a single character in stream mode
120 * @code{FRACTION}: FRACTION, Fractional part of the model representation
121 * @code{FREE}: FREE, Memory de-allocation subroutine
122 * @code{FSEEK}: FSEEK, Low level file positioning subroutine
123 * @code{FSTAT}: FSTAT, Get file status
124 * @code{FTELL}: FTELL, Current stream position
125 * @code{GAMMA}: GAMMA, Gamma function
126 * @code{GERROR}: GERROR, Get last system error message
127 * @code{GETARG}: GETARG, Get command line arguments
128 * @code{GET_COMMAND}: GET_COMMAND, Get the entire command line
129 * @code{GET_COMMAND_ARGUMENT}: GET_COMMAND_ARGUMENT, Get command line arguments
130 * @code{GETCWD}: GETCWD, Get current working directory
131 * @code{GETENV}: GETENV, Get an environmental variable
132 * @code{GET_ENVIRONMENT_VARIABLE}: GET_ENVIRONMENT_VARIABLE, Get an environmental variable
133 * @code{GETGID}: GETGID, Group ID function
134 * @code{GETLOG}: GETLOG, Get login name
135 * @code{GETPID}: GETPID, Process ID function
136 * @code{GETUID}: GETUID, User ID function
137 * @code{GMTIME}: GMTIME, Convert time to GMT info
138 * @code{HOSTNM}: HOSTNM, Get system host name
139 * @code{HUGE}: HUGE, Largest number of a kind
140 * @code{HYPOT}: HYPOT, Euclidian distance function
141 * @code{IACHAR}: IACHAR, Code in @acronym{ASCII} collating sequence
142 * @code{IAND}: IAND, Bitwise logical and
143 * @code{IARGC}: IARGC, Get the number of command line arguments
144 * @code{IBCLR}: IBCLR, Clear bit
145 * @code{IBITS}: IBITS, Bit extraction
146 * @code{IBSET}: IBSET, Set bit
147 * @code{ICHAR}: ICHAR, Character-to-integer conversion function
148 * @code{IDATE}: IDATE, Current local time (day/month/year)
149 * @code{IEOR}: IEOR, Bitwise logical exclusive or
150 * @code{IERRNO}: IERRNO, Function to get the last system error number
151 * @code{INDEX}: INDEX intrinsic, Position of a substring within a string
152 * @code{INT}: INT, Convert to integer type
153 * @code{INT2}: INT2, Convert to 16-bit integer type
154 * @code{INT8}: INT8, Convert to 64-bit integer type
155 * @code{IOR}: IOR, Bitwise logical or
156 * @code{IRAND}: IRAND, Integer pseudo-random number
157 * @code{IMAGE_INDEX}: IMAGE_INDEX, Cosubscript to image index convertion
158 * @code{IS_IOSTAT_END}: IS_IOSTAT_END, Test for end-of-file value
159 * @code{IS_IOSTAT_EOR}: IS_IOSTAT_EOR, Test for end-of-record value
160 * @code{ISATTY}: ISATTY, Whether a unit is a terminal device
161 * @code{ISHFT}: ISHFT, Shift bits
162 * @code{ISHFTC}: ISHFTC, Shift bits circularly
163 * @code{ISNAN}: ISNAN, Tests for a NaN
164 * @code{ITIME}: ITIME, Current local time (hour/minutes/seconds)
165 * @code{KILL}: KILL, Send a signal to a process
166 * @code{KIND}: KIND, Kind of an entity
167 * @code{LBOUND}: LBOUND, Lower dimension bounds of an array
168 * @code{LCOBOUND}: LCOBOUND, Lower codimension bounds of an array
169 * @code{LEADZ}: LEADZ, Number of leading zero bits of an integer
170 * @code{LEN}: LEN, Length of a character entity
171 * @code{LEN_TRIM}: LEN_TRIM, Length of a character entity without trailing blank characters
172 * @code{LGE}: LGE, Lexical greater than or equal
173 * @code{LGT}: LGT, Lexical greater than
174 * @code{LINK}: LINK, Create a hard link
175 * @code{LLE}: LLE, Lexical less than or equal
176 * @code{LLT}: LLT, Lexical less than
177 * @code{LNBLNK}: LNBLNK, Index of the last non-blank character in a string
178 * @code{LOC}: LOC, Returns the address of a variable
179 * @code{LOG}: LOG, Logarithm function
180 * @code{LOG10}: LOG10, Base 10 logarithm function
181 * @code{LOG_GAMMA}: LOG_GAMMA, Logarithm of the Gamma function
182 * @code{LOGICAL}: LOGICAL, Convert to logical type
183 * @code{LONG}: LONG, Convert to integer type
184 * @code{LSHIFT}: LSHIFT, Left shift bits
185 * @code{LSTAT}: LSTAT, Get file status
186 * @code{LTIME}: LTIME, Convert time to local time info
187 * @code{MALLOC}: MALLOC, Dynamic memory allocation function
188 * @code{MATMUL}: MATMUL, matrix multiplication
189 * @code{MAX}: MAX, Maximum value of an argument list
190 * @code{MAXEXPONENT}: MAXEXPONENT, Maximum exponent of a real kind
191 * @code{MAXLOC}: MAXLOC, Location of the maximum value within an array
192 * @code{MAXVAL}: MAXVAL, Maximum value of an array
193 * @code{MCLOCK}: MCLOCK, Time function
194 * @code{MCLOCK8}: MCLOCK8, Time function (64-bit)
195 * @code{MERGE}: MERGE, Merge arrays
196 * @code{MIN}: MIN, Minimum value of an argument list
197 * @code{MINEXPONENT}: MINEXPONENT, Minimum exponent of a real kind
198 * @code{MINLOC}: MINLOC, Location of the minimum value within an array
199 * @code{MINVAL}: MINVAL, Minimum value of an array
200 * @code{MOD}: MOD, Remainder function
201 * @code{MODULO}: MODULO, Modulo function
202 * @code{MOVE_ALLOC}: MOVE_ALLOC, Move allocation from one object to another
203 * @code{MVBITS}: MVBITS, Move bits from one integer to another
204 * @code{NEAREST}: NEAREST, Nearest representable number
205 * @code{NEW_LINE}: NEW_LINE, New line character
206 * @code{NINT}: NINT, Nearest whole number
207 * @code{NOT}: NOT, Logical negation
208 * @code{NULL}: NULL, Function that returns an disassociated pointer
209 * @code{NUM_IMAGES}: NUM_IMAGES, Number of images
210 * @code{OR}: OR, Bitwise logical OR
211 * @code{PACK}: PACK, Pack an array into an array of rank one
212 * @code{PERROR}: PERROR, Print system error message
213 * @code{PRECISION}: PRECISION, Decimal precision of a real kind
214 * @code{PRESENT}: PRESENT, Determine whether an optional dummy argument is specified
215 * @code{PRODUCT}: PRODUCT, Product of array elements
216 * @code{RADIX}: RADIX, Base of a data model
217 * @code{RANDOM_NUMBER}: RANDOM_NUMBER, Pseudo-random number
218 * @code{RANDOM_SEED}: RANDOM_SEED, Initialize a pseudo-random number sequence
219 * @code{RAND}: RAND, Real pseudo-random number
220 * @code{RANGE}: RANGE, Decimal exponent range
221 * @code{RAN}: RAN, Real pseudo-random number
222 * @code{REAL}: REAL, Convert to real type
223 * @code{RENAME}: RENAME, Rename a file
224 * @code{REPEAT}: REPEAT, Repeated string concatenation
225 * @code{RESHAPE}: RESHAPE, Function to reshape an array
226 * @code{RRSPACING}: RRSPACING, Reciprocal of the relative spacing
227 * @code{RSHIFT}: RSHIFT, Right shift bits
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{SNGL}: SNGL, Convert double precision real to default real
245 * @code{SPACING}: SPACING, Smallest distance between two numbers of a given type
246 * @code{SPREAD}: SPREAD, Add a dimension to an array
247 * @code{SQRT}: SQRT, Square-root function
248 * @code{SRAND}: SRAND, Reinitialize the random number generator
249 * @code{STAT}: STAT, Get file status
250 * @code{SUM}: SUM, Sum of array elements
251 * @code{SYMLNK}: SYMLNK, Create a symbolic link
252 * @code{SYSTEM}: SYSTEM, Execute a shell command
253 * @code{SYSTEM_CLOCK}: SYSTEM_CLOCK, Time function
254 * @code{TAN}: TAN, Tangent function
255 * @code{TANH}: TANH, Hyperbolic tangent function
256 * @code{THIS_IMAGE}: THIS_IMAGE, Cosubscript index of this image
257 * @code{TIME}: TIME, Time function
258 * @code{TIME8}: TIME8, Time function (64-bit)
259 * @code{TINY}: TINY, Smallest positive number of a real kind
260 * @code{TRAILZ}: TRAILZ, Number of trailing zero bits of an integer
261 * @code{TRANSFER}: TRANSFER, Transfer bit patterns
262 * @code{TRANSPOSE}: TRANSPOSE, Transpose an array of rank two
263 * @code{TRIM}: TRIM, Remove trailing blank characters of a string
264 * @code{TTYNAM}: TTYNAM, Get the name of a terminal device.
265 * @code{UBOUND}: UBOUND, Upper dimension bounds of an array
266 * @code{UCOBOUND}: UCOBOUND, Upper codimension bounds of an array
267 * @code{UMASK}: UMASK, Set the file creation mask
268 * @code{UNLINK}: UNLINK, Remove a file from the file system
269 * @code{UNPACK}: UNPACK, Unpack an array of rank one into an array
270 * @code{VERIFY}: VERIFY, Scan a string for the absence of a set of characters
271 * @code{XOR}: XOR, Bitwise logical exclusive or
274 @node Introduction to Intrinsics
275 @section Introduction to intrinsic procedures
277 The intrinsic procedures provided by GNU Fortran include all of the
278 intrinsic procedures required by the Fortran 95 standard, a set of
279 intrinsic procedures for backwards compatibility with G77, and a
280 selection of intrinsic procedures from the Fortran 2003 and Fortran 2008
281 standards. Any conflict between a description here and a description in
282 either the Fortran 95 standard, the Fortran 2003 standard or the Fortran
283 2008 standard is unintentional, and the standard(s) should be considered
286 The enumeration of the @code{KIND} type parameter is processor defined in
287 the Fortran 95 standard. GNU Fortran defines the default integer type and
288 default real type by @code{INTEGER(KIND=4)} and @code{REAL(KIND=4)},
289 respectively. The standard mandates that both data types shall have
290 another kind, which have more precision. On typical target architectures
291 supported by @command{gfortran}, this kind type parameter is @code{KIND=8}.
292 Hence, @code{REAL(KIND=8)} and @code{DOUBLE PRECISION} are equivalent.
293 In the description of generic intrinsic procedures, the kind type parameter
294 will be specified by @code{KIND=*}, and in the description of specific
295 names for an intrinsic procedure the kind type parameter will be explicitly
296 given (e.g., @code{REAL(KIND=4)} or @code{REAL(KIND=8)}). Finally, for
297 brevity the optional @code{KIND=} syntax will be omitted.
299 Many of the intrinsic procedures take one or more optional arguments.
300 This document follows the convention used in the Fortran 95 standard,
301 and denotes such arguments by square brackets.
303 GNU Fortran offers the @option{-std=f95} and @option{-std=gnu} options,
304 which can be used to restrict the set of intrinsic procedures to a
305 given standard. By default, @command{gfortran} sets the @option{-std=gnu}
306 option, and so all intrinsic procedures described here are accepted. There
307 is one caveat. For a select group of intrinsic procedures, @command{g77}
308 implemented both a function and a subroutine. Both classes
309 have been implemented in @command{gfortran} for backwards compatibility
310 with @command{g77}. It is noted here that these functions and subroutines
311 cannot be intermixed in a given subprogram. In the descriptions that follow,
312 the applicable standard for each intrinsic procedure is noted.
317 @section @code{ABORT} --- Abort the program
319 @cindex program termination, with core dump
320 @cindex terminate program, with core dump
324 @item @emph{Description}:
325 @code{ABORT} causes immediate termination of the program. On operating
326 systems that support a core dump, @code{ABORT} will produce a core dump even if
327 the option @option{-fno-dump-core} is in effect, which is suitable for debugging
329 @c TODO: Check if this (with -fno-dump-core) is correct.
331 @item @emph{Standard}:
340 @item @emph{Return value}:
343 @item @emph{Example}:
346 integer :: i = 1, j = 2
347 if (i /= j) call abort
348 end program test_abort
351 @item @emph{See also}:
352 @ref{EXIT}, @ref{KILL}
359 @section @code{ABS} --- Absolute value
366 @cindex absolute value
369 @item @emph{Description}:
370 @code{ABS(A)} computes the absolute value of @code{A}.
372 @item @emph{Standard}:
373 Fortran 77 and later, has overloads that are GNU extensions
379 @code{RESULT = ABS(A)}
381 @item @emph{Arguments}:
382 @multitable @columnfractions .15 .70
383 @item @var{A} @tab The type of the argument shall be an @code{INTEGER},
384 @code{REAL}, or @code{COMPLEX}.
387 @item @emph{Return value}:
388 The return value is of the same type and
389 kind as the argument except the return value is @code{REAL} for a
390 @code{COMPLEX} argument.
392 @item @emph{Example}:
397 complex :: z = (-1.e0,0.e0)
404 @item @emph{Specific names}:
405 @multitable @columnfractions .20 .20 .20 .25
406 @item Name @tab Argument @tab Return type @tab Standard
407 @item @code{ABS(A)} @tab @code{REAL(4) A} @tab @code{REAL(4)} @tab Fortran 77 and later
408 @item @code{CABS(A)} @tab @code{COMPLEX(4) A} @tab @code{REAL(4)} @tab Fortran 77 and later
409 @item @code{DABS(A)} @tab @code{REAL(8) A} @tab @code{REAL(8)} @tab Fortran 77 and later
410 @item @code{IABS(A)} @tab @code{INTEGER(4) A} @tab @code{INTEGER(4)} @tab Fortran 77 and later
411 @item @code{ZABS(A)} @tab @code{COMPLEX(8) A} @tab @code{COMPLEX(8)} @tab GNU extension
412 @item @code{CDABS(A)} @tab @code{COMPLEX(8) A} @tab @code{COMPLEX(8)} @tab GNU extension
419 @section @code{ACCESS} --- Checks file access modes
421 @cindex file system, access mode
424 @item @emph{Description}:
425 @code{ACCESS(NAME, MODE)} checks whether the file @var{NAME}
426 exists, is readable, writable or executable. Except for the
427 executable check, @code{ACCESS} can be replaced by
428 Fortran 95's @code{INQUIRE}.
430 @item @emph{Standard}:
437 @code{RESULT = ACCESS(NAME, MODE)}
439 @item @emph{Arguments}:
440 @multitable @columnfractions .15 .70
441 @item @var{NAME} @tab Scalar @code{CHARACTER} of default kind with the
442 file name. Tailing blank are ignored unless the character @code{achar(0)}
443 is present, then all characters up to and excluding @code{achar(0)} are
445 @item @var{MODE} @tab Scalar @code{CHARACTER} of default kind with the
446 file access mode, may be any concatenation of @code{"r"} (readable),
447 @code{"w"} (writable) and @code{"x"} (executable), or @code{" "} to check
451 @item @emph{Return value}:
452 Returns a scalar @code{INTEGER}, which is @code{0} if the file is
453 accessible in the given mode; otherwise or if an invalid argument
454 has been given for @code{MODE} the value @code{1} is returned.
456 @item @emph{Example}:
460 character(len=*), parameter :: file = 'test.dat'
461 character(len=*), parameter :: file2 = 'test.dat '//achar(0)
462 if(access(file,' ') == 0) print *, trim(file),' is exists'
463 if(access(file,'r') == 0) print *, trim(file),' is readable'
464 if(access(file,'w') == 0) print *, trim(file),' is writable'
465 if(access(file,'x') == 0) print *, trim(file),' is executable'
466 if(access(file2,'rwx') == 0) &
467 print *, trim(file2),' is readable, writable and executable'
468 end program access_test
470 @item @emph{Specific names}:
471 @item @emph{See also}:
478 @section @code{ACHAR} --- Character in @acronym{ASCII} collating sequence
480 @cindex @acronym{ASCII} collating sequence
481 @cindex collating sequence, @acronym{ASCII}
484 @item @emph{Description}:
485 @code{ACHAR(I)} returns the character located at position @code{I}
486 in the @acronym{ASCII} collating sequence.
488 @item @emph{Standard}:
489 Fortran 77 and later, with @var{KIND} argument Fortran 2003 and later
495 @code{RESULT = ACHAR(I [, KIND])}
497 @item @emph{Arguments}:
498 @multitable @columnfractions .15 .70
499 @item @var{I} @tab The type shall be @code{INTEGER}.
500 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
501 expression indicating the kind parameter of the result.
504 @item @emph{Return value}:
505 The return value is of type @code{CHARACTER} with a length of one.
506 If the @var{KIND} argument is present, the return value is of the
507 specified kind and of the default kind otherwise.
509 @item @emph{Example}:
514 end program test_achar
518 See @ref{ICHAR} for a discussion of converting between numerical values
519 and formatted string representations.
521 @item @emph{See also}:
522 @ref{CHAR}, @ref{IACHAR}, @ref{ICHAR}
529 @section @code{ACOS} --- Arccosine function
532 @cindex trigonometric function, cosine, inverse
533 @cindex cosine, inverse
536 @item @emph{Description}:
537 @code{ACOS(X)} computes the arccosine of @var{X} (inverse of @code{COS(X)}).
539 @item @emph{Standard}:
540 Fortran 77 and later, for a complex argument Fortran 2008 or later
546 @code{RESULT = ACOS(X)}
548 @item @emph{Arguments}:
549 @multitable @columnfractions .15 .70
550 @item @var{X} @tab The type shall either be @code{REAL} with a magnitude that is
551 less than or equal to one - or the type shall be @code{COMPLEX}.
554 @item @emph{Return value}:
555 The return value is of the same type and kind as @var{X}.
556 The real part of the result is in radians and lies in the range
557 @math{0 \leq \Re \acos(x) \leq \pi}.
559 @item @emph{Example}:
562 real(8) :: x = 0.866_8
564 end program test_acos
567 @item @emph{Specific names}:
568 @multitable @columnfractions .20 .20 .20 .25
569 @item Name @tab Argument @tab Return type @tab Standard
570 @item @code{ACOS(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab Fortran 77 and later
571 @item @code{DACOS(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab Fortran 77 and later
574 @item @emph{See also}:
575 Inverse function: @ref{COS}
582 @section @code{ACOSH} --- Hyperbolic arccosine function
585 @cindex area hyperbolic cosine
586 @cindex hyperbolic arccosine
587 @cindex hyperbolic function, cosine, inverse
588 @cindex cosine, hyperbolic, inverse
591 @item @emph{Description}:
592 @code{ACOSH(X)} computes the hyperbolic arccosine of @var{X} (inverse of
595 @item @emph{Standard}:
596 Fortran 2008 and later
602 @code{RESULT = ACOSH(X)}
604 @item @emph{Arguments}:
605 @multitable @columnfractions .15 .70
606 @item @var{X} @tab The type shall be @code{REAL} or @code{COMPLEX}.
609 @item @emph{Return value}:
610 The return value has the same type and kind as @var{X}. If @var{X} is
611 complex, the imaginary part of the result is in radians and lies between
612 @math{ 0 \leq \Im \acosh(x) \leq \pi}.
614 @item @emph{Example}:
617 REAL(8), DIMENSION(3) :: x = (/ 1.0, 2.0, 3.0 /)
622 @item @emph{Specific names}:
623 @multitable @columnfractions .20 .20 .20 .25
624 @item Name @tab Argument @tab Return type @tab Standard
625 @item @code{DACOSH(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU extension
628 @item @emph{See also}:
629 Inverse function: @ref{COSH}
635 @section @code{ADJUSTL} --- Left adjust a string
637 @cindex string, adjust left
638 @cindex adjust string
641 @item @emph{Description}:
642 @code{ADJUSTL(STRING)} will left adjust a string by removing leading spaces.
643 Spaces are inserted at the end of the string as needed.
645 @item @emph{Standard}:
652 @code{RESULT = ADJUSTL(STRING)}
654 @item @emph{Arguments}:
655 @multitable @columnfractions .15 .70
656 @item @var{STRING} @tab The type shall be @code{CHARACTER}.
659 @item @emph{Return value}:
660 The return value is of type @code{CHARACTER} and of the same kind as
661 @var{STRING} where leading spaces are removed and the same number of
662 spaces are inserted on the end of @var{STRING}.
664 @item @emph{Example}:
667 character(len=20) :: str = ' gfortran'
670 end program test_adjustl
673 @item @emph{See also}:
674 @ref{ADJUSTR}, @ref{TRIM}
680 @section @code{ADJUSTR} --- Right adjust a string
682 @cindex string, adjust right
683 @cindex adjust string
686 @item @emph{Description}:
687 @code{ADJUSTR(STRING)} will right adjust a string by removing trailing spaces.
688 Spaces are inserted at the start of the string as needed.
690 @item @emph{Standard}:
697 @code{RESULT = ADJUSTR(STRING)}
699 @item @emph{Arguments}:
700 @multitable @columnfractions .15 .70
701 @item @var{STR} @tab The type shall be @code{CHARACTER}.
704 @item @emph{Return value}:
705 The return value is of type @code{CHARACTER} and of the same kind as
706 @var{STRING} where trailing spaces are removed and the same number of
707 spaces are inserted at the start of @var{STRING}.
709 @item @emph{Example}:
712 character(len=20) :: str = 'gfortran'
715 end program test_adjustr
718 @item @emph{See also}:
719 @ref{ADJUSTL}, @ref{TRIM}
725 @section @code{AIMAG} --- Imaginary part of complex number
730 @cindex complex numbers, imaginary part
733 @item @emph{Description}:
734 @code{AIMAG(Z)} yields the imaginary part of complex argument @code{Z}.
735 The @code{IMAG(Z)} and @code{IMAGPART(Z)} intrinsic functions are provided
736 for compatibility with @command{g77}, and their use in new code is
737 strongly discouraged.
739 @item @emph{Standard}:
740 Fortran 77 and later, has overloads that are GNU extensions
746 @code{RESULT = AIMAG(Z)}
748 @item @emph{Arguments}:
749 @multitable @columnfractions .15 .70
750 @item @var{Z} @tab The type of the argument shall be @code{COMPLEX}.
753 @item @emph{Return value}:
754 The return value is of type @code{REAL} with the
755 kind type parameter of the argument.
757 @item @emph{Example}:
762 z4 = cmplx(1.e0_4, 0.e0_4)
763 z8 = cmplx(0.e0_8, 1.e0_8)
764 print *, aimag(z4), dimag(z8)
765 end program test_aimag
768 @item @emph{Specific names}:
769 @multitable @columnfractions .20 .20 .20 .25
770 @item Name @tab Argument @tab Return type @tab Standard
771 @item @code{AIMAG(Z)} @tab @code{COMPLEX Z} @tab @code{REAL} @tab GNU extension
772 @item @code{DIMAG(Z)} @tab @code{COMPLEX(8) Z} @tab @code{REAL(8)} @tab GNU extension
773 @item @code{IMAG(Z)} @tab @code{COMPLEX Z} @tab @code{REAL} @tab GNU extension
774 @item @code{IMAGPART(Z)} @tab @code{COMPLEX Z} @tab @code{REAL} @tab GNU extension
781 @section @code{AINT} --- Truncate to a whole number
785 @cindex rounding, floor
788 @item @emph{Description}:
789 @code{AINT(A [, KIND])} truncates its argument to a whole number.
791 @item @emph{Standard}:
798 @code{RESULT = AINT(A [, KIND])}
800 @item @emph{Arguments}:
801 @multitable @columnfractions .15 .70
802 @item @var{A} @tab The type of the argument shall be @code{REAL}.
803 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
804 expression indicating the kind parameter of the result.
807 @item @emph{Return value}:
808 The return value is of type @code{REAL} with the kind type parameter of the
809 argument if the optional @var{KIND} is absent; otherwise, the kind
810 type parameter will be given by @var{KIND}. If the magnitude of
811 @var{X} is less than one, @code{AINT(X)} returns zero. If the
812 magnitude is equal to or greater than one then it returns the largest
813 whole number that does not exceed its magnitude. The sign is the same
814 as the sign of @var{X}.
816 @item @emph{Example}:
823 print *, aint(x4), dint(x8)
825 end program test_aint
828 @item @emph{Specific names}:
829 @multitable @columnfractions .20 .20 .20 .25
830 @item Name @tab Argument @tab Return type @tab Standard
831 @item @code{AINT(A)} @tab @code{REAL(4) A} @tab @code{REAL(4)} @tab Fortran 77 and later
832 @item @code{DINT(A)} @tab @code{REAL(8) A} @tab @code{REAL(8)} @tab Fortran 77 and later
839 @section @code{ALARM} --- Execute a routine after a given delay
841 @cindex delayed execution
844 @item @emph{Description}:
845 @code{ALARM(SECONDS, HANDLER [, STATUS])} causes external subroutine @var{HANDLER}
846 to be executed after a delay of @var{SECONDS} by using @code{alarm(2)} to
847 set up a signal and @code{signal(2)} to catch it. If @var{STATUS} is
848 supplied, it will be returned with the number of seconds remaining until
849 any previously scheduled alarm was due to be delivered, or zero if there
850 was no previously scheduled alarm.
852 @item @emph{Standard}:
859 @code{CALL ALARM(SECONDS, HANDLER [, STATUS])}
861 @item @emph{Arguments}:
862 @multitable @columnfractions .15 .70
863 @item @var{SECONDS} @tab The type of the argument shall be a scalar
864 @code{INTEGER}. It is @code{INTENT(IN)}.
865 @item @var{HANDLER} @tab Signal handler (@code{INTEGER FUNCTION} or
866 @code{SUBROUTINE}) or dummy/global @code{INTEGER} scalar. The scalar
867 values may be either @code{SIG_IGN=1} to ignore the alarm generated
868 or @code{SIG_DFL=0} to set the default action. It is @code{INTENT(IN)}.
869 @item @var{STATUS} @tab (Optional) @var{STATUS} shall be a scalar
870 variable of the default @code{INTEGER} kind. It is @code{INTENT(OUT)}.
873 @item @emph{Example}:
876 external handler_print
878 call alarm (3, handler_print, i)
881 end program test_alarm
883 This will cause the external routine @var{handler_print} to be called
890 @section @code{ALL} --- All values in @var{MASK} along @var{DIM} are true
892 @cindex array, apply condition
893 @cindex array, condition testing
896 @item @emph{Description}:
897 @code{ALL(MASK [, DIM])} determines if all the values are true in @var{MASK}
898 in the array along dimension @var{DIM}.
900 @item @emph{Standard}:
904 Transformational function
907 @code{RESULT = ALL(MASK [, DIM])}
909 @item @emph{Arguments}:
910 @multitable @columnfractions .15 .70
911 @item @var{MASK} @tab The type of the argument shall be @code{LOGICAL} and
912 it shall not be scalar.
913 @item @var{DIM} @tab (Optional) @var{DIM} shall be a scalar integer
914 with a value that lies between one and the rank of @var{MASK}.
917 @item @emph{Return value}:
918 @code{ALL(MASK)} returns a scalar value of type @code{LOGICAL} where
919 the kind type parameter is the same as the kind type parameter of
920 @var{MASK}. If @var{DIM} is present, then @code{ALL(MASK, DIM)} returns
921 an array with the rank of @var{MASK} minus 1. The shape is determined from
922 the shape of @var{MASK} where the @var{DIM} dimension is elided.
926 @code{ALL(MASK)} is true if all elements of @var{MASK} are true.
927 It also is true if @var{MASK} has zero size; otherwise, it is false.
929 If the rank of @var{MASK} is one, then @code{ALL(MASK,DIM)} is equivalent
930 to @code{ALL(MASK)}. If the rank is greater than one, then @code{ALL(MASK,DIM)}
931 is determined by applying @code{ALL} to the array sections.
934 @item @emph{Example}:
938 l = all((/.true., .true., .true./))
943 integer a(2,3), b(2,3)
947 print *, all(a .eq. b, 1)
948 print *, all(a .eq. b, 2)
949 end subroutine section
957 @section @code{ALLOCATED} --- Status of an allocatable entity
959 @cindex allocation, status
962 @item @emph{Description}:
963 @code{ALLOCATED(ARRAY)} and @code{ALLOCATED(SCALAR)} check the allocation
964 status of @var{ARRAY} and @var{SCALAR}, respectively.
966 @item @emph{Standard}:
967 Fortran 95 and later. Note, the @code{SCALAR=} keyword and allocatable
968 scalar entities are available in Fortran 2003 and later.
974 @code{RESULT = ALLOCATED(ARRAY)} or @code{RESULT = ALLOCATED(SCALAR)}
976 @item @emph{Arguments}:
977 @multitable @columnfractions .15 .70
978 @item @var{ARRAY} @tab The argument shall be an @code{ALLOCATABLE} array.
979 @item @var{SCALAR} @tab The argument shall be an @code{ALLOCATABLE} scalar.
982 @item @emph{Return value}:
983 The return value is a scalar @code{LOGICAL} with the default logical
984 kind type parameter. If the argument is allocated, then the result is
985 @code{.TRUE.}; otherwise, it returns @code{.FALSE.}
987 @item @emph{Example}:
989 program test_allocated
991 real(4), allocatable :: x(:)
992 if (.not. allocated(x)) allocate(x(i))
993 end program test_allocated
1000 @section @code{AND} --- Bitwise logical AND
1002 @cindex bitwise logical and
1003 @cindex logical and, bitwise
1006 @item @emph{Description}:
1007 Bitwise logical @code{AND}.
1009 This intrinsic routine is provided for backwards compatibility with
1010 GNU Fortran 77. For integer arguments, programmers should consider
1011 the use of the @ref{IAND} intrinsic defined by the Fortran standard.
1013 @item @emph{Standard}:
1019 @item @emph{Syntax}:
1020 @code{RESULT = AND(I, J)}
1022 @item @emph{Arguments}:
1023 @multitable @columnfractions .15 .70
1024 @item @var{I} @tab The type shall be either a scalar @code{INTEGER}
1025 type or a scalar @code{LOGICAL} type.
1026 @item @var{J} @tab The type shall be the same as the type of @var{I}.
1029 @item @emph{Return value}:
1030 The return type is either a scalar @code{INTEGER} or a scalar
1031 @code{LOGICAL}. If the kind type parameters differ, then the
1032 smaller kind type is implicitly converted to larger kind, and the
1033 return has the larger kind.
1035 @item @emph{Example}:
1038 LOGICAL :: T = .TRUE., F = .FALSE.
1040 DATA a / Z'F' /, b / Z'3' /
1042 WRITE (*,*) AND(T, T), AND(T, F), AND(F, T), AND(F, F)
1043 WRITE (*,*) AND(a, b)
1047 @item @emph{See also}:
1048 Fortran 95 elemental function: @ref{IAND}
1054 @section @code{ANINT} --- Nearest whole number
1058 @cindex rounding, ceiling
1061 @item @emph{Description}:
1062 @code{ANINT(A [, KIND])} rounds its argument to the nearest whole number.
1064 @item @emph{Standard}:
1065 Fortran 77 and later
1070 @item @emph{Syntax}:
1071 @code{RESULT = ANINT(A [, KIND])}
1073 @item @emph{Arguments}:
1074 @multitable @columnfractions .15 .70
1075 @item @var{A} @tab The type of the argument shall be @code{REAL}.
1076 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
1077 expression indicating the kind parameter of the result.
1080 @item @emph{Return value}:
1081 The return value is of type real with the kind type parameter of the
1082 argument if the optional @var{KIND} is absent; otherwise, the kind
1083 type parameter will be given by @var{KIND}. If @var{A} is greater than
1084 zero, @code{ANINT(A)} returns @code{AINT(X+0.5)}. If @var{A} is
1085 less than or equal to zero then it returns @code{AINT(X-0.5)}.
1087 @item @emph{Example}:
1094 print *, anint(x4), dnint(x8)
1096 end program test_anint
1099 @item @emph{Specific names}:
1100 @multitable @columnfractions .20 .20 .20 .25
1101 @item Name @tab Argument @tab Return type @tab Standard
1102 @item @code{AINT(A)} @tab @code{REAL(4) A} @tab @code{REAL(4)} @tab Fortran 77 and later
1103 @item @code{DNINT(A)} @tab @code{REAL(8) A} @tab @code{REAL(8)} @tab Fortran 77 and later
1110 @section @code{ANY} --- Any value in @var{MASK} along @var{DIM} is true
1112 @cindex array, apply condition
1113 @cindex array, condition testing
1116 @item @emph{Description}:
1117 @code{ANY(MASK [, DIM])} determines if any of the values in the logical array
1118 @var{MASK} along dimension @var{DIM} are @code{.TRUE.}.
1120 @item @emph{Standard}:
1121 Fortran 95 and later
1124 Transformational function
1126 @item @emph{Syntax}:
1127 @code{RESULT = ANY(MASK [, DIM])}
1129 @item @emph{Arguments}:
1130 @multitable @columnfractions .15 .70
1131 @item @var{MASK} @tab The type of the argument shall be @code{LOGICAL} and
1132 it shall not be scalar.
1133 @item @var{DIM} @tab (Optional) @var{DIM} shall be a scalar integer
1134 with a value that lies between one and the rank of @var{MASK}.
1137 @item @emph{Return value}:
1138 @code{ANY(MASK)} returns a scalar value of type @code{LOGICAL} where
1139 the kind type parameter is the same as the kind type parameter of
1140 @var{MASK}. If @var{DIM} is present, then @code{ANY(MASK, DIM)} returns
1141 an array with the rank of @var{MASK} minus 1. The shape is determined from
1142 the shape of @var{MASK} where the @var{DIM} dimension is elided.
1146 @code{ANY(MASK)} is true if any element of @var{MASK} is true;
1147 otherwise, it is false. It also is false if @var{MASK} has zero size.
1149 If the rank of @var{MASK} is one, then @code{ANY(MASK,DIM)} is equivalent
1150 to @code{ANY(MASK)}. If the rank is greater than one, then @code{ANY(MASK,DIM)}
1151 is determined by applying @code{ANY} to the array sections.
1154 @item @emph{Example}:
1158 l = any((/.true., .true., .true./))
1163 integer a(2,3), b(2,3)
1167 print *, any(a .eq. b, 1)
1168 print *, any(a .eq. b, 2)
1169 end subroutine section
1170 end program test_any
1177 @section @code{ASIN} --- Arcsine function
1180 @cindex trigonometric function, sine, inverse
1181 @cindex sine, inverse
1184 @item @emph{Description}:
1185 @code{ASIN(X)} computes the arcsine of its @var{X} (inverse of @code{SIN(X)}).
1187 @item @emph{Standard}:
1188 Fortran 77 and later, for a complex argument Fortran 2008 or later
1193 @item @emph{Syntax}:
1194 @code{RESULT = ASIN(X)}
1196 @item @emph{Arguments}:
1197 @multitable @columnfractions .15 .70
1198 @item @var{X} @tab The type shall be either @code{REAL} and a magnitude that is
1199 less than or equal to one - or be @code{COMPLEX}.
1202 @item @emph{Return value}:
1203 The return value is of the same type and kind as @var{X}.
1204 The real part of the result is in radians and lies in the range
1205 @math{-\pi/2 \leq \Re \asin(x) \leq \pi/2}.
1207 @item @emph{Example}:
1210 real(8) :: x = 0.866_8
1212 end program test_asin
1215 @item @emph{Specific names}:
1216 @multitable @columnfractions .20 .20 .20 .25
1217 @item Name @tab Argument @tab Return type @tab Standard
1218 @item @code{ASIN(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab Fortran 77 and later
1219 @item @code{DASIN(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab Fortran 77 and later
1222 @item @emph{See also}:
1223 Inverse function: @ref{SIN}
1230 @section @code{ASINH} --- Hyperbolic arcsine function
1233 @cindex area hyperbolic sine
1234 @cindex hyperbolic arcsine
1235 @cindex hyperbolic function, sine, inverse
1236 @cindex sine, hyperbolic, inverse
1239 @item @emph{Description}:
1240 @code{ASINH(X)} computes the hyperbolic arcsine of @var{X} (inverse of @code{SINH(X)}).
1242 @item @emph{Standard}:
1243 Fortran 2008 and later
1248 @item @emph{Syntax}:
1249 @code{RESULT = ASINH(X)}
1251 @item @emph{Arguments}:
1252 @multitable @columnfractions .15 .70
1253 @item @var{X} @tab The type shall be @code{REAL} or @code{COMPLEX}.
1256 @item @emph{Return value}:
1257 The return value is of the same type and kind as @var{X}. If @var{X} is
1258 complex, the imaginary part of the result is in radians and lies between
1259 @math{-\pi/2 \leq \Im \asinh(x) \leq \pi/2}.
1261 @item @emph{Example}:
1264 REAL(8), DIMENSION(3) :: x = (/ -1.0, 0.0, 1.0 /)
1265 WRITE (*,*) ASINH(x)
1269 @item @emph{Specific names}:
1270 @multitable @columnfractions .20 .20 .20 .25
1271 @item Name @tab Argument @tab Return type @tab Standard
1272 @item @code{DASINH(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU extension.
1275 @item @emph{See also}:
1276 Inverse function: @ref{SINH}
1282 @section @code{ASSOCIATED} --- Status of a pointer or pointer/target pair
1284 @cindex pointer, status
1285 @cindex association status
1288 @item @emph{Description}:
1289 @code{ASSOCIATED(POINTER [, TARGET])} determines the status of the pointer
1290 @var{POINTER} or if @var{POINTER} is associated with the target @var{TARGET}.
1292 @item @emph{Standard}:
1293 Fortran 95 and later
1298 @item @emph{Syntax}:
1299 @code{RESULT = ASSOCIATED(POINTER [, TARGET])}
1301 @item @emph{Arguments}:
1302 @multitable @columnfractions .15 .70
1303 @item @var{POINTER} @tab @var{POINTER} shall have the @code{POINTER} attribute
1304 and it can be of any type.
1305 @item @var{TARGET} @tab (Optional) @var{TARGET} shall be a pointer or
1306 a target. It must have the same type, kind type parameter, and
1307 array rank as @var{POINTER}.
1309 The association status of neither @var{POINTER} nor @var{TARGET} shall be
1312 @item @emph{Return value}:
1313 @code{ASSOCIATED(POINTER)} returns a scalar value of type @code{LOGICAL(4)}.
1314 There are several cases:
1316 @item (A) When the optional @var{TARGET} is not present then
1317 @code{ASSOCIATED(POINTER)} is true if @var{POINTER} is associated with a target; otherwise, it returns false.
1318 @item (B) If @var{TARGET} is present and a scalar target, the result is true if
1319 @var{TARGET} is not a zero-sized storage sequence and the target associated with @var{POINTER} occupies the same storage units. If @var{POINTER} is
1320 disassociated, the result is false.
1321 @item (C) If @var{TARGET} is present and an array target, the result is true if
1322 @var{TARGET} and @var{POINTER} have the same shape, are not zero-sized arrays,
1323 are arrays whose elements are not zero-sized storage sequences, and
1324 @var{TARGET} and @var{POINTER} occupy the same storage units in array element
1326 As in case(B), the result is false, if @var{POINTER} is disassociated.
1327 @item (D) If @var{TARGET} is present and an scalar pointer, the result is true
1328 if @var{TARGET} is associated with @var{POINTER}, the target associated with
1329 @var{TARGET} are not zero-sized storage sequences and occupy the same storage
1331 The result is false, if either @var{TARGET} or @var{POINTER} is disassociated.
1332 @item (E) If @var{TARGET} is present and an array pointer, the result is true if
1333 target associated with @var{POINTER} and the target associated with @var{TARGET}
1334 have the same shape, are not zero-sized arrays, are arrays whose elements are
1335 not zero-sized storage sequences, and @var{TARGET} and @var{POINTER} occupy
1336 the same storage units in array element order.
1337 The result is false, if either @var{TARGET} or @var{POINTER} is disassociated.
1340 @item @emph{Example}:
1342 program test_associated
1344 real, target :: tgt(2) = (/1., 2./)
1345 real, pointer :: ptr(:)
1347 if (associated(ptr) .eqv. .false.) call abort
1348 if (associated(ptr,tgt) .eqv. .false.) call abort
1349 end program test_associated
1352 @item @emph{See also}:
1359 @section @code{ATAN} --- Arctangent function
1362 @cindex trigonometric function, tangent, inverse
1363 @cindex tangent, inverse
1366 @item @emph{Description}:
1367 @code{ATAN(X)} computes the arctangent of @var{X}.
1369 @item @emph{Standard}:
1370 Fortran 77 and later, for a complex argument and for two arguments
1371 Fortran 2008 or later
1376 @item @emph{Syntax}:
1377 @code{RESULT = ATAN(X)}
1378 @code{RESULT = ATAN(Y, X)}
1380 @item @emph{Arguments}:
1381 @multitable @columnfractions .15 .70
1382 @item @var{X} @tab The type shall be @code{REAL} or @code{COMPLEX};
1383 if @var{Y} is present, @var{X} shall be REAL.
1384 @item @var{Y} shall be of the same type and kind as @var{X}.
1387 @item @emph{Return value}:
1388 The return value is of the same type and kind as @var{X}.
1389 If @var{Y} is present, the result is identical to @code{ATAN2(Y,X)}.
1390 Otherwise, it the arcus tangent of @var{X}, where the real part of
1391 the result is in radians and lies in the range
1392 @math{-\pi/2 \leq \Re \atan(x) \leq \pi/2}.
1394 @item @emph{Example}:
1397 real(8) :: x = 2.866_8
1399 end program test_atan
1402 @item @emph{Specific names}:
1403 @multitable @columnfractions .20 .20 .20 .25
1404 @item Name @tab Argument @tab Return type @tab Standard
1405 @item @code{ATAN(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab Fortran 77 and later
1406 @item @code{DATAN(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab Fortran 77 and later
1409 @item @emph{See also}:
1410 Inverse function: @ref{TAN}
1417 @section @code{ATAN2} --- Arctangent function
1420 @cindex trigonometric function, tangent, inverse
1421 @cindex tangent, inverse
1424 @item @emph{Description}:
1425 @code{ATAN2(Y, X)} computes the principal value of the argument
1426 function of the complex number @math{X + i Y}. This function can
1427 be used to transform from carthesian into polar coordinates and
1428 allows to determine the angle in the correct quadrant.
1430 @item @emph{Standard}:
1431 Fortran 77 and later
1436 @item @emph{Syntax}:
1437 @code{RESULT = ATAN2(Y, X)}
1439 @item @emph{Arguments}:
1440 @multitable @columnfractions .15 .70
1441 @item @var{Y} @tab The type shall be @code{REAL}.
1442 @item @var{X} @tab The type and kind type parameter shall be the same as @var{Y}.
1443 If @var{Y} is zero, then @var{X} must be nonzero.
1446 @item @emph{Return value}:
1447 The return value has the same type and kind type parameter as @var{Y}.
1448 It is the principal value of the complex number @math{X + i Y}. If
1449 @var{X} is nonzero, then it lies in the range @math{-\pi \le \atan (x) \leq \pi}.
1450 The sign is positive if @var{Y} is positive. If @var{Y} is zero, then
1451 the return value is zero if @var{X} is positive and @math{\pi} if @var{X}
1452 is negative. Finally, if @var{X} is zero, then the magnitude of the result
1455 @item @emph{Example}:
1458 real(4) :: x = 1.e0_4, y = 0.5e0_4
1460 end program test_atan2
1463 @item @emph{Specific names}:
1464 @multitable @columnfractions .20 .20 .20 .25
1465 @item Name @tab Argument @tab Return type @tab Standard
1466 @item @code{ATAN2(X, Y)} @tab @code{REAL(4) X, Y} @tab @code{REAL(4)} @tab Fortran 77 and later
1467 @item @code{DATAN2(X, Y)} @tab @code{REAL(8) X, Y} @tab @code{REAL(8)} @tab Fortran 77 and later
1474 @section @code{ATANH} --- Hyperbolic arctangent function
1477 @cindex area hyperbolic tangent
1478 @cindex hyperbolic arctangent
1479 @cindex hyperbolic function, tangent, inverse
1480 @cindex tangent, hyperbolic, inverse
1483 @item @emph{Description}:
1484 @code{ATANH(X)} computes the hyperbolic arctangent of @var{X} (inverse
1487 @item @emph{Standard}:
1488 Fortran 2008 and later
1493 @item @emph{Syntax}:
1494 @code{RESULT = ATANH(X)}
1496 @item @emph{Arguments}:
1497 @multitable @columnfractions .15 .70
1498 @item @var{X} @tab The type shall be @code{REAL} or @code{COMPLEX}.
1501 @item @emph{Return value}:
1502 The return value has same type and kind as @var{X}. If @var{X} is
1503 complex, the imaginary part of the result is in radians and lies between
1504 @math{-\pi/2 \leq \Im \atanh(x) \leq \pi/2}.
1506 @item @emph{Example}:
1509 REAL, DIMENSION(3) :: x = (/ -1.0, 0.0, 1.0 /)
1510 WRITE (*,*) ATANH(x)
1514 @item @emph{Specific names}:
1515 @multitable @columnfractions .20 .20 .20 .25
1516 @item Name @tab Argument @tab Return type @tab Standard
1517 @item @code{DATANH(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU extension
1520 @item @emph{See also}:
1521 Inverse function: @ref{TANH}
1527 @section @code{BESSEL_J0} --- Bessel function of the first kind of order 0
1531 @cindex Bessel function, first kind
1534 @item @emph{Description}:
1535 @code{BESSEL_J0(X)} computes the Bessel function of the first kind of
1536 order 0 of @var{X}. This function is available under the name
1537 @code{BESJ0} as a GNU extension.
1539 @item @emph{Standard}:
1540 Fortran 2008 and later
1545 @item @emph{Syntax}:
1546 @code{RESULT = BESSEL_J0(X)}
1548 @item @emph{Arguments}:
1549 @multitable @columnfractions .15 .70
1550 @item @var{X} @tab The type shall be @code{REAL}, and it shall be scalar.
1553 @item @emph{Return value}:
1554 The return value is of type @code{REAL} and lies in the
1555 range @math{ - 0.4027... \leq Bessel (0,x) \leq 1}. It has the same
1558 @item @emph{Example}:
1561 real(8) :: x = 0.0_8
1563 end program test_besj0
1566 @item @emph{Specific names}:
1567 @multitable @columnfractions .20 .20 .20 .25
1568 @item Name @tab Argument @tab Return type @tab Standard
1569 @item @code{DBESJ0(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU extension
1576 @section @code{BESSEL_J1} --- Bessel function of the first kind of order 1
1580 @cindex Bessel function, first kind
1583 @item @emph{Description}:
1584 @code{BESSEL_J1(X)} computes the Bessel function of the first kind of
1585 order 1 of @var{X}. This function is available under the name
1586 @code{BESJ1} as a GNU extension.
1588 @item @emph{Standard}:
1594 @item @emph{Syntax}:
1595 @code{RESULT = BESSEL_J1(X)}
1597 @item @emph{Arguments}:
1598 @multitable @columnfractions .15 .70
1599 @item @var{X} @tab The type shall be @code{REAL}, and it shall be scalar.
1602 @item @emph{Return value}:
1603 The return value is of type @code{REAL} and it lies in the
1604 range @math{ - 0.5818... \leq Bessel (0,x) \leq 0.5818 }. It has the same
1607 @item @emph{Example}:
1610 real(8) :: x = 1.0_8
1612 end program test_besj1
1615 @item @emph{Specific names}:
1616 @multitable @columnfractions .20 .20 .20 .25
1617 @item Name @tab Argument @tab Return type @tab Standard
1618 @item @code{DBESJ1(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU extension
1625 @section @code{BESSEL_JN} --- Bessel function of the first kind
1629 @cindex Bessel function, first kind
1632 @item @emph{Description}:
1633 @code{BESSEL_JN(N, X)} computes the Bessel function of the first kind of
1634 order @var{N} of @var{X}. This function is available under the name
1635 @code{BESJN} as a GNU extension.
1637 If both arguments are arrays, their ranks and shapes shall conform.
1639 @item @emph{Standard}:
1640 Fortran 2008 and later
1645 @item @emph{Syntax}:
1646 @code{RESULT = BESSEL_JN(N, X)}
1648 @item @emph{Arguments}:
1649 @multitable @columnfractions .15 .70
1650 @item @var{N} @tab Shall be a scalar or an array of type @code{INTEGER}.
1651 @item @var{X} @tab Shall be a scalar or an array of type @code{REAL}.
1654 @item @emph{Return value}:
1655 The return value is a scalar of type @code{REAL}. It has the same
1658 @item @emph{Example}:
1661 real(8) :: x = 1.0_8
1663 end program test_besjn
1666 @item @emph{Specific names}:
1667 @multitable @columnfractions .20 .20 .20 .25
1668 @item Name @tab Argument @tab Return type @tab Standard
1669 @item @code{DBESJN(N, X)} @tab @code{INTEGER N} @tab @code{REAL(8)} @tab GNU extension
1670 @item @tab @code{REAL(8) X} @tab @tab
1677 @section @code{BESSEL_Y0} --- Bessel function of the second kind of order 0
1681 @cindex Bessel function, second kind
1684 @item @emph{Description}:
1685 @code{BESSEL_Y0(X)} computes the Bessel function of the second kind of
1686 order 0 of @var{X}. This function is available under the name
1687 @code{BESY0} as a GNU extension.
1689 @item @emph{Standard}:
1690 Fortran 2008 and later
1695 @item @emph{Syntax}:
1696 @code{RESULT = BESSEL_Y0(X)}
1698 @item @emph{Arguments}:
1699 @multitable @columnfractions .15 .70
1700 @item @var{X} @tab The type shall be @code{REAL}, and it shall be scalar.
1703 @item @emph{Return value}:
1704 The return value is a scalar of type @code{REAL}. It has the same
1707 @item @emph{Example}:
1710 real(8) :: x = 0.0_8
1712 end program test_besy0
1715 @item @emph{Specific names}:
1716 @multitable @columnfractions .20 .20 .20 .25
1717 @item Name @tab Argument @tab Return type @tab Standard
1718 @item @code{DBESY0(X)}@tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU extension
1725 @section @code{BESSEL_Y1} --- Bessel function of the second kind of order 1
1729 @cindex Bessel function, second kind
1732 @item @emph{Description}:
1733 @code{BESSEL_Y1(X)} computes the Bessel function of the second kind of
1734 order 1 of @var{X}. This function is available under the name
1735 @code{BESY1} as a GNU extension.
1737 @item @emph{Standard}:
1738 Fortran 2008 and later
1743 @item @emph{Syntax}:
1744 @code{RESULT = BESSEL_Y1(X)}
1746 @item @emph{Arguments}:
1747 @multitable @columnfractions .15 .70
1748 @item @var{X} @tab The type shall be @code{REAL}, and it shall be scalar.
1751 @item @emph{Return value}:
1752 The return value is a scalar of type @code{REAL}. It has the same
1755 @item @emph{Example}:
1758 real(8) :: x = 1.0_8
1760 end program test_besy1
1763 @item @emph{Specific names}:
1764 @multitable @columnfractions .20 .20 .20 .25
1765 @item Name @tab Argument @tab Return type @tab Standard
1766 @item @code{DBESY1(X)}@tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU extension
1773 @section @code{BESSEL_YN} --- Bessel function of the second kind
1777 @cindex Bessel function, second kind
1780 @item @emph{Description}:
1781 @code{BESSEL_YN(N, X)} computes the Bessel function of the second kind of
1782 order @var{N} of @var{X}. This function is available under the name
1783 @code{BESYN} as a GNU extension.
1785 If both arguments are arrays, their ranks and shapes shall conform.
1787 @item @emph{Standard}:
1788 Fortran 2008 and later
1793 @item @emph{Syntax}:
1794 @code{RESULT = BESSEL_YN(N, X)}
1796 @item @emph{Arguments}:
1797 @multitable @columnfractions .15 .70
1798 @item @var{N} @tab Shall be a scalar or an array of type @code{INTEGER}.
1799 @item @var{X} @tab Shall be a scalar or an array of type @code{REAL}.
1802 @item @emph{Return value}:
1803 The return value is a scalar of type @code{REAL}. It has the same
1806 @item @emph{Example}:
1809 real(8) :: x = 1.0_8
1811 end program test_besyn
1814 @item @emph{Specific names}:
1815 @multitable @columnfractions .20 .20 .20 .25
1816 @item Name @tab Argument @tab Return type @tab Standard
1817 @item @code{DBESYN(N,X)} @tab @code{INTEGER N} @tab @code{REAL(8)} @tab GNU extension
1818 @item @tab @code{REAL(8) X} @tab @tab
1825 @section @code{BIT_SIZE} --- Bit size inquiry function
1827 @cindex bits, number of
1828 @cindex size of a variable, in bits
1831 @item @emph{Description}:
1832 @code{BIT_SIZE(I)} returns the number of bits (integer precision plus sign bit)
1833 represented by the type of @var{I}. The result of @code{BIT_SIZE(I)} is
1834 independent of the actual value of @var{I}.
1836 @item @emph{Standard}:
1837 Fortran 95 and later
1842 @item @emph{Syntax}:
1843 @code{RESULT = BIT_SIZE(I)}
1845 @item @emph{Arguments}:
1846 @multitable @columnfractions .15 .70
1847 @item @var{I} @tab The type shall be @code{INTEGER}.
1850 @item @emph{Return value}:
1851 The return value is of type @code{INTEGER}
1853 @item @emph{Example}:
1855 program test_bit_size
1860 end program test_bit_size
1867 @section @code{BTEST} --- Bit test function
1869 @cindex bits, testing
1872 @item @emph{Description}:
1873 @code{BTEST(I,POS)} returns logical @code{.TRUE.} if the bit at @var{POS}
1874 in @var{I} is set. The counting of the bits starts at 0.
1876 @item @emph{Standard}:
1877 Fortran 95 and later
1882 @item @emph{Syntax}:
1883 @code{RESULT = BTEST(I, POS)}
1885 @item @emph{Arguments}:
1886 @multitable @columnfractions .15 .70
1887 @item @var{I} @tab The type shall be @code{INTEGER}.
1888 @item @var{POS} @tab The type shall be @code{INTEGER}.
1891 @item @emph{Return value}:
1892 The return value is of type @code{LOGICAL}
1894 @item @emph{Example}:
1897 integer :: i = 32768 + 1024 + 64
1901 bool = btest(i, pos)
1904 end program test_btest
1910 @section @code{C_ASSOCIATED} --- Status of a C pointer
1911 @fnindex C_ASSOCIATED
1912 @cindex association status, C pointer
1913 @cindex pointer, C association status
1916 @item @emph{Description}:
1917 @code{C_ASSOCIATED(c_prt_1[, c_ptr_2])} determines the status of the C pointer
1918 @var{c_ptr_1} or if @var{c_ptr_1} is associated with the target @var{c_ptr_2}.
1920 @item @emph{Standard}:
1921 Fortran 2003 and later
1926 @item @emph{Syntax}:
1927 @code{RESULT = C_ASSOCIATED(c_prt_1[, c_ptr_2])}
1929 @item @emph{Arguments}:
1930 @multitable @columnfractions .15 .70
1931 @item @var{c_ptr_1} @tab Scalar of the type @code{C_PTR} or @code{C_FUNPTR}.
1932 @item @var{c_ptr_2} @tab (Optional) Scalar of the same type as @var{c_ptr_1}.
1935 @item @emph{Return value}:
1936 The return value is of type @code{LOGICAL}; it is @code{.false.} if either
1937 @var{c_ptr_1} is a C NULL pointer or if @var{c_ptr1} and @var{c_ptr_2}
1938 point to different addresses.
1940 @item @emph{Example}:
1942 subroutine association_test(a,b)
1943 use iso_c_binding, only: c_associated, c_loc, c_ptr
1947 if(c_associated(b, c_loc(a))) &
1948 stop 'b and a do not point to same target'
1949 end subroutine association_test
1952 @item @emph{See also}:
1953 @ref{C_LOC}, @ref{C_FUNLOC}
1958 @section @code{C_FUNLOC} --- Obtain the C address of a procedure
1960 @cindex pointer, C address of procedures
1963 @item @emph{Description}:
1964 @code{C_FUNLOC(x)} determines the C address of the argument.
1966 @item @emph{Standard}:
1967 Fortran 2003 and later
1972 @item @emph{Syntax}:
1973 @code{RESULT = C_FUNLOC(x)}
1975 @item @emph{Arguments}:
1976 @multitable @columnfractions .15 .70
1977 @item @var{x} @tab Interoperable function or pointer to such function.
1980 @item @emph{Return value}:
1981 The return value is of type @code{C_FUNPTR} and contains the C address
1984 @item @emph{Example}:
1990 subroutine sub(a) bind(c)
2000 subroutine my_routine(p) bind(c,name='myC_func')
2002 type(c_funptr), intent(in) :: p
2005 call my_routine(c_funloc(sub))
2009 @item @emph{See also}:
2010 @ref{C_ASSOCIATED}, @ref{C_LOC}, @ref{C_F_POINTER}, @ref{C_F_PROCPOINTER}
2014 @node C_F_PROCPOINTER
2015 @section @code{C_F_PROCPOINTER} --- Convert C into Fortran procedure pointer
2016 @fnindex C_F_PROCPOINTER
2017 @cindex pointer, C address of pointers
2020 @item @emph{Description}:
2021 @code{C_F_PROCPOINTER(CPTR, FPTR)} Assign the target of the C function pointer
2022 @var{CPTR} to the Fortran procedure pointer @var{FPTR}.
2024 @item @emph{Standard}:
2025 Fortran 2003 and later
2030 @item @emph{Syntax}:
2031 @code{CALL C_F_PROCPOINTER(cptr, fptr)}
2033 @item @emph{Arguments}:
2034 @multitable @columnfractions .15 .70
2035 @item @var{CPTR} @tab scalar of the type @code{C_FUNPTR}. It is
2037 @item @var{FPTR} @tab procedure pointer interoperable with @var{cptr}. It is
2041 @item @emph{Example}:
2049 real(c_float), intent(in) :: a
2050 real(c_float) :: func
2054 function getIterFunc() bind(c,name="getIterFunc")
2056 type(c_funptr) :: getIterFunc
2059 type(c_funptr) :: cfunptr
2060 procedure(func), pointer :: myFunc
2061 cfunptr = getIterFunc()
2062 call c_f_procpointer(cfunptr, myFunc)
2066 @item @emph{See also}:
2067 @ref{C_LOC}, @ref{C_F_POINTER}
2072 @section @code{C_F_POINTER} --- Convert C into Fortran pointer
2073 @fnindex C_F_POINTER
2074 @cindex pointer, convert C to Fortran
2077 @item @emph{Description}:
2078 @code{C_F_POINTER(CPTR, FPTR[, SHAPE])} Assign the target the C pointer
2079 @var{CPTR} to the Fortran pointer @var{FPTR} and specify its
2082 @item @emph{Standard}:
2083 Fortran 2003 and later
2088 @item @emph{Syntax}:
2089 @code{CALL C_F_POINTER(CPTR, FPTR[, SHAPE])}
2091 @item @emph{Arguments}:
2092 @multitable @columnfractions .15 .70
2093 @item @var{CPTR} @tab scalar of the type @code{C_PTR}. It is
2095 @item @var{FPTR} @tab pointer interoperable with @var{cptr}. It is
2097 @item @var{SHAPE} @tab (Optional) Rank-one array of type @code{INTEGER}
2098 with @code{INTENT(IN)}. It shall be present
2099 if and only if @var{fptr} is an array. The size
2100 must be equal to the rank of @var{fptr}.
2103 @item @emph{Example}:
2109 subroutine my_routine(p) bind(c,name='myC_func')
2111 type(c_ptr), intent(out) :: p
2115 real,pointer :: a(:)
2116 call my_routine(cptr)
2117 call c_f_pointer(cptr, a, [12])
2121 @item @emph{See also}:
2122 @ref{C_LOC}, @ref{C_F_PROCPOINTER}
2127 @section @code{C_LOC} --- Obtain the C address of an object
2129 @cindex procedure pointer, convert C to Fortran
2132 @item @emph{Description}:
2133 @code{C_LOC(X)} determines the C address of the argument.
2135 @item @emph{Standard}:
2136 Fortran 2003 and later
2141 @item @emph{Syntax}:
2142 @code{RESULT = C_LOC(X)}
2144 @item @emph{Arguments}:
2145 @multitable @columnfractions .15 .70
2146 @item @var{X} @tab Associated scalar pointer or interoperable scalar
2147 or allocated allocatable variable with @code{TARGET} attribute.
2150 @item @emph{Return value}:
2151 The return value is of type @code{C_PTR} and contains the C address
2154 @item @emph{Example}:
2156 subroutine association_test(a,b)
2157 use iso_c_binding, only: c_associated, c_loc, c_ptr
2161 if(c_associated(b, c_loc(a))) &
2162 stop 'b and a do not point to same target'
2163 end subroutine association_test
2166 @item @emph{See also}:
2167 @ref{C_ASSOCIATED}, @ref{C_FUNLOC}, @ref{C_F_POINTER}, @ref{C_F_PROCPOINTER}
2172 @section @code{C_SIZEOF} --- Size in bytes of an expression
2174 @cindex expression size
2175 @cindex size of an expression
2178 @item @emph{Description}:
2179 @code{C_SIZEOF(X)} calculates the number of bytes of storage the
2180 expression @code{X} occupies.
2182 @item @emph{Standard}:
2188 @item @emph{Syntax}:
2189 @code{N = C_SIZEOF(X)}
2191 @item @emph{Arguments}:
2192 @multitable @columnfractions .15 .70
2193 @item @var{X} @tab The argument shall be of any type, rank or shape.
2196 @item @emph{Return value}:
2197 The return value is of type integer and of the system-dependent kind
2198 @var{C_SIZE_T} (from the @var{ISO_C_BINDING} module). Its value is the
2199 number of bytes occupied by the argument. If the argument has the
2200 @code{POINTER} attribute, the number of bytes of the storage area pointed
2201 to is returned. If the argument is of a derived type with @code{POINTER}
2202 or @code{ALLOCATABLE} components, the return value doesn't account for
2203 the sizes of the data pointed to by these components.
2205 @item @emph{Example}:
2209 real(c_float) :: r, s(5)
2210 print *, (c_sizeof(s)/c_sizeof(r) == 5)
2213 The example will print @code{.TRUE.} unless you are using a platform
2214 where default @code{REAL} variables are unusually padded.
2216 @item @emph{See also}:
2222 @section @code{CEILING} --- Integer ceiling function
2225 @cindex rounding, ceiling
2228 @item @emph{Description}:
2229 @code{CEILING(A)} returns the least integer greater than or equal to @var{A}.
2231 @item @emph{Standard}:
2232 Fortran 95 and later
2237 @item @emph{Syntax}:
2238 @code{RESULT = CEILING(A [, KIND])}
2240 @item @emph{Arguments}:
2241 @multitable @columnfractions .15 .70
2242 @item @var{A} @tab The type shall be @code{REAL}.
2243 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
2244 expression indicating the kind parameter of the result.
2247 @item @emph{Return value}:
2248 The return value is of type @code{INTEGER(KIND)} if @var{KIND} is present
2249 and a default-kind @code{INTEGER} otherwise.
2251 @item @emph{Example}:
2253 program test_ceiling
2256 print *, ceiling(x) ! returns 64
2257 print *, ceiling(y) ! returns -63
2258 end program test_ceiling
2261 @item @emph{See also}:
2262 @ref{FLOOR}, @ref{NINT}
2269 @section @code{CHAR} --- Character conversion function
2271 @cindex conversion, to character
2274 @item @emph{Description}:
2275 @code{CHAR(I [, KIND])} returns the character represented by the integer @var{I}.
2277 @item @emph{Standard}:
2278 Fortran 77 and later
2283 @item @emph{Syntax}:
2284 @code{RESULT = CHAR(I [, KIND])}
2286 @item @emph{Arguments}:
2287 @multitable @columnfractions .15 .70
2288 @item @var{I} @tab The type shall be @code{INTEGER}.
2289 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
2290 expression indicating the kind parameter of the result.
2293 @item @emph{Return value}:
2294 The return value is of type @code{CHARACTER(1)}
2296 @item @emph{Example}:
2302 print *, i, c ! returns 'J'
2303 end program test_char
2306 @item @emph{Specific names}:
2307 @multitable @columnfractions .20 .20 .20 .25
2308 @item Name @tab Argument @tab Return type @tab Standard
2309 @item @code{CHAR(I)} @tab @code{INTEGER I} @tab @code{CHARACTER(LEN=1)} @tab F77 and later
2313 See @ref{ICHAR} for a discussion of converting between numerical values
2314 and formatted string representations.
2316 @item @emph{See also}:
2317 @ref{ACHAR}, @ref{IACHAR}, @ref{ICHAR}
2324 @section @code{CHDIR} --- Change working directory
2326 @cindex system, working directory
2329 @item @emph{Description}:
2330 Change current working directory to a specified path.
2332 This intrinsic is provided in both subroutine and function forms; however,
2333 only one form can be used in any given program unit.
2335 @item @emph{Standard}:
2339 Subroutine, function
2341 @item @emph{Syntax}:
2342 @multitable @columnfractions .80
2343 @item @code{CALL CHDIR(NAME [, STATUS])}
2344 @item @code{STATUS = CHDIR(NAME)}
2347 @item @emph{Arguments}:
2348 @multitable @columnfractions .15 .70
2349 @item @var{NAME} @tab The type shall be @code{CHARACTER} of default
2350 kind and shall specify a valid path within the file system.
2351 @item @var{STATUS} @tab (Optional) @code{INTEGER} status flag of the default
2352 kind. Returns 0 on success, and a system specific and nonzero error code
2356 @item @emph{Example}:
2359 CHARACTER(len=255) :: path
2361 WRITE(*,*) TRIM(path)
2364 WRITE(*,*) TRIM(path)
2368 @item @emph{See also}:
2375 @section @code{CHMOD} --- Change access permissions of files
2377 @cindex file system, change access mode
2380 @item @emph{Description}:
2381 @code{CHMOD} changes the permissions of a file. This function invokes
2382 @code{/bin/chmod} and might therefore not work on all platforms.
2384 This intrinsic is provided in both subroutine and function forms; however,
2385 only one form can be used in any given program unit.
2387 @item @emph{Standard}:
2391 Subroutine, function
2393 @item @emph{Syntax}:
2394 @multitable @columnfractions .80
2395 @item @code{CALL CHMOD(NAME, MODE[, STATUS])}
2396 @item @code{STATUS = CHMOD(NAME, MODE)}
2399 @item @emph{Arguments}:
2400 @multitable @columnfractions .15 .70
2402 @item @var{NAME} @tab Scalar @code{CHARACTER} of default kind with the
2403 file name. Trailing blanks are ignored unless the character
2404 @code{achar(0)} is present, then all characters up to and excluding
2405 @code{achar(0)} are used as the file name.
2407 @item @var{MODE} @tab Scalar @code{CHARACTER} of default kind giving the
2408 file permission. @var{MODE} uses the same syntax as the @var{MODE}
2409 argument of @code{/bin/chmod}.
2411 @item @var{STATUS} @tab (optional) scalar @code{INTEGER}, which is
2412 @code{0} on success and nonzero otherwise.
2415 @item @emph{Return value}:
2416 In either syntax, @var{STATUS} is set to @code{0} on success and nonzero
2419 @item @emph{Example}:
2420 @code{CHMOD} as subroutine
2425 call chmod('test.dat','u+x',status)
2426 print *, 'Status: ', status
2427 end program chmod_test
2429 @code{CHMOD} as function:
2434 status = chmod('test.dat','u+x')
2435 print *, 'Status: ', status
2436 end program chmod_test
2444 @section @code{CMPLX} --- Complex conversion function
2446 @cindex complex numbers, conversion to
2447 @cindex conversion, to complex
2450 @item @emph{Description}:
2451 @code{CMPLX(X [, Y [, KIND]])} returns a complex number where @var{X} is converted to
2452 the real component. If @var{Y} is present it is converted to the imaginary
2453 component. If @var{Y} is not present then the imaginary component is set to
2454 0.0. If @var{X} is complex then @var{Y} must not be present.
2456 @item @emph{Standard}:
2457 Fortran 77 and later
2462 @item @emph{Syntax}:
2463 @code{RESULT = CMPLX(X [, Y [, KIND]])}
2465 @item @emph{Arguments}:
2466 @multitable @columnfractions .15 .70
2467 @item @var{X} @tab The type may be @code{INTEGER}, @code{REAL},
2469 @item @var{Y} @tab (Optional; only allowed if @var{X} is not
2470 @code{COMPLEX}.) May be @code{INTEGER} or @code{REAL}.
2471 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
2472 expression indicating the kind parameter of the result.
2475 @item @emph{Return value}:
2476 The return value is of @code{COMPLEX} type, with a kind equal to
2477 @var{KIND} if it is specified. If @var{KIND} is not specified, the
2478 result is of the default @code{COMPLEX} kind, regardless of the kinds of
2479 @var{X} and @var{Y}.
2481 @item @emph{Example}:
2488 print *, z, cmplx(x)
2489 end program test_cmplx
2492 @item @emph{See also}:
2498 @node COMMAND_ARGUMENT_COUNT
2499 @section @code{COMMAND_ARGUMENT_COUNT} --- Get number of command line arguments
2500 @fnindex COMMAND_ARGUMENT_COUNT
2501 @cindex command-line arguments
2502 @cindex command-line arguments, number of
2503 @cindex arguments, to program
2506 @item @emph{Description}:
2507 @code{COMMAND_ARGUMENT_COUNT()} returns the number of arguments passed on the
2508 command line when the containing program was invoked.
2510 @item @emph{Standard}:
2511 Fortran 2003 and later
2516 @item @emph{Syntax}:
2517 @code{RESULT = COMMAND_ARGUMENT_COUNT()}
2519 @item @emph{Arguments}:
2520 @multitable @columnfractions .15 .70
2524 @item @emph{Return value}:
2525 The return value is an @code{INTEGER} of default kind.
2527 @item @emph{Example}:
2529 program test_command_argument_count
2531 count = command_argument_count()
2533 end program test_command_argument_count
2536 @item @emph{See also}:
2537 @ref{GET_COMMAND}, @ref{GET_COMMAND_ARGUMENT}
2543 @section @code{COMPLEX} --- Complex conversion function
2545 @cindex complex numbers, conversion to
2546 @cindex conversion, to complex
2549 @item @emph{Description}:
2550 @code{COMPLEX(X, Y)} returns a complex number where @var{X} is converted
2551 to the real component and @var{Y} is converted to the imaginary
2554 @item @emph{Standard}:
2560 @item @emph{Syntax}:
2561 @code{RESULT = COMPLEX(X, Y)}
2563 @item @emph{Arguments}:
2564 @multitable @columnfractions .15 .70
2565 @item @var{X} @tab The type may be @code{INTEGER} or @code{REAL}.
2566 @item @var{Y} @tab The type may be @code{INTEGER} or @code{REAL}.
2569 @item @emph{Return value}:
2570 If @var{X} and @var{Y} are both of @code{INTEGER} type, then the return
2571 value is of default @code{COMPLEX} type.
2573 If @var{X} and @var{Y} are of @code{REAL} type, or one is of @code{REAL}
2574 type and one is of @code{INTEGER} type, then the return value is of
2575 @code{COMPLEX} type with a kind equal to that of the @code{REAL}
2576 argument with the highest precision.
2578 @item @emph{Example}:
2580 program test_complex
2583 print *, complex(i, x)
2584 end program test_complex
2587 @item @emph{See also}:
2594 @section @code{CONJG} --- Complex conjugate function
2597 @cindex complex conjugate
2600 @item @emph{Description}:
2601 @code{CONJG(Z)} returns the conjugate of @var{Z}. If @var{Z} is @code{(x, y)}
2602 then the result is @code{(x, -y)}
2604 @item @emph{Standard}:
2605 Fortran 77 and later, has overloads that are GNU extensions
2610 @item @emph{Syntax}:
2613 @item @emph{Arguments}:
2614 @multitable @columnfractions .15 .70
2615 @item @var{Z} @tab The type shall be @code{COMPLEX}.
2618 @item @emph{Return value}:
2619 The return value is of type @code{COMPLEX}.
2621 @item @emph{Example}:
2624 complex :: z = (2.0, 3.0)
2625 complex(8) :: dz = (2.71_8, -3.14_8)
2630 end program test_conjg
2633 @item @emph{Specific names}:
2634 @multitable @columnfractions .20 .20 .20 .25
2635 @item Name @tab Argument @tab Return type @tab Standard
2636 @item @code{CONJG(Z)} @tab @code{COMPLEX Z} @tab @code{COMPLEX} @tab GNU extension
2637 @item @code{DCONJG(Z)} @tab @code{COMPLEX(8) Z} @tab @code{COMPLEX(8)} @tab GNU extension
2644 @section @code{COS} --- Cosine function
2650 @cindex trigonometric function, cosine
2654 @item @emph{Description}:
2655 @code{COS(X)} computes the cosine of @var{X}.
2657 @item @emph{Standard}:
2658 Fortran 77 and later, has overloads that are GNU extensions
2663 @item @emph{Syntax}:
2664 @code{RESULT = COS(X)}
2666 @item @emph{Arguments}:
2667 @multitable @columnfractions .15 .70
2668 @item @var{X} @tab The type shall be @code{REAL} or
2672 @item @emph{Return value}:
2673 The return value is of the same type and kind as @var{X}. The real part
2674 of the result is in radians. If @var{X} is of the type @code{REAL},
2675 the return value lies in the range @math{ -1 \leq \cos (x) \leq 1}.
2677 @item @emph{Example}:
2682 end program test_cos
2685 @item @emph{Specific names}:
2686 @multitable @columnfractions .20 .20 .20 .25
2687 @item Name @tab Argument @tab Return type @tab Standard
2688 @item @code{COS(X)} n@tab @code{REAL(4) X} @tab @code{REAL(4)} @tab Fortran 77 and later
2689 @item @code{DCOS(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab Fortran 77 and later
2690 @item @code{CCOS(X)} @tab @code{COMPLEX(4) X} @tab @code{COMPLEX(4)} @tab Fortran 77 and later
2691 @item @code{ZCOS(X)} @tab @code{COMPLEX(8) X} @tab @code{COMPLEX(8)} @tab GNU extension
2692 @item @code{CDCOS(X)} @tab @code{COMPLEX(8) X} @tab @code{COMPLEX(8)} @tab GNU extension
2695 @item @emph{See also}:
2696 Inverse function: @ref{ACOS}
2703 @section @code{COSH} --- Hyperbolic cosine function
2706 @cindex hyperbolic cosine
2707 @cindex hyperbolic function, cosine
2708 @cindex cosine, hyperbolic
2711 @item @emph{Description}:
2712 @code{COSH(X)} computes the hyperbolic cosine of @var{X}.
2714 @item @emph{Standard}:
2715 Fortran 77 and later, for a complex argument Fortran 2008 or later
2720 @item @emph{Syntax}:
2723 @item @emph{Arguments}:
2724 @multitable @columnfractions .15 .70
2725 @item @var{X} @tab The type shall be @code{REAL} or @code{COMPLEX}.
2728 @item @emph{Return value}:
2729 The return value has same type and kind as @var{X}. If @var{X} is
2730 complex, the imaginary part of the result is in radians. If @var{X}
2731 is @code{REAL}, the return value has a lower bound of one,
2732 @math{\cosh (x) \geq 1}.
2734 @item @emph{Example}:
2737 real(8) :: x = 1.0_8
2739 end program test_cosh
2742 @item @emph{Specific names}:
2743 @multitable @columnfractions .20 .20 .20 .25
2744 @item Name @tab Argument @tab Return type @tab Standard
2745 @item @code{COSH(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab Fortran 77 and later
2746 @item @code{DCOSH(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab Fortran 77 and later
2749 @item @emph{See also}:
2750 Inverse function: @ref{ACOSH}
2757 @section @code{COUNT} --- Count function
2759 @cindex array, conditionally count elements
2760 @cindex array, element counting
2761 @cindex array, number of elements
2764 @item @emph{Description}:
2766 Counts the number of @code{.TRUE.} elements in a logical @var{MASK},
2767 or, if the @var{DIM} argument is supplied, counts the number of
2768 elements along each row of the array in the @var{DIM} direction.
2769 If the array has zero size, or all of the elements of @var{MASK} are
2770 @code{.FALSE.}, then the result is @code{0}.
2772 @item @emph{Standard}:
2773 Fortran 95 and later, with @var{KIND} argument Fortran 2003 and later
2776 Transformational function
2778 @item @emph{Syntax}:
2779 @code{RESULT = COUNT(MASK [, DIM, KIND])}
2781 @item @emph{Arguments}:
2782 @multitable @columnfractions .15 .70
2783 @item @var{MASK} @tab The type shall be @code{LOGICAL}.
2784 @item @var{DIM} @tab (Optional) The type shall be @code{INTEGER}.
2785 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
2786 expression indicating the kind parameter of the result.
2789 @item @emph{Return value}:
2790 The return value is of type @code{INTEGER} and of kind @var{KIND}. If
2791 @var{KIND} is absent, the return value is of default integer kind.
2792 If @var{DIM} is present, the result is an array with a rank one less
2793 than the rank of @var{ARRAY}, and a size corresponding to the shape
2794 of @var{ARRAY} with the @var{DIM} dimension removed.
2796 @item @emph{Example}:
2799 integer, dimension(2,3) :: a, b
2800 logical, dimension(2,3) :: mask
2801 a = reshape( (/ 1, 2, 3, 4, 5, 6 /), (/ 2, 3 /))
2802 b = reshape( (/ 0, 7, 3, 4, 5, 8 /), (/ 2, 3 /))
2803 print '(3i3)', a(1,:)
2804 print '(3i3)', a(2,:)
2806 print '(3i3)', b(1,:)
2807 print '(3i3)', b(2,:)
2810 print '(3l3)', mask(1,:)
2811 print '(3l3)', mask(2,:)
2813 print '(3i3)', count(mask)
2815 print '(3i3)', count(mask, 1)
2817 print '(3i3)', count(mask, 2)
2818 end program test_count
2825 @section @code{CPU_TIME} --- CPU elapsed time in seconds
2827 @cindex time, elapsed
2830 @item @emph{Description}:
2831 Returns a @code{REAL} value representing the elapsed CPU time in
2832 seconds. This is useful for testing segments of code to determine
2835 If a time source is available, time will be reported with microsecond
2836 resolution. If no time source is available, @var{TIME} is set to
2839 Note that @var{TIME} may contain a, system dependent, arbitrary offset
2840 and may not start with @code{0.0}. For @code{CPU_TIME}, the absolute
2841 value is meaningless, only differences between subsequent calls to
2842 this subroutine, as shown in the example below, should be used.
2845 @item @emph{Standard}:
2846 Fortran 95 and later
2851 @item @emph{Syntax}:
2852 @code{CALL CPU_TIME(TIME)}
2854 @item @emph{Arguments}:
2855 @multitable @columnfractions .15 .70
2856 @item @var{TIME} @tab The type shall be @code{REAL} with @code{INTENT(OUT)}.
2859 @item @emph{Return value}:
2862 @item @emph{Example}:
2864 program test_cpu_time
2865 real :: start, finish
2866 call cpu_time(start)
2867 ! put code to test here
2868 call cpu_time(finish)
2869 print '("Time = ",f6.3," seconds.")',finish-start
2870 end program test_cpu_time
2873 @item @emph{See also}:
2874 @ref{SYSTEM_CLOCK}, @ref{DATE_AND_TIME}
2880 @section @code{CSHIFT} --- Circular shift elements of an array
2882 @cindex array, shift circularly
2883 @cindex array, permutation
2884 @cindex array, rotate
2887 @item @emph{Description}:
2888 @code{CSHIFT(ARRAY, SHIFT [, DIM])} performs a circular shift on elements of
2889 @var{ARRAY} along the dimension of @var{DIM}. If @var{DIM} is omitted it is
2890 taken to be @code{1}. @var{DIM} is a scalar of type @code{INTEGER} in the
2891 range of @math{1 \leq DIM \leq n)} where @math{n} is the rank of @var{ARRAY}.
2892 If the rank of @var{ARRAY} is one, then all elements of @var{ARRAY} are shifted
2893 by @var{SHIFT} places. If rank is greater than one, then all complete rank one
2894 sections of @var{ARRAY} along the given dimension are shifted. Elements
2895 shifted out one end of each rank one section are shifted back in the other end.
2897 @item @emph{Standard}:
2898 Fortran 95 and later
2901 Transformational function
2903 @item @emph{Syntax}:
2904 @code{RESULT = CSHIFT(ARRAY, SHIFT [, DIM])}
2906 @item @emph{Arguments}:
2907 @multitable @columnfractions .15 .70
2908 @item @var{ARRAY} @tab Shall be an array of any type.
2909 @item @var{SHIFT} @tab The type shall be @code{INTEGER}.
2910 @item @var{DIM} @tab The type shall be @code{INTEGER}.
2913 @item @emph{Return value}:
2914 Returns an array of same type and rank as the @var{ARRAY} argument.
2916 @item @emph{Example}:
2919 integer, dimension(3,3) :: a
2920 a = reshape( (/ 1, 2, 3, 4, 5, 6, 7, 8, 9 /), (/ 3, 3 /))
2921 print '(3i3)', a(1,:)
2922 print '(3i3)', a(2,:)
2923 print '(3i3)', a(3,:)
2924 a = cshift(a, SHIFT=(/1, 2, -1/), DIM=2)
2926 print '(3i3)', a(1,:)
2927 print '(3i3)', a(2,:)
2928 print '(3i3)', a(3,:)
2929 end program test_cshift
2936 @section @code{CTIME} --- Convert a time into a string
2938 @cindex time, conversion to string
2939 @cindex conversion, to string
2942 @item @emph{Description}:
2943 @code{CTIME} converts a system time value, such as returned by
2944 @code{TIME8()}, to a string of the form @samp{Sat Aug 19 18:13:14 1995}.
2946 This intrinsic is provided in both subroutine and function forms; however,
2947 only one form can be used in any given program unit.
2949 @item @emph{Standard}:
2953 Subroutine, function
2955 @item @emph{Syntax}:
2956 @multitable @columnfractions .80
2957 @item @code{CALL CTIME(TIME, RESULT)}.
2958 @item @code{RESULT = CTIME(TIME)}, (not recommended).
2961 @item @emph{Arguments}:
2962 @multitable @columnfractions .15 .70
2963 @item @var{TIME} @tab The type shall be of type @code{INTEGER(KIND=8)}.
2964 @item @var{RESULT} @tab The type shall be of type @code{CHARACTER} and
2968 @item @emph{Return value}:
2969 The converted date and time as a string.
2971 @item @emph{Example}:
2975 character(len=30) :: date
2978 ! Do something, main part of the program
2981 print *, 'Program was started on ', date
2982 end program test_ctime
2985 @item @emph{See Also}:
2986 @ref{GMTIME}, @ref{LTIME}, @ref{TIME}, @ref{TIME8}
2992 @section @code{DATE_AND_TIME} --- Date and time subroutine
2993 @fnindex DATE_AND_TIME
2994 @cindex date, current
2995 @cindex current date
2996 @cindex time, current
2997 @cindex current time
3000 @item @emph{Description}:
3001 @code{DATE_AND_TIME(DATE, TIME, ZONE, VALUES)} gets the corresponding date and
3002 time information from the real-time system clock. @var{DATE} is
3003 @code{INTENT(OUT)} and has form ccyymmdd. @var{TIME} is @code{INTENT(OUT)} and
3004 has form hhmmss.sss. @var{ZONE} is @code{INTENT(OUT)} and has form (+-)hhmm,
3005 representing the difference with respect to Coordinated Universal Time (UTC).
3006 Unavailable time and date parameters return blanks.
3008 @var{VALUES} is @code{INTENT(OUT)} and provides the following:
3010 @multitable @columnfractions .15 .30 .40
3011 @item @tab @code{VALUE(1)}: @tab The year
3012 @item @tab @code{VALUE(2)}: @tab The month
3013 @item @tab @code{VALUE(3)}: @tab The day of the month
3014 @item @tab @code{VALUE(4)}: @tab Time difference with UTC in minutes
3015 @item @tab @code{VALUE(5)}: @tab The hour of the day
3016 @item @tab @code{VALUE(6)}: @tab The minutes of the hour
3017 @item @tab @code{VALUE(7)}: @tab The seconds of the minute
3018 @item @tab @code{VALUE(8)}: @tab The milliseconds of the second
3021 @item @emph{Standard}:
3022 Fortran 95 and later
3027 @item @emph{Syntax}:
3028 @code{CALL DATE_AND_TIME([DATE, TIME, ZONE, VALUES])}
3030 @item @emph{Arguments}:
3031 @multitable @columnfractions .15 .70
3032 @item @var{DATE} @tab (Optional) The type shall be @code{CHARACTER(LEN=8)}
3033 or larger, and of default kind.
3034 @item @var{TIME} @tab (Optional) The type shall be @code{CHARACTER(LEN=10)}
3035 or larger, and of default kind.
3036 @item @var{ZONE} @tab (Optional) The type shall be @code{CHARACTER(LEN=5)}
3037 or larger, and of default kind.
3038 @item @var{VALUES}@tab (Optional) The type shall be @code{INTEGER(8)}.
3041 @item @emph{Return value}:
3044 @item @emph{Example}:
3046 program test_time_and_date
3047 character(8) :: date
3048 character(10) :: time
3049 character(5) :: zone
3050 integer,dimension(8) :: values
3051 ! using keyword arguments
3052 call date_and_time(date,time,zone,values)
3053 call date_and_time(DATE=date,ZONE=zone)
3054 call date_and_time(TIME=time)
3055 call date_and_time(VALUES=values)
3056 print '(a,2x,a,2x,a)', date, time, zone
3057 print '(8i5))', values
3058 end program test_time_and_date
3061 @item @emph{See also}:
3062 @ref{CPU_TIME}, @ref{SYSTEM_CLOCK}
3068 @section @code{DBLE} --- Double conversion function
3070 @cindex conversion, to real
3073 @item @emph{Description}:
3074 @code{DBLE(A)} Converts @var{A} to double precision real type.
3076 @item @emph{Standard}:
3077 Fortran 77 and later
3082 @item @emph{Syntax}:
3083 @code{RESULT = DBLE(A)}
3085 @item @emph{Arguments}:
3086 @multitable @columnfractions .15 .70
3087 @item @var{A} @tab The type shall be @code{INTEGER}, @code{REAL},
3091 @item @emph{Return value}:
3092 The return value is of type double precision real.
3094 @item @emph{Example}:
3099 complex :: z = (2.3,1.14)
3100 print *, dble(x), dble(i), dble(z)
3101 end program test_dble
3104 @item @emph{See also}:
3105 @ref{DFLOAT}, @ref{FLOAT}, @ref{REAL}
3111 @section @code{DCMPLX} --- Double complex conversion function
3113 @cindex complex numbers, conversion to
3114 @cindex conversion, to complex
3117 @item @emph{Description}:
3118 @code{DCMPLX(X [,Y])} returns a double complex number where @var{X} is
3119 converted to the real component. If @var{Y} is present it is converted to the
3120 imaginary component. If @var{Y} is not present then the imaginary component is
3121 set to 0.0. If @var{X} is complex then @var{Y} must not be present.
3123 @item @emph{Standard}:
3129 @item @emph{Syntax}:
3130 @code{RESULT = DCMPLX(X [, Y])}
3132 @item @emph{Arguments}:
3133 @multitable @columnfractions .15 .70
3134 @item @var{X} @tab The type may be @code{INTEGER}, @code{REAL},
3136 @item @var{Y} @tab (Optional if @var{X} is not @code{COMPLEX}.) May be
3137 @code{INTEGER} or @code{REAL}.
3140 @item @emph{Return value}:
3141 The return value is of type @code{COMPLEX(8)}
3143 @item @emph{Example}:
3153 print *, dcmplx(x,i)
3154 end program test_dcmplx
3161 @section @code{DFLOAT} --- Double conversion function
3163 @cindex conversion, to real
3166 @item @emph{Description}:
3167 @code{DFLOAT(A)} Converts @var{A} to double precision real type.
3169 @item @emph{Standard}:
3175 @item @emph{Syntax}:
3176 @code{RESULT = DFLOAT(A)}
3178 @item @emph{Arguments}:
3179 @multitable @columnfractions .15 .70
3180 @item @var{A} @tab The type shall be @code{INTEGER}.
3183 @item @emph{Return value}:
3184 The return value is of type double precision real.
3186 @item @emph{Example}:
3191 end program test_dfloat
3194 @item @emph{See also}:
3195 @ref{DBLE}, @ref{FLOAT}, @ref{REAL}
3201 @section @code{DIGITS} --- Significant binary digits function
3203 @cindex model representation, significant digits
3206 @item @emph{Description}:
3207 @code{DIGITS(X)} returns the number of significant binary digits of the internal
3208 model representation of @var{X}. For example, on a system using a 32-bit
3209 floating point representation, a default real number would likely return 24.
3211 @item @emph{Standard}:
3212 Fortran 95 and later
3217 @item @emph{Syntax}:
3218 @code{RESULT = DIGITS(X)}
3220 @item @emph{Arguments}:
3221 @multitable @columnfractions .15 .70
3222 @item @var{X} @tab The type may be @code{INTEGER} or @code{REAL}.
3225 @item @emph{Return value}:
3226 The return value is of type @code{INTEGER}.
3228 @item @emph{Example}:
3231 integer :: i = 12345
3237 end program test_digits
3244 @section @code{DIM} --- Positive difference
3248 @cindex positive difference
3251 @item @emph{Description}:
3252 @code{DIM(X,Y)} returns the difference @code{X-Y} if the result is positive;
3253 otherwise returns zero.
3255 @item @emph{Standard}:
3256 Fortran 77 and later
3261 @item @emph{Syntax}:
3262 @code{RESULT = DIM(X, Y)}
3264 @item @emph{Arguments}:
3265 @multitable @columnfractions .15 .70
3266 @item @var{X} @tab The type shall be @code{INTEGER} or @code{REAL}
3267 @item @var{Y} @tab The type shall be the same type and kind as @var{X}.
3270 @item @emph{Return value}:
3271 The return value is of type @code{INTEGER} or @code{REAL}.
3273 @item @emph{Example}:
3279 x = dim(4.345_8, 2.111_8)
3282 end program test_dim
3285 @item @emph{Specific names}:
3286 @multitable @columnfractions .20 .20 .20 .25
3287 @item Name @tab Argument @tab Return type @tab Standard
3288 @item @code{DIM(X,Y)} @tab @code{REAL(4) X, Y} @tab @code{REAL(4)} @tab Fortran 77 and later
3289 @item @code{IDIM(X,Y)} @tab @code{INTEGER(4) X, Y} @tab @code{INTEGER(4)} @tab Fortran 77 and later
3290 @item @code{DDIM(X,Y)} @tab @code{REAL(8) X, Y} @tab @code{REAL(8)} @tab Fortran 77 and later
3297 @section @code{DOT_PRODUCT} --- Dot product function
3298 @fnindex DOT_PRODUCT
3300 @cindex vector product
3301 @cindex product, vector
3304 @item @emph{Description}:
3305 @code{DOT_PRODUCT(VECTOR_A, VECTOR_B)} computes the dot product multiplication
3306 of two vectors @var{VECTOR_A} and @var{VECTOR_B}. The two vectors may be
3307 either numeric or logical and must be arrays of rank one and of equal size. If
3308 the vectors are @code{INTEGER} or @code{REAL}, the result is
3309 @code{SUM(VECTOR_A*VECTOR_B)}. If the vectors are @code{COMPLEX}, the result
3310 is @code{SUM(CONJG(VECTOR_A)*VECTOR_B)}. If the vectors are @code{LOGICAL},
3311 the result is @code{ANY(VECTOR_A .AND. VECTOR_B)}.
3313 @item @emph{Standard}:
3314 Fortran 95 and later
3317 Transformational function
3319 @item @emph{Syntax}:
3320 @code{RESULT = DOT_PRODUCT(VECTOR_A, VECTOR_B)}
3322 @item @emph{Arguments}:
3323 @multitable @columnfractions .15 .70
3324 @item @var{VECTOR_A} @tab The type shall be numeric or @code{LOGICAL}, rank 1.
3325 @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.
3328 @item @emph{Return value}:
3329 If the arguments are numeric, the return value is a scalar of numeric type,
3330 @code{INTEGER}, @code{REAL}, or @code{COMPLEX}. If the arguments are
3331 @code{LOGICAL}, the return value is @code{.TRUE.} or @code{.FALSE.}.
3333 @item @emph{Example}:
3335 program test_dot_prod
3336 integer, dimension(3) :: a, b
3343 print *, dot_product(a,b)
3344 end program test_dot_prod
3351 @section @code{DPROD} --- Double product function
3353 @cindex product, double-precision
3356 @item @emph{Description}:
3357 @code{DPROD(X,Y)} returns the product @code{X*Y}.
3359 @item @emph{Standard}:
3360 Fortran 77 and later
3365 @item @emph{Syntax}:
3366 @code{RESULT = DPROD(X, Y)}
3368 @item @emph{Arguments}:
3369 @multitable @columnfractions .15 .70
3370 @item @var{X} @tab The type shall be @code{REAL}.
3371 @item @var{Y} @tab The type shall be @code{REAL}.
3374 @item @emph{Return value}:
3375 The return value is of type @code{REAL(8)}.
3377 @item @emph{Example}:
3385 end program test_dprod
3388 @item @emph{Specific names}:
3389 @multitable @columnfractions .20 .20 .20 .25
3390 @item Name @tab Argument @tab Return type @tab Standard
3391 @item @code{DPROD(X,Y)} @tab @code{REAL(4) X, Y} @tab @code{REAL(4)} @tab Fortran 77 and later
3398 @section @code{DREAL} --- Double real part function
3400 @cindex complex numbers, real part
3403 @item @emph{Description}:
3404 @code{DREAL(Z)} returns the real part of complex variable @var{Z}.
3406 @item @emph{Standard}:
3412 @item @emph{Syntax}:
3413 @code{RESULT = DREAL(A)}
3415 @item @emph{Arguments}:
3416 @multitable @columnfractions .15 .70
3417 @item @var{A} @tab The type shall be @code{COMPLEX(8)}.
3420 @item @emph{Return value}:
3421 The return value is of type @code{REAL(8)}.
3423 @item @emph{Example}:
3426 complex(8) :: z = (1.3_8,7.2_8)
3428 end program test_dreal
3431 @item @emph{See also}:
3439 @section @code{DTIME} --- Execution time subroutine (or function)
3441 @cindex time, elapsed
3442 @cindex elapsed time
3445 @item @emph{Description}:
3446 @code{DTIME(VALUES, TIME)} initially returns the number of seconds of runtime
3447 since the start of the process's execution in @var{TIME}. @var{VALUES}
3448 returns the user and system components of this time in @code{VALUES(1)} and
3449 @code{VALUES(2)} respectively. @var{TIME} is equal to @code{VALUES(1) +
3452 Subsequent invocations of @code{DTIME} return values accumulated since the
3453 previous invocation.
3455 On some systems, the underlying timings are represented using types with
3456 sufficiently small limits that overflows (wrap around) are possible, such as
3457 32-bit types. Therefore, the values returned by this intrinsic might be, or
3458 become, negative, or numerically less than previous values, during a single
3459 run of the compiled program.
3461 Please note, that this implementation is thread safe if used within OpenMP
3462 directives, i.e., its state will be consistent while called from multiple
3463 threads. However, if @code{DTIME} is called from multiple threads, the result
3464 is still the time since the last invocation. This may not give the intended
3465 results. If possible, use @code{CPU_TIME} instead.
3467 This intrinsic is provided in both subroutine and function forms; however,
3468 only one form can be used in any given program unit.
3470 @var{VALUES} and @var{TIME} are @code{INTENT(OUT)} and provide the following:
3472 @multitable @columnfractions .15 .30 .40
3473 @item @tab @code{VALUES(1)}: @tab User time in seconds.
3474 @item @tab @code{VALUES(2)}: @tab System time in seconds.
3475 @item @tab @code{TIME}: @tab Run time since start in seconds.
3478 @item @emph{Standard}:
3482 Subroutine, function
3484 @item @emph{Syntax}:
3485 @multitable @columnfractions .80
3486 @item @code{CALL DTIME(VALUES, TIME)}.
3487 @item @code{TIME = DTIME(VALUES)}, (not recommended).
3490 @item @emph{Arguments}:
3491 @multitable @columnfractions .15 .70
3492 @item @var{VALUES}@tab The type shall be @code{REAL(4), DIMENSION(2)}.
3493 @item @var{TIME}@tab The type shall be @code{REAL(4)}.
3496 @item @emph{Return value}:
3497 Elapsed time in seconds since the last invocation or since the start of program
3498 execution if not called before.
3500 @item @emph{Example}:
3504 real, dimension(2) :: tarray
3506 call dtime(tarray, result)
3510 do i=1,100000000 ! Just a delay
3513 call dtime(tarray, result)
3517 end program test_dtime
3520 @item @emph{See also}:
3528 @section @code{EOSHIFT} --- End-off shift elements of an array
3530 @cindex array, shift
3533 @item @emph{Description}:
3534 @code{EOSHIFT(ARRAY, SHIFT[, BOUNDARY, DIM])} performs an end-off shift on
3535 elements of @var{ARRAY} along the dimension of @var{DIM}. If @var{DIM} is
3536 omitted it is taken to be @code{1}. @var{DIM} is a scalar of type
3537 @code{INTEGER} in the range of @math{1 \leq DIM \leq n)} where @math{n} is the
3538 rank of @var{ARRAY}. If the rank of @var{ARRAY} is one, then all elements of
3539 @var{ARRAY} are shifted by @var{SHIFT} places. If rank is greater than one,
3540 then all complete rank one sections of @var{ARRAY} along the given dimension are
3541 shifted. Elements shifted out one end of each rank one section are dropped. If
3542 @var{BOUNDARY} is present then the corresponding value of from @var{BOUNDARY}
3543 is copied back in the other end. If @var{BOUNDARY} is not present then the
3544 following are copied in depending on the type of @var{ARRAY}.
3546 @multitable @columnfractions .15 .80
3547 @item @emph{Array Type} @tab @emph{Boundary Value}
3548 @item Numeric @tab 0 of the type and kind of @var{ARRAY}.
3549 @item Logical @tab @code{.FALSE.}.
3550 @item Character(@var{len}) @tab @var{len} blanks.
3553 @item @emph{Standard}:
3554 Fortran 95 and later
3557 Transformational function
3559 @item @emph{Syntax}:
3560 @code{RESULT = EOSHIFT(ARRAY, SHIFT [, BOUNDARY, DIM])}
3562 @item @emph{Arguments}:
3563 @multitable @columnfractions .15 .70
3564 @item @var{ARRAY} @tab May be any type, not scalar.
3565 @item @var{SHIFT} @tab The type shall be @code{INTEGER}.
3566 @item @var{BOUNDARY} @tab Same type as @var{ARRAY}.
3567 @item @var{DIM} @tab The type shall be @code{INTEGER}.
3570 @item @emph{Return value}:
3571 Returns an array of same type and rank as the @var{ARRAY} argument.
3573 @item @emph{Example}:
3575 program test_eoshift
3576 integer, dimension(3,3) :: a
3577 a = reshape( (/ 1, 2, 3, 4, 5, 6, 7, 8, 9 /), (/ 3, 3 /))
3578 print '(3i3)', a(1,:)
3579 print '(3i3)', a(2,:)
3580 print '(3i3)', a(3,:)
3581 a = EOSHIFT(a, SHIFT=(/1, 2, 1/), BOUNDARY=-5, DIM=2)
3583 print '(3i3)', a(1,:)
3584 print '(3i3)', a(2,:)
3585 print '(3i3)', a(3,:)
3586 end program test_eoshift
3593 @section @code{EPSILON} --- Epsilon function
3595 @cindex model representation, epsilon
3598 @item @emph{Description}:
3599 @code{EPSILON(X)} returns the smallest number @var{E} of the same kind
3600 as @var{X} such that @math{1 + E > 1}.
3602 @item @emph{Standard}:
3603 Fortran 95 and later
3608 @item @emph{Syntax}:
3609 @code{RESULT = EPSILON(X)}
3611 @item @emph{Arguments}:
3612 @multitable @columnfractions .15 .70
3613 @item @var{X} @tab The type shall be @code{REAL}.
3616 @item @emph{Return value}:
3617 The return value is of same type as the argument.
3619 @item @emph{Example}:
3621 program test_epsilon
3626 end program test_epsilon
3633 @section @code{ERF} --- Error function
3635 @cindex error function
3638 @item @emph{Description}:
3639 @code{ERF(X)} computes the error function of @var{X}.
3641 @item @emph{Standard}:
3642 Fortran 2008 and later
3647 @item @emph{Syntax}:
3648 @code{RESULT = ERF(X)}
3650 @item @emph{Arguments}:
3651 @multitable @columnfractions .15 .70
3652 @item @var{X} @tab The type shall be @code{REAL}.
3655 @item @emph{Return value}:
3656 The return value is of type @code{REAL}, of the same kind as
3657 @var{X} and lies in the range @math{-1 \leq erf (x) \leq 1 }.
3659 @item @emph{Example}:
3662 real(8) :: x = 0.17_8
3664 end program test_erf
3667 @item @emph{Specific names}:
3668 @multitable @columnfractions .20 .20 .20 .25
3669 @item Name @tab Argument @tab Return type @tab Standard
3670 @item @code{DERF(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU extension
3677 @section @code{ERFC} --- Error function
3679 @cindex error function, complementary
3682 @item @emph{Description}:
3683 @code{ERFC(X)} computes the complementary error function of @var{X}.
3685 @item @emph{Standard}:
3686 Fortran 2008 and later
3691 @item @emph{Syntax}:
3692 @code{RESULT = ERFC(X)}
3694 @item @emph{Arguments}:
3695 @multitable @columnfractions .15 .70
3696 @item @var{X} @tab The type shall be @code{REAL}.
3699 @item @emph{Return value}:
3700 The return value is of type @code{REAL} and of the same kind as @var{X}.
3701 It lies in the range @math{ 0 \leq erfc (x) \leq 2 }.
3703 @item @emph{Example}:
3706 real(8) :: x = 0.17_8
3708 end program test_erfc
3711 @item @emph{Specific names}:
3712 @multitable @columnfractions .20 .20 .20 .25
3713 @item Name @tab Argument @tab Return type @tab Standard
3714 @item @code{DERFC(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU extension
3721 @section @code{ERFC_SCALED} --- Error function
3722 @fnindex ERFC_SCALED
3723 @cindex error function, complementary, exponentially-scaled
3726 @item @emph{Description}:
3727 @code{ERFC_SCALED(X)} computes the exponentially-scaled complementary
3728 error function of @var{X}.
3730 @item @emph{Standard}:
3731 Fortran 2008 and later
3736 @item @emph{Syntax}:
3737 @code{RESULT = ERFC_SCALED(X)}
3739 @item @emph{Arguments}:
3740 @multitable @columnfractions .15 .70
3741 @item @var{X} @tab The type shall be @code{REAL}.
3744 @item @emph{Return value}:
3745 The return value is of type @code{REAL} and of the same kind as @var{X}.
3747 @item @emph{Example}:
3749 program test_erfc_scaled
3750 real(8) :: x = 0.17_8
3752 end program test_erfc_scaled
3759 @section @code{ETIME} --- Execution time subroutine (or function)
3761 @cindex time, elapsed
3764 @item @emph{Description}:
3765 @code{ETIME(VALUES, TIME)} returns the number of seconds of runtime
3766 since the start of the process's execution in @var{TIME}. @var{VALUES}
3767 returns the user and system components of this time in @code{VALUES(1)} and
3768 @code{VALUES(2)} respectively. @var{TIME} is equal to @code{VALUES(1) + VALUES(2)}.
3770 On some systems, the underlying timings are represented using types with
3771 sufficiently small limits that overflows (wrap around) are possible, such as
3772 32-bit types. Therefore, the values returned by this intrinsic might be, or
3773 become, negative, or numerically less than previous values, during a single
3774 run of the compiled program.
3776 This intrinsic is provided in both subroutine and function forms; however,
3777 only one form can be used in any given program unit.
3779 @var{VALUES} and @var{TIME} are @code{INTENT(OUT)} and provide the following:
3781 @multitable @columnfractions .15 .30 .60
3782 @item @tab @code{VALUES(1)}: @tab User time in seconds.
3783 @item @tab @code{VALUES(2)}: @tab System time in seconds.
3784 @item @tab @code{TIME}: @tab Run time since start in seconds.
3787 @item @emph{Standard}:
3791 Subroutine, function
3793 @item @emph{Syntax}:
3794 @multitable @columnfractions .80
3795 @item @code{CALL ETIME(VALUES, TIME)}.
3796 @item @code{TIME = ETIME(VALUES)}, (not recommended).
3799 @item @emph{Arguments}:
3800 @multitable @columnfractions .15 .70
3801 @item @var{VALUES}@tab The type shall be @code{REAL(4), DIMENSION(2)}.
3802 @item @var{TIME}@tab The type shall be @code{REAL(4)}.
3805 @item @emph{Return value}:
3806 Elapsed time in seconds since the start of program execution.
3808 @item @emph{Example}:
3812 real, dimension(2) :: tarray
3814 call ETIME(tarray, result)
3818 do i=1,100000000 ! Just a delay
3821 call ETIME(tarray, result)
3825 end program test_etime
3828 @item @emph{See also}:
3836 @section @code{EXIT} --- Exit the program with status.
3838 @cindex program termination
3839 @cindex terminate program
3842 @item @emph{Description}:
3843 @code{EXIT} causes immediate termination of the program with status. If status
3844 is omitted it returns the canonical @emph{success} for the system. All Fortran
3845 I/O units are closed.
3847 @item @emph{Standard}:
3853 @item @emph{Syntax}:
3854 @code{CALL EXIT([STATUS])}
3856 @item @emph{Arguments}:
3857 @multitable @columnfractions .15 .70
3858 @item @var{STATUS} @tab Shall be an @code{INTEGER} of the default kind.
3861 @item @emph{Return value}:
3862 @code{STATUS} is passed to the parent process on exit.
3864 @item @emph{Example}:
3867 integer :: STATUS = 0
3868 print *, 'This program is going to exit.'
3870 end program test_exit
3873 @item @emph{See also}:
3874 @ref{ABORT}, @ref{KILL}
3880 @section @code{EXP} --- Exponential function
3886 @cindex exponential function
3887 @cindex logarithmic function, inverse
3890 @item @emph{Description}:
3891 @code{EXP(X)} computes the base @math{e} exponential of @var{X}.
3893 @item @emph{Standard}:
3894 Fortran 77 and later, has overloads that are GNU extensions
3899 @item @emph{Syntax}:
3900 @code{RESULT = EXP(X)}
3902 @item @emph{Arguments}:
3903 @multitable @columnfractions .15 .70
3904 @item @var{X} @tab The type shall be @code{REAL} or
3908 @item @emph{Return value}:
3909 The return value has same type and kind as @var{X}.
3911 @item @emph{Example}:
3916 end program test_exp
3919 @item @emph{Specific names}:
3920 @multitable @columnfractions .20 .20 .20 .25
3921 @item Name @tab Argument @tab Return type @tab Standard
3922 @item @code{EXP(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab Fortran 77 and later
3923 @item @code{DEXP(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab Fortran 77 and later
3924 @item @code{CEXP(X)} @tab @code{COMPLEX(4) X} @tab @code{COMPLEX(4)} @tab Fortran 77 and later
3925 @item @code{ZEXP(X)} @tab @code{COMPLEX(8) X} @tab @code{COMPLEX(8)} @tab GNU extension
3926 @item @code{CDEXP(X)} @tab @code{COMPLEX(8) X} @tab @code{COMPLEX(8)} @tab GNU extension
3933 @section @code{EXPONENT} --- Exponent function
3935 @cindex real number, exponent
3936 @cindex floating point, exponent
3939 @item @emph{Description}:
3940 @code{EXPONENT(X)} returns the value of the exponent part of @var{X}. If @var{X}
3941 is zero the value returned is zero.
3943 @item @emph{Standard}:
3944 Fortran 95 and later
3949 @item @emph{Syntax}:
3950 @code{RESULT = EXPONENT(X)}
3952 @item @emph{Arguments}:
3953 @multitable @columnfractions .15 .70
3954 @item @var{X} @tab The type shall be @code{REAL}.
3957 @item @emph{Return value}:
3958 The return value is of type default @code{INTEGER}.
3960 @item @emph{Example}:
3962 program test_exponent
3967 print *, exponent(0.0)
3968 end program test_exponent
3975 @section @code{FDATE} --- Get the current time as a string
3977 @cindex time, current
3978 @cindex current time
3979 @cindex date, current
3980 @cindex current date
3983 @item @emph{Description}:
3984 @code{FDATE(DATE)} returns the current date (using the same format as
3985 @code{CTIME}) in @var{DATE}. It is equivalent to @code{CALL CTIME(DATE,
3988 This intrinsic is provided in both subroutine and function forms; however,
3989 only one form can be used in any given program unit.
3991 @var{DATE} is an @code{INTENT(OUT)} @code{CHARACTER} variable of the
3994 @item @emph{Standard}:
3998 Subroutine, function
4000 @item @emph{Syntax}:
4001 @multitable @columnfractions .80
4002 @item @code{CALL FDATE(DATE)}.
4003 @item @code{DATE = FDATE()}, (not recommended).
4006 @item @emph{Arguments}:
4007 @multitable @columnfractions .15 .70
4008 @item @var{DATE}@tab The type shall be of type @code{CHARACTER} of the
4012 @item @emph{Return value}:
4013 The current date as a string.
4015 @item @emph{Example}:
4019 character(len=30) :: date
4021 print *, 'Program started on ', date
4022 do i = 1, 100000000 ! Just a delay
4026 print *, 'Program ended on ', date
4027 end program test_fdate
4034 @section @code{FLOAT} --- Convert integer to default real
4036 @cindex conversion, to real
4039 @item @emph{Description}:
4040 @code{FLOAT(A)} converts the integer @var{A} to a default real value.
4042 @item @emph{Standard}:
4043 Fortran 77 and later
4048 @item @emph{Syntax}:
4049 @code{RESULT = FLOAT(A)}
4051 @item @emph{Arguments}:
4052 @multitable @columnfractions .15 .70
4053 @item @var{A} @tab The type shall be @code{INTEGER}.
4056 @item @emph{Return value}:
4057 The return value is of type default @code{REAL}.
4059 @item @emph{Example}:
4063 if (float(i) /= 1.) call abort
4064 end program test_float
4067 @item @emph{See also}:
4068 @ref{DBLE}, @ref{DFLOAT}, @ref{REAL}
4074 @section @code{FGET} --- Read a single character in stream mode from stdin
4076 @cindex read character, stream mode
4077 @cindex stream mode, read character
4078 @cindex file operation, read character
4081 @item @emph{Description}:
4082 Read a single character in stream mode from stdin by bypassing normal
4083 formatted output. Stream I/O should not be mixed with normal record-oriented
4084 (formatted or unformatted) I/O on the same unit; the results are unpredictable.
4086 This intrinsic is provided in both subroutine and function forms; however,
4087 only one form can be used in any given program unit.
4089 Note that the @code{FGET} intrinsic is provided for backwards compatibility with
4090 @command{g77}. GNU Fortran provides the Fortran 2003 Stream facility.
4091 Programmers should consider the use of new stream IO feature in new code
4092 for future portability. See also @ref{Fortran 2003 status}.
4094 @item @emph{Standard}:
4098 Subroutine, function
4100 @item @emph{Syntax}:
4101 @code{CALL FGET(C [, STATUS])}
4103 @item @emph{Arguments}:
4104 @multitable @columnfractions .15 .70
4105 @item @var{C} @tab The type shall be @code{CHARACTER} and of default
4107 @item @var{STATUS} @tab (Optional) status flag of type @code{INTEGER}.
4108 Returns 0 on success, -1 on end-of-file, and a system specific positive
4109 error code otherwise.
4112 @item @emph{Example}:
4115 INTEGER, PARAMETER :: strlen = 100
4116 INTEGER :: status, i = 1
4117 CHARACTER(len=strlen) :: str = ""
4119 WRITE (*,*) 'Enter text:'
4121 CALL fget(str(i:i), status)
4122 if (status /= 0 .OR. i > strlen) exit
4125 WRITE (*,*) TRIM(str)
4129 @item @emph{See also}:
4130 @ref{FGETC}, @ref{FPUT}, @ref{FPUTC}
4136 @section @code{FGETC} --- Read a single character in stream mode
4138 @cindex read character, stream mode
4139 @cindex stream mode, read character
4140 @cindex file operation, read character
4143 @item @emph{Description}:
4144 Read a single character in stream mode by bypassing normal formatted output.
4145 Stream I/O should not be mixed with normal record-oriented (formatted or
4146 unformatted) I/O on the same unit; the results are unpredictable.
4148 This intrinsic is provided in both subroutine and function forms; however,
4149 only one form can be used in any given program unit.
4151 Note that the @code{FGET} intrinsic is provided for backwards compatibility
4152 with @command{g77}. GNU Fortran provides the Fortran 2003 Stream facility.
4153 Programmers should consider the use of new stream IO feature in new code
4154 for future portability. See also @ref{Fortran 2003 status}.
4156 @item @emph{Standard}:
4160 Subroutine, function
4162 @item @emph{Syntax}:
4163 @code{CALL FGETC(UNIT, C [, STATUS])}
4165 @item @emph{Arguments}:
4166 @multitable @columnfractions .15 .70
4167 @item @var{UNIT} @tab The type shall be @code{INTEGER}.
4168 @item @var{C} @tab The type shall be @code{CHARACTER} and of default
4170 @item @var{STATUS} @tab (Optional) status flag of type @code{INTEGER}.
4171 Returns 0 on success, -1 on end-of-file and a system specific positive
4172 error code otherwise.
4175 @item @emph{Example}:
4178 INTEGER :: fd = 42, status
4181 OPEN(UNIT=fd, FILE="/etc/passwd", ACTION="READ", STATUS = "OLD")
4183 CALL fgetc(fd, c, status)
4184 IF (status /= 0) EXIT
4191 @item @emph{See also}:
4192 @ref{FGET}, @ref{FPUT}, @ref{FPUTC}
4198 @section @code{FLOOR} --- Integer floor function
4201 @cindex rounding, floor
4204 @item @emph{Description}:
4205 @code{FLOOR(A)} returns the greatest integer less than or equal to @var{X}.
4207 @item @emph{Standard}:
4208 Fortran 95 and later
4213 @item @emph{Syntax}:
4214 @code{RESULT = FLOOR(A [, KIND])}
4216 @item @emph{Arguments}:
4217 @multitable @columnfractions .15 .70
4218 @item @var{A} @tab The type shall be @code{REAL}.
4219 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
4220 expression indicating the kind parameter of the result.
4223 @item @emph{Return value}:
4224 The return value is of type @code{INTEGER(KIND)} if @var{KIND} is present
4225 and of default-kind @code{INTEGER} otherwise.
4227 @item @emph{Example}:
4232 print *, floor(x) ! returns 63
4233 print *, floor(y) ! returns -64
4234 end program test_floor
4237 @item @emph{See also}:
4238 @ref{CEILING}, @ref{NINT}
4245 @section @code{FLUSH} --- Flush I/O unit(s)
4247 @cindex file operation, flush
4250 @item @emph{Description}:
4251 Flushes Fortran unit(s) currently open for output. Without the optional
4252 argument, all units are flushed, otherwise just the unit specified.
4254 @item @emph{Standard}:
4260 @item @emph{Syntax}:
4261 @code{CALL FLUSH(UNIT)}
4263 @item @emph{Arguments}:
4264 @multitable @columnfractions .15 .70
4265 @item @var{UNIT} @tab (Optional) The type shall be @code{INTEGER}.
4269 Beginning with the Fortran 2003 standard, there is a @code{FLUSH}
4270 statement that should be preferred over the @code{FLUSH} intrinsic.
4277 @section @code{FNUM} --- File number function
4279 @cindex file operation, file number
4282 @item @emph{Description}:
4283 @code{FNUM(UNIT)} returns the POSIX file descriptor number corresponding to the
4284 open Fortran I/O unit @code{UNIT}.
4286 @item @emph{Standard}:
4292 @item @emph{Syntax}:
4293 @code{RESULT = FNUM(UNIT)}
4295 @item @emph{Arguments}:
4296 @multitable @columnfractions .15 .70
4297 @item @var{UNIT} @tab The type shall be @code{INTEGER}.
4300 @item @emph{Return value}:
4301 The return value is of type @code{INTEGER}
4303 @item @emph{Example}:
4307 open (unit=10, status = "scratch")
4311 end program test_fnum
4318 @section @code{FPUT} --- Write a single character in stream mode to stdout
4320 @cindex write character, stream mode
4321 @cindex stream mode, write character
4322 @cindex file operation, write character
4325 @item @emph{Description}:
4326 Write a single character in stream mode to stdout by bypassing normal
4327 formatted output. Stream I/O should not be mixed with normal record-oriented
4328 (formatted or unformatted) I/O on the same unit; the results are unpredictable.
4330 This intrinsic is provided in both subroutine and function forms; however,
4331 only one form can be used in any given program unit.
4333 Note that the @code{FGET} intrinsic is provided for backwards compatibility with
4334 @command{g77}. GNU Fortran provides the Fortran 2003 Stream facility.
4335 Programmers should consider the use of new stream IO feature in new code
4336 for future portability. See also @ref{Fortran 2003 status}.
4338 @item @emph{Standard}:
4342 Subroutine, function
4344 @item @emph{Syntax}:
4345 @code{CALL FPUT(C [, STATUS])}
4347 @item @emph{Arguments}:
4348 @multitable @columnfractions .15 .70
4349 @item @var{C} @tab The type shall be @code{CHARACTER} and of default
4351 @item @var{STATUS} @tab (Optional) status flag of type @code{INTEGER}.
4352 Returns 0 on success, -1 on end-of-file and a system specific positive
4353 error code otherwise.
4356 @item @emph{Example}:
4359 CHARACTER(len=10) :: str = "gfortran"
4361 DO i = 1, len_trim(str)
4367 @item @emph{See also}:
4368 @ref{FPUTC}, @ref{FGET}, @ref{FGETC}
4374 @section @code{FPUTC} --- Write a single character in stream mode
4376 @cindex write character, stream mode
4377 @cindex stream mode, write character
4378 @cindex file operation, write character
4381 @item @emph{Description}:
4382 Write a single character in stream mode by bypassing normal formatted
4383 output. Stream I/O should not be mixed with normal record-oriented
4384 (formatted or unformatted) I/O on the same unit; the results are unpredictable.
4386 This intrinsic is provided in both subroutine and function forms; however,
4387 only one form can be used in any given program unit.
4389 Note that the @code{FGET} intrinsic is provided for backwards compatibility with
4390 @command{g77}. GNU Fortran provides the Fortran 2003 Stream facility.
4391 Programmers should consider the use of new stream IO feature in new code
4392 for future portability. See also @ref{Fortran 2003 status}.
4394 @item @emph{Standard}:
4398 Subroutine, function
4400 @item @emph{Syntax}:
4401 @code{CALL FPUTC(UNIT, C [, STATUS])}
4403 @item @emph{Arguments}:
4404 @multitable @columnfractions .15 .70
4405 @item @var{UNIT} @tab The type shall be @code{INTEGER}.
4406 @item @var{C} @tab The type shall be @code{CHARACTER} and of default
4408 @item @var{STATUS} @tab (Optional) status flag of type @code{INTEGER}.
4409 Returns 0 on success, -1 on end-of-file and a system specific positive
4410 error code otherwise.
4413 @item @emph{Example}:
4416 CHARACTER(len=10) :: str = "gfortran"
4417 INTEGER :: fd = 42, i
4419 OPEN(UNIT = fd, FILE = "out", ACTION = "WRITE", STATUS="NEW")
4420 DO i = 1, len_trim(str)
4421 CALL fputc(fd, str(i:i))
4427 @item @emph{See also}:
4428 @ref{FPUT}, @ref{FGET}, @ref{FGETC}
4434 @section @code{FRACTION} --- Fractional part of the model representation
4436 @cindex real number, fraction
4437 @cindex floating point, fraction
4440 @item @emph{Description}:
4441 @code{FRACTION(X)} returns the fractional part of the model
4442 representation of @code{X}.
4444 @item @emph{Standard}:
4445 Fortran 95 and later
4450 @item @emph{Syntax}:
4451 @code{Y = FRACTION(X)}
4453 @item @emph{Arguments}:
4454 @multitable @columnfractions .15 .70
4455 @item @var{X} @tab The type of the argument shall be a @code{REAL}.
4458 @item @emph{Return value}:
4459 The return value is of the same type and kind as the argument.
4460 The fractional part of the model representation of @code{X} is returned;
4461 it is @code{X * RADIX(X)**(-EXPONENT(X))}.
4463 @item @emph{Example}:
4465 program test_fraction
4468 print *, fraction(x), x * radix(x)**(-exponent(x))
4469 end program test_fraction
4477 @section @code{FREE} --- Frees memory
4479 @cindex pointer, cray
4482 @item @emph{Description}:
4483 Frees memory previously allocated by @code{MALLOC()}. The @code{FREE}
4484 intrinsic is an extension intended to be used with Cray pointers, and is
4485 provided in GNU Fortran to allow user to compile legacy code. For
4486 new code using Fortran 95 pointers, the memory de-allocation intrinsic is
4489 @item @emph{Standard}:
4495 @item @emph{Syntax}:
4496 @code{CALL FREE(PTR)}
4498 @item @emph{Arguments}:
4499 @multitable @columnfractions .15 .70
4500 @item @var{PTR} @tab The type shall be @code{INTEGER}. It represents the
4501 location of the memory that should be de-allocated.
4504 @item @emph{Return value}:
4507 @item @emph{Example}:
4508 See @code{MALLOC} for an example.
4510 @item @emph{See also}:
4517 @section @code{FSEEK} --- Low level file positioning subroutine
4519 @cindex file operation, seek
4520 @cindex file operation, position
4523 @item @emph{Description}:
4524 Moves @var{UNIT} to the specified @var{OFFSET}. If @var{WHENCE}
4525 is set to 0, the @var{OFFSET} is taken as an absolute value @code{SEEK_SET},
4526 if set to 1, @var{OFFSET} is taken to be relative to the current position
4527 @code{SEEK_CUR}, and if set to 2 relative to the end of the file @code{SEEK_END}.
4528 On error, @var{STATUS} is set to a nonzero value. If @var{STATUS} the seek
4531 This intrinsic routine is not fully backwards compatible with @command{g77}.
4532 In @command{g77}, the @code{FSEEK} takes a statement label instead of a
4533 @var{STATUS} variable. If FSEEK is used in old code, change
4535 CALL FSEEK(UNIT, OFFSET, WHENCE, *label)
4540 CALL FSEEK(UNIT, OFFSET, WHENCE, status)
4541 IF (status /= 0) GOTO label
4544 Please note that GNU Fortran provides the Fortran 2003 Stream facility.
4545 Programmers should consider the use of new stream IO feature in new code
4546 for future portability. See also @ref{Fortran 2003 status}.
4548 @item @emph{Standard}:
4554 @item @emph{Syntax}:
4555 @code{CALL FSEEK(UNIT, OFFSET, WHENCE[, STATUS])}
4557 @item @emph{Arguments}:
4558 @multitable @columnfractions .15 .70
4559 @item @var{UNIT} @tab Shall be a scalar of type @code{INTEGER}.
4560 @item @var{OFFSET} @tab Shall be a scalar of type @code{INTEGER}.
4561 @item @var{WHENCE} @tab Shall be a scalar of type @code{INTEGER}.
4562 Its value shall be either 0, 1 or 2.
4563 @item @var{STATUS} @tab (Optional) shall be a scalar of type
4567 @item @emph{Example}:
4570 INTEGER, PARAMETER :: SEEK_SET = 0, SEEK_CUR = 1, SEEK_END = 2
4571 INTEGER :: fd, offset, ierr
4577 OPEN(UNIT=fd, FILE="fseek.test")
4578 CALL FSEEK(fd, offset, SEEK_SET, ierr) ! move to OFFSET
4579 print *, FTELL(fd), ierr
4581 CALL FSEEK(fd, 0, SEEK_END, ierr) ! move to end
4582 print *, FTELL(fd), ierr
4584 CALL FSEEK(fd, 0, SEEK_SET, ierr) ! move to beginning
4585 print *, FTELL(fd), ierr
4591 @item @emph{See also}:
4598 @section @code{FSTAT} --- Get file status
4600 @cindex file system, file status
4603 @item @emph{Description}:
4604 @code{FSTAT} is identical to @ref{STAT}, except that information about an
4605 already opened file is obtained.
4607 The elements in @code{VALUES} are the same as described by @ref{STAT}.
4609 This intrinsic is provided in both subroutine and function forms; however,
4610 only one form can be used in any given program unit.
4612 @item @emph{Standard}:
4616 Subroutine, function
4618 @item @emph{Syntax}:
4619 @code{CALL FSTAT(UNIT, VALUES [, STATUS])}
4621 @item @emph{Arguments}:
4622 @multitable @columnfractions .15 .70
4623 @item @var{UNIT} @tab An open I/O unit number of type @code{INTEGER}.
4624 @item @var{VALUES} @tab The type shall be @code{INTEGER(4), DIMENSION(13)}.
4625 @item @var{STATUS} @tab (Optional) status flag of type @code{INTEGER(4)}. Returns 0
4626 on success and a system specific error code otherwise.
4629 @item @emph{Example}:
4630 See @ref{STAT} for an example.
4632 @item @emph{See also}:
4633 To stat a link: @ref{LSTAT}, to stat a file: @ref{STAT}
4639 @section @code{FTELL} --- Current stream position
4641 @cindex file operation, position
4644 @item @emph{Description}:
4645 Retrieves the current position within an open file.
4647 This intrinsic is provided in both subroutine and function forms; however,
4648 only one form can be used in any given program unit.
4650 @item @emph{Standard}:
4654 Subroutine, function
4656 @item @emph{Syntax}:
4657 @multitable @columnfractions .80
4658 @item @code{CALL FTELL(UNIT, OFFSET)}
4659 @item @code{OFFSET = FTELL(UNIT)}
4662 @item @emph{Arguments}:
4663 @multitable @columnfractions .15 .70
4664 @item @var{OFFSET} @tab Shall of type @code{INTEGER}.
4665 @item @var{UNIT} @tab Shall of type @code{INTEGER}.
4668 @item @emph{Return value}:
4669 In either syntax, @var{OFFSET} is set to the current offset of unit
4670 number @var{UNIT}, or to @math{-1} if the unit is not currently open.
4672 @item @emph{Example}:
4676 OPEN(10, FILE="temp.dat")
4682 @item @emph{See also}:
4689 @section @code{GAMMA} --- Gamma function
4692 @cindex Gamma function
4693 @cindex Factorial function
4696 @item @emph{Description}:
4697 @code{GAMMA(X)} computes Gamma (@math{\Gamma}) of @var{X}. For positive,
4698 integer values of @var{X} the Gamma function simplifies to the factorial
4699 function @math{\Gamma(x)=(x-1)!}.
4703 \Gamma(x) = \int_0^\infty t^{x-1}{\rm e}^{-t}\,{\rm d}t
4707 @item @emph{Standard}:
4708 Fortran 2008 and later
4713 @item @emph{Syntax}:
4716 @item @emph{Arguments}:
4717 @multitable @columnfractions .15 .70
4718 @item @var{X} @tab Shall be of type @code{REAL} and neither zero
4719 nor a negative integer.
4722 @item @emph{Return value}:
4723 The return value is of type @code{REAL} of the same kind as @var{X}.
4725 @item @emph{Example}:
4729 x = gamma(x) ! returns 1.0
4730 end program test_gamma
4733 @item @emph{Specific names}:
4734 @multitable @columnfractions .20 .20 .20 .25
4735 @item Name @tab Argument @tab Return type @tab Standard
4736 @item @code{GAMMA(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab GNU Extension
4737 @item @code{DGAMMA(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU Extension
4740 @item @emph{See also}:
4741 Logarithm of the Gamma function: @ref{LOG_GAMMA}
4748 @section @code{GERROR} --- Get last system error message
4750 @cindex system, error handling
4753 @item @emph{Description}:
4754 Returns the system error message corresponding to the last system error.
4755 This resembles the functionality of @code{strerror(3)} in C.
4757 @item @emph{Standard}:
4763 @item @emph{Syntax}:
4764 @code{CALL GERROR(RESULT)}
4766 @item @emph{Arguments}:
4767 @multitable @columnfractions .15 .70
4768 @item @var{RESULT} @tab Shall of type @code{CHARACTER} and of default
4771 @item @emph{Example}:
4774 CHARACTER(len=100) :: msg
4780 @item @emph{See also}:
4781 @ref{IERRNO}, @ref{PERROR}
4787 @section @code{GETARG} --- Get command line arguments
4789 @cindex command-line arguments
4790 @cindex arguments, to program
4793 @item @emph{Description}:
4794 Retrieve the @var{POS}-th argument that was passed on the
4795 command line when the containing program was invoked.
4797 This intrinsic routine is provided for backwards compatibility with
4798 GNU Fortran 77. In new code, programmers should consider the use of
4799 the @ref{GET_COMMAND_ARGUMENT} intrinsic defined by the Fortran 2003
4802 @item @emph{Standard}:
4808 @item @emph{Syntax}:
4809 @code{CALL GETARG(POS, VALUE)}
4811 @item @emph{Arguments}:
4812 @multitable @columnfractions .15 .70
4813 @item @var{POS} @tab Shall be of type @code{INTEGER} and not wider than
4814 the default integer kind; @math{@var{POS} \geq 0}
4815 @item @var{VALUE} @tab Shall be of type @code{CHARACTER} and of default
4817 @item @var{VALUE} @tab Shall be of type @code{CHARACTER}.
4820 @item @emph{Return value}:
4821 After @code{GETARG} returns, the @var{VALUE} argument holds the
4822 @var{POS}th command line argument. If @var{VALUE} can not hold the
4823 argument, it is truncated to fit the length of @var{VALUE}. If there are
4824 less than @var{POS} arguments specified at the command line, @var{VALUE}
4825 will be filled with blanks. If @math{@var{POS} = 0}, @var{VALUE} is set
4826 to the name of the program (on systems that support this feature).
4828 @item @emph{Example}:
4832 CHARACTER(len=32) :: arg
4841 @item @emph{See also}:
4842 GNU Fortran 77 compatibility function: @ref{IARGC}
4844 Fortran 2003 functions and subroutines: @ref{GET_COMMAND},
4845 @ref{GET_COMMAND_ARGUMENT}, @ref{COMMAND_ARGUMENT_COUNT}
4851 @section @code{GET_COMMAND} --- Get the entire command line
4852 @fnindex GET_COMMAND
4853 @cindex command-line arguments
4854 @cindex arguments, to program
4857 @item @emph{Description}:
4858 Retrieve the entire command line that was used to invoke the program.
4860 @item @emph{Standard}:
4861 Fortran 2003 and later
4866 @item @emph{Syntax}:
4867 @code{CALL GET_COMMAND([COMMAND, LENGTH, STATUS])}
4869 @item @emph{Arguments}:
4870 @multitable @columnfractions .15 .70
4871 @item @var{COMMAND} @tab (Optional) shall be of type @code{CHARACTER} and
4873 @item @var{LENGTH} @tab (Optional) Shall be of type @code{INTEGER} and of
4875 @item @var{STATUS} @tab (Optional) Shall be of type @code{INTEGER} and of
4879 @item @emph{Return value}:
4880 If @var{COMMAND} is present, stores the entire command line that was used
4881 to invoke the program in @var{COMMAND}. If @var{LENGTH} is present, it is
4882 assigned the length of the command line. If @var{STATUS} is present, it
4883 is assigned 0 upon success of the command, -1 if @var{COMMAND} is too
4884 short to store the command line, or a positive value in case of an error.
4886 @item @emph{Example}:
4888 PROGRAM test_get_command
4889 CHARACTER(len=255) :: cmd
4890 CALL get_command(cmd)
4891 WRITE (*,*) TRIM(cmd)
4895 @item @emph{See also}:
4896 @ref{GET_COMMAND_ARGUMENT}, @ref{COMMAND_ARGUMENT_COUNT}
4901 @node GET_COMMAND_ARGUMENT
4902 @section @code{GET_COMMAND_ARGUMENT} --- Get command line arguments
4903 @fnindex GET_COMMAND_ARGUMENT
4904 @cindex command-line arguments
4905 @cindex arguments, to program
4908 @item @emph{Description}:
4909 Retrieve the @var{NUMBER}-th argument that was passed on the
4910 command line when the containing program was invoked.
4912 @item @emph{Standard}:
4913 Fortran 2003 and later
4918 @item @emph{Syntax}:
4919 @code{CALL GET_COMMAND_ARGUMENT(NUMBER [, VALUE, LENGTH, STATUS])}
4921 @item @emph{Arguments}:
4922 @multitable @columnfractions .15 .70
4923 @item @var{NUMBER} @tab Shall be a scalar of type @code{INTEGER} and of
4924 default kind, @math{@var{NUMBER} \geq 0}
4925 @item @var{VALUE} @tab Shall be a scalar of type @code{CHARACTER}
4926 and of default kind.
4927 @item @var{LENGTH} @tab (Option) Shall be a scalar of type @code{INTEGER}
4928 and of default kind.
4929 @item @var{STATUS} @tab (Option) Shall be a scalar of type @code{INTEGER}
4930 and of default kind.
4933 @item @emph{Return value}:
4934 After @code{GET_COMMAND_ARGUMENT} returns, the @var{VALUE} argument holds the
4935 @var{NUMBER}-th command line argument. If @var{VALUE} can not hold the argument, it is
4936 truncated to fit the length of @var{VALUE}. If there are less than @var{NUMBER}
4937 arguments specified at the command line, @var{VALUE} will be filled with blanks.
4938 If @math{@var{NUMBER} = 0}, @var{VALUE} is set to the name of the program (on
4939 systems that support this feature). The @var{LENGTH} argument contains the
4940 length of the @var{NUMBER}-th command line argument. If the argument retrieval
4941 fails, @var{STATUS} is a positive number; if @var{VALUE} contains a truncated
4942 command line argument, @var{STATUS} is -1; and otherwise the @var{STATUS} is
4945 @item @emph{Example}:
4947 PROGRAM test_get_command_argument
4949 CHARACTER(len=32) :: arg
4953 CALL get_command_argument(i, arg)
4954 IF (LEN_TRIM(arg) == 0) EXIT
4956 WRITE (*,*) TRIM(arg)
4962 @item @emph{See also}:
4963 @ref{GET_COMMAND}, @ref{COMMAND_ARGUMENT_COUNT}
4969 @section @code{GETCWD} --- Get current working directory
4971 @cindex system, working directory
4974 @item @emph{Description}:
4975 Get current working directory.
4977 This intrinsic is provided in both subroutine and function forms; however,
4978 only one form can be used in any given program unit.
4980 @item @emph{Standard}:
4984 Subroutine, function
4986 @item @emph{Syntax}:
4987 @code{CALL GETCWD(C [, STATUS])}
4989 @item @emph{Arguments}:
4990 @multitable @columnfractions .15 .70
4991 @item @var{C} @tab The type shall be @code{CHARACTER} and of default kind.
4992 @item @var{STATUS} @tab (Optional) status flag. Returns 0 on success,
4993 a system specific and nonzero error code otherwise.
4996 @item @emph{Example}:
4999 CHARACTER(len=255) :: cwd
5001 WRITE(*,*) TRIM(cwd)
5005 @item @emph{See also}:
5012 @section @code{GETENV} --- Get an environmental variable
5014 @cindex environment variable
5017 @item @emph{Description}:
5018 Get the @var{VALUE} of the environmental variable @var{NAME}.
5020 This intrinsic routine is provided for backwards compatibility with
5021 GNU Fortran 77. In new code, programmers should consider the use of
5022 the @ref{GET_ENVIRONMENT_VARIABLE} intrinsic defined by the Fortran
5025 @item @emph{Standard}:
5031 @item @emph{Syntax}:
5032 @code{CALL GETENV(NAME, VALUE)}
5034 @item @emph{Arguments}:
5035 @multitable @columnfractions .15 .70
5036 @item @var{NAME} @tab Shall be of type @code{CHARACTER} and of default kind.
5037 @item @var{VALUE} @tab Shall be of type @code{CHARACTER} and of default kind.
5040 @item @emph{Return value}:
5041 Stores the value of @var{NAME} in @var{VALUE}. If @var{VALUE} is
5042 not large enough to hold the data, it is truncated. If @var{NAME}
5043 is not set, @var{VALUE} will be filled with blanks.
5045 @item @emph{Example}:
5048 CHARACTER(len=255) :: homedir
5049 CALL getenv("HOME", homedir)
5050 WRITE (*,*) TRIM(homedir)
5054 @item @emph{See also}:
5055 @ref{GET_ENVIRONMENT_VARIABLE}
5060 @node GET_ENVIRONMENT_VARIABLE
5061 @section @code{GET_ENVIRONMENT_VARIABLE} --- Get an environmental variable
5062 @fnindex GET_ENVIRONMENT_VARIABLE
5063 @cindex environment variable
5066 @item @emph{Description}:
5067 Get the @var{VALUE} of the environmental variable @var{NAME}.
5069 @item @emph{Standard}:
5070 Fortran 2003 and later
5075 @item @emph{Syntax}:
5076 @code{CALL GET_ENVIRONMENT_VARIABLE(NAME[, VALUE, LENGTH, STATUS, TRIM_NAME)}
5078 @item @emph{Arguments}:
5079 @multitable @columnfractions .15 .70
5080 @item @var{NAME} @tab Shall be a scalar of type @code{CHARACTER}
5081 and of default kind.
5082 @item @var{VALUE} @tab Shall be a scalar of type @code{CHARACTER}
5083 and of default kind.
5084 @item @var{LENGTH} @tab Shall be a scalar of type @code{INTEGER}
5085 and of default kind.
5086 @item @var{STATUS} @tab Shall be a scalar of type @code{INTEGER}
5087 and of default kind.
5088 @item @var{TRIM_NAME} @tab Shall be a scalar of type @code{LOGICAL}
5089 and of default kind.
5092 @item @emph{Return value}:
5093 Stores the value of @var{NAME} in @var{VALUE}. If @var{VALUE} is
5094 not large enough to hold the data, it is truncated. If @var{NAME}
5095 is not set, @var{VALUE} will be filled with blanks. Argument @var{LENGTH}
5096 contains the length needed for storing the environment variable @var{NAME}
5097 or zero if it is not present. @var{STATUS} is -1 if @var{VALUE} is present
5098 but too short for the environment variable; it is 1 if the environment
5099 variable does not exist and 2 if the processor does not support environment
5100 variables; in all other cases @var{STATUS} is zero. If @var{TRIM_NAME} is
5101 present with the value @code{.FALSE.}, the trailing blanks in @var{NAME}
5102 are significant; otherwise they are not part of the environment variable
5105 @item @emph{Example}:
5108 CHARACTER(len=255) :: homedir
5109 CALL get_environment_variable("HOME", homedir)
5110 WRITE (*,*) TRIM(homedir)
5118 @section @code{GETGID} --- Group ID function
5120 @cindex system, group id
5123 @item @emph{Description}:
5124 Returns the numerical group ID of the current process.
5126 @item @emph{Standard}:
5132 @item @emph{Syntax}:
5133 @code{RESULT = GETGID()}
5135 @item @emph{Return value}:
5136 The return value of @code{GETGID} is an @code{INTEGER} of the default
5140 @item @emph{Example}:
5141 See @code{GETPID} for an example.
5143 @item @emph{See also}:
5144 @ref{GETPID}, @ref{GETUID}
5150 @section @code{GETLOG} --- Get login name
5152 @cindex system, login name
5156 @item @emph{Description}:
5157 Gets the username under which the program is running.
5159 @item @emph{Standard}:
5165 @item @emph{Syntax}:
5166 @code{CALL GETLOG(C)}
5168 @item @emph{Arguments}:
5169 @multitable @columnfractions .15 .70
5170 @item @var{C} @tab Shall be of type @code{CHARACTER} and of default kind.
5173 @item @emph{Return value}:
5174 Stores the current user name in @var{LOGIN}. (On systems where POSIX
5175 functions @code{geteuid} and @code{getpwuid} are not available, and
5176 the @code{getlogin} function is not implemented either, this will
5177 return a blank string.)
5179 @item @emph{Example}:
5182 CHARACTER(32) :: login
5188 @item @emph{See also}:
5195 @section @code{GETPID} --- Process ID function
5197 @cindex system, process id
5201 @item @emph{Description}:
5202 Returns the numerical process identifier of the current process.
5204 @item @emph{Standard}:
5210 @item @emph{Syntax}:
5211 @code{RESULT = GETPID()}
5213 @item @emph{Return value}:
5214 The return value of @code{GETPID} is an @code{INTEGER} of the default
5218 @item @emph{Example}:
5221 print *, "The current process ID is ", getpid()
5222 print *, "Your numerical user ID is ", getuid()
5223 print *, "Your numerical group ID is ", getgid()
5227 @item @emph{See also}:
5228 @ref{GETGID}, @ref{GETUID}
5234 @section @code{GETUID} --- User ID function
5236 @cindex system, user id
5240 @item @emph{Description}:
5241 Returns the numerical user ID of the current process.
5243 @item @emph{Standard}:
5249 @item @emph{Syntax}:
5250 @code{RESULT = GETUID()}
5252 @item @emph{Return value}:
5253 The return value of @code{GETUID} is an @code{INTEGER} of the default
5257 @item @emph{Example}:
5258 See @code{GETPID} for an example.
5260 @item @emph{See also}:
5261 @ref{GETPID}, @ref{GETLOG}
5267 @section @code{GMTIME} --- Convert time to GMT info
5269 @cindex time, conversion to GMT info
5272 @item @emph{Description}:
5273 Given a system time value @var{TIME} (as provided by the @code{TIME8()}
5274 intrinsic), fills @var{VALUES} with values extracted from it appropriate
5275 to the UTC time zone (Universal Coordinated Time, also known in some
5276 countries as GMT, Greenwich Mean Time), using @code{gmtime(3)}.
5278 @item @emph{Standard}:
5284 @item @emph{Syntax}:
5285 @code{CALL GMTIME(TIME, VALUES)}
5287 @item @emph{Arguments}:
5288 @multitable @columnfractions .15 .70
5289 @item @var{TIME} @tab An @code{INTEGER} scalar expression
5290 corresponding to a system time, with @code{INTENT(IN)}.
5291 @item @var{VALUES} @tab A default @code{INTEGER} array with 9 elements,
5292 with @code{INTENT(OUT)}.
5295 @item @emph{Return value}:
5296 The elements of @var{VALUES} are assigned as follows:
5298 @item Seconds after the minute, range 0--59 or 0--61 to allow for leap
5300 @item Minutes after the hour, range 0--59
5301 @item Hours past midnight, range 0--23
5302 @item Day of month, range 0--31
5303 @item Number of months since January, range 0--12
5304 @item Years since 1900
5305 @item Number of days since Sunday, range 0--6
5306 @item Days since January 1
5307 @item Daylight savings indicator: positive if daylight savings is in
5308 effect, zero if not, and negative if the information is not available.
5311 @item @emph{See also}:
5312 @ref{CTIME}, @ref{LTIME}, @ref{TIME}, @ref{TIME8}
5319 @section @code{HOSTNM} --- Get system host name
5321 @cindex system, host name
5324 @item @emph{Description}:
5325 Retrieves the host name of the system on which the program is running.
5327 This intrinsic is provided in both subroutine and function forms; however,
5328 only one form can be used in any given program unit.
5330 @item @emph{Standard}:
5334 Subroutine, function
5336 @item @emph{Syntax}:
5337 @multitable @columnfractions .80
5338 @item @code{CALL HOSTNM(C [, STATUS])}
5339 @item @code{STATUS = HOSTNM(NAME)}
5342 @item @emph{Arguments}:
5343 @multitable @columnfractions .15 .70
5344 @item @var{C} @tab Shall of type @code{CHARACTER} and of default kind.
5345 @item @var{STATUS} @tab (Optional) status flag of type @code{INTEGER}.
5346 Returns 0 on success, or a system specific error code otherwise.
5349 @item @emph{Return value}:
5350 In either syntax, @var{NAME} is set to the current hostname if it can
5351 be obtained, or to a blank string otherwise.
5358 @section @code{HUGE} --- Largest number of a kind
5360 @cindex limits, largest number
5361 @cindex model representation, largest number
5364 @item @emph{Description}:
5365 @code{HUGE(X)} returns the largest number that is not an infinity in
5366 the model of the type of @code{X}.
5368 @item @emph{Standard}:
5369 Fortran 95 and later
5374 @item @emph{Syntax}:
5375 @code{RESULT = HUGE(X)}
5377 @item @emph{Arguments}:
5378 @multitable @columnfractions .15 .70
5379 @item @var{X} @tab Shall be of type @code{REAL} or @code{INTEGER}.
5382 @item @emph{Return value}:
5383 The return value is of the same type and kind as @var{X}
5385 @item @emph{Example}:
5387 program test_huge_tiny
5388 print *, huge(0), huge(0.0), huge(0.0d0)
5389 print *, tiny(0.0), tiny(0.0d0)
5390 end program test_huge_tiny
5397 @section @code{HYPOT} --- Euclidean distance function
5399 @cindex Euclidean distance
5402 @item @emph{Description}:
5403 @code{HYPOT(X,Y)} is the Euclidean distance function. It is equal to
5404 @math{\sqrt{X^2 + Y^2}}, without undue underflow or overflow.
5406 @item @emph{Standard}:
5407 Fortran 2008 and later
5412 @item @emph{Syntax}:
5413 @code{RESULT = HYPOT(X, Y)}
5415 @item @emph{Arguments}:
5416 @multitable @columnfractions .15 .70
5417 @item @var{X} @tab The type shall be @code{REAL}.
5418 @item @var{Y} @tab The type and kind type parameter shall be the same as
5422 @item @emph{Return value}:
5423 The return value has the same type and kind type parameter as @var{X}.
5425 @item @emph{Example}:
5428 real(4) :: x = 1.e0_4, y = 0.5e0_4
5430 end program test_hypot
5437 @section @code{IACHAR} --- Code in @acronym{ASCII} collating sequence
5439 @cindex @acronym{ASCII} collating sequence
5440 @cindex collating sequence, @acronym{ASCII}
5441 @cindex conversion, to integer
5444 @item @emph{Description}:
5445 @code{IACHAR(C)} returns the code for the @acronym{ASCII} character
5446 in the first character position of @code{C}.
5448 @item @emph{Standard}:
5449 Fortran 95 and later, with @var{KIND} argument Fortran 2003 and later
5454 @item @emph{Syntax}:
5455 @code{RESULT = IACHAR(C [, KIND])}
5457 @item @emph{Arguments}:
5458 @multitable @columnfractions .15 .70
5459 @item @var{C} @tab Shall be a scalar @code{CHARACTER}, with @code{INTENT(IN)}
5460 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
5461 expression indicating the kind parameter of the result.
5464 @item @emph{Return value}:
5465 The return value is of type @code{INTEGER} and of kind @var{KIND}. If
5466 @var{KIND} is absent, the return value is of default integer kind.
5468 @item @emph{Example}:
5473 end program test_iachar
5477 See @ref{ICHAR} for a discussion of converting between numerical values
5478 and formatted string representations.
5480 @item @emph{See also}:
5481 @ref{ACHAR}, @ref{CHAR}, @ref{ICHAR}
5488 @section @code{IAND} --- Bitwise logical and
5490 @cindex bitwise logical and
5491 @cindex logical and, bitwise
5494 @item @emph{Description}:
5495 Bitwise logical @code{AND}.
5497 @item @emph{Standard}:
5498 Fortran 95 and later
5503 @item @emph{Syntax}:
5504 @code{RESULT = IAND(I, J)}
5506 @item @emph{Arguments}:
5507 @multitable @columnfractions .15 .70
5508 @item @var{I} @tab The type shall be @code{INTEGER}.
5509 @item @var{J} @tab The type shall be @code{INTEGER}, of the same
5510 kind as @var{I}. (As a GNU extension, different kinds are also
5514 @item @emph{Return value}:
5515 The return type is @code{INTEGER}, of the same kind as the
5516 arguments. (If the argument kinds differ, it is of the same kind as
5517 the larger argument.)
5519 @item @emph{Example}:
5523 DATA a / Z'F' /, b / Z'3' /
5524 WRITE (*,*) IAND(a, b)
5528 @item @emph{See also}:
5529 @ref{IOR}, @ref{IEOR}, @ref{IBITS}, @ref{IBSET}, @ref{IBCLR}, @ref{NOT}
5536 @section @code{IARGC} --- Get the number of command line arguments
5538 @cindex command-line arguments
5539 @cindex command-line arguments, number of
5540 @cindex arguments, to program
5543 @item @emph{Description}:
5544 @code{IARGC()} returns the number of arguments passed on the
5545 command line when the containing program was invoked.
5547 This intrinsic routine is provided for backwards compatibility with
5548 GNU Fortran 77. In new code, programmers should consider the use of
5549 the @ref{COMMAND_ARGUMENT_COUNT} intrinsic defined by the Fortran 2003
5552 @item @emph{Standard}:
5558 @item @emph{Syntax}:
5559 @code{RESULT = IARGC()}
5561 @item @emph{Arguments}:
5564 @item @emph{Return value}:
5565 The number of command line arguments, type @code{INTEGER(4)}.
5567 @item @emph{Example}:
5570 @item @emph{See also}:
5571 GNU Fortran 77 compatibility subroutine: @ref{GETARG}
5573 Fortran 2003 functions and subroutines: @ref{GET_COMMAND},
5574 @ref{GET_COMMAND_ARGUMENT}, @ref{COMMAND_ARGUMENT_COUNT}
5580 @section @code{IBCLR} --- Clear bit
5586 @item @emph{Description}:
5587 @code{IBCLR} returns the value of @var{I} with the bit at position
5588 @var{POS} set to zero.
5590 @item @emph{Standard}:
5591 Fortran 95 and later
5596 @item @emph{Syntax}:
5597 @code{RESULT = IBCLR(I, POS)}
5599 @item @emph{Arguments}:
5600 @multitable @columnfractions .15 .70
5601 @item @var{I} @tab The type shall be @code{INTEGER}.
5602 @item @var{POS} @tab The type shall be @code{INTEGER}.
5605 @item @emph{Return value}:
5606 The return value is of type @code{INTEGER} and of the same kind as
5609 @item @emph{See also}:
5610 @ref{IBITS}, @ref{IBSET}, @ref{IAND}, @ref{IOR}, @ref{IEOR}, @ref{MVBITS}
5617 @section @code{IBITS} --- Bit extraction
5620 @cindex bits, extract
5623 @item @emph{Description}:
5624 @code{IBITS} extracts a field of length @var{LEN} from @var{I},
5625 starting from bit position @var{POS} and extending left for @var{LEN}
5626 bits. The result is right-justified and the remaining bits are
5627 zeroed. The value of @code{POS+LEN} must be less than or equal to the
5628 value @code{BIT_SIZE(I)}.
5630 @item @emph{Standard}:
5631 Fortran 95 and later
5636 @item @emph{Syntax}:
5637 @code{RESULT = IBITS(I, POS, LEN)}
5639 @item @emph{Arguments}:
5640 @multitable @columnfractions .15 .70
5641 @item @var{I} @tab The type shall be @code{INTEGER}.
5642 @item @var{POS} @tab The type shall be @code{INTEGER}.
5643 @item @var{LEN} @tab The type shall be @code{INTEGER}.
5646 @item @emph{Return value}:
5647 The return value is of type @code{INTEGER} and of the same kind as
5650 @item @emph{See also}:
5651 @ref{BIT_SIZE}, @ref{IBCLR}, @ref{IBSET}, @ref{IAND}, @ref{IOR}, @ref{IEOR}
5657 @section @code{IBSET} --- Set bit
5662 @item @emph{Description}:
5663 @code{IBSET} returns the value of @var{I} with the bit at position
5664 @var{POS} set to one.
5666 @item @emph{Standard}:
5667 Fortran 95 and later
5672 @item @emph{Syntax}:
5673 @code{RESULT = IBSET(I, POS)}
5675 @item @emph{Arguments}:
5676 @multitable @columnfractions .15 .70
5677 @item @var{I} @tab The type shall be @code{INTEGER}.
5678 @item @var{POS} @tab The type shall be @code{INTEGER}.
5681 @item @emph{Return value}:
5682 The return value is of type @code{INTEGER} and of the same kind as
5685 @item @emph{See also}:
5686 @ref{IBCLR}, @ref{IBITS}, @ref{IAND}, @ref{IOR}, @ref{IEOR}, @ref{MVBITS}
5693 @section @code{ICHAR} --- Character-to-integer conversion function
5695 @cindex conversion, to integer
5698 @item @emph{Description}:
5699 @code{ICHAR(C)} returns the code for the character in the first character
5700 position of @code{C} in the system's native character set.
5701 The correspondence between characters and their codes is not necessarily
5702 the same across different GNU Fortran implementations.
5704 @item @emph{Standard}:
5705 Fortan 95 and later, with @var{KIND} argument Fortran 2003 and later
5710 @item @emph{Syntax}:
5711 @code{RESULT = ICHAR(C [, KIND])}
5713 @item @emph{Arguments}:
5714 @multitable @columnfractions .15 .70
5715 @item @var{C} @tab Shall be a scalar @code{CHARACTER}, with @code{INTENT(IN)}
5716 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
5717 expression indicating the kind parameter of the result.
5720 @item @emph{Return value}:
5721 The return value is of type @code{INTEGER} and of kind @var{KIND}. If
5722 @var{KIND} is absent, the return value is of default integer kind.
5724 @item @emph{Example}:
5729 end program test_ichar
5732 @item @emph{Specific names}:
5733 @multitable @columnfractions .20 .20 .20 .25
5734 @item Name @tab Argument @tab Return type @tab Standard
5735 @item @code{ICHAR(C)} @tab @code{CHARACTER C} @tab @code{INTEGER(4)} @tab Fortran 77 and later
5739 No intrinsic exists to convert between a numeric value and a formatted
5740 character string representation -- for instance, given the
5741 @code{CHARACTER} value @code{'154'}, obtaining an @code{INTEGER} or
5742 @code{REAL} value with the value 154, or vice versa. Instead, this
5743 functionality is provided by internal-file I/O, as in the following
5748 character(len=10) string, string2
5751 ! Convert a string to a numeric value
5752 read (string,'(I10)') value
5755 ! Convert a value to a formatted string
5756 write (string2,'(I10)') value
5758 end program read_val
5761 @item @emph{See also}:
5762 @ref{ACHAR}, @ref{CHAR}, @ref{IACHAR}
5769 @section @code{IDATE} --- Get current local time subroutine (day/month/year)
5771 @cindex date, current
5772 @cindex current date
5775 @item @emph{Description}:
5776 @code{IDATE(VALUES)} Fills @var{VALUES} with the numerical values at the
5777 current local time. The day (in the range 1-31), month (in the range 1-12),
5778 and year appear in elements 1, 2, and 3 of @var{VALUES}, respectively.
5779 The year has four significant digits.
5781 @item @emph{Standard}:
5787 @item @emph{Syntax}:
5788 @code{CALL IDATE(VALUES)}
5790 @item @emph{Arguments}:
5791 @multitable @columnfractions .15 .70
5792 @item @var{VALUES} @tab The type shall be @code{INTEGER, DIMENSION(3)} and
5793 the kind shall be the default integer kind.
5796 @item @emph{Return value}:
5797 Does not return anything.
5799 @item @emph{Example}:
5802 integer, dimension(3) :: tarray
5807 end program test_idate
5814 @section @code{IEOR} --- Bitwise logical exclusive or
5816 @cindex bitwise logical exclusive or
5817 @cindex logical exclusive or, bitwise
5820 @item @emph{Description}:
5821 @code{IEOR} returns the bitwise boolean exclusive-OR of @var{I} and
5824 @item @emph{Standard}:
5825 Fortran 95 and later
5830 @item @emph{Syntax}:
5831 @code{RESULT = IEOR(I, J)}
5833 @item @emph{Arguments}:
5834 @multitable @columnfractions .15 .70
5835 @item @var{I} @tab The type shall be @code{INTEGER}.
5836 @item @var{J} @tab The type shall be @code{INTEGER}, of the same
5837 kind as @var{I}. (As a GNU extension, different kinds are also
5841 @item @emph{Return value}:
5842 The return type is @code{INTEGER}, of the same kind as the
5843 arguments. (If the argument kinds differ, it is of the same kind as
5844 the larger argument.)
5846 @item @emph{See also}:
5847 @ref{IOR}, @ref{IAND}, @ref{IBITS}, @ref{IBSET}, @ref{IBCLR}, @ref{NOT}
5853 @section @code{IERRNO} --- Get the last system error number
5855 @cindex system, error handling
5858 @item @emph{Description}:
5859 Returns the last system error number, as given by the C @code{errno()}
5862 @item @emph{Standard}:
5868 @item @emph{Syntax}:
5869 @code{RESULT = IERRNO()}
5871 @item @emph{Arguments}:
5874 @item @emph{Return value}:
5875 The return value is of type @code{INTEGER} and of the default integer
5878 @item @emph{See also}:
5884 @node INDEX intrinsic
5885 @section @code{INDEX} --- Position of a substring within a string
5887 @cindex substring position
5888 @cindex string, find substring
5891 @item @emph{Description}:
5892 Returns the position of the start of the first occurrence of string
5893 @var{SUBSTRING} as a substring in @var{STRING}, counting from one. If
5894 @var{SUBSTRING} is not present in @var{STRING}, zero is returned. If
5895 the @var{BACK} argument is present and true, the return value is the
5896 start of the last occurrence rather than the first.
5898 @item @emph{Standard}:
5899 Fortran 77 and later, with @var{KIND} argument Fortran 2003 and later
5904 @item @emph{Syntax}:
5905 @code{RESULT = INDEX(STRING, SUBSTRING [, BACK [, KIND]])}
5907 @item @emph{Arguments}:
5908 @multitable @columnfractions .15 .70
5909 @item @var{STRING} @tab Shall be a scalar @code{CHARACTER}, with
5911 @item @var{SUBSTRING} @tab Shall be a scalar @code{CHARACTER}, with
5913 @item @var{BACK} @tab (Optional) Shall be a scalar @code{LOGICAL}, with
5915 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
5916 expression indicating the kind parameter of the result.
5919 @item @emph{Return value}:
5920 The return value is of type @code{INTEGER} and of kind @var{KIND}. If
5921 @var{KIND} is absent, the return value is of default integer kind.
5923 @item @emph{Specific names}:
5924 @multitable @columnfractions .20 .20 .20 .25
5925 @item Name @tab Argument @tab Return type @tab Standard
5926 @item @code{INDEX(STRING, SUBSTRING)} @tab @code{CHARACTER} @tab @code{INTEGER(4)} @tab Fortran 77 and later
5929 @item @emph{See also}:
5930 @ref{SCAN}, @ref{VERIFY}
5936 @section @code{INT} --- Convert to integer type
5940 @cindex conversion, to integer
5943 @item @emph{Description}:
5944 Convert to integer type
5946 @item @emph{Standard}:
5947 Fortran 77 and later
5952 @item @emph{Syntax}:
5953 @code{RESULT = INT(A [, KIND))}
5955 @item @emph{Arguments}:
5956 @multitable @columnfractions .15 .70
5957 @item @var{A} @tab Shall be of type @code{INTEGER},
5958 @code{REAL}, or @code{COMPLEX}.
5959 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
5960 expression indicating the kind parameter of the result.
5963 @item @emph{Return value}:
5964 These functions return a @code{INTEGER} variable or array under
5965 the following rules:
5969 If @var{A} is of type @code{INTEGER}, @code{INT(A) = A}
5971 If @var{A} is of type @code{REAL} and @math{|A| < 1}, @code{INT(A)} equals @code{0}.
5972 If @math{|A| \geq 1}, then @code{INT(A)} equals the largest integer that does not exceed
5973 the range of @var{A} and whose sign is the same as the sign of @var{A}.
5975 If @var{A} is of type @code{COMPLEX}, rule B is applied to the real part of @var{A}.
5978 @item @emph{Example}:
5982 complex :: z = (-3.7, 1.0)
5984 print *, int(z), int(z,8)
5988 @item @emph{Specific names}:
5989 @multitable @columnfractions .20 .20 .20 .25
5990 @item Name @tab Argument @tab Return type @tab Standard
5991 @item @code{INT(A)} @tab @code{REAL(4) A} @tab @code{INTEGER} @tab Fortran 77 and later
5992 @item @code{IFIX(A)} @tab @code{REAL(4) A} @tab @code{INTEGER} @tab Fortran 77 and later
5993 @item @code{IDINT(A)} @tab @code{REAL(8) A} @tab @code{INTEGER} @tab Fortran 77 and later
6000 @section @code{INT2} --- Convert to 16-bit integer type
6003 @cindex conversion, to integer
6006 @item @emph{Description}:
6007 Convert to a @code{KIND=2} integer type. This is equivalent to the
6008 standard @code{INT} intrinsic with an optional argument of
6009 @code{KIND=2}, and is only included for backwards compatibility.
6011 The @code{SHORT} intrinsic is equivalent to @code{INT2}.
6013 @item @emph{Standard}:
6019 @item @emph{Syntax}:
6020 @code{RESULT = INT2(A)}
6022 @item @emph{Arguments}:
6023 @multitable @columnfractions .15 .70
6024 @item @var{A} @tab Shall be of type @code{INTEGER},
6025 @code{REAL}, or @code{COMPLEX}.
6028 @item @emph{Return value}:
6029 The return value is a @code{INTEGER(2)} variable.
6031 @item @emph{See also}:
6032 @ref{INT}, @ref{INT8}, @ref{LONG}
6038 @section @code{INT8} --- Convert to 64-bit integer type
6040 @cindex conversion, to integer
6043 @item @emph{Description}:
6044 Convert to a @code{KIND=8} integer type. This is equivalent to the
6045 standard @code{INT} intrinsic with an optional argument of
6046 @code{KIND=8}, and is only included for backwards compatibility.
6048 @item @emph{Standard}:
6054 @item @emph{Syntax}:
6055 @code{RESULT = INT8(A)}
6057 @item @emph{Arguments}:
6058 @multitable @columnfractions .15 .70
6059 @item @var{A} @tab Shall be of type @code{INTEGER},
6060 @code{REAL}, or @code{COMPLEX}.
6063 @item @emph{Return value}:
6064 The return value is a @code{INTEGER(8)} variable.
6066 @item @emph{See also}:
6067 @ref{INT}, @ref{INT2}, @ref{LONG}
6073 @section @code{IOR} --- Bitwise logical or
6075 @cindex bitwise logical or
6076 @cindex logical or, bitwise
6079 @item @emph{Description}:
6080 @code{IOR} returns the bitwise boolean inclusive-OR of @var{I} and
6083 @item @emph{Standard}:
6084 Fortran 95 and later
6089 @item @emph{Syntax}:
6090 @code{RESULT = IOR(I, J)}
6092 @item @emph{Arguments}:
6093 @multitable @columnfractions .15 .70
6094 @item @var{I} @tab The type shall be @code{INTEGER}.
6095 @item @var{J} @tab The type shall be @code{INTEGER}, of the same
6096 kind as @var{I}. (As a GNU extension, different kinds are also
6100 @item @emph{Return value}:
6101 The return type is @code{INTEGER}, of the same kind as the
6102 arguments. (If the argument kinds differ, it is of the same kind as
6103 the larger argument.)
6105 @item @emph{See also}:
6106 @ref{IEOR}, @ref{IAND}, @ref{IBITS}, @ref{IBSET}, @ref{IBCLR}, @ref{NOT}
6112 @section @code{IRAND} --- Integer pseudo-random number
6114 @cindex random number generation
6117 @item @emph{Description}:
6118 @code{IRAND(FLAG)} returns a pseudo-random number from a uniform
6119 distribution between 0 and a system-dependent limit (which is in most
6120 cases 2147483647). If @var{FLAG} is 0, the next number
6121 in the current sequence is returned; if @var{FLAG} is 1, the generator
6122 is restarted by @code{CALL SRAND(0)}; if @var{FLAG} has any other value,
6123 it is used as a new seed with @code{SRAND}.
6125 This intrinsic routine is provided for backwards compatibility with
6126 GNU Fortran 77. It implements a simple modulo generator as provided
6127 by @command{g77}. For new code, one should consider the use of
6128 @ref{RANDOM_NUMBER} as it implements a superior algorithm.
6130 @item @emph{Standard}:
6136 @item @emph{Syntax}:
6137 @code{RESULT = IRAND(I)}
6139 @item @emph{Arguments}:
6140 @multitable @columnfractions .15 .70
6141 @item @var{I} @tab Shall be a scalar @code{INTEGER} of kind 4.
6144 @item @emph{Return value}:
6145 The return value is of @code{INTEGER(kind=4)} type.
6147 @item @emph{Example}:
6150 integer,parameter :: seed = 86456
6153 print *, irand(), irand(), irand(), irand()
6154 print *, irand(seed), irand(), irand(), irand()
6155 end program test_irand
6163 @section @code{IMAGE_INDEX} --- Function that converts a cosubscript to an image index
6164 @fnindex IMAGE_INDEX
6165 @cindex coarray, IMAGE_INDEX
6166 @cindex images, cosubscript to image index conversion
6169 @item @emph{Description}:
6170 Returns the image index belonging to a cosubscript.
6172 @item @emph{Standard}:
6173 Fortran 2008 and later
6178 @item @emph{Syntax}:
6179 @code{RESULT = IMAGE_INDEX(COARRAY, SUB)}
6181 @item @emph{Arguments}: None.
6182 @multitable @columnfractions .15 .70
6183 @item @var{COARRAY} @tab Coarray of any type.
6184 @item @var{SUB} @tab default integer rank-1 array of a size equal to
6185 the corank of @var{COARRAY}.
6189 @item @emph{Return value}:
6190 Scalar default integer with the value of the image index which corresponds
6191 to the cosubscripts. For invalid cosubscripts the result is zero.
6193 @item @emph{Example}:
6195 INTEGER :: array[2,-1:4,8,*]
6196 ! Writes 28 (or 0 if there are fewer than 28 images)
6197 WRITE (*,*) IMAGE_INDEX (array, [2,0,3,1])
6200 @item @emph{See also}:
6201 @ref{THIS_IMAGE}, @ref{NUM_IMAGES}
6207 @section @code{IS_IOSTAT_END} --- Test for end-of-file value
6208 @fnindex IS_IOSTAT_END
6209 @cindex IOSTAT, end of file
6212 @item @emph{Description}:
6213 @code{IS_IOSTAT_END} tests whether an variable has the value of the I/O
6214 status ``end of file''. The function is equivalent to comparing the variable
6215 with the @code{IOSTAT_END} parameter of the intrinsic module
6216 @code{ISO_FORTRAN_ENV}.
6218 @item @emph{Standard}:
6219 Fortran 2003 and later
6224 @item @emph{Syntax}:
6225 @code{RESULT = IS_IOSTAT_END(I)}
6227 @item @emph{Arguments}:
6228 @multitable @columnfractions .15 .70
6229 @item @var{I} @tab Shall be of the type @code{INTEGER}.
6232 @item @emph{Return value}:
6233 Returns a @code{LOGICAL} of the default kind, which @code{.TRUE.} if
6234 @var{I} has the value which indicates an end of file condition for
6235 IOSTAT= specifiers, and is @code{.FALSE.} otherwise.
6237 @item @emph{Example}:
6242 OPEN(88, FILE='test.dat')
6243 READ(88, *, IOSTAT=stat) i
6244 IF(IS_IOSTAT_END(stat)) STOP 'END OF FILE'
6252 @section @code{IS_IOSTAT_EOR} --- Test for end-of-record value
6253 @fnindex IS_IOSTAT_EOR
6254 @cindex IOSTAT, end of record
6257 @item @emph{Description}:
6258 @code{IS_IOSTAT_EOR} tests whether an variable has the value of the I/O
6259 status ``end of record''. The function is equivalent to comparing the
6260 variable with the @code{IOSTAT_EOR} parameter of the intrinsic module
6261 @code{ISO_FORTRAN_ENV}.
6263 @item @emph{Standard}:
6264 Fortran 2003 and later
6269 @item @emph{Syntax}:
6270 @code{RESULT = IS_IOSTAT_EOR(I)}
6272 @item @emph{Arguments}:
6273 @multitable @columnfractions .15 .70
6274 @item @var{I} @tab Shall be of the type @code{INTEGER}.
6277 @item @emph{Return value}:
6278 Returns a @code{LOGICAL} of the default kind, which @code{.TRUE.} if
6279 @var{I} has the value which indicates an end of file condition for
6280 IOSTAT= specifiers, and is @code{.FALSE.} otherwise.
6282 @item @emph{Example}:
6286 INTEGER :: stat, i(50)
6287 OPEN(88, FILE='test.dat', FORM='UNFORMATTED')
6288 READ(88, IOSTAT=stat) i
6289 IF(IS_IOSTAT_EOR(stat)) STOP 'END OF RECORD'
6297 @section @code{ISATTY} --- Whether a unit is a terminal device.
6299 @cindex system, terminal
6302 @item @emph{Description}:
6303 Determine whether a unit is connected to a terminal device.
6305 @item @emph{Standard}:
6311 @item @emph{Syntax}:
6312 @code{RESULT = ISATTY(UNIT)}
6314 @item @emph{Arguments}:
6315 @multitable @columnfractions .15 .70
6316 @item @var{UNIT} @tab Shall be a scalar @code{INTEGER}.
6319 @item @emph{Return value}:
6320 Returns @code{.TRUE.} if the @var{UNIT} is connected to a terminal
6321 device, @code{.FALSE.} otherwise.
6323 @item @emph{Example}:
6326 INTEGER(kind=1) :: unit
6328 write(*,*) isatty(unit=unit)
6332 @item @emph{See also}:
6339 @section @code{ISHFT} --- Shift bits
6344 @item @emph{Description}:
6345 @code{ISHFT} returns a value corresponding to @var{I} with all of the
6346 bits shifted @var{SHIFT} places. A value of @var{SHIFT} greater than
6347 zero corresponds to a left shift, a value of zero corresponds to no
6348 shift, and a value less than zero corresponds to a right shift. If the
6349 absolute value of @var{SHIFT} is greater than @code{BIT_SIZE(I)}, the
6350 value is undefined. Bits shifted out from the left end or right end are
6351 lost; zeros are shifted in from the opposite end.
6353 @item @emph{Standard}:
6354 Fortran 95 and later
6359 @item @emph{Syntax}:
6360 @code{RESULT = ISHFT(I, SHIFT)}
6362 @item @emph{Arguments}:
6363 @multitable @columnfractions .15 .70
6364 @item @var{I} @tab The type shall be @code{INTEGER}.
6365 @item @var{SHIFT} @tab The type shall be @code{INTEGER}.
6368 @item @emph{Return value}:
6369 The return value is of type @code{INTEGER} and of the same kind as
6372 @item @emph{See also}:
6379 @section @code{ISHFTC} --- Shift bits circularly
6381 @cindex bits, shift circular
6384 @item @emph{Description}:
6385 @code{ISHFTC} returns a value corresponding to @var{I} with the
6386 rightmost @var{SIZE} bits shifted circularly @var{SHIFT} places; that
6387 is, bits shifted out one end are shifted into the opposite end. A value
6388 of @var{SHIFT} greater than zero corresponds to a left shift, a value of
6389 zero corresponds to no shift, and a value less than zero corresponds to
6390 a right shift. The absolute value of @var{SHIFT} must be less than
6391 @var{SIZE}. If the @var{SIZE} argument is omitted, it is taken to be
6392 equivalent to @code{BIT_SIZE(I)}.
6394 @item @emph{Standard}:
6395 Fortran 95 and later
6400 @item @emph{Syntax}:
6401 @code{RESULT = ISHFTC(I, SHIFT [, SIZE])}
6403 @item @emph{Arguments}:
6404 @multitable @columnfractions .15 .70
6405 @item @var{I} @tab The type shall be @code{INTEGER}.
6406 @item @var{SHIFT} @tab The type shall be @code{INTEGER}.
6407 @item @var{SIZE} @tab (Optional) The type shall be @code{INTEGER};
6408 the value must be greater than zero and less than or equal to
6412 @item @emph{Return value}:
6413 The return value is of type @code{INTEGER} and of the same kind as
6416 @item @emph{See also}:
6423 @section @code{ISNAN} --- Test for a NaN
6428 @item @emph{Description}:
6429 @code{ISNAN} tests whether a floating-point value is an IEEE
6431 @item @emph{Standard}:
6437 @item @emph{Syntax}:
6440 @item @emph{Arguments}:
6441 @multitable @columnfractions .15 .70
6442 @item @var{X} @tab Variable of the type @code{REAL}.
6446 @item @emph{Return value}:
6447 Returns a default-kind @code{LOGICAL}. The returned value is @code{TRUE}
6448 if @var{X} is a NaN and @code{FALSE} otherwise.
6450 @item @emph{Example}:
6457 if (isnan(x)) stop '"x" is a NaN'
6458 end program test_nan
6465 @section @code{ITIME} --- Get current local time subroutine (hour/minutes/seconds)
6467 @cindex time, current
6468 @cindex current time
6471 @item @emph{Description}:
6472 @code{IDATE(VALUES)} Fills @var{VALUES} with the numerical values at the
6473 current local time. The hour (in the range 1-24), minute (in the range 1-60),
6474 and seconds (in the range 1-60) appear in elements 1, 2, and 3 of @var{VALUES},
6477 @item @emph{Standard}:
6483 @item @emph{Syntax}:
6484 @code{CALL ITIME(VALUES)}
6486 @item @emph{Arguments}:
6487 @multitable @columnfractions .15 .70
6488 @item @var{VALUES} @tab The type shall be @code{INTEGER, DIMENSION(3)}
6489 and the kind shall be the default integer kind.
6492 @item @emph{Return value}:
6493 Does not return anything.
6496 @item @emph{Example}:
6499 integer, dimension(3) :: tarray
6504 end program test_itime
6511 @section @code{KILL} --- Send a signal to a process
6515 @item @emph{Description}:
6516 @item @emph{Standard}:
6517 Sends the signal specified by @var{SIGNAL} to the process @var{PID}.
6520 This intrinsic is provided in both subroutine and function forms; however,
6521 only one form can be used in any given program unit.
6524 Subroutine, function
6526 @item @emph{Syntax}:
6527 @code{CALL KILL(C, VALUE [, STATUS])}
6529 @item @emph{Arguments}:
6530 @multitable @columnfractions .15 .70
6531 @item @var{C} @tab Shall be a scalar @code{INTEGER}, with
6533 @item @var{VALUE} @tab Shall be a scalar @code{INTEGER}, with
6535 @item @var{STATUS} @tab (Optional) status flag of type @code{INTEGER(4)} or
6536 @code{INTEGER(8)}. Returns 0 on success, or a system-specific error code
6540 @item @emph{See also}:
6541 @ref{ABORT}, @ref{EXIT}
6547 @section @code{KIND} --- Kind of an entity
6552 @item @emph{Description}:
6553 @code{KIND(X)} returns the kind value of the entity @var{X}.
6555 @item @emph{Standard}:
6556 Fortran 95 and later
6561 @item @emph{Syntax}:
6564 @item @emph{Arguments}:
6565 @multitable @columnfractions .15 .70
6566 @item @var{X} @tab Shall be of type @code{LOGICAL}, @code{INTEGER},
6567 @code{REAL}, @code{COMPLEX} or @code{CHARACTER}.
6570 @item @emph{Return value}:
6571 The return value is a scalar of type @code{INTEGER} and of the default
6574 @item @emph{Example}:
6577 integer,parameter :: kc = kind(' ')
6578 integer,parameter :: kl = kind(.true.)
6580 print *, "The default character kind is ", kc
6581 print *, "The default logical kind is ", kl
6582 end program test_kind
6590 @section @code{LBOUND} --- Lower dimension bounds of an array
6592 @cindex array, lower bound
6595 @item @emph{Description}:
6596 Returns the lower bounds of an array, or a single lower bound
6597 along the @var{DIM} dimension.
6598 @item @emph{Standard}:
6599 Fortran 95 and later, with @var{KIND} argument Fortran 2003 and later
6604 @item @emph{Syntax}:
6605 @code{RESULT = LBOUND(ARRAY [, DIM [, KIND]])}
6607 @item @emph{Arguments}:
6608 @multitable @columnfractions .15 .70
6609 @item @var{ARRAY} @tab Shall be an array, of any type.
6610 @item @var{DIM} @tab (Optional) Shall be a scalar @code{INTEGER}.
6611 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
6612 expression indicating the kind parameter of the result.
6615 @item @emph{Return value}:
6616 The return value is of type @code{INTEGER} and of kind @var{KIND}. If
6617 @var{KIND} is absent, the return value is of default integer kind.
6618 If @var{DIM} is absent, the result is an array of the lower bounds of
6619 @var{ARRAY}. If @var{DIM} is present, the result is a scalar
6620 corresponding to the lower bound of the array along that dimension. If
6621 @var{ARRAY} is an expression rather than a whole array or array
6622 structure component, or if it has a zero extent along the relevant
6623 dimension, the lower bound is taken to be 1.
6625 @item @emph{See also}:
6626 @ref{UBOUND}, @ref{LCOBOUND}
6632 @section @code{LCOBOUND} --- Lower codimension bounds of an array
6634 @cindex coarray, lower bound
6637 @item @emph{Description}:
6638 Returns the lower bounds of a coarray, or a single lower cobound
6639 along the @var{DIM} codimension.
6640 @item @emph{Standard}:
6641 Fortran 2008 and later
6646 @item @emph{Syntax}:
6647 @code{RESULT = LCOBOUND(COARRAY [, DIM [, KIND]])}
6649 @item @emph{Arguments}:
6650 @multitable @columnfractions .15 .70
6651 @item @var{ARRAY} @tab Shall be an coarray, of any type.
6652 @item @var{DIM} @tab (Optional) Shall be a scalar @code{INTEGER}.
6653 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
6654 expression indicating the kind parameter of the result.
6657 @item @emph{Return value}:
6658 The return value is of type @code{INTEGER} and of kind @var{KIND}. If
6659 @var{KIND} is absent, the return value is of default integer kind.
6660 If @var{DIM} is absent, the result is an array of the lower cobounds of
6661 @var{COARRAY}. If @var{DIM} is present, the result is a scalar
6662 corresponding to the lower cobound of the array along that codimension.
6664 @item @emph{See also}:
6665 @ref{UCOBOUND}, @ref{LBOUND}
6671 @section @code{LEADZ} --- Number of leading zero bits of an integer
6676 @item @emph{Description}:
6677 @code{LEADZ} returns the number of leading zero bits of an integer.
6679 @item @emph{Standard}:
6680 Fortran 2008 and later
6685 @item @emph{Syntax}:
6686 @code{RESULT = LEADZ(I)}
6688 @item @emph{Arguments}:
6689 @multitable @columnfractions .15 .70
6690 @item @var{I} @tab Shall be of type @code{INTEGER}.
6693 @item @emph{Return value}:
6694 The type of the return value is the default @code{INTEGER}.
6695 If all the bits of @code{I} are zero, the result value is @code{BIT_SIZE(I)}.
6697 @item @emph{Example}:
6700 WRITE (*,*) LEADZ(1) ! prints 8 if BITSIZE(I) has the value 32
6704 @item @emph{See also}:
6705 @ref{BIT_SIZE}, @ref{TRAILZ}
6711 @section @code{LEN} --- Length of a character entity
6713 @cindex string, length
6716 @item @emph{Description}:
6717 Returns the length of a character string. If @var{STRING} is an array,
6718 the length of an element of @var{STRING} is returned. Note that
6719 @var{STRING} need not be defined when this intrinsic is invoked, since
6720 only the length, not the content, of @var{STRING} is needed.
6722 @item @emph{Standard}:
6723 Fortran 77 and later, with @var{KIND} argument Fortran 2003 and later
6728 @item @emph{Syntax}:
6729 @code{L = LEN(STRING [, KIND])}
6731 @item @emph{Arguments}:
6732 @multitable @columnfractions .15 .70
6733 @item @var{STRING} @tab Shall be a scalar or array of type
6734 @code{CHARACTER}, with @code{INTENT(IN)}
6735 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
6736 expression indicating the kind parameter of the result.
6739 @item @emph{Return value}:
6740 The return value is of type @code{INTEGER} and of kind @var{KIND}. If
6741 @var{KIND} is absent, the return value is of default integer kind.
6744 @item @emph{Specific names}:
6745 @multitable @columnfractions .20 .20 .20 .25
6746 @item Name @tab Argument @tab Return type @tab Standard
6747 @item @code{LEN(STRING)} @tab @code{CHARACTER} @tab @code{INTEGER} @tab Fortran 77 and later
6751 @item @emph{See also}:
6752 @ref{LEN_TRIM}, @ref{ADJUSTL}, @ref{ADJUSTR}
6758 @section @code{LEN_TRIM} --- Length of a character entity without trailing blank characters
6760 @cindex string, length, without trailing whitespace
6763 @item @emph{Description}:
6764 Returns the length of a character string, ignoring any trailing blanks.
6766 @item @emph{Standard}:
6767 Fortran 95 and later, with @var{KIND} argument Fortran 2003 and later
6772 @item @emph{Syntax}:
6773 @code{RESULT = LEN_TRIM(STRING [, KIND])}
6775 @item @emph{Arguments}:
6776 @multitable @columnfractions .15 .70
6777 @item @var{STRING} @tab Shall be a scalar of type @code{CHARACTER},
6778 with @code{INTENT(IN)}
6779 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
6780 expression indicating the kind parameter of the result.
6783 @item @emph{Return value}:
6784 The return value is of type @code{INTEGER} and of kind @var{KIND}. If
6785 @var{KIND} is absent, the return value is of default integer kind.
6787 @item @emph{See also}:
6788 @ref{LEN}, @ref{ADJUSTL}, @ref{ADJUSTR}
6794 @section @code{LGE} --- Lexical greater than or equal
6796 @cindex lexical comparison of strings
6797 @cindex string, comparison
6800 @item @emph{Description}:
6801 Determines whether one string is lexically greater than or equal to
6802 another string, where the two strings are interpreted as containing
6803 ASCII character codes. If the String A and String B are not the same
6804 length, the shorter is compared as if spaces were appended to it to form
6805 a value that has the same length as the longer.
6807 In general, the lexical comparison intrinsics @code{LGE}, @code{LGT},
6808 @code{LLE}, and @code{LLT} differ from the corresponding intrinsic
6809 operators @code{.GE.}, @code{.GT.}, @code{.LE.}, and @code{.LT.}, in
6810 that the latter use the processor's character ordering (which is not
6811 ASCII on some targets), whereas the former always use the ASCII
6814 @item @emph{Standard}:
6815 Fortran 77 and later
6820 @item @emph{Syntax}:
6821 @code{RESULT = LGE(STRING_A, STRING_B)}
6823 @item @emph{Arguments}:
6824 @multitable @columnfractions .15 .70
6825 @item @var{STRING_A} @tab Shall be of default @code{CHARACTER} type.
6826 @item @var{STRING_B} @tab Shall be of default @code{CHARACTER} type.
6829 @item @emph{Return value}:
6830 Returns @code{.TRUE.} if @code{STRING_A >= STRING_B}, and @code{.FALSE.}
6831 otherwise, based on the ASCII ordering.
6833 @item @emph{Specific names}:
6834 @multitable @columnfractions .20 .20 .20 .25
6835 @item Name @tab Argument @tab Return type @tab Standard
6836 @item @code{LGE(STRING_A, STRING_B)} @tab @code{CHARACTER} @tab @code{LOGICAL} @tab Fortran 77 and later
6839 @item @emph{See also}:
6840 @ref{LGT}, @ref{LLE}, @ref{LLT}
6846 @section @code{LGT} --- Lexical greater than
6848 @cindex lexical comparison of strings
6849 @cindex string, comparison
6852 @item @emph{Description}:
6853 Determines whether one string is lexically greater than another string,
6854 where the two strings are interpreted as containing ASCII character
6855 codes. If the String A and String B are not the same length, the
6856 shorter is compared as if spaces were appended to it to form a value
6857 that has the same length as the longer.
6859 In general, the lexical comparison intrinsics @code{LGE}, @code{LGT},
6860 @code{LLE}, and @code{LLT} differ from the corresponding intrinsic
6861 operators @code{.GE.}, @code{.GT.}, @code{.LE.}, and @code{.LT.}, in
6862 that the latter use the processor's character ordering (which is not
6863 ASCII on some targets), whereas the former always use the ASCII
6866 @item @emph{Standard}:
6867 Fortran 77 and later
6872 @item @emph{Syntax}:
6873 @code{RESULT = LGT(STRING_A, STRING_B)}
6875 @item @emph{Arguments}:
6876 @multitable @columnfractions .15 .70
6877 @item @var{STRING_A} @tab Shall be of default @code{CHARACTER} type.
6878 @item @var{STRING_B} @tab Shall be of default @code{CHARACTER} type.
6881 @item @emph{Return value}:
6882 Returns @code{.TRUE.} if @code{STRING_A > STRING_B}, and @code{.FALSE.}
6883 otherwise, based on the ASCII ordering.
6885 @item @emph{Specific names}:
6886 @multitable @columnfractions .20 .20 .20 .25
6887 @item Name @tab Argument @tab Return type @tab Standard
6888 @item @code{LGT(STRING_A, STRING_B)} @tab @code{CHARACTER} @tab @code{LOGICAL} @tab Fortran 77 and later
6891 @item @emph{See also}:
6892 @ref{LGE}, @ref{LLE}, @ref{LLT}
6898 @section @code{LINK} --- Create a hard link
6900 @cindex file system, create link
6901 @cindex file system, hard link
6904 @item @emph{Description}:
6905 Makes a (hard) link from file @var{PATH1} to @var{PATH2}. A null
6906 character (@code{CHAR(0)}) can be used to mark the end of the names in
6907 @var{PATH1} and @var{PATH2}; otherwise, trailing blanks in the file
6908 names are ignored. If the @var{STATUS} argument is supplied, it
6909 contains 0 on success or a nonzero error code upon return; see
6912 This intrinsic is provided in both subroutine and function forms;
6913 however, only one form can be used in any given program unit.
6915 @item @emph{Standard}:
6919 Subroutine, function
6921 @item @emph{Syntax}:
6922 @multitable @columnfractions .80
6923 @item @code{CALL LINK(PATH1, PATH2 [, STATUS])}
6924 @item @code{STATUS = LINK(PATH1, PATH2)}
6927 @item @emph{Arguments}:
6928 @multitable @columnfractions .15 .70
6929 @item @var{PATH1} @tab Shall be of default @code{CHARACTER} type.
6930 @item @var{PATH2} @tab Shall be of default @code{CHARACTER} type.
6931 @item @var{STATUS} @tab (Optional) Shall be of default @code{INTEGER} type.
6934 @item @emph{See also}:
6935 @ref{SYMLNK}, @ref{UNLINK}
6941 @section @code{LLE} --- Lexical less than or equal
6943 @cindex lexical comparison of strings
6944 @cindex string, comparison
6947 @item @emph{Description}:
6948 Determines whether one string is lexically less than or equal to another
6949 string, where the two strings are interpreted as containing ASCII
6950 character codes. If the String A and String B are not the same length,
6951 the shorter is compared as if spaces were appended to it to form a value
6952 that has the same length as the longer.
6954 In general, the lexical comparison intrinsics @code{LGE}, @code{LGT},
6955 @code{LLE}, and @code{LLT} differ from the corresponding intrinsic
6956 operators @code{.GE.}, @code{.GT.}, @code{.LE.}, and @code{.LT.}, in
6957 that the latter use the processor's character ordering (which is not
6958 ASCII on some targets), whereas the former always use the ASCII
6961 @item @emph{Standard}:
6962 Fortran 77 and later
6967 @item @emph{Syntax}:
6968 @code{RESULT = LLE(STRING_A, STRING_B)}
6970 @item @emph{Arguments}:
6971 @multitable @columnfractions .15 .70
6972 @item @var{STRING_A} @tab Shall be of default @code{CHARACTER} type.
6973 @item @var{STRING_B} @tab Shall be of default @code{CHARACTER} type.
6976 @item @emph{Return value}:
6977 Returns @code{.TRUE.} if @code{STRING_A <= STRING_B}, and @code{.FALSE.}
6978 otherwise, based on the ASCII ordering.
6980 @item @emph{Specific names}:
6981 @multitable @columnfractions .20 .20 .20 .25
6982 @item Name @tab Argument @tab Return type @tab Standard
6983 @item @code{LLE(STRING_A, STRING_B)} @tab @code{CHARACTER} @tab @code{LOGICAL} @tab Fortran 77 and later
6986 @item @emph{See also}:
6987 @ref{LGE}, @ref{LGT}, @ref{LLT}
6993 @section @code{LLT} --- Lexical less than
6995 @cindex lexical comparison of strings
6996 @cindex string, comparison
6999 @item @emph{Description}:
7000 Determines whether one string is lexically less than another string,
7001 where the two strings are interpreted as containing ASCII character
7002 codes. If the String A and String B are not the same length, the
7003 shorter is compared as if spaces were appended to it to form a value
7004 that has the same length as the longer.
7006 In general, the lexical comparison intrinsics @code{LGE}, @code{LGT},
7007 @code{LLE}, and @code{LLT} differ from the corresponding intrinsic
7008 operators @code{.GE.}, @code{.GT.}, @code{.LE.}, and @code{.LT.}, in
7009 that the latter use the processor's character ordering (which is not
7010 ASCII on some targets), whereas the former always use the ASCII
7013 @item @emph{Standard}:
7014 Fortran 77 and later
7019 @item @emph{Syntax}:
7020 @code{RESULT = LLT(STRING_A, STRING_B)}
7022 @item @emph{Arguments}:
7023 @multitable @columnfractions .15 .70
7024 @item @var{STRING_A} @tab Shall be of default @code{CHARACTER} type.
7025 @item @var{STRING_B} @tab Shall be of default @code{CHARACTER} type.
7028 @item @emph{Return value}:
7029 Returns @code{.TRUE.} if @code{STRING_A < STRING_B}, and @code{.FALSE.}
7030 otherwise, based on the ASCII ordering.
7032 @item @emph{Specific names}:
7033 @multitable @columnfractions .20 .20 .20 .25
7034 @item Name @tab Argument @tab Return type @tab Standard
7035 @item @code{LLT(STRING_A, STRING_B)} @tab @code{CHARACTER} @tab @code{LOGICAL} @tab Fortran 77 and later
7038 @item @emph{See also}:
7039 @ref{LGE}, @ref{LGT}, @ref{LLE}
7045 @section @code{LNBLNK} --- Index of the last non-blank character in a string
7047 @cindex string, find non-blank character
7050 @item @emph{Description}:
7051 Returns the length of a character string, ignoring any trailing blanks.
7052 This is identical to the standard @code{LEN_TRIM} intrinsic, and is only
7053 included for backwards compatibility.
7055 @item @emph{Standard}:
7061 @item @emph{Syntax}:
7062 @code{RESULT = LNBLNK(STRING)}
7064 @item @emph{Arguments}:
7065 @multitable @columnfractions .15 .70
7066 @item @var{STRING} @tab Shall be a scalar of type @code{CHARACTER},
7067 with @code{INTENT(IN)}
7070 @item @emph{Return value}:
7071 The return value is of @code{INTEGER(kind=4)} type.
7073 @item @emph{See also}:
7074 @ref{INDEX intrinsic}, @ref{LEN_TRIM}
7080 @section @code{LOC} --- Returns the address of a variable
7082 @cindex location of a variable in memory
7085 @item @emph{Description}:
7086 @code{LOC(X)} returns the address of @var{X} as an integer.
7088 @item @emph{Standard}:
7094 @item @emph{Syntax}:
7095 @code{RESULT = LOC(X)}
7097 @item @emph{Arguments}:
7098 @multitable @columnfractions .15 .70
7099 @item @var{X} @tab Variable of any type.
7102 @item @emph{Return value}:
7103 The return value is of type @code{INTEGER}, with a @code{KIND}
7104 corresponding to the size (in bytes) of a memory address on the target
7107 @item @emph{Example}:
7114 end program test_loc
7121 @section @code{LOG} --- Logarithm function
7128 @cindex exponential function, inverse
7129 @cindex logarithmic function
7132 @item @emph{Description}:
7133 @code{LOG(X)} computes the logarithm of @var{X}.
7135 @item @emph{Standard}:
7136 Fortran 77 and later
7141 @item @emph{Syntax}:
7142 @code{RESULT = LOG(X)}
7144 @item @emph{Arguments}:
7145 @multitable @columnfractions .15 .70
7146 @item @var{X} @tab The type shall be @code{REAL} or
7150 @item @emph{Return value}:
7151 The return value is of type @code{REAL} or @code{COMPLEX}.
7152 The kind type parameter is the same as @var{X}.
7153 If @var{X} is @code{COMPLEX}, the imaginary part @math{\omega} is in the range
7154 @math{-\pi \leq \omega \leq \pi}.
7156 @item @emph{Example}:
7159 real(8) :: x = 1.0_8
7160 complex :: z = (1.0, 2.0)
7163 end program test_log
7166 @item @emph{Specific names}:
7167 @multitable @columnfractions .20 .20 .20 .25
7168 @item Name @tab Argument @tab Return type @tab Standard
7169 @item @code{ALOG(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab f95, gnu
7170 @item @code{DLOG(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab f95, gnu
7171 @item @code{CLOG(X)} @tab @code{COMPLEX(4) X} @tab @code{COMPLEX(4)} @tab f95, gnu
7172 @item @code{ZLOG(X)} @tab @code{COMPLEX(8) X} @tab @code{COMPLEX(8)} @tab f95, gnu
7173 @item @code{CDLOG(X)} @tab @code{COMPLEX(8) X} @tab @code{COMPLEX(8)} @tab f95, gnu
7180 @section @code{LOG10} --- Base 10 logarithm function
7184 @cindex exponential function, inverse
7185 @cindex logarithmic function
7188 @item @emph{Description}:
7189 @code{LOG10(X)} computes the base 10 logarithm of @var{X}.
7191 @item @emph{Standard}:
7192 Fortran 77 and later
7197 @item @emph{Syntax}:
7198 @code{RESULT = LOG10(X)}
7200 @item @emph{Arguments}:
7201 @multitable @columnfractions .15 .70
7202 @item @var{X} @tab The type shall be @code{REAL}.
7205 @item @emph{Return value}:
7206 The return value is of type @code{REAL} or @code{COMPLEX}.
7207 The kind type parameter is the same as @var{X}.
7209 @item @emph{Example}:
7212 real(8) :: x = 10.0_8
7214 end program test_log10
7217 @item @emph{Specific names}:
7218 @multitable @columnfractions .20 .20 .20 .25
7219 @item Name @tab Argument @tab Return type @tab Standard
7220 @item @code{ALOG10(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab Fortran 95 and later
7221 @item @code{DLOG10(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab Fortran 95 and later
7228 @section @code{LOG_GAMMA} --- Logarithm of the Gamma function
7233 @cindex Gamma function, logarithm of
7236 @item @emph{Description}:
7237 @code{LOG_GAMMA(X)} computes the natural logarithm of the absolute value
7238 of the Gamma (@math{\Gamma}) function.
7240 @item @emph{Standard}:
7241 Fortran 2008 and later
7246 @item @emph{Syntax}:
7247 @code{X = LOG_GAMMA(X)}
7249 @item @emph{Arguments}:
7250 @multitable @columnfractions .15 .70
7251 @item @var{X} @tab Shall be of type @code{REAL} and neither zero
7252 nor a negative integer.
7255 @item @emph{Return value}:
7256 The return value is of type @code{REAL} of the same kind as @var{X}.
7258 @item @emph{Example}:
7260 program test_log_gamma
7262 x = lgamma(x) ! returns 0.0
7263 end program test_log_gamma
7266 @item @emph{Specific names}:
7267 @multitable @columnfractions .20 .20 .20 .25
7268 @item Name @tab Argument @tab Return type @tab Standard
7269 @item @code{LGAMMA(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab GNU Extension
7270 @item @code{ALGAMA(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab GNU Extension
7271 @item @code{DLGAMA(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU Extension
7274 @item @emph{See also}:
7275 Gamma function: @ref{GAMMA}
7282 @section @code{LOGICAL} --- Convert to logical type
7284 @cindex conversion, to logical
7287 @item @emph{Description}:
7288 Converts one kind of @code{LOGICAL} variable to another.
7290 @item @emph{Standard}:
7291 Fortran 95 and later
7296 @item @emph{Syntax}:
7297 @code{RESULT = LOGICAL(L [, KIND])}
7299 @item @emph{Arguments}:
7300 @multitable @columnfractions .15 .70
7301 @item @var{L} @tab The type shall be @code{LOGICAL}.
7302 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
7303 expression indicating the kind parameter of the result.
7306 @item @emph{Return value}:
7307 The return value is a @code{LOGICAL} value equal to @var{L}, with a
7308 kind corresponding to @var{KIND}, or of the default logical kind if
7309 @var{KIND} is not given.
7311 @item @emph{See also}:
7312 @ref{INT}, @ref{REAL}, @ref{CMPLX}
7318 @section @code{LONG} --- Convert to integer type
7320 @cindex conversion, to integer
7323 @item @emph{Description}:
7324 Convert to a @code{KIND=4} integer type, which is the same size as a C
7325 @code{long} integer. This is equivalent to the standard @code{INT}
7326 intrinsic with an optional argument of @code{KIND=4}, and is only
7327 included for backwards compatibility.
7329 @item @emph{Standard}:
7335 @item @emph{Syntax}:
7336 @code{RESULT = LONG(A)}
7338 @item @emph{Arguments}:
7339 @multitable @columnfractions .15 .70
7340 @item @var{A} @tab Shall be of type @code{INTEGER},
7341 @code{REAL}, or @code{COMPLEX}.
7344 @item @emph{Return value}:
7345 The return value is a @code{INTEGER(4)} variable.
7347 @item @emph{See also}:
7348 @ref{INT}, @ref{INT2}, @ref{INT8}
7354 @section @code{LSHIFT} --- Left shift bits
7356 @cindex bits, shift left
7359 @item @emph{Description}:
7360 @code{LSHIFT} returns a value corresponding to @var{I} with all of the
7361 bits shifted left by @var{SHIFT} places. If the absolute value of
7362 @var{SHIFT} is greater than @code{BIT_SIZE(I)}, the value is undefined.
7363 Bits shifted out from the left end are lost; zeros are shifted in from
7366 This function has been superseded by the @code{ISHFT} intrinsic, which
7367 is standard in Fortran 95 and later.
7369 @item @emph{Standard}:
7375 @item @emph{Syntax}:
7376 @code{RESULT = LSHIFT(I, SHIFT)}
7378 @item @emph{Arguments}:
7379 @multitable @columnfractions .15 .70
7380 @item @var{I} @tab The type shall be @code{INTEGER}.
7381 @item @var{SHIFT} @tab The type shall be @code{INTEGER}.
7384 @item @emph{Return value}:
7385 The return value is of type @code{INTEGER} and of the same kind as
7388 @item @emph{See also}:
7389 @ref{ISHFT}, @ref{ISHFTC}, @ref{RSHIFT}
7396 @section @code{LSTAT} --- Get file status
7398 @cindex file system, file status
7401 @item @emph{Description}:
7402 @code{LSTAT} is identical to @ref{STAT}, except that if path is a
7403 symbolic link, then the link itself is statted, not the file that it
7406 The elements in @code{VALUES} are the same as described by @ref{STAT}.
7408 This intrinsic is provided in both subroutine and function forms;
7409 however, only one form can be used in any given program unit.
7411 @item @emph{Standard}:
7415 Subroutine, function
7417 @item @emph{Syntax}:
7418 @code{CALL LSTAT(NAME, VALUES [, STATUS])}
7420 @item @emph{Arguments}:
7421 @multitable @columnfractions .15 .70
7422 @item @var{NAME} @tab The type shall be @code{CHARACTER} of the default
7423 kind, a valid path within the file system.
7424 @item @var{VALUES} @tab The type shall be @code{INTEGER(4), DIMENSION(13)}.
7425 @item @var{STATUS} @tab (Optional) status flag of type @code{INTEGER(4)}.
7426 Returns 0 on success and a system specific error code otherwise.
7429 @item @emph{Example}:
7430 See @ref{STAT} for an example.
7432 @item @emph{See also}:
7433 To stat an open file: @ref{FSTAT}, to stat a file: @ref{STAT}
7439 @section @code{LTIME} --- Convert time to local time info
7441 @cindex time, conversion to local time info
7444 @item @emph{Description}:
7445 Given a system time value @var{TIME} (as provided by the @code{TIME8()}
7446 intrinsic), fills @var{VALUES} with values extracted from it appropriate
7447 to the local time zone using @code{localtime(3)}.
7449 @item @emph{Standard}:
7455 @item @emph{Syntax}:
7456 @code{CALL LTIME(TIME, VALUES)}
7458 @item @emph{Arguments}:
7459 @multitable @columnfractions .15 .70
7460 @item @var{TIME} @tab An @code{INTEGER} scalar expression
7461 corresponding to a system time, with @code{INTENT(IN)}.
7462 @item @var{VALUES} @tab A default @code{INTEGER} array with 9 elements,
7463 with @code{INTENT(OUT)}.
7466 @item @emph{Return value}:
7467 The elements of @var{VALUES} are assigned as follows:
7469 @item Seconds after the minute, range 0--59 or 0--61 to allow for leap
7471 @item Minutes after the hour, range 0--59
7472 @item Hours past midnight, range 0--23
7473 @item Day of month, range 0--31
7474 @item Number of months since January, range 0--12
7475 @item Years since 1900
7476 @item Number of days since Sunday, range 0--6
7477 @item Days since January 1
7478 @item Daylight savings indicator: positive if daylight savings is in
7479 effect, zero if not, and negative if the information is not available.
7482 @item @emph{See also}:
7483 @ref{CTIME}, @ref{GMTIME}, @ref{TIME}, @ref{TIME8}
7490 @section @code{MALLOC} --- Allocate dynamic memory
7492 @cindex pointer, cray
7495 @item @emph{Description}:
7496 @code{MALLOC(SIZE)} allocates @var{SIZE} bytes of dynamic memory and
7497 returns the address of the allocated memory. The @code{MALLOC} intrinsic
7498 is an extension intended to be used with Cray pointers, and is provided
7499 in GNU Fortran to allow the user to compile legacy code. For new code
7500 using Fortran 95 pointers, the memory allocation intrinsic is
7503 @item @emph{Standard}:
7509 @item @emph{Syntax}:
7510 @code{PTR = MALLOC(SIZE)}
7512 @item @emph{Arguments}:
7513 @multitable @columnfractions .15 .70
7514 @item @var{SIZE} @tab The type shall be @code{INTEGER}.
7517 @item @emph{Return value}:
7518 The return value is of type @code{INTEGER(K)}, with @var{K} such that
7519 variables of type @code{INTEGER(K)} have the same size as
7520 C pointers (@code{sizeof(void *)}).
7522 @item @emph{Example}:
7523 The following example demonstrates the use of @code{MALLOC} and
7524 @code{FREE} with Cray pointers.
7533 ptr_x = malloc(20*8)
7535 x(i) = sqrt(1.0d0 / i)
7543 end program test_malloc
7546 @item @emph{See also}:
7553 @section @code{MATMUL} --- matrix multiplication
7555 @cindex matrix multiplication
7556 @cindex product, matrix
7559 @item @emph{Description}:
7560 Performs a matrix multiplication on numeric or logical arguments.
7562 @item @emph{Standard}:
7563 Fortran 95 and later
7566 Transformational function
7568 @item @emph{Syntax}:
7569 @code{RESULT = MATMUL(MATRIX_A, MATRIX_B)}
7571 @item @emph{Arguments}:
7572 @multitable @columnfractions .15 .70
7573 @item @var{MATRIX_A} @tab An array of @code{INTEGER},
7574 @code{REAL}, @code{COMPLEX}, or @code{LOGICAL} type, with a rank of
7576 @item @var{MATRIX_B} @tab An array of @code{INTEGER},
7577 @code{REAL}, or @code{COMPLEX} type if @var{MATRIX_A} is of a numeric
7578 type; otherwise, an array of @code{LOGICAL} type. The rank shall be one
7579 or two, and the first (or only) dimension of @var{MATRIX_B} shall be
7580 equal to the last (or only) dimension of @var{MATRIX_A}.
7583 @item @emph{Return value}:
7584 The matrix product of @var{MATRIX_A} and @var{MATRIX_B}. The type and
7585 kind of the result follow the usual type and kind promotion rules, as
7586 for the @code{*} or @code{.AND.} operators.
7588 @item @emph{See also}:
7594 @section @code{MAX} --- Maximum value of an argument list
7601 @cindex maximum value
7604 @item @emph{Description}:
7605 Returns the argument with the largest (most positive) value.
7607 @item @emph{Standard}:
7608 Fortran 77 and later
7613 @item @emph{Syntax}:
7614 @code{RESULT = MAX(A1, A2 [, A3 [, ...]])}
7616 @item @emph{Arguments}:
7617 @multitable @columnfractions .15 .70
7618 @item @var{A1} @tab The type shall be @code{INTEGER} or
7620 @item @var{A2}, @var{A3}, ... @tab An expression of the same type and kind
7621 as @var{A1}. (As a GNU extension, arguments of different kinds are
7625 @item @emph{Return value}:
7626 The return value corresponds to the maximum value among the arguments,
7627 and has the same type and kind as the first argument.
7629 @item @emph{Specific names}:
7630 @multitable @columnfractions .20 .20 .20 .25
7631 @item Name @tab Argument @tab Return type @tab Standard
7632 @item @code{MAX0(A1)} @tab @code{INTEGER(4) A1} @tab @code{INTEGER(4)} @tab Fortran 77 and later
7633 @item @code{AMAX0(A1)} @tab @code{INTEGER(4) A1} @tab @code{REAL(MAX(X))} @tab Fortran 77 and later
7634 @item @code{MAX1(A1)} @tab @code{REAL A1} @tab @code{INT(MAX(X))} @tab Fortran 77 and later
7635 @item @code{AMAX1(A1)} @tab @code{REAL(4) A1} @tab @code{REAL(4)} @tab Fortran 77 and later
7636 @item @code{DMAX1(A1)} @tab @code{REAL(8) A1} @tab @code{REAL(8)} @tab Fortran 77 and later
7639 @item @emph{See also}:
7640 @ref{MAXLOC} @ref{MAXVAL}, @ref{MIN}
7647 @section @code{MAXEXPONENT} --- Maximum exponent of a real kind
7648 @fnindex MAXEXPONENT
7649 @cindex model representation, maximum exponent
7652 @item @emph{Description}:
7653 @code{MAXEXPONENT(X)} returns the maximum exponent in the model of the
7656 @item @emph{Standard}:
7657 Fortran 95 and later
7662 @item @emph{Syntax}:
7663 @code{RESULT = MAXEXPONENT(X)}
7665 @item @emph{Arguments}:
7666 @multitable @columnfractions .15 .70
7667 @item @var{X} @tab Shall be of type @code{REAL}.
7670 @item @emph{Return value}:
7671 The return value is of type @code{INTEGER} and of the default integer
7674 @item @emph{Example}:
7680 print *, minexponent(x), maxexponent(x)
7681 print *, minexponent(y), maxexponent(y)
7682 end program exponents
7689 @section @code{MAXLOC} --- Location of the maximum value within an array
7691 @cindex array, location of maximum element
7694 @item @emph{Description}:
7695 Determines the location of the element in the array with the maximum
7696 value, or, if the @var{DIM} argument is supplied, determines the
7697 locations of the maximum element along each row of the array in the
7698 @var{DIM} direction. If @var{MASK} is present, only the elements for
7699 which @var{MASK} is @code{.TRUE.} are considered. If more than one
7700 element in the array has the maximum value, the location returned is
7701 that of the first such element in array element order. If the array has
7702 zero size, or all of the elements of @var{MASK} are @code{.FALSE.}, then
7703 the result is an array of zeroes. Similarly, if @var{DIM} is supplied
7704 and all of the elements of @var{MASK} along a given row are zero, the
7705 result value for that row is zero.
7707 @item @emph{Standard}:
7708 Fortran 95 and later
7711 Transformational function
7713 @item @emph{Syntax}:
7714 @multitable @columnfractions .80
7715 @item @code{RESULT = MAXLOC(ARRAY, DIM [, MASK])}
7716 @item @code{RESULT = MAXLOC(ARRAY [, MASK])}
7719 @item @emph{Arguments}:
7720 @multitable @columnfractions .15 .70
7721 @item @var{ARRAY} @tab Shall be an array of type @code{INTEGER} or
7723 @item @var{DIM} @tab (Optional) Shall be a scalar of type
7724 @code{INTEGER}, with a value between one and the rank of @var{ARRAY},
7725 inclusive. It may not be an optional dummy argument.
7726 @item @var{MASK} @tab Shall be an array of type @code{LOGICAL},
7727 and conformable with @var{ARRAY}.
7730 @item @emph{Return value}:
7731 If @var{DIM} is absent, the result is a rank-one array with a length
7732 equal to the rank of @var{ARRAY}. If @var{DIM} is present, the result
7733 is an array with a rank one less than the rank of @var{ARRAY}, and a
7734 size corresponding to the size of @var{ARRAY} with the @var{DIM}
7735 dimension removed. If @var{DIM} is present and @var{ARRAY} has a rank
7736 of one, the result is a scalar. In all cases, the result is of default
7737 @code{INTEGER} type.
7739 @item @emph{See also}:
7740 @ref{MAX}, @ref{MAXVAL}
7747 @section @code{MAXVAL} --- Maximum value of an array
7749 @cindex array, maximum value
7750 @cindex maximum value
7753 @item @emph{Description}:
7754 Determines the maximum value of the elements in an array value, or, if
7755 the @var{DIM} argument is supplied, determines the maximum value along
7756 each row of the array in the @var{DIM} direction. If @var{MASK} is
7757 present, only the elements for which @var{MASK} is @code{.TRUE.} are
7758 considered. If the array has zero size, or all of the elements of
7759 @var{MASK} are @code{.FALSE.}, then the result is @code{-HUGE(ARRAY)}
7760 if @var{ARRAY} is numeric, or a string of nulls if @var{ARRAY} is of character
7763 @item @emph{Standard}:
7764 Fortran 95 and later
7767 Transformational function
7769 @item @emph{Syntax}:
7770 @multitable @columnfractions .80
7771 @item @code{RESULT = MAXVAL(ARRAY, DIM [, MASK])}
7772 @item @code{RESULT = MAXVAL(ARRAY [, MASK])}
7775 @item @emph{Arguments}:
7776 @multitable @columnfractions .15 .70
7777 @item @var{ARRAY} @tab Shall be an array of type @code{INTEGER} or
7779 @item @var{DIM} @tab (Optional) Shall be a scalar of type
7780 @code{INTEGER}, with a value between one and the rank of @var{ARRAY},
7781 inclusive. It may not be an optional dummy argument.
7782 @item @var{MASK} @tab Shall be an array of type @code{LOGICAL},
7783 and conformable with @var{ARRAY}.
7786 @item @emph{Return value}:
7787 If @var{DIM} is absent, or if @var{ARRAY} has a rank of one, the result
7788 is a scalar. If @var{DIM} is present, the result is an array with a
7789 rank one less than the rank of @var{ARRAY}, and a size corresponding to
7790 the size of @var{ARRAY} with the @var{DIM} dimension removed. In all
7791 cases, the result is of the same type and kind as @var{ARRAY}.
7793 @item @emph{See also}:
7794 @ref{MAX}, @ref{MAXLOC}
7800 @section @code{MCLOCK} --- Time function
7802 @cindex time, clock ticks
7806 @item @emph{Description}:
7807 Returns the number of clock ticks since the start of the process, based
7808 on the UNIX function @code{clock(3)}.
7810 This intrinsic is not fully portable, such as to systems with 32-bit
7811 @code{INTEGER} types but supporting times wider than 32 bits. Therefore,
7812 the values returned by this intrinsic might be, or become, negative, or
7813 numerically less than previous values, during a single run of the
7816 @item @emph{Standard}:
7822 @item @emph{Syntax}:
7823 @code{RESULT = MCLOCK()}
7825 @item @emph{Return value}:
7826 The return value is a scalar of type @code{INTEGER(4)}, equal to the
7827 number of clock ticks since the start of the process, or @code{-1} if
7828 the system does not support @code{clock(3)}.
7830 @item @emph{See also}:
7831 @ref{CTIME}, @ref{GMTIME}, @ref{LTIME}, @ref{MCLOCK}, @ref{TIME}
7838 @section @code{MCLOCK8} --- Time function (64-bit)
7840 @cindex time, clock ticks
7844 @item @emph{Description}:
7845 Returns the number of clock ticks since the start of the process, based
7846 on the UNIX function @code{clock(3)}.
7848 @emph{Warning:} this intrinsic does not increase the range of the timing
7849 values over that returned by @code{clock(3)}. On a system with a 32-bit
7850 @code{clock(3)}, @code{MCLOCK8()} will return a 32-bit value, even though
7851 it is converted to a 64-bit @code{INTEGER(8)} value. That means
7852 overflows of the 32-bit value can still occur. Therefore, the values
7853 returned by this intrinsic might be or become negative or numerically
7854 less than previous values during a single run of the compiled program.
7856 @item @emph{Standard}:
7862 @item @emph{Syntax}:
7863 @code{RESULT = MCLOCK8()}
7865 @item @emph{Return value}:
7866 The return value is a scalar of type @code{INTEGER(8)}, equal to the
7867 number of clock ticks since the start of the process, or @code{-1} if
7868 the system does not support @code{clock(3)}.
7870 @item @emph{See also}:
7871 @ref{CTIME}, @ref{GMTIME}, @ref{LTIME}, @ref{MCLOCK}, @ref{TIME8}
7878 @section @code{MERGE} --- Merge variables
7880 @cindex array, merge arrays
7881 @cindex array, combine arrays
7884 @item @emph{Description}:
7885 Select values from two arrays according to a logical mask. The result
7886 is equal to @var{TSOURCE} if @var{MASK} is @code{.TRUE.}, or equal to
7887 @var{FSOURCE} if it is @code{.FALSE.}.
7889 @item @emph{Standard}:
7890 Fortran 95 and later
7895 @item @emph{Syntax}:
7896 @code{RESULT = MERGE(TSOURCE, FSOURCE, MASK)}
7898 @item @emph{Arguments}:
7899 @multitable @columnfractions .15 .70
7900 @item @var{TSOURCE} @tab May be of any type.
7901 @item @var{FSOURCE} @tab Shall be of the same type and type parameters
7903 @item @var{MASK} @tab Shall be of type @code{LOGICAL}.
7906 @item @emph{Return value}:
7907 The result is of the same type and type parameters as @var{TSOURCE}.
7914 @section @code{MIN} --- Minimum value of an argument list
7921 @cindex minimum value
7924 @item @emph{Description}:
7925 Returns the argument with the smallest (most negative) value.
7927 @item @emph{Standard}:
7928 Fortran 77 and later
7933 @item @emph{Syntax}:
7934 @code{RESULT = MIN(A1, A2 [, A3, ...])}
7936 @item @emph{Arguments}:
7937 @multitable @columnfractions .15 .70
7938 @item @var{A1} @tab The type shall be @code{INTEGER} or
7940 @item @var{A2}, @var{A3}, ... @tab An expression of the same type and kind
7941 as @var{A1}. (As a GNU extension, arguments of different kinds are
7945 @item @emph{Return value}:
7946 The return value corresponds to the maximum value among the arguments,
7947 and has the same type and kind as the first argument.
7949 @item @emph{Specific names}:
7950 @multitable @columnfractions .20 .20 .20 .25
7951 @item Name @tab Argument @tab Return type @tab Standard
7952 @item @code{MIN0(A1)} @tab @code{INTEGER(4) A1} @tab @code{INTEGER(4)} @tab Fortran 77 and later
7953 @item @code{AMIN0(A1)} @tab @code{INTEGER(4) A1} @tab @code{REAL(4)} @tab Fortran 77 and later
7954 @item @code{MIN1(A1)} @tab @code{REAL A1} @tab @code{INTEGER(4)} @tab Fortran 77 and later
7955 @item @code{AMIN1(A1)} @tab @code{REAL(4) A1} @tab @code{REAL(4)} @tab Fortran 77 and later
7956 @item @code{DMIN1(A1)} @tab @code{REAL(8) A1} @tab @code{REAL(8)} @tab Fortran 77 and later
7959 @item @emph{See also}:
7960 @ref{MAX}, @ref{MINLOC}, @ref{MINVAL}
7966 @section @code{MINEXPONENT} --- Minimum exponent of a real kind
7967 @fnindex MINEXPONENT
7968 @cindex model representation, minimum exponent
7971 @item @emph{Description}:
7972 @code{MINEXPONENT(X)} returns the minimum exponent in the model of the
7975 @item @emph{Standard}:
7976 Fortran 95 and later
7981 @item @emph{Syntax}:
7982 @code{RESULT = MINEXPONENT(X)}
7984 @item @emph{Arguments}:
7985 @multitable @columnfractions .15 .70
7986 @item @var{X} @tab Shall be of type @code{REAL}.
7989 @item @emph{Return value}:
7990 The return value is of type @code{INTEGER} and of the default integer
7993 @item @emph{Example}:
7994 See @code{MAXEXPONENT} for an example.
8000 @section @code{MINLOC} --- Location of the minimum value within an array
8002 @cindex array, location of minimum element
8005 @item @emph{Description}:
8006 Determines the location of the element in the array with the minimum
8007 value, or, if the @var{DIM} argument is supplied, determines the
8008 locations of the minimum element along each row of the array in the
8009 @var{DIM} direction. If @var{MASK} is present, only the elements for
8010 which @var{MASK} is @code{.TRUE.} are considered. If more than one
8011 element in the array has the minimum value, the location returned is
8012 that of the first such element in array element order. If the array has
8013 zero size, or all of the elements of @var{MASK} are @code{.FALSE.}, then
8014 the result is an array of zeroes. Similarly, if @var{DIM} is supplied
8015 and all of the elements of @var{MASK} along a given row are zero, the
8016 result value for that row is zero.
8018 @item @emph{Standard}:
8019 Fortran 95 and later
8022 Transformational function
8024 @item @emph{Syntax}:
8025 @multitable @columnfractions .80
8026 @item @code{RESULT = MINLOC(ARRAY, DIM [, MASK])}
8027 @item @code{RESULT = MINLOC(ARRAY [, MASK])}
8030 @item @emph{Arguments}:
8031 @multitable @columnfractions .15 .70
8032 @item @var{ARRAY} @tab Shall be an array of type @code{INTEGER} or
8034 @item @var{DIM} @tab (Optional) Shall be a scalar of type
8035 @code{INTEGER}, with a value between one and the rank of @var{ARRAY},
8036 inclusive. It may not be an optional dummy argument.
8037 @item @var{MASK} @tab Shall be an array of type @code{LOGICAL},
8038 and conformable with @var{ARRAY}.
8041 @item @emph{Return value}:
8042 If @var{DIM} is absent, the result is a rank-one array with a length
8043 equal to the rank of @var{ARRAY}. If @var{DIM} is present, the result
8044 is an array with a rank one less than the rank of @var{ARRAY}, and a
8045 size corresponding to the size of @var{ARRAY} with the @var{DIM}
8046 dimension removed. If @var{DIM} is present and @var{ARRAY} has a rank
8047 of one, the result is a scalar. In all cases, the result is of default
8048 @code{INTEGER} type.
8050 @item @emph{See also}:
8051 @ref{MIN}, @ref{MINVAL}
8058 @section @code{MINVAL} --- Minimum value of an array
8060 @cindex array, minimum value
8061 @cindex minimum value
8064 @item @emph{Description}:
8065 Determines the minimum value of the elements in an array value, or, if
8066 the @var{DIM} argument is supplied, determines the minimum value along
8067 each row of the array in the @var{DIM} direction. If @var{MASK} is
8068 present, only the elements for which @var{MASK} is @code{.TRUE.} are
8069 considered. If the array has zero size, or all of the elements of
8070 @var{MASK} are @code{.FALSE.}, then the result is @code{HUGE(ARRAY)} if
8071 @var{ARRAY} is numeric, or a string of @code{CHAR(255)} characters if
8072 @var{ARRAY} is of character type.
8074 @item @emph{Standard}:
8075 Fortran 95 and later
8078 Transformational function
8080 @item @emph{Syntax}:
8081 @multitable @columnfractions .80
8082 @item @code{RESULT = MINVAL(ARRAY, DIM [, MASK])}
8083 @item @code{RESULT = MINVAL(ARRAY [, MASK])}
8086 @item @emph{Arguments}:
8087 @multitable @columnfractions .15 .70
8088 @item @var{ARRAY} @tab Shall be an array of type @code{INTEGER} or
8090 @item @var{DIM} @tab (Optional) Shall be a scalar of type
8091 @code{INTEGER}, with a value between one and the rank of @var{ARRAY},
8092 inclusive. It may not be an optional dummy argument.
8093 @item @var{MASK} @tab Shall be an array of type @code{LOGICAL},
8094 and conformable with @var{ARRAY}.
8097 @item @emph{Return value}:
8098 If @var{DIM} is absent, or if @var{ARRAY} has a rank of one, the result
8099 is a scalar. If @var{DIM} is present, the result is an array with a
8100 rank one less than the rank of @var{ARRAY}, and a size corresponding to
8101 the size of @var{ARRAY} with the @var{DIM} dimension removed. In all
8102 cases, the result is of the same type and kind as @var{ARRAY}.
8104 @item @emph{See also}:
8105 @ref{MIN}, @ref{MINLOC}
8112 @section @code{MOD} --- Remainder function
8117 @cindex division, remainder
8120 @item @emph{Description}:
8121 @code{MOD(A,P)} computes the remainder of the division of A by P@. It is
8122 calculated as @code{A - (INT(A/P) * P)}.
8124 @item @emph{Standard}:
8125 Fortran 77 and later
8130 @item @emph{Syntax}:
8131 @code{RESULT = MOD(A, P)}
8133 @item @emph{Arguments}:
8134 @multitable @columnfractions .15 .70
8135 @item @var{A} @tab Shall be a scalar of type @code{INTEGER} or @code{REAL}
8136 @item @var{P} @tab Shall be a scalar of the same type as @var{A} and not
8140 @item @emph{Return value}:
8141 The kind of the return value is the result of cross-promoting
8142 the kinds of the arguments.
8144 @item @emph{Example}:
8148 print *, mod(17.5,5.5)
8149 print *, mod(17.5d0,5.5)
8150 print *, mod(17.5,5.5d0)
8153 print *, mod(-17.5,5.5)
8154 print *, mod(-17.5d0,5.5)
8155 print *, mod(-17.5,5.5d0)
8158 print *, mod(17.5,-5.5)
8159 print *, mod(17.5d0,-5.5)
8160 print *, mod(17.5,-5.5d0)
8161 end program test_mod
8164 @item @emph{Specific names}:
8165 @multitable @columnfractions .20 .20 .20 .25
8166 @item Name @tab Arguments @tab Return type @tab Standard
8167 @item @code{MOD(A,P)} @tab @code{INTEGER A,P} @tab @code{INTEGER} @tab Fortran 95 and later
8168 @item @code{AMOD(A,P)} @tab @code{REAL(4) A,P} @tab @code{REAL(4)} @tab Fortran 95 and later
8169 @item @code{DMOD(A,P)} @tab @code{REAL(8) A,P} @tab @code{REAL(8)} @tab Fortran 95 and later
8176 @section @code{MODULO} --- Modulo function
8179 @cindex division, modulo
8182 @item @emph{Description}:
8183 @code{MODULO(A,P)} computes the @var{A} modulo @var{P}.
8185 @item @emph{Standard}:
8186 Fortran 95 and later
8191 @item @emph{Syntax}:
8192 @code{RESULT = MODULO(A, P)}
8194 @item @emph{Arguments}:
8195 @multitable @columnfractions .15 .70
8196 @item @var{A} @tab Shall be a scalar of type @code{INTEGER} or @code{REAL}
8197 @item @var{P} @tab Shall be a scalar of the same type and kind as @var{A}
8200 @item @emph{Return value}:
8201 The type and kind of the result are those of the arguments.
8203 @item If @var{A} and @var{P} are of type @code{INTEGER}:
8204 @code{MODULO(A,P)} has the value @var{R} such that @code{A=Q*P+R}, where
8205 @var{Q} is an integer and @var{R} is between 0 (inclusive) and @var{P}
8207 @item If @var{A} and @var{P} are of type @code{REAL}:
8208 @code{MODULO(A,P)} has the value of @code{A - FLOOR (A / P) * P}.
8210 In all cases, if @var{P} is zero the result is processor-dependent.
8212 @item @emph{Example}:
8215 print *, modulo(17,3)
8216 print *, modulo(17.5,5.5)
8218 print *, modulo(-17,3)
8219 print *, modulo(-17.5,5.5)
8221 print *, modulo(17,-3)
8222 print *, modulo(17.5,-5.5)
8231 @section @code{MOVE_ALLOC} --- Move allocation from one object to another
8233 @cindex moving allocation
8234 @cindex allocation, moving
8237 @item @emph{Description}:
8238 @code{MOVE_ALLOC(FROM, TO)} moves the allocation from @var{FROM} to
8239 @var{TO}. @var{FROM} will become deallocated in the process.
8241 @item @emph{Standard}:
8242 Fortran 2003 and later
8247 @item @emph{Syntax}:
8248 @code{CALL MOVE_ALLOC(FROM, TO)}
8250 @item @emph{Arguments}:
8251 @multitable @columnfractions .15 .70
8252 @item @var{FROM} @tab @code{ALLOCATABLE}, @code{INTENT(INOUT)}, may be
8253 of any type and kind.
8254 @item @var{TO} @tab @code{ALLOCATABLE}, @code{INTENT(OUT)}, shall be
8255 of the same type, kind and rank as @var{FROM}.
8258 @item @emph{Return value}:
8261 @item @emph{Example}:
8263 program test_move_alloc
8264 integer, allocatable :: a(:), b(:)
8268 call move_alloc(a, b)
8269 print *, allocated(a), allocated(b)
8271 end program test_move_alloc
8278 @section @code{MVBITS} --- Move bits from one integer to another
8283 @item @emph{Description}:
8284 Moves @var{LEN} bits from positions @var{FROMPOS} through
8285 @code{FROMPOS+LEN-1} of @var{FROM} to positions @var{TOPOS} through
8286 @code{TOPOS+LEN-1} of @var{TO}. The portion of argument @var{TO} not
8287 affected by the movement of bits is unchanged. The values of
8288 @code{FROMPOS+LEN-1} and @code{TOPOS+LEN-1} must be less than
8289 @code{BIT_SIZE(FROM)}.
8291 @item @emph{Standard}:
8292 Fortran 95 and later
8295 Elemental subroutine
8297 @item @emph{Syntax}:
8298 @code{CALL MVBITS(FROM, FROMPOS, LEN, TO, TOPOS)}
8300 @item @emph{Arguments}:
8301 @multitable @columnfractions .15 .70
8302 @item @var{FROM} @tab The type shall be @code{INTEGER}.
8303 @item @var{FROMPOS} @tab The type shall be @code{INTEGER}.
8304 @item @var{LEN} @tab The type shall be @code{INTEGER}.
8305 @item @var{TO} @tab The type shall be @code{INTEGER}, of the
8306 same kind as @var{FROM}.
8307 @item @var{TOPOS} @tab The type shall be @code{INTEGER}.
8310 @item @emph{See also}:
8311 @ref{IBCLR}, @ref{IBSET}, @ref{IBITS}, @ref{IAND}, @ref{IOR}, @ref{IEOR}
8317 @section @code{NEAREST} --- Nearest representable number
8319 @cindex real number, nearest different
8320 @cindex floating point, nearest different
8323 @item @emph{Description}:
8324 @code{NEAREST(X, S)} returns the processor-representable number nearest
8325 to @code{X} in the direction indicated by the sign of @code{S}.
8327 @item @emph{Standard}:
8328 Fortran 95 and later
8333 @item @emph{Syntax}:
8334 @code{RESULT = NEAREST(X, S)}
8336 @item @emph{Arguments}:
8337 @multitable @columnfractions .15 .70
8338 @item @var{X} @tab Shall be of type @code{REAL}.
8339 @item @var{S} @tab (Optional) shall be of type @code{REAL} and
8343 @item @emph{Return value}:
8344 The return value is of the same type as @code{X}. If @code{S} is
8345 positive, @code{NEAREST} returns the processor-representable number
8346 greater than @code{X} and nearest to it. If @code{S} is negative,
8347 @code{NEAREST} returns the processor-representable number smaller than
8348 @code{X} and nearest to it.
8350 @item @emph{Example}:
8352 program test_nearest
8354 x = nearest(42.0, 1.0)
8355 y = nearest(42.0, -1.0)
8356 write (*,"(3(G20.15))") x, y, x - y
8357 end program test_nearest
8364 @section @code{NEW_LINE} --- New line character
8367 @cindex output, newline
8370 @item @emph{Description}:
8371 @code{NEW_LINE(C)} returns the new-line character.
8373 @item @emph{Standard}:
8374 Fortran 2003 and later
8379 @item @emph{Syntax}:
8380 @code{RESULT = NEW_LINE(C)}
8382 @item @emph{Arguments}:
8383 @multitable @columnfractions .15 .70
8384 @item @var{C} @tab The argument shall be a scalar or array of the
8385 type @code{CHARACTER}.
8388 @item @emph{Return value}:
8389 Returns a @var{CHARACTER} scalar of length one with the new-line character of
8390 the same kind as parameter @var{C}.
8392 @item @emph{Example}:
8396 write(*,'(A)') 'This is record 1.'//NEW_LINE('A')//'This is record 2.'
8404 @section @code{NINT} --- Nearest whole number
8407 @cindex rounding, nearest whole number
8410 @item @emph{Description}:
8411 @code{NINT(A)} rounds its argument to the nearest whole number.
8413 @item @emph{Standard}:
8414 Fortran 77 and later, with @var{KIND} argument Fortran 90 and later
8419 @item @emph{Syntax}:
8420 @code{RESULT = NINT(A [, KIND])}
8422 @item @emph{Arguments}:
8423 @multitable @columnfractions .15 .70
8424 @item @var{A} @tab The type of the argument shall be @code{REAL}.
8425 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
8426 expression indicating the kind parameter of the result.
8429 @item @emph{Return value}:
8430 Returns @var{A} with the fractional portion of its magnitude eliminated by
8431 rounding to the nearest whole number and with its sign preserved,
8432 converted to an @code{INTEGER} of the default kind.
8434 @item @emph{Example}:
8441 print *, nint(x4), idnint(x8)
8442 end program test_nint
8445 @item @emph{Specific names}:
8446 @multitable @columnfractions .20 .20 .20 .25
8447 @item Name @tab Argument @tab Return Type @tab Standard
8448 @item @code{NINT(A)} @tab @code{REAL(4) A} @tab @code{INTEGER} @tab Fortran 95 and later
8449 @item @code{IDNINT(A)} @tab @code{REAL(8) A} @tab @code{INTEGER} @tab Fortran 95 and later
8452 @item @emph{See also}:
8453 @ref{CEILING}, @ref{FLOOR}
8460 @section @code{NOT} --- Logical negation
8462 @cindex bits, negate
8463 @cindex bitwise logical not
8464 @cindex logical not, bitwise
8467 @item @emph{Description}:
8468 @code{NOT} returns the bitwise boolean inverse of @var{I}.
8470 @item @emph{Standard}:
8471 Fortran 95 and later
8476 @item @emph{Syntax}:
8477 @code{RESULT = NOT(I)}
8479 @item @emph{Arguments}:
8480 @multitable @columnfractions .15 .70
8481 @item @var{I} @tab The type shall be @code{INTEGER}.
8484 @item @emph{Return value}:
8485 The return type is @code{INTEGER}, of the same kind as the
8488 @item @emph{See also}:
8489 @ref{IAND}, @ref{IEOR}, @ref{IOR}, @ref{IBITS}, @ref{IBSET}, @ref{IBCLR}
8496 @section @code{NULL} --- Function that returns an disassociated pointer
8498 @cindex pointer, status
8499 @cindex pointer, disassociated
8502 @item @emph{Description}:
8503 Returns a disassociated pointer.
8505 If @var{MOLD} is present, a dissassociated pointer of the same type is
8506 returned, otherwise the type is determined by context.
8508 In Fortran 95, @var{MOLD} is optional. Please note that Fortran 2003
8509 includes cases where it is required.
8511 @item @emph{Standard}:
8512 Fortran 95 and later
8515 Transformational function
8517 @item @emph{Syntax}:
8518 @code{PTR => NULL([MOLD])}
8520 @item @emph{Arguments}:
8521 @multitable @columnfractions .15 .70
8522 @item @var{MOLD} @tab (Optional) shall be a pointer of any association
8523 status and of any type.
8526 @item @emph{Return value}:
8527 A disassociated pointer.
8529 @item @emph{Example}:
8531 REAL, POINTER, DIMENSION(:) :: VEC => NULL ()
8534 @item @emph{See also}:
8541 @section @code{NUM_IMAGES} --- Function that returns the number of images
8543 @cindex coarray, NUM_IMAGES
8544 @cindex images, number of
8547 @item @emph{Description}:
8548 Returns the number of images.
8550 @item @emph{Standard}:
8551 Fortran 2008 and later
8554 Transformational function
8556 @item @emph{Syntax}:
8557 @code{RESULT = NUM_IMAGES()}
8559 @item @emph{Arguments}: None.
8561 @item @emph{Return value}:
8562 Scalar default-kind integer.
8564 @item @emph{Example}:
8568 value = THIS_IMAGE()
8570 IF (THIS_IMAGE() == 1) THEN
8571 DO i = 1, NUM_IMAGES()
8572 WRITE(*,'(2(a,i0))') 'value[', i, '] is ', value[i]
8577 @item @emph{See also}:
8578 @ref{THIS_IMAGE}, @ref{IMAGE_INDEX}
8584 @section @code{OR} --- Bitwise logical OR
8586 @cindex bitwise logical or
8587 @cindex logical or, bitwise
8590 @item @emph{Description}:
8591 Bitwise logical @code{OR}.
8593 This intrinsic routine is provided for backwards compatibility with
8594 GNU Fortran 77. For integer arguments, programmers should consider
8595 the use of the @ref{IOR} intrinsic defined by the Fortran standard.
8597 @item @emph{Standard}:
8603 @item @emph{Syntax}:
8604 @code{RESULT = OR(I, J)}
8606 @item @emph{Arguments}:
8607 @multitable @columnfractions .15 .70
8608 @item @var{I} @tab The type shall be either a scalar @code{INTEGER}
8609 type or a scalar @code{LOGICAL} type.
8610 @item @var{J} @tab The type shall be the same as the type of @var{J}.
8613 @item @emph{Return value}:
8614 The return type is either a scalar @code{INTEGER} or a scalar
8615 @code{LOGICAL}. If the kind type parameters differ, then the
8616 smaller kind type is implicitly converted to larger kind, and the
8617 return has the larger kind.
8619 @item @emph{Example}:
8622 LOGICAL :: T = .TRUE., F = .FALSE.
8624 DATA a / Z'F' /, b / Z'3' /
8626 WRITE (*,*) OR(T, T), OR(T, F), OR(F, T), OR(F, F)
8627 WRITE (*,*) OR(a, b)
8631 @item @emph{See also}:
8632 Fortran 95 elemental function: @ref{IOR}
8638 @section @code{PACK} --- Pack an array into an array of rank one
8640 @cindex array, packing
8641 @cindex array, reduce dimension
8642 @cindex array, gather elements
8645 @item @emph{Description}:
8646 Stores the elements of @var{ARRAY} in an array of rank one.
8648 The beginning of the resulting array is made up of elements whose @var{MASK}
8649 equals @code{TRUE}. Afterwards, positions are filled with elements taken from
8652 @item @emph{Standard}:
8653 Fortran 95 and later
8656 Transformational function
8658 @item @emph{Syntax}:
8659 @code{RESULT = PACK(ARRAY, MASK[,VECTOR]}
8661 @item @emph{Arguments}:
8662 @multitable @columnfractions .15 .70
8663 @item @var{ARRAY} @tab Shall be an array of any type.
8664 @item @var{MASK} @tab Shall be an array of type @code{LOGICAL} and
8665 of the same size as @var{ARRAY}. Alternatively, it may be a @code{LOGICAL}
8667 @item @var{VECTOR} @tab (Optional) shall be an array of the same type
8668 as @var{ARRAY} and of rank one. If present, the number of elements in
8669 @var{VECTOR} shall be equal to or greater than the number of true elements
8670 in @var{MASK}. If @var{MASK} is scalar, the number of elements in
8671 @var{VECTOR} shall be equal to or greater than the number of elements in
8675 @item @emph{Return value}:
8676 The result is an array of rank one and the same type as that of @var{ARRAY}.
8677 If @var{VECTOR} is present, the result size is that of @var{VECTOR}, the
8678 number of @code{TRUE} values in @var{MASK} otherwise.
8680 @item @emph{Example}:
8681 Gathering nonzero elements from an array:
8685 m = (/ 1, 0, 0, 0, 5, 0 /)
8686 WRITE(*, FMT="(6(I0, ' '))") pack(m, m /= 0) ! "1 5"
8690 Gathering nonzero elements from an array and appending elements from @var{VECTOR}:
8694 m = (/ 1, 0, 0, 2 /)
8695 WRITE(*, FMT="(4(I0, ' '))") pack(m, m /= 0, (/ 0, 0, 3, 4 /)) ! "1 2 3 4"
8699 @item @emph{See also}:
8706 @section @code{PERROR} --- Print system error message
8708 @cindex system, error handling
8711 @item @emph{Description}:
8712 Prints (on the C @code{stderr} stream) a newline-terminated error
8713 message corresponding to the last system error. This is prefixed by
8714 @var{STRING}, a colon and a space. See @code{perror(3)}.
8716 @item @emph{Standard}:
8722 @item @emph{Syntax}:
8723 @code{CALL PERROR(STRING)}
8725 @item @emph{Arguments}:
8726 @multitable @columnfractions .15 .70
8727 @item @var{STRING} @tab A scalar of type @code{CHARACTER} and of the
8731 @item @emph{See also}:
8738 @section @code{PRECISION} --- Decimal precision of a real kind
8740 @cindex model representation, precision
8743 @item @emph{Description}:
8744 @code{PRECISION(X)} returns the decimal precision in the model of the
8747 @item @emph{Standard}:
8748 Fortran 95 and later
8753 @item @emph{Syntax}:
8754 @code{RESULT = PRECISION(X)}
8756 @item @emph{Arguments}:
8757 @multitable @columnfractions .15 .70
8758 @item @var{X} @tab Shall be of type @code{REAL} or @code{COMPLEX}.
8761 @item @emph{Return value}:
8762 The return value is of type @code{INTEGER} and of the default integer
8765 @item @emph{Example}:
8767 program prec_and_range
8768 real(kind=4) :: x(2)
8769 complex(kind=8) :: y
8771 print *, precision(x), range(x)
8772 print *, precision(y), range(y)
8773 end program prec_and_range
8780 @section @code{PRESENT} --- Determine whether an optional dummy argument is specified
8784 @item @emph{Description}:
8785 Determines whether an optional dummy argument is present.
8787 @item @emph{Standard}:
8788 Fortran 95 and later
8793 @item @emph{Syntax}:
8794 @code{RESULT = PRESENT(A)}
8796 @item @emph{Arguments}:
8797 @multitable @columnfractions .15 .70
8798 @item @var{A} @tab May be of any type and may be a pointer, scalar or array
8799 value, or a dummy procedure. It shall be the name of an optional dummy argument
8800 accessible within the current subroutine or function.
8803 @item @emph{Return value}:
8804 Returns either @code{TRUE} if the optional argument @var{A} is present, or
8805 @code{FALSE} otherwise.
8807 @item @emph{Example}:
8809 PROGRAM test_present
8810 WRITE(*,*) f(), f(42) ! "F T"
8812 LOGICAL FUNCTION f(x)
8813 INTEGER, INTENT(IN), OPTIONAL :: x
8823 @section @code{PRODUCT} --- Product of array elements
8825 @cindex array, product
8826 @cindex array, multiply elements
8827 @cindex array, conditionally multiply elements
8828 @cindex multiply array elements
8831 @item @emph{Description}:
8832 Multiplies the elements of @var{ARRAY} along dimension @var{DIM} if
8833 the corresponding element in @var{MASK} is @code{TRUE}.
8835 @item @emph{Standard}:
8836 Fortran 95 and later
8839 Transformational function
8841 @item @emph{Syntax}:
8842 @multitable @columnfractions .80
8843 @item @code{RESULT = PRODUCT(ARRAY[, MASK])}
8844 @item @code{RESULT = PRODUCT(ARRAY, DIM[, MASK])}
8847 @item @emph{Arguments}:
8848 @multitable @columnfractions .15 .70
8849 @item @var{ARRAY} @tab Shall be an array of type @code{INTEGER},
8850 @code{REAL} or @code{COMPLEX}.
8851 @item @var{DIM} @tab (Optional) shall be a scalar of type
8852 @code{INTEGER} with a value in the range from 1 to n, where n
8853 equals the rank of @var{ARRAY}.
8854 @item @var{MASK} @tab (Optional) shall be of type @code{LOGICAL}
8855 and either be a scalar or an array of the same shape as @var{ARRAY}.
8858 @item @emph{Return value}:
8859 The result is of the same type as @var{ARRAY}.
8861 If @var{DIM} is absent, a scalar with the product of all elements in
8862 @var{ARRAY} is returned. Otherwise, an array of rank n-1, where n equals
8863 the rank of @var{ARRAY}, and a shape similar to that of @var{ARRAY} with
8864 dimension @var{DIM} dropped is returned.
8867 @item @emph{Example}:
8869 PROGRAM test_product
8870 INTEGER :: x(5) = (/ 1, 2, 3, 4 ,5 /)
8871 print *, PRODUCT(x) ! all elements, product = 120
8872 print *, PRODUCT(x, MASK=MOD(x, 2)==1) ! odd elements, product = 15
8876 @item @emph{See also}:
8883 @section @code{RADIX} --- Base of a model number
8885 @cindex model representation, base
8886 @cindex model representation, radix
8889 @item @emph{Description}:
8890 @code{RADIX(X)} returns the base of the model representing the entity @var{X}.
8892 @item @emph{Standard}:
8893 Fortran 95 and later
8898 @item @emph{Syntax}:
8899 @code{RESULT = RADIX(X)}
8901 @item @emph{Arguments}:
8902 @multitable @columnfractions .15 .70
8903 @item @var{X} @tab Shall be of type @code{INTEGER} or @code{REAL}
8906 @item @emph{Return value}:
8907 The return value is a scalar of type @code{INTEGER} and of the default
8910 @item @emph{Example}:
8913 print *, "The radix for the default integer kind is", radix(0)
8914 print *, "The radix for the default real kind is", radix(0.0)
8915 end program test_radix
8923 @section @code{RAN} --- Real pseudo-random number
8925 @cindex random number generation
8928 @item @emph{Description}:
8929 For compatibility with HP FORTRAN 77/iX, the @code{RAN} intrinsic is
8930 provided as an alias for @code{RAND}. See @ref{RAND} for complete
8933 @item @emph{Standard}:
8939 @item @emph{See also}:
8940 @ref{RAND}, @ref{RANDOM_NUMBER}
8946 @section @code{RAND} --- Real pseudo-random number
8948 @cindex random number generation
8951 @item @emph{Description}:
8952 @code{RAND(FLAG)} returns a pseudo-random number from a uniform
8953 distribution between 0 and 1. If @var{FLAG} is 0, the next number
8954 in the current sequence is returned; if @var{FLAG} is 1, the generator
8955 is restarted by @code{CALL SRAND(0)}; if @var{FLAG} has any other value,
8956 it is used as a new seed with @code{SRAND}.
8958 This intrinsic routine is provided for backwards compatibility with
8959 GNU Fortran 77. It implements a simple modulo generator as provided
8960 by @command{g77}. For new code, one should consider the use of
8961 @ref{RANDOM_NUMBER} as it implements a superior algorithm.
8963 @item @emph{Standard}:
8969 @item @emph{Syntax}:
8970 @code{RESULT = RAND(I)}
8972 @item @emph{Arguments}:
8973 @multitable @columnfractions .15 .70
8974 @item @var{I} @tab Shall be a scalar @code{INTEGER} of kind 4.
8977 @item @emph{Return value}:
8978 The return value is of @code{REAL} type and the default kind.
8980 @item @emph{Example}:
8983 integer,parameter :: seed = 86456
8986 print *, rand(), rand(), rand(), rand()
8987 print *, rand(seed), rand(), rand(), rand()
8988 end program test_rand
8991 @item @emph{See also}:
8992 @ref{SRAND}, @ref{RANDOM_NUMBER}
8999 @section @code{RANDOM_NUMBER} --- Pseudo-random number
9000 @fnindex RANDOM_NUMBER
9001 @cindex random number generation
9004 @item @emph{Description}:
9005 Returns a single pseudorandom number or an array of pseudorandom numbers
9006 from the uniform distribution over the range @math{ 0 \leq x < 1}.
9008 The runtime-library implements George Marsaglia's KISS (Keep It Simple
9009 Stupid) random number generator (RNG). This RNG combines:
9011 @item The congruential generator @math{x(n) = 69069 \cdot x(n-1) + 1327217885}
9012 with a period of @math{2^{32}},
9013 @item A 3-shift shift-register generator with a period of @math{2^{32} - 1},
9014 @item Two 16-bit multiply-with-carry generators with a period of
9015 @math{597273182964842497 > 2^{59}}.
9017 The overall period exceeds @math{2^{123}}.
9019 Please note, this RNG is thread safe if used within OpenMP directives,
9020 i.e., its state will be consistent while called from multiple threads.
9021 However, the KISS generator does not create random numbers in parallel
9022 from multiple sources, but in sequence from a single source. If an
9023 OpenMP-enabled application heavily relies on random numbers, one should
9024 consider employing a dedicated parallel random number generator instead.
9026 @item @emph{Standard}:
9027 Fortran 95 and later
9032 @item @emph{Syntax}:
9033 @code{RANDOM_NUMBER(HARVEST)}
9035 @item @emph{Arguments}:
9036 @multitable @columnfractions .15 .70
9037 @item @var{HARVEST} @tab Shall be a scalar or an array of type @code{REAL}.
9040 @item @emph{Example}:
9042 program test_random_number
9044 CALL init_random_seed() ! see example of RANDOM_SEED
9045 CALL RANDOM_NUMBER(r)
9049 @item @emph{See also}:
9056 @section @code{RANDOM_SEED} --- Initialize a pseudo-random number sequence
9057 @fnindex RANDOM_SEED
9058 @cindex random number generation, seeding
9059 @cindex seeding a random number generator
9062 @item @emph{Description}:
9063 Restarts or queries the state of the pseudorandom number generator used by
9064 @code{RANDOM_NUMBER}.
9066 If @code{RANDOM_SEED} is called without arguments, it is initialized to
9067 a default state. The example below shows how to initialize the random
9068 seed based on the system's time.
9070 @item @emph{Standard}:
9071 Fortran 95 and later
9076 @item @emph{Syntax}:
9077 @code{CALL RANDOM_SEED([SIZE, PUT, GET])}
9079 @item @emph{Arguments}:
9080 @multitable @columnfractions .15 .70
9081 @item @var{SIZE} @tab (Optional) Shall be a scalar and of type default
9082 @code{INTEGER}, with @code{INTENT(OUT)}. It specifies the minimum size
9083 of the arrays used with the @var{PUT} and @var{GET} arguments.
9084 @item @var{PUT} @tab (Optional) Shall be an array of type default
9085 @code{INTEGER} and rank one. It is @code{INTENT(IN)} and the size of
9086 the array must be larger than or equal to the number returned by the
9087 @var{SIZE} argument.
9088 @item @var{GET} @tab (Optional) Shall be an array of type default
9089 @code{INTEGER} and rank one. It is @code{INTENT(OUT)} and the size
9090 of the array must be larger than or equal to the number returned by
9091 the @var{SIZE} argument.
9094 @item @emph{Example}:
9096 SUBROUTINE init_random_seed()
9097 INTEGER :: i, n, clock
9098 INTEGER, DIMENSION(:), ALLOCATABLE :: seed
9100 CALL RANDOM_SEED(size = n)
9103 CALL SYSTEM_CLOCK(COUNT=clock)
9105 seed = clock + 37 * (/ (i - 1, i = 1, n) /)
9106 CALL RANDOM_SEED(PUT = seed)
9112 @item @emph{See also}:
9119 @section @code{RANGE} --- Decimal exponent range
9121 @cindex model representation, range
9124 @item @emph{Description}:
9125 @code{RANGE(X)} returns the decimal exponent range in the model of the
9128 @item @emph{Standard}:
9129 Fortran 95 and later
9134 @item @emph{Syntax}:
9135 @code{RESULT = RANGE(X)}
9137 @item @emph{Arguments}:
9138 @multitable @columnfractions .15 .70
9139 @item @var{X} @tab Shall be of type @code{INTEGER}, @code{REAL}
9143 @item @emph{Return value}:
9144 The return value is of type @code{INTEGER} and of the default integer
9147 @item @emph{Example}:
9148 See @code{PRECISION} for an example.
9154 @section @code{REAL} --- Convert to real type
9157 @cindex conversion, to real
9158 @cindex complex numbers, real part
9161 @item @emph{Description}:
9162 @code{REAL(A [, KIND])} converts its argument @var{A} to a real type. The
9163 @code{REALPART} function is provided for compatibility with @command{g77},
9164 and its use is strongly discouraged.
9166 @item @emph{Standard}:
9167 Fortran 77 and later
9172 @item @emph{Syntax}:
9173 @multitable @columnfractions .80
9174 @item @code{RESULT = REAL(A [, KIND])}
9175 @item @code{RESULT = REALPART(Z)}
9178 @item @emph{Arguments}:
9179 @multitable @columnfractions .15 .70
9180 @item @var{A} @tab Shall be @code{INTEGER}, @code{REAL}, or
9182 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
9183 expression indicating the kind parameter of the result.
9186 @item @emph{Return value}:
9187 These functions return a @code{REAL} variable or array under
9188 the following rules:
9192 @code{REAL(A)} is converted to a default real type if @var{A} is an
9193 integer or real variable.
9195 @code{REAL(A)} is converted to a real type with the kind type parameter
9196 of @var{A} if @var{A} is a complex variable.
9198 @code{REAL(A, KIND)} is converted to a real type with kind type
9199 parameter @var{KIND} if @var{A} is a complex, integer, or real
9203 @item @emph{Example}:
9206 complex :: x = (1.0, 2.0)
9207 print *, real(x), real(x,8), realpart(x)
9208 end program test_real
9211 @item @emph{Specific names}:
9212 @multitable @columnfractions .20 .20 .20 .25
9213 @item Name @tab Argument @tab Return type @tab Standard
9214 @item @code{REAL(A)} @tab @code{INTEGER(4)} @tab @code{REAL(4)} @tab Fortran 77 and later
9218 @item @emph{See also}:
9219 @ref{DBLE}, @ref{DFLOAT}, @ref{FLOAT}
9226 @section @code{RENAME} --- Rename a file
9228 @cindex file system, rename file
9231 @item @emph{Description}:
9232 Renames a file from file @var{PATH1} to @var{PATH2}. A null
9233 character (@code{CHAR(0)}) can be used to mark the end of the names in
9234 @var{PATH1} and @var{PATH2}; otherwise, trailing blanks in the file
9235 names are ignored. If the @var{STATUS} argument is supplied, it
9236 contains 0 on success or a nonzero error code upon return; see
9239 This intrinsic is provided in both subroutine and function forms;
9240 however, only one form can be used in any given program unit.
9242 @item @emph{Standard}:
9246 Subroutine, function
9248 @item @emph{Syntax}:
9249 @multitable @columnfractions .80
9250 @item @code{CALL RENAME(PATH1, PATH2 [, STATUS])}
9251 @item @code{STATUS = RENAME(PATH1, PATH2)}
9254 @item @emph{Arguments}:
9255 @multitable @columnfractions .15 .70
9256 @item @var{PATH1} @tab Shall be of default @code{CHARACTER} type.
9257 @item @var{PATH2} @tab Shall be of default @code{CHARACTER} type.
9258 @item @var{STATUS} @tab (Optional) Shall be of default @code{INTEGER} type.
9261 @item @emph{See also}:
9269 @section @code{REPEAT} --- Repeated string concatenation
9271 @cindex string, repeat
9272 @cindex string, concatenate
9275 @item @emph{Description}:
9276 Concatenates @var{NCOPIES} copies of a string.
9278 @item @emph{Standard}:
9279 Fortran 95 and later
9282 Transformational function
9284 @item @emph{Syntax}:
9285 @code{RESULT = REPEAT(STRING, NCOPIES)}
9287 @item @emph{Arguments}:
9288 @multitable @columnfractions .15 .70
9289 @item @var{STRING} @tab Shall be scalar and of type @code{CHARACTER}.
9290 @item @var{NCOPIES} @tab Shall be scalar and of type @code{INTEGER}.
9293 @item @emph{Return value}:
9294 A new scalar of type @code{CHARACTER} built up from @var{NCOPIES} copies
9297 @item @emph{Example}:
9300 write(*,*) repeat("x", 5) ! "xxxxx"
9308 @section @code{RESHAPE} --- Function to reshape an array
9310 @cindex array, change dimensions
9311 @cindex array, transmogrify
9314 @item @emph{Description}:
9315 Reshapes @var{SOURCE} to correspond to @var{SHAPE}. If necessary,
9316 the new array may be padded with elements from @var{PAD} or permuted
9317 as defined by @var{ORDER}.
9319 @item @emph{Standard}:
9320 Fortran 95 and later
9323 Transformational function
9325 @item @emph{Syntax}:
9326 @code{RESULT = RESHAPE(SOURCE, SHAPE[, PAD, ORDER])}
9328 @item @emph{Arguments}:
9329 @multitable @columnfractions .15 .70
9330 @item @var{SOURCE} @tab Shall be an array of any type.
9331 @item @var{SHAPE} @tab Shall be of type @code{INTEGER} and an
9332 array of rank one. Its values must be positive or zero.
9333 @item @var{PAD} @tab (Optional) shall be an array of the same
9334 type as @var{SOURCE}.
9335 @item @var{ORDER} @tab (Optional) shall be of type @code{INTEGER}
9336 and an array of the same shape as @var{SHAPE}. Its values shall
9337 be a permutation of the numbers from 1 to n, where n is the size of
9338 @var{SHAPE}. If @var{ORDER} is absent, the natural ordering shall
9342 @item @emph{Return value}:
9343 The result is an array of shape @var{SHAPE} with the same type as
9346 @item @emph{Example}:
9348 PROGRAM test_reshape
9349 INTEGER, DIMENSION(4) :: x
9350 WRITE(*,*) SHAPE(x) ! prints "4"
9351 WRITE(*,*) SHAPE(RESHAPE(x, (/2, 2/))) ! prints "2 2"
9355 @item @emph{See also}:
9362 @section @code{RRSPACING} --- Reciprocal of the relative spacing
9364 @cindex real number, relative spacing
9365 @cindex floating point, relative spacing
9369 @item @emph{Description}:
9370 @code{RRSPACING(X)} returns the reciprocal of the relative spacing of
9371 model numbers near @var{X}.
9373 @item @emph{Standard}:
9374 Fortran 95 and later
9379 @item @emph{Syntax}:
9380 @code{RESULT = RRSPACING(X)}
9382 @item @emph{Arguments}:
9383 @multitable @columnfractions .15 .70
9384 @item @var{X} @tab Shall be of type @code{REAL}.
9387 @item @emph{Return value}:
9388 The return value is of the same type and kind as @var{X}.
9389 The value returned is equal to
9390 @code{ABS(FRACTION(X)) * FLOAT(RADIX(X))**DIGITS(X)}.
9392 @item @emph{See also}:
9399 @section @code{RSHIFT} --- Right shift bits
9401 @cindex bits, shift right
9404 @item @emph{Description}:
9405 @code{RSHIFT} returns a value corresponding to @var{I} with all of the
9406 bits shifted right by @var{SHIFT} places. If the absolute value of
9407 @var{SHIFT} is greater than @code{BIT_SIZE(I)}, the value is undefined.
9408 Bits shifted out from the left end are lost; zeros are shifted in from
9411 This function has been superseded by the @code{ISHFT} intrinsic, which
9412 is standard in Fortran 95 and later.
9414 @item @emph{Standard}:
9420 @item @emph{Syntax}:
9421 @code{RESULT = RSHIFT(I, SHIFT)}
9423 @item @emph{Arguments}:
9424 @multitable @columnfractions .15 .70
9425 @item @var{I} @tab The type shall be @code{INTEGER}.
9426 @item @var{SHIFT} @tab The type shall be @code{INTEGER}.
9429 @item @emph{Return value}:
9430 The return value is of type @code{INTEGER} and of the same kind as
9433 @item @emph{See also}:
9434 @ref{ISHFT}, @ref{ISHFTC}, @ref{LSHIFT}
9441 @section @code{SCALE} --- Scale a real value
9443 @cindex real number, scale
9444 @cindex floating point, scale
9447 @item @emph{Description}:
9448 @code{SCALE(X,I)} returns @code{X * RADIX(X)**I}.
9450 @item @emph{Standard}:
9451 Fortran 95 and later
9456 @item @emph{Syntax}:
9457 @code{RESULT = SCALE(X, I)}
9459 @item @emph{Arguments}:
9460 @multitable @columnfractions .15 .70
9461 @item @var{X} @tab The type of the argument shall be a @code{REAL}.
9462 @item @var{I} @tab The type of the argument shall be a @code{INTEGER}.
9465 @item @emph{Return value}:
9466 The return value is of the same type and kind as @var{X}.
9467 Its value is @code{X * RADIX(X)**I}.
9469 @item @emph{Example}:
9472 real :: x = 178.1387e-4
9474 print *, scale(x,i), x*radix(x)**i
9475 end program test_scale
9483 @section @code{SCAN} --- Scan a string for the presence of a set of characters
9485 @cindex string, find subset
9488 @item @emph{Description}:
9489 Scans a @var{STRING} for any of the characters in a @var{SET}
9492 If @var{BACK} is either absent or equals @code{FALSE}, this function
9493 returns the position of the leftmost character of @var{STRING} that is
9494 in @var{SET}. If @var{BACK} equals @code{TRUE}, the rightmost position
9495 is returned. If no character of @var{SET} is found in @var{STRING}, the
9498 @item @emph{Standard}:
9499 Fortran 95 and later, with @var{KIND} argument Fortran 2003 and later
9504 @item @emph{Syntax}:
9505 @code{RESULT = SCAN(STRING, SET[, BACK [, KIND]])}
9507 @item @emph{Arguments}:
9508 @multitable @columnfractions .15 .70
9509 @item @var{STRING} @tab Shall be of type @code{CHARACTER}.
9510 @item @var{SET} @tab Shall be of type @code{CHARACTER}.
9511 @item @var{BACK} @tab (Optional) shall be of type @code{LOGICAL}.
9512 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
9513 expression indicating the kind parameter of the result.
9516 @item @emph{Return value}:
9517 The return value is of type @code{INTEGER} and of kind @var{KIND}. If
9518 @var{KIND} is absent, the return value is of default integer kind.
9520 @item @emph{Example}:
9523 WRITE(*,*) SCAN("FORTRAN", "AO") ! 2, found 'O'
9524 WRITE(*,*) SCAN("FORTRAN", "AO", .TRUE.) ! 6, found 'A'
9525 WRITE(*,*) SCAN("FORTRAN", "C++") ! 0, found none
9529 @item @emph{See also}:
9530 @ref{INDEX intrinsic}, @ref{VERIFY}
9536 @section @code{SECNDS} --- Time function
9538 @cindex time, elapsed
9539 @cindex elapsed time
9542 @item @emph{Description}:
9543 @code{SECNDS(X)} gets the time in seconds from the real-time system clock.
9544 @var{X} is a reference time, also in seconds. If this is zero, the time in
9545 seconds from midnight is returned. This function is non-standard and its
9548 @item @emph{Standard}:
9554 @item @emph{Syntax}:
9555 @code{RESULT = SECNDS (X)}
9557 @item @emph{Arguments}:
9558 @multitable @columnfractions .15 .70
9559 @item @var{T} @tab Shall be of type @code{REAL(4)}.
9560 @item @var{X} @tab Shall be of type @code{REAL(4)}.
9563 @item @emph{Return value}:
9566 @item @emph{Example}:
9571 print *, secnds (0.0) ! seconds since midnight
9572 t1 = secnds (0.0) ! reference time
9573 do i = 1, 10000000 ! do something
9575 t2 = secnds (t1) ! elapsed time
9576 print *, "Something took ", t2, " seconds."
9577 end program test_secnds
9584 @section @code{SECOND} --- CPU time function
9586 @cindex time, elapsed
9587 @cindex elapsed time
9590 @item @emph{Description}:
9591 Returns a @code{REAL(4)} value representing the elapsed CPU time in
9592 seconds. This provides the same functionality as the standard
9593 @code{CPU_TIME} intrinsic, and is only included for backwards
9596 This intrinsic is provided in both subroutine and function forms;
9597 however, only one form can be used in any given program unit.
9599 @item @emph{Standard}:
9603 Subroutine, function
9605 @item @emph{Syntax}:
9606 @multitable @columnfractions .80
9607 @item @code{CALL SECOND(TIME)}
9608 @item @code{TIME = SECOND()}
9611 @item @emph{Arguments}:
9612 @multitable @columnfractions .15 .70
9613 @item @var{TIME} @tab Shall be of type @code{REAL(4)}.
9616 @item @emph{Return value}:
9617 In either syntax, @var{TIME} is set to the process's current runtime in
9620 @item @emph{See also}:
9627 @node SELECTED_CHAR_KIND
9628 @section @code{SELECTED_CHAR_KIND} --- Choose character kind
9629 @fnindex SELECTED_CHAR_KIND
9630 @cindex character kind
9631 @cindex kind, character
9634 @item @emph{Description}:
9636 @code{SELECTED_CHAR_KIND(NAME)} returns the kind value for the character
9637 set named @var{NAME}, if a character set with such a name is supported,
9638 or @math{-1} otherwise. Currently, supported character sets include
9639 ``ASCII'' and ``DEFAULT'', which are equivalent.
9641 @item @emph{Standard}:
9642 Fortran 2003 and later
9645 Transformational function
9647 @item @emph{Syntax}:
9648 @code{RESULT = SELECTED_CHAR_KIND(NAME)}
9650 @item @emph{Arguments}:
9651 @multitable @columnfractions .15 .70
9652 @item @var{NAME} @tab Shall be a scalar and of the default character type.
9655 @item @emph{Example}:
9658 integer,parameter :: ascii = selected_char_kind("ascii")
9659 character(kind=ascii, len=26) :: s
9661 s = ascii_"abcdefghijklmnopqrstuvwxyz"
9663 end program ascii_kind
9669 @node SELECTED_INT_KIND
9670 @section @code{SELECTED_INT_KIND} --- Choose integer kind
9671 @fnindex SELECTED_INT_KIND
9672 @cindex integer kind
9673 @cindex kind, integer
9676 @item @emph{Description}:
9677 @code{SELECTED_INT_KIND(R)} return the kind value of the smallest integer
9678 type that can represent all values ranging from @math{-10^R} (exclusive)
9679 to @math{10^R} (exclusive). If there is no integer kind that accommodates
9680 this range, @code{SELECTED_INT_KIND} returns @math{-1}.
9682 @item @emph{Standard}:
9683 Fortran 95 and later
9686 Transformational function
9688 @item @emph{Syntax}:
9689 @code{RESULT = SELECTED_INT_KIND(R)}
9691 @item @emph{Arguments}:
9692 @multitable @columnfractions .15 .70
9693 @item @var{R} @tab Shall be a scalar and of type @code{INTEGER}.
9696 @item @emph{Example}:
9698 program large_integers
9699 integer,parameter :: k5 = selected_int_kind(5)
9700 integer,parameter :: k15 = selected_int_kind(15)
9701 integer(kind=k5) :: i5
9702 integer(kind=k15) :: i15
9704 print *, huge(i5), huge(i15)
9706 ! The following inequalities are always true
9707 print *, huge(i5) >= 10_k5**5-1
9708 print *, huge(i15) >= 10_k15**15-1
9709 end program large_integers
9715 @node SELECTED_REAL_KIND
9716 @section @code{SELECTED_REAL_KIND} --- Choose real kind
9717 @fnindex SELECTED_REAL_KIND
9722 @item @emph{Description}:
9723 @code{SELECTED_REAL_KIND(P,R)} returns the kind value of a real data type
9724 with decimal precision of at least @code{P} digits and exponent
9725 range greater at least @code{R}.
9727 @item @emph{Standard}:
9728 Fortran 95 and later
9731 Transformational function
9733 @item @emph{Syntax}:
9734 @code{RESULT = SELECTED_REAL_KIND([P, R])}
9736 @item @emph{Arguments}:
9737 @multitable @columnfractions .15 .70
9738 @item @var{P} @tab (Optional) shall be a scalar and of type @code{INTEGER}.
9739 @item @var{R} @tab (Optional) shall be a scalar and of type @code{INTEGER}.
9741 At least one argument shall be present.
9743 @item @emph{Return value}:
9745 @code{SELECTED_REAL_KIND} returns the value of the kind type parameter of
9746 a real data type with decimal precision of at least @code{P} digits and a
9747 decimal exponent range of at least @code{R}. If more than one real data
9748 type meet the criteria, the kind of the data type with the smallest
9749 decimal precision is returned. If no real data type matches the criteria,
9752 @item -1 if the processor does not support a real data type with a
9753 precision greater than or equal to @code{P}
9754 @item -2 if the processor does not support a real type with an exponent
9755 range greater than or equal to @code{R}
9756 @item -3 if neither is supported.
9759 @item @emph{Example}:
9762 integer,parameter :: p6 = selected_real_kind(6)
9763 integer,parameter :: p10r100 = selected_real_kind(10,100)
9764 integer,parameter :: r400 = selected_real_kind(r=400)
9766 real(kind=p10r100) :: y
9767 real(kind=r400) :: z
9769 print *, precision(x), range(x)
9770 print *, precision(y), range(y)
9771 print *, precision(z), range(z)
9772 end program real_kinds
9779 @section @code{SET_EXPONENT} --- Set the exponent of the model
9780 @fnindex SET_EXPONENT
9781 @cindex real number, set exponent
9782 @cindex floating point, set exponent
9785 @item @emph{Description}:
9786 @code{SET_EXPONENT(X, I)} returns the real number whose fractional part
9787 is that that of @var{X} and whose exponent part is @var{I}.
9789 @item @emph{Standard}:
9790 Fortran 95 and later
9795 @item @emph{Syntax}:
9796 @code{RESULT = SET_EXPONENT(X, I)}
9798 @item @emph{Arguments}:
9799 @multitable @columnfractions .15 .70
9800 @item @var{X} @tab Shall be of type @code{REAL}.
9801 @item @var{I} @tab Shall be of type @code{INTEGER}.
9804 @item @emph{Return value}:
9805 The return value is of the same type and kind as @var{X}.
9806 The real number whose fractional part
9807 is that that of @var{X} and whose exponent part if @var{I} is returned;
9808 it is @code{FRACTION(X) * RADIX(X)**I}.
9810 @item @emph{Example}:
9813 REAL :: x = 178.1387e-4
9815 PRINT *, SET_EXPONENT(x, i), FRACTION(x) * RADIX(x)**i
9824 @section @code{SHAPE} --- Determine the shape of an array
9826 @cindex array, shape
9829 @item @emph{Description}:
9830 Determines the shape of an array.
9832 @item @emph{Standard}:
9833 Fortran 95 and later
9838 @item @emph{Syntax}:
9839 @code{RESULT = SHAPE(SOURCE)}
9841 @item @emph{Arguments}:
9842 @multitable @columnfractions .15 .70
9843 @item @var{SOURCE} @tab Shall be an array or scalar of any type.
9844 If @var{SOURCE} is a pointer it must be associated and allocatable
9845 arrays must be allocated.
9848 @item @emph{Return value}:
9849 An @code{INTEGER} array of rank one with as many elements as @var{SOURCE}
9850 has dimensions. The elements of the resulting array correspond to the extend
9851 of @var{SOURCE} along the respective dimensions. If @var{SOURCE} is a scalar,
9852 the result is the rank one array of size zero.
9854 @item @emph{Example}:
9857 INTEGER, DIMENSION(-1:1, -1:2) :: A
9858 WRITE(*,*) SHAPE(A) ! (/ 3, 4 /)
9859 WRITE(*,*) SIZE(SHAPE(42)) ! (/ /)
9863 @item @emph{See also}:
9864 @ref{RESHAPE}, @ref{SIZE}
9870 @section @code{SIGN} --- Sign copying function
9874 @cindex sign copying
9877 @item @emph{Description}:
9878 @code{SIGN(A,B)} returns the value of @var{A} with the sign of @var{B}.
9880 @item @emph{Standard}:
9881 Fortran 77 and later
9886 @item @emph{Syntax}:
9887 @code{RESULT = SIGN(A, B)}
9889 @item @emph{Arguments}:
9890 @multitable @columnfractions .15 .70
9891 @item @var{A} @tab Shall be of type @code{INTEGER} or @code{REAL}
9892 @item @var{B} @tab Shall be of the same type and kind as @var{A}
9895 @item @emph{Return value}:
9896 The kind of the return value is that of @var{A} and @var{B}.
9897 If @math{B\ge 0} then the result is @code{ABS(A)}, else
9898 it is @code{-ABS(A)}.
9900 @item @emph{Example}:
9903 print *, sign(-12,1)
9904 print *, sign(-12,0)
9905 print *, sign(-12,-1)
9907 print *, sign(-12.,1.)
9908 print *, sign(-12.,0.)
9909 print *, sign(-12.,-1.)
9910 end program test_sign
9913 @item @emph{Specific names}:
9914 @multitable @columnfractions .20 .20 .20 .25
9915 @item Name @tab Arguments @tab Return type @tab Standard
9916 @item @code{SIGN(A,B)} @tab @code{REAL(4) A, B} @tab @code{REAL(4)} @tab f77, gnu
9917 @item @code{ISIGN(A,B)} @tab @code{INTEGER(4) A, B} @tab @code{INTEGER(4)} @tab f77, gnu
9918 @item @code{DSIGN(A,B)} @tab @code{REAL(8) A, B} @tab @code{REAL(8)} @tab f77, gnu
9925 @section @code{SIGNAL} --- Signal handling subroutine (or function)
9927 @cindex system, signal handling
9930 @item @emph{Description}:
9931 @code{SIGNAL(NUMBER, HANDLER [, STATUS])} causes external subroutine
9932 @var{HANDLER} to be executed with a single integer argument when signal
9933 @var{NUMBER} occurs. If @var{HANDLER} is an integer, it can be used to
9934 turn off handling of signal @var{NUMBER} or revert to its default
9935 action. See @code{signal(2)}.
9937 If @code{SIGNAL} is called as a subroutine and the @var{STATUS} argument
9938 is supplied, it is set to the value returned by @code{signal(2)}.
9940 @item @emph{Standard}:
9944 Subroutine, function
9946 @item @emph{Syntax}:
9947 @multitable @columnfractions .80
9948 @item @code{CALL SIGNAL(NUMBER, HANDLER [, STATUS])}
9949 @item @code{STATUS = SIGNAL(NUMBER, HANDLER)}
9952 @item @emph{Arguments}:
9953 @multitable @columnfractions .15 .70
9954 @item @var{NUMBER} @tab Shall be a scalar integer, with @code{INTENT(IN)}
9955 @item @var{HANDLER}@tab Signal handler (@code{INTEGER FUNCTION} or
9956 @code{SUBROUTINE}) or dummy/global @code{INTEGER} scalar.
9957 @code{INTEGER}. It is @code{INTENT(IN)}.
9958 @item @var{STATUS} @tab (Optional) @var{STATUS} shall be a scalar
9959 integer. It has @code{INTENT(OUT)}.
9961 @c TODO: What should the interface of the handler be? Does it take arguments?
9963 @item @emph{Return value}:
9964 The @code{SIGNAL} function returns the value returned by @code{signal(2)}.
9966 @item @emph{Example}:
9970 external handler_print
9972 call signal (12, handler_print)
9976 end program test_signal
9983 @section @code{SIN} --- Sine function
9989 @cindex trigonometric function, sine
9993 @item @emph{Description}:
9994 @code{SIN(X)} computes the sine of @var{X}.
9996 @item @emph{Standard}:
9997 Fortran 77 and later
10002 @item @emph{Syntax}:
10003 @code{RESULT = SIN(X)}
10005 @item @emph{Arguments}:
10006 @multitable @columnfractions .15 .70
10007 @item @var{X} @tab The type shall be @code{REAL} or
10011 @item @emph{Return value}:
10012 The return value has same type and kind as @var{X}.
10014 @item @emph{Example}:
10019 end program test_sin
10022 @item @emph{Specific names}:
10023 @multitable @columnfractions .20 .20 .20 .25
10024 @item Name @tab Argument @tab Return type @tab Standard
10025 @item @code{SIN(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab f77, gnu
10026 @item @code{DSIN(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab f95, gnu
10027 @item @code{CSIN(X)} @tab @code{COMPLEX(4) X} @tab @code{COMPLEX(4)} @tab f95, gnu
10028 @item @code{ZSIN(X)} @tab @code{COMPLEX(8) X} @tab @code{COMPLEX(8)} @tab f95, gnu
10029 @item @code{CDSIN(X)} @tab @code{COMPLEX(8) X} @tab @code{COMPLEX(8)} @tab f95, gnu
10032 @item @emph{See also}:
10039 @section @code{SINH} --- Hyperbolic sine function
10042 @cindex hyperbolic sine
10043 @cindex hyperbolic function, sine
10044 @cindex sine, hyperbolic
10047 @item @emph{Description}:
10048 @code{SINH(X)} computes the hyperbolic sine of @var{X}.
10050 @item @emph{Standard}:
10051 Fortran 95 and later, for a complex argument Fortran 2008 or later
10053 @item @emph{Class}:
10056 @item @emph{Syntax}:
10057 @code{RESULT = SINH(X)}
10059 @item @emph{Arguments}:
10060 @multitable @columnfractions .15 .70
10061 @item @var{X} @tab The type shall be @code{REAL} or @code{COMPLEX}.
10064 @item @emph{Return value}:
10065 The return value has same type and kind as @var{X}.
10067 @item @emph{Example}:
10070 real(8) :: x = - 1.0_8
10072 end program test_sinh
10075 @item @emph{Specific names}:
10076 @multitable @columnfractions .20 .20 .20 .25
10077 @item Name @tab Argument @tab Return type @tab Standard
10078 @item @code{SINH(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab Fortran 95 and later
10079 @item @code{DSINH(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab Fortran 95 and later
10082 @item @emph{See also}:
10089 @section @code{SIZE} --- Determine the size of an array
10091 @cindex array, size
10092 @cindex array, number of elements
10093 @cindex array, count elements
10096 @item @emph{Description}:
10097 Determine the extent of @var{ARRAY} along a specified dimension @var{DIM},
10098 or the total number of elements in @var{ARRAY} if @var{DIM} is absent.
10100 @item @emph{Standard}:
10101 Fortran 95 and later, with @var{KIND} argument Fortran 2003 and later
10103 @item @emph{Class}:
10106 @item @emph{Syntax}:
10107 @code{RESULT = SIZE(ARRAY[, DIM [, KIND]])}
10109 @item @emph{Arguments}:
10110 @multitable @columnfractions .15 .70
10111 @item @var{ARRAY} @tab Shall be an array of any type. If @var{ARRAY} is
10112 a pointer it must be associated and allocatable arrays must be allocated.
10113 @item @var{DIM} @tab (Optional) shall be a scalar of type @code{INTEGER}
10114 and its value shall be in the range from 1 to n, where n equals the rank
10116 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
10117 expression indicating the kind parameter of the result.
10120 @item @emph{Return value}:
10121 The return value is of type @code{INTEGER} and of kind @var{KIND}. If
10122 @var{KIND} is absent, the return value is of default integer kind.
10124 @item @emph{Example}:
10127 WRITE(*,*) SIZE((/ 1, 2 /)) ! 2
10131 @item @emph{See also}:
10132 @ref{SHAPE}, @ref{RESHAPE}
10137 @section @code{SIZEOF} --- Size in bytes of an expression
10139 @cindex expression size
10140 @cindex size of an expression
10143 @item @emph{Description}:
10144 @code{SIZEOF(X)} calculates the number of bytes of storage the
10145 expression @code{X} occupies.
10147 @item @emph{Standard}:
10150 @item @emph{Class}:
10153 @item @emph{Syntax}:
10154 @code{N = SIZEOF(X)}
10156 @item @emph{Arguments}:
10157 @multitable @columnfractions .15 .70
10158 @item @var{X} @tab The argument shall be of any type, rank or shape.
10161 @item @emph{Return value}:
10162 The return value is of type integer and of the system-dependent kind
10163 @var{C_SIZE_T} (from the @var{ISO_C_BINDING} module). Its value is the
10164 number of bytes occupied by the argument. If the argument has the
10165 @code{POINTER} attribute, the number of bytes of the storage area pointed
10166 to is returned. If the argument is of a derived type with @code{POINTER}
10167 or @code{ALLOCATABLE} components, the return value doesn't account for
10168 the sizes of the data pointed to by these components.
10170 @item @emph{Example}:
10174 print *, (sizeof(s)/sizeof(r) == 5)
10177 The example will print @code{.TRUE.} unless you are using a platform
10178 where default @code{REAL} variables are unusually padded.
10180 @item @emph{See also}:
10186 @section @code{SLEEP} --- Sleep for the specified number of seconds
10188 @cindex delayed execution
10191 @item @emph{Description}:
10192 Calling this subroutine causes the process to pause for @var{SECONDS} seconds.
10194 @item @emph{Standard}:
10197 @item @emph{Class}:
10200 @item @emph{Syntax}:
10201 @code{CALL SLEEP(SECONDS)}
10203 @item @emph{Arguments}:
10204 @multitable @columnfractions .15 .70
10205 @item @var{SECONDS} @tab The type shall be of default @code{INTEGER}.
10208 @item @emph{Example}:
10219 @section @code{SNGL} --- Convert double precision real to default real
10221 @cindex conversion, to real
10224 @item @emph{Description}:
10225 @code{SNGL(A)} converts the double precision real @var{A}
10226 to a default real value. This is an archaic form of @code{REAL}
10227 that is specific to one type for @var{A}.
10229 @item @emph{Standard}:
10230 Fortran 77 and later
10232 @item @emph{Class}:
10235 @item @emph{Syntax}:
10236 @code{RESULT = SNGL(A)}
10238 @item @emph{Arguments}:
10239 @multitable @columnfractions .15 .70
10240 @item @var{A} @tab The type shall be a double precision @code{REAL}.
10243 @item @emph{Return value}:
10244 The return value is of type default @code{REAL}.
10246 @item @emph{See also}:
10253 @section @code{SPACING} --- Smallest distance between two numbers of a given type
10255 @cindex real number, relative spacing
10256 @cindex floating point, relative spacing
10259 @item @emph{Description}:
10260 Determines the distance between the argument @var{X} and the nearest
10261 adjacent number of the same type.
10263 @item @emph{Standard}:
10264 Fortran 95 and later
10266 @item @emph{Class}:
10269 @item @emph{Syntax}:
10270 @code{RESULT = SPACING(X)}
10272 @item @emph{Arguments}:
10273 @multitable @columnfractions .15 .70
10274 @item @var{X} @tab Shall be of type @code{REAL}.
10277 @item @emph{Return value}:
10278 The result is of the same type as the input argument @var{X}.
10280 @item @emph{Example}:
10282 PROGRAM test_spacing
10283 INTEGER, PARAMETER :: SGL = SELECTED_REAL_KIND(p=6, r=37)
10284 INTEGER, PARAMETER :: DBL = SELECTED_REAL_KIND(p=13, r=200)
10286 WRITE(*,*) spacing(1.0_SGL) ! "1.1920929E-07" on i686
10287 WRITE(*,*) spacing(1.0_DBL) ! "2.220446049250313E-016" on i686
10291 @item @emph{See also}:
10298 @section @code{SPREAD} --- Add a dimension to an array
10300 @cindex array, increase dimension
10301 @cindex array, duplicate elements
10302 @cindex array, duplicate dimensions
10305 @item @emph{Description}:
10306 Replicates a @var{SOURCE} array @var{NCOPIES} times along a specified
10307 dimension @var{DIM}.
10309 @item @emph{Standard}:
10310 Fortran 95 and later
10312 @item @emph{Class}:
10313 Transformational function
10315 @item @emph{Syntax}:
10316 @code{RESULT = SPREAD(SOURCE, DIM, NCOPIES)}
10318 @item @emph{Arguments}:
10319 @multitable @columnfractions .15 .70
10320 @item @var{SOURCE} @tab Shall be a scalar or an array of any type and
10321 a rank less than seven.
10322 @item @var{DIM} @tab Shall be a scalar of type @code{INTEGER} with a
10323 value in the range from 1 to n+1, where n equals the rank of @var{SOURCE}.
10324 @item @var{NCOPIES} @tab Shall be a scalar of type @code{INTEGER}.
10327 @item @emph{Return value}:
10328 The result is an array of the same type as @var{SOURCE} and has rank n+1
10329 where n equals the rank of @var{SOURCE}.
10331 @item @emph{Example}:
10333 PROGRAM test_spread
10334 INTEGER :: a = 1, b(2) = (/ 1, 2 /)
10335 WRITE(*,*) SPREAD(A, 1, 2) ! "1 1"
10336 WRITE(*,*) SPREAD(B, 1, 2) ! "1 1 2 2"
10340 @item @emph{See also}:
10347 @section @code{SQRT} --- Square-root function
10354 @cindex square-root
10357 @item @emph{Description}:
10358 @code{SQRT(X)} computes the square root of @var{X}.
10360 @item @emph{Standard}:
10361 Fortran 77 and later
10363 @item @emph{Class}:
10366 @item @emph{Syntax}:
10367 @code{RESULT = SQRT(X)}
10369 @item @emph{Arguments}:
10370 @multitable @columnfractions .15 .70
10371 @item @var{X} @tab The type shall be @code{REAL} or
10375 @item @emph{Return value}:
10376 The return value is of type @code{REAL} or @code{COMPLEX}.
10377 The kind type parameter is the same as @var{X}.
10379 @item @emph{Example}:
10382 real(8) :: x = 2.0_8
10383 complex :: z = (1.0, 2.0)
10386 end program test_sqrt
10389 @item @emph{Specific names}:
10390 @multitable @columnfractions .20 .20 .20 .25
10391 @item Name @tab Argument @tab Return type @tab Standard
10392 @item @code{SQRT(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab Fortran 95 and later
10393 @item @code{DSQRT(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab Fortran 95 and later
10394 @item @code{CSQRT(X)} @tab @code{COMPLEX(4) X} @tab @code{COMPLEX(4)} @tab Fortran 95 and later
10395 @item @code{ZSQRT(X)} @tab @code{COMPLEX(8) X} @tab @code{COMPLEX(8)} @tab GNU extension
10396 @item @code{CDSQRT(X)} @tab @code{COMPLEX(8) X} @tab @code{COMPLEX(8)} @tab GNU extension
10403 @section @code{SRAND} --- Reinitialize the random number generator
10405 @cindex random number generation, seeding
10406 @cindex seeding a random number generator
10409 @item @emph{Description}:
10410 @code{SRAND} reinitializes the pseudo-random number generator
10411 called by @code{RAND} and @code{IRAND}. The new seed used by the
10412 generator is specified by the required argument @var{SEED}.
10414 @item @emph{Standard}:
10417 @item @emph{Class}:
10420 @item @emph{Syntax}:
10421 @code{CALL SRAND(SEED)}
10423 @item @emph{Arguments}:
10424 @multitable @columnfractions .15 .70
10425 @item @var{SEED} @tab Shall be a scalar @code{INTEGER(kind=4)}.
10428 @item @emph{Return value}:
10429 Does not return anything.
10431 @item @emph{Example}:
10432 See @code{RAND} and @code{IRAND} for examples.
10434 @item @emph{Notes}:
10435 The Fortran 2003 standard specifies the intrinsic @code{RANDOM_SEED} to
10436 initialize the pseudo-random numbers generator and @code{RANDOM_NUMBER}
10437 to generate pseudo-random numbers. Please note that in
10438 GNU Fortran, these two sets of intrinsics (@code{RAND},
10439 @code{IRAND} and @code{SRAND} on the one hand, @code{RANDOM_NUMBER} and
10440 @code{RANDOM_SEED} on the other hand) access two independent
10441 pseudo-random number generators.
10443 @item @emph{See also}:
10444 @ref{RAND}, @ref{RANDOM_SEED}, @ref{RANDOM_NUMBER}
10451 @section @code{STAT} --- Get file status
10453 @cindex file system, file status
10456 @item @emph{Description}:
10457 This function returns information about a file. No permissions are required on
10458 the file itself, but execute (search) permission is required on all of the
10459 directories in path that lead to the file.
10461 The elements that are obtained and stored in the array @code{VALUES}:
10462 @multitable @columnfractions .15 .70
10463 @item @code{VALUES(1)} @tab Device ID
10464 @item @code{VALUES(2)} @tab Inode number
10465 @item @code{VALUES(3)} @tab File mode
10466 @item @code{VALUES(4)} @tab Number of links
10467 @item @code{VALUES(5)} @tab Owner's uid
10468 @item @code{VALUES(6)} @tab Owner's gid
10469 @item @code{VALUES(7)} @tab ID of device containing directory entry for file (0 if not available)
10470 @item @code{VALUES(8)} @tab File size (bytes)
10471 @item @code{VALUES(9)} @tab Last access time
10472 @item @code{VALUES(10)} @tab Last modification time
10473 @item @code{VALUES(11)} @tab Last file status change time
10474 @item @code{VALUES(12)} @tab Preferred I/O block size (-1 if not available)
10475 @item @code{VALUES(13)} @tab Number of blocks allocated (-1 if not available)
10478 Not all these elements are relevant on all systems.
10479 If an element is not relevant, it is returned as 0.
10481 This intrinsic is provided in both subroutine and function forms; however,
10482 only one form can be used in any given program unit.
10484 @item @emph{Standard}:
10487 @item @emph{Class}:
10488 Subroutine, function
10490 @item @emph{Syntax}:
10491 @code{CALL STAT(NAME, VALUES [, STATUS])}
10493 @item @emph{Arguments}:
10494 @multitable @columnfractions .15 .70
10495 @item @var{NAME} @tab The type shall be @code{CHARACTER}, of the
10496 default kind and a valid path within the file system.
10497 @item @var{VALUES} @tab The type shall be @code{INTEGER(4), DIMENSION(13)}.
10498 @item @var{STATUS} @tab (Optional) status flag of type @code{INTEGER(4)}. Returns 0
10499 on success and a system specific error code otherwise.
10502 @item @emph{Example}:
10505 INTEGER, DIMENSION(13) :: buff
10508 CALL STAT("/etc/passwd", buff, status)
10510 IF (status == 0) THEN
10511 WRITE (*, FMT="('Device ID:', T30, I19)") buff(1)
10512 WRITE (*, FMT="('Inode number:', T30, I19)") buff(2)
10513 WRITE (*, FMT="('File mode (octal):', T30, O19)") buff(3)
10514 WRITE (*, FMT="('Number of links:', T30, I19)") buff(4)
10515 WRITE (*, FMT="('Owner''s uid:', T30, I19)") buff(5)
10516 WRITE (*, FMT="('Owner''s gid:', T30, I19)") buff(6)
10517 WRITE (*, FMT="('Device where located:', T30, I19)") buff(7)
10518 WRITE (*, FMT="('File size:', T30, I19)") buff(8)
10519 WRITE (*, FMT="('Last access time:', T30, A19)") CTIME(buff(9))
10520 WRITE (*, FMT="('Last modification time', T30, A19)") CTIME(buff(10))
10521 WRITE (*, FMT="('Last status change time:', T30, A19)") CTIME(buff(11))
10522 WRITE (*, FMT="('Preferred block size:', T30, I19)") buff(12)
10523 WRITE (*, FMT="('No. of blocks allocated:', T30, I19)") buff(13)
10528 @item @emph{See also}:
10529 To stat an open file: @ref{FSTAT}, to stat a link: @ref{LSTAT}
10535 @section @code{SUM} --- Sum of array elements
10538 @cindex array, add elements
10539 @cindex array, conditionally add elements
10540 @cindex sum array elements
10543 @item @emph{Description}:
10544 Adds the elements of @var{ARRAY} along dimension @var{DIM} if
10545 the corresponding element in @var{MASK} is @code{TRUE}.
10547 @item @emph{Standard}:
10548 Fortran 95 and later
10550 @item @emph{Class}:
10551 Transformational function
10553 @item @emph{Syntax}:
10554 @multitable @columnfractions .80
10555 @item @code{RESULT = SUM(ARRAY[, MASK])}
10556 @item @code{RESULT = SUM(ARRAY, DIM[, MASK])}
10559 @item @emph{Arguments}:
10560 @multitable @columnfractions .15 .70
10561 @item @var{ARRAY} @tab Shall be an array of type @code{INTEGER},
10562 @code{REAL} or @code{COMPLEX}.
10563 @item @var{DIM} @tab (Optional) shall be a scalar of type
10564 @code{INTEGER} with a value in the range from 1 to n, where n
10565 equals the rank of @var{ARRAY}.
10566 @item @var{MASK} @tab (Optional) shall be of type @code{LOGICAL}
10567 and either be a scalar or an array of the same shape as @var{ARRAY}.
10570 @item @emph{Return value}:
10571 The result is of the same type as @var{ARRAY}.
10573 If @var{DIM} is absent, a scalar with the sum of all elements in @var{ARRAY}
10574 is returned. Otherwise, an array of rank n-1, where n equals the rank of
10575 @var{ARRAY},and a shape similar to that of @var{ARRAY} with dimension @var{DIM}
10576 dropped is returned.
10578 @item @emph{Example}:
10581 INTEGER :: x(5) = (/ 1, 2, 3, 4 ,5 /)
10582 print *, SUM(x) ! all elements, sum = 15
10583 print *, SUM(x, MASK=MOD(x, 2)==1) ! odd elements, sum = 9
10587 @item @emph{See also}:
10594 @section @code{SYMLNK} --- Create a symbolic link
10596 @cindex file system, create link
10597 @cindex file system, soft link
10600 @item @emph{Description}:
10601 Makes a symbolic link from file @var{PATH1} to @var{PATH2}. A null
10602 character (@code{CHAR(0)}) can be used to mark the end of the names in
10603 @var{PATH1} and @var{PATH2}; otherwise, trailing blanks in the file
10604 names are ignored. If the @var{STATUS} argument is supplied, it
10605 contains 0 on success or a nonzero error code upon return; see
10606 @code{symlink(2)}. If the system does not supply @code{symlink(2)},
10607 @code{ENOSYS} is returned.
10609 This intrinsic is provided in both subroutine and function forms;
10610 however, only one form can be used in any given program unit.
10612 @item @emph{Standard}:
10615 @item @emph{Class}:
10616 Subroutine, function
10618 @item @emph{Syntax}:
10619 @multitable @columnfractions .80
10620 @item @code{CALL SYMLNK(PATH1, PATH2 [, STATUS])}
10621 @item @code{STATUS = SYMLNK(PATH1, PATH2)}
10624 @item @emph{Arguments}:
10625 @multitable @columnfractions .15 .70
10626 @item @var{PATH1} @tab Shall be of default @code{CHARACTER} type.
10627 @item @var{PATH2} @tab Shall be of default @code{CHARACTER} type.
10628 @item @var{STATUS} @tab (Optional) Shall be of default @code{INTEGER} type.
10631 @item @emph{See also}:
10632 @ref{LINK}, @ref{UNLINK}
10639 @section @code{SYSTEM} --- Execute a shell command
10641 @cindex system, system call
10644 @item @emph{Description}:
10645 Passes the command @var{COMMAND} to a shell (see @code{system(3)}). If
10646 argument @var{STATUS} is present, it contains the value returned by
10647 @code{system(3)}, which is presumably 0 if the shell command succeeded.
10648 Note that which shell is used to invoke the command is system-dependent
10649 and environment-dependent.
10651 This intrinsic is provided in both subroutine and function forms;
10652 however, only one form can be used in any given program unit.
10654 @item @emph{Standard}:
10657 @item @emph{Class}:
10658 Subroutine, function
10660 @item @emph{Syntax}:
10661 @multitable @columnfractions .80
10662 @item @code{CALL SYSTEM(COMMAND [, STATUS])}
10663 @item @code{STATUS = SYSTEM(COMMAND)}
10666 @item @emph{Arguments}:
10667 @multitable @columnfractions .15 .70
10668 @item @var{COMMAND} @tab Shall be of default @code{CHARACTER} type.
10669 @item @var{STATUS} @tab (Optional) Shall be of default @code{INTEGER} type.
10672 @item @emph{See also}:
10678 @section @code{SYSTEM_CLOCK} --- Time function
10679 @fnindex SYSTEM_CLOCK
10680 @cindex time, clock ticks
10681 @cindex clock ticks
10684 @item @emph{Description}:
10685 Determines the @var{COUNT} of milliseconds of wall clock time since
10686 the Epoch (00:00:00 UTC, January 1, 1970) modulo @var{COUNT_MAX},
10687 @var{COUNT_RATE} determines the number of clock ticks per second.
10688 @var{COUNT_RATE} and @var{COUNT_MAX} are constant and specific to
10689 @command{gfortran}.
10691 If there is no clock, @var{COUNT} is set to @code{-HUGE(COUNT)}, and
10692 @var{COUNT_RATE} and @var{COUNT_MAX} are set to zero
10694 @item @emph{Standard}:
10695 Fortran 95 and later
10697 @item @emph{Class}:
10700 @item @emph{Syntax}:
10701 @code{CALL SYSTEM_CLOCK([COUNT, COUNT_RATE, COUNT_MAX])}
10703 @item @emph{Arguments}:
10704 @item @emph{Arguments}:
10705 @multitable @columnfractions .15 .70
10706 @item @var{COUNT} @tab (Optional) shall be a scalar of type default
10707 @code{INTEGER} with @code{INTENT(OUT)}.
10708 @item @var{COUNT_RATE} @tab (Optional) shall be a scalar of type default
10709 @code{INTEGER} with @code{INTENT(OUT)}.
10710 @item @var{COUNT_MAX} @tab (Optional) shall be a scalar of type default
10711 @code{INTEGER} with @code{INTENT(OUT)}.
10714 @item @emph{Example}:
10716 PROGRAM test_system_clock
10717 INTEGER :: count, count_rate, count_max
10718 CALL SYSTEM_CLOCK(count, count_rate, count_max)
10719 WRITE(*,*) count, count_rate, count_max
10723 @item @emph{See also}:
10724 @ref{DATE_AND_TIME}, @ref{CPU_TIME}
10730 @section @code{TAN} --- Tangent function
10733 @cindex trigonometric function, tangent
10737 @item @emph{Description}:
10738 @code{TAN(X)} computes the tangent of @var{X}.
10740 @item @emph{Standard}:
10741 Fortran 77 and later, for a complex argument Fortran 2008 or later
10743 @item @emph{Class}:
10746 @item @emph{Syntax}:
10747 @code{RESULT = TAN(X)}
10749 @item @emph{Arguments}:
10750 @multitable @columnfractions .15 .70
10751 @item @var{X} @tab The type shall be @code{REAL} or @code{COMPLEX}.
10754 @item @emph{Return value}:
10755 The return value has same type and kind as @var{X}.
10757 @item @emph{Example}:
10760 real(8) :: x = 0.165_8
10762 end program test_tan
10765 @item @emph{Specific names}:
10766 @multitable @columnfractions .20 .20 .20 .25
10767 @item Name @tab Argument @tab Return type @tab Standard
10768 @item @code{TAN(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab Fortran 95 and later
10769 @item @code{DTAN(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab Fortran 95 and later
10772 @item @emph{See also}:
10779 @section @code{TANH} --- Hyperbolic tangent function
10782 @cindex hyperbolic tangent
10783 @cindex hyperbolic function, tangent
10784 @cindex tangent, hyperbolic
10787 @item @emph{Description}:
10788 @code{TANH(X)} computes the hyperbolic tangent of @var{X}.
10790 @item @emph{Standard}:
10791 Fortran 77 and later, for a complex argument Fortran 2008 or later
10793 @item @emph{Class}:
10796 @item @emph{Syntax}:
10799 @item @emph{Arguments}:
10800 @multitable @columnfractions .15 .70
10801 @item @var{X} @tab The type shall be @code{REAL} or @code{COMPLEX}.
10804 @item @emph{Return value}:
10805 The return value has same type and kind as @var{X}. If @var{X} is
10806 complex, the imaginary part of the result is in radians. If @var{X}
10807 is @code{REAL}, the return value lies in the range
10808 @math{ - 1 \leq tanh(x) \leq 1 }.
10810 @item @emph{Example}:
10813 real(8) :: x = 2.1_8
10815 end program test_tanh
10818 @item @emph{Specific names}:
10819 @multitable @columnfractions .20 .20 .20 .25
10820 @item Name @tab Argument @tab Return type @tab Standard
10821 @item @code{TANH(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab Fortran 95 and later
10822 @item @code{DTANH(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab Fortran 95 and later
10825 @item @emph{See also}:
10832 @section @code{THIS_IMAGE} --- Function that returns the cosubscript index of this image
10833 @fnindex THIS_IMAGE
10834 @cindex coarray, THIS_IMAGE
10835 @cindex images, index of this image
10838 @item @emph{Description}:
10839 Returns the cosubscript for this image.
10841 @item @emph{Standard}:
10842 Fortran 2008 and later
10844 @item @emph{Class}:
10845 Transformational function
10847 @item @emph{Syntax}:
10848 @multitable @columnfractions .80
10849 @item @code{RESULT = THIS_IMAGE()}
10850 @item @code{RESULT = THIS_IMAGE(COARRAY [, DIM])}
10853 @item @emph{Arguments}:
10854 @multitable @columnfractions .15 .70
10855 @item @var{COARRAY} @tab Coarray of any type (optional; if @var{DIM}
10856 present, required).
10857 @item @var{DIM} @tab default integer scalar (optional). If present,
10858 @var{DIM} shall be between one and the corank of @var{COARRAY}.
10862 @item @emph{Return value}:
10863 Default integer. If @var{COARRAY} is not present, it is scalar and its value
10864 is the index of the invoking image. Otherwise, if @var{DIM} is not present,
10865 a rank-1 array with corank elements is returned, containing the cosubscripts
10866 for @var{COARRAY} specifying the invoking image. If @var{DIM} is present,
10867 a scalar is returned, with the value of the @var{DIM} element of
10868 @code{THIS_IMAGE(COARRAY)}.
10870 @item @emph{Example}:
10872 INTEGER :: value[*]
10874 value = THIS_IMAGE()
10876 IF (THIS_IMAGE() == 1) THEN
10877 DO i = 1, NUM_IMAGES()
10878 WRITE(*,'(2(a,i0))') 'value[', i, '] is ', value[i]
10883 @item @emph{See also}:
10884 @ref{NUM_IMAGES}, @ref{IMAGE_INDEX}
10890 @section @code{TIME} --- Time function
10892 @cindex time, current
10893 @cindex current time
10896 @item @emph{Description}:
10897 Returns the current time encoded as an integer (in the manner of the
10898 UNIX function @code{time(3)}). This value is suitable for passing to
10899 @code{CTIME()}, @code{GMTIME()}, and @code{LTIME()}.
10901 This intrinsic is not fully portable, such as to systems with 32-bit
10902 @code{INTEGER} types but supporting times wider than 32 bits. Therefore,
10903 the values returned by this intrinsic might be, or become, negative, or
10904 numerically less than previous values, during a single run of the
10907 See @ref{TIME8}, for information on a similar intrinsic that might be
10908 portable to more GNU Fortran implementations, though to fewer Fortran
10911 @item @emph{Standard}:
10914 @item @emph{Class}:
10917 @item @emph{Syntax}:
10918 @code{RESULT = TIME()}
10920 @item @emph{Return value}:
10921 The return value is a scalar of type @code{INTEGER(4)}.
10923 @item @emph{See also}:
10924 @ref{CTIME}, @ref{GMTIME}, @ref{LTIME}, @ref{MCLOCK}, @ref{TIME8}
10931 @section @code{TIME8} --- Time function (64-bit)
10933 @cindex time, current
10934 @cindex current time
10937 @item @emph{Description}:
10938 Returns the current time encoded as an integer (in the manner of the
10939 UNIX function @code{time(3)}). This value is suitable for passing to
10940 @code{CTIME()}, @code{GMTIME()}, and @code{LTIME()}.
10942 @emph{Warning:} this intrinsic does not increase the range of the timing
10943 values over that returned by @code{time(3)}. On a system with a 32-bit
10944 @code{time(3)}, @code{TIME8()} will return a 32-bit value, even though
10945 it is converted to a 64-bit @code{INTEGER(8)} value. That means
10946 overflows of the 32-bit value can still occur. Therefore, the values
10947 returned by this intrinsic might be or become negative or numerically
10948 less than previous values during a single run of the compiled program.
10950 @item @emph{Standard}:
10953 @item @emph{Class}:
10956 @item @emph{Syntax}:
10957 @code{RESULT = TIME8()}
10959 @item @emph{Return value}:
10960 The return value is a scalar of type @code{INTEGER(8)}.
10962 @item @emph{See also}:
10963 @ref{CTIME}, @ref{GMTIME}, @ref{LTIME}, @ref{MCLOCK8}, @ref{TIME}
10970 @section @code{TINY} --- Smallest positive number of a real kind
10972 @cindex limits, smallest number
10973 @cindex model representation, smallest number
10976 @item @emph{Description}:
10977 @code{TINY(X)} returns the smallest positive (non zero) number
10978 in the model of the type of @code{X}.
10980 @item @emph{Standard}:
10981 Fortran 95 and later
10983 @item @emph{Class}:
10986 @item @emph{Syntax}:
10987 @code{RESULT = TINY(X)}
10989 @item @emph{Arguments}:
10990 @multitable @columnfractions .15 .70
10991 @item @var{X} @tab Shall be of type @code{REAL}.
10994 @item @emph{Return value}:
10995 The return value is of the same type and kind as @var{X}
10997 @item @emph{Example}:
10998 See @code{HUGE} for an example.
11004 @section @code{TRAILZ} --- Number of trailing zero bits of an integer
11009 @item @emph{Description}:
11010 @code{TRAILZ} returns the number of trailing zero bits of an integer.
11012 @item @emph{Standard}:
11013 Fortran 2008 and later
11015 @item @emph{Class}:
11018 @item @emph{Syntax}:
11019 @code{RESULT = TRAILZ(I)}
11021 @item @emph{Arguments}:
11022 @multitable @columnfractions .15 .70
11023 @item @var{I} @tab Shall be of type @code{INTEGER}.
11026 @item @emph{Return value}:
11027 The type of the return value is the default @code{INTEGER}.
11028 If all the bits of @code{I} are zero, the result value is @code{BIT_SIZE(I)}.
11030 @item @emph{Example}:
11032 PROGRAM test_trailz
11033 WRITE (*,*) TRAILZ(8) ! prints 3
11037 @item @emph{See also}:
11038 @ref{BIT_SIZE}, @ref{LEADZ}
11044 @section @code{TRANSFER} --- Transfer bit patterns
11050 @item @emph{Description}:
11051 Interprets the bitwise representation of @var{SOURCE} in memory as if it
11052 is the representation of a variable or array of the same type and type
11053 parameters as @var{MOLD}.
11055 This is approximately equivalent to the C concept of @emph{casting} one
11058 @item @emph{Standard}:
11059 Fortran 95 and later
11061 @item @emph{Class}:
11062 Transformational function
11064 @item @emph{Syntax}:
11065 @code{RESULT = TRANSFER(SOURCE, MOLD[, SIZE])}
11067 @item @emph{Arguments}:
11068 @multitable @columnfractions .15 .70
11069 @item @var{SOURCE} @tab Shall be a scalar or an array of any type.
11070 @item @var{MOLD} @tab Shall be a scalar or an array of any type.
11071 @item @var{SIZE} @tab (Optional) shall be a scalar of type
11075 @item @emph{Return value}:
11076 The result has the same type as @var{MOLD}, with the bit level
11077 representation of @var{SOURCE}. If @var{SIZE} is present, the result is
11078 a one-dimensional array of length @var{SIZE}. If @var{SIZE} is absent
11079 but @var{MOLD} is an array (of any size or shape), the result is a one-
11080 dimensional array of the minimum length needed to contain the entirety
11081 of the bitwise representation of @var{SOURCE}. If @var{SIZE} is absent
11082 and @var{MOLD} is a scalar, the result is a scalar.
11084 If the bitwise representation of the result is longer than that of
11085 @var{SOURCE}, then the leading bits of the result correspond to those of
11086 @var{SOURCE} and any trailing bits are filled arbitrarily.
11088 When the resulting bit representation does not correspond to a valid
11089 representation of a variable of the same type as @var{MOLD}, the results
11090 are undefined, and subsequent operations on the result cannot be
11091 guaranteed to produce sensible behavior. For example, it is possible to
11092 create @code{LOGICAL} variables for which @code{@var{VAR}} and
11093 @code{.NOT.@var{VAR}} both appear to be true.
11095 @item @emph{Example}:
11097 PROGRAM test_transfer
11098 integer :: x = 2143289344
11099 print *, transfer(x, 1.0) ! prints "NaN" on i686
11107 @section @code{TRANSPOSE} --- Transpose an array of rank two
11109 @cindex array, transpose
11110 @cindex matrix, transpose
11114 @item @emph{Description}:
11115 Transpose an array of rank two. Element (i, j) of the result has the value
11116 @code{MATRIX(j, i)}, for all i, j.
11118 @item @emph{Standard}:
11119 Fortran 95 and later
11121 @item @emph{Class}:
11122 Transformational function
11124 @item @emph{Syntax}:
11125 @code{RESULT = TRANSPOSE(MATRIX)}
11127 @item @emph{Arguments}:
11128 @multitable @columnfractions .15 .70
11129 @item @var{MATRIX} @tab Shall be an array of any type and have a rank of two.
11132 @item @emph{Return value}:
11133 The result has the same type as @var{MATRIX}, and has shape
11134 @code{(/ m, n /)} if @var{MATRIX} has shape @code{(/ n, m /)}.
11140 @section @code{TRIM} --- Remove trailing blank characters of a string
11142 @cindex string, remove trailing whitespace
11145 @item @emph{Description}:
11146 Removes trailing blank characters of a string.
11148 @item @emph{Standard}:
11149 Fortran 95 and later
11151 @item @emph{Class}:
11152 Transformational function
11154 @item @emph{Syntax}:
11155 @code{RESULT = TRIM(STRING)}
11157 @item @emph{Arguments}:
11158 @multitable @columnfractions .15 .70
11159 @item @var{STRING} @tab Shall be a scalar of type @code{CHARACTER}.
11162 @item @emph{Return value}:
11163 A scalar of type @code{CHARACTER} which length is that of @var{STRING}
11164 less the number of trailing blanks.
11166 @item @emph{Example}:
11169 CHARACTER(len=10), PARAMETER :: s = "GFORTRAN "
11170 WRITE(*,*) LEN(s), LEN(TRIM(s)) ! "10 8", with/without trailing blanks
11174 @item @emph{See also}:
11175 @ref{ADJUSTL}, @ref{ADJUSTR}
11181 @section @code{TTYNAM} --- Get the name of a terminal device.
11183 @cindex system, terminal
11186 @item @emph{Description}:
11187 Get the name of a terminal device. For more information,
11188 see @code{ttyname(3)}.
11190 This intrinsic is provided in both subroutine and function forms;
11191 however, only one form can be used in any given program unit.
11193 @item @emph{Standard}:
11196 @item @emph{Class}:
11197 Subroutine, function
11199 @item @emph{Syntax}:
11200 @multitable @columnfractions .80
11201 @item @code{CALL TTYNAM(UNIT, NAME)}
11202 @item @code{NAME = TTYNAM(UNIT)}
11205 @item @emph{Arguments}:
11206 @multitable @columnfractions .15 .70
11207 @item @var{UNIT} @tab Shall be a scalar @code{INTEGER}.
11208 @item @var{NAME} @tab Shall be of type @code{CHARACTER}.
11211 @item @emph{Example}:
11213 PROGRAM test_ttynam
11216 IF (isatty(unit=unit)) write(*,*) ttynam(unit)
11221 @item @emph{See also}:
11228 @section @code{UBOUND} --- Upper dimension bounds of an array
11230 @cindex array, upper bound
11233 @item @emph{Description}:
11234 Returns the upper bounds of an array, or a single upper bound
11235 along the @var{DIM} dimension.
11236 @item @emph{Standard}:
11237 Fortran 95 and later, with @var{KIND} argument Fortran 2003 and later
11239 @item @emph{Class}:
11242 @item @emph{Syntax}:
11243 @code{RESULT = UBOUND(ARRAY [, DIM [, KIND]])}
11245 @item @emph{Arguments}:
11246 @multitable @columnfractions .15 .70
11247 @item @var{ARRAY} @tab Shall be an array, of any type.
11248 @item @var{DIM} @tab (Optional) Shall be a scalar @code{INTEGER}.
11249 @item @var{KIND}@tab (Optional) An @code{INTEGER} initialization
11250 expression indicating the kind parameter of the result.
11253 @item @emph{Return value}:
11254 The return value is of type @code{INTEGER} and of kind @var{KIND}. If
11255 @var{KIND} is absent, the return value is of default integer kind.
11256 If @var{DIM} is absent, the result is an array of the upper bounds of
11257 @var{ARRAY}. If @var{DIM} is present, the result is a scalar
11258 corresponding to the upper bound of the array along that dimension. If
11259 @var{ARRAY} is an expression rather than a whole array or array
11260 structure component, or if it has a zero extent along the relevant
11261 dimension, the upper bound is taken to be the number of elements along
11262 the relevant dimension.
11264 @item @emph{See also}:
11265 @ref{LBOUND}, @ref{LCOBOUND}
11271 @section @code{UCOBOUND} --- Upper codimension bounds of an array
11273 @cindex coarray, upper bound
11276 @item @emph{Description}:
11277 Returns the upper cobounds of a coarray, or a single upper cobound
11278 along the @var{DIM} codimension.
11279 @item @emph{Standard}:
11280 Fortran 2008 and later
11282 @item @emph{Class}:
11285 @item @emph{Syntax}:
11286 @code{RESULT = UCOBOUND(COARRAY [, DIM [, KIND]])}
11288 @item @emph{Arguments}:
11289 @multitable @columnfractions .15 .70
11290 @item @var{ARRAY} @tab Shall be an coarray, of any type.
11291 @item @var{DIM} @tab (Optional) Shall be a scalar @code{INTEGER}.
11292 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
11293 expression indicating the kind parameter of the result.
11296 @item @emph{Return value}:
11297 The return value is of type @code{INTEGER} and of kind @var{KIND}. If
11298 @var{KIND} is absent, the return value is of default integer kind.
11299 If @var{DIM} is absent, the result is an array of the lower cobounds of
11300 @var{COARRAY}. If @var{DIM} is present, the result is a scalar
11301 corresponding to the lower cobound of the array along that codimension.
11303 @item @emph{See also}:
11304 @ref{LCOBOUND}, @ref{LBOUND}
11310 @section @code{UMASK} --- Set the file creation mask
11312 @cindex file system, file creation mask
11315 @item @emph{Description}:
11316 Sets the file creation mask to @var{MASK}. If called as a function, it
11317 returns the old value. If called as a subroutine and argument @var{OLD}
11318 if it is supplied, it is set to the old value. See @code{umask(2)}.
11320 @item @emph{Standard}:
11323 @item @emph{Class}:
11324 Subroutine, function
11326 @item @emph{Syntax}:
11327 @code{CALL UMASK(MASK [, OLD])}
11328 @code{OLD = UMASK(MASK)}
11330 @item @emph{Arguments}:
11331 @multitable @columnfractions .15 .70
11332 @item @var{MASK} @tab Shall be a scalar of type @code{INTEGER}.
11333 @item @var{OLD} @tab (Optional) Shall be a scalar of type
11342 @section @code{UNLINK} --- Remove a file from the file system
11344 @cindex file system, remove file
11347 @item @emph{Description}:
11348 Unlinks the file @var{PATH}. A null character (@code{CHAR(0)}) can be
11349 used to mark the end of the name in @var{PATH}; otherwise, trailing
11350 blanks in the file name are ignored. If the @var{STATUS} argument is
11351 supplied, it contains 0 on success or a nonzero error code upon return;
11352 see @code{unlink(2)}.
11354 This intrinsic is provided in both subroutine and function forms;
11355 however, only one form can be used in any given program unit.
11357 @item @emph{Standard}:
11360 @item @emph{Class}:
11361 Subroutine, function
11363 @item @emph{Syntax}:
11364 @multitable @columnfractions .80
11365 @item @code{CALL UNLINK(PATH [, STATUS])}
11366 @item @code{STATUS = UNLINK(PATH)}
11369 @item @emph{Arguments}:
11370 @multitable @columnfractions .15 .70
11371 @item @var{PATH} @tab Shall be of default @code{CHARACTER} type.
11372 @item @var{STATUS} @tab (Optional) Shall be of default @code{INTEGER} type.
11375 @item @emph{See also}:
11376 @ref{LINK}, @ref{SYMLNK}
11382 @section @code{UNPACK} --- Unpack an array of rank one into an array
11384 @cindex array, unpacking
11385 @cindex array, increase dimension
11386 @cindex array, scatter elements
11389 @item @emph{Description}:
11390 Store the elements of @var{VECTOR} in an array of higher rank.
11392 @item @emph{Standard}:
11393 Fortran 95 and later
11395 @item @emph{Class}:
11396 Transformational function
11398 @item @emph{Syntax}:
11399 @code{RESULT = UNPACK(VECTOR, MASK, FIELD)}
11401 @item @emph{Arguments}:
11402 @multitable @columnfractions .15 .70
11403 @item @var{VECTOR} @tab Shall be an array of any type and rank one. It
11404 shall have at least as many elements as @var{MASK} has @code{TRUE} values.
11405 @item @var{MASK} @tab Shall be an array of type @code{LOGICAL}.
11406 @item @var{FIELD} @tab Shall be of the same type as @var{VECTOR} and have
11407 the same shape as @var{MASK}.
11410 @item @emph{Return value}:
11411 The resulting array corresponds to @var{FIELD} with @code{TRUE} elements
11412 of @var{MASK} replaced by values from @var{VECTOR} in array element order.
11414 @item @emph{Example}:
11416 PROGRAM test_unpack
11417 integer :: vector(2) = (/1,1/)
11418 logical :: mask(4) = (/ .TRUE., .FALSE., .FALSE., .TRUE. /)
11419 integer :: field(2,2) = 0, unity(2,2)
11421 ! result: unity matrix
11422 unity = unpack(vector, reshape(mask, (/2,2/)), field)
11426 @item @emph{See also}:
11427 @ref{PACK}, @ref{SPREAD}
11433 @section @code{VERIFY} --- Scan a string for the absence of a set of characters
11435 @cindex string, find missing set
11438 @item @emph{Description}:
11439 Verifies that all the characters in a @var{SET} are present in a @var{STRING}.
11441 If @var{BACK} is either absent or equals @code{FALSE}, this function
11442 returns the position of the leftmost character of @var{STRING} that is
11443 not in @var{SET}. If @var{BACK} equals @code{TRUE}, the rightmost position
11444 is returned. If all characters of @var{SET} are found in @var{STRING}, the
11447 @item @emph{Standard}:
11448 Fortran 95 and later, with @var{KIND} argument Fortran 2003 and later
11450 @item @emph{Class}:
11453 @item @emph{Syntax}:
11454 @code{RESULT = VERIFY(STRING, SET[, BACK [, KIND]])}
11456 @item @emph{Arguments}:
11457 @multitable @columnfractions .15 .70
11458 @item @var{STRING} @tab Shall be of type @code{CHARACTER}.
11459 @item @var{SET} @tab Shall be of type @code{CHARACTER}.
11460 @item @var{BACK} @tab (Optional) shall be of type @code{LOGICAL}.
11461 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
11462 expression indicating the kind parameter of the result.
11465 @item @emph{Return value}:
11466 The return value is of type @code{INTEGER} and of kind @var{KIND}. If
11467 @var{KIND} is absent, the return value is of default integer kind.
11469 @item @emph{Example}:
11471 PROGRAM test_verify
11472 WRITE(*,*) VERIFY("FORTRAN", "AO") ! 1, found 'F'
11473 WRITE(*,*) VERIFY("FORTRAN", "FOO") ! 3, found 'R'
11474 WRITE(*,*) VERIFY("FORTRAN", "C++") ! 1, found 'F'
11475 WRITE(*,*) VERIFY("FORTRAN", "C++", .TRUE.) ! 7, found 'N'
11476 WRITE(*,*) VERIFY("FORTRAN", "FORTRAN") ! 0' found none
11480 @item @emph{See also}:
11481 @ref{SCAN}, @ref{INDEX intrinsic}
11487 @section @code{XOR} --- Bitwise logical exclusive OR
11489 @cindex bitwise logical exclusive or
11490 @cindex logical exclusive or, bitwise
11493 @item @emph{Description}:
11494 Bitwise logical exclusive or.
11496 This intrinsic routine is provided for backwards compatibility with
11497 GNU Fortran 77. For integer arguments, programmers should consider
11498 the use of the @ref{IEOR} intrinsic and for logical arguments the
11499 @code{.NEQV.} operator, which are both defined by the Fortran standard.
11501 @item @emph{Standard}:
11504 @item @emph{Class}:
11507 @item @emph{Syntax}:
11508 @code{RESULT = XOR(I, J)}
11510 @item @emph{Arguments}:
11511 @multitable @columnfractions .15 .70
11512 @item @var{I} @tab The type shall be either a scalar @code{INTEGER}
11513 type or a scalar @code{LOGICAL} type.
11514 @item @var{J} @tab The type shall be the same as the type of @var{I}.
11517 @item @emph{Return value}:
11518 The return type is either a scalar @code{INTEGER} or a scalar
11519 @code{LOGICAL}. If the kind type parameters differ, then the
11520 smaller kind type is implicitly converted to larger kind, and the
11521 return has the larger kind.
11523 @item @emph{Example}:
11526 LOGICAL :: T = .TRUE., F = .FALSE.
11528 DATA a / Z'F' /, b / Z'3' /
11530 WRITE (*,*) XOR(T, T), XOR(T, F), XOR(F, T), XOR(F, F)
11531 WRITE (*,*) XOR(a, b)
11535 @item @emph{See also}:
11536 Fortran 95 elemental function: @ref{IEOR}
11541 @node Intrinsic Modules
11542 @chapter Intrinsic Modules
11543 @cindex intrinsic Modules
11546 * ISO_FORTRAN_ENV::
11548 * OpenMP Modules OMP_LIB and OMP_LIB_KINDS::
11551 @node ISO_FORTRAN_ENV
11552 @section @code{ISO_FORTRAN_ENV}
11554 @item @emph{Standard}:
11555 Fortran 2003 and later, except when otherwise noted
11558 The @code{ISO_FORTRAN_ENV} module provides the following scalar default-integer
11562 @item @code{ATOMIC_INT_KIND}:
11563 Default-kind integer constant to be used as kind parameter when defining
11564 integer variables used in atomic operations. (Fortran 2008 or later.)
11566 @item @code{ATOMIC_LOGICAL_KIND}:
11567 Default-kind integer constant to be used as kind parameter when defining
11568 logical variables used in atomic operations. (Fortran 2008 or later.)
11570 @item @code{CHARACTER_STORAGE_SIZE}:
11571 Size in bits of the character storage unit.
11573 @item @code{ERROR_UNIT}:
11574 Identifies the preconnected unit used for error reporting.
11576 @item @code{FILE_STORAGE_SIZE}:
11577 Size in bits of the file-storage unit.
11579 @item @code{INPUT_UNIT}:
11580 Identifies the preconnected unit identified by the asterisk
11581 (@code{*}) in @code{READ} statement.
11583 @item @code{INT8}, @code{INT16}, @code{INT32}, @code{INT64}:
11584 Kind type parameters to specify an INTEGER type with a storage
11585 size of 16, 32, and 64 bits. It is negative if a target platform
11586 does not support the particular kind. (Fortran 2008 or later.)
11588 @item @code{IOSTAT_END}:
11589 The value assigned to the variable passed to the IOSTAT= specifier of
11590 an input/output statement if an end-of-file condition occurred.
11592 @item @code{IOSTAT_EOR}:
11593 The value assigned to the variable passed to the IOSTAT= specifier of
11594 an input/output statement if an end-of-record condition occurred.
11596 @item @code{IOSTAT_INQUIRE_INTERNAL_UNIT}:
11597 Scalar default-integer constant, used by @code{INQUIRE} for the
11598 IOSTAT= specifier to denote an that a unit number identifies an
11599 internal unit. (Fortran 2008 or later.)
11601 @item @code{NUMERIC_STORAGE_SIZE}:
11602 The size in bits of the numeric storage unit.
11604 @item @code{OUTPUT_UNIT}:
11605 Identifies the preconnected unit identified by the asterisk
11606 (@code{*}) in @code{WRITE} statement.
11608 @item @code{REAL32}, @code{REAL64}, @code{REAL128}:
11609 Kind type parameters to specify a REAL type with a storage
11610 size of 32, 64, and 128 bits. It is negative if a target platform
11611 does not support the particular kind. (Fortran 2008 or later.)
11613 @item @code{STAT_LOCKED}:
11614 Scalar default-integer constant used as STAT= return value by @code{LOCK} to
11615 denote that the lock variable is locked by the executing image. (Fortran 2008
11618 @item @code{STAT_LOCKED_OTHER_IMAGE}:
11619 Scalar default-integer constant used as STAT= return value by @code{UNLOCK} to
11620 denote that the lock variable is locked by another image. (Fortran 2008 or
11623 @item @code{STAT_STOPPED_IMAGE}:
11624 Positive, scalar default-integer constant used as STAT= return value if the
11625 argument in the statement requires synchronisation with an image, which has
11626 initiated the termination of the execution. (Fortran 2008 or later.)
11628 @item @code{STAT_UNLOCKED}:
11629 Scalar default-integer constant used as STAT= return value by @code{UNLOCK} to
11630 denote that the lock variable is unlocked. (Fortran 2008 or later.)
11635 @node ISO_C_BINDING
11636 @section @code{ISO_C_BINDING}
11638 @item @emph{Standard}:
11639 Fortran 2003 and later, GNU extensions
11642 The following intrinsic procedures are provided by the module; their
11643 definition can be found in the section Intrinsic Procedures of this
11647 @item @code{C_ASSOCIATED}
11648 @item @code{C_F_POINTER}
11649 @item @code{C_F_PROCPOINTER}
11650 @item @code{C_FUNLOC}
11653 @c TODO: Vertical spacing between C_FUNLOC and C_LOC wrong in PDF,
11654 @c don't really know why.
11656 The @code{ISO_C_BINDING} module provides the following named constants of
11657 type default integer, which can be used as KIND type parameters.
11659 In addition to the integer named constants required by the Fortran 2003
11660 standard, GNU Fortran provides as an extension named constants for the
11661 128-bit integer types supported by the C compiler: @code{C_INT128_T,
11662 C_INT_LEAST128_T, C_INT_FAST128_T}.
11664 @multitable @columnfractions .15 .35 .35 .35
11665 @item Fortran Type @tab Named constant @tab C type @tab Extension
11666 @item @code{INTEGER}@tab @code{C_INT} @tab @code{int}
11667 @item @code{INTEGER}@tab @code{C_SHORT} @tab @code{short int}
11668 @item @code{INTEGER}@tab @code{C_LONG} @tab @code{long int}
11669 @item @code{INTEGER}@tab @code{C_LONG_LONG} @tab @code{long long int}
11670 @item @code{INTEGER}@tab @code{C_SIGNED_CHAR} @tab @code{signed char}/@code{unsigned char}
11671 @item @code{INTEGER}@tab @code{C_SIZE_T} @tab @code{size_t}
11672 @item @code{INTEGER}@tab @code{C_INT8_T} @tab @code{int8_t}
11673 @item @code{INTEGER}@tab @code{C_INT16_T} @tab @code{int16_t}
11674 @item @code{INTEGER}@tab @code{C_INT32_T} @tab @code{int32_t}
11675 @item @code{INTEGER}@tab @code{C_INT64_T} @tab @code{int64_t}
11676 @item @code{INTEGER}@tab @code{C_INT128_T} @tab @code{int128_t} @tab Ext.
11677 @item @code{INTEGER}@tab @code{C_INT_LEAST8_T} @tab @code{int_least8_t}
11678 @item @code{INTEGER}@tab @code{C_INT_LEAST16_T} @tab @code{int_least16_t}
11679 @item @code{INTEGER}@tab @code{C_INT_LEAST32_T} @tab @code{int_least32_t}
11680 @item @code{INTEGER}@tab @code{C_INT_LEAST64_T} @tab @code{int_least64_t}
11681 @item @code{INTEGER}@tab @code{C_INT_LEAST128_T}@tab @code{int_least128_t} @tab Ext.
11682 @item @code{INTEGER}@tab @code{C_INT_FAST8_T} @tab @code{int_fast8_t}
11683 @item @code{INTEGER}@tab @code{C_INT_FAST16_T} @tab @code{int_fast16_t}
11684 @item @code{INTEGER}@tab @code{C_INT_FAST32_T} @tab @code{int_fast32_t}
11685 @item @code{INTEGER}@tab @code{C_INT_FAST64_T} @tab @code{int_fast64_t}
11686 @item @code{INTEGER}@tab @code{C_INT_FAST128_T} @tab @code{int_fast128_t} @tab Ext.
11687 @item @code{INTEGER}@tab @code{C_INTMAX_T} @tab @code{intmax_t}
11688 @item @code{INTEGER}@tab @code{C_INTPTR_T} @tab @code{intptr_t}
11689 @item @code{REAL} @tab @code{C_FLOAT} @tab @code{float}
11690 @item @code{REAL} @tab @code{C_DOUBLE} @tab @code{double}
11691 @item @code{REAL} @tab @code{C_LONG_DOUBLE} @tab @code{long double}
11692 @item @code{COMPLEX}@tab @code{C_FLOAT_COMPLEX} @tab @code{float _Complex}
11693 @item @code{COMPLEX}@tab @code{C_DOUBLE_COMPLEX}@tab @code{double _Complex}
11694 @item @code{COMPLEX}@tab @code{C_LONG_DOUBLE_COMPLEX}@tab @code{long double _Complex}
11695 @item @code{LOGICAL}@tab @code{C_BOOL} @tab @code{_Bool}
11696 @item @code{CHARACTER}@tab @code{C_CHAR} @tab @code{char}
11699 Additionally, the following parameters of type @code{CHARACTER(KIND=C_CHAR)}
11702 @multitable @columnfractions .20 .45 .15
11703 @item Name @tab C definition @tab Value
11704 @item @code{C_NULL_CHAR} @tab null character @tab @code{'\0'}
11705 @item @code{C_ALERT} @tab alert @tab @code{'\a'}
11706 @item @code{C_BACKSPACE} @tab backspace @tab @code{'\b'}
11707 @item @code{C_FORM_FEED} @tab form feed @tab @code{'\f'}
11708 @item @code{C_NEW_LINE} @tab new line @tab @code{'\n'}
11709 @item @code{C_CARRIAGE_RETURN} @tab carriage return @tab @code{'\r'}
11710 @item @code{C_HORIZONTAL_TAB} @tab horizontal tab @tab @code{'\t'}
11711 @item @code{C_VERTICAL_TAB} @tab vertical tab @tab @code{'\v'}
11714 @node OpenMP Modules OMP_LIB and OMP_LIB_KINDS
11715 @section OpenMP Modules @code{OMP_LIB} and @code{OMP_LIB_KINDS}
11717 @item @emph{Standard}:
11718 OpenMP Application Program Interface v3.0
11722 The OpenMP Fortran runtime library routines are provided both in
11723 a form of two Fortran 90 modules, named @code{OMP_LIB} and
11724 @code{OMP_LIB_KINDS}, and in a form of a Fortran @code{include} file named
11725 @file{omp_lib.h}. The procedures provided by @code{OMP_LIB} can be found
11726 in the @ref{Top,,Introduction,libgomp,GNU OpenMP runtime library} manual,
11727 the named constants defined in the @code{OMP_LIB_KINDS} module are listed
11730 For details refer to the actual
11731 @uref{http://www.openmp.org/mp-documents/spec30.pdf,
11732 OpenMP Application Program Interface v3.0}.
11734 @code{OMP_LIB_KINDS} provides the following scalar default-integer
11738 @item @code{omp_integer_kind}
11739 @item @code{omp_logical_kind}
11740 @item @code{omp_lock_kind}
11741 @item @code{omp_nest_lock_kind}
11742 @item @code{omp_sched_kind}