2 Copyright (C) 2005, 2006, 2007
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{BESJ0}: BESJ0, Bessel function of the first kind of order 0
66 * @code{BESJ1}: BESJ1, Bessel function of the first kind of order 1
67 * @code{BESJN}: BESJN, Bessel function of the first kind
68 * @code{BESY0}: BESY0, Bessel function of the second kind of order 0
69 * @code{BESY1}: BESY1, Bessel function of the second kind of order 1
70 * @code{BESYN}: BESYN, 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{ETIME}: ETIME, Execution time subroutine (or function)
107 * @code{EXIT}: EXIT, Exit the program with status.
108 * @code{EXP}: EXP, Exponential function
109 * @code{EXPONENT}: EXPONENT, Exponent function
110 * @code{FDATE}: FDATE, Subroutine (or function) to get the current time as a string
111 * @code{FGET}: FGET, Read a single character in stream mode from stdin
112 * @code{FGETC}: FGETC, Read a single character in stream mode
113 * @code{FLOAT}: FLOAT, Convert integer to default real
114 * @code{FLOOR}: FLOOR, Integer floor function
115 * @code{FLUSH}: FLUSH, Flush I/O unit(s)
116 * @code{FNUM}: FNUM, File number function
117 * @code{FPUT}: FPUT, Write a single character in stream mode to stdout
118 * @code{FPUTC}: FPUTC, Write a single character in stream mode
119 * @code{FRACTION}: FRACTION, Fractional part of the model representation
120 * @code{FREE}: FREE, Memory de-allocation subroutine
121 * @code{FSEEK}: FSEEK, Low level file positioning subroutine
122 * @code{FSTAT}: FSTAT, Get file status
123 * @code{FTELL}: FTELL, Current stream position
124 * @code{GERROR}: GERROR, Get last system error message
125 * @code{GETARG}: GETARG, Get command line arguments
126 * @code{GET_COMMAND}: GET_COMMAND, Get the entire command line
127 * @code{GET_COMMAND_ARGUMENT}: GET_COMMAND_ARGUMENT, Get command line arguments
128 * @code{GETCWD}: GETCWD, Get current working directory
129 * @code{GETENV}: GETENV, Get an environmental variable
130 * @code{GET_ENVIRONMENT_VARIABLE}: GET_ENVIRONMENT_VARIABLE, Get an environmental variable
131 * @code{GETGID}: GETGID, Group ID function
132 * @code{GETLOG}: GETLOG, Get login name
133 * @code{GETPID}: GETPID, Process ID function
134 * @code{GETUID}: GETUID, User ID function
135 * @code{GMTIME}: GMTIME, Convert time to GMT info
136 * @code{HOSTNM}: HOSTNM, Get system host name
137 * @code{HUGE}: HUGE, Largest number of a kind
138 * @code{IACHAR}: IACHAR, Code in @acronym{ASCII} collating sequence
139 * @code{IAND}: IAND, Bitwise logical and
140 * @code{IARGC}: IARGC, Get the number of command line arguments
141 * @code{IBCLR}: IBCLR, Clear bit
142 * @code{IBITS}: IBITS, Bit extraction
143 * @code{IBSET}: IBSET, Set bit
144 * @code{ICHAR}: ICHAR, Character-to-integer conversion function
145 * @code{IDATE}: IDATE, Current local time (day/month/year)
146 * @code{IEOR}: IEOR, Bitwise logical exclusive or
147 * @code{IERRNO}: IERRNO, Function to get the last system error number
148 * @code{INDEX}: INDEX, Position of a substring within a string
149 * @code{INT}: INT, Convert to integer type
150 * @code{INT2}: INT2, Convert to 16-bit integer type
151 * @code{INT8}: INT8, Convert to 64-bit integer type
152 * @code{IOR}: IOR, Bitwise logical or
153 * @code{IRAND}: IRAND, Integer pseudo-random number
154 * @code{ISATTY}: ISATTY, Whether a unit is a terminal device
155 * @code{ISHFT}: ISHFT, Shift bits
156 * @code{ISHFTC}: ISHFTC, Shift bits circularly
157 * @code{ITIME}: ITIME, Current local time (hour/minutes/seconds)
158 * @code{KILL}: KILL, Send a signal to a process
159 * @code{KIND}: KIND, Kind of an entity
160 * @code{LBOUND}: LBOUND, Lower dimension bounds of an array
161 * @code{LEN}: LEN, Length of a character entity
162 * @code{LEN_TRIM}: LEN_TRIM, Length of a character entity without trailing blank characters
163 * @code{LGE}: LGE, Lexical greater than or equal
164 * @code{LGT}: LGT, Lexical greater than
165 * @code{LINK}: LINK, Create a hard link
166 * @code{LLE}: LLE, Lexical less than or equal
167 * @code{LLT}: LLT, Lexical less than
168 * @code{LNBLNK}: LNBLNK, Index of the last non-blank character in a string
169 * @code{LOC}: LOC, Returns the address of a variable
170 * @code{LOG}: LOG, Logarithm function
171 * @code{LOG10}: LOG10, Base 10 logarithm function
172 * @code{LOGICAL}: LOGICAL, Convert to logical type
173 * @code{LONG}: LONG, Convert to integer type
174 * @code{LSHIFT}: LSHIFT, Left shift bits
175 * @code{LSTAT}: LSTAT, Get file status
176 * @code{LTIME}: LTIME, Convert time to local time info
177 * @code{MALLOC}: MALLOC, Dynamic memory allocation function
178 * @code{MATMUL}: MATMUL, matrix multiplication
179 * @code{MAX}: MAX, Maximum value of an argument list
180 * @code{MAXEXPONENT}: MAXEXPONENT, Maximum exponent of a real kind
181 * @code{MAXLOC}: MAXLOC, Location of the maximum value within an array
182 * @code{MAXVAL}: MAXVAL, Maximum value of an array
183 * @code{MCLOCK}: MCLOCK, Time function
184 * @code{MCLOCK8}: MCLOCK8, Time function (64-bit)
185 * @code{MERGE}: MERGE, Merge arrays
186 * @code{MIN}: MIN, Minimum value of an argument list
187 * @code{MINEXPONENT}: MINEXPONENT, Minimum exponent of a real kind
188 * @code{MINLOC}: MINLOC, Location of the minimum value within an array
189 * @code{MINVAL}: MINVAL, Minimum value of an array
190 * @code{MOD}: MOD, Remainder function
191 * @code{MODULO}: MODULO, Modulo function
192 * @code{MOVE_ALLOC}: MOVE_ALLOC, Move allocation from one object to another
193 * @code{MVBITS}: MVBITS, Move bits from one integer to another
194 * @code{NEAREST}: NEAREST, Nearest representable number
195 * @code{NEW_LINE}: NEW_LINE, New line character
196 * @code{NINT}: NINT, Nearest whole number
197 * @code{NOT}: NOT, Logical negation
198 * @code{NULL}: NULL, Function that returns an disassociated pointer
199 * @code{OR}: OR, Bitwise logical OR
200 * @code{PACK}: PACK, Pack an array into an array of rank one
201 * @code{PERROR}: PERROR, Print system error message
202 * @code{PRECISION}: PRECISION, Decimal precision of a real kind
203 * @code{PRESENT}: PRESENT, Determine whether an optional dummy argument is specified
204 * @code{PRODUCT}: PRODUCT, Product of array elements
205 * @code{RADIX}: RADIX, Base of a data model
206 * @code{RANDOM_NUMBER}: RANDOM_NUMBER, Pseudo-random number
207 * @code{RANDOM_SEED}: RANDOM_SEED, Initialize a pseudo-random number sequence
208 * @code{RAND}: RAND, Real pseudo-random number
209 * @code{RANGE}: RANGE, Decimal exponent range of a real kind
210 * @code{RAN}: RAN, Real pseudo-random number
211 * @code{REAL}: REAL, Convert to real type
212 * @code{RENAME}: RENAME, Rename a file
213 * @code{REPEAT}: REPEAT, Repeated string concatenation
214 * @code{RESHAPE}: RESHAPE, Function to reshape an array
215 * @code{RRSPACING}: RRSPACING, Reciprocal of the relative spacing
216 * @code{RSHIFT}: RSHIFT, Right shift bits
217 * @code{SCALE}: SCALE, Scale a real value
218 * @code{SCAN}: SCAN, Scan a string for the presence of a set of characters
219 * @code{SECNDS}: SECNDS, Time function
220 * @code{SECOND}: SECOND, CPU time function
221 * @code{SELECTED_INT_KIND}: SELECTED_INT_KIND, Choose integer kind
222 * @code{SELECTED_REAL_KIND}: SELECTED_REAL_KIND, Choose real kind
223 * @code{SET_EXPONENT}: SET_EXPONENT, Set the exponent of the model
224 * @code{SHAPE}: SHAPE, Determine the shape of an array
225 * @code{SIGN}: SIGN, Sign copying function
226 * @code{SIGNAL}: SIGNAL, Signal handling subroutine (or function)
227 * @code{SIN}: SIN, Sine function
228 * @code{SINH}: SINH, Hyperbolic sine function
229 * @code{SIZE}: SIZE, Function to determine the size of an array
230 * @code{SIZEOF}: SIZEOF, Determine the size in bytes of an expression
231 * @code{SLEEP}: SLEEP, Sleep for the specified number of seconds
232 * @code{SNGL}: SNGL, Convert double precision real to default real
233 * @code{SPACING}: SPACING, Smallest distance between two numbers of a given type
234 * @code{SPREAD}: SPREAD, Add a dimension to an array
235 * @code{SQRT}: SQRT, Square-root function
236 * @code{SRAND}: SRAND, Reinitialize the random number generator
237 * @code{STAT}: STAT, Get file status
238 * @code{SUM}: SUM, Sum of array elements
239 * @code{SYMLNK}: SYMLNK, Create a symbolic link
240 * @code{SYSTEM}: SYSTEM, Execute a shell command
241 * @code{SYSTEM_CLOCK}: SYSTEM_CLOCK, Time function
242 * @code{TAN}: TAN, Tangent function
243 * @code{TANH}: TANH, Hyperbolic tangent function
244 * @code{TIME}: TIME, Time function
245 * @code{TIME8}: TIME8, Time function (64-bit)
246 * @code{TINY}: TINY, Smallest positive number of a real kind
247 * @code{TRANSFER}: TRANSFER, Transfer bit patterns
248 * @code{TRANSPOSE}: TRANSPOSE, Transpose an array of rank two
249 * @code{TRIM}: TRIM, Remove trailing blank characters of a string
250 * @code{TTYNAM}: TTYNAM, Get the name of a terminal device.
251 * @code{UBOUND}: UBOUND, Upper dimension bounds of an array
252 * @code{UMASK}: UMASK, Set the file creation mask
253 * @code{UNLINK}: UNLINK, Remove a file from the file system
254 * @code{UNPACK}: UNPACK, Unpack an array of rank one into an array
255 * @code{VERIFY}: VERIFY, Scan a string for the absence of a set of characters
256 * @code{XOR}: XOR, Bitwise logical exclusive or
259 @node Introduction to Intrinsics
260 @section Introduction to intrinsic procedures
262 The intrinsic procedures provided by GNU Fortran include all of the
263 intrinsic procedures required by the Fortran 95 standard, a set of
264 intrinsic procedures for backwards compatibility with G77, and a small
265 selection of intrinsic procedures from the Fortran 2003 standard. Any
266 conflict between a description here and a description in either the
267 Fortran 95 standard or the Fortran 2003 standard is unintentional, and
268 the standard(s) should be considered authoritative.
270 The enumeration of the @code{KIND} type parameter is processor defined in
271 the Fortran 95 standard. GNU Fortran defines the default integer type and
272 default real type by @code{INTEGER(KIND=4)} and @code{REAL(KIND=4)},
273 respectively. The standard mandates that both data types shall have
274 another kind, which have more precision. On typical target architectures
275 supported by @command{gfortran}, this kind type parameter is @code{KIND=8}.
276 Hence, @code{REAL(KIND=8)} and @code{DOUBLE PRECISION} are equivalent.
277 In the description of generic intrinsic procedures, the kind type parameter
278 will be specified by @code{KIND=*}, and in the description of specific
279 names for an intrinsic procedure the kind type parameter will be explicitly
280 given (e.g., @code{REAL(KIND=4)} or @code{REAL(KIND=8)}). Finally, for
281 brevity the optional @code{KIND=} syntax will be omitted.
283 Many of the intrinsic procedures take one or more optional arguments.
284 This document follows the convention used in the Fortran 95 standard,
285 and denotes such arguments by square brackets.
287 GNU Fortran offers the @option{-std=f95} and @option{-std=gnu} options,
288 which can be used to restrict the set of intrinsic procedures to a
289 given standard. By default, @command{gfortran} sets the @option{-std=gnu}
290 option, and so all intrinsic procedures described here are accepted. There
291 is one caveat. For a select group of intrinsic procedures, @command{g77}
292 implemented both a function and a subroutine. Both classes
293 have been implemented in @command{gfortran} for backwards compatibility
294 with @command{g77}. It is noted here that these functions and subroutines
295 cannot be intermixed in a given subprogram. In the descriptions that follow,
296 the applicable standard for each intrinsic procedure is noted.
301 @section @code{ABORT} --- Abort the program
303 @cindex program termination, with core dump
304 @cindex terminate program, with core dump
308 @item @emph{Description}:
309 @code{ABORT} causes immediate termination of the program. On operating
310 systems that support a core dump, @code{ABORT} will produce a core dump,
311 which is suitable for debugging purposes.
313 @item @emph{Standard}:
322 @item @emph{Return value}:
325 @item @emph{Example}:
328 integer :: i = 1, j = 2
329 if (i /= j) call abort
330 end program test_abort
333 @item @emph{See also}:
334 @ref{EXIT}, @ref{KILL}
341 @section @code{ABS} --- Absolute value
348 @cindex absolute value
351 @item @emph{Description}:
352 @code{ABS(X)} computes the absolute value of @code{X}.
354 @item @emph{Standard}:
355 F77 and later, has overloads that are GNU extensions
361 @code{RESULT = ABS(X)}
363 @item @emph{Arguments}:
364 @multitable @columnfractions .15 .70
365 @item @var{X} @tab The type of the argument shall be an @code{INTEGER(*)},
366 @code{REAL(*)}, or @code{COMPLEX(*)}.
369 @item @emph{Return value}:
370 The return value is of the same type and
371 kind as the argument except the return value is @code{REAL(*)} for a
372 @code{COMPLEX(*)} argument.
374 @item @emph{Example}:
379 complex :: z = (-1.e0,0.e0)
386 @item @emph{Specific names}:
387 @multitable @columnfractions .20 .20 .20 .25
388 @item Name @tab Argument @tab Return type @tab Standard
389 @item @code{CABS(Z)} @tab @code{COMPLEX(4) Z} @tab @code{REAL(4)} @tab F77 and later
390 @item @code{DABS(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab F77 and later
391 @item @code{IABS(I)} @tab @code{INTEGER(4) I} @tab @code{INTEGER(4)} @tab F77 and later
392 @item @code{ZABS(Z)} @tab @code{COMPLEX(8) Z} @tab @code{COMPLEX(8)} @tab GNU extension
393 @item @code{CDABS(Z)} @tab @code{COMPLEX(8) Z} @tab @code{COMPLEX(8)} @tab GNU extension
400 @section @code{ACCESS} --- Checks file access modes
402 @cindex file system, access mode
405 @item @emph{Description}:
406 @code{ACCESS(NAME, MODE)} checks whether the file @var{NAME}
407 exists, is readable, writable or executable. Except for the
408 executable check, @code{ACCESS} can be replaced by
409 Fortran 95's @code{INQUIRE}.
411 @item @emph{Standard}:
418 @code{RESULT = ACCESS(NAME, MODE)}
420 @item @emph{Arguments}:
421 @multitable @columnfractions .15 .70
422 @item @var{NAME} @tab Scalar @code{CHARACTER} with the file name.
423 Tailing blank are ignored unless the character @code{achar(0)} is
424 present, then all characters up to and excluding @code{achar(0)} are
426 @item @var{MODE} @tab Scalar @code{CHARACTER} with the file access mode,
427 may be any concatenation of @code{"r"} (readable), @code{"w"} (writable)
428 and @code{"x"} (executable), or @code{" "} to check for existence.
431 @item @emph{Return value}:
432 Returns a scalar @code{INTEGER}, which is @code{0} if the file is
433 accessible in the given mode; otherwise or if an invalid argument
434 has been given for @code{MODE} the value @code{1} is returned.
436 @item @emph{Example}:
440 character(len=*), parameter :: file = 'test.dat'
441 character(len=*), parameter :: file2 = 'test.dat '//achar(0)
442 if(access(file,' ') == 0) print *, trim(file),' is exists'
443 if(access(file,'r') == 0) print *, trim(file),' is readable'
444 if(access(file,'w') == 0) print *, trim(file),' is writable'
445 if(access(file,'x') == 0) print *, trim(file),' is executable'
446 if(access(file2,'rwx') == 0) &
447 print *, trim(file2),' is readable, writable and executable'
448 end program access_test
450 @item @emph{Specific names}:
451 @item @emph{See also}:
458 @section @code{ACHAR} --- Character in @acronym{ASCII} collating sequence
460 @cindex @acronym{ASCII} collating sequence
461 @cindex collating sequence, @acronym{ASCII}
464 @item @emph{Description}:
465 @code{ACHAR(I)} returns the character located at position @code{I}
466 in the @acronym{ASCII} collating sequence.
468 @item @emph{Standard}:
475 @code{RESULT = ACHAR(I)}
477 @item @emph{Arguments}:
478 @multitable @columnfractions .15 .70
479 @item @var{I} @tab The type shall be @code{INTEGER(*)}.
482 @item @emph{Return value}:
483 The return value is of type @code{CHARACTER} with a length of one. The
484 kind type parameter is the same as @code{KIND('A')}.
486 @item @emph{Example}:
491 end program test_achar
495 See @ref{ICHAR} for a discussion of converting between numerical values
496 and formatted string representations.
498 @item @emph{See also}:
499 @ref{CHAR}, @ref{IACHAR}, @ref{ICHAR}
506 @section @code{ACOS} --- Arccosine function
509 @cindex trigonometric function, cosine, inverse
510 @cindex cosine, inverse
513 @item @emph{Description}:
514 @code{ACOS(X)} computes the arccosine of @var{X} (inverse of @code{COS(X)}).
516 @item @emph{Standard}:
523 @code{RESULT = ACOS(X)}
525 @item @emph{Arguments}:
526 @multitable @columnfractions .15 .70
527 @item @var{X} @tab The type shall be @code{REAL(*)} with a magnitude that is
531 @item @emph{Return value}:
532 The return value is of type @code{REAL(*)} and it lies in the
533 range @math{ 0 \leq \acos(x) \leq \pi}. The kind type parameter
534 is the same as @var{X}.
536 @item @emph{Example}:
539 real(8) :: x = 0.866_8
541 end program test_acos
544 @item @emph{Specific names}:
545 @multitable @columnfractions .20 .20 .20 .25
546 @item Name @tab Argument @tab Return type @tab Standard
547 @item @code{DACOS(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab F77 and later
550 @item @emph{See also}:
551 Inverse function: @ref{COS}
558 @section @code{ACOSH} --- Hyperbolic arccosine function
561 @cindex area hyperbolic cosine
562 @cindex hyperbolic arccosine
563 @cindex hyperbolic function, cosine, inverse
564 @cindex cosine, hyperbolic, inverse
567 @item @emph{Description}:
568 @code{ACOSH(X)} computes the hyperbolic arccosine of @var{X} (inverse of
571 @item @emph{Standard}:
578 @code{RESULT = ACOSH(X)}
580 @item @emph{Arguments}:
581 @multitable @columnfractions .15 .70
582 @item @var{X} @tab The type shall be @code{REAL(*)} with a magnitude that is
583 greater or equal to one.
586 @item @emph{Return value}:
587 The return value is of type @code{REAL(*)} and it lies in the
588 range @math{0 \leq \acosh (x) \leq \infty}.
590 @item @emph{Example}:
593 REAL(8), DIMENSION(3) :: x = (/ 1.0, 2.0, 3.0 /)
598 @item @emph{Specific names}:
599 @multitable @columnfractions .20 .20 .20 .25
600 @item Name @tab Argument @tab Return type @tab Standard
601 @item @code{DACOSH(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU extension
604 @item @emph{See also}:
605 Inverse function: @ref{COSH}
611 @section @code{ADJUSTL} --- Left adjust a string
613 @cindex string, adjust left
614 @cindex adjust string
617 @item @emph{Description}:
618 @code{ADJUSTL(STR)} will left adjust a string by removing leading spaces.
619 Spaces are inserted at the end of the string as needed.
621 @item @emph{Standard}:
628 @code{RESULT = ADJUSTL(STR)}
630 @item @emph{Arguments}:
631 @multitable @columnfractions .15 .70
632 @item @var{STR} @tab The type shall be @code{CHARACTER}.
635 @item @emph{Return value}:
636 The return value is of type @code{CHARACTER} where leading spaces
637 are removed and the same number of spaces are inserted on the end
640 @item @emph{Example}:
643 character(len=20) :: str = ' gfortran'
646 end program test_adjustl
649 @item @emph{See also}:
650 @ref{ADJUSTR}, @ref{TRIM}
656 @section @code{ADJUSTR} --- Right adjust a string
658 @cindex string, adjust right
659 @cindex adjust string
662 @item @emph{Description}:
663 @code{ADJUSTR(STR)} will right adjust a string by removing trailing spaces.
664 Spaces are inserted at the start of the string as needed.
666 @item @emph{Standard}:
673 @code{RESULT = ADJUSTR(STR)}
675 @item @emph{Arguments}:
676 @multitable @columnfractions .15 .70
677 @item @var{STR} @tab The type shall be @code{CHARACTER}.
680 @item @emph{Return value}:
681 The return value is of type @code{CHARACTER} where trailing spaces
682 are removed and the same number of spaces are inserted at the start
685 @item @emph{Example}:
688 character(len=20) :: str = 'gfortran'
691 end program test_adjustr
694 @item @emph{See also}:
695 @ref{ADJUSTL}, @ref{TRIM}
701 @section @code{AIMAG} --- Imaginary part of complex number
706 @cindex complex numbers, imaginary part
709 @item @emph{Description}:
710 @code{AIMAG(Z)} yields the imaginary part of complex argument @code{Z}.
711 The @code{IMAG(Z)} and @code{IMAGPART(Z)} intrinsic functions are provided
712 for compatibility with @command{g77}, and their use in new code is
713 strongly discouraged.
715 @item @emph{Standard}:
716 F77 and later, has overloads that are GNU extensions
722 @code{RESULT = AIMAG(Z)}
724 @item @emph{Arguments}:
725 @multitable @columnfractions .15 .70
726 @item @var{Z} @tab The type of the argument shall be @code{COMPLEX(*)}.
729 @item @emph{Return value}:
730 The return value is of type real with the
731 kind type parameter of the argument.
733 @item @emph{Example}:
738 z4 = cmplx(1.e0_4, 0.e0_4)
739 z8 = cmplx(0.e0_8, 1.e0_8)
740 print *, aimag(z4), dimag(z8)
741 end program test_aimag
744 @item @emph{Specific names}:
745 @multitable @columnfractions .20 .20 .20 .25
746 @item Name @tab Argument @tab Return type @tab Standard
747 @item @code{DIMAG(Z)} @tab @code{COMPLEX(8) Z} @tab @code{REAL(8)} @tab GNU extension
748 @item @code{IMAG(Z)} @tab @code{COMPLEX(*) Z} @tab @code{REAL(*)} @tab GNU extension
749 @item @code{IMAGPART(Z)} @tab @code{COMPLEX(*) Z} @tab @code{REAL(*)} @tab GNU extension
756 @section @code{AINT} --- Truncate to a whole number
760 @cindex rounding, floor
763 @item @emph{Description}:
764 @code{AINT(X [, KIND])} truncates its argument to a whole number.
766 @item @emph{Standard}:
773 @code{RESULT = AINT(X [, KIND])}
775 @item @emph{Arguments}:
776 @multitable @columnfractions .15 .70
777 @item @var{X} @tab The type of the argument shall be @code{REAL(*)}.
778 @item @var{KIND} @tab (Optional) An @code{INTEGER(*)} initialization
779 expression indicating the kind parameter of
783 @item @emph{Return value}:
784 The return value is of type real with the kind type parameter of the
785 argument if the optional @var{KIND} is absent; otherwise, the kind
786 type parameter will be given by @var{KIND}. If the magnitude of
787 @var{X} is less than one, then @code{AINT(X)} returns zero. If the
788 magnitude is equal to or greater than one, then it returns the largest
789 whole number that does not exceed its magnitude. The sign is the same
790 as the sign of @var{X}.
792 @item @emph{Example}:
799 print *, aint(x4), dint(x8)
801 end program test_aint
804 @item @emph{Specific names}:
805 @multitable @columnfractions .20 .20 .20 .25
806 @item Name @tab Argument @tab Return type @tab Standard
807 @item @code{DINT(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab F77 and later
814 @section @code{ALARM} --- Execute a routine after a given delay
816 @cindex delayed execution
819 @item @emph{Description}:
820 @code{ALARM(SECONDS, HANDLER [, STATUS])} causes external subroutine @var{HANDLER}
821 to be executed after a delay of @var{SECONDS} by using @code{alarm(2)} to
822 set up a signal and @code{signal(2)} to catch it. If @var{STATUS} is
823 supplied, it will be returned with the number of seconds remaining until
824 any previously scheduled alarm was due to be delivered, or zero if there
825 was no previously scheduled alarm.
827 @item @emph{Standard}:
834 @code{CALL ALARM(SECONDS, HANDLER [, STATUS])}
836 @item @emph{Arguments}:
837 @multitable @columnfractions .15 .70
838 @item @var{SECONDS} @tab The type of the argument shall be a scalar
839 @code{INTEGER}. It is @code{INTENT(IN)}.
840 @item @var{HANDLER} @tab Signal handler (@code{INTEGER FUNCTION} or
841 @code{SUBROUTINE}) or dummy/global @code{INTEGER} scalar. The scalar
842 values may be either @code{SIG_IGN=1} to ignore the alarm generated
843 or @code{SIG_DFL=0} to set the default action. It is @code{INTENT(IN)}.
844 @item @var{STATUS} @tab (Optional) @var{STATUS} shall be a scalar
845 variable of the default @code{INTEGER} kind. It is @code{INTENT(OUT)}.
848 @item @emph{Example}:
851 external handler_print
853 call alarm (3, handler_print, i)
856 end program test_alarm
858 This will cause the external routine @var{handler_print} to be called
865 @section @code{ALL} --- All values in @var{MASK} along @var{DIM} are true
867 @cindex array, apply condition
868 @cindex array, condition testing
871 @item @emph{Description}:
872 @code{ALL(MASK [, DIM])} determines if all the values are true in @var{MASK}
873 in the array along dimension @var{DIM}.
875 @item @emph{Standard}:
879 Transformational function
882 @code{RESULT = ALL(MASK [, DIM])}
884 @item @emph{Arguments}:
885 @multitable @columnfractions .15 .70
886 @item @var{MASK} @tab The type of the argument shall be @code{LOGICAL(*)} and
887 it shall not be scalar.
888 @item @var{DIM} @tab (Optional) @var{DIM} shall be a scalar integer
889 with a value that lies between one and the rank of @var{MASK}.
892 @item @emph{Return value}:
893 @code{ALL(MASK)} returns a scalar value of type @code{LOGICAL(*)} where
894 the kind type parameter is the same as the kind type parameter of
895 @var{MASK}. If @var{DIM} is present, then @code{ALL(MASK, DIM)} returns
896 an array with the rank of @var{MASK} minus 1. The shape is determined from
897 the shape of @var{MASK} where the @var{DIM} dimension is elided.
901 @code{ALL(MASK)} is true if all elements of @var{MASK} are true.
902 It also is true if @var{MASK} has zero size; otherwise, it is false.
904 If the rank of @var{MASK} is one, then @code{ALL(MASK,DIM)} is equivalent
905 to @code{ALL(MASK)}. If the rank is greater than one, then @code{ALL(MASK,DIM)}
906 is determined by applying @code{ALL} to the array sections.
909 @item @emph{Example}:
913 l = all((/.true., .true., .true./))
918 integer a(2,3), b(2,3)
922 print *, all(a .eq. b, 1)
923 print *, all(a .eq. b, 2)
924 end subroutine section
932 @section @code{ALLOCATED} --- Status of an allocatable entity
934 @cindex allocation, status
937 @item @emph{Description}:
938 @code{ALLOCATED(X)} checks the status of whether @var{X} is allocated.
940 @item @emph{Standard}:
947 @code{RESULT = ALLOCATED(X)}
949 @item @emph{Arguments}:
950 @multitable @columnfractions .15 .70
951 @item @var{X} @tab The argument shall be an @code{ALLOCATABLE} array.
954 @item @emph{Return value}:
955 The return value is a scalar @code{LOGICAL} with the default logical
956 kind type parameter. If @var{X} is allocated, @code{ALLOCATED(X)}
957 is @code{.TRUE.}; otherwise, it returns the @code{.TRUE.}
959 @item @emph{Example}:
961 program test_allocated
963 real(4), allocatable :: x(:)
964 if (allocated(x) .eqv. .false.) allocate(x(i))
965 end program test_allocated
972 @section @code{AND} --- Bitwise logical AND
974 @cindex bitwise logical and
975 @cindex logical and, bitwise
978 @item @emph{Description}:
979 Bitwise logical @code{AND}.
981 This intrinsic routine is provided for backwards compatibility with
982 GNU Fortran 77. For integer arguments, programmers should consider
983 the use of the @ref{IAND} intrinsic defined by the Fortran standard.
985 @item @emph{Standard}:
992 @code{RESULT = AND(I, J)}
994 @item @emph{Arguments}:
995 @multitable @columnfractions .15 .70
996 @item @var{I} @tab The type shall be either @code{INTEGER(*)} or @code{LOGICAL}.
997 @item @var{J} @tab The type shall be either @code{INTEGER(*)} or @code{LOGICAL}.
1000 @item @emph{Return value}:
1001 The return type is either @code{INTEGER(*)} or @code{LOGICAL} after
1002 cross-promotion of the arguments.
1004 @item @emph{Example}:
1007 LOGICAL :: T = .TRUE., F = .FALSE.
1009 DATA a / Z'F' /, b / Z'3' /
1011 WRITE (*,*) AND(T, T), AND(T, F), AND(F, T), AND(F, F)
1012 WRITE (*,*) AND(a, b)
1016 @item @emph{See also}:
1017 F95 elemental function: @ref{IAND}
1023 @section @code{ANINT} --- Nearest whole number
1027 @cindex rounding, ceiling
1030 @item @emph{Description}:
1031 @code{ANINT(X [, KIND])} rounds its argument to the nearest whole number.
1033 @item @emph{Standard}:
1039 @item @emph{Syntax}:
1040 @code{RESULT = ANINT(X [, KIND])}
1042 @item @emph{Arguments}:
1043 @multitable @columnfractions .15 .70
1044 @item @var{X} @tab The type of the argument shall be @code{REAL(*)}.
1045 @item @var{KIND} @tab (Optional) An @code{INTEGER(*)} initialization
1046 expression indicating the kind parameter of
1050 @item @emph{Return value}:
1051 The return value is of type real with the kind type parameter of the
1052 argument if the optional @var{KIND} is absent; otherwise, the kind
1053 type parameter will be given by @var{KIND}. If @var{X} is greater than
1054 zero, then @code{ANINT(X)} returns @code{AINT(X+0.5)}. If @var{X} is
1055 less than or equal to zero, then it returns @code{AINT(X-0.5)}.
1057 @item @emph{Example}:
1064 print *, anint(x4), dnint(x8)
1066 end program test_anint
1069 @item @emph{Specific names}:
1070 @multitable @columnfractions .20 .20 .20 .25
1071 @item Name @tab Argument @tab Return type @tab Standard
1072 @item @code{DNINT(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab F77 and later
1079 @section @code{ANY} --- Any value in @var{MASK} along @var{DIM} is true
1081 @cindex array, apply condition
1082 @cindex array, condition testing
1085 @item @emph{Description}:
1086 @code{ANY(MASK [, DIM])} determines if any of the values in the logical array
1087 @var{MASK} along dimension @var{DIM} are @code{.TRUE.}.
1089 @item @emph{Standard}:
1093 Transformational function
1095 @item @emph{Syntax}:
1096 @code{RESULT = ANY(MASK [, DIM])}
1098 @item @emph{Arguments}:
1099 @multitable @columnfractions .15 .70
1100 @item @var{MASK} @tab The type of the argument shall be @code{LOGICAL(*)} and
1101 it shall not be scalar.
1102 @item @var{DIM} @tab (Optional) @var{DIM} shall be a scalar integer
1103 with a value that lies between one and the rank of @var{MASK}.
1106 @item @emph{Return value}:
1107 @code{ANY(MASK)} returns a scalar value of type @code{LOGICAL(*)} where
1108 the kind type parameter is the same as the kind type parameter of
1109 @var{MASK}. If @var{DIM} is present, then @code{ANY(MASK, DIM)} returns
1110 an array with the rank of @var{MASK} minus 1. The shape is determined from
1111 the shape of @var{MASK} where the @var{DIM} dimension is elided.
1115 @code{ANY(MASK)} is true if any element of @var{MASK} is true;
1116 otherwise, it is false. It also is false if @var{MASK} has zero size.
1118 If the rank of @var{MASK} is one, then @code{ANY(MASK,DIM)} is equivalent
1119 to @code{ANY(MASK)}. If the rank is greater than one, then @code{ANY(MASK,DIM)}
1120 is determined by applying @code{ANY} to the array sections.
1123 @item @emph{Example}:
1127 l = any((/.true., .true., .true./))
1132 integer a(2,3), b(2,3)
1136 print *, any(a .eq. b, 1)
1137 print *, any(a .eq. b, 2)
1138 end subroutine section
1139 end program test_any
1146 @section @code{ASIN} --- Arcsine function
1149 @cindex trigonometric function, sine, inverse
1150 @cindex sine, inverse
1153 @item @emph{Description}:
1154 @code{ASIN(X)} computes the arcsine of its @var{X} (inverse of @code{SIN(X)}).
1156 @item @emph{Standard}:
1162 @item @emph{Syntax}:
1163 @code{RESULT = ASIN(X)}
1165 @item @emph{Arguments}:
1166 @multitable @columnfractions .15 .70
1167 @item @var{X} @tab The type shall be @code{REAL(*)}, and a magnitude that is
1171 @item @emph{Return value}:
1172 The return value is of type @code{REAL(*)} and it lies in the
1173 range @math{-\pi / 2 \leq \asin (x) \leq \pi / 2}. The kind type
1174 parameter is the same as @var{X}.
1176 @item @emph{Example}:
1179 real(8) :: x = 0.866_8
1181 end program test_asin
1184 @item @emph{Specific names}:
1185 @multitable @columnfractions .20 .20 .20 .25
1186 @item Name @tab Argument @tab Return type @tab Standard
1187 @item @code{DASIN(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab F77 and later
1190 @item @emph{See also}:
1191 Inverse function: @ref{SIN}
1198 @section @code{ASINH} --- Hyperbolic arcsine function
1201 @cindex area hyperbolic sine
1202 @cindex hyperbolic arcsine
1203 @cindex hyperbolic function, sine, inverse
1204 @cindex sine, hyperbolic, inverse
1207 @item @emph{Description}:
1208 @code{ASINH(X)} computes the hyperbolic arcsine of @var{X} (inverse of @code{SINH(X)}).
1210 @item @emph{Standard}:
1216 @item @emph{Syntax}:
1217 @code{RESULT = ASINH(X)}
1219 @item @emph{Arguments}:
1220 @multitable @columnfractions .15 .70
1221 @item @var{X} @tab The type shall be @code{REAL(*)}, with @var{X} a real number.
1224 @item @emph{Return value}:
1225 The return value is of type @code{REAL(*)} and it lies in the
1226 range @math{-\infty \leq \asinh (x) \leq \infty}.
1228 @item @emph{Example}:
1231 REAL(8), DIMENSION(3) :: x = (/ -1.0, 0.0, 1.0 /)
1232 WRITE (*,*) ASINH(x)
1236 @item @emph{Specific names}:
1237 @multitable @columnfractions .20 .20 .20 .25
1238 @item Name @tab Argument @tab Return type @tab Standard
1239 @item @code{DASINH(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU extension.
1242 @item @emph{See also}:
1243 Inverse function: @ref{SINH}
1249 @section @code{ASSOCIATED} --- Status of a pointer or pointer/target pair
1251 @cindex pointer, status
1252 @cindex association status
1255 @item @emph{Description}:
1256 @code{ASSOCIATED(PTR [, TGT])} determines the status of the pointer @var{PTR}
1257 or if @var{PTR} is associated with the target @var{TGT}.
1259 @item @emph{Standard}:
1265 @item @emph{Syntax}:
1266 @code{RESULT = ASSOCIATED(PTR [, TGT])}
1268 @item @emph{Arguments}:
1269 @multitable @columnfractions .15 .70
1270 @item @var{PTR} @tab @var{PTR} shall have the @code{POINTER} attribute and
1271 it can be of any type.
1272 @item @var{TGT} @tab (Optional) @var{TGT} shall be a @code{POINTER} or
1273 a @code{TARGET}. It must have the same type, kind type parameter, and
1274 array rank as @var{PTR}.
1276 The status of neither @var{PTR} nor @var{TGT} can be undefined.
1278 @item @emph{Return value}:
1279 @code{ASSOCIATED(PTR)} returns a scalar value of type @code{LOGICAL(4)}.
1280 There are several cases:
1282 @item (A) If the optional @var{TGT} is not present, then @code{ASSOCIATED(PTR)}
1283 is true if @var{PTR} is associated with a target; otherwise, it returns false.
1284 @item (B) If @var{TGT} is present and a scalar target, the result is true if
1286 is not a 0 sized storage sequence and the target associated with @var{PTR}
1287 occupies the same storage units. If @var{PTR} is disassociated, then the
1289 @item (C) If @var{TGT} is present and an array target, the result is true if
1290 @var{TGT} and @var{PTR} have the same shape, are not 0 sized arrays, are
1291 arrays whose elements are not 0 sized storage sequences, and @var{TGT} and
1292 @var{PTR} occupy the same storage units in array element order.
1293 As in case(B), the result is false, if @var{PTR} is disassociated.
1294 @item (D) If @var{TGT} is present and an scalar pointer, the result is true if
1295 target associated with @var{PTR} and the target associated with @var{TGT}
1296 are not 0 sized storage sequences and occupy the same storage units.
1297 The result is false, if either @var{TGT} or @var{PTR} is disassociated.
1298 @item (E) If @var{TGT} is present and an array pointer, the result is true if
1299 target associated with @var{PTR} and the target associated with @var{TGT}
1300 have the same shape, are not 0 sized arrays, are arrays whose elements are
1301 not 0 sized storage sequences, and @var{TGT} and @var{PTR} occupy the same
1302 storage units in array element order.
1303 The result is false, if either @var{TGT} or @var{PTR} is disassociated.
1306 @item @emph{Example}:
1308 program test_associated
1310 real, target :: tgt(2) = (/1., 2./)
1311 real, pointer :: ptr(:)
1313 if (associated(ptr) .eqv. .false.) call abort
1314 if (associated(ptr,tgt) .eqv. .false.) call abort
1315 end program test_associated
1318 @item @emph{See also}:
1325 @section @code{ATAN} --- Arctangent function
1328 @cindex trigonometric function, tangent, inverse
1329 @cindex tangent, inverse
1332 @item @emph{Description}:
1333 @code{ATAN(X)} computes the arctangent of @var{X}.
1335 @item @emph{Standard}:
1341 @item @emph{Syntax}:
1342 @code{RESULT = ATAN(X)}
1344 @item @emph{Arguments}:
1345 @multitable @columnfractions .15 .70
1346 @item @var{X} @tab The type shall be @code{REAL(*)}.
1349 @item @emph{Return value}:
1350 The return value is of type @code{REAL(*)} and it lies in the
1351 range @math{ - \pi / 2 \leq \atan (x) \leq \pi / 2}.
1353 @item @emph{Example}:
1356 real(8) :: x = 2.866_8
1358 end program test_atan
1361 @item @emph{Specific names}:
1362 @multitable @columnfractions .20 .20 .20 .25
1363 @item Name @tab Argument @tab Return type @tab Standard
1364 @item @code{DATAN(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab F77 and later
1367 @item @emph{See also}:
1368 Inverse function: @ref{TAN}
1375 @section @code{ATAN2} --- Arctangent function
1378 @cindex trigonometric function, tangent, inverse
1379 @cindex tangent, inverse
1382 @item @emph{Description}:
1383 @code{ATAN2(Y,X)} computes the arctangent of the complex number
1386 @item @emph{Standard}:
1392 @item @emph{Syntax}:
1393 @code{RESULT = ATAN2(Y,X)}
1395 @item @emph{Arguments}:
1396 @multitable @columnfractions .15 .70
1397 @item @var{Y} @tab The type shall be @code{REAL(*)}.
1398 @item @var{X} @tab The type and kind type parameter shall be the same as @var{Y}.
1399 If @var{Y} is zero, then @var{X} must be nonzero.
1402 @item @emph{Return value}:
1403 The return value has the same type and kind type parameter as @var{Y}.
1404 It is the principal value of the complex number @math{X + i Y}. If
1405 @var{X} is nonzero, then it lies in the range @math{-\pi \le \atan (x) \leq \pi}.
1406 The sign is positive if @var{Y} is positive. If @var{Y} is zero, then
1407 the return value is zero if @var{X} is positive and @math{\pi} if @var{X}
1408 is negative. Finally, if @var{X} is zero, then the magnitude of the result
1411 @item @emph{Example}:
1414 real(4) :: x = 1.e0_4, y = 0.5e0_4
1416 end program test_atan2
1419 @item @emph{Specific names}:
1420 @multitable @columnfractions .20 .20 .20 .25
1421 @item Name @tab Argument @tab Return type @tab Standard
1422 @item @code{DATAN2(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab F77 and later
1429 @section @code{ATANH} --- Hyperbolic arctangent function
1432 @cindex area hyperbolic tangent
1433 @cindex hyperbolic arctangent
1434 @cindex hyperbolic function, tangent, inverse
1435 @cindex tangent, hyperbolic, inverse
1438 @item @emph{Description}:
1439 @code{ATANH(X)} computes the hyperbolic arctangent of @var{X} (inverse
1442 @item @emph{Standard}:
1448 @item @emph{Syntax}:
1449 @code{RESULT = ATANH(X)}
1451 @item @emph{Arguments}:
1452 @multitable @columnfractions .15 .70
1453 @item @var{X} @tab The type shall be @code{REAL(*)} with a magnitude
1454 that is less than or equal to one.
1457 @item @emph{Return value}:
1458 The return value is of type @code{REAL(*)} and it lies in the
1459 range @math{-\infty \leq \atanh(x) \leq \infty}.
1461 @item @emph{Example}:
1464 REAL, DIMENSION(3) :: x = (/ -1.0, 0.0, 1.0 /)
1465 WRITE (*,*) ATANH(x)
1469 @item @emph{Specific names}:
1470 @multitable @columnfractions .20 .20 .20 .25
1471 @item Name @tab Argument @tab Return type @tab Standard
1472 @item @code{DATANH(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU extension
1475 @item @emph{See also}:
1476 Inverse function: @ref{TANH}
1482 @section @code{BESJ0} --- Bessel function of the first kind of order 0
1485 @cindex Bessel function, first kind
1488 @item @emph{Description}:
1489 @code{BESJ0(X)} computes the Bessel function of the first kind of order 0
1492 @item @emph{Standard}:
1498 @item @emph{Syntax}:
1499 @code{RESULT = BESJ0(X)}
1501 @item @emph{Arguments}:
1502 @multitable @columnfractions .15 .70
1503 @item @var{X} @tab The type shall be @code{REAL(*)}, and it shall be scalar.
1506 @item @emph{Return value}:
1507 The return value is of type @code{REAL(*)} and it lies in the
1508 range @math{ - 0.4027... \leq Bessel (0,x) \leq 1}.
1510 @item @emph{Example}:
1513 real(8) :: x = 0.0_8
1515 end program test_besj0
1518 @item @emph{Specific names}:
1519 @multitable @columnfractions .20 .20 .20 .25
1520 @item Name @tab Argument @tab Return type @tab Standard
1521 @item @code{DBESJ0(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU extension
1528 @section @code{BESJ1} --- Bessel function of the first kind of order 1
1531 @cindex Bessel function, first kind
1534 @item @emph{Description}:
1535 @code{BESJ1(X)} computes the Bessel function of the first kind of order 1
1538 @item @emph{Standard}:
1544 @item @emph{Syntax}:
1545 @code{RESULT = BESJ1(X)}
1547 @item @emph{Arguments}:
1548 @multitable @columnfractions .15 .70
1549 @item @var{X} @tab The type shall be @code{REAL(*)}, and it shall be scalar.
1552 @item @emph{Return value}:
1553 The return value is of type @code{REAL(*)} and it lies in the
1554 range @math{ - 0.5818... \leq Bessel (0,x) \leq 0.5818 }.
1556 @item @emph{Example}:
1559 real(8) :: x = 1.0_8
1561 end program test_besj1
1564 @item @emph{Specific names}:
1565 @multitable @columnfractions .20 .20 .20 .25
1566 @item Name @tab Argument @tab Return type @tab Standard
1567 @item @code{DBESJ1(X)}@tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU extension
1574 @section @code{BESJN} --- Bessel function of the first kind
1577 @cindex Bessel function, first kind
1580 @item @emph{Description}:
1581 @code{BESJN(N, X)} computes the Bessel function of the first kind of order
1584 If both arguments are arrays, their ranks and shapes shall conform.
1586 @item @emph{Standard}:
1592 @item @emph{Syntax}:
1593 @code{RESULT = BESJN(N, X)}
1595 @item @emph{Arguments}:
1596 @multitable @columnfractions .15 .70
1597 @item @var{N} @tab Shall be a scalar or an array of type @code{INTEGER(*)}.
1598 @item @var{X} @tab Shall be a scalar or an array of type @code{REAL(*)}.
1601 @item @emph{Return value}:
1602 The return value is a scalar of type @code{REAL(*)}.
1604 @item @emph{Example}:
1607 real(8) :: x = 1.0_8
1609 end program test_besjn
1612 @item @emph{Specific names}:
1613 @multitable @columnfractions .20 .20 .20 .25
1614 @item Name @tab Argument @tab Return type @tab Standard
1615 @item @code{DBESJN(X)} @tab @code{INTEGER(*) N} @tab @code{REAL(8)} @tab GNU extension
1616 @item @tab @code{REAL(8) X} @tab @tab
1623 @section @code{BESY0} --- Bessel function of the second kind of order 0
1626 @cindex Bessel function, second kind
1629 @item @emph{Description}:
1630 @code{BESY0(X)} computes the Bessel function of the second kind of order 0
1633 @item @emph{Standard}:
1639 @item @emph{Syntax}:
1640 @code{RESULT = BESY0(X)}
1642 @item @emph{Arguments}:
1643 @multitable @columnfractions .15 .70
1644 @item @var{X} @tab The type shall be @code{REAL(*)}, and it shall be scalar.
1647 @item @emph{Return value}:
1648 The return value is a scalar of type @code{REAL(*)}.
1650 @item @emph{Example}:
1653 real(8) :: x = 0.0_8
1655 end program test_besy0
1658 @item @emph{Specific names}:
1659 @multitable @columnfractions .20 .20 .20 .25
1660 @item Name @tab Argument @tab Return type @tab Standard
1661 @item @code{DBESY0(X)}@tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU extension
1668 @section @code{BESY1} --- Bessel function of the second kind of order 1
1671 @cindex Bessel function, second kind
1674 @item @emph{Description}:
1675 @code{BESY1(X)} computes the Bessel function of the second kind of order 1
1678 @item @emph{Standard}:
1684 @item @emph{Syntax}:
1685 @code{RESULT = BESY1(X)}
1687 @item @emph{Arguments}:
1688 @multitable @columnfractions .15 .70
1689 @item @var{X} @tab The type shall be @code{REAL(*)}, and it shall be scalar.
1692 @item @emph{Return value}:
1693 The return value is a scalar of type @code{REAL(*)}.
1695 @item @emph{Example}:
1698 real(8) :: x = 1.0_8
1700 end program test_besy1
1703 @item @emph{Specific names}:
1704 @multitable @columnfractions .20 .20 .20 .25
1705 @item Name @tab Argument @tab Return type @tab Standard
1706 @item @code{DBESY1(X)}@tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU extension
1713 @section @code{BESYN} --- Bessel function of the second kind
1716 @cindex Bessel function, second kind
1719 @item @emph{Description}:
1720 @code{BESYN(N, X)} computes the Bessel function of the second kind of order
1723 If both arguments are arrays, their ranks and shapes shall conform.
1725 @item @emph{Standard}:
1731 @item @emph{Syntax}:
1732 @code{RESULT = BESYN(N, X)}
1734 @item @emph{Arguments}:
1735 @multitable @columnfractions .15 .70
1736 @item @var{N} @tab Shall be a scalar or an array of type @code{INTEGER(*)}.
1737 @item @var{X} @tab Shall be a scalar or an array of type @code{REAL(*)}.
1740 @item @emph{Return value}:
1741 The return value is a scalar of type @code{REAL(*)}.
1743 @item @emph{Example}:
1746 real(8) :: x = 1.0_8
1748 end program test_besyn
1751 @item @emph{Specific names}:
1752 @multitable @columnfractions .20 .20 .20 .25
1753 @item Name @tab Argument @tab Return type @tab Standard
1754 @item @code{DBESYN(N,X)} @tab @code{INTEGER(*) N} @tab @code{REAL(8)} @tab GNU extension
1755 @item @tab @code{REAL(8) X} @tab @tab
1762 @section @code{BIT_SIZE} --- Bit size inquiry function
1764 @cindex bits, number of
1765 @cindex size of a variable, in bits
1768 @item @emph{Description}:
1769 @code{BIT_SIZE(I)} returns the number of bits (integer precision plus sign bit)
1770 represented by the type of @var{I}.
1772 @item @emph{Standard}:
1778 @item @emph{Syntax}:
1779 @code{RESULT = BIT_SIZE(I)}
1781 @item @emph{Arguments}:
1782 @multitable @columnfractions .15 .70
1783 @item @var{I} @tab The type shall be @code{INTEGER(*)}.
1786 @item @emph{Return value}:
1787 The return value is of type @code{INTEGER(*)}
1789 @item @emph{Example}:
1791 program test_bit_size
1796 end program test_bit_size
1803 @section @code{BTEST} --- Bit test function
1805 @cindex bits, testing
1808 @item @emph{Description}:
1809 @code{BTEST(I,POS)} returns logical @code{.TRUE.} if the bit at @var{POS}
1812 @item @emph{Standard}:
1818 @item @emph{Syntax}:
1819 @code{RESULT = BTEST(I, POS)}
1821 @item @emph{Arguments}:
1822 @multitable @columnfractions .15 .70
1823 @item @var{I} @tab The type shall be @code{INTEGER(*)}.
1824 @item @var{POS} @tab The type shall be @code{INTEGER(*)}.
1827 @item @emph{Return value}:
1828 The return value is of type @code{LOGICAL}
1830 @item @emph{Example}:
1833 integer :: i = 32768 + 1024 + 64
1837 bool = btest(i, pos)
1840 end program test_btest
1846 @section @code{C_ASSOCIATED} --- Status of a C pointer
1847 @fnindex C_ASSOCIATED
1848 @cindex association status, C pointer
1849 @cindex pointer, C association status
1852 @item @emph{Description}:
1853 @code{C_ASSOICATED(c_prt1[, c_ptr2])} determines the status of the C pointer @var{c_ptr1}
1854 or if @var{c_ptr1} is associated with the target @var{c_ptr2}.
1856 @item @emph{Standard}:
1862 @item @emph{Syntax}:
1863 @code{RESULT = C_ASSOICATED(c_prt1[, c_ptr2])}
1865 @item @emph{Arguments}:
1866 @multitable @columnfractions .15 .70
1867 @item @var{c_ptr1} @tab Scalar of the type @code{C_PTR} or @code{C_FUNPTR}.
1868 @item @var{c_ptr2} @tab (Optional) Scalar of the same type as @var{c_ptr1}.
1871 @item @emph{Return value}:
1872 The return value is of type @code{LOGICAL}; it is @code{.false.} if either
1873 @var{c_ptr1} is a C NULL pointer or if @var{c_ptr1} and @var{c_ptr2}
1874 point to different addresses.
1876 @item @emph{Example}:
1878 subroutine association_test(a,b)
1879 use iso_c_binding, only: c_associated, c_loc, c_ptr
1883 if(c_associated(b, c_loc(a))) &
1884 stop 'b and a do not point to same target'
1885 end subroutine association_test
1888 @item @emph{See also}:
1889 @ref{C_LOC}, @ref{C_FUNLOC}
1894 @section @code{C_FUNLOC} --- Obtain the C address of a procedure
1896 @cindex pointer, C address of procedures
1899 @item @emph{Description}:
1900 @code{C_FUNLOC(x)} determines the C address of the argument.
1902 @item @emph{Standard}:
1908 @item @emph{Syntax}:
1909 @code{RESULT = C_FUNLOC(x)}
1911 @item @emph{Arguments}:
1912 @multitable @columnfractions .15 .70
1913 @item @var{x} @tab Interoperable function or pointer to such function.
1916 @item @emph{Return value}:
1917 The return value is of type @code{C_FUNPTR} and contains the C address
1920 @item @emph{Example}:
1926 subroutine sub(a) bind(c)
1936 subroutine my_routine(p) bind(c,name='myC_func')
1938 type(c_funptr), intent(in) :: p
1941 call my_routine(c_funloc(sub))
1945 @item @emph{See also}:
1946 @ref{C_ASSOCIATED}, @ref{C_LOC}, @ref{C_F_POINTER}, @ref{C_F_PROCPOINTER}
1950 @node C_F_PROCPOINTER
1951 @section @code{C_F_PROCPOINTER} --- Convert C into Fortran procedure pointer
1952 @fnindex C_F_PROCPOINTER
1953 @cindex pointer, C address of pointers
1956 @item @emph{Description}:
1957 @code{C_F_PROCPOINTER(cptr, fptr)} Assign the target of the C function pointer
1958 @var{cptr} to the Fortran procedure pointer @var{fptr}.
1960 Note: Due to the currently lacking support of procedure pointers in GNU Fortran
1961 this function is not fully operable.
1963 @item @emph{Standard}:
1969 @item @emph{Syntax}:
1970 @code{CALL C_F_PROCPOINTER(cptr, fptr)}
1972 @item @emph{Arguments}:
1973 @multitable @columnfractions .15 .70
1974 @item @var{cptr} @tab scalar of the type @code{C_FUNPTR}. It is
1976 @item @var{fptr} @tab procedure pointer interoperable with @var{cptr}. It is
1980 @item @emph{Example}:
1988 real(c_float), intent(in) :: a
1989 real(c_float) :: func
1993 function getIterFunc() bind(c,name="getIterFunc")
1995 type(c_funptr) :: getIterFunc
1998 type(c_funptr) :: cfunptr
1999 procedure(func), pointer :: myFunc
2000 cfunptr = getIterFunc()
2001 call c_f_procpointer(cfunptr, myFunc)
2005 @item @emph{See also}:
2006 @ref{C_LOC}, @ref{C_F_POINTER}
2011 @section @code{C_F_POINTER} --- Convert C into Fortran pointer
2012 @fnindex C_F_POINTER
2013 @cindex pointer, convert C to Fortran
2016 @item @emph{Description}:
2017 @code{C_F_POINTER(cptr, fptr[, shape])} Assign the target the C pointer
2018 @var{cptr} to the Fortran pointer @var{fptr} and specify its
2021 @item @emph{Standard}:
2027 @item @emph{Syntax}:
2028 @code{CALL C_F_POINTER(cptr, fptr[, shape])}
2030 @item @emph{Arguments}:
2031 @multitable @columnfractions .15 .70
2032 @item @var{cptr} @tab scalar of the type @code{C_PTR}. It is
2034 @item @var{fptr} @tab pointer interoperable with @var{cptr}. It is
2036 @item @var{shape} @tab (Optional) Rank-one array of type @code{INTEGER}
2037 with @code{INTENT(IN)}. It shall be present
2038 if and only if @var{fptr} is an array. The size
2039 must be equal to the rank of @var{fptr}.
2042 @item @emph{Example}:
2048 subroutine my_routine(p) bind(c,name='myC_func')
2050 type(c_ptr), intent(out) :: p
2054 real,pointer :: a(:)
2055 call my_routine(cptr)
2056 call c_f_pointer(cptr, a, [12])
2060 @item @emph{See also}:
2061 @ref{C_LOC}, @ref{C_F_PROCPOINTER}
2066 @section @code{C_LOC} --- Obtain the C address of an object
2068 @cindex procedure pointer, convert C to Fortran
2071 @item @emph{Description}:
2072 @code{C_LOC(x)} determines the C address of the argument.
2074 @item @emph{Standard}:
2080 @item @emph{Syntax}:
2081 @code{RESULT = C_LOC(x)}
2083 @item @emph{Arguments}:
2084 @multitable @columnfractions .15 .70
2085 @item @var{x} @tab Associated scalar pointer or interoperable scalar
2086 or allocated allocatable variable with @code{TARGET}
2090 @item @emph{Return value}:
2091 The return value is of type @code{C_PTR} and contains the C address
2094 @item @emph{Example}:
2096 subroutine association_test(a,b)
2097 use iso_c_binding, only: c_associated, c_loc, c_ptr
2101 if(c_associated(b, c_loc(a))) &
2102 stop 'b and a do not point to same target'
2103 end subroutine association_test
2106 @item @emph{See also}:
2107 @ref{C_ASSOCIATED}, @ref{C_FUNLOC}, @ref{C_F_POINTER}, @ref{C_F_PROCPOINTER}
2112 @section @code{CEILING} --- Integer ceiling function
2115 @cindex rounding, ceiling
2118 @item @emph{Description}:
2119 @code{CEILING(X)} returns the least integer greater than or equal to @var{X}.
2121 @item @emph{Standard}:
2127 @item @emph{Syntax}:
2128 @code{RESULT = CEILING(X [, KIND])}
2130 @item @emph{Arguments}:
2131 @multitable @columnfractions .15 .70
2132 @item @var{X} @tab The type shall be @code{REAL(*)}.
2133 @item @var{KIND} @tab (Optional) An @code{INTEGER(*)} initialization
2134 expression indicating the kind parameter of
2138 @item @emph{Return value}:
2139 The return value is of type @code{INTEGER(KIND)}
2141 @item @emph{Example}:
2143 program test_ceiling
2146 print *, ceiling(x) ! returns 64
2147 print *, ceiling(y) ! returns -63
2148 end program test_ceiling
2151 @item @emph{See also}:
2152 @ref{FLOOR}, @ref{NINT}
2159 @section @code{CHAR} --- Character conversion function
2161 @cindex conversion, to character
2164 @item @emph{Description}:
2165 @code{CHAR(I [, KIND])} returns the character represented by the integer @var{I}.
2167 @item @emph{Standard}:
2173 @item @emph{Syntax}:
2174 @code{RESULT = CHAR(I [, KIND])}
2176 @item @emph{Arguments}:
2177 @multitable @columnfractions .15 .70
2178 @item @var{I} @tab The type shall be @code{INTEGER(*)}.
2179 @item @var{KIND} @tab (Optional) An @code{INTEGER(*)} initialization
2180 expression indicating the kind parameter of
2184 @item @emph{Return value}:
2185 The return value is of type @code{CHARACTER(1)}
2187 @item @emph{Example}:
2193 print *, i, c ! returns 'J'
2194 end program test_char
2198 See @ref{ICHAR} for a discussion of converting between numerical values
2199 and formatted string representations.
2201 @item @emph{See also}:
2202 @ref{ACHAR}, @ref{IACHAR}, @ref{ICHAR}
2209 @section @code{CHDIR} --- Change working directory
2211 @cindex system, working directory
2214 @item @emph{Description}:
2215 Change current working directory to a specified path.
2217 This intrinsic is provided in both subroutine and function forms; however,
2218 only one form can be used in any given program unit.
2220 @item @emph{Standard}:
2224 Subroutine, function
2226 @item @emph{Syntax}:
2227 @multitable @columnfractions .80
2228 @item @code{CALL CHDIR(NAME [, STATUS])}
2229 @item @code{STATUS = CHDIR(NAME)}
2232 @item @emph{Arguments}:
2233 @multitable @columnfractions .15 .70
2234 @item @var{NAME} @tab The type shall be @code{CHARACTER(*)} and shall
2235 specify a valid path within the file system.
2236 @item @var{STATUS} @tab (Optional) @code{INTEGER} status flag of the default
2237 kind. Returns 0 on success, and a system specific
2238 and nonzero error code otherwise.
2241 @item @emph{Example}:
2244 CHARACTER(len=255) :: path
2246 WRITE(*,*) TRIM(path)
2249 WRITE(*,*) TRIM(path)
2253 @item @emph{See also}:
2260 @section @code{CHMOD} --- Change access permissions of files
2262 @cindex file system, change access mode
2265 @item @emph{Description}:
2266 @code{CHMOD} changes the permissions of a file. This function invokes
2267 @code{/bin/chmod} and might therefore not work on all platforms.
2269 This intrinsic is provided in both subroutine and function forms; however,
2270 only one form can be used in any given program unit.
2272 @item @emph{Standard}:
2276 Subroutine, function
2278 @item @emph{Syntax}:
2279 @multitable @columnfractions .80
2280 @item @code{CALL CHMOD(NAME, MODE[, STATUS])}
2281 @item @code{STATUS = CHMOD(NAME, MODE)}
2284 @item @emph{Arguments}:
2285 @multitable @columnfractions .15 .70
2286 @item @var{NAME} @tab Scalar @code{CHARACTER} with the file name.
2287 Trailing blanks are ignored unless the character @code{achar(0)} is
2288 present, then all characters up to and excluding @code{achar(0)} are
2289 used as the file name.
2291 @item @var{MODE} @tab Scalar @code{CHARACTER} giving the file permission.
2292 @var{MODE} uses the same syntax as the @var{MODE} argument of
2295 @item @var{STATUS} @tab (optional) scalar @code{INTEGER}, which is
2296 @code{0} on success and nonzero otherwise.
2299 @item @emph{Return value}:
2300 In either syntax, @var{STATUS} is set to @code{0} on success and nonzero
2303 @item @emph{Example}:
2304 @code{CHMOD} as subroutine
2309 call chmod('test.dat','u+x',status)
2310 print *, 'Status: ', status
2311 end program chmod_test
2313 @code{CHMOD} as function:
2318 status = chmod('test.dat','u+x')
2319 print *, 'Status: ', status
2320 end program chmod_test
2328 @section @code{CMPLX} --- Complex conversion function
2330 @cindex complex numbers, conversion to
2331 @cindex conversion, to complex
2334 @item @emph{Description}:
2335 @code{CMPLX(X [, Y [, KIND]])} returns a complex number where @var{X} is converted to
2336 the real component. If @var{Y} is present it is converted to the imaginary
2337 component. If @var{Y} is not present then the imaginary component is set to
2338 0.0. If @var{X} is complex then @var{Y} must not be present.
2340 @item @emph{Standard}:
2346 @item @emph{Syntax}:
2347 @code{RESULT = CMPLX(X [, Y [, KIND]])}
2349 @item @emph{Arguments}:
2350 @multitable @columnfractions .15 .70
2351 @item @var{X} @tab The type may be @code{INTEGER(*)}, @code{REAL(*)},
2352 or @code{COMPLEX(*)}.
2353 @item @var{Y} @tab (Optional; only allowed if @var{X} is not
2354 @code{COMPLEX(*)}.) May be @code{INTEGER(*)}
2356 @item @var{KIND} @tab (Optional) An @code{INTEGER(*)} initialization
2357 expression indicating the kind parameter of
2361 @item @emph{Return value}:
2362 The return value is of @code{COMPLEX} type, with a kind equal to
2363 @var{KIND} if it is specified. If @var{KIND} is not specified, the
2364 result is of the default @code{COMPLEX} kind, regardless of the kinds of
2365 @var{X} and @var{Y}.
2367 @item @emph{Example}:
2374 print *, z, cmplx(x)
2375 end program test_cmplx
2378 @item @emph{See also}:
2384 @node COMMAND_ARGUMENT_COUNT
2385 @section @code{COMMAND_ARGUMENT_COUNT} --- Get number of command line arguments
2386 @fnindex COMMAND_ARGUMENT_COUNT
2387 @cindex command-line arguments
2388 @cindex command-line arguments, number of
2389 @cindex arguments, to program
2392 @item @emph{Description}:
2393 @code{COMMAND_ARGUMENT_COUNT()} returns the number of arguments passed on the
2394 command line when the containing program was invoked.
2396 @item @emph{Standard}:
2402 @item @emph{Syntax}:
2403 @code{RESULT = COMMAND_ARGUMENT_COUNT()}
2405 @item @emph{Arguments}:
2406 @multitable @columnfractions .15 .70
2410 @item @emph{Return value}:
2411 The return value is of type @code{INTEGER(4)}
2413 @item @emph{Example}:
2415 program test_command_argument_count
2417 count = command_argument_count()
2419 end program test_command_argument_count
2422 @item @emph{See also}:
2423 @ref{GET_COMMAND}, @ref{GET_COMMAND_ARGUMENT}
2429 @section @code{COMPLEX} --- Complex conversion function
2431 @cindex complex numbers, conversion to
2432 @cindex conversion, to complex
2435 @item @emph{Description}:
2436 @code{COMPLEX(X, Y)} returns a complex number where @var{X} is converted
2437 to the real component and @var{Y} is converted to the imaginary
2440 @item @emph{Standard}:
2446 @item @emph{Syntax}:
2447 @code{RESULT = COMPLEX(X, Y)}
2449 @item @emph{Arguments}:
2450 @multitable @columnfractions .15 .70
2451 @item @var{X} @tab The type may be @code{INTEGER(*)} or @code{REAL(*)}.
2452 @item @var{Y} @tab The type may be @code{INTEGER(*)} or @code{REAL(*)}.
2455 @item @emph{Return value}:
2456 If @var{X} and @var{Y} are both of @code{INTEGER} type, then the return
2457 value is of default @code{COMPLEX} type.
2459 If @var{X} and @var{Y} are of @code{REAL} type, or one is of @code{REAL}
2460 type and one is of @code{INTEGER} type, then the return value is of
2461 @code{COMPLEX} type with a kind equal to that of the @code{REAL}
2462 argument with the highest precision.
2464 @item @emph{Example}:
2466 program test_complex
2469 print *, complex(i, x)
2470 end program test_complex
2473 @item @emph{See also}:
2480 @section @code{CONJG} --- Complex conjugate function
2483 @cindex complex conjugate
2486 @item @emph{Description}:
2487 @code{CONJG(Z)} returns the conjugate of @var{Z}. If @var{Z} is @code{(x, y)}
2488 then the result is @code{(x, -y)}
2490 @item @emph{Standard}:
2491 F77 and later, has overloads that are GNU extensions
2496 @item @emph{Syntax}:
2499 @item @emph{Arguments}:
2500 @multitable @columnfractions .15 .70
2501 @item @var{Z} @tab The type shall be @code{COMPLEX(*)}.
2504 @item @emph{Return value}:
2505 The return value is of type @code{COMPLEX(*)}.
2507 @item @emph{Example}:
2510 complex :: z = (2.0, 3.0)
2511 complex(8) :: dz = (2.71_8, -3.14_8)
2516 end program test_conjg
2519 @item @emph{Specific names}:
2520 @multitable @columnfractions .20 .20 .20 .25
2521 @item Name @tab Argument @tab Return type @tab Standard
2522 @item @code{DCONJG(Z)} @tab @code{COMPLEX(8) Z} @tab @code{COMPLEX(8)} @tab GNU extension
2529 @section @code{COS} --- Cosine function
2535 @cindex trigonometric function, cosine
2539 @item @emph{Description}:
2540 @code{COS(X)} computes the cosine of @var{X}.
2542 @item @emph{Standard}:
2543 F77 and later, has overloads that are GNU extensions
2548 @item @emph{Syntax}:
2549 @code{RESULT = COS(X)}
2551 @item @emph{Arguments}:
2552 @multitable @columnfractions .15 .70
2553 @item @var{X} @tab The type shall be @code{REAL(*)} or
2557 @item @emph{Return value}:
2558 The return value is of type @code{REAL(*)} and it lies in the
2559 range @math{ -1 \leq \cos (x) \leq 1}. The kind type
2560 parameter is the same as @var{X}.
2562 @item @emph{Example}:
2567 end program test_cos
2570 @item @emph{Specific names}:
2571 @multitable @columnfractions .20 .20 .20 .25
2572 @item Name @tab Argument @tab Return type @tab Standard
2573 @item @code{DCOS(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab F77 and later
2574 @item @code{CCOS(X)} @tab @code{COMPLEX(4) X} @tab @code{COMPLEX(4)} @tab F77 and later
2575 @item @code{ZCOS(X)} @tab @code{COMPLEX(8) X} @tab @code{COMPLEX(8)} @tab GNU extension
2576 @item @code{CDCOS(X)} @tab @code{COMPLEX(8) X} @tab @code{COMPLEX(8)} @tab GNU extension
2579 @item @emph{See also}:
2580 Inverse function: @ref{ACOS}
2587 @section @code{COSH} --- Hyperbolic cosine function
2590 @cindex hyperbolic cosine
2591 @cindex hyperbolic function, cosine
2592 @cindex cosine, hyperbolic
2595 @item @emph{Description}:
2596 @code{COSH(X)} computes the hyperbolic cosine of @var{X}.
2598 @item @emph{Standard}:
2604 @item @emph{Syntax}:
2607 @item @emph{Arguments}:
2608 @multitable @columnfractions .15 .70
2609 @item @var{X} @tab The type shall be @code{REAL(*)}.
2612 @item @emph{Return value}:
2613 The return value is of type @code{REAL(*)} and it is positive
2614 (@math{ \cosh (x) \geq 0 }.
2616 @item @emph{Example}:
2619 real(8) :: x = 1.0_8
2621 end program test_cosh
2624 @item @emph{Specific names}:
2625 @multitable @columnfractions .20 .20 .20 .25
2626 @item Name @tab Argument @tab Return type @tab Standard
2627 @item @code{DCOSH(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab F77 and later
2630 @item @emph{See also}:
2631 Inverse function: @ref{ACOSH}
2638 @section @code{COUNT} --- Count function
2640 @cindex array, conditionally count elements
2641 @cindex array, element counting
2642 @cindex array, number of elements
2645 @item @emph{Description}:
2646 @code{COUNT(MASK [, DIM])} counts the number of @code{.TRUE.} elements of
2647 @var{MASK} along the dimension of @var{DIM}. If @var{DIM} is omitted it is
2648 taken to be @code{1}. @var{DIM} is a scaler of type @code{INTEGER} in the
2649 range of @math{1 /leq DIM /leq n)} where @math{n} is the rank of @var{MASK}.
2651 @item @emph{Standard}:
2655 Transformational function
2657 @item @emph{Syntax}:
2658 @code{RESULT = COUNT(MASK [, DIM])}
2660 @item @emph{Arguments}:
2661 @multitable @columnfractions .15 .70
2662 @item @var{MASK} @tab The type shall be @code{LOGICAL}.
2663 @item @var{DIM} @tab The type shall be @code{INTEGER}.
2666 @item @emph{Return value}:
2667 The return value is of type @code{INTEGER} with rank equal to that of
2670 @item @emph{Example}:
2673 integer, dimension(2,3) :: a, b
2674 logical, dimension(2,3) :: mask
2675 a = reshape( (/ 1, 2, 3, 4, 5, 6 /), (/ 2, 3 /))
2676 b = reshape( (/ 0, 7, 3, 4, 5, 8 /), (/ 2, 3 /))
2677 print '(3i3)', a(1,:)
2678 print '(3i3)', a(2,:)
2680 print '(3i3)', b(1,:)
2681 print '(3i3)', b(2,:)
2684 print '(3l3)', mask(1,:)
2685 print '(3l3)', mask(2,:)
2687 print '(3i3)', count(mask)
2689 print '(3i3)', count(mask, 1)
2691 print '(3i3)', count(mask, 2)
2692 end program test_count
2699 @section @code{CPU_TIME} --- CPU elapsed time in seconds
2701 @cindex time, elapsed
2704 @item @emph{Description}:
2705 Returns a @code{REAL(*)} value representing the elapsed CPU time in
2706 seconds. This is useful for testing segments of code to determine
2709 @item @emph{Standard}:
2715 @item @emph{Syntax}:
2716 @code{CALL CPU_TIME(TIME)}
2718 @item @emph{Arguments}:
2719 @multitable @columnfractions .15 .70
2720 @item @var{TIME} @tab The type shall be @code{REAL(*)} with @code{INTENT(OUT)}.
2723 @item @emph{Return value}:
2726 @item @emph{Example}:
2728 program test_cpu_time
2729 real :: start, finish
2730 call cpu_time(start)
2731 ! put code to test here
2732 call cpu_time(finish)
2733 print '("Time = ",f6.3," seconds.")',finish-start
2734 end program test_cpu_time
2737 @item @emph{See also}:
2738 @ref{SYSTEM_CLOCK}, @ref{DATE_AND_TIME}
2744 @section @code{CSHIFT} --- Circular shift elements of an array
2746 @cindex array, shift circularly
2747 @cindex array, permutation
2748 @cindex array, rotate
2751 @item @emph{Description}:
2752 @code{CSHIFT(ARRAY, SHIFT [, DIM])} performs a circular shift on elements of
2753 @var{ARRAY} along the dimension of @var{DIM}. If @var{DIM} is omitted it is
2754 taken to be @code{1}. @var{DIM} is a scaler of type @code{INTEGER} in the
2755 range of @math{1 /leq DIM /leq n)} where @math{n} is the rank of @var{ARRAY}.
2756 If the rank of @var{ARRAY} is one, then all elements of @var{ARRAY} are shifted
2757 by @var{SHIFT} places. If rank is greater than one, then all complete rank one
2758 sections of @var{ARRAY} along the given dimension are shifted. Elements
2759 shifted out one end of each rank one section are shifted back in the other end.
2761 @item @emph{Standard}:
2765 Transformational function
2767 @item @emph{Syntax}:
2768 @code{RESULT = CSHIFT(ARRAY, SHIFT [, DIM])}
2770 @item @emph{Arguments}:
2771 @multitable @columnfractions .15 .70
2772 @item @var{ARRAY} @tab Shall be an array of any type.
2773 @item @var{SHIFT} @tab The type shall be @code{INTEGER}.
2774 @item @var{DIM} @tab The type shall be @code{INTEGER}.
2777 @item @emph{Return value}:
2778 Returns an array of same type and rank as the @var{ARRAY} argument.
2780 @item @emph{Example}:
2783 integer, dimension(3,3) :: a
2784 a = reshape( (/ 1, 2, 3, 4, 5, 6, 7, 8, 9 /), (/ 3, 3 /))
2785 print '(3i3)', a(1,:)
2786 print '(3i3)', a(2,:)
2787 print '(3i3)', a(3,:)
2788 a = cshift(a, SHIFT=(/1, 2, -1/), DIM=2)
2790 print '(3i3)', a(1,:)
2791 print '(3i3)', a(2,:)
2792 print '(3i3)', a(3,:)
2793 end program test_cshift
2800 @section @code{CTIME} --- Convert a time into a string
2802 @cindex time, conversion to string
2803 @cindex conversion, to string
2806 @item @emph{Description}:
2807 @code{CTIME} converts a system time value, such as returned by
2808 @code{TIME8()}, to a string of the form @samp{Sat Aug 19 18:13:14 1995}.
2810 This intrinsic is provided in both subroutine and function forms; however,
2811 only one form can be used in any given program unit.
2813 @item @emph{Standard}:
2817 Subroutine, function
2819 @item @emph{Syntax}:
2820 @multitable @columnfractions .80
2821 @item @code{CALL CTIME(TIME, RESULT)}.
2822 @item @code{RESULT = CTIME(TIME)}, (not recommended).
2825 @item @emph{Arguments}:
2826 @multitable @columnfractions .15 .70
2827 @item @var{TIME} @tab The type shall be of type @code{INTEGER(KIND=8)}.
2828 @item @var{RESULT} @tab The type shall be of type @code{CHARACTER}.
2831 @item @emph{Return value}:
2832 The converted date and time as a string.
2834 @item @emph{Example}:
2838 character(len=30) :: date
2841 ! Do something, main part of the program
2844 print *, 'Program was started on ', date
2845 end program test_ctime
2848 @item @emph{See Also}:
2849 @ref{GMTIME}, @ref{LTIME}, @ref{TIME}, @ref{TIME8}
2855 @section @code{DATE_AND_TIME} --- Date and time subroutine
2856 @fnindex DATE_AND_TIME
2857 @cindex date, current
2858 @cindex current date
2859 @cindex time, current
2860 @cindex current time
2863 @item @emph{Description}:
2864 @code{DATE_AND_TIME(DATE, TIME, ZONE, VALUES)} gets the corresponding date and
2865 time information from the real-time system clock. @var{DATE} is
2866 @code{INTENT(OUT)} and has form ccyymmdd. @var{TIME} is @code{INTENT(OUT)} and
2867 has form hhmmss.sss. @var{ZONE} is @code{INTENT(OUT)} and has form (+-)hhmm,
2868 representing the difference with respect to Coordinated Universal Time (UTC).
2869 Unavailable time and date parameters return blanks.
2871 @var{VALUES} is @code{INTENT(OUT)} and provides the following:
2873 @multitable @columnfractions .15 .30 .40
2874 @item @tab @code{VALUE(1)}: @tab The year
2875 @item @tab @code{VALUE(2)}: @tab The month
2876 @item @tab @code{VALUE(3)}: @tab The day of the month
2877 @item @tab @code{VALUE(4)}: @tab Time difference with UTC in minutes
2878 @item @tab @code{VALUE(5)}: @tab The hour of the day
2879 @item @tab @code{VALUE(6)}: @tab The minutes of the hour
2880 @item @tab @code{VALUE(7)}: @tab The seconds of the minute
2881 @item @tab @code{VALUE(8)}: @tab The milliseconds of the second
2884 @item @emph{Standard}:
2890 @item @emph{Syntax}:
2891 @code{CALL DATE_AND_TIME([DATE, TIME, ZONE, VALUES])}
2893 @item @emph{Arguments}:
2894 @multitable @columnfractions .15 .70
2895 @item @var{DATE} @tab (Optional) The type shall be @code{CHARACTER(8)} or larger.
2896 @item @var{TIME} @tab (Optional) The type shall be @code{CHARACTER(10)} or larger.
2897 @item @var{ZONE} @tab (Optional) The type shall be @code{CHARACTER(5)} or larger.
2898 @item @var{VALUES}@tab (Optional) The type shall be @code{INTEGER(8)}.
2901 @item @emph{Return value}:
2904 @item @emph{Example}:
2906 program test_time_and_date
2907 character(8) :: date
2908 character(10) :: time
2909 character(5) :: zone
2910 integer,dimension(8) :: values
2911 ! using keyword arguments
2912 call date_and_time(date,time,zone,values)
2913 call date_and_time(DATE=date,ZONE=zone)
2914 call date_and_time(TIME=time)
2915 call date_and_time(VALUES=values)
2916 print '(a,2x,a,2x,a)', date, time, zone
2917 print '(8i5))', values
2918 end program test_time_and_date
2921 @item @emph{See also}:
2922 @ref{CPU_TIME}, @ref{SYSTEM_CLOCK}
2928 @section @code{DBLE} --- Double conversion function
2930 @cindex conversion, to real
2933 @item @emph{Description}:
2934 @code{DBLE(X)} Converts @var{X} to double precision real type.
2936 @item @emph{Standard}:
2942 @item @emph{Syntax}:
2943 @code{RESULT = DBLE(X)}
2945 @item @emph{Arguments}:
2946 @multitable @columnfractions .15 .70
2947 @item @var{X} @tab The type shall be @code{INTEGER(*)}, @code{REAL(*)},
2948 or @code{COMPLEX(*)}.
2951 @item @emph{Return value}:
2952 The return value is of type double precision real.
2954 @item @emph{Example}:
2959 complex :: z = (2.3,1.14)
2960 print *, dble(x), dble(i), dble(z)
2961 end program test_dble
2964 @item @emph{See also}:
2965 @ref{DFLOAT}, @ref{FLOAT}, @ref{REAL}
2971 @section @code{DCMPLX} --- Double complex conversion function
2973 @cindex complex numbers, conversion to
2974 @cindex conversion, to complex
2977 @item @emph{Description}:
2978 @code{DCMPLX(X [,Y])} returns a double complex number where @var{X} is
2979 converted to the real component. If @var{Y} is present it is converted to the
2980 imaginary component. If @var{Y} is not present then the imaginary component is
2981 set to 0.0. If @var{X} is complex then @var{Y} must not be present.
2983 @item @emph{Standard}:
2989 @item @emph{Syntax}:
2990 @code{RESULT = DCMPLX(X [, Y])}
2992 @item @emph{Arguments}:
2993 @multitable @columnfractions .15 .70
2994 @item @var{X} @tab The type may be @code{INTEGER(*)}, @code{REAL(*)},
2995 or @code{COMPLEX(*)}.
2996 @item @var{Y} @tab (Optional if @var{X} is not @code{COMPLEX(*)}.) May be
2997 @code{INTEGER(*)} or @code{REAL(*)}.
3000 @item @emph{Return value}:
3001 The return value is of type @code{COMPLEX(8)}
3003 @item @emph{Example}:
3013 print *, dcmplx(x,i)
3014 end program test_dcmplx
3021 @section @code{DFLOAT} --- Double conversion function
3023 @cindex conversion, to real
3026 @item @emph{Description}:
3027 @code{DFLOAT(X)} Converts @var{X} to double precision real type.
3029 @item @emph{Standard}:
3035 @item @emph{Syntax}:
3036 @code{RESULT = DFLOAT(X)}
3038 @item @emph{Arguments}:
3039 @multitable @columnfractions .15 .70
3040 @item @var{X} @tab The type shall be @code{INTEGER(*)}.
3043 @item @emph{Return value}:
3044 The return value is of type double precision real.
3046 @item @emph{Example}:
3051 end program test_dfloat
3054 @item @emph{See also}:
3055 @ref{DBLE}, @ref{FLOAT}, @ref{REAL}
3061 @section @code{DIGITS} --- Significant digits function
3063 @cindex model representation, significant digits
3066 @item @emph{Description}:
3067 @code{DIGITS(X)} returns the number of significant digits of the internal model
3068 representation of @var{X}. For example, on a system using a 32-bit
3069 floating point representation, a default real number would likely return 24.
3071 @item @emph{Standard}:
3077 @item @emph{Syntax}:
3078 @code{RESULT = DIGITS(X)}
3080 @item @emph{Arguments}:
3081 @multitable @columnfractions .15 .70
3082 @item @var{X} @tab The type may be @code{INTEGER(*)} or @code{REAL(*)}.
3085 @item @emph{Return value}:
3086 The return value is of type @code{INTEGER}.
3088 @item @emph{Example}:
3091 integer :: i = 12345
3097 end program test_digits
3104 @section @code{DIM} --- Positive difference
3108 @cindex positive difference
3111 @item @emph{Description}:
3112 @code{DIM(X,Y)} returns the difference @code{X-Y} if the result is positive;
3113 otherwise returns zero.
3115 @item @emph{Standard}:
3121 @item @emph{Syntax}:
3122 @code{RESULT = DIM(X, Y)}
3124 @item @emph{Arguments}:
3125 @multitable @columnfractions .15 .70
3126 @item @var{X} @tab The type shall be @code{INTEGER(*)} or @code{REAL(*)}
3127 @item @var{Y} @tab The type shall be the same type and kind as @var{X}.
3130 @item @emph{Return value}:
3131 The return value is of type @code{INTEGER(*)} or @code{REAL(*)}.
3133 @item @emph{Example}:
3139 x = dim(4.345_8, 2.111_8)
3142 end program test_dim
3145 @item @emph{Specific names}:
3146 @multitable @columnfractions .20 .20 .20 .25
3147 @item Name @tab Argument @tab Return type @tab Standard
3148 @item @code{IDIM(X,Y)} @tab @code{INTEGER(4) X,Y} @tab @code{INTEGER(4)} @tab F77 and later
3149 @item @code{DDIM(X,Y)} @tab @code{REAL(8) X,Y} @tab @code{REAL(8)} @tab F77 and later
3156 @section @code{DOT_PRODUCT} --- Dot product function
3157 @fnindex DOT_PRODUCT
3159 @cindex vector product
3160 @cindex product, vector
3163 @item @emph{Description}:
3164 @code{DOT_PRODUCT(X,Y)} computes the dot product multiplication of two vectors
3165 @var{X} and @var{Y}. The two vectors may be either numeric or logical
3166 and must be arrays of rank one and of equal size. If the vectors are
3167 @code{INTEGER(*)} or @code{REAL(*)}, the result is @code{SUM(X*Y)}. If the
3168 vectors are @code{COMPLEX(*)}, the result is @code{SUM(CONJG(X)*Y)}. If the
3169 vectors are @code{LOGICAL}, the result is @code{ANY(X.AND.Y)}.
3171 @item @emph{Standard}:
3175 Transformational function
3177 @item @emph{Syntax}:
3178 @code{RESULT = DOT_PRODUCT(X, Y)}
3180 @item @emph{Arguments}:
3181 @multitable @columnfractions .15 .70
3182 @item @var{X} @tab The type shall be numeric or @code{LOGICAL}, rank 1.
3183 @item @var{Y} @tab The type shall be numeric or @code{LOGICAL}, rank 1.
3186 @item @emph{Return value}:
3187 If the arguments are numeric, the return value is a scaler of numeric type,
3188 @code{INTEGER(*)}, @code{REAL(*)}, or @code{COMPLEX(*)}. If the arguments are
3189 @code{LOGICAL}, the return value is @code{.TRUE.} or @code{.FALSE.}.
3191 @item @emph{Example}:
3193 program test_dot_prod
3194 integer, dimension(3) :: a, b
3201 print *, dot_product(a,b)
3202 end program test_dot_prod
3209 @section @code{DPROD} --- Double product function
3211 @cindex product, double-precision
3214 @item @emph{Description}:
3215 @code{DPROD(X,Y)} returns the product @code{X*Y}.
3217 @item @emph{Standard}:
3223 @item @emph{Syntax}:
3224 @code{RESULT = DPROD(X, Y)}
3226 @item @emph{Arguments}:
3227 @multitable @columnfractions .15 .70
3228 @item @var{X} @tab The type shall be @code{REAL}.
3229 @item @var{Y} @tab The type shall be @code{REAL}.
3232 @item @emph{Return value}:
3233 The return value is of type @code{REAL(8)}.
3235 @item @emph{Example}:
3243 end program test_dprod
3250 @section @code{DREAL} --- Double real part function
3252 @cindex complex numbers, real part
3255 @item @emph{Description}:
3256 @code{DREAL(Z)} returns the real part of complex variable @var{Z}.
3258 @item @emph{Standard}:
3264 @item @emph{Syntax}:
3265 @code{RESULT = DREAL(Z)}
3267 @item @emph{Arguments}:
3268 @multitable @columnfractions .15 .70
3269 @item @var{Z} @tab The type shall be @code{COMPLEX(8)}.
3272 @item @emph{Return value}:
3273 The return value is of type @code{REAL(8)}.
3275 @item @emph{Example}:
3278 complex(8) :: z = (1.3_8,7.2_8)
3280 end program test_dreal
3283 @item @emph{See also}:
3291 @section @code{DTIME} --- Execution time subroutine (or function)
3293 @cindex time, elapsed
3294 @cindex elapsed time
3297 @item @emph{Description}:
3298 @code{DTIME(TARRAY, RESULT)} initially returns the number of seconds of runtime
3299 since the start of the process's execution in @var{RESULT}. @var{TARRAY}
3300 returns the user and system components of this time in @code{TARRAY(1)} and
3301 @code{TARRAY(2)} respectively. @var{RESULT} is equal to @code{TARRAY(1) +
3304 Subsequent invocations of @code{DTIME} return values accumulated since the
3305 previous invocation.
3307 On some systems, the underlying timings are represented using types with
3308 sufficiently small limits that overflows (wrap around) are possible, such as
3309 32-bit types. Therefore, the values returned by this intrinsic might be, or
3310 become, negative, or numerically less than previous values, during a single
3311 run of the compiled program.
3313 This intrinsic is provided in both subroutine and function forms; however,
3314 only one form can be used in any given program unit.
3316 @var{TARRAY} and @var{RESULT} are @code{INTENT(OUT)} and provide the following:
3318 @multitable @columnfractions .15 .30 .40
3319 @item @tab @code{TARRAY(1)}: @tab User time in seconds.
3320 @item @tab @code{TARRAY(2)}: @tab System time in seconds.
3321 @item @tab @code{RESULT}: @tab Run time since start in seconds.
3324 @item @emph{Standard}:
3328 Subroutine, function
3330 @item @emph{Syntax}:
3331 @multitable @columnfractions .80
3332 @item @code{CALL DTIME(TARRAY, RESULT)}.
3333 @item @code{RESULT = DTIME(TARRAY)}, (not recommended).
3336 @item @emph{Arguments}:
3337 @multitable @columnfractions .15 .70
3338 @item @var{TARRAY}@tab The type shall be @code{REAL, DIMENSION(2)}.
3339 @item @var{RESULT}@tab The type shall be @code{REAL}.
3342 @item @emph{Return value}:
3343 Elapsed time in seconds since the start of program execution.
3345 @item @emph{Example}:
3349 real, dimension(2) :: tarray
3351 call dtime(tarray, result)
3355 do i=1,100000000 ! Just a delay
3358 call dtime(tarray, result)
3362 end program test_dtime
3369 @section @code{EOSHIFT} --- End-off shift elements of an array
3371 @cindex array, shift
3374 @item @emph{Description}:
3375 @code{EOSHIFT(ARRAY, SHIFT[,BOUNDARY, DIM])} performs an end-off shift on
3376 elements of @var{ARRAY} along the dimension of @var{DIM}. If @var{DIM} is
3377 omitted it is taken to be @code{1}. @var{DIM} is a scaler of type
3378 @code{INTEGER} in the range of @math{1 /leq DIM /leq n)} where @math{n} is the
3379 rank of @var{ARRAY}. If the rank of @var{ARRAY} is one, then all elements of
3380 @var{ARRAY} are shifted by @var{SHIFT} places. If rank is greater than one,
3381 then all complete rank one sections of @var{ARRAY} along the given dimension are
3382 shifted. Elements shifted out one end of each rank one section are dropped. If
3383 @var{BOUNDARY} is present then the corresponding value of from @var{BOUNDARY}
3384 is copied back in the other end. If @var{BOUNDARY} is not present then the
3385 following are copied in depending on the type of @var{ARRAY}.
3387 @multitable @columnfractions .15 .80
3388 @item @emph{Array Type} @tab @emph{Boundary Value}
3389 @item Numeric @tab 0 of the type and kind of @var{ARRAY}.
3390 @item Logical @tab @code{.FALSE.}.
3391 @item Character(@var{len}) @tab @var{len} blanks.
3394 @item @emph{Standard}:
3398 Transformational function
3400 @item @emph{Syntax}:
3401 @code{RESULT = EOSHIFT(ARRAY, SHIFT [, BOUNDARY, DIM])}
3403 @item @emph{Arguments}:
3404 @multitable @columnfractions .15 .70
3405 @item @var{ARRAY} @tab May be any type, not scaler.
3406 @item @var{SHIFT} @tab The type shall be @code{INTEGER}.
3407 @item @var{BOUNDARY} @tab Same type as @var{ARRAY}.
3408 @item @var{DIM} @tab The type shall be @code{INTEGER}.
3411 @item @emph{Return value}:
3412 Returns an array of same type and rank as the @var{ARRAY} argument.
3414 @item @emph{Example}:
3416 program test_eoshift
3417 integer, dimension(3,3) :: a
3418 a = reshape( (/ 1, 2, 3, 4, 5, 6, 7, 8, 9 /), (/ 3, 3 /))
3419 print '(3i3)', a(1,:)
3420 print '(3i3)', a(2,:)
3421 print '(3i3)', a(3,:)
3422 a = EOSHIFT(a, SHIFT=(/1, 2, 1/), BOUNDARY=-5, DIM=2)
3424 print '(3i3)', a(1,:)
3425 print '(3i3)', a(2,:)
3426 print '(3i3)', a(3,:)
3427 end program test_eoshift
3434 @section @code{EPSILON} --- Epsilon function
3436 @cindex model representation, epsilon
3439 @item @emph{Description}:
3440 @code{EPSILON(X)} returns a nearly negligible number relative to @code{1}.
3442 @item @emph{Standard}:
3448 @item @emph{Syntax}:
3449 @code{RESULT = EPSILON(X)}
3451 @item @emph{Arguments}:
3452 @multitable @columnfractions .15 .70
3453 @item @var{X} @tab The type shall be @code{REAL(*)}.
3456 @item @emph{Return value}:
3457 The return value is of same type as the argument.
3459 @item @emph{Example}:
3461 program test_epsilon
3466 end program test_epsilon
3473 @section @code{ERF} --- Error function
3475 @cindex error function
3478 @item @emph{Description}:
3479 @code{ERF(X)} computes the error function of @var{X}.
3481 @item @emph{Standard}:
3487 @item @emph{Syntax}:
3488 @code{RESULT = ERF(X)}
3490 @item @emph{Arguments}:
3491 @multitable @columnfractions .15 .70
3492 @item @var{X} @tab The type shall be @code{REAL(*)}, and it shall be scalar.
3495 @item @emph{Return value}:
3496 The return value is a scalar of type @code{REAL(*)} and it is positive
3497 (@math{ - 1 \leq erf (x) \leq 1 }.
3499 @item @emph{Example}:
3502 real(8) :: x = 0.17_8
3504 end program test_erf
3507 @item @emph{Specific names}:
3508 @multitable @columnfractions .20 .20 .20 .25
3509 @item Name @tab Argument @tab Return type @tab Standard
3510 @item @code{DERF(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU extension
3517 @section @code{ERFC} --- Error function
3519 @cindex error function, complementary
3522 @item @emph{Description}:
3523 @code{ERFC(X)} computes the complementary error function of @var{X}.
3525 @item @emph{Standard}:
3531 @item @emph{Syntax}:
3532 @code{RESULT = ERFC(X)}
3534 @item @emph{Arguments}:
3535 @multitable @columnfractions .15 .70
3536 @item @var{X} @tab The type shall be @code{REAL(*)}, and it shall be scalar.
3539 @item @emph{Return value}:
3540 The return value is a scalar of type @code{REAL(*)} and it is positive
3541 (@math{ 0 \leq erfc (x) \leq 2 }.
3543 @item @emph{Example}:
3546 real(8) :: x = 0.17_8
3548 end program test_erfc
3551 @item @emph{Specific names}:
3552 @multitable @columnfractions .20 .20 .20 .25
3553 @item Name @tab Argument @tab Return type @tab Standard
3554 @item @code{DERFC(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU extension
3561 @section @code{ETIME} --- Execution time subroutine (or function)
3563 @cindex time, elapsed
3566 @item @emph{Description}:
3567 @code{ETIME(TARRAY, RESULT)} returns the number of seconds of runtime
3568 since the start of the process's execution in @var{RESULT}. @var{TARRAY}
3569 returns the user and system components of this time in @code{TARRAY(1)} and
3570 @code{TARRAY(2)} respectively. @var{RESULT} is equal to @code{TARRAY(1) + TARRAY(2)}.
3572 On some systems, the underlying timings are represented using types with
3573 sufficiently small limits that overflows (wrap around) are possible, such as
3574 32-bit types. Therefore, the values returned by this intrinsic might be, or
3575 become, negative, or numerically less than previous values, during a single
3576 run of the compiled program.
3578 This intrinsic is provided in both subroutine and function forms; however,
3579 only one form can be used in any given program unit.
3581 @var{TARRAY} and @var{RESULT} are @code{INTENT(OUT)} and provide the following:
3583 @multitable @columnfractions .15 .30 .60
3584 @item @tab @code{TARRAY(1)}: @tab User time in seconds.
3585 @item @tab @code{TARRAY(2)}: @tab System time in seconds.
3586 @item @tab @code{RESULT}: @tab Run time since start in seconds.
3589 @item @emph{Standard}:
3593 Subroutine, function
3595 @item @emph{Syntax}:
3596 @multitable @columnfractions .80
3597 @item @code{CALL ETIME(TARRAY, RESULT)}.
3598 @item @code{RESULT = ETIME(TARRAY)}, (not recommended).
3601 @item @emph{Arguments}:
3602 @multitable @columnfractions .15 .70
3603 @item @var{TARRAY}@tab The type shall be @code{REAL, DIMENSION(2)}.
3604 @item @var{RESULT}@tab The type shall be @code{REAL}.
3607 @item @emph{Return value}:
3608 Elapsed time in seconds since the start of program execution.
3610 @item @emph{Example}:
3614 real, dimension(2) :: tarray
3616 call ETIME(tarray, result)
3620 do i=1,100000000 ! Just a delay
3623 call ETIME(tarray, result)
3627 end program test_etime
3630 @item @emph{See also}:
3638 @section @code{EXIT} --- Exit the program with status.
3640 @cindex program termination
3641 @cindex terminate program
3644 @item @emph{Description}:
3645 @code{EXIT} causes immediate termination of the program with status. If status
3646 is omitted it returns the canonical @emph{success} for the system. All Fortran
3647 I/O units are closed.
3649 @item @emph{Standard}:
3655 @item @emph{Syntax}:
3656 @code{CALL EXIT([STATUS])}
3658 @item @emph{Arguments}:
3659 @multitable @columnfractions .15 .70
3660 @item @var{STATUS} @tab Shall be an @code{INTEGER} of the default kind.
3663 @item @emph{Return value}:
3664 @code{STATUS} is passed to the parent process on exit.
3666 @item @emph{Example}:
3669 integer :: STATUS = 0
3670 print *, 'This program is going to exit.'
3672 end program test_exit
3675 @item @emph{See also}:
3676 @ref{ABORT}, @ref{KILL}
3682 @section @code{EXP} --- Exponential function
3688 @cindex exponential function
3689 @cindex logarithmic function, inverse
3692 @item @emph{Description}:
3693 @code{EXP(X)} computes the base @math{e} exponential of @var{X}.
3695 @item @emph{Standard}:
3696 F77 and later, has overloads that are GNU extensions
3701 @item @emph{Syntax}:
3702 @code{RESULT = EXP(X)}
3704 @item @emph{Arguments}:
3705 @multitable @columnfractions .15 .70
3706 @item @var{X} @tab The type shall be @code{REAL(*)} or
3710 @item @emph{Return value}:
3711 The return value has same type and kind as @var{X}.
3713 @item @emph{Example}:
3718 end program test_exp
3721 @item @emph{Specific names}:
3722 @multitable @columnfractions .20 .20 .20 .25
3723 @item Name @tab Argument @tab Return type @tab Standard
3724 @item @code{DEXP(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab F77 and later
3725 @item @code{CEXP(X)} @tab @code{COMPLEX(4) X} @tab @code{COMPLEX(4)} @tab F77 and later
3726 @item @code{ZEXP(X)} @tab @code{COMPLEX(8) X} @tab @code{COMPLEX(8)} @tab GNU extension
3727 @item @code{CDEXP(X)} @tab @code{COMPLEX(8) X} @tab @code{COMPLEX(8)} @tab GNU extension
3734 @section @code{EXPONENT} --- Exponent function
3736 @cindex real number, exponent
3737 @cindex floating point, exponent
3740 @item @emph{Description}:
3741 @code{EXPONENT(X)} returns the value of the exponent part of @var{X}. If @var{X}
3742 is zero the value returned is zero.
3744 @item @emph{Standard}:
3750 @item @emph{Syntax}:
3751 @code{RESULT = EXPONENT(X)}
3753 @item @emph{Arguments}:
3754 @multitable @columnfractions .15 .70
3755 @item @var{X} @tab The type shall be @code{REAL(*)}.
3758 @item @emph{Return value}:
3759 The return value is of type default @code{INTEGER}.
3761 @item @emph{Example}:
3763 program test_exponent
3768 print *, exponent(0.0)
3769 end program test_exponent
3776 @section @code{FDATE} --- Get the current time as a string
3778 @cindex time, current
3779 @cindex current time
3780 @cindex date, current
3781 @cindex current date
3784 @item @emph{Description}:
3785 @code{FDATE(DATE)} returns the current date (using the same format as
3786 @code{CTIME}) in @var{DATE}. It is equivalent to @code{CALL CTIME(DATE,
3789 This intrinsic is provided in both subroutine and function forms; however,
3790 only one form can be used in any given program unit.
3792 @var{DATE} is an @code{INTENT(OUT)} @code{CHARACTER} variable.
3794 @item @emph{Standard}:
3798 Subroutine, function
3800 @item @emph{Syntax}:
3801 @multitable @columnfractions .80
3802 @item @code{CALL FDATE(DATE)}.
3803 @item @code{DATE = FDATE()}, (not recommended).
3806 @item @emph{Arguments}:
3807 @multitable @columnfractions .15 .70
3808 @item @var{DATE}@tab The type shall be of type @code{CHARACTER}.
3811 @item @emph{Return value}:
3812 The current date as a string.
3814 @item @emph{Example}:
3818 character(len=30) :: date
3820 print *, 'Program started on ', date
3821 do i = 1, 100000000 ! Just a delay
3825 print *, 'Program ended on ', date
3826 end program test_fdate
3833 @section @code{FLOAT} --- Convert integer to default real
3835 @cindex conversion, to real
3838 @item @emph{Description}:
3839 @code{FLOAT(I)} converts the integer @var{I} to a default real value.
3841 @item @emph{Standard}:
3847 @item @emph{Syntax}:
3848 @code{RESULT = FLOAT(I)}
3850 @item @emph{Arguments}:
3851 @multitable @columnfractions .15 .70
3852 @item @var{I} @tab The type shall be @code{INTEGER(*)}.
3855 @item @emph{Return value}:
3856 The return value is of type default @code{REAL}.
3858 @item @emph{Example}:
3862 if (float(i) /= 1.) call abort
3863 end program test_float
3866 @item @emph{See also}:
3867 @ref{DBLE}, @ref{DFLOAT}, @ref{REAL}
3873 @section @code{FGET} --- Read a single character in stream mode from stdin
3875 @cindex read character, stream mode
3876 @cindex stream mode, read character
3877 @cindex file operation, read character
3880 @item @emph{Description}:
3881 Read a single character in stream mode from stdin by bypassing normal
3882 formatted output. Stream I/O should not be mixed with normal record-oriented
3883 (formatted or unformatted) I/O on the same unit; the results are unpredictable.
3885 This intrinsic is provided in both subroutine and function forms; however,
3886 only one form can be used in any given program unit.
3888 Note that the @code{FGET} intrinsic is provided for backwards compatibility with
3889 @command{g77}. GNU Fortran provides the Fortran 2003 Stream facility.
3890 Programmers should consider the use of new stream IO feature in new code
3891 for future portability. See also @ref{Fortran 2003 status}.
3893 @item @emph{Standard}:
3897 Subroutine, function
3899 @item @emph{Syntax}:
3900 @code{CALL FGET(C [, STATUS])}
3902 @item @emph{Arguments}:
3903 @multitable @columnfractions .15 .70
3904 @item @var{C} @tab The type shall be @code{CHARACTER}.
3905 @item @var{STATUS} @tab (Optional) status flag of type @code{INTEGER}.
3906 Returns 0 on success, -1 on end-of-file, and a
3907 system specific positive error code otherwise.
3910 @item @emph{Example}:
3913 INTEGER, PARAMETER :: strlen = 100
3914 INTEGER :: status, i = 1
3915 CHARACTER(len=strlen) :: str = ""
3917 WRITE (*,*) 'Enter text:'
3919 CALL fget(str(i:i), status)
3920 if (status /= 0 .OR. i > strlen) exit
3923 WRITE (*,*) TRIM(str)
3927 @item @emph{See also}:
3928 @ref{FGETC}, @ref{FPUT}, @ref{FPUTC}
3934 @section @code{FGETC} --- Read a single character in stream mode
3936 @cindex read character, stream mode
3937 @cindex stream mode, read character
3938 @cindex file operation, read character
3941 @item @emph{Description}:
3942 Read a single character in stream mode by bypassing normal formatted output.
3943 Stream I/O should not be mixed with normal record-oriented (formatted or
3944 unformatted) I/O on the same unit; the results are unpredictable.
3946 This intrinsic is provided in both subroutine and function forms; however,
3947 only one form can be used in any given program unit.
3949 Note that the @code{FGET} intrinsic is provided for backwards compatibility
3950 with @command{g77}. GNU Fortran provides the Fortran 2003 Stream facility.
3951 Programmers should consider the use of new stream IO feature in new code
3952 for future portability. See also @ref{Fortran 2003 status}.
3954 @item @emph{Standard}:
3958 Subroutine, function
3960 @item @emph{Syntax}:
3961 @code{CALL FGETC(UNIT, C [, STATUS])}
3963 @item @emph{Arguments}:
3964 @multitable @columnfractions .15 .70
3965 @item @var{UNIT} @tab The type shall be @code{INTEGER}.
3966 @item @var{C} @tab The type shall be @code{CHARACTER}.
3967 @item @var{STATUS} @tab (Optional) status flag of type @code{INTEGER}. Returns 0 on success,
3968 -1 on end-of-file and a system specific positive error code otherwise.
3971 @item @emph{Example}:
3974 INTEGER :: fd = 42, status
3977 OPEN(UNIT=fd, FILE="/etc/passwd", ACTION="READ", STATUS = "OLD")
3979 CALL fgetc(fd, c, status)
3980 IF (status /= 0) EXIT
3987 @item @emph{See also}:
3988 @ref{FGET}, @ref{FPUT}, @ref{FPUTC}
3994 @section @code{FLOOR} --- Integer floor function
3997 @cindex rounding, floor
4000 @item @emph{Description}:
4001 @code{FLOOR(X)} returns the greatest integer less than or equal to @var{X}.
4003 @item @emph{Standard}:
4009 @item @emph{Syntax}:
4010 @code{RESULT = FLOOR(X [, KIND])}
4012 @item @emph{Arguments}:
4013 @multitable @columnfractions .15 .70
4014 @item @var{X} @tab The type shall be @code{REAL(*)}.
4015 @item @var{KIND} @tab (Optional) An @code{INTEGER(*)} initialization
4016 expression indicating the kind parameter of
4020 @item @emph{Return value}:
4021 The return value is of type @code{INTEGER(KIND)}
4023 @item @emph{Example}:
4028 print *, floor(x) ! returns 63
4029 print *, floor(y) ! returns -64
4030 end program test_floor
4033 @item @emph{See also}:
4034 @ref{CEILING}, @ref{NINT}
4041 @section @code{FLUSH} --- Flush I/O unit(s)
4043 @cindex file operation, flush
4046 @item @emph{Description}:
4047 Flushes Fortran unit(s) currently open for output. Without the optional
4048 argument, all units are flushed, otherwise just the unit specified.
4050 @item @emph{Standard}:
4056 @item @emph{Syntax}:
4057 @code{CALL FLUSH(UNIT)}
4059 @item @emph{Arguments}:
4060 @multitable @columnfractions .15 .70
4061 @item @var{UNIT} @tab (Optional) The type shall be @code{INTEGER}.
4065 Beginning with the Fortran 2003 standard, there is a @code{FLUSH}
4066 statement that should be preferred over the @code{FLUSH} intrinsic.
4073 @section @code{FNUM} --- File number function
4075 @cindex file operation, file number
4078 @item @emph{Description}:
4079 @code{FNUM(UNIT)} returns the POSIX file descriptor number corresponding to the
4080 open Fortran I/O unit @code{UNIT}.
4082 @item @emph{Standard}:
4088 @item @emph{Syntax}:
4089 @code{RESULT = FNUM(UNIT)}
4091 @item @emph{Arguments}:
4092 @multitable @columnfractions .15 .70
4093 @item @var{UNIT} @tab The type shall be @code{INTEGER}.
4096 @item @emph{Return value}:
4097 The return value is of type @code{INTEGER}
4099 @item @emph{Example}:
4103 open (unit=10, status = "scratch")
4107 end program test_fnum
4114 @section @code{FPUT} --- Write a single character in stream mode to stdout
4116 @cindex write character, stream mode
4117 @cindex stream mode, write character
4118 @cindex file operation, write character
4121 @item @emph{Description}:
4122 Write a single character in stream mode to stdout by bypassing normal
4123 formatted output. Stream I/O should not be mixed with normal record-oriented
4124 (formatted or unformatted) I/O on the same unit; the results are unpredictable.
4126 This intrinsic is provided in both subroutine and function forms; however,
4127 only one form can be used in any given program unit.
4129 Note that the @code{FGET} intrinsic is provided for backwards compatibility with
4130 @command{g77}. GNU Fortran provides the Fortran 2003 Stream facility.
4131 Programmers should consider the use of new stream IO feature in new code
4132 for future portability. See also @ref{Fortran 2003 status}.
4134 @item @emph{Standard}:
4138 Subroutine, function
4140 @item @emph{Syntax}:
4141 @code{CALL FPUT(C [, STATUS])}
4143 @item @emph{Arguments}:
4144 @multitable @columnfractions .15 .70
4145 @item @var{C} @tab The type shall be @code{CHARACTER}.
4146 @item @var{STATUS} @tab (Optional) status flag of type @code{INTEGER}. Returns 0 on success,
4147 -1 on end-of-file and a system specific positive error code otherwise.
4150 @item @emph{Example}:
4153 CHARACTER(len=10) :: str = "gfortran"
4155 DO i = 1, len_trim(str)
4161 @item @emph{See also}:
4162 @ref{FPUTC}, @ref{FGET}, @ref{FGETC}
4168 @section @code{FPUTC} --- Write a single character in stream mode
4170 @cindex write character, stream mode
4171 @cindex stream mode, write character
4172 @cindex file operation, write character
4175 @item @emph{Description}:
4176 Write a single character in stream mode by bypassing normal formatted
4177 output. Stream I/O should not be mixed with normal record-oriented
4178 (formatted or unformatted) I/O on the same unit; the results are unpredictable.
4180 This intrinsic is provided in both subroutine and function forms; however,
4181 only one form can be used in any given program unit.
4183 Note that the @code{FGET} intrinsic is provided for backwards compatibility with
4184 @command{g77}. GNU Fortran provides the Fortran 2003 Stream facility.
4185 Programmers should consider the use of new stream IO feature in new code
4186 for future portability. See also @ref{Fortran 2003 status}.
4188 @item @emph{Standard}:
4192 Subroutine, function
4194 @item @emph{Syntax}:
4195 @code{CALL FPUTC(UNIT, C [, STATUS])}
4197 @item @emph{Arguments}:
4198 @multitable @columnfractions .15 .70
4199 @item @var{UNIT} @tab The type shall be @code{INTEGER}.
4200 @item @var{C} @tab The type shall be @code{CHARACTER}.
4201 @item @var{STATUS} @tab (Optional) status flag of type @code{INTEGER}. Returns 0 on success,
4202 -1 on end-of-file and a system specific positive error code otherwise.
4205 @item @emph{Example}:
4208 CHARACTER(len=10) :: str = "gfortran"
4209 INTEGER :: fd = 42, i
4211 OPEN(UNIT = fd, FILE = "out", ACTION = "WRITE", STATUS="NEW")
4212 DO i = 1, len_trim(str)
4213 CALL fputc(fd, str(i:i))
4219 @item @emph{See also}:
4220 @ref{FPUT}, @ref{FGET}, @ref{FGETC}
4226 @section @code{FRACTION} --- Fractional part of the model representation
4228 @cindex real number, fraction
4229 @cindex floating point, fraction
4232 @item @emph{Description}:
4233 @code{FRACTION(X)} returns the fractional part of the model
4234 representation of @code{X}.
4236 @item @emph{Standard}:
4242 @item @emph{Syntax}:
4243 @code{Y = FRACTION(X)}
4245 @item @emph{Arguments}:
4246 @multitable @columnfractions .15 .70
4247 @item @var{X} @tab The type of the argument shall be a @code{REAL}.
4250 @item @emph{Return value}:
4251 The return value is of the same type and kind as the argument.
4252 The fractional part of the model representation of @code{X} is returned;
4253 it is @code{X * RADIX(X)**(-EXPONENT(X))}.
4255 @item @emph{Example}:
4257 program test_fraction
4260 print *, fraction(x), x * radix(x)**(-exponent(x))
4261 end program test_fraction
4269 @section @code{FREE} --- Frees memory
4271 @cindex pointer, cray
4274 @item @emph{Description}:
4275 Frees memory previously allocated by @code{MALLOC()}. The @code{FREE}
4276 intrinsic is an extension intended to be used with Cray pointers, and is
4277 provided in GNU Fortran to allow user to compile legacy code. For
4278 new code using Fortran 95 pointers, the memory de-allocation intrinsic is
4281 @item @emph{Standard}:
4287 @item @emph{Syntax}:
4288 @code{CALL FREE(PTR)}
4290 @item @emph{Arguments}:
4291 @multitable @columnfractions .15 .70
4292 @item @var{PTR} @tab The type shall be @code{INTEGER}. It represents the
4293 location of the memory that should be de-allocated.
4296 @item @emph{Return value}:
4299 @item @emph{Example}:
4300 See @code{MALLOC} for an example.
4302 @item @emph{See also}:
4309 @section @code{FSEEK} --- Low level file positioning subroutine
4311 @cindex file operation, seek
4312 @cindex file operation, position
4315 @item @emph{Description}:
4316 Moves @var{UNIT} to the specified @var{OFFSET}. If @var{WHENCE}
4317 is set to 0, the @var{OFFSET} is taken as an absolute value @code{SEEK_SET},
4318 if set to 1, @var{OFFSET} is taken to be relative to the current position
4319 @code{SEEK_CUR}, and if set to 2 relative to the end of the file @code{SEEK_END}.
4320 On error, @var{STATUS} is set to a nonzero value. If @var{STATUS} the seek
4323 This intrinsic routine is not fully backwards compatible with @command{g77}.
4324 In @command{g77}, the @code{FSEEK} takes a statement label instead of a
4325 @var{STATUS} variable. If FSEEK is used in old code, change
4327 CALL FSEEK(UNIT, OFFSET, WHENCE, *label)
4332 CALL FSEEK(UNIT, OFFSET, WHENCE, status)
4333 IF (status /= 0) GOTO label
4336 Please note that GNU Fortran provides the Fortran 2003 Stream facility.
4337 Programmers should consider the use of new stream IO feature in new code
4338 for future portability. See also @ref{Fortran 2003 status}.
4340 @item @emph{Standard}:
4346 @item @emph{Syntax}:
4347 @code{CALL FSEEK(UNIT, OFFSET, WHENCE[, STATUS])}
4349 @item @emph{Arguments}:
4350 @multitable @columnfractions .15 .70
4351 @item @var{UNIT} @tab Shall be a scalar of type @code{INTEGER}.
4352 @item @var{OFFSET} @tab Shall be a scalar of type @code{INTEGER}.
4353 @item @var{WHENCE} @tab Shall be a scalar of type @code{INTEGER}.
4354 Its value shall be either 0, 1 or 2.
4355 @item @var{STATUS} @tab (Optional) shall be a scalar of type
4359 @item @emph{Example}:
4362 INTEGER, PARAMETER :: SEEK_SET = 0, SEEK_CUR = 1, SEEK_END = 2
4363 INTEGER :: fd, offset, ierr
4369 OPEN(UNIT=fd, FILE="fseek.test")
4370 CALL FSEEK(fd, offset, SEEK_SET, ierr) ! move to OFFSET
4371 print *, FTELL(fd), ierr
4373 CALL FSEEK(fd, 0, SEEK_END, ierr) ! move to end
4374 print *, FTELL(fd), ierr
4376 CALL FSEEK(fd, 0, SEEK_SET, ierr) ! move to beginning
4377 print *, FTELL(fd), ierr
4383 @item @emph{See also}:
4390 @section @code{FSTAT} --- Get file status
4392 @cindex file system, file status
4395 @item @emph{Description}:
4396 @code{FSTAT} is identical to @ref{STAT}, except that information about an
4397 already opened file is obtained.
4399 The elements in @code{BUFF} are the same as described by @ref{STAT}.
4401 This intrinsic is provided in both subroutine and function forms; however,
4402 only one form can be used in any given program unit.
4404 @item @emph{Standard}:
4408 Subroutine, function
4410 @item @emph{Syntax}:
4411 @code{CALL FSTAT(UNIT, BUFF [, STATUS])}
4413 @item @emph{Arguments}:
4414 @multitable @columnfractions .15 .70
4415 @item @var{UNIT} @tab An open I/O unit number of type @code{INTEGER}.
4416 @item @var{BUFF} @tab The type shall be @code{INTEGER(4), DIMENSION(13)}.
4417 @item @var{STATUS} @tab (Optional) status flag of type @code{INTEGER(4)}. Returns 0
4418 on success and a system specific error code otherwise.
4421 @item @emph{Example}:
4422 See @ref{STAT} for an example.
4424 @item @emph{See also}:
4425 To stat a link: @ref{LSTAT}, to stat a file: @ref{STAT}
4431 @section @code{FTELL} --- Current stream position
4433 @cindex file operation, position
4436 @item @emph{Description}:
4437 Retrieves the current position within an open file.
4439 This intrinsic is provided in both subroutine and function forms; however,
4440 only one form can be used in any given program unit.
4442 @item @emph{Standard}:
4446 Subroutine, function
4448 @item @emph{Syntax}:
4449 @multitable @columnfractions .80
4450 @item @code{CALL FTELL(UNIT, OFFSET)}
4451 @item @code{OFFSET = FTELL(UNIT)}
4454 @item @emph{Arguments}:
4455 @multitable @columnfractions .15 .70
4456 @item @var{OFFSET} @tab Shall of type @code{INTEGER}.
4457 @item @var{UNIT} @tab Shall of type @code{INTEGER}.
4460 @item @emph{Return value}:
4461 In either syntax, @var{OFFSET} is set to the current offset of unit
4462 number @var{UNIT}, or to @math{-1} if the unit is not currently open.
4464 @item @emph{Example}:
4468 OPEN(10, FILE="temp.dat")
4474 @item @emph{See also}:
4481 @section @code{GERROR} --- Get last system error message
4483 @cindex system, error handling
4486 @item @emph{Description}:
4487 Returns the system error message corresponding to the last system error.
4488 This resembles the functionality of @code{strerror(3)} in C.
4490 @item @emph{Standard}:
4496 @item @emph{Syntax}:
4497 @code{CALL GERROR(RESULT)}
4499 @item @emph{Arguments}:
4500 @multitable @columnfractions .15 .70
4501 @item @var{RESULT} @tab Shall of type @code{CHARACTER(*)}.
4504 @item @emph{Example}:
4507 CHARACTER(len=100) :: msg
4513 @item @emph{See also}:
4514 @ref{IERRNO}, @ref{PERROR}
4520 @section @code{GETARG} --- Get command line arguments
4522 @cindex command-line arguments
4523 @cindex arguments, to program
4526 @item @emph{Description}:
4527 Retrieve the @var{N}th argument that was passed on the
4528 command line when the containing program was invoked.
4530 This intrinsic routine is provided for backwards compatibility with
4531 GNU Fortran 77. In new code, programmers should consider the use of
4532 the @ref{GET_COMMAND_ARGUMENT} intrinsic defined by the Fortran 2003
4535 @item @emph{Standard}:
4541 @item @emph{Syntax}:
4542 @code{CALL GETARG(N, ARG)}
4544 @item @emph{Arguments}:
4545 @multitable @columnfractions .15 .70
4546 @item @var{N} @tab Shall be of type @code{INTEGER(4)}, @math{@var{N} \geq 0}
4547 @item @var{ARG} @tab Shall be of type @code{CHARACTER(*)}.
4550 @item @emph{Return value}:
4551 After @code{GETARG} returns, the @var{ARG} argument holds the @var{N}th
4552 command line argument. If @var{ARG} can not hold the argument, it is
4553 truncated to fit the length of @var{ARG}. If there are less than @var{N}
4554 arguments specified at the command line, @var{ARG} will be filled with blanks.
4555 If @math{@var{N} = 0}, @var{ARG} is set to the name of the program (on systems
4556 that support this feature).
4558 @item @emph{Example}:
4562 CHARACTER(len=32) :: arg
4571 @item @emph{See also}:
4572 GNU Fortran 77 compatibility function: @ref{IARGC}
4574 F2003 functions and subroutines: @ref{GET_COMMAND}, @ref{GET_COMMAND_ARGUMENT},
4575 @ref{COMMAND_ARGUMENT_COUNT}
4581 @section @code{GET_COMMAND} --- Get the entire command line
4582 @fnindex GET_COMMAND
4583 @cindex command-line arguments
4584 @cindex arguments, to program
4587 @item @emph{Description}:
4588 Retrieve the entire command line that was used to invoke the program.
4590 @item @emph{Standard}:
4596 @item @emph{Syntax}:
4597 @code{CALL GET_COMMAND(CMD)}
4599 @item @emph{Arguments}:
4600 @multitable @columnfractions .15 .70
4601 @item @var{CMD} @tab Shall be of type @code{CHARACTER(*)}.
4604 @item @emph{Return value}:
4605 Stores the entire command line that was used to invoke the program in @var{ARG}.
4606 If @var{ARG} is not large enough, the command will be truncated.
4608 @item @emph{Example}:
4610 PROGRAM test_get_command
4611 CHARACTER(len=255) :: cmd
4612 CALL get_command(cmd)
4613 WRITE (*,*) TRIM(cmd)
4617 @item @emph{See also}:
4618 @ref{GET_COMMAND_ARGUMENT}, @ref{COMMAND_ARGUMENT_COUNT}
4623 @node GET_COMMAND_ARGUMENT
4624 @section @code{GET_COMMAND_ARGUMENT} --- Get command line arguments
4625 @fnindex GET_COMMAND_ARGUMENT
4626 @cindex command-line arguments
4627 @cindex arguments, to program
4630 @item @emph{Description}:
4631 Retrieve the @var{N}th argument that was passed on the
4632 command line when the containing program was invoked.
4634 @item @emph{Standard}:
4640 @item @emph{Syntax}:
4641 @code{CALL GET_COMMAND_ARGUMENT(N, ARG)}
4643 @item @emph{Arguments}:
4644 @multitable @columnfractions .15 .70
4645 @item @var{N} @tab Shall be of type @code{INTEGER(4)}, @math{@var{N} \geq 0}
4646 @item @var{ARG} @tab Shall be of type @code{CHARACTER(*)}.
4649 @item @emph{Return value}:
4650 After @code{GET_COMMAND_ARGUMENT} returns, the @var{ARG} argument holds the
4651 @var{N}th command line argument. If @var{ARG} can not hold the argument, it is
4652 truncated to fit the length of @var{ARG}. If there are less than @var{N}
4653 arguments specified at the command line, @var{ARG} will be filled with blanks.
4654 If @math{@var{N} = 0}, @var{ARG} is set to the name of the program (on systems
4655 that support this feature).
4657 @item @emph{Example}:
4659 PROGRAM test_get_command_argument
4661 CHARACTER(len=32) :: arg
4665 CALL get_command_argument(i, arg)
4666 IF (LEN_TRIM(arg) == 0) EXIT
4668 WRITE (*,*) TRIM(arg)
4674 @item @emph{See also}:
4675 @ref{GET_COMMAND}, @ref{COMMAND_ARGUMENT_COUNT}
4681 @section @code{GETCWD} --- Get current working directory
4683 @cindex system, working directory
4686 @item @emph{Description}:
4687 Get current working directory.
4689 This intrinsic is provided in both subroutine and function forms; however,
4690 only one form can be used in any given program unit.
4692 @item @emph{Standard}:
4696 Subroutine, function
4698 @item @emph{Syntax}:
4699 @code{CALL GETCWD(CWD [, STATUS])}
4701 @item @emph{Arguments}:
4702 @multitable @columnfractions .15 .70
4703 @item @var{CWD} @tab The type shall be @code{CHARACTER(*)}.
4704 @item @var{STATUS} @tab (Optional) status flag. Returns 0 on success,
4705 a system specific and nonzero error code otherwise.
4708 @item @emph{Example}:
4711 CHARACTER(len=255) :: cwd
4713 WRITE(*,*) TRIM(cwd)
4717 @item @emph{See also}:
4724 @section @code{GETENV} --- Get an environmental variable
4726 @cindex environment variable
4729 @item @emph{Description}:
4730 Get the @var{VALUE} of the environmental variable @var{ENVVAR}.
4732 This intrinsic routine is provided for backwards compatibility with
4733 GNU Fortran 77. In new code, programmers should consider the use of
4734 the @ref{GET_ENVIRONMENT_VARIABLE} intrinsic defined by the Fortran
4737 @item @emph{Standard}:
4743 @item @emph{Syntax}:
4744 @code{CALL GETENV(ENVVAR, VALUE)}
4746 @item @emph{Arguments}:
4747 @multitable @columnfractions .15 .70
4748 @item @var{ENVVAR} @tab Shall be of type @code{CHARACTER(*)}.
4749 @item @var{VALUE} @tab Shall be of type @code{CHARACTER(*)}.
4752 @item @emph{Return value}:
4753 Stores the value of @var{ENVVAR} in @var{VALUE}. If @var{VALUE} is
4754 not large enough to hold the data, it is truncated. If @var{ENVVAR}
4755 is not set, @var{VALUE} will be filled with blanks.
4757 @item @emph{Example}:
4760 CHARACTER(len=255) :: homedir
4761 CALL getenv("HOME", homedir)
4762 WRITE (*,*) TRIM(homedir)
4766 @item @emph{See also}:
4767 @ref{GET_ENVIRONMENT_VARIABLE}
4772 @node GET_ENVIRONMENT_VARIABLE
4773 @section @code{GET_ENVIRONMENT_VARIABLE} --- Get an environmental variable
4774 @fnindex GET_ENVIRONMENT_VARIABLE
4775 @cindex environment variable
4778 @item @emph{Description}:
4779 Get the @var{VALUE} of the environmental variable @var{ENVVAR}.
4781 @item @emph{Standard}:
4787 @item @emph{Syntax}:
4788 @code{CALL GET_ENVIRONMENT_VARIABLE(ENVVAR, VALUE)}
4790 @item @emph{Arguments}:
4791 @multitable @columnfractions .15 .70
4792 @item @var{ENVVAR} @tab Shall be of type @code{CHARACTER(*)}.
4793 @item @var{VALUE} @tab Shall be of type @code{CHARACTER(*)}.
4796 @item @emph{Return value}:
4797 Stores the value of @var{ENVVAR} in @var{VALUE}. If @var{VALUE} is
4798 not large enough to hold the data, it is truncated. If @var{ENVVAR}
4799 is not set, @var{VALUE} will be filled with blanks.
4801 @item @emph{Example}:
4804 CHARACTER(len=255) :: homedir
4805 CALL get_environment_variable("HOME", homedir)
4806 WRITE (*,*) TRIM(homedir)
4814 @section @code{GETGID} --- Group ID function
4816 @cindex system, group id
4819 @item @emph{Description}:
4820 Returns the numerical group ID of the current process.
4822 @item @emph{Standard}:
4828 @item @emph{Syntax}:
4829 @code{RESULT = GETGID()}
4831 @item @emph{Return value}:
4832 The return value of @code{GETGID} is an @code{INTEGER} of the default
4836 @item @emph{Example}:
4837 See @code{GETPID} for an example.
4839 @item @emph{See also}:
4840 @ref{GETPID}, @ref{GETUID}
4846 @section @code{GETLOG} --- Get login name
4848 @cindex system, login name
4852 @item @emph{Description}:
4853 Gets the username under which the program is running.
4855 @item @emph{Standard}:
4861 @item @emph{Syntax}:
4862 @code{CALL GETLOG(LOGIN)}
4864 @item @emph{Arguments}:
4865 @multitable @columnfractions .15 .70
4866 @item @var{LOGIN} @tab Shall be of type @code{CHARACTER(*)}.
4869 @item @emph{Return value}:
4870 Stores the current user name in @var{LOGIN}. (On systems where POSIX
4871 functions @code{geteuid} and @code{getpwuid} are not available, and
4872 the @code{getlogin} function is not implemented either, this will
4873 return a blank string.)
4875 @item @emph{Example}:
4878 CHARACTER(32) :: login
4884 @item @emph{See also}:
4891 @section @code{GETPID} --- Process ID function
4893 @cindex system, process id
4897 @item @emph{Description}:
4898 Returns the numerical process identifier of the current process.
4900 @item @emph{Standard}:
4906 @item @emph{Syntax}:
4907 @code{RESULT = GETPID()}
4909 @item @emph{Return value}:
4910 The return value of @code{GETPID} is an @code{INTEGER} of the default
4914 @item @emph{Example}:
4917 print *, "The current process ID is ", getpid()
4918 print *, "Your numerical user ID is ", getuid()
4919 print *, "Your numerical group ID is ", getgid()
4923 @item @emph{See also}:
4924 @ref{GETGID}, @ref{GETUID}
4930 @section @code{GETUID} --- User ID function
4932 @cindex system, user id
4936 @item @emph{Description}:
4937 Returns the numerical user ID of the current process.
4939 @item @emph{Standard}:
4945 @item @emph{Syntax}:
4946 @code{RESULT = GETUID()}
4948 @item @emph{Return value}:
4949 The return value of @code{GETUID} is an @code{INTEGER} of the default
4953 @item @emph{Example}:
4954 See @code{GETPID} for an example.
4956 @item @emph{See also}:
4957 @ref{GETPID}, @ref{GETLOG}
4963 @section @code{GMTIME} --- Convert time to GMT info
4965 @cindex time, conversion to GMT info
4968 @item @emph{Description}:
4969 Given a system time value @var{STIME} (as provided by the @code{TIME8()}
4970 intrinsic), fills @var{TARRAY} with values extracted from it appropriate
4971 to the UTC time zone (Universal Coordinated Time, also known in some
4972 countries as GMT, Greenwich Mean Time), using @code{gmtime(3)}.
4974 @item @emph{Standard}:
4980 @item @emph{Syntax}:
4981 @code{CALL GMTIME(STIME, TARRAY)}
4983 @item @emph{Arguments}:
4984 @multitable @columnfractions .15 .70
4985 @item @var{STIME} @tab An @code{INTEGER(*)} scalar expression
4986 corresponding to a system time, with
4988 @item @var{TARRAY} @tab A default @code{INTEGER} array with 9 elements,
4989 with @code{INTENT(OUT)}.
4992 @item @emph{Return value}:
4993 The elements of @var{TARRAY} are assigned as follows:
4995 @item Seconds after the minute, range 0--59 or 0--61 to allow for leap
4997 @item Minutes after the hour, range 0--59
4998 @item Hours past midnight, range 0--23
4999 @item Day of month, range 0--31
5000 @item Number of months since January, range 0--12
5001 @item Years since 1900
5002 @item Number of days since Sunday, range 0--6
5003 @item Days since January 1
5004 @item Daylight savings indicator: positive if daylight savings is in
5005 effect, zero if not, and negative if the information is not
5009 @item @emph{See also}:
5010 @ref{CTIME}, @ref{LTIME}, @ref{TIME}, @ref{TIME8}
5017 @section @code{HOSTNM} --- Get system host name
5019 @cindex system, host name
5022 @item @emph{Description}:
5023 Retrieves the host name of the system on which the program is running.
5025 This intrinsic is provided in both subroutine and function forms; however,
5026 only one form can be used in any given program unit.
5028 @item @emph{Standard}:
5032 Subroutine, function
5034 @item @emph{Syntax}:
5035 @multitable @columnfractions .80
5036 @item @code{CALL HOSTNM(NAME[, STATUS])}
5037 @item @code{STATUS = HOSTNM(NAME)}
5040 @item @emph{Arguments}:
5041 @multitable @columnfractions .15 .70
5042 @item @var{NAME} @tab Shall of type @code{CHARACTER(*)}.
5043 @item @var{STATUS} @tab (Optional) status flag of type @code{INTEGER}.
5044 Returns 0 on success, or a system specific error
5048 @item @emph{Return value}:
5049 In either syntax, @var{NAME} is set to the current hostname if it can
5050 be obtained, or to a blank string otherwise.
5057 @section @code{HUGE} --- Largest number of a kind
5059 @cindex limits, largest number
5060 @cindex model representation, largest number
5063 @item @emph{Description}:
5064 @code{HUGE(X)} returns the largest number that is not an infinity in
5065 the model of the type of @code{X}.
5067 @item @emph{Standard}:
5073 @item @emph{Syntax}:
5074 @code{RESULT = HUGE(X)}
5076 @item @emph{Arguments}:
5077 @multitable @columnfractions .15 .70
5078 @item @var{X} @tab Shall be of type @code{REAL} or @code{INTEGER}.
5081 @item @emph{Return value}:
5082 The return value is of the same type and kind as @var{X}
5084 @item @emph{Example}:
5086 program test_huge_tiny
5087 print *, huge(0), huge(0.0), huge(0.0d0)
5088 print *, tiny(0.0), tiny(0.0d0)
5089 end program test_huge_tiny
5096 @section @code{IACHAR} --- Code in @acronym{ASCII} collating sequence
5098 @cindex @acronym{ASCII} collating sequence
5099 @cindex collating sequence, @acronym{ASCII}
5100 @cindex conversion, to integer
5103 @item @emph{Description}:
5104 @code{IACHAR(C)} returns the code for the @acronym{ASCII} character
5105 in the first character position of @code{C}.
5107 @item @emph{Standard}:
5113 @item @emph{Syntax}:
5114 @code{RESULT = IACHAR(C)}
5116 @item @emph{Arguments}:
5117 @multitable @columnfractions .15 .70
5118 @item @var{C} @tab Shall be a scalar @code{CHARACTER}, with @code{INTENT(IN)}
5121 @item @emph{Return value}:
5122 The return value is of type @code{INTEGER} and of the default integer
5125 @item @emph{Example}:
5130 end program test_iachar
5134 See @ref{ICHAR} for a discussion of converting between numerical values
5135 and formatted string representations.
5137 @item @emph{See also}:
5138 @ref{ACHAR}, @ref{CHAR}, @ref{ICHAR}
5145 @section @code{IAND} --- Bitwise logical and
5147 @cindex bitwise logical and
5148 @cindex logical and, bitwise
5151 @item @emph{Description}:
5152 Bitwise logical @code{AND}.
5154 @item @emph{Standard}:
5160 @item @emph{Syntax}:
5161 @code{RESULT = IAND(I, J)}
5163 @item @emph{Arguments}:
5164 @multitable @columnfractions .15 .70
5165 @item @var{I} @tab The type shall be @code{INTEGER(*)}.
5166 @item @var{J} @tab The type shall be @code{INTEGER(*)}, of the same
5167 kind as @var{I}. (As a GNU extension, different kinds are also
5171 @item @emph{Return value}:
5172 The return type is @code{INTEGER(*)}, of the same kind as the
5173 arguments. (If the argument kinds differ, it is of the same kind as
5174 the larger argument.)
5176 @item @emph{Example}:
5180 DATA a / Z'F' /, b / Z'3' /
5181 WRITE (*,*) IAND(a, b)
5185 @item @emph{See also}:
5186 @ref{IOR}, @ref{IEOR}, @ref{IBITS}, @ref{IBSET}, @ref{IBCLR}, @ref{NOT}
5193 @section @code{IARGC} --- Get the number of command line arguments
5195 @cindex command-line arguments
5196 @cindex command-line arguments, number of
5197 @cindex arguments, to program
5200 @item @emph{Description}:
5201 @code{IARGC()} returns the number of arguments passed on the
5202 command line when the containing program was invoked.
5204 This intrinsic routine is provided for backwards compatibility with
5205 GNU Fortran 77. In new code, programmers should consider the use of
5206 the @ref{COMMAND_ARGUMENT_COUNT} intrinsic defined by the Fortran 2003
5209 @item @emph{Standard}:
5215 @item @emph{Syntax}:
5216 @code{RESULT = IARGC()}
5218 @item @emph{Arguments}:
5221 @item @emph{Return value}:
5222 The number of command line arguments, type @code{INTEGER(4)}.
5224 @item @emph{Example}:
5227 @item @emph{See also}:
5228 GNU Fortran 77 compatibility subroutine: @ref{GETARG}
5230 F2003 functions and subroutines: @ref{GET_COMMAND}, @ref{GET_COMMAND_ARGUMENT},
5231 @ref{COMMAND_ARGUMENT_COUNT}
5237 @section @code{IBCLR} --- Clear bit
5243 @item @emph{Description}:
5244 @code{IBCLR} returns the value of @var{I} with the bit at position
5245 @var{POS} set to zero.
5247 @item @emph{Standard}:
5253 @item @emph{Syntax}:
5254 @code{RESULT = IBCLR(I, POS)}
5256 @item @emph{Arguments}:
5257 @multitable @columnfractions .15 .70
5258 @item @var{I} @tab The type shall be @code{INTEGER(*)}.
5259 @item @var{POS} @tab The type shall be @code{INTEGER(*)}.
5262 @item @emph{Return value}:
5263 The return value is of type @code{INTEGER(*)} and of the same kind as
5266 @item @emph{See also}:
5267 @ref{IBITS}, @ref{IBSET}, @ref{IAND}, @ref{IOR}, @ref{IEOR}, @ref{MVBITS}
5274 @section @code{IBITS} --- Bit extraction
5277 @cindex bits, extract
5280 @item @emph{Description}:
5281 @code{IBITS} extracts a field of length @var{LEN} from @var{I},
5282 starting from bit position @var{POS} and extending left for @var{LEN}
5283 bits. The result is right-justified and the remaining bits are
5284 zeroed. The value of @code{POS+LEN} must be less than or equal to the
5285 value @code{BIT_SIZE(I)}.
5287 @item @emph{Standard}:
5293 @item @emph{Syntax}:
5294 @code{RESULT = IBITS(I, POS, LEN)}
5296 @item @emph{Arguments}:
5297 @multitable @columnfractions .15 .70
5298 @item @var{I} @tab The type shall be @code{INTEGER(*)}.
5299 @item @var{POS} @tab The type shall be @code{INTEGER(*)}.
5300 @item @var{LEN} @tab The type shall be @code{INTEGER(*)}.
5303 @item @emph{Return value}:
5304 The return value is of type @code{INTEGER(*)} and of the same kind as
5307 @item @emph{See also}:
5308 @ref{BIT_SIZE}, @ref{IBCLR}, @ref{IBSET}, @ref{IAND}, @ref{IOR}, @ref{IEOR}
5314 @section @code{IBSET} --- Set bit
5319 @item @emph{Description}:
5320 @code{IBSET} returns the value of @var{I} with the bit at position
5321 @var{POS} set to one.
5323 @item @emph{Standard}:
5329 @item @emph{Syntax}:
5330 @code{RESULT = IBSET(I, POS)}
5332 @item @emph{Arguments}:
5333 @multitable @columnfractions .15 .70
5334 @item @var{I} @tab The type shall be @code{INTEGER(*)}.
5335 @item @var{POS} @tab The type shall be @code{INTEGER(*)}.
5338 @item @emph{Return value}:
5339 The return value is of type @code{INTEGER(*)} and of the same kind as
5342 @item @emph{See also}:
5343 @ref{IBCLR}, @ref{IBITS}, @ref{IAND}, @ref{IOR}, @ref{IEOR}, @ref{MVBITS}
5350 @section @code{ICHAR} --- Character-to-integer conversion function
5352 @cindex conversion, to integer
5355 @item @emph{Description}:
5356 @code{ICHAR(C)} returns the code for the character in the first character
5357 position of @code{C} in the system's native character set.
5358 The correspondence between characters and their codes is not necessarily
5359 the same across different GNU Fortran implementations.
5361 @item @emph{Standard}:
5367 @item @emph{Syntax}:
5368 @code{RESULT = ICHAR(C)}
5370 @item @emph{Arguments}:
5371 @multitable @columnfractions .15 .70
5372 @item @var{C} @tab Shall be a scalar @code{CHARACTER}, with @code{INTENT(IN)}
5375 @item @emph{Return value}:
5376 The return value is of type @code{INTEGER} and of the default integer
5379 @item @emph{Example}:
5384 end program test_ichar
5388 No intrinsic exists to convert between a numeric value and a formatted
5389 character string representation -- for instance, given the
5390 @code{CHARACTER} value @code{'154'}, obtaining an @code{INTEGER} or
5391 @code{REAL} value with the value 154, or vice versa. Instead, this
5392 functionality is provided by internal-file I/O, as in the following
5397 character(len=10) string, string2
5400 ! Convert a string to a numeric value
5401 read (string,'(I10)') value
5404 ! Convert a value to a formatted string
5405 write (string2,'(I10)') value
5407 end program read_val
5410 @item @emph{See also}:
5411 @ref{ACHAR}, @ref{CHAR}, @ref{IACHAR}
5418 @section @code{IDATE} --- Get current local time subroutine (day/month/year)
5420 @cindex date, current
5421 @cindex current date
5424 @item @emph{Description}:
5425 @code{IDATE(TARRAY)} Fills @var{TARRAY} with the numerical values at the
5426 current local time. The day (in the range 1-31), month (in the range 1-12),
5427 and year appear in elements 1, 2, and 3 of @var{TARRAY}, respectively.
5428 The year has four significant digits.
5430 @item @emph{Standard}:
5436 @item @emph{Syntax}:
5437 @code{CALL IDATE(TARRAY)}
5439 @item @emph{Arguments}:
5440 @multitable @columnfractions .15 .70
5441 @item @var{TARRAY} @tab The type shall be @code{INTEGER, DIMENSION(3)} and
5442 the kind shall be the default integer kind.
5445 @item @emph{Return value}:
5448 @item @emph{Example}:
5451 integer, dimension(3) :: tarray
5456 end program test_idate
5463 @section @code{IEOR} --- Bitwise logical exclusive or
5465 @cindex bitwise logical exclusive or
5466 @cindex logical exclusive or, bitwise
5469 @item @emph{Description}:
5470 @code{IEOR} returns the bitwise boolean exclusive-OR of @var{I} and
5473 @item @emph{Standard}:
5479 @item @emph{Syntax}:
5480 @code{RESULT = IEOR(I, J)}
5482 @item @emph{Arguments}:
5483 @multitable @columnfractions .15 .70
5484 @item @var{I} @tab The type shall be @code{INTEGER(*)}.
5485 @item @var{J} @tab The type shall be @code{INTEGER(*)}, of the same
5486 kind as @var{I}. (As a GNU extension, different kinds are also
5490 @item @emph{Return value}:
5491 The return type is @code{INTEGER(*)}, of the same kind as the
5492 arguments. (If the argument kinds differ, it is of the same kind as
5493 the larger argument.)
5495 @item @emph{See also}:
5496 @ref{IOR}, @ref{IAND}, @ref{IBITS}, @ref{IBSET}, @ref{IBCLR}, @ref{NOT}
5502 @section @code{IERRNO} --- Get the last system error number
5504 @cindex system, error handling
5507 @item @emph{Description}:
5508 Returns the last system error number, as given by the C @code{errno()}
5511 @item @emph{Standard}:
5517 @item @emph{Syntax}:
5518 @code{RESULT = IERRNO()}
5520 @item @emph{Arguments}:
5523 @item @emph{Return value}:
5524 The return value is of type @code{INTEGER} and of the default integer
5527 @item @emph{See also}:
5534 @section @code{INDEX} --- Position of a substring within a string
5536 @cindex substring position
5537 @cindex string, find substring
5540 @item @emph{Description}:
5541 Returns the position of the start of the first occurrence of string
5542 @var{SUBSTRING} as a substring in @var{STRING}, counting from one. If
5543 @var{SUBSTRING} is not present in @var{STRING}, zero is returned. If
5544 the @var{BACK} argument is present and true, the return value is the
5545 start of the last occurrence rather than the first.
5547 @item @emph{Standard}:
5553 @item @emph{Syntax}:
5554 @code{RESULT = INDEX(STRING, SUBSTRING [, BACK])}
5556 @item @emph{Arguments}:
5557 @multitable @columnfractions .15 .70
5558 @item @var{STRING} @tab Shall be a scalar @code{CHARACTER(*)}, with
5560 @item @var{SUBSTRING} @tab Shall be a scalar @code{CHARACTER(*)}, with
5562 @item @var{BACK} @tab (Optional) Shall be a scalar @code{LOGICAL(*)}, with
5566 @item @emph{Return value}:
5567 The return value is of type @code{INTEGER} and of the default integer
5570 @item @emph{See also}:
5571 @ref{SCAN}, @ref{VERIFY}
5577 @section @code{INT} --- Convert to integer type
5581 @cindex conversion, to integer
5584 @item @emph{Description}:
5585 Convert to integer type
5587 @item @emph{Standard}:
5593 @item @emph{Syntax}:
5594 @code{RESULT = INT(A [, KIND))}
5596 @item @emph{Arguments}:
5597 @multitable @columnfractions .15 .70
5598 @item @var{A} @tab Shall be of type @code{INTEGER(*)},
5599 @code{REAL(*)}, or @code{COMPLEX(*)}.
5600 @item @var{KIND} @tab (Optional) An @code{INTEGER(*)} initialization
5601 expression indicating the kind parameter of
5605 @item @emph{Return value}:
5606 These functions return a @code{INTEGER(*)} variable or array under
5607 the following rules:
5611 If @var{A} is of type @code{INTEGER(*)}, @code{INT(A) = A}
5613 If @var{A} is of type @code{REAL(*)} and @math{|A| < 1}, @code{INT(A)} equals @code{0}.
5614 If @math{|A| \geq 1}, then @code{INT(A)} equals the largest integer that does not exceed
5615 the range of @var{A} and whose sign is the same as the sign of @var{A}.
5617 If @var{A} is of type @code{COMPLEX(*)}, rule B is applied to the real part of @var{A}.
5620 @item @emph{Example}:
5624 complex :: z = (-3.7, 1.0)
5626 print *, int(z), int(z,8)
5630 @item @emph{Specific names}:
5631 @multitable @columnfractions .20 .20 .20 .25
5632 @item Name @tab Argument @tab Return type @tab Standard
5633 @item @code{IFIX(A)} @tab @code{REAL(4) A} @tab @code{INTEGER} @tab F77 and later
5634 @item @code{IDINT(A)} @tab @code{REAL(8) A} @tab @code{INTEGER} @tab F77 and later
5642 @section @code{INT2} --- Convert to 16-bit integer type
5645 @cindex conversion, to integer
5648 @item @emph{Description}:
5649 Convert to a @code{KIND=2} integer type. This is equivalent to the
5650 standard @code{INT} intrinsic with an optional argument of
5651 @code{KIND=2}, and is only included for backwards compatibility.
5653 The @code{SHORT} intrinsic is equivalent to @code{INT2}.
5655 @item @emph{Standard}:
5661 @item @emph{Syntax}:
5662 @code{RESULT = INT2(A)}
5664 @item @emph{Arguments}:
5665 @multitable @columnfractions .15 .70
5666 @item @var{A} @tab Shall be of type @code{INTEGER(*)},
5667 @code{REAL(*)}, or @code{COMPLEX(*)}.
5670 @item @emph{Return value}:
5671 The return value is a @code{INTEGER(2)} variable.
5673 @item @emph{See also}:
5674 @ref{INT}, @ref{INT8}, @ref{LONG}
5680 @section @code{INT8} --- Convert to 64-bit integer type
5682 @cindex conversion, to integer
5685 @item @emph{Description}:
5686 Convert to a @code{KIND=8} integer type. This is equivalent to the
5687 standard @code{INT} intrinsic with an optional argument of
5688 @code{KIND=8}, and is only included for backwards compatibility.
5690 @item @emph{Standard}:
5696 @item @emph{Syntax}:
5697 @code{RESULT = INT8(A)}
5699 @item @emph{Arguments}:
5700 @multitable @columnfractions .15 .70
5701 @item @var{A} @tab Shall be of type @code{INTEGER(*)},
5702 @code{REAL(*)}, or @code{COMPLEX(*)}.
5705 @item @emph{Return value}:
5706 The return value is a @code{INTEGER(8)} variable.
5708 @item @emph{See also}:
5709 @ref{INT}, @ref{INT2}, @ref{LONG}
5715 @section @code{IOR} --- Bitwise logical or
5717 @cindex bitwise logical or
5718 @cindex logical or, bitwise
5721 @item @emph{Description}:
5722 @code{IEOR} returns the bitwise boolean OR of @var{I} and
5725 @item @emph{Standard}:
5731 @item @emph{Syntax}:
5732 @code{RESULT = IEOR(I, J)}
5734 @item @emph{Arguments}:
5735 @multitable @columnfractions .15 .70
5736 @item @var{I} @tab The type shall be @code{INTEGER(*)}.
5737 @item @var{J} @tab The type shall be @code{INTEGER(*)}, of the same
5738 kind as @var{I}. (As a GNU extension, different kinds are also
5742 @item @emph{Return value}:
5743 The return type is @code{INTEGER(*)}, of the same kind as the
5744 arguments. (If the argument kinds differ, it is of the same kind as
5745 the larger argument.)
5747 @item @emph{See also}:
5748 @ref{IEOR}, @ref{IAND}, @ref{IBITS}, @ref{IBSET}, @ref{IBCLR}, @ref{NOT}
5754 @section @code{IRAND} --- Integer pseudo-random number
5756 @cindex random number generation
5759 @item @emph{Description}:
5760 @code{IRAND(FLAG)} returns a pseudo-random number from a uniform
5761 distribution between 0 and a system-dependent limit (which is in most
5762 cases 2147483647). If @var{FLAG} is 0, the next number
5763 in the current sequence is returned; if @var{FLAG} is 1, the generator
5764 is restarted by @code{CALL SRAND(0)}; if @var{FLAG} has any other value,
5765 it is used as a new seed with @code{SRAND}.
5767 This intrinsic routine is provided for backwards compatibility with
5768 GNU Fortran 77. It implements a simple modulo generator as provided
5769 by @command{g77}. For new code, one should consider the use of
5770 @ref{RANDOM_NUMBER} as it implements a superior algorithm.
5772 @item @emph{Standard}:
5778 @item @emph{Syntax}:
5779 @code{RESULT = IRAND(FLAG)}
5781 @item @emph{Arguments}:
5782 @multitable @columnfractions .15 .70
5783 @item @var{FLAG} @tab Shall be a scalar @code{INTEGER} of kind 4.
5786 @item @emph{Return value}:
5787 The return value is of @code{INTEGER(kind=4)} type.
5789 @item @emph{Example}:
5792 integer,parameter :: seed = 86456
5795 print *, irand(), irand(), irand(), irand()
5796 print *, irand(seed), irand(), irand(), irand()
5797 end program test_irand
5805 @section @code{ISATTY} --- Whether a unit is a terminal device.
5807 @cindex system, terminal
5810 @item @emph{Description}:
5811 Determine whether a unit is connected to a terminal device.
5813 @item @emph{Standard}:
5819 @item @emph{Syntax}:
5820 @code{RESULT = ISATTY(UNIT)}
5822 @item @emph{Arguments}:
5823 @multitable @columnfractions .15 .70
5824 @item @var{UNIT} @tab Shall be a scalar @code{INTEGER(*)}.
5827 @item @emph{Return value}:
5828 Returns @code{.TRUE.} if the @var{UNIT} is connected to a terminal
5829 device, @code{.FALSE.} otherwise.
5831 @item @emph{Example}:
5834 INTEGER(kind=1) :: unit
5836 write(*,*) isatty(unit=unit)
5840 @item @emph{See also}:
5847 @section @code{ISHFT} --- Shift bits
5852 @item @emph{Description}:
5853 @code{ISHFT} returns a value corresponding to @var{I} with all of the
5854 bits shifted @var{SHIFT} places. A value of @var{SHIFT} greater than
5855 zero corresponds to a left shift, a value of zero corresponds to no
5856 shift, and a value less than zero corresponds to a right shift. If the
5857 absolute value of @var{SHIFT} is greater than @code{BIT_SIZE(I)}, the
5858 value is undefined. Bits shifted out from the left end or right end are
5859 lost; zeros are shifted in from the opposite end.
5861 @item @emph{Standard}:
5867 @item @emph{Syntax}:
5868 @code{RESULT = ISHFT(I, SHIFT)}
5870 @item @emph{Arguments}:
5871 @multitable @columnfractions .15 .70
5872 @item @var{I} @tab The type shall be @code{INTEGER(*)}.
5873 @item @var{SHIFT} @tab The type shall be @code{INTEGER(*)}.
5876 @item @emph{Return value}:
5877 The return value is of type @code{INTEGER(*)} and of the same kind as
5880 @item @emph{See also}:
5887 @section @code{ISHFTC} --- Shift bits circularly
5889 @cindex bits, shift circular
5892 @item @emph{Description}:
5893 @code{ISHFTC} returns a value corresponding to @var{I} with the
5894 rightmost @var{SIZE} bits shifted circularly @var{SHIFT} places; that
5895 is, bits shifted out one end are shifted into the opposite end. A value
5896 of @var{SHIFT} greater than zero corresponds to a left shift, a value of
5897 zero corresponds to no shift, and a value less than zero corresponds to
5898 a right shift. The absolute value of @var{SHIFT} must be less than
5899 @var{SIZE}. If the @var{SIZE} argument is omitted, it is taken to be
5900 equivalent to @code{BIT_SIZE(I)}.
5902 @item @emph{Standard}:
5908 @item @emph{Syntax}:
5909 @code{RESULT = ISHFTC(I, SHIFT [, SIZE])}
5911 @item @emph{Arguments}:
5912 @multitable @columnfractions .15 .70
5913 @item @var{I} @tab The type shall be @code{INTEGER(*)}.
5914 @item @var{SHIFT} @tab The type shall be @code{INTEGER(*)}.
5915 @item @var{SIZE} @tab (Optional) The type shall be @code{INTEGER(*)};
5916 the value must be greater than zero and less than or equal to
5920 @item @emph{Return value}:
5921 The return value is of type @code{INTEGER(*)} and of the same kind as
5924 @item @emph{See also}:
5931 @section @code{ITIME} --- Get current local time subroutine (hour/minutes/seconds)
5933 @cindex time, current
5934 @cindex current time
5937 @item @emph{Description}:
5938 @code{IDATE(TARRAY)} Fills @var{TARRAY} with the numerical values at the
5939 current local time. The hour (in the range 1-24), minute (in the range 1-60),
5940 and seconds (in the range 1-60) appear in elements 1, 2, and 3 of @var{TARRAY},
5943 @item @emph{Standard}:
5949 @item @emph{Syntax}:
5950 @code{CALL ITIME(TARRAY)}
5952 @item @emph{Arguments}:
5953 @multitable @columnfractions .15 .70
5954 @item @var{TARRAY} @tab The type shall be @code{INTEGER, DIMENSION(3)}
5955 and the kind shall be the default integer kind.
5958 @item @emph{Return value}:
5962 @item @emph{Example}:
5965 integer, dimension(3) :: tarray
5970 end program test_itime
5977 @section @code{KILL} --- Send a signal to a process
5981 @item @emph{Description}:
5982 @item @emph{Standard}:
5983 Sends the signal specified by @var{SIGNAL} to the process @var{PID}.
5986 This intrinsic is provided in both subroutine and function forms; however,
5987 only one form can be used in any given program unit.
5990 Subroutine, function
5992 @item @emph{Syntax}:
5993 @code{CALL KILL(PID, SIGNAL [, STATUS])}
5995 @item @emph{Arguments}:
5996 @multitable @columnfractions .15 .70
5997 @item @var{PID} @tab Shall be a scalar @code{INTEGER}, with
5999 @item @var{SIGNAL} @tab Shall be a scalar @code{INTEGER}, with
6001 @item @var{STATUS} @tab (Optional) status flag of type @code{INTEGER(4)} or
6002 @code{INTEGER(8)}. Returns 0 on success, or a
6003 system-specific error code otherwise.
6006 @item @emph{See also}:
6007 @ref{ABORT}, @ref{EXIT}
6013 @section @code{KIND} --- Kind of an entity
6018 @item @emph{Description}:
6019 @code{KIND(X)} returns the kind value of the entity @var{X}.
6021 @item @emph{Standard}:
6027 @item @emph{Syntax}:
6030 @item @emph{Arguments}:
6031 @multitable @columnfractions .15 .70
6032 @item @var{X} @tab Shall be of type @code{LOGICAL}, @code{INTEGER},
6033 @code{REAL}, @code{COMPLEX} or @code{CHARACTER}.
6036 @item @emph{Return value}:
6037 The return value is a scalar of type @code{INTEGER} and of the default
6040 @item @emph{Example}:
6043 integer,parameter :: kc = kind(' ')
6044 integer,parameter :: kl = kind(.true.)
6046 print *, "The default character kind is ", kc
6047 print *, "The default logical kind is ", kl
6048 end program test_kind
6056 @section @code{LBOUND} --- Lower dimension bounds of an array
6058 @cindex array, lower bound
6061 @item @emph{Description}:
6062 Returns the lower bounds of an array, or a single lower bound
6063 along the @var{DIM} dimension.
6064 @item @emph{Standard}:
6070 @item @emph{Syntax}:
6071 @code{RESULT = LBOUND(ARRAY [, DIM])}
6073 @item @emph{Arguments}:
6074 @multitable @columnfractions .15 .70
6075 @item @var{ARRAY} @tab Shall be an array, of any type.
6076 @item @var{DIM} @tab (Optional) Shall be a scalar @code{INTEGER(*)}.
6079 @item @emph{Return value}:
6080 If @var{DIM} is absent, the result is an array of the lower bounds of
6081 @var{ARRAY}. If @var{DIM} is present, the result is a scalar
6082 corresponding to the lower bound of the array along that dimension. If
6083 @var{ARRAY} is an expression rather than a whole array or array
6084 structure component, or if it has a zero extent along the relevant
6085 dimension, the lower bound is taken to be 1.
6087 @item @emph{See also}:
6094 @section @code{LEN} --- Length of a character entity
6096 @cindex string, length
6099 @item @emph{Description}:
6100 Returns the length of a character string. If @var{STRING} is an array,
6101 the length of an element of @var{STRING} is returned. Note that
6102 @var{STRING} need not be defined when this intrinsic is invoked, since
6103 only the length, not the content, of @var{STRING} is needed.
6105 @item @emph{Standard}:
6111 @item @emph{Syntax}:
6112 @code{L = LEN(STRING)}
6114 @item @emph{Arguments}:
6115 @multitable @columnfractions .15 .70
6116 @item @var{STRING} @tab Shall be a scalar or array of type
6117 @code{CHARACTER(*)}, with @code{INTENT(IN)}
6120 @item @emph{Return value}:
6121 The return value is an @code{INTEGER} of the default kind.
6123 @item @emph{See also}:
6124 @ref{LEN_TRIM}, @ref{ADJUSTL}, @ref{ADJUSTR}
6130 @section @code{LEN_TRIM} --- Length of a character entity without trailing blank characters
6132 @cindex string, length, without trailing whitespace
6135 @item @emph{Description}:
6136 Returns the length of a character string, ignoring any trailing blanks.
6138 @item @emph{Standard}:
6144 @item @emph{Syntax}:
6145 @code{RESULT = LEN_TRIM(STRING)}
6147 @item @emph{Arguments}:
6148 @multitable @columnfractions .15 .70
6149 @item @var{STRING} @tab Shall be a scalar of type @code{CHARACTER(*)},
6150 with @code{INTENT(IN)}
6153 @item @emph{Return value}:
6154 The return value is an @code{INTEGER} of the default kind.
6156 @item @emph{See also}:
6157 @ref{LEN}, @ref{ADJUSTL}, @ref{ADJUSTR}
6163 @section @code{LGE} --- Lexical greater than or equal
6165 @cindex lexical comparison of strings
6166 @cindex string, comparison
6169 @item @emph{Description}:
6170 Determines whether one string is lexically greater than or equal to
6171 another string, where the two strings are interpreted as containing
6172 ASCII character codes. If the String A and String B are not the same
6173 length, the shorter is compared as if spaces were appended to it to form
6174 a value that has the same length as the longer.
6176 In general, the lexical comparison intrinsics @code{LGE}, @code{LGT},
6177 @code{LLE}, and @code{LLT} differ from the corresponding intrinsic
6178 operators @code{.GE.}, @code{.GT.}, @code{.LE.}, and @code{.LT.}, in
6179 that the latter use the processor's character ordering (which is not
6180 ASCII on some targets), whereas the former always use the ASCII
6183 @item @emph{Standard}:
6189 @item @emph{Syntax}:
6190 @code{RESULT = LGE(STRING_A, STRING_B)}
6192 @item @emph{Arguments}:
6193 @multitable @columnfractions .15 .70
6194 @item @var{STRING_A} @tab Shall be of default @code{CHARACTER} type.
6195 @item @var{STRING_B} @tab Shall be of default @code{CHARACTER} type.
6198 @item @emph{Return value}:
6199 Returns @code{.TRUE.} if @code{STRING_A >= STRING_B}, and @code{.FALSE.}
6200 otherwise, based on the ASCII ordering.
6202 @item @emph{See also}:
6203 @ref{LGT}, @ref{LLE}, @ref{LLT}
6209 @section @code{LGT} --- Lexical greater than
6211 @cindex lexical comparison of strings
6212 @cindex string, comparison
6215 @item @emph{Description}:
6216 Determines whether one string is lexically greater than another string,
6217 where the two strings are interpreted as containing ASCII character
6218 codes. If the String A and String B are not the same length, the
6219 shorter is compared as if spaces were appended to it to form a value
6220 that has the same length as the longer.
6222 In general, the lexical comparison intrinsics @code{LGE}, @code{LGT},
6223 @code{LLE}, and @code{LLT} differ from the corresponding intrinsic
6224 operators @code{.GE.}, @code{.GT.}, @code{.LE.}, and @code{.LT.}, in
6225 that the latter use the processor's character ordering (which is not
6226 ASCII on some targets), whereas the former always use the ASCII
6229 @item @emph{Standard}:
6235 @item @emph{Syntax}:
6236 @code{RESULT = LGT(STRING_A, STRING_B)}
6238 @item @emph{Arguments}:
6239 @multitable @columnfractions .15 .70
6240 @item @var{STRING_A} @tab Shall be of default @code{CHARACTER} type.
6241 @item @var{STRING_B} @tab Shall be of default @code{CHARACTER} type.
6244 @item @emph{Return value}:
6245 Returns @code{.TRUE.} if @code{STRING_A > STRING_B}, and @code{.FALSE.}
6246 otherwise, based on the ASCII ordering.
6248 @item @emph{See also}:
6249 @ref{LGE}, @ref{LLE}, @ref{LLT}
6255 @section @code{LINK} --- Create a hard link
6257 @cindex file system, create link
6258 @cindex file system, hard link
6261 @item @emph{Description}:
6262 Makes a (hard) link from file @var{PATH1} to @var{PATH2}. A null
6263 character (@code{CHAR(0)}) can be used to mark the end of the names in
6264 @var{PATH1} and @var{PATH2}; otherwise, trailing blanks in the file
6265 names are ignored. If the @var{STATUS} argument is supplied, it
6266 contains 0 on success or a nonzero error code upon return; see
6269 This intrinsic is provided in both subroutine and function forms;
6270 however, only one form can be used in any given program unit.
6272 @item @emph{Standard}:
6276 Subroutine, function
6278 @item @emph{Syntax}:
6279 @multitable @columnfractions .80
6280 @item @code{CALL LINK(PATH1, PATH2 [, STATUS])}
6281 @item @code{STATUS = LINK(PATH1, PATH2)}
6284 @item @emph{Arguments}:
6285 @multitable @columnfractions .15 .70
6286 @item @var{PATH1} @tab Shall be of default @code{CHARACTER} type.
6287 @item @var{PATH2} @tab Shall be of default @code{CHARACTER} type.
6288 @item @var{STATUS} @tab (Optional) Shall be of default @code{INTEGER} type.
6291 @item @emph{See also}:
6292 @ref{SYMLNK}, @ref{UNLINK}
6298 @section @code{LLE} --- Lexical less than or equal
6300 @cindex lexical comparison of strings
6301 @cindex string, comparison
6304 @item @emph{Description}:
6305 Determines whether one string is lexically less than or equal to another
6306 string, where the two strings are interpreted as containing ASCII
6307 character codes. If the String A and String B are not the same length,
6308 the shorter is compared as if spaces were appended to it to form a value
6309 that has the same length as the longer.
6311 In general, the lexical comparison intrinsics @code{LGE}, @code{LGT},
6312 @code{LLE}, and @code{LLT} differ from the corresponding intrinsic
6313 operators @code{.GE.}, @code{.GT.}, @code{.LE.}, and @code{.LT.}, in
6314 that the latter use the processor's character ordering (which is not
6315 ASCII on some targets), whereas the former always use the ASCII
6318 @item @emph{Standard}:
6324 @item @emph{Syntax}:
6325 @code{RESULT = LLE(STRING_A, STRING_B)}
6327 @item @emph{Arguments}:
6328 @multitable @columnfractions .15 .70
6329 @item @var{STRING_A} @tab Shall be of default @code{CHARACTER} type.
6330 @item @var{STRING_B} @tab Shall be of default @code{CHARACTER} type.
6333 @item @emph{Return value}:
6334 Returns @code{.TRUE.} if @code{STRING_A <= STRING_B}, and @code{.FALSE.}
6335 otherwise, based on the ASCII ordering.
6337 @item @emph{See also}:
6338 @ref{LGE}, @ref{LGT}, @ref{LLT}
6344 @section @code{LLT} --- Lexical less than
6346 @cindex lexical comparison of strings
6347 @cindex string, comparison
6350 @item @emph{Description}:
6351 Determines whether one string is lexically less than another string,
6352 where the two strings are interpreted as containing ASCII character
6353 codes. If the String A and String B are not the same length, the
6354 shorter is compared as if spaces were appended to it to form a value
6355 that has the same length as the longer.
6357 In general, the lexical comparison intrinsics @code{LGE}, @code{LGT},
6358 @code{LLE}, and @code{LLT} differ from the corresponding intrinsic
6359 operators @code{.GE.}, @code{.GT.}, @code{.LE.}, and @code{.LT.}, in
6360 that the latter use the processor's character ordering (which is not
6361 ASCII on some targets), whereas the former always use the ASCII
6364 @item @emph{Standard}:
6370 @item @emph{Syntax}:
6371 @code{RESULT = LLT(STRING_A, STRING_B)}
6373 @item @emph{Arguments}:
6374 @multitable @columnfractions .15 .70
6375 @item @var{STRING_A} @tab Shall be of default @code{CHARACTER} type.
6376 @item @var{STRING_B} @tab Shall be of default @code{CHARACTER} type.
6379 @item @emph{Return value}:
6380 Returns @code{.TRUE.} if @code{STRING_A < STRING_B}, and @code{.FALSE.}
6381 otherwise, based on the ASCII ordering.
6383 @item @emph{See also}:
6384 @ref{LGE}, @ref{LGT}, @ref{LLE}
6390 @section @code{LNBLNK} --- Index of the last non-blank character in a string
6392 @cindex string, find non-blank character
6395 @item @emph{Description}:
6396 Returns the length of a character string, ignoring any trailing blanks.
6397 This is identical to the standard @code{LEN_TRIM} intrinsic, and is only
6398 included for backwards compatibility.
6400 @item @emph{Standard}:
6406 @item @emph{Syntax}:
6407 @code{RESULT = LNBLNK(STRING)}
6409 @item @emph{Arguments}:
6410 @multitable @columnfractions .15 .70
6411 @item @var{STRING} @tab Shall be a scalar of type @code{CHARACTER(*)},
6412 with @code{INTENT(IN)}
6415 @item @emph{Return value}:
6416 The return value is of @code{INTEGER(kind=4)} type.
6418 @item @emph{See also}:
6419 @ref{INDEX}, @ref{LEN_TRIM}
6425 @section @code{LOC} --- Returns the address of a variable
6427 @cindex location of a variable in memory
6430 @item @emph{Description}:
6431 @code{LOC(X)} returns the address of @var{X} as an integer.
6433 @item @emph{Standard}:
6439 @item @emph{Syntax}:
6440 @code{RESULT = LOC(X)}
6442 @item @emph{Arguments}:
6443 @multitable @columnfractions .15 .70
6444 @item @var{X} @tab Variable of any type.
6447 @item @emph{Return value}:
6448 The return value is of type @code{INTEGER}, with a @code{KIND}
6449 corresponding to the size (in bytes) of a memory address on the target
6452 @item @emph{Example}:
6459 end program test_loc
6466 @section @code{LOG} --- Logarithm function
6473 @cindex exponential function, inverse
6474 @cindex logarithmic function
6477 @item @emph{Description}:
6478 @code{LOG(X)} computes the logarithm of @var{X}.
6480 @item @emph{Standard}:
6486 @item @emph{Syntax}:
6487 @code{RESULT = LOG(X)}
6489 @item @emph{Arguments}:
6490 @multitable @columnfractions .15 .70
6491 @item @var{X} @tab The type shall be @code{REAL(*)} or
6495 @item @emph{Return value}:
6496 The return value is of type @code{REAL(*)} or @code{COMPLEX(*)}.
6497 The kind type parameter is the same as @var{X}.
6499 @item @emph{Example}:
6502 real(8) :: x = 1.0_8
6503 complex :: z = (1.0, 2.0)
6506 end program test_log
6509 @item @emph{Specific names}:
6510 @multitable @columnfractions .20 .20 .20 .25
6511 @item Name @tab Argument @tab Return type @tab Standard
6512 @item @code{ALOG(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab f95, gnu
6513 @item @code{DLOG(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab f95, gnu
6514 @item @code{CLOG(X)} @tab @code{COMPLEX(4) X} @tab @code{COMPLEX(4)} @tab f95, gnu
6515 @item @code{ZLOG(X)} @tab @code{COMPLEX(8) X} @tab @code{COMPLEX(8)} @tab f95, gnu
6516 @item @code{CDLOG(X)} @tab @code{COMPLEX(8) X} @tab @code{COMPLEX(8)} @tab f95, gnu
6523 @section @code{LOG10} --- Base 10 logarithm function
6527 @cindex exponential function, inverse
6528 @cindex logarithmic function
6531 @item @emph{Description}:
6532 @code{LOG10(X)} computes the base 10 logarithm of @var{X}.
6534 @item @emph{Standard}:
6540 @item @emph{Syntax}:
6541 @code{RESULT = LOG10(X)}
6543 @item @emph{Arguments}:
6544 @multitable @columnfractions .15 .70
6545 @item @var{X} @tab The type shall be @code{REAL(*)}.
6548 @item @emph{Return value}:
6549 The return value is of type @code{REAL(*)} or @code{COMPLEX(*)}.
6550 The kind type parameter is the same as @var{X}.
6552 @item @emph{Example}:
6555 real(8) :: x = 10.0_8
6557 end program test_log10
6560 @item @emph{Specific names}:
6561 @multitable @columnfractions .20 .20 .20 .25
6562 @item Name @tab Argument @tab Return type @tab Standard
6563 @item @code{ALOG10(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab F95 and later
6564 @item @code{DLOG10(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab F95 and later
6571 @section @code{LOGICAL} --- Convert to logical type
6573 @cindex conversion, to logical
6576 @item @emph{Description}:
6577 Converts one kind of @code{LOGICAL} variable to another.
6579 @item @emph{Standard}:
6585 @item @emph{Syntax}:
6586 @code{RESULT = LOGICAL(L [, KIND])}
6588 @item @emph{Arguments}:
6589 @multitable @columnfractions .15 .70
6590 @item @var{L} @tab The type shall be @code{LOGICAL(*)}.
6591 @item @var{KIND} @tab (Optional) An @code{INTEGER(*)} initialization
6592 expression indicating the kind parameter of
6596 @item @emph{Return value}:
6597 The return value is a @code{LOGICAL} value equal to @var{L}, with a
6598 kind corresponding to @var{KIND}, or of the default logical kind if
6599 @var{KIND} is not given.
6601 @item @emph{See also}:
6602 @ref{INT}, @ref{REAL}, @ref{CMPLX}
6608 @section @code{LONG} --- Convert to integer type
6610 @cindex conversion, to integer
6613 @item @emph{Description}:
6614 Convert to a @code{KIND=4} integer type, which is the same size as a C
6615 @code{long} integer. This is equivalent to the standard @code{INT}
6616 intrinsic with an optional argument of @code{KIND=4}, and is only
6617 included for backwards compatibility.
6619 @item @emph{Standard}:
6625 @item @emph{Syntax}:
6626 @code{RESULT = LONG(A)}
6628 @item @emph{Arguments}:
6629 @multitable @columnfractions .15 .70
6630 @item @var{A} @tab Shall be of type @code{INTEGER(*)},
6631 @code{REAL(*)}, or @code{COMPLEX(*)}.
6634 @item @emph{Return value}:
6635 The return value is a @code{INTEGER(4)} variable.
6637 @item @emph{See also}:
6638 @ref{INT}, @ref{INT2}, @ref{INT8}
6644 @section @code{LSHIFT} --- Left shift bits
6646 @cindex bits, shift left
6649 @item @emph{Description}:
6650 @code{LSHIFT} returns a value corresponding to @var{I} with all of the
6651 bits shifted left by @var{SHIFT} places. If the absolute value of
6652 @var{SHIFT} is greater than @code{BIT_SIZE(I)}, the value is undefined.
6653 Bits shifted out from the left end are lost; zeros are shifted in from
6656 This function has been superseded by the @code{ISHFT} intrinsic, which
6657 is standard in Fortran 95 and later.
6659 @item @emph{Standard}:
6665 @item @emph{Syntax}:
6666 @code{RESULT = LSHIFT(I, SHIFT)}
6668 @item @emph{Arguments}:
6669 @multitable @columnfractions .15 .70
6670 @item @var{I} @tab The type shall be @code{INTEGER(*)}.
6671 @item @var{SHIFT} @tab The type shall be @code{INTEGER(*)}.
6674 @item @emph{Return value}:
6675 The return value is of type @code{INTEGER(*)} and of the same kind as
6678 @item @emph{See also}:
6679 @ref{ISHFT}, @ref{ISHFTC}, @ref{RSHIFT}
6686 @section @code{LSTAT} --- Get file status
6688 @cindex file system, file status
6691 @item @emph{Description}:
6692 @code{LSTAT} is identical to @ref{STAT}, except that if path is a symbolic link,
6693 then the link itself is statted, not the file that it refers to.
6695 The elements in @code{BUFF} are the same as described by @ref{STAT}.
6697 This intrinsic is provided in both subroutine and function forms; however,
6698 only one form can be used in any given program unit.
6700 @item @emph{Standard}:
6704 Subroutine, function
6706 @item @emph{Syntax}:
6707 @code{CALL LSTAT(FILE, BUFF [, STATUS])}
6709 @item @emph{Arguments}:
6710 @multitable @columnfractions .15 .70
6711 @item @var{FILE} @tab The type shall be @code{CHARACTER(*)}, a valid path within the file system.
6712 @item @var{BUFF} @tab The type shall be @code{INTEGER(4), DIMENSION(13)}.
6713 @item @var{STATUS} @tab (Optional) status flag of type @code{INTEGER(4)}. Returns 0
6714 on success and a system specific error code otherwise.
6717 @item @emph{Example}:
6718 See @ref{STAT} for an example.
6720 @item @emph{See also}:
6721 To stat an open file: @ref{FSTAT}, to stat a file: @ref{STAT}
6727 @section @code{LTIME} --- Convert time to local time info
6729 @cindex time, conversion to local time info
6732 @item @emph{Description}:
6733 Given a system time value @var{STIME} (as provided by the @code{TIME8()}
6734 intrinsic), fills @var{TARRAY} with values extracted from it appropriate
6735 to the local time zone using @code{localtime(3)}.
6737 @item @emph{Standard}:
6743 @item @emph{Syntax}:
6744 @code{CALL LTIME(STIME, TARRAY)}
6746 @item @emph{Arguments}:
6747 @multitable @columnfractions .15 .70
6748 @item @var{STIME} @tab An @code{INTEGER(*)} scalar expression
6749 corresponding to a system time, with
6751 @item @var{TARRAY} @tab A default @code{INTEGER} array with 9 elements,
6752 with @code{INTENT(OUT)}.
6755 @item @emph{Return value}:
6756 The elements of @var{TARRAY} are assigned as follows:
6758 @item Seconds after the minute, range 0--59 or 0--61 to allow for leap
6760 @item Minutes after the hour, range 0--59
6761 @item Hours past midnight, range 0--23
6762 @item Day of month, range 0--31
6763 @item Number of months since January, range 0--12
6764 @item Years since 1900
6765 @item Number of days since Sunday, range 0--6
6766 @item Days since January 1
6767 @item Daylight savings indicator: positive if daylight savings is in
6768 effect, zero if not, and negative if the information is not
6772 @item @emph{See also}:
6773 @ref{CTIME}, @ref{GMTIME}, @ref{TIME}, @ref{TIME8}
6780 @section @code{MALLOC} --- Allocate dynamic memory
6782 @cindex pointer, cray
6785 @item @emph{Description}:
6786 @code{MALLOC(SIZE)} allocates @var{SIZE} bytes of dynamic memory and
6787 returns the address of the allocated memory. The @code{MALLOC} intrinsic
6788 is an extension intended to be used with Cray pointers, and is provided
6789 in GNU Fortran to allow the user to compile legacy code. For new code
6790 using Fortran 95 pointers, the memory allocation intrinsic is
6793 @item @emph{Standard}:
6799 @item @emph{Syntax}:
6800 @code{PTR = MALLOC(SIZE)}
6802 @item @emph{Arguments}:
6803 @multitable @columnfractions .15 .70
6804 @item @var{SIZE} @tab The type shall be @code{INTEGER(*)}.
6807 @item @emph{Return value}:
6808 The return value is of type @code{INTEGER(K)}, with @var{K} such that
6809 variables of type @code{INTEGER(K)} have the same size as
6810 C pointers (@code{sizeof(void *)}).
6812 @item @emph{Example}:
6813 The following example demonstrates the use of @code{MALLOC} and
6814 @code{FREE} with Cray pointers. This example is intended to run on
6815 32-bit systems, where the default integer kind is suitable to store
6816 pointers; on 64-bit systems, ptr_x would need to be declared as
6817 @code{integer(kind=8)}.
6826 ptr_x = malloc(20*8)
6828 x(i) = sqrt(1.0d0 / i)
6836 end program test_malloc
6839 @item @emph{See also}:
6846 @section @code{MATMUL} --- matrix multiplication
6848 @cindex matrix multiplication
6849 @cindex product, matrix
6852 @item @emph{Description}:
6853 Performs a matrix multiplication on numeric or logical arguments.
6855 @item @emph{Standard}:
6859 Transformational function
6861 @item @emph{Syntax}:
6862 @code{RESULT = MATMUL(MATRIX_A, MATRIX_B)}
6864 @item @emph{Arguments}:
6865 @multitable @columnfractions .15 .70
6866 @item @var{MATRIX_A} @tab An array of @code{INTEGER(*)},
6867 @code{REAL(*)}, @code{COMPLEX(*)}, or
6868 @code{LOGICAL(*)} type, with a rank of
6870 @item @var{MATRIX_B} @tab An array of @code{INTEGER(*)},
6871 @code{REAL(*)}, or @code{COMPLEX(*)} type if
6872 @var{MATRIX_A} is of a numeric type;
6873 otherwise, an array of @code{LOGICAL(*)}
6874 type. The rank shall be one or two, and the
6875 first (or only) dimension of @var{MATRIX_B}
6876 shall be equal to the last (or only)
6877 dimension of @var{MATRIX_A}.
6880 @item @emph{Return value}:
6881 The matrix product of @var{MATRIX_A} and @var{MATRIX_B}. The type and
6882 kind of the result follow the usual type and kind promotion rules, as
6883 for the @code{*} or @code{.AND.} operators.
6885 @item @emph{See also}:
6891 @section @code{MAX} --- Maximum value of an argument list
6898 @cindex maximum value
6901 @item @emph{Description}:
6902 Returns the argument with the largest (most positive) value.
6904 @item @emph{Standard}:
6910 @item @emph{Syntax}:
6911 @code{RESULT = MAX(A1, A2 [, A3 [, ...]])}
6913 @item @emph{Arguments}:
6914 @multitable @columnfractions .15 .70
6915 @item @var{A1} @tab The type shall be @code{INTEGER(*)} or
6917 @item @var{A2}, @var{A3}, ... @tab An expression of the same type and kind
6918 as @var{A1}. (As a GNU extension,
6919 arguments of different kinds are
6923 @item @emph{Return value}:
6924 The return value corresponds to the maximum value among the arguments,
6925 and has the same type and kind as the first argument.
6927 @item @emph{Specific names}:
6928 @multitable @columnfractions .20 .20 .20 .25
6929 @item Name @tab Argument @tab Return type @tab Standard
6930 @item @code{MAX0(I)} @tab @code{INTEGER(4) I} @tab @code{INTEGER(4)} @tab F77 and later
6931 @item @code{AMAX0(I)} @tab @code{INTEGER(4) I} @tab @code{REAL(MAX(X))} @tab F77 and later
6932 @item @code{MAX1(X)} @tab @code{REAL(*) X} @tab @code{INT(MAX(X))} @tab F77 and later
6933 @item @code{AMAX1(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab F77 and later
6934 @item @code{DMAX1(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab F77 and later
6937 @item @emph{See also}:
6938 @ref{MAXLOC} @ref{MAXVAL}, @ref{MIN}
6945 @section @code{MAXEXPONENT} --- Maximum exponent of a real kind
6946 @fnindex MAXEXPONENT
6947 @cindex model representation, maximum exponent
6950 @item @emph{Description}:
6951 @code{MAXEXPONENT(X)} returns the maximum exponent in the model of the
6954 @item @emph{Standard}:
6960 @item @emph{Syntax}:
6961 @code{RESULT = MAXEXPONENT(X)}
6963 @item @emph{Arguments}:
6964 @multitable @columnfractions .15 .70
6965 @item @var{X} @tab Shall be of type @code{REAL}.
6968 @item @emph{Return value}:
6969 The return value is of type @code{INTEGER} and of the default integer
6972 @item @emph{Example}:
6978 print *, minexponent(x), maxexponent(x)
6979 print *, minexponent(y), maxexponent(y)
6980 end program exponents
6987 @section @code{MAXLOC} --- Location of the maximum value within an array
6989 @cindex array, location of maximum element
6992 @item @emph{Description}:
6993 Determines the location of the element in the array with the maximum
6994 value, or, if the @var{DIM} argument is supplied, determines the
6995 locations of the maximum element along each row of the array in the
6996 @var{DIM} direction. If @var{MASK} is present, only the elements for
6997 which @var{MASK} is @code{.TRUE.} are considered. If more than one
6998 element in the array has the maximum value, the location returned is
6999 that of the first such element in array element order. If the array has
7000 zero size, or all of the elements of @var{MASK} are @code{.FALSE.}, then
7001 the result is an array of zeroes. Similarly, if @var{DIM} is supplied
7002 and all of the elements of @var{MASK} along a given row are zero, the
7003 result value for that row is zero.
7005 @item @emph{Standard}:
7009 Transformational function
7011 @item @emph{Syntax}:
7012 @multitable @columnfractions .80
7013 @item @code{RESULT = MAXLOC(ARRAY, DIM [, MASK])}
7014 @item @code{RESULT = MAXLOC(ARRAY [, MASK])}
7017 @item @emph{Arguments}:
7018 @multitable @columnfractions .15 .70
7019 @item @var{ARRAY} @tab Shall be an array of type @code{INTEGER(*)},
7020 @code{REAL(*)}, or @code{CHARACTER(*)}.
7021 @item @var{DIM} @tab (Optional) Shall be a scalar of type
7022 @code{INTEGER(*)}, with a value between one
7023 and the rank of @var{ARRAY}, inclusive. It
7024 may not be an optional dummy argument.
7025 @item @var{MASK} @tab Shall be an array of type @code{LOGICAL(*)},
7026 and conformable with @var{ARRAY}.
7029 @item @emph{Return value}:
7030 If @var{DIM} is absent, the result is a rank-one array with a length
7031 equal to the rank of @var{ARRAY}. If @var{DIM} is present, the result
7032 is an array with a rank one less than the rank of @var{ARRAY}, and a
7033 size corresponding to the size of @var{ARRAY} with the @var{DIM}
7034 dimension removed. If @var{DIM} is present and @var{ARRAY} has a rank
7035 of one, the result is a scalar. In all cases, the result is of default
7036 @code{INTEGER} type.
7038 @item @emph{See also}:
7039 @ref{MAX}, @ref{MAXVAL}
7046 @section @code{MAXVAL} --- Maximum value of an array
7048 @cindex array, maximum value
7049 @cindex maximum value
7052 @item @emph{Description}:
7053 Determines the maximum value of the elements in an array value, or, if
7054 the @var{DIM} argument is supplied, determines the maximum value along
7055 each row of the array in the @var{DIM} direction. If @var{MASK} is
7056 present, only the elements for which @var{MASK} is @code{.TRUE.} are
7057 considered. If the array has zero size, or all of the elements of
7058 @var{MASK} are @code{.FALSE.}, then the result is the most negative
7059 number of the type and kind of @var{ARRAY} if @var{ARRAY} is numeric, or
7060 a string of nulls if @var{ARRAY} is of character type.
7062 @item @emph{Standard}:
7066 Transformational function
7068 @item @emph{Syntax}:
7069 @multitable @columnfractions .80
7070 @item @code{RESULT = MAXVAL(ARRAY, DIM [, MASK])}
7071 @item @code{RESULT = MAXVAL(ARRAY [, MASK])}
7074 @item @emph{Arguments}:
7075 @multitable @columnfractions .15 .70
7076 @item @var{ARRAY} @tab Shall be an array of type @code{INTEGER(*)},
7077 @code{REAL(*)}, or @code{CHARACTER(*)}.
7078 @item @var{DIM} @tab (Optional) Shall be a scalar of type
7079 @code{INTEGER(*)}, with a value between one
7080 and the rank of @var{ARRAY}, inclusive. It
7081 may not be an optional dummy argument.
7082 @item @var{MASK} @tab Shall be an array of type @code{LOGICAL(*)},
7083 and conformable with @var{ARRAY}.
7086 @item @emph{Return value}:
7087 If @var{DIM} is absent, or if @var{ARRAY} has a rank of one, the result
7088 is a scalar. If @var{DIM} is present, the result is an array with a
7089 rank one less than the rank of @var{ARRAY}, and a size corresponding to
7090 the size of @var{ARRAY} with the @var{DIM} dimension removed. In all
7091 cases, the result is of the same type and kind as @var{ARRAY}.
7093 @item @emph{See also}:
7094 @ref{MAX}, @ref{MAXLOC}
7100 @section @code{MCLOCK} --- Time function
7102 @cindex time, clock ticks
7106 @item @emph{Description}:
7107 Returns the number of clock ticks since the start of the process, based
7108 on the UNIX function @code{clock(3)}.
7110 This intrinsic is not fully portable, such as to systems with 32-bit
7111 @code{INTEGER} types but supporting times wider than 32 bits. Therefore,
7112 the values returned by this intrinsic might be, or become, negative, or
7113 numerically less than previous values, during a single run of the
7116 @item @emph{Standard}:
7122 @item @emph{Syntax}:
7123 @code{RESULT = MCLOCK()}
7125 @item @emph{Return value}:
7126 The return value is a scalar of type @code{INTEGER(4)}, equal to the
7127 number of clock ticks since the start of the process, or @code{-1} if
7128 the system does not support @code{clock(3)}.
7130 @item @emph{See also}:
7131 @ref{CTIME}, @ref{GMTIME}, @ref{LTIME}, @ref{MCLOCK}, @ref{TIME}
7138 @section @code{MCLOCK8} --- Time function (64-bit)
7140 @cindex time, clock ticks
7144 @item @emph{Description}:
7145 Returns the number of clock ticks since the start of the process, based
7146 on the UNIX function @code{clock(3)}.
7148 @emph{Warning:} this intrinsic does not increase the range of the timing
7149 values over that returned by @code{clock(3)}. On a system with a 32-bit
7150 @code{clock(3)}, @code{MCLOCK8()} will return a 32-bit value, even though
7151 it is converted to a 64-bit @code{INTEGER(8)} value. That means
7152 overflows of the 32-bit value can still occur. Therefore, the values
7153 returned by this intrinsic might be or become negative or numerically
7154 less than previous values during a single run of the compiled program.
7156 @item @emph{Standard}:
7162 @item @emph{Syntax}:
7163 @code{RESULT = MCLOCK8()}
7165 @item @emph{Return value}:
7166 The return value is a scalar of type @code{INTEGER(8)}, equal to the
7167 number of clock ticks since the start of the process, or @code{-1} if
7168 the system does not support @code{clock(3)}.
7170 @item @emph{See also}:
7171 @ref{CTIME}, @ref{GMTIME}, @ref{LTIME}, @ref{MCLOCK}, @ref{TIME8}
7178 @section @code{MERGE} --- Merge variables
7180 @cindex array, merge arrays
7181 @cindex array, combine arrays
7184 @item @emph{Description}:
7185 Select values from two arrays according to a logical mask. The result
7186 is equal to @var{TSOURCE} if @var{MASK} is @code{.TRUE.}, or equal to
7187 @var{FSOURCE} if it is @code{.FALSE.}.
7189 @item @emph{Standard}:
7195 @item @emph{Syntax}:
7196 @code{RESULT = MERGE(TSOURCE, FSOURCE, MASK)}
7198 @item @emph{Arguments}:
7199 @multitable @columnfractions .15 .70
7200 @item @var{TSOURCE} @tab May be of any type.
7201 @item @var{FSOURCE} @tab Shall be of the same type and type parameters
7203 @item @var{MASK} @tab Shall be of type @code{LOGICAL(*)}.
7206 @item @emph{Return value}:
7207 The result is of the same type and type parameters as @var{TSOURCE}.
7214 @section @code{MIN} --- Minimum value of an argument list
7221 @cindex minimum value
7224 @item @emph{Description}:
7225 Returns the argument with the smallest (most negative) value.
7227 @item @emph{Standard}:
7233 @item @emph{Syntax}:
7234 @code{RESULT = MIN(A1, A2 [, A3, ...])}
7236 @item @emph{Arguments}:
7237 @multitable @columnfractions .15 .70
7238 @item @var{A1} @tab The type shall be @code{INTEGER(*)} or
7240 @item @var{A2}, @var{A3}, ... @tab An expression of the same type and kind
7241 as @var{A1}. (As a GNU extension,
7242 arguments of different kinds are
7246 @item @emph{Return value}:
7247 The return value corresponds to the maximum value among the arguments,
7248 and has the same type and kind as the first argument.
7250 @item @emph{Specific names}:
7251 @multitable @columnfractions .20 .20 .20 .25
7252 @item Name @tab Argument @tab Return type @tab Standard
7253 @item @code{MIN0(I)} @tab @code{INTEGER(4) I} @tab @code{INTEGER(4)} @tab F77 and later
7254 @item @code{AMIN0(I)} @tab @code{INTEGER(4) I} @tab @code{REAL(MIN(X))} @tab F77 and later
7255 @item @code{MIN1(X)} @tab @code{REAL(*) X} @tab @code{INT(MIN(X))} @tab F77 and later
7256 @item @code{AMIN1(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab F77 and later
7257 @item @code{DMIN1(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab F77 and later
7260 @item @emph{See also}:
7261 @ref{MAX}, @ref{MINLOC}, @ref{MINVAL}
7267 @section @code{MINEXPONENT} --- Minimum exponent of a real kind
7268 @fnindex MINEXPONENT
7269 @cindex model representation, minimum exponent
7272 @item @emph{Description}:
7273 @code{MINEXPONENT(X)} returns the minimum exponent in the model of the
7276 @item @emph{Standard}:
7282 @item @emph{Syntax}:
7283 @code{RESULT = MINEXPONENT(X)}
7285 @item @emph{Arguments}:
7286 @multitable @columnfractions .15 .70
7287 @item @var{X} @tab Shall be of type @code{REAL}.
7290 @item @emph{Return value}:
7291 The return value is of type @code{INTEGER} and of the default integer
7294 @item @emph{Example}:
7295 See @code{MAXEXPONENT} for an example.
7301 @section @code{MINLOC} --- Location of the minimum value within an array
7303 @cindex array, location of minimum element
7306 @item @emph{Description}:
7307 Determines the location of the element in the array with the minimum
7308 value, or, if the @var{DIM} argument is supplied, determines the
7309 locations of the minimum element along each row of the array in the
7310 @var{DIM} direction. If @var{MASK} is present, only the elements for
7311 which @var{MASK} is @code{.TRUE.} are considered. If more than one
7312 element in the array has the minimum value, the location returned is
7313 that of the first such element in array element order. If the array has
7314 zero size, or all of the elements of @var{MASK} are @code{.FALSE.}, then
7315 the result is an array of zeroes. Similarly, if @var{DIM} is supplied
7316 and all of the elements of @var{MASK} along a given row are zero, the
7317 result value for that row is zero.
7319 @item @emph{Standard}:
7323 Transformational function
7325 @item @emph{Syntax}:
7326 @multitable @columnfractions .80
7327 @item @code{RESULT = MINLOC(ARRAY, DIM [, MASK])}
7328 @item @code{RESULT = MINLOC(ARRAY [, MASK])}
7331 @item @emph{Arguments}:
7332 @multitable @columnfractions .15 .70
7333 @item @var{ARRAY} @tab Shall be an array of type @code{INTEGER(*)},
7334 @code{REAL(*)}, or @code{CHARACTER(*)}.
7335 @item @var{DIM} @tab (Optional) Shall be a scalar of type
7336 @code{INTEGER(*)}, with a value between one
7337 and the rank of @var{ARRAY}, inclusive. It
7338 may not be an optional dummy argument.
7339 @item @var{MASK} @tab Shall be an array of type @code{LOGICAL(*)},
7340 and conformable with @var{ARRAY}.
7343 @item @emph{Return value}:
7344 If @var{DIM} is absent, the result is a rank-one array with a length
7345 equal to the rank of @var{ARRAY}. If @var{DIM} is present, the result
7346 is an array with a rank one less than the rank of @var{ARRAY}, and a
7347 size corresponding to the size of @var{ARRAY} with the @var{DIM}
7348 dimension removed. If @var{DIM} is present and @var{ARRAY} has a rank
7349 of one, the result is a scalar. In all cases, the result is of default
7350 @code{INTEGER} type.
7352 @item @emph{See also}:
7353 @ref{MIN}, @ref{MINVAL}
7360 @section @code{MINVAL} --- Minimum value of an array
7362 @cindex array, minimum value
7363 @cindex minimum value
7366 @item @emph{Description}:
7367 Determines the minimum value of the elements in an array value, or, if
7368 the @var{DIM} argument is supplied, determines the minimum value along
7369 each row of the array in the @var{DIM} direction. If @var{MASK} is
7370 present, only the elements for which @var{MASK} is @code{.TRUE.} are
7371 considered. If the array has zero size, or all of the elements of
7372 @var{MASK} are @code{.FALSE.}, then the result is @code{HUGE(ARRAY)} if
7373 @var{ARRAY} is numeric, or a string of @code{CHAR(255)} characters if
7374 @var{ARRAY} is of character type.
7376 @item @emph{Standard}:
7380 Transformational function
7382 @item @emph{Syntax}:
7383 @multitable @columnfractions .80
7384 @item @code{RESULT = MINVAL(ARRAY, DIM [, MASK])}
7385 @item @code{RESULT = MINVAL(ARRAY [, MASK])}
7388 @item @emph{Arguments}:
7389 @multitable @columnfractions .15 .70
7390 @item @var{ARRAY} @tab Shall be an array of type @code{INTEGER(*)},
7391 @code{REAL(*)}, or @code{CHARACTER(*)}.
7392 @item @var{DIM} @tab (Optional) Shall be a scalar of type
7393 @code{INTEGER(*)}, with a value between one
7394 and the rank of @var{ARRAY}, inclusive. It
7395 may not be an optional dummy argument.
7396 @item @var{MASK} @tab Shall be an array of type @code{LOGICAL(*)},
7397 and conformable with @var{ARRAY}.
7400 @item @emph{Return value}:
7401 If @var{DIM} is absent, or if @var{ARRAY} has a rank of one, the result
7402 is a scalar. If @var{DIM} is present, the result is an array with a
7403 rank one less than the rank of @var{ARRAY}, and a size corresponding to
7404 the size of @var{ARRAY} with the @var{DIM} dimension removed. In all
7405 cases, the result is of the same type and kind as @var{ARRAY}.
7407 @item @emph{See also}:
7408 @ref{MIN}, @ref{MINLOC}
7415 @section @code{MOD} --- Remainder function
7420 @cindex division, remainder
7423 @item @emph{Description}:
7424 @code{MOD(A,P)} computes the remainder of the division of A by P. It is
7425 calculated as @code{A - (INT(A/P) * P)}.
7427 @item @emph{Standard}:
7433 @item @emph{Syntax}:
7434 @code{RESULT = MOD(A, P)}
7436 @item @emph{Arguments}:
7437 @multitable @columnfractions .15 .70
7438 @item @var{A} @tab Shall be a scalar of type @code{INTEGER} or @code{REAL}
7439 @item @var{P} @tab Shall be a scalar of the same type as @var{A} and not
7443 @item @emph{Return value}:
7444 The kind of the return value is the result of cross-promoting
7445 the kinds of the arguments.
7447 @item @emph{Example}:
7451 print *, mod(17.5,5.5)
7452 print *, mod(17.5d0,5.5)
7453 print *, mod(17.5,5.5d0)
7456 print *, mod(-17.5,5.5)
7457 print *, mod(-17.5d0,5.5)
7458 print *, mod(-17.5,5.5d0)
7461 print *, mod(17.5,-5.5)
7462 print *, mod(17.5d0,-5.5)
7463 print *, mod(17.5,-5.5d0)
7464 end program test_mod
7467 @item @emph{Specific names}:
7468 @multitable @columnfractions .20 .20 .20 .25
7469 @item Name @tab Arguments @tab Return type @tab Standard
7470 @item @code{AMOD(A,P)} @tab @code{REAL(4)} @tab @code{REAL(4)} @tab F95 and later
7471 @item @code{DMOD(A,P)} @tab @code{REAL(8)} @tab @code{REAL(8)} @tab F95 and later
7478 @section @code{MODULO} --- Modulo function
7481 @cindex division, modulo
7484 @item @emph{Description}:
7485 @code{MODULO(A,P)} computes the @var{A} modulo @var{P}.
7487 @item @emph{Standard}:
7493 @item @emph{Syntax}:
7494 @code{RESULT = MODULO(A, P)}
7496 @item @emph{Arguments}:
7497 @multitable @columnfractions .15 .70
7498 @item @var{A} @tab Shall be a scalar of type @code{INTEGER} or @code{REAL}
7499 @item @var{P} @tab Shall be a scalar of the same type and kind as @var{A}
7502 @item @emph{Return value}:
7503 The type and kind of the result are those of the arguments.
7505 @item If @var{A} and @var{P} are of type @code{INTEGER}:
7506 @code{MODULO(A,P)} has the value @var{R} such that @code{A=Q*P+R}, where
7507 @var{Q} is an integer and @var{R} is between 0 (inclusive) and @var{P}
7509 @item If @var{A} and @var{P} are of type @code{REAL}:
7510 @code{MODULO(A,P)} has the value of @code{A - FLOOR (A / P) * P}.
7512 In all cases, if @var{P} is zero the result is processor-dependent.
7514 @item @emph{Example}:
7517 print *, modulo(17,3)
7518 print *, modulo(17.5,5.5)
7520 print *, modulo(-17,3)
7521 print *, modulo(-17.5,5.5)
7523 print *, modulo(17,-3)
7524 print *, modulo(17.5,-5.5)
7533 @section @code{MOVE_ALLOC} --- Move allocation from one object to another
7535 @cindex moving allocation
7536 @cindex allocation, moving
7539 @item @emph{Description}:
7540 @code{MOVE_ALLOC(SRC, DEST)} moves the allocation from @var{SRC} to
7541 @var{DEST}. @var{SRC} will become deallocated in the process.
7543 @item @emph{Standard}:
7549 @item @emph{Syntax}:
7550 @code{CALL MOVE_ALLOC(SRC, DEST)}
7552 @item @emph{Arguments}:
7553 @multitable @columnfractions .15 .70
7554 @item @var{SRC} @tab @code{ALLOCATABLE}, @code{INTENT(INOUT)}, may be
7555 of any type and kind.
7556 @item @var{DEST} @tab @code{ALLOCATABLE}, @code{INTENT(OUT)}, shall be
7557 of the same type, kind and rank as @var{SRC}
7560 @item @emph{Return value}:
7563 @item @emph{Example}:
7565 program test_move_alloc
7566 integer, allocatable :: a(:), b(:)
7570 call move_alloc(a, b)
7571 print *, allocated(a), allocated(b)
7573 end program test_move_alloc
7580 @section @code{MVBITS} --- Move bits from one integer to another
7585 @item @emph{Description}:
7586 Moves @var{LEN} bits from positions @var{FROMPOS} through
7587 @code{FROMPOS+LEN-1} of @var{FROM} to positions @var{TOPOS} through
7588 @code{TOPOS+LEN-1} of @var{TO}. The portion of argument @var{TO} not
7589 affected by the movement of bits is unchanged. The values of
7590 @code{FROMPOS+LEN-1} and @code{TOPOS+LEN-1} must be less than
7591 @code{BIT_SIZE(FROM)}.
7593 @item @emph{Standard}:
7597 Elemental subroutine
7599 @item @emph{Syntax}:
7600 @code{CALL MVBITS(FROM, FROMPOS, LEN, TO, TOPOS)}
7602 @item @emph{Arguments}:
7603 @multitable @columnfractions .15 .70
7604 @item @var{FROM} @tab The type shall be @code{INTEGER(*)}.
7605 @item @var{FROMPOS} @tab The type shall be @code{INTEGER(*)}.
7606 @item @var{LEN} @tab The type shall be @code{INTEGER(*)}.
7607 @item @var{TO} @tab The type shall be @code{INTEGER(*)}, of the
7608 same kind as @var{FROM}.
7609 @item @var{TOPOS} @tab The type shall be @code{INTEGER(*)}.
7612 @item @emph{See also}:
7613 @ref{IBCLR}, @ref{IBSET}, @ref{IBITS}, @ref{IAND}, @ref{IOR}, @ref{IEOR}
7619 @section @code{NEAREST} --- Nearest representable number
7621 @cindex real number, nearest different
7622 @cindex floating point, nearest different
7625 @item @emph{Description}:
7626 @code{NEAREST(X, S)} returns the processor-representable number nearest
7627 to @code{X} in the direction indicated by the sign of @code{S}.
7629 @item @emph{Standard}:
7635 @item @emph{Syntax}:
7636 @code{RESULT = NEAREST(X, S)}
7638 @item @emph{Arguments}:
7639 @multitable @columnfractions .15 .70
7640 @item @var{X} @tab Shall be of type @code{REAL}.
7641 @item @var{S} @tab (Optional) shall be of type @code{REAL} and
7645 @item @emph{Return value}:
7646 The return value is of the same type as @code{X}. If @code{S} is
7647 positive, @code{NEAREST} returns the processor-representable number
7648 greater than @code{X} and nearest to it. If @code{S} is negative,
7649 @code{NEAREST} returns the processor-representable number smaller than
7650 @code{X} and nearest to it.
7652 @item @emph{Example}:
7654 program test_nearest
7656 x = nearest(42.0, 1.0)
7657 y = nearest(42.0, -1.0)
7658 write (*,"(3(G20.15))") x, y, x - y
7659 end program test_nearest
7666 @section @code{NEW_LINE} --- New line character
7669 @cindex output, newline
7672 @item @emph{Description}:
7673 @code{NEW_LINE(C)} returns the new-line character.
7675 @item @emph{Standard}:
7681 @item @emph{Syntax}:
7682 @code{RESULT = NEW_LINE(C)}
7684 @item @emph{Arguments}:
7685 @multitable @columnfractions .15 .70
7686 @item @var{C} @tab The argument shall be a scalar or array of the
7687 type @code{CHARACTER}.
7690 @item @emph{Return value}:
7691 Returns a @var{CHARACTER} scalar of length one with the new-line character of
7692 the same kind as parameter @var{C}.
7694 @item @emph{Example}:
7698 write(*,'(A)') 'This is record 1.'//NEW_LINE('A')//'This is record 2.'
7706 @section @code{NINT} --- Nearest whole number
7709 @cindex rounding, nearest whole number
7712 @item @emph{Description}:
7713 @code{NINT(X)} rounds its argument to the nearest whole number.
7715 @item @emph{Standard}:
7721 @item @emph{Syntax}:
7722 @code{RESULT = NINT(X)}
7724 @item @emph{Arguments}:
7725 @multitable @columnfractions .15 .70
7726 @item @var{X} @tab The type of the argument shall be @code{REAL}.
7729 @item @emph{Return value}:
7730 Returns @var{A} with the fractional portion of its magnitude eliminated by
7731 rounding to the nearest whole number and with its sign preserved,
7732 converted to an @code{INTEGER} of the default kind.
7734 @item @emph{Example}:
7741 print *, nint(x4), idnint(x8)
7742 end program test_nint
7745 @item @emph{Specific names}:
7746 @multitable @columnfractions .25 .25 .25
7747 @item Name @tab Argument @tab Standard
7748 @item @code{IDNINT(X)} @tab @code{REAL(8)} @tab F95 and later
7751 @item @emph{See also}:
7752 @ref{CEILING}, @ref{FLOOR}
7759 @section @code{NOT} --- Logical negation
7761 @cindex bits, negate
7762 @cindex bitwise logical not
7763 @cindex logical not, bitwise
7766 @item @emph{Description}:
7767 @code{NOT} returns the bitwise boolean inverse of @var{I}.
7769 @item @emph{Standard}:
7775 @item @emph{Syntax}:
7776 @code{RESULT = NOT(I)}
7778 @item @emph{Arguments}:
7779 @multitable @columnfractions .15 .70
7780 @item @var{I} @tab The type shall be @code{INTEGER(*)}.
7783 @item @emph{Return value}:
7784 The return type is @code{INTEGER(*)}, of the same kind as the
7787 @item @emph{See also}:
7788 @ref{IAND}, @ref{IEOR}, @ref{IOR}, @ref{IBITS}, @ref{IBSET}, @ref{IBCLR}
7795 @section @code{NULL} --- Function that returns an disassociated pointer
7797 @cindex pointer, status
7798 @cindex pointer, disassociated
7801 @item @emph{Description}:
7802 Returns a disassociated pointer.
7804 If @var{MOLD} is present, a dissassociated pointer of the same type is
7805 returned, otherwise the type is determined by context.
7807 In Fortran 95, @var{MOLD} is optional. Please note that F2003 includes
7808 cases where it is required.
7810 @item @emph{Standard}:
7814 Transformational function
7816 @item @emph{Syntax}:
7817 @code{PTR => NULL([MOLD])}
7819 @item @emph{Arguments}:
7820 @multitable @columnfractions .15 .70
7821 @item @var{MOLD} @tab (Optional) shall be a pointer of any association
7822 status and of any type.
7825 @item @emph{Return value}:
7826 A disassociated pointer.
7828 @item @emph{Example}:
7830 REAL, POINTER, DIMENSION(:) :: VEC => NULL ()
7833 @item @emph{See also}:
7840 @section @code{OR} --- Bitwise logical OR
7842 @cindex bitwise logical or
7843 @cindex logical or, bitwise
7846 @item @emph{Description}:
7847 Bitwise logical @code{OR}.
7849 This intrinsic routine is provided for backwards compatibility with
7850 GNU Fortran 77. For integer arguments, programmers should consider
7851 the use of the @ref{IOR} intrinsic defined by the Fortran standard.
7853 @item @emph{Standard}:
7859 @item @emph{Syntax}:
7860 @code{RESULT = OR(X, Y)}
7862 @item @emph{Arguments}:
7863 @multitable @columnfractions .15 .70
7864 @item @var{X} @tab The type shall be either @code{INTEGER(*)} or @code{LOGICAL}.
7865 @item @var{Y} @tab The type shall be either @code{INTEGER(*)} or @code{LOGICAL}.
7868 @item @emph{Return value}:
7869 The return type is either @code{INTEGER(*)} or @code{LOGICAL}
7870 after cross-promotion of the arguments.
7872 @item @emph{Example}:
7875 LOGICAL :: T = .TRUE., F = .FALSE.
7877 DATA a / Z'F' /, b / Z'3' /
7879 WRITE (*,*) OR(T, T), OR(T, F), OR(F, T), OR(F, F)
7880 WRITE (*,*) OR(a, b)
7884 @item @emph{See also}:
7885 F95 elemental function: @ref{IOR}
7891 @section @code{PACK} --- Pack an array into an array of rank one
7893 @cindex array, packing
7894 @cindex array, reduce dimension
7895 @cindex array, gather elements
7898 @item @emph{Description}:
7899 Stores the elements of @var{ARRAY} in an array of rank one.
7901 The beginning of the resulting array is made up of elements whose @var{MASK}
7902 equals @code{TRUE}. Afterwards, positions are filled with elements taken from
7905 @item @emph{Standard}:
7909 Transformational function
7911 @item @emph{Syntax}:
7912 @code{RESULT = PACK(ARRAY, MASK[,VECTOR]}
7914 @item @emph{Arguments}:
7915 @multitable @columnfractions .15 .70
7916 @item @var{ARRAY} @tab Shall be an array of any type.
7917 @item @var{MASK} @tab Shall be an array of type @code{LOGICAL} and
7918 of the same size as @var{ARRAY}. Alternatively, it may be a @code{LOGICAL}
7920 @item @var{VECTOR} @tab (Optional) shall be an array of the same type
7921 as @var{ARRAY} and of rank one. If present, the number of elements in
7922 @var{VECTOR} shall be equal to or greater than the number of true elements
7923 in @var{MASK}. If @var{MASK} is scalar, the number of elements in
7924 @var{VECTOR} shall be equal to or greater than the number of elements in
7928 @item @emph{Return value}:
7929 The result is an array of rank one and the same type as that of @var{ARRAY}.
7930 If @var{VECTOR} is present, the result size is that of @var{VECTOR}, the
7931 number of @code{TRUE} values in @var{MASK} otherwise.
7933 @item @emph{Example}:
7934 Gathering nonzero elements from an array:
7938 m = (/ 1, 0, 0, 0, 5, 0 /)
7939 WRITE(*, FMT="(6(I0, ' '))") pack(m, m /= 0) ! "1 5"
7943 Gathering nonzero elements from an array and appending elements from @var{VECTOR}:
7947 m = (/ 1, 0, 0, 2 /)
7948 WRITE(*, FMT="(4(I0, ' '))") pack(m, m /= 0, (/ 0, 0, 3, 4 /)) ! "1 2 3 4"
7952 @item @emph{See also}:
7959 @section @code{PERROR} --- Print system error message
7961 @cindex system, error handling
7964 @item @emph{Description}:
7965 Prints (on the C @code{stderr} stream) a newline-terminated error
7966 message corresponding to the last system error. This is prefixed by
7967 @var{STRING}, a colon and a space. See @code{perror(3)}.
7969 @item @emph{Standard}:
7975 @item @emph{Syntax}:
7976 @code{CALL PERROR(STRING)}
7978 @item @emph{Arguments}:
7979 @multitable @columnfractions .15 .70
7980 @item @var{STRING} @tab A scalar of default @code{CHARACTER} type.
7983 @item @emph{See also}:
7990 @section @code{PRECISION} --- Decimal precision of a real kind
7992 @cindex model representation, precision
7995 @item @emph{Description}:
7996 @code{PRECISION(X)} returns the decimal precision in the model of the
7999 @item @emph{Standard}:
8005 @item @emph{Syntax}:
8006 @code{RESULT = PRECISION(X)}
8008 @item @emph{Arguments}:
8009 @multitable @columnfractions .15 .70
8010 @item @var{X} @tab Shall be of type @code{REAL} or @code{COMPLEX}.
8013 @item @emph{Return value}:
8014 The return value is of type @code{INTEGER} and of the default integer
8017 @item @emph{Example}:
8019 program prec_and_range
8020 real(kind=4) :: x(2)
8021 complex(kind=8) :: y
8023 print *, precision(x), range(x)
8024 print *, precision(y), range(y)
8025 end program prec_and_range
8032 @section @code{PRESENT} --- Determine whether an optional dummy argument is specified
8036 @item @emph{Description}:
8037 Determines whether an optional dummy argument is present.
8039 @item @emph{Standard}:
8045 @item @emph{Syntax}:
8046 @code{RESULT = PRESENT(A)}
8048 @item @emph{Arguments}:
8049 @multitable @columnfractions .15 .70
8050 @item @var{A} @tab May be of any type and may be a pointer, scalar or array
8051 value, or a dummy procedure. It shall be the name of an optional dummy argument
8052 accessible within the current subroutine or function.
8055 @item @emph{Return value}:
8056 Returns either @code{TRUE} if the optional argument @var{A} is present, or
8057 @code{FALSE} otherwise.
8059 @item @emph{Example}:
8061 PROGRAM test_present
8062 WRITE(*,*) f(), f(42) ! "F T"
8064 LOGICAL FUNCTION f(x)
8065 INTEGER, INTENT(IN), OPTIONAL :: x
8075 @section @code{PRODUCT} --- Product of array elements
8077 @cindex array, product
8078 @cindex array, multiply elements
8079 @cindex array, conditionally multiply elements
8080 @cindex multiply array elements
8083 @item @emph{Description}:
8084 Multiplies the elements of @var{ARRAY} along dimension @var{DIM} if
8085 the corresponding element in @var{MASK} is @code{TRUE}.
8087 @item @emph{Standard}:
8091 Transformational function
8093 @item @emph{Syntax}:
8094 @code{RESULT = PRODUCT(ARRAY[, MASK])}
8095 @code{RESULT = PRODUCT(ARRAY, DIM[, MASK])}
8097 @item @emph{Arguments}:
8098 @multitable @columnfractions .15 .70
8099 @item @var{ARRAY} @tab Shall be an array of type @code{INTEGER(*)},
8100 @code{REAL(*)} or @code{COMPLEX(*)}.
8101 @item @var{DIM} @tab (Optional) shall be a scalar of type
8102 @code{INTEGER} with a value in the range from 1 to n, where n
8103 equals the rank of @var{ARRAY}.
8104 @item @var{MASK} @tab (Optional) shall be of type @code{LOGICAL}
8105 and either be a scalar or an array of the same shape as @var{ARRAY}.
8108 @item @emph{Return value}:
8109 The result is of the same type as @var{ARRAY}.
8111 If @var{DIM} is absent, a scalar with the product of all elements in
8112 @var{ARRAY} is returned. Otherwise, an array of rank n-1, where n equals
8113 the rank of @var{ARRAY}, and a shape similar to that of @var{ARRAY} with
8114 dimension @var{DIM} dropped is returned.
8117 @item @emph{Example}:
8119 PROGRAM test_product
8120 INTEGER :: x(5) = (/ 1, 2, 3, 4 ,5 /)
8121 print *, PRODUCT(x) ! all elements, product = 120
8122 print *, PRODUCT(x, MASK=MOD(x, 2)==1) ! odd elements, product = 15
8126 @item @emph{See also}:
8133 @section @code{RADIX} --- Base of a model number
8135 @cindex model representation, base
8136 @cindex model representation, radix
8139 @item @emph{Description}:
8140 @code{RADIX(X)} returns the base of the model representing the entity @var{X}.
8142 @item @emph{Standard}:
8148 @item @emph{Syntax}:
8149 @code{RESULT = RADIX(X)}
8151 @item @emph{Arguments}:
8152 @multitable @columnfractions .15 .70
8153 @item @var{X} @tab Shall be of type @code{INTEGER} or @code{REAL}
8156 @item @emph{Return value}:
8157 The return value is a scalar of type @code{INTEGER} and of the default
8160 @item @emph{Example}:
8163 print *, "The radix for the default integer kind is", radix(0)
8164 print *, "The radix for the default real kind is", radix(0.0)
8165 end program test_radix
8173 @section @code{RAN} --- Real pseudo-random number
8175 @cindex random number generation
8178 @item @emph{Description}:
8179 For compatibility with HP FORTRAN 77/iX, the @code{RAN} intrinsic is
8180 provided as an alias for @code{RAND}. See @ref{RAND} for complete
8183 @item @emph{Standard}:
8189 @item @emph{See also}:
8190 @ref{RAND}, @ref{RANDOM_NUMBER}
8196 @section @code{RAND} --- Real pseudo-random number
8198 @cindex random number generation
8201 @item @emph{Description}:
8202 @code{RAND(FLAG)} returns a pseudo-random number from a uniform
8203 distribution between 0 and 1. If @var{FLAG} is 0, the next number
8204 in the current sequence is returned; if @var{FLAG} is 1, the generator
8205 is restarted by @code{CALL SRAND(0)}; if @var{FLAG} has any other value,
8206 it is used as a new seed with @code{SRAND}.
8208 This intrinsic routine is provided for backwards compatibility with
8209 GNU Fortran 77. It implements a simple modulo generator as provided
8210 by @command{g77}. For new code, one should consider the use of
8211 @ref{RANDOM_NUMBER} as it implements a superior algorithm.
8213 @item @emph{Standard}:
8219 @item @emph{Syntax}:
8220 @code{RESULT = RAND(FLAG)}
8222 @item @emph{Arguments}:
8223 @multitable @columnfractions .15 .70
8224 @item @var{FLAG} @tab Shall be a scalar @code{INTEGER} of kind 4.
8227 @item @emph{Return value}:
8228 The return value is of @code{REAL} type and the default kind.
8230 @item @emph{Example}:
8233 integer,parameter :: seed = 86456
8236 print *, rand(), rand(), rand(), rand()
8237 print *, rand(seed), rand(), rand(), rand()
8238 end program test_rand
8241 @item @emph{See also}:
8242 @ref{SRAND}, @ref{RANDOM_NUMBER}
8249 @section @code{RANDOM_NUMBER} --- Pseudo-random number
8250 @fnindex RANDOM_NUMBER
8251 @cindex random number generation
8254 @item @emph{Description}:
8255 Returns a single pseudorandom number or an array of pseudorandom numbers
8256 from the uniform distribution over the range @math{ 0 \leq x < 1}.
8258 The runtime-library implements George Marsaglia's KISS (Keep It Simple
8259 Stupid) random number generator (RNG). This RNG combines:
8261 @item The congruential generator @math{x(n) = 69069 \cdot x(n-1) + 1327217885}
8262 with a period of @math{2^{32}},
8263 @item A 3-shift shift-register generator with a period of @math{2^{32} - 1},
8264 @item Two 16-bit multiply-with-carry generators with a period of
8265 @math{597273182964842497 > 2^{59}}.
8267 The overall period exceeds @math{2^{123}}.
8269 Please note, this RNG is thread safe if used within OpenMP directives,
8270 i. e. its state will be consistent while called from multiple threads.
8271 However, the KISS generator does not create random numbers in parallel
8272 from multiple sources, but in sequence from a single source. If an
8273 OpenMP-enabled application heavily relies on random numbers, one should
8274 consider employing a dedicated parallel random number generator instead.
8276 @item @emph{Standard}:
8282 @item @emph{Syntax}:
8283 @code{RANDOM_NUMBER(HARVEST)}
8285 @item @emph{Arguments}:
8286 @multitable @columnfractions .15 .70
8287 @item @var{HARVEST} @tab Shall be a scalar or an array of type @code{REAL(*)}.
8290 @item @emph{Example}:
8292 program test_random_number
8294 CALL init_random_seed() ! see example of RANDOM_SEED
8295 CALL RANDOM_NUMBER(r)
8299 @item @emph{See also}:
8306 @section @code{RANDOM_SEED} --- Initialize a pseudo-random number sequence
8307 @fnindex RANDOM_SEED
8308 @cindex random number generation, seeding
8309 @cindex seeding a random number generator
8312 @item @emph{Description}:
8313 Restarts or queries the state of the pseudorandom number generator used by
8314 @code{RANDOM_NUMBER}.
8316 If @code{RANDOM_SEED} is called without arguments, it is initialized to
8317 a default state. The example below shows how to initialize the random
8318 seed based on the system's time.
8320 @item @emph{Standard}:
8326 @item @emph{Syntax}:
8327 @code{CALL RANDOM_SEED(SIZE, PUT, GET)}
8329 @item @emph{Arguments}:
8330 @multitable @columnfractions .15 .70
8331 @item @var{SIZE} @tab (Optional) Shall be a scalar and of type default
8332 @code{INTEGER}, with @code{INTENT(OUT)}. It specifies the minimum size
8333 of the arrays used with the @var{PUT} and @var{GET} arguments.
8334 @item @var{PUT} @tab (Optional) Shall be an array of type default
8335 @code{INTEGER} and rank one. It is @code{INTENT(IN)} and the size of
8336 the array must be larger than or equal to the number returned by the
8337 @var{SIZE} argument.
8338 @item @var{GET} @tab (Optional) Shall be an array of type default
8339 @code{INTEGER} and rank one. It is @code{INTENT(OUT)} and the size
8340 of the array must be larger than or equal to the number returned by
8341 the @var{SIZE} argument.
8344 @item @emph{Example}:
8346 SUBROUTINE init_random_seed()
8347 INTEGER :: i, n, clock
8348 INTEGER, DIMENSION(:), ALLOCATABLE :: seed
8350 CALL RANDOM_SEED(size = n)
8353 CALL SYSTEM_CLOCK(COUNT=clock)
8355 seed = clock + 37 * (/ (i - 1, i = 1, n) /)
8356 CALL RANDOM_SEED(PUT = seed)
8362 @item @emph{See also}:
8369 @section @code{RANGE} --- Decimal exponent range of a real kind
8371 @cindex model representation, range
8374 @item @emph{Description}:
8375 @code{RANGE(X)} returns the decimal exponent range in the model of the
8378 @item @emph{Standard}:
8384 @item @emph{Syntax}:
8385 @code{RESULT = RANGE(X)}
8387 @item @emph{Arguments}:
8388 @multitable @columnfractions .15 .70
8389 @item @var{X} @tab Shall be of type @code{REAL} or @code{COMPLEX}.
8392 @item @emph{Return value}:
8393 The return value is of type @code{INTEGER} and of the default integer
8396 @item @emph{Example}:
8397 See @code{PRECISION} for an example.
8403 @section @code{REAL} --- Convert to real type
8406 @cindex conversion, to real
8407 @cindex complex numbers, real part
8410 @item @emph{Description}:
8411 @code{REAL(X [, KIND])} converts its argument @var{X} to a real type. The
8412 @code{REALPART(X)} function is provided for compatibility with @command{g77},
8413 and its use is strongly discouraged.
8415 @item @emph{Standard}:
8421 @item @emph{Syntax}:
8422 @multitable @columnfractions .80
8423 @item @code{RESULT = REAL(X [, KIND])}
8424 @item @code{RESULT = REALPART(Z)}
8427 @item @emph{Arguments}:
8428 @multitable @columnfractions .15 .70
8429 @item @var{X} @tab Shall be @code{INTEGER(*)}, @code{REAL(*)}, or
8431 @item @var{KIND} @tab (Optional) An @code{INTEGER(*)} initialization
8432 expression indicating the kind parameter of
8436 @item @emph{Return value}:
8437 These functions return a @code{REAL(*)} variable or array under
8438 the following rules:
8442 @code{REAL(X)} is converted to a default real type if @var{X} is an
8443 integer or real variable.
8445 @code{REAL(X)} is converted to a real type with the kind type parameter
8446 of @var{X} if @var{X} is a complex variable.
8448 @code{REAL(X, KIND)} is converted to a real type with kind type
8449 parameter @var{KIND} if @var{X} is a complex, integer, or real
8453 @item @emph{Example}:
8456 complex :: x = (1.0, 2.0)
8457 print *, real(x), real(x,8), realpart(x)
8458 end program test_real
8461 @item @emph{See also}:
8462 @ref{DBLE}, @ref{DFLOAT}, @ref{FLOAT}
8469 @section @code{RENAME} --- Rename a file
8471 @cindex file system, rename file
8474 @item @emph{Description}:
8475 Renames a file from file @var{PATH1} to @var{PATH2}. A null
8476 character (@code{CHAR(0)}) can be used to mark the end of the names in
8477 @var{PATH1} and @var{PATH2}; otherwise, trailing blanks in the file
8478 names are ignored. If the @var{STATUS} argument is supplied, it
8479 contains 0 on success or a nonzero error code upon return; see
8482 This intrinsic is provided in both subroutine and function forms;
8483 however, only one form can be used in any given program unit.
8485 @item @emph{Standard}:
8489 Subroutine, function
8491 @item @emph{Syntax}:
8492 @multitable @columnfractions .80
8493 @item @code{CALL RENAME(PATH1, PATH2 [, STATUS])}
8494 @item @code{STATUS = RENAME(PATH1, PATH2)}
8497 @item @emph{Arguments}:
8498 @multitable @columnfractions .15 .70
8499 @item @var{PATH1} @tab Shall be of default @code{CHARACTER} type.
8500 @item @var{PATH2} @tab Shall be of default @code{CHARACTER} type.
8501 @item @var{STATUS} @tab (Optional) Shall be of default @code{INTEGER} type.
8504 @item @emph{See also}:
8512 @section @code{REPEAT} --- Repeated string concatenation
8514 @cindex string, repeat
8515 @cindex string, concatenate
8518 @item @emph{Description}:
8519 Concatenates @var{NCOPIES} copies of a string.
8521 @item @emph{Standard}:
8525 Transformational function
8527 @item @emph{Syntax}:
8528 @code{RESULT = REPEAT(STRING, NCOPIES)}
8530 @item @emph{Arguments}:
8531 @multitable @columnfractions .15 .70
8532 @item @var{STRING} @tab Shall be scalar and of type @code{CHARACTER(*)}.
8533 @item @var{NCOPIES} @tab Shall be scalar and of type @code{INTEGER(*)}.
8536 @item @emph{Return value}:
8537 A new scalar of type @code{CHARACTER} built up from @var{NCOPIES} copies
8540 @item @emph{Example}:
8543 write(*,*) repeat("x", 5) ! "xxxxx"
8551 @section @code{RESHAPE} --- Function to reshape an array
8553 @cindex array, change dimensions
8554 @cindex array, transmogrify
8557 @item @emph{Description}:
8558 Reshapes @var{SOURCE} to correspond to @var{SHAPE}. If necessary,
8559 the new array may be padded with elements from @var{PAD} or permuted
8560 as defined by @var{ORDER}.
8562 @item @emph{Standard}:
8566 Transformational function
8568 @item @emph{Syntax}:
8569 @code{RESULT = RESHAPE(SOURCE, SHAPE[, PAD, ORDER])}
8571 @item @emph{Arguments}:
8572 @multitable @columnfractions .15 .70
8573 @item @var{SOURCE} @tab Shall be an array of any type.
8574 @item @var{SHAPE} @tab Shall be of type @code{INTEGER} and an
8575 array of rank one. Its values must be positive or zero.
8576 @item @var{PAD} @tab (Optional) shall be an array of the same
8577 type as @var{SOURCE}.
8578 @item @var{ORDER} @tab (Optional) shall be of type @code{INTEGER}
8579 and an array of the same shape as @var{SHAPE}. Its values shall
8580 be a permutation of the numbers from 1 to n, where n is the size of
8581 @var{SHAPE}. If @var{ORDER} is absent, the natural ordering shall
8585 @item @emph{Return value}:
8586 The result is an array of shape @var{SHAPE} with the same type as
8589 @item @emph{Example}:
8591 PROGRAM test_reshape
8592 INTEGER, DIMENSION(4) :: x
8593 WRITE(*,*) SHAPE(x) ! prints "4"
8594 WRITE(*,*) SHAPE(RESHAPE(x, (/2, 2/))) ! prints "2 2"
8598 @item @emph{See also}:
8605 @section @code{RRSPACING} --- Reciprocal of the relative spacing
8607 @cindex real number, relative spacing
8608 @cindex floating point, relative spacing
8612 @item @emph{Description}:
8613 @code{RRSPACING(X)} returns the reciprocal of the relative spacing of
8614 model numbers near @var{X}.
8616 @item @emph{Standard}:
8622 @item @emph{Syntax}:
8623 @code{RESULT = RRSPACING(X)}
8625 @item @emph{Arguments}:
8626 @multitable @columnfractions .15 .70
8627 @item @var{X} @tab Shall be of type @code{REAL}.
8630 @item @emph{Return value}:
8631 The return value is of the same type and kind as @var{X}.
8632 The value returned is equal to
8633 @code{ABS(FRACTION(X)) * FLOAT(RADIX(X))**DIGITS(X)}.
8635 @item @emph{See also}:
8642 @section @code{RSHIFT} --- Right shift bits
8644 @cindex bits, shift right
8647 @item @emph{Description}:
8648 @code{RSHIFT} returns a value corresponding to @var{I} with all of the
8649 bits shifted right by @var{SHIFT} places. If the absolute value of
8650 @var{SHIFT} is greater than @code{BIT_SIZE(I)}, the value is undefined.
8651 Bits shifted out from the left end are lost; zeros are shifted in from
8654 This function has been superseded by the @code{ISHFT} intrinsic, which
8655 is standard in Fortran 95 and later.
8657 @item @emph{Standard}:
8663 @item @emph{Syntax}:
8664 @code{RESULT = RSHIFT(I, SHIFT)}
8666 @item @emph{Arguments}:
8667 @multitable @columnfractions .15 .70
8668 @item @var{I} @tab The type shall be @code{INTEGER(*)}.
8669 @item @var{SHIFT} @tab The type shall be @code{INTEGER(*)}.
8672 @item @emph{Return value}:
8673 The return value is of type @code{INTEGER(*)} and of the same kind as
8676 @item @emph{See also}:
8677 @ref{ISHFT}, @ref{ISHFTC}, @ref{LSHIFT}
8684 @section @code{SCALE} --- Scale a real value
8686 @cindex real number, scale
8687 @cindex floating point, scale
8690 @item @emph{Description}:
8691 @code{SCALE(X,I)} returns @code{X * RADIX(X)**I}.
8693 @item @emph{Standard}:
8699 @item @emph{Syntax}:
8700 @code{RESULT = SCALE(X, I)}
8702 @item @emph{Arguments}:
8703 @multitable @columnfractions .15 .70
8704 @item @var{X} @tab The type of the argument shall be a @code{REAL}.
8705 @item @var{I} @tab The type of the argument shall be a @code{INTEGER}.
8708 @item @emph{Return value}:
8709 The return value is of the same type and kind as @var{X}.
8710 Its value is @code{X * RADIX(X)**I}.
8712 @item @emph{Example}:
8715 real :: x = 178.1387e-4
8717 print *, scale(x,i), x*radix(x)**i
8718 end program test_scale
8726 @section @code{SCAN} --- Scan a string for the presence of a set of characters
8728 @cindex string, find subset
8731 @item @emph{Description}:
8732 Scans a @var{STRING} for any of the characters in a @var{SET}
8735 If @var{BACK} is either absent or equals @code{FALSE}, this function
8736 returns the position of the leftmost character of @var{STRING} that is
8737 in @var{SET}. If @var{BACK} equals @code{TRUE}, the rightmost position
8738 is returned. If no character of @var{SET} is found in @var{STRING}, the
8741 @item @emph{Standard}:
8747 @item @emph{Syntax}:
8748 @code{RESULT = SCAN(STRING, SET[, BACK])}
8750 @item @emph{Arguments}:
8751 @multitable @columnfractions .15 .70
8752 @item @var{STRING} @tab Shall be of type @code{CHARACTER(*)}.
8753 @item @var{SET} @tab Shall be of type @code{CHARACTER(*)}.
8754 @item @var{BACK} @tab (Optional) shall be of type @code{LOGICAL}.
8757 @item @emph{Return value}:
8758 The return value is of type @code{INTEGER} and of the default
8761 @item @emph{Example}:
8764 WRITE(*,*) SCAN("FORTRAN", "AO") ! 2, found 'O'
8765 WRITE(*,*) SCAN("FORTRAN", "AO", .TRUE.) ! 6, found 'A'
8766 WRITE(*,*) SCAN("FORTRAN", "C++") ! 0, found none
8770 @item @emph{See also}:
8771 @ref{INDEX}, @ref{VERIFY}
8777 @section @code{SECNDS} --- Time function
8779 @cindex time, elapsed
8780 @cindex elapsed time
8783 @item @emph{Description}:
8784 @code{SECNDS(X)} gets the time in seconds from the real-time system clock.
8785 @var{X} is a reference time, also in seconds. If this is zero, the time in
8786 seconds from midnight is returned. This function is non-standard and its
8789 @item @emph{Standard}:
8795 @item @emph{Syntax}:
8796 @code{RESULT = SECNDS (X)}
8798 @item @emph{Arguments}:
8799 @multitable @columnfractions .15 .70
8800 @item @var{T} @tab Shall be of type @code{REAL(4)}.
8801 @item @var{X} @tab Shall be of type @code{REAL(4)}.
8804 @item @emph{Return value}:
8807 @item @emph{Example}:
8812 print *, secnds (0.0) ! seconds since midnight
8813 t1 = secnds (0.0) ! reference time
8814 do i = 1, 10000000 ! do something
8816 t2 = secnds (t1) ! elapsed time
8817 print *, "Something took ", t2, " seconds."
8818 end program test_secnds
8825 @section @code{SECOND} --- CPU time function
8827 @cindex time, elapsed
8828 @cindex elapsed time
8831 @item @emph{Description}:
8832 Returns a @code{REAL(4)} value representing the elapsed CPU time in
8833 seconds. This provides the same functionality as the standard
8834 @code{CPU_TIME} intrinsic, and is only included for backwards
8837 This intrinsic is provided in both subroutine and function forms;
8838 however, only one form can be used in any given program unit.
8840 @item @emph{Standard}:
8844 Subroutine, function
8846 @item @emph{Syntax}:
8847 @multitable @columnfractions .80
8848 @item @code{CALL SECOND(TIME)}
8849 @item @code{TIME = SECOND()}
8852 @item @emph{Arguments}:
8853 @multitable @columnfractions .15 .70
8854 @item @var{TIME} @tab Shall be of type @code{REAL(4)}.
8857 @item @emph{Return value}:
8858 In either syntax, @var{TIME} is set to the process's current runtime in
8861 @item @emph{See also}:
8868 @node SELECTED_INT_KIND
8869 @section @code{SELECTED_INT_KIND} --- Choose integer kind
8870 @fnindex SELECTED_INT_KIND
8871 @cindex integer kind
8872 @cindex kind, integer
8875 @item @emph{Description}:
8876 @code{SELECTED_INT_KIND(I)} return the kind value of the smallest integer
8877 type that can represent all values ranging from @math{-10^I} (exclusive)
8878 to @math{10^I} (exclusive). If there is no integer kind that accommodates
8879 this range, @code{SELECTED_INT_KIND} returns @math{-1}.
8881 @item @emph{Standard}:
8885 Transformational function
8887 @item @emph{Syntax}:
8888 @code{RESULT = SELECTED_INT_KIND(I)}
8890 @item @emph{Arguments}:
8891 @multitable @columnfractions .15 .70
8892 @item @var{I} @tab Shall be a scalar and of type @code{INTEGER}.
8895 @item @emph{Example}:
8897 program large_integers
8898 integer,parameter :: k5 = selected_int_kind(5)
8899 integer,parameter :: k15 = selected_int_kind(15)
8900 integer(kind=k5) :: i5
8901 integer(kind=k15) :: i15
8903 print *, huge(i5), huge(i15)
8905 ! The following inequalities are always true
8906 print *, huge(i5) >= 10_k5**5-1
8907 print *, huge(i15) >= 10_k15**15-1
8908 end program large_integers
8914 @node SELECTED_REAL_KIND
8915 @section @code{SELECTED_REAL_KIND} --- Choose real kind
8916 @fnindex SELECTED_REAL_KIND
8921 @item @emph{Description}:
8922 @code{SELECTED_REAL_KIND(P,R)} return the kind value of a real data type
8923 with decimal precision greater of at least @code{P} digits and exponent
8924 range greater at least @code{R}.
8926 @item @emph{Standard}:
8930 Transformational function
8932 @item @emph{Syntax}:
8933 @code{RESULT = SELECTED_REAL_KIND(P, R)}
8935 @item @emph{Arguments}:
8936 @multitable @columnfractions .15 .70
8937 @item @var{P} @tab (Optional) shall be a scalar and of type @code{INTEGER}.
8938 @item @var{R} @tab (Optional) shall be a scalar and of type @code{INTEGER}.
8940 At least one argument shall be present.
8942 @item @emph{Return value}:
8944 @code{SELECTED_REAL_KIND} returns the value of the kind type parameter of
8945 a real data type with decimal precision of at least @code{P} digits and a
8946 decimal exponent range of at least @code{R}. If more than one real data
8947 type meet the criteria, the kind of the data type with the smallest
8948 decimal precision is returned. If no real data type matches the criteria,
8951 @item -1 if the processor does not support a real data type with a
8952 precision greater than or equal to @code{P}
8953 @item -2 if the processor does not support a real type with an exponent
8954 range greater than or equal to @code{R}
8955 @item -3 if neither is supported.
8958 @item @emph{Example}:
8961 integer,parameter :: p6 = selected_real_kind(6)
8962 integer,parameter :: p10r100 = selected_real_kind(10,100)
8963 integer,parameter :: r400 = selected_real_kind(r=400)
8965 real(kind=p10r100) :: y
8966 real(kind=r400) :: z
8968 print *, precision(x), range(x)
8969 print *, precision(y), range(y)
8970 print *, precision(z), range(z)
8971 end program real_kinds
8978 @section @code{SET_EXPONENT} --- Set the exponent of the model
8979 @fnindex SET_EXPONENT
8980 @cindex real number, set exponent
8981 @cindex floating point, set exponent
8984 @item @emph{Description}:
8985 @code{SET_EXPONENT(X, I)} returns the real number whose fractional part
8986 is that that of @var{X} and whose exponent part is @var{I}.
8988 @item @emph{Standard}:
8994 @item @emph{Syntax}:
8995 @code{RESULT = SET_EXPONENT(X, I)}
8997 @item @emph{Arguments}:
8998 @multitable @columnfractions .15 .70
8999 @item @var{X} @tab Shall be of type @code{REAL}.
9000 @item @var{I} @tab Shall be of type @code{INTEGER}.
9003 @item @emph{Return value}:
9004 The return value is of the same type and kind as @var{X}.
9005 The real number whose fractional part
9006 is that that of @var{X} and whose exponent part if @var{I} is returned;
9007 it is @code{FRACTION(X) * RADIX(X)**I}.
9009 @item @emph{Example}:
9012 REAL :: x = 178.1387e-4
9014 PRINT *, SET_EXPONENT(x, i), FRACTION(x) * RADIX(x)**i
9023 @section @code{SHAPE} --- Determine the shape of an array
9025 @cindex array, shape
9028 @item @emph{Description}:
9029 Determines the shape of an array.
9031 @item @emph{Standard}:
9037 @item @emph{Syntax}:
9038 @code{RESULT = SHAPE(SOURCE)}
9040 @item @emph{Arguments}:
9041 @multitable @columnfractions .15 .70
9042 @item @var{SOURCE} @tab Shall be an array or scalar of any type.
9043 If @var{SOURCE} is a pointer it must be associated and allocatable
9044 arrays must be allocated.
9047 @item @emph{Return value}:
9048 An @code{INTEGER} array of rank one with as many elements as @var{SOURCE}
9049 has dimensions. The elements of the resulting array correspond to the extend
9050 of @var{SOURCE} along the respective dimensions. If @var{SOURCE} is a scalar,
9051 the result is the rank one array of size zero.
9053 @item @emph{Example}:
9056 INTEGER, DIMENSION(-1:1, -1:2) :: A
9057 WRITE(*,*) SHAPE(A) ! (/ 3, 4 /)
9058 WRITE(*,*) SIZE(SHAPE(42)) ! (/ /)
9062 @item @emph{See also}:
9063 @ref{RESHAPE}, @ref{SIZE}
9069 @section @code{SIGN} --- Sign copying function
9073 @cindex sign copying
9076 @item @emph{Description}:
9077 @code{SIGN(A,B)} returns the value of @var{A} with the sign of @var{B}.
9079 @item @emph{Standard}:
9085 @item @emph{Syntax}:
9086 @code{RESULT = SIGN(A, B)}
9088 @item @emph{Arguments}:
9089 @multitable @columnfractions .15 .70
9090 @item @var{A} @tab Shall be of type @code{INTEGER} or @code{REAL}
9091 @item @var{B} @tab Shall be of the same type and kind as @var{A}
9094 @item @emph{Return value}:
9095 The kind of the return value is that of @var{A} and @var{B}.
9096 If @math{B\ge 0} then the result is @code{ABS(A)}, else
9097 it is @code{-ABS(A)}.
9099 @item @emph{Example}:
9102 print *, sign(-12,1)
9103 print *, sign(-12,0)
9104 print *, sign(-12,-1)
9106 print *, sign(-12.,1.)
9107 print *, sign(-12.,0.)
9108 print *, sign(-12.,-1.)
9109 end program test_sign
9112 @item @emph{Specific names}:
9113 @multitable @columnfractions .20 .20 .20 .25
9114 @item Name @tab Arguments @tab Return type @tab Standard
9115 @item @code{ISIGN(A,P)} @tab @code{INTEGER(4)} @tab @code{INTEGER(4)} @tab f95, gnu
9116 @item @code{DSIGN(A,P)} @tab @code{REAL(8)} @tab @code{REAL(8)} @tab f95, gnu
9123 @section @code{SIGNAL} --- Signal handling subroutine (or function)
9125 @cindex system, signal handling
9128 @item @emph{Description}:
9129 @code{SIGNAL(NUMBER, HANDLER [, STATUS])} causes external subroutine
9130 @var{HANDLER} to be executed with a single integer argument when signal
9131 @var{NUMBER} occurs. If @var{HANDLER} is an integer, it can be used to
9132 turn off handling of signal @var{NUMBER} or revert to its default
9133 action. See @code{signal(2)}.
9135 If @code{SIGNAL} is called as a subroutine and the @var{STATUS} argument
9136 is supplied, it is set to the value returned by @code{signal(2)}.
9138 @item @emph{Standard}:
9142 Subroutine, function
9144 @item @emph{Syntax}:
9145 @multitable @columnfractions .80
9146 @item @code{CALL SIGNAL(NUMBER, HANDLER [, STATUS])}
9147 @item @code{STATUS = SIGNAL(NUMBER, HANDLER)}
9150 @item @emph{Arguments}:
9151 @multitable @columnfractions .15 .70
9152 @item @var{NUMBER} @tab Shall be a scalar integer, with @code{INTENT(IN)}
9153 @item @var{HANDLER}@tab Signal handler (@code{INTEGER FUNCTION} or
9154 @code{SUBROUTINE}) or dummy/global @code{INTEGER} scalar.
9155 @code{INTEGER}. It is @code{INTENT(IN)}.
9156 @item @var{STATUS} @tab (Optional) @var{STATUS} shall be a scalar
9157 integer. It has @code{INTENT(OUT)}.
9160 @item @emph{Return value}:
9161 The @code{SIGNAL} function returns the value returned by @code{signal(2)}.
9163 @item @emph{Example}:
9167 external handler_print
9169 call signal (12, handler_print)
9173 end program test_signal
9180 @section @code{SIN} --- Sine function
9186 @cindex trigonometric function, sine
9190 @item @emph{Description}:
9191 @code{SIN(X)} computes the sine of @var{X}.
9193 @item @emph{Standard}:
9199 @item @emph{Syntax}:
9200 @code{RESULT = SIN(X)}
9202 @item @emph{Arguments}:
9203 @multitable @columnfractions .15 .70
9204 @item @var{X} @tab The type shall be @code{REAL(*)} or
9208 @item @emph{Return value}:
9209 The return value has same type and kind as @var{X}.
9211 @item @emph{Example}:
9216 end program test_sin
9219 @item @emph{Specific names}:
9220 @multitable @columnfractions .20 .20 .20 .25
9221 @item Name @tab Argument @tab Return type @tab Standard
9222 @item @code{DSIN(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab f95, gnu
9223 @item @code{CSIN(X)} @tab @code{COMPLEX(4) X} @tab @code{COMPLEX(4)} @tab f95, gnu
9224 @item @code{ZSIN(X)} @tab @code{COMPLEX(8) X} @tab @code{COMPLEX(8)} @tab f95, gnu
9225 @item @code{CDSIN(X)} @tab @code{COMPLEX(8) X} @tab @code{COMPLEX(8)} @tab f95, gnu
9228 @item @emph{See also}:
9235 @section @code{SINH} --- Hyperbolic sine function
9238 @cindex hyperbolic sine
9239 @cindex hyperbolic function, sine
9240 @cindex sine, hyperbolic
9243 @item @emph{Description}:
9244 @code{SINH(X)} computes the hyperbolic sine of @var{X}.
9246 @item @emph{Standard}:
9252 @item @emph{Syntax}:
9253 @code{RESULT = SINH(X)}
9255 @item @emph{Arguments}:
9256 @multitable @columnfractions .15 .70
9257 @item @var{X} @tab The type shall be @code{REAL(*)}.
9260 @item @emph{Return value}:
9261 The return value is of type @code{REAL(*)}.
9263 @item @emph{Example}:
9266 real(8) :: x = - 1.0_8
9268 end program test_sinh
9271 @item @emph{Specific names}:
9272 @multitable @columnfractions .20 .20 .20 .25
9273 @item Name @tab Argument @tab Return type @tab Standard
9274 @item @code{DSINH(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab F95 and later
9277 @item @emph{See also}:
9284 @section @code{SIZE} --- Determine the size of an array
9287 @cindex array, number of elements
9288 @cindex array, count elements
9291 @item @emph{Description}:
9292 Determine the extent of @var{ARRAY} along a specified dimension @var{DIM},
9293 or the total number of elements in @var{ARRAY} if @var{DIM} is absent.
9295 @item @emph{Standard}:
9301 @item @emph{Syntax}:
9302 @code{RESULT = SIZE(ARRAY[, DIM])}
9304 @item @emph{Arguments}:
9305 @multitable @columnfractions .15 .70
9306 @item @var{ARRAY} @tab Shall be an array of any type. If @var{ARRAY} is
9307 a pointer it must be associated and allocatable arrays must be allocated.
9308 @item @var{DIM} @tab (Optional) shall be a scalar of type @code{INTEGER}
9309 and its value shall be in the range from 1 to n, where n equals the rank
9313 @item @emph{Return value}:
9314 The return value is of type @code{INTEGER} and of the default
9317 @item @emph{Example}:
9320 WRITE(*,*) SIZE((/ 1, 2 /)) ! 2
9324 @item @emph{See also}:
9325 @ref{SHAPE}, @ref{RESHAPE}
9330 @section @code{SIZEOF} --- Size in bytes of an expression
9332 @cindex expression size
9333 @cindex size of an expression
9336 @item @emph{Description}:
9337 @code{SIZEOF(X)} calculates the number of bytes of storage the
9338 expression @code{X} occupies.
9340 @item @emph{Standard}:
9346 @item @emph{Syntax}:
9347 @code{N = SIZEOF(X)}
9349 @item @emph{Arguments}:
9350 @multitable @columnfractions .15 .70
9351 @item @var{X} @tab The argument shall be of any type, rank or shape.
9354 @item @emph{Return value}:
9355 The return value is of type integer. Its value is the number of bytes
9356 occupied by the argument. If the argument has the @code{POINTER}
9357 attribute, the number of bytes of the storage area pointed to is
9358 returned. If the argument is of a derived type with @code{POINTER} or
9359 @code{ALLOCATABLE} components, the return value doesn't account for
9360 the sizes of the data pointed to by these components.
9362 @item @emph{Example}:
9366 print *, (sizeof(s)/sizeof(r) == 5)
9369 The example will print @code{.TRUE.} unless you are using a platform
9370 where default @code{REAL} variables are unusually padded.
9374 @section @code{SLEEP} --- Sleep for the specified number of seconds
9376 @cindex delayed execution
9379 @item @emph{Description}:
9380 Calling this subroutine causes the process to pause for @var{SECONDS} seconds.
9382 @item @emph{Standard}:
9388 @item @emph{Syntax}:
9389 @code{CALL SLEEP(SECONDS)}
9391 @item @emph{Arguments}:
9392 @multitable @columnfractions .15 .70
9393 @item @var{SECONDS} @tab The type shall be of default @code{INTEGER}.
9396 @item @emph{Example}:
9407 @section @code{SNGL} --- Convert double precision real to default real
9409 @cindex conversion, to real
9412 @item @emph{Description}:
9413 @code{SNGL(A)} converts the double precision real @var{A}
9414 to a default real value. This is an archaic form of @code{REAL}
9415 that is specific to one type for @var{A}.
9417 @item @emph{Standard}:
9423 @item @emph{Syntax}:
9424 @code{RESULT = SNGL(A)}
9426 @item @emph{Arguments}:
9427 @multitable @columnfractions .15 .70
9428 @item @var{A} @tab The type shall be a double precision @code{REAL}.
9431 @item @emph{Return value}:
9432 The return value is of type default @code{REAL}.
9434 @item @emph{See also}:
9441 @section @code{SPACING} --- Smallest distance between two numbers of a given type
9443 @cindex real number, relative spacing
9444 @cindex floating point, relative spacing
9447 @item @emph{Description}:
9448 Determines the distance between the argument @var{X} and the nearest
9449 adjacent number of the same type.
9451 @item @emph{Standard}:
9457 @item @emph{Syntax}:
9458 @code{RESULT = SPACING(X)}
9460 @item @emph{Arguments}:
9461 @multitable @columnfractions .15 .70
9462 @item @var{X} @tab Shall be of type @code{REAL(*)}.
9465 @item @emph{Return value}:
9466 The result is of the same type as the input argument @var{X}.
9468 @item @emph{Example}:
9470 PROGRAM test_spacing
9471 INTEGER, PARAMETER :: SGL = SELECTED_REAL_KIND(p=6, r=37)
9472 INTEGER, PARAMETER :: DBL = SELECTED_REAL_KIND(p=13, r=200)
9474 WRITE(*,*) spacing(1.0_SGL) ! "1.1920929E-07" on i686
9475 WRITE(*,*) spacing(1.0_DBL) ! "2.220446049250313E-016" on i686
9479 @item @emph{See also}:
9486 @section @code{SPREAD} --- Add a dimension to an array
9488 @cindex array, increase dimension
9489 @cindex array, duplicate elements
9490 @cindex array, duplicate dimensions
9493 @item @emph{Description}:
9494 Replicates a @var{SOURCE} array @var{NCOPIES} times along a specified
9495 dimension @var{DIM}.
9497 @item @emph{Standard}:
9501 Transformational function
9503 @item @emph{Syntax}:
9504 @code{RESULT = SPREAD(SOURCE, DIM, NCOPIES)}
9506 @item @emph{Arguments}:
9507 @multitable @columnfractions .15 .70
9508 @item @var{SOURCE} @tab Shall be a scalar or an array of any type and
9509 a rank less than seven.
9510 @item @var{DIM} @tab Shall be a scalar of type @code{INTEGER} with a
9511 value in the range from 1 to n+1, where n equals the rank of @var{SOURCE}.
9512 @item @var{NCOPIES} @tab Shall be a scalar of type @code{INTEGER}.
9515 @item @emph{Return value}:
9516 The result is an array of the same type as @var{SOURCE} and has rank n+1
9517 where n equals the rank of @var{SOURCE}.
9519 @item @emph{Example}:
9522 INTEGER :: a = 1, b(2) = (/ 1, 2 /)
9523 WRITE(*,*) SPREAD(A, 1, 2) ! "1 1"
9524 WRITE(*,*) SPREAD(B, 1, 2) ! "1 1 2 2"
9528 @item @emph{See also}:
9535 @section @code{SQRT} --- Square-root function
9545 @item @emph{Description}:
9546 @code{SQRT(X)} computes the square root of @var{X}.
9548 @item @emph{Standard}:
9554 @item @emph{Syntax}:
9555 @code{RESULT = SQRT(X)}
9557 @item @emph{Arguments}:
9558 @multitable @columnfractions .15 .70
9559 @item @var{X} @tab The type shall be @code{REAL(*)} or
9563 @item @emph{Return value}:
9564 The return value is of type @code{REAL(*)} or @code{COMPLEX(*)}.
9565 The kind type parameter is the same as @var{X}.
9567 @item @emph{Example}:
9570 real(8) :: x = 2.0_8
9571 complex :: z = (1.0, 2.0)
9574 end program test_sqrt
9577 @item @emph{Specific names}:
9578 @multitable @columnfractions .20 .20 .20 .25
9579 @item Name @tab Argument @tab Return type @tab Standard
9580 @item @code{DSQRT(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab F95 and later
9581 @item @code{CSQRT(X)} @tab @code{COMPLEX(4) X} @tab @code{COMPLEX(4)} @tab F95 and later
9582 @item @code{ZSQRT(X)} @tab @code{COMPLEX(8) X} @tab @code{COMPLEX(8)} @tab GNU extension
9583 @item @code{CDSQRT(X)} @tab @code{COMPLEX(8) X} @tab @code{COMPLEX(8)} @tab GNU extension
9590 @section @code{SRAND} --- Reinitialize the random number generator
9592 @cindex random number generation, seeding
9593 @cindex seeding a random number generator
9596 @item @emph{Description}:
9597 @code{SRAND} reinitializes the pseudo-random number generator
9598 called by @code{RAND} and @code{IRAND}. The new seed used by the
9599 generator is specified by the required argument @var{SEED}.
9601 @item @emph{Standard}:
9607 @item @emph{Syntax}:
9608 @code{CALL SRAND(SEED)}
9610 @item @emph{Arguments}:
9611 @multitable @columnfractions .15 .70
9612 @item @var{SEED} @tab Shall be a scalar @code{INTEGER(kind=4)}.
9615 @item @emph{Return value}:
9618 @item @emph{Example}:
9619 See @code{RAND} and @code{IRAND} for examples.
9622 The Fortran 2003 standard specifies the intrinsic @code{RANDOM_SEED} to
9623 initialize the pseudo-random numbers generator and @code{RANDOM_NUMBER}
9624 to generate pseudo-random numbers. Please note that in
9625 GNU Fortran, these two sets of intrinsics (@code{RAND},
9626 @code{IRAND} and @code{SRAND} on the one hand, @code{RANDOM_NUMBER} and
9627 @code{RANDOM_SEED} on the other hand) access two independent
9628 pseudo-random number generators.
9630 @item @emph{See also}:
9631 @ref{RAND}, @ref{RANDOM_SEED}, @ref{RANDOM_NUMBER}
9638 @section @code{STAT} --- Get file status
9640 @cindex file system, file status
9643 @item @emph{Description}:
9644 This function returns information about a file. No permissions are required on
9645 the file itself, but execute (search) permission is required on all of the
9646 directories in path that lead to the file.
9648 The elements that are obtained and stored in the array @code{BUFF}:
9649 @multitable @columnfractions .15 .70
9650 @item @code{buff(1)} @tab Device ID
9651 @item @code{buff(2)} @tab Inode number
9652 @item @code{buff(3)} @tab File mode
9653 @item @code{buff(4)} @tab Number of links
9654 @item @code{buff(5)} @tab Owner's uid
9655 @item @code{buff(6)} @tab Owner's gid
9656 @item @code{buff(7)} @tab ID of device containing directory entry for file (0 if not available)
9657 @item @code{buff(8)} @tab File size (bytes)
9658 @item @code{buff(9)} @tab Last access time
9659 @item @code{buff(10)} @tab Last modification time
9660 @item @code{buff(11)} @tab Last file status change time
9661 @item @code{buff(12)} @tab Preferred I/O block size (-1 if not available)
9662 @item @code{buff(13)} @tab Number of blocks allocated (-1 if not available)
9665 Not all these elements are relevant on all systems.
9666 If an element is not relevant, it is returned as 0.
9668 This intrinsic is provided in both subroutine and function forms; however,
9669 only one form can be used in any given program unit.
9671 @item @emph{Standard}:
9675 Subroutine, function
9677 @item @emph{Syntax}:
9678 @code{CALL STAT(FILE,BUFF[,STATUS])}
9680 @item @emph{Arguments}:
9681 @multitable @columnfractions .15 .70
9682 @item @var{FILE} @tab The type shall be @code{CHARACTER(*)}, a valid path within the file system.
9683 @item @var{BUFF} @tab The type shall be @code{INTEGER(4), DIMENSION(13)}.
9684 @item @var{STATUS} @tab (Optional) status flag of type @code{INTEGER(4)}. Returns 0
9685 on success and a system specific error code otherwise.
9688 @item @emph{Example}:
9691 INTEGER, DIMENSION(13) :: buff
9694 CALL STAT("/etc/passwd", buff, status)
9696 IF (status == 0) THEN
9697 WRITE (*, FMT="('Device ID:', T30, I19)") buff(1)
9698 WRITE (*, FMT="('Inode number:', T30, I19)") buff(2)
9699 WRITE (*, FMT="('File mode (octal):', T30, O19)") buff(3)
9700 WRITE (*, FMT="('Number of links:', T30, I19)") buff(4)
9701 WRITE (*, FMT="('Owner''s uid:', T30, I19)") buff(5)
9702 WRITE (*, FMT="('Owner''s gid:', T30, I19)") buff(6)
9703 WRITE (*, FMT="('Device where located:', T30, I19)") buff(7)
9704 WRITE (*, FMT="('File size:', T30, I19)") buff(8)
9705 WRITE (*, FMT="('Last access time:', T30, A19)") CTIME(buff(9))
9706 WRITE (*, FMT="('Last modification time', T30, A19)") CTIME(buff(10))
9707 WRITE (*, FMT="('Last status change time:', T30, A19)") CTIME(buff(11))
9708 WRITE (*, FMT="('Preferred block size:', T30, I19)") buff(12)
9709 WRITE (*, FMT="('No. of blocks allocated:', T30, I19)") buff(13)
9714 @item @emph{See also}:
9715 To stat an open file: @ref{FSTAT}, to stat a link: @ref{LSTAT}
9721 @section @code{SUM} --- Sum of array elements
9724 @cindex array, add elements
9725 @cindex array, conditionally add elements
9726 @cindex sum array elements
9729 @item @emph{Description}:
9730 Adds the elements of @var{ARRAY} along dimension @var{DIM} if
9731 the corresponding element in @var{MASK} is @code{TRUE}.
9733 @item @emph{Standard}:
9737 Transformational function
9739 @item @emph{Syntax}:
9740 @code{RESULT = SUM(ARRAY[, MASK])}
9741 @code{RESULT = SUM(ARRAY, DIM[, MASK])}
9743 @item @emph{Arguments}:
9744 @multitable @columnfractions .15 .70
9745 @item @var{ARRAY} @tab Shall be an array of type @code{INTEGER(*)},
9746 @code{REAL(*)} or @code{COMPLEX(*)}.
9747 @item @var{DIM} @tab (Optional) shall be a scalar of type
9748 @code{INTEGER} with a value in the range from 1 to n, where n
9749 equals the rank of @var{ARRAY}.
9750 @item @var{MASK} @tab (Optional) shall be of type @code{LOGICAL}
9751 and either be a scalar or an array of the same shape as @var{ARRAY}.
9754 @item @emph{Return value}:
9755 The result is of the same type as @var{ARRAY}.
9757 If @var{DIM} is absent, a scalar with the sum of all elements in @var{ARRAY}
9758 is returned. Otherwise, an array of rank n-1, where n equals the rank of
9759 @var{ARRAY},and a shape similar to that of @var{ARRAY} with dimension @var{DIM}
9760 dropped is returned.
9762 @item @emph{Example}:
9765 INTEGER :: x(5) = (/ 1, 2, 3, 4 ,5 /)
9766 print *, SUM(x) ! all elements, sum = 15
9767 print *, SUM(x, MASK=MOD(x, 2)==1) ! odd elements, sum = 9
9771 @item @emph{See also}:
9778 @section @code{SYMLNK} --- Create a symbolic link
9780 @cindex file system, create link
9781 @cindex file system, soft link
9784 @item @emph{Description}:
9785 Makes a symbolic link from file @var{PATH1} to @var{PATH2}. A null
9786 character (@code{CHAR(0)}) can be used to mark the end of the names in
9787 @var{PATH1} and @var{PATH2}; otherwise, trailing blanks in the file
9788 names are ignored. If the @var{STATUS} argument is supplied, it
9789 contains 0 on success or a nonzero error code upon return; see
9790 @code{symlink(2)}. If the system does not supply @code{symlink(2)},
9791 @code{ENOSYS} is returned.
9793 This intrinsic is provided in both subroutine and function forms;
9794 however, only one form can be used in any given program unit.
9796 @item @emph{Standard}:
9800 Subroutine, function
9802 @item @emph{Syntax}:
9803 @multitable @columnfractions .80
9804 @item @code{CALL SYMLNK(PATH1, PATH2 [, STATUS])}
9805 @item @code{STATUS = SYMLNK(PATH1, PATH2)}
9808 @item @emph{Arguments}:
9809 @multitable @columnfractions .15 .70
9810 @item @var{PATH1} @tab Shall be of default @code{CHARACTER} type.
9811 @item @var{PATH2} @tab Shall be of default @code{CHARACTER} type.
9812 @item @var{STATUS} @tab (Optional) Shall be of default @code{INTEGER} type.
9815 @item @emph{See also}:
9816 @ref{LINK}, @ref{UNLINK}
9823 @section @code{SYSTEM} --- Execute a shell command
9825 @cindex system, system call
9828 @item @emph{Description}:
9829 Passes the command @var{COMMAND} to a shell (see @code{system(3)}). If
9830 argument @var{STATUS} is present, it contains the value returned by
9831 @code{system(3)}, which is presumably 0 if the shell command succeeded.
9832 Note that which shell is used to invoke the command is system-dependent
9833 and environment-dependent.
9835 This intrinsic is provided in both subroutine and function forms;
9836 however, only one form can be used in any given program unit.
9838 @item @emph{Standard}:
9842 Subroutine, function
9844 @item @emph{Syntax}:
9845 @multitable @columnfractions .80
9846 @item @code{CALL SYSTEM(COMMAND [, STATUS])}
9847 @item @code{STATUS = SYSTEM(COMMAND)}
9850 @item @emph{Arguments}:
9851 @multitable @columnfractions .15 .70
9852 @item @var{COMMAND} @tab Shall be of default @code{CHARACTER} type.
9853 @item @var{STATUS} @tab (Optional) Shall be of default @code{INTEGER} type.
9856 @item @emph{See also}:
9862 @section @code{SYSTEM_CLOCK} --- Time function
9863 @fnindex SYSTEM_CLOCK
9864 @cindex time, clock ticks
9868 @item @emph{Description}:
9869 Determines the @var{COUNT} of milliseconds of wall clock time since
9870 the Epoch (00:00:00 UTC, January 1, 1970) modulo @var{COUNT_MAX},
9871 @var{COUNT_RATE} determines the number of clock ticks per second.
9872 @var{COUNT_RATE} and @var{COUNT_MAX} are constant and specific to
9875 If there is no clock, @var{COUNT} is set to @code{-HUGE(COUNT)}, and
9876 @var{COUNT_RATE} and @var{COUNT_MAX} are set to zero
9878 @item @emph{Standard}:
9884 @item @emph{Syntax}:
9885 @code{CALL SYSTEM_CLOCK([COUNT, COUNT_RATE, COUNT_MAX])}
9887 @item @emph{Arguments}:
9888 @item @emph{Arguments}:
9889 @multitable @columnfractions .15 .70
9890 @item @var{COUNT} @tab (Optional) shall be a scalar of type default
9891 @code{INTEGER} with @code{INTENT(OUT)}.
9892 @item @var{COUNT_RATE} @tab (Optional) shall be a scalar of type default
9893 @code{INTEGER} with @code{INTENT(OUT)}.
9894 @item @var{COUNT_MAX} @tab (Optional) shall be a scalar of type default
9895 @code{INTEGER} with @code{INTENT(OUT)}.
9898 @item @emph{Example}:
9900 PROGRAM test_system_clock
9901 INTEGER :: count, count_rate, count_max
9902 CALL SYSTEM_CLOCK(count, count_rate, count_max)
9903 WRITE(*,*) count, count_rate, count_max
9907 @item @emph{See also}:
9908 @ref{DATE_AND_TIME}, @ref{CPU_TIME}
9914 @section @code{TAN} --- Tangent function
9917 @cindex trigonometric function, tangent
9921 @item @emph{Description}:
9922 @code{TAN(X)} computes the tangent of @var{X}.
9924 @item @emph{Standard}:
9930 @item @emph{Syntax}:
9931 @code{RESULT = TAN(X)}
9933 @item @emph{Arguments}:
9934 @multitable @columnfractions .15 .70
9935 @item @var{X} @tab The type shall be @code{REAL(*)}.
9938 @item @emph{Return value}:
9939 The return value is of type @code{REAL(*)}. The kind type parameter is
9940 the same as @var{X}.
9942 @item @emph{Example}:
9945 real(8) :: x = 0.165_8
9947 end program test_tan
9950 @item @emph{Specific names}:
9951 @multitable @columnfractions .20 .20 .20 .25
9952 @item Name @tab Argument @tab Return type @tab Standard
9953 @item @code{DTAN(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab F95 and later
9956 @item @emph{See also}:
9963 @section @code{TANH} --- Hyperbolic tangent function
9966 @cindex hyperbolic tangent
9967 @cindex hyperbolic function, tangent
9968 @cindex tangent, hyperbolic
9971 @item @emph{Description}:
9972 @code{TANH(X)} computes the hyperbolic tangent of @var{X}.
9974 @item @emph{Standard}:
9980 @item @emph{Syntax}:
9983 @item @emph{Arguments}:
9984 @multitable @columnfractions .15 .70
9985 @item @var{X} @tab The type shall be @code{REAL(*)}.
9988 @item @emph{Return value}:
9989 The return value is of type @code{REAL(*)} and lies in the range
9990 @math{ - 1 \leq tanh(x) \leq 1 }.
9992 @item @emph{Example}:
9995 real(8) :: x = 2.1_8
9997 end program test_tanh
10000 @item @emph{Specific names}:
10001 @multitable @columnfractions .20 .20 .20 .25
10002 @item Name @tab Argument @tab Return type @tab Standard
10003 @item @code{DTANH(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab F95 and later
10006 @item @emph{See also}:
10013 @section @code{TIME} --- Time function
10015 @cindex time, current
10016 @cindex current time
10019 @item @emph{Description}:
10020 Returns the current time encoded as an integer (in the manner of the
10021 UNIX function @code{time(3)}). This value is suitable for passing to
10022 @code{CTIME()}, @code{GMTIME()}, and @code{LTIME()}.
10024 This intrinsic is not fully portable, such as to systems with 32-bit
10025 @code{INTEGER} types but supporting times wider than 32 bits. Therefore,
10026 the values returned by this intrinsic might be, or become, negative, or
10027 numerically less than previous values, during a single run of the
10030 See @ref{TIME8}, for information on a similar intrinsic that might be
10031 portable to more GNU Fortran implementations, though to fewer Fortran
10034 @item @emph{Standard}:
10037 @item @emph{Class}:
10040 @item @emph{Syntax}:
10041 @code{RESULT = TIME()}
10043 @item @emph{Return value}:
10044 The return value is a scalar of type @code{INTEGER(4)}.
10046 @item @emph{See also}:
10047 @ref{CTIME}, @ref{GMTIME}, @ref{LTIME}, @ref{MCLOCK}, @ref{TIME8}
10054 @section @code{TIME8} --- Time function (64-bit)
10056 @cindex time, current
10057 @cindex current time
10060 @item @emph{Description}:
10061 Returns the current time encoded as an integer (in the manner of the
10062 UNIX function @code{time(3)}). This value is suitable for passing to
10063 @code{CTIME()}, @code{GMTIME()}, and @code{LTIME()}.
10065 @emph{Warning:} this intrinsic does not increase the range of the timing
10066 values over that returned by @code{time(3)}. On a system with a 32-bit
10067 @code{time(3)}, @code{TIME8()} will return a 32-bit value, even though
10068 it is converted to a 64-bit @code{INTEGER(8)} value. That means
10069 overflows of the 32-bit value can still occur. Therefore, the values
10070 returned by this intrinsic might be or become negative or numerically
10071 less than previous values during a single run of the compiled program.
10073 @item @emph{Standard}:
10076 @item @emph{Class}:
10079 @item @emph{Syntax}:
10080 @code{RESULT = TIME8()}
10082 @item @emph{Return value}:
10083 The return value is a scalar of type @code{INTEGER(8)}.
10085 @item @emph{See also}:
10086 @ref{CTIME}, @ref{GMTIME}, @ref{LTIME}, @ref{MCLOCK8}, @ref{TIME}
10093 @section @code{TINY} --- Smallest positive number of a real kind
10095 @cindex limits, smallest number
10096 @cindex model representation, smallest number
10099 @item @emph{Description}:
10100 @code{TINY(X)} returns the smallest positive (non zero) number
10101 in the model of the type of @code{X}.
10103 @item @emph{Standard}:
10106 @item @emph{Class}:
10109 @item @emph{Syntax}:
10110 @code{RESULT = TINY(X)}
10112 @item @emph{Arguments}:
10113 @multitable @columnfractions .15 .70
10114 @item @var{X} @tab Shall be of type @code{REAL}.
10117 @item @emph{Return value}:
10118 The return value is of the same type and kind as @var{X}
10120 @item @emph{Example}:
10121 See @code{HUGE} for an example.
10127 @section @code{TRANSFER} --- Transfer bit patterns
10133 @item @emph{Description}:
10134 Interprets the bitwise representation of @var{SOURCE} in memory as if it
10135 is the representation of a variable or array of the same type and type
10136 parameters as @var{MOLD}.
10138 This is approximately equivalent to the C concept of @emph{casting} one
10141 @item @emph{Standard}:
10144 @item @emph{Class}:
10145 Transformational function
10147 @item @emph{Syntax}:
10148 @code{RESULT = TRANSFER(SOURCE, MOLD[, SIZE])}
10150 @item @emph{Arguments}:
10151 @multitable @columnfractions .15 .70
10152 @item @var{SOURCE} @tab Shall be a scalar or an array of any type.
10153 @item @var{MOLD} @tab Shall be a scalar or an array of any type.
10154 @item @var{SIZE} @tab (Optional) shall be a scalar of type
10158 @item @emph{Return value}:
10159 The result has the same type as @var{MOLD}, with the bit level
10160 representation of @var{SOURCE}. If @var{SIZE} is present, the result is
10161 a one-dimensional array of length @var{SIZE}. If @var{SIZE} is absent
10162 but @var{MOLD} is an array (of any size or shape), the result is a one-
10163 dimensional array of the minimum length needed to contain the entirety
10164 of the bitwise representation of @var{SOURCE}. If @var{SIZE} is absent
10165 and @var{MOLD} is a scalar, the result is a scalar.
10167 If the bitwise representation of the result is longer than that of
10168 @var{SOURCE}, then the leading bits of the result correspond to those of
10169 @var{SOURCE} and any trailing bits are filled arbitrarily.
10171 When the resulting bit representation does not correspond to a valid
10172 representation of a variable of the same type as @var{MOLD}, the results
10173 are undefined, and subsequent operations on the result cannot be
10174 guaranteed to produce sensible behavior. For example, it is possible to
10175 create @code{LOGICAL} variables for which @code{@var{VAR}} and
10176 @code{.NOT.@var{VAR}} both appear to be true.
10178 @item @emph{Example}:
10180 PROGRAM test_transfer
10181 integer :: x = 2143289344
10182 print *, transfer(x, 1.0) ! prints "NaN" on i686
10190 @section @code{TRANSPOSE} --- Transpose an array of rank two
10192 @cindex array, transpose
10193 @cindex matrix, transpose
10197 @item @emph{Description}:
10198 Transpose an array of rank two. Element (i, j) of the result has the value
10199 @code{MATRIX(j, i)}, for all i, j.
10201 @item @emph{Standard}:
10204 @item @emph{Class}:
10205 Transformational function
10207 @item @emph{Syntax}:
10208 @code{RESULT = TRANSPOSE(MATRIX)}
10210 @item @emph{Arguments}:
10211 @multitable @columnfractions .15 .70
10212 @item @var{MATRIX} @tab Shall be an array of any type and have a rank of two.
10215 @item @emph{Return value}:
10216 The result has the the same type as @var{MATRIX}, and has shape
10217 @code{(/ m, n /)} if @var{MATRIX} has shape @code{(/ n, m /)}.
10223 @section @code{TRIM} --- Remove trailing blank characters of a string
10225 @cindex string, remove trailing whitespace
10228 @item @emph{Description}:
10229 Removes trailing blank characters of a string.
10231 @item @emph{Standard}:
10234 @item @emph{Class}:
10235 Transformational function
10237 @item @emph{Syntax}:
10238 @code{RESULT = TRIM(STRING)}
10240 @item @emph{Arguments}:
10241 @multitable @columnfractions .15 .70
10242 @item @var{STRING} @tab Shall be a scalar of type @code{CHARACTER(*)}.
10245 @item @emph{Return value}:
10246 A scalar of type @code{CHARACTER(*)} which length is that of @var{STRING}
10247 less the number of trailing blanks.
10249 @item @emph{Example}:
10252 CHARACTER(len=10), PARAMETER :: s = "GFORTRAN "
10253 WRITE(*,*) LEN(s), LEN(TRIM(s)) ! "10 8", with/without trailing blanks
10257 @item @emph{See also}:
10258 @ref{ADJUSTL}, @ref{ADJUSTR}
10264 @section @code{TTYNAM} --- Get the name of a terminal device.
10266 @cindex system, terminal
10269 @item @emph{Description}:
10270 Get the name of a terminal device. For more information,
10271 see @code{ttyname(3)}.
10273 This intrinsic is provided in both subroutine and function forms;
10274 however, only one form can be used in any given program unit.
10276 @item @emph{Standard}:
10279 @item @emph{Class}:
10280 Subroutine, function
10282 @item @emph{Syntax}:
10283 @multitable @columnfractions .80
10284 @item @code{CALL TTYNAM(UNIT, NAME)}
10285 @item @code{NAME = TTYNAM(UNIT)}
10288 @item @emph{Arguments}:
10289 @multitable @columnfractions .15 .70
10290 @item @var{UNIT} @tab Shall be a scalar @code{INTEGER(*)}.
10291 @item @var{NAME} @tab Shall be of type @code{CHARACTER(*)}.
10294 @item @emph{Example}:
10296 PROGRAM test_ttynam
10299 IF (isatty(unit=unit)) write(*,*) ttynam(unit)
10304 @item @emph{See also}:
10311 @section @code{UBOUND} --- Upper dimension bounds of an array
10313 @cindex array, upper bound
10316 @item @emph{Description}:
10317 Returns the upper bounds of an array, or a single upper bound
10318 along the @var{DIM} dimension.
10319 @item @emph{Standard}:
10322 @item @emph{Class}:
10325 @item @emph{Syntax}:
10326 @code{RESULT = UBOUND(ARRAY [, DIM])}
10328 @item @emph{Arguments}:
10329 @multitable @columnfractions .15 .70
10330 @item @var{ARRAY} @tab Shall be an array, of any type.
10331 @item @var{DIM} @tab (Optional) Shall be a scalar @code{INTEGER(*)}.
10334 @item @emph{Return value}:
10335 If @var{DIM} is absent, the result is an array of the upper bounds of
10336 @var{ARRAY}. If @var{DIM} is present, the result is a scalar
10337 corresponding to the upper bound of the array along that dimension. If
10338 @var{ARRAY} is an expression rather than a whole array or array
10339 structure component, or if it has a zero extent along the relevant
10340 dimension, the upper bound is taken to be the number of elements along
10341 the relevant dimension.
10343 @item @emph{See also}:
10350 @section @code{UMASK} --- Set the file creation mask
10352 @cindex file system, file creation mask
10355 @item @emph{Description}:
10356 Sets the file creation mask to @var{MASK} and returns the old value in
10357 argument @var{OLD} if it is supplied. See @code{umask(2)}.
10359 @item @emph{Standard}:
10362 @item @emph{Class}:
10365 @item @emph{Syntax}:
10366 @code{CALL UMASK(MASK [, OLD])}
10368 @item @emph{Arguments}:
10369 @multitable @columnfractions .15 .70
10370 @item @var{MASK} @tab Shall be a scalar of type @code{INTEGER(*)}.
10371 @item @var{MASK} @tab (Optional) Shall be a scalar of type
10380 @section @code{UNLINK} --- Remove a file from the file system
10382 @cindex file system, remove file
10385 @item @emph{Description}:
10386 Unlinks the file @var{PATH}. A null character (@code{CHAR(0)}) can be
10387 used to mark the end of the name in @var{PATH}; otherwise, trailing
10388 blanks in the file name are ignored. If the @var{STATUS} argument is
10389 supplied, it contains 0 on success or a nonzero error code upon return;
10390 see @code{unlink(2)}.
10392 This intrinsic is provided in both subroutine and function forms;
10393 however, only one form can be used in any given program unit.
10395 @item @emph{Standard}:
10398 @item @emph{Class}:
10399 Subroutine, function
10401 @item @emph{Syntax}:
10402 @multitable @columnfractions .80
10403 @item @code{CALL UNLINK(PATH [, STATUS])}
10404 @item @code{STATUS = UNLINK(PATH)}
10407 @item @emph{Arguments}:
10408 @multitable @columnfractions .15 .70
10409 @item @var{PATH} @tab Shall be of default @code{CHARACTER} type.
10410 @item @var{STATUS} @tab (Optional) Shall be of default @code{INTEGER} type.
10413 @item @emph{See also}:
10414 @ref{LINK}, @ref{SYMLNK}
10420 @section @code{UNPACK} --- Unpack an array of rank one into an array
10422 @cindex array, unpacking
10423 @cindex array, increase dimension
10424 @cindex array, scatter elements
10427 @item @emph{Description}:
10428 Store the elements of @var{VECTOR} in an array of higher rank.
10430 @item @emph{Standard}:
10433 @item @emph{Class}:
10434 Transformational function
10436 @item @emph{Syntax}:
10437 @code{RESULT = UNPACK(VECTOR, MASK, FIELD)}
10439 @item @emph{Arguments}:
10440 @multitable @columnfractions .15 .70
10441 @item @var{VECTOR} @tab Shall be an array of any type and rank one. It
10442 shall have at least as many elements as @var{MASK} has @code{TRUE} values.
10443 @item @var{MASK} @tab Shall be an array of type @code{LOGICAL}.
10444 @item @var{FIELD} @tab Shall be of the sam type as @var{VECTOR} and have
10445 the same shape as @var{MASK}.
10448 @item @emph{Return value}:
10449 The resulting array corresponds to @var{FIELD} with @code{TRUE} elements
10450 of @var{MASK} replaced by values from @var{VECTOR} in array element order.
10452 @item @emph{Example}:
10454 PROGRAM test_unpack
10455 integer :: vector(2) = (/1,1/)
10456 logical :: mask(4) = (/ .TRUE., .FALSE., .FALSE., .TRUE. /)
10457 integer :: field(2,2) = 0, unity(2,2)
10459 ! result: unity matrix
10460 unity = unpack(vector, reshape(mask, (/2,2/)), field)
10464 @item @emph{See also}:
10465 @ref{PACK}, @ref{SPREAD}
10471 @section @code{VERIFY} --- Scan a string for the absence of a set of characters
10473 @cindex string, find missing set
10476 @item @emph{Description}:
10477 Verifies that all the characters in a @var{SET} are present in a @var{STRING}.
10479 If @var{BACK} is either absent or equals @code{FALSE}, this function
10480 returns the position of the leftmost character of @var{STRING} that is
10481 not in @var{SET}. If @var{BACK} equals @code{TRUE}, the rightmost position
10482 is returned. If all characters of @var{SET} are found in @var{STRING}, the
10485 @item @emph{Standard}:
10488 @item @emph{Class}:
10491 @item @emph{Syntax}:
10492 @code{RESULT = VERIFY(STRING, SET[, BACK])}
10494 @item @emph{Arguments}:
10495 @multitable @columnfractions .15 .70
10496 @item @var{STRING} @tab Shall be of type @code{CHARACTER(*)}.
10497 @item @var{SET} @tab Shall be of type @code{CHARACTER(*)}.
10498 @item @var{BACK} @tab (Optional) shall be of type @code{LOGICAL}.
10501 @item @emph{Return value}:
10502 The return value is of type @code{INTEGER} and of the default
10505 @item @emph{Example}:
10507 PROGRAM test_verify
10508 WRITE(*,*) VERIFY("FORTRAN", "AO") ! 1, found 'F'
10509 WRITE(*,*) VERIFY("FORTRAN", "FOO") ! 3, found 'R'
10510 WRITE(*,*) VERIFY("FORTRAN", "C++") ! 1, found 'F'
10511 WRITE(*,*) VERIFY("FORTRAN", "C++", .TRUE.) ! 7, found 'N'
10512 WRITE(*,*) VERIFY("FORTRAN", "FORTRAN") ! 0' found none
10516 @item @emph{See also}:
10517 @ref{SCAN}, @ref{INDEX}
10523 @section @code{XOR} --- Bitwise logical exclusive OR
10525 @cindex bitwise logical exclusive or
10526 @cindex logical exclusive or, bitwise
10529 @item @emph{Description}:
10530 Bitwise logical exclusive or.
10532 This intrinsic routine is provided for backwards compatibility with
10533 GNU Fortran 77. For integer arguments, programmers should consider
10534 the use of the @ref{IEOR} intrinsic defined by the Fortran standard.
10536 @item @emph{Standard}:
10539 @item @emph{Class}:
10542 @item @emph{Syntax}:
10543 @code{RESULT = XOR(X, Y)}
10545 @item @emph{Arguments}:
10546 @multitable @columnfractions .15 .70
10547 @item @var{X} @tab The type shall be either @code{INTEGER(*)} or @code{LOGICAL}.
10548 @item @var{Y} @tab The type shall be either @code{INTEGER(*)} or @code{LOGICAL}.
10551 @item @emph{Return value}:
10552 The return type is either @code{INTEGER(*)} or @code{LOGICAL}
10553 after cross-promotion of the arguments.
10555 @item @emph{Example}:
10558 LOGICAL :: T = .TRUE., F = .FALSE.
10560 DATA a / Z'F' /, b / Z'3' /
10562 WRITE (*,*) XOR(T, T), XOR(T, F), XOR(F, T), XOR(F, F)
10563 WRITE (*,*) XOR(a, b)
10567 @item @emph{See also}:
10568 F95 elemental function: @ref{IEOR}