2 Copyright (C) 2005, 2006, 2007, 2008
3 Free Software Foundation, Inc.
4 This is part of the GNU Fortran manual.
5 For copying conditions, see the file gfortran.texi.
7 Permission is granted to copy, distribute and/or modify this document
8 under the terms of the GNU Free Documentation License, Version 1.2 or
9 any later version published by the Free Software Foundation; with the
10 Invariant Sections being ``Funding Free Software'', the Front-Cover
11 Texts being (a) (see below), and with the Back-Cover Texts being (b)
12 (see below). A copy of the license is included in the gfdl(7) man page.
15 Some basic guidelines for editing this document:
17 (1) The intrinsic procedures are to be listed in alphabetical order.
18 (2) The generic name is to be used.
19 (3) The specific names are included in the function index and in a
20 table at the end of the node (See ABS entry).
21 (4) Try to maintain the same style for each entry.
27 \gdef\acos{\mathop{\rm acos}\nolimits}
28 \gdef\asin{\mathop{\rm asin}\nolimits}
29 \gdef\atan{\mathop{\rm atan}\nolimits}
30 \gdef\acosh{\mathop{\rm acosh}\nolimits}
31 \gdef\asinh{\mathop{\rm asinh}\nolimits}
32 \gdef\atanh{\mathop{\rm atanh}\nolimits}
36 @node Intrinsic Procedures
37 @chapter Intrinsic Procedures
38 @cindex intrinsic procedures
41 * Introduction: Introduction to Intrinsics
42 * @code{ABORT}: ABORT, Abort the program
43 * @code{ABS}: ABS, Absolute value
44 * @code{ACCESS}: ACCESS, Checks file access modes
45 * @code{ACHAR}: ACHAR, Character in @acronym{ASCII} collating sequence
46 * @code{ACOS}: ACOS, Arccosine function
47 * @code{ACOSH}: ACOSH, Hyperbolic arccosine function
48 * @code{ADJUSTL}: ADJUSTL, Left adjust a string
49 * @code{ADJUSTR}: ADJUSTR, Right adjust a string
50 * @code{AIMAG}: AIMAG, Imaginary part of complex number
51 * @code{AINT}: AINT, Truncate to a whole number
52 * @code{ALARM}: ALARM, Set an alarm clock
53 * @code{ALL}: ALL, Determine if all values are true
54 * @code{ALLOCATED}: ALLOCATED, Status of allocatable entity
55 * @code{AND}: AND, Bitwise logical AND
56 * @code{ANINT}: ANINT, Nearest whole number
57 * @code{ANY}: ANY, Determine if any values are true
58 * @code{ASIN}: ASIN, Arcsine function
59 * @code{ASINH}: ASINH, Hyperbolic arcsine function
60 * @code{ASSOCIATED}: ASSOCIATED, Status of a pointer or pointer/target pair
61 * @code{ATAN}: ATAN, Arctangent function
62 * @code{ATAN2}: ATAN2, Arctangent function
63 * @code{ATANH}: ATANH, Hyperbolic arctangent function
64 * @code{BESSEL_J0}: BESSEL_J0, Bessel function of the first kind of order 0
65 * @code{BESSEL_J1}: BESSEL_J1, Bessel function of the first kind of order 1
66 * @code{BESSEL_JN}: BESSEL_JN, Bessel function of the first kind
67 * @code{BESSEL_Y0}: BESSEL_Y0, Bessel function of the second kind of order 0
68 * @code{BESSEL_Y1}: BESSEL_Y1, Bessel function of the second kind of order 1
69 * @code{BESSEL_YN}: BESSEL_YN, Bessel function of the second kind
70 * @code{BIT_SIZE}: BIT_SIZE, Bit size inquiry function
71 * @code{BTEST}: BTEST, Bit test function
72 * @code{C_ASSOCIATED}: C_ASSOCIATED, Status of a C pointer
73 * @code{C_F_POINTER}: C_F_POINTER, Convert C into Fortran pointer
74 * @code{C_F_PROCPOINTER}: C_F_PROCPOINTER, Convert C into Fortran procedure pointer
75 * @code{C_FUNLOC}: C_FUNLOC, Obtain the C address of a procedure
76 * @code{C_LOC}: C_LOC, Obtain the C address of an object
77 * @code{C_SIZEOF}: C_SIZEOF, Size in bytes of an expression
78 * @code{CEILING}: CEILING, Integer ceiling function
79 * @code{CHAR}: CHAR, Integer-to-character conversion function
80 * @code{CHDIR}: CHDIR, Change working directory
81 * @code{CHMOD}: CHMOD, Change access permissions of files
82 * @code{CMPLX}: CMPLX, Complex conversion function
83 * @code{COMMAND_ARGUMENT_COUNT}: COMMAND_ARGUMENT_COUNT, Get number of command line arguments
84 * @code{COMPLEX}: COMPLEX, Complex conversion function
85 * @code{CONJG}: CONJG, Complex conjugate function
86 * @code{COS}: COS, Cosine function
87 * @code{COSH}: COSH, Hyperbolic cosine function
88 * @code{COUNT}: COUNT, Count occurrences of TRUE in an array
89 * @code{CPU_TIME}: CPU_TIME, CPU time subroutine
90 * @code{CSHIFT}: CSHIFT, Circular shift elements of an array
91 * @code{CTIME}: CTIME, Subroutine (or function) to convert a time into a string
92 * @code{DATE_AND_TIME}: DATE_AND_TIME, Date and time subroutine
93 * @code{DBLE}: DBLE, Double precision conversion function
94 * @code{DCMPLX}: DCMPLX, Double complex conversion function
95 * @code{DFLOAT}: DFLOAT, Double precision conversion function
96 * @code{DIGITS}: DIGITS, Significant digits function
97 * @code{DIM}: DIM, Positive difference
98 * @code{DOT_PRODUCT}: DOT_PRODUCT, Dot product function
99 * @code{DPROD}: DPROD, Double product function
100 * @code{DREAL}: DREAL, Double real part function
101 * @code{DTIME}: DTIME, Execution time subroutine (or function)
102 * @code{EOSHIFT}: EOSHIFT, End-off shift elements of an array
103 * @code{EPSILON}: EPSILON, Epsilon function
104 * @code{ERF}: ERF, Error function
105 * @code{ERFC}: ERFC, Complementary error function
106 * @code{ERFC_SCALED}: ERFC_SCALED, Exponentially-scaled complementary error function
107 * @code{ETIME}: ETIME, Execution time subroutine (or function)
108 * @code{EXIT}: EXIT, Exit the program with status.
109 * @code{EXP}: EXP, Exponential function
110 * @code{EXPONENT}: EXPONENT, Exponent function
111 * @code{FDATE}: FDATE, Subroutine (or function) to get the current time as a string
112 * @code{FGET}: FGET, Read a single character in stream mode from stdin
113 * @code{FGETC}: FGETC, Read a single character in stream mode
114 * @code{FLOAT}: FLOAT, Convert integer to default real
115 * @code{FLOOR}: FLOOR, Integer floor function
116 * @code{FLUSH}: FLUSH, Flush I/O unit(s)
117 * @code{FNUM}: FNUM, File number function
118 * @code{FPUT}: FPUT, Write a single character in stream mode to stdout
119 * @code{FPUTC}: FPUTC, Write a single character in stream mode
120 * @code{FRACTION}: FRACTION, Fractional part of the model representation
121 * @code{FREE}: FREE, Memory de-allocation subroutine
122 * @code{FSEEK}: FSEEK, Low level file positioning subroutine
123 * @code{FSTAT}: FSTAT, Get file status
124 * @code{FTELL}: FTELL, Current stream position
125 * @code{GAMMA}: GAMMA, Gamma function
126 * @code{GERROR}: GERROR, Get last system error message
127 * @code{GETARG}: GETARG, Get command line arguments
128 * @code{GET_COMMAND}: GET_COMMAND, Get the entire command line
129 * @code{GET_COMMAND_ARGUMENT}: GET_COMMAND_ARGUMENT, Get command line arguments
130 * @code{GETCWD}: GETCWD, Get current working directory
131 * @code{GETENV}: GETENV, Get an environmental variable
132 * @code{GET_ENVIRONMENT_VARIABLE}: GET_ENVIRONMENT_VARIABLE, Get an environmental variable
133 * @code{GETGID}: GETGID, Group ID function
134 * @code{GETLOG}: GETLOG, Get login name
135 * @code{GETPID}: GETPID, Process ID function
136 * @code{GETUID}: GETUID, User ID function
137 * @code{GMTIME}: GMTIME, Convert time to GMT info
138 * @code{HOSTNM}: HOSTNM, Get system host name
139 * @code{HUGE}: HUGE, Largest number of a kind
140 * @code{HYPOT}: HYPOT, Euclidian distance function
141 * @code{IACHAR}: IACHAR, Code in @acronym{ASCII} collating sequence
142 * @code{IAND}: IAND, Bitwise logical and
143 * @code{IARGC}: IARGC, Get the number of command line arguments
144 * @code{IBCLR}: IBCLR, Clear bit
145 * @code{IBITS}: IBITS, Bit extraction
146 * @code{IBSET}: IBSET, Set bit
147 * @code{ICHAR}: ICHAR, Character-to-integer conversion function
148 * @code{IDATE}: IDATE, Current local time (day/month/year)
149 * @code{IEOR}: IEOR, Bitwise logical exclusive or
150 * @code{IERRNO}: IERRNO, Function to get the last system error number
151 * @code{INDEX}: INDEX intrinsic, Position of a substring within a string
152 * @code{INT}: INT, Convert to integer type
153 * @code{INT2}: INT2, Convert to 16-bit integer type
154 * @code{INT8}: INT8, Convert to 64-bit integer type
155 * @code{IOR}: IOR, Bitwise logical or
156 * @code{IRAND}: IRAND, Integer pseudo-random number
157 * @code{IS_IOSTAT_END}: IS_IOSTAT_END, Test for end-of-file value
158 * @code{IS_IOSTAT_EOR}: IS_IOSTAT_EOR, Test for end-of-record value
159 * @code{ISATTY}: ISATTY, Whether a unit is a terminal device
160 * @code{ISHFT}: ISHFT, Shift bits
161 * @code{ISHFTC}: ISHFTC, Shift bits circularly
162 * @code{ISNAN}: ISNAN, Tests for a NaN
163 * @code{ITIME}: ITIME, Current local time (hour/minutes/seconds)
164 * @code{KILL}: KILL, Send a signal to a process
165 * @code{KIND}: KIND, Kind of an entity
166 * @code{LBOUND}: LBOUND, Lower dimension bounds of an array
167 * @code{LEADZ}: LEADZ, Number of leading zero bits of an integer
168 * @code{LEN}: LEN, Length of a character entity
169 * @code{LEN_TRIM}: LEN_TRIM, Length of a character entity without trailing blank characters
170 * @code{LOG_GAMMA}: LOG_GAMMA, Logarithm of the Gamma function
171 * @code{LGE}: LGE, Lexical greater than or equal
172 * @code{LGT}: LGT, Lexical greater than
173 * @code{LINK}: LINK, Create a hard link
174 * @code{LLE}: LLE, Lexical less than or equal
175 * @code{LLT}: LLT, Lexical less than
176 * @code{LNBLNK}: LNBLNK, Index of the last non-blank character in a string
177 * @code{LOC}: LOC, Returns the address of a variable
178 * @code{LOG}: LOG, Logarithm function
179 * @code{LOG10}: LOG10, Base 10 logarithm function
180 * @code{LOGICAL}: LOGICAL, Convert to logical type
181 * @code{LONG}: LONG, Convert to integer type
182 * @code{LSHIFT}: LSHIFT, Left shift bits
183 * @code{LSTAT}: LSTAT, Get file status
184 * @code{LTIME}: LTIME, Convert time to local time info
185 * @code{MALLOC}: MALLOC, Dynamic memory allocation function
186 * @code{MATMUL}: MATMUL, matrix multiplication
187 * @code{MAX}: MAX, Maximum value of an argument list
188 * @code{MAXEXPONENT}: MAXEXPONENT, Maximum exponent of a real kind
189 * @code{MAXLOC}: MAXLOC, Location of the maximum value within an array
190 * @code{MAXVAL}: MAXVAL, Maximum value of an array
191 * @code{MCLOCK}: MCLOCK, Time function
192 * @code{MCLOCK8}: MCLOCK8, Time function (64-bit)
193 * @code{MERGE}: MERGE, Merge arrays
194 * @code{MIN}: MIN, Minimum value of an argument list
195 * @code{MINEXPONENT}: MINEXPONENT, Minimum exponent of a real kind
196 * @code{MINLOC}: MINLOC, Location of the minimum value within an array
197 * @code{MINVAL}: MINVAL, Minimum value of an array
198 * @code{MOD}: MOD, Remainder function
199 * @code{MODULO}: MODULO, Modulo function
200 * @code{MOVE_ALLOC}: MOVE_ALLOC, Move allocation from one object to another
201 * @code{MVBITS}: MVBITS, Move bits from one integer to another
202 * @code{NEAREST}: NEAREST, Nearest representable number
203 * @code{NEW_LINE}: NEW_LINE, New line character
204 * @code{NINT}: NINT, Nearest whole number
205 * @code{NOT}: NOT, Logical negation
206 * @code{NULL}: NULL, Function that returns an disassociated pointer
207 * @code{OR}: OR, Bitwise logical OR
208 * @code{PACK}: PACK, Pack an array into an array of rank one
209 * @code{PERROR}: PERROR, Print system error message
210 * @code{PRECISION}: PRECISION, Decimal precision of a real kind
211 * @code{PRESENT}: PRESENT, Determine whether an optional dummy argument is specified
212 * @code{PRODUCT}: PRODUCT, Product of array elements
213 * @code{RADIX}: RADIX, Base of a data model
214 * @code{RANDOM_NUMBER}: RANDOM_NUMBER, Pseudo-random number
215 * @code{RANDOM_SEED}: RANDOM_SEED, Initialize a pseudo-random number sequence
216 * @code{RAND}: RAND, Real pseudo-random number
217 * @code{RANGE}: RANGE, Decimal exponent range of a real kind
218 * @code{RAN}: RAN, Real pseudo-random number
219 * @code{REAL}: REAL, Convert to real type
220 * @code{RENAME}: RENAME, Rename a file
221 * @code{REPEAT}: REPEAT, Repeated string concatenation
222 * @code{RESHAPE}: RESHAPE, Function to reshape an array
223 * @code{RRSPACING}: RRSPACING, Reciprocal of the relative spacing
224 * @code{RSHIFT}: RSHIFT, Right shift bits
225 * @code{SCALE}: SCALE, Scale a real value
226 * @code{SCAN}: SCAN, Scan a string for the presence of a set of characters
227 * @code{SECNDS}: SECNDS, Time function
228 * @code{SECOND}: SECOND, CPU time function
229 * @code{SELECTED_CHAR_KIND}: SELECTED_CHAR_KIND, Choose character kind
230 * @code{SELECTED_INT_KIND}: SELECTED_INT_KIND, Choose integer kind
231 * @code{SELECTED_REAL_KIND}: SELECTED_REAL_KIND, Choose real kind
232 * @code{SET_EXPONENT}: SET_EXPONENT, Set the exponent of the model
233 * @code{SHAPE}: SHAPE, Determine the shape of an array
234 * @code{SIGN}: SIGN, Sign copying function
235 * @code{SIGNAL}: SIGNAL, Signal handling subroutine (or function)
236 * @code{SIN}: SIN, Sine function
237 * @code{SINH}: SINH, Hyperbolic sine function
238 * @code{SIZE}: SIZE, Function to determine the size of an array
239 * @code{SIZEOF}: SIZEOF, Determine the size in bytes of an expression
240 * @code{SLEEP}: SLEEP, Sleep for the specified number of seconds
241 * @code{SNGL}: SNGL, Convert double precision real to default real
242 * @code{SPACING}: SPACING, Smallest distance between two numbers of a given type
243 * @code{SPREAD}: SPREAD, Add a dimension to an array
244 * @code{SQRT}: SQRT, Square-root function
245 * @code{SRAND}: SRAND, Reinitialize the random number generator
246 * @code{STAT}: STAT, Get file status
247 * @code{SUM}: SUM, Sum of array elements
248 * @code{SYMLNK}: SYMLNK, Create a symbolic link
249 * @code{SYSTEM}: SYSTEM, Execute a shell command
250 * @code{SYSTEM_CLOCK}: SYSTEM_CLOCK, Time function
251 * @code{TAN}: TAN, Tangent function
252 * @code{TANH}: TANH, Hyperbolic tangent function
253 * @code{TIME}: TIME, Time function
254 * @code{TIME8}: TIME8, Time function (64-bit)
255 * @code{TINY}: TINY, Smallest positive number of a real kind
256 * @code{TRAILZ}: TRAILZ, Number of trailing zero bits of an integer
257 * @code{TRANSFER}: TRANSFER, Transfer bit patterns
258 * @code{TRANSPOSE}: TRANSPOSE, Transpose an array of rank two
259 * @code{TRIM}: TRIM, Remove trailing blank characters of a string
260 * @code{TTYNAM}: TTYNAM, Get the name of a terminal device.
261 * @code{UBOUND}: UBOUND, Upper dimension bounds of an array
262 * @code{UMASK}: UMASK, Set the file creation mask
263 * @code{UNLINK}: UNLINK, Remove a file from the file system
264 * @code{UNPACK}: UNPACK, Unpack an array of rank one into an array
265 * @code{VERIFY}: VERIFY, Scan a string for the absence of a set of characters
266 * @code{XOR}: XOR, Bitwise logical exclusive or
269 @node Introduction to Intrinsics
270 @section Introduction to intrinsic procedures
272 The intrinsic procedures provided by GNU Fortran include all of the
273 intrinsic procedures required by the Fortran 95 standard, a set of
274 intrinsic procedures for backwards compatibility with G77, and a
275 selection of intrinsic procedures from the Fortran 2003 and Fortran 2008
276 standards. Any conflict between a description here and a description in
277 either the Fortran 95 standard, the Fortran 2003 standard or the Fortran
278 2008 standard is unintentional, and the standard(s) should be considered
281 The enumeration of the @code{KIND} type parameter is processor defined in
282 the Fortran 95 standard. GNU Fortran defines the default integer type and
283 default real type by @code{INTEGER(KIND=4)} and @code{REAL(KIND=4)},
284 respectively. The standard mandates that both data types shall have
285 another kind, which have more precision. On typical target architectures
286 supported by @command{gfortran}, this kind type parameter is @code{KIND=8}.
287 Hence, @code{REAL(KIND=8)} and @code{DOUBLE PRECISION} are equivalent.
288 In the description of generic intrinsic procedures, the kind type parameter
289 will be specified by @code{KIND=*}, and in the description of specific
290 names for an intrinsic procedure the kind type parameter will be explicitly
291 given (e.g., @code{REAL(KIND=4)} or @code{REAL(KIND=8)}). Finally, for
292 brevity the optional @code{KIND=} syntax will be omitted.
294 Many of the intrinsic procedures take one or more optional arguments.
295 This document follows the convention used in the Fortran 95 standard,
296 and denotes such arguments by square brackets.
298 GNU Fortran offers the @option{-std=f95} and @option{-std=gnu} options,
299 which can be used to restrict the set of intrinsic procedures to a
300 given standard. By default, @command{gfortran} sets the @option{-std=gnu}
301 option, and so all intrinsic procedures described here are accepted. There
302 is one caveat. For a select group of intrinsic procedures, @command{g77}
303 implemented both a function and a subroutine. Both classes
304 have been implemented in @command{gfortran} for backwards compatibility
305 with @command{g77}. It is noted here that these functions and subroutines
306 cannot be intermixed in a given subprogram. In the descriptions that follow,
307 the applicable standard for each intrinsic procedure is noted.
312 @section @code{ABORT} --- Abort the program
314 @cindex program termination, with core dump
315 @cindex terminate program, with core dump
319 @item @emph{Description}:
320 @code{ABORT} causes immediate termination of the program. On operating
321 systems that support a core dump, @code{ABORT} will produce a core dump,
322 which is suitable for debugging purposes.
324 @item @emph{Standard}:
333 @item @emph{Return value}:
336 @item @emph{Example}:
339 integer :: i = 1, j = 2
340 if (i /= j) call abort
341 end program test_abort
344 @item @emph{See also}:
345 @ref{EXIT}, @ref{KILL}
352 @section @code{ABS} --- Absolute value
359 @cindex absolute value
362 @item @emph{Description}:
363 @code{ABS(A)} computes the absolute value of @code{A}.
365 @item @emph{Standard}:
366 Fortran 77 and later, has overloads that are GNU extensions
372 @code{RESULT = ABS(A)}
374 @item @emph{Arguments}:
375 @multitable @columnfractions .15 .70
376 @item @var{A} @tab The type of the argument shall be an @code{INTEGER},
377 @code{REAL}, or @code{COMPLEX}.
380 @item @emph{Return value}:
381 The return value is of the same type and
382 kind as the argument except the return value is @code{REAL} for a
383 @code{COMPLEX} argument.
385 @item @emph{Example}:
390 complex :: z = (-1.e0,0.e0)
397 @item @emph{Specific names}:
398 @multitable @columnfractions .20 .20 .20 .25
399 @item Name @tab Argument @tab Return type @tab Standard
400 @item @code{CABS(A)} @tab @code{COMPLEX(4) Z} @tab @code{REAL(4)} @tab Fortran 77 and later
401 @item @code{DABS(A)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab Fortran 77 and later
402 @item @code{IABS(A)} @tab @code{INTEGER(4) I} @tab @code{INTEGER(4)} @tab Fortran 77 and later
403 @item @code{ZABS(A)} @tab @code{COMPLEX(8) Z} @tab @code{COMPLEX(8)} @tab GNU extension
404 @item @code{CDABS(A)} @tab @code{COMPLEX(8) Z} @tab @code{COMPLEX(8)} @tab GNU extension
411 @section @code{ACCESS} --- Checks file access modes
413 @cindex file system, access mode
416 @item @emph{Description}:
417 @code{ACCESS(NAME, MODE)} checks whether the file @var{NAME}
418 exists, is readable, writable or executable. Except for the
419 executable check, @code{ACCESS} can be replaced by
420 Fortran 95's @code{INQUIRE}.
422 @item @emph{Standard}:
429 @code{RESULT = ACCESS(NAME, MODE)}
431 @item @emph{Arguments}:
432 @multitable @columnfractions .15 .70
433 @item @var{NAME} @tab Scalar @code{CHARACTER} of default kind with the
434 file name. Tailing blank are ignored unless the character @code{achar(0)}
435 is present, then all characters up to and excluding @code{achar(0)} are
437 @item @var{MODE} @tab Scalar @code{CHARACTER} of default kind with the
438 file access mode, may be any concatenation of @code{"r"} (readable),
439 @code{"w"} (writable) and @code{"x"} (executable), or @code{" "} to check
443 @item @emph{Return value}:
444 Returns a scalar @code{INTEGER}, which is @code{0} if the file is
445 accessible in the given mode; otherwise or if an invalid argument
446 has been given for @code{MODE} the value @code{1} is returned.
448 @item @emph{Example}:
452 character(len=*), parameter :: file = 'test.dat'
453 character(len=*), parameter :: file2 = 'test.dat '//achar(0)
454 if(access(file,' ') == 0) print *, trim(file),' is exists'
455 if(access(file,'r') == 0) print *, trim(file),' is readable'
456 if(access(file,'w') == 0) print *, trim(file),' is writable'
457 if(access(file,'x') == 0) print *, trim(file),' is executable'
458 if(access(file2,'rwx') == 0) &
459 print *, trim(file2),' is readable, writable and executable'
460 end program access_test
462 @item @emph{Specific names}:
463 @item @emph{See also}:
470 @section @code{ACHAR} --- Character in @acronym{ASCII} collating sequence
472 @cindex @acronym{ASCII} collating sequence
473 @cindex collating sequence, @acronym{ASCII}
476 @item @emph{Description}:
477 @code{ACHAR(I)} returns the character located at position @code{I}
478 in the @acronym{ASCII} collating sequence.
480 @item @emph{Standard}:
481 Fortran 77 and later, with @var{KIND} argument Fortran 2003 and later
487 @code{RESULT = ACHAR(I [, KIND])}
489 @item @emph{Arguments}:
490 @multitable @columnfractions .15 .70
491 @item @var{I} @tab The type shall be @code{INTEGER}.
492 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
493 expression indicating the kind parameter of the result.
496 @item @emph{Return value}:
497 The return value is of type @code{CHARACTER} with a length of one.
498 If the @var{KIND} argument is present, the return value is of the
499 specified kind and of the default kind otherwise.
501 @item @emph{Example}:
506 end program test_achar
510 See @ref{ICHAR} for a discussion of converting between numerical values
511 and formatted string representations.
513 @item @emph{See also}:
514 @ref{CHAR}, @ref{IACHAR}, @ref{ICHAR}
521 @section @code{ACOS} --- Arccosine function
524 @cindex trigonometric function, cosine, inverse
525 @cindex cosine, inverse
528 @item @emph{Description}:
529 @code{ACOS(X)} computes the arccosine of @var{X} (inverse of @code{COS(X)}).
531 @item @emph{Standard}:
538 @code{RESULT = ACOS(X)}
540 @item @emph{Arguments}:
541 @multitable @columnfractions .15 .70
542 @item @var{X} @tab The type shall be @code{REAL} with a magnitude that is
546 @item @emph{Return value}:
547 The return value is of type @code{REAL} and it lies in the
548 range @math{ 0 \leq \acos(x) \leq \pi}. The return value if of the same
551 @item @emph{Example}:
554 real(8) :: x = 0.866_8
556 end program test_acos
559 @item @emph{Specific names}:
560 @multitable @columnfractions .20 .20 .20 .25
561 @item Name @tab Argument @tab Return type @tab Standard
562 @item @code{DACOS(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab Fortran 77 and later
565 @item @emph{See also}:
566 Inverse function: @ref{COS}
573 @section @code{ACOSH} --- Hyperbolic arccosine function
576 @cindex area hyperbolic cosine
577 @cindex hyperbolic arccosine
578 @cindex hyperbolic function, cosine, inverse
579 @cindex cosine, hyperbolic, inverse
582 @item @emph{Description}:
583 @code{ACOSH(X)} computes the hyperbolic arccosine of @var{X} (inverse of
586 @item @emph{Standard}:
587 Fortran 2008 and later
593 @code{RESULT = ACOSH(X)}
595 @item @emph{Arguments}:
596 @multitable @columnfractions .15 .70
597 @item @var{X} @tab The type shall be @code{REAL} or @code{COMPLEX}.
600 @item @emph{Return value}:
601 The return value has the same type and kind as @var{X}
603 @item @emph{Example}:
606 REAL(8), DIMENSION(3) :: x = (/ 1.0, 2.0, 3.0 /)
611 @item @emph{Specific names}:
612 @multitable @columnfractions .20 .20 .20 .25
613 @item Name @tab Argument @tab Return type @tab Standard
614 @item @code{DACOSH(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU extension
617 @item @emph{See also}:
618 Inverse function: @ref{COSH}
624 @section @code{ADJUSTL} --- Left adjust a string
626 @cindex string, adjust left
627 @cindex adjust string
630 @item @emph{Description}:
631 @code{ADJUSTL(STRING)} will left adjust a string by removing leading spaces.
632 Spaces are inserted at the end of the string as needed.
634 @item @emph{Standard}:
641 @code{RESULT = ADJUSTL(STRING)}
643 @item @emph{Arguments}:
644 @multitable @columnfractions .15 .70
645 @item @var{STRING} @tab The type shall be @code{CHARACTER}.
648 @item @emph{Return value}:
649 The return value is of type @code{CHARACTER} and of the same kind as
650 @var{STRING} where leading spaces are removed and the same number of
651 spaces are inserted on the end of @var{STRING}.
653 @item @emph{Example}:
656 character(len=20) :: str = ' gfortran'
659 end program test_adjustl
662 @item @emph{See also}:
663 @ref{ADJUSTR}, @ref{TRIM}
669 @section @code{ADJUSTR} --- Right adjust a string
671 @cindex string, adjust right
672 @cindex adjust string
675 @item @emph{Description}:
676 @code{ADJUSTR(STRING)} will right adjust a string by removing trailing spaces.
677 Spaces are inserted at the start of the string as needed.
679 @item @emph{Standard}:
686 @code{RESULT = ADJUSTR(STRING)}
688 @item @emph{Arguments}:
689 @multitable @columnfractions .15 .70
690 @item @var{STR} @tab The type shall be @code{CHARACTER}.
693 @item @emph{Return value}:
694 The return value is of type @code{CHARACTER} and of the same kind as
695 @var{STRING} where trailing spaces are removed and the same number of
696 spaces are inserted at the start of @var{STRING}.
698 @item @emph{Example}:
701 character(len=20) :: str = 'gfortran'
704 end program test_adjustr
707 @item @emph{See also}:
708 @ref{ADJUSTL}, @ref{TRIM}
714 @section @code{AIMAG} --- Imaginary part of complex number
719 @cindex complex numbers, imaginary part
722 @item @emph{Description}:
723 @code{AIMAG(Z)} yields the imaginary part of complex argument @code{Z}.
724 The @code{IMAG(Z)} and @code{IMAGPART(Z)} intrinsic functions are provided
725 for compatibility with @command{g77}, and their use in new code is
726 strongly discouraged.
728 @item @emph{Standard}:
729 Fortran 77 and later, has overloads that are GNU extensions
735 @code{RESULT = AIMAG(Z)}
737 @item @emph{Arguments}:
738 @multitable @columnfractions .15 .70
739 @item @var{Z} @tab The type of the argument shall be @code{COMPLEX}.
742 @item @emph{Return value}:
743 The return value is of type @code{REAL} with the
744 kind type parameter of the argument.
746 @item @emph{Example}:
751 z4 = cmplx(1.e0_4, 0.e0_4)
752 z8 = cmplx(0.e0_8, 1.e0_8)
753 print *, aimag(z4), dimag(z8)
754 end program test_aimag
757 @item @emph{Specific names}:
758 @multitable @columnfractions .20 .20 .20 .25
759 @item Name @tab Argument @tab Return type @tab Standard
760 @item @code{DIMAG(Z)} @tab @code{COMPLEX(8) Z} @tab @code{REAL(8)} @tab GNU extension
761 @item @code{IMAG(Z)} @tab @code{COMPLEX Z} @tab @code{REAL} @tab GNU extension
762 @item @code{IMAGPART(Z)} @tab @code{COMPLEX Z} @tab @code{REAL} @tab GNU extension
769 @section @code{AINT} --- Truncate to a whole number
773 @cindex rounding, floor
776 @item @emph{Description}:
777 @code{AINT(A [, KIND])} truncates its argument to a whole number.
779 @item @emph{Standard}:
786 @code{RESULT = AINT(A [, KIND])}
788 @item @emph{Arguments}:
789 @multitable @columnfractions .15 .70
790 @item @var{A} @tab The type of the argument shall be @code{REAL}.
791 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
792 expression indicating the kind parameter of the result.
795 @item @emph{Return value}:
796 The return value is of type @code{REAL} with the kind type parameter of the
797 argument if the optional @var{KIND} is absent; otherwise, the kind
798 type parameter will be given by @var{KIND}. If the magnitude of
799 @var{X} is less than one, @code{AINT(X)} returns zero. If the
800 magnitude is equal to or greater than one then it returns the largest
801 whole number that does not exceed its magnitude. The sign is the same
802 as the sign of @var{X}.
804 @item @emph{Example}:
811 print *, aint(x4), dint(x8)
813 end program test_aint
816 @item @emph{Specific names}:
817 @multitable @columnfractions .20 .20 .20 .25
818 @item Name @tab Argument @tab Return type @tab Standard
819 @item @code{DINT(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab Fortran 77 and later
826 @section @code{ALARM} --- Execute a routine after a given delay
828 @cindex delayed execution
831 @item @emph{Description}:
832 @code{ALARM(SECONDS, HANDLER [, STATUS])} causes external subroutine @var{HANDLER}
833 to be executed after a delay of @var{SECONDS} by using @code{alarm(2)} to
834 set up a signal and @code{signal(2)} to catch it. If @var{STATUS} is
835 supplied, it will be returned with the number of seconds remaining until
836 any previously scheduled alarm was due to be delivered, or zero if there
837 was no previously scheduled alarm.
839 @item @emph{Standard}:
846 @code{CALL ALARM(SECONDS, HANDLER [, STATUS])}
848 @item @emph{Arguments}:
849 @multitable @columnfractions .15 .70
850 @item @var{SECONDS} @tab The type of the argument shall be a scalar
851 @code{INTEGER}. It is @code{INTENT(IN)}.
852 @item @var{HANDLER} @tab Signal handler (@code{INTEGER FUNCTION} or
853 @code{SUBROUTINE}) or dummy/global @code{INTEGER} scalar. The scalar
854 values may be either @code{SIG_IGN=1} to ignore the alarm generated
855 or @code{SIG_DFL=0} to set the default action. It is @code{INTENT(IN)}.
856 @item @var{STATUS} @tab (Optional) @var{STATUS} shall be a scalar
857 variable of the default @code{INTEGER} kind. It is @code{INTENT(OUT)}.
860 @item @emph{Example}:
863 external handler_print
865 call alarm (3, handler_print, i)
868 end program test_alarm
870 This will cause the external routine @var{handler_print} to be called
877 @section @code{ALL} --- All values in @var{MASK} along @var{DIM} are true
879 @cindex array, apply condition
880 @cindex array, condition testing
883 @item @emph{Description}:
884 @code{ALL(MASK [, DIM])} determines if all the values are true in @var{MASK}
885 in the array along dimension @var{DIM}.
887 @item @emph{Standard}:
891 Transformational function
894 @code{RESULT = ALL(MASK [, DIM])}
896 @item @emph{Arguments}:
897 @multitable @columnfractions .15 .70
898 @item @var{MASK} @tab The type of the argument shall be @code{LOGICAL} and
899 it shall not be scalar.
900 @item @var{DIM} @tab (Optional) @var{DIM} shall be a scalar integer
901 with a value that lies between one and the rank of @var{MASK}.
904 @item @emph{Return value}:
905 @code{ALL(MASK)} returns a scalar value of type @code{LOGICAL} where
906 the kind type parameter is the same as the kind type parameter of
907 @var{MASK}. If @var{DIM} is present, then @code{ALL(MASK, DIM)} returns
908 an array with the rank of @var{MASK} minus 1. The shape is determined from
909 the shape of @var{MASK} where the @var{DIM} dimension is elided.
913 @code{ALL(MASK)} is true if all elements of @var{MASK} are true.
914 It also is true if @var{MASK} has zero size; otherwise, it is false.
916 If the rank of @var{MASK} is one, then @code{ALL(MASK,DIM)} is equivalent
917 to @code{ALL(MASK)}. If the rank is greater than one, then @code{ALL(MASK,DIM)}
918 is determined by applying @code{ALL} to the array sections.
921 @item @emph{Example}:
925 l = all((/.true., .true., .true./))
930 integer a(2,3), b(2,3)
934 print *, all(a .eq. b, 1)
935 print *, all(a .eq. b, 2)
936 end subroutine section
944 @section @code{ALLOCATED} --- Status of an allocatable entity
946 @cindex allocation, status
949 @item @emph{Description}:
950 @code{ALLOCATED(ARRAY)} checks the status of whether @var{X} is allocated.
952 @item @emph{Standard}:
959 @code{RESULT = ALLOCATED(ARRAY)}
961 @item @emph{Arguments}:
962 @multitable @columnfractions .15 .70
963 @item @var{ARRAY} @tab The argument shall be an @code{ALLOCATABLE} array.
966 @item @emph{Return value}:
967 The return value is a scalar @code{LOGICAL} with the default logical
968 kind type parameter. If @var{ARRAY} is allocated, @code{ALLOCATED(ARRAY)}
969 is @code{.TRUE.}; otherwise, it returns @code{.FALSE.}
971 @item @emph{Example}:
973 program test_allocated
975 real(4), allocatable :: x(:)
976 if (allocated(x) .eqv. .false.) allocate(x(i))
977 end program test_allocated
984 @section @code{AND} --- Bitwise logical AND
986 @cindex bitwise logical and
987 @cindex logical and, bitwise
990 @item @emph{Description}:
991 Bitwise logical @code{AND}.
993 This intrinsic routine is provided for backwards compatibility with
994 GNU Fortran 77. For integer arguments, programmers should consider
995 the use of the @ref{IAND} intrinsic defined by the Fortran standard.
997 @item @emph{Standard}:
1003 @item @emph{Syntax}:
1004 @code{RESULT = AND(I, J)}
1006 @item @emph{Arguments}:
1007 @multitable @columnfractions .15 .70
1008 @item @var{I} @tab The type shall be either a scalar @code{INTEGER}
1009 type or a scalar @code{LOGICAL} type.
1010 @item @var{J} @tab The type shall be the same as the type of @var{I}.
1013 @item @emph{Return value}:
1014 The return type is either a scalar @code{INTEGER} or a scalar
1015 @code{LOGICAL}. If the kind type parameters differ, then the
1016 smaller kind type is implicitly converted to larger kind, and the
1017 return has the larger kind.
1019 @item @emph{Example}:
1022 LOGICAL :: T = .TRUE., F = .FALSE.
1024 DATA a / Z'F' /, b / Z'3' /
1026 WRITE (*,*) AND(T, T), AND(T, F), AND(F, T), AND(F, F)
1027 WRITE (*,*) AND(a, b)
1031 @item @emph{See also}:
1032 Fortran 95 elemental function: @ref{IAND}
1038 @section @code{ANINT} --- Nearest whole number
1042 @cindex rounding, ceiling
1045 @item @emph{Description}:
1046 @code{ANINT(A [, KIND])} rounds its argument to the nearest whole number.
1048 @item @emph{Standard}:
1049 Fortran 77 and later
1054 @item @emph{Syntax}:
1055 @code{RESULT = ANINT(A [, KIND])}
1057 @item @emph{Arguments}:
1058 @multitable @columnfractions .15 .70
1059 @item @var{A} @tab The type of the argument shall be @code{REAL}.
1060 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
1061 expression indicating the kind parameter of the result.
1064 @item @emph{Return value}:
1065 The return value is of type real with the kind type parameter of the
1066 argument if the optional @var{KIND} is absent; otherwise, the kind
1067 type parameter will be given by @var{KIND}. If @var{A} is greater than
1068 zero, @code{ANINT(A)} returns @code{AINT(X+0.5)}. If @var{A} is
1069 less than or equal to zero then it returns @code{AINT(X-0.5)}.
1071 @item @emph{Example}:
1078 print *, anint(x4), dnint(x8)
1080 end program test_anint
1083 @item @emph{Specific names}:
1084 @multitable @columnfractions .20 .20 .20 .25
1085 @item Name @tab Argument @tab Return type @tab Standard
1086 @item @code{DNINT(A)} @tab @code{REAL(8) A} @tab @code{REAL(8)} @tab Fortran 77 and later
1093 @section @code{ANY} --- Any value in @var{MASK} along @var{DIM} is true
1095 @cindex array, apply condition
1096 @cindex array, condition testing
1099 @item @emph{Description}:
1100 @code{ANY(MASK [, DIM])} determines if any of the values in the logical array
1101 @var{MASK} along dimension @var{DIM} are @code{.TRUE.}.
1103 @item @emph{Standard}:
1104 Fortran 95 and later
1107 Transformational function
1109 @item @emph{Syntax}:
1110 @code{RESULT = ANY(MASK [, DIM])}
1112 @item @emph{Arguments}:
1113 @multitable @columnfractions .15 .70
1114 @item @var{MASK} @tab The type of the argument shall be @code{LOGICAL} and
1115 it shall not be scalar.
1116 @item @var{DIM} @tab (Optional) @var{DIM} shall be a scalar integer
1117 with a value that lies between one and the rank of @var{MASK}.
1120 @item @emph{Return value}:
1121 @code{ANY(MASK)} returns a scalar value of type @code{LOGICAL} where
1122 the kind type parameter is the same as the kind type parameter of
1123 @var{MASK}. If @var{DIM} is present, then @code{ANY(MASK, DIM)} returns
1124 an array with the rank of @var{MASK} minus 1. The shape is determined from
1125 the shape of @var{MASK} where the @var{DIM} dimension is elided.
1129 @code{ANY(MASK)} is true if any element of @var{MASK} is true;
1130 otherwise, it is false. It also is false if @var{MASK} has zero size.
1132 If the rank of @var{MASK} is one, then @code{ANY(MASK,DIM)} is equivalent
1133 to @code{ANY(MASK)}. If the rank is greater than one, then @code{ANY(MASK,DIM)}
1134 is determined by applying @code{ANY} to the array sections.
1137 @item @emph{Example}:
1141 l = any((/.true., .true., .true./))
1146 integer a(2,3), b(2,3)
1150 print *, any(a .eq. b, 1)
1151 print *, any(a .eq. b, 2)
1152 end subroutine section
1153 end program test_any
1160 @section @code{ASIN} --- Arcsine function
1163 @cindex trigonometric function, sine, inverse
1164 @cindex sine, inverse
1167 @item @emph{Description}:
1168 @code{ASIN(X)} computes the arcsine of its @var{X} (inverse of @code{SIN(X)}).
1170 @item @emph{Standard}:
1171 Fortran 77 and later
1176 @item @emph{Syntax}:
1177 @code{RESULT = ASIN(X)}
1179 @item @emph{Arguments}:
1180 @multitable @columnfractions .15 .70
1181 @item @var{X} @tab The type shall be @code{REAL}, and a magnitude that is
1185 @item @emph{Return value}:
1186 The return value is of type @code{REAL} and it lies in the
1187 range @math{-\pi / 2 \leq \asin (x) \leq \pi / 2}. The kind type
1188 parameter is the same as @var{X}.
1190 @item @emph{Example}:
1193 real(8) :: x = 0.866_8
1195 end program test_asin
1198 @item @emph{Specific names}:
1199 @multitable @columnfractions .20 .20 .20 .25
1200 @item Name @tab Argument @tab Return type @tab Standard
1201 @item @code{DASIN(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab Fortran 77 and later
1204 @item @emph{See also}:
1205 Inverse function: @ref{SIN}
1212 @section @code{ASINH} --- Hyperbolic arcsine function
1215 @cindex area hyperbolic sine
1216 @cindex hyperbolic arcsine
1217 @cindex hyperbolic function, sine, inverse
1218 @cindex sine, hyperbolic, inverse
1221 @item @emph{Description}:
1222 @code{ASINH(X)} computes the hyperbolic arcsine of @var{X} (inverse of @code{SINH(X)}).
1224 @item @emph{Standard}:
1225 Fortran 2008 and later
1230 @item @emph{Syntax}:
1231 @code{RESULT = ASINH(X)}
1233 @item @emph{Arguments}:
1234 @multitable @columnfractions .15 .70
1235 @item @var{X} @tab The type shall be @code{REAL} or @code{COMPLEX}.
1238 @item @emph{Return value}:
1239 The return value is of the same type and kind as @var{X}.
1241 @item @emph{Example}:
1244 REAL(8), DIMENSION(3) :: x = (/ -1.0, 0.0, 1.0 /)
1245 WRITE (*,*) ASINH(x)
1249 @item @emph{Specific names}:
1250 @multitable @columnfractions .20 .20 .20 .25
1251 @item Name @tab Argument @tab Return type @tab Standard
1252 @item @code{DASINH(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU extension.
1255 @item @emph{See also}:
1256 Inverse function: @ref{SINH}
1262 @section @code{ASSOCIATED} --- Status of a pointer or pointer/target pair
1264 @cindex pointer, status
1265 @cindex association status
1268 @item @emph{Description}:
1269 @code{ASSOCIATED(POINTER [, TARGET])} determines the status of the pointer
1270 @var{POINTER} or if @var{POINTER} is associated with the target @var{TARGET}.
1272 @item @emph{Standard}:
1273 Fortran 95 and later
1278 @item @emph{Syntax}:
1279 @code{RESULT = ASSOCIATED(POINTER [, TARGET])}
1281 @item @emph{Arguments}:
1282 @multitable @columnfractions .15 .70
1283 @item @var{POINTER} @tab @var{POINTER} shall have the @code{POINTER} attribute
1284 and it can be of any type.
1285 @item @var{TARGET} @tab (Optional) @var{TARGET} shall be a pointer or
1286 a target. It must have the same type, kind type parameter, and
1287 array rank as @var{POINTER}.
1289 The association status of neither @var{POINTER} nor @var{TARGET} shall be
1292 @item @emph{Return value}:
1293 @code{ASSOCIATED(POINTER)} returns a scalar value of type @code{LOGICAL(4)}.
1294 There are several cases:
1296 @item (A) When the optional @var{TARGET} is not present then
1297 @code{ASSOCIATED(POINTER)} is true if @var{POINTER} is associated with a target; otherwise, it returns false.
1298 @item (B) If @var{TARGET} is present and a scalar target, the result is true if
1299 @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
1300 disassociated, the result is false.
1301 @item (C) If @var{TARGET} is present and an array target, the result is true if
1302 @var{TARGET} and @var{POINTER} have the same shape, are not zero-sized arrays,
1303 are arrays whose elements are not zero-sized storage sequences, and
1304 @var{TARGET} and @var{POINTER} occupy the same storage units in array element
1306 As in case(B), the result is false, if @var{POINTER} is disassociated.
1307 @item (D) If @var{TARGET} is present and an scalar pointer, the result is true
1308 if @var{TARGET} is associated with @var{POINTER}, the target associated with
1309 @var{TARGET} are not zero-sized storage sequences and occupy the same storage
1311 The result is false, if either @var{TARGET} or @var{POINTER} is disassociated.
1312 @item (E) If @var{TARGET} is present and an array pointer, the result is true if
1313 target associated with @var{POINTER} and the target associated with @var{TARGET}
1314 have the same shape, are not zero-sized arrays, are arrays whose elements are
1315 not zero-sized storage sequences, and @var{TARGET} and @var{POINTER} occupy
1316 the same storage units in array element order.
1317 The result is false, if either @var{TARGET} or @var{POINTER} is disassociated.
1320 @item @emph{Example}:
1322 program test_associated
1324 real, target :: tgt(2) = (/1., 2./)
1325 real, pointer :: ptr(:)
1327 if (associated(ptr) .eqv. .false.) call abort
1328 if (associated(ptr,tgt) .eqv. .false.) call abort
1329 end program test_associated
1332 @item @emph{See also}:
1339 @section @code{ATAN} --- Arctangent function
1342 @cindex trigonometric function, tangent, inverse
1343 @cindex tangent, inverse
1346 @item @emph{Description}:
1347 @code{ATAN(X)} computes the arctangent of @var{X}.
1349 @item @emph{Standard}:
1350 Fortran 77 and later
1355 @item @emph{Syntax}:
1356 @code{RESULT = ATAN(X)}
1358 @item @emph{Arguments}:
1359 @multitable @columnfractions .15 .70
1360 @item @var{X} @tab The type shall be @code{REAL}.
1363 @item @emph{Return value}:
1364 The return value is of type @code{REAL} and it lies in the
1365 range @math{ - \pi / 2 \leq \atan (x) \leq \pi / 2}.
1367 @item @emph{Example}:
1370 real(8) :: x = 2.866_8
1372 end program test_atan
1375 @item @emph{Specific names}:
1376 @multitable @columnfractions .20 .20 .20 .25
1377 @item Name @tab Argument @tab Return type @tab Standard
1378 @item @code{DATAN(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab Fortran 77 and later
1381 @item @emph{See also}:
1382 Inverse function: @ref{TAN}
1389 @section @code{ATAN2} --- Arctangent function
1392 @cindex trigonometric function, tangent, inverse
1393 @cindex tangent, inverse
1396 @item @emph{Description}:
1397 @code{ATAN2(Y, X)} computes the arctangent of the complex number
1400 @item @emph{Standard}:
1401 Fortran 77 and later
1406 @item @emph{Syntax}:
1407 @code{RESULT = ATAN2(Y, X)}
1409 @item @emph{Arguments}:
1410 @multitable @columnfractions .15 .70
1411 @item @var{Y} @tab The type shall be @code{REAL}.
1412 @item @var{X} @tab The type and kind type parameter shall be the same as @var{Y}.
1413 If @var{Y} is zero, then @var{X} must be nonzero.
1416 @item @emph{Return value}:
1417 The return value has the same type and kind type parameter as @var{Y}.
1418 It is the principal value of the complex number @math{X + i Y}. If
1419 @var{X} is nonzero, then it lies in the range @math{-\pi \le \atan (x) \leq \pi}.
1420 The sign is positive if @var{Y} is positive. If @var{Y} is zero, then
1421 the return value is zero if @var{X} is positive and @math{\pi} if @var{X}
1422 is negative. Finally, if @var{X} is zero, then the magnitude of the result
1425 @item @emph{Example}:
1428 real(4) :: x = 1.e0_4, y = 0.5e0_4
1430 end program test_atan2
1433 @item @emph{Specific names}:
1434 @multitable @columnfractions .20 .20 .20 .25
1435 @item Name @tab Argument @tab Return type @tab Standard
1436 @item @code{DATAN2(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab Fortran 77 and later
1443 @section @code{ATANH} --- Hyperbolic arctangent function
1446 @cindex area hyperbolic tangent
1447 @cindex hyperbolic arctangent
1448 @cindex hyperbolic function, tangent, inverse
1449 @cindex tangent, hyperbolic, inverse
1452 @item @emph{Description}:
1453 @code{ATANH(X)} computes the hyperbolic arctangent of @var{X} (inverse
1456 @item @emph{Standard}:
1457 Fortran 2008 and later
1462 @item @emph{Syntax}:
1463 @code{RESULT = ATANH(X)}
1465 @item @emph{Arguments}:
1466 @multitable @columnfractions .15 .70
1467 @item @var{X} @tab The type shall be @code{REAL} or @code{COMPLEX}.
1470 @item @emph{Return value}:
1471 The return value has same type and kind as @var{X}.
1473 @item @emph{Example}:
1476 REAL, DIMENSION(3) :: x = (/ -1.0, 0.0, 1.0 /)
1477 WRITE (*,*) ATANH(x)
1481 @item @emph{Specific names}:
1482 @multitable @columnfractions .20 .20 .20 .25
1483 @item Name @tab Argument @tab Return type @tab Standard
1484 @item @code{DATANH(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU extension
1487 @item @emph{See also}:
1488 Inverse function: @ref{TANH}
1494 @section @code{BESSEL_J0} --- Bessel function of the first kind of order 0
1498 @cindex Bessel function, first kind
1501 @item @emph{Description}:
1502 @code{BESSEL_J0(X)} computes the Bessel function of the first kind of
1503 order 0 of @var{X}. This function is available under the name
1504 @code{BESJ0} as a GNU extension.
1506 @item @emph{Standard}:
1507 Fortran 2008 and later
1512 @item @emph{Syntax}:
1513 @code{RESULT = BESSEL_J0(X)}
1515 @item @emph{Arguments}:
1516 @multitable @columnfractions .15 .70
1517 @item @var{X} @tab The type shall be @code{REAL}, and it shall be scalar.
1520 @item @emph{Return value}:
1521 The return value is of type @code{REAL} and lies in the
1522 range @math{ - 0.4027... \leq Bessel (0,x) \leq 1}. It has the same
1525 @item @emph{Example}:
1528 real(8) :: x = 0.0_8
1530 end program test_besj0
1533 @item @emph{Specific names}:
1534 @multitable @columnfractions .20 .20 .20 .25
1535 @item Name @tab Argument @tab Return type @tab Standard
1536 @item @code{DBESJ0(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU extension
1543 @section @code{BESSEL_J1} --- Bessel function of the first kind of order 1
1547 @cindex Bessel function, first kind
1550 @item @emph{Description}:
1551 @code{BESSEL_J1(X)} computes the Bessel function of the first kind of
1552 order 1 of @var{X}. This function is available under the name
1553 @code{BESJ1} as a GNU extension.
1555 @item @emph{Standard}:
1561 @item @emph{Syntax}:
1562 @code{RESULT = BESSEL_J1(X)}
1564 @item @emph{Arguments}:
1565 @multitable @columnfractions .15 .70
1566 @item @var{X} @tab The type shall be @code{REAL}, and it shall be scalar.
1569 @item @emph{Return value}:
1570 The return value is of type @code{REAL} and it lies in the
1571 range @math{ - 0.5818... \leq Bessel (0,x) \leq 0.5818 }. It has the same
1574 @item @emph{Example}:
1577 real(8) :: x = 1.0_8
1579 end program test_besj1
1582 @item @emph{Specific names}:
1583 @multitable @columnfractions .20 .20 .20 .25
1584 @item Name @tab Argument @tab Return type @tab Standard
1585 @item @code{DBESJ1(X)}@tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU extension
1592 @section @code{BESSEL_JN} --- Bessel function of the first kind
1596 @cindex Bessel function, first kind
1599 @item @emph{Description}:
1600 @code{BESSEL_JN(N, X)} computes the Bessel function of the first kind of
1601 order @var{N} of @var{X}. This function is available under the name
1602 @code{BESJN} as a GNU extension.
1604 If both arguments are arrays, their ranks and shapes shall conform.
1606 @item @emph{Standard}:
1607 Fortran 2008 and later
1612 @item @emph{Syntax}:
1613 @code{RESULT = BESSEL_JN(N, X)}
1615 @item @emph{Arguments}:
1616 @multitable @columnfractions .15 .70
1617 @item @var{N} @tab Shall be a scalar or an array of type @code{INTEGER}.
1618 @item @var{X} @tab Shall be a scalar or an array of type @code{REAL}.
1621 @item @emph{Return value}:
1622 The return value is a scalar of type @code{REAL}. It has the same
1625 @item @emph{Example}:
1628 real(8) :: x = 1.0_8
1630 end program test_besjn
1633 @item @emph{Specific names}:
1634 @multitable @columnfractions .20 .20 .20 .25
1635 @item Name @tab Argument @tab Return type @tab Standard
1636 @item @code{DBESJN(X)} @tab @code{INTEGER N} @tab @code{REAL(8)} @tab GNU extension
1637 @item @tab @code{REAL(8) X} @tab @tab
1644 @section @code{BESSEL_Y0} --- Bessel function of the second kind of order 0
1648 @cindex Bessel function, second kind
1651 @item @emph{Description}:
1652 @code{BESSEL_Y0(X)} computes the Bessel function of the second kind of
1653 order 0 of @var{X}. This function is available under the name
1654 @code{BESY0} as a GNU extension.
1656 @item @emph{Standard}:
1657 Fortran 2008 and later
1662 @item @emph{Syntax}:
1663 @code{RESULT = BESSEL_Y0(X)}
1665 @item @emph{Arguments}:
1666 @multitable @columnfractions .15 .70
1667 @item @var{X} @tab The type shall be @code{REAL}, and it shall be scalar.
1670 @item @emph{Return value}:
1671 The return value is a scalar of type @code{REAL}. It has the same
1674 @item @emph{Example}:
1677 real(8) :: x = 0.0_8
1679 end program test_besy0
1682 @item @emph{Specific names}:
1683 @multitable @columnfractions .20 .20 .20 .25
1684 @item Name @tab Argument @tab Return type @tab Standard
1685 @item @code{DBESY0(X)}@tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU extension
1692 @section @code{BESSEL_Y1} --- Bessel function of the second kind of order 1
1696 @cindex Bessel function, second kind
1699 @item @emph{Description}:
1700 @code{BESSEL_Y1(X)} computes the Bessel function of the second kind of
1701 order 1 of @var{X}. This function is available under the name
1702 @code{BESY1} as a GNU extension.
1704 @item @emph{Standard}:
1705 Fortran 2008 and later
1710 @item @emph{Syntax}:
1711 @code{RESULT = BESSEL_Y1(X)}
1713 @item @emph{Arguments}:
1714 @multitable @columnfractions .15 .70
1715 @item @var{X} @tab The type shall be @code{REAL}, and it shall be scalar.
1718 @item @emph{Return value}:
1719 The return value is a scalar of type @code{REAL}. It has the same
1722 @item @emph{Example}:
1725 real(8) :: x = 1.0_8
1727 end program test_besy1
1730 @item @emph{Specific names}:
1731 @multitable @columnfractions .20 .20 .20 .25
1732 @item Name @tab Argument @tab Return type @tab Standard
1733 @item @code{DBESY1(X)}@tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU extension
1740 @section @code{BESSEL_YN} --- Bessel function of the second kind
1744 @cindex Bessel function, second kind
1747 @item @emph{Description}:
1748 @code{BESSEL_YN(N, X)} computes the Bessel function of the second kind of
1749 order @var{N} of @var{X}. This function is available under the name
1750 @code{BESYN} as a GNU extension.
1752 If both arguments are arrays, their ranks and shapes shall conform.
1754 @item @emph{Standard}:
1755 Fortran 2008 and later
1760 @item @emph{Syntax}:
1761 @code{RESULT = BESSEL_YN(N, X)}
1763 @item @emph{Arguments}:
1764 @multitable @columnfractions .15 .70
1765 @item @var{N} @tab Shall be a scalar or an array of type @code{INTEGER}.
1766 @item @var{X} @tab Shall be a scalar or an array of type @code{REAL}.
1769 @item @emph{Return value}:
1770 The return value is a scalar of type @code{REAL}. It has the same
1773 @item @emph{Example}:
1776 real(8) :: x = 1.0_8
1778 end program test_besyn
1781 @item @emph{Specific names}:
1782 @multitable @columnfractions .20 .20 .20 .25
1783 @item Name @tab Argument @tab Return type @tab Standard
1784 @item @code{DBESYN(N,X)} @tab @code{INTEGER N} @tab @code{REAL(8)} @tab GNU extension
1785 @item @tab @code{REAL(8) X} @tab @tab
1792 @section @code{BIT_SIZE} --- Bit size inquiry function
1794 @cindex bits, number of
1795 @cindex size of a variable, in bits
1798 @item @emph{Description}:
1799 @code{BIT_SIZE(I)} returns the number of bits (integer precision plus sign bit)
1800 represented by the type of @var{I}.
1802 @item @emph{Standard}:
1803 Fortran 95 and later
1808 @item @emph{Syntax}:
1809 @code{RESULT = BIT_SIZE(I)}
1811 @item @emph{Arguments}:
1812 @multitable @columnfractions .15 .70
1813 @item @var{I} @tab The type shall be @code{INTEGER}.
1816 @item @emph{Return value}:
1817 The return value is of type @code{INTEGER}
1819 @item @emph{Example}:
1821 program test_bit_size
1826 end program test_bit_size
1833 @section @code{BTEST} --- Bit test function
1835 @cindex bits, testing
1838 @item @emph{Description}:
1839 @code{BTEST(I,POS)} returns logical @code{.TRUE.} if the bit at @var{POS}
1842 @item @emph{Standard}:
1843 Fortran 95 and later
1848 @item @emph{Syntax}:
1849 @code{RESULT = BTEST(I, POS)}
1851 @item @emph{Arguments}:
1852 @multitable @columnfractions .15 .70
1853 @item @var{I} @tab The type shall be @code{INTEGER}.
1854 @item @var{POS} @tab The type shall be @code{INTEGER}.
1857 @item @emph{Return value}:
1858 The return value is of type @code{LOGICAL}
1860 @item @emph{Example}:
1863 integer :: i = 32768 + 1024 + 64
1867 bool = btest(i, pos)
1870 end program test_btest
1876 @section @code{C_ASSOCIATED} --- Status of a C pointer
1877 @fnindex C_ASSOCIATED
1878 @cindex association status, C pointer
1879 @cindex pointer, C association status
1882 @item @emph{Description}:
1883 @code{C_ASSOCIATED(c_prt_1[, c_ptr_2])} determines the status of the C pointer
1884 @var{c_ptr_1} or if @var{c_ptr_1} is associated with the target @var{c_ptr_2}.
1886 @item @emph{Standard}:
1887 Fortran 2003 and later
1892 @item @emph{Syntax}:
1893 @code{RESULT = C_ASSOCIATED(c_prt_1[, c_ptr_2])}
1895 @item @emph{Arguments}:
1896 @multitable @columnfractions .15 .70
1897 @item @var{c_ptr_1} @tab Scalar of the type @code{C_PTR} or @code{C_FUNPTR}.
1898 @item @var{c_ptr_2} @tab (Optional) Scalar of the same type as @var{c_ptr_1}.
1901 @item @emph{Return value}:
1902 The return value is of type @code{LOGICAL}; it is @code{.false.} if either
1903 @var{c_ptr_1} is a C NULL pointer or if @var{c_ptr1} and @var{c_ptr_2}
1904 point to different addresses.
1906 @item @emph{Example}:
1908 subroutine association_test(a,b)
1909 use iso_c_binding, only: c_associated, c_loc, c_ptr
1913 if(c_associated(b, c_loc(a))) &
1914 stop 'b and a do not point to same target'
1915 end subroutine association_test
1918 @item @emph{See also}:
1919 @ref{C_LOC}, @ref{C_FUNLOC}
1924 @section @code{C_FUNLOC} --- Obtain the C address of a procedure
1926 @cindex pointer, C address of procedures
1929 @item @emph{Description}:
1930 @code{C_FUNLOC(x)} determines the C address of the argument.
1932 @item @emph{Standard}:
1933 Fortran 2003 and later
1938 @item @emph{Syntax}:
1939 @code{RESULT = C_FUNLOC(x)}
1941 @item @emph{Arguments}:
1942 @multitable @columnfractions .15 .70
1943 @item @var{x} @tab Interoperable function or pointer to such function.
1946 @item @emph{Return value}:
1947 The return value is of type @code{C_FUNPTR} and contains the C address
1950 @item @emph{Example}:
1956 subroutine sub(a) bind(c)
1966 subroutine my_routine(p) bind(c,name='myC_func')
1968 type(c_funptr), intent(in) :: p
1971 call my_routine(c_funloc(sub))
1975 @item @emph{See also}:
1976 @ref{C_ASSOCIATED}, @ref{C_LOC}, @ref{C_F_POINTER}, @ref{C_F_PROCPOINTER}
1980 @node C_F_PROCPOINTER
1981 @section @code{C_F_PROCPOINTER} --- Convert C into Fortran procedure pointer
1982 @fnindex C_F_PROCPOINTER
1983 @cindex pointer, C address of pointers
1986 @item @emph{Description}:
1987 @code{C_F_PROCPOINTER(CPTR, FPTR)} Assign the target of the C function pointer
1988 @var{CPTR} to the Fortran procedure pointer @var{FPTR}.
1990 Note: Due to the currently lacking support of procedure pointers in GNU Fortran
1991 this function is not fully operable.
1993 @item @emph{Standard}:
1994 Fortran 2003 and later
1999 @item @emph{Syntax}:
2000 @code{CALL C_F_PROCPOINTER(cptr, fptr)}
2002 @item @emph{Arguments}:
2003 @multitable @columnfractions .15 .70
2004 @item @var{CPTR} @tab scalar of the type @code{C_FUNPTR}. It is
2006 @item @var{FPTR} @tab procedure pointer interoperable with @var{cptr}. It is
2010 @item @emph{Example}:
2018 real(c_float), intent(in) :: a
2019 real(c_float) :: func
2023 function getIterFunc() bind(c,name="getIterFunc")
2025 type(c_funptr) :: getIterFunc
2028 type(c_funptr) :: cfunptr
2029 procedure(func), pointer :: myFunc
2030 cfunptr = getIterFunc()
2031 call c_f_procpointer(cfunptr, myFunc)
2035 @item @emph{See also}:
2036 @ref{C_LOC}, @ref{C_F_POINTER}
2041 @section @code{C_F_POINTER} --- Convert C into Fortran pointer
2042 @fnindex C_F_POINTER
2043 @cindex pointer, convert C to Fortran
2046 @item @emph{Description}:
2047 @code{C_F_POINTER(CPTR, FPTR[, SHAPE])} Assign the target the C pointer
2048 @var{CPTR} to the Fortran pointer @var{FPTR} and specify its
2051 @item @emph{Standard}:
2052 Fortran 2003 and later
2057 @item @emph{Syntax}:
2058 @code{CALL C_F_POINTER(CPTR, FPTR[, SHAPE])}
2060 @item @emph{Arguments}:
2061 @multitable @columnfractions .15 .70
2062 @item @var{CPTR} @tab scalar of the type @code{C_PTR}. It is
2064 @item @var{FPTR} @tab pointer interoperable with @var{cptr}. It is
2066 @item @var{SHAPE} @tab (Optional) Rank-one array of type @code{INTEGER}
2067 with @code{INTENT(IN)}. It shall be present
2068 if and only if @var{fptr} is an array. The size
2069 must be equal to the rank of @var{fptr}.
2072 @item @emph{Example}:
2078 subroutine my_routine(p) bind(c,name='myC_func')
2080 type(c_ptr), intent(out) :: p
2084 real,pointer :: a(:)
2085 call my_routine(cptr)
2086 call c_f_pointer(cptr, a, [12])
2090 @item @emph{See also}:
2091 @ref{C_LOC}, @ref{C_F_PROCPOINTER}
2096 @section @code{C_LOC} --- Obtain the C address of an object
2098 @cindex procedure pointer, convert C to Fortran
2101 @item @emph{Description}:
2102 @code{C_LOC(X)} determines the C address of the argument.
2104 @item @emph{Standard}:
2105 Fortran 2003 and later
2110 @item @emph{Syntax}:
2111 @code{RESULT = C_LOC(X)}
2113 @item @emph{Arguments}:
2114 @multitable @columnfractions .15 .70
2115 @item @var{X} @tab Associated scalar pointer or interoperable scalar
2116 or allocated allocatable variable with @code{TARGET} attribute.
2119 @item @emph{Return value}:
2120 The return value is of type @code{C_PTR} and contains the C address
2123 @item @emph{Example}:
2125 subroutine association_test(a,b)
2126 use iso_c_binding, only: c_associated, c_loc, c_ptr
2130 if(c_associated(b, c_loc(a))) &
2131 stop 'b and a do not point to same target'
2132 end subroutine association_test
2135 @item @emph{See also}:
2136 @ref{C_ASSOCIATED}, @ref{C_FUNLOC}, @ref{C_F_POINTER}, @ref{C_F_PROCPOINTER}
2141 @section @code{C_SIZEOF} --- Size in bytes of an expression
2143 @cindex expression size
2144 @cindex size of an expression
2147 @item @emph{Description}:
2148 @code{C_SIZEOF(X)} calculates the number of bytes of storage the
2149 expression @code{X} occupies.
2151 @item @emph{Standard}:
2157 @item @emph{Syntax}:
2158 @code{N = C_SIZEOF(X)}
2160 @item @emph{Arguments}:
2161 @multitable @columnfractions .15 .70
2162 @item @var{X} @tab The argument shall be of any type, rank or shape.
2165 @item @emph{Return value}:
2166 The return value is of type integer and of the system-dependent kind
2167 @var{C_SIZE_T} (from the @var{ISO_C_BINDING} module). Its value is the
2168 number of bytes occupied by the argument. If the argument has the
2169 @code{POINTER} attribute, the number of bytes of the storage area pointed
2170 to is returned. If the argument is of a derived type with @code{POINTER}
2171 or @code{ALLOCATABLE} components, the return value doesn't account for
2172 the sizes of the data pointed to by these components.
2174 @item @emph{Example}:
2178 real(c_float) :: r, s(5)
2179 print *, (c_sizeof(s)/c_sizeof(r) == 5)
2182 The example will print @code{.TRUE.} unless you are using a platform
2183 where default @code{REAL} variables are unusually padded.
2185 @item @emph{See also}:
2191 @section @code{CEILING} --- Integer ceiling function
2194 @cindex rounding, ceiling
2197 @item @emph{Description}:
2198 @code{CEILING(A)} returns the least integer greater than or equal to @var{A}.
2200 @item @emph{Standard}:
2201 Fortran 95 and later
2206 @item @emph{Syntax}:
2207 @code{RESULT = CEILING(A [, KIND])}
2209 @item @emph{Arguments}:
2210 @multitable @columnfractions .15 .70
2211 @item @var{A} @tab The type shall be @code{REAL}.
2212 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
2213 expression indicating the kind parameter of the result.
2216 @item @emph{Return value}:
2217 The return value is of type @code{INTEGER(KIND)} if @var{KIND} is present
2218 and a default-kind @code{INTEGER} otherwise.
2220 @item @emph{Example}:
2222 program test_ceiling
2225 print *, ceiling(x) ! returns 64
2226 print *, ceiling(y) ! returns -63
2227 end program test_ceiling
2230 @item @emph{See also}:
2231 @ref{FLOOR}, @ref{NINT}
2238 @section @code{CHAR} --- Character conversion function
2240 @cindex conversion, to character
2243 @item @emph{Description}:
2244 @code{CHAR(I [, KIND])} returns the character represented by the integer @var{I}.
2246 @item @emph{Standard}:
2247 Fortran 77 and later
2252 @item @emph{Syntax}:
2253 @code{RESULT = CHAR(I [, KIND])}
2255 @item @emph{Arguments}:
2256 @multitable @columnfractions .15 .70
2257 @item @var{I} @tab The type shall be @code{INTEGER}.
2258 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
2259 expression indicating the kind parameter of the result.
2262 @item @emph{Return value}:
2263 The return value is of type @code{CHARACTER(1)}
2265 @item @emph{Example}:
2271 print *, i, c ! returns 'J'
2272 end program test_char
2276 See @ref{ICHAR} for a discussion of converting between numerical values
2277 and formatted string representations.
2279 @item @emph{See also}:
2280 @ref{ACHAR}, @ref{IACHAR}, @ref{ICHAR}
2287 @section @code{CHDIR} --- Change working directory
2289 @cindex system, working directory
2292 @item @emph{Description}:
2293 Change current working directory to a specified path.
2295 This intrinsic is provided in both subroutine and function forms; however,
2296 only one form can be used in any given program unit.
2298 @item @emph{Standard}:
2302 Subroutine, function
2304 @item @emph{Syntax}:
2305 @multitable @columnfractions .80
2306 @item @code{CALL CHDIR(NAME [, STATUS])}
2307 @item @code{STATUS = CHDIR(NAME)}
2310 @item @emph{Arguments}:
2311 @multitable @columnfractions .15 .70
2312 @item @var{NAME} @tab The type shall be @code{CHARACTER} of default
2313 kind and shall specify a valid path within the file system.
2314 @item @var{STATUS} @tab (Optional) @code{INTEGER} status flag of the default
2315 kind. Returns 0 on success, and a system specific and nonzero error code
2319 @item @emph{Example}:
2322 CHARACTER(len=255) :: path
2324 WRITE(*,*) TRIM(path)
2327 WRITE(*,*) TRIM(path)
2331 @item @emph{See also}:
2338 @section @code{CHMOD} --- Change access permissions of files
2340 @cindex file system, change access mode
2343 @item @emph{Description}:
2344 @code{CHMOD} changes the permissions of a file. This function invokes
2345 @code{/bin/chmod} and might therefore not work on all platforms.
2347 This intrinsic is provided in both subroutine and function forms; however,
2348 only one form can be used in any given program unit.
2350 @item @emph{Standard}:
2354 Subroutine, function
2356 @item @emph{Syntax}:
2357 @multitable @columnfractions .80
2358 @item @code{CALL CHMOD(NAME, MODE[, STATUS])}
2359 @item @code{STATUS = CHMOD(NAME, MODE)}
2362 @item @emph{Arguments}:
2363 @multitable @columnfractions .15 .70
2365 @item @var{NAME} @tab Scalar @code{CHARACTER} of default kind with the
2366 file name. Trailing blanks are ignored unless the character
2367 @code{achar(0)} is present, then all characters up to and excluding
2368 @code{achar(0)} are used as the file name.
2370 @item @var{MODE} @tab Scalar @code{CHARACTER} of default kind giving the
2371 file permission. @var{MODE} uses the same syntax as the @var{MODE}
2372 argument of @code{/bin/chmod}.
2374 @item @var{STATUS} @tab (optional) scalar @code{INTEGER}, which is
2375 @code{0} on success and nonzero otherwise.
2378 @item @emph{Return value}:
2379 In either syntax, @var{STATUS} is set to @code{0} on success and nonzero
2382 @item @emph{Example}:
2383 @code{CHMOD} as subroutine
2388 call chmod('test.dat','u+x',status)
2389 print *, 'Status: ', status
2390 end program chmod_test
2392 @code{CHMOD} as function:
2397 status = chmod('test.dat','u+x')
2398 print *, 'Status: ', status
2399 end program chmod_test
2407 @section @code{CMPLX} --- Complex conversion function
2409 @cindex complex numbers, conversion to
2410 @cindex conversion, to complex
2413 @item @emph{Description}:
2414 @code{CMPLX(X [, Y [, KIND]])} returns a complex number where @var{X} is converted to
2415 the real component. If @var{Y} is present it is converted to the imaginary
2416 component. If @var{Y} is not present then the imaginary component is set to
2417 0.0. If @var{X} is complex then @var{Y} must not be present.
2419 @item @emph{Standard}:
2420 Fortran 77 and later
2425 @item @emph{Syntax}:
2426 @code{RESULT = CMPLX(X [, Y [, KIND]])}
2428 @item @emph{Arguments}:
2429 @multitable @columnfractions .15 .70
2430 @item @var{X} @tab The type may be @code{INTEGER}, @code{REAL},
2432 @item @var{Y} @tab (Optional; only allowed if @var{X} is not
2433 @code{COMPLEX}.) May be @code{INTEGER} or @code{REAL}.
2434 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
2435 expression indicating the kind parameter of the result.
2438 @item @emph{Return value}:
2439 The return value is of @code{COMPLEX} type, with a kind equal to
2440 @var{KIND} if it is specified. If @var{KIND} is not specified, the
2441 result is of the default @code{COMPLEX} kind, regardless of the kinds of
2442 @var{X} and @var{Y}.
2444 @item @emph{Example}:
2451 print *, z, cmplx(x)
2452 end program test_cmplx
2455 @item @emph{See also}:
2461 @node COMMAND_ARGUMENT_COUNT
2462 @section @code{COMMAND_ARGUMENT_COUNT} --- Get number of command line arguments
2463 @fnindex COMMAND_ARGUMENT_COUNT
2464 @cindex command-line arguments
2465 @cindex command-line arguments, number of
2466 @cindex arguments, to program
2469 @item @emph{Description}:
2470 @code{COMMAND_ARGUMENT_COUNT()} returns the number of arguments passed on the
2471 command line when the containing program was invoked.
2473 @item @emph{Standard}:
2474 Fortran 2003 and later
2479 @item @emph{Syntax}:
2480 @code{RESULT = COMMAND_ARGUMENT_COUNT()}
2482 @item @emph{Arguments}:
2483 @multitable @columnfractions .15 .70
2487 @item @emph{Return value}:
2488 The return value is of type @code{INTEGER(4)}
2490 @item @emph{Example}:
2492 program test_command_argument_count
2494 count = command_argument_count()
2496 end program test_command_argument_count
2499 @item @emph{See also}:
2500 @ref{GET_COMMAND}, @ref{GET_COMMAND_ARGUMENT}
2506 @section @code{COMPLEX} --- Complex conversion function
2508 @cindex complex numbers, conversion to
2509 @cindex conversion, to complex
2512 @item @emph{Description}:
2513 @code{COMPLEX(X, Y)} returns a complex number where @var{X} is converted
2514 to the real component and @var{Y} is converted to the imaginary
2517 @item @emph{Standard}:
2523 @item @emph{Syntax}:
2524 @code{RESULT = COMPLEX(X, Y)}
2526 @item @emph{Arguments}:
2527 @multitable @columnfractions .15 .70
2528 @item @var{X} @tab The type may be @code{INTEGER} or @code{REAL}.
2529 @item @var{Y} @tab The type may be @code{INTEGER} or @code{REAL}.
2532 @item @emph{Return value}:
2533 If @var{X} and @var{Y} are both of @code{INTEGER} type, then the return
2534 value is of default @code{COMPLEX} type.
2536 If @var{X} and @var{Y} are of @code{REAL} type, or one is of @code{REAL}
2537 type and one is of @code{INTEGER} type, then the return value is of
2538 @code{COMPLEX} type with a kind equal to that of the @code{REAL}
2539 argument with the highest precision.
2541 @item @emph{Example}:
2543 program test_complex
2546 print *, complex(i, x)
2547 end program test_complex
2550 @item @emph{See also}:
2557 @section @code{CONJG} --- Complex conjugate function
2560 @cindex complex conjugate
2563 @item @emph{Description}:
2564 @code{CONJG(Z)} returns the conjugate of @var{Z}. If @var{Z} is @code{(x, y)}
2565 then the result is @code{(x, -y)}
2567 @item @emph{Standard}:
2568 Fortran 77 and later, has overloads that are GNU extensions
2573 @item @emph{Syntax}:
2576 @item @emph{Arguments}:
2577 @multitable @columnfractions .15 .70
2578 @item @var{Z} @tab The type shall be @code{COMPLEX}.
2581 @item @emph{Return value}:
2582 The return value is of type @code{COMPLEX}.
2584 @item @emph{Example}:
2587 complex :: z = (2.0, 3.0)
2588 complex(8) :: dz = (2.71_8, -3.14_8)
2593 end program test_conjg
2596 @item @emph{Specific names}:
2597 @multitable @columnfractions .20 .20 .20 .25
2598 @item Name @tab Argument @tab Return type @tab Standard
2599 @item @code{DCONJG(Z)} @tab @code{COMPLEX(8) Z} @tab @code{COMPLEX(8)} @tab GNU extension
2606 @section @code{COS} --- Cosine function
2612 @cindex trigonometric function, cosine
2616 @item @emph{Description}:
2617 @code{COS(X)} computes the cosine of @var{X}.
2619 @item @emph{Standard}:
2620 Fortran 77 and later, has overloads that are GNU extensions
2625 @item @emph{Syntax}:
2626 @code{RESULT = COS(X)}
2628 @item @emph{Arguments}:
2629 @multitable @columnfractions .15 .70
2630 @item @var{X} @tab The type shall be @code{REAL} or
2634 @item @emph{Return value}:
2635 The return value is of type @code{REAL} and it lies in the
2636 range @math{ -1 \leq \cos (x) \leq 1}. The kind type
2637 parameter is the same as @var{X}.
2639 @item @emph{Example}:
2644 end program test_cos
2647 @item @emph{Specific names}:
2648 @multitable @columnfractions .20 .20 .20 .25
2649 @item Name @tab Argument @tab Return type @tab Standard
2650 @item @code{DCOS(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab Fortran 77 and later
2651 @item @code{CCOS(X)} @tab @code{COMPLEX(4) X} @tab @code{COMPLEX(4)} @tab Fortran 77 and later
2652 @item @code{ZCOS(X)} @tab @code{COMPLEX(8) X} @tab @code{COMPLEX(8)} @tab GNU extension
2653 @item @code{CDCOS(X)} @tab @code{COMPLEX(8) X} @tab @code{COMPLEX(8)} @tab GNU extension
2656 @item @emph{See also}:
2657 Inverse function: @ref{ACOS}
2664 @section @code{COSH} --- Hyperbolic cosine function
2667 @cindex hyperbolic cosine
2668 @cindex hyperbolic function, cosine
2669 @cindex cosine, hyperbolic
2672 @item @emph{Description}:
2673 @code{COSH(X)} computes the hyperbolic cosine of @var{X}.
2675 @item @emph{Standard}:
2676 Fortran 77 and later
2681 @item @emph{Syntax}:
2684 @item @emph{Arguments}:
2685 @multitable @columnfractions .15 .70
2686 @item @var{X} @tab The type shall be @code{REAL}.
2689 @item @emph{Return value}:
2690 The return value is of type @code{REAL} and it is positive
2691 (@math{ \cosh (x) \geq 0 }. The return value is of the same
2694 @item @emph{Example}:
2697 real(8) :: x = 1.0_8
2699 end program test_cosh
2702 @item @emph{Specific names}:
2703 @multitable @columnfractions .20 .20 .20 .25
2704 @item Name @tab Argument @tab Return type @tab Standard
2705 @item @code{DCOSH(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab Fortran 77 and later
2708 @item @emph{See also}:
2709 Inverse function: @ref{ACOSH}
2716 @section @code{COUNT} --- Count function
2718 @cindex array, conditionally count elements
2719 @cindex array, element counting
2720 @cindex array, number of elements
2723 @item @emph{Description}:
2725 @code{COUNT(MASK [, DIM [, KIND]])} counts the number of @code{.TRUE.}
2726 elements of @var{MASK} along the dimension of @var{DIM}. If @var{DIM} is
2727 omitted it is taken to be @code{1}. @var{DIM} is a scaler of type
2728 @code{INTEGER} in the range of @math{1 /leq DIM /leq n)} where @math{n}
2729 is the rank of @var{MASK}.
2731 @item @emph{Standard}:
2732 Fortran 95 and later, with @var{KIND} argument Fortran 2003 and later
2735 Transformational function
2737 @item @emph{Syntax}:
2738 @code{RESULT = COUNT(MASK [, DIM [, KIND]])}
2740 @item @emph{Arguments}:
2741 @multitable @columnfractions .15 .70
2742 @item @var{MASK} @tab The type shall be @code{LOGICAL}.
2743 @item @var{DIM} @tab (Optional) The type shall be @code{INTEGER}.
2744 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
2745 expression indicating the kind parameter of the result.
2748 @item @emph{Return value}:
2749 The return value is of type @code{INTEGER} and of kind @var{KIND}. If
2750 @var{KIND} is absent, the return value is of default integer kind.
2751 The result has a rank equal to that of @var{MASK}.
2753 @item @emph{Example}:
2756 integer, dimension(2,3) :: a, b
2757 logical, dimension(2,3) :: mask
2758 a = reshape( (/ 1, 2, 3, 4, 5, 6 /), (/ 2, 3 /))
2759 b = reshape( (/ 0, 7, 3, 4, 5, 8 /), (/ 2, 3 /))
2760 print '(3i3)', a(1,:)
2761 print '(3i3)', a(2,:)
2763 print '(3i3)', b(1,:)
2764 print '(3i3)', b(2,:)
2767 print '(3l3)', mask(1,:)
2768 print '(3l3)', mask(2,:)
2770 print '(3i3)', count(mask)
2772 print '(3i3)', count(mask, 1)
2774 print '(3i3)', count(mask, 2)
2775 end program test_count
2782 @section @code{CPU_TIME} --- CPU elapsed time in seconds
2784 @cindex time, elapsed
2787 @item @emph{Description}:
2788 Returns a @code{REAL} value representing the elapsed CPU time in
2789 seconds. This is useful for testing segments of code to determine
2792 If a time source is available, time will be reported with microsecond
2793 resolution. If no time source is available, @var{TIME} is set to
2796 Note that @var{TIME} may contain a, system dependent, arbitrary offset
2797 and may not start with @code{0.0}. For @code{CPU_TIME}, the absolute
2798 value is meaningless, only differences between subsequent calls to
2799 this subroutine, as shown in the example below, should be used.
2802 @item @emph{Standard}:
2803 Fortran 95 and later
2808 @item @emph{Syntax}:
2809 @code{CALL CPU_TIME(TIME)}
2811 @item @emph{Arguments}:
2812 @multitable @columnfractions .15 .70
2813 @item @var{TIME} @tab The type shall be @code{REAL} with @code{INTENT(OUT)}.
2816 @item @emph{Return value}:
2819 @item @emph{Example}:
2821 program test_cpu_time
2822 real :: start, finish
2823 call cpu_time(start)
2824 ! put code to test here
2825 call cpu_time(finish)
2826 print '("Time = ",f6.3," seconds.")',finish-start
2827 end program test_cpu_time
2830 @item @emph{See also}:
2831 @ref{SYSTEM_CLOCK}, @ref{DATE_AND_TIME}
2837 @section @code{CSHIFT} --- Circular shift elements of an array
2839 @cindex array, shift circularly
2840 @cindex array, permutation
2841 @cindex array, rotate
2844 @item @emph{Description}:
2845 @code{CSHIFT(ARRAY, SHIFT [, DIM])} performs a circular shift on elements of
2846 @var{ARRAY} along the dimension of @var{DIM}. If @var{DIM} is omitted it is
2847 taken to be @code{1}. @var{DIM} is a scaler of type @code{INTEGER} in the
2848 range of @math{1 /leq DIM /leq n)} where @math{n} is the rank of @var{ARRAY}.
2849 If the rank of @var{ARRAY} is one, then all elements of @var{ARRAY} are shifted
2850 by @var{SHIFT} places. If rank is greater than one, then all complete rank one
2851 sections of @var{ARRAY} along the given dimension are shifted. Elements
2852 shifted out one end of each rank one section are shifted back in the other end.
2854 @item @emph{Standard}:
2855 Fortran 95 and later
2858 Transformational function
2860 @item @emph{Syntax}:
2861 @code{RESULT = CSHIFT(ARRAY, SHIFT [, DIM])}
2863 @item @emph{Arguments}:
2864 @multitable @columnfractions .15 .70
2865 @item @var{ARRAY} @tab Shall be an array of any type.
2866 @item @var{SHIFT} @tab The type shall be @code{INTEGER}.
2867 @item @var{DIM} @tab The type shall be @code{INTEGER}.
2870 @item @emph{Return value}:
2871 Returns an array of same type and rank as the @var{ARRAY} argument.
2873 @item @emph{Example}:
2876 integer, dimension(3,3) :: a
2877 a = reshape( (/ 1, 2, 3, 4, 5, 6, 7, 8, 9 /), (/ 3, 3 /))
2878 print '(3i3)', a(1,:)
2879 print '(3i3)', a(2,:)
2880 print '(3i3)', a(3,:)
2881 a = cshift(a, SHIFT=(/1, 2, -1/), DIM=2)
2883 print '(3i3)', a(1,:)
2884 print '(3i3)', a(2,:)
2885 print '(3i3)', a(3,:)
2886 end program test_cshift
2893 @section @code{CTIME} --- Convert a time into a string
2895 @cindex time, conversion to string
2896 @cindex conversion, to string
2899 @item @emph{Description}:
2900 @code{CTIME} converts a system time value, such as returned by
2901 @code{TIME8()}, to a string of the form @samp{Sat Aug 19 18:13:14 1995}.
2903 This intrinsic is provided in both subroutine and function forms; however,
2904 only one form can be used in any given program unit.
2906 @item @emph{Standard}:
2910 Subroutine, function
2912 @item @emph{Syntax}:
2913 @multitable @columnfractions .80
2914 @item @code{CALL CTIME(TIME, RESULT)}.
2915 @item @code{RESULT = CTIME(TIME)}, (not recommended).
2918 @item @emph{Arguments}:
2919 @multitable @columnfractions .15 .70
2920 @item @var{TIME} @tab The type shall be of type @code{INTEGER(KIND=8)}.
2921 @item @var{RESULT} @tab The type shall be of type @code{CHARACTER} and
2925 @item @emph{Return value}:
2926 The converted date and time as a string.
2928 @item @emph{Example}:
2932 character(len=30) :: date
2935 ! Do something, main part of the program
2938 print *, 'Program was started on ', date
2939 end program test_ctime
2942 @item @emph{See Also}:
2943 @ref{GMTIME}, @ref{LTIME}, @ref{TIME}, @ref{TIME8}
2949 @section @code{DATE_AND_TIME} --- Date and time subroutine
2950 @fnindex DATE_AND_TIME
2951 @cindex date, current
2952 @cindex current date
2953 @cindex time, current
2954 @cindex current time
2957 @item @emph{Description}:
2958 @code{DATE_AND_TIME(DATE, TIME, ZONE, VALUES)} gets the corresponding date and
2959 time information from the real-time system clock. @var{DATE} is
2960 @code{INTENT(OUT)} and has form ccyymmdd. @var{TIME} is @code{INTENT(OUT)} and
2961 has form hhmmss.sss. @var{ZONE} is @code{INTENT(OUT)} and has form (+-)hhmm,
2962 representing the difference with respect to Coordinated Universal Time (UTC).
2963 Unavailable time and date parameters return blanks.
2965 @var{VALUES} is @code{INTENT(OUT)} and provides the following:
2967 @multitable @columnfractions .15 .30 .40
2968 @item @tab @code{VALUE(1)}: @tab The year
2969 @item @tab @code{VALUE(2)}: @tab The month
2970 @item @tab @code{VALUE(3)}: @tab The day of the month
2971 @item @tab @code{VALUE(4)}: @tab Time difference with UTC in minutes
2972 @item @tab @code{VALUE(5)}: @tab The hour of the day
2973 @item @tab @code{VALUE(6)}: @tab The minutes of the hour
2974 @item @tab @code{VALUE(7)}: @tab The seconds of the minute
2975 @item @tab @code{VALUE(8)}: @tab The milliseconds of the second
2978 @item @emph{Standard}:
2979 Fortran 95 and later
2984 @item @emph{Syntax}:
2985 @code{CALL DATE_AND_TIME([DATE, TIME, ZONE, VALUES])}
2987 @item @emph{Arguments}:
2988 @multitable @columnfractions .15 .70
2989 @item @var{DATE} @tab (Optional) The type shall be @code{CHARACTER(LEN=8)}
2990 or larger, and of default kind.
2991 @item @var{TIME} @tab (Optional) The type shall be @code{CHARACTER(LEN=10)}
2992 or larger, and of default kind.
2993 @item @var{ZONE} @tab (Optional) The type shall be @code{CHARACTER(LEN=5)}
2994 or larger, and of default kind.
2995 @item @var{VALUES}@tab (Optional) The type shall be @code{INTEGER(8)}.
2998 @item @emph{Return value}:
3001 @item @emph{Example}:
3003 program test_time_and_date
3004 character(8) :: date
3005 character(10) :: time
3006 character(5) :: zone
3007 integer,dimension(8) :: values
3008 ! using keyword arguments
3009 call date_and_time(date,time,zone,values)
3010 call date_and_time(DATE=date,ZONE=zone)
3011 call date_and_time(TIME=time)
3012 call date_and_time(VALUES=values)
3013 print '(a,2x,a,2x,a)', date, time, zone
3014 print '(8i5))', values
3015 end program test_time_and_date
3018 @item @emph{See also}:
3019 @ref{CPU_TIME}, @ref{SYSTEM_CLOCK}
3025 @section @code{DBLE} --- Double conversion function
3027 @cindex conversion, to real
3030 @item @emph{Description}:
3031 @code{DBLE(A)} Converts @var{A} to double precision real type.
3033 @item @emph{Standard}:
3034 Fortran 77 and later
3039 @item @emph{Syntax}:
3040 @code{RESULT = DBLE(A)}
3042 @item @emph{Arguments}:
3043 @multitable @columnfractions .15 .70
3044 @item @var{A} @tab The type shall be @code{INTEGER}, @code{REAL},
3048 @item @emph{Return value}:
3049 The return value is of type double precision real.
3051 @item @emph{Example}:
3056 complex :: z = (2.3,1.14)
3057 print *, dble(x), dble(i), dble(z)
3058 end program test_dble
3061 @item @emph{See also}:
3062 @ref{DFLOAT}, @ref{FLOAT}, @ref{REAL}
3068 @section @code{DCMPLX} --- Double complex conversion function
3070 @cindex complex numbers, conversion to
3071 @cindex conversion, to complex
3074 @item @emph{Description}:
3075 @code{DCMPLX(X [,Y])} returns a double complex number where @var{X} is
3076 converted to the real component. If @var{Y} is present it is converted to the
3077 imaginary component. If @var{Y} is not present then the imaginary component is
3078 set to 0.0. If @var{X} is complex then @var{Y} must not be present.
3080 @item @emph{Standard}:
3086 @item @emph{Syntax}:
3087 @code{RESULT = DCMPLX(X [, Y])}
3089 @item @emph{Arguments}:
3090 @multitable @columnfractions .15 .70
3091 @item @var{X} @tab The type may be @code{INTEGER}, @code{REAL},
3093 @item @var{Y} @tab (Optional if @var{X} is not @code{COMPLEX}.) May be
3094 @code{INTEGER} or @code{REAL}.
3097 @item @emph{Return value}:
3098 The return value is of type @code{COMPLEX(8)}
3100 @item @emph{Example}:
3110 print *, dcmplx(x,i)
3111 end program test_dcmplx
3118 @section @code{DFLOAT} --- Double conversion function
3120 @cindex conversion, to real
3123 @item @emph{Description}:
3124 @code{DFLOAT(A)} Converts @var{A} to double precision real type.
3126 @item @emph{Standard}:
3132 @item @emph{Syntax}:
3133 @code{RESULT = DFLOAT(A)}
3135 @item @emph{Arguments}:
3136 @multitable @columnfractions .15 .70
3137 @item @var{A} @tab The type shall be @code{INTEGER}.
3140 @item @emph{Return value}:
3141 The return value is of type double precision real.
3143 @item @emph{Example}:
3148 end program test_dfloat
3151 @item @emph{See also}:
3152 @ref{DBLE}, @ref{FLOAT}, @ref{REAL}
3158 @section @code{DIGITS} --- Significant digits function
3160 @cindex model representation, significant digits
3163 @item @emph{Description}:
3164 @code{DIGITS(X)} returns the number of significant digits of the internal model
3165 representation of @var{X}. For example, on a system using a 32-bit
3166 floating point representation, a default real number would likely return 24.
3168 @item @emph{Standard}:
3169 Fortran 95 and later
3174 @item @emph{Syntax}:
3175 @code{RESULT = DIGITS(X)}
3177 @item @emph{Arguments}:
3178 @multitable @columnfractions .15 .70
3179 @item @var{X} @tab The type may be @code{INTEGER} or @code{REAL}.
3182 @item @emph{Return value}:
3183 The return value is of type @code{INTEGER}.
3185 @item @emph{Example}:
3188 integer :: i = 12345
3194 end program test_digits
3201 @section @code{DIM} --- Positive difference
3205 @cindex positive difference
3208 @item @emph{Description}:
3209 @code{DIM(X,Y)} returns the difference @code{X-Y} if the result is positive;
3210 otherwise returns zero.
3212 @item @emph{Standard}:
3213 Fortran 77 and later
3218 @item @emph{Syntax}:
3219 @code{RESULT = DIM(X, Y)}
3221 @item @emph{Arguments}:
3222 @multitable @columnfractions .15 .70
3223 @item @var{X} @tab The type shall be @code{INTEGER} or @code{REAL}
3224 @item @var{Y} @tab The type shall be the same type and kind as @var{X}.
3227 @item @emph{Return value}:
3228 The return value is of type @code{INTEGER} or @code{REAL}.
3230 @item @emph{Example}:
3236 x = dim(4.345_8, 2.111_8)
3239 end program test_dim
3242 @item @emph{Specific names}:
3243 @multitable @columnfractions .20 .20 .20 .25
3244 @item Name @tab Argument @tab Return type @tab Standard
3245 @item @code{IDIM(X,Y)} @tab @code{INTEGER(4) X,Y} @tab @code{INTEGER(4)} @tab Fortran 77 and later
3246 @item @code{DDIM(X,Y)} @tab @code{REAL(8) X,Y} @tab @code{REAL(8)} @tab Fortran 77 and later
3253 @section @code{DOT_PRODUCT} --- Dot product function
3254 @fnindex DOT_PRODUCT
3256 @cindex vector product
3257 @cindex product, vector
3260 @item @emph{Description}:
3261 @code{DOT_PRODUCT(VECTOR_A, VECTOR_B)} computes the dot product multiplication
3262 of two vectors @var{VECTOR_A} and @var{VECTOR_B}. The two vectors may be
3263 either numeric or logical and must be arrays of rank one and of equal size. If
3264 the vectors are @code{INTEGER} or @code{REAL}, the result is
3265 @code{SUM(VECTOR_A*VECTOR_B)}. If the vectors are @code{COMPLEX}, the result
3266 is @code{SUM(CONJG(VECTOR_A)*VECTOR_B)}. If the vectors are @code{LOGICAL},
3267 the result is @code{ANY(VECTOR_A .AND. VECTOR_B)}.
3269 @item @emph{Standard}:
3270 Fortran 95 and later
3273 Transformational function
3275 @item @emph{Syntax}:
3276 @code{RESULT = DOT_PRODUCT(VECTOR_A, VECTOR_B)}
3278 @item @emph{Arguments}:
3279 @multitable @columnfractions .15 .70
3280 @item @var{VECTOR_A} @tab The type shall be numeric or @code{LOGICAL}, rank 1.
3281 @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.
3284 @item @emph{Return value}:
3285 If the arguments are numeric, the return value is a scaler of numeric type,
3286 @code{INTEGER}, @code{REAL}, or @code{COMPLEX}. If the arguments are
3287 @code{LOGICAL}, the return value is @code{.TRUE.} or @code{.FALSE.}.
3289 @item @emph{Example}:
3291 program test_dot_prod
3292 integer, dimension(3) :: a, b
3299 print *, dot_product(a,b)
3300 end program test_dot_prod
3307 @section @code{DPROD} --- Double product function
3309 @cindex product, double-precision
3312 @item @emph{Description}:
3313 @code{DPROD(X,Y)} returns the product @code{X*Y}.
3315 @item @emph{Standard}:
3316 Fortran 77 and later
3321 @item @emph{Syntax}:
3322 @code{RESULT = DPROD(X, Y)}
3324 @item @emph{Arguments}:
3325 @multitable @columnfractions .15 .70
3326 @item @var{X} @tab The type shall be @code{REAL}.
3327 @item @var{Y} @tab The type shall be @code{REAL}.
3330 @item @emph{Return value}:
3331 The return value is of type @code{REAL(8)}.
3333 @item @emph{Example}:
3341 end program test_dprod
3348 @section @code{DREAL} --- Double real part function
3350 @cindex complex numbers, real part
3353 @item @emph{Description}:
3354 @code{DREAL(Z)} returns the real part of complex variable @var{Z}.
3356 @item @emph{Standard}:
3362 @item @emph{Syntax}:
3363 @code{RESULT = DREAL(A)}
3365 @item @emph{Arguments}:
3366 @multitable @columnfractions .15 .70
3367 @item @var{A} @tab The type shall be @code{COMPLEX(8)}.
3370 @item @emph{Return value}:
3371 The return value is of type @code{REAL(8)}.
3373 @item @emph{Example}:
3376 complex(8) :: z = (1.3_8,7.2_8)
3378 end program test_dreal
3381 @item @emph{See also}:
3389 @section @code{DTIME} --- Execution time subroutine (or function)
3391 @cindex time, elapsed
3392 @cindex elapsed time
3395 @item @emph{Description}:
3396 @code{DTIME(TARRAY, RESULT)} initially returns the number of seconds of runtime
3397 since the start of the process's execution in @var{RESULT}. @var{TARRAY}
3398 returns the user and system components of this time in @code{TARRAY(1)} and
3399 @code{TARRAY(2)} respectively. @var{RESULT} is equal to @code{TARRAY(1) +
3402 Subsequent invocations of @code{DTIME} return values accumulated since the
3403 previous invocation.
3405 On some systems, the underlying timings are represented using types with
3406 sufficiently small limits that overflows (wrap around) are possible, such as
3407 32-bit types. Therefore, the values returned by this intrinsic might be, or
3408 become, negative, or numerically less than previous values, during a single
3409 run of the compiled program.
3411 Please note, that this implementation is thread safe if used within OpenMP
3412 directives, i.e., its state will be consistent while called from multiple
3413 threads. However, if @code{DTIME} is called from multiple threads, the result
3414 is still the time since the last invocation. This may not give the intended
3415 results. If possible, use @code{CPU_TIME} instead.
3417 This intrinsic is provided in both subroutine and function forms; however,
3418 only one form can be used in any given program unit.
3420 @var{TARRAY} and @var{RESULT} are @code{INTENT(OUT)} and provide the following:
3422 @multitable @columnfractions .15 .30 .40
3423 @item @tab @code{TARRAY(1)}: @tab User time in seconds.
3424 @item @tab @code{TARRAY(2)}: @tab System time in seconds.
3425 @item @tab @code{RESULT}: @tab Run time since start in seconds.
3428 @item @emph{Standard}:
3432 Subroutine, function
3434 @item @emph{Syntax}:
3435 @multitable @columnfractions .80
3436 @item @code{CALL DTIME(TARRAY, RESULT)}.
3437 @item @code{RESULT = DTIME(TARRAY)}, (not recommended).
3440 @item @emph{Arguments}:
3441 @multitable @columnfractions .15 .70
3442 @item @var{TARRAY}@tab The type shall be @code{REAL, DIMENSION(2)}.
3443 @item @var{RESULT}@tab The type shall be @code{REAL}.
3446 @item @emph{Return value}:
3447 Elapsed time in seconds since the last invocation or since the start of program
3448 execution if not called before.
3450 @item @emph{Example}:
3454 real, dimension(2) :: tarray
3456 call dtime(tarray, result)
3460 do i=1,100000000 ! Just a delay
3463 call dtime(tarray, result)
3467 end program test_dtime
3470 @item @emph{See also}:
3478 @section @code{EOSHIFT} --- End-off shift elements of an array
3480 @cindex array, shift
3483 @item @emph{Description}:
3484 @code{EOSHIFT(ARRAY, SHIFT[, BOUNDARY, DIM])} performs an end-off shift on
3485 elements of @var{ARRAY} along the dimension of @var{DIM}. If @var{DIM} is
3486 omitted it is taken to be @code{1}. @var{DIM} is a scaler of type
3487 @code{INTEGER} in the range of @math{1 /leq DIM /leq n)} where @math{n} is the
3488 rank of @var{ARRAY}. If the rank of @var{ARRAY} is one, then all elements of
3489 @var{ARRAY} are shifted by @var{SHIFT} places. If rank is greater than one,
3490 then all complete rank one sections of @var{ARRAY} along the given dimension are
3491 shifted. Elements shifted out one end of each rank one section are dropped. If
3492 @var{BOUNDARY} is present then the corresponding value of from @var{BOUNDARY}
3493 is copied back in the other end. If @var{BOUNDARY} is not present then the
3494 following are copied in depending on the type of @var{ARRAY}.
3496 @multitable @columnfractions .15 .80
3497 @item @emph{Array Type} @tab @emph{Boundary Value}
3498 @item Numeric @tab 0 of the type and kind of @var{ARRAY}.
3499 @item Logical @tab @code{.FALSE.}.
3500 @item Character(@var{len}) @tab @var{len} blanks.
3503 @item @emph{Standard}:
3504 Fortran 95 and later
3507 Transformational function
3509 @item @emph{Syntax}:
3510 @code{RESULT = EOSHIFT(ARRAY, SHIFT [, BOUNDARY, DIM])}
3512 @item @emph{Arguments}:
3513 @multitable @columnfractions .15 .70
3514 @item @var{ARRAY} @tab May be any type, not scaler.
3515 @item @var{SHIFT} @tab The type shall be @code{INTEGER}.
3516 @item @var{BOUNDARY} @tab Same type as @var{ARRAY}.
3517 @item @var{DIM} @tab The type shall be @code{INTEGER}.
3520 @item @emph{Return value}:
3521 Returns an array of same type and rank as the @var{ARRAY} argument.
3523 @item @emph{Example}:
3525 program test_eoshift
3526 integer, dimension(3,3) :: a
3527 a = reshape( (/ 1, 2, 3, 4, 5, 6, 7, 8, 9 /), (/ 3, 3 /))
3528 print '(3i3)', a(1,:)
3529 print '(3i3)', a(2,:)
3530 print '(3i3)', a(3,:)
3531 a = EOSHIFT(a, SHIFT=(/1, 2, 1/), BOUNDARY=-5, DIM=2)
3533 print '(3i3)', a(1,:)
3534 print '(3i3)', a(2,:)
3535 print '(3i3)', a(3,:)
3536 end program test_eoshift
3543 @section @code{EPSILON} --- Epsilon function
3545 @cindex model representation, epsilon
3548 @item @emph{Description}:
3549 @code{EPSILON(X)} returns a nearly negligible number relative to @code{1}.
3551 @item @emph{Standard}:
3552 Fortran 95 and later
3557 @item @emph{Syntax}:
3558 @code{RESULT = EPSILON(X)}
3560 @item @emph{Arguments}:
3561 @multitable @columnfractions .15 .70
3562 @item @var{X} @tab The type shall be @code{REAL}.
3565 @item @emph{Return value}:
3566 The return value is of same type as the argument.
3568 @item @emph{Example}:
3570 program test_epsilon
3575 end program test_epsilon
3582 @section @code{ERF} --- Error function
3584 @cindex error function
3587 @item @emph{Description}:
3588 @code{ERF(X)} computes the error function of @var{X}.
3590 @item @emph{Standard}:
3591 Fortran 2008 and later
3596 @item @emph{Syntax}:
3597 @code{RESULT = ERF(X)}
3599 @item @emph{Arguments}:
3600 @multitable @columnfractions .15 .70
3601 @item @var{X} @tab The type shall be @code{REAL}.
3604 @item @emph{Return value}:
3605 The return value is of type @code{REAL}, of the same kind as
3606 @var{X} and lies in the range @math{-1 \leq erf (x) \leq 1 }.
3608 @item @emph{Example}:
3611 real(8) :: x = 0.17_8
3613 end program test_erf
3616 @item @emph{Specific names}:
3617 @multitable @columnfractions .20 .20 .20 .25
3618 @item Name @tab Argument @tab Return type @tab Standard
3619 @item @code{DERF(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU extension
3626 @section @code{ERFC} --- Error function
3628 @cindex error function, complementary
3631 @item @emph{Description}:
3632 @code{ERFC(X)} computes the complementary error function of @var{X}.
3634 @item @emph{Standard}:
3635 Fortran 2008 and later
3640 @item @emph{Syntax}:
3641 @code{RESULT = ERFC(X)}
3643 @item @emph{Arguments}:
3644 @multitable @columnfractions .15 .70
3645 @item @var{X} @tab The type shall be @code{REAL}.
3648 @item @emph{Return value}:
3649 The return value is of type @code{REAL} and of the same kind as @var{X}.
3650 It lies in the range @math{ 0 \leq erfc (x) \leq 2 }.
3652 @item @emph{Example}:
3655 real(8) :: x = 0.17_8
3657 end program test_erfc
3660 @item @emph{Specific names}:
3661 @multitable @columnfractions .20 .20 .20 .25
3662 @item Name @tab Argument @tab Return type @tab Standard
3663 @item @code{DERFC(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU extension
3670 @section @code{ERFC_SCALED} --- Error function
3671 @fnindex ERFC_SCALED
3672 @cindex error function, complementary, exponentially-scaled
3675 @item @emph{Description}:
3676 @code{ERFC_SCALED(X)} computes the exponentially-scaled complementary
3677 error function of @var{X}.
3679 @item @emph{Standard}:
3680 Fortran 2008 and later
3685 @item @emph{Syntax}:
3686 @code{RESULT = ERFC_SCALED(X)}
3688 @item @emph{Arguments}:
3689 @multitable @columnfractions .15 .70
3690 @item @var{X} @tab The type shall be @code{REAL}.
3693 @item @emph{Return value}:
3694 The return value is of type @code{REAL} and of the same kind as @var{X}.
3696 @item @emph{Example}:
3698 program test_erfc_scaled
3699 real(8) :: x = 0.17_8
3701 end program test_erfc_scaled
3708 @section @code{ETIME} --- Execution time subroutine (or function)
3710 @cindex time, elapsed
3713 @item @emph{Description}:
3714 @code{ETIME(TARRAY, RESULT)} returns the number of seconds of runtime
3715 since the start of the process's execution in @var{RESULT}. @var{TARRAY}
3716 returns the user and system components of this time in @code{TARRAY(1)} and
3717 @code{TARRAY(2)} respectively. @var{RESULT} is equal to @code{TARRAY(1) + TARRAY(2)}.
3719 On some systems, the underlying timings are represented using types with
3720 sufficiently small limits that overflows (wrap around) are possible, such as
3721 32-bit types. Therefore, the values returned by this intrinsic might be, or
3722 become, negative, or numerically less than previous values, during a single
3723 run of the compiled program.
3725 This intrinsic is provided in both subroutine and function forms; however,
3726 only one form can be used in any given program unit.
3728 @var{TARRAY} and @var{RESULT} are @code{INTENT(OUT)} and provide the following:
3730 @multitable @columnfractions .15 .30 .60
3731 @item @tab @code{TARRAY(1)}: @tab User time in seconds.
3732 @item @tab @code{TARRAY(2)}: @tab System time in seconds.
3733 @item @tab @code{RESULT}: @tab Run time since start in seconds.
3736 @item @emph{Standard}:
3740 Subroutine, function
3742 @item @emph{Syntax}:
3743 @multitable @columnfractions .80
3744 @item @code{CALL ETIME(TARRAY, RESULT)}.
3745 @item @code{RESULT = ETIME(TARRAY)}, (not recommended).
3748 @item @emph{Arguments}:
3749 @multitable @columnfractions .15 .70
3750 @item @var{TARRAY}@tab The type shall be @code{REAL, DIMENSION(2)}.
3751 @item @var{RESULT}@tab The type shall be @code{REAL}.
3754 @item @emph{Return value}:
3755 Elapsed time in seconds since the start of program execution.
3757 @item @emph{Example}:
3761 real, dimension(2) :: tarray
3763 call ETIME(tarray, result)
3767 do i=1,100000000 ! Just a delay
3770 call ETIME(tarray, result)
3774 end program test_etime
3777 @item @emph{See also}:
3785 @section @code{EXIT} --- Exit the program with status.
3787 @cindex program termination
3788 @cindex terminate program
3791 @item @emph{Description}:
3792 @code{EXIT} causes immediate termination of the program with status. If status
3793 is omitted it returns the canonical @emph{success} for the system. All Fortran
3794 I/O units are closed.
3796 @item @emph{Standard}:
3802 @item @emph{Syntax}:
3803 @code{CALL EXIT([STATUS])}
3805 @item @emph{Arguments}:
3806 @multitable @columnfractions .15 .70
3807 @item @var{STATUS} @tab Shall be an @code{INTEGER} of the default kind.
3810 @item @emph{Return value}:
3811 @code{STATUS} is passed to the parent process on exit.
3813 @item @emph{Example}:
3816 integer :: STATUS = 0
3817 print *, 'This program is going to exit.'
3819 end program test_exit
3822 @item @emph{See also}:
3823 @ref{ABORT}, @ref{KILL}
3829 @section @code{EXP} --- Exponential function
3835 @cindex exponential function
3836 @cindex logarithmic function, inverse
3839 @item @emph{Description}:
3840 @code{EXP(X)} computes the base @math{e} exponential of @var{X}.
3842 @item @emph{Standard}:
3843 Fortran 77 and later, has overloads that are GNU extensions
3848 @item @emph{Syntax}:
3849 @code{RESULT = EXP(X)}
3851 @item @emph{Arguments}:
3852 @multitable @columnfractions .15 .70
3853 @item @var{X} @tab The type shall be @code{REAL} or
3857 @item @emph{Return value}:
3858 The return value has same type and kind as @var{X}.
3860 @item @emph{Example}:
3865 end program test_exp
3868 @item @emph{Specific names}:
3869 @multitable @columnfractions .20 .20 .20 .25
3870 @item Name @tab Argument @tab Return type @tab Standard
3871 @item @code{DEXP(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab Fortran 77 and later
3872 @item @code{CEXP(X)} @tab @code{COMPLEX(4) X} @tab @code{COMPLEX(4)} @tab Fortran 77 and later
3873 @item @code{ZEXP(X)} @tab @code{COMPLEX(8) X} @tab @code{COMPLEX(8)} @tab GNU extension
3874 @item @code{CDEXP(X)} @tab @code{COMPLEX(8) X} @tab @code{COMPLEX(8)} @tab GNU extension
3881 @section @code{EXPONENT} --- Exponent function
3883 @cindex real number, exponent
3884 @cindex floating point, exponent
3887 @item @emph{Description}:
3888 @code{EXPONENT(X)} returns the value of the exponent part of @var{X}. If @var{X}
3889 is zero the value returned is zero.
3891 @item @emph{Standard}:
3892 Fortran 95 and later
3897 @item @emph{Syntax}:
3898 @code{RESULT = EXPONENT(X)}
3900 @item @emph{Arguments}:
3901 @multitable @columnfractions .15 .70
3902 @item @var{X} @tab The type shall be @code{REAL}.
3905 @item @emph{Return value}:
3906 The return value is of type default @code{INTEGER}.
3908 @item @emph{Example}:
3910 program test_exponent
3915 print *, exponent(0.0)
3916 end program test_exponent
3923 @section @code{FDATE} --- Get the current time as a string
3925 @cindex time, current
3926 @cindex current time
3927 @cindex date, current
3928 @cindex current date
3931 @item @emph{Description}:
3932 @code{FDATE(DATE)} returns the current date (using the same format as
3933 @code{CTIME}) in @var{DATE}. It is equivalent to @code{CALL CTIME(DATE,
3936 This intrinsic is provided in both subroutine and function forms; however,
3937 only one form can be used in any given program unit.
3939 @var{DATE} is an @code{INTENT(OUT)} @code{CHARACTER} variable of the
3942 @item @emph{Standard}:
3946 Subroutine, function
3948 @item @emph{Syntax}:
3949 @multitable @columnfractions .80
3950 @item @code{CALL FDATE(DATE)}.
3951 @item @code{DATE = FDATE()}, (not recommended).
3954 @item @emph{Arguments}:
3955 @multitable @columnfractions .15 .70
3956 @item @var{DATE}@tab The type shall be of type @code{CHARACTER} of the
3960 @item @emph{Return value}:
3961 The current date as a string.
3963 @item @emph{Example}:
3967 character(len=30) :: date
3969 print *, 'Program started on ', date
3970 do i = 1, 100000000 ! Just a delay
3974 print *, 'Program ended on ', date
3975 end program test_fdate
3982 @section @code{FLOAT} --- Convert integer to default real
3984 @cindex conversion, to real
3987 @item @emph{Description}:
3988 @code{FLOAT(A)} converts the integer @var{A} to a default real value.
3990 @item @emph{Standard}:
3991 Fortran 77 and later
3996 @item @emph{Syntax}:
3997 @code{RESULT = FLOAT(A)}
3999 @item @emph{Arguments}:
4000 @multitable @columnfractions .15 .70
4001 @item @var{A} @tab The type shall be @code{INTEGER}.
4004 @item @emph{Return value}:
4005 The return value is of type default @code{REAL}.
4007 @item @emph{Example}:
4011 if (float(i) /= 1.) call abort
4012 end program test_float
4015 @item @emph{See also}:
4016 @ref{DBLE}, @ref{DFLOAT}, @ref{REAL}
4022 @section @code{FGET} --- Read a single character in stream mode from stdin
4024 @cindex read character, stream mode
4025 @cindex stream mode, read character
4026 @cindex file operation, read character
4029 @item @emph{Description}:
4030 Read a single character in stream mode from stdin by bypassing normal
4031 formatted output. Stream I/O should not be mixed with normal record-oriented
4032 (formatted or unformatted) I/O on the same unit; the results are unpredictable.
4034 This intrinsic is provided in both subroutine and function forms; however,
4035 only one form can be used in any given program unit.
4037 Note that the @code{FGET} intrinsic is provided for backwards compatibility with
4038 @command{g77}. GNU Fortran provides the Fortran 2003 Stream facility.
4039 Programmers should consider the use of new stream IO feature in new code
4040 for future portability. See also @ref{Fortran 2003 status}.
4042 @item @emph{Standard}:
4046 Subroutine, function
4048 @item @emph{Syntax}:
4049 @code{CALL FGET(C [, STATUS])}
4051 @item @emph{Arguments}:
4052 @multitable @columnfractions .15 .70
4053 @item @var{C} @tab The type shall be @code{CHARACTER} and of default
4055 @item @var{STATUS} @tab (Optional) status flag of type @code{INTEGER}.
4056 Returns 0 on success, -1 on end-of-file, and a system specific positive
4057 error code otherwise.
4060 @item @emph{Example}:
4063 INTEGER, PARAMETER :: strlen = 100
4064 INTEGER :: status, i = 1
4065 CHARACTER(len=strlen) :: str = ""
4067 WRITE (*,*) 'Enter text:'
4069 CALL fget(str(i:i), status)
4070 if (status /= 0 .OR. i > strlen) exit
4073 WRITE (*,*) TRIM(str)
4077 @item @emph{See also}:
4078 @ref{FGETC}, @ref{FPUT}, @ref{FPUTC}
4084 @section @code{FGETC} --- Read a single character in stream mode
4086 @cindex read character, stream mode
4087 @cindex stream mode, read character
4088 @cindex file operation, read character
4091 @item @emph{Description}:
4092 Read a single character in stream mode by bypassing normal formatted output.
4093 Stream I/O should not be mixed with normal record-oriented (formatted or
4094 unformatted) I/O on the same unit; the results are unpredictable.
4096 This intrinsic is provided in both subroutine and function forms; however,
4097 only one form can be used in any given program unit.
4099 Note that the @code{FGET} intrinsic is provided for backwards compatibility
4100 with @command{g77}. GNU Fortran provides the Fortran 2003 Stream facility.
4101 Programmers should consider the use of new stream IO feature in new code
4102 for future portability. See also @ref{Fortran 2003 status}.
4104 @item @emph{Standard}:
4108 Subroutine, function
4110 @item @emph{Syntax}:
4111 @code{CALL FGETC(UNIT, C [, STATUS])}
4113 @item @emph{Arguments}:
4114 @multitable @columnfractions .15 .70
4115 @item @var{UNIT} @tab The type shall be @code{INTEGER}.
4116 @item @var{C} @tab The type shall be @code{CHARACTER} and of default
4118 @item @var{STATUS} @tab (Optional) status flag of type @code{INTEGER}.
4119 Returns 0 on success, -1 on end-of-file and a system specific positive
4120 error code otherwise.
4123 @item @emph{Example}:
4126 INTEGER :: fd = 42, status
4129 OPEN(UNIT=fd, FILE="/etc/passwd", ACTION="READ", STATUS = "OLD")
4131 CALL fgetc(fd, c, status)
4132 IF (status /= 0) EXIT
4139 @item @emph{See also}:
4140 @ref{FGET}, @ref{FPUT}, @ref{FPUTC}
4146 @section @code{FLOOR} --- Integer floor function
4149 @cindex rounding, floor
4152 @item @emph{Description}:
4153 @code{FLOOR(A)} returns the greatest integer less than or equal to @var{X}.
4155 @item @emph{Standard}:
4156 Fortran 95 and later
4161 @item @emph{Syntax}:
4162 @code{RESULT = FLOOR(A [, KIND])}
4164 @item @emph{Arguments}:
4165 @multitable @columnfractions .15 .70
4166 @item @var{A} @tab The type shall be @code{REAL}.
4167 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
4168 expression indicating the kind parameter of the result.
4171 @item @emph{Return value}:
4172 The return value is of type @code{INTEGER(KIND)} if @var{KIND} is present
4173 and of default-kind @code{INTEGER} otherwise.
4175 @item @emph{Example}:
4180 print *, floor(x) ! returns 63
4181 print *, floor(y) ! returns -64
4182 end program test_floor
4185 @item @emph{See also}:
4186 @ref{CEILING}, @ref{NINT}
4193 @section @code{FLUSH} --- Flush I/O unit(s)
4195 @cindex file operation, flush
4198 @item @emph{Description}:
4199 Flushes Fortran unit(s) currently open for output. Without the optional
4200 argument, all units are flushed, otherwise just the unit specified.
4202 @item @emph{Standard}:
4208 @item @emph{Syntax}:
4209 @code{CALL FLUSH(UNIT)}
4211 @item @emph{Arguments}:
4212 @multitable @columnfractions .15 .70
4213 @item @var{UNIT} @tab (Optional) The type shall be @code{INTEGER}.
4217 Beginning with the Fortran 2003 standard, there is a @code{FLUSH}
4218 statement that should be preferred over the @code{FLUSH} intrinsic.
4225 @section @code{FNUM} --- File number function
4227 @cindex file operation, file number
4230 @item @emph{Description}:
4231 @code{FNUM(UNIT)} returns the POSIX file descriptor number corresponding to the
4232 open Fortran I/O unit @code{UNIT}.
4234 @item @emph{Standard}:
4240 @item @emph{Syntax}:
4241 @code{RESULT = FNUM(UNIT)}
4243 @item @emph{Arguments}:
4244 @multitable @columnfractions .15 .70
4245 @item @var{UNIT} @tab The type shall be @code{INTEGER}.
4248 @item @emph{Return value}:
4249 The return value is of type @code{INTEGER}
4251 @item @emph{Example}:
4255 open (unit=10, status = "scratch")
4259 end program test_fnum
4266 @section @code{FPUT} --- Write a single character in stream mode to stdout
4268 @cindex write character, stream mode
4269 @cindex stream mode, write character
4270 @cindex file operation, write character
4273 @item @emph{Description}:
4274 Write a single character in stream mode to stdout by bypassing normal
4275 formatted output. Stream I/O should not be mixed with normal record-oriented
4276 (formatted or unformatted) I/O on the same unit; the results are unpredictable.
4278 This intrinsic is provided in both subroutine and function forms; however,
4279 only one form can be used in any given program unit.
4281 Note that the @code{FGET} intrinsic is provided for backwards compatibility with
4282 @command{g77}. GNU Fortran provides the Fortran 2003 Stream facility.
4283 Programmers should consider the use of new stream IO feature in new code
4284 for future portability. See also @ref{Fortran 2003 status}.
4286 @item @emph{Standard}:
4290 Subroutine, function
4292 @item @emph{Syntax}:
4293 @code{CALL FPUT(C [, STATUS])}
4295 @item @emph{Arguments}:
4296 @multitable @columnfractions .15 .70
4297 @item @var{C} @tab The type shall be @code{CHARACTER} and of default
4299 @item @var{STATUS} @tab (Optional) status flag of type @code{INTEGER}.
4300 Returns 0 on success, -1 on end-of-file and a system specific positive
4301 error code otherwise.
4304 @item @emph{Example}:
4307 CHARACTER(len=10) :: str = "gfortran"
4309 DO i = 1, len_trim(str)
4315 @item @emph{See also}:
4316 @ref{FPUTC}, @ref{FGET}, @ref{FGETC}
4322 @section @code{FPUTC} --- Write a single character in stream mode
4324 @cindex write character, stream mode
4325 @cindex stream mode, write character
4326 @cindex file operation, write character
4329 @item @emph{Description}:
4330 Write a single character in stream mode by bypassing normal formatted
4331 output. Stream I/O should not be mixed with normal record-oriented
4332 (formatted or unformatted) I/O on the same unit; the results are unpredictable.
4334 This intrinsic is provided in both subroutine and function forms; however,
4335 only one form can be used in any given program unit.
4337 Note that the @code{FGET} intrinsic is provided for backwards compatibility with
4338 @command{g77}. GNU Fortran provides the Fortran 2003 Stream facility.
4339 Programmers should consider the use of new stream IO feature in new code
4340 for future portability. See also @ref{Fortran 2003 status}.
4342 @item @emph{Standard}:
4346 Subroutine, function
4348 @item @emph{Syntax}:
4349 @code{CALL FPUTC(UNIT, C [, STATUS])}
4351 @item @emph{Arguments}:
4352 @multitable @columnfractions .15 .70
4353 @item @var{UNIT} @tab The type shall be @code{INTEGER}.
4354 @item @var{C} @tab The type shall be @code{CHARACTER} and of default
4356 @item @var{STATUS} @tab (Optional) status flag of type @code{INTEGER}.
4357 Returns 0 on success, -1 on end-of-file and a system specific positive
4358 error code otherwise.
4361 @item @emph{Example}:
4364 CHARACTER(len=10) :: str = "gfortran"
4365 INTEGER :: fd = 42, i
4367 OPEN(UNIT = fd, FILE = "out", ACTION = "WRITE", STATUS="NEW")
4368 DO i = 1, len_trim(str)
4369 CALL fputc(fd, str(i:i))
4375 @item @emph{See also}:
4376 @ref{FPUT}, @ref{FGET}, @ref{FGETC}
4382 @section @code{FRACTION} --- Fractional part of the model representation
4384 @cindex real number, fraction
4385 @cindex floating point, fraction
4388 @item @emph{Description}:
4389 @code{FRACTION(X)} returns the fractional part of the model
4390 representation of @code{X}.
4392 @item @emph{Standard}:
4393 Fortran 95 and later
4398 @item @emph{Syntax}:
4399 @code{Y = FRACTION(X)}
4401 @item @emph{Arguments}:
4402 @multitable @columnfractions .15 .70
4403 @item @var{X} @tab The type of the argument shall be a @code{REAL}.
4406 @item @emph{Return value}:
4407 The return value is of the same type and kind as the argument.
4408 The fractional part of the model representation of @code{X} is returned;
4409 it is @code{X * RADIX(X)**(-EXPONENT(X))}.
4411 @item @emph{Example}:
4413 program test_fraction
4416 print *, fraction(x), x * radix(x)**(-exponent(x))
4417 end program test_fraction
4425 @section @code{FREE} --- Frees memory
4427 @cindex pointer, cray
4430 @item @emph{Description}:
4431 Frees memory previously allocated by @code{MALLOC()}. The @code{FREE}
4432 intrinsic is an extension intended to be used with Cray pointers, and is
4433 provided in GNU Fortran to allow user to compile legacy code. For
4434 new code using Fortran 95 pointers, the memory de-allocation intrinsic is
4437 @item @emph{Standard}:
4443 @item @emph{Syntax}:
4444 @code{CALL FREE(PTR)}
4446 @item @emph{Arguments}:
4447 @multitable @columnfractions .15 .70
4448 @item @var{PTR} @tab The type shall be @code{INTEGER}. It represents the
4449 location of the memory that should be de-allocated.
4452 @item @emph{Return value}:
4455 @item @emph{Example}:
4456 See @code{MALLOC} for an example.
4458 @item @emph{See also}:
4465 @section @code{FSEEK} --- Low level file positioning subroutine
4467 @cindex file operation, seek
4468 @cindex file operation, position
4471 @item @emph{Description}:
4472 Moves @var{UNIT} to the specified @var{OFFSET}. If @var{WHENCE}
4473 is set to 0, the @var{OFFSET} is taken as an absolute value @code{SEEK_SET},
4474 if set to 1, @var{OFFSET} is taken to be relative to the current position
4475 @code{SEEK_CUR}, and if set to 2 relative to the end of the file @code{SEEK_END}.
4476 On error, @var{STATUS} is set to a nonzero value. If @var{STATUS} the seek
4479 This intrinsic routine is not fully backwards compatible with @command{g77}.
4480 In @command{g77}, the @code{FSEEK} takes a statement label instead of a
4481 @var{STATUS} variable. If FSEEK is used in old code, change
4483 CALL FSEEK(UNIT, OFFSET, WHENCE, *label)
4488 CALL FSEEK(UNIT, OFFSET, WHENCE, status)
4489 IF (status /= 0) GOTO label
4492 Please note that GNU Fortran provides the Fortran 2003 Stream facility.
4493 Programmers should consider the use of new stream IO feature in new code
4494 for future portability. See also @ref{Fortran 2003 status}.
4496 @item @emph{Standard}:
4502 @item @emph{Syntax}:
4503 @code{CALL FSEEK(UNIT, OFFSET, WHENCE[, STATUS])}
4505 @item @emph{Arguments}:
4506 @multitable @columnfractions .15 .70
4507 @item @var{UNIT} @tab Shall be a scalar of type @code{INTEGER}.
4508 @item @var{OFFSET} @tab Shall be a scalar of type @code{INTEGER}.
4509 @item @var{WHENCE} @tab Shall be a scalar of type @code{INTEGER}.
4510 Its value shall be either 0, 1 or 2.
4511 @item @var{STATUS} @tab (Optional) shall be a scalar of type
4515 @item @emph{Example}:
4518 INTEGER, PARAMETER :: SEEK_SET = 0, SEEK_CUR = 1, SEEK_END = 2
4519 INTEGER :: fd, offset, ierr
4525 OPEN(UNIT=fd, FILE="fseek.test")
4526 CALL FSEEK(fd, offset, SEEK_SET, ierr) ! move to OFFSET
4527 print *, FTELL(fd), ierr
4529 CALL FSEEK(fd, 0, SEEK_END, ierr) ! move to end
4530 print *, FTELL(fd), ierr
4532 CALL FSEEK(fd, 0, SEEK_SET, ierr) ! move to beginning
4533 print *, FTELL(fd), ierr
4539 @item @emph{See also}:
4546 @section @code{FSTAT} --- Get file status
4548 @cindex file system, file status
4551 @item @emph{Description}:
4552 @code{FSTAT} is identical to @ref{STAT}, except that information about an
4553 already opened file is obtained.
4555 The elements in @code{BUFF} are the same as described by @ref{STAT}.
4557 This intrinsic is provided in both subroutine and function forms; however,
4558 only one form can be used in any given program unit.
4560 @item @emph{Standard}:
4564 Subroutine, function
4566 @item @emph{Syntax}:
4567 @code{CALL FSTAT(UNIT, BUFF [, STATUS])}
4569 @item @emph{Arguments}:
4570 @multitable @columnfractions .15 .70
4571 @item @var{UNIT} @tab An open I/O unit number of type @code{INTEGER}.
4572 @item @var{BUFF} @tab The type shall be @code{INTEGER(4), DIMENSION(13)}.
4573 @item @var{STATUS} @tab (Optional) status flag of type @code{INTEGER(4)}. Returns 0
4574 on success and a system specific error code otherwise.
4577 @item @emph{Example}:
4578 See @ref{STAT} for an example.
4580 @item @emph{See also}:
4581 To stat a link: @ref{LSTAT}, to stat a file: @ref{STAT}
4587 @section @code{FTELL} --- Current stream position
4589 @cindex file operation, position
4592 @item @emph{Description}:
4593 Retrieves the current position within an open file.
4595 This intrinsic is provided in both subroutine and function forms; however,
4596 only one form can be used in any given program unit.
4598 @item @emph{Standard}:
4602 Subroutine, function
4604 @item @emph{Syntax}:
4605 @multitable @columnfractions .80
4606 @item @code{CALL FTELL(UNIT, OFFSET)}
4607 @item @code{OFFSET = FTELL(UNIT)}
4610 @item @emph{Arguments}:
4611 @multitable @columnfractions .15 .70
4612 @item @var{OFFSET} @tab Shall of type @code{INTEGER}.
4613 @item @var{UNIT} @tab Shall of type @code{INTEGER}.
4616 @item @emph{Return value}:
4617 In either syntax, @var{OFFSET} is set to the current offset of unit
4618 number @var{UNIT}, or to @math{-1} if the unit is not currently open.
4620 @item @emph{Example}:
4624 OPEN(10, FILE="temp.dat")
4630 @item @emph{See also}:
4637 @section @code{GAMMA} --- Gamma function
4640 @cindex Gamma function
4641 @cindex Factorial function
4644 @item @emph{Description}:
4645 @code{GAMMA(X)} computes Gamma (@math{\Gamma}) of @var{X}. For positive,
4646 integer values of @var{X} the Gamma function simplifies to the factorial
4647 function @math{\Gamma(x)=(x-1)!}.
4651 \Gamma(x) = \int_0^\infty t^{x-1}{\rm e}^{-t}\,{\rm d}t
4655 @item @emph{Standard}:
4656 Fortran 2008 and later
4661 @item @emph{Syntax}:
4664 @item @emph{Arguments}:
4665 @multitable @columnfractions .15 .70
4666 @item @var{X} @tab Shall be of type @code{REAL} and neither zero
4667 nor a negative integer.
4670 @item @emph{Return value}:
4671 The return value is of type @code{REAL} of the same kind as @var{X}.
4673 @item @emph{Example}:
4677 x = gamma(x) ! returns 1.0
4678 end program test_gamma
4681 @item @emph{Specific names}:
4682 @multitable @columnfractions .20 .20 .20 .25
4683 @item Name @tab Argument @tab Return type @tab Standard
4684 @item @code{GAMMA(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab GNU Extension
4685 @item @code{DGAMMA(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU Extension
4688 @item @emph{See also}:
4689 Logarithm of the Gamma function: @ref{LOG_GAMMA}
4696 @section @code{GERROR} --- Get last system error message
4698 @cindex system, error handling
4701 @item @emph{Description}:
4702 Returns the system error message corresponding to the last system error.
4703 This resembles the functionality of @code{strerror(3)} in C.
4705 @item @emph{Standard}:
4711 @item @emph{Syntax}:
4712 @code{CALL GERROR(RESULT)}
4714 @item @emph{Arguments}:
4715 @multitable @columnfractions .15 .70
4716 @item @var{RESULT} @tab Shall of type @code{CHARACTER} and of default
4719 @item @emph{Example}:
4722 CHARACTER(len=100) :: msg
4728 @item @emph{See also}:
4729 @ref{IERRNO}, @ref{PERROR}
4735 @section @code{GETARG} --- Get command line arguments
4737 @cindex command-line arguments
4738 @cindex arguments, to program
4741 @item @emph{Description}:
4742 Retrieve the @var{POS}-th argument that was passed on the
4743 command line when the containing program was invoked.
4745 This intrinsic routine is provided for backwards compatibility with
4746 GNU Fortran 77. In new code, programmers should consider the use of
4747 the @ref{GET_COMMAND_ARGUMENT} intrinsic defined by the Fortran 2003
4750 @item @emph{Standard}:
4756 @item @emph{Syntax}:
4757 @code{CALL GETARG(POS, VALUE)}
4759 @item @emph{Arguments}:
4760 @multitable @columnfractions .15 .70
4761 @item @var{POS} @tab Shall be of type @code{INTEGER} and not wider than
4762 the default integer kind; @math{@var{POS} \geq 0}
4763 @item @var{VALUE} @tab Shall be of type @code{CHARACTER} and of default
4765 @item @var{VALUE} @tab Shall be of type @code{CHARACTER}.
4768 @item @emph{Return value}:
4769 After @code{GETARG} returns, the @var{VALUE} argument holds the
4770 @var{POS}th command line argument. If @var{VALUE} can not hold the
4771 argument, it is truncated to fit the length of @var{VALUE}. If there are
4772 less than @var{POS} arguments specified at the command line, @var{VALUE}
4773 will be filled with blanks. If @math{@var{POS} = 0}, @var{VALUE} is set
4774 to the name of the program (on systems that support this feature).
4776 @item @emph{Example}:
4780 CHARACTER(len=32) :: arg
4789 @item @emph{See also}:
4790 GNU Fortran 77 compatibility function: @ref{IARGC}
4792 Fortran 2003 functions and subroutines: @ref{GET_COMMAND},
4793 @ref{GET_COMMAND_ARGUMENT}, @ref{COMMAND_ARGUMENT_COUNT}
4799 @section @code{GET_COMMAND} --- Get the entire command line
4800 @fnindex GET_COMMAND
4801 @cindex command-line arguments
4802 @cindex arguments, to program
4805 @item @emph{Description}:
4806 Retrieve the entire command line that was used to invoke the program.
4808 @item @emph{Standard}:
4809 Fortran 2003 and later
4814 @item @emph{Syntax}:
4815 @code{CALL GET_COMMAND(COMMAND)}
4817 @item @emph{Arguments}:
4818 @multitable @columnfractions .15 .70
4819 @item @var{COMMAND} @tab Shall be of type @code{CHARACTER} and of default
4823 @item @emph{Return value}:
4824 Stores the entire command line that was used to invoke the program in
4825 @var{COMMAND}. If @var{COMMAND} is not large enough, the command will be
4828 @item @emph{Example}:
4830 PROGRAM test_get_command
4831 CHARACTER(len=255) :: cmd
4832 CALL get_command(cmd)
4833 WRITE (*,*) TRIM(cmd)
4837 @item @emph{See also}:
4838 @ref{GET_COMMAND_ARGUMENT}, @ref{COMMAND_ARGUMENT_COUNT}
4843 @node GET_COMMAND_ARGUMENT
4844 @section @code{GET_COMMAND_ARGUMENT} --- Get command line arguments
4845 @fnindex GET_COMMAND_ARGUMENT
4846 @cindex command-line arguments
4847 @cindex arguments, to program
4850 @item @emph{Description}:
4851 Retrieve the @var{NUMBER}-th argument that was passed on the
4852 command line when the containing program was invoked.
4854 @item @emph{Standard}:
4855 Fortran 2003 and later
4860 @item @emph{Syntax}:
4861 @code{CALL GET_COMMAND_ARGUMENT(NUMBER [, VALUE, LENGTH, STATUS])}
4863 @item @emph{Arguments}:
4864 @multitable @columnfractions .15 .70
4865 @item @var{NUMBER} @tab Shall be a scalar of type @code{INTEGER(4)},
4866 @math{@var{NUMBER} \geq 0}
4867 @item @var{VALUE} @tab Shall be a scalar of type @code{CHARACTER}
4868 and of default kind.
4869 @item @var{LENGTH} @tab (Option) Shall be a scalar of type @code{INTEGER(4)}.
4870 @item @var{STATUS} @tab (Option) Shall be a scalar of type @code{INTEGER(4)}.
4873 @item @emph{Return value}:
4874 After @code{GET_COMMAND_ARGUMENT} returns, the @var{VALUE} argument holds the
4875 @var{NUMBER}-th command line argument. If @var{VALUE} can not hold the argument, it is
4876 truncated to fit the length of @var{VALUE}. If there are less than @var{NUMBER}
4877 arguments specified at the command line, @var{VALUE} will be filled with blanks.
4878 If @math{@var{NUMBER} = 0}, @var{VALUE} is set to the name of the program (on systems
4879 that support this feature). The @var{LENGTH} argument contains the length of the
4880 @var{NUMBER}-th command line argument. If the argument retrival fails, @var{STATUS}
4881 is a positiv number; if @var{VALUE} contains a truncated command line argument,
4882 @var{STATUS} is -1; and otherwise the @var{STATUS} is zero.
4884 @item @emph{Example}:
4886 PROGRAM test_get_command_argument
4888 CHARACTER(len=32) :: arg
4892 CALL get_command_argument(i, arg)
4893 IF (LEN_TRIM(arg) == 0) EXIT
4895 WRITE (*,*) TRIM(arg)
4901 @item @emph{See also}:
4902 @ref{GET_COMMAND}, @ref{COMMAND_ARGUMENT_COUNT}
4908 @section @code{GETCWD} --- Get current working directory
4910 @cindex system, working directory
4913 @item @emph{Description}:
4914 Get current working directory.
4916 This intrinsic is provided in both subroutine and function forms; however,
4917 only one form can be used in any given program unit.
4919 @item @emph{Standard}:
4923 Subroutine, function
4925 @item @emph{Syntax}:
4926 @code{CALL GETCWD(C [, STATUS])}
4928 @item @emph{Arguments}:
4929 @multitable @columnfractions .15 .70
4930 @item @var{C} @tab The type shall be @code{CHARACTER} and of default kind.
4931 @item @var{STATUS} @tab (Optional) status flag. Returns 0 on success,
4932 a system specific and nonzero error code otherwise.
4935 @item @emph{Example}:
4938 CHARACTER(len=255) :: cwd
4940 WRITE(*,*) TRIM(cwd)
4944 @item @emph{See also}:
4951 @section @code{GETENV} --- Get an environmental variable
4953 @cindex environment variable
4956 @item @emph{Description}:
4957 Get the @var{VALUE} of the environmental variable @var{NAME}.
4959 This intrinsic routine is provided for backwards compatibility with
4960 GNU Fortran 77. In new code, programmers should consider the use of
4961 the @ref{GET_ENVIRONMENT_VARIABLE} intrinsic defined by the Fortran
4964 @item @emph{Standard}:
4970 @item @emph{Syntax}:
4971 @code{CALL GETENV(NAME, VALUE)}
4973 @item @emph{Arguments}:
4974 @multitable @columnfractions .15 .70
4975 @item @var{NAME} @tab Shall be of type @code{CHARACTER} and of default kind.
4976 @item @var{VALUE} @tab Shall be of type @code{CHARACTER} and of default kind.
4979 @item @emph{Return value}:
4980 Stores the value of @var{NAME} in @var{VALUE}. If @var{VALUE} is
4981 not large enough to hold the data, it is truncated. If @var{NAME}
4982 is not set, @var{VALUE} will be filled with blanks.
4984 @item @emph{Example}:
4987 CHARACTER(len=255) :: homedir
4988 CALL getenv("HOME", homedir)
4989 WRITE (*,*) TRIM(homedir)
4993 @item @emph{See also}:
4994 @ref{GET_ENVIRONMENT_VARIABLE}
4999 @node GET_ENVIRONMENT_VARIABLE
5000 @section @code{GET_ENVIRONMENT_VARIABLE} --- Get an environmental variable
5001 @fnindex GET_ENVIRONMENT_VARIABLE
5002 @cindex environment variable
5005 @item @emph{Description}:
5006 Get the @var{VALUE} of the environmental variable @var{NAME}.
5008 @item @emph{Standard}:
5009 Fortran 2003 and later
5014 @item @emph{Syntax}:
5015 @code{CALL GET_ENVIRONMENT_VARIABLE(NAME[, VALUE, LENGTH, STATUS, TRIM_NAME)}
5017 @item @emph{Arguments}:
5018 @multitable @columnfractions .15 .70
5019 @item @var{NAME} @tab Shall be a scalar of type @code{CHARACTER(1)}.
5020 @item @var{VALUE} @tab Shall be a scalar of type @code{CHARACTER(1)}.
5021 @item @var{LENGTH} @tab Shall be a scalar of type @code{INTEGER(4)}.
5022 @item @var{STATUS} @tab Shall be a scalar of type @code{INTEGER(4)}.
5023 @item @var{TRIM_NAME} @tab Shall be a scalar of type @code{LOGICAL(4)}.
5026 @item @emph{Return value}:
5027 Stores the value of @var{NAME} in @var{VALUE}. If @var{VALUE} is
5028 not large enough to hold the data, it is truncated. If @var{NAME}
5029 is not set, @var{VALUE} will be filled with blanks. Argument @var{LENGTH}
5030 contains the length needed for storing the environment variable @var{NAME}
5031 or zero if it is not present. @var{STATUS} is -1 if @var{VALUE} is present
5032 but too short for the environment variable; it is 1 if the environment
5033 variable does not exist and 2 if the processor does not support environment
5034 variables; in all other cases @var{STATUS} is zero. If @var{TRIM_NAME} is
5035 present with the value @code{.FALSE.}, the trailing blanks in @var{NAME}
5036 are significant; otherwise they are not part of the environment variable
5039 @item @emph{Example}:
5042 CHARACTER(len=255) :: homedir
5043 CALL get_environment_variable("HOME", homedir)
5044 WRITE (*,*) TRIM(homedir)
5052 @section @code{GETGID} --- Group ID function
5054 @cindex system, group id
5057 @item @emph{Description}:
5058 Returns the numerical group ID of the current process.
5060 @item @emph{Standard}:
5066 @item @emph{Syntax}:
5067 @code{RESULT = GETGID()}
5069 @item @emph{Return value}:
5070 The return value of @code{GETGID} is an @code{INTEGER} of the default
5074 @item @emph{Example}:
5075 See @code{GETPID} for an example.
5077 @item @emph{See also}:
5078 @ref{GETPID}, @ref{GETUID}
5084 @section @code{GETLOG} --- Get login name
5086 @cindex system, login name
5090 @item @emph{Description}:
5091 Gets the username under which the program is running.
5093 @item @emph{Standard}:
5099 @item @emph{Syntax}:
5100 @code{CALL GETLOG(C)}
5102 @item @emph{Arguments}:
5103 @multitable @columnfractions .15 .70
5104 @item @var{C} @tab Shall be of type @code{CHARACTER} and of default kind.
5107 @item @emph{Return value}:
5108 Stores the current user name in @var{LOGIN}. (On systems where POSIX
5109 functions @code{geteuid} and @code{getpwuid} are not available, and
5110 the @code{getlogin} function is not implemented either, this will
5111 return a blank string.)
5113 @item @emph{Example}:
5116 CHARACTER(32) :: login
5122 @item @emph{See also}:
5129 @section @code{GETPID} --- Process ID function
5131 @cindex system, process id
5135 @item @emph{Description}:
5136 Returns the numerical process identifier of the current process.
5138 @item @emph{Standard}:
5144 @item @emph{Syntax}:
5145 @code{RESULT = GETPID()}
5147 @item @emph{Return value}:
5148 The return value of @code{GETPID} is an @code{INTEGER} of the default
5152 @item @emph{Example}:
5155 print *, "The current process ID is ", getpid()
5156 print *, "Your numerical user ID is ", getuid()
5157 print *, "Your numerical group ID is ", getgid()
5161 @item @emph{See also}:
5162 @ref{GETGID}, @ref{GETUID}
5168 @section @code{GETUID} --- User ID function
5170 @cindex system, user id
5174 @item @emph{Description}:
5175 Returns the numerical user ID of the current process.
5177 @item @emph{Standard}:
5183 @item @emph{Syntax}:
5184 @code{RESULT = GETUID()}
5186 @item @emph{Return value}:
5187 The return value of @code{GETUID} is an @code{INTEGER} of the default
5191 @item @emph{Example}:
5192 See @code{GETPID} for an example.
5194 @item @emph{See also}:
5195 @ref{GETPID}, @ref{GETLOG}
5201 @section @code{GMTIME} --- Convert time to GMT info
5203 @cindex time, conversion to GMT info
5206 @item @emph{Description}:
5207 Given a system time value @var{TIME} (as provided by the @code{TIME8()}
5208 intrinsic), fills @var{VALUES} with values extracted from it appropriate
5209 to the UTC time zone (Universal Coordinated Time, also known in some
5210 countries as GMT, Greenwich Mean Time), using @code{gmtime(3)}.
5212 @item @emph{Standard}:
5218 @item @emph{Syntax}:
5219 @code{CALL GMTIME(TIME, VALUES)}
5221 @item @emph{Arguments}:
5222 @multitable @columnfractions .15 .70
5223 @item @var{TIME} @tab An @code{INTEGER} scalar expression
5224 corresponding to a system time, with @code{INTENT(IN)}.
5225 @item @var{VALUES} @tab A default @code{INTEGER} array with 9 elements,
5226 with @code{INTENT(OUT)}.
5229 @item @emph{Return value}:
5230 The elements of @var{VALUES} are assigned as follows:
5232 @item Seconds after the minute, range 0--59 or 0--61 to allow for leap
5234 @item Minutes after the hour, range 0--59
5235 @item Hours past midnight, range 0--23
5236 @item Day of month, range 0--31
5237 @item Number of months since January, range 0--12
5238 @item Years since 1900
5239 @item Number of days since Sunday, range 0--6
5240 @item Days since January 1
5241 @item Daylight savings indicator: positive if daylight savings is in
5242 effect, zero if not, and negative if the information is not available.
5245 @item @emph{See also}:
5246 @ref{CTIME}, @ref{LTIME}, @ref{TIME}, @ref{TIME8}
5253 @section @code{HOSTNM} --- Get system host name
5255 @cindex system, host name
5258 @item @emph{Description}:
5259 Retrieves the host name of the system on which the program is running.
5261 This intrinsic is provided in both subroutine and function forms; however,
5262 only one form can be used in any given program unit.
5264 @item @emph{Standard}:
5268 Subroutine, function
5270 @item @emph{Syntax}:
5271 @multitable @columnfractions .80
5272 @item @code{CALL HOSTNM(C [, STATUS])}
5273 @item @code{STATUS = HOSTNM(NAME)}
5276 @item @emph{Arguments}:
5277 @multitable @columnfractions .15 .70
5278 @item @var{C} @tab Shall of type @code{CHARACTER} and of default kind.
5279 @item @var{STATUS} @tab (Optional) status flag of type @code{INTEGER}.
5280 Returns 0 on success, or a system specific error code otherwise.
5283 @item @emph{Return value}:
5284 In either syntax, @var{NAME} is set to the current hostname if it can
5285 be obtained, or to a blank string otherwise.
5292 @section @code{HUGE} --- Largest number of a kind
5294 @cindex limits, largest number
5295 @cindex model representation, largest number
5298 @item @emph{Description}:
5299 @code{HUGE(X)} returns the largest number that is not an infinity in
5300 the model of the type of @code{X}.
5302 @item @emph{Standard}:
5303 Fortran 95 and later
5308 @item @emph{Syntax}:
5309 @code{RESULT = HUGE(X)}
5311 @item @emph{Arguments}:
5312 @multitable @columnfractions .15 .70
5313 @item @var{X} @tab Shall be of type @code{REAL} or @code{INTEGER}.
5316 @item @emph{Return value}:
5317 The return value is of the same type and kind as @var{X}
5319 @item @emph{Example}:
5321 program test_huge_tiny
5322 print *, huge(0), huge(0.0), huge(0.0d0)
5323 print *, tiny(0.0), tiny(0.0d0)
5324 end program test_huge_tiny
5331 @section @code{HYPOT} --- Euclidean distance function
5333 @cindex Euclidean distance
5336 @item @emph{Description}:
5337 @code{HYPOT(X,Y)} is the Euclidean distance function. It is equal to
5338 @math{\sqrt{X^2 + Y^2}}, without undue underflow or overflow.
5340 @item @emph{Standard}:
5341 Fortran 2008 and later
5346 @item @emph{Syntax}:
5347 @code{RESULT = HYPOT(X, Y)}
5349 @item @emph{Arguments}:
5350 @multitable @columnfractions .15 .70
5351 @item @var{X} @tab The type shall be @code{REAL}.
5352 @item @var{Y} @tab The type and kind type parameter shall be the same as
5356 @item @emph{Return value}:
5357 The return value has the same type and kind type parameter as @var{X}.
5359 @item @emph{Example}:
5362 real(4) :: x = 1.e0_4, y = 0.5e0_4
5364 end program test_hypot
5371 @section @code{IACHAR} --- Code in @acronym{ASCII} collating sequence
5373 @cindex @acronym{ASCII} collating sequence
5374 @cindex collating sequence, @acronym{ASCII}
5375 @cindex conversion, to integer
5378 @item @emph{Description}:
5379 @code{IACHAR(C)} returns the code for the @acronym{ASCII} character
5380 in the first character position of @code{C}.
5382 @item @emph{Standard}:
5383 Fortran 95 and later, with @var{KIND} argument Fortran 2003 and later
5388 @item @emph{Syntax}:
5389 @code{RESULT = IACHAR(C [, KIND])}
5391 @item @emph{Arguments}:
5392 @multitable @columnfractions .15 .70
5393 @item @var{C} @tab Shall be a scalar @code{CHARACTER}, with @code{INTENT(IN)}
5394 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
5395 expression indicating the kind parameter of the result.
5398 @item @emph{Return value}:
5399 The return value is of type @code{INTEGER} and of kind @var{KIND}. If
5400 @var{KIND} is absent, the return value is of default integer kind.
5402 @item @emph{Example}:
5407 end program test_iachar
5411 See @ref{ICHAR} for a discussion of converting between numerical values
5412 and formatted string representations.
5414 @item @emph{See also}:
5415 @ref{ACHAR}, @ref{CHAR}, @ref{ICHAR}
5422 @section @code{IAND} --- Bitwise logical and
5424 @cindex bitwise logical and
5425 @cindex logical and, bitwise
5428 @item @emph{Description}:
5429 Bitwise logical @code{AND}.
5431 @item @emph{Standard}:
5432 Fortran 95 and later
5437 @item @emph{Syntax}:
5438 @code{RESULT = IAND(I, J)}
5440 @item @emph{Arguments}:
5441 @multitable @columnfractions .15 .70
5442 @item @var{I} @tab The type shall be @code{INTEGER}.
5443 @item @var{J} @tab The type shall be @code{INTEGER}, of the same
5444 kind as @var{I}. (As a GNU extension, different kinds are also
5448 @item @emph{Return value}:
5449 The return type is @code{INTEGER}, of the same kind as the
5450 arguments. (If the argument kinds differ, it is of the same kind as
5451 the larger argument.)
5453 @item @emph{Example}:
5457 DATA a / Z'F' /, b / Z'3' /
5458 WRITE (*,*) IAND(a, b)
5462 @item @emph{See also}:
5463 @ref{IOR}, @ref{IEOR}, @ref{IBITS}, @ref{IBSET}, @ref{IBCLR}, @ref{NOT}
5470 @section @code{IARGC} --- Get the number of command line arguments
5472 @cindex command-line arguments
5473 @cindex command-line arguments, number of
5474 @cindex arguments, to program
5477 @item @emph{Description}:
5478 @code{IARGC()} returns the number of arguments passed on the
5479 command line when the containing program was invoked.
5481 This intrinsic routine is provided for backwards compatibility with
5482 GNU Fortran 77. In new code, programmers should consider the use of
5483 the @ref{COMMAND_ARGUMENT_COUNT} intrinsic defined by the Fortran 2003
5486 @item @emph{Standard}:
5492 @item @emph{Syntax}:
5493 @code{RESULT = IARGC()}
5495 @item @emph{Arguments}:
5498 @item @emph{Return value}:
5499 The number of command line arguments, type @code{INTEGER(4)}.
5501 @item @emph{Example}:
5504 @item @emph{See also}:
5505 GNU Fortran 77 compatibility subroutine: @ref{GETARG}
5507 Fortran 2003 functions and subroutines: @ref{GET_COMMAND},
5508 @ref{GET_COMMAND_ARGUMENT}, @ref{COMMAND_ARGUMENT_COUNT}
5514 @section @code{IBCLR} --- Clear bit
5520 @item @emph{Description}:
5521 @code{IBCLR} returns the value of @var{I} with the bit at position
5522 @var{POS} set to zero.
5524 @item @emph{Standard}:
5525 Fortran 95 and later
5530 @item @emph{Syntax}:
5531 @code{RESULT = IBCLR(I, POS)}
5533 @item @emph{Arguments}:
5534 @multitable @columnfractions .15 .70
5535 @item @var{I} @tab The type shall be @code{INTEGER}.
5536 @item @var{POS} @tab The type shall be @code{INTEGER}.
5539 @item @emph{Return value}:
5540 The return value is of type @code{INTEGER} and of the same kind as
5543 @item @emph{See also}:
5544 @ref{IBITS}, @ref{IBSET}, @ref{IAND}, @ref{IOR}, @ref{IEOR}, @ref{MVBITS}
5551 @section @code{IBITS} --- Bit extraction
5554 @cindex bits, extract
5557 @item @emph{Description}:
5558 @code{IBITS} extracts a field of length @var{LEN} from @var{I},
5559 starting from bit position @var{POS} and extending left for @var{LEN}
5560 bits. The result is right-justified and the remaining bits are
5561 zeroed. The value of @code{POS+LEN} must be less than or equal to the
5562 value @code{BIT_SIZE(I)}.
5564 @item @emph{Standard}:
5565 Fortran 95 and later
5570 @item @emph{Syntax}:
5571 @code{RESULT = IBITS(I, POS, LEN)}
5573 @item @emph{Arguments}:
5574 @multitable @columnfractions .15 .70
5575 @item @var{I} @tab The type shall be @code{INTEGER}.
5576 @item @var{POS} @tab The type shall be @code{INTEGER}.
5577 @item @var{LEN} @tab The type shall be @code{INTEGER}.
5580 @item @emph{Return value}:
5581 The return value is of type @code{INTEGER} and of the same kind as
5584 @item @emph{See also}:
5585 @ref{BIT_SIZE}, @ref{IBCLR}, @ref{IBSET}, @ref{IAND}, @ref{IOR}, @ref{IEOR}
5591 @section @code{IBSET} --- Set bit
5596 @item @emph{Description}:
5597 @code{IBSET} returns the value of @var{I} with the bit at position
5598 @var{POS} set to one.
5600 @item @emph{Standard}:
5601 Fortran 95 and later
5606 @item @emph{Syntax}:
5607 @code{RESULT = IBSET(I, POS)}
5609 @item @emph{Arguments}:
5610 @multitable @columnfractions .15 .70
5611 @item @var{I} @tab The type shall be @code{INTEGER}.
5612 @item @var{POS} @tab The type shall be @code{INTEGER}.
5615 @item @emph{Return value}:
5616 The return value is of type @code{INTEGER} and of the same kind as
5619 @item @emph{See also}:
5620 @ref{IBCLR}, @ref{IBITS}, @ref{IAND}, @ref{IOR}, @ref{IEOR}, @ref{MVBITS}
5627 @section @code{ICHAR} --- Character-to-integer conversion function
5629 @cindex conversion, to integer
5632 @item @emph{Description}:
5633 @code{ICHAR(C)} returns the code for the character in the first character
5634 position of @code{C} in the system's native character set.
5635 The correspondence between characters and their codes is not necessarily
5636 the same across different GNU Fortran implementations.
5638 @item @emph{Standard}:
5639 Fortan 95 and later, with @var{KIND} argument Fortran 2003 and later
5644 @item @emph{Syntax}:
5645 @code{RESULT = ICHAR(C [, KIND])}
5647 @item @emph{Arguments}:
5648 @multitable @columnfractions .15 .70
5649 @item @var{C} @tab Shall be a scalar @code{CHARACTER}, with @code{INTENT(IN)}
5650 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
5651 expression indicating the kind parameter of the result.
5654 @item @emph{Return value}:
5655 The return value is of type @code{INTEGER} and of kind @var{KIND}. If
5656 @var{KIND} is absent, the return value is of default integer kind.
5658 @item @emph{Example}:
5663 end program test_ichar
5667 No intrinsic exists to convert between a numeric value and a formatted
5668 character string representation -- for instance, given the
5669 @code{CHARACTER} value @code{'154'}, obtaining an @code{INTEGER} or
5670 @code{REAL} value with the value 154, or vice versa. Instead, this
5671 functionality is provided by internal-file I/O, as in the following
5676 character(len=10) string, string2
5679 ! Convert a string to a numeric value
5680 read (string,'(I10)') value
5683 ! Convert a value to a formatted string
5684 write (string2,'(I10)') value
5686 end program read_val
5689 @item @emph{See also}:
5690 @ref{ACHAR}, @ref{CHAR}, @ref{IACHAR}
5697 @section @code{IDATE} --- Get current local time subroutine (day/month/year)
5699 @cindex date, current
5700 @cindex current date
5703 @item @emph{Description}:
5704 @code{IDATE(TARRAY)} Fills @var{TARRAY} with the numerical values at the
5705 current local time. The day (in the range 1-31), month (in the range 1-12),
5706 and year appear in elements 1, 2, and 3 of @var{TARRAY}, respectively.
5707 The year has four significant digits.
5709 @item @emph{Standard}:
5715 @item @emph{Syntax}:
5716 @code{CALL IDATE(VALUES)}
5718 @item @emph{Arguments}:
5719 @multitable @columnfractions .15 .70
5720 @item @var{VALUES} @tab The type shall be @code{INTEGER, DIMENSION(3)} and
5721 the kind shall be the default integer kind.
5724 @item @emph{Return value}:
5727 @item @emph{Example}:
5730 integer, dimension(3) :: tarray
5735 end program test_idate
5742 @section @code{IEOR} --- Bitwise logical exclusive or
5744 @cindex bitwise logical exclusive or
5745 @cindex logical exclusive or, bitwise
5748 @item @emph{Description}:
5749 @code{IEOR} returns the bitwise boolean exclusive-OR of @var{I} and
5752 @item @emph{Standard}:
5753 Fortran 95 and later
5758 @item @emph{Syntax}:
5759 @code{RESULT = IEOR(I, J)}
5761 @item @emph{Arguments}:
5762 @multitable @columnfractions .15 .70
5763 @item @var{I} @tab The type shall be @code{INTEGER}.
5764 @item @var{J} @tab The type shall be @code{INTEGER}, of the same
5765 kind as @var{I}. (As a GNU extension, different kinds are also
5769 @item @emph{Return value}:
5770 The return type is @code{INTEGER}, of the same kind as the
5771 arguments. (If the argument kinds differ, it is of the same kind as
5772 the larger argument.)
5774 @item @emph{See also}:
5775 @ref{IOR}, @ref{IAND}, @ref{IBITS}, @ref{IBSET}, @ref{IBCLR}, @ref{NOT}
5781 @section @code{IERRNO} --- Get the last system error number
5783 @cindex system, error handling
5786 @item @emph{Description}:
5787 Returns the last system error number, as given by the C @code{errno()}
5790 @item @emph{Standard}:
5796 @item @emph{Syntax}:
5797 @code{RESULT = IERRNO()}
5799 @item @emph{Arguments}:
5802 @item @emph{Return value}:
5803 The return value is of type @code{INTEGER} and of the default integer
5806 @item @emph{See also}:
5812 @node INDEX intrinsic
5813 @section @code{INDEX} --- Position of a substring within a string
5815 @cindex substring position
5816 @cindex string, find substring
5819 @item @emph{Description}:
5820 Returns the position of the start of the first occurrence of string
5821 @var{SUBSTRING} as a substring in @var{STRING}, counting from one. If
5822 @var{SUBSTRING} is not present in @var{STRING}, zero is returned. If
5823 the @var{BACK} argument is present and true, the return value is the
5824 start of the last occurrence rather than the first.
5826 @item @emph{Standard}:
5827 Fortran 77 and later, with @var{KIND} argument Fortran 2003 and later
5832 @item @emph{Syntax}:
5833 @code{RESULT = INDEX(STRING, SUBSTRING [, BACK [, KIND]])}
5835 @item @emph{Arguments}:
5836 @multitable @columnfractions .15 .70
5837 @item @var{STRING} @tab Shall be a scalar @code{CHARACTER}, with
5839 @item @var{SUBSTRING} @tab Shall be a scalar @code{CHARACTER}, with
5841 @item @var{BACK} @tab (Optional) Shall be a scalar @code{LOGICAL}, with
5843 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
5844 expression indicating the kind parameter of the result.
5847 @item @emph{Return value}:
5848 The return value is of type @code{INTEGER} and of kind @var{KIND}. If
5849 @var{KIND} is absent, the return value is of default integer kind.
5851 @item @emph{See also}:
5852 @ref{SCAN}, @ref{VERIFY}
5858 @section @code{INT} --- Convert to integer type
5862 @cindex conversion, to integer
5865 @item @emph{Description}:
5866 Convert to integer type
5868 @item @emph{Standard}:
5869 Fortran 77 and later
5874 @item @emph{Syntax}:
5875 @code{RESULT = INT(A [, KIND))}
5877 @item @emph{Arguments}:
5878 @multitable @columnfractions .15 .70
5879 @item @var{A} @tab Shall be of type @code{INTEGER},
5880 @code{REAL}, or @code{COMPLEX}.
5881 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
5882 expression indicating the kind parameter of the result.
5885 @item @emph{Return value}:
5886 These functions return a @code{INTEGER} variable or array under
5887 the following rules:
5891 If @var{A} is of type @code{INTEGER}, @code{INT(A) = A}
5893 If @var{A} is of type @code{REAL} and @math{|A| < 1}, @code{INT(A)} equals @code{0}.
5894 If @math{|A| \geq 1}, then @code{INT(A)} equals the largest integer that does not exceed
5895 the range of @var{A} and whose sign is the same as the sign of @var{A}.
5897 If @var{A} is of type @code{COMPLEX}, rule B is applied to the real part of @var{A}.
5900 @item @emph{Example}:
5904 complex :: z = (-3.7, 1.0)
5906 print *, int(z), int(z,8)
5910 @item @emph{Specific names}:
5911 @multitable @columnfractions .20 .20 .20 .25
5912 @item Name @tab Argument @tab Return type @tab Standard
5913 @item @code{IFIX(A)} @tab @code{REAL(4) A} @tab @code{INTEGER} @tab Fortran 77 and later
5914 @item @code{IDINT(A)} @tab @code{REAL(8) A} @tab @code{INTEGER} @tab Fortran 77 and later
5922 @section @code{INT2} --- Convert to 16-bit integer type
5925 @cindex conversion, to integer
5928 @item @emph{Description}:
5929 Convert to a @code{KIND=2} integer type. This is equivalent to the
5930 standard @code{INT} intrinsic with an optional argument of
5931 @code{KIND=2}, and is only included for backwards compatibility.
5933 The @code{SHORT} intrinsic is equivalent to @code{INT2}.
5935 @item @emph{Standard}:
5941 @item @emph{Syntax}:
5942 @code{RESULT = INT2(A)}
5944 @item @emph{Arguments}:
5945 @multitable @columnfractions .15 .70
5946 @item @var{A} @tab Shall be of type @code{INTEGER},
5947 @code{REAL}, or @code{COMPLEX}.
5950 @item @emph{Return value}:
5951 The return value is a @code{INTEGER(2)} variable.
5953 @item @emph{See also}:
5954 @ref{INT}, @ref{INT8}, @ref{LONG}
5960 @section @code{INT8} --- Convert to 64-bit integer type
5962 @cindex conversion, to integer
5965 @item @emph{Description}:
5966 Convert to a @code{KIND=8} integer type. This is equivalent to the
5967 standard @code{INT} intrinsic with an optional argument of
5968 @code{KIND=8}, and is only included for backwards compatibility.
5970 @item @emph{Standard}:
5976 @item @emph{Syntax}:
5977 @code{RESULT = INT8(A)}
5979 @item @emph{Arguments}:
5980 @multitable @columnfractions .15 .70
5981 @item @var{A} @tab Shall be of type @code{INTEGER},
5982 @code{REAL}, or @code{COMPLEX}.
5985 @item @emph{Return value}:
5986 The return value is a @code{INTEGER(8)} variable.
5988 @item @emph{See also}:
5989 @ref{INT}, @ref{INT2}, @ref{LONG}
5995 @section @code{IOR} --- Bitwise logical or
5997 @cindex bitwise logical or
5998 @cindex logical or, bitwise
6001 @item @emph{Description}:
6002 @code{IOR} returns the bitwise boolean inclusive-OR of @var{I} and
6005 @item @emph{Standard}:
6006 Fortran 95 and later
6011 @item @emph{Syntax}:
6012 @code{RESULT = IOR(I, J)}
6014 @item @emph{Arguments}:
6015 @multitable @columnfractions .15 .70
6016 @item @var{I} @tab The type shall be @code{INTEGER}.
6017 @item @var{J} @tab The type shall be @code{INTEGER}, of the same
6018 kind as @var{I}. (As a GNU extension, different kinds are also
6022 @item @emph{Return value}:
6023 The return type is @code{INTEGER}, of the same kind as the
6024 arguments. (If the argument kinds differ, it is of the same kind as
6025 the larger argument.)
6027 @item @emph{See also}:
6028 @ref{IEOR}, @ref{IAND}, @ref{IBITS}, @ref{IBSET}, @ref{IBCLR}, @ref{NOT}
6034 @section @code{IRAND} --- Integer pseudo-random number
6036 @cindex random number generation
6039 @item @emph{Description}:
6040 @code{IRAND(FLAG)} returns a pseudo-random number from a uniform
6041 distribution between 0 and a system-dependent limit (which is in most
6042 cases 2147483647). If @var{FLAG} is 0, the next number
6043 in the current sequence is returned; if @var{FLAG} is 1, the generator
6044 is restarted by @code{CALL SRAND(0)}; if @var{FLAG} has any other value,
6045 it is used as a new seed with @code{SRAND}.
6047 This intrinsic routine is provided for backwards compatibility with
6048 GNU Fortran 77. It implements a simple modulo generator as provided
6049 by @command{g77}. For new code, one should consider the use of
6050 @ref{RANDOM_NUMBER} as it implements a superior algorithm.
6052 @item @emph{Standard}:
6058 @item @emph{Syntax}:
6059 @code{RESULT = IRAND(I)}
6061 @item @emph{Arguments}:
6062 @multitable @columnfractions .15 .70
6063 @item @var{I} @tab Shall be a scalar @code{INTEGER} of kind 4.
6066 @item @emph{Return value}:
6067 The return value is of @code{INTEGER(kind=4)} type.
6069 @item @emph{Example}:
6072 integer,parameter :: seed = 86456
6075 print *, irand(), irand(), irand(), irand()
6076 print *, irand(seed), irand(), irand(), irand()
6077 end program test_irand
6085 @section @code{IS_IOSTAT_END} --- Test for end-of-file value
6086 @fnindex IS_IOSTAT_END
6087 @cindex IOSTAT, end of file
6090 @item @emph{Description}:
6091 @code{IS_IOSTAT_END} tests whether an variable has the value of the I/O
6092 status ``end of file''. The function is equivalent to comparing the variable
6093 with the @code{IOSTAT_END} parameter of the intrinsic module
6094 @code{ISO_FORTRAN_ENV}.
6096 @item @emph{Standard}:
6097 Fortran 2003 and later
6102 @item @emph{Syntax}:
6103 @code{RESULT = IS_IOSTAT_END(I)}
6105 @item @emph{Arguments}:
6106 @multitable @columnfractions .15 .70
6107 @item @var{I} @tab Shall be of the type @code{INTEGER}.
6110 @item @emph{Return value}:
6111 Returns a @code{LOGICAL} of the default kind, which @code{.TRUE.} if
6112 @var{I} has the value which indicates an end of file condition for
6113 IOSTAT= specifiers, and is @code{.FALSE.} otherwise.
6115 @item @emph{Example}:
6120 OPEN(88, FILE='test.dat')
6121 READ(88, *, IOSTAT=stat) i
6122 IF(IS_IOSTAT_END(stat)) STOP 'END OF FILE'
6130 @section @code{IS_IOSTAT_EOR} --- Test for end-of-record value
6131 @fnindex IS_IOSTAT_EOR
6132 @cindex IOSTAT, end of record
6135 @item @emph{Description}:
6136 @code{IS_IOSTAT_EOR} tests whether an variable has the value of the I/O
6137 status ``end of record''. The function is equivalent to comparing the
6138 variable with the @code{IOSTAT_EOR} parameter of the intrinsic module
6139 @code{ISO_FORTRAN_ENV}.
6141 @item @emph{Standard}:
6142 Fortran 2003 and later
6147 @item @emph{Syntax}:
6148 @code{RESULT = IS_IOSTAT_EOR(I)}
6150 @item @emph{Arguments}:
6151 @multitable @columnfractions .15 .70
6152 @item @var{I} @tab Shall be of the type @code{INTEGER}.
6155 @item @emph{Return value}:
6156 Returns a @code{LOGICAL} of the default kind, which @code{.TRUE.} if
6157 @var{I} has the value which indicates an end of file condition for
6158 IOSTAT= specifiers, and is @code{.FALSE.} otherwise.
6160 @item @emph{Example}:
6164 INTEGER :: stat, i(50)
6165 OPEN(88, FILE='test.dat', FORM='UNFORMATTED')
6166 READ(88, IOSTAT=stat) i
6167 IF(IS_IOSTAT_EOR(stat)) STOP 'END OF RECORD'
6175 @section @code{ISATTY} --- Whether a unit is a terminal device.
6177 @cindex system, terminal
6180 @item @emph{Description}:
6181 Determine whether a unit is connected to a terminal device.
6183 @item @emph{Standard}:
6189 @item @emph{Syntax}:
6190 @code{RESULT = ISATTY(UNIT)}
6192 @item @emph{Arguments}:
6193 @multitable @columnfractions .15 .70
6194 @item @var{UNIT} @tab Shall be a scalar @code{INTEGER}.
6197 @item @emph{Return value}:
6198 Returns @code{.TRUE.} if the @var{UNIT} is connected to a terminal
6199 device, @code{.FALSE.} otherwise.
6201 @item @emph{Example}:
6204 INTEGER(kind=1) :: unit
6206 write(*,*) isatty(unit=unit)
6210 @item @emph{See also}:
6217 @section @code{ISHFT} --- Shift bits
6222 @item @emph{Description}:
6223 @code{ISHFT} returns a value corresponding to @var{I} with all of the
6224 bits shifted @var{SHIFT} places. A value of @var{SHIFT} greater than
6225 zero corresponds to a left shift, a value of zero corresponds to no
6226 shift, and a value less than zero corresponds to a right shift. If the
6227 absolute value of @var{SHIFT} is greater than @code{BIT_SIZE(I)}, the
6228 value is undefined. Bits shifted out from the left end or right end are
6229 lost; zeros are shifted in from the opposite end.
6231 @item @emph{Standard}:
6232 Fortran 95 and later
6237 @item @emph{Syntax}:
6238 @code{RESULT = ISHFT(I, SHIFT)}
6240 @item @emph{Arguments}:
6241 @multitable @columnfractions .15 .70
6242 @item @var{I} @tab The type shall be @code{INTEGER}.
6243 @item @var{SHIFT} @tab The type shall be @code{INTEGER}.
6246 @item @emph{Return value}:
6247 The return value is of type @code{INTEGER} and of the same kind as
6250 @item @emph{See also}:
6257 @section @code{ISHFTC} --- Shift bits circularly
6259 @cindex bits, shift circular
6262 @item @emph{Description}:
6263 @code{ISHFTC} returns a value corresponding to @var{I} with the
6264 rightmost @var{SIZE} bits shifted circularly @var{SHIFT} places; that
6265 is, bits shifted out one end are shifted into the opposite end. A value
6266 of @var{SHIFT} greater than zero corresponds to a left shift, a value of
6267 zero corresponds to no shift, and a value less than zero corresponds to
6268 a right shift. The absolute value of @var{SHIFT} must be less than
6269 @var{SIZE}. If the @var{SIZE} argument is omitted, it is taken to be
6270 equivalent to @code{BIT_SIZE(I)}.
6272 @item @emph{Standard}:
6273 Fortran 95 and later
6278 @item @emph{Syntax}:
6279 @code{RESULT = ISHFTC(I, SHIFT [, SIZE])}
6281 @item @emph{Arguments}:
6282 @multitable @columnfractions .15 .70
6283 @item @var{I} @tab The type shall be @code{INTEGER}.
6284 @item @var{SHIFT} @tab The type shall be @code{INTEGER}.
6285 @item @var{SIZE} @tab (Optional) The type shall be @code{INTEGER};
6286 the value must be greater than zero and less than or equal to
6290 @item @emph{Return value}:
6291 The return value is of type @code{INTEGER} and of the same kind as
6294 @item @emph{See also}:
6301 @section @code{ISNAN} --- Test for a NaN
6306 @item @emph{Description}:
6307 @code{ISNAN} tests whether a floating-point value is an IEEE
6309 @item @emph{Standard}:
6315 @item @emph{Syntax}:
6318 @item @emph{Arguments}:
6319 @multitable @columnfractions .15 .70
6320 @item @var{X} @tab Variable of the type @code{REAL}.
6324 @item @emph{Return value}:
6325 Returns a default-kind @code{LOGICAL}. The returned value is @code{TRUE}
6326 if @var{X} is a NaN and @code{FALSE} otherwise.
6328 @item @emph{Example}:
6335 if (isnan(x)) stop '"x" is a NaN'
6336 end program test_nan
6343 @section @code{ITIME} --- Get current local time subroutine (hour/minutes/seconds)
6345 @cindex time, current
6346 @cindex current time
6349 @item @emph{Description}:
6350 @code{IDATE(VALUES)} Fills @var{VALUES} with the numerical values at the
6351 current local time. The hour (in the range 1-24), minute (in the range 1-60),
6352 and seconds (in the range 1-60) appear in elements 1, 2, and 3 of @var{VALUES},
6355 @item @emph{Standard}:
6361 @item @emph{Syntax}:
6362 @code{CALL ITIME(VALUES)}
6364 @item @emph{Arguments}:
6365 @multitable @columnfractions .15 .70
6366 @item @var{VALUES} @tab The type shall be @code{INTEGER, DIMENSION(3)}
6367 and the kind shall be the default integer kind.
6370 @item @emph{Return value}:
6374 @item @emph{Example}:
6377 integer, dimension(3) :: tarray
6382 end program test_itime
6389 @section @code{KILL} --- Send a signal to a process
6393 @item @emph{Description}:
6394 @item @emph{Standard}:
6395 Sends the signal specified by @var{SIGNAL} to the process @var{PID}.
6398 This intrinsic is provided in both subroutine and function forms; however,
6399 only one form can be used in any given program unit.
6402 Subroutine, function
6404 @item @emph{Syntax}:
6405 @code{CALL KILL(C, VALUE [, STATUS])}
6407 @item @emph{Arguments}:
6408 @multitable @columnfractions .15 .70
6409 @item @var{C} @tab Shall be a scalar @code{INTEGER}, with
6411 @item @var{VALUE} @tab Shall be a scalar @code{INTEGER}, with
6413 @item @var{STATUS} @tab (Optional) status flag of type @code{INTEGER(4)} or
6414 @code{INTEGER(8)}. Returns 0 on success, or a system-specific error code
6418 @item @emph{See also}:
6419 @ref{ABORT}, @ref{EXIT}
6425 @section @code{KIND} --- Kind of an entity
6430 @item @emph{Description}:
6431 @code{KIND(X)} returns the kind value of the entity @var{X}.
6433 @item @emph{Standard}:
6434 Fortran 95 and later
6439 @item @emph{Syntax}:
6442 @item @emph{Arguments}:
6443 @multitable @columnfractions .15 .70
6444 @item @var{X} @tab Shall be of type @code{LOGICAL}, @code{INTEGER},
6445 @code{REAL}, @code{COMPLEX} or @code{CHARACTER}.
6448 @item @emph{Return value}:
6449 The return value is a scalar of type @code{INTEGER} and of the default
6452 @item @emph{Example}:
6455 integer,parameter :: kc = kind(' ')
6456 integer,parameter :: kl = kind(.true.)
6458 print *, "The default character kind is ", kc
6459 print *, "The default logical kind is ", kl
6460 end program test_kind
6468 @section @code{LBOUND} --- Lower dimension bounds of an array
6470 @cindex array, lower bound
6473 @item @emph{Description}:
6474 Returns the lower bounds of an array, or a single lower bound
6475 along the @var{DIM} dimension.
6476 @item @emph{Standard}:
6477 Fortran 95 and later, with @var{KIND} argument Fortran 2003 and later
6482 @item @emph{Syntax}:
6483 @code{RESULT = LBOUND(ARRAY [, DIM [, KIND]])}
6485 @item @emph{Arguments}:
6486 @multitable @columnfractions .15 .70
6487 @item @var{ARRAY} @tab Shall be an array, of any type.
6488 @item @var{DIM} @tab (Optional) Shall be a scalar @code{INTEGER}.
6489 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
6490 expression indicating the kind parameter of the result.
6493 @item @emph{Return value}:
6494 The return value is of type @code{INTEGER} and of kind @var{KIND}. If
6495 @var{KIND} is absent, the return value is of default integer kind.
6496 If @var{DIM} is absent, the result is an array of the lower bounds of
6497 @var{ARRAY}. If @var{DIM} is present, the result is a scalar
6498 corresponding to the lower bound of the array along that dimension. If
6499 @var{ARRAY} is an expression rather than a whole array or array
6500 structure component, or if it has a zero extent along the relevant
6501 dimension, the lower bound is taken to be 1.
6503 @item @emph{See also}:
6510 @section @code{LEADZ} --- Number of leading zero bits of an integer
6515 @item @emph{Description}:
6516 @code{LEADZ} returns the number of leading zero bits of an integer.
6518 @item @emph{Standard}:
6519 Fortran 2008 and later
6524 @item @emph{Syntax}:
6525 @code{RESULT = LEADZ(I)}
6527 @item @emph{Arguments}:
6528 @multitable @columnfractions .15 .70
6529 @item @var{I} @tab Shall be of type @code{INTEGER}.
6532 @item @emph{Return value}:
6533 The type of the return value is the default @code{INTEGER}.
6534 If all the bits of @code{I} are zero, the result value is @code{BIT_SIZE(I)}.
6536 @item @emph{Example}:
6539 WRITE (*,*) LEADZ(1) ! prints 8 if BITSIZE(I) has the value 32
6543 @item @emph{See also}:
6544 @ref{BIT_SIZE}, @ref{TRAILZ}
6550 @section @code{LEN} --- Length of a character entity
6552 @cindex string, length
6555 @item @emph{Description}:
6556 Returns the length of a character string. If @var{STRING} is an array,
6557 the length of an element of @var{STRING} is returned. Note that
6558 @var{STRING} need not be defined when this intrinsic is invoked, since
6559 only the length, not the content, of @var{STRING} is needed.
6561 @item @emph{Standard}:
6562 Fortran 77 and later, with @var{KIND} argument Fortran 2003 and later
6567 @item @emph{Syntax}:
6568 @code{L = LEN(STRING [, KIND])}
6570 @item @emph{Arguments}:
6571 @multitable @columnfractions .15 .70
6572 @item @var{STRING} @tab Shall be a scalar or array of type
6573 @code{CHARACTER}, with @code{INTENT(IN)}
6574 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
6575 expression indicating the kind parameter of the result.
6578 @item @emph{Return value}:
6579 The return value is of type @code{INTEGER} and of kind @var{KIND}. If
6580 @var{KIND} is absent, the return value is of default integer kind.
6582 @item @emph{See also}:
6583 @ref{LEN_TRIM}, @ref{ADJUSTL}, @ref{ADJUSTR}
6589 @section @code{LEN_TRIM} --- Length of a character entity without trailing blank characters
6591 @cindex string, length, without trailing whitespace
6594 @item @emph{Description}:
6595 Returns the length of a character string, ignoring any trailing blanks.
6597 @item @emph{Standard}:
6598 Fortran 95 and later, with @var{KIND} argument Fortran 2003 and later
6603 @item @emph{Syntax}:
6604 @code{RESULT = LEN_TRIM(STRING [, KIND])}
6606 @item @emph{Arguments}:
6607 @multitable @columnfractions .15 .70
6608 @item @var{STRING} @tab Shall be a scalar of type @code{CHARACTER},
6609 with @code{INTENT(IN)}
6610 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
6611 expression indicating the kind parameter of the result.
6614 @item @emph{Return value}:
6615 The return value is of type @code{INTEGER} and of kind @var{KIND}. If
6616 @var{KIND} is absent, the return value is of default integer kind.
6618 @item @emph{See also}:
6619 @ref{LEN}, @ref{ADJUSTL}, @ref{ADJUSTR}
6625 @section @code{LGE} --- Lexical greater than or equal
6627 @cindex lexical comparison of strings
6628 @cindex string, comparison
6631 @item @emph{Description}:
6632 Determines whether one string is lexically greater than or equal to
6633 another string, where the two strings are interpreted as containing
6634 ASCII character codes. If the String A and String B are not the same
6635 length, the shorter is compared as if spaces were appended to it to form
6636 a value that has the same length as the longer.
6638 In general, the lexical comparison intrinsics @code{LGE}, @code{LGT},
6639 @code{LLE}, and @code{LLT} differ from the corresponding intrinsic
6640 operators @code{.GE.}, @code{.GT.}, @code{.LE.}, and @code{.LT.}, in
6641 that the latter use the processor's character ordering (which is not
6642 ASCII on some targets), whereas the former always use the ASCII
6645 @item @emph{Standard}:
6646 Fortran 77 and later
6651 @item @emph{Syntax}:
6652 @code{RESULT = LGE(STRING_A, STRING_B)}
6654 @item @emph{Arguments}:
6655 @multitable @columnfractions .15 .70
6656 @item @var{STRING_A} @tab Shall be of default @code{CHARACTER} type.
6657 @item @var{STRING_B} @tab Shall be of default @code{CHARACTER} type.
6660 @item @emph{Return value}:
6661 Returns @code{.TRUE.} if @code{STRING_A >= STRING_B}, and @code{.FALSE.}
6662 otherwise, based on the ASCII ordering.
6664 @item @emph{See also}:
6665 @ref{LGT}, @ref{LLE}, @ref{LLT}
6671 @section @code{LGT} --- Lexical greater than
6673 @cindex lexical comparison of strings
6674 @cindex string, comparison
6677 @item @emph{Description}:
6678 Determines whether one string is lexically greater than another string,
6679 where the two strings are interpreted as containing ASCII character
6680 codes. If the String A and String B are not the same length, the
6681 shorter is compared as if spaces were appended to it to form a value
6682 that has the same length as the longer.
6684 In general, the lexical comparison intrinsics @code{LGE}, @code{LGT},
6685 @code{LLE}, and @code{LLT} differ from the corresponding intrinsic
6686 operators @code{.GE.}, @code{.GT.}, @code{.LE.}, and @code{.LT.}, in
6687 that the latter use the processor's character ordering (which is not
6688 ASCII on some targets), whereas the former always use the ASCII
6691 @item @emph{Standard}:
6692 Fortran 77 and later
6697 @item @emph{Syntax}:
6698 @code{RESULT = LGT(STRING_A, STRING_B)}
6700 @item @emph{Arguments}:
6701 @multitable @columnfractions .15 .70
6702 @item @var{STRING_A} @tab Shall be of default @code{CHARACTER} type.
6703 @item @var{STRING_B} @tab Shall be of default @code{CHARACTER} type.
6706 @item @emph{Return value}:
6707 Returns @code{.TRUE.} if @code{STRING_A > STRING_B}, and @code{.FALSE.}
6708 otherwise, based on the ASCII ordering.
6710 @item @emph{See also}:
6711 @ref{LGE}, @ref{LLE}, @ref{LLT}
6717 @section @code{LINK} --- Create a hard link
6719 @cindex file system, create link
6720 @cindex file system, hard link
6723 @item @emph{Description}:
6724 Makes a (hard) link from file @var{PATH1} to @var{PATH2}. A null
6725 character (@code{CHAR(0)}) can be used to mark the end of the names in
6726 @var{PATH1} and @var{PATH2}; otherwise, trailing blanks in the file
6727 names are ignored. If the @var{STATUS} argument is supplied, it
6728 contains 0 on success or a nonzero error code upon return; see
6731 This intrinsic is provided in both subroutine and function forms;
6732 however, only one form can be used in any given program unit.
6734 @item @emph{Standard}:
6738 Subroutine, function
6740 @item @emph{Syntax}:
6741 @multitable @columnfractions .80
6742 @item @code{CALL LINK(PATH1, PATH2 [, STATUS])}
6743 @item @code{STATUS = LINK(PATH1, PATH2)}
6746 @item @emph{Arguments}:
6747 @multitable @columnfractions .15 .70
6748 @item @var{PATH1} @tab Shall be of default @code{CHARACTER} type.
6749 @item @var{PATH2} @tab Shall be of default @code{CHARACTER} type.
6750 @item @var{STATUS} @tab (Optional) Shall be of default @code{INTEGER} type.
6753 @item @emph{See also}:
6754 @ref{SYMLNK}, @ref{UNLINK}
6760 @section @code{LLE} --- Lexical less than or equal
6762 @cindex lexical comparison of strings
6763 @cindex string, comparison
6766 @item @emph{Description}:
6767 Determines whether one string is lexically less than or equal to another
6768 string, where the two strings are interpreted as containing ASCII
6769 character codes. If the String A and String B are not the same length,
6770 the shorter is compared as if spaces were appended to it to form a value
6771 that has the same length as the longer.
6773 In general, the lexical comparison intrinsics @code{LGE}, @code{LGT},
6774 @code{LLE}, and @code{LLT} differ from the corresponding intrinsic
6775 operators @code{.GE.}, @code{.GT.}, @code{.LE.}, and @code{.LT.}, in
6776 that the latter use the processor's character ordering (which is not
6777 ASCII on some targets), whereas the former always use the ASCII
6780 @item @emph{Standard}:
6781 Fortran 77 and later
6786 @item @emph{Syntax}:
6787 @code{RESULT = LLE(STRING_A, STRING_B)}
6789 @item @emph{Arguments}:
6790 @multitable @columnfractions .15 .70
6791 @item @var{STRING_A} @tab Shall be of default @code{CHARACTER} type.
6792 @item @var{STRING_B} @tab Shall be of default @code{CHARACTER} type.
6795 @item @emph{Return value}:
6796 Returns @code{.TRUE.} if @code{STRING_A <= STRING_B}, and @code{.FALSE.}
6797 otherwise, based on the ASCII ordering.
6799 @item @emph{See also}:
6800 @ref{LGE}, @ref{LGT}, @ref{LLT}
6806 @section @code{LLT} --- Lexical less than
6808 @cindex lexical comparison of strings
6809 @cindex string, comparison
6812 @item @emph{Description}:
6813 Determines whether one string is lexically less than another string,
6814 where the two strings are interpreted as containing ASCII character
6815 codes. If the String A and String B are not the same length, the
6816 shorter is compared as if spaces were appended to it to form a value
6817 that has the same length as the longer.
6819 In general, the lexical comparison intrinsics @code{LGE}, @code{LGT},
6820 @code{LLE}, and @code{LLT} differ from the corresponding intrinsic
6821 operators @code{.GE.}, @code{.GT.}, @code{.LE.}, and @code{.LT.}, in
6822 that the latter use the processor's character ordering (which is not
6823 ASCII on some targets), whereas the former always use the ASCII
6826 @item @emph{Standard}:
6827 Fortran 77 and later
6832 @item @emph{Syntax}:
6833 @code{RESULT = LLT(STRING_A, STRING_B)}
6835 @item @emph{Arguments}:
6836 @multitable @columnfractions .15 .70
6837 @item @var{STRING_A} @tab Shall be of default @code{CHARACTER} type.
6838 @item @var{STRING_B} @tab Shall be of default @code{CHARACTER} type.
6841 @item @emph{Return value}:
6842 Returns @code{.TRUE.} if @code{STRING_A < STRING_B}, and @code{.FALSE.}
6843 otherwise, based on the ASCII ordering.
6845 @item @emph{See also}:
6846 @ref{LGE}, @ref{LGT}, @ref{LLE}
6852 @section @code{LNBLNK} --- Index of the last non-blank character in a string
6854 @cindex string, find non-blank character
6857 @item @emph{Description}:
6858 Returns the length of a character string, ignoring any trailing blanks.
6859 This is identical to the standard @code{LEN_TRIM} intrinsic, and is only
6860 included for backwards compatibility.
6862 @item @emph{Standard}:
6868 @item @emph{Syntax}:
6869 @code{RESULT = LNBLNK(STRING)}
6871 @item @emph{Arguments}:
6872 @multitable @columnfractions .15 .70
6873 @item @var{STRING} @tab Shall be a scalar of type @code{CHARACTER},
6874 with @code{INTENT(IN)}
6877 @item @emph{Return value}:
6878 The return value is of @code{INTEGER(kind=4)} type.
6880 @item @emph{See also}:
6881 @ref{INDEX intrinsic}, @ref{LEN_TRIM}
6887 @section @code{LOC} --- Returns the address of a variable
6889 @cindex location of a variable in memory
6892 @item @emph{Description}:
6893 @code{LOC(X)} returns the address of @var{X} as an integer.
6895 @item @emph{Standard}:
6901 @item @emph{Syntax}:
6902 @code{RESULT = LOC(X)}
6904 @item @emph{Arguments}:
6905 @multitable @columnfractions .15 .70
6906 @item @var{X} @tab Variable of any type.
6909 @item @emph{Return value}:
6910 The return value is of type @code{INTEGER}, with a @code{KIND}
6911 corresponding to the size (in bytes) of a memory address on the target
6914 @item @emph{Example}:
6921 end program test_loc
6928 @section @code{LOG} --- Logarithm function
6935 @cindex exponential function, inverse
6936 @cindex logarithmic function
6939 @item @emph{Description}:
6940 @code{LOG(X)} computes the logarithm of @var{X}.
6942 @item @emph{Standard}:
6943 Fortran 77 and later
6948 @item @emph{Syntax}:
6949 @code{RESULT = LOG(X)}
6951 @item @emph{Arguments}:
6952 @multitable @columnfractions .15 .70
6953 @item @var{X} @tab The type shall be @code{REAL} or
6957 @item @emph{Return value}:
6958 The return value is of type @code{REAL} or @code{COMPLEX}.
6959 The kind type parameter is the same as @var{X}.
6961 @item @emph{Example}:
6964 real(8) :: x = 1.0_8
6965 complex :: z = (1.0, 2.0)
6968 end program test_log
6971 @item @emph{Specific names}:
6972 @multitable @columnfractions .20 .20 .20 .25
6973 @item Name @tab Argument @tab Return type @tab Standard
6974 @item @code{ALOG(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab f95, gnu
6975 @item @code{DLOG(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab f95, gnu
6976 @item @code{CLOG(X)} @tab @code{COMPLEX(4) X} @tab @code{COMPLEX(4)} @tab f95, gnu
6977 @item @code{ZLOG(X)} @tab @code{COMPLEX(8) X} @tab @code{COMPLEX(8)} @tab f95, gnu
6978 @item @code{CDLOG(X)} @tab @code{COMPLEX(8) X} @tab @code{COMPLEX(8)} @tab f95, gnu
6985 @section @code{LOG10} --- Base 10 logarithm function
6989 @cindex exponential function, inverse
6990 @cindex logarithmic function
6993 @item @emph{Description}:
6994 @code{LOG10(X)} computes the base 10 logarithm of @var{X}.
6996 @item @emph{Standard}:
6997 Fortran 77 and later
7002 @item @emph{Syntax}:
7003 @code{RESULT = LOG10(X)}
7005 @item @emph{Arguments}:
7006 @multitable @columnfractions .15 .70
7007 @item @var{X} @tab The type shall be @code{REAL}.
7010 @item @emph{Return value}:
7011 The return value is of type @code{REAL} or @code{COMPLEX}.
7012 The kind type parameter is the same as @var{X}.
7014 @item @emph{Example}:
7017 real(8) :: x = 10.0_8
7019 end program test_log10
7022 @item @emph{Specific names}:
7023 @multitable @columnfractions .20 .20 .20 .25
7024 @item Name @tab Argument @tab Return type @tab Standard
7025 @item @code{ALOG10(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab Fortran 95 and later
7026 @item @code{DLOG10(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab Fortran 95 and later
7033 @section @code{LOG_GAMMA} --- Logarithm of the Gamma function
7038 @cindex Gamma function, logarithm of
7041 @item @emph{Description}:
7042 @code{LOG_GAMMA(X)} computes the natural logarithm of the absolute value
7043 of the Gamma (@math{\Gamma}) function.
7045 @item @emph{Standard}:
7046 Fortran 2008 and later
7051 @item @emph{Syntax}:
7052 @code{X = LOG_GAMMA(X)}
7054 @item @emph{Arguments}:
7055 @multitable @columnfractions .15 .70
7056 @item @var{X} @tab Shall be of type @code{REAL} and neither zero
7057 nor a negative integer.
7060 @item @emph{Return value}:
7061 The return value is of type @code{REAL} of the same kind as @var{X}.
7063 @item @emph{Example}:
7065 program test_log_gamma
7067 x = lgamma(x) ! returns 0.0
7068 end program test_log_gamma
7071 @item @emph{Specific names}:
7072 @multitable @columnfractions .20 .20 .20 .25
7073 @item Name @tab Argument @tab Return type @tab Standard
7074 @item @code{LGAMMA(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab GNU Extension
7075 @item @code{ALGAMA(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab GNU Extension
7076 @item @code{DLGAMA(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU Extension
7079 @item @emph{See also}:
7080 Gamma function: @ref{GAMMA}
7087 @section @code{LOGICAL} --- Convert to logical type
7089 @cindex conversion, to logical
7092 @item @emph{Description}:
7093 Converts one kind of @code{LOGICAL} variable to another.
7095 @item @emph{Standard}:
7096 Fortran 95 and later
7101 @item @emph{Syntax}:
7102 @code{RESULT = LOGICAL(L [, KIND])}
7104 @item @emph{Arguments}:
7105 @multitable @columnfractions .15 .70
7106 @item @var{L} @tab The type shall be @code{LOGICAL}.
7107 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
7108 expression indicating the kind parameter of the result.
7111 @item @emph{Return value}:
7112 The return value is a @code{LOGICAL} value equal to @var{L}, with a
7113 kind corresponding to @var{KIND}, or of the default logical kind if
7114 @var{KIND} is not given.
7116 @item @emph{See also}:
7117 @ref{INT}, @ref{REAL}, @ref{CMPLX}
7123 @section @code{LONG} --- Convert to integer type
7125 @cindex conversion, to integer
7128 @item @emph{Description}:
7129 Convert to a @code{KIND=4} integer type, which is the same size as a C
7130 @code{long} integer. This is equivalent to the standard @code{INT}
7131 intrinsic with an optional argument of @code{KIND=4}, and is only
7132 included for backwards compatibility.
7134 @item @emph{Standard}:
7140 @item @emph{Syntax}:
7141 @code{RESULT = LONG(A)}
7143 @item @emph{Arguments}:
7144 @multitable @columnfractions .15 .70
7145 @item @var{A} @tab Shall be of type @code{INTEGER},
7146 @code{REAL}, or @code{COMPLEX}.
7149 @item @emph{Return value}:
7150 The return value is a @code{INTEGER(4)} variable.
7152 @item @emph{See also}:
7153 @ref{INT}, @ref{INT2}, @ref{INT8}
7159 @section @code{LSHIFT} --- Left shift bits
7161 @cindex bits, shift left
7164 @item @emph{Description}:
7165 @code{LSHIFT} returns a value corresponding to @var{I} with all of the
7166 bits shifted left by @var{SHIFT} places. If the absolute value of
7167 @var{SHIFT} is greater than @code{BIT_SIZE(I)}, the value is undefined.
7168 Bits shifted out from the left end are lost; zeros are shifted in from
7171 This function has been superseded by the @code{ISHFT} intrinsic, which
7172 is standard in Fortran 95 and later.
7174 @item @emph{Standard}:
7180 @item @emph{Syntax}:
7181 @code{RESULT = LSHIFT(I, SHIFT)}
7183 @item @emph{Arguments}:
7184 @multitable @columnfractions .15 .70
7185 @item @var{I} @tab The type shall be @code{INTEGER}.
7186 @item @var{SHIFT} @tab The type shall be @code{INTEGER}.
7189 @item @emph{Return value}:
7190 The return value is of type @code{INTEGER} and of the same kind as
7193 @item @emph{See also}:
7194 @ref{ISHFT}, @ref{ISHFTC}, @ref{RSHIFT}
7201 @section @code{LSTAT} --- Get file status
7203 @cindex file system, file status
7206 @item @emph{Description}:
7207 @code{LSTAT} is identical to @ref{STAT}, except that if path is a symbolic link,
7208 then the link itself is statted, not the file that it refers to.
7210 The elements in @code{BUFF} are the same as described by @ref{STAT}.
7212 This intrinsic is provided in both subroutine and function forms; however,
7213 only one form can be used in any given program unit.
7215 @item @emph{Standard}:
7219 Subroutine, function
7221 @item @emph{Syntax}:
7222 @code{CALL LSTAT(FILE, BUFF [, STATUS])}
7224 @item @emph{Arguments}:
7225 @multitable @columnfractions .15 .70
7226 @item @var{FILE} @tab The type shall be @code{CHARACTER} of the default
7227 kind, a valid path within the file system.
7228 @item @var{BUFF} @tab The type shall be @code{INTEGER(4), DIMENSION(13)}.
7229 @item @var{STATUS} @tab (Optional) status flag of type @code{INTEGER(4)}.
7230 Returns 0 on success and a system specific error code otherwise.
7233 @item @emph{Example}:
7234 See @ref{STAT} for an example.
7236 @item @emph{See also}:
7237 To stat an open file: @ref{FSTAT}, to stat a file: @ref{STAT}
7243 @section @code{LTIME} --- Convert time to local time info
7245 @cindex time, conversion to local time info
7248 @item @emph{Description}:
7249 Given a system time value @var{STIME} (as provided by the @code{TIME8()}
7250 intrinsic), fills @var{TARRAY} with values extracted from it appropriate
7251 to the local time zone using @code{localtime(3)}.
7253 @item @emph{Standard}:
7259 @item @emph{Syntax}:
7260 @code{CALL LTIME(STIME, TARRAY)}
7262 @item @emph{Arguments}:
7263 @multitable @columnfractions .15 .70
7264 @item @var{STIME} @tab An @code{INTEGER} scalar expression
7265 corresponding to a system time, with @code{INTENT(IN)}.
7266 @item @var{TARRAY} @tab A default @code{INTEGER} array with 9 elements,
7267 with @code{INTENT(OUT)}.
7270 @item @emph{Return value}:
7271 The elements of @var{TARRAY} are assigned as follows:
7273 @item Seconds after the minute, range 0--59 or 0--61 to allow for leap
7275 @item Minutes after the hour, range 0--59
7276 @item Hours past midnight, range 0--23
7277 @item Day of month, range 0--31
7278 @item Number of months since January, range 0--12
7279 @item Years since 1900
7280 @item Number of days since Sunday, range 0--6
7281 @item Days since January 1
7282 @item Daylight savings indicator: positive if daylight savings is in
7283 effect, zero if not, and negative if the information is not available.
7286 @item @emph{See also}:
7287 @ref{CTIME}, @ref{GMTIME}, @ref{TIME}, @ref{TIME8}
7294 @section @code{MALLOC} --- Allocate dynamic memory
7296 @cindex pointer, cray
7299 @item @emph{Description}:
7300 @code{MALLOC(SIZE)} allocates @var{SIZE} bytes of dynamic memory and
7301 returns the address of the allocated memory. The @code{MALLOC} intrinsic
7302 is an extension intended to be used with Cray pointers, and is provided
7303 in GNU Fortran to allow the user to compile legacy code. For new code
7304 using Fortran 95 pointers, the memory allocation intrinsic is
7307 @item @emph{Standard}:
7313 @item @emph{Syntax}:
7314 @code{PTR = MALLOC(SIZE)}
7316 @item @emph{Arguments}:
7317 @multitable @columnfractions .15 .70
7318 @item @var{SIZE} @tab The type shall be @code{INTEGER}.
7321 @item @emph{Return value}:
7322 The return value is of type @code{INTEGER(K)}, with @var{K} such that
7323 variables of type @code{INTEGER(K)} have the same size as
7324 C pointers (@code{sizeof(void *)}).
7326 @item @emph{Example}:
7327 The following example demonstrates the use of @code{MALLOC} and
7328 @code{FREE} with Cray pointers. This example is intended to run on
7329 32-bit systems, where the default integer kind is suitable to store
7330 pointers; on 64-bit systems, ptr_x would need to be declared as
7331 @code{integer(kind=8)}.
7340 ptr_x = malloc(20*8)
7342 x(i) = sqrt(1.0d0 / i)
7350 end program test_malloc
7353 @item @emph{See also}:
7360 @section @code{MATMUL} --- matrix multiplication
7362 @cindex matrix multiplication
7363 @cindex product, matrix
7366 @item @emph{Description}:
7367 Performs a matrix multiplication on numeric or logical arguments.
7369 @item @emph{Standard}:
7370 Fortran 95 and later
7373 Transformational function
7375 @item @emph{Syntax}:
7376 @code{RESULT = MATMUL(MATRIX_A, MATRIX_B)}
7378 @item @emph{Arguments}:
7379 @multitable @columnfractions .15 .70
7380 @item @var{MATRIX_A} @tab An array of @code{INTEGER},
7381 @code{REAL}, @code{COMPLEX}, or @code{LOGICAL} type, with a rank of
7383 @item @var{MATRIX_B} @tab An array of @code{INTEGER},
7384 @code{REAL}, or @code{COMPLEX} type if @var{MATRIX_A} is of a numeric
7385 type; otherwise, an array of @code{LOGICAL} type. The rank shall be one
7386 or two, and the first (or only) dimension of @var{MATRIX_B} shall be
7387 equal to the last (or only) dimension of @var{MATRIX_A}.
7390 @item @emph{Return value}:
7391 The matrix product of @var{MATRIX_A} and @var{MATRIX_B}. The type and
7392 kind of the result follow the usual type and kind promotion rules, as
7393 for the @code{*} or @code{.AND.} operators.
7395 @item @emph{See also}:
7401 @section @code{MAX} --- Maximum value of an argument list
7408 @cindex maximum value
7411 @item @emph{Description}:
7412 Returns the argument with the largest (most positive) value.
7414 @item @emph{Standard}:
7415 Fortran 77 and later
7420 @item @emph{Syntax}:
7421 @code{RESULT = MAX(A1, A2 [, A3 [, ...]])}
7423 @item @emph{Arguments}:
7424 @multitable @columnfractions .15 .70
7425 @item @var{A1} @tab The type shall be @code{INTEGER} or
7427 @item @var{A2}, @var{A3}, ... @tab An expression of the same type and kind
7428 as @var{A1}. (As a GNU extension, arguments of different kinds are
7432 @item @emph{Return value}:
7433 The return value corresponds to the maximum value among the arguments,
7434 and has the same type and kind as the first argument.
7436 @item @emph{Specific names}:
7437 @multitable @columnfractions .20 .20 .20 .25
7438 @item Name @tab Argument @tab Return type @tab Standard
7439 @item @code{MAX0(I)} @tab @code{INTEGER(4) I} @tab @code{INTEGER(4)} @tab Fortran 77 and later
7440 @item @code{AMAX0(I)} @tab @code{INTEGER(4) I} @tab @code{REAL(MAX(X))} @tab Fortran 77 and later
7441 @item @code{MAX1(X)} @tab @code{REAL X} @tab @code{INT(MAX(X))} @tab Fortran 77 and later
7442 @item @code{AMAX1(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab Fortran 77 and later
7443 @item @code{DMAX1(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab Fortran 77 and later
7446 @item @emph{See also}:
7447 @ref{MAXLOC} @ref{MAXVAL}, @ref{MIN}
7454 @section @code{MAXEXPONENT} --- Maximum exponent of a real kind
7455 @fnindex MAXEXPONENT
7456 @cindex model representation, maximum exponent
7459 @item @emph{Description}:
7460 @code{MAXEXPONENT(X)} returns the maximum exponent in the model of the
7463 @item @emph{Standard}:
7464 Fortran 95 and later
7469 @item @emph{Syntax}:
7470 @code{RESULT = MAXEXPONENT(X)}
7472 @item @emph{Arguments}:
7473 @multitable @columnfractions .15 .70
7474 @item @var{X} @tab Shall be of type @code{REAL}.
7477 @item @emph{Return value}:
7478 The return value is of type @code{INTEGER} and of the default integer
7481 @item @emph{Example}:
7487 print *, minexponent(x), maxexponent(x)
7488 print *, minexponent(y), maxexponent(y)
7489 end program exponents
7496 @section @code{MAXLOC} --- Location of the maximum value within an array
7498 @cindex array, location of maximum element
7501 @item @emph{Description}:
7502 Determines the location of the element in the array with the maximum
7503 value, or, if the @var{DIM} argument is supplied, determines the
7504 locations of the maximum element along each row of the array in the
7505 @var{DIM} direction. If @var{MASK} is present, only the elements for
7506 which @var{MASK} is @code{.TRUE.} are considered. If more than one
7507 element in the array has the maximum value, the location returned is
7508 that of the first such element in array element order. If the array has
7509 zero size, or all of the elements of @var{MASK} are @code{.FALSE.}, then
7510 the result is an array of zeroes. Similarly, if @var{DIM} is supplied
7511 and all of the elements of @var{MASK} along a given row are zero, the
7512 result value for that row is zero.
7514 @item @emph{Standard}:
7515 Fortran 95 and later
7518 Transformational function
7520 @item @emph{Syntax}:
7521 @multitable @columnfractions .80
7522 @item @code{RESULT = MAXLOC(ARRAY, DIM [, MASK])}
7523 @item @code{RESULT = MAXLOC(ARRAY [, MASK])}
7526 @item @emph{Arguments}:
7527 @multitable @columnfractions .15 .70
7528 @item @var{ARRAY} @tab Shall be an array of type @code{INTEGER},
7529 @code{REAL}, or @code{CHARACTER}.
7530 @item @var{DIM} @tab (Optional) Shall be a scalar of type
7531 @code{INTEGER}, with a value between one and the rank of @var{ARRAY},
7532 inclusive. It may not be an optional dummy argument.
7533 @item @var{MASK} @tab Shall be an array of type @code{LOGICAL},
7534 and conformable with @var{ARRAY}.
7537 @item @emph{Return value}:
7538 If @var{DIM} is absent, the result is a rank-one array with a length
7539 equal to the rank of @var{ARRAY}. If @var{DIM} is present, the result
7540 is an array with a rank one less than the rank of @var{ARRAY}, and a
7541 size corresponding to the size of @var{ARRAY} with the @var{DIM}
7542 dimension removed. If @var{DIM} is present and @var{ARRAY} has a rank
7543 of one, the result is a scalar. In all cases, the result is of default
7544 @code{INTEGER} type.
7546 @item @emph{See also}:
7547 @ref{MAX}, @ref{MAXVAL}
7554 @section @code{MAXVAL} --- Maximum value of an array
7556 @cindex array, maximum value
7557 @cindex maximum value
7560 @item @emph{Description}:
7561 Determines the maximum value of the elements in an array value, or, if
7562 the @var{DIM} argument is supplied, determines the maximum value along
7563 each row of the array in the @var{DIM} direction. If @var{MASK} is
7564 present, only the elements for which @var{MASK} is @code{.TRUE.} are
7565 considered. If the array has zero size, or all of the elements of
7566 @var{MASK} are @code{.FALSE.}, then the result is the most negative
7567 number of the type and kind of @var{ARRAY} if @var{ARRAY} is numeric, or
7568 a string of nulls if @var{ARRAY} is of character type.
7570 @item @emph{Standard}:
7571 Fortran 95 and later
7574 Transformational function
7576 @item @emph{Syntax}:
7577 @multitable @columnfractions .80
7578 @item @code{RESULT = MAXVAL(ARRAY, DIM [, MASK])}
7579 @item @code{RESULT = MAXVAL(ARRAY [, MASK])}
7582 @item @emph{Arguments}:
7583 @multitable @columnfractions .15 .70
7584 @item @var{ARRAY} @tab Shall be an array of type @code{INTEGER},
7585 @code{REAL}, or @code{CHARACTER}.
7586 @item @var{DIM} @tab (Optional) Shall be a scalar of type
7587 @code{INTEGER}, with a value between one and the rank of @var{ARRAY},
7588 inclusive. It may not be an optional dummy argument.
7589 @item @var{MASK} @tab Shall be an array of type @code{LOGICAL},
7590 and conformable with @var{ARRAY}.
7593 @item @emph{Return value}:
7594 If @var{DIM} is absent, or if @var{ARRAY} has a rank of one, the result
7595 is a scalar. If @var{DIM} is present, the result is an array with a
7596 rank one less than the rank of @var{ARRAY}, and a size corresponding to
7597 the size of @var{ARRAY} with the @var{DIM} dimension removed. In all
7598 cases, the result is of the same type and kind as @var{ARRAY}.
7600 @item @emph{See also}:
7601 @ref{MAX}, @ref{MAXLOC}
7607 @section @code{MCLOCK} --- Time function
7609 @cindex time, clock ticks
7613 @item @emph{Description}:
7614 Returns the number of clock ticks since the start of the process, based
7615 on the UNIX function @code{clock(3)}.
7617 This intrinsic is not fully portable, such as to systems with 32-bit
7618 @code{INTEGER} types but supporting times wider than 32 bits. Therefore,
7619 the values returned by this intrinsic might be, or become, negative, or
7620 numerically less than previous values, during a single run of the
7623 @item @emph{Standard}:
7629 @item @emph{Syntax}:
7630 @code{RESULT = MCLOCK()}
7632 @item @emph{Return value}:
7633 The return value is a scalar of type @code{INTEGER(4)}, equal to the
7634 number of clock ticks since the start of the process, or @code{-1} if
7635 the system does not support @code{clock(3)}.
7637 @item @emph{See also}:
7638 @ref{CTIME}, @ref{GMTIME}, @ref{LTIME}, @ref{MCLOCK}, @ref{TIME}
7645 @section @code{MCLOCK8} --- Time function (64-bit)
7647 @cindex time, clock ticks
7651 @item @emph{Description}:
7652 Returns the number of clock ticks since the start of the process, based
7653 on the UNIX function @code{clock(3)}.
7655 @emph{Warning:} this intrinsic does not increase the range of the timing
7656 values over that returned by @code{clock(3)}. On a system with a 32-bit
7657 @code{clock(3)}, @code{MCLOCK8()} will return a 32-bit value, even though
7658 it is converted to a 64-bit @code{INTEGER(8)} value. That means
7659 overflows of the 32-bit value can still occur. Therefore, the values
7660 returned by this intrinsic might be or become negative or numerically
7661 less than previous values during a single run of the compiled program.
7663 @item @emph{Standard}:
7669 @item @emph{Syntax}:
7670 @code{RESULT = MCLOCK8()}
7672 @item @emph{Return value}:
7673 The return value is a scalar of type @code{INTEGER(8)}, equal to the
7674 number of clock ticks since the start of the process, or @code{-1} if
7675 the system does not support @code{clock(3)}.
7677 @item @emph{See also}:
7678 @ref{CTIME}, @ref{GMTIME}, @ref{LTIME}, @ref{MCLOCK}, @ref{TIME8}
7685 @section @code{MERGE} --- Merge variables
7687 @cindex array, merge arrays
7688 @cindex array, combine arrays
7691 @item @emph{Description}:
7692 Select values from two arrays according to a logical mask. The result
7693 is equal to @var{TSOURCE} if @var{MASK} is @code{.TRUE.}, or equal to
7694 @var{FSOURCE} if it is @code{.FALSE.}.
7696 @item @emph{Standard}:
7697 Fortran 95 and later
7702 @item @emph{Syntax}:
7703 @code{RESULT = MERGE(TSOURCE, FSOURCE, MASK)}
7705 @item @emph{Arguments}:
7706 @multitable @columnfractions .15 .70
7707 @item @var{TSOURCE} @tab May be of any type.
7708 @item @var{FSOURCE} @tab Shall be of the same type and type parameters
7710 @item @var{MASK} @tab Shall be of type @code{LOGICAL}.
7713 @item @emph{Return value}:
7714 The result is of the same type and type parameters as @var{TSOURCE}.
7721 @section @code{MIN} --- Minimum value of an argument list
7728 @cindex minimum value
7731 @item @emph{Description}:
7732 Returns the argument with the smallest (most negative) value.
7734 @item @emph{Standard}:
7735 Fortran 77 and later
7740 @item @emph{Syntax}:
7741 @code{RESULT = MIN(A1, A2 [, A3, ...])}
7743 @item @emph{Arguments}:
7744 @multitable @columnfractions .15 .70
7745 @item @var{A1} @tab The type shall be @code{INTEGER} or
7747 @item @var{A2}, @var{A3}, ... @tab An expression of the same type and kind
7748 as @var{A1}. (As a GNU extension, arguments of different kinds are
7752 @item @emph{Return value}:
7753 The return value corresponds to the maximum value among the arguments,
7754 and has the same type and kind as the first argument.
7756 @item @emph{Specific names}:
7757 @multitable @columnfractions .20 .20 .20 .25
7758 @item Name @tab Argument @tab Return type @tab Standard
7759 @item @code{MIN0(I)} @tab @code{INTEGER(4) I} @tab @code{INTEGER(4)} @tab Fortran 77 and later
7760 @item @code{AMIN0(I)} @tab @code{INTEGER(4) I} @tab @code{REAL(MIN(X))} @tab Fortran 77 and later
7761 @item @code{MIN1(X)} @tab @code{REAL X} @tab @code{INT(MIN(X))} @tab Fortran 77 and later
7762 @item @code{AMIN1(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab Fortran 77 and later
7763 @item @code{DMIN1(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab Fortran 77 and later
7766 @item @emph{See also}:
7767 @ref{MAX}, @ref{MINLOC}, @ref{MINVAL}
7773 @section @code{MINEXPONENT} --- Minimum exponent of a real kind
7774 @fnindex MINEXPONENT
7775 @cindex model representation, minimum exponent
7778 @item @emph{Description}:
7779 @code{MINEXPONENT(X)} returns the minimum exponent in the model of the
7782 @item @emph{Standard}:
7783 Fortran 95 and later
7788 @item @emph{Syntax}:
7789 @code{RESULT = MINEXPONENT(X)}
7791 @item @emph{Arguments}:
7792 @multitable @columnfractions .15 .70
7793 @item @var{X} @tab Shall be of type @code{REAL}.
7796 @item @emph{Return value}:
7797 The return value is of type @code{INTEGER} and of the default integer
7800 @item @emph{Example}:
7801 See @code{MAXEXPONENT} for an example.
7807 @section @code{MINLOC} --- Location of the minimum value within an array
7809 @cindex array, location of minimum element
7812 @item @emph{Description}:
7813 Determines the location of the element in the array with the minimum
7814 value, or, if the @var{DIM} argument is supplied, determines the
7815 locations of the minimum element along each row of the array in the
7816 @var{DIM} direction. If @var{MASK} is present, only the elements for
7817 which @var{MASK} is @code{.TRUE.} are considered. If more than one
7818 element in the array has the minimum value, the location returned is
7819 that of the first such element in array element order. If the array has
7820 zero size, or all of the elements of @var{MASK} are @code{.FALSE.}, then
7821 the result is an array of zeroes. Similarly, if @var{DIM} is supplied
7822 and all of the elements of @var{MASK} along a given row are zero, the
7823 result value for that row is zero.
7825 @item @emph{Standard}:
7826 Fortran 95 and later
7829 Transformational function
7831 @item @emph{Syntax}:
7832 @multitable @columnfractions .80
7833 @item @code{RESULT = MINLOC(ARRAY, DIM [, MASK])}
7834 @item @code{RESULT = MINLOC(ARRAY [, MASK])}
7837 @item @emph{Arguments}:
7838 @multitable @columnfractions .15 .70
7839 @item @var{ARRAY} @tab Shall be an array of type @code{INTEGER},
7840 @code{REAL}, or @code{CHARACTER}.
7841 @item @var{DIM} @tab (Optional) Shall be a scalar of type
7842 @code{INTEGER}, with a value between one and the rank of @var{ARRAY},
7843 inclusive. It may not be an optional dummy argument.
7844 @item @var{MASK} @tab Shall be an array of type @code{LOGICAL},
7845 and conformable with @var{ARRAY}.
7848 @item @emph{Return value}:
7849 If @var{DIM} is absent, the result is a rank-one array with a length
7850 equal to the rank of @var{ARRAY}. If @var{DIM} is present, the result
7851 is an array with a rank one less than the rank of @var{ARRAY}, and a
7852 size corresponding to the size of @var{ARRAY} with the @var{DIM}
7853 dimension removed. If @var{DIM} is present and @var{ARRAY} has a rank
7854 of one, the result is a scalar. In all cases, the result is of default
7855 @code{INTEGER} type.
7857 @item @emph{See also}:
7858 @ref{MIN}, @ref{MINVAL}
7865 @section @code{MINVAL} --- Minimum value of an array
7867 @cindex array, minimum value
7868 @cindex minimum value
7871 @item @emph{Description}:
7872 Determines the minimum value of the elements in an array value, or, if
7873 the @var{DIM} argument is supplied, determines the minimum value along
7874 each row of the array in the @var{DIM} direction. If @var{MASK} is
7875 present, only the elements for which @var{MASK} is @code{.TRUE.} are
7876 considered. If the array has zero size, or all of the elements of
7877 @var{MASK} are @code{.FALSE.}, then the result is @code{HUGE(ARRAY)} if
7878 @var{ARRAY} is numeric, or a string of @code{CHAR(255)} characters if
7879 @var{ARRAY} is of character type.
7881 @item @emph{Standard}:
7882 Fortran 95 and later
7885 Transformational function
7887 @item @emph{Syntax}:
7888 @multitable @columnfractions .80
7889 @item @code{RESULT = MINVAL(ARRAY, DIM [, MASK])}
7890 @item @code{RESULT = MINVAL(ARRAY [, MASK])}
7893 @item @emph{Arguments}:
7894 @multitable @columnfractions .15 .70
7895 @item @var{ARRAY} @tab Shall be an array of type @code{INTEGER},
7896 @code{REAL}, or @code{CHARACTER}.
7897 @item @var{DIM} @tab (Optional) Shall be a scalar of type
7898 @code{INTEGER}, with a value between one and the rank of @var{ARRAY},
7899 inclusive. It may not be an optional dummy argument.
7900 @item @var{MASK} @tab Shall be an array of type @code{LOGICAL},
7901 and conformable with @var{ARRAY}.
7904 @item @emph{Return value}:
7905 If @var{DIM} is absent, or if @var{ARRAY} has a rank of one, the result
7906 is a scalar. If @var{DIM} is present, the result is an array with a
7907 rank one less than the rank of @var{ARRAY}, and a size corresponding to
7908 the size of @var{ARRAY} with the @var{DIM} dimension removed. In all
7909 cases, the result is of the same type and kind as @var{ARRAY}.
7911 @item @emph{See also}:
7912 @ref{MIN}, @ref{MINLOC}
7919 @section @code{MOD} --- Remainder function
7924 @cindex division, remainder
7927 @item @emph{Description}:
7928 @code{MOD(A,P)} computes the remainder of the division of A by P@. It is
7929 calculated as @code{A - (INT(A/P) * P)}.
7931 @item @emph{Standard}:
7932 Fortran 77 and later
7937 @item @emph{Syntax}:
7938 @code{RESULT = MOD(A, P)}
7940 @item @emph{Arguments}:
7941 @multitable @columnfractions .15 .70
7942 @item @var{A} @tab Shall be a scalar of type @code{INTEGER} or @code{REAL}
7943 @item @var{P} @tab Shall be a scalar of the same type as @var{A} and not
7947 @item @emph{Return value}:
7948 The kind of the return value is the result of cross-promoting
7949 the kinds of the arguments.
7951 @item @emph{Example}:
7955 print *, mod(17.5,5.5)
7956 print *, mod(17.5d0,5.5)
7957 print *, mod(17.5,5.5d0)
7960 print *, mod(-17.5,5.5)
7961 print *, mod(-17.5d0,5.5)
7962 print *, mod(-17.5,5.5d0)
7965 print *, mod(17.5,-5.5)
7966 print *, mod(17.5d0,-5.5)
7967 print *, mod(17.5,-5.5d0)
7968 end program test_mod
7971 @item @emph{Specific names}:
7972 @multitable @columnfractions .20 .20 .20 .25
7973 @item Name @tab Arguments @tab Return type @tab Standard
7974 @item @code{AMOD(A,P)} @tab @code{REAL(4)} @tab @code{REAL(4)} @tab Fortran 95 and later
7975 @item @code{DMOD(A,P)} @tab @code{REAL(8)} @tab @code{REAL(8)} @tab Fortran 95 and later
7982 @section @code{MODULO} --- Modulo function
7985 @cindex division, modulo
7988 @item @emph{Description}:
7989 @code{MODULO(A,P)} computes the @var{A} modulo @var{P}.
7991 @item @emph{Standard}:
7992 Fortran 95 and later
7997 @item @emph{Syntax}:
7998 @code{RESULT = MODULO(A, P)}
8000 @item @emph{Arguments}:
8001 @multitable @columnfractions .15 .70
8002 @item @var{A} @tab Shall be a scalar of type @code{INTEGER} or @code{REAL}
8003 @item @var{P} @tab Shall be a scalar of the same type and kind as @var{A}
8006 @item @emph{Return value}:
8007 The type and kind of the result are those of the arguments.
8009 @item If @var{A} and @var{P} are of type @code{INTEGER}:
8010 @code{MODULO(A,P)} has the value @var{R} such that @code{A=Q*P+R}, where
8011 @var{Q} is an integer and @var{R} is between 0 (inclusive) and @var{P}
8013 @item If @var{A} and @var{P} are of type @code{REAL}:
8014 @code{MODULO(A,P)} has the value of @code{A - FLOOR (A / P) * P}.
8016 In all cases, if @var{P} is zero the result is processor-dependent.
8018 @item @emph{Example}:
8021 print *, modulo(17,3)
8022 print *, modulo(17.5,5.5)
8024 print *, modulo(-17,3)
8025 print *, modulo(-17.5,5.5)
8027 print *, modulo(17,-3)
8028 print *, modulo(17.5,-5.5)
8037 @section @code{MOVE_ALLOC} --- Move allocation from one object to another
8039 @cindex moving allocation
8040 @cindex allocation, moving
8043 @item @emph{Description}:
8044 @code{MOVE_ALLOC(SRC, DEST)} moves the allocation from @var{SRC} to
8045 @var{DEST}. @var{SRC} will become deallocated in the process.
8047 @item @emph{Standard}:
8048 Fortran 2003 and later
8053 @item @emph{Syntax}:
8054 @code{CALL MOVE_ALLOC(SRC, DEST)}
8056 @item @emph{Arguments}:
8057 @multitable @columnfractions .15 .70
8058 @item @var{SRC} @tab @code{ALLOCATABLE}, @code{INTENT(INOUT)}, may be
8059 of any type and kind.
8060 @item @var{DEST} @tab @code{ALLOCATABLE}, @code{INTENT(OUT)}, shall be
8061 of the same type, kind and rank as @var{SRC}.
8064 @item @emph{Return value}:
8067 @item @emph{Example}:
8069 program test_move_alloc
8070 integer, allocatable :: a(:), b(:)
8074 call move_alloc(a, b)
8075 print *, allocated(a), allocated(b)
8077 end program test_move_alloc
8084 @section @code{MVBITS} --- Move bits from one integer to another
8089 @item @emph{Description}:
8090 Moves @var{LEN} bits from positions @var{FROMPOS} through
8091 @code{FROMPOS+LEN-1} of @var{FROM} to positions @var{TOPOS} through
8092 @code{TOPOS+LEN-1} of @var{TO}. The portion of argument @var{TO} not
8093 affected by the movement of bits is unchanged. The values of
8094 @code{FROMPOS+LEN-1} and @code{TOPOS+LEN-1} must be less than
8095 @code{BIT_SIZE(FROM)}.
8097 @item @emph{Standard}:
8098 Fortran 95 and later
8101 Elemental subroutine
8103 @item @emph{Syntax}:
8104 @code{CALL MVBITS(FROM, FROMPOS, LEN, TO, TOPOS)}
8106 @item @emph{Arguments}:
8107 @multitable @columnfractions .15 .70
8108 @item @var{FROM} @tab The type shall be @code{INTEGER}.
8109 @item @var{FROMPOS} @tab The type shall be @code{INTEGER}.
8110 @item @var{LEN} @tab The type shall be @code{INTEGER}.
8111 @item @var{TO} @tab The type shall be @code{INTEGER}, of the
8112 same kind as @var{FROM}.
8113 @item @var{TOPOS} @tab The type shall be @code{INTEGER}.
8116 @item @emph{See also}:
8117 @ref{IBCLR}, @ref{IBSET}, @ref{IBITS}, @ref{IAND}, @ref{IOR}, @ref{IEOR}
8123 @section @code{NEAREST} --- Nearest representable number
8125 @cindex real number, nearest different
8126 @cindex floating point, nearest different
8129 @item @emph{Description}:
8130 @code{NEAREST(X, S)} returns the processor-representable number nearest
8131 to @code{X} in the direction indicated by the sign of @code{S}.
8133 @item @emph{Standard}:
8134 Fortran 95 and later
8139 @item @emph{Syntax}:
8140 @code{RESULT = NEAREST(X, S)}
8142 @item @emph{Arguments}:
8143 @multitable @columnfractions .15 .70
8144 @item @var{X} @tab Shall be of type @code{REAL}.
8145 @item @var{S} @tab (Optional) shall be of type @code{REAL} and
8149 @item @emph{Return value}:
8150 The return value is of the same type as @code{X}. If @code{S} is
8151 positive, @code{NEAREST} returns the processor-representable number
8152 greater than @code{X} and nearest to it. If @code{S} is negative,
8153 @code{NEAREST} returns the processor-representable number smaller than
8154 @code{X} and nearest to it.
8156 @item @emph{Example}:
8158 program test_nearest
8160 x = nearest(42.0, 1.0)
8161 y = nearest(42.0, -1.0)
8162 write (*,"(3(G20.15))") x, y, x - y
8163 end program test_nearest
8170 @section @code{NEW_LINE} --- New line character
8173 @cindex output, newline
8176 @item @emph{Description}:
8177 @code{NEW_LINE(C)} returns the new-line character.
8179 @item @emph{Standard}:
8180 Fortran 2003 and later
8185 @item @emph{Syntax}:
8186 @code{RESULT = NEW_LINE(C)}
8188 @item @emph{Arguments}:
8189 @multitable @columnfractions .15 .70
8190 @item @var{C} @tab The argument shall be a scalar or array of the
8191 type @code{CHARACTER}.
8194 @item @emph{Return value}:
8195 Returns a @var{CHARACTER} scalar of length one with the new-line character of
8196 the same kind as parameter @var{C}.
8198 @item @emph{Example}:
8202 write(*,'(A)') 'This is record 1.'//NEW_LINE('A')//'This is record 2.'
8210 @section @code{NINT} --- Nearest whole number
8213 @cindex rounding, nearest whole number
8216 @item @emph{Description}:
8217 @code{NINT(X)} rounds its argument to the nearest whole number.
8219 @item @emph{Standard}:
8220 Fortran 77 and later, with @var{KIND} argument Fortran 90 and later
8225 @item @emph{Syntax}:
8226 @code{RESULT = NINT(X [, KIND])}
8228 @item @emph{Arguments}:
8229 @multitable @columnfractions .15 .70
8230 @item @var{X} @tab The type of the argument shall be @code{REAL}.
8231 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
8232 expression indicating the kind parameter of the result.
8235 @item @emph{Return value}:
8236 Returns @var{A} with the fractional portion of its magnitude eliminated by
8237 rounding to the nearest whole number and with its sign preserved,
8238 converted to an @code{INTEGER} of the default kind.
8240 @item @emph{Example}:
8247 print *, nint(x4), idnint(x8)
8248 end program test_nint
8251 @item @emph{Specific names}:
8252 @multitable @columnfractions .25 .25 .25
8253 @item Name @tab Argument @tab Standard
8254 @item @code{IDNINT(X)} @tab @code{REAL(8)} @tab Fortran 95 and later
8257 @item @emph{See also}:
8258 @ref{CEILING}, @ref{FLOOR}
8265 @section @code{NOT} --- Logical negation
8267 @cindex bits, negate
8268 @cindex bitwise logical not
8269 @cindex logical not, bitwise
8272 @item @emph{Description}:
8273 @code{NOT} returns the bitwise boolean inverse of @var{I}.
8275 @item @emph{Standard}:
8276 Fortran 95 and later
8281 @item @emph{Syntax}:
8282 @code{RESULT = NOT(I)}
8284 @item @emph{Arguments}:
8285 @multitable @columnfractions .15 .70
8286 @item @var{I} @tab The type shall be @code{INTEGER}.
8289 @item @emph{Return value}:
8290 The return type is @code{INTEGER}, of the same kind as the
8293 @item @emph{See also}:
8294 @ref{IAND}, @ref{IEOR}, @ref{IOR}, @ref{IBITS}, @ref{IBSET}, @ref{IBCLR}
8301 @section @code{NULL} --- Function that returns an disassociated pointer
8303 @cindex pointer, status
8304 @cindex pointer, disassociated
8307 @item @emph{Description}:
8308 Returns a disassociated pointer.
8310 If @var{MOLD} is present, a dissassociated pointer of the same type is
8311 returned, otherwise the type is determined by context.
8313 In Fortran 95, @var{MOLD} is optional. Please note that Fortran 2003
8314 includes cases where it is required.
8316 @item @emph{Standard}:
8317 Fortran 95 and later
8320 Transformational function
8322 @item @emph{Syntax}:
8323 @code{PTR => NULL([MOLD])}
8325 @item @emph{Arguments}:
8326 @multitable @columnfractions .15 .70
8327 @item @var{MOLD} @tab (Optional) shall be a pointer of any association
8328 status and of any type.
8331 @item @emph{Return value}:
8332 A disassociated pointer.
8334 @item @emph{Example}:
8336 REAL, POINTER, DIMENSION(:) :: VEC => NULL ()
8339 @item @emph{See also}:
8346 @section @code{OR} --- Bitwise logical OR
8348 @cindex bitwise logical or
8349 @cindex logical or, bitwise
8352 @item @emph{Description}:
8353 Bitwise logical @code{OR}.
8355 This intrinsic routine is provided for backwards compatibility with
8356 GNU Fortran 77. For integer arguments, programmers should consider
8357 the use of the @ref{IOR} intrinsic defined by the Fortran standard.
8359 @item @emph{Standard}:
8365 @item @emph{Syntax}:
8366 @code{RESULT = OR(X, Y)}
8368 @item @emph{Arguments}:
8369 @multitable @columnfractions .15 .70
8370 @item @var{X} @tab The type shall be either a scalar @code{INTEGER}
8371 type or a scalar @code{LOGICAL} type.
8372 @item @var{Y} @tab The type shall be the same as the type of @var{X}.
8375 @item @emph{Return value}:
8376 The return type is either a scalar @code{INTEGER} or a scalar
8377 @code{LOGICAL}. If the kind type parameters differ, then the
8378 smaller kind type is implicitly converted to larger kind, and the
8379 return has the larger kind.
8381 @item @emph{Example}:
8384 LOGICAL :: T = .TRUE., F = .FALSE.
8386 DATA a / Z'F' /, b / Z'3' /
8388 WRITE (*,*) OR(T, T), OR(T, F), OR(F, T), OR(F, F)
8389 WRITE (*,*) OR(a, b)
8393 @item @emph{See also}:
8394 Fortran 95 elemental function: @ref{IOR}
8400 @section @code{PACK} --- Pack an array into an array of rank one
8402 @cindex array, packing
8403 @cindex array, reduce dimension
8404 @cindex array, gather elements
8407 @item @emph{Description}:
8408 Stores the elements of @var{ARRAY} in an array of rank one.
8410 The beginning of the resulting array is made up of elements whose @var{MASK}
8411 equals @code{TRUE}. Afterwards, positions are filled with elements taken from
8414 @item @emph{Standard}:
8415 Fortran 95 and later
8418 Transformational function
8420 @item @emph{Syntax}:
8421 @code{RESULT = PACK(ARRAY, MASK[,VECTOR]}
8423 @item @emph{Arguments}:
8424 @multitable @columnfractions .15 .70
8425 @item @var{ARRAY} @tab Shall be an array of any type.
8426 @item @var{MASK} @tab Shall be an array of type @code{LOGICAL} and
8427 of the same size as @var{ARRAY}. Alternatively, it may be a @code{LOGICAL}
8429 @item @var{VECTOR} @tab (Optional) shall be an array of the same type
8430 as @var{ARRAY} and of rank one. If present, the number of elements in
8431 @var{VECTOR} shall be equal to or greater than the number of true elements
8432 in @var{MASK}. If @var{MASK} is scalar, the number of elements in
8433 @var{VECTOR} shall be equal to or greater than the number of elements in
8437 @item @emph{Return value}:
8438 The result is an array of rank one and the same type as that of @var{ARRAY}.
8439 If @var{VECTOR} is present, the result size is that of @var{VECTOR}, the
8440 number of @code{TRUE} values in @var{MASK} otherwise.
8442 @item @emph{Example}:
8443 Gathering nonzero elements from an array:
8447 m = (/ 1, 0, 0, 0, 5, 0 /)
8448 WRITE(*, FMT="(6(I0, ' '))") pack(m, m /= 0) ! "1 5"
8452 Gathering nonzero elements from an array and appending elements from @var{VECTOR}:
8456 m = (/ 1, 0, 0, 2 /)
8457 WRITE(*, FMT="(4(I0, ' '))") pack(m, m /= 0, (/ 0, 0, 3, 4 /)) ! "1 2 3 4"
8461 @item @emph{See also}:
8468 @section @code{PERROR} --- Print system error message
8470 @cindex system, error handling
8473 @item @emph{Description}:
8474 Prints (on the C @code{stderr} stream) a newline-terminated error
8475 message corresponding to the last system error. This is prefixed by
8476 @var{STRING}, a colon and a space. See @code{perror(3)}.
8478 @item @emph{Standard}:
8484 @item @emph{Syntax}:
8485 @code{CALL PERROR(STRING)}
8487 @item @emph{Arguments}:
8488 @multitable @columnfractions .15 .70
8489 @item @var{STRING} @tab A scalar of type @code{CHARACTER} and of the
8493 @item @emph{See also}:
8500 @section @code{PRECISION} --- Decimal precision of a real kind
8502 @cindex model representation, precision
8505 @item @emph{Description}:
8506 @code{PRECISION(X)} returns the decimal precision in the model of the
8509 @item @emph{Standard}:
8510 Fortran 95 and later
8515 @item @emph{Syntax}:
8516 @code{RESULT = PRECISION(X)}
8518 @item @emph{Arguments}:
8519 @multitable @columnfractions .15 .70
8520 @item @var{X} @tab Shall be of type @code{REAL} or @code{COMPLEX}.
8523 @item @emph{Return value}:
8524 The return value is of type @code{INTEGER} and of the default integer
8527 @item @emph{Example}:
8529 program prec_and_range
8530 real(kind=4) :: x(2)
8531 complex(kind=8) :: y
8533 print *, precision(x), range(x)
8534 print *, precision(y), range(y)
8535 end program prec_and_range
8542 @section @code{PRESENT} --- Determine whether an optional dummy argument is specified
8546 @item @emph{Description}:
8547 Determines whether an optional dummy argument is present.
8549 @item @emph{Standard}:
8550 Fortran 95 and later
8555 @item @emph{Syntax}:
8556 @code{RESULT = PRESENT(A)}
8558 @item @emph{Arguments}:
8559 @multitable @columnfractions .15 .70
8560 @item @var{A} @tab May be of any type and may be a pointer, scalar or array
8561 value, or a dummy procedure. It shall be the name of an optional dummy argument
8562 accessible within the current subroutine or function.
8565 @item @emph{Return value}:
8566 Returns either @code{TRUE} if the optional argument @var{A} is present, or
8567 @code{FALSE} otherwise.
8569 @item @emph{Example}:
8571 PROGRAM test_present
8572 WRITE(*,*) f(), f(42) ! "F T"
8574 LOGICAL FUNCTION f(x)
8575 INTEGER, INTENT(IN), OPTIONAL :: x
8585 @section @code{PRODUCT} --- Product of array elements
8587 @cindex array, product
8588 @cindex array, multiply elements
8589 @cindex array, conditionally multiply elements
8590 @cindex multiply array elements
8593 @item @emph{Description}:
8594 Multiplies the elements of @var{ARRAY} along dimension @var{DIM} if
8595 the corresponding element in @var{MASK} is @code{TRUE}.
8597 @item @emph{Standard}:
8598 Fortran 95 and later
8601 Transformational function
8603 @item @emph{Syntax}:
8604 @code{RESULT = PRODUCT(ARRAY[, MASK])}
8605 @code{RESULT = PRODUCT(ARRAY, DIM[, MASK])}
8607 @item @emph{Arguments}:
8608 @multitable @columnfractions .15 .70
8609 @item @var{ARRAY} @tab Shall be an array of type @code{INTEGER},
8610 @code{REAL} or @code{COMPLEX}.
8611 @item @var{DIM} @tab (Optional) shall be a scalar of type
8612 @code{INTEGER} with a value in the range from 1 to n, where n
8613 equals the rank of @var{ARRAY}.
8614 @item @var{MASK} @tab (Optional) shall be of type @code{LOGICAL}
8615 and either be a scalar or an array of the same shape as @var{ARRAY}.
8618 @item @emph{Return value}:
8619 The result is of the same type as @var{ARRAY}.
8621 If @var{DIM} is absent, a scalar with the product of all elements in
8622 @var{ARRAY} is returned. Otherwise, an array of rank n-1, where n equals
8623 the rank of @var{ARRAY}, and a shape similar to that of @var{ARRAY} with
8624 dimension @var{DIM} dropped is returned.
8627 @item @emph{Example}:
8629 PROGRAM test_product
8630 INTEGER :: x(5) = (/ 1, 2, 3, 4 ,5 /)
8631 print *, PRODUCT(x) ! all elements, product = 120
8632 print *, PRODUCT(x, MASK=MOD(x, 2)==1) ! odd elements, product = 15
8636 @item @emph{See also}:
8643 @section @code{RADIX} --- Base of a model number
8645 @cindex model representation, base
8646 @cindex model representation, radix
8649 @item @emph{Description}:
8650 @code{RADIX(X)} returns the base of the model representing the entity @var{X}.
8652 @item @emph{Standard}:
8653 Fortran 95 and later
8658 @item @emph{Syntax}:
8659 @code{RESULT = RADIX(X)}
8661 @item @emph{Arguments}:
8662 @multitable @columnfractions .15 .70
8663 @item @var{X} @tab Shall be of type @code{INTEGER} or @code{REAL}
8666 @item @emph{Return value}:
8667 The return value is a scalar of type @code{INTEGER} and of the default
8670 @item @emph{Example}:
8673 print *, "The radix for the default integer kind is", radix(0)
8674 print *, "The radix for the default real kind is", radix(0.0)
8675 end program test_radix
8683 @section @code{RAN} --- Real pseudo-random number
8685 @cindex random number generation
8688 @item @emph{Description}:
8689 For compatibility with HP FORTRAN 77/iX, the @code{RAN} intrinsic is
8690 provided as an alias for @code{RAND}. See @ref{RAND} for complete
8693 @item @emph{Standard}:
8699 @item @emph{See also}:
8700 @ref{RAND}, @ref{RANDOM_NUMBER}
8706 @section @code{RAND} --- Real pseudo-random number
8708 @cindex random number generation
8711 @item @emph{Description}:
8712 @code{RAND(FLAG)} returns a pseudo-random number from a uniform
8713 distribution between 0 and 1. If @var{FLAG} is 0, the next number
8714 in the current sequence is returned; if @var{FLAG} is 1, the generator
8715 is restarted by @code{CALL SRAND(0)}; if @var{FLAG} has any other value,
8716 it is used as a new seed with @code{SRAND}.
8718 This intrinsic routine is provided for backwards compatibility with
8719 GNU Fortran 77. It implements a simple modulo generator as provided
8720 by @command{g77}. For new code, one should consider the use of
8721 @ref{RANDOM_NUMBER} as it implements a superior algorithm.
8723 @item @emph{Standard}:
8729 @item @emph{Syntax}:
8730 @code{RESULT = RAND(FLAG)}
8732 @item @emph{Arguments}:
8733 @multitable @columnfractions .15 .70
8734 @item @var{FLAG} @tab Shall be a scalar @code{INTEGER} of kind 4.
8737 @item @emph{Return value}:
8738 The return value is of @code{REAL} type and the default kind.
8740 @item @emph{Example}:
8743 integer,parameter :: seed = 86456
8746 print *, rand(), rand(), rand(), rand()
8747 print *, rand(seed), rand(), rand(), rand()
8748 end program test_rand
8751 @item @emph{See also}:
8752 @ref{SRAND}, @ref{RANDOM_NUMBER}
8759 @section @code{RANDOM_NUMBER} --- Pseudo-random number
8760 @fnindex RANDOM_NUMBER
8761 @cindex random number generation
8764 @item @emph{Description}:
8765 Returns a single pseudorandom number or an array of pseudorandom numbers
8766 from the uniform distribution over the range @math{ 0 \leq x < 1}.
8768 The runtime-library implements George Marsaglia's KISS (Keep It Simple
8769 Stupid) random number generator (RNG). This RNG combines:
8771 @item The congruential generator @math{x(n) = 69069 \cdot x(n-1) + 1327217885}
8772 with a period of @math{2^{32}},
8773 @item A 3-shift shift-register generator with a period of @math{2^{32} - 1},
8774 @item Two 16-bit multiply-with-carry generators with a period of
8775 @math{597273182964842497 > 2^{59}}.
8777 The overall period exceeds @math{2^{123}}.
8779 Please note, this RNG is thread safe if used within OpenMP directives,
8780 i.e., its state will be consistent while called from multiple threads.
8781 However, the KISS generator does not create random numbers in parallel
8782 from multiple sources, but in sequence from a single source. If an
8783 OpenMP-enabled application heavily relies on random numbers, one should
8784 consider employing a dedicated parallel random number generator instead.
8786 @item @emph{Standard}:
8787 Fortran 95 and later
8792 @item @emph{Syntax}:
8793 @code{RANDOM_NUMBER(HARVEST)}
8795 @item @emph{Arguments}:
8796 @multitable @columnfractions .15 .70
8797 @item @var{HARVEST} @tab Shall be a scalar or an array of type @code{REAL}.
8800 @item @emph{Example}:
8802 program test_random_number
8804 CALL init_random_seed() ! see example of RANDOM_SEED
8805 CALL RANDOM_NUMBER(r)
8809 @item @emph{See also}:
8816 @section @code{RANDOM_SEED} --- Initialize a pseudo-random number sequence
8817 @fnindex RANDOM_SEED
8818 @cindex random number generation, seeding
8819 @cindex seeding a random number generator
8822 @item @emph{Description}:
8823 Restarts or queries the state of the pseudorandom number generator used by
8824 @code{RANDOM_NUMBER}.
8826 If @code{RANDOM_SEED} is called without arguments, it is initialized to
8827 a default state. The example below shows how to initialize the random
8828 seed based on the system's time.
8830 @item @emph{Standard}:
8831 Fortran 95 and later
8836 @item @emph{Syntax}:
8837 @code{CALL RANDOM_SEED(SIZE, PUT, GET)}
8839 @item @emph{Arguments}:
8840 @multitable @columnfractions .15 .70
8841 @item @var{SIZE} @tab (Optional) Shall be a scalar and of type default
8842 @code{INTEGER}, with @code{INTENT(OUT)}. It specifies the minimum size
8843 of the arrays used with the @var{PUT} and @var{GET} arguments.
8844 @item @var{PUT} @tab (Optional) Shall be an array of type default
8845 @code{INTEGER} and rank one. It is @code{INTENT(IN)} and the size of
8846 the array must be larger than or equal to the number returned by the
8847 @var{SIZE} argument.
8848 @item @var{GET} @tab (Optional) Shall be an array of type default
8849 @code{INTEGER} and rank one. It is @code{INTENT(OUT)} and the size
8850 of the array must be larger than or equal to the number returned by
8851 the @var{SIZE} argument.
8854 @item @emph{Example}:
8856 SUBROUTINE init_random_seed()
8857 INTEGER :: i, n, clock
8858 INTEGER, DIMENSION(:), ALLOCATABLE :: seed
8860 CALL RANDOM_SEED(size = n)
8863 CALL SYSTEM_CLOCK(COUNT=clock)
8865 seed = clock + 37 * (/ (i - 1, i = 1, n) /)
8866 CALL RANDOM_SEED(PUT = seed)
8872 @item @emph{See also}:
8879 @section @code{RANGE} --- Decimal exponent range of a real kind
8881 @cindex model representation, range
8884 @item @emph{Description}:
8885 @code{RANGE(X)} returns the decimal exponent range in the model of the
8888 @item @emph{Standard}:
8889 Fortran 95 and later
8894 @item @emph{Syntax}:
8895 @code{RESULT = RANGE(X)}
8897 @item @emph{Arguments}:
8898 @multitable @columnfractions .15 .70
8899 @item @var{X} @tab Shall be of type @code{REAL} or @code{COMPLEX}.
8902 @item @emph{Return value}:
8903 The return value is of type @code{INTEGER} and of the default integer
8906 @item @emph{Example}:
8907 See @code{PRECISION} for an example.
8913 @section @code{REAL} --- Convert to real type
8916 @cindex conversion, to real
8917 @cindex complex numbers, real part
8920 @item @emph{Description}:
8921 @code{REAL(X [, KIND])} converts its argument @var{X} to a real type. The
8922 @code{REALPART(X)} function is provided for compatibility with @command{g77},
8923 and its use is strongly discouraged.
8925 @item @emph{Standard}:
8926 Fortran 77 and later
8931 @item @emph{Syntax}:
8932 @multitable @columnfractions .80
8933 @item @code{RESULT = REAL(X [, KIND])}
8934 @item @code{RESULT = REALPART(Z)}
8937 @item @emph{Arguments}:
8938 @multitable @columnfractions .15 .70
8939 @item @var{X} @tab Shall be @code{INTEGER}, @code{REAL}, or
8941 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
8942 expression indicating the kind parameter of the result.
8945 @item @emph{Return value}:
8946 These functions return a @code{REAL} variable or array under
8947 the following rules:
8951 @code{REAL(X)} is converted to a default real type if @var{X} is an
8952 integer or real variable.
8954 @code{REAL(X)} is converted to a real type with the kind type parameter
8955 of @var{X} if @var{X} is a complex variable.
8957 @code{REAL(X, KIND)} is converted to a real type with kind type
8958 parameter @var{KIND} if @var{X} is a complex, integer, or real
8962 @item @emph{Example}:
8965 complex :: x = (1.0, 2.0)
8966 print *, real(x), real(x,8), realpart(x)
8967 end program test_real
8970 @item @emph{See also}:
8971 @ref{DBLE}, @ref{DFLOAT}, @ref{FLOAT}
8978 @section @code{RENAME} --- Rename a file
8980 @cindex file system, rename file
8983 @item @emph{Description}:
8984 Renames a file from file @var{PATH1} to @var{PATH2}. A null
8985 character (@code{CHAR(0)}) can be used to mark the end of the names in
8986 @var{PATH1} and @var{PATH2}; otherwise, trailing blanks in the file
8987 names are ignored. If the @var{STATUS} argument is supplied, it
8988 contains 0 on success or a nonzero error code upon return; see
8991 This intrinsic is provided in both subroutine and function forms;
8992 however, only one form can be used in any given program unit.
8994 @item @emph{Standard}:
8998 Subroutine, function
9000 @item @emph{Syntax}:
9001 @multitable @columnfractions .80
9002 @item @code{CALL RENAME(PATH1, PATH2 [, STATUS])}
9003 @item @code{STATUS = RENAME(PATH1, PATH2)}
9006 @item @emph{Arguments}:
9007 @multitable @columnfractions .15 .70
9008 @item @var{PATH1} @tab Shall be of default @code{CHARACTER} type.
9009 @item @var{PATH2} @tab Shall be of default @code{CHARACTER} type.
9010 @item @var{STATUS} @tab (Optional) Shall be of default @code{INTEGER} type.
9013 @item @emph{See also}:
9021 @section @code{REPEAT} --- Repeated string concatenation
9023 @cindex string, repeat
9024 @cindex string, concatenate
9027 @item @emph{Description}:
9028 Concatenates @var{NCOPIES} copies of a string.
9030 @item @emph{Standard}:
9031 Fortran 95 and later
9034 Transformational function
9036 @item @emph{Syntax}:
9037 @code{RESULT = REPEAT(STRING, NCOPIES)}
9039 @item @emph{Arguments}:
9040 @multitable @columnfractions .15 .70
9041 @item @var{STRING} @tab Shall be scalar and of type @code{CHARACTER}.
9042 @item @var{NCOPIES} @tab Shall be scalar and of type @code{INTEGER}.
9045 @item @emph{Return value}:
9046 A new scalar of type @code{CHARACTER} built up from @var{NCOPIES} copies
9049 @item @emph{Example}:
9052 write(*,*) repeat("x", 5) ! "xxxxx"
9060 @section @code{RESHAPE} --- Function to reshape an array
9062 @cindex array, change dimensions
9063 @cindex array, transmogrify
9066 @item @emph{Description}:
9067 Reshapes @var{SOURCE} to correspond to @var{SHAPE}. If necessary,
9068 the new array may be padded with elements from @var{PAD} or permuted
9069 as defined by @var{ORDER}.
9071 @item @emph{Standard}:
9072 Fortran 95 and later
9075 Transformational function
9077 @item @emph{Syntax}:
9078 @code{RESULT = RESHAPE(SOURCE, SHAPE[, PAD, ORDER])}
9080 @item @emph{Arguments}:
9081 @multitable @columnfractions .15 .70
9082 @item @var{SOURCE} @tab Shall be an array of any type.
9083 @item @var{SHAPE} @tab Shall be of type @code{INTEGER} and an
9084 array of rank one. Its values must be positive or zero.
9085 @item @var{PAD} @tab (Optional) shall be an array of the same
9086 type as @var{SOURCE}.
9087 @item @var{ORDER} @tab (Optional) shall be of type @code{INTEGER}
9088 and an array of the same shape as @var{SHAPE}. Its values shall
9089 be a permutation of the numbers from 1 to n, where n is the size of
9090 @var{SHAPE}. If @var{ORDER} is absent, the natural ordering shall
9094 @item @emph{Return value}:
9095 The result is an array of shape @var{SHAPE} with the same type as
9098 @item @emph{Example}:
9100 PROGRAM test_reshape
9101 INTEGER, DIMENSION(4) :: x
9102 WRITE(*,*) SHAPE(x) ! prints "4"
9103 WRITE(*,*) SHAPE(RESHAPE(x, (/2, 2/))) ! prints "2 2"
9107 @item @emph{See also}:
9114 @section @code{RRSPACING} --- Reciprocal of the relative spacing
9116 @cindex real number, relative spacing
9117 @cindex floating point, relative spacing
9121 @item @emph{Description}:
9122 @code{RRSPACING(X)} returns the reciprocal of the relative spacing of
9123 model numbers near @var{X}.
9125 @item @emph{Standard}:
9126 Fortran 95 and later
9131 @item @emph{Syntax}:
9132 @code{RESULT = RRSPACING(X)}
9134 @item @emph{Arguments}:
9135 @multitable @columnfractions .15 .70
9136 @item @var{X} @tab Shall be of type @code{REAL}.
9139 @item @emph{Return value}:
9140 The return value is of the same type and kind as @var{X}.
9141 The value returned is equal to
9142 @code{ABS(FRACTION(X)) * FLOAT(RADIX(X))**DIGITS(X)}.
9144 @item @emph{See also}:
9151 @section @code{RSHIFT} --- Right shift bits
9153 @cindex bits, shift right
9156 @item @emph{Description}:
9157 @code{RSHIFT} returns a value corresponding to @var{I} with all of the
9158 bits shifted right by @var{SHIFT} places. If the absolute value of
9159 @var{SHIFT} is greater than @code{BIT_SIZE(I)}, the value is undefined.
9160 Bits shifted out from the left end are lost; zeros are shifted in from
9163 This function has been superseded by the @code{ISHFT} intrinsic, which
9164 is standard in Fortran 95 and later.
9166 @item @emph{Standard}:
9172 @item @emph{Syntax}:
9173 @code{RESULT = RSHIFT(I, SHIFT)}
9175 @item @emph{Arguments}:
9176 @multitable @columnfractions .15 .70
9177 @item @var{I} @tab The type shall be @code{INTEGER}.
9178 @item @var{SHIFT} @tab The type shall be @code{INTEGER}.
9181 @item @emph{Return value}:
9182 The return value is of type @code{INTEGER} and of the same kind as
9185 @item @emph{See also}:
9186 @ref{ISHFT}, @ref{ISHFTC}, @ref{LSHIFT}
9193 @section @code{SCALE} --- Scale a real value
9195 @cindex real number, scale
9196 @cindex floating point, scale
9199 @item @emph{Description}:
9200 @code{SCALE(X,I)} returns @code{X * RADIX(X)**I}.
9202 @item @emph{Standard}:
9203 Fortran 95 and later
9208 @item @emph{Syntax}:
9209 @code{RESULT = SCALE(X, I)}
9211 @item @emph{Arguments}:
9212 @multitable @columnfractions .15 .70
9213 @item @var{X} @tab The type of the argument shall be a @code{REAL}.
9214 @item @var{I} @tab The type of the argument shall be a @code{INTEGER}.
9217 @item @emph{Return value}:
9218 The return value is of the same type and kind as @var{X}.
9219 Its value is @code{X * RADIX(X)**I}.
9221 @item @emph{Example}:
9224 real :: x = 178.1387e-4
9226 print *, scale(x,i), x*radix(x)**i
9227 end program test_scale
9235 @section @code{SCAN} --- Scan a string for the presence of a set of characters
9237 @cindex string, find subset
9240 @item @emph{Description}:
9241 Scans a @var{STRING} for any of the characters in a @var{SET}
9244 If @var{BACK} is either absent or equals @code{FALSE}, this function
9245 returns the position of the leftmost character of @var{STRING} that is
9246 in @var{SET}. If @var{BACK} equals @code{TRUE}, the rightmost position
9247 is returned. If no character of @var{SET} is found in @var{STRING}, the
9250 @item @emph{Standard}:
9251 Fortran 95 and later, with @var{KIND} argument Fortran 2003 and later
9256 @item @emph{Syntax}:
9257 @code{RESULT = SCAN(STRING, SET[, BACK [, KIND]])}
9259 @item @emph{Arguments}:
9260 @multitable @columnfractions .15 .70
9261 @item @var{STRING} @tab Shall be of type @code{CHARACTER}.
9262 @item @var{SET} @tab Shall be of type @code{CHARACTER}.
9263 @item @var{BACK} @tab (Optional) shall be of type @code{LOGICAL}.
9264 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
9265 expression indicating the kind parameter of the result.
9268 @item @emph{Return value}:
9269 The return value is of type @code{INTEGER} and of kind @var{KIND}. If
9270 @var{KIND} is absent, the return value is of default integer kind.
9272 @item @emph{Example}:
9275 WRITE(*,*) SCAN("FORTRAN", "AO") ! 2, found 'O'
9276 WRITE(*,*) SCAN("FORTRAN", "AO", .TRUE.) ! 6, found 'A'
9277 WRITE(*,*) SCAN("FORTRAN", "C++") ! 0, found none
9281 @item @emph{See also}:
9282 @ref{INDEX intrinsic}, @ref{VERIFY}
9288 @section @code{SECNDS} --- Time function
9290 @cindex time, elapsed
9291 @cindex elapsed time
9294 @item @emph{Description}:
9295 @code{SECNDS(X)} gets the time in seconds from the real-time system clock.
9296 @var{X} is a reference time, also in seconds. If this is zero, the time in
9297 seconds from midnight is returned. This function is non-standard and its
9300 @item @emph{Standard}:
9306 @item @emph{Syntax}:
9307 @code{RESULT = SECNDS (X)}
9309 @item @emph{Arguments}:
9310 @multitable @columnfractions .15 .70
9311 @item @var{T} @tab Shall be of type @code{REAL(4)}.
9312 @item @var{X} @tab Shall be of type @code{REAL(4)}.
9315 @item @emph{Return value}:
9318 @item @emph{Example}:
9323 print *, secnds (0.0) ! seconds since midnight
9324 t1 = secnds (0.0) ! reference time
9325 do i = 1, 10000000 ! do something
9327 t2 = secnds (t1) ! elapsed time
9328 print *, "Something took ", t2, " seconds."
9329 end program test_secnds
9336 @section @code{SECOND} --- CPU time function
9338 @cindex time, elapsed
9339 @cindex elapsed time
9342 @item @emph{Description}:
9343 Returns a @code{REAL(4)} value representing the elapsed CPU time in
9344 seconds. This provides the same functionality as the standard
9345 @code{CPU_TIME} intrinsic, and is only included for backwards
9348 This intrinsic is provided in both subroutine and function forms;
9349 however, only one form can be used in any given program unit.
9351 @item @emph{Standard}:
9355 Subroutine, function
9357 @item @emph{Syntax}:
9358 @multitable @columnfractions .80
9359 @item @code{CALL SECOND(TIME)}
9360 @item @code{TIME = SECOND()}
9363 @item @emph{Arguments}:
9364 @multitable @columnfractions .15 .70
9365 @item @var{TIME} @tab Shall be of type @code{REAL(4)}.
9368 @item @emph{Return value}:
9369 In either syntax, @var{TIME} is set to the process's current runtime in
9372 @item @emph{See also}:
9379 @node SELECTED_CHAR_KIND
9380 @section @code{SELECTED_CHAR_KIND} --- Choose character kind
9381 @fnindex SELECTED_CHAR_KIND
9382 @cindex character kind
9383 @cindex kind, character
9386 @item @emph{Description}:
9388 @code{SELECTED_CHAR_KIND(NAME)} returns the kind value for the character
9389 set named @var{NAME}, if a character set with such a name is supported,
9390 or @math{-1} otherwise. Currently, supported character sets include
9391 ``ASCII'' and ``DEFAULT'', which are equivalent.
9393 @item @emph{Standard}:
9394 Fortran 2003 and later
9397 Transformational function
9399 @item @emph{Syntax}:
9400 @code{RESULT = SELECTED_CHAR_KIND(NAME)}
9402 @item @emph{Arguments}:
9403 @multitable @columnfractions .15 .70
9404 @item @var{NAME} @tab Shall be a scalar and of the default character type.
9407 @item @emph{Example}:
9410 integer,parameter :: ascii = selected_char_kind("ascii")
9411 character(kind=ascii, len=26) :: s
9413 s = ascii_"abcdefghijklmnopqrstuvwxyz"
9415 end program ascii_kind
9421 @node SELECTED_INT_KIND
9422 @section @code{SELECTED_INT_KIND} --- Choose integer kind
9423 @fnindex SELECTED_INT_KIND
9424 @cindex integer kind
9425 @cindex kind, integer
9428 @item @emph{Description}:
9429 @code{SELECTED_INT_KIND(I)} return the kind value of the smallest integer
9430 type that can represent all values ranging from @math{-10^I} (exclusive)
9431 to @math{10^I} (exclusive). If there is no integer kind that accommodates
9432 this range, @code{SELECTED_INT_KIND} returns @math{-1}.
9434 @item @emph{Standard}:
9435 Fortran 95 and later
9438 Transformational function
9440 @item @emph{Syntax}:
9441 @code{RESULT = SELECTED_INT_KIND(I)}
9443 @item @emph{Arguments}:
9444 @multitable @columnfractions .15 .70
9445 @item @var{I} @tab Shall be a scalar and of type @code{INTEGER}.
9448 @item @emph{Example}:
9450 program large_integers
9451 integer,parameter :: k5 = selected_int_kind(5)
9452 integer,parameter :: k15 = selected_int_kind(15)
9453 integer(kind=k5) :: i5
9454 integer(kind=k15) :: i15
9456 print *, huge(i5), huge(i15)
9458 ! The following inequalities are always true
9459 print *, huge(i5) >= 10_k5**5-1
9460 print *, huge(i15) >= 10_k15**15-1
9461 end program large_integers
9467 @node SELECTED_REAL_KIND
9468 @section @code{SELECTED_REAL_KIND} --- Choose real kind
9469 @fnindex SELECTED_REAL_KIND
9474 @item @emph{Description}:
9475 @code{SELECTED_REAL_KIND(P,R)} return the kind value of a real data type
9476 with decimal precision greater of at least @code{P} digits and exponent
9477 range greater at least @code{R}.
9479 @item @emph{Standard}:
9480 Fortran 95 and later
9483 Transformational function
9485 @item @emph{Syntax}:
9486 @code{RESULT = SELECTED_REAL_KIND(P, R)}
9488 @item @emph{Arguments}:
9489 @multitable @columnfractions .15 .70
9490 @item @var{P} @tab (Optional) shall be a scalar and of type @code{INTEGER}.
9491 @item @var{R} @tab (Optional) shall be a scalar and of type @code{INTEGER}.
9493 At least one argument shall be present.
9495 @item @emph{Return value}:
9497 @code{SELECTED_REAL_KIND} returns the value of the kind type parameter of
9498 a real data type with decimal precision of at least @code{P} digits and a
9499 decimal exponent range of at least @code{R}. If more than one real data
9500 type meet the criteria, the kind of the data type with the smallest
9501 decimal precision is returned. If no real data type matches the criteria,
9504 @item -1 if the processor does not support a real data type with a
9505 precision greater than or equal to @code{P}
9506 @item -2 if the processor does not support a real type with an exponent
9507 range greater than or equal to @code{R}
9508 @item -3 if neither is supported.
9511 @item @emph{Example}:
9514 integer,parameter :: p6 = selected_real_kind(6)
9515 integer,parameter :: p10r100 = selected_real_kind(10,100)
9516 integer,parameter :: r400 = selected_real_kind(r=400)
9518 real(kind=p10r100) :: y
9519 real(kind=r400) :: z
9521 print *, precision(x), range(x)
9522 print *, precision(y), range(y)
9523 print *, precision(z), range(z)
9524 end program real_kinds
9531 @section @code{SET_EXPONENT} --- Set the exponent of the model
9532 @fnindex SET_EXPONENT
9533 @cindex real number, set exponent
9534 @cindex floating point, set exponent
9537 @item @emph{Description}:
9538 @code{SET_EXPONENT(X, I)} returns the real number whose fractional part
9539 is that that of @var{X} and whose exponent part is @var{I}.
9541 @item @emph{Standard}:
9542 Fortran 95 and later
9547 @item @emph{Syntax}:
9548 @code{RESULT = SET_EXPONENT(X, I)}
9550 @item @emph{Arguments}:
9551 @multitable @columnfractions .15 .70
9552 @item @var{X} @tab Shall be of type @code{REAL}.
9553 @item @var{I} @tab Shall be of type @code{INTEGER}.
9556 @item @emph{Return value}:
9557 The return value is of the same type and kind as @var{X}.
9558 The real number whose fractional part
9559 is that that of @var{X} and whose exponent part if @var{I} is returned;
9560 it is @code{FRACTION(X) * RADIX(X)**I}.
9562 @item @emph{Example}:
9565 REAL :: x = 178.1387e-4
9567 PRINT *, SET_EXPONENT(x, i), FRACTION(x) * RADIX(x)**i
9576 @section @code{SHAPE} --- Determine the shape of an array
9578 @cindex array, shape
9581 @item @emph{Description}:
9582 Determines the shape of an array.
9584 @item @emph{Standard}:
9585 Fortran 95 and later
9590 @item @emph{Syntax}:
9591 @code{RESULT = SHAPE(SOURCE)}
9593 @item @emph{Arguments}:
9594 @multitable @columnfractions .15 .70
9595 @item @var{SOURCE} @tab Shall be an array or scalar of any type.
9596 If @var{SOURCE} is a pointer it must be associated and allocatable
9597 arrays must be allocated.
9600 @item @emph{Return value}:
9601 An @code{INTEGER} array of rank one with as many elements as @var{SOURCE}
9602 has dimensions. The elements of the resulting array correspond to the extend
9603 of @var{SOURCE} along the respective dimensions. If @var{SOURCE} is a scalar,
9604 the result is the rank one array of size zero.
9606 @item @emph{Example}:
9609 INTEGER, DIMENSION(-1:1, -1:2) :: A
9610 WRITE(*,*) SHAPE(A) ! (/ 3, 4 /)
9611 WRITE(*,*) SIZE(SHAPE(42)) ! (/ /)
9615 @item @emph{See also}:
9616 @ref{RESHAPE}, @ref{SIZE}
9622 @section @code{SIGN} --- Sign copying function
9626 @cindex sign copying
9629 @item @emph{Description}:
9630 @code{SIGN(A,B)} returns the value of @var{A} with the sign of @var{B}.
9632 @item @emph{Standard}:
9633 Fortran 77 and later
9638 @item @emph{Syntax}:
9639 @code{RESULT = SIGN(A, B)}
9641 @item @emph{Arguments}:
9642 @multitable @columnfractions .15 .70
9643 @item @var{A} @tab Shall be of type @code{INTEGER} or @code{REAL}
9644 @item @var{B} @tab Shall be of the same type and kind as @var{A}
9647 @item @emph{Return value}:
9648 The kind of the return value is that of @var{A} and @var{B}.
9649 If @math{B\ge 0} then the result is @code{ABS(A)}, else
9650 it is @code{-ABS(A)}.
9652 @item @emph{Example}:
9655 print *, sign(-12,1)
9656 print *, sign(-12,0)
9657 print *, sign(-12,-1)
9659 print *, sign(-12.,1.)
9660 print *, sign(-12.,0.)
9661 print *, sign(-12.,-1.)
9662 end program test_sign
9665 @item @emph{Specific names}:
9666 @multitable @columnfractions .20 .20 .20 .25
9667 @item Name @tab Arguments @tab Return type @tab Standard
9668 @item @code{ISIGN(A,P)} @tab @code{INTEGER(4)} @tab @code{INTEGER(4)} @tab f95, gnu
9669 @item @code{DSIGN(A,P)} @tab @code{REAL(8)} @tab @code{REAL(8)} @tab f95, gnu
9676 @section @code{SIGNAL} --- Signal handling subroutine (or function)
9678 @cindex system, signal handling
9681 @item @emph{Description}:
9682 @code{SIGNAL(NUMBER, HANDLER [, STATUS])} causes external subroutine
9683 @var{HANDLER} to be executed with a single integer argument when signal
9684 @var{NUMBER} occurs. If @var{HANDLER} is an integer, it can be used to
9685 turn off handling of signal @var{NUMBER} or revert to its default
9686 action. See @code{signal(2)}.
9688 If @code{SIGNAL} is called as a subroutine and the @var{STATUS} argument
9689 is supplied, it is set to the value returned by @code{signal(2)}.
9691 @item @emph{Standard}:
9695 Subroutine, function
9697 @item @emph{Syntax}:
9698 @multitable @columnfractions .80
9699 @item @code{CALL SIGNAL(NUMBER, HANDLER [, STATUS])}
9700 @item @code{STATUS = SIGNAL(NUMBER, HANDLER)}
9703 @item @emph{Arguments}:
9704 @multitable @columnfractions .15 .70
9705 @item @var{NUMBER} @tab Shall be a scalar integer, with @code{INTENT(IN)}
9706 @item @var{HANDLER}@tab Signal handler (@code{INTEGER FUNCTION} or
9707 @code{SUBROUTINE}) or dummy/global @code{INTEGER} scalar.
9708 @code{INTEGER}. It is @code{INTENT(IN)}.
9709 @item @var{STATUS} @tab (Optional) @var{STATUS} shall be a scalar
9710 integer. It has @code{INTENT(OUT)}.
9713 @item @emph{Return value}:
9714 The @code{SIGNAL} function returns the value returned by @code{signal(2)}.
9716 @item @emph{Example}:
9720 external handler_print
9722 call signal (12, handler_print)
9726 end program test_signal
9733 @section @code{SIN} --- Sine function
9739 @cindex trigonometric function, sine
9743 @item @emph{Description}:
9744 @code{SIN(X)} computes the sine of @var{X}.
9746 @item @emph{Standard}:
9747 Fortran 77 and later
9752 @item @emph{Syntax}:
9753 @code{RESULT = SIN(X)}
9755 @item @emph{Arguments}:
9756 @multitable @columnfractions .15 .70
9757 @item @var{X} @tab The type shall be @code{REAL} or
9761 @item @emph{Return value}:
9762 The return value has same type and kind as @var{X}.
9764 @item @emph{Example}:
9769 end program test_sin
9772 @item @emph{Specific names}:
9773 @multitable @columnfractions .20 .20 .20 .25
9774 @item Name @tab Argument @tab Return type @tab Standard
9775 @item @code{DSIN(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab f95, gnu
9776 @item @code{CSIN(X)} @tab @code{COMPLEX(4) X} @tab @code{COMPLEX(4)} @tab f95, gnu
9777 @item @code{ZSIN(X)} @tab @code{COMPLEX(8) X} @tab @code{COMPLEX(8)} @tab f95, gnu
9778 @item @code{CDSIN(X)} @tab @code{COMPLEX(8) X} @tab @code{COMPLEX(8)} @tab f95, gnu
9781 @item @emph{See also}:
9788 @section @code{SINH} --- Hyperbolic sine function
9791 @cindex hyperbolic sine
9792 @cindex hyperbolic function, sine
9793 @cindex sine, hyperbolic
9796 @item @emph{Description}:
9797 @code{SINH(X)} computes the hyperbolic sine of @var{X}.
9799 @item @emph{Standard}:
9800 Fortran 95 and later
9805 @item @emph{Syntax}:
9806 @code{RESULT = SINH(X)}
9808 @item @emph{Arguments}:
9809 @multitable @columnfractions .15 .70
9810 @item @var{X} @tab The type shall be @code{REAL}.
9813 @item @emph{Return value}:
9814 The return value is of type @code{REAL}.
9816 @item @emph{Example}:
9819 real(8) :: x = - 1.0_8
9821 end program test_sinh
9824 @item @emph{Specific names}:
9825 @multitable @columnfractions .20 .20 .20 .25
9826 @item Name @tab Argument @tab Return type @tab Standard
9827 @item @code{DSINH(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab Fortran 95 and later
9830 @item @emph{See also}:
9837 @section @code{SIZE} --- Determine the size of an array
9840 @cindex array, number of elements
9841 @cindex array, count elements
9844 @item @emph{Description}:
9845 Determine the extent of @var{ARRAY} along a specified dimension @var{DIM},
9846 or the total number of elements in @var{ARRAY} if @var{DIM} is absent.
9848 @item @emph{Standard}:
9849 Fortran 95 and later, with @var{KIND} argument Fortran 2003 and later
9854 @item @emph{Syntax}:
9855 @code{RESULT = SIZE(ARRAY[, DIM [, KIND]])}
9857 @item @emph{Arguments}:
9858 @multitable @columnfractions .15 .70
9859 @item @var{ARRAY} @tab Shall be an array of any type. If @var{ARRAY} is
9860 a pointer it must be associated and allocatable arrays must be allocated.
9861 @item @var{DIM} @tab (Optional) shall be a scalar of type @code{INTEGER}
9862 and its value shall be in the range from 1 to n, where n equals the rank
9864 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
9865 expression indicating the kind parameter of the result.
9868 @item @emph{Return value}:
9869 The return value is of type @code{INTEGER} and of kind @var{KIND}. If
9870 @var{KIND} is absent, the return value is of default integer kind.
9872 @item @emph{Example}:
9875 WRITE(*,*) SIZE((/ 1, 2 /)) ! 2
9879 @item @emph{See also}:
9880 @ref{SHAPE}, @ref{RESHAPE}
9885 @section @code{SIZEOF} --- Size in bytes of an expression
9887 @cindex expression size
9888 @cindex size of an expression
9891 @item @emph{Description}:
9892 @code{SIZEOF(X)} calculates the number of bytes of storage the
9893 expression @code{X} occupies.
9895 @item @emph{Standard}:
9901 @item @emph{Syntax}:
9902 @code{N = SIZEOF(X)}
9904 @item @emph{Arguments}:
9905 @multitable @columnfractions .15 .70
9906 @item @var{X} @tab The argument shall be of any type, rank or shape.
9909 @item @emph{Return value}:
9910 The return value is of type integer and of the system-dependent kind
9911 @var{C_SIZE_T} (from the @var{ISO_C_BINDING} module). Its value is the
9912 number of bytes occupied by the argument. If the argument has the
9913 @code{POINTER} attribute, the number of bytes of the storage area pointed
9914 to is returned. If the argument is of a derived type with @code{POINTER}
9915 or @code{ALLOCATABLE} components, the return value doesn't account for
9916 the sizes of the data pointed to by these components.
9918 @item @emph{Example}:
9922 print *, (sizeof(s)/sizeof(r) == 5)
9925 The example will print @code{.TRUE.} unless you are using a platform
9926 where default @code{REAL} variables are unusually padded.
9928 @item @emph{See also}:
9934 @section @code{SLEEP} --- Sleep for the specified number of seconds
9936 @cindex delayed execution
9939 @item @emph{Description}:
9940 Calling this subroutine causes the process to pause for @var{SECONDS} seconds.
9942 @item @emph{Standard}:
9948 @item @emph{Syntax}:
9949 @code{CALL SLEEP(SECONDS)}
9951 @item @emph{Arguments}:
9952 @multitable @columnfractions .15 .70
9953 @item @var{SECONDS} @tab The type shall be of default @code{INTEGER}.
9956 @item @emph{Example}:
9967 @section @code{SNGL} --- Convert double precision real to default real
9969 @cindex conversion, to real
9972 @item @emph{Description}:
9973 @code{SNGL(A)} converts the double precision real @var{A}
9974 to a default real value. This is an archaic form of @code{REAL}
9975 that is specific to one type for @var{A}.
9977 @item @emph{Standard}:
9978 Fortran 77 and later
9983 @item @emph{Syntax}:
9984 @code{RESULT = SNGL(A)}
9986 @item @emph{Arguments}:
9987 @multitable @columnfractions .15 .70
9988 @item @var{A} @tab The type shall be a double precision @code{REAL}.
9991 @item @emph{Return value}:
9992 The return value is of type default @code{REAL}.
9994 @item @emph{See also}:
10001 @section @code{SPACING} --- Smallest distance between two numbers of a given type
10003 @cindex real number, relative spacing
10004 @cindex floating point, relative spacing
10007 @item @emph{Description}:
10008 Determines the distance between the argument @var{X} and the nearest
10009 adjacent number of the same type.
10011 @item @emph{Standard}:
10012 Fortran 95 and later
10014 @item @emph{Class}:
10017 @item @emph{Syntax}:
10018 @code{RESULT = SPACING(X)}
10020 @item @emph{Arguments}:
10021 @multitable @columnfractions .15 .70
10022 @item @var{X} @tab Shall be of type @code{REAL}.
10025 @item @emph{Return value}:
10026 The result is of the same type as the input argument @var{X}.
10028 @item @emph{Example}:
10030 PROGRAM test_spacing
10031 INTEGER, PARAMETER :: SGL = SELECTED_REAL_KIND(p=6, r=37)
10032 INTEGER, PARAMETER :: DBL = SELECTED_REAL_KIND(p=13, r=200)
10034 WRITE(*,*) spacing(1.0_SGL) ! "1.1920929E-07" on i686
10035 WRITE(*,*) spacing(1.0_DBL) ! "2.220446049250313E-016" on i686
10039 @item @emph{See also}:
10046 @section @code{SPREAD} --- Add a dimension to an array
10048 @cindex array, increase dimension
10049 @cindex array, duplicate elements
10050 @cindex array, duplicate dimensions
10053 @item @emph{Description}:
10054 Replicates a @var{SOURCE} array @var{NCOPIES} times along a specified
10055 dimension @var{DIM}.
10057 @item @emph{Standard}:
10058 Fortran 95 and later
10060 @item @emph{Class}:
10061 Transformational function
10063 @item @emph{Syntax}:
10064 @code{RESULT = SPREAD(SOURCE, DIM, NCOPIES)}
10066 @item @emph{Arguments}:
10067 @multitable @columnfractions .15 .70
10068 @item @var{SOURCE} @tab Shall be a scalar or an array of any type and
10069 a rank less than seven.
10070 @item @var{DIM} @tab Shall be a scalar of type @code{INTEGER} with a
10071 value in the range from 1 to n+1, where n equals the rank of @var{SOURCE}.
10072 @item @var{NCOPIES} @tab Shall be a scalar of type @code{INTEGER}.
10075 @item @emph{Return value}:
10076 The result is an array of the same type as @var{SOURCE} and has rank n+1
10077 where n equals the rank of @var{SOURCE}.
10079 @item @emph{Example}:
10081 PROGRAM test_spread
10082 INTEGER :: a = 1, b(2) = (/ 1, 2 /)
10083 WRITE(*,*) SPREAD(A, 1, 2) ! "1 1"
10084 WRITE(*,*) SPREAD(B, 1, 2) ! "1 1 2 2"
10088 @item @emph{See also}:
10095 @section @code{SQRT} --- Square-root function
10102 @cindex square-root
10105 @item @emph{Description}:
10106 @code{SQRT(X)} computes the square root of @var{X}.
10108 @item @emph{Standard}:
10109 Fortran 77 and later
10111 @item @emph{Class}:
10114 @item @emph{Syntax}:
10115 @code{RESULT = SQRT(X)}
10117 @item @emph{Arguments}:
10118 @multitable @columnfractions .15 .70
10119 @item @var{X} @tab The type shall be @code{REAL} or
10123 @item @emph{Return value}:
10124 The return value is of type @code{REAL} or @code{COMPLEX}.
10125 The kind type parameter is the same as @var{X}.
10127 @item @emph{Example}:
10130 real(8) :: x = 2.0_8
10131 complex :: z = (1.0, 2.0)
10134 end program test_sqrt
10137 @item @emph{Specific names}:
10138 @multitable @columnfractions .20 .20 .20 .25
10139 @item Name @tab Argument @tab Return type @tab Standard
10140 @item @code{DSQRT(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab Fortran 95 and later
10141 @item @code{CSQRT(X)} @tab @code{COMPLEX(4) X} @tab @code{COMPLEX(4)} @tab Fortran 95 and later
10142 @item @code{ZSQRT(X)} @tab @code{COMPLEX(8) X} @tab @code{COMPLEX(8)} @tab GNU extension
10143 @item @code{CDSQRT(X)} @tab @code{COMPLEX(8) X} @tab @code{COMPLEX(8)} @tab GNU extension
10150 @section @code{SRAND} --- Reinitialize the random number generator
10152 @cindex random number generation, seeding
10153 @cindex seeding a random number generator
10156 @item @emph{Description}:
10157 @code{SRAND} reinitializes the pseudo-random number generator
10158 called by @code{RAND} and @code{IRAND}. The new seed used by the
10159 generator is specified by the required argument @var{SEED}.
10161 @item @emph{Standard}:
10164 @item @emph{Class}:
10167 @item @emph{Syntax}:
10168 @code{CALL SRAND(SEED)}
10170 @item @emph{Arguments}:
10171 @multitable @columnfractions .15 .70
10172 @item @var{SEED} @tab Shall be a scalar @code{INTEGER(kind=4)}.
10175 @item @emph{Return value}:
10178 @item @emph{Example}:
10179 See @code{RAND} and @code{IRAND} for examples.
10181 @item @emph{Notes}:
10182 The Fortran 2003 standard specifies the intrinsic @code{RANDOM_SEED} to
10183 initialize the pseudo-random numbers generator and @code{RANDOM_NUMBER}
10184 to generate pseudo-random numbers. Please note that in
10185 GNU Fortran, these two sets of intrinsics (@code{RAND},
10186 @code{IRAND} and @code{SRAND} on the one hand, @code{RANDOM_NUMBER} and
10187 @code{RANDOM_SEED} on the other hand) access two independent
10188 pseudo-random number generators.
10190 @item @emph{See also}:
10191 @ref{RAND}, @ref{RANDOM_SEED}, @ref{RANDOM_NUMBER}
10198 @section @code{STAT} --- Get file status
10200 @cindex file system, file status
10203 @item @emph{Description}:
10204 This function returns information about a file. No permissions are required on
10205 the file itself, but execute (search) permission is required on all of the
10206 directories in path that lead to the file.
10208 The elements that are obtained and stored in the array @code{BUFF}:
10209 @multitable @columnfractions .15 .70
10210 @item @code{buff(1)} @tab Device ID
10211 @item @code{buff(2)} @tab Inode number
10212 @item @code{buff(3)} @tab File mode
10213 @item @code{buff(4)} @tab Number of links
10214 @item @code{buff(5)} @tab Owner's uid
10215 @item @code{buff(6)} @tab Owner's gid
10216 @item @code{buff(7)} @tab ID of device containing directory entry for file (0 if not available)
10217 @item @code{buff(8)} @tab File size (bytes)
10218 @item @code{buff(9)} @tab Last access time
10219 @item @code{buff(10)} @tab Last modification time
10220 @item @code{buff(11)} @tab Last file status change time
10221 @item @code{buff(12)} @tab Preferred I/O block size (-1 if not available)
10222 @item @code{buff(13)} @tab Number of blocks allocated (-1 if not available)
10225 Not all these elements are relevant on all systems.
10226 If an element is not relevant, it is returned as 0.
10228 This intrinsic is provided in both subroutine and function forms; however,
10229 only one form can be used in any given program unit.
10231 @item @emph{Standard}:
10234 @item @emph{Class}:
10235 Subroutine, function
10237 @item @emph{Syntax}:
10238 @code{CALL STAT(FILE,BUFF[,STATUS])}
10240 @item @emph{Arguments}:
10241 @multitable @columnfractions .15 .70
10242 @item @var{FILE} @tab The type shall be @code{CHARACTER}, of the
10243 default kind and a valid path within the file system.
10244 @item @var{BUFF} @tab The type shall be @code{INTEGER(4), DIMENSION(13)}.
10245 @item @var{STATUS} @tab (Optional) status flag of type @code{INTEGER(4)}. Returns 0
10246 on success and a system specific error code otherwise.
10249 @item @emph{Example}:
10252 INTEGER, DIMENSION(13) :: buff
10255 CALL STAT("/etc/passwd", buff, status)
10257 IF (status == 0) THEN
10258 WRITE (*, FMT="('Device ID:', T30, I19)") buff(1)
10259 WRITE (*, FMT="('Inode number:', T30, I19)") buff(2)
10260 WRITE (*, FMT="('File mode (octal):', T30, O19)") buff(3)
10261 WRITE (*, FMT="('Number of links:', T30, I19)") buff(4)
10262 WRITE (*, FMT="('Owner''s uid:', T30, I19)") buff(5)
10263 WRITE (*, FMT="('Owner''s gid:', T30, I19)") buff(6)
10264 WRITE (*, FMT="('Device where located:', T30, I19)") buff(7)
10265 WRITE (*, FMT="('File size:', T30, I19)") buff(8)
10266 WRITE (*, FMT="('Last access time:', T30, A19)") CTIME(buff(9))
10267 WRITE (*, FMT="('Last modification time', T30, A19)") CTIME(buff(10))
10268 WRITE (*, FMT="('Last status change time:', T30, A19)") CTIME(buff(11))
10269 WRITE (*, FMT="('Preferred block size:', T30, I19)") buff(12)
10270 WRITE (*, FMT="('No. of blocks allocated:', T30, I19)") buff(13)
10275 @item @emph{See also}:
10276 To stat an open file: @ref{FSTAT}, to stat a link: @ref{LSTAT}
10282 @section @code{SUM} --- Sum of array elements
10285 @cindex array, add elements
10286 @cindex array, conditionally add elements
10287 @cindex sum array elements
10290 @item @emph{Description}:
10291 Adds the elements of @var{ARRAY} along dimension @var{DIM} if
10292 the corresponding element in @var{MASK} is @code{TRUE}.
10294 @item @emph{Standard}:
10295 Fortran 95 and later
10297 @item @emph{Class}:
10298 Transformational function
10300 @item @emph{Syntax}:
10301 @code{RESULT = SUM(ARRAY[, MASK])}
10302 @code{RESULT = SUM(ARRAY, DIM[, MASK])}
10304 @item @emph{Arguments}:
10305 @multitable @columnfractions .15 .70
10306 @item @var{ARRAY} @tab Shall be an array of type @code{INTEGER},
10307 @code{REAL} or @code{COMPLEX}.
10308 @item @var{DIM} @tab (Optional) shall be a scalar of type
10309 @code{INTEGER} with a value in the range from 1 to n, where n
10310 equals the rank of @var{ARRAY}.
10311 @item @var{MASK} @tab (Optional) shall be of type @code{LOGICAL}
10312 and either be a scalar or an array of the same shape as @var{ARRAY}.
10315 @item @emph{Return value}:
10316 The result is of the same type as @var{ARRAY}.
10318 If @var{DIM} is absent, a scalar with the sum of all elements in @var{ARRAY}
10319 is returned. Otherwise, an array of rank n-1, where n equals the rank of
10320 @var{ARRAY},and a shape similar to that of @var{ARRAY} with dimension @var{DIM}
10321 dropped is returned.
10323 @item @emph{Example}:
10326 INTEGER :: x(5) = (/ 1, 2, 3, 4 ,5 /)
10327 print *, SUM(x) ! all elements, sum = 15
10328 print *, SUM(x, MASK=MOD(x, 2)==1) ! odd elements, sum = 9
10332 @item @emph{See also}:
10339 @section @code{SYMLNK} --- Create a symbolic link
10341 @cindex file system, create link
10342 @cindex file system, soft link
10345 @item @emph{Description}:
10346 Makes a symbolic link from file @var{PATH1} to @var{PATH2}. A null
10347 character (@code{CHAR(0)}) can be used to mark the end of the names in
10348 @var{PATH1} and @var{PATH2}; otherwise, trailing blanks in the file
10349 names are ignored. If the @var{STATUS} argument is supplied, it
10350 contains 0 on success or a nonzero error code upon return; see
10351 @code{symlink(2)}. If the system does not supply @code{symlink(2)},
10352 @code{ENOSYS} is returned.
10354 This intrinsic is provided in both subroutine and function forms;
10355 however, only one form can be used in any given program unit.
10357 @item @emph{Standard}:
10360 @item @emph{Class}:
10361 Subroutine, function
10363 @item @emph{Syntax}:
10364 @multitable @columnfractions .80
10365 @item @code{CALL SYMLNK(PATH1, PATH2 [, STATUS])}
10366 @item @code{STATUS = SYMLNK(PATH1, PATH2)}
10369 @item @emph{Arguments}:
10370 @multitable @columnfractions .15 .70
10371 @item @var{PATH1} @tab Shall be of default @code{CHARACTER} type.
10372 @item @var{PATH2} @tab Shall be of default @code{CHARACTER} type.
10373 @item @var{STATUS} @tab (Optional) Shall be of default @code{INTEGER} type.
10376 @item @emph{See also}:
10377 @ref{LINK}, @ref{UNLINK}
10384 @section @code{SYSTEM} --- Execute a shell command
10386 @cindex system, system call
10389 @item @emph{Description}:
10390 Passes the command @var{COMMAND} to a shell (see @code{system(3)}). If
10391 argument @var{STATUS} is present, it contains the value returned by
10392 @code{system(3)}, which is presumably 0 if the shell command succeeded.
10393 Note that which shell is used to invoke the command is system-dependent
10394 and environment-dependent.
10396 This intrinsic is provided in both subroutine and function forms;
10397 however, only one form can be used in any given program unit.
10399 @item @emph{Standard}:
10402 @item @emph{Class}:
10403 Subroutine, function
10405 @item @emph{Syntax}:
10406 @multitable @columnfractions .80
10407 @item @code{CALL SYSTEM(COMMAND [, STATUS])}
10408 @item @code{STATUS = SYSTEM(COMMAND)}
10411 @item @emph{Arguments}:
10412 @multitable @columnfractions .15 .70
10413 @item @var{COMMAND} @tab Shall be of default @code{CHARACTER} type.
10414 @item @var{STATUS} @tab (Optional) Shall be of default @code{INTEGER} type.
10417 @item @emph{See also}:
10423 @section @code{SYSTEM_CLOCK} --- Time function
10424 @fnindex SYSTEM_CLOCK
10425 @cindex time, clock ticks
10426 @cindex clock ticks
10429 @item @emph{Description}:
10430 Determines the @var{COUNT} of milliseconds of wall clock time since
10431 the Epoch (00:00:00 UTC, January 1, 1970) modulo @var{COUNT_MAX},
10432 @var{COUNT_RATE} determines the number of clock ticks per second.
10433 @var{COUNT_RATE} and @var{COUNT_MAX} are constant and specific to
10434 @command{gfortran}.
10436 If there is no clock, @var{COUNT} is set to @code{-HUGE(COUNT)}, and
10437 @var{COUNT_RATE} and @var{COUNT_MAX} are set to zero
10439 @item @emph{Standard}:
10440 Fortran 95 and later
10442 @item @emph{Class}:
10445 @item @emph{Syntax}:
10446 @code{CALL SYSTEM_CLOCK([COUNT, COUNT_RATE, COUNT_MAX])}
10448 @item @emph{Arguments}:
10449 @item @emph{Arguments}:
10450 @multitable @columnfractions .15 .70
10451 @item @var{COUNT} @tab (Optional) shall be a scalar of type default
10452 @code{INTEGER} with @code{INTENT(OUT)}.
10453 @item @var{COUNT_RATE} @tab (Optional) shall be a scalar of type default
10454 @code{INTEGER} with @code{INTENT(OUT)}.
10455 @item @var{COUNT_MAX} @tab (Optional) shall be a scalar of type default
10456 @code{INTEGER} with @code{INTENT(OUT)}.
10459 @item @emph{Example}:
10461 PROGRAM test_system_clock
10462 INTEGER :: count, count_rate, count_max
10463 CALL SYSTEM_CLOCK(count, count_rate, count_max)
10464 WRITE(*,*) count, count_rate, count_max
10468 @item @emph{See also}:
10469 @ref{DATE_AND_TIME}, @ref{CPU_TIME}
10475 @section @code{TAN} --- Tangent function
10478 @cindex trigonometric function, tangent
10482 @item @emph{Description}:
10483 @code{TAN(X)} computes the tangent of @var{X}.
10485 @item @emph{Standard}:
10486 Fortran 77 and later
10488 @item @emph{Class}:
10491 @item @emph{Syntax}:
10492 @code{RESULT = TAN(X)}
10494 @item @emph{Arguments}:
10495 @multitable @columnfractions .15 .70
10496 @item @var{X} @tab The type shall be @code{REAL}.
10499 @item @emph{Return value}:
10500 The return value is of type @code{REAL}. The kind type parameter is
10501 the same as @var{X}.
10503 @item @emph{Example}:
10506 real(8) :: x = 0.165_8
10508 end program test_tan
10511 @item @emph{Specific names}:
10512 @multitable @columnfractions .20 .20 .20 .25
10513 @item Name @tab Argument @tab Return type @tab Standard
10514 @item @code{DTAN(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab Fortran 95 and later
10517 @item @emph{See also}:
10524 @section @code{TANH} --- Hyperbolic tangent function
10527 @cindex hyperbolic tangent
10528 @cindex hyperbolic function, tangent
10529 @cindex tangent, hyperbolic
10532 @item @emph{Description}:
10533 @code{TANH(X)} computes the hyperbolic tangent of @var{X}.
10535 @item @emph{Standard}:
10536 Fortran 77 and later
10538 @item @emph{Class}:
10541 @item @emph{Syntax}:
10544 @item @emph{Arguments}:
10545 @multitable @columnfractions .15 .70
10546 @item @var{X} @tab The type shall be @code{REAL}.
10549 @item @emph{Return value}:
10550 The return value is of type @code{REAL} and lies in the range
10551 @math{ - 1 \leq tanh(x) \leq 1 }.
10553 @item @emph{Example}:
10556 real(8) :: x = 2.1_8
10558 end program test_tanh
10561 @item @emph{Specific names}:
10562 @multitable @columnfractions .20 .20 .20 .25
10563 @item Name @tab Argument @tab Return type @tab Standard
10564 @item @code{DTANH(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab Fortran 95 and later
10567 @item @emph{See also}:
10574 @section @code{TIME} --- Time function
10576 @cindex time, current
10577 @cindex current time
10580 @item @emph{Description}:
10581 Returns the current time encoded as an integer (in the manner of the
10582 UNIX function @code{time(3)}). This value is suitable for passing to
10583 @code{CTIME()}, @code{GMTIME()}, and @code{LTIME()}.
10585 This intrinsic is not fully portable, such as to systems with 32-bit
10586 @code{INTEGER} types but supporting times wider than 32 bits. Therefore,
10587 the values returned by this intrinsic might be, or become, negative, or
10588 numerically less than previous values, during a single run of the
10591 See @ref{TIME8}, for information on a similar intrinsic that might be
10592 portable to more GNU Fortran implementations, though to fewer Fortran
10595 @item @emph{Standard}:
10598 @item @emph{Class}:
10601 @item @emph{Syntax}:
10602 @code{RESULT = TIME()}
10604 @item @emph{Return value}:
10605 The return value is a scalar of type @code{INTEGER(4)}.
10607 @item @emph{See also}:
10608 @ref{CTIME}, @ref{GMTIME}, @ref{LTIME}, @ref{MCLOCK}, @ref{TIME8}
10615 @section @code{TIME8} --- Time function (64-bit)
10617 @cindex time, current
10618 @cindex current time
10621 @item @emph{Description}:
10622 Returns the current time encoded as an integer (in the manner of the
10623 UNIX function @code{time(3)}). This value is suitable for passing to
10624 @code{CTIME()}, @code{GMTIME()}, and @code{LTIME()}.
10626 @emph{Warning:} this intrinsic does not increase the range of the timing
10627 values over that returned by @code{time(3)}. On a system with a 32-bit
10628 @code{time(3)}, @code{TIME8()} will return a 32-bit value, even though
10629 it is converted to a 64-bit @code{INTEGER(8)} value. That means
10630 overflows of the 32-bit value can still occur. Therefore, the values
10631 returned by this intrinsic might be or become negative or numerically
10632 less than previous values during a single run of the compiled program.
10634 @item @emph{Standard}:
10637 @item @emph{Class}:
10640 @item @emph{Syntax}:
10641 @code{RESULT = TIME8()}
10643 @item @emph{Return value}:
10644 The return value is a scalar of type @code{INTEGER(8)}.
10646 @item @emph{See also}:
10647 @ref{CTIME}, @ref{GMTIME}, @ref{LTIME}, @ref{MCLOCK8}, @ref{TIME}
10654 @section @code{TINY} --- Smallest positive number of a real kind
10656 @cindex limits, smallest number
10657 @cindex model representation, smallest number
10660 @item @emph{Description}:
10661 @code{TINY(X)} returns the smallest positive (non zero) number
10662 in the model of the type of @code{X}.
10664 @item @emph{Standard}:
10665 Fortran 95 and later
10667 @item @emph{Class}:
10670 @item @emph{Syntax}:
10671 @code{RESULT = TINY(X)}
10673 @item @emph{Arguments}:
10674 @multitable @columnfractions .15 .70
10675 @item @var{X} @tab Shall be of type @code{REAL}.
10678 @item @emph{Return value}:
10679 The return value is of the same type and kind as @var{X}
10681 @item @emph{Example}:
10682 See @code{HUGE} for an example.
10688 @section @code{TRAILZ} --- Number of trailing zero bits of an integer
10693 @item @emph{Description}:
10694 @code{TRAILZ} returns the number of trailing zero bits of an integer.
10696 @item @emph{Standard}:
10697 Fortran 2008 and later
10699 @item @emph{Class}:
10702 @item @emph{Syntax}:
10703 @code{RESULT = TRAILZ(I)}
10705 @item @emph{Arguments}:
10706 @multitable @columnfractions .15 .70
10707 @item @var{I} @tab Shall be of type @code{INTEGER}.
10710 @item @emph{Return value}:
10711 The type of the return value is the default @code{INTEGER}.
10712 If all the bits of @code{I} are zero, the result value is @code{BIT_SIZE(I)}.
10714 @item @emph{Example}:
10716 PROGRAM test_trailz
10717 WRITE (*,*) TRAILZ(8) ! prints 3
10721 @item @emph{See also}:
10722 @ref{BIT_SIZE}, @ref{LEADZ}
10728 @section @code{TRANSFER} --- Transfer bit patterns
10734 @item @emph{Description}:
10735 Interprets the bitwise representation of @var{SOURCE} in memory as if it
10736 is the representation of a variable or array of the same type and type
10737 parameters as @var{MOLD}.
10739 This is approximately equivalent to the C concept of @emph{casting} one
10742 @item @emph{Standard}:
10743 Fortran 95 and later
10745 @item @emph{Class}:
10746 Transformational function
10748 @item @emph{Syntax}:
10749 @code{RESULT = TRANSFER(SOURCE, MOLD[, SIZE])}
10751 @item @emph{Arguments}:
10752 @multitable @columnfractions .15 .70
10753 @item @var{SOURCE} @tab Shall be a scalar or an array of any type.
10754 @item @var{MOLD} @tab Shall be a scalar or an array of any type.
10755 @item @var{SIZE} @tab (Optional) shall be a scalar of type
10759 @item @emph{Return value}:
10760 The result has the same type as @var{MOLD}, with the bit level
10761 representation of @var{SOURCE}. If @var{SIZE} is present, the result is
10762 a one-dimensional array of length @var{SIZE}. If @var{SIZE} is absent
10763 but @var{MOLD} is an array (of any size or shape), the result is a one-
10764 dimensional array of the minimum length needed to contain the entirety
10765 of the bitwise representation of @var{SOURCE}. If @var{SIZE} is absent
10766 and @var{MOLD} is a scalar, the result is a scalar.
10768 If the bitwise representation of the result is longer than that of
10769 @var{SOURCE}, then the leading bits of the result correspond to those of
10770 @var{SOURCE} and any trailing bits are filled arbitrarily.
10772 When the resulting bit representation does not correspond to a valid
10773 representation of a variable of the same type as @var{MOLD}, the results
10774 are undefined, and subsequent operations on the result cannot be
10775 guaranteed to produce sensible behavior. For example, it is possible to
10776 create @code{LOGICAL} variables for which @code{@var{VAR}} and
10777 @code{.NOT.@var{VAR}} both appear to be true.
10779 @item @emph{Example}:
10781 PROGRAM test_transfer
10782 integer :: x = 2143289344
10783 print *, transfer(x, 1.0) ! prints "NaN" on i686
10791 @section @code{TRANSPOSE} --- Transpose an array of rank two
10793 @cindex array, transpose
10794 @cindex matrix, transpose
10798 @item @emph{Description}:
10799 Transpose an array of rank two. Element (i, j) of the result has the value
10800 @code{MATRIX(j, i)}, for all i, j.
10802 @item @emph{Standard}:
10803 Fortran 95 and later
10805 @item @emph{Class}:
10806 Transformational function
10808 @item @emph{Syntax}:
10809 @code{RESULT = TRANSPOSE(MATRIX)}
10811 @item @emph{Arguments}:
10812 @multitable @columnfractions .15 .70
10813 @item @var{MATRIX} @tab Shall be an array of any type and have a rank of two.
10816 @item @emph{Return value}:
10817 The result has the same type as @var{MATRIX}, and has shape
10818 @code{(/ m, n /)} if @var{MATRIX} has shape @code{(/ n, m /)}.
10824 @section @code{TRIM} --- Remove trailing blank characters of a string
10826 @cindex string, remove trailing whitespace
10829 @item @emph{Description}:
10830 Removes trailing blank characters of a string.
10832 @item @emph{Standard}:
10833 Fortran 95 and later
10835 @item @emph{Class}:
10836 Transformational function
10838 @item @emph{Syntax}:
10839 @code{RESULT = TRIM(STRING)}
10841 @item @emph{Arguments}:
10842 @multitable @columnfractions .15 .70
10843 @item @var{STRING} @tab Shall be a scalar of type @code{CHARACTER}.
10846 @item @emph{Return value}:
10847 A scalar of type @code{CHARACTER} which length is that of @var{STRING}
10848 less the number of trailing blanks.
10850 @item @emph{Example}:
10853 CHARACTER(len=10), PARAMETER :: s = "GFORTRAN "
10854 WRITE(*,*) LEN(s), LEN(TRIM(s)) ! "10 8", with/without trailing blanks
10858 @item @emph{See also}:
10859 @ref{ADJUSTL}, @ref{ADJUSTR}
10865 @section @code{TTYNAM} --- Get the name of a terminal device.
10867 @cindex system, terminal
10870 @item @emph{Description}:
10871 Get the name of a terminal device. For more information,
10872 see @code{ttyname(3)}.
10874 This intrinsic is provided in both subroutine and function forms;
10875 however, only one form can be used in any given program unit.
10877 @item @emph{Standard}:
10880 @item @emph{Class}:
10881 Subroutine, function
10883 @item @emph{Syntax}:
10884 @multitable @columnfractions .80
10885 @item @code{CALL TTYNAM(UNIT, NAME)}
10886 @item @code{NAME = TTYNAM(UNIT)}
10889 @item @emph{Arguments}:
10890 @multitable @columnfractions .15 .70
10891 @item @var{UNIT} @tab Shall be a scalar @code{INTEGER}.
10892 @item @var{NAME} @tab Shall be of type @code{CHARACTER}.
10895 @item @emph{Example}:
10897 PROGRAM test_ttynam
10900 IF (isatty(unit=unit)) write(*,*) ttynam(unit)
10905 @item @emph{See also}:
10912 @section @code{UBOUND} --- Upper dimension bounds of an array
10914 @cindex array, upper bound
10917 @item @emph{Description}:
10918 Returns the upper bounds of an array, or a single upper bound
10919 along the @var{DIM} dimension.
10920 @item @emph{Standard}:
10921 Fortran 95 and later, with @var{KIND} argument Fortran 2003 and later
10923 @item @emph{Class}:
10926 @item @emph{Syntax}:
10927 @code{RESULT = UBOUND(ARRAY [, DIM [, KIND]])}
10929 @item @emph{Arguments}:
10930 @multitable @columnfractions .15 .70
10931 @item @var{ARRAY} @tab Shall be an array, of any type.
10932 @item @var{DIM} @tab (Optional) Shall be a scalar @code{INTEGER}.
10933 @item @var{KIND}@tab (Optional) An @code{INTEGER} initialization
10934 expression indicating the kind parameter of the result.
10937 @item @emph{Return value}:
10938 The return value is of type @code{INTEGER} and of kind @var{KIND}. If
10939 @var{KIND} is absent, the return value is of default integer kind.
10940 If @var{DIM} is absent, the result is an array of the upper bounds of
10941 @var{ARRAY}. If @var{DIM} is present, the result is a scalar
10942 corresponding to the upper bound of the array along that dimension. If
10943 @var{ARRAY} is an expression rather than a whole array or array
10944 structure component, or if it has a zero extent along the relevant
10945 dimension, the upper bound is taken to be the number of elements along
10946 the relevant dimension.
10948 @item @emph{See also}:
10955 @section @code{UMASK} --- Set the file creation mask
10957 @cindex file system, file creation mask
10960 @item @emph{Description}:
10961 Sets the file creation mask to @var{MASK} and returns the old value in
10962 argument @var{OLD} if it is supplied. See @code{umask(2)}.
10964 @item @emph{Standard}:
10967 @item @emph{Class}:
10970 @item @emph{Syntax}:
10971 @code{CALL UMASK(MASK [, OLD])}
10973 @item @emph{Arguments}:
10974 @multitable @columnfractions .15 .70
10975 @item @var{MASK} @tab Shall be a scalar of type @code{INTEGER}.
10976 @item @var{MASK} @tab (Optional) Shall be a scalar of type
10985 @section @code{UNLINK} --- Remove a file from the file system
10987 @cindex file system, remove file
10990 @item @emph{Description}:
10991 Unlinks the file @var{PATH}. A null character (@code{CHAR(0)}) can be
10992 used to mark the end of the name in @var{PATH}; otherwise, trailing
10993 blanks in the file name are ignored. If the @var{STATUS} argument is
10994 supplied, it contains 0 on success or a nonzero error code upon return;
10995 see @code{unlink(2)}.
10997 This intrinsic is provided in both subroutine and function forms;
10998 however, only one form can be used in any given program unit.
11000 @item @emph{Standard}:
11003 @item @emph{Class}:
11004 Subroutine, function
11006 @item @emph{Syntax}:
11007 @multitable @columnfractions .80
11008 @item @code{CALL UNLINK(PATH [, STATUS])}
11009 @item @code{STATUS = UNLINK(PATH)}
11012 @item @emph{Arguments}:
11013 @multitable @columnfractions .15 .70
11014 @item @var{PATH} @tab Shall be of default @code{CHARACTER} type.
11015 @item @var{STATUS} @tab (Optional) Shall be of default @code{INTEGER} type.
11018 @item @emph{See also}:
11019 @ref{LINK}, @ref{SYMLNK}
11025 @section @code{UNPACK} --- Unpack an array of rank one into an array
11027 @cindex array, unpacking
11028 @cindex array, increase dimension
11029 @cindex array, scatter elements
11032 @item @emph{Description}:
11033 Store the elements of @var{VECTOR} in an array of higher rank.
11035 @item @emph{Standard}:
11036 Fortran 95 and later
11038 @item @emph{Class}:
11039 Transformational function
11041 @item @emph{Syntax}:
11042 @code{RESULT = UNPACK(VECTOR, MASK, FIELD)}
11044 @item @emph{Arguments}:
11045 @multitable @columnfractions .15 .70
11046 @item @var{VECTOR} @tab Shall be an array of any type and rank one. It
11047 shall have at least as many elements as @var{MASK} has @code{TRUE} values.
11048 @item @var{MASK} @tab Shall be an array of type @code{LOGICAL}.
11049 @item @var{FIELD} @tab Shall be of the same type as @var{VECTOR} and have
11050 the same shape as @var{MASK}.
11053 @item @emph{Return value}:
11054 The resulting array corresponds to @var{FIELD} with @code{TRUE} elements
11055 of @var{MASK} replaced by values from @var{VECTOR} in array element order.
11057 @item @emph{Example}:
11059 PROGRAM test_unpack
11060 integer :: vector(2) = (/1,1/)
11061 logical :: mask(4) = (/ .TRUE., .FALSE., .FALSE., .TRUE. /)
11062 integer :: field(2,2) = 0, unity(2,2)
11064 ! result: unity matrix
11065 unity = unpack(vector, reshape(mask, (/2,2/)), field)
11069 @item @emph{See also}:
11070 @ref{PACK}, @ref{SPREAD}
11076 @section @code{VERIFY} --- Scan a string for the absence of a set of characters
11078 @cindex string, find missing set
11081 @item @emph{Description}:
11082 Verifies that all the characters in a @var{SET} are present in a @var{STRING}.
11084 If @var{BACK} is either absent or equals @code{FALSE}, this function
11085 returns the position of the leftmost character of @var{STRING} that is
11086 not in @var{SET}. If @var{BACK} equals @code{TRUE}, the rightmost position
11087 is returned. If all characters of @var{SET} are found in @var{STRING}, the
11090 @item @emph{Standard}:
11091 Fortran 95 and later, with @var{KIND} argument Fortran 2003 and later
11093 @item @emph{Class}:
11096 @item @emph{Syntax}:
11097 @code{RESULT = VERIFY(STRING, SET[, BACK [, KIND]])}
11099 @item @emph{Arguments}:
11100 @multitable @columnfractions .15 .70
11101 @item @var{STRING} @tab Shall be of type @code{CHARACTER}.
11102 @item @var{SET} @tab Shall be of type @code{CHARACTER}.
11103 @item @var{BACK} @tab (Optional) shall be of type @code{LOGICAL}.
11104 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
11105 expression indicating the kind parameter of the result.
11108 @item @emph{Return value}:
11109 The return value is of type @code{INTEGER} and of kind @var{KIND}. If
11110 @var{KIND} is absent, the return value is of default integer kind.
11112 @item @emph{Example}:
11114 PROGRAM test_verify
11115 WRITE(*,*) VERIFY("FORTRAN", "AO") ! 1, found 'F'
11116 WRITE(*,*) VERIFY("FORTRAN", "FOO") ! 3, found 'R'
11117 WRITE(*,*) VERIFY("FORTRAN", "C++") ! 1, found 'F'
11118 WRITE(*,*) VERIFY("FORTRAN", "C++", .TRUE.) ! 7, found 'N'
11119 WRITE(*,*) VERIFY("FORTRAN", "FORTRAN") ! 0' found none
11123 @item @emph{See also}:
11124 @ref{SCAN}, @ref{INDEX intrinsic}
11130 @section @code{XOR} --- Bitwise logical exclusive OR
11132 @cindex bitwise logical exclusive or
11133 @cindex logical exclusive or, bitwise
11136 @item @emph{Description}:
11137 Bitwise logical exclusive or.
11139 This intrinsic routine is provided for backwards compatibility with
11140 GNU Fortran 77. For integer arguments, programmers should consider
11141 the use of the @ref{IEOR} intrinsic defined by the Fortran standard.
11143 @item @emph{Standard}:
11146 @item @emph{Class}:
11149 @item @emph{Syntax}:
11150 @code{RESULT = XOR(X, Y)}
11152 @item @emph{Arguments}:
11153 @multitable @columnfractions .15 .70
11154 @item @var{X} @tab The type shall be either a scalar @code{INTEGER}
11155 type or a scalar @code{LOGICAL} type.
11156 @item @var{Y} @tab The type shall be the same as the type of @var{I}.
11159 @item @emph{Return value}:
11160 The return type is either a scalar @code{INTEGER} or a scalar
11161 @code{LOGICAL}. If the kind type parameters differ, then the
11162 smaller kind type is implicitly converted to larger kind, and the
11163 return has the larger kind.
11165 @item @emph{Example}:
11168 LOGICAL :: T = .TRUE., F = .FALSE.
11170 DATA a / Z'F' /, b / Z'3' /
11172 WRITE (*,*) XOR(T, T), XOR(T, F), XOR(F, T), XOR(F, F)
11173 WRITE (*,*) XOR(a, b)
11177 @item @emph{See also}:
11178 Fortran 95 elemental function: @ref{IEOR}
11183 @node Intrinsic Modules
11184 @chapter Intrinsic Modules
11185 @cindex intrinsic Modules
11187 @c @node ISO_FORTRAN_ENV
11188 @section @code{ISO_FORTRAN_ENV}
11190 @item @emph{Standard}:
11191 Fortran 2003 and later
11194 The @code{ISO_FORTRAN_ENV} module provides the following scalar default-integer
11198 @item @code{CHARACTER_STORAGE_SIZE}:
11199 Size in bits of the character storage unit.
11201 @item @code{ERROR_UNIT}:
11202 Identifies the preconnected unit used for error reporting.
11204 @item @code{FILE_STORAGE_SIZE}:
11205 Size in bits of the file-storage unit.
11207 @item @code{INPUT_UNIT}:
11208 Identifies the preconnected unit identified by the asterisk
11209 (@code{*}) in @code{READ} statement.
11211 @item @code{IOSTAT_END}:
11212 The value assigned to the variable passed to the IOSTAT= specifier of
11213 an input/output statement if an end-of-file condition occurred.
11215 @item @code{IOSTAT_EOR}:
11216 The value assigned to the variable passed to the IOSTAT= specifier of
11217 an input/output statement if an end-of-record condition occurred.
11219 @item @code{NUMERIC_STORAGE_SIZE}:
11220 The size in bits of the numeric storage unit.
11222 @item @code{OUTPUT_UNIT}:
11223 Identifies the preconnected unit identified by the asterisk
11224 (@code{*}) in @code{WRITE} statement.
11227 @c @node ISO_C_BINDING
11228 @section @code{ISO_C_BINDING}
11230 @item @emph{Standard}:
11231 Fortran 2003 and later, GNU extensions
11234 The following intrinsic procedures are provided by the module; their
11235 definition can be found in the section Intrinsic Procedures of this
11239 @item @code{C_ASSOCIATED}
11240 @item @code{C_F_POINTER}
11241 @item @code{C_F_PROCPOINTER}
11242 @item @code{C_FUNLOC}
11246 The @code{ISO_C_BINDING} module provides the following named constants of the
11247 type integer, which can be used as KIND type parameter. Note that GNU
11248 Fortran currently does not support the @code{C_INT_FAST...} KIND type
11249 parameters (marked by an asterisk (@code{*}) in the list below).
11250 The @code{C_INT_FAST...} parameters have therefore the value @math{-2}
11251 and cannot be used as KIND type parameter of the @code{INTEGER} type.
11253 In addition to the integer named constants required by the Fortran 2003
11254 standard, GNU Fortran provides as an extension named constants for the
11255 128-bit integer types supported by the C compiler: @code{C_INT128_T,
11256 C_INT_LEAST128_T, C_INT_FAST128_T}.
11258 @multitable @columnfractions .15 .35 .35 .35
11259 @item Fortran Type @tab Named constant @tab C type @tab Extension
11260 @item @code{INTEGER}@tab @code{C_INT} @tab @code{int}
11261 @item @code{INTEGER}@tab @code{C_SHORT} @tab @code{short int}
11262 @item @code{INTEGER}@tab @code{C_LONG} @tab @code{long int}
11263 @item @code{INTEGER}@tab @code{C_LONG_LONG} @tab @code{long long int}
11264 @item @code{INTEGER}@tab @code{C_SIGNED_CHAR} @tab @code{signed char}/@code{unsigned char}
11265 @item @code{INTEGER}@tab @code{C_SIZE_T} @tab @code{size_t}
11266 @item @code{INTEGER}@tab @code{C_INT8_T} @tab @code{int8_t}
11267 @item @code{INTEGER}@tab @code{C_INT16_T} @tab @code{int16_t}
11268 @item @code{INTEGER}@tab @code{C_INT32_T} @tab @code{int32_t}
11269 @item @code{INTEGER}@tab @code{C_INT64_T} @tab @code{int64_t}
11270 @item @code{INTEGER}@tab @code{C_INT128_T} @tab @code{int128_t} @tab Ext.
11271 @item @code{INTEGER}@tab @code{C_INT_LEAST8_T} @tab @code{int_least8_t}
11272 @item @code{INTEGER}@tab @code{C_INT_LEAST16_T} @tab @code{int_least16_t}
11273 @item @code{INTEGER}@tab @code{C_INT_LEAST32_T} @tab @code{int_least32_t}
11274 @item @code{INTEGER}@tab @code{C_INT_LEAST64_T} @tab @code{int_least64_t}
11275 @item @code{INTEGER}@tab @code{C_INT_LEAST128_T} @tab @code{int_least128_t} @tab Ext.
11276 @item @code{INTEGER}@tab @code{C_INT_FAST8_T}* @tab @code{int_fast8_t}
11277 @item @code{INTEGER}@tab @code{C_INT_FAST16_T}* @tab @code{int_fast16_t}
11278 @item @code{INTEGER}@tab @code{C_INT_FAST32_T}* @tab @code{int_fast32_t}
11279 @item @code{INTEGER}@tab @code{C_INT_FAST64_T}* @tab @code{int_fast64_t}
11280 @item @code{INTEGER}@tab @code{C_INT_FAST128_T}* @tab @code{int_fast128_t} @tab Ext.
11281 @item @code{INTEGER}@tab @code{C_INTMAX_T} @tab @code{intmax_t}
11282 @item @code{INTEGER}@tab @code{C_INTPTR_T} @tab @code{intptr_t}
11283 @item @code{REAL} @tab @code{C_FLOAT} @tab @code{float}
11284 @item @code{REAL} @tab @code{C_DOUBLE} @tab @code{double}
11285 @item @code{REAL} @tab @code{C_LONG_DOUBLE} @tab @code{long double}
11286 @item @code{COMPLEX}@tab @code{C_FLOAT_COMPLEX} @tab @code{float _Complex}
11287 @item @code{COMPLEX}@tab @code{C_DOUBLE_COMPLEX}@tab @code{double _Complex}
11288 @item @code{COMPLEX}@tab @code{C_LONG_DOUBLE_COMPLEX}@tab @code{long double _Complex}
11289 @item @code{LOGICAL}@tab @code{C_BOOL} @tab @code{_Bool}
11290 @item @code{CHARACTER}@tab @code{C_CHAR} @tab @code{char}
11293 Additionally, the following @code{(CHARACTER(KIND=C_CHAR)} are
11296 @multitable @columnfractions .20 .45 .15
11297 @item Name @tab C definition @tab Value
11298 @item @code{C_NULL_CHAR} @tab null character @tab @code{'\0'}
11299 @item @code{C_ALERT} @tab alert @tab @code{'\a'}
11300 @item @code{C_BACKSPACE} @tab backspace @tab @code{'\b'}
11301 @item @code{C_FORM_FEED} @tab form feed @tab @code{'\f'}
11302 @item @code{C_NEW_LINE} @tab new line @tab @code{'\n'}
11303 @item @code{C_CARRIAGE_RETURN} @tab carriage return @tab @code{'\r'}
11304 @item @code{C_HORIZONTAL_TAB} @tab horizontal tab @tab @code{'\t'}
11305 @item @code{C_VERTICAL_TAB} @tab vertical tab @tab @code{'\v'}
11308 @c @node OpenMP Modules OMP_LIB and OMP_LIB_KINDS
11309 @section OpenMP Modules @code{OMP_LIB} and @code{OMP_LIB_KINDS}
11311 @item @emph{Standard}:
11312 OpenMP Application Program Interface v3.0
11316 The OpenMP Fortran runtime library routines are provided both in
11317 a form of two Fortran 90 modules, named @code{OMP_LIB} and
11318 @code{OMP_LIB_KINDS}, and in a form of a Fortran @code{include} file named
11319 @file{omp_lib.h}. The procedures provided by @code{OMP_LIB} can be found
11320 in the @ref{Top,,Introduction,libgomp,GNU OpenMP runtime library} manual,
11321 the named constants defined in the @code{OMP_LIB_KINDS} module are listed
11324 For details refer to the actual
11325 @uref{http://www.openmp.org/mp-documents/spec30.pdf,
11326 OpenMP Application Program Interface v3.0}.
11328 @code{OMP_LIB_KINDS} provides the following scalar default-integer
11332 @item @code{omp_integer_kind}
11333 @item @code{omp_logical_kind}
11334 @item @code{omp_lock_kind}
11335 @item @code{omp_nest_lock_kind}
11336 @item @code{omp_sched_kind}