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 ``GNU General Public License'' and ``Funding
11 Free Software'', the Front-Cover texts being (a) (see below), and with
12 the Back-Cover Texts being (b) (see below). A copy of the license is
13 included in the gfdl(7) man page.
16 Some basic guidelines for editing this document:
18 (1) The intrinsic procedures are to be listed in alphabetical order.
19 (2) The generic name is to be used.
20 (3) The specific names are included in the function index and in a
21 table at the end of the node (See ABS entry).
22 (4) Try to maintain the same style for each entry.
28 \gdef\acos{\mathop{\rm acos}\nolimits}
29 \gdef\asin{\mathop{\rm asin}\nolimits}
30 \gdef\atan{\mathop{\rm atan}\nolimits}
31 \gdef\acosh{\mathop{\rm acosh}\nolimits}
32 \gdef\asinh{\mathop{\rm asinh}\nolimits}
33 \gdef\atanh{\mathop{\rm atanh}\nolimits}
37 @node Intrinsic Procedures
38 @chapter Intrinsic Procedures
39 @cindex intrinsic procedures
42 * Introduction: Introduction to Intrinsics
43 * @code{ABORT}: ABORT, Abort the program
44 * @code{ABS}: ABS, Absolute value
45 * @code{ACCESS}: ACCESS, Checks file access modes
46 * @code{ACHAR}: ACHAR, Character in @acronym{ASCII} collating sequence
47 * @code{ACOS}: ACOS, Arccosine function
48 * @code{ACOSH}: ACOSH, Hyperbolic arccosine function
49 * @code{ADJUSTL}: ADJUSTL, Left adjust a string
50 * @code{ADJUSTR}: ADJUSTR, Right adjust a string
51 * @code{AIMAG}: AIMAG, Imaginary part of complex number
52 * @code{AINT}: AINT, Truncate to a whole number
53 * @code{ALARM}: ALARM, Set an alarm clock
54 * @code{ALL}: ALL, Determine if all values are true
55 * @code{ALLOCATED}: ALLOCATED, Status of allocatable entity
56 * @code{AND}: AND, Bitwise logical AND
57 * @code{ANINT}: ANINT, Nearest whole number
58 * @code{ANY}: ANY, Determine if any values are true
59 * @code{ASIN}: ASIN, Arcsine function
60 * @code{ASINH}: ASINH, Hyperbolic arcsine function
61 * @code{ASSOCIATED}: ASSOCIATED, Status of a pointer or pointer/target pair
62 * @code{ATAN}: ATAN, Arctangent function
63 * @code{ATAN2}: ATAN2, Arctangent function
64 * @code{ATANH}: ATANH, Hyperbolic arctangent function
65 * @code{BESSEL_J0}: BESSEL_J0, Bessel function of the first kind of order 0
66 * @code{BESSEL_J1}: BESSEL_J1, Bessel function of the first kind of order 1
67 * @code{BESSEL_JN}: BESSEL_JN, Bessel function of the first kind
68 * @code{BESSEL_Y0}: BESSEL_Y0, Bessel function of the second kind of order 0
69 * @code{BESSEL_Y1}: BESSEL_Y1, Bessel function of the second kind of order 1
70 * @code{BESSEL_YN}: BESSEL_YN, Bessel function of the second kind
71 * @code{BIT_SIZE}: BIT_SIZE, Bit size inquiry function
72 * @code{BTEST}: BTEST, Bit test function
73 * @code{C_ASSOCIATED}: C_ASSOCIATED, Status of a C pointer
74 * @code{C_F_POINTER}: C_F_POINTER, Convert C into Fortran pointer
75 * @code{C_F_PROCPOINTER}: C_F_PROCPOINTER, Convert C into Fortran procedure pointer
76 * @code{C_FUNLOC}: C_FUNLOC, Obtain the C address of a procedure
77 * @code{C_LOC}: C_LOC, Obtain the C address of an object
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{LEN}: LEN, Length of a character entity
168 * @code{LEN_TRIM}: LEN_TRIM, Length of a character entity without trailing blank characters
169 * @code{LOG_GAMMA}: LOG_GAMMA, Logarithm of the Gamma function
170 * @code{LGE}: LGE, Lexical greater than or equal
171 * @code{LGT}: LGT, Lexical greater than
172 * @code{LINK}: LINK, Create a hard link
173 * @code{LLE}: LLE, Lexical less than or equal
174 * @code{LLT}: LLT, Lexical less than
175 * @code{LNBLNK}: LNBLNK, Index of the last non-blank character in a string
176 * @code{LOC}: LOC, Returns the address of a variable
177 * @code{LOG}: LOG, Logarithm function
178 * @code{LOG10}: LOG10, Base 10 logarithm function
179 * @code{LOGICAL}: LOGICAL, Convert to logical type
180 * @code{LONG}: LONG, Convert to integer type
181 * @code{LSHIFT}: LSHIFT, Left shift bits
182 * @code{LSTAT}: LSTAT, Get file status
183 * @code{LTIME}: LTIME, Convert time to local time info
184 * @code{MALLOC}: MALLOC, Dynamic memory allocation function
185 * @code{MATMUL}: MATMUL, matrix multiplication
186 * @code{MAX}: MAX, Maximum value of an argument list
187 * @code{MAXEXPONENT}: MAXEXPONENT, Maximum exponent of a real kind
188 * @code{MAXLOC}: MAXLOC, Location of the maximum value within an array
189 * @code{MAXVAL}: MAXVAL, Maximum value of an array
190 * @code{MCLOCK}: MCLOCK, Time function
191 * @code{MCLOCK8}: MCLOCK8, Time function (64-bit)
192 * @code{MERGE}: MERGE, Merge arrays
193 * @code{MIN}: MIN, Minimum value of an argument list
194 * @code{MINEXPONENT}: MINEXPONENT, Minimum exponent of a real kind
195 * @code{MINLOC}: MINLOC, Location of the minimum value within an array
196 * @code{MINVAL}: MINVAL, Minimum value of an array
197 * @code{MOD}: MOD, Remainder function
198 * @code{MODULO}: MODULO, Modulo function
199 * @code{MOVE_ALLOC}: MOVE_ALLOC, Move allocation from one object to another
200 * @code{MVBITS}: MVBITS, Move bits from one integer to another
201 * @code{NEAREST}: NEAREST, Nearest representable number
202 * @code{NEW_LINE}: NEW_LINE, New line character
203 * @code{NINT}: NINT, Nearest whole number
204 * @code{NOT}: NOT, Logical negation
205 * @code{NULL}: NULL, Function that returns an disassociated pointer
206 * @code{OR}: OR, Bitwise logical OR
207 * @code{PACK}: PACK, Pack an array into an array of rank one
208 * @code{PERROR}: PERROR, Print system error message
209 * @code{PRECISION}: PRECISION, Decimal precision of a real kind
210 * @code{PRESENT}: PRESENT, Determine whether an optional dummy argument is specified
211 * @code{PRODUCT}: PRODUCT, Product of array elements
212 * @code{RADIX}: RADIX, Base of a data model
213 * @code{RANDOM_NUMBER}: RANDOM_NUMBER, Pseudo-random number
214 * @code{RANDOM_SEED}: RANDOM_SEED, Initialize a pseudo-random number sequence
215 * @code{RAND}: RAND, Real pseudo-random number
216 * @code{RANGE}: RANGE, Decimal exponent range of a real kind
217 * @code{RAN}: RAN, Real pseudo-random number
218 * @code{REAL}: REAL, Convert to real type
219 * @code{RENAME}: RENAME, Rename a file
220 * @code{REPEAT}: REPEAT, Repeated string concatenation
221 * @code{RESHAPE}: RESHAPE, Function to reshape an array
222 * @code{RRSPACING}: RRSPACING, Reciprocal of the relative spacing
223 * @code{RSHIFT}: RSHIFT, Right shift bits
224 * @code{SCALE}: SCALE, Scale a real value
225 * @code{SCAN}: SCAN, Scan a string for the presence of a set of characters
226 * @code{SECNDS}: SECNDS, Time function
227 * @code{SECOND}: SECOND, CPU time function
228 * @code{SELECTED_INT_KIND}: SELECTED_INT_KIND, Choose integer kind
229 * @code{SELECTED_REAL_KIND}: SELECTED_REAL_KIND, Choose real kind
230 * @code{SET_EXPONENT}: SET_EXPONENT, Set the exponent of the model
231 * @code{SHAPE}: SHAPE, Determine the shape of an array
232 * @code{SIGN}: SIGN, Sign copying function
233 * @code{SIGNAL}: SIGNAL, Signal handling subroutine (or function)
234 * @code{SIN}: SIN, Sine function
235 * @code{SINH}: SINH, Hyperbolic sine function
236 * @code{SIZE}: SIZE, Function to determine the size of an array
237 * @code{SIZEOF}: SIZEOF, Determine the size in bytes of an expression
238 * @code{SLEEP}: SLEEP, Sleep for the specified number of seconds
239 * @code{SNGL}: SNGL, Convert double precision real to default real
240 * @code{SPACING}: SPACING, Smallest distance between two numbers of a given type
241 * @code{SPREAD}: SPREAD, Add a dimension to an array
242 * @code{SQRT}: SQRT, Square-root function
243 * @code{SRAND}: SRAND, Reinitialize the random number generator
244 * @code{STAT}: STAT, Get file status
245 * @code{SUM}: SUM, Sum of array elements
246 * @code{SYMLNK}: SYMLNK, Create a symbolic link
247 * @code{SYSTEM}: SYSTEM, Execute a shell command
248 * @code{SYSTEM_CLOCK}: SYSTEM_CLOCK, Time function
249 * @code{TAN}: TAN, Tangent function
250 * @code{TANH}: TANH, Hyperbolic tangent function
251 * @code{TIME}: TIME, Time function
252 * @code{TIME8}: TIME8, Time function (64-bit)
253 * @code{TINY}: TINY, Smallest positive number of a real kind
254 * @code{TRANSFER}: TRANSFER, Transfer bit patterns
255 * @code{TRANSPOSE}: TRANSPOSE, Transpose an array of rank two
256 * @code{TRIM}: TRIM, Remove trailing blank characters of a string
257 * @code{TTYNAM}: TTYNAM, Get the name of a terminal device.
258 * @code{UBOUND}: UBOUND, Upper dimension bounds of an array
259 * @code{UMASK}: UMASK, Set the file creation mask
260 * @code{UNLINK}: UNLINK, Remove a file from the file system
261 * @code{UNPACK}: UNPACK, Unpack an array of rank one into an array
262 * @code{VERIFY}: VERIFY, Scan a string for the absence of a set of characters
263 * @code{XOR}: XOR, Bitwise logical exclusive or
266 @node Introduction to Intrinsics
267 @section Introduction to intrinsic procedures
269 The intrinsic procedures provided by GNU Fortran include all of the
270 intrinsic procedures required by the Fortran 95 standard, a set of
271 intrinsic procedures for backwards compatibility with G77, and a
272 selection of intrinsic procedures from the Fortran 2003 and Fortran 2008
273 standards. Any conflict between a description here and a description in
274 either the Fortran 95 standard, the Fortran 2003 standard or the Fortran
275 2008 standard is unintentional, and the standard(s) should be considered
278 The enumeration of the @code{KIND} type parameter is processor defined in
279 the Fortran 95 standard. GNU Fortran defines the default integer type and
280 default real type by @code{INTEGER(KIND=4)} and @code{REAL(KIND=4)},
281 respectively. The standard mandates that both data types shall have
282 another kind, which have more precision. On typical target architectures
283 supported by @command{gfortran}, this kind type parameter is @code{KIND=8}.
284 Hence, @code{REAL(KIND=8)} and @code{DOUBLE PRECISION} are equivalent.
285 In the description of generic intrinsic procedures, the kind type parameter
286 will be specified by @code{KIND=*}, and in the description of specific
287 names for an intrinsic procedure the kind type parameter will be explicitly
288 given (e.g., @code{REAL(KIND=4)} or @code{REAL(KIND=8)}). Finally, for
289 brevity the optional @code{KIND=} syntax will be omitted.
291 Many of the intrinsic procedures take one or more optional arguments.
292 This document follows the convention used in the Fortran 95 standard,
293 and denotes such arguments by square brackets.
295 GNU Fortran offers the @option{-std=f95} and @option{-std=gnu} options,
296 which can be used to restrict the set of intrinsic procedures to a
297 given standard. By default, @command{gfortran} sets the @option{-std=gnu}
298 option, and so all intrinsic procedures described here are accepted. There
299 is one caveat. For a select group of intrinsic procedures, @command{g77}
300 implemented both a function and a subroutine. Both classes
301 have been implemented in @command{gfortran} for backwards compatibility
302 with @command{g77}. It is noted here that these functions and subroutines
303 cannot be intermixed in a given subprogram. In the descriptions that follow,
304 the applicable standard for each intrinsic procedure is noted.
309 @section @code{ABORT} --- Abort the program
311 @cindex program termination, with core dump
312 @cindex terminate program, with core dump
316 @item @emph{Description}:
317 @code{ABORT} causes immediate termination of the program. On operating
318 systems that support a core dump, @code{ABORT} will produce a core dump,
319 which is suitable for debugging purposes.
321 @item @emph{Standard}:
330 @item @emph{Return value}:
333 @item @emph{Example}:
336 integer :: i = 1, j = 2
337 if (i /= j) call abort
338 end program test_abort
341 @item @emph{See also}:
342 @ref{EXIT}, @ref{KILL}
349 @section @code{ABS} --- Absolute value
356 @cindex absolute value
359 @item @emph{Description}:
360 @code{ABS(X)} computes the absolute value of @code{X}.
362 @item @emph{Standard}:
363 F77 and later, has overloads that are GNU extensions
369 @code{RESULT = ABS(X)}
371 @item @emph{Arguments}:
372 @multitable @columnfractions .15 .70
373 @item @var{X} @tab The type of the argument shall be an @code{INTEGER(*)},
374 @code{REAL(*)}, or @code{COMPLEX(*)}.
377 @item @emph{Return value}:
378 The return value is of the same type and
379 kind as the argument except the return value is @code{REAL(*)} for a
380 @code{COMPLEX(*)} argument.
382 @item @emph{Example}:
387 complex :: z = (-1.e0,0.e0)
394 @item @emph{Specific names}:
395 @multitable @columnfractions .20 .20 .20 .25
396 @item Name @tab Argument @tab Return type @tab Standard
397 @item @code{CABS(Z)} @tab @code{COMPLEX(4) Z} @tab @code{REAL(4)} @tab F77 and later
398 @item @code{DABS(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab F77 and later
399 @item @code{IABS(I)} @tab @code{INTEGER(4) I} @tab @code{INTEGER(4)} @tab F77 and later
400 @item @code{ZABS(Z)} @tab @code{COMPLEX(8) Z} @tab @code{COMPLEX(8)} @tab GNU extension
401 @item @code{CDABS(Z)} @tab @code{COMPLEX(8) Z} @tab @code{COMPLEX(8)} @tab GNU extension
408 @section @code{ACCESS} --- Checks file access modes
410 @cindex file system, access mode
413 @item @emph{Description}:
414 @code{ACCESS(NAME, MODE)} checks whether the file @var{NAME}
415 exists, is readable, writable or executable. Except for the
416 executable check, @code{ACCESS} can be replaced by
417 Fortran 95's @code{INQUIRE}.
419 @item @emph{Standard}:
426 @code{RESULT = ACCESS(NAME, MODE)}
428 @item @emph{Arguments}:
429 @multitable @columnfractions .15 .70
430 @item @var{NAME} @tab Scalar @code{CHARACTER} with the file name.
431 Tailing blank are ignored unless the character @code{achar(0)} is
432 present, then all characters up to and excluding @code{achar(0)} are
434 @item @var{MODE} @tab Scalar @code{CHARACTER} with the file access mode,
435 may be any concatenation of @code{"r"} (readable), @code{"w"} (writable)
436 and @code{"x"} (executable), or @code{" "} to check for existence.
439 @item @emph{Return value}:
440 Returns a scalar @code{INTEGER}, which is @code{0} if the file is
441 accessible in the given mode; otherwise or if an invalid argument
442 has been given for @code{MODE} the value @code{1} is returned.
444 @item @emph{Example}:
448 character(len=*), parameter :: file = 'test.dat'
449 character(len=*), parameter :: file2 = 'test.dat '//achar(0)
450 if(access(file,' ') == 0) print *, trim(file),' is exists'
451 if(access(file,'r') == 0) print *, trim(file),' is readable'
452 if(access(file,'w') == 0) print *, trim(file),' is writable'
453 if(access(file,'x') == 0) print *, trim(file),' is executable'
454 if(access(file2,'rwx') == 0) &
455 print *, trim(file2),' is readable, writable and executable'
456 end program access_test
458 @item @emph{Specific names}:
459 @item @emph{See also}:
466 @section @code{ACHAR} --- Character in @acronym{ASCII} collating sequence
468 @cindex @acronym{ASCII} collating sequence
469 @cindex collating sequence, @acronym{ASCII}
472 @item @emph{Description}:
473 @code{ACHAR(I)} returns the character located at position @code{I}
474 in the @acronym{ASCII} collating sequence.
476 @item @emph{Standard}:
483 @code{RESULT = ACHAR(I)}
485 @item @emph{Arguments}:
486 @multitable @columnfractions .15 .70
487 @item @var{I} @tab The type shall be @code{INTEGER(*)}.
490 @item @emph{Return value}:
491 The return value is of type @code{CHARACTER} with a length of one. The
492 kind type parameter is the same as @code{KIND('A')}.
494 @item @emph{Example}:
499 end program test_achar
503 See @ref{ICHAR} for a discussion of converting between numerical values
504 and formatted string representations.
506 @item @emph{See also}:
507 @ref{CHAR}, @ref{IACHAR}, @ref{ICHAR}
514 @section @code{ACOS} --- Arccosine function
517 @cindex trigonometric function, cosine, inverse
518 @cindex cosine, inverse
521 @item @emph{Description}:
522 @code{ACOS(X)} computes the arccosine of @var{X} (inverse of @code{COS(X)}).
524 @item @emph{Standard}:
531 @code{RESULT = ACOS(X)}
533 @item @emph{Arguments}:
534 @multitable @columnfractions .15 .70
535 @item @var{X} @tab The type shall be @code{REAL(*)} with a magnitude that is
539 @item @emph{Return value}:
540 The return value is of type @code{REAL(*)} and it lies in the
541 range @math{ 0 \leq \acos(x) \leq \pi}. The kind type parameter
542 is the same as @var{X}.
544 @item @emph{Example}:
547 real(8) :: x = 0.866_8
549 end program test_acos
552 @item @emph{Specific names}:
553 @multitable @columnfractions .20 .20 .20 .25
554 @item Name @tab Argument @tab Return type @tab Standard
555 @item @code{DACOS(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab F77 and later
558 @item @emph{See also}:
559 Inverse function: @ref{COS}
566 @section @code{ACOSH} --- Hyperbolic arccosine function
569 @cindex area hyperbolic cosine
570 @cindex hyperbolic arccosine
571 @cindex hyperbolic function, cosine, inverse
572 @cindex cosine, hyperbolic, inverse
575 @item @emph{Description}:
576 @code{ACOSH(X)} computes the hyperbolic arccosine of @var{X} (inverse of
579 @item @emph{Standard}:
580 Fortran 2008 and later
586 @code{RESULT = ACOSH(X)}
588 @item @emph{Arguments}:
589 @multitable @columnfractions .15 .70
590 @item @var{X} @tab The type shall be @code{REAL} or @code{COMPLEX}.
593 @item @emph{Return value}:
594 The return value has the same type and kind as @var{X}
596 @item @emph{Example}:
599 REAL(8), DIMENSION(3) :: x = (/ 1.0, 2.0, 3.0 /)
604 @item @emph{Specific names}:
605 @multitable @columnfractions .20 .20 .20 .25
606 @item Name @tab Argument @tab Return type @tab Standard
607 @item @code{DACOSH(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU extension
610 @item @emph{See also}:
611 Inverse function: @ref{COSH}
617 @section @code{ADJUSTL} --- Left adjust a string
619 @cindex string, adjust left
620 @cindex adjust string
623 @item @emph{Description}:
624 @code{ADJUSTL(STR)} will left adjust a string by removing leading spaces.
625 Spaces are inserted at the end of the string as needed.
627 @item @emph{Standard}:
634 @code{RESULT = ADJUSTL(STR)}
636 @item @emph{Arguments}:
637 @multitable @columnfractions .15 .70
638 @item @var{STR} @tab The type shall be @code{CHARACTER}.
641 @item @emph{Return value}:
642 The return value is of type @code{CHARACTER} where leading spaces
643 are removed and the same number of spaces are inserted on the end
646 @item @emph{Example}:
649 character(len=20) :: str = ' gfortran'
652 end program test_adjustl
655 @item @emph{See also}:
656 @ref{ADJUSTR}, @ref{TRIM}
662 @section @code{ADJUSTR} --- Right adjust a string
664 @cindex string, adjust right
665 @cindex adjust string
668 @item @emph{Description}:
669 @code{ADJUSTR(STR)} will right adjust a string by removing trailing spaces.
670 Spaces are inserted at the start of the string as needed.
672 @item @emph{Standard}:
679 @code{RESULT = ADJUSTR(STR)}
681 @item @emph{Arguments}:
682 @multitable @columnfractions .15 .70
683 @item @var{STR} @tab The type shall be @code{CHARACTER}.
686 @item @emph{Return value}:
687 The return value is of type @code{CHARACTER} where trailing spaces
688 are removed and the same number of spaces are inserted at the start
691 @item @emph{Example}:
694 character(len=20) :: str = 'gfortran'
697 end program test_adjustr
700 @item @emph{See also}:
701 @ref{ADJUSTL}, @ref{TRIM}
707 @section @code{AIMAG} --- Imaginary part of complex number
712 @cindex complex numbers, imaginary part
715 @item @emph{Description}:
716 @code{AIMAG(Z)} yields the imaginary part of complex argument @code{Z}.
717 The @code{IMAG(Z)} and @code{IMAGPART(Z)} intrinsic functions are provided
718 for compatibility with @command{g77}, and their use in new code is
719 strongly discouraged.
721 @item @emph{Standard}:
722 F77 and later, has overloads that are GNU extensions
728 @code{RESULT = AIMAG(Z)}
730 @item @emph{Arguments}:
731 @multitable @columnfractions .15 .70
732 @item @var{Z} @tab The type of the argument shall be @code{COMPLEX(*)}.
735 @item @emph{Return value}:
736 The return value is of type real with the
737 kind type parameter of the argument.
739 @item @emph{Example}:
744 z4 = cmplx(1.e0_4, 0.e0_4)
745 z8 = cmplx(0.e0_8, 1.e0_8)
746 print *, aimag(z4), dimag(z8)
747 end program test_aimag
750 @item @emph{Specific names}:
751 @multitable @columnfractions .20 .20 .20 .25
752 @item Name @tab Argument @tab Return type @tab Standard
753 @item @code{DIMAG(Z)} @tab @code{COMPLEX(8) Z} @tab @code{REAL(8)} @tab GNU extension
754 @item @code{IMAG(Z)} @tab @code{COMPLEX(*) Z} @tab @code{REAL(*)} @tab GNU extension
755 @item @code{IMAGPART(Z)} @tab @code{COMPLEX(*) Z} @tab @code{REAL(*)} @tab GNU extension
762 @section @code{AINT} --- Truncate to a whole number
766 @cindex rounding, floor
769 @item @emph{Description}:
770 @code{AINT(X [, KIND])} truncates its argument to a whole number.
772 @item @emph{Standard}:
779 @code{RESULT = AINT(X [, KIND])}
781 @item @emph{Arguments}:
782 @multitable @columnfractions .15 .70
783 @item @var{X} @tab The type of the argument shall be @code{REAL(*)}.
784 @item @var{KIND} @tab (Optional) An @code{INTEGER(*)} initialization
785 expression indicating the kind parameter of
789 @item @emph{Return value}:
790 The return value is of type real with the kind type parameter of the
791 argument if the optional @var{KIND} is absent; otherwise, the kind
792 type parameter will be given by @var{KIND}. If the magnitude of
793 @var{X} is less than one, then @code{AINT(X)} returns zero. If the
794 magnitude is equal to or greater than one, then it returns the largest
795 whole number that does not exceed its magnitude. The sign is the same
796 as the sign of @var{X}.
798 @item @emph{Example}:
805 print *, aint(x4), dint(x8)
807 end program test_aint
810 @item @emph{Specific names}:
811 @multitable @columnfractions .20 .20 .20 .25
812 @item Name @tab Argument @tab Return type @tab Standard
813 @item @code{DINT(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab F77 and later
820 @section @code{ALARM} --- Execute a routine after a given delay
822 @cindex delayed execution
825 @item @emph{Description}:
826 @code{ALARM(SECONDS, HANDLER [, STATUS])} causes external subroutine @var{HANDLER}
827 to be executed after a delay of @var{SECONDS} by using @code{alarm(2)} to
828 set up a signal and @code{signal(2)} to catch it. If @var{STATUS} is
829 supplied, it will be returned with the number of seconds remaining until
830 any previously scheduled alarm was due to be delivered, or zero if there
831 was no previously scheduled alarm.
833 @item @emph{Standard}:
840 @code{CALL ALARM(SECONDS, HANDLER [, STATUS])}
842 @item @emph{Arguments}:
843 @multitable @columnfractions .15 .70
844 @item @var{SECONDS} @tab The type of the argument shall be a scalar
845 @code{INTEGER}. It is @code{INTENT(IN)}.
846 @item @var{HANDLER} @tab Signal handler (@code{INTEGER FUNCTION} or
847 @code{SUBROUTINE}) or dummy/global @code{INTEGER} scalar. The scalar
848 values may be either @code{SIG_IGN=1} to ignore the alarm generated
849 or @code{SIG_DFL=0} to set the default action. It is @code{INTENT(IN)}.
850 @item @var{STATUS} @tab (Optional) @var{STATUS} shall be a scalar
851 variable of the default @code{INTEGER} kind. It is @code{INTENT(OUT)}.
854 @item @emph{Example}:
857 external handler_print
859 call alarm (3, handler_print, i)
862 end program test_alarm
864 This will cause the external routine @var{handler_print} to be called
871 @section @code{ALL} --- All values in @var{MASK} along @var{DIM} are true
873 @cindex array, apply condition
874 @cindex array, condition testing
877 @item @emph{Description}:
878 @code{ALL(MASK [, DIM])} determines if all the values are true in @var{MASK}
879 in the array along dimension @var{DIM}.
881 @item @emph{Standard}:
885 Transformational function
888 @code{RESULT = ALL(MASK [, DIM])}
890 @item @emph{Arguments}:
891 @multitable @columnfractions .15 .70
892 @item @var{MASK} @tab The type of the argument shall be @code{LOGICAL(*)} and
893 it shall not be scalar.
894 @item @var{DIM} @tab (Optional) @var{DIM} shall be a scalar integer
895 with a value that lies between one and the rank of @var{MASK}.
898 @item @emph{Return value}:
899 @code{ALL(MASK)} returns a scalar value of type @code{LOGICAL(*)} where
900 the kind type parameter is the same as the kind type parameter of
901 @var{MASK}. If @var{DIM} is present, then @code{ALL(MASK, DIM)} returns
902 an array with the rank of @var{MASK} minus 1. The shape is determined from
903 the shape of @var{MASK} where the @var{DIM} dimension is elided.
907 @code{ALL(MASK)} is true if all elements of @var{MASK} are true.
908 It also is true if @var{MASK} has zero size; otherwise, it is false.
910 If the rank of @var{MASK} is one, then @code{ALL(MASK,DIM)} is equivalent
911 to @code{ALL(MASK)}. If the rank is greater than one, then @code{ALL(MASK,DIM)}
912 is determined by applying @code{ALL} to the array sections.
915 @item @emph{Example}:
919 l = all((/.true., .true., .true./))
924 integer a(2,3), b(2,3)
928 print *, all(a .eq. b, 1)
929 print *, all(a .eq. b, 2)
930 end subroutine section
938 @section @code{ALLOCATED} --- Status of an allocatable entity
940 @cindex allocation, status
943 @item @emph{Description}:
944 @code{ALLOCATED(X)} checks the status of whether @var{X} is allocated.
946 @item @emph{Standard}:
953 @code{RESULT = ALLOCATED(X)}
955 @item @emph{Arguments}:
956 @multitable @columnfractions .15 .70
957 @item @var{X} @tab The argument shall be an @code{ALLOCATABLE} array.
960 @item @emph{Return value}:
961 The return value is a scalar @code{LOGICAL} with the default logical
962 kind type parameter. If @var{X} is allocated, @code{ALLOCATED(X)}
963 is @code{.TRUE.}; otherwise, it returns @code{.FALSE.}
965 @item @emph{Example}:
967 program test_allocated
969 real(4), allocatable :: x(:)
970 if (allocated(x) .eqv. .false.) allocate(x(i))
971 end program test_allocated
978 @section @code{AND} --- Bitwise logical AND
980 @cindex bitwise logical and
981 @cindex logical and, bitwise
984 @item @emph{Description}:
985 Bitwise logical @code{AND}.
987 This intrinsic routine is provided for backwards compatibility with
988 GNU Fortran 77. For integer arguments, programmers should consider
989 the use of the @ref{IAND} intrinsic defined by the Fortran standard.
991 @item @emph{Standard}:
998 @code{RESULT = AND(I, J)}
1000 @item @emph{Arguments}:
1001 @multitable @columnfractions .15 .70
1002 @item @var{I} @tab The type shall be either @code{INTEGER(*)} or @code{LOGICAL}.
1003 @item @var{J} @tab The type shall be either @code{INTEGER(*)} or @code{LOGICAL}.
1006 @item @emph{Return value}:
1007 The return type is either @code{INTEGER(*)} or @code{LOGICAL} after
1008 cross-promotion of the arguments.
1010 @item @emph{Example}:
1013 LOGICAL :: T = .TRUE., F = .FALSE.
1015 DATA a / Z'F' /, b / Z'3' /
1017 WRITE (*,*) AND(T, T), AND(T, F), AND(F, T), AND(F, F)
1018 WRITE (*,*) AND(a, b)
1022 @item @emph{See also}:
1023 F95 elemental function: @ref{IAND}
1029 @section @code{ANINT} --- Nearest whole number
1033 @cindex rounding, ceiling
1036 @item @emph{Description}:
1037 @code{ANINT(X [, KIND])} rounds its argument to the nearest whole number.
1039 @item @emph{Standard}:
1045 @item @emph{Syntax}:
1046 @code{RESULT = ANINT(X [, KIND])}
1048 @item @emph{Arguments}:
1049 @multitable @columnfractions .15 .70
1050 @item @var{X} @tab The type of the argument shall be @code{REAL(*)}.
1051 @item @var{KIND} @tab (Optional) An @code{INTEGER(*)} initialization
1052 expression indicating the kind parameter of
1056 @item @emph{Return value}:
1057 The return value is of type real with the kind type parameter of the
1058 argument if the optional @var{KIND} is absent; otherwise, the kind
1059 type parameter will be given by @var{KIND}. If @var{X} is greater than
1060 zero, then @code{ANINT(X)} returns @code{AINT(X+0.5)}. If @var{X} is
1061 less than or equal to zero, then it returns @code{AINT(X-0.5)}.
1063 @item @emph{Example}:
1070 print *, anint(x4), dnint(x8)
1072 end program test_anint
1075 @item @emph{Specific names}:
1076 @multitable @columnfractions .20 .20 .20 .25
1077 @item Name @tab Argument @tab Return type @tab Standard
1078 @item @code{DNINT(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab F77 and later
1085 @section @code{ANY} --- Any value in @var{MASK} along @var{DIM} is true
1087 @cindex array, apply condition
1088 @cindex array, condition testing
1091 @item @emph{Description}:
1092 @code{ANY(MASK [, DIM])} determines if any of the values in the logical array
1093 @var{MASK} along dimension @var{DIM} are @code{.TRUE.}.
1095 @item @emph{Standard}:
1099 Transformational function
1101 @item @emph{Syntax}:
1102 @code{RESULT = ANY(MASK [, DIM])}
1104 @item @emph{Arguments}:
1105 @multitable @columnfractions .15 .70
1106 @item @var{MASK} @tab The type of the argument shall be @code{LOGICAL(*)} and
1107 it shall not be scalar.
1108 @item @var{DIM} @tab (Optional) @var{DIM} shall be a scalar integer
1109 with a value that lies between one and the rank of @var{MASK}.
1112 @item @emph{Return value}:
1113 @code{ANY(MASK)} returns a scalar value of type @code{LOGICAL(*)} where
1114 the kind type parameter is the same as the kind type parameter of
1115 @var{MASK}. If @var{DIM} is present, then @code{ANY(MASK, DIM)} returns
1116 an array with the rank of @var{MASK} minus 1. The shape is determined from
1117 the shape of @var{MASK} where the @var{DIM} dimension is elided.
1121 @code{ANY(MASK)} is true if any element of @var{MASK} is true;
1122 otherwise, it is false. It also is false if @var{MASK} has zero size.
1124 If the rank of @var{MASK} is one, then @code{ANY(MASK,DIM)} is equivalent
1125 to @code{ANY(MASK)}. If the rank is greater than one, then @code{ANY(MASK,DIM)}
1126 is determined by applying @code{ANY} to the array sections.
1129 @item @emph{Example}:
1133 l = any((/.true., .true., .true./))
1138 integer a(2,3), b(2,3)
1142 print *, any(a .eq. b, 1)
1143 print *, any(a .eq. b, 2)
1144 end subroutine section
1145 end program test_any
1152 @section @code{ASIN} --- Arcsine function
1155 @cindex trigonometric function, sine, inverse
1156 @cindex sine, inverse
1159 @item @emph{Description}:
1160 @code{ASIN(X)} computes the arcsine of its @var{X} (inverse of @code{SIN(X)}).
1162 @item @emph{Standard}:
1168 @item @emph{Syntax}:
1169 @code{RESULT = ASIN(X)}
1171 @item @emph{Arguments}:
1172 @multitable @columnfractions .15 .70
1173 @item @var{X} @tab The type shall be @code{REAL(*)}, and a magnitude that is
1177 @item @emph{Return value}:
1178 The return value is of type @code{REAL(*)} and it lies in the
1179 range @math{-\pi / 2 \leq \asin (x) \leq \pi / 2}. The kind type
1180 parameter is the same as @var{X}.
1182 @item @emph{Example}:
1185 real(8) :: x = 0.866_8
1187 end program test_asin
1190 @item @emph{Specific names}:
1191 @multitable @columnfractions .20 .20 .20 .25
1192 @item Name @tab Argument @tab Return type @tab Standard
1193 @item @code{DASIN(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab F77 and later
1196 @item @emph{See also}:
1197 Inverse function: @ref{SIN}
1204 @section @code{ASINH} --- Hyperbolic arcsine function
1207 @cindex area hyperbolic sine
1208 @cindex hyperbolic arcsine
1209 @cindex hyperbolic function, sine, inverse
1210 @cindex sine, hyperbolic, inverse
1213 @item @emph{Description}:
1214 @code{ASINH(X)} computes the hyperbolic arcsine of @var{X} (inverse of @code{SINH(X)}).
1216 @item @emph{Standard}:
1217 Fortran 2008 and later
1222 @item @emph{Syntax}:
1223 @code{RESULT = ASINH(X)}
1225 @item @emph{Arguments}:
1226 @multitable @columnfractions .15 .70
1227 @item @var{X} @tab The type shall be @code{REAL} or @code{COMPLEX}.
1230 @item @emph{Return value}:
1231 The return value is of the same type and kind as @var{X}.
1233 @item @emph{Example}:
1236 REAL(8), DIMENSION(3) :: x = (/ -1.0, 0.0, 1.0 /)
1237 WRITE (*,*) ASINH(x)
1241 @item @emph{Specific names}:
1242 @multitable @columnfractions .20 .20 .20 .25
1243 @item Name @tab Argument @tab Return type @tab Standard
1244 @item @code{DASINH(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU extension.
1247 @item @emph{See also}:
1248 Inverse function: @ref{SINH}
1254 @section @code{ASSOCIATED} --- Status of a pointer or pointer/target pair
1256 @cindex pointer, status
1257 @cindex association status
1260 @item @emph{Description}:
1261 @code{ASSOCIATED(PTR [, TGT])} determines the status of the pointer @var{PTR}
1262 or if @var{PTR} is associated with the target @var{TGT}.
1264 @item @emph{Standard}:
1270 @item @emph{Syntax}:
1271 @code{RESULT = ASSOCIATED(PTR [, TGT])}
1273 @item @emph{Arguments}:
1274 @multitable @columnfractions .15 .70
1275 @item @var{PTR} @tab @var{PTR} shall have the @code{POINTER} attribute and
1276 it can be of any type.
1277 @item @var{TGT} @tab (Optional) @var{TGT} shall be a @code{POINTER} or
1278 a @code{TARGET}. It must have the same type, kind type parameter, and
1279 array rank as @var{PTR}.
1281 The status of neither @var{PTR} nor @var{TGT} can be undefined.
1283 @item @emph{Return value}:
1284 @code{ASSOCIATED(PTR)} returns a scalar value of type @code{LOGICAL(4)}.
1285 There are several cases:
1287 @item (A) If the optional @var{TGT} is not present, then @code{ASSOCIATED(PTR)}
1288 is true if @var{PTR} is associated with a target; otherwise, it returns false.
1289 @item (B) If @var{TGT} is present and a scalar target, the result is true if
1291 is not a 0 sized storage sequence and the target associated with @var{PTR}
1292 occupies the same storage units. If @var{PTR} is disassociated, then the
1294 @item (C) If @var{TGT} is present and an array target, the result is true if
1295 @var{TGT} and @var{PTR} have the same shape, are not 0 sized arrays, are
1296 arrays whose elements are not 0 sized storage sequences, and @var{TGT} and
1297 @var{PTR} occupy the same storage units in array element order.
1298 As in case(B), the result is false, if @var{PTR} is disassociated.
1299 @item (D) If @var{TGT} is present and an scalar pointer, the result is true if
1300 target associated with @var{PTR} and the target associated with @var{TGT}
1301 are not 0 sized storage sequences and occupy the same storage units.
1302 The result is false, if either @var{TGT} or @var{PTR} is disassociated.
1303 @item (E) If @var{TGT} is present and an array pointer, the result is true if
1304 target associated with @var{PTR} and the target associated with @var{TGT}
1305 have the same shape, are not 0 sized arrays, are arrays whose elements are
1306 not 0 sized storage sequences, and @var{TGT} and @var{PTR} occupy the same
1307 storage units in array element order.
1308 The result is false, if either @var{TGT} or @var{PTR} is disassociated.
1311 @item @emph{Example}:
1313 program test_associated
1315 real, target :: tgt(2) = (/1., 2./)
1316 real, pointer :: ptr(:)
1318 if (associated(ptr) .eqv. .false.) call abort
1319 if (associated(ptr,tgt) .eqv. .false.) call abort
1320 end program test_associated
1323 @item @emph{See also}:
1330 @section @code{ATAN} --- Arctangent function
1333 @cindex trigonometric function, tangent, inverse
1334 @cindex tangent, inverse
1337 @item @emph{Description}:
1338 @code{ATAN(X)} computes the arctangent of @var{X}.
1340 @item @emph{Standard}:
1346 @item @emph{Syntax}:
1347 @code{RESULT = ATAN(X)}
1349 @item @emph{Arguments}:
1350 @multitable @columnfractions .15 .70
1351 @item @var{X} @tab The type shall be @code{REAL(*)}.
1354 @item @emph{Return value}:
1355 The return value is of type @code{REAL(*)} and it lies in the
1356 range @math{ - \pi / 2 \leq \atan (x) \leq \pi / 2}.
1358 @item @emph{Example}:
1361 real(8) :: x = 2.866_8
1363 end program test_atan
1366 @item @emph{Specific names}:
1367 @multitable @columnfractions .20 .20 .20 .25
1368 @item Name @tab Argument @tab Return type @tab Standard
1369 @item @code{DATAN(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab F77 and later
1372 @item @emph{See also}:
1373 Inverse function: @ref{TAN}
1380 @section @code{ATAN2} --- Arctangent function
1383 @cindex trigonometric function, tangent, inverse
1384 @cindex tangent, inverse
1387 @item @emph{Description}:
1388 @code{ATAN2(Y,X)} computes the arctangent of the complex number
1391 @item @emph{Standard}:
1397 @item @emph{Syntax}:
1398 @code{RESULT = ATAN2(Y,X)}
1400 @item @emph{Arguments}:
1401 @multitable @columnfractions .15 .70
1402 @item @var{Y} @tab The type shall be @code{REAL(*)}.
1403 @item @var{X} @tab The type and kind type parameter shall be the same as @var{Y}.
1404 If @var{Y} is zero, then @var{X} must be nonzero.
1407 @item @emph{Return value}:
1408 The return value has the same type and kind type parameter as @var{Y}.
1409 It is the principal value of the complex number @math{X + i Y}. If
1410 @var{X} is nonzero, then it lies in the range @math{-\pi \le \atan (x) \leq \pi}.
1411 The sign is positive if @var{Y} is positive. If @var{Y} is zero, then
1412 the return value is zero if @var{X} is positive and @math{\pi} if @var{X}
1413 is negative. Finally, if @var{X} is zero, then the magnitude of the result
1416 @item @emph{Example}:
1419 real(4) :: x = 1.e0_4, y = 0.5e0_4
1421 end program test_atan2
1424 @item @emph{Specific names}:
1425 @multitable @columnfractions .20 .20 .20 .25
1426 @item Name @tab Argument @tab Return type @tab Standard
1427 @item @code{DATAN2(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab F77 and later
1434 @section @code{ATANH} --- Hyperbolic arctangent function
1437 @cindex area hyperbolic tangent
1438 @cindex hyperbolic arctangent
1439 @cindex hyperbolic function, tangent, inverse
1440 @cindex tangent, hyperbolic, inverse
1443 @item @emph{Description}:
1444 @code{ATANH(X)} computes the hyperbolic arctangent of @var{X} (inverse
1447 @item @emph{Standard}:
1448 Fortran 2008 and later
1453 @item @emph{Syntax}:
1454 @code{RESULT = ATANH(X)}
1456 @item @emph{Arguments}:
1457 @multitable @columnfractions .15 .70
1458 @item @var{X} @tab The type shall be @code{REAL} or @code{COMPLEX}.
1461 @item @emph{Return value}:
1462 The return value has same type and kind as @var{X}.
1464 @item @emph{Example}:
1467 REAL, DIMENSION(3) :: x = (/ -1.0, 0.0, 1.0 /)
1468 WRITE (*,*) ATANH(x)
1472 @item @emph{Specific names}:
1473 @multitable @columnfractions .20 .20 .20 .25
1474 @item Name @tab Argument @tab Return type @tab Standard
1475 @item @code{DATANH(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU extension
1478 @item @emph{See also}:
1479 Inverse function: @ref{TANH}
1485 @section @code{BESSEL_J0} --- Bessel function of the first kind of order 0
1489 @cindex Bessel function, first kind
1492 @item @emph{Description}:
1493 @code{BESSEL_J0(X)} computes the Bessel function of the first kind of
1494 order 0 of @var{X}. This function is available under the name
1495 @code{BESJ0} as a GNU extension.
1497 @item @emph{Standard}:
1498 Fortran 2008 and later
1503 @item @emph{Syntax}:
1504 @code{RESULT = BESSEL_J0(X)}
1506 @item @emph{Arguments}:
1507 @multitable @columnfractions .15 .70
1508 @item @var{X} @tab The type shall be @code{REAL(*)}, and it shall be scalar.
1511 @item @emph{Return value}:
1512 The return value is of type @code{REAL(*)} and it lies in the
1513 range @math{ - 0.4027... \leq Bessel (0,x) \leq 1}.
1515 @item @emph{Example}:
1518 real(8) :: x = 0.0_8
1520 end program test_besj0
1523 @item @emph{Specific names}:
1524 @multitable @columnfractions .20 .20 .20 .25
1525 @item Name @tab Argument @tab Return type @tab Standard
1526 @item @code{DBESJ0(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU extension
1533 @section @code{BESEL_J1} --- Bessel function of the first kind of order 1
1537 @cindex Bessel function, first kind
1540 @item @emph{Description}:
1541 @code{BESSEL_J1(X)} computes the Bessel function of the first kind of
1542 order 1 of @var{X}. This function is available under the name
1543 @code{BESJ1} as a GNU extension.
1545 @item @emph{Standard}:
1551 @item @emph{Syntax}:
1552 @code{RESULT = BESSEL_J1(X)}
1554 @item @emph{Arguments}:
1555 @multitable @columnfractions .15 .70
1556 @item @var{X} @tab The type shall be @code{REAL(*)}, and it shall be scalar.
1559 @item @emph{Return value}:
1560 The return value is of type @code{REAL(*)} and it lies in the
1561 range @math{ - 0.5818... \leq Bessel (0,x) \leq 0.5818 }.
1563 @item @emph{Example}:
1566 real(8) :: x = 1.0_8
1568 end program test_besj1
1571 @item @emph{Specific names}:
1572 @multitable @columnfractions .20 .20 .20 .25
1573 @item Name @tab Argument @tab Return type @tab Standard
1574 @item @code{DBESJ1(X)}@tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU extension
1581 @section @code{BESSEL_JN} --- Bessel function of the first kind
1585 @cindex Bessel function, first kind
1588 @item @emph{Description}:
1589 @code{BESSEL_JN(N, X)} computes the Bessel function of the first kind of
1590 order @var{N} of @var{X}. This function is available under the name
1591 @code{BESJN} as a GNU extension.
1593 If both arguments are arrays, their ranks and shapes shall conform.
1595 @item @emph{Standard}:
1596 Fortran 2008 and later
1601 @item @emph{Syntax}:
1602 @code{RESULT = BESSEL_JN(N, X)}
1604 @item @emph{Arguments}:
1605 @multitable @columnfractions .15 .70
1606 @item @var{N} @tab Shall be a scalar or an array of type @code{INTEGER(*)}.
1607 @item @var{X} @tab Shall be a scalar or an array of type @code{REAL(*)}.
1610 @item @emph{Return value}:
1611 The return value is a scalar of type @code{REAL(*)}.
1613 @item @emph{Example}:
1616 real(8) :: x = 1.0_8
1618 end program test_besjn
1621 @item @emph{Specific names}:
1622 @multitable @columnfractions .20 .20 .20 .25
1623 @item Name @tab Argument @tab Return type @tab Standard
1624 @item @code{DBESJN(X)} @tab @code{INTEGER(*) N} @tab @code{REAL(8)} @tab GNU extension
1625 @item @tab @code{REAL(8) X} @tab @tab
1632 @section @code{BESSEL_Y0} --- Bessel function of the second kind of order 0
1636 @cindex Bessel function, second kind
1639 @item @emph{Description}:
1640 @code{BESSEL_Y0(X)} computes the Bessel function of the second kind of
1641 order 0 of @var{X}. This function is available under the name
1642 @code{BESY0} as a GNU extension.
1644 @item @emph{Standard}:
1645 Fortran 2008 and later
1650 @item @emph{Syntax}:
1651 @code{RESULT = BESSEL_Y0(X)}
1653 @item @emph{Arguments}:
1654 @multitable @columnfractions .15 .70
1655 @item @var{X} @tab The type shall be @code{REAL(*)}, and it shall be scalar.
1658 @item @emph{Return value}:
1659 The return value is a scalar of type @code{REAL(*)}.
1661 @item @emph{Example}:
1664 real(8) :: x = 0.0_8
1666 end program test_besy0
1669 @item @emph{Specific names}:
1670 @multitable @columnfractions .20 .20 .20 .25
1671 @item Name @tab Argument @tab Return type @tab Standard
1672 @item @code{DBESY0(X)}@tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU extension
1679 @section @code{BESSEL_Y1} --- Bessel function of the second kind of order 1
1683 @cindex Bessel function, second kind
1686 @item @emph{Description}:
1687 @code{BESSEL_Y1(X)} computes the Bessel function of the second kind of
1688 order 1 of @var{X}. This function is available under the name
1689 @code{BESY1} as a GNU extension.
1691 @item @emph{Standard}:
1692 Fortran 2008 and later
1697 @item @emph{Syntax}:
1698 @code{RESULT = BESSEL_Y1(X)}
1700 @item @emph{Arguments}:
1701 @multitable @columnfractions .15 .70
1702 @item @var{X} @tab The type shall be @code{REAL(*)}, and it shall be scalar.
1705 @item @emph{Return value}:
1706 The return value is a scalar of type @code{REAL(*)}.
1708 @item @emph{Example}:
1711 real(8) :: x = 1.0_8
1713 end program test_besy1
1716 @item @emph{Specific names}:
1717 @multitable @columnfractions .20 .20 .20 .25
1718 @item Name @tab Argument @tab Return type @tab Standard
1719 @item @code{DBESY1(X)}@tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU extension
1726 @section @code{BESSEL_YN} --- Bessel function of the second kind
1730 @cindex Bessel function, second kind
1733 @item @emph{Description}:
1734 @code{BESSEL_YN(N, X)} computes the Bessel function of the second kind of
1735 order @var{N} of @var{X}. This function is available under the name
1736 @code{BESYN} as a GNU extension.
1738 If both arguments are arrays, their ranks and shapes shall conform.
1740 @item @emph{Standard}:
1741 Fortran 2008 and later
1746 @item @emph{Syntax}:
1747 @code{RESULT = BESSEL_YN(N, X)}
1749 @item @emph{Arguments}:
1750 @multitable @columnfractions .15 .70
1751 @item @var{N} @tab Shall be a scalar or an array of type @code{INTEGER(*)}.
1752 @item @var{X} @tab Shall be a scalar or an array of type @code{REAL(*)}.
1755 @item @emph{Return value}:
1756 The return value is a scalar of type @code{REAL(*)}.
1758 @item @emph{Example}:
1761 real(8) :: x = 1.0_8
1763 end program test_besyn
1766 @item @emph{Specific names}:
1767 @multitable @columnfractions .20 .20 .20 .25
1768 @item Name @tab Argument @tab Return type @tab Standard
1769 @item @code{DBESYN(N,X)} @tab @code{INTEGER(*) N} @tab @code{REAL(8)} @tab GNU extension
1770 @item @tab @code{REAL(8) X} @tab @tab
1777 @section @code{BIT_SIZE} --- Bit size inquiry function
1779 @cindex bits, number of
1780 @cindex size of a variable, in bits
1783 @item @emph{Description}:
1784 @code{BIT_SIZE(I)} returns the number of bits (integer precision plus sign bit)
1785 represented by the type of @var{I}.
1787 @item @emph{Standard}:
1793 @item @emph{Syntax}:
1794 @code{RESULT = BIT_SIZE(I)}
1796 @item @emph{Arguments}:
1797 @multitable @columnfractions .15 .70
1798 @item @var{I} @tab The type shall be @code{INTEGER(*)}.
1801 @item @emph{Return value}:
1802 The return value is of type @code{INTEGER(*)}
1804 @item @emph{Example}:
1806 program test_bit_size
1811 end program test_bit_size
1818 @section @code{BTEST} --- Bit test function
1820 @cindex bits, testing
1823 @item @emph{Description}:
1824 @code{BTEST(I,POS)} returns logical @code{.TRUE.} if the bit at @var{POS}
1827 @item @emph{Standard}:
1833 @item @emph{Syntax}:
1834 @code{RESULT = BTEST(I, POS)}
1836 @item @emph{Arguments}:
1837 @multitable @columnfractions .15 .70
1838 @item @var{I} @tab The type shall be @code{INTEGER(*)}.
1839 @item @var{POS} @tab The type shall be @code{INTEGER(*)}.
1842 @item @emph{Return value}:
1843 The return value is of type @code{LOGICAL}
1845 @item @emph{Example}:
1848 integer :: i = 32768 + 1024 + 64
1852 bool = btest(i, pos)
1855 end program test_btest
1861 @section @code{C_ASSOCIATED} --- Status of a C pointer
1862 @fnindex C_ASSOCIATED
1863 @cindex association status, C pointer
1864 @cindex pointer, C association status
1867 @item @emph{Description}:
1868 @code{C_ASSOCIATED(c_prt1[, c_ptr2])} determines the status of the C pointer @var{c_ptr1}
1869 or if @var{c_ptr1} is associated with the target @var{c_ptr2}.
1871 @item @emph{Standard}:
1872 Fortran 2003 and later
1877 @item @emph{Syntax}:
1878 @code{RESULT = C_ASSOCIATED(c_prt1[, c_ptr2])}
1880 @item @emph{Arguments}:
1881 @multitable @columnfractions .15 .70
1882 @item @var{c_ptr1} @tab Scalar of the type @code{C_PTR} or @code{C_FUNPTR}.
1883 @item @var{c_ptr2} @tab (Optional) Scalar of the same type as @var{c_ptr1}.
1886 @item @emph{Return value}:
1887 The return value is of type @code{LOGICAL}; it is @code{.false.} if either
1888 @var{c_ptr1} is a C NULL pointer or if @var{c_ptr1} and @var{c_ptr2}
1889 point to different addresses.
1891 @item @emph{Example}:
1893 subroutine association_test(a,b)
1894 use iso_c_binding, only: c_associated, c_loc, c_ptr
1898 if(c_associated(b, c_loc(a))) &
1899 stop 'b and a do not point to same target'
1900 end subroutine association_test
1903 @item @emph{See also}:
1904 @ref{C_LOC}, @ref{C_FUNLOC}
1909 @section @code{C_FUNLOC} --- Obtain the C address of a procedure
1911 @cindex pointer, C address of procedures
1914 @item @emph{Description}:
1915 @code{C_FUNLOC(x)} determines the C address of the argument.
1917 @item @emph{Standard}:
1918 Fortran 2003 and later
1923 @item @emph{Syntax}:
1924 @code{RESULT = C_FUNLOC(x)}
1926 @item @emph{Arguments}:
1927 @multitable @columnfractions .15 .70
1928 @item @var{x} @tab Interoperable function or pointer to such function.
1931 @item @emph{Return value}:
1932 The return value is of type @code{C_FUNPTR} and contains the C address
1935 @item @emph{Example}:
1941 subroutine sub(a) bind(c)
1951 subroutine my_routine(p) bind(c,name='myC_func')
1953 type(c_funptr), intent(in) :: p
1956 call my_routine(c_funloc(sub))
1960 @item @emph{See also}:
1961 @ref{C_ASSOCIATED}, @ref{C_LOC}, @ref{C_F_POINTER}, @ref{C_F_PROCPOINTER}
1965 @node C_F_PROCPOINTER
1966 @section @code{C_F_PROCPOINTER} --- Convert C into Fortran procedure pointer
1967 @fnindex C_F_PROCPOINTER
1968 @cindex pointer, C address of pointers
1971 @item @emph{Description}:
1972 @code{C_F_PROCPOINTER(cptr, fptr)} Assign the target of the C function pointer
1973 @var{cptr} to the Fortran procedure pointer @var{fptr}.
1975 Note: Due to the currently lacking support of procedure pointers in GNU Fortran
1976 this function is not fully operable.
1978 @item @emph{Standard}:
1979 Fortran 2003 and later
1984 @item @emph{Syntax}:
1985 @code{CALL C_F_PROCPOINTER(cptr, fptr)}
1987 @item @emph{Arguments}:
1988 @multitable @columnfractions .15 .70
1989 @item @var{cptr} @tab scalar of the type @code{C_FUNPTR}. It is
1991 @item @var{fptr} @tab procedure pointer interoperable with @var{cptr}. It is
1995 @item @emph{Example}:
2003 real(c_float), intent(in) :: a
2004 real(c_float) :: func
2008 function getIterFunc() bind(c,name="getIterFunc")
2010 type(c_funptr) :: getIterFunc
2013 type(c_funptr) :: cfunptr
2014 procedure(func), pointer :: myFunc
2015 cfunptr = getIterFunc()
2016 call c_f_procpointer(cfunptr, myFunc)
2020 @item @emph{See also}:
2021 @ref{C_LOC}, @ref{C_F_POINTER}
2026 @section @code{C_F_POINTER} --- Convert C into Fortran pointer
2027 @fnindex C_F_POINTER
2028 @cindex pointer, convert C to Fortran
2031 @item @emph{Description}:
2032 @code{C_F_POINTER(cptr, fptr[, shape])} Assign the target the C pointer
2033 @var{cptr} to the Fortran pointer @var{fptr} and specify its
2036 @item @emph{Standard}:
2037 Fortran 2003 and later
2042 @item @emph{Syntax}:
2043 @code{CALL C_F_POINTER(cptr, fptr[, shape])}
2045 @item @emph{Arguments}:
2046 @multitable @columnfractions .15 .70
2047 @item @var{cptr} @tab scalar of the type @code{C_PTR}. It is
2049 @item @var{fptr} @tab pointer interoperable with @var{cptr}. It is
2051 @item @var{shape} @tab (Optional) Rank-one array of type @code{INTEGER}
2052 with @code{INTENT(IN)}. It shall be present
2053 if and only if @var{fptr} is an array. The size
2054 must be equal to the rank of @var{fptr}.
2057 @item @emph{Example}:
2063 subroutine my_routine(p) bind(c,name='myC_func')
2065 type(c_ptr), intent(out) :: p
2069 real,pointer :: a(:)
2070 call my_routine(cptr)
2071 call c_f_pointer(cptr, a, [12])
2075 @item @emph{See also}:
2076 @ref{C_LOC}, @ref{C_F_PROCPOINTER}
2081 @section @code{C_LOC} --- Obtain the C address of an object
2083 @cindex procedure pointer, convert C to Fortran
2086 @item @emph{Description}:
2087 @code{C_LOC(x)} determines the C address of the argument.
2089 @item @emph{Standard}:
2090 Fortran 2003 and later
2095 @item @emph{Syntax}:
2096 @code{RESULT = C_LOC(x)}
2098 @item @emph{Arguments}:
2099 @multitable @columnfractions .15 .70
2100 @item @var{x} @tab Associated scalar pointer or interoperable scalar
2101 or allocated allocatable variable with @code{TARGET}
2105 @item @emph{Return value}:
2106 The return value is of type @code{C_PTR} and contains the C address
2109 @item @emph{Example}:
2111 subroutine association_test(a,b)
2112 use iso_c_binding, only: c_associated, c_loc, c_ptr
2116 if(c_associated(b, c_loc(a))) &
2117 stop 'b and a do not point to same target'
2118 end subroutine association_test
2121 @item @emph{See also}:
2122 @ref{C_ASSOCIATED}, @ref{C_FUNLOC}, @ref{C_F_POINTER}, @ref{C_F_PROCPOINTER}
2127 @section @code{CEILING} --- Integer ceiling function
2130 @cindex rounding, ceiling
2133 @item @emph{Description}:
2134 @code{CEILING(X)} returns the least integer greater than or equal to @var{X}.
2136 @item @emph{Standard}:
2142 @item @emph{Syntax}:
2143 @code{RESULT = CEILING(X [, KIND])}
2145 @item @emph{Arguments}:
2146 @multitable @columnfractions .15 .70
2147 @item @var{X} @tab The type shall be @code{REAL(*)}.
2148 @item @var{KIND} @tab (Optional) An @code{INTEGER(*)} initialization
2149 expression indicating the kind parameter of
2153 @item @emph{Return value}:
2154 The return value is of type @code{INTEGER(KIND)}
2156 @item @emph{Example}:
2158 program test_ceiling
2161 print *, ceiling(x) ! returns 64
2162 print *, ceiling(y) ! returns -63
2163 end program test_ceiling
2166 @item @emph{See also}:
2167 @ref{FLOOR}, @ref{NINT}
2174 @section @code{CHAR} --- Character conversion function
2176 @cindex conversion, to character
2179 @item @emph{Description}:
2180 @code{CHAR(I [, KIND])} returns the character represented by the integer @var{I}.
2182 @item @emph{Standard}:
2188 @item @emph{Syntax}:
2189 @code{RESULT = CHAR(I [, KIND])}
2191 @item @emph{Arguments}:
2192 @multitable @columnfractions .15 .70
2193 @item @var{I} @tab The type shall be @code{INTEGER(*)}.
2194 @item @var{KIND} @tab (Optional) An @code{INTEGER(*)} initialization
2195 expression indicating the kind parameter of
2199 @item @emph{Return value}:
2200 The return value is of type @code{CHARACTER(1)}
2202 @item @emph{Example}:
2208 print *, i, c ! returns 'J'
2209 end program test_char
2213 See @ref{ICHAR} for a discussion of converting between numerical values
2214 and formatted string representations.
2216 @item @emph{See also}:
2217 @ref{ACHAR}, @ref{IACHAR}, @ref{ICHAR}
2224 @section @code{CHDIR} --- Change working directory
2226 @cindex system, working directory
2229 @item @emph{Description}:
2230 Change current working directory to a specified path.
2232 This intrinsic is provided in both subroutine and function forms; however,
2233 only one form can be used in any given program unit.
2235 @item @emph{Standard}:
2239 Subroutine, function
2241 @item @emph{Syntax}:
2242 @multitable @columnfractions .80
2243 @item @code{CALL CHDIR(NAME [, STATUS])}
2244 @item @code{STATUS = CHDIR(NAME)}
2247 @item @emph{Arguments}:
2248 @multitable @columnfractions .15 .70
2249 @item @var{NAME} @tab The type shall be @code{CHARACTER(*)} and shall
2250 specify a valid path within the file system.
2251 @item @var{STATUS} @tab (Optional) @code{INTEGER} status flag of the default
2252 kind. Returns 0 on success, and a system specific
2253 and nonzero error code otherwise.
2256 @item @emph{Example}:
2259 CHARACTER(len=255) :: path
2261 WRITE(*,*) TRIM(path)
2264 WRITE(*,*) TRIM(path)
2268 @item @emph{See also}:
2275 @section @code{CHMOD} --- Change access permissions of files
2277 @cindex file system, change access mode
2280 @item @emph{Description}:
2281 @code{CHMOD} changes the permissions of a file. This function invokes
2282 @code{/bin/chmod} and might therefore not work on all platforms.
2284 This intrinsic is provided in both subroutine and function forms; however,
2285 only one form can be used in any given program unit.
2287 @item @emph{Standard}:
2291 Subroutine, function
2293 @item @emph{Syntax}:
2294 @multitable @columnfractions .80
2295 @item @code{CALL CHMOD(NAME, MODE[, STATUS])}
2296 @item @code{STATUS = CHMOD(NAME, MODE)}
2299 @item @emph{Arguments}:
2300 @multitable @columnfractions .15 .70
2301 @item @var{NAME} @tab Scalar @code{CHARACTER} with the file name.
2302 Trailing blanks are ignored unless the character @code{achar(0)} is
2303 present, then all characters up to and excluding @code{achar(0)} are
2304 used as the file name.
2306 @item @var{MODE} @tab Scalar @code{CHARACTER} giving the file permission.
2307 @var{MODE} uses the same syntax as the @var{MODE} argument of
2310 @item @var{STATUS} @tab (optional) scalar @code{INTEGER}, which is
2311 @code{0} on success and nonzero otherwise.
2314 @item @emph{Return value}:
2315 In either syntax, @var{STATUS} is set to @code{0} on success and nonzero
2318 @item @emph{Example}:
2319 @code{CHMOD} as subroutine
2324 call chmod('test.dat','u+x',status)
2325 print *, 'Status: ', status
2326 end program chmod_test
2328 @code{CHMOD} as function:
2333 status = chmod('test.dat','u+x')
2334 print *, 'Status: ', status
2335 end program chmod_test
2343 @section @code{CMPLX} --- Complex conversion function
2345 @cindex complex numbers, conversion to
2346 @cindex conversion, to complex
2349 @item @emph{Description}:
2350 @code{CMPLX(X [, Y [, KIND]])} returns a complex number where @var{X} is converted to
2351 the real component. If @var{Y} is present it is converted to the imaginary
2352 component. If @var{Y} is not present then the imaginary component is set to
2353 0.0. If @var{X} is complex then @var{Y} must not be present.
2355 @item @emph{Standard}:
2361 @item @emph{Syntax}:
2362 @code{RESULT = CMPLX(X [, Y [, KIND]])}
2364 @item @emph{Arguments}:
2365 @multitable @columnfractions .15 .70
2366 @item @var{X} @tab The type may be @code{INTEGER(*)}, @code{REAL(*)},
2367 or @code{COMPLEX(*)}.
2368 @item @var{Y} @tab (Optional; only allowed if @var{X} is not
2369 @code{COMPLEX(*)}.) May be @code{INTEGER(*)}
2371 @item @var{KIND} @tab (Optional) An @code{INTEGER(*)} initialization
2372 expression indicating the kind parameter of
2376 @item @emph{Return value}:
2377 The return value is of @code{COMPLEX} type, with a kind equal to
2378 @var{KIND} if it is specified. If @var{KIND} is not specified, the
2379 result is of the default @code{COMPLEX} kind, regardless of the kinds of
2380 @var{X} and @var{Y}.
2382 @item @emph{Example}:
2389 print *, z, cmplx(x)
2390 end program test_cmplx
2393 @item @emph{See also}:
2399 @node COMMAND_ARGUMENT_COUNT
2400 @section @code{COMMAND_ARGUMENT_COUNT} --- Get number of command line arguments
2401 @fnindex COMMAND_ARGUMENT_COUNT
2402 @cindex command-line arguments
2403 @cindex command-line arguments, number of
2404 @cindex arguments, to program
2407 @item @emph{Description}:
2408 @code{COMMAND_ARGUMENT_COUNT()} returns the number of arguments passed on the
2409 command line when the containing program was invoked.
2411 @item @emph{Standard}:
2412 Fortran 2003 and later
2417 @item @emph{Syntax}:
2418 @code{RESULT = COMMAND_ARGUMENT_COUNT()}
2420 @item @emph{Arguments}:
2421 @multitable @columnfractions .15 .70
2425 @item @emph{Return value}:
2426 The return value is of type @code{INTEGER(4)}
2428 @item @emph{Example}:
2430 program test_command_argument_count
2432 count = command_argument_count()
2434 end program test_command_argument_count
2437 @item @emph{See also}:
2438 @ref{GET_COMMAND}, @ref{GET_COMMAND_ARGUMENT}
2444 @section @code{COMPLEX} --- Complex conversion function
2446 @cindex complex numbers, conversion to
2447 @cindex conversion, to complex
2450 @item @emph{Description}:
2451 @code{COMPLEX(X, Y)} returns a complex number where @var{X} is converted
2452 to the real component and @var{Y} is converted to the imaginary
2455 @item @emph{Standard}:
2461 @item @emph{Syntax}:
2462 @code{RESULT = COMPLEX(X, Y)}
2464 @item @emph{Arguments}:
2465 @multitable @columnfractions .15 .70
2466 @item @var{X} @tab The type may be @code{INTEGER(*)} or @code{REAL(*)}.
2467 @item @var{Y} @tab The type may be @code{INTEGER(*)} or @code{REAL(*)}.
2470 @item @emph{Return value}:
2471 If @var{X} and @var{Y} are both of @code{INTEGER} type, then the return
2472 value is of default @code{COMPLEX} type.
2474 If @var{X} and @var{Y} are of @code{REAL} type, or one is of @code{REAL}
2475 type and one is of @code{INTEGER} type, then the return value is of
2476 @code{COMPLEX} type with a kind equal to that of the @code{REAL}
2477 argument with the highest precision.
2479 @item @emph{Example}:
2481 program test_complex
2484 print *, complex(i, x)
2485 end program test_complex
2488 @item @emph{See also}:
2495 @section @code{CONJG} --- Complex conjugate function
2498 @cindex complex conjugate
2501 @item @emph{Description}:
2502 @code{CONJG(Z)} returns the conjugate of @var{Z}. If @var{Z} is @code{(x, y)}
2503 then the result is @code{(x, -y)}
2505 @item @emph{Standard}:
2506 F77 and later, has overloads that are GNU extensions
2511 @item @emph{Syntax}:
2514 @item @emph{Arguments}:
2515 @multitable @columnfractions .15 .70
2516 @item @var{Z} @tab The type shall be @code{COMPLEX(*)}.
2519 @item @emph{Return value}:
2520 The return value is of type @code{COMPLEX(*)}.
2522 @item @emph{Example}:
2525 complex :: z = (2.0, 3.0)
2526 complex(8) :: dz = (2.71_8, -3.14_8)
2531 end program test_conjg
2534 @item @emph{Specific names}:
2535 @multitable @columnfractions .20 .20 .20 .25
2536 @item Name @tab Argument @tab Return type @tab Standard
2537 @item @code{DCONJG(Z)} @tab @code{COMPLEX(8) Z} @tab @code{COMPLEX(8)} @tab GNU extension
2544 @section @code{COS} --- Cosine function
2550 @cindex trigonometric function, cosine
2554 @item @emph{Description}:
2555 @code{COS(X)} computes the cosine of @var{X}.
2557 @item @emph{Standard}:
2558 F77 and later, has overloads that are GNU extensions
2563 @item @emph{Syntax}:
2564 @code{RESULT = COS(X)}
2566 @item @emph{Arguments}:
2567 @multitable @columnfractions .15 .70
2568 @item @var{X} @tab The type shall be @code{REAL(*)} or
2572 @item @emph{Return value}:
2573 The return value is of type @code{REAL(*)} and it lies in the
2574 range @math{ -1 \leq \cos (x) \leq 1}. The kind type
2575 parameter is the same as @var{X}.
2577 @item @emph{Example}:
2582 end program test_cos
2585 @item @emph{Specific names}:
2586 @multitable @columnfractions .20 .20 .20 .25
2587 @item Name @tab Argument @tab Return type @tab Standard
2588 @item @code{DCOS(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab F77 and later
2589 @item @code{CCOS(X)} @tab @code{COMPLEX(4) X} @tab @code{COMPLEX(4)} @tab F77 and later
2590 @item @code{ZCOS(X)} @tab @code{COMPLEX(8) X} @tab @code{COMPLEX(8)} @tab GNU extension
2591 @item @code{CDCOS(X)} @tab @code{COMPLEX(8) X} @tab @code{COMPLEX(8)} @tab GNU extension
2594 @item @emph{See also}:
2595 Inverse function: @ref{ACOS}
2602 @section @code{COSH} --- Hyperbolic cosine function
2605 @cindex hyperbolic cosine
2606 @cindex hyperbolic function, cosine
2607 @cindex cosine, hyperbolic
2610 @item @emph{Description}:
2611 @code{COSH(X)} computes the hyperbolic cosine of @var{X}.
2613 @item @emph{Standard}:
2619 @item @emph{Syntax}:
2622 @item @emph{Arguments}:
2623 @multitable @columnfractions .15 .70
2624 @item @var{X} @tab The type shall be @code{REAL(*)}.
2627 @item @emph{Return value}:
2628 The return value is of type @code{REAL(*)} and it is positive
2629 (@math{ \cosh (x) \geq 0 }.
2631 @item @emph{Example}:
2634 real(8) :: x = 1.0_8
2636 end program test_cosh
2639 @item @emph{Specific names}:
2640 @multitable @columnfractions .20 .20 .20 .25
2641 @item Name @tab Argument @tab Return type @tab Standard
2642 @item @code{DCOSH(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab F77 and later
2645 @item @emph{See also}:
2646 Inverse function: @ref{ACOSH}
2653 @section @code{COUNT} --- Count function
2655 @cindex array, conditionally count elements
2656 @cindex array, element counting
2657 @cindex array, number of elements
2660 @item @emph{Description}:
2662 @code{COUNT(MASK [, DIM [, KIND]])} counts the number of @code{.TRUE.}
2663 elements of @var{MASK} along the dimension of @var{DIM}. If @var{DIM} is
2664 omitted it is taken to be @code{1}. @var{DIM} is a scaler of type
2665 @code{INTEGER} in the range of @math{1 /leq DIM /leq n)} where @math{n}
2666 is the rank of @var{MASK}.
2668 @item @emph{Standard}:
2672 Transformational function
2674 @item @emph{Syntax}:
2675 @code{RESULT = COUNT(MASK [, DIM [, KIND]])}
2677 @item @emph{Arguments}:
2678 @multitable @columnfractions .15 .70
2679 @item @var{MASK} @tab The type shall be @code{LOGICAL}.
2680 @item @var{DIM} @tab (Optional) The type shall be @code{INTEGER}.
2681 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
2682 expression indicating the kind parameter of
2686 @item @emph{Return value}:
2687 The return value is of type @code{INTEGER} and of kind @var{KIND}. If
2688 @var{KIND} is absent, the return value is of default integer kind.
2689 The result has a rank equal to that of @var{MASK}.
2691 @item @emph{Example}:
2694 integer, dimension(2,3) :: a, b
2695 logical, dimension(2,3) :: mask
2696 a = reshape( (/ 1, 2, 3, 4, 5, 6 /), (/ 2, 3 /))
2697 b = reshape( (/ 0, 7, 3, 4, 5, 8 /), (/ 2, 3 /))
2698 print '(3i3)', a(1,:)
2699 print '(3i3)', a(2,:)
2701 print '(3i3)', b(1,:)
2702 print '(3i3)', b(2,:)
2705 print '(3l3)', mask(1,:)
2706 print '(3l3)', mask(2,:)
2708 print '(3i3)', count(mask)
2710 print '(3i3)', count(mask, 1)
2712 print '(3i3)', count(mask, 2)
2713 end program test_count
2720 @section @code{CPU_TIME} --- CPU elapsed time in seconds
2722 @cindex time, elapsed
2725 @item @emph{Description}:
2726 Returns a @code{REAL(*)} value representing the elapsed CPU time in
2727 seconds. This is useful for testing segments of code to determine
2730 If a time source is available, time will be reported with microsecond
2731 resolution. If no time source is available, @var{TIME} is set to
2734 Note that @var{TIME} may contain a, system dependent, arbitrary offset
2735 and may not start with @code{0.0}. For @code{CPU_TIME}, the absolute
2736 value is meaningless, only differences between subsequent calls to
2737 this subroutine, as shown in the example below, should be used.
2740 @item @emph{Standard}:
2746 @item @emph{Syntax}:
2747 @code{CALL CPU_TIME(TIME)}
2749 @item @emph{Arguments}:
2750 @multitable @columnfractions .15 .70
2751 @item @var{TIME} @tab The type shall be @code{REAL(*)} with @code{INTENT(OUT)}.
2754 @item @emph{Return value}:
2757 @item @emph{Example}:
2759 program test_cpu_time
2760 real :: start, finish
2761 call cpu_time(start)
2762 ! put code to test here
2763 call cpu_time(finish)
2764 print '("Time = ",f6.3," seconds.")',finish-start
2765 end program test_cpu_time
2768 @item @emph{See also}:
2769 @ref{SYSTEM_CLOCK}, @ref{DATE_AND_TIME}
2775 @section @code{CSHIFT} --- Circular shift elements of an array
2777 @cindex array, shift circularly
2778 @cindex array, permutation
2779 @cindex array, rotate
2782 @item @emph{Description}:
2783 @code{CSHIFT(ARRAY, SHIFT [, DIM])} performs a circular shift on elements of
2784 @var{ARRAY} along the dimension of @var{DIM}. If @var{DIM} is omitted it is
2785 taken to be @code{1}. @var{DIM} is a scaler of type @code{INTEGER} in the
2786 range of @math{1 /leq DIM /leq n)} where @math{n} is the rank of @var{ARRAY}.
2787 If the rank of @var{ARRAY} is one, then all elements of @var{ARRAY} are shifted
2788 by @var{SHIFT} places. If rank is greater than one, then all complete rank one
2789 sections of @var{ARRAY} along the given dimension are shifted. Elements
2790 shifted out one end of each rank one section are shifted back in the other end.
2792 @item @emph{Standard}:
2796 Transformational function
2798 @item @emph{Syntax}:
2799 @code{RESULT = CSHIFT(ARRAY, SHIFT [, DIM])}
2801 @item @emph{Arguments}:
2802 @multitable @columnfractions .15 .70
2803 @item @var{ARRAY} @tab Shall be an array of any type.
2804 @item @var{SHIFT} @tab The type shall be @code{INTEGER}.
2805 @item @var{DIM} @tab The type shall be @code{INTEGER}.
2808 @item @emph{Return value}:
2809 Returns an array of same type and rank as the @var{ARRAY} argument.
2811 @item @emph{Example}:
2814 integer, dimension(3,3) :: a
2815 a = reshape( (/ 1, 2, 3, 4, 5, 6, 7, 8, 9 /), (/ 3, 3 /))
2816 print '(3i3)', a(1,:)
2817 print '(3i3)', a(2,:)
2818 print '(3i3)', a(3,:)
2819 a = cshift(a, SHIFT=(/1, 2, -1/), DIM=2)
2821 print '(3i3)', a(1,:)
2822 print '(3i3)', a(2,:)
2823 print '(3i3)', a(3,:)
2824 end program test_cshift
2831 @section @code{CTIME} --- Convert a time into a string
2833 @cindex time, conversion to string
2834 @cindex conversion, to string
2837 @item @emph{Description}:
2838 @code{CTIME} converts a system time value, such as returned by
2839 @code{TIME8()}, to a string of the form @samp{Sat Aug 19 18:13:14 1995}.
2841 This intrinsic is provided in both subroutine and function forms; however,
2842 only one form can be used in any given program unit.
2844 @item @emph{Standard}:
2848 Subroutine, function
2850 @item @emph{Syntax}:
2851 @multitable @columnfractions .80
2852 @item @code{CALL CTIME(TIME, RESULT)}.
2853 @item @code{RESULT = CTIME(TIME)}, (not recommended).
2856 @item @emph{Arguments}:
2857 @multitable @columnfractions .15 .70
2858 @item @var{TIME} @tab The type shall be of type @code{INTEGER(KIND=8)}.
2859 @item @var{RESULT} @tab The type shall be of type @code{CHARACTER}.
2862 @item @emph{Return value}:
2863 The converted date and time as a string.
2865 @item @emph{Example}:
2869 character(len=30) :: date
2872 ! Do something, main part of the program
2875 print *, 'Program was started on ', date
2876 end program test_ctime
2879 @item @emph{See Also}:
2880 @ref{GMTIME}, @ref{LTIME}, @ref{TIME}, @ref{TIME8}
2886 @section @code{DATE_AND_TIME} --- Date and time subroutine
2887 @fnindex DATE_AND_TIME
2888 @cindex date, current
2889 @cindex current date
2890 @cindex time, current
2891 @cindex current time
2894 @item @emph{Description}:
2895 @code{DATE_AND_TIME(DATE, TIME, ZONE, VALUES)} gets the corresponding date and
2896 time information from the real-time system clock. @var{DATE} is
2897 @code{INTENT(OUT)} and has form ccyymmdd. @var{TIME} is @code{INTENT(OUT)} and
2898 has form hhmmss.sss. @var{ZONE} is @code{INTENT(OUT)} and has form (+-)hhmm,
2899 representing the difference with respect to Coordinated Universal Time (UTC).
2900 Unavailable time and date parameters return blanks.
2902 @var{VALUES} is @code{INTENT(OUT)} and provides the following:
2904 @multitable @columnfractions .15 .30 .40
2905 @item @tab @code{VALUE(1)}: @tab The year
2906 @item @tab @code{VALUE(2)}: @tab The month
2907 @item @tab @code{VALUE(3)}: @tab The day of the month
2908 @item @tab @code{VALUE(4)}: @tab Time difference with UTC in minutes
2909 @item @tab @code{VALUE(5)}: @tab The hour of the day
2910 @item @tab @code{VALUE(6)}: @tab The minutes of the hour
2911 @item @tab @code{VALUE(7)}: @tab The seconds of the minute
2912 @item @tab @code{VALUE(8)}: @tab The milliseconds of the second
2915 @item @emph{Standard}:
2921 @item @emph{Syntax}:
2922 @code{CALL DATE_AND_TIME([DATE, TIME, ZONE, VALUES])}
2924 @item @emph{Arguments}:
2925 @multitable @columnfractions .15 .70
2926 @item @var{DATE} @tab (Optional) The type shall be @code{CHARACTER(8)} or larger.
2927 @item @var{TIME} @tab (Optional) The type shall be @code{CHARACTER(10)} or larger.
2928 @item @var{ZONE} @tab (Optional) The type shall be @code{CHARACTER(5)} or larger.
2929 @item @var{VALUES}@tab (Optional) The type shall be @code{INTEGER(8)}.
2932 @item @emph{Return value}:
2935 @item @emph{Example}:
2937 program test_time_and_date
2938 character(8) :: date
2939 character(10) :: time
2940 character(5) :: zone
2941 integer,dimension(8) :: values
2942 ! using keyword arguments
2943 call date_and_time(date,time,zone,values)
2944 call date_and_time(DATE=date,ZONE=zone)
2945 call date_and_time(TIME=time)
2946 call date_and_time(VALUES=values)
2947 print '(a,2x,a,2x,a)', date, time, zone
2948 print '(8i5))', values
2949 end program test_time_and_date
2952 @item @emph{See also}:
2953 @ref{CPU_TIME}, @ref{SYSTEM_CLOCK}
2959 @section @code{DBLE} --- Double conversion function
2961 @cindex conversion, to real
2964 @item @emph{Description}:
2965 @code{DBLE(X)} Converts @var{X} to double precision real type.
2967 @item @emph{Standard}:
2973 @item @emph{Syntax}:
2974 @code{RESULT = DBLE(X)}
2976 @item @emph{Arguments}:
2977 @multitable @columnfractions .15 .70
2978 @item @var{X} @tab The type shall be @code{INTEGER(*)}, @code{REAL(*)},
2979 or @code{COMPLEX(*)}.
2982 @item @emph{Return value}:
2983 The return value is of type double precision real.
2985 @item @emph{Example}:
2990 complex :: z = (2.3,1.14)
2991 print *, dble(x), dble(i), dble(z)
2992 end program test_dble
2995 @item @emph{See also}:
2996 @ref{DFLOAT}, @ref{FLOAT}, @ref{REAL}
3002 @section @code{DCMPLX} --- Double complex conversion function
3004 @cindex complex numbers, conversion to
3005 @cindex conversion, to complex
3008 @item @emph{Description}:
3009 @code{DCMPLX(X [,Y])} returns a double complex number where @var{X} is
3010 converted to the real component. If @var{Y} is present it is converted to the
3011 imaginary component. If @var{Y} is not present then the imaginary component is
3012 set to 0.0. If @var{X} is complex then @var{Y} must not be present.
3014 @item @emph{Standard}:
3020 @item @emph{Syntax}:
3021 @code{RESULT = DCMPLX(X [, Y])}
3023 @item @emph{Arguments}:
3024 @multitable @columnfractions .15 .70
3025 @item @var{X} @tab The type may be @code{INTEGER(*)}, @code{REAL(*)},
3026 or @code{COMPLEX(*)}.
3027 @item @var{Y} @tab (Optional if @var{X} is not @code{COMPLEX(*)}.) May be
3028 @code{INTEGER(*)} or @code{REAL(*)}.
3031 @item @emph{Return value}:
3032 The return value is of type @code{COMPLEX(8)}
3034 @item @emph{Example}:
3044 print *, dcmplx(x,i)
3045 end program test_dcmplx
3052 @section @code{DFLOAT} --- Double conversion function
3054 @cindex conversion, to real
3057 @item @emph{Description}:
3058 @code{DFLOAT(X)} Converts @var{X} to double precision real type.
3060 @item @emph{Standard}:
3066 @item @emph{Syntax}:
3067 @code{RESULT = DFLOAT(X)}
3069 @item @emph{Arguments}:
3070 @multitable @columnfractions .15 .70
3071 @item @var{X} @tab The type shall be @code{INTEGER(*)}.
3074 @item @emph{Return value}:
3075 The return value is of type double precision real.
3077 @item @emph{Example}:
3082 end program test_dfloat
3085 @item @emph{See also}:
3086 @ref{DBLE}, @ref{FLOAT}, @ref{REAL}
3092 @section @code{DIGITS} --- Significant digits function
3094 @cindex model representation, significant digits
3097 @item @emph{Description}:
3098 @code{DIGITS(X)} returns the number of significant digits of the internal model
3099 representation of @var{X}. For example, on a system using a 32-bit
3100 floating point representation, a default real number would likely return 24.
3102 @item @emph{Standard}:
3108 @item @emph{Syntax}:
3109 @code{RESULT = DIGITS(X)}
3111 @item @emph{Arguments}:
3112 @multitable @columnfractions .15 .70
3113 @item @var{X} @tab The type may be @code{INTEGER(*)} or @code{REAL(*)}.
3116 @item @emph{Return value}:
3117 The return value is of type @code{INTEGER}.
3119 @item @emph{Example}:
3122 integer :: i = 12345
3128 end program test_digits
3135 @section @code{DIM} --- Positive difference
3139 @cindex positive difference
3142 @item @emph{Description}:
3143 @code{DIM(X,Y)} returns the difference @code{X-Y} if the result is positive;
3144 otherwise returns zero.
3146 @item @emph{Standard}:
3152 @item @emph{Syntax}:
3153 @code{RESULT = DIM(X, Y)}
3155 @item @emph{Arguments}:
3156 @multitable @columnfractions .15 .70
3157 @item @var{X} @tab The type shall be @code{INTEGER(*)} or @code{REAL(*)}
3158 @item @var{Y} @tab The type shall be the same type and kind as @var{X}.
3161 @item @emph{Return value}:
3162 The return value is of type @code{INTEGER(*)} or @code{REAL(*)}.
3164 @item @emph{Example}:
3170 x = dim(4.345_8, 2.111_8)
3173 end program test_dim
3176 @item @emph{Specific names}:
3177 @multitable @columnfractions .20 .20 .20 .25
3178 @item Name @tab Argument @tab Return type @tab Standard
3179 @item @code{IDIM(X,Y)} @tab @code{INTEGER(4) X,Y} @tab @code{INTEGER(4)} @tab F77 and later
3180 @item @code{DDIM(X,Y)} @tab @code{REAL(8) X,Y} @tab @code{REAL(8)} @tab F77 and later
3187 @section @code{DOT_PRODUCT} --- Dot product function
3188 @fnindex DOT_PRODUCT
3190 @cindex vector product
3191 @cindex product, vector
3194 @item @emph{Description}:
3195 @code{DOT_PRODUCT(X,Y)} computes the dot product multiplication of two vectors
3196 @var{X} and @var{Y}. The two vectors may be either numeric or logical
3197 and must be arrays of rank one and of equal size. If the vectors are
3198 @code{INTEGER(*)} or @code{REAL(*)}, the result is @code{SUM(X*Y)}. If the
3199 vectors are @code{COMPLEX(*)}, the result is @code{SUM(CONJG(X)*Y)}. If the
3200 vectors are @code{LOGICAL}, the result is @code{ANY(X.AND.Y)}.
3202 @item @emph{Standard}:
3206 Transformational function
3208 @item @emph{Syntax}:
3209 @code{RESULT = DOT_PRODUCT(X, Y)}
3211 @item @emph{Arguments}:
3212 @multitable @columnfractions .15 .70
3213 @item @var{X} @tab The type shall be numeric or @code{LOGICAL}, rank 1.
3214 @item @var{Y} @tab The type shall be numeric or @code{LOGICAL}, rank 1.
3217 @item @emph{Return value}:
3218 If the arguments are numeric, the return value is a scaler of numeric type,
3219 @code{INTEGER(*)}, @code{REAL(*)}, or @code{COMPLEX(*)}. If the arguments are
3220 @code{LOGICAL}, the return value is @code{.TRUE.} or @code{.FALSE.}.
3222 @item @emph{Example}:
3224 program test_dot_prod
3225 integer, dimension(3) :: a, b
3232 print *, dot_product(a,b)
3233 end program test_dot_prod
3240 @section @code{DPROD} --- Double product function
3242 @cindex product, double-precision
3245 @item @emph{Description}:
3246 @code{DPROD(X,Y)} returns the product @code{X*Y}.
3248 @item @emph{Standard}:
3254 @item @emph{Syntax}:
3255 @code{RESULT = DPROD(X, Y)}
3257 @item @emph{Arguments}:
3258 @multitable @columnfractions .15 .70
3259 @item @var{X} @tab The type shall be @code{REAL}.
3260 @item @var{Y} @tab The type shall be @code{REAL}.
3263 @item @emph{Return value}:
3264 The return value is of type @code{REAL(8)}.
3266 @item @emph{Example}:
3274 end program test_dprod
3281 @section @code{DREAL} --- Double real part function
3283 @cindex complex numbers, real part
3286 @item @emph{Description}:
3287 @code{DREAL(Z)} returns the real part of complex variable @var{Z}.
3289 @item @emph{Standard}:
3295 @item @emph{Syntax}:
3296 @code{RESULT = DREAL(Z)}
3298 @item @emph{Arguments}:
3299 @multitable @columnfractions .15 .70
3300 @item @var{Z} @tab The type shall be @code{COMPLEX(8)}.
3303 @item @emph{Return value}:
3304 The return value is of type @code{REAL(8)}.
3306 @item @emph{Example}:
3309 complex(8) :: z = (1.3_8,7.2_8)
3311 end program test_dreal
3314 @item @emph{See also}:
3322 @section @code{DTIME} --- Execution time subroutine (or function)
3324 @cindex time, elapsed
3325 @cindex elapsed time
3328 @item @emph{Description}:
3329 @code{DTIME(TARRAY, RESULT)} initially returns the number of seconds of runtime
3330 since the start of the process's execution in @var{RESULT}. @var{TARRAY}
3331 returns the user and system components of this time in @code{TARRAY(1)} and
3332 @code{TARRAY(2)} respectively. @var{RESULT} is equal to @code{TARRAY(1) +
3335 Subsequent invocations of @code{DTIME} return values accumulated since the
3336 previous invocation.
3338 On some systems, the underlying timings are represented using types with
3339 sufficiently small limits that overflows (wrap around) are possible, such as
3340 32-bit types. Therefore, the values returned by this intrinsic might be, or
3341 become, negative, or numerically less than previous values, during a single
3342 run of the compiled program.
3344 Please note, that this implementation is thread safe if used within OpenMP
3345 directives, i.e., its state will be consistent while called from multiple
3346 threads. However, if @code{DTIME} is called from multiple threads, the result
3347 is still the time since the last invocation. This may not give the intended
3348 results. If possible, use @code{CPU_TIME} instead.
3350 This intrinsic is provided in both subroutine and function forms; however,
3351 only one form can be used in any given program unit.
3353 @var{TARRAY} and @var{RESULT} are @code{INTENT(OUT)} and provide the following:
3355 @multitable @columnfractions .15 .30 .40
3356 @item @tab @code{TARRAY(1)}: @tab User time in seconds.
3357 @item @tab @code{TARRAY(2)}: @tab System time in seconds.
3358 @item @tab @code{RESULT}: @tab Run time since start in seconds.
3361 @item @emph{Standard}:
3365 Subroutine, function
3367 @item @emph{Syntax}:
3368 @multitable @columnfractions .80
3369 @item @code{CALL DTIME(TARRAY, RESULT)}.
3370 @item @code{RESULT = DTIME(TARRAY)}, (not recommended).
3373 @item @emph{Arguments}:
3374 @multitable @columnfractions .15 .70
3375 @item @var{TARRAY}@tab The type shall be @code{REAL, DIMENSION(2)}.
3376 @item @var{RESULT}@tab The type shall be @code{REAL}.
3379 @item @emph{Return value}:
3380 Elapsed time in seconds since the last invocation or since the start of program
3381 execution if not called before.
3383 @item @emph{Example}:
3387 real, dimension(2) :: tarray
3389 call dtime(tarray, result)
3393 do i=1,100000000 ! Just a delay
3396 call dtime(tarray, result)
3400 end program test_dtime
3403 @item @emph{See also}:
3411 @section @code{EOSHIFT} --- End-off shift elements of an array
3413 @cindex array, shift
3416 @item @emph{Description}:
3417 @code{EOSHIFT(ARRAY, SHIFT[,BOUNDARY, DIM])} performs an end-off shift on
3418 elements of @var{ARRAY} along the dimension of @var{DIM}. If @var{DIM} is
3419 omitted it is taken to be @code{1}. @var{DIM} is a scaler of type
3420 @code{INTEGER} in the range of @math{1 /leq DIM /leq n)} where @math{n} is the
3421 rank of @var{ARRAY}. If the rank of @var{ARRAY} is one, then all elements of
3422 @var{ARRAY} are shifted by @var{SHIFT} places. If rank is greater than one,
3423 then all complete rank one sections of @var{ARRAY} along the given dimension are
3424 shifted. Elements shifted out one end of each rank one section are dropped. If
3425 @var{BOUNDARY} is present then the corresponding value of from @var{BOUNDARY}
3426 is copied back in the other end. If @var{BOUNDARY} is not present then the
3427 following are copied in depending on the type of @var{ARRAY}.
3429 @multitable @columnfractions .15 .80
3430 @item @emph{Array Type} @tab @emph{Boundary Value}
3431 @item Numeric @tab 0 of the type and kind of @var{ARRAY}.
3432 @item Logical @tab @code{.FALSE.}.
3433 @item Character(@var{len}) @tab @var{len} blanks.
3436 @item @emph{Standard}:
3440 Transformational function
3442 @item @emph{Syntax}:
3443 @code{RESULT = EOSHIFT(ARRAY, SHIFT [, BOUNDARY, DIM])}
3445 @item @emph{Arguments}:
3446 @multitable @columnfractions .15 .70
3447 @item @var{ARRAY} @tab May be any type, not scaler.
3448 @item @var{SHIFT} @tab The type shall be @code{INTEGER}.
3449 @item @var{BOUNDARY} @tab Same type as @var{ARRAY}.
3450 @item @var{DIM} @tab The type shall be @code{INTEGER}.
3453 @item @emph{Return value}:
3454 Returns an array of same type and rank as the @var{ARRAY} argument.
3456 @item @emph{Example}:
3458 program test_eoshift
3459 integer, dimension(3,3) :: a
3460 a = reshape( (/ 1, 2, 3, 4, 5, 6, 7, 8, 9 /), (/ 3, 3 /))
3461 print '(3i3)', a(1,:)
3462 print '(3i3)', a(2,:)
3463 print '(3i3)', a(3,:)
3464 a = EOSHIFT(a, SHIFT=(/1, 2, 1/), BOUNDARY=-5, DIM=2)
3466 print '(3i3)', a(1,:)
3467 print '(3i3)', a(2,:)
3468 print '(3i3)', a(3,:)
3469 end program test_eoshift
3476 @section @code{EPSILON} --- Epsilon function
3478 @cindex model representation, epsilon
3481 @item @emph{Description}:
3482 @code{EPSILON(X)} returns a nearly negligible number relative to @code{1}.
3484 @item @emph{Standard}:
3490 @item @emph{Syntax}:
3491 @code{RESULT = EPSILON(X)}
3493 @item @emph{Arguments}:
3494 @multitable @columnfractions .15 .70
3495 @item @var{X} @tab The type shall be @code{REAL(*)}.
3498 @item @emph{Return value}:
3499 The return value is of same type as the argument.
3501 @item @emph{Example}:
3503 program test_epsilon
3508 end program test_epsilon
3515 @section @code{ERF} --- Error function
3517 @cindex error function
3520 @item @emph{Description}:
3521 @code{ERF(X)} computes the error function of @var{X}.
3523 @item @emph{Standard}:
3524 Fortran 2008 and later
3529 @item @emph{Syntax}:
3530 @code{RESULT = ERF(X)}
3532 @item @emph{Arguments}:
3533 @multitable @columnfractions .15 .70
3534 @item @var{X} @tab The type shall be @code{REAL}.
3537 @item @emph{Return value}:
3538 The return value is of type @code{REAL}, of the same kind as
3539 @var{X} and lies in the range @math{-1 \leq erf (x) \leq 1 }.
3541 @item @emph{Example}:
3544 real(8) :: x = 0.17_8
3546 end program test_erf
3549 @item @emph{Specific names}:
3550 @multitable @columnfractions .20 .20 .20 .25
3551 @item Name @tab Argument @tab Return type @tab Standard
3552 @item @code{DERF(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU extension
3559 @section @code{ERFC} --- Error function
3561 @cindex error function, complementary
3564 @item @emph{Description}:
3565 @code{ERFC(X)} computes the complementary error function of @var{X}.
3567 @item @emph{Standard}:
3568 Fortran 2008 and later
3573 @item @emph{Syntax}:
3574 @code{RESULT = ERFC(X)}
3576 @item @emph{Arguments}:
3577 @multitable @columnfractions .15 .70
3578 @item @var{X} @tab The type shall be @code{REAL}.
3581 @item @emph{Return value}:
3582 The return value is of type @code{REAL} and of the same kind as @var{X}.
3583 It lies in the range @math{ 0 \leq erfc (x) \leq 2 }.
3585 @item @emph{Example}:
3588 real(8) :: x = 0.17_8
3590 end program test_erfc
3593 @item @emph{Specific names}:
3594 @multitable @columnfractions .20 .20 .20 .25
3595 @item Name @tab Argument @tab Return type @tab Standard
3596 @item @code{DERFC(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU extension
3603 @section @code{ERFC_SCALED} --- Error function
3604 @fnindex ERFC_SCALED
3605 @cindex error function, complementary, exponentially-scaled
3608 @item @emph{Description}:
3609 @code{ERFC_SCALED(X)} computes the exponentially-scaled complementary
3610 error function of @var{X}.
3612 @item @emph{Standard}:
3613 Fortran 2008 and later
3618 @item @emph{Syntax}:
3619 @code{RESULT = ERFC_SCALED(X)}
3621 @item @emph{Arguments}:
3622 @multitable @columnfractions .15 .70
3623 @item @var{X} @tab The type shall be @code{REAL}.
3626 @item @emph{Return value}:
3627 The return value is of type @code{REAL} and of the same kind as @var{X}.
3629 @item @emph{Example}:
3631 program test_erfc_scaled
3632 real(8) :: x = 0.17_8
3634 end program test_erfc_scaled
3641 @section @code{ETIME} --- Execution time subroutine (or function)
3643 @cindex time, elapsed
3646 @item @emph{Description}:
3647 @code{ETIME(TARRAY, RESULT)} returns the number of seconds of runtime
3648 since the start of the process's execution in @var{RESULT}. @var{TARRAY}
3649 returns the user and system components of this time in @code{TARRAY(1)} and
3650 @code{TARRAY(2)} respectively. @var{RESULT} is equal to @code{TARRAY(1) + TARRAY(2)}.
3652 On some systems, the underlying timings are represented using types with
3653 sufficiently small limits that overflows (wrap around) are possible, such as
3654 32-bit types. Therefore, the values returned by this intrinsic might be, or
3655 become, negative, or numerically less than previous values, during a single
3656 run of the compiled program.
3658 This intrinsic is provided in both subroutine and function forms; however,
3659 only one form can be used in any given program unit.
3661 @var{TARRAY} and @var{RESULT} are @code{INTENT(OUT)} and provide the following:
3663 @multitable @columnfractions .15 .30 .60
3664 @item @tab @code{TARRAY(1)}: @tab User time in seconds.
3665 @item @tab @code{TARRAY(2)}: @tab System time in seconds.
3666 @item @tab @code{RESULT}: @tab Run time since start in seconds.
3669 @item @emph{Standard}:
3673 Subroutine, function
3675 @item @emph{Syntax}:
3676 @multitable @columnfractions .80
3677 @item @code{CALL ETIME(TARRAY, RESULT)}.
3678 @item @code{RESULT = ETIME(TARRAY)}, (not recommended).
3681 @item @emph{Arguments}:
3682 @multitable @columnfractions .15 .70
3683 @item @var{TARRAY}@tab The type shall be @code{REAL, DIMENSION(2)}.
3684 @item @var{RESULT}@tab The type shall be @code{REAL}.
3687 @item @emph{Return value}:
3688 Elapsed time in seconds since the start of program execution.
3690 @item @emph{Example}:
3694 real, dimension(2) :: tarray
3696 call ETIME(tarray, result)
3700 do i=1,100000000 ! Just a delay
3703 call ETIME(tarray, result)
3707 end program test_etime
3710 @item @emph{See also}:
3718 @section @code{EXIT} --- Exit the program with status.
3720 @cindex program termination
3721 @cindex terminate program
3724 @item @emph{Description}:
3725 @code{EXIT} causes immediate termination of the program with status. If status
3726 is omitted it returns the canonical @emph{success} for the system. All Fortran
3727 I/O units are closed.
3729 @item @emph{Standard}:
3735 @item @emph{Syntax}:
3736 @code{CALL EXIT([STATUS])}
3738 @item @emph{Arguments}:
3739 @multitable @columnfractions .15 .70
3740 @item @var{STATUS} @tab Shall be an @code{INTEGER} of the default kind.
3743 @item @emph{Return value}:
3744 @code{STATUS} is passed to the parent process on exit.
3746 @item @emph{Example}:
3749 integer :: STATUS = 0
3750 print *, 'This program is going to exit.'
3752 end program test_exit
3755 @item @emph{See also}:
3756 @ref{ABORT}, @ref{KILL}
3762 @section @code{EXP} --- Exponential function
3768 @cindex exponential function
3769 @cindex logarithmic function, inverse
3772 @item @emph{Description}:
3773 @code{EXP(X)} computes the base @math{e} exponential of @var{X}.
3775 @item @emph{Standard}:
3776 F77 and later, has overloads that are GNU extensions
3781 @item @emph{Syntax}:
3782 @code{RESULT = EXP(X)}
3784 @item @emph{Arguments}:
3785 @multitable @columnfractions .15 .70
3786 @item @var{X} @tab The type shall be @code{REAL(*)} or
3790 @item @emph{Return value}:
3791 The return value has same type and kind as @var{X}.
3793 @item @emph{Example}:
3798 end program test_exp
3801 @item @emph{Specific names}:
3802 @multitable @columnfractions .20 .20 .20 .25
3803 @item Name @tab Argument @tab Return type @tab Standard
3804 @item @code{DEXP(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab F77 and later
3805 @item @code{CEXP(X)} @tab @code{COMPLEX(4) X} @tab @code{COMPLEX(4)} @tab F77 and later
3806 @item @code{ZEXP(X)} @tab @code{COMPLEX(8) X} @tab @code{COMPLEX(8)} @tab GNU extension
3807 @item @code{CDEXP(X)} @tab @code{COMPLEX(8) X} @tab @code{COMPLEX(8)} @tab GNU extension
3814 @section @code{EXPONENT} --- Exponent function
3816 @cindex real number, exponent
3817 @cindex floating point, exponent
3820 @item @emph{Description}:
3821 @code{EXPONENT(X)} returns the value of the exponent part of @var{X}. If @var{X}
3822 is zero the value returned is zero.
3824 @item @emph{Standard}:
3830 @item @emph{Syntax}:
3831 @code{RESULT = EXPONENT(X)}
3833 @item @emph{Arguments}:
3834 @multitable @columnfractions .15 .70
3835 @item @var{X} @tab The type shall be @code{REAL(*)}.
3838 @item @emph{Return value}:
3839 The return value is of type default @code{INTEGER}.
3841 @item @emph{Example}:
3843 program test_exponent
3848 print *, exponent(0.0)
3849 end program test_exponent
3856 @section @code{FDATE} --- Get the current time as a string
3858 @cindex time, current
3859 @cindex current time
3860 @cindex date, current
3861 @cindex current date
3864 @item @emph{Description}:
3865 @code{FDATE(DATE)} returns the current date (using the same format as
3866 @code{CTIME}) in @var{DATE}. It is equivalent to @code{CALL CTIME(DATE,
3869 This intrinsic is provided in both subroutine and function forms; however,
3870 only one form can be used in any given program unit.
3872 @var{DATE} is an @code{INTENT(OUT)} @code{CHARACTER} variable.
3874 @item @emph{Standard}:
3878 Subroutine, function
3880 @item @emph{Syntax}:
3881 @multitable @columnfractions .80
3882 @item @code{CALL FDATE(DATE)}.
3883 @item @code{DATE = FDATE()}, (not recommended).
3886 @item @emph{Arguments}:
3887 @multitable @columnfractions .15 .70
3888 @item @var{DATE}@tab The type shall be of type @code{CHARACTER}.
3891 @item @emph{Return value}:
3892 The current date as a string.
3894 @item @emph{Example}:
3898 character(len=30) :: date
3900 print *, 'Program started on ', date
3901 do i = 1, 100000000 ! Just a delay
3905 print *, 'Program ended on ', date
3906 end program test_fdate
3913 @section @code{FLOAT} --- Convert integer to default real
3915 @cindex conversion, to real
3918 @item @emph{Description}:
3919 @code{FLOAT(I)} converts the integer @var{I} to a default real value.
3921 @item @emph{Standard}:
3927 @item @emph{Syntax}:
3928 @code{RESULT = FLOAT(I)}
3930 @item @emph{Arguments}:
3931 @multitable @columnfractions .15 .70
3932 @item @var{I} @tab The type shall be @code{INTEGER(*)}.
3935 @item @emph{Return value}:
3936 The return value is of type default @code{REAL}.
3938 @item @emph{Example}:
3942 if (float(i) /= 1.) call abort
3943 end program test_float
3946 @item @emph{See also}:
3947 @ref{DBLE}, @ref{DFLOAT}, @ref{REAL}
3953 @section @code{FGET} --- Read a single character in stream mode from stdin
3955 @cindex read character, stream mode
3956 @cindex stream mode, read character
3957 @cindex file operation, read character
3960 @item @emph{Description}:
3961 Read a single character in stream mode from stdin by bypassing normal
3962 formatted output. Stream I/O should not be mixed with normal record-oriented
3963 (formatted or unformatted) I/O on the same unit; the results are unpredictable.
3965 This intrinsic is provided in both subroutine and function forms; however,
3966 only one form can be used in any given program unit.
3968 Note that the @code{FGET} intrinsic is provided for backwards compatibility with
3969 @command{g77}. GNU Fortran provides the Fortran 2003 Stream facility.
3970 Programmers should consider the use of new stream IO feature in new code
3971 for future portability. See also @ref{Fortran 2003 status}.
3973 @item @emph{Standard}:
3977 Subroutine, function
3979 @item @emph{Syntax}:
3980 @code{CALL FGET(C [, STATUS])}
3982 @item @emph{Arguments}:
3983 @multitable @columnfractions .15 .70
3984 @item @var{C} @tab The type shall be @code{CHARACTER}.
3985 @item @var{STATUS} @tab (Optional) status flag of type @code{INTEGER}.
3986 Returns 0 on success, -1 on end-of-file, and a
3987 system specific positive error code otherwise.
3990 @item @emph{Example}:
3993 INTEGER, PARAMETER :: strlen = 100
3994 INTEGER :: status, i = 1
3995 CHARACTER(len=strlen) :: str = ""
3997 WRITE (*,*) 'Enter text:'
3999 CALL fget(str(i:i), status)
4000 if (status /= 0 .OR. i > strlen) exit
4003 WRITE (*,*) TRIM(str)
4007 @item @emph{See also}:
4008 @ref{FGETC}, @ref{FPUT}, @ref{FPUTC}
4014 @section @code{FGETC} --- Read a single character in stream mode
4016 @cindex read character, stream mode
4017 @cindex stream mode, read character
4018 @cindex file operation, read character
4021 @item @emph{Description}:
4022 Read a single character in stream mode by bypassing normal formatted output.
4023 Stream I/O should not be mixed with normal record-oriented (formatted or
4024 unformatted) I/O on the same unit; the results are unpredictable.
4026 This intrinsic is provided in both subroutine and function forms; however,
4027 only one form can be used in any given program unit.
4029 Note that the @code{FGET} intrinsic is provided for backwards compatibility
4030 with @command{g77}. GNU Fortran provides the Fortran 2003 Stream facility.
4031 Programmers should consider the use of new stream IO feature in new code
4032 for future portability. See also @ref{Fortran 2003 status}.
4034 @item @emph{Standard}:
4038 Subroutine, function
4040 @item @emph{Syntax}:
4041 @code{CALL FGETC(UNIT, C [, STATUS])}
4043 @item @emph{Arguments}:
4044 @multitable @columnfractions .15 .70
4045 @item @var{UNIT} @tab The type shall be @code{INTEGER}.
4046 @item @var{C} @tab The type shall be @code{CHARACTER}.
4047 @item @var{STATUS} @tab (Optional) status flag of type @code{INTEGER}. Returns 0 on success,
4048 -1 on end-of-file and a system specific positive error code otherwise.
4051 @item @emph{Example}:
4054 INTEGER :: fd = 42, status
4057 OPEN(UNIT=fd, FILE="/etc/passwd", ACTION="READ", STATUS = "OLD")
4059 CALL fgetc(fd, c, status)
4060 IF (status /= 0) EXIT
4067 @item @emph{See also}:
4068 @ref{FGET}, @ref{FPUT}, @ref{FPUTC}
4074 @section @code{FLOOR} --- Integer floor function
4077 @cindex rounding, floor
4080 @item @emph{Description}:
4081 @code{FLOOR(X)} returns the greatest integer less than or equal to @var{X}.
4083 @item @emph{Standard}:
4089 @item @emph{Syntax}:
4090 @code{RESULT = FLOOR(X [, KIND])}
4092 @item @emph{Arguments}:
4093 @multitable @columnfractions .15 .70
4094 @item @var{X} @tab The type shall be @code{REAL(*)}.
4095 @item @var{KIND} @tab (Optional) An @code{INTEGER(*)} initialization
4096 expression indicating the kind parameter of
4100 @item @emph{Return value}:
4101 The return value is of type @code{INTEGER(KIND)}
4103 @item @emph{Example}:
4108 print *, floor(x) ! returns 63
4109 print *, floor(y) ! returns -64
4110 end program test_floor
4113 @item @emph{See also}:
4114 @ref{CEILING}, @ref{NINT}
4121 @section @code{FLUSH} --- Flush I/O unit(s)
4123 @cindex file operation, flush
4126 @item @emph{Description}:
4127 Flushes Fortran unit(s) currently open for output. Without the optional
4128 argument, all units are flushed, otherwise just the unit specified.
4130 @item @emph{Standard}:
4136 @item @emph{Syntax}:
4137 @code{CALL FLUSH(UNIT)}
4139 @item @emph{Arguments}:
4140 @multitable @columnfractions .15 .70
4141 @item @var{UNIT} @tab (Optional) The type shall be @code{INTEGER}.
4145 Beginning with the Fortran 2003 standard, there is a @code{FLUSH}
4146 statement that should be preferred over the @code{FLUSH} intrinsic.
4153 @section @code{FNUM} --- File number function
4155 @cindex file operation, file number
4158 @item @emph{Description}:
4159 @code{FNUM(UNIT)} returns the POSIX file descriptor number corresponding to the
4160 open Fortran I/O unit @code{UNIT}.
4162 @item @emph{Standard}:
4168 @item @emph{Syntax}:
4169 @code{RESULT = FNUM(UNIT)}
4171 @item @emph{Arguments}:
4172 @multitable @columnfractions .15 .70
4173 @item @var{UNIT} @tab The type shall be @code{INTEGER}.
4176 @item @emph{Return value}:
4177 The return value is of type @code{INTEGER}
4179 @item @emph{Example}:
4183 open (unit=10, status = "scratch")
4187 end program test_fnum
4194 @section @code{FPUT} --- Write a single character in stream mode to stdout
4196 @cindex write character, stream mode
4197 @cindex stream mode, write character
4198 @cindex file operation, write character
4201 @item @emph{Description}:
4202 Write a single character in stream mode to stdout by bypassing normal
4203 formatted output. Stream I/O should not be mixed with normal record-oriented
4204 (formatted or unformatted) I/O on the same unit; the results are unpredictable.
4206 This intrinsic is provided in both subroutine and function forms; however,
4207 only one form can be used in any given program unit.
4209 Note that the @code{FGET} intrinsic is provided for backwards compatibility with
4210 @command{g77}. GNU Fortran provides the Fortran 2003 Stream facility.
4211 Programmers should consider the use of new stream IO feature in new code
4212 for future portability. See also @ref{Fortran 2003 status}.
4214 @item @emph{Standard}:
4218 Subroutine, function
4220 @item @emph{Syntax}:
4221 @code{CALL FPUT(C [, STATUS])}
4223 @item @emph{Arguments}:
4224 @multitable @columnfractions .15 .70
4225 @item @var{C} @tab The type shall be @code{CHARACTER}.
4226 @item @var{STATUS} @tab (Optional) status flag of type @code{INTEGER}. Returns 0 on success,
4227 -1 on end-of-file and a system specific positive error code otherwise.
4230 @item @emph{Example}:
4233 CHARACTER(len=10) :: str = "gfortran"
4235 DO i = 1, len_trim(str)
4241 @item @emph{See also}:
4242 @ref{FPUTC}, @ref{FGET}, @ref{FGETC}
4248 @section @code{FPUTC} --- Write a single character in stream mode
4250 @cindex write character, stream mode
4251 @cindex stream mode, write character
4252 @cindex file operation, write character
4255 @item @emph{Description}:
4256 Write a single character in stream mode by bypassing normal formatted
4257 output. Stream I/O should not be mixed with normal record-oriented
4258 (formatted or unformatted) I/O on the same unit; the results are unpredictable.
4260 This intrinsic is provided in both subroutine and function forms; however,
4261 only one form can be used in any given program unit.
4263 Note that the @code{FGET} intrinsic is provided for backwards compatibility with
4264 @command{g77}. GNU Fortran provides the Fortran 2003 Stream facility.
4265 Programmers should consider the use of new stream IO feature in new code
4266 for future portability. See also @ref{Fortran 2003 status}.
4268 @item @emph{Standard}:
4272 Subroutine, function
4274 @item @emph{Syntax}:
4275 @code{CALL FPUTC(UNIT, C [, STATUS])}
4277 @item @emph{Arguments}:
4278 @multitable @columnfractions .15 .70
4279 @item @var{UNIT} @tab The type shall be @code{INTEGER}.
4280 @item @var{C} @tab The type shall be @code{CHARACTER}.
4281 @item @var{STATUS} @tab (Optional) status flag of type @code{INTEGER}. Returns 0 on success,
4282 -1 on end-of-file and a system specific positive error code otherwise.
4285 @item @emph{Example}:
4288 CHARACTER(len=10) :: str = "gfortran"
4289 INTEGER :: fd = 42, i
4291 OPEN(UNIT = fd, FILE = "out", ACTION = "WRITE", STATUS="NEW")
4292 DO i = 1, len_trim(str)
4293 CALL fputc(fd, str(i:i))
4299 @item @emph{See also}:
4300 @ref{FPUT}, @ref{FGET}, @ref{FGETC}
4306 @section @code{FRACTION} --- Fractional part of the model representation
4308 @cindex real number, fraction
4309 @cindex floating point, fraction
4312 @item @emph{Description}:
4313 @code{FRACTION(X)} returns the fractional part of the model
4314 representation of @code{X}.
4316 @item @emph{Standard}:
4322 @item @emph{Syntax}:
4323 @code{Y = FRACTION(X)}
4325 @item @emph{Arguments}:
4326 @multitable @columnfractions .15 .70
4327 @item @var{X} @tab The type of the argument shall be a @code{REAL}.
4330 @item @emph{Return value}:
4331 The return value is of the same type and kind as the argument.
4332 The fractional part of the model representation of @code{X} is returned;
4333 it is @code{X * RADIX(X)**(-EXPONENT(X))}.
4335 @item @emph{Example}:
4337 program test_fraction
4340 print *, fraction(x), x * radix(x)**(-exponent(x))
4341 end program test_fraction
4349 @section @code{FREE} --- Frees memory
4351 @cindex pointer, cray
4354 @item @emph{Description}:
4355 Frees memory previously allocated by @code{MALLOC()}. The @code{FREE}
4356 intrinsic is an extension intended to be used with Cray pointers, and is
4357 provided in GNU Fortran to allow user to compile legacy code. For
4358 new code using Fortran 95 pointers, the memory de-allocation intrinsic is
4361 @item @emph{Standard}:
4367 @item @emph{Syntax}:
4368 @code{CALL FREE(PTR)}
4370 @item @emph{Arguments}:
4371 @multitable @columnfractions .15 .70
4372 @item @var{PTR} @tab The type shall be @code{INTEGER}. It represents the
4373 location of the memory that should be de-allocated.
4376 @item @emph{Return value}:
4379 @item @emph{Example}:
4380 See @code{MALLOC} for an example.
4382 @item @emph{See also}:
4389 @section @code{FSEEK} --- Low level file positioning subroutine
4391 @cindex file operation, seek
4392 @cindex file operation, position
4395 @item @emph{Description}:
4396 Moves @var{UNIT} to the specified @var{OFFSET}. If @var{WHENCE}
4397 is set to 0, the @var{OFFSET} is taken as an absolute value @code{SEEK_SET},
4398 if set to 1, @var{OFFSET} is taken to be relative to the current position
4399 @code{SEEK_CUR}, and if set to 2 relative to the end of the file @code{SEEK_END}.
4400 On error, @var{STATUS} is set to a nonzero value. If @var{STATUS} the seek
4403 This intrinsic routine is not fully backwards compatible with @command{g77}.
4404 In @command{g77}, the @code{FSEEK} takes a statement label instead of a
4405 @var{STATUS} variable. If FSEEK is used in old code, change
4407 CALL FSEEK(UNIT, OFFSET, WHENCE, *label)
4412 CALL FSEEK(UNIT, OFFSET, WHENCE, status)
4413 IF (status /= 0) GOTO label
4416 Please note that GNU Fortran provides the Fortran 2003 Stream facility.
4417 Programmers should consider the use of new stream IO feature in new code
4418 for future portability. See also @ref{Fortran 2003 status}.
4420 @item @emph{Standard}:
4426 @item @emph{Syntax}:
4427 @code{CALL FSEEK(UNIT, OFFSET, WHENCE[, STATUS])}
4429 @item @emph{Arguments}:
4430 @multitable @columnfractions .15 .70
4431 @item @var{UNIT} @tab Shall be a scalar of type @code{INTEGER}.
4432 @item @var{OFFSET} @tab Shall be a scalar of type @code{INTEGER}.
4433 @item @var{WHENCE} @tab Shall be a scalar of type @code{INTEGER}.
4434 Its value shall be either 0, 1 or 2.
4435 @item @var{STATUS} @tab (Optional) shall be a scalar of type
4439 @item @emph{Example}:
4442 INTEGER, PARAMETER :: SEEK_SET = 0, SEEK_CUR = 1, SEEK_END = 2
4443 INTEGER :: fd, offset, ierr
4449 OPEN(UNIT=fd, FILE="fseek.test")
4450 CALL FSEEK(fd, offset, SEEK_SET, ierr) ! move to OFFSET
4451 print *, FTELL(fd), ierr
4453 CALL FSEEK(fd, 0, SEEK_END, ierr) ! move to end
4454 print *, FTELL(fd), ierr
4456 CALL FSEEK(fd, 0, SEEK_SET, ierr) ! move to beginning
4457 print *, FTELL(fd), ierr
4463 @item @emph{See also}:
4470 @section @code{FSTAT} --- Get file status
4472 @cindex file system, file status
4475 @item @emph{Description}:
4476 @code{FSTAT} is identical to @ref{STAT}, except that information about an
4477 already opened file is obtained.
4479 The elements in @code{BUFF} are the same as described by @ref{STAT}.
4481 This intrinsic is provided in both subroutine and function forms; however,
4482 only one form can be used in any given program unit.
4484 @item @emph{Standard}:
4488 Subroutine, function
4490 @item @emph{Syntax}:
4491 @code{CALL FSTAT(UNIT, BUFF [, STATUS])}
4493 @item @emph{Arguments}:
4494 @multitable @columnfractions .15 .70
4495 @item @var{UNIT} @tab An open I/O unit number of type @code{INTEGER}.
4496 @item @var{BUFF} @tab The type shall be @code{INTEGER(4), DIMENSION(13)}.
4497 @item @var{STATUS} @tab (Optional) status flag of type @code{INTEGER(4)}. Returns 0
4498 on success and a system specific error code otherwise.
4501 @item @emph{Example}:
4502 See @ref{STAT} for an example.
4504 @item @emph{See also}:
4505 To stat a link: @ref{LSTAT}, to stat a file: @ref{STAT}
4511 @section @code{FTELL} --- Current stream position
4513 @cindex file operation, position
4516 @item @emph{Description}:
4517 Retrieves the current position within an open file.
4519 This intrinsic is provided in both subroutine and function forms; however,
4520 only one form can be used in any given program unit.
4522 @item @emph{Standard}:
4526 Subroutine, function
4528 @item @emph{Syntax}:
4529 @multitable @columnfractions .80
4530 @item @code{CALL FTELL(UNIT, OFFSET)}
4531 @item @code{OFFSET = FTELL(UNIT)}
4534 @item @emph{Arguments}:
4535 @multitable @columnfractions .15 .70
4536 @item @var{OFFSET} @tab Shall of type @code{INTEGER}.
4537 @item @var{UNIT} @tab Shall of type @code{INTEGER}.
4540 @item @emph{Return value}:
4541 In either syntax, @var{OFFSET} is set to the current offset of unit
4542 number @var{UNIT}, or to @math{-1} if the unit is not currently open.
4544 @item @emph{Example}:
4548 OPEN(10, FILE="temp.dat")
4554 @item @emph{See also}:
4561 @section @code{GAMMA} --- Gamma function
4564 @cindex Gamma function
4565 @cindex Factorial function
4568 @item @emph{Description}:
4569 @code{GAMMA(X)} computes Gamma (@math{\Gamma}) of @var{X}. For positive,
4570 integer values of @var{X} the Gamma function simplifies to the factorial
4571 function @math{\Gamma(x)=(x-1)!}.
4575 \Gamma(x) = \int_0^\infty t^{x-1}{\rm e}^{-t}\,{\rm d}t
4579 @item @emph{Standard}:
4580 Fortran 2008 and later
4585 @item @emph{Syntax}:
4588 @item @emph{Arguments}:
4589 @multitable @columnfractions .15 .70
4590 @item @var{X} @tab Shall be of type @code{REAL} and neither zero
4591 nor a negative integer.
4594 @item @emph{Return value}:
4595 The return value is of type @code{REAL} of the same kind as @var{X}.
4597 @item @emph{Example}:
4601 x = gamma(x) ! returns 1.0
4602 end program test_gamma
4605 @item @emph{Specific names}:
4606 @multitable @columnfractions .20 .20 .20 .25
4607 @item Name @tab Argument @tab Return type @tab Standard
4608 @item @code{GAMMA(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab GNU Extension
4609 @item @code{DGAMMA(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU Extension
4612 @item @emph{See also}:
4613 Logarithm of the Gamma function: @ref{LOG_GAMMA}
4620 @section @code{GERROR} --- Get last system error message
4622 @cindex system, error handling
4625 @item @emph{Description}:
4626 Returns the system error message corresponding to the last system error.
4627 This resembles the functionality of @code{strerror(3)} in C.
4629 @item @emph{Standard}:
4635 @item @emph{Syntax}:
4636 @code{CALL GERROR(RESULT)}
4638 @item @emph{Arguments}:
4639 @multitable @columnfractions .15 .70
4640 @item @var{RESULT} @tab Shall of type @code{CHARACTER(*)}.
4643 @item @emph{Example}:
4646 CHARACTER(len=100) :: msg
4652 @item @emph{See also}:
4653 @ref{IERRNO}, @ref{PERROR}
4659 @section @code{GETARG} --- Get command line arguments
4661 @cindex command-line arguments
4662 @cindex arguments, to program
4665 @item @emph{Description}:
4666 Retrieve the @var{N}th argument that was passed on the
4667 command line when the containing program was invoked.
4669 This intrinsic routine is provided for backwards compatibility with
4670 GNU Fortran 77. In new code, programmers should consider the use of
4671 the @ref{GET_COMMAND_ARGUMENT} intrinsic defined by the Fortran 2003
4674 @item @emph{Standard}:
4680 @item @emph{Syntax}:
4681 @code{CALL GETARG(POS, VALUE)}
4683 @item @emph{Arguments}:
4684 @multitable @columnfractions .15 .70
4685 @item @var{POS} @tab Shall be of type @code{INTEGER} and not wider than
4686 the default integer kind; @math{@var{POS} \geq 0}
4687 @item @var{VALUE} @tab Shall be of type @code{CHARACTER(*)}.
4690 @item @emph{Return value}:
4691 After @code{GETARG} returns, the @var{VALUE} argument holds the
4692 @var{POS}th command line argument. If @var{VALUE} can not hold the
4693 argument, it is truncated to fit the length of @var{VALUE}. If there are
4694 less than @var{POS} arguments specified at the command line, @var{VALUE}
4695 will be filled with blanks. If @math{@var{POS} = 0}, @var{VALUE} is set
4696 to the name of the program (on systems that support this feature).
4698 @item @emph{Example}:
4702 CHARACTER(len=32) :: arg
4711 @item @emph{See also}:
4712 GNU Fortran 77 compatibility function: @ref{IARGC}
4714 Fortran 2003 functions and subroutines: @ref{GET_COMMAND},
4715 @ref{GET_COMMAND_ARGUMENT}, @ref{COMMAND_ARGUMENT_COUNT}
4721 @section @code{GET_COMMAND} --- Get the entire command line
4722 @fnindex GET_COMMAND
4723 @cindex command-line arguments
4724 @cindex arguments, to program
4727 @item @emph{Description}:
4728 Retrieve the entire command line that was used to invoke the program.
4730 @item @emph{Standard}:
4731 Fortran 2003 and later
4736 @item @emph{Syntax}:
4737 @code{CALL GET_COMMAND(CMD)}
4739 @item @emph{Arguments}:
4740 @multitable @columnfractions .15 .70
4741 @item @var{CMD} @tab Shall be of type @code{CHARACTER(*)}.
4744 @item @emph{Return value}:
4745 Stores the entire command line that was used to invoke the program in @var{ARG}.
4746 If @var{ARG} is not large enough, the command will be truncated.
4748 @item @emph{Example}:
4750 PROGRAM test_get_command
4751 CHARACTER(len=255) :: cmd
4752 CALL get_command(cmd)
4753 WRITE (*,*) TRIM(cmd)
4757 @item @emph{See also}:
4758 @ref{GET_COMMAND_ARGUMENT}, @ref{COMMAND_ARGUMENT_COUNT}
4763 @node GET_COMMAND_ARGUMENT
4764 @section @code{GET_COMMAND_ARGUMENT} --- Get command line arguments
4765 @fnindex GET_COMMAND_ARGUMENT
4766 @cindex command-line arguments
4767 @cindex arguments, to program
4770 @item @emph{Description}:
4771 Retrieve the @var{N}th argument that was passed on the
4772 command line when the containing program was invoked.
4774 @item @emph{Standard}:
4775 Fortran 2003 and later
4780 @item @emph{Syntax}:
4781 @code{CALL GET_COMMAND_ARGUMENT(N, ARG)}
4783 @item @emph{Arguments}:
4784 @multitable @columnfractions .15 .70
4785 @item @var{N} @tab Shall be of type @code{INTEGER(4)}, @math{@var{N} \geq 0}
4786 @item @var{ARG} @tab Shall be of type @code{CHARACTER(*)}.
4789 @item @emph{Return value}:
4790 After @code{GET_COMMAND_ARGUMENT} returns, the @var{ARG} argument holds the
4791 @var{N}th command line argument. If @var{ARG} can not hold the argument, it is
4792 truncated to fit the length of @var{ARG}. If there are less than @var{N}
4793 arguments specified at the command line, @var{ARG} will be filled with blanks.
4794 If @math{@var{N} = 0}, @var{ARG} is set to the name of the program (on systems
4795 that support this feature).
4797 @item @emph{Example}:
4799 PROGRAM test_get_command_argument
4801 CHARACTER(len=32) :: arg
4805 CALL get_command_argument(i, arg)
4806 IF (LEN_TRIM(arg) == 0) EXIT
4808 WRITE (*,*) TRIM(arg)
4814 @item @emph{See also}:
4815 @ref{GET_COMMAND}, @ref{COMMAND_ARGUMENT_COUNT}
4821 @section @code{GETCWD} --- Get current working directory
4823 @cindex system, working directory
4826 @item @emph{Description}:
4827 Get current working directory.
4829 This intrinsic is provided in both subroutine and function forms; however,
4830 only one form can be used in any given program unit.
4832 @item @emph{Standard}:
4836 Subroutine, function
4838 @item @emph{Syntax}:
4839 @code{CALL GETCWD(CWD [, STATUS])}
4841 @item @emph{Arguments}:
4842 @multitable @columnfractions .15 .70
4843 @item @var{CWD} @tab The type shall be @code{CHARACTER(*)}.
4844 @item @var{STATUS} @tab (Optional) status flag. Returns 0 on success,
4845 a system specific and nonzero error code otherwise.
4848 @item @emph{Example}:
4851 CHARACTER(len=255) :: cwd
4853 WRITE(*,*) TRIM(cwd)
4857 @item @emph{See also}:
4864 @section @code{GETENV} --- Get an environmental variable
4866 @cindex environment variable
4869 @item @emph{Description}:
4870 Get the @var{VALUE} of the environmental variable @var{ENVVAR}.
4872 This intrinsic routine is provided for backwards compatibility with
4873 GNU Fortran 77. In new code, programmers should consider the use of
4874 the @ref{GET_ENVIRONMENT_VARIABLE} intrinsic defined by the Fortran
4877 @item @emph{Standard}:
4883 @item @emph{Syntax}:
4884 @code{CALL GETENV(ENVVAR, VALUE)}
4886 @item @emph{Arguments}:
4887 @multitable @columnfractions .15 .70
4888 @item @var{ENVVAR} @tab Shall be of type @code{CHARACTER(*)}.
4889 @item @var{VALUE} @tab Shall be of type @code{CHARACTER(*)}.
4892 @item @emph{Return value}:
4893 Stores the value of @var{ENVVAR} in @var{VALUE}. If @var{VALUE} is
4894 not large enough to hold the data, it is truncated. If @var{ENVVAR}
4895 is not set, @var{VALUE} will be filled with blanks.
4897 @item @emph{Example}:
4900 CHARACTER(len=255) :: homedir
4901 CALL getenv("HOME", homedir)
4902 WRITE (*,*) TRIM(homedir)
4906 @item @emph{See also}:
4907 @ref{GET_ENVIRONMENT_VARIABLE}
4912 @node GET_ENVIRONMENT_VARIABLE
4913 @section @code{GET_ENVIRONMENT_VARIABLE} --- Get an environmental variable
4914 @fnindex GET_ENVIRONMENT_VARIABLE
4915 @cindex environment variable
4918 @item @emph{Description}:
4919 Get the @var{VALUE} of the environmental variable @var{ENVVAR}.
4921 @item @emph{Standard}:
4922 Fortran 2003 and later
4927 @item @emph{Syntax}:
4928 @code{CALL GET_ENVIRONMENT_VARIABLE(ENVVAR, VALUE)}
4930 @item @emph{Arguments}:
4931 @multitable @columnfractions .15 .70
4932 @item @var{ENVVAR} @tab Shall be of type @code{CHARACTER(*)}.
4933 @item @var{VALUE} @tab Shall be of type @code{CHARACTER(*)}.
4936 @item @emph{Return value}:
4937 Stores the value of @var{ENVVAR} in @var{VALUE}. If @var{VALUE} is
4938 not large enough to hold the data, it is truncated. If @var{ENVVAR}
4939 is not set, @var{VALUE} will be filled with blanks.
4941 @item @emph{Example}:
4944 CHARACTER(len=255) :: homedir
4945 CALL get_environment_variable("HOME", homedir)
4946 WRITE (*,*) TRIM(homedir)
4954 @section @code{GETGID} --- Group ID function
4956 @cindex system, group id
4959 @item @emph{Description}:
4960 Returns the numerical group ID of the current process.
4962 @item @emph{Standard}:
4968 @item @emph{Syntax}:
4969 @code{RESULT = GETGID()}
4971 @item @emph{Return value}:
4972 The return value of @code{GETGID} is an @code{INTEGER} of the default
4976 @item @emph{Example}:
4977 See @code{GETPID} for an example.
4979 @item @emph{See also}:
4980 @ref{GETPID}, @ref{GETUID}
4986 @section @code{GETLOG} --- Get login name
4988 @cindex system, login name
4992 @item @emph{Description}:
4993 Gets the username under which the program is running.
4995 @item @emph{Standard}:
5001 @item @emph{Syntax}:
5002 @code{CALL GETLOG(LOGIN)}
5004 @item @emph{Arguments}:
5005 @multitable @columnfractions .15 .70
5006 @item @var{LOGIN} @tab Shall be of type @code{CHARACTER(*)}.
5009 @item @emph{Return value}:
5010 Stores the current user name in @var{LOGIN}. (On systems where POSIX
5011 functions @code{geteuid} and @code{getpwuid} are not available, and
5012 the @code{getlogin} function is not implemented either, this will
5013 return a blank string.)
5015 @item @emph{Example}:
5018 CHARACTER(32) :: login
5024 @item @emph{See also}:
5031 @section @code{GETPID} --- Process ID function
5033 @cindex system, process id
5037 @item @emph{Description}:
5038 Returns the numerical process identifier of the current process.
5040 @item @emph{Standard}:
5046 @item @emph{Syntax}:
5047 @code{RESULT = GETPID()}
5049 @item @emph{Return value}:
5050 The return value of @code{GETPID} is an @code{INTEGER} of the default
5054 @item @emph{Example}:
5057 print *, "The current process ID is ", getpid()
5058 print *, "Your numerical user ID is ", getuid()
5059 print *, "Your numerical group ID is ", getgid()
5063 @item @emph{See also}:
5064 @ref{GETGID}, @ref{GETUID}
5070 @section @code{GETUID} --- User ID function
5072 @cindex system, user id
5076 @item @emph{Description}:
5077 Returns the numerical user ID of the current process.
5079 @item @emph{Standard}:
5085 @item @emph{Syntax}:
5086 @code{RESULT = GETUID()}
5088 @item @emph{Return value}:
5089 The return value of @code{GETUID} is an @code{INTEGER} of the default
5093 @item @emph{Example}:
5094 See @code{GETPID} for an example.
5096 @item @emph{See also}:
5097 @ref{GETPID}, @ref{GETLOG}
5103 @section @code{GMTIME} --- Convert time to GMT info
5105 @cindex time, conversion to GMT info
5108 @item @emph{Description}:
5109 Given a system time value @var{STIME} (as provided by the @code{TIME8()}
5110 intrinsic), fills @var{TARRAY} with values extracted from it appropriate
5111 to the UTC time zone (Universal Coordinated Time, also known in some
5112 countries as GMT, Greenwich Mean Time), using @code{gmtime(3)}.
5114 @item @emph{Standard}:
5120 @item @emph{Syntax}:
5121 @code{CALL GMTIME(STIME, TARRAY)}
5123 @item @emph{Arguments}:
5124 @multitable @columnfractions .15 .70
5125 @item @var{STIME} @tab An @code{INTEGER(*)} scalar expression
5126 corresponding to a system time, with
5128 @item @var{TARRAY} @tab A default @code{INTEGER} array with 9 elements,
5129 with @code{INTENT(OUT)}.
5132 @item @emph{Return value}:
5133 The elements of @var{TARRAY} are assigned as follows:
5135 @item Seconds after the minute, range 0--59 or 0--61 to allow for leap
5137 @item Minutes after the hour, range 0--59
5138 @item Hours past midnight, range 0--23
5139 @item Day of month, range 0--31
5140 @item Number of months since January, range 0--12
5141 @item Years since 1900
5142 @item Number of days since Sunday, range 0--6
5143 @item Days since January 1
5144 @item Daylight savings indicator: positive if daylight savings is in
5145 effect, zero if not, and negative if the information is not
5149 @item @emph{See also}:
5150 @ref{CTIME}, @ref{LTIME}, @ref{TIME}, @ref{TIME8}
5157 @section @code{HOSTNM} --- Get system host name
5159 @cindex system, host name
5162 @item @emph{Description}:
5163 Retrieves the host name of the system on which the program is running.
5165 This intrinsic is provided in both subroutine and function forms; however,
5166 only one form can be used in any given program unit.
5168 @item @emph{Standard}:
5172 Subroutine, function
5174 @item @emph{Syntax}:
5175 @multitable @columnfractions .80
5176 @item @code{CALL HOSTNM(NAME[, STATUS])}
5177 @item @code{STATUS = HOSTNM(NAME)}
5180 @item @emph{Arguments}:
5181 @multitable @columnfractions .15 .70
5182 @item @var{NAME} @tab Shall of type @code{CHARACTER(*)}.
5183 @item @var{STATUS} @tab (Optional) status flag of type @code{INTEGER}.
5184 Returns 0 on success, or a system specific error
5188 @item @emph{Return value}:
5189 In either syntax, @var{NAME} is set to the current hostname if it can
5190 be obtained, or to a blank string otherwise.
5197 @section @code{HUGE} --- Largest number of a kind
5199 @cindex limits, largest number
5200 @cindex model representation, largest number
5203 @item @emph{Description}:
5204 @code{HUGE(X)} returns the largest number that is not an infinity in
5205 the model of the type of @code{X}.
5207 @item @emph{Standard}:
5213 @item @emph{Syntax}:
5214 @code{RESULT = HUGE(X)}
5216 @item @emph{Arguments}:
5217 @multitable @columnfractions .15 .70
5218 @item @var{X} @tab Shall be of type @code{REAL} or @code{INTEGER}.
5221 @item @emph{Return value}:
5222 The return value is of the same type and kind as @var{X}
5224 @item @emph{Example}:
5226 program test_huge_tiny
5227 print *, huge(0), huge(0.0), huge(0.0d0)
5228 print *, tiny(0.0), tiny(0.0d0)
5229 end program test_huge_tiny
5236 @section @code{HYPOT} --- Euclidean distance function
5238 @cindex Euclidean distance
5241 @item @emph{Description}:
5242 @code{HYPOT(X,Y)} is the Euclidean distance function. It is equal to
5243 @math{\sqrt{X^2 + Y^2}}, without undue underflow or overflow.
5245 @item @emph{Standard}:
5246 Fortran 2008 and later
5251 @item @emph{Syntax}:
5252 @code{RESULT = HYPOT(X,Y)}
5254 @item @emph{Arguments}:
5255 @multitable @columnfractions .15 .70
5256 @item @var{X} @tab The type shall be @code{REAL}.
5257 @item @var{Y} @tab The type and kind type parameter shall be the same as
5261 @item @emph{Return value}:
5262 The return value has the same type and kind type parameter as @var{X}.
5264 @item @emph{Example}:
5267 real(4) :: x = 1.e0_4, y = 0.5e0_4
5269 end program test_hypot
5276 @section @code{IACHAR} --- Code in @acronym{ASCII} collating sequence
5278 @cindex @acronym{ASCII} collating sequence
5279 @cindex collating sequence, @acronym{ASCII}
5280 @cindex conversion, to integer
5283 @item @emph{Description}:
5284 @code{IACHAR(C)} returns the code for the @acronym{ASCII} character
5285 in the first character position of @code{C}.
5287 @item @emph{Standard}:
5293 @item @emph{Syntax}:
5294 @code{RESULT = IACHAR(C [, KIND])}
5296 @item @emph{Arguments}:
5297 @multitable @columnfractions .15 .70
5298 @item @var{C} @tab Shall be a scalar @code{CHARACTER}, with @code{INTENT(IN)}
5299 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
5300 expression indicating the kind parameter of
5304 @item @emph{Return value}:
5305 The return value is of type @code{INTEGER} and of kind @var{KIND}. If
5306 @var{KIND} is absent, the return value is of default integer kind.
5308 @item @emph{Example}:
5313 end program test_iachar
5317 See @ref{ICHAR} for a discussion of converting between numerical values
5318 and formatted string representations.
5320 @item @emph{See also}:
5321 @ref{ACHAR}, @ref{CHAR}, @ref{ICHAR}
5328 @section @code{IAND} --- Bitwise logical and
5330 @cindex bitwise logical and
5331 @cindex logical and, bitwise
5334 @item @emph{Description}:
5335 Bitwise logical @code{AND}.
5337 @item @emph{Standard}:
5343 @item @emph{Syntax}:
5344 @code{RESULT = IAND(I, J)}
5346 @item @emph{Arguments}:
5347 @multitable @columnfractions .15 .70
5348 @item @var{I} @tab The type shall be @code{INTEGER(*)}.
5349 @item @var{J} @tab The type shall be @code{INTEGER(*)}, of the same
5350 kind as @var{I}. (As a GNU extension, different kinds are also
5354 @item @emph{Return value}:
5355 The return type is @code{INTEGER(*)}, of the same kind as the
5356 arguments. (If the argument kinds differ, it is of the same kind as
5357 the larger argument.)
5359 @item @emph{Example}:
5363 DATA a / Z'F' /, b / Z'3' /
5364 WRITE (*,*) IAND(a, b)
5368 @item @emph{See also}:
5369 @ref{IOR}, @ref{IEOR}, @ref{IBITS}, @ref{IBSET}, @ref{IBCLR}, @ref{NOT}
5376 @section @code{IARGC} --- Get the number of command line arguments
5378 @cindex command-line arguments
5379 @cindex command-line arguments, number of
5380 @cindex arguments, to program
5383 @item @emph{Description}:
5384 @code{IARGC()} returns the number of arguments passed on the
5385 command line when the containing program was invoked.
5387 This intrinsic routine is provided for backwards compatibility with
5388 GNU Fortran 77. In new code, programmers should consider the use of
5389 the @ref{COMMAND_ARGUMENT_COUNT} intrinsic defined by the Fortran 2003
5392 @item @emph{Standard}:
5398 @item @emph{Syntax}:
5399 @code{RESULT = IARGC()}
5401 @item @emph{Arguments}:
5404 @item @emph{Return value}:
5405 The number of command line arguments, type @code{INTEGER(4)}.
5407 @item @emph{Example}:
5410 @item @emph{See also}:
5411 GNU Fortran 77 compatibility subroutine: @ref{GETARG}
5413 Fortran 2003 functions and subroutines: @ref{GET_COMMAND},
5414 @ref{GET_COMMAND_ARGUMENT}, @ref{COMMAND_ARGUMENT_COUNT}
5420 @section @code{IBCLR} --- Clear bit
5426 @item @emph{Description}:
5427 @code{IBCLR} returns the value of @var{I} with the bit at position
5428 @var{POS} set to zero.
5430 @item @emph{Standard}:
5436 @item @emph{Syntax}:
5437 @code{RESULT = IBCLR(I, POS)}
5439 @item @emph{Arguments}:
5440 @multitable @columnfractions .15 .70
5441 @item @var{I} @tab The type shall be @code{INTEGER(*)}.
5442 @item @var{POS} @tab The type shall be @code{INTEGER(*)}.
5445 @item @emph{Return value}:
5446 The return value is of type @code{INTEGER(*)} and of the same kind as
5449 @item @emph{See also}:
5450 @ref{IBITS}, @ref{IBSET}, @ref{IAND}, @ref{IOR}, @ref{IEOR}, @ref{MVBITS}
5457 @section @code{IBITS} --- Bit extraction
5460 @cindex bits, extract
5463 @item @emph{Description}:
5464 @code{IBITS} extracts a field of length @var{LEN} from @var{I},
5465 starting from bit position @var{POS} and extending left for @var{LEN}
5466 bits. The result is right-justified and the remaining bits are
5467 zeroed. The value of @code{POS+LEN} must be less than or equal to the
5468 value @code{BIT_SIZE(I)}.
5470 @item @emph{Standard}:
5476 @item @emph{Syntax}:
5477 @code{RESULT = IBITS(I, POS, LEN)}
5479 @item @emph{Arguments}:
5480 @multitable @columnfractions .15 .70
5481 @item @var{I} @tab The type shall be @code{INTEGER(*)}.
5482 @item @var{POS} @tab The type shall be @code{INTEGER(*)}.
5483 @item @var{LEN} @tab The type shall be @code{INTEGER(*)}.
5486 @item @emph{Return value}:
5487 The return value is of type @code{INTEGER(*)} and of the same kind as
5490 @item @emph{See also}:
5491 @ref{BIT_SIZE}, @ref{IBCLR}, @ref{IBSET}, @ref{IAND}, @ref{IOR}, @ref{IEOR}
5497 @section @code{IBSET} --- Set bit
5502 @item @emph{Description}:
5503 @code{IBSET} returns the value of @var{I} with the bit at position
5504 @var{POS} set to one.
5506 @item @emph{Standard}:
5512 @item @emph{Syntax}:
5513 @code{RESULT = IBSET(I, POS)}
5515 @item @emph{Arguments}:
5516 @multitable @columnfractions .15 .70
5517 @item @var{I} @tab The type shall be @code{INTEGER(*)}.
5518 @item @var{POS} @tab The type shall be @code{INTEGER(*)}.
5521 @item @emph{Return value}:
5522 The return value is of type @code{INTEGER(*)} and of the same kind as
5525 @item @emph{See also}:
5526 @ref{IBCLR}, @ref{IBITS}, @ref{IAND}, @ref{IOR}, @ref{IEOR}, @ref{MVBITS}
5533 @section @code{ICHAR} --- Character-to-integer conversion function
5535 @cindex conversion, to integer
5538 @item @emph{Description}:
5539 @code{ICHAR(C)} returns the code for the character in the first character
5540 position of @code{C} in the system's native character set.
5541 The correspondence between characters and their codes is not necessarily
5542 the same across different GNU Fortran implementations.
5544 @item @emph{Standard}:
5550 @item @emph{Syntax}:
5551 @code{RESULT = ICHAR(C [, KIND])}
5553 @item @emph{Arguments}:
5554 @multitable @columnfractions .15 .70
5555 @item @var{C} @tab Shall be a scalar @code{CHARACTER}, with @code{INTENT(IN)}
5556 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
5557 expression indicating the kind parameter of
5561 @item @emph{Return value}:
5562 The return value is of type @code{INTEGER} and of kind @var{KIND}. If
5563 @var{KIND} is absent, the return value is of default integer kind.
5565 @item @emph{Example}:
5570 end program test_ichar
5574 No intrinsic exists to convert between a numeric value and a formatted
5575 character string representation -- for instance, given the
5576 @code{CHARACTER} value @code{'154'}, obtaining an @code{INTEGER} or
5577 @code{REAL} value with the value 154, or vice versa. Instead, this
5578 functionality is provided by internal-file I/O, as in the following
5583 character(len=10) string, string2
5586 ! Convert a string to a numeric value
5587 read (string,'(I10)') value
5590 ! Convert a value to a formatted string
5591 write (string2,'(I10)') value
5593 end program read_val
5596 @item @emph{See also}:
5597 @ref{ACHAR}, @ref{CHAR}, @ref{IACHAR}
5604 @section @code{IDATE} --- Get current local time subroutine (day/month/year)
5606 @cindex date, current
5607 @cindex current date
5610 @item @emph{Description}:
5611 @code{IDATE(TARRAY)} Fills @var{TARRAY} with the numerical values at the
5612 current local time. The day (in the range 1-31), month (in the range 1-12),
5613 and year appear in elements 1, 2, and 3 of @var{TARRAY}, respectively.
5614 The year has four significant digits.
5616 @item @emph{Standard}:
5622 @item @emph{Syntax}:
5623 @code{CALL IDATE(TARRAY)}
5625 @item @emph{Arguments}:
5626 @multitable @columnfractions .15 .70
5627 @item @var{TARRAY} @tab The type shall be @code{INTEGER, DIMENSION(3)} and
5628 the kind shall be the default integer kind.
5631 @item @emph{Return value}:
5634 @item @emph{Example}:
5637 integer, dimension(3) :: tarray
5642 end program test_idate
5649 @section @code{IEOR} --- Bitwise logical exclusive or
5651 @cindex bitwise logical exclusive or
5652 @cindex logical exclusive or, bitwise
5655 @item @emph{Description}:
5656 @code{IEOR} returns the bitwise boolean exclusive-OR of @var{I} and
5659 @item @emph{Standard}:
5665 @item @emph{Syntax}:
5666 @code{RESULT = IEOR(I, J)}
5668 @item @emph{Arguments}:
5669 @multitable @columnfractions .15 .70
5670 @item @var{I} @tab The type shall be @code{INTEGER(*)}.
5671 @item @var{J} @tab The type shall be @code{INTEGER(*)}, of the same
5672 kind as @var{I}. (As a GNU extension, different kinds are also
5676 @item @emph{Return value}:
5677 The return type is @code{INTEGER(*)}, of the same kind as the
5678 arguments. (If the argument kinds differ, it is of the same kind as
5679 the larger argument.)
5681 @item @emph{See also}:
5682 @ref{IOR}, @ref{IAND}, @ref{IBITS}, @ref{IBSET}, @ref{IBCLR}, @ref{NOT}
5688 @section @code{IERRNO} --- Get the last system error number
5690 @cindex system, error handling
5693 @item @emph{Description}:
5694 Returns the last system error number, as given by the C @code{errno()}
5697 @item @emph{Standard}:
5703 @item @emph{Syntax}:
5704 @code{RESULT = IERRNO()}
5706 @item @emph{Arguments}:
5709 @item @emph{Return value}:
5710 The return value is of type @code{INTEGER} and of the default integer
5713 @item @emph{See also}:
5719 @node INDEX intrinsic
5720 @section @code{INDEX} --- Position of a substring within a string
5722 @cindex substring position
5723 @cindex string, find substring
5726 @item @emph{Description}:
5727 Returns the position of the start of the first occurrence of string
5728 @var{SUBSTRING} as a substring in @var{STRING}, counting from one. If
5729 @var{SUBSTRING} is not present in @var{STRING}, zero is returned. If
5730 the @var{BACK} argument is present and true, the return value is the
5731 start of the last occurrence rather than the first.
5733 @item @emph{Standard}:
5739 @item @emph{Syntax}:
5740 @code{RESULT = INDEX(STRING, SUBSTRING [, BACK [, KIND]])}
5742 @item @emph{Arguments}:
5743 @multitable @columnfractions .15 .70
5744 @item @var{STRING} @tab Shall be a scalar @code{CHARACTER(*)}, with
5746 @item @var{SUBSTRING} @tab Shall be a scalar @code{CHARACTER(*)}, with
5748 @item @var{BACK} @tab (Optional) Shall be a scalar @code{LOGICAL(*)}, with
5750 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
5751 expression indicating the kind parameter of
5755 @item @emph{Return value}:
5756 The return value is of type @code{INTEGER} and of kind @var{KIND}. If
5757 @var{KIND} is absent, the return value is of default integer kind.
5759 @item @emph{See also}:
5760 @ref{SCAN}, @ref{VERIFY}
5766 @section @code{INT} --- Convert to integer type
5770 @cindex conversion, to integer
5773 @item @emph{Description}:
5774 Convert to integer type
5776 @item @emph{Standard}:
5782 @item @emph{Syntax}:
5783 @code{RESULT = INT(A [, KIND))}
5785 @item @emph{Arguments}:
5786 @multitable @columnfractions .15 .70
5787 @item @var{A} @tab Shall be of type @code{INTEGER(*)},
5788 @code{REAL(*)}, or @code{COMPLEX(*)}.
5789 @item @var{KIND} @tab (Optional) An @code{INTEGER(*)} initialization
5790 expression indicating the kind parameter of
5794 @item @emph{Return value}:
5795 These functions return a @code{INTEGER(*)} variable or array under
5796 the following rules:
5800 If @var{A} is of type @code{INTEGER(*)}, @code{INT(A) = A}
5802 If @var{A} is of type @code{REAL(*)} and @math{|A| < 1}, @code{INT(A)} equals @code{0}.
5803 If @math{|A| \geq 1}, then @code{INT(A)} equals the largest integer that does not exceed
5804 the range of @var{A} and whose sign is the same as the sign of @var{A}.
5806 If @var{A} is of type @code{COMPLEX(*)}, rule B is applied to the real part of @var{A}.
5809 @item @emph{Example}:
5813 complex :: z = (-3.7, 1.0)
5815 print *, int(z), int(z,8)
5819 @item @emph{Specific names}:
5820 @multitable @columnfractions .20 .20 .20 .25
5821 @item Name @tab Argument @tab Return type @tab Standard
5822 @item @code{IFIX(A)} @tab @code{REAL(4) A} @tab @code{INTEGER} @tab F77 and later
5823 @item @code{IDINT(A)} @tab @code{REAL(8) A} @tab @code{INTEGER} @tab F77 and later
5831 @section @code{INT2} --- Convert to 16-bit integer type
5834 @cindex conversion, to integer
5837 @item @emph{Description}:
5838 Convert to a @code{KIND=2} integer type. This is equivalent to the
5839 standard @code{INT} intrinsic with an optional argument of
5840 @code{KIND=2}, and is only included for backwards compatibility.
5842 The @code{SHORT} intrinsic is equivalent to @code{INT2}.
5844 @item @emph{Standard}:
5850 @item @emph{Syntax}:
5851 @code{RESULT = INT2(A)}
5853 @item @emph{Arguments}:
5854 @multitable @columnfractions .15 .70
5855 @item @var{A} @tab Shall be of type @code{INTEGER(*)},
5856 @code{REAL(*)}, or @code{COMPLEX(*)}.
5859 @item @emph{Return value}:
5860 The return value is a @code{INTEGER(2)} variable.
5862 @item @emph{See also}:
5863 @ref{INT}, @ref{INT8}, @ref{LONG}
5869 @section @code{INT8} --- Convert to 64-bit integer type
5871 @cindex conversion, to integer
5874 @item @emph{Description}:
5875 Convert to a @code{KIND=8} integer type. This is equivalent to the
5876 standard @code{INT} intrinsic with an optional argument of
5877 @code{KIND=8}, and is only included for backwards compatibility.
5879 @item @emph{Standard}:
5885 @item @emph{Syntax}:
5886 @code{RESULT = INT8(A)}
5888 @item @emph{Arguments}:
5889 @multitable @columnfractions .15 .70
5890 @item @var{A} @tab Shall be of type @code{INTEGER(*)},
5891 @code{REAL(*)}, or @code{COMPLEX(*)}.
5894 @item @emph{Return value}:
5895 The return value is a @code{INTEGER(8)} variable.
5897 @item @emph{See also}:
5898 @ref{INT}, @ref{INT2}, @ref{LONG}
5904 @section @code{IOR} --- Bitwise logical or
5906 @cindex bitwise logical or
5907 @cindex logical or, bitwise
5910 @item @emph{Description}:
5911 @code{IOR} returns the bitwise boolean inclusive-OR of @var{I} and
5914 @item @emph{Standard}:
5920 @item @emph{Syntax}:
5921 @code{RESULT = IOR(I, J)}
5923 @item @emph{Arguments}:
5924 @multitable @columnfractions .15 .70
5925 @item @var{I} @tab The type shall be @code{INTEGER(*)}.
5926 @item @var{J} @tab The type shall be @code{INTEGER(*)}, of the same
5927 kind as @var{I}. (As a GNU extension, different kinds are also
5931 @item @emph{Return value}:
5932 The return type is @code{INTEGER(*)}, of the same kind as the
5933 arguments. (If the argument kinds differ, it is of the same kind as
5934 the larger argument.)
5936 @item @emph{See also}:
5937 @ref{IEOR}, @ref{IAND}, @ref{IBITS}, @ref{IBSET}, @ref{IBCLR}, @ref{NOT}
5943 @section @code{IRAND} --- Integer pseudo-random number
5945 @cindex random number generation
5948 @item @emph{Description}:
5949 @code{IRAND(FLAG)} returns a pseudo-random number from a uniform
5950 distribution between 0 and a system-dependent limit (which is in most
5951 cases 2147483647). If @var{FLAG} is 0, the next number
5952 in the current sequence is returned; if @var{FLAG} is 1, the generator
5953 is restarted by @code{CALL SRAND(0)}; if @var{FLAG} has any other value,
5954 it is used as a new seed with @code{SRAND}.
5956 This intrinsic routine is provided for backwards compatibility with
5957 GNU Fortran 77. It implements a simple modulo generator as provided
5958 by @command{g77}. For new code, one should consider the use of
5959 @ref{RANDOM_NUMBER} as it implements a superior algorithm.
5961 @item @emph{Standard}:
5967 @item @emph{Syntax}:
5968 @code{RESULT = IRAND(FLAG)}
5970 @item @emph{Arguments}:
5971 @multitable @columnfractions .15 .70
5972 @item @var{FLAG} @tab Shall be a scalar @code{INTEGER} of kind 4.
5975 @item @emph{Return value}:
5976 The return value is of @code{INTEGER(kind=4)} type.
5978 @item @emph{Example}:
5981 integer,parameter :: seed = 86456
5984 print *, irand(), irand(), irand(), irand()
5985 print *, irand(seed), irand(), irand(), irand()
5986 end program test_irand
5994 @section @code{IS_IOSTAT_END} --- Test for end-of-file value
5995 @fnindex IS_IOSTAT_END
5996 @cindex IOSTAT, end of file
5999 @item @emph{Description}:
6000 @code{IS_IOSTAT_END} tests whether an variable has the value of the I/O
6001 status ``end of file''. The function is equivalent to comparing the variable
6002 with the @code{IOSTAT_END} parameter of the intrinsic module
6003 @code{ISO_FORTRAN_ENV}.
6005 @item @emph{Standard}:
6006 Fortran 2003 and later
6011 @item @emph{Syntax}:
6012 @code{RESULT = IS_IOSTAT_END(I)}
6014 @item @emph{Arguments}:
6015 @multitable @columnfractions .15 .70
6016 @item @var{I} @tab Shall be of the type @code{INTEGER}.
6019 @item @emph{Return value}:
6020 Returns a @code{LOGICAL} of the default kind, which @code{.TRUE.} if
6021 @var{I} has the value which indicates an end of file condition for
6022 IOSTAT= specifiers, and is @code{.FALSE.} otherwise.
6024 @item @emph{Example}:
6029 OPEN(88, FILE='test.dat')
6030 READ(88, *, IOSTAT=stat) i
6031 IF(IS_IOSTAT_END(stat)) STOP 'END OF FILE'
6039 @section @code{IS_IOSTAT_EOR} --- Test for end-of-record value
6040 @fnindex IS_IOSTAT_EOR
6041 @cindex IOSTAT, end of record
6044 @item @emph{Description}:
6045 @code{IS_IOSTAT_EOR} tests whether an variable has the value of the I/O
6046 status ``end of record''. The function is equivalent to comparing the
6047 variable with the @code{IOSTAT_EOR} parameter of the intrinsic module
6048 @code{ISO_FORTRAN_ENV}.
6050 @item @emph{Standard}:
6051 Fortran 2003 and later
6056 @item @emph{Syntax}:
6057 @code{RESULT = IS_IOSTAT_EOR(I)}
6059 @item @emph{Arguments}:
6060 @multitable @columnfractions .15 .70
6061 @item @var{I} @tab Shall be of the type @code{INTEGER}.
6064 @item @emph{Return value}:
6065 Returns a @code{LOGICAL} of the default kind, which @code{.TRUE.} if
6066 @var{I} has the value which indicates an end of file condition for
6067 IOSTAT= specifiers, and is @code{.FALSE.} otherwise.
6069 @item @emph{Example}:
6073 INTEGER :: stat, i(50)
6074 OPEN(88, FILE='test.dat', FORM='UNFORMATTED')
6075 READ(88, IOSTAT=stat) i
6076 IF(IS_IOSTAT_EOR(stat)) STOP 'END OF RECORD'
6084 @section @code{ISATTY} --- Whether a unit is a terminal device.
6086 @cindex system, terminal
6089 @item @emph{Description}:
6090 Determine whether a unit is connected to a terminal device.
6092 @item @emph{Standard}:
6098 @item @emph{Syntax}:
6099 @code{RESULT = ISATTY(UNIT)}
6101 @item @emph{Arguments}:
6102 @multitable @columnfractions .15 .70
6103 @item @var{UNIT} @tab Shall be a scalar @code{INTEGER(*)}.
6106 @item @emph{Return value}:
6107 Returns @code{.TRUE.} if the @var{UNIT} is connected to a terminal
6108 device, @code{.FALSE.} otherwise.
6110 @item @emph{Example}:
6113 INTEGER(kind=1) :: unit
6115 write(*,*) isatty(unit=unit)
6119 @item @emph{See also}:
6126 @section @code{ISHFT} --- Shift bits
6131 @item @emph{Description}:
6132 @code{ISHFT} returns a value corresponding to @var{I} with all of the
6133 bits shifted @var{SHIFT} places. A value of @var{SHIFT} greater than
6134 zero corresponds to a left shift, a value of zero corresponds to no
6135 shift, and a value less than zero corresponds to a right shift. If the
6136 absolute value of @var{SHIFT} is greater than @code{BIT_SIZE(I)}, the
6137 value is undefined. Bits shifted out from the left end or right end are
6138 lost; zeros are shifted in from the opposite end.
6140 @item @emph{Standard}:
6146 @item @emph{Syntax}:
6147 @code{RESULT = ISHFT(I, SHIFT)}
6149 @item @emph{Arguments}:
6150 @multitable @columnfractions .15 .70
6151 @item @var{I} @tab The type shall be @code{INTEGER(*)}.
6152 @item @var{SHIFT} @tab The type shall be @code{INTEGER(*)}.
6155 @item @emph{Return value}:
6156 The return value is of type @code{INTEGER(*)} and of the same kind as
6159 @item @emph{See also}:
6166 @section @code{ISHFTC} --- Shift bits circularly
6168 @cindex bits, shift circular
6171 @item @emph{Description}:
6172 @code{ISHFTC} returns a value corresponding to @var{I} with the
6173 rightmost @var{SIZE} bits shifted circularly @var{SHIFT} places; that
6174 is, bits shifted out one end are shifted into the opposite end. A value
6175 of @var{SHIFT} greater than zero corresponds to a left shift, a value of
6176 zero corresponds to no shift, and a value less than zero corresponds to
6177 a right shift. The absolute value of @var{SHIFT} must be less than
6178 @var{SIZE}. If the @var{SIZE} argument is omitted, it is taken to be
6179 equivalent to @code{BIT_SIZE(I)}.
6181 @item @emph{Standard}:
6187 @item @emph{Syntax}:
6188 @code{RESULT = ISHFTC(I, SHIFT [, SIZE])}
6190 @item @emph{Arguments}:
6191 @multitable @columnfractions .15 .70
6192 @item @var{I} @tab The type shall be @code{INTEGER(*)}.
6193 @item @var{SHIFT} @tab The type shall be @code{INTEGER(*)}.
6194 @item @var{SIZE} @tab (Optional) The type shall be @code{INTEGER(*)};
6195 the value must be greater than zero and less than or equal to
6199 @item @emph{Return value}:
6200 The return value is of type @code{INTEGER(*)} and of the same kind as
6203 @item @emph{See also}:
6210 @section @code{ISNAN} --- Test for a NaN
6215 @item @emph{Description}:
6216 @code{ISNAN} tests whether a floating-point value is an IEEE
6218 @item @emph{Standard}:
6224 @item @emph{Syntax}:
6227 @item @emph{Arguments}:
6228 @multitable @columnfractions .15 .70
6229 @item @var{X} @tab Variable of the type @code{REAL}.
6233 @item @emph{Return value}:
6234 Returns a default-kind @code{LOGICAL}. The returned value is @code{TRUE}
6235 if @var{X} is a NaN and @code{FALSE} otherwise.
6237 @item @emph{Example}:
6244 if (isnan(x)) stop '"x" is a NaN'
6245 end program test_nan
6252 @section @code{ITIME} --- Get current local time subroutine (hour/minutes/seconds)
6254 @cindex time, current
6255 @cindex current time
6258 @item @emph{Description}:
6259 @code{IDATE(TARRAY)} Fills @var{TARRAY} with the numerical values at the
6260 current local time. The hour (in the range 1-24), minute (in the range 1-60),
6261 and seconds (in the range 1-60) appear in elements 1, 2, and 3 of @var{TARRAY},
6264 @item @emph{Standard}:
6270 @item @emph{Syntax}:
6271 @code{CALL ITIME(TARRAY)}
6273 @item @emph{Arguments}:
6274 @multitable @columnfractions .15 .70
6275 @item @var{TARRAY} @tab The type shall be @code{INTEGER, DIMENSION(3)}
6276 and the kind shall be the default integer kind.
6279 @item @emph{Return value}:
6283 @item @emph{Example}:
6286 integer, dimension(3) :: tarray
6291 end program test_itime
6298 @section @code{KILL} --- Send a signal to a process
6302 @item @emph{Description}:
6303 @item @emph{Standard}:
6304 Sends the signal specified by @var{SIGNAL} to the process @var{PID}.
6307 This intrinsic is provided in both subroutine and function forms; however,
6308 only one form can be used in any given program unit.
6311 Subroutine, function
6313 @item @emph{Syntax}:
6314 @code{CALL KILL(PID, SIGNAL [, STATUS])}
6316 @item @emph{Arguments}:
6317 @multitable @columnfractions .15 .70
6318 @item @var{PID} @tab Shall be a scalar @code{INTEGER}, with
6320 @item @var{SIGNAL} @tab Shall be a scalar @code{INTEGER}, with
6322 @item @var{STATUS} @tab (Optional) status flag of type @code{INTEGER(4)} or
6323 @code{INTEGER(8)}. Returns 0 on success, or a
6324 system-specific error code otherwise.
6327 @item @emph{See also}:
6328 @ref{ABORT}, @ref{EXIT}
6334 @section @code{KIND} --- Kind of an entity
6339 @item @emph{Description}:
6340 @code{KIND(X)} returns the kind value of the entity @var{X}.
6342 @item @emph{Standard}:
6348 @item @emph{Syntax}:
6351 @item @emph{Arguments}:
6352 @multitable @columnfractions .15 .70
6353 @item @var{X} @tab Shall be of type @code{LOGICAL}, @code{INTEGER},
6354 @code{REAL}, @code{COMPLEX} or @code{CHARACTER}.
6357 @item @emph{Return value}:
6358 The return value is a scalar of type @code{INTEGER} and of the default
6361 @item @emph{Example}:
6364 integer,parameter :: kc = kind(' ')
6365 integer,parameter :: kl = kind(.true.)
6367 print *, "The default character kind is ", kc
6368 print *, "The default logical kind is ", kl
6369 end program test_kind
6377 @section @code{LBOUND} --- Lower dimension bounds of an array
6379 @cindex array, lower bound
6382 @item @emph{Description}:
6383 Returns the lower bounds of an array, or a single lower bound
6384 along the @var{DIM} dimension.
6385 @item @emph{Standard}:
6391 @item @emph{Syntax}:
6392 @code{RESULT = LBOUND(ARRAY [, DIM [, KIND]])}
6394 @item @emph{Arguments}:
6395 @multitable @columnfractions .15 .70
6396 @item @var{ARRAY} @tab Shall be an array, of any type.
6397 @item @var{DIM} @tab (Optional) Shall be a scalar @code{INTEGER(*)}.
6398 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
6399 expression indicating the kind parameter of
6403 @item @emph{Return value}:
6404 The return value is of type @code{INTEGER} and of kind @var{KIND}. If
6405 @var{KIND} is absent, the return value is of default integer kind.
6406 If @var{DIM} is absent, the result is an array of the lower bounds of
6407 @var{ARRAY}. If @var{DIM} is present, the result is a scalar
6408 corresponding to the lower bound of the array along that dimension. If
6409 @var{ARRAY} is an expression rather than a whole array or array
6410 structure component, or if it has a zero extent along the relevant
6411 dimension, the lower bound is taken to be 1.
6413 @item @emph{See also}:
6420 @section @code{LEN} --- Length of a character entity
6422 @cindex string, length
6425 @item @emph{Description}:
6426 Returns the length of a character string. If @var{STRING} is an array,
6427 the length of an element of @var{STRING} is returned. Note that
6428 @var{STRING} need not be defined when this intrinsic is invoked, since
6429 only the length, not the content, of @var{STRING} is needed.
6431 @item @emph{Standard}:
6437 @item @emph{Syntax}:
6438 @code{L = LEN(STRING [, KIND])}
6440 @item @emph{Arguments}:
6441 @multitable @columnfractions .15 .70
6442 @item @var{STRING} @tab Shall be a scalar or array of type
6443 @code{CHARACTER(*)}, with @code{INTENT(IN)}
6444 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
6445 expression indicating the kind parameter of
6449 @item @emph{Return value}:
6450 The return value is of type @code{INTEGER} and of kind @var{KIND}. If
6451 @var{KIND} is absent, the return value is of default integer kind.
6453 @item @emph{See also}:
6454 @ref{LEN_TRIM}, @ref{ADJUSTL}, @ref{ADJUSTR}
6460 @section @code{LEN_TRIM} --- Length of a character entity without trailing blank characters
6462 @cindex string, length, without trailing whitespace
6465 @item @emph{Description}:
6466 Returns the length of a character string, ignoring any trailing blanks.
6468 @item @emph{Standard}:
6474 @item @emph{Syntax}:
6475 @code{RESULT = LEN_TRIM(STRING [, KIND])}
6477 @item @emph{Arguments}:
6478 @multitable @columnfractions .15 .70
6479 @item @var{STRING} @tab Shall be a scalar of type @code{CHARACTER(*)},
6480 with @code{INTENT(IN)}
6481 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
6482 expression indicating the kind parameter of
6486 @item @emph{Return value}:
6487 The return value is of type @code{INTEGER} and of kind @var{KIND}. If
6488 @var{KIND} is absent, the return value is of default integer kind.
6490 @item @emph{See also}:
6491 @ref{LEN}, @ref{ADJUSTL}, @ref{ADJUSTR}
6497 @section @code{LOG_GAMMA} --- Logarithm of the Gamma function
6502 @cindex Gamma function, logarithm of
6505 @item @emph{Description}:
6506 @code{LOG_GAMMA(X)} computes the natural logarithm of the absolute value
6507 of the Gamma (@math{\Gamma}) function.
6509 @item @emph{Standard}:
6510 Fortran 2008 and later
6515 @item @emph{Syntax}:
6516 @code{X = LOG_GAMMA(X)}
6518 @item @emph{Arguments}:
6519 @multitable @columnfractions .15 .70
6520 @item @var{X} @tab Shall be of type @code{REAL} and neither zero
6521 nor a negative integer.
6524 @item @emph{Return value}:
6525 The return value is of type @code{REAL} of the same kind as @var{X}.
6527 @item @emph{Example}:
6529 program test_log_gamma
6531 x = lgamma(x) ! returns 0.0
6532 end program test_log_gamma
6535 @item @emph{Specific names}:
6536 @multitable @columnfractions .20 .20 .20 .25
6537 @item Name @tab Argument @tab Return type @tab Standard
6538 @item @code{LGAMMA(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab GNU Extension
6539 @item @code{ALGAMA(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab GNU Extension
6540 @item @code{DLGAMA(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU Extension
6543 @item @emph{See also}:
6544 Gamma function: @ref{GAMMA}
6551 @section @code{LGE} --- Lexical greater than or equal
6553 @cindex lexical comparison of strings
6554 @cindex string, comparison
6557 @item @emph{Description}:
6558 Determines whether one string is lexically greater than or equal to
6559 another string, where the two strings are interpreted as containing
6560 ASCII character codes. If the String A and String B are not the same
6561 length, the shorter is compared as if spaces were appended to it to form
6562 a value that has the same length as the longer.
6564 In general, the lexical comparison intrinsics @code{LGE}, @code{LGT},
6565 @code{LLE}, and @code{LLT} differ from the corresponding intrinsic
6566 operators @code{.GE.}, @code{.GT.}, @code{.LE.}, and @code{.LT.}, in
6567 that the latter use the processor's character ordering (which is not
6568 ASCII on some targets), whereas the former always use the ASCII
6571 @item @emph{Standard}:
6577 @item @emph{Syntax}:
6578 @code{RESULT = LGE(STRING_A, STRING_B)}
6580 @item @emph{Arguments}:
6581 @multitable @columnfractions .15 .70
6582 @item @var{STRING_A} @tab Shall be of default @code{CHARACTER} type.
6583 @item @var{STRING_B} @tab Shall be of default @code{CHARACTER} type.
6586 @item @emph{Return value}:
6587 Returns @code{.TRUE.} if @code{STRING_A >= STRING_B}, and @code{.FALSE.}
6588 otherwise, based on the ASCII ordering.
6590 @item @emph{See also}:
6591 @ref{LGT}, @ref{LLE}, @ref{LLT}
6597 @section @code{LGT} --- Lexical greater than
6599 @cindex lexical comparison of strings
6600 @cindex string, comparison
6603 @item @emph{Description}:
6604 Determines whether one string is lexically greater than another string,
6605 where the two strings are interpreted as containing ASCII character
6606 codes. If the String A and String B are not the same length, the
6607 shorter is compared as if spaces were appended to it to form a value
6608 that has the same length as the longer.
6610 In general, the lexical comparison intrinsics @code{LGE}, @code{LGT},
6611 @code{LLE}, and @code{LLT} differ from the corresponding intrinsic
6612 operators @code{.GE.}, @code{.GT.}, @code{.LE.}, and @code{.LT.}, in
6613 that the latter use the processor's character ordering (which is not
6614 ASCII on some targets), whereas the former always use the ASCII
6617 @item @emph{Standard}:
6623 @item @emph{Syntax}:
6624 @code{RESULT = LGT(STRING_A, STRING_B)}
6626 @item @emph{Arguments}:
6627 @multitable @columnfractions .15 .70
6628 @item @var{STRING_A} @tab Shall be of default @code{CHARACTER} type.
6629 @item @var{STRING_B} @tab Shall be of default @code{CHARACTER} type.
6632 @item @emph{Return value}:
6633 Returns @code{.TRUE.} if @code{STRING_A > STRING_B}, and @code{.FALSE.}
6634 otherwise, based on the ASCII ordering.
6636 @item @emph{See also}:
6637 @ref{LGE}, @ref{LLE}, @ref{LLT}
6643 @section @code{LINK} --- Create a hard link
6645 @cindex file system, create link
6646 @cindex file system, hard link
6649 @item @emph{Description}:
6650 Makes a (hard) link from file @var{PATH1} to @var{PATH2}. A null
6651 character (@code{CHAR(0)}) can be used to mark the end of the names in
6652 @var{PATH1} and @var{PATH2}; otherwise, trailing blanks in the file
6653 names are ignored. If the @var{STATUS} argument is supplied, it
6654 contains 0 on success or a nonzero error code upon return; see
6657 This intrinsic is provided in both subroutine and function forms;
6658 however, only one form can be used in any given program unit.
6660 @item @emph{Standard}:
6664 Subroutine, function
6666 @item @emph{Syntax}:
6667 @multitable @columnfractions .80
6668 @item @code{CALL LINK(PATH1, PATH2 [, STATUS])}
6669 @item @code{STATUS = LINK(PATH1, PATH2)}
6672 @item @emph{Arguments}:
6673 @multitable @columnfractions .15 .70
6674 @item @var{PATH1} @tab Shall be of default @code{CHARACTER} type.
6675 @item @var{PATH2} @tab Shall be of default @code{CHARACTER} type.
6676 @item @var{STATUS} @tab (Optional) Shall be of default @code{INTEGER} type.
6679 @item @emph{See also}:
6680 @ref{SYMLNK}, @ref{UNLINK}
6686 @section @code{LLE} --- Lexical less than or equal
6688 @cindex lexical comparison of strings
6689 @cindex string, comparison
6692 @item @emph{Description}:
6693 Determines whether one string is lexically less than or equal to another
6694 string, where the two strings are interpreted as containing ASCII
6695 character codes. If the String A and String B are not the same length,
6696 the shorter is compared as if spaces were appended to it to form a value
6697 that has the same length as the longer.
6699 In general, the lexical comparison intrinsics @code{LGE}, @code{LGT},
6700 @code{LLE}, and @code{LLT} differ from the corresponding intrinsic
6701 operators @code{.GE.}, @code{.GT.}, @code{.LE.}, and @code{.LT.}, in
6702 that the latter use the processor's character ordering (which is not
6703 ASCII on some targets), whereas the former always use the ASCII
6706 @item @emph{Standard}:
6712 @item @emph{Syntax}:
6713 @code{RESULT = LLE(STRING_A, STRING_B)}
6715 @item @emph{Arguments}:
6716 @multitable @columnfractions .15 .70
6717 @item @var{STRING_A} @tab Shall be of default @code{CHARACTER} type.
6718 @item @var{STRING_B} @tab Shall be of default @code{CHARACTER} type.
6721 @item @emph{Return value}:
6722 Returns @code{.TRUE.} if @code{STRING_A <= STRING_B}, and @code{.FALSE.}
6723 otherwise, based on the ASCII ordering.
6725 @item @emph{See also}:
6726 @ref{LGE}, @ref{LGT}, @ref{LLT}
6732 @section @code{LLT} --- Lexical less than
6734 @cindex lexical comparison of strings
6735 @cindex string, comparison
6738 @item @emph{Description}:
6739 Determines whether one string is lexically less than another string,
6740 where the two strings are interpreted as containing ASCII character
6741 codes. If the String A and String B are not the same length, the
6742 shorter is compared as if spaces were appended to it to form a value
6743 that has the same length as the longer.
6745 In general, the lexical comparison intrinsics @code{LGE}, @code{LGT},
6746 @code{LLE}, and @code{LLT} differ from the corresponding intrinsic
6747 operators @code{.GE.}, @code{.GT.}, @code{.LE.}, and @code{.LT.}, in
6748 that the latter use the processor's character ordering (which is not
6749 ASCII on some targets), whereas the former always use the ASCII
6752 @item @emph{Standard}:
6758 @item @emph{Syntax}:
6759 @code{RESULT = LLT(STRING_A, STRING_B)}
6761 @item @emph{Arguments}:
6762 @multitable @columnfractions .15 .70
6763 @item @var{STRING_A} @tab Shall be of default @code{CHARACTER} type.
6764 @item @var{STRING_B} @tab Shall be of default @code{CHARACTER} type.
6767 @item @emph{Return value}:
6768 Returns @code{.TRUE.} if @code{STRING_A < STRING_B}, and @code{.FALSE.}
6769 otherwise, based on the ASCII ordering.
6771 @item @emph{See also}:
6772 @ref{LGE}, @ref{LGT}, @ref{LLE}
6778 @section @code{LNBLNK} --- Index of the last non-blank character in a string
6780 @cindex string, find non-blank character
6783 @item @emph{Description}:
6784 Returns the length of a character string, ignoring any trailing blanks.
6785 This is identical to the standard @code{LEN_TRIM} intrinsic, and is only
6786 included for backwards compatibility.
6788 @item @emph{Standard}:
6794 @item @emph{Syntax}:
6795 @code{RESULT = LNBLNK(STRING)}
6797 @item @emph{Arguments}:
6798 @multitable @columnfractions .15 .70
6799 @item @var{STRING} @tab Shall be a scalar of type @code{CHARACTER(*)},
6800 with @code{INTENT(IN)}
6803 @item @emph{Return value}:
6804 The return value is of @code{INTEGER(kind=4)} type.
6806 @item @emph{See also}:
6807 @ref{INDEX intrinsic}, @ref{LEN_TRIM}
6813 @section @code{LOC} --- Returns the address of a variable
6815 @cindex location of a variable in memory
6818 @item @emph{Description}:
6819 @code{LOC(X)} returns the address of @var{X} as an integer.
6821 @item @emph{Standard}:
6827 @item @emph{Syntax}:
6828 @code{RESULT = LOC(X)}
6830 @item @emph{Arguments}:
6831 @multitable @columnfractions .15 .70
6832 @item @var{X} @tab Variable of any type.
6835 @item @emph{Return value}:
6836 The return value is of type @code{INTEGER}, with a @code{KIND}
6837 corresponding to the size (in bytes) of a memory address on the target
6840 @item @emph{Example}:
6847 end program test_loc
6854 @section @code{LOG} --- Logarithm function
6861 @cindex exponential function, inverse
6862 @cindex logarithmic function
6865 @item @emph{Description}:
6866 @code{LOG(X)} computes the logarithm of @var{X}.
6868 @item @emph{Standard}:
6874 @item @emph{Syntax}:
6875 @code{RESULT = LOG(X)}
6877 @item @emph{Arguments}:
6878 @multitable @columnfractions .15 .70
6879 @item @var{X} @tab The type shall be @code{REAL(*)} or
6883 @item @emph{Return value}:
6884 The return value is of type @code{REAL(*)} or @code{COMPLEX(*)}.
6885 The kind type parameter is the same as @var{X}.
6887 @item @emph{Example}:
6890 real(8) :: x = 1.0_8
6891 complex :: z = (1.0, 2.0)
6894 end program test_log
6897 @item @emph{Specific names}:
6898 @multitable @columnfractions .20 .20 .20 .25
6899 @item Name @tab Argument @tab Return type @tab Standard
6900 @item @code{ALOG(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab f95, gnu
6901 @item @code{DLOG(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab f95, gnu
6902 @item @code{CLOG(X)} @tab @code{COMPLEX(4) X} @tab @code{COMPLEX(4)} @tab f95, gnu
6903 @item @code{ZLOG(X)} @tab @code{COMPLEX(8) X} @tab @code{COMPLEX(8)} @tab f95, gnu
6904 @item @code{CDLOG(X)} @tab @code{COMPLEX(8) X} @tab @code{COMPLEX(8)} @tab f95, gnu
6911 @section @code{LOG10} --- Base 10 logarithm function
6915 @cindex exponential function, inverse
6916 @cindex logarithmic function
6919 @item @emph{Description}:
6920 @code{LOG10(X)} computes the base 10 logarithm of @var{X}.
6922 @item @emph{Standard}:
6928 @item @emph{Syntax}:
6929 @code{RESULT = LOG10(X)}
6931 @item @emph{Arguments}:
6932 @multitable @columnfractions .15 .70
6933 @item @var{X} @tab The type shall be @code{REAL(*)}.
6936 @item @emph{Return value}:
6937 The return value is of type @code{REAL(*)} or @code{COMPLEX(*)}.
6938 The kind type parameter is the same as @var{X}.
6940 @item @emph{Example}:
6943 real(8) :: x = 10.0_8
6945 end program test_log10
6948 @item @emph{Specific names}:
6949 @multitable @columnfractions .20 .20 .20 .25
6950 @item Name @tab Argument @tab Return type @tab Standard
6951 @item @code{ALOG10(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab F95 and later
6952 @item @code{DLOG10(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab F95 and later
6959 @section @code{LOGICAL} --- Convert to logical type
6961 @cindex conversion, to logical
6964 @item @emph{Description}:
6965 Converts one kind of @code{LOGICAL} variable to another.
6967 @item @emph{Standard}:
6973 @item @emph{Syntax}:
6974 @code{RESULT = LOGICAL(L [, KIND])}
6976 @item @emph{Arguments}:
6977 @multitable @columnfractions .15 .70
6978 @item @var{L} @tab The type shall be @code{LOGICAL(*)}.
6979 @item @var{KIND} @tab (Optional) An @code{INTEGER(*)} initialization
6980 expression indicating the kind parameter of
6984 @item @emph{Return value}:
6985 The return value is a @code{LOGICAL} value equal to @var{L}, with a
6986 kind corresponding to @var{KIND}, or of the default logical kind if
6987 @var{KIND} is not given.
6989 @item @emph{See also}:
6990 @ref{INT}, @ref{REAL}, @ref{CMPLX}
6996 @section @code{LONG} --- Convert to integer type
6998 @cindex conversion, to integer
7001 @item @emph{Description}:
7002 Convert to a @code{KIND=4} integer type, which is the same size as a C
7003 @code{long} integer. This is equivalent to the standard @code{INT}
7004 intrinsic with an optional argument of @code{KIND=4}, and is only
7005 included for backwards compatibility.
7007 @item @emph{Standard}:
7013 @item @emph{Syntax}:
7014 @code{RESULT = LONG(A)}
7016 @item @emph{Arguments}:
7017 @multitable @columnfractions .15 .70
7018 @item @var{A} @tab Shall be of type @code{INTEGER(*)},
7019 @code{REAL(*)}, or @code{COMPLEX(*)}.
7022 @item @emph{Return value}:
7023 The return value is a @code{INTEGER(4)} variable.
7025 @item @emph{See also}:
7026 @ref{INT}, @ref{INT2}, @ref{INT8}
7032 @section @code{LSHIFT} --- Left shift bits
7034 @cindex bits, shift left
7037 @item @emph{Description}:
7038 @code{LSHIFT} returns a value corresponding to @var{I} with all of the
7039 bits shifted left by @var{SHIFT} places. If the absolute value of
7040 @var{SHIFT} is greater than @code{BIT_SIZE(I)}, the value is undefined.
7041 Bits shifted out from the left end are lost; zeros are shifted in from
7044 This function has been superseded by the @code{ISHFT} intrinsic, which
7045 is standard in Fortran 95 and later.
7047 @item @emph{Standard}:
7053 @item @emph{Syntax}:
7054 @code{RESULT = LSHIFT(I, SHIFT)}
7056 @item @emph{Arguments}:
7057 @multitable @columnfractions .15 .70
7058 @item @var{I} @tab The type shall be @code{INTEGER(*)}.
7059 @item @var{SHIFT} @tab The type shall be @code{INTEGER(*)}.
7062 @item @emph{Return value}:
7063 The return value is of type @code{INTEGER(*)} and of the same kind as
7066 @item @emph{See also}:
7067 @ref{ISHFT}, @ref{ISHFTC}, @ref{RSHIFT}
7074 @section @code{LSTAT} --- Get file status
7076 @cindex file system, file status
7079 @item @emph{Description}:
7080 @code{LSTAT} is identical to @ref{STAT}, except that if path is a symbolic link,
7081 then the link itself is statted, not the file that it refers to.
7083 The elements in @code{BUFF} are the same as described by @ref{STAT}.
7085 This intrinsic is provided in both subroutine and function forms; however,
7086 only one form can be used in any given program unit.
7088 @item @emph{Standard}:
7092 Subroutine, function
7094 @item @emph{Syntax}:
7095 @code{CALL LSTAT(FILE, BUFF [, STATUS])}
7097 @item @emph{Arguments}:
7098 @multitable @columnfractions .15 .70
7099 @item @var{FILE} @tab The type shall be @code{CHARACTER(*)}, a valid path within the file system.
7100 @item @var{BUFF} @tab The type shall be @code{INTEGER(4), DIMENSION(13)}.
7101 @item @var{STATUS} @tab (Optional) status flag of type @code{INTEGER(4)}. Returns 0
7102 on success and a system specific error code otherwise.
7105 @item @emph{Example}:
7106 See @ref{STAT} for an example.
7108 @item @emph{See also}:
7109 To stat an open file: @ref{FSTAT}, to stat a file: @ref{STAT}
7115 @section @code{LTIME} --- Convert time to local time info
7117 @cindex time, conversion to local time info
7120 @item @emph{Description}:
7121 Given a system time value @var{STIME} (as provided by the @code{TIME8()}
7122 intrinsic), fills @var{TARRAY} with values extracted from it appropriate
7123 to the local time zone using @code{localtime(3)}.
7125 @item @emph{Standard}:
7131 @item @emph{Syntax}:
7132 @code{CALL LTIME(STIME, TARRAY)}
7134 @item @emph{Arguments}:
7135 @multitable @columnfractions .15 .70
7136 @item @var{STIME} @tab An @code{INTEGER(*)} scalar expression
7137 corresponding to a system time, with
7139 @item @var{TARRAY} @tab A default @code{INTEGER} array with 9 elements,
7140 with @code{INTENT(OUT)}.
7143 @item @emph{Return value}:
7144 The elements of @var{TARRAY} are assigned as follows:
7146 @item Seconds after the minute, range 0--59 or 0--61 to allow for leap
7148 @item Minutes after the hour, range 0--59
7149 @item Hours past midnight, range 0--23
7150 @item Day of month, range 0--31
7151 @item Number of months since January, range 0--12
7152 @item Years since 1900
7153 @item Number of days since Sunday, range 0--6
7154 @item Days since January 1
7155 @item Daylight savings indicator: positive if daylight savings is in
7156 effect, zero if not, and negative if the information is not
7160 @item @emph{See also}:
7161 @ref{CTIME}, @ref{GMTIME}, @ref{TIME}, @ref{TIME8}
7168 @section @code{MALLOC} --- Allocate dynamic memory
7170 @cindex pointer, cray
7173 @item @emph{Description}:
7174 @code{MALLOC(SIZE)} allocates @var{SIZE} bytes of dynamic memory and
7175 returns the address of the allocated memory. The @code{MALLOC} intrinsic
7176 is an extension intended to be used with Cray pointers, and is provided
7177 in GNU Fortran to allow the user to compile legacy code. For new code
7178 using Fortran 95 pointers, the memory allocation intrinsic is
7181 @item @emph{Standard}:
7187 @item @emph{Syntax}:
7188 @code{PTR = MALLOC(SIZE)}
7190 @item @emph{Arguments}:
7191 @multitable @columnfractions .15 .70
7192 @item @var{SIZE} @tab The type shall be @code{INTEGER(*)}.
7195 @item @emph{Return value}:
7196 The return value is of type @code{INTEGER(K)}, with @var{K} such that
7197 variables of type @code{INTEGER(K)} have the same size as
7198 C pointers (@code{sizeof(void *)}).
7200 @item @emph{Example}:
7201 The following example demonstrates the use of @code{MALLOC} and
7202 @code{FREE} with Cray pointers. This example is intended to run on
7203 32-bit systems, where the default integer kind is suitable to store
7204 pointers; on 64-bit systems, ptr_x would need to be declared as
7205 @code{integer(kind=8)}.
7214 ptr_x = malloc(20*8)
7216 x(i) = sqrt(1.0d0 / i)
7224 end program test_malloc
7227 @item @emph{See also}:
7234 @section @code{MATMUL} --- matrix multiplication
7236 @cindex matrix multiplication
7237 @cindex product, matrix
7240 @item @emph{Description}:
7241 Performs a matrix multiplication on numeric or logical arguments.
7243 @item @emph{Standard}:
7247 Transformational function
7249 @item @emph{Syntax}:
7250 @code{RESULT = MATMUL(MATRIX_A, MATRIX_B)}
7252 @item @emph{Arguments}:
7253 @multitable @columnfractions .15 .70
7254 @item @var{MATRIX_A} @tab An array of @code{INTEGER(*)},
7255 @code{REAL(*)}, @code{COMPLEX(*)}, or
7256 @code{LOGICAL(*)} type, with a rank of
7258 @item @var{MATRIX_B} @tab An array of @code{INTEGER(*)},
7259 @code{REAL(*)}, or @code{COMPLEX(*)} type if
7260 @var{MATRIX_A} is of a numeric type;
7261 otherwise, an array of @code{LOGICAL(*)}
7262 type. The rank shall be one or two, and the
7263 first (or only) dimension of @var{MATRIX_B}
7264 shall be equal to the last (or only)
7265 dimension of @var{MATRIX_A}.
7268 @item @emph{Return value}:
7269 The matrix product of @var{MATRIX_A} and @var{MATRIX_B}. The type and
7270 kind of the result follow the usual type and kind promotion rules, as
7271 for the @code{*} or @code{.AND.} operators.
7273 @item @emph{See also}:
7279 @section @code{MAX} --- Maximum value of an argument list
7286 @cindex maximum value
7289 @item @emph{Description}:
7290 Returns the argument with the largest (most positive) value.
7292 @item @emph{Standard}:
7298 @item @emph{Syntax}:
7299 @code{RESULT = MAX(A1, A2 [, A3 [, ...]])}
7301 @item @emph{Arguments}:
7302 @multitable @columnfractions .15 .70
7303 @item @var{A1} @tab The type shall be @code{INTEGER(*)} or
7305 @item @var{A2}, @var{A3}, ... @tab An expression of the same type and kind
7306 as @var{A1}. (As a GNU extension,
7307 arguments of different kinds are
7311 @item @emph{Return value}:
7312 The return value corresponds to the maximum value among the arguments,
7313 and has the same type and kind as the first argument.
7315 @item @emph{Specific names}:
7316 @multitable @columnfractions .20 .20 .20 .25
7317 @item Name @tab Argument @tab Return type @tab Standard
7318 @item @code{MAX0(I)} @tab @code{INTEGER(4) I} @tab @code{INTEGER(4)} @tab F77 and later
7319 @item @code{AMAX0(I)} @tab @code{INTEGER(4) I} @tab @code{REAL(MAX(X))} @tab F77 and later
7320 @item @code{MAX1(X)} @tab @code{REAL(*) X} @tab @code{INT(MAX(X))} @tab F77 and later
7321 @item @code{AMAX1(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab F77 and later
7322 @item @code{DMAX1(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab F77 and later
7325 @item @emph{See also}:
7326 @ref{MAXLOC} @ref{MAXVAL}, @ref{MIN}
7333 @section @code{MAXEXPONENT} --- Maximum exponent of a real kind
7334 @fnindex MAXEXPONENT
7335 @cindex model representation, maximum exponent
7338 @item @emph{Description}:
7339 @code{MAXEXPONENT(X)} returns the maximum exponent in the model of the
7342 @item @emph{Standard}:
7348 @item @emph{Syntax}:
7349 @code{RESULT = MAXEXPONENT(X)}
7351 @item @emph{Arguments}:
7352 @multitable @columnfractions .15 .70
7353 @item @var{X} @tab Shall be of type @code{REAL}.
7356 @item @emph{Return value}:
7357 The return value is of type @code{INTEGER} and of the default integer
7360 @item @emph{Example}:
7366 print *, minexponent(x), maxexponent(x)
7367 print *, minexponent(y), maxexponent(y)
7368 end program exponents
7375 @section @code{MAXLOC} --- Location of the maximum value within an array
7377 @cindex array, location of maximum element
7380 @item @emph{Description}:
7381 Determines the location of the element in the array with the maximum
7382 value, or, if the @var{DIM} argument is supplied, determines the
7383 locations of the maximum element along each row of the array in the
7384 @var{DIM} direction. If @var{MASK} is present, only the elements for
7385 which @var{MASK} is @code{.TRUE.} are considered. If more than one
7386 element in the array has the maximum value, the location returned is
7387 that of the first such element in array element order. If the array has
7388 zero size, or all of the elements of @var{MASK} are @code{.FALSE.}, then
7389 the result is an array of zeroes. Similarly, if @var{DIM} is supplied
7390 and all of the elements of @var{MASK} along a given row are zero, the
7391 result value for that row is zero.
7393 @item @emph{Standard}:
7397 Transformational function
7399 @item @emph{Syntax}:
7400 @multitable @columnfractions .80
7401 @item @code{RESULT = MAXLOC(ARRAY, DIM [, MASK])}
7402 @item @code{RESULT = MAXLOC(ARRAY [, MASK])}
7405 @item @emph{Arguments}:
7406 @multitable @columnfractions .15 .70
7407 @item @var{ARRAY} @tab Shall be an array of type @code{INTEGER(*)},
7408 @code{REAL(*)}, or @code{CHARACTER(*)}.
7409 @item @var{DIM} @tab (Optional) Shall be a scalar of type
7410 @code{INTEGER(*)}, with a value between one
7411 and the rank of @var{ARRAY}, inclusive. It
7412 may not be an optional dummy argument.
7413 @item @var{MASK} @tab Shall be an array of type @code{LOGICAL(*)},
7414 and conformable with @var{ARRAY}.
7417 @item @emph{Return value}:
7418 If @var{DIM} is absent, the result is a rank-one array with a length
7419 equal to the rank of @var{ARRAY}. If @var{DIM} is present, the result
7420 is an array with a rank one less than the rank of @var{ARRAY}, and a
7421 size corresponding to the size of @var{ARRAY} with the @var{DIM}
7422 dimension removed. If @var{DIM} is present and @var{ARRAY} has a rank
7423 of one, the result is a scalar. In all cases, the result is of default
7424 @code{INTEGER} type.
7426 @item @emph{See also}:
7427 @ref{MAX}, @ref{MAXVAL}
7434 @section @code{MAXVAL} --- Maximum value of an array
7436 @cindex array, maximum value
7437 @cindex maximum value
7440 @item @emph{Description}:
7441 Determines the maximum value of the elements in an array value, or, if
7442 the @var{DIM} argument is supplied, determines the maximum value along
7443 each row of the array in the @var{DIM} direction. If @var{MASK} is
7444 present, only the elements for which @var{MASK} is @code{.TRUE.} are
7445 considered. If the array has zero size, or all of the elements of
7446 @var{MASK} are @code{.FALSE.}, then the result is the most negative
7447 number of the type and kind of @var{ARRAY} if @var{ARRAY} is numeric, or
7448 a string of nulls if @var{ARRAY} is of character type.
7450 @item @emph{Standard}:
7454 Transformational function
7456 @item @emph{Syntax}:
7457 @multitable @columnfractions .80
7458 @item @code{RESULT = MAXVAL(ARRAY, DIM [, MASK])}
7459 @item @code{RESULT = MAXVAL(ARRAY [, MASK])}
7462 @item @emph{Arguments}:
7463 @multitable @columnfractions .15 .70
7464 @item @var{ARRAY} @tab Shall be an array of type @code{INTEGER(*)},
7465 @code{REAL(*)}, or @code{CHARACTER(*)}.
7466 @item @var{DIM} @tab (Optional) Shall be a scalar of type
7467 @code{INTEGER(*)}, with a value between one
7468 and the rank of @var{ARRAY}, inclusive. It
7469 may not be an optional dummy argument.
7470 @item @var{MASK} @tab Shall be an array of type @code{LOGICAL(*)},
7471 and conformable with @var{ARRAY}.
7474 @item @emph{Return value}:
7475 If @var{DIM} is absent, or if @var{ARRAY} has a rank of one, the result
7476 is a scalar. If @var{DIM} is present, the result is an array with a
7477 rank one less than the rank of @var{ARRAY}, and a size corresponding to
7478 the size of @var{ARRAY} with the @var{DIM} dimension removed. In all
7479 cases, the result is of the same type and kind as @var{ARRAY}.
7481 @item @emph{See also}:
7482 @ref{MAX}, @ref{MAXLOC}
7488 @section @code{MCLOCK} --- Time function
7490 @cindex time, clock ticks
7494 @item @emph{Description}:
7495 Returns the number of clock ticks since the start of the process, based
7496 on the UNIX function @code{clock(3)}.
7498 This intrinsic is not fully portable, such as to systems with 32-bit
7499 @code{INTEGER} types but supporting times wider than 32 bits. Therefore,
7500 the values returned by this intrinsic might be, or become, negative, or
7501 numerically less than previous values, during a single run of the
7504 @item @emph{Standard}:
7510 @item @emph{Syntax}:
7511 @code{RESULT = MCLOCK()}
7513 @item @emph{Return value}:
7514 The return value is a scalar of type @code{INTEGER(4)}, equal to the
7515 number of clock ticks since the start of the process, or @code{-1} if
7516 the system does not support @code{clock(3)}.
7518 @item @emph{See also}:
7519 @ref{CTIME}, @ref{GMTIME}, @ref{LTIME}, @ref{MCLOCK}, @ref{TIME}
7526 @section @code{MCLOCK8} --- Time function (64-bit)
7528 @cindex time, clock ticks
7532 @item @emph{Description}:
7533 Returns the number of clock ticks since the start of the process, based
7534 on the UNIX function @code{clock(3)}.
7536 @emph{Warning:} this intrinsic does not increase the range of the timing
7537 values over that returned by @code{clock(3)}. On a system with a 32-bit
7538 @code{clock(3)}, @code{MCLOCK8()} will return a 32-bit value, even though
7539 it is converted to a 64-bit @code{INTEGER(8)} value. That means
7540 overflows of the 32-bit value can still occur. Therefore, the values
7541 returned by this intrinsic might be or become negative or numerically
7542 less than previous values during a single run of the compiled program.
7544 @item @emph{Standard}:
7550 @item @emph{Syntax}:
7551 @code{RESULT = MCLOCK8()}
7553 @item @emph{Return value}:
7554 The return value is a scalar of type @code{INTEGER(8)}, equal to the
7555 number of clock ticks since the start of the process, or @code{-1} if
7556 the system does not support @code{clock(3)}.
7558 @item @emph{See also}:
7559 @ref{CTIME}, @ref{GMTIME}, @ref{LTIME}, @ref{MCLOCK}, @ref{TIME8}
7566 @section @code{MERGE} --- Merge variables
7568 @cindex array, merge arrays
7569 @cindex array, combine arrays
7572 @item @emph{Description}:
7573 Select values from two arrays according to a logical mask. The result
7574 is equal to @var{TSOURCE} if @var{MASK} is @code{.TRUE.}, or equal to
7575 @var{FSOURCE} if it is @code{.FALSE.}.
7577 @item @emph{Standard}:
7583 @item @emph{Syntax}:
7584 @code{RESULT = MERGE(TSOURCE, FSOURCE, MASK)}
7586 @item @emph{Arguments}:
7587 @multitable @columnfractions .15 .70
7588 @item @var{TSOURCE} @tab May be of any type.
7589 @item @var{FSOURCE} @tab Shall be of the same type and type parameters
7591 @item @var{MASK} @tab Shall be of type @code{LOGICAL(*)}.
7594 @item @emph{Return value}:
7595 The result is of the same type and type parameters as @var{TSOURCE}.
7602 @section @code{MIN} --- Minimum value of an argument list
7609 @cindex minimum value
7612 @item @emph{Description}:
7613 Returns the argument with the smallest (most negative) value.
7615 @item @emph{Standard}:
7621 @item @emph{Syntax}:
7622 @code{RESULT = MIN(A1, A2 [, A3, ...])}
7624 @item @emph{Arguments}:
7625 @multitable @columnfractions .15 .70
7626 @item @var{A1} @tab The type shall be @code{INTEGER(*)} or
7628 @item @var{A2}, @var{A3}, ... @tab An expression of the same type and kind
7629 as @var{A1}. (As a GNU extension,
7630 arguments of different kinds are
7634 @item @emph{Return value}:
7635 The return value corresponds to the maximum value among the arguments,
7636 and has the same type and kind as the first argument.
7638 @item @emph{Specific names}:
7639 @multitable @columnfractions .20 .20 .20 .25
7640 @item Name @tab Argument @tab Return type @tab Standard
7641 @item @code{MIN0(I)} @tab @code{INTEGER(4) I} @tab @code{INTEGER(4)} @tab F77 and later
7642 @item @code{AMIN0(I)} @tab @code{INTEGER(4) I} @tab @code{REAL(MIN(X))} @tab F77 and later
7643 @item @code{MIN1(X)} @tab @code{REAL(*) X} @tab @code{INT(MIN(X))} @tab F77 and later
7644 @item @code{AMIN1(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab F77 and later
7645 @item @code{DMIN1(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab F77 and later
7648 @item @emph{See also}:
7649 @ref{MAX}, @ref{MINLOC}, @ref{MINVAL}
7655 @section @code{MINEXPONENT} --- Minimum exponent of a real kind
7656 @fnindex MINEXPONENT
7657 @cindex model representation, minimum exponent
7660 @item @emph{Description}:
7661 @code{MINEXPONENT(X)} returns the minimum exponent in the model of the
7664 @item @emph{Standard}:
7670 @item @emph{Syntax}:
7671 @code{RESULT = MINEXPONENT(X)}
7673 @item @emph{Arguments}:
7674 @multitable @columnfractions .15 .70
7675 @item @var{X} @tab Shall be of type @code{REAL}.
7678 @item @emph{Return value}:
7679 The return value is of type @code{INTEGER} and of the default integer
7682 @item @emph{Example}:
7683 See @code{MAXEXPONENT} for an example.
7689 @section @code{MINLOC} --- Location of the minimum value within an array
7691 @cindex array, location of minimum element
7694 @item @emph{Description}:
7695 Determines the location of the element in the array with the minimum
7696 value, or, if the @var{DIM} argument is supplied, determines the
7697 locations of the minimum element along each row of the array in the
7698 @var{DIM} direction. If @var{MASK} is present, only the elements for
7699 which @var{MASK} is @code{.TRUE.} are considered. If more than one
7700 element in the array has the minimum value, the location returned is
7701 that of the first such element in array element order. If the array has
7702 zero size, or all of the elements of @var{MASK} are @code{.FALSE.}, then
7703 the result is an array of zeroes. Similarly, if @var{DIM} is supplied
7704 and all of the elements of @var{MASK} along a given row are zero, the
7705 result value for that row is zero.
7707 @item @emph{Standard}:
7711 Transformational function
7713 @item @emph{Syntax}:
7714 @multitable @columnfractions .80
7715 @item @code{RESULT = MINLOC(ARRAY, DIM [, MASK])}
7716 @item @code{RESULT = MINLOC(ARRAY [, MASK])}
7719 @item @emph{Arguments}:
7720 @multitable @columnfractions .15 .70
7721 @item @var{ARRAY} @tab Shall be an array of type @code{INTEGER(*)},
7722 @code{REAL(*)}, or @code{CHARACTER(*)}.
7723 @item @var{DIM} @tab (Optional) Shall be a scalar of type
7724 @code{INTEGER(*)}, with a value between one
7725 and the rank of @var{ARRAY}, inclusive. It
7726 may not be an optional dummy argument.
7727 @item @var{MASK} @tab Shall be an array of type @code{LOGICAL(*)},
7728 and conformable with @var{ARRAY}.
7731 @item @emph{Return value}:
7732 If @var{DIM} is absent, the result is a rank-one array with a length
7733 equal to the rank of @var{ARRAY}. If @var{DIM} is present, the result
7734 is an array with a rank one less than the rank of @var{ARRAY}, and a
7735 size corresponding to the size of @var{ARRAY} with the @var{DIM}
7736 dimension removed. If @var{DIM} is present and @var{ARRAY} has a rank
7737 of one, the result is a scalar. In all cases, the result is of default
7738 @code{INTEGER} type.
7740 @item @emph{See also}:
7741 @ref{MIN}, @ref{MINVAL}
7748 @section @code{MINVAL} --- Minimum value of an array
7750 @cindex array, minimum value
7751 @cindex minimum value
7754 @item @emph{Description}:
7755 Determines the minimum value of the elements in an array value, or, if
7756 the @var{DIM} argument is supplied, determines the minimum value along
7757 each row of the array in the @var{DIM} direction. If @var{MASK} is
7758 present, only the elements for which @var{MASK} is @code{.TRUE.} are
7759 considered. If the array has zero size, or all of the elements of
7760 @var{MASK} are @code{.FALSE.}, then the result is @code{HUGE(ARRAY)} if
7761 @var{ARRAY} is numeric, or a string of @code{CHAR(255)} characters if
7762 @var{ARRAY} is of character type.
7764 @item @emph{Standard}:
7768 Transformational function
7770 @item @emph{Syntax}:
7771 @multitable @columnfractions .80
7772 @item @code{RESULT = MINVAL(ARRAY, DIM [, MASK])}
7773 @item @code{RESULT = MINVAL(ARRAY [, MASK])}
7776 @item @emph{Arguments}:
7777 @multitable @columnfractions .15 .70
7778 @item @var{ARRAY} @tab Shall be an array of type @code{INTEGER(*)},
7779 @code{REAL(*)}, or @code{CHARACTER(*)}.
7780 @item @var{DIM} @tab (Optional) Shall be a scalar of type
7781 @code{INTEGER(*)}, with a value between one
7782 and the rank of @var{ARRAY}, inclusive. It
7783 may not be an optional dummy argument.
7784 @item @var{MASK} @tab Shall be an array of type @code{LOGICAL(*)},
7785 and conformable with @var{ARRAY}.
7788 @item @emph{Return value}:
7789 If @var{DIM} is absent, or if @var{ARRAY} has a rank of one, the result
7790 is a scalar. If @var{DIM} is present, the result is an array with a
7791 rank one less than the rank of @var{ARRAY}, and a size corresponding to
7792 the size of @var{ARRAY} with the @var{DIM} dimension removed. In all
7793 cases, the result is of the same type and kind as @var{ARRAY}.
7795 @item @emph{See also}:
7796 @ref{MIN}, @ref{MINLOC}
7803 @section @code{MOD} --- Remainder function
7808 @cindex division, remainder
7811 @item @emph{Description}:
7812 @code{MOD(A,P)} computes the remainder of the division of A by P@. It is
7813 calculated as @code{A - (INT(A/P) * P)}.
7815 @item @emph{Standard}:
7821 @item @emph{Syntax}:
7822 @code{RESULT = MOD(A, P)}
7824 @item @emph{Arguments}:
7825 @multitable @columnfractions .15 .70
7826 @item @var{A} @tab Shall be a scalar of type @code{INTEGER} or @code{REAL}
7827 @item @var{P} @tab Shall be a scalar of the same type as @var{A} and not
7831 @item @emph{Return value}:
7832 The kind of the return value is the result of cross-promoting
7833 the kinds of the arguments.
7835 @item @emph{Example}:
7839 print *, mod(17.5,5.5)
7840 print *, mod(17.5d0,5.5)
7841 print *, mod(17.5,5.5d0)
7844 print *, mod(-17.5,5.5)
7845 print *, mod(-17.5d0,5.5)
7846 print *, mod(-17.5,5.5d0)
7849 print *, mod(17.5,-5.5)
7850 print *, mod(17.5d0,-5.5)
7851 print *, mod(17.5,-5.5d0)
7852 end program test_mod
7855 @item @emph{Specific names}:
7856 @multitable @columnfractions .20 .20 .20 .25
7857 @item Name @tab Arguments @tab Return type @tab Standard
7858 @item @code{AMOD(A,P)} @tab @code{REAL(4)} @tab @code{REAL(4)} @tab F95 and later
7859 @item @code{DMOD(A,P)} @tab @code{REAL(8)} @tab @code{REAL(8)} @tab F95 and later
7866 @section @code{MODULO} --- Modulo function
7869 @cindex division, modulo
7872 @item @emph{Description}:
7873 @code{MODULO(A,P)} computes the @var{A} modulo @var{P}.
7875 @item @emph{Standard}:
7881 @item @emph{Syntax}:
7882 @code{RESULT = MODULO(A, P)}
7884 @item @emph{Arguments}:
7885 @multitable @columnfractions .15 .70
7886 @item @var{A} @tab Shall be a scalar of type @code{INTEGER} or @code{REAL}
7887 @item @var{P} @tab Shall be a scalar of the same type and kind as @var{A}
7890 @item @emph{Return value}:
7891 The type and kind of the result are those of the arguments.
7893 @item If @var{A} and @var{P} are of type @code{INTEGER}:
7894 @code{MODULO(A,P)} has the value @var{R} such that @code{A=Q*P+R}, where
7895 @var{Q} is an integer and @var{R} is between 0 (inclusive) and @var{P}
7897 @item If @var{A} and @var{P} are of type @code{REAL}:
7898 @code{MODULO(A,P)} has the value of @code{A - FLOOR (A / P) * P}.
7900 In all cases, if @var{P} is zero the result is processor-dependent.
7902 @item @emph{Example}:
7905 print *, modulo(17,3)
7906 print *, modulo(17.5,5.5)
7908 print *, modulo(-17,3)
7909 print *, modulo(-17.5,5.5)
7911 print *, modulo(17,-3)
7912 print *, modulo(17.5,-5.5)
7921 @section @code{MOVE_ALLOC} --- Move allocation from one object to another
7923 @cindex moving allocation
7924 @cindex allocation, moving
7927 @item @emph{Description}:
7928 @code{MOVE_ALLOC(SRC, DEST)} moves the allocation from @var{SRC} to
7929 @var{DEST}. @var{SRC} will become deallocated in the process.
7931 @item @emph{Standard}:
7932 Fortran 2003 and later
7937 @item @emph{Syntax}:
7938 @code{CALL MOVE_ALLOC(SRC, DEST)}
7940 @item @emph{Arguments}:
7941 @multitable @columnfractions .15 .70
7942 @item @var{SRC} @tab @code{ALLOCATABLE}, @code{INTENT(INOUT)}, may be
7943 of any type and kind.
7944 @item @var{DEST} @tab @code{ALLOCATABLE}, @code{INTENT(OUT)}, shall be
7945 of the same type, kind and rank as @var{SRC}
7948 @item @emph{Return value}:
7951 @item @emph{Example}:
7953 program test_move_alloc
7954 integer, allocatable :: a(:), b(:)
7958 call move_alloc(a, b)
7959 print *, allocated(a), allocated(b)
7961 end program test_move_alloc
7968 @section @code{MVBITS} --- Move bits from one integer to another
7973 @item @emph{Description}:
7974 Moves @var{LEN} bits from positions @var{FROMPOS} through
7975 @code{FROMPOS+LEN-1} of @var{FROM} to positions @var{TOPOS} through
7976 @code{TOPOS+LEN-1} of @var{TO}. The portion of argument @var{TO} not
7977 affected by the movement of bits is unchanged. The values of
7978 @code{FROMPOS+LEN-1} and @code{TOPOS+LEN-1} must be less than
7979 @code{BIT_SIZE(FROM)}.
7981 @item @emph{Standard}:
7985 Elemental subroutine
7987 @item @emph{Syntax}:
7988 @code{CALL MVBITS(FROM, FROMPOS, LEN, TO, TOPOS)}
7990 @item @emph{Arguments}:
7991 @multitable @columnfractions .15 .70
7992 @item @var{FROM} @tab The type shall be @code{INTEGER(*)}.
7993 @item @var{FROMPOS} @tab The type shall be @code{INTEGER(*)}.
7994 @item @var{LEN} @tab The type shall be @code{INTEGER(*)}.
7995 @item @var{TO} @tab The type shall be @code{INTEGER(*)}, of the
7996 same kind as @var{FROM}.
7997 @item @var{TOPOS} @tab The type shall be @code{INTEGER(*)}.
8000 @item @emph{See also}:
8001 @ref{IBCLR}, @ref{IBSET}, @ref{IBITS}, @ref{IAND}, @ref{IOR}, @ref{IEOR}
8007 @section @code{NEAREST} --- Nearest representable number
8009 @cindex real number, nearest different
8010 @cindex floating point, nearest different
8013 @item @emph{Description}:
8014 @code{NEAREST(X, S)} returns the processor-representable number nearest
8015 to @code{X} in the direction indicated by the sign of @code{S}.
8017 @item @emph{Standard}:
8023 @item @emph{Syntax}:
8024 @code{RESULT = NEAREST(X, S)}
8026 @item @emph{Arguments}:
8027 @multitable @columnfractions .15 .70
8028 @item @var{X} @tab Shall be of type @code{REAL}.
8029 @item @var{S} @tab (Optional) shall be of type @code{REAL} and
8033 @item @emph{Return value}:
8034 The return value is of the same type as @code{X}. If @code{S} is
8035 positive, @code{NEAREST} returns the processor-representable number
8036 greater than @code{X} and nearest to it. If @code{S} is negative,
8037 @code{NEAREST} returns the processor-representable number smaller than
8038 @code{X} and nearest to it.
8040 @item @emph{Example}:
8042 program test_nearest
8044 x = nearest(42.0, 1.0)
8045 y = nearest(42.0, -1.0)
8046 write (*,"(3(G20.15))") x, y, x - y
8047 end program test_nearest
8054 @section @code{NEW_LINE} --- New line character
8057 @cindex output, newline
8060 @item @emph{Description}:
8061 @code{NEW_LINE(C)} returns the new-line character.
8063 @item @emph{Standard}:
8064 Fortran 2003 and later
8069 @item @emph{Syntax}:
8070 @code{RESULT = NEW_LINE(C)}
8072 @item @emph{Arguments}:
8073 @multitable @columnfractions .15 .70
8074 @item @var{C} @tab The argument shall be a scalar or array of the
8075 type @code{CHARACTER}.
8078 @item @emph{Return value}:
8079 Returns a @var{CHARACTER} scalar of length one with the new-line character of
8080 the same kind as parameter @var{C}.
8082 @item @emph{Example}:
8086 write(*,'(A)') 'This is record 1.'//NEW_LINE('A')//'This is record 2.'
8094 @section @code{NINT} --- Nearest whole number
8097 @cindex rounding, nearest whole number
8100 @item @emph{Description}:
8101 @code{NINT(X)} rounds its argument to the nearest whole number.
8103 @item @emph{Standard}:
8109 @item @emph{Syntax}:
8110 @code{RESULT = NINT(X)}
8112 @item @emph{Arguments}:
8113 @multitable @columnfractions .15 .70
8114 @item @var{X} @tab The type of the argument shall be @code{REAL}.
8117 @item @emph{Return value}:
8118 Returns @var{A} with the fractional portion of its magnitude eliminated by
8119 rounding to the nearest whole number and with its sign preserved,
8120 converted to an @code{INTEGER} of the default kind.
8122 @item @emph{Example}:
8129 print *, nint(x4), idnint(x8)
8130 end program test_nint
8133 @item @emph{Specific names}:
8134 @multitable @columnfractions .25 .25 .25
8135 @item Name @tab Argument @tab Standard
8136 @item @code{IDNINT(X)} @tab @code{REAL(8)} @tab F95 and later
8139 @item @emph{See also}:
8140 @ref{CEILING}, @ref{FLOOR}
8147 @section @code{NOT} --- Logical negation
8149 @cindex bits, negate
8150 @cindex bitwise logical not
8151 @cindex logical not, bitwise
8154 @item @emph{Description}:
8155 @code{NOT} returns the bitwise boolean inverse of @var{I}.
8157 @item @emph{Standard}:
8163 @item @emph{Syntax}:
8164 @code{RESULT = NOT(I)}
8166 @item @emph{Arguments}:
8167 @multitable @columnfractions .15 .70
8168 @item @var{I} @tab The type shall be @code{INTEGER(*)}.
8171 @item @emph{Return value}:
8172 The return type is @code{INTEGER(*)}, of the same kind as the
8175 @item @emph{See also}:
8176 @ref{IAND}, @ref{IEOR}, @ref{IOR}, @ref{IBITS}, @ref{IBSET}, @ref{IBCLR}
8183 @section @code{NULL} --- Function that returns an disassociated pointer
8185 @cindex pointer, status
8186 @cindex pointer, disassociated
8189 @item @emph{Description}:
8190 Returns a disassociated pointer.
8192 If @var{MOLD} is present, a dissassociated pointer of the same type is
8193 returned, otherwise the type is determined by context.
8195 In Fortran 95, @var{MOLD} is optional. Please note that Fortran 2003
8196 includes cases where it is required.
8198 @item @emph{Standard}:
8202 Transformational function
8204 @item @emph{Syntax}:
8205 @code{PTR => NULL([MOLD])}
8207 @item @emph{Arguments}:
8208 @multitable @columnfractions .15 .70
8209 @item @var{MOLD} @tab (Optional) shall be a pointer of any association
8210 status and of any type.
8213 @item @emph{Return value}:
8214 A disassociated pointer.
8216 @item @emph{Example}:
8218 REAL, POINTER, DIMENSION(:) :: VEC => NULL ()
8221 @item @emph{See also}:
8228 @section @code{OR} --- Bitwise logical OR
8230 @cindex bitwise logical or
8231 @cindex logical or, bitwise
8234 @item @emph{Description}:
8235 Bitwise logical @code{OR}.
8237 This intrinsic routine is provided for backwards compatibility with
8238 GNU Fortran 77. For integer arguments, programmers should consider
8239 the use of the @ref{IOR} intrinsic defined by the Fortran standard.
8241 @item @emph{Standard}:
8247 @item @emph{Syntax}:
8248 @code{RESULT = OR(X, Y)}
8250 @item @emph{Arguments}:
8251 @multitable @columnfractions .15 .70
8252 @item @var{X} @tab The type shall be either @code{INTEGER(*)} or @code{LOGICAL}.
8253 @item @var{Y} @tab The type shall be either @code{INTEGER(*)} or @code{LOGICAL}.
8256 @item @emph{Return value}:
8257 The return type is either @code{INTEGER(*)} or @code{LOGICAL}
8258 after cross-promotion of the arguments.
8260 @item @emph{Example}:
8263 LOGICAL :: T = .TRUE., F = .FALSE.
8265 DATA a / Z'F' /, b / Z'3' /
8267 WRITE (*,*) OR(T, T), OR(T, F), OR(F, T), OR(F, F)
8268 WRITE (*,*) OR(a, b)
8272 @item @emph{See also}:
8273 F95 elemental function: @ref{IOR}
8279 @section @code{PACK} --- Pack an array into an array of rank one
8281 @cindex array, packing
8282 @cindex array, reduce dimension
8283 @cindex array, gather elements
8286 @item @emph{Description}:
8287 Stores the elements of @var{ARRAY} in an array of rank one.
8289 The beginning of the resulting array is made up of elements whose @var{MASK}
8290 equals @code{TRUE}. Afterwards, positions are filled with elements taken from
8293 @item @emph{Standard}:
8297 Transformational function
8299 @item @emph{Syntax}:
8300 @code{RESULT = PACK(ARRAY, MASK[,VECTOR]}
8302 @item @emph{Arguments}:
8303 @multitable @columnfractions .15 .70
8304 @item @var{ARRAY} @tab Shall be an array of any type.
8305 @item @var{MASK} @tab Shall be an array of type @code{LOGICAL} and
8306 of the same size as @var{ARRAY}. Alternatively, it may be a @code{LOGICAL}
8308 @item @var{VECTOR} @tab (Optional) shall be an array of the same type
8309 as @var{ARRAY} and of rank one. If present, the number of elements in
8310 @var{VECTOR} shall be equal to or greater than the number of true elements
8311 in @var{MASK}. If @var{MASK} is scalar, the number of elements in
8312 @var{VECTOR} shall be equal to or greater than the number of elements in
8316 @item @emph{Return value}:
8317 The result is an array of rank one and the same type as that of @var{ARRAY}.
8318 If @var{VECTOR} is present, the result size is that of @var{VECTOR}, the
8319 number of @code{TRUE} values in @var{MASK} otherwise.
8321 @item @emph{Example}:
8322 Gathering nonzero elements from an array:
8326 m = (/ 1, 0, 0, 0, 5, 0 /)
8327 WRITE(*, FMT="(6(I0, ' '))") pack(m, m /= 0) ! "1 5"
8331 Gathering nonzero elements from an array and appending elements from @var{VECTOR}:
8335 m = (/ 1, 0, 0, 2 /)
8336 WRITE(*, FMT="(4(I0, ' '))") pack(m, m /= 0, (/ 0, 0, 3, 4 /)) ! "1 2 3 4"
8340 @item @emph{See also}:
8347 @section @code{PERROR} --- Print system error message
8349 @cindex system, error handling
8352 @item @emph{Description}:
8353 Prints (on the C @code{stderr} stream) a newline-terminated error
8354 message corresponding to the last system error. This is prefixed by
8355 @var{STRING}, a colon and a space. See @code{perror(3)}.
8357 @item @emph{Standard}:
8363 @item @emph{Syntax}:
8364 @code{CALL PERROR(STRING)}
8366 @item @emph{Arguments}:
8367 @multitable @columnfractions .15 .70
8368 @item @var{STRING} @tab A scalar of default @code{CHARACTER} type.
8371 @item @emph{See also}:
8378 @section @code{PRECISION} --- Decimal precision of a real kind
8380 @cindex model representation, precision
8383 @item @emph{Description}:
8384 @code{PRECISION(X)} returns the decimal precision in the model of the
8387 @item @emph{Standard}:
8393 @item @emph{Syntax}:
8394 @code{RESULT = PRECISION(X)}
8396 @item @emph{Arguments}:
8397 @multitable @columnfractions .15 .70
8398 @item @var{X} @tab Shall be of type @code{REAL} or @code{COMPLEX}.
8401 @item @emph{Return value}:
8402 The return value is of type @code{INTEGER} and of the default integer
8405 @item @emph{Example}:
8407 program prec_and_range
8408 real(kind=4) :: x(2)
8409 complex(kind=8) :: y
8411 print *, precision(x), range(x)
8412 print *, precision(y), range(y)
8413 end program prec_and_range
8420 @section @code{PRESENT} --- Determine whether an optional dummy argument is specified
8424 @item @emph{Description}:
8425 Determines whether an optional dummy argument is present.
8427 @item @emph{Standard}:
8433 @item @emph{Syntax}:
8434 @code{RESULT = PRESENT(A)}
8436 @item @emph{Arguments}:
8437 @multitable @columnfractions .15 .70
8438 @item @var{A} @tab May be of any type and may be a pointer, scalar or array
8439 value, or a dummy procedure. It shall be the name of an optional dummy argument
8440 accessible within the current subroutine or function.
8443 @item @emph{Return value}:
8444 Returns either @code{TRUE} if the optional argument @var{A} is present, or
8445 @code{FALSE} otherwise.
8447 @item @emph{Example}:
8449 PROGRAM test_present
8450 WRITE(*,*) f(), f(42) ! "F T"
8452 LOGICAL FUNCTION f(x)
8453 INTEGER, INTENT(IN), OPTIONAL :: x
8463 @section @code{PRODUCT} --- Product of array elements
8465 @cindex array, product
8466 @cindex array, multiply elements
8467 @cindex array, conditionally multiply elements
8468 @cindex multiply array elements
8471 @item @emph{Description}:
8472 Multiplies the elements of @var{ARRAY} along dimension @var{DIM} if
8473 the corresponding element in @var{MASK} is @code{TRUE}.
8475 @item @emph{Standard}:
8479 Transformational function
8481 @item @emph{Syntax}:
8482 @code{RESULT = PRODUCT(ARRAY[, MASK])}
8483 @code{RESULT = PRODUCT(ARRAY, DIM[, MASK])}
8485 @item @emph{Arguments}:
8486 @multitable @columnfractions .15 .70
8487 @item @var{ARRAY} @tab Shall be an array of type @code{INTEGER(*)},
8488 @code{REAL(*)} or @code{COMPLEX(*)}.
8489 @item @var{DIM} @tab (Optional) shall be a scalar of type
8490 @code{INTEGER} with a value in the range from 1 to n, where n
8491 equals the rank of @var{ARRAY}.
8492 @item @var{MASK} @tab (Optional) shall be of type @code{LOGICAL}
8493 and either be a scalar or an array of the same shape as @var{ARRAY}.
8496 @item @emph{Return value}:
8497 The result is of the same type as @var{ARRAY}.
8499 If @var{DIM} is absent, a scalar with the product of all elements in
8500 @var{ARRAY} is returned. Otherwise, an array of rank n-1, where n equals
8501 the rank of @var{ARRAY}, and a shape similar to that of @var{ARRAY} with
8502 dimension @var{DIM} dropped is returned.
8505 @item @emph{Example}:
8507 PROGRAM test_product
8508 INTEGER :: x(5) = (/ 1, 2, 3, 4 ,5 /)
8509 print *, PRODUCT(x) ! all elements, product = 120
8510 print *, PRODUCT(x, MASK=MOD(x, 2)==1) ! odd elements, product = 15
8514 @item @emph{See also}:
8521 @section @code{RADIX} --- Base of a model number
8523 @cindex model representation, base
8524 @cindex model representation, radix
8527 @item @emph{Description}:
8528 @code{RADIX(X)} returns the base of the model representing the entity @var{X}.
8530 @item @emph{Standard}:
8536 @item @emph{Syntax}:
8537 @code{RESULT = RADIX(X)}
8539 @item @emph{Arguments}:
8540 @multitable @columnfractions .15 .70
8541 @item @var{X} @tab Shall be of type @code{INTEGER} or @code{REAL}
8544 @item @emph{Return value}:
8545 The return value is a scalar of type @code{INTEGER} and of the default
8548 @item @emph{Example}:
8551 print *, "The radix for the default integer kind is", radix(0)
8552 print *, "The radix for the default real kind is", radix(0.0)
8553 end program test_radix
8561 @section @code{RAN} --- Real pseudo-random number
8563 @cindex random number generation
8566 @item @emph{Description}:
8567 For compatibility with HP FORTRAN 77/iX, the @code{RAN} intrinsic is
8568 provided as an alias for @code{RAND}. See @ref{RAND} for complete
8571 @item @emph{Standard}:
8577 @item @emph{See also}:
8578 @ref{RAND}, @ref{RANDOM_NUMBER}
8584 @section @code{RAND} --- Real pseudo-random number
8586 @cindex random number generation
8589 @item @emph{Description}:
8590 @code{RAND(FLAG)} returns a pseudo-random number from a uniform
8591 distribution between 0 and 1. If @var{FLAG} is 0, the next number
8592 in the current sequence is returned; if @var{FLAG} is 1, the generator
8593 is restarted by @code{CALL SRAND(0)}; if @var{FLAG} has any other value,
8594 it is used as a new seed with @code{SRAND}.
8596 This intrinsic routine is provided for backwards compatibility with
8597 GNU Fortran 77. It implements a simple modulo generator as provided
8598 by @command{g77}. For new code, one should consider the use of
8599 @ref{RANDOM_NUMBER} as it implements a superior algorithm.
8601 @item @emph{Standard}:
8607 @item @emph{Syntax}:
8608 @code{RESULT = RAND(FLAG)}
8610 @item @emph{Arguments}:
8611 @multitable @columnfractions .15 .70
8612 @item @var{FLAG} @tab Shall be a scalar @code{INTEGER} of kind 4.
8615 @item @emph{Return value}:
8616 The return value is of @code{REAL} type and the default kind.
8618 @item @emph{Example}:
8621 integer,parameter :: seed = 86456
8624 print *, rand(), rand(), rand(), rand()
8625 print *, rand(seed), rand(), rand(), rand()
8626 end program test_rand
8629 @item @emph{See also}:
8630 @ref{SRAND}, @ref{RANDOM_NUMBER}
8637 @section @code{RANDOM_NUMBER} --- Pseudo-random number
8638 @fnindex RANDOM_NUMBER
8639 @cindex random number generation
8642 @item @emph{Description}:
8643 Returns a single pseudorandom number or an array of pseudorandom numbers
8644 from the uniform distribution over the range @math{ 0 \leq x < 1}.
8646 The runtime-library implements George Marsaglia's KISS (Keep It Simple
8647 Stupid) random number generator (RNG). This RNG combines:
8649 @item The congruential generator @math{x(n) = 69069 \cdot x(n-1) + 1327217885}
8650 with a period of @math{2^{32}},
8651 @item A 3-shift shift-register generator with a period of @math{2^{32} - 1},
8652 @item Two 16-bit multiply-with-carry generators with a period of
8653 @math{597273182964842497 > 2^{59}}.
8655 The overall period exceeds @math{2^{123}}.
8657 Please note, this RNG is thread safe if used within OpenMP directives,
8658 i.e., its state will be consistent while called from multiple threads.
8659 However, the KISS generator does not create random numbers in parallel
8660 from multiple sources, but in sequence from a single source. If an
8661 OpenMP-enabled application heavily relies on random numbers, one should
8662 consider employing a dedicated parallel random number generator instead.
8664 @item @emph{Standard}:
8670 @item @emph{Syntax}:
8671 @code{RANDOM_NUMBER(HARVEST)}
8673 @item @emph{Arguments}:
8674 @multitable @columnfractions .15 .70
8675 @item @var{HARVEST} @tab Shall be a scalar or an array of type @code{REAL(*)}.
8678 @item @emph{Example}:
8680 program test_random_number
8682 CALL init_random_seed() ! see example of RANDOM_SEED
8683 CALL RANDOM_NUMBER(r)
8687 @item @emph{See also}:
8694 @section @code{RANDOM_SEED} --- Initialize a pseudo-random number sequence
8695 @fnindex RANDOM_SEED
8696 @cindex random number generation, seeding
8697 @cindex seeding a random number generator
8700 @item @emph{Description}:
8701 Restarts or queries the state of the pseudorandom number generator used by
8702 @code{RANDOM_NUMBER}.
8704 If @code{RANDOM_SEED} is called without arguments, it is initialized to
8705 a default state. The example below shows how to initialize the random
8706 seed based on the system's time.
8708 @item @emph{Standard}:
8714 @item @emph{Syntax}:
8715 @code{CALL RANDOM_SEED(SIZE, PUT, GET)}
8717 @item @emph{Arguments}:
8718 @multitable @columnfractions .15 .70
8719 @item @var{SIZE} @tab (Optional) Shall be a scalar and of type default
8720 @code{INTEGER}, with @code{INTENT(OUT)}. It specifies the minimum size
8721 of the arrays used with the @var{PUT} and @var{GET} arguments.
8722 @item @var{PUT} @tab (Optional) Shall be an array of type default
8723 @code{INTEGER} and rank one. It is @code{INTENT(IN)} and the size of
8724 the array must be larger than or equal to the number returned by the
8725 @var{SIZE} argument.
8726 @item @var{GET} @tab (Optional) Shall be an array of type default
8727 @code{INTEGER} and rank one. It is @code{INTENT(OUT)} and the size
8728 of the array must be larger than or equal to the number returned by
8729 the @var{SIZE} argument.
8732 @item @emph{Example}:
8734 SUBROUTINE init_random_seed()
8735 INTEGER :: i, n, clock
8736 INTEGER, DIMENSION(:), ALLOCATABLE :: seed
8738 CALL RANDOM_SEED(size = n)
8741 CALL SYSTEM_CLOCK(COUNT=clock)
8743 seed = clock + 37 * (/ (i - 1, i = 1, n) /)
8744 CALL RANDOM_SEED(PUT = seed)
8750 @item @emph{See also}:
8757 @section @code{RANGE} --- Decimal exponent range of a real kind
8759 @cindex model representation, range
8762 @item @emph{Description}:
8763 @code{RANGE(X)} returns the decimal exponent range in the model of the
8766 @item @emph{Standard}:
8772 @item @emph{Syntax}:
8773 @code{RESULT = RANGE(X)}
8775 @item @emph{Arguments}:
8776 @multitable @columnfractions .15 .70
8777 @item @var{X} @tab Shall be of type @code{REAL} or @code{COMPLEX}.
8780 @item @emph{Return value}:
8781 The return value is of type @code{INTEGER} and of the default integer
8784 @item @emph{Example}:
8785 See @code{PRECISION} for an example.
8791 @section @code{REAL} --- Convert to real type
8794 @cindex conversion, to real
8795 @cindex complex numbers, real part
8798 @item @emph{Description}:
8799 @code{REAL(X [, KIND])} converts its argument @var{X} to a real type. The
8800 @code{REALPART(X)} function is provided for compatibility with @command{g77},
8801 and its use is strongly discouraged.
8803 @item @emph{Standard}:
8809 @item @emph{Syntax}:
8810 @multitable @columnfractions .80
8811 @item @code{RESULT = REAL(X [, KIND])}
8812 @item @code{RESULT = REALPART(Z)}
8815 @item @emph{Arguments}:
8816 @multitable @columnfractions .15 .70
8817 @item @var{X} @tab Shall be @code{INTEGER(*)}, @code{REAL(*)}, or
8819 @item @var{KIND} @tab (Optional) An @code{INTEGER(*)} initialization
8820 expression indicating the kind parameter of
8824 @item @emph{Return value}:
8825 These functions return a @code{REAL(*)} variable or array under
8826 the following rules:
8830 @code{REAL(X)} is converted to a default real type if @var{X} is an
8831 integer or real variable.
8833 @code{REAL(X)} is converted to a real type with the kind type parameter
8834 of @var{X} if @var{X} is a complex variable.
8836 @code{REAL(X, KIND)} is converted to a real type with kind type
8837 parameter @var{KIND} if @var{X} is a complex, integer, or real
8841 @item @emph{Example}:
8844 complex :: x = (1.0, 2.0)
8845 print *, real(x), real(x,8), realpart(x)
8846 end program test_real
8849 @item @emph{See also}:
8850 @ref{DBLE}, @ref{DFLOAT}, @ref{FLOAT}
8857 @section @code{RENAME} --- Rename a file
8859 @cindex file system, rename file
8862 @item @emph{Description}:
8863 Renames a file from file @var{PATH1} to @var{PATH2}. A null
8864 character (@code{CHAR(0)}) can be used to mark the end of the names in
8865 @var{PATH1} and @var{PATH2}; otherwise, trailing blanks in the file
8866 names are ignored. If the @var{STATUS} argument is supplied, it
8867 contains 0 on success or a nonzero error code upon return; see
8870 This intrinsic is provided in both subroutine and function forms;
8871 however, only one form can be used in any given program unit.
8873 @item @emph{Standard}:
8877 Subroutine, function
8879 @item @emph{Syntax}:
8880 @multitable @columnfractions .80
8881 @item @code{CALL RENAME(PATH1, PATH2 [, STATUS])}
8882 @item @code{STATUS = RENAME(PATH1, PATH2)}
8885 @item @emph{Arguments}:
8886 @multitable @columnfractions .15 .70
8887 @item @var{PATH1} @tab Shall be of default @code{CHARACTER} type.
8888 @item @var{PATH2} @tab Shall be of default @code{CHARACTER} type.
8889 @item @var{STATUS} @tab (Optional) Shall be of default @code{INTEGER} type.
8892 @item @emph{See also}:
8900 @section @code{REPEAT} --- Repeated string concatenation
8902 @cindex string, repeat
8903 @cindex string, concatenate
8906 @item @emph{Description}:
8907 Concatenates @var{NCOPIES} copies of a string.
8909 @item @emph{Standard}:
8913 Transformational function
8915 @item @emph{Syntax}:
8916 @code{RESULT = REPEAT(STRING, NCOPIES)}
8918 @item @emph{Arguments}:
8919 @multitable @columnfractions .15 .70
8920 @item @var{STRING} @tab Shall be scalar and of type @code{CHARACTER(*)}.
8921 @item @var{NCOPIES} @tab Shall be scalar and of type @code{INTEGER(*)}.
8924 @item @emph{Return value}:
8925 A new scalar of type @code{CHARACTER} built up from @var{NCOPIES} copies
8928 @item @emph{Example}:
8931 write(*,*) repeat("x", 5) ! "xxxxx"
8939 @section @code{RESHAPE} --- Function to reshape an array
8941 @cindex array, change dimensions
8942 @cindex array, transmogrify
8945 @item @emph{Description}:
8946 Reshapes @var{SOURCE} to correspond to @var{SHAPE}. If necessary,
8947 the new array may be padded with elements from @var{PAD} or permuted
8948 as defined by @var{ORDER}.
8950 @item @emph{Standard}:
8954 Transformational function
8956 @item @emph{Syntax}:
8957 @code{RESULT = RESHAPE(SOURCE, SHAPE[, PAD, ORDER])}
8959 @item @emph{Arguments}:
8960 @multitable @columnfractions .15 .70
8961 @item @var{SOURCE} @tab Shall be an array of any type.
8962 @item @var{SHAPE} @tab Shall be of type @code{INTEGER} and an
8963 array of rank one. Its values must be positive or zero.
8964 @item @var{PAD} @tab (Optional) shall be an array of the same
8965 type as @var{SOURCE}.
8966 @item @var{ORDER} @tab (Optional) shall be of type @code{INTEGER}
8967 and an array of the same shape as @var{SHAPE}. Its values shall
8968 be a permutation of the numbers from 1 to n, where n is the size of
8969 @var{SHAPE}. If @var{ORDER} is absent, the natural ordering shall
8973 @item @emph{Return value}:
8974 The result is an array of shape @var{SHAPE} with the same type as
8977 @item @emph{Example}:
8979 PROGRAM test_reshape
8980 INTEGER, DIMENSION(4) :: x
8981 WRITE(*,*) SHAPE(x) ! prints "4"
8982 WRITE(*,*) SHAPE(RESHAPE(x, (/2, 2/))) ! prints "2 2"
8986 @item @emph{See also}:
8993 @section @code{RRSPACING} --- Reciprocal of the relative spacing
8995 @cindex real number, relative spacing
8996 @cindex floating point, relative spacing
9000 @item @emph{Description}:
9001 @code{RRSPACING(X)} returns the reciprocal of the relative spacing of
9002 model numbers near @var{X}.
9004 @item @emph{Standard}:
9010 @item @emph{Syntax}:
9011 @code{RESULT = RRSPACING(X)}
9013 @item @emph{Arguments}:
9014 @multitable @columnfractions .15 .70
9015 @item @var{X} @tab Shall be of type @code{REAL}.
9018 @item @emph{Return value}:
9019 The return value is of the same type and kind as @var{X}.
9020 The value returned is equal to
9021 @code{ABS(FRACTION(X)) * FLOAT(RADIX(X))**DIGITS(X)}.
9023 @item @emph{See also}:
9030 @section @code{RSHIFT} --- Right shift bits
9032 @cindex bits, shift right
9035 @item @emph{Description}:
9036 @code{RSHIFT} returns a value corresponding to @var{I} with all of the
9037 bits shifted right by @var{SHIFT} places. If the absolute value of
9038 @var{SHIFT} is greater than @code{BIT_SIZE(I)}, the value is undefined.
9039 Bits shifted out from the left end are lost; zeros are shifted in from
9042 This function has been superseded by the @code{ISHFT} intrinsic, which
9043 is standard in Fortran 95 and later.
9045 @item @emph{Standard}:
9051 @item @emph{Syntax}:
9052 @code{RESULT = RSHIFT(I, SHIFT)}
9054 @item @emph{Arguments}:
9055 @multitable @columnfractions .15 .70
9056 @item @var{I} @tab The type shall be @code{INTEGER(*)}.
9057 @item @var{SHIFT} @tab The type shall be @code{INTEGER(*)}.
9060 @item @emph{Return value}:
9061 The return value is of type @code{INTEGER(*)} and of the same kind as
9064 @item @emph{See also}:
9065 @ref{ISHFT}, @ref{ISHFTC}, @ref{LSHIFT}
9072 @section @code{SCALE} --- Scale a real value
9074 @cindex real number, scale
9075 @cindex floating point, scale
9078 @item @emph{Description}:
9079 @code{SCALE(X,I)} returns @code{X * RADIX(X)**I}.
9081 @item @emph{Standard}:
9087 @item @emph{Syntax}:
9088 @code{RESULT = SCALE(X, I)}
9090 @item @emph{Arguments}:
9091 @multitable @columnfractions .15 .70
9092 @item @var{X} @tab The type of the argument shall be a @code{REAL}.
9093 @item @var{I} @tab The type of the argument shall be a @code{INTEGER}.
9096 @item @emph{Return value}:
9097 The return value is of the same type and kind as @var{X}.
9098 Its value is @code{X * RADIX(X)**I}.
9100 @item @emph{Example}:
9103 real :: x = 178.1387e-4
9105 print *, scale(x,i), x*radix(x)**i
9106 end program test_scale
9114 @section @code{SCAN} --- Scan a string for the presence of a set of characters
9116 @cindex string, find subset
9119 @item @emph{Description}:
9120 Scans a @var{STRING} for any of the characters in a @var{SET}
9123 If @var{BACK} is either absent or equals @code{FALSE}, this function
9124 returns the position of the leftmost character of @var{STRING} that is
9125 in @var{SET}. If @var{BACK} equals @code{TRUE}, the rightmost position
9126 is returned. If no character of @var{SET} is found in @var{STRING}, the
9129 @item @emph{Standard}:
9135 @item @emph{Syntax}:
9136 @code{RESULT = SCAN(STRING, SET[, BACK [, KIND]])}
9138 @item @emph{Arguments}:
9139 @multitable @columnfractions .15 .70
9140 @item @var{STRING} @tab Shall be of type @code{CHARACTER(*)}.
9141 @item @var{SET} @tab Shall be of type @code{CHARACTER(*)}.
9142 @item @var{BACK} @tab (Optional) shall be of type @code{LOGICAL}.
9143 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
9144 expression indicating the kind parameter of
9148 @item @emph{Return value}:
9149 The return value is of type @code{INTEGER} and of kind @var{KIND}. If
9150 @var{KIND} is absent, the return value is of default integer kind.
9152 @item @emph{Example}:
9155 WRITE(*,*) SCAN("FORTRAN", "AO") ! 2, found 'O'
9156 WRITE(*,*) SCAN("FORTRAN", "AO", .TRUE.) ! 6, found 'A'
9157 WRITE(*,*) SCAN("FORTRAN", "C++") ! 0, found none
9161 @item @emph{See also}:
9162 @ref{INDEX intrinsic}, @ref{VERIFY}
9168 @section @code{SECNDS} --- Time function
9170 @cindex time, elapsed
9171 @cindex elapsed time
9174 @item @emph{Description}:
9175 @code{SECNDS(X)} gets the time in seconds from the real-time system clock.
9176 @var{X} is a reference time, also in seconds. If this is zero, the time in
9177 seconds from midnight is returned. This function is non-standard and its
9180 @item @emph{Standard}:
9186 @item @emph{Syntax}:
9187 @code{RESULT = SECNDS (X)}
9189 @item @emph{Arguments}:
9190 @multitable @columnfractions .15 .70
9191 @item @var{T} @tab Shall be of type @code{REAL(4)}.
9192 @item @var{X} @tab Shall be of type @code{REAL(4)}.
9195 @item @emph{Return value}:
9198 @item @emph{Example}:
9203 print *, secnds (0.0) ! seconds since midnight
9204 t1 = secnds (0.0) ! reference time
9205 do i = 1, 10000000 ! do something
9207 t2 = secnds (t1) ! elapsed time
9208 print *, "Something took ", t2, " seconds."
9209 end program test_secnds
9216 @section @code{SECOND} --- CPU time function
9218 @cindex time, elapsed
9219 @cindex elapsed time
9222 @item @emph{Description}:
9223 Returns a @code{REAL(4)} value representing the elapsed CPU time in
9224 seconds. This provides the same functionality as the standard
9225 @code{CPU_TIME} intrinsic, and is only included for backwards
9228 This intrinsic is provided in both subroutine and function forms;
9229 however, only one form can be used in any given program unit.
9231 @item @emph{Standard}:
9235 Subroutine, function
9237 @item @emph{Syntax}:
9238 @multitable @columnfractions .80
9239 @item @code{CALL SECOND(TIME)}
9240 @item @code{TIME = SECOND()}
9243 @item @emph{Arguments}:
9244 @multitable @columnfractions .15 .70
9245 @item @var{TIME} @tab Shall be of type @code{REAL(4)}.
9248 @item @emph{Return value}:
9249 In either syntax, @var{TIME} is set to the process's current runtime in
9252 @item @emph{See also}:
9259 @node SELECTED_INT_KIND
9260 @section @code{SELECTED_INT_KIND} --- Choose integer kind
9261 @fnindex SELECTED_INT_KIND
9262 @cindex integer kind
9263 @cindex kind, integer
9266 @item @emph{Description}:
9267 @code{SELECTED_INT_KIND(I)} return the kind value of the smallest integer
9268 type that can represent all values ranging from @math{-10^I} (exclusive)
9269 to @math{10^I} (exclusive). If there is no integer kind that accommodates
9270 this range, @code{SELECTED_INT_KIND} returns @math{-1}.
9272 @item @emph{Standard}:
9276 Transformational function
9278 @item @emph{Syntax}:
9279 @code{RESULT = SELECTED_INT_KIND(I)}
9281 @item @emph{Arguments}:
9282 @multitable @columnfractions .15 .70
9283 @item @var{I} @tab Shall be a scalar and of type @code{INTEGER}.
9286 @item @emph{Example}:
9288 program large_integers
9289 integer,parameter :: k5 = selected_int_kind(5)
9290 integer,parameter :: k15 = selected_int_kind(15)
9291 integer(kind=k5) :: i5
9292 integer(kind=k15) :: i15
9294 print *, huge(i5), huge(i15)
9296 ! The following inequalities are always true
9297 print *, huge(i5) >= 10_k5**5-1
9298 print *, huge(i15) >= 10_k15**15-1
9299 end program large_integers
9305 @node SELECTED_REAL_KIND
9306 @section @code{SELECTED_REAL_KIND} --- Choose real kind
9307 @fnindex SELECTED_REAL_KIND
9312 @item @emph{Description}:
9313 @code{SELECTED_REAL_KIND(P,R)} return the kind value of a real data type
9314 with decimal precision greater of at least @code{P} digits and exponent
9315 range greater at least @code{R}.
9317 @item @emph{Standard}:
9321 Transformational function
9323 @item @emph{Syntax}:
9324 @code{RESULT = SELECTED_REAL_KIND(P, R)}
9326 @item @emph{Arguments}:
9327 @multitable @columnfractions .15 .70
9328 @item @var{P} @tab (Optional) shall be a scalar and of type @code{INTEGER}.
9329 @item @var{R} @tab (Optional) shall be a scalar and of type @code{INTEGER}.
9331 At least one argument shall be present.
9333 @item @emph{Return value}:
9335 @code{SELECTED_REAL_KIND} returns the value of the kind type parameter of
9336 a real data type with decimal precision of at least @code{P} digits and a
9337 decimal exponent range of at least @code{R}. If more than one real data
9338 type meet the criteria, the kind of the data type with the smallest
9339 decimal precision is returned. If no real data type matches the criteria,
9342 @item -1 if the processor does not support a real data type with a
9343 precision greater than or equal to @code{P}
9344 @item -2 if the processor does not support a real type with an exponent
9345 range greater than or equal to @code{R}
9346 @item -3 if neither is supported.
9349 @item @emph{Example}:
9352 integer,parameter :: p6 = selected_real_kind(6)
9353 integer,parameter :: p10r100 = selected_real_kind(10,100)
9354 integer,parameter :: r400 = selected_real_kind(r=400)
9356 real(kind=p10r100) :: y
9357 real(kind=r400) :: z
9359 print *, precision(x), range(x)
9360 print *, precision(y), range(y)
9361 print *, precision(z), range(z)
9362 end program real_kinds
9369 @section @code{SET_EXPONENT} --- Set the exponent of the model
9370 @fnindex SET_EXPONENT
9371 @cindex real number, set exponent
9372 @cindex floating point, set exponent
9375 @item @emph{Description}:
9376 @code{SET_EXPONENT(X, I)} returns the real number whose fractional part
9377 is that that of @var{X} and whose exponent part is @var{I}.
9379 @item @emph{Standard}:
9385 @item @emph{Syntax}:
9386 @code{RESULT = SET_EXPONENT(X, I)}
9388 @item @emph{Arguments}:
9389 @multitable @columnfractions .15 .70
9390 @item @var{X} @tab Shall be of type @code{REAL}.
9391 @item @var{I} @tab Shall be of type @code{INTEGER}.
9394 @item @emph{Return value}:
9395 The return value is of the same type and kind as @var{X}.
9396 The real number whose fractional part
9397 is that that of @var{X} and whose exponent part if @var{I} is returned;
9398 it is @code{FRACTION(X) * RADIX(X)**I}.
9400 @item @emph{Example}:
9403 REAL :: x = 178.1387e-4
9405 PRINT *, SET_EXPONENT(x, i), FRACTION(x) * RADIX(x)**i
9414 @section @code{SHAPE} --- Determine the shape of an array
9416 @cindex array, shape
9419 @item @emph{Description}:
9420 Determines the shape of an array.
9422 @item @emph{Standard}:
9428 @item @emph{Syntax}:
9429 @code{RESULT = SHAPE(SOURCE)}
9431 @item @emph{Arguments}:
9432 @multitable @columnfractions .15 .70
9433 @item @var{SOURCE} @tab Shall be an array or scalar of any type.
9434 If @var{SOURCE} is a pointer it must be associated and allocatable
9435 arrays must be allocated.
9438 @item @emph{Return value}:
9439 An @code{INTEGER} array of rank one with as many elements as @var{SOURCE}
9440 has dimensions. The elements of the resulting array correspond to the extend
9441 of @var{SOURCE} along the respective dimensions. If @var{SOURCE} is a scalar,
9442 the result is the rank one array of size zero.
9444 @item @emph{Example}:
9447 INTEGER, DIMENSION(-1:1, -1:2) :: A
9448 WRITE(*,*) SHAPE(A) ! (/ 3, 4 /)
9449 WRITE(*,*) SIZE(SHAPE(42)) ! (/ /)
9453 @item @emph{See also}:
9454 @ref{RESHAPE}, @ref{SIZE}
9460 @section @code{SIGN} --- Sign copying function
9464 @cindex sign copying
9467 @item @emph{Description}:
9468 @code{SIGN(A,B)} returns the value of @var{A} with the sign of @var{B}.
9470 @item @emph{Standard}:
9476 @item @emph{Syntax}:
9477 @code{RESULT = SIGN(A, B)}
9479 @item @emph{Arguments}:
9480 @multitable @columnfractions .15 .70
9481 @item @var{A} @tab Shall be of type @code{INTEGER} or @code{REAL}
9482 @item @var{B} @tab Shall be of the same type and kind as @var{A}
9485 @item @emph{Return value}:
9486 The kind of the return value is that of @var{A} and @var{B}.
9487 If @math{B\ge 0} then the result is @code{ABS(A)}, else
9488 it is @code{-ABS(A)}.
9490 @item @emph{Example}:
9493 print *, sign(-12,1)
9494 print *, sign(-12,0)
9495 print *, sign(-12,-1)
9497 print *, sign(-12.,1.)
9498 print *, sign(-12.,0.)
9499 print *, sign(-12.,-1.)
9500 end program test_sign
9503 @item @emph{Specific names}:
9504 @multitable @columnfractions .20 .20 .20 .25
9505 @item Name @tab Arguments @tab Return type @tab Standard
9506 @item @code{ISIGN(A,P)} @tab @code{INTEGER(4)} @tab @code{INTEGER(4)} @tab f95, gnu
9507 @item @code{DSIGN(A,P)} @tab @code{REAL(8)} @tab @code{REAL(8)} @tab f95, gnu
9514 @section @code{SIGNAL} --- Signal handling subroutine (or function)
9516 @cindex system, signal handling
9519 @item @emph{Description}:
9520 @code{SIGNAL(NUMBER, HANDLER [, STATUS])} causes external subroutine
9521 @var{HANDLER} to be executed with a single integer argument when signal
9522 @var{NUMBER} occurs. If @var{HANDLER} is an integer, it can be used to
9523 turn off handling of signal @var{NUMBER} or revert to its default
9524 action. See @code{signal(2)}.
9526 If @code{SIGNAL} is called as a subroutine and the @var{STATUS} argument
9527 is supplied, it is set to the value returned by @code{signal(2)}.
9529 @item @emph{Standard}:
9533 Subroutine, function
9535 @item @emph{Syntax}:
9536 @multitable @columnfractions .80
9537 @item @code{CALL SIGNAL(NUMBER, HANDLER [, STATUS])}
9538 @item @code{STATUS = SIGNAL(NUMBER, HANDLER)}
9541 @item @emph{Arguments}:
9542 @multitable @columnfractions .15 .70
9543 @item @var{NUMBER} @tab Shall be a scalar integer, with @code{INTENT(IN)}
9544 @item @var{HANDLER}@tab Signal handler (@code{INTEGER FUNCTION} or
9545 @code{SUBROUTINE}) or dummy/global @code{INTEGER} scalar.
9546 @code{INTEGER}. It is @code{INTENT(IN)}.
9547 @item @var{STATUS} @tab (Optional) @var{STATUS} shall be a scalar
9548 integer. It has @code{INTENT(OUT)}.
9551 @item @emph{Return value}:
9552 The @code{SIGNAL} function returns the value returned by @code{signal(2)}.
9554 @item @emph{Example}:
9558 external handler_print
9560 call signal (12, handler_print)
9564 end program test_signal
9571 @section @code{SIN} --- Sine function
9577 @cindex trigonometric function, sine
9581 @item @emph{Description}:
9582 @code{SIN(X)} computes the sine of @var{X}.
9584 @item @emph{Standard}:
9590 @item @emph{Syntax}:
9591 @code{RESULT = SIN(X)}
9593 @item @emph{Arguments}:
9594 @multitable @columnfractions .15 .70
9595 @item @var{X} @tab The type shall be @code{REAL(*)} or
9599 @item @emph{Return value}:
9600 The return value has same type and kind as @var{X}.
9602 @item @emph{Example}:
9607 end program test_sin
9610 @item @emph{Specific names}:
9611 @multitable @columnfractions .20 .20 .20 .25
9612 @item Name @tab Argument @tab Return type @tab Standard
9613 @item @code{DSIN(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab f95, gnu
9614 @item @code{CSIN(X)} @tab @code{COMPLEX(4) X} @tab @code{COMPLEX(4)} @tab f95, gnu
9615 @item @code{ZSIN(X)} @tab @code{COMPLEX(8) X} @tab @code{COMPLEX(8)} @tab f95, gnu
9616 @item @code{CDSIN(X)} @tab @code{COMPLEX(8) X} @tab @code{COMPLEX(8)} @tab f95, gnu
9619 @item @emph{See also}:
9626 @section @code{SINH} --- Hyperbolic sine function
9629 @cindex hyperbolic sine
9630 @cindex hyperbolic function, sine
9631 @cindex sine, hyperbolic
9634 @item @emph{Description}:
9635 @code{SINH(X)} computes the hyperbolic sine of @var{X}.
9637 @item @emph{Standard}:
9643 @item @emph{Syntax}:
9644 @code{RESULT = SINH(X)}
9646 @item @emph{Arguments}:
9647 @multitable @columnfractions .15 .70
9648 @item @var{X} @tab The type shall be @code{REAL(*)}.
9651 @item @emph{Return value}:
9652 The return value is of type @code{REAL(*)}.
9654 @item @emph{Example}:
9657 real(8) :: x = - 1.0_8
9659 end program test_sinh
9662 @item @emph{Specific names}:
9663 @multitable @columnfractions .20 .20 .20 .25
9664 @item Name @tab Argument @tab Return type @tab Standard
9665 @item @code{DSINH(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab F95 and later
9668 @item @emph{See also}:
9675 @section @code{SIZE} --- Determine the size of an array
9678 @cindex array, number of elements
9679 @cindex array, count elements
9682 @item @emph{Description}:
9683 Determine the extent of @var{ARRAY} along a specified dimension @var{DIM},
9684 or the total number of elements in @var{ARRAY} if @var{DIM} is absent.
9686 @item @emph{Standard}:
9692 @item @emph{Syntax}:
9693 @code{RESULT = SIZE(ARRAY[, DIM [, KIND]])}
9695 @item @emph{Arguments}:
9696 @multitable @columnfractions .15 .70
9697 @item @var{ARRAY} @tab Shall be an array of any type. If @var{ARRAY} is
9698 a pointer it must be associated and allocatable arrays must be allocated.
9699 @item @var{DIM} @tab (Optional) shall be a scalar of type @code{INTEGER}
9700 and its value shall be in the range from 1 to n, where n equals the rank
9702 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
9703 expression indicating the kind parameter of
9707 @item @emph{Return value}:
9708 The return value is of type @code{INTEGER} and of kind @var{KIND}. If
9709 @var{KIND} is absent, the return value is of default integer kind.
9711 @item @emph{Example}:
9714 WRITE(*,*) SIZE((/ 1, 2 /)) ! 2
9718 @item @emph{See also}:
9719 @ref{SHAPE}, @ref{RESHAPE}
9724 @section @code{SIZEOF} --- Size in bytes of an expression
9726 @cindex expression size
9727 @cindex size of an expression
9730 @item @emph{Description}:
9731 @code{SIZEOF(X)} calculates the number of bytes of storage the
9732 expression @code{X} occupies.
9734 @item @emph{Standard}:
9740 @item @emph{Syntax}:
9741 @code{N = SIZEOF(X)}
9743 @item @emph{Arguments}:
9744 @multitable @columnfractions .15 .70
9745 @item @var{X} @tab The argument shall be of any type, rank or shape.
9748 @item @emph{Return value}:
9749 The return value is of type integer and of the system-dependent kind
9750 @var{C_SIZE_T} (from the @var{ISO_C_BINDING} module). Its value is the
9751 number of bytes occupied by the argument. If the argument has the
9752 @code{POINTER} attribute, the number of bytes of the storage area pointed
9753 to is returned. If the argument is of a derived type with @code{POINTER}
9754 or @code{ALLOCATABLE} components, the return value doesn't account for
9755 the sizes of the data pointed to by these components.
9757 @item @emph{Example}:
9761 print *, (sizeof(s)/sizeof(r) == 5)
9764 The example will print @code{.TRUE.} unless you are using a platform
9765 where default @code{REAL} variables are unusually padded.
9769 @section @code{SLEEP} --- Sleep for the specified number of seconds
9771 @cindex delayed execution
9774 @item @emph{Description}:
9775 Calling this subroutine causes the process to pause for @var{SECONDS} seconds.
9777 @item @emph{Standard}:
9783 @item @emph{Syntax}:
9784 @code{CALL SLEEP(SECONDS)}
9786 @item @emph{Arguments}:
9787 @multitable @columnfractions .15 .70
9788 @item @var{SECONDS} @tab The type shall be of default @code{INTEGER}.
9791 @item @emph{Example}:
9802 @section @code{SNGL} --- Convert double precision real to default real
9804 @cindex conversion, to real
9807 @item @emph{Description}:
9808 @code{SNGL(A)} converts the double precision real @var{A}
9809 to a default real value. This is an archaic form of @code{REAL}
9810 that is specific to one type for @var{A}.
9812 @item @emph{Standard}:
9818 @item @emph{Syntax}:
9819 @code{RESULT = SNGL(A)}
9821 @item @emph{Arguments}:
9822 @multitable @columnfractions .15 .70
9823 @item @var{A} @tab The type shall be a double precision @code{REAL}.
9826 @item @emph{Return value}:
9827 The return value is of type default @code{REAL}.
9829 @item @emph{See also}:
9836 @section @code{SPACING} --- Smallest distance between two numbers of a given type
9838 @cindex real number, relative spacing
9839 @cindex floating point, relative spacing
9842 @item @emph{Description}:
9843 Determines the distance between the argument @var{X} and the nearest
9844 adjacent number of the same type.
9846 @item @emph{Standard}:
9852 @item @emph{Syntax}:
9853 @code{RESULT = SPACING(X)}
9855 @item @emph{Arguments}:
9856 @multitable @columnfractions .15 .70
9857 @item @var{X} @tab Shall be of type @code{REAL(*)}.
9860 @item @emph{Return value}:
9861 The result is of the same type as the input argument @var{X}.
9863 @item @emph{Example}:
9865 PROGRAM test_spacing
9866 INTEGER, PARAMETER :: SGL = SELECTED_REAL_KIND(p=6, r=37)
9867 INTEGER, PARAMETER :: DBL = SELECTED_REAL_KIND(p=13, r=200)
9869 WRITE(*,*) spacing(1.0_SGL) ! "1.1920929E-07" on i686
9870 WRITE(*,*) spacing(1.0_DBL) ! "2.220446049250313E-016" on i686
9874 @item @emph{See also}:
9881 @section @code{SPREAD} --- Add a dimension to an array
9883 @cindex array, increase dimension
9884 @cindex array, duplicate elements
9885 @cindex array, duplicate dimensions
9888 @item @emph{Description}:
9889 Replicates a @var{SOURCE} array @var{NCOPIES} times along a specified
9890 dimension @var{DIM}.
9892 @item @emph{Standard}:
9896 Transformational function
9898 @item @emph{Syntax}:
9899 @code{RESULT = SPREAD(SOURCE, DIM, NCOPIES)}
9901 @item @emph{Arguments}:
9902 @multitable @columnfractions .15 .70
9903 @item @var{SOURCE} @tab Shall be a scalar or an array of any type and
9904 a rank less than seven.
9905 @item @var{DIM} @tab Shall be a scalar of type @code{INTEGER} with a
9906 value in the range from 1 to n+1, where n equals the rank of @var{SOURCE}.
9907 @item @var{NCOPIES} @tab Shall be a scalar of type @code{INTEGER}.
9910 @item @emph{Return value}:
9911 The result is an array of the same type as @var{SOURCE} and has rank n+1
9912 where n equals the rank of @var{SOURCE}.
9914 @item @emph{Example}:
9917 INTEGER :: a = 1, b(2) = (/ 1, 2 /)
9918 WRITE(*,*) SPREAD(A, 1, 2) ! "1 1"
9919 WRITE(*,*) SPREAD(B, 1, 2) ! "1 1 2 2"
9923 @item @emph{See also}:
9930 @section @code{SQRT} --- Square-root function
9940 @item @emph{Description}:
9941 @code{SQRT(X)} computes the square root of @var{X}.
9943 @item @emph{Standard}:
9949 @item @emph{Syntax}:
9950 @code{RESULT = SQRT(X)}
9952 @item @emph{Arguments}:
9953 @multitable @columnfractions .15 .70
9954 @item @var{X} @tab The type shall be @code{REAL(*)} or
9958 @item @emph{Return value}:
9959 The return value is of type @code{REAL(*)} or @code{COMPLEX(*)}.
9960 The kind type parameter is the same as @var{X}.
9962 @item @emph{Example}:
9965 real(8) :: x = 2.0_8
9966 complex :: z = (1.0, 2.0)
9969 end program test_sqrt
9972 @item @emph{Specific names}:
9973 @multitable @columnfractions .20 .20 .20 .25
9974 @item Name @tab Argument @tab Return type @tab Standard
9975 @item @code{DSQRT(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab F95 and later
9976 @item @code{CSQRT(X)} @tab @code{COMPLEX(4) X} @tab @code{COMPLEX(4)} @tab F95 and later
9977 @item @code{ZSQRT(X)} @tab @code{COMPLEX(8) X} @tab @code{COMPLEX(8)} @tab GNU extension
9978 @item @code{CDSQRT(X)} @tab @code{COMPLEX(8) X} @tab @code{COMPLEX(8)} @tab GNU extension
9985 @section @code{SRAND} --- Reinitialize the random number generator
9987 @cindex random number generation, seeding
9988 @cindex seeding a random number generator
9991 @item @emph{Description}:
9992 @code{SRAND} reinitializes the pseudo-random number generator
9993 called by @code{RAND} and @code{IRAND}. The new seed used by the
9994 generator is specified by the required argument @var{SEED}.
9996 @item @emph{Standard}:
10002 @item @emph{Syntax}:
10003 @code{CALL SRAND(SEED)}
10005 @item @emph{Arguments}:
10006 @multitable @columnfractions .15 .70
10007 @item @var{SEED} @tab Shall be a scalar @code{INTEGER(kind=4)}.
10010 @item @emph{Return value}:
10013 @item @emph{Example}:
10014 See @code{RAND} and @code{IRAND} for examples.
10016 @item @emph{Notes}:
10017 The Fortran 2003 standard specifies the intrinsic @code{RANDOM_SEED} to
10018 initialize the pseudo-random numbers generator and @code{RANDOM_NUMBER}
10019 to generate pseudo-random numbers. Please note that in
10020 GNU Fortran, these two sets of intrinsics (@code{RAND},
10021 @code{IRAND} and @code{SRAND} on the one hand, @code{RANDOM_NUMBER} and
10022 @code{RANDOM_SEED} on the other hand) access two independent
10023 pseudo-random number generators.
10025 @item @emph{See also}:
10026 @ref{RAND}, @ref{RANDOM_SEED}, @ref{RANDOM_NUMBER}
10033 @section @code{STAT} --- Get file status
10035 @cindex file system, file status
10038 @item @emph{Description}:
10039 This function returns information about a file. No permissions are required on
10040 the file itself, but execute (search) permission is required on all of the
10041 directories in path that lead to the file.
10043 The elements that are obtained and stored in the array @code{BUFF}:
10044 @multitable @columnfractions .15 .70
10045 @item @code{buff(1)} @tab Device ID
10046 @item @code{buff(2)} @tab Inode number
10047 @item @code{buff(3)} @tab File mode
10048 @item @code{buff(4)} @tab Number of links
10049 @item @code{buff(5)} @tab Owner's uid
10050 @item @code{buff(6)} @tab Owner's gid
10051 @item @code{buff(7)} @tab ID of device containing directory entry for file (0 if not available)
10052 @item @code{buff(8)} @tab File size (bytes)
10053 @item @code{buff(9)} @tab Last access time
10054 @item @code{buff(10)} @tab Last modification time
10055 @item @code{buff(11)} @tab Last file status change time
10056 @item @code{buff(12)} @tab Preferred I/O block size (-1 if not available)
10057 @item @code{buff(13)} @tab Number of blocks allocated (-1 if not available)
10060 Not all these elements are relevant on all systems.
10061 If an element is not relevant, it is returned as 0.
10063 This intrinsic is provided in both subroutine and function forms; however,
10064 only one form can be used in any given program unit.
10066 @item @emph{Standard}:
10069 @item @emph{Class}:
10070 Subroutine, function
10072 @item @emph{Syntax}:
10073 @code{CALL STAT(FILE,BUFF[,STATUS])}
10075 @item @emph{Arguments}:
10076 @multitable @columnfractions .15 .70
10077 @item @var{FILE} @tab The type shall be @code{CHARACTER(*)}, a valid path within the file system.
10078 @item @var{BUFF} @tab The type shall be @code{INTEGER(4), DIMENSION(13)}.
10079 @item @var{STATUS} @tab (Optional) status flag of type @code{INTEGER(4)}. Returns 0
10080 on success and a system specific error code otherwise.
10083 @item @emph{Example}:
10086 INTEGER, DIMENSION(13) :: buff
10089 CALL STAT("/etc/passwd", buff, status)
10091 IF (status == 0) THEN
10092 WRITE (*, FMT="('Device ID:', T30, I19)") buff(1)
10093 WRITE (*, FMT="('Inode number:', T30, I19)") buff(2)
10094 WRITE (*, FMT="('File mode (octal):', T30, O19)") buff(3)
10095 WRITE (*, FMT="('Number of links:', T30, I19)") buff(4)
10096 WRITE (*, FMT="('Owner''s uid:', T30, I19)") buff(5)
10097 WRITE (*, FMT="('Owner''s gid:', T30, I19)") buff(6)
10098 WRITE (*, FMT="('Device where located:', T30, I19)") buff(7)
10099 WRITE (*, FMT="('File size:', T30, I19)") buff(8)
10100 WRITE (*, FMT="('Last access time:', T30, A19)") CTIME(buff(9))
10101 WRITE (*, FMT="('Last modification time', T30, A19)") CTIME(buff(10))
10102 WRITE (*, FMT="('Last status change time:', T30, A19)") CTIME(buff(11))
10103 WRITE (*, FMT="('Preferred block size:', T30, I19)") buff(12)
10104 WRITE (*, FMT="('No. of blocks allocated:', T30, I19)") buff(13)
10109 @item @emph{See also}:
10110 To stat an open file: @ref{FSTAT}, to stat a link: @ref{LSTAT}
10116 @section @code{SUM} --- Sum of array elements
10119 @cindex array, add elements
10120 @cindex array, conditionally add elements
10121 @cindex sum array elements
10124 @item @emph{Description}:
10125 Adds the elements of @var{ARRAY} along dimension @var{DIM} if
10126 the corresponding element in @var{MASK} is @code{TRUE}.
10128 @item @emph{Standard}:
10131 @item @emph{Class}:
10132 Transformational function
10134 @item @emph{Syntax}:
10135 @code{RESULT = SUM(ARRAY[, MASK])}
10136 @code{RESULT = SUM(ARRAY, DIM[, MASK])}
10138 @item @emph{Arguments}:
10139 @multitable @columnfractions .15 .70
10140 @item @var{ARRAY} @tab Shall be an array of type @code{INTEGER(*)},
10141 @code{REAL(*)} or @code{COMPLEX(*)}.
10142 @item @var{DIM} @tab (Optional) shall be a scalar of type
10143 @code{INTEGER} with a value in the range from 1 to n, where n
10144 equals the rank of @var{ARRAY}.
10145 @item @var{MASK} @tab (Optional) shall be of type @code{LOGICAL}
10146 and either be a scalar or an array of the same shape as @var{ARRAY}.
10149 @item @emph{Return value}:
10150 The result is of the same type as @var{ARRAY}.
10152 If @var{DIM} is absent, a scalar with the sum of all elements in @var{ARRAY}
10153 is returned. Otherwise, an array of rank n-1, where n equals the rank of
10154 @var{ARRAY},and a shape similar to that of @var{ARRAY} with dimension @var{DIM}
10155 dropped is returned.
10157 @item @emph{Example}:
10160 INTEGER :: x(5) = (/ 1, 2, 3, 4 ,5 /)
10161 print *, SUM(x) ! all elements, sum = 15
10162 print *, SUM(x, MASK=MOD(x, 2)==1) ! odd elements, sum = 9
10166 @item @emph{See also}:
10173 @section @code{SYMLNK} --- Create a symbolic link
10175 @cindex file system, create link
10176 @cindex file system, soft link
10179 @item @emph{Description}:
10180 Makes a symbolic link from file @var{PATH1} to @var{PATH2}. A null
10181 character (@code{CHAR(0)}) can be used to mark the end of the names in
10182 @var{PATH1} and @var{PATH2}; otherwise, trailing blanks in the file
10183 names are ignored. If the @var{STATUS} argument is supplied, it
10184 contains 0 on success or a nonzero error code upon return; see
10185 @code{symlink(2)}. If the system does not supply @code{symlink(2)},
10186 @code{ENOSYS} is returned.
10188 This intrinsic is provided in both subroutine and function forms;
10189 however, only one form can be used in any given program unit.
10191 @item @emph{Standard}:
10194 @item @emph{Class}:
10195 Subroutine, function
10197 @item @emph{Syntax}:
10198 @multitable @columnfractions .80
10199 @item @code{CALL SYMLNK(PATH1, PATH2 [, STATUS])}
10200 @item @code{STATUS = SYMLNK(PATH1, PATH2)}
10203 @item @emph{Arguments}:
10204 @multitable @columnfractions .15 .70
10205 @item @var{PATH1} @tab Shall be of default @code{CHARACTER} type.
10206 @item @var{PATH2} @tab Shall be of default @code{CHARACTER} type.
10207 @item @var{STATUS} @tab (Optional) Shall be of default @code{INTEGER} type.
10210 @item @emph{See also}:
10211 @ref{LINK}, @ref{UNLINK}
10218 @section @code{SYSTEM} --- Execute a shell command
10220 @cindex system, system call
10223 @item @emph{Description}:
10224 Passes the command @var{COMMAND} to a shell (see @code{system(3)}). If
10225 argument @var{STATUS} is present, it contains the value returned by
10226 @code{system(3)}, which is presumably 0 if the shell command succeeded.
10227 Note that which shell is used to invoke the command is system-dependent
10228 and environment-dependent.
10230 This intrinsic is provided in both subroutine and function forms;
10231 however, only one form can be used in any given program unit.
10233 @item @emph{Standard}:
10236 @item @emph{Class}:
10237 Subroutine, function
10239 @item @emph{Syntax}:
10240 @multitable @columnfractions .80
10241 @item @code{CALL SYSTEM(COMMAND [, STATUS])}
10242 @item @code{STATUS = SYSTEM(COMMAND)}
10245 @item @emph{Arguments}:
10246 @multitable @columnfractions .15 .70
10247 @item @var{COMMAND} @tab Shall be of default @code{CHARACTER} type.
10248 @item @var{STATUS} @tab (Optional) Shall be of default @code{INTEGER} type.
10251 @item @emph{See also}:
10257 @section @code{SYSTEM_CLOCK} --- Time function
10258 @fnindex SYSTEM_CLOCK
10259 @cindex time, clock ticks
10260 @cindex clock ticks
10263 @item @emph{Description}:
10264 Determines the @var{COUNT} of milliseconds of wall clock time since
10265 the Epoch (00:00:00 UTC, January 1, 1970) modulo @var{COUNT_MAX},
10266 @var{COUNT_RATE} determines the number of clock ticks per second.
10267 @var{COUNT_RATE} and @var{COUNT_MAX} are constant and specific to
10268 @command{gfortran}.
10270 If there is no clock, @var{COUNT} is set to @code{-HUGE(COUNT)}, and
10271 @var{COUNT_RATE} and @var{COUNT_MAX} are set to zero
10273 @item @emph{Standard}:
10276 @item @emph{Class}:
10279 @item @emph{Syntax}:
10280 @code{CALL SYSTEM_CLOCK([COUNT, COUNT_RATE, COUNT_MAX])}
10282 @item @emph{Arguments}:
10283 @item @emph{Arguments}:
10284 @multitable @columnfractions .15 .70
10285 @item @var{COUNT} @tab (Optional) shall be a scalar of type default
10286 @code{INTEGER} with @code{INTENT(OUT)}.
10287 @item @var{COUNT_RATE} @tab (Optional) shall be a scalar of type default
10288 @code{INTEGER} with @code{INTENT(OUT)}.
10289 @item @var{COUNT_MAX} @tab (Optional) shall be a scalar of type default
10290 @code{INTEGER} with @code{INTENT(OUT)}.
10293 @item @emph{Example}:
10295 PROGRAM test_system_clock
10296 INTEGER :: count, count_rate, count_max
10297 CALL SYSTEM_CLOCK(count, count_rate, count_max)
10298 WRITE(*,*) count, count_rate, count_max
10302 @item @emph{See also}:
10303 @ref{DATE_AND_TIME}, @ref{CPU_TIME}
10309 @section @code{TAN} --- Tangent function
10312 @cindex trigonometric function, tangent
10316 @item @emph{Description}:
10317 @code{TAN(X)} computes the tangent of @var{X}.
10319 @item @emph{Standard}:
10322 @item @emph{Class}:
10325 @item @emph{Syntax}:
10326 @code{RESULT = TAN(X)}
10328 @item @emph{Arguments}:
10329 @multitable @columnfractions .15 .70
10330 @item @var{X} @tab The type shall be @code{REAL(*)}.
10333 @item @emph{Return value}:
10334 The return value is of type @code{REAL(*)}. The kind type parameter is
10335 the same as @var{X}.
10337 @item @emph{Example}:
10340 real(8) :: x = 0.165_8
10342 end program test_tan
10345 @item @emph{Specific names}:
10346 @multitable @columnfractions .20 .20 .20 .25
10347 @item Name @tab Argument @tab Return type @tab Standard
10348 @item @code{DTAN(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab F95 and later
10351 @item @emph{See also}:
10358 @section @code{TANH} --- Hyperbolic tangent function
10361 @cindex hyperbolic tangent
10362 @cindex hyperbolic function, tangent
10363 @cindex tangent, hyperbolic
10366 @item @emph{Description}:
10367 @code{TANH(X)} computes the hyperbolic tangent of @var{X}.
10369 @item @emph{Standard}:
10372 @item @emph{Class}:
10375 @item @emph{Syntax}:
10378 @item @emph{Arguments}:
10379 @multitable @columnfractions .15 .70
10380 @item @var{X} @tab The type shall be @code{REAL(*)}.
10383 @item @emph{Return value}:
10384 The return value is of type @code{REAL(*)} and lies in the range
10385 @math{ - 1 \leq tanh(x) \leq 1 }.
10387 @item @emph{Example}:
10390 real(8) :: x = 2.1_8
10392 end program test_tanh
10395 @item @emph{Specific names}:
10396 @multitable @columnfractions .20 .20 .20 .25
10397 @item Name @tab Argument @tab Return type @tab Standard
10398 @item @code{DTANH(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab F95 and later
10401 @item @emph{See also}:
10408 @section @code{TIME} --- Time function
10410 @cindex time, current
10411 @cindex current time
10414 @item @emph{Description}:
10415 Returns the current time encoded as an integer (in the manner of the
10416 UNIX function @code{time(3)}). This value is suitable for passing to
10417 @code{CTIME()}, @code{GMTIME()}, and @code{LTIME()}.
10419 This intrinsic is not fully portable, such as to systems with 32-bit
10420 @code{INTEGER} types but supporting times wider than 32 bits. Therefore,
10421 the values returned by this intrinsic might be, or become, negative, or
10422 numerically less than previous values, during a single run of the
10425 See @ref{TIME8}, for information on a similar intrinsic that might be
10426 portable to more GNU Fortran implementations, though to fewer Fortran
10429 @item @emph{Standard}:
10432 @item @emph{Class}:
10435 @item @emph{Syntax}:
10436 @code{RESULT = TIME()}
10438 @item @emph{Return value}:
10439 The return value is a scalar of type @code{INTEGER(4)}.
10441 @item @emph{See also}:
10442 @ref{CTIME}, @ref{GMTIME}, @ref{LTIME}, @ref{MCLOCK}, @ref{TIME8}
10449 @section @code{TIME8} --- Time function (64-bit)
10451 @cindex time, current
10452 @cindex current time
10455 @item @emph{Description}:
10456 Returns the current time encoded as an integer (in the manner of the
10457 UNIX function @code{time(3)}). This value is suitable for passing to
10458 @code{CTIME()}, @code{GMTIME()}, and @code{LTIME()}.
10460 @emph{Warning:} this intrinsic does not increase the range of the timing
10461 values over that returned by @code{time(3)}. On a system with a 32-bit
10462 @code{time(3)}, @code{TIME8()} will return a 32-bit value, even though
10463 it is converted to a 64-bit @code{INTEGER(8)} value. That means
10464 overflows of the 32-bit value can still occur. Therefore, the values
10465 returned by this intrinsic might be or become negative or numerically
10466 less than previous values during a single run of the compiled program.
10468 @item @emph{Standard}:
10471 @item @emph{Class}:
10474 @item @emph{Syntax}:
10475 @code{RESULT = TIME8()}
10477 @item @emph{Return value}:
10478 The return value is a scalar of type @code{INTEGER(8)}.
10480 @item @emph{See also}:
10481 @ref{CTIME}, @ref{GMTIME}, @ref{LTIME}, @ref{MCLOCK8}, @ref{TIME}
10488 @section @code{TINY} --- Smallest positive number of a real kind
10490 @cindex limits, smallest number
10491 @cindex model representation, smallest number
10494 @item @emph{Description}:
10495 @code{TINY(X)} returns the smallest positive (non zero) number
10496 in the model of the type of @code{X}.
10498 @item @emph{Standard}:
10501 @item @emph{Class}:
10504 @item @emph{Syntax}:
10505 @code{RESULT = TINY(X)}
10507 @item @emph{Arguments}:
10508 @multitable @columnfractions .15 .70
10509 @item @var{X} @tab Shall be of type @code{REAL}.
10512 @item @emph{Return value}:
10513 The return value is of the same type and kind as @var{X}
10515 @item @emph{Example}:
10516 See @code{HUGE} for an example.
10522 @section @code{TRANSFER} --- Transfer bit patterns
10528 @item @emph{Description}:
10529 Interprets the bitwise representation of @var{SOURCE} in memory as if it
10530 is the representation of a variable or array of the same type and type
10531 parameters as @var{MOLD}.
10533 This is approximately equivalent to the C concept of @emph{casting} one
10536 @item @emph{Standard}:
10539 @item @emph{Class}:
10540 Transformational function
10542 @item @emph{Syntax}:
10543 @code{RESULT = TRANSFER(SOURCE, MOLD[, SIZE])}
10545 @item @emph{Arguments}:
10546 @multitable @columnfractions .15 .70
10547 @item @var{SOURCE} @tab Shall be a scalar or an array of any type.
10548 @item @var{MOLD} @tab Shall be a scalar or an array of any type.
10549 @item @var{SIZE} @tab (Optional) shall be a scalar of type
10553 @item @emph{Return value}:
10554 The result has the same type as @var{MOLD}, with the bit level
10555 representation of @var{SOURCE}. If @var{SIZE} is present, the result is
10556 a one-dimensional array of length @var{SIZE}. If @var{SIZE} is absent
10557 but @var{MOLD} is an array (of any size or shape), the result is a one-
10558 dimensional array of the minimum length needed to contain the entirety
10559 of the bitwise representation of @var{SOURCE}. If @var{SIZE} is absent
10560 and @var{MOLD} is a scalar, the result is a scalar.
10562 If the bitwise representation of the result is longer than that of
10563 @var{SOURCE}, then the leading bits of the result correspond to those of
10564 @var{SOURCE} and any trailing bits are filled arbitrarily.
10566 When the resulting bit representation does not correspond to a valid
10567 representation of a variable of the same type as @var{MOLD}, the results
10568 are undefined, and subsequent operations on the result cannot be
10569 guaranteed to produce sensible behavior. For example, it is possible to
10570 create @code{LOGICAL} variables for which @code{@var{VAR}} and
10571 @code{.NOT.@var{VAR}} both appear to be true.
10573 @item @emph{Example}:
10575 PROGRAM test_transfer
10576 integer :: x = 2143289344
10577 print *, transfer(x, 1.0) ! prints "NaN" on i686
10585 @section @code{TRANSPOSE} --- Transpose an array of rank two
10587 @cindex array, transpose
10588 @cindex matrix, transpose
10592 @item @emph{Description}:
10593 Transpose an array of rank two. Element (i, j) of the result has the value
10594 @code{MATRIX(j, i)}, for all i, j.
10596 @item @emph{Standard}:
10599 @item @emph{Class}:
10600 Transformational function
10602 @item @emph{Syntax}:
10603 @code{RESULT = TRANSPOSE(MATRIX)}
10605 @item @emph{Arguments}:
10606 @multitable @columnfractions .15 .70
10607 @item @var{MATRIX} @tab Shall be an array of any type and have a rank of two.
10610 @item @emph{Return value}:
10611 The result has the same type as @var{MATRIX}, and has shape
10612 @code{(/ m, n /)} if @var{MATRIX} has shape @code{(/ n, m /)}.
10618 @section @code{TRIM} --- Remove trailing blank characters of a string
10620 @cindex string, remove trailing whitespace
10623 @item @emph{Description}:
10624 Removes trailing blank characters of a string.
10626 @item @emph{Standard}:
10629 @item @emph{Class}:
10630 Transformational function
10632 @item @emph{Syntax}:
10633 @code{RESULT = TRIM(STRING)}
10635 @item @emph{Arguments}:
10636 @multitable @columnfractions .15 .70
10637 @item @var{STRING} @tab Shall be a scalar of type @code{CHARACTER(*)}.
10640 @item @emph{Return value}:
10641 A scalar of type @code{CHARACTER(*)} which length is that of @var{STRING}
10642 less the number of trailing blanks.
10644 @item @emph{Example}:
10647 CHARACTER(len=10), PARAMETER :: s = "GFORTRAN "
10648 WRITE(*,*) LEN(s), LEN(TRIM(s)) ! "10 8", with/without trailing blanks
10652 @item @emph{See also}:
10653 @ref{ADJUSTL}, @ref{ADJUSTR}
10659 @section @code{TTYNAM} --- Get the name of a terminal device.
10661 @cindex system, terminal
10664 @item @emph{Description}:
10665 Get the name of a terminal device. For more information,
10666 see @code{ttyname(3)}.
10668 This intrinsic is provided in both subroutine and function forms;
10669 however, only one form can be used in any given program unit.
10671 @item @emph{Standard}:
10674 @item @emph{Class}:
10675 Subroutine, function
10677 @item @emph{Syntax}:
10678 @multitable @columnfractions .80
10679 @item @code{CALL TTYNAM(UNIT, NAME)}
10680 @item @code{NAME = TTYNAM(UNIT)}
10683 @item @emph{Arguments}:
10684 @multitable @columnfractions .15 .70
10685 @item @var{UNIT} @tab Shall be a scalar @code{INTEGER(*)}.
10686 @item @var{NAME} @tab Shall be of type @code{CHARACTER(*)}.
10689 @item @emph{Example}:
10691 PROGRAM test_ttynam
10694 IF (isatty(unit=unit)) write(*,*) ttynam(unit)
10699 @item @emph{See also}:
10706 @section @code{UBOUND} --- Upper dimension bounds of an array
10708 @cindex array, upper bound
10711 @item @emph{Description}:
10712 Returns the upper bounds of an array, or a single upper bound
10713 along the @var{DIM} dimension.
10714 @item @emph{Standard}:
10717 @item @emph{Class}:
10720 @item @emph{Syntax}:
10721 @code{RESULT = UBOUND(ARRAY [, DIM [, KIND]])}
10723 @item @emph{Arguments}:
10724 @multitable @columnfractions .15 .70
10725 @item @var{ARRAY} @tab Shall be an array, of any type.
10726 @item @var{DIM} @tab (Optional) Shall be a scalar @code{INTEGER(*)}.
10727 @item @var{KIND}@tab (Optional) An @code{INTEGER} initialization
10728 expression indicating the kind parameter of
10732 @item @emph{Return value}:
10733 The return value is of type @code{INTEGER} and of kind @var{KIND}. If
10734 @var{KIND} is absent, the return value is of default integer kind.
10735 If @var{DIM} is absent, the result is an array of the upper bounds of
10736 @var{ARRAY}. If @var{DIM} is present, the result is a scalar
10737 corresponding to the upper bound of the array along that dimension. If
10738 @var{ARRAY} is an expression rather than a whole array or array
10739 structure component, or if it has a zero extent along the relevant
10740 dimension, the upper bound is taken to be the number of elements along
10741 the relevant dimension.
10743 @item @emph{See also}:
10750 @section @code{UMASK} --- Set the file creation mask
10752 @cindex file system, file creation mask
10755 @item @emph{Description}:
10756 Sets the file creation mask to @var{MASK} and returns the old value in
10757 argument @var{OLD} if it is supplied. See @code{umask(2)}.
10759 @item @emph{Standard}:
10762 @item @emph{Class}:
10765 @item @emph{Syntax}:
10766 @code{CALL UMASK(MASK [, OLD])}
10768 @item @emph{Arguments}:
10769 @multitable @columnfractions .15 .70
10770 @item @var{MASK} @tab Shall be a scalar of type @code{INTEGER(*)}.
10771 @item @var{MASK} @tab (Optional) Shall be a scalar of type
10780 @section @code{UNLINK} --- Remove a file from the file system
10782 @cindex file system, remove file
10785 @item @emph{Description}:
10786 Unlinks the file @var{PATH}. A null character (@code{CHAR(0)}) can be
10787 used to mark the end of the name in @var{PATH}; otherwise, trailing
10788 blanks in the file name are ignored. If the @var{STATUS} argument is
10789 supplied, it contains 0 on success or a nonzero error code upon return;
10790 see @code{unlink(2)}.
10792 This intrinsic is provided in both subroutine and function forms;
10793 however, only one form can be used in any given program unit.
10795 @item @emph{Standard}:
10798 @item @emph{Class}:
10799 Subroutine, function
10801 @item @emph{Syntax}:
10802 @multitable @columnfractions .80
10803 @item @code{CALL UNLINK(PATH [, STATUS])}
10804 @item @code{STATUS = UNLINK(PATH)}
10807 @item @emph{Arguments}:
10808 @multitable @columnfractions .15 .70
10809 @item @var{PATH} @tab Shall be of default @code{CHARACTER} type.
10810 @item @var{STATUS} @tab (Optional) Shall be of default @code{INTEGER} type.
10813 @item @emph{See also}:
10814 @ref{LINK}, @ref{SYMLNK}
10820 @section @code{UNPACK} --- Unpack an array of rank one into an array
10822 @cindex array, unpacking
10823 @cindex array, increase dimension
10824 @cindex array, scatter elements
10827 @item @emph{Description}:
10828 Store the elements of @var{VECTOR} in an array of higher rank.
10830 @item @emph{Standard}:
10833 @item @emph{Class}:
10834 Transformational function
10836 @item @emph{Syntax}:
10837 @code{RESULT = UNPACK(VECTOR, MASK, FIELD)}
10839 @item @emph{Arguments}:
10840 @multitable @columnfractions .15 .70
10841 @item @var{VECTOR} @tab Shall be an array of any type and rank one. It
10842 shall have at least as many elements as @var{MASK} has @code{TRUE} values.
10843 @item @var{MASK} @tab Shall be an array of type @code{LOGICAL}.
10844 @item @var{FIELD} @tab Shall be of the same type as @var{VECTOR} and have
10845 the same shape as @var{MASK}.
10848 @item @emph{Return value}:
10849 The resulting array corresponds to @var{FIELD} with @code{TRUE} elements
10850 of @var{MASK} replaced by values from @var{VECTOR} in array element order.
10852 @item @emph{Example}:
10854 PROGRAM test_unpack
10855 integer :: vector(2) = (/1,1/)
10856 logical :: mask(4) = (/ .TRUE., .FALSE., .FALSE., .TRUE. /)
10857 integer :: field(2,2) = 0, unity(2,2)
10859 ! result: unity matrix
10860 unity = unpack(vector, reshape(mask, (/2,2/)), field)
10864 @item @emph{See also}:
10865 @ref{PACK}, @ref{SPREAD}
10871 @section @code{VERIFY} --- Scan a string for the absence of a set of characters
10873 @cindex string, find missing set
10876 @item @emph{Description}:
10877 Verifies that all the characters in a @var{SET} are present in a @var{STRING}.
10879 If @var{BACK} is either absent or equals @code{FALSE}, this function
10880 returns the position of the leftmost character of @var{STRING} that is
10881 not in @var{SET}. If @var{BACK} equals @code{TRUE}, the rightmost position
10882 is returned. If all characters of @var{SET} are found in @var{STRING}, the
10885 @item @emph{Standard}:
10888 @item @emph{Class}:
10891 @item @emph{Syntax}:
10892 @code{RESULT = VERIFY(STRING, SET[, BACK [, KIND]])}
10894 @item @emph{Arguments}:
10895 @multitable @columnfractions .15 .70
10896 @item @var{STRING} @tab Shall be of type @code{CHARACTER(*)}.
10897 @item @var{SET} @tab Shall be of type @code{CHARACTER(*)}.
10898 @item @var{BACK} @tab (Optional) shall be of type @code{LOGICAL}.
10899 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
10900 expression indicating the kind parameter of
10904 @item @emph{Return value}:
10905 The return value is of type @code{INTEGER} and of kind @var{KIND}. If
10906 @var{KIND} is absent, the return value is of default integer kind.
10908 @item @emph{Example}:
10910 PROGRAM test_verify
10911 WRITE(*,*) VERIFY("FORTRAN", "AO") ! 1, found 'F'
10912 WRITE(*,*) VERIFY("FORTRAN", "FOO") ! 3, found 'R'
10913 WRITE(*,*) VERIFY("FORTRAN", "C++") ! 1, found 'F'
10914 WRITE(*,*) VERIFY("FORTRAN", "C++", .TRUE.) ! 7, found 'N'
10915 WRITE(*,*) VERIFY("FORTRAN", "FORTRAN") ! 0' found none
10919 @item @emph{See also}:
10920 @ref{SCAN}, @ref{INDEX intrinsic}
10926 @section @code{XOR} --- Bitwise logical exclusive OR
10928 @cindex bitwise logical exclusive or
10929 @cindex logical exclusive or, bitwise
10932 @item @emph{Description}:
10933 Bitwise logical exclusive or.
10935 This intrinsic routine is provided for backwards compatibility with
10936 GNU Fortran 77. For integer arguments, programmers should consider
10937 the use of the @ref{IEOR} intrinsic defined by the Fortran standard.
10939 @item @emph{Standard}:
10942 @item @emph{Class}:
10945 @item @emph{Syntax}:
10946 @code{RESULT = XOR(X, Y)}
10948 @item @emph{Arguments}:
10949 @multitable @columnfractions .15 .70
10950 @item @var{X} @tab The type shall be either @code{INTEGER(*)} or @code{LOGICAL}.
10951 @item @var{Y} @tab The type shall be either @code{INTEGER(*)} or @code{LOGICAL}.
10954 @item @emph{Return value}:
10955 The return type is either @code{INTEGER(*)} or @code{LOGICAL}
10956 after cross-promotion of the arguments.
10958 @item @emph{Example}:
10961 LOGICAL :: T = .TRUE., F = .FALSE.
10963 DATA a / Z'F' /, b / Z'3' /
10965 WRITE (*,*) XOR(T, T), XOR(T, F), XOR(F, T), XOR(F, F)
10966 WRITE (*,*) XOR(a, b)
10970 @item @emph{See also}:
10971 F95 elemental function: @ref{IEOR}
10976 @node Intrinsic Modules
10977 @chapter Intrinsic Modules
10978 @cindex intrinsic Modules
10980 @c @node ISO_FORTRAN_ENV
10981 @section @code{ISO_FORTRAN_ENV}
10983 @item @emph{Standard}:
10984 Fortran 2003 and later
10987 The @code{ISO_FORTRAN_ENV} module provides the following scalar default-integer
10991 @item @code{CHARACTER_STORAGE_SIZE}:
10992 Size in bits of the character storage unit.
10994 @item @code{ERROR_UNIT}:
10995 Identifies the preconnected unit used for error reporting.
10997 @item @code{FILE_STORAGE_SIZE}:
10998 Size in bits of the file-storage unit.
11000 @item @code{INPUT_UNIT}:
11001 Identifies the preconnected unit identified by the asterisk
11002 (@code{*}) in @code{READ} statement.
11004 @item @code{IOSTAT_END}:
11005 The value assigned to the variable passed to the IOSTAT= specifier of
11006 an input/output statement if an end-of-file condition occurred.
11008 @item @code{IOSTAT_EOR}:
11009 The value assigned to the variable passed to the IOSTAT= specifier of
11010 an input/output statement if an end-of-record condition occurred.
11012 @item @code{NUMERIC_STORAGE_SIZE}:
11013 The size in bits of the numeric storage unit.
11015 @item @code{OUTPUT_UNIT}:
11016 Identifies the preconnected unit identified by the asterisk
11017 (@code{*}) in @code{WRITE} statement.
11020 @c @node ISO_C_BINDING
11021 @section @code{ISO_C_BINDING}
11023 @item @emph{Standard}:
11024 Fortran 2003 and later
11027 The following intrinsic procedures are provided by the module; their
11028 definition can be found in the section Intrinsic Procedures of this
11032 @item @code{C_ASSOCIATED}
11033 @item @code{C_F_POINTER}
11034 @item @code{C_F_PROCPOINTER}
11035 @item @code{C_FUNLOC}
11039 The @code{ISO_C_BINDING} module provides the following named constants of the
11040 type integer, which can be used as KIND type parameter. Note that GNU
11041 Fortran currently does not support the @code{C_INT_FAST...} KIND type
11042 parameters (marked by an asterisk (@code{*}) in the list below).
11043 The @code{C_INT_FAST...} parameters have therefore the value @math{-2}
11044 and cannot be used as KIND type parameter of the @code{INTEGER} type.
11046 @multitable @columnfractions .15 .35 .35
11047 @item Fortran Type @tab Named constant @tab C type
11048 @item @code{INTEGER}@tab @code{C_INT} @tab @code{int}
11049 @item @code{INTEGER}@tab @code{C_SHORT} @tab @code{short int}
11050 @item @code{INTEGER}@tab @code{C_LONG} @tab @code{long int}
11051 @item @code{INTEGER}@tab @code{C_LONG_LONG} @tab @code{long long int}
11052 @item @code{INTEGER}@tab @code{C_SIGNED_CHAR} @tab @code{signed char}/@code{unsigned char}
11053 @item @code{INTEGER}@tab @code{C_SIZE_T} @tab @code{size_t}
11054 @item @code{INTEGER}@tab @code{C_INT8_T} @tab @code{int8_t}
11055 @item @code{INTEGER}@tab @code{C_INT16_T} @tab @code{int16_t}
11056 @item @code{INTEGER}@tab @code{C_INT32_T} @tab @code{int32_t}
11057 @item @code{INTEGER}@tab @code{C_INT64_T} @tab @code{int64_t}
11058 @item @code{INTEGER}@tab @code{C_INT_LEAST8_T} @tab @code{int_least8_t}
11059 @item @code{INTEGER}@tab @code{C_INT_LEAST16_T} @tab @code{int_least16_t}
11060 @item @code{INTEGER}@tab @code{C_INT_LEAST32_T} @tab @code{int_least32_t}
11061 @item @code{INTEGER}@tab @code{C_INT_LEAST64_T} @tab @code{int_least64_t}
11062 @item @code{INTEGER}@tab @code{C_INT_FAST8_T}* @tab @code{int_fast8_t}
11063 @item @code{INTEGER}@tab @code{C_INT_FAST16_T}* @tab @code{int_fast16_t}
11064 @item @code{INTEGER}@tab @code{C_INT_FAST32_T}* @tab @code{int_fast32_t}
11065 @item @code{INTEGER}@tab @code{C_INT_FAST64_T}* @tab @code{int_fast64_t}
11066 @item @code{INTEGER}@tab @code{C_INTMAX_T} @tab @code{intmax_t}
11067 @item @code{INTEGER}@tab @code{C_INTPTR_T} @tab @code{intptr_t}
11068 @item @code{REAL} @tab @code{C_FLOAT} @tab @code{float}
11069 @item @code{REAL} @tab @code{C_DOUBLE} @tab @code{double}
11070 @item @code{REAL} @tab @code{C_LONG_DOUBLE} @tab @code{long double}
11071 @item @code{COMPLEX}@tab @code{C_FLOAT_COMPLEX} @tab @code{float _Complex}
11072 @item @code{COMPLEX}@tab @code{C_DOUBLE_COMPLEX}@tab @code{double _Complex}
11073 @item @code{COMPLEX}@tab @code{C_LONG_DOUBLE_COMPLEX}@tab @code{long double _Complex}
11074 @item @code{LOGICAL}@tab @code{C_BOOL} @tab @code{_Bool}
11075 @item @code{CHARACTER}@tab @code{C_CHAR} @tab @code{char}
11078 Additionally, the following @code{(CHARACTER(KIND=C_CHAR)} are
11081 @multitable @columnfractions .20 .45 .15
11082 @item Name @tab C definition @tab Value
11083 @item @code{C_NULL_CHAR} @tab null character @tab @code{'\0'}
11084 @item @code{C_ALERT} @tab alert @tab @code{'\a'}
11085 @item @code{C_BACKSPACE} @tab backspace @tab @code{'\b'}
11086 @item @code{C_FORM_FEED} @tab form feed @tab @code{'\f'}
11087 @item @code{C_NEW_LINE} @tab new line @tab @code{'\n'}
11088 @item @code{C_CARRIAGE_RETURN} @tab carriage return @tab @code{'\r'}
11089 @item @code{C_HORIZONTAL_TAB} @tab horizontal tab @tab @code{'\t'}
11090 @item @code{C_VERTICAL_TAB} @tab vertical tab @tab @code{'\v'}
11093 @c @node OpenMP Modules OMP_LIB and OMP_LIB_KINDS
11094 @section OpenMP Modules @code{OMP_LIB} and @code{OMP_LIB_KINDS}
11096 @item @emph{Standard}:
11097 OpenMP Application Program Interface v2.5
11101 The OpenMP Fortran runtime library routines are provided both in
11102 a form of two Fortran 90 modules, named @code{OMP_LIB} and
11103 @code{OMP_LIB_KINDS}, and in a form of a Fortran @code{include} file named
11104 @file{omp_lib.h}. The procedures provided by @code{OMP_LIB} can be found
11105 in the @ref{Top,,Introduction,libgomp,GNU OpenMP runtime library} manual,
11106 the named constants defined in the @code{OMP_LIB_KINDS} module are listed
11109 For details refer to the actual
11110 @uref{http://www.openmp.org/drupal/mp-documents/spec25.pdf,
11111 OpenMP Application Program Interface v2.5}.
11113 @code{OMP_LIB_KINDS} provides the following scalar default-integer
11117 @item @code{omp_integer_kind}
11118 @item @code{omp_logical_kind}
11119 @item @code{omp_lock_kind}
11120 @item @code{omp_nest_lock_kind}