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{GAMMA}: GAMMA, Gamma function
125 * @code{GERROR}: GERROR, Get last system error message
126 * @code{GETARG}: GETARG, Get command line arguments
127 * @code{GET_COMMAND}: GET_COMMAND, Get the entire command line
128 * @code{GET_COMMAND_ARGUMENT}: GET_COMMAND_ARGUMENT, Get command line arguments
129 * @code{GETCWD}: GETCWD, Get current working directory
130 * @code{GETENV}: GETENV, Get an environmental variable
131 * @code{GET_ENVIRONMENT_VARIABLE}: GET_ENVIRONMENT_VARIABLE, Get an environmental variable
132 * @code{GETGID}: GETGID, Group ID function
133 * @code{GETLOG}: GETLOG, Get login name
134 * @code{GETPID}: GETPID, Process ID function
135 * @code{GETUID}: GETUID, User ID function
136 * @code{GMTIME}: GMTIME, Convert time to GMT info
137 * @code{HOSTNM}: HOSTNM, Get system host name
138 * @code{HUGE}: HUGE, Largest number of a kind
139 * @code{IACHAR}: IACHAR, Code in @acronym{ASCII} collating sequence
140 * @code{IAND}: IAND, Bitwise logical and
141 * @code{IARGC}: IARGC, Get the number of command line arguments
142 * @code{IBCLR}: IBCLR, Clear bit
143 * @code{IBITS}: IBITS, Bit extraction
144 * @code{IBSET}: IBSET, Set bit
145 * @code{ICHAR}: ICHAR, Character-to-integer conversion function
146 * @code{IDATE}: IDATE, Current local time (day/month/year)
147 * @code{IEOR}: IEOR, Bitwise logical exclusive or
148 * @code{IERRNO}: IERRNO, Function to get the last system error number
149 * @code{INDEX}: INDEX intrinsic, Position of a substring within a string
150 * @code{INT}: INT, Convert to integer type
151 * @code{INT2}: INT2, Convert to 16-bit integer type
152 * @code{INT8}: INT8, Convert to 64-bit integer type
153 * @code{IOR}: IOR, Bitwise logical or
154 * @code{IRAND}: IRAND, Integer pseudo-random number
155 * @code{IS_IOSTAT_END}: IS_IOSTAT_END, Test for end-of-file value
156 * @code{IS_IOSTAT_EOR}: IS_IOSTAT_EOR, Test for end-of-record value
157 * @code{ISATTY}: ISATTY, Whether a unit is a terminal device
158 * @code{ISHFT}: ISHFT, Shift bits
159 * @code{ISHFTC}: ISHFTC, Shift bits circularly
160 * @code{ISNAN}: ISNAN, Tests for a NaN
161 * @code{ITIME}: ITIME, Current local time (hour/minutes/seconds)
162 * @code{KILL}: KILL, Send a signal to a process
163 * @code{KIND}: KIND, Kind of an entity
164 * @code{LBOUND}: LBOUND, Lower dimension bounds of an array
165 * @code{LEN}: LEN, Length of a character entity
166 * @code{LEN_TRIM}: LEN_TRIM, Length of a character entity without trailing blank characters
167 * @code{LGAMMA}: LGAMMA, Logarithm of the Gamma function
168 * @code{LGE}: LGE, Lexical greater than or equal
169 * @code{LGT}: LGT, Lexical greater than
170 * @code{LINK}: LINK, Create a hard link
171 * @code{LLE}: LLE, Lexical less than or equal
172 * @code{LLT}: LLT, Lexical less than
173 * @code{LNBLNK}: LNBLNK, Index of the last non-blank character in a string
174 * @code{LOC}: LOC, Returns the address of a variable
175 * @code{LOG}: LOG, Logarithm function
176 * @code{LOG10}: LOG10, Base 10 logarithm function
177 * @code{LOGICAL}: LOGICAL, Convert to logical type
178 * @code{LONG}: LONG, Convert to integer type
179 * @code{LSHIFT}: LSHIFT, Left shift bits
180 * @code{LSTAT}: LSTAT, Get file status
181 * @code{LTIME}: LTIME, Convert time to local time info
182 * @code{MALLOC}: MALLOC, Dynamic memory allocation function
183 * @code{MATMUL}: MATMUL, matrix multiplication
184 * @code{MAX}: MAX, Maximum value of an argument list
185 * @code{MAXEXPONENT}: MAXEXPONENT, Maximum exponent of a real kind
186 * @code{MAXLOC}: MAXLOC, Location of the maximum value within an array
187 * @code{MAXVAL}: MAXVAL, Maximum value of an array
188 * @code{MCLOCK}: MCLOCK, Time function
189 * @code{MCLOCK8}: MCLOCK8, Time function (64-bit)
190 * @code{MERGE}: MERGE, Merge arrays
191 * @code{MIN}: MIN, Minimum value of an argument list
192 * @code{MINEXPONENT}: MINEXPONENT, Minimum exponent of a real kind
193 * @code{MINLOC}: MINLOC, Location of the minimum value within an array
194 * @code{MINVAL}: MINVAL, Minimum value of an array
195 * @code{MOD}: MOD, Remainder function
196 * @code{MODULO}: MODULO, Modulo function
197 * @code{MOVE_ALLOC}: MOVE_ALLOC, Move allocation from one object to another
198 * @code{MVBITS}: MVBITS, Move bits from one integer to another
199 * @code{NEAREST}: NEAREST, Nearest representable number
200 * @code{NEW_LINE}: NEW_LINE, New line character
201 * @code{NINT}: NINT, Nearest whole number
202 * @code{NOT}: NOT, Logical negation
203 * @code{NULL}: NULL, Function that returns an disassociated pointer
204 * @code{OR}: OR, Bitwise logical OR
205 * @code{PACK}: PACK, Pack an array into an array of rank one
206 * @code{PERROR}: PERROR, Print system error message
207 * @code{PRECISION}: PRECISION, Decimal precision of a real kind
208 * @code{PRESENT}: PRESENT, Determine whether an optional dummy argument is specified
209 * @code{PRODUCT}: PRODUCT, Product of array elements
210 * @code{RADIX}: RADIX, Base of a data model
211 * @code{RANDOM_NUMBER}: RANDOM_NUMBER, Pseudo-random number
212 * @code{RANDOM_SEED}: RANDOM_SEED, Initialize a pseudo-random number sequence
213 * @code{RAND}: RAND, Real pseudo-random number
214 * @code{RANGE}: RANGE, Decimal exponent range of a real kind
215 * @code{RAN}: RAN, Real pseudo-random number
216 * @code{REAL}: REAL, Convert to real type
217 * @code{RENAME}: RENAME, Rename a file
218 * @code{REPEAT}: REPEAT, Repeated string concatenation
219 * @code{RESHAPE}: RESHAPE, Function to reshape an array
220 * @code{RRSPACING}: RRSPACING, Reciprocal of the relative spacing
221 * @code{RSHIFT}: RSHIFT, Right shift bits
222 * @code{SCALE}: SCALE, Scale a real value
223 * @code{SCAN}: SCAN, Scan a string for the presence of a set of characters
224 * @code{SECNDS}: SECNDS, Time function
225 * @code{SECOND}: SECOND, CPU time function
226 * @code{SELECTED_INT_KIND}: SELECTED_INT_KIND, Choose integer kind
227 * @code{SELECTED_REAL_KIND}: SELECTED_REAL_KIND, Choose real kind
228 * @code{SET_EXPONENT}: SET_EXPONENT, Set the exponent of the model
229 * @code{SHAPE}: SHAPE, Determine the shape of an array
230 * @code{SIGN}: SIGN, Sign copying function
231 * @code{SIGNAL}: SIGNAL, Signal handling subroutine (or function)
232 * @code{SIN}: SIN, Sine function
233 * @code{SINH}: SINH, Hyperbolic sine function
234 * @code{SIZE}: SIZE, Function to determine the size of an array
235 * @code{SIZEOF}: SIZEOF, Determine the size in bytes of an expression
236 * @code{SLEEP}: SLEEP, Sleep for the specified number of seconds
237 * @code{SNGL}: SNGL, Convert double precision real to default real
238 * @code{SPACING}: SPACING, Smallest distance between two numbers of a given type
239 * @code{SPREAD}: SPREAD, Add a dimension to an array
240 * @code{SQRT}: SQRT, Square-root function
241 * @code{SRAND}: SRAND, Reinitialize the random number generator
242 * @code{STAT}: STAT, Get file status
243 * @code{SUM}: SUM, Sum of array elements
244 * @code{SYMLNK}: SYMLNK, Create a symbolic link
245 * @code{SYSTEM}: SYSTEM, Execute a shell command
246 * @code{SYSTEM_CLOCK}: SYSTEM_CLOCK, Time function
247 * @code{TAN}: TAN, Tangent function
248 * @code{TANH}: TANH, Hyperbolic tangent function
249 * @code{TIME}: TIME, Time function
250 * @code{TIME8}: TIME8, Time function (64-bit)
251 * @code{TINY}: TINY, Smallest positive number of a real kind
252 * @code{TRANSFER}: TRANSFER, Transfer bit patterns
253 * @code{TRANSPOSE}: TRANSPOSE, Transpose an array of rank two
254 * @code{TRIM}: TRIM, Remove trailing blank characters of a string
255 * @code{TTYNAM}: TTYNAM, Get the name of a terminal device.
256 * @code{UBOUND}: UBOUND, Upper dimension bounds of an array
257 * @code{UMASK}: UMASK, Set the file creation mask
258 * @code{UNLINK}: UNLINK, Remove a file from the file system
259 * @code{UNPACK}: UNPACK, Unpack an array of rank one into an array
260 * @code{VERIFY}: VERIFY, Scan a string for the absence of a set of characters
261 * @code{XOR}: XOR, Bitwise logical exclusive or
264 @node Introduction to Intrinsics
265 @section Introduction to intrinsic procedures
267 The intrinsic procedures provided by GNU Fortran include all of the
268 intrinsic procedures required by the Fortran 95 standard, a set of
269 intrinsic procedures for backwards compatibility with G77, and a small
270 selection of intrinsic procedures from the Fortran 2003 standard. Any
271 conflict between a description here and a description in either the
272 Fortran 95 standard or the Fortran 2003 standard is unintentional, and
273 the standard(s) should be considered authoritative.
275 The enumeration of the @code{KIND} type parameter is processor defined in
276 the Fortran 95 standard. GNU Fortran defines the default integer type and
277 default real type by @code{INTEGER(KIND=4)} and @code{REAL(KIND=4)},
278 respectively. The standard mandates that both data types shall have
279 another kind, which have more precision. On typical target architectures
280 supported by @command{gfortran}, this kind type parameter is @code{KIND=8}.
281 Hence, @code{REAL(KIND=8)} and @code{DOUBLE PRECISION} are equivalent.
282 In the description of generic intrinsic procedures, the kind type parameter
283 will be specified by @code{KIND=*}, and in the description of specific
284 names for an intrinsic procedure the kind type parameter will be explicitly
285 given (e.g., @code{REAL(KIND=4)} or @code{REAL(KIND=8)}). Finally, for
286 brevity the optional @code{KIND=} syntax will be omitted.
288 Many of the intrinsic procedures take one or more optional arguments.
289 This document follows the convention used in the Fortran 95 standard,
290 and denotes such arguments by square brackets.
292 GNU Fortran offers the @option{-std=f95} and @option{-std=gnu} options,
293 which can be used to restrict the set of intrinsic procedures to a
294 given standard. By default, @command{gfortran} sets the @option{-std=gnu}
295 option, and so all intrinsic procedures described here are accepted. There
296 is one caveat. For a select group of intrinsic procedures, @command{g77}
297 implemented both a function and a subroutine. Both classes
298 have been implemented in @command{gfortran} for backwards compatibility
299 with @command{g77}. It is noted here that these functions and subroutines
300 cannot be intermixed in a given subprogram. In the descriptions that follow,
301 the applicable standard for each intrinsic procedure is noted.
306 @section @code{ABORT} --- Abort the program
308 @cindex program termination, with core dump
309 @cindex terminate program, with core dump
313 @item @emph{Description}:
314 @code{ABORT} causes immediate termination of the program. On operating
315 systems that support a core dump, @code{ABORT} will produce a core dump,
316 which is suitable for debugging purposes.
318 @item @emph{Standard}:
327 @item @emph{Return value}:
330 @item @emph{Example}:
333 integer :: i = 1, j = 2
334 if (i /= j) call abort
335 end program test_abort
338 @item @emph{See also}:
339 @ref{EXIT}, @ref{KILL}
346 @section @code{ABS} --- Absolute value
353 @cindex absolute value
356 @item @emph{Description}:
357 @code{ABS(X)} computes the absolute value of @code{X}.
359 @item @emph{Standard}:
360 F77 and later, has overloads that are GNU extensions
366 @code{RESULT = ABS(X)}
368 @item @emph{Arguments}:
369 @multitable @columnfractions .15 .70
370 @item @var{X} @tab The type of the argument shall be an @code{INTEGER(*)},
371 @code{REAL(*)}, or @code{COMPLEX(*)}.
374 @item @emph{Return value}:
375 The return value is of the same type and
376 kind as the argument except the return value is @code{REAL(*)} for a
377 @code{COMPLEX(*)} argument.
379 @item @emph{Example}:
384 complex :: z = (-1.e0,0.e0)
391 @item @emph{Specific names}:
392 @multitable @columnfractions .20 .20 .20 .25
393 @item Name @tab Argument @tab Return type @tab Standard
394 @item @code{CABS(Z)} @tab @code{COMPLEX(4) Z} @tab @code{REAL(4)} @tab F77 and later
395 @item @code{DABS(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab F77 and later
396 @item @code{IABS(I)} @tab @code{INTEGER(4) I} @tab @code{INTEGER(4)} @tab F77 and later
397 @item @code{ZABS(Z)} @tab @code{COMPLEX(8) Z} @tab @code{COMPLEX(8)} @tab GNU extension
398 @item @code{CDABS(Z)} @tab @code{COMPLEX(8) Z} @tab @code{COMPLEX(8)} @tab GNU extension
405 @section @code{ACCESS} --- Checks file access modes
407 @cindex file system, access mode
410 @item @emph{Description}:
411 @code{ACCESS(NAME, MODE)} checks whether the file @var{NAME}
412 exists, is readable, writable or executable. Except for the
413 executable check, @code{ACCESS} can be replaced by
414 Fortran 95's @code{INQUIRE}.
416 @item @emph{Standard}:
423 @code{RESULT = ACCESS(NAME, MODE)}
425 @item @emph{Arguments}:
426 @multitable @columnfractions .15 .70
427 @item @var{NAME} @tab Scalar @code{CHARACTER} with the file name.
428 Tailing blank are ignored unless the character @code{achar(0)} is
429 present, then all characters up to and excluding @code{achar(0)} are
431 @item @var{MODE} @tab Scalar @code{CHARACTER} with the file access mode,
432 may be any concatenation of @code{"r"} (readable), @code{"w"} (writable)
433 and @code{"x"} (executable), or @code{" "} to check for existence.
436 @item @emph{Return value}:
437 Returns a scalar @code{INTEGER}, which is @code{0} if the file is
438 accessible in the given mode; otherwise or if an invalid argument
439 has been given for @code{MODE} the value @code{1} is returned.
441 @item @emph{Example}:
445 character(len=*), parameter :: file = 'test.dat'
446 character(len=*), parameter :: file2 = 'test.dat '//achar(0)
447 if(access(file,' ') == 0) print *, trim(file),' is exists'
448 if(access(file,'r') == 0) print *, trim(file),' is readable'
449 if(access(file,'w') == 0) print *, trim(file),' is writable'
450 if(access(file,'x') == 0) print *, trim(file),' is executable'
451 if(access(file2,'rwx') == 0) &
452 print *, trim(file2),' is readable, writable and executable'
453 end program access_test
455 @item @emph{Specific names}:
456 @item @emph{See also}:
463 @section @code{ACHAR} --- Character in @acronym{ASCII} collating sequence
465 @cindex @acronym{ASCII} collating sequence
466 @cindex collating sequence, @acronym{ASCII}
469 @item @emph{Description}:
470 @code{ACHAR(I)} returns the character located at position @code{I}
471 in the @acronym{ASCII} collating sequence.
473 @item @emph{Standard}:
480 @code{RESULT = ACHAR(I)}
482 @item @emph{Arguments}:
483 @multitable @columnfractions .15 .70
484 @item @var{I} @tab The type shall be @code{INTEGER(*)}.
487 @item @emph{Return value}:
488 The return value is of type @code{CHARACTER} with a length of one. The
489 kind type parameter is the same as @code{KIND('A')}.
491 @item @emph{Example}:
496 end program test_achar
500 See @ref{ICHAR} for a discussion of converting between numerical values
501 and formatted string representations.
503 @item @emph{See also}:
504 @ref{CHAR}, @ref{IACHAR}, @ref{ICHAR}
511 @section @code{ACOS} --- Arccosine function
514 @cindex trigonometric function, cosine, inverse
515 @cindex cosine, inverse
518 @item @emph{Description}:
519 @code{ACOS(X)} computes the arccosine of @var{X} (inverse of @code{COS(X)}).
521 @item @emph{Standard}:
528 @code{RESULT = ACOS(X)}
530 @item @emph{Arguments}:
531 @multitable @columnfractions .15 .70
532 @item @var{X} @tab The type shall be @code{REAL(*)} with a magnitude that is
536 @item @emph{Return value}:
537 The return value is of type @code{REAL(*)} and it lies in the
538 range @math{ 0 \leq \acos(x) \leq \pi}. The kind type parameter
539 is the same as @var{X}.
541 @item @emph{Example}:
544 real(8) :: x = 0.866_8
546 end program test_acos
549 @item @emph{Specific names}:
550 @multitable @columnfractions .20 .20 .20 .25
551 @item Name @tab Argument @tab Return type @tab Standard
552 @item @code{DACOS(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab F77 and later
555 @item @emph{See also}:
556 Inverse function: @ref{COS}
563 @section @code{ACOSH} --- Hyperbolic arccosine function
566 @cindex area hyperbolic cosine
567 @cindex hyperbolic arccosine
568 @cindex hyperbolic function, cosine, inverse
569 @cindex cosine, hyperbolic, inverse
572 @item @emph{Description}:
573 @code{ACOSH(X)} computes the hyperbolic arccosine of @var{X} (inverse of
576 @item @emph{Standard}:
583 @code{RESULT = ACOSH(X)}
585 @item @emph{Arguments}:
586 @multitable @columnfractions .15 .70
587 @item @var{X} @tab The type shall be @code{REAL(*)} with a magnitude that is
588 greater or equal to one.
591 @item @emph{Return value}:
592 The return value is of type @code{REAL(*)} and it lies in the
593 range @math{0 \leq \acosh (x) \leq \infty}.
595 @item @emph{Example}:
598 REAL(8), DIMENSION(3) :: x = (/ 1.0, 2.0, 3.0 /)
603 @item @emph{Specific names}:
604 @multitable @columnfractions .20 .20 .20 .25
605 @item Name @tab Argument @tab Return type @tab Standard
606 @item @code{DACOSH(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU extension
609 @item @emph{See also}:
610 Inverse function: @ref{COSH}
616 @section @code{ADJUSTL} --- Left adjust a string
618 @cindex string, adjust left
619 @cindex adjust string
622 @item @emph{Description}:
623 @code{ADJUSTL(STR)} will left adjust a string by removing leading spaces.
624 Spaces are inserted at the end of the string as needed.
626 @item @emph{Standard}:
633 @code{RESULT = ADJUSTL(STR)}
635 @item @emph{Arguments}:
636 @multitable @columnfractions .15 .70
637 @item @var{STR} @tab The type shall be @code{CHARACTER}.
640 @item @emph{Return value}:
641 The return value is of type @code{CHARACTER} where leading spaces
642 are removed and the same number of spaces are inserted on the end
645 @item @emph{Example}:
648 character(len=20) :: str = ' gfortran'
651 end program test_adjustl
654 @item @emph{See also}:
655 @ref{ADJUSTR}, @ref{TRIM}
661 @section @code{ADJUSTR} --- Right adjust a string
663 @cindex string, adjust right
664 @cindex adjust string
667 @item @emph{Description}:
668 @code{ADJUSTR(STR)} will right adjust a string by removing trailing spaces.
669 Spaces are inserted at the start of the string as needed.
671 @item @emph{Standard}:
678 @code{RESULT = ADJUSTR(STR)}
680 @item @emph{Arguments}:
681 @multitable @columnfractions .15 .70
682 @item @var{STR} @tab The type shall be @code{CHARACTER}.
685 @item @emph{Return value}:
686 The return value is of type @code{CHARACTER} where trailing spaces
687 are removed and the same number of spaces are inserted at the start
690 @item @emph{Example}:
693 character(len=20) :: str = 'gfortran'
696 end program test_adjustr
699 @item @emph{See also}:
700 @ref{ADJUSTL}, @ref{TRIM}
706 @section @code{AIMAG} --- Imaginary part of complex number
711 @cindex complex numbers, imaginary part
714 @item @emph{Description}:
715 @code{AIMAG(Z)} yields the imaginary part of complex argument @code{Z}.
716 The @code{IMAG(Z)} and @code{IMAGPART(Z)} intrinsic functions are provided
717 for compatibility with @command{g77}, and their use in new code is
718 strongly discouraged.
720 @item @emph{Standard}:
721 F77 and later, has overloads that are GNU extensions
727 @code{RESULT = AIMAG(Z)}
729 @item @emph{Arguments}:
730 @multitable @columnfractions .15 .70
731 @item @var{Z} @tab The type of the argument shall be @code{COMPLEX(*)}.
734 @item @emph{Return value}:
735 The return value is of type real with the
736 kind type parameter of the argument.
738 @item @emph{Example}:
743 z4 = cmplx(1.e0_4, 0.e0_4)
744 z8 = cmplx(0.e0_8, 1.e0_8)
745 print *, aimag(z4), dimag(z8)
746 end program test_aimag
749 @item @emph{Specific names}:
750 @multitable @columnfractions .20 .20 .20 .25
751 @item Name @tab Argument @tab Return type @tab Standard
752 @item @code{DIMAG(Z)} @tab @code{COMPLEX(8) Z} @tab @code{REAL(8)} @tab GNU extension
753 @item @code{IMAG(Z)} @tab @code{COMPLEX(*) Z} @tab @code{REAL(*)} @tab GNU extension
754 @item @code{IMAGPART(Z)} @tab @code{COMPLEX(*) Z} @tab @code{REAL(*)} @tab GNU extension
761 @section @code{AINT} --- Truncate to a whole number
765 @cindex rounding, floor
768 @item @emph{Description}:
769 @code{AINT(X [, KIND])} truncates its argument to a whole number.
771 @item @emph{Standard}:
778 @code{RESULT = AINT(X [, KIND])}
780 @item @emph{Arguments}:
781 @multitable @columnfractions .15 .70
782 @item @var{X} @tab The type of the argument shall be @code{REAL(*)}.
783 @item @var{KIND} @tab (Optional) An @code{INTEGER(*)} initialization
784 expression indicating the kind parameter of
788 @item @emph{Return value}:
789 The return value is of type real with the kind type parameter of the
790 argument if the optional @var{KIND} is absent; otherwise, the kind
791 type parameter will be given by @var{KIND}. If the magnitude of
792 @var{X} is less than one, then @code{AINT(X)} returns zero. If the
793 magnitude is equal to or greater than one, then it returns the largest
794 whole number that does not exceed its magnitude. The sign is the same
795 as the sign of @var{X}.
797 @item @emph{Example}:
804 print *, aint(x4), dint(x8)
806 end program test_aint
809 @item @emph{Specific names}:
810 @multitable @columnfractions .20 .20 .20 .25
811 @item Name @tab Argument @tab Return type @tab Standard
812 @item @code{DINT(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab F77 and later
819 @section @code{ALARM} --- Execute a routine after a given delay
821 @cindex delayed execution
824 @item @emph{Description}:
825 @code{ALARM(SECONDS, HANDLER [, STATUS])} causes external subroutine @var{HANDLER}
826 to be executed after a delay of @var{SECONDS} by using @code{alarm(2)} to
827 set up a signal and @code{signal(2)} to catch it. If @var{STATUS} is
828 supplied, it will be returned with the number of seconds remaining until
829 any previously scheduled alarm was due to be delivered, or zero if there
830 was no previously scheduled alarm.
832 @item @emph{Standard}:
839 @code{CALL ALARM(SECONDS, HANDLER [, STATUS])}
841 @item @emph{Arguments}:
842 @multitable @columnfractions .15 .70
843 @item @var{SECONDS} @tab The type of the argument shall be a scalar
844 @code{INTEGER}. It is @code{INTENT(IN)}.
845 @item @var{HANDLER} @tab Signal handler (@code{INTEGER FUNCTION} or
846 @code{SUBROUTINE}) or dummy/global @code{INTEGER} scalar. The scalar
847 values may be either @code{SIG_IGN=1} to ignore the alarm generated
848 or @code{SIG_DFL=0} to set the default action. It is @code{INTENT(IN)}.
849 @item @var{STATUS} @tab (Optional) @var{STATUS} shall be a scalar
850 variable of the default @code{INTEGER} kind. It is @code{INTENT(OUT)}.
853 @item @emph{Example}:
856 external handler_print
858 call alarm (3, handler_print, i)
861 end program test_alarm
863 This will cause the external routine @var{handler_print} to be called
870 @section @code{ALL} --- All values in @var{MASK} along @var{DIM} are true
872 @cindex array, apply condition
873 @cindex array, condition testing
876 @item @emph{Description}:
877 @code{ALL(MASK [, DIM])} determines if all the values are true in @var{MASK}
878 in the array along dimension @var{DIM}.
880 @item @emph{Standard}:
884 Transformational function
887 @code{RESULT = ALL(MASK [, DIM])}
889 @item @emph{Arguments}:
890 @multitable @columnfractions .15 .70
891 @item @var{MASK} @tab The type of the argument shall be @code{LOGICAL(*)} and
892 it shall not be scalar.
893 @item @var{DIM} @tab (Optional) @var{DIM} shall be a scalar integer
894 with a value that lies between one and the rank of @var{MASK}.
897 @item @emph{Return value}:
898 @code{ALL(MASK)} returns a scalar value of type @code{LOGICAL(*)} where
899 the kind type parameter is the same as the kind type parameter of
900 @var{MASK}. If @var{DIM} is present, then @code{ALL(MASK, DIM)} returns
901 an array with the rank of @var{MASK} minus 1. The shape is determined from
902 the shape of @var{MASK} where the @var{DIM} dimension is elided.
906 @code{ALL(MASK)} is true if all elements of @var{MASK} are true.
907 It also is true if @var{MASK} has zero size; otherwise, it is false.
909 If the rank of @var{MASK} is one, then @code{ALL(MASK,DIM)} is equivalent
910 to @code{ALL(MASK)}. If the rank is greater than one, then @code{ALL(MASK,DIM)}
911 is determined by applying @code{ALL} to the array sections.
914 @item @emph{Example}:
918 l = all((/.true., .true., .true./))
923 integer a(2,3), b(2,3)
927 print *, all(a .eq. b, 1)
928 print *, all(a .eq. b, 2)
929 end subroutine section
937 @section @code{ALLOCATED} --- Status of an allocatable entity
939 @cindex allocation, status
942 @item @emph{Description}:
943 @code{ALLOCATED(X)} checks the status of whether @var{X} is allocated.
945 @item @emph{Standard}:
952 @code{RESULT = ALLOCATED(X)}
954 @item @emph{Arguments}:
955 @multitable @columnfractions .15 .70
956 @item @var{X} @tab The argument shall be an @code{ALLOCATABLE} array.
959 @item @emph{Return value}:
960 The return value is a scalar @code{LOGICAL} with the default logical
961 kind type parameter. If @var{X} is allocated, @code{ALLOCATED(X)}
962 is @code{.TRUE.}; otherwise, it returns @code{.FALSE.}
964 @item @emph{Example}:
966 program test_allocated
968 real(4), allocatable :: x(:)
969 if (allocated(x) .eqv. .false.) allocate(x(i))
970 end program test_allocated
977 @section @code{AND} --- Bitwise logical AND
979 @cindex bitwise logical and
980 @cindex logical and, bitwise
983 @item @emph{Description}:
984 Bitwise logical @code{AND}.
986 This intrinsic routine is provided for backwards compatibility with
987 GNU Fortran 77. For integer arguments, programmers should consider
988 the use of the @ref{IAND} intrinsic defined by the Fortran standard.
990 @item @emph{Standard}:
997 @code{RESULT = AND(I, J)}
999 @item @emph{Arguments}:
1000 @multitable @columnfractions .15 .70
1001 @item @var{I} @tab The type shall be either @code{INTEGER(*)} or @code{LOGICAL}.
1002 @item @var{J} @tab The type shall be either @code{INTEGER(*)} or @code{LOGICAL}.
1005 @item @emph{Return value}:
1006 The return type is either @code{INTEGER(*)} or @code{LOGICAL} after
1007 cross-promotion of the arguments.
1009 @item @emph{Example}:
1012 LOGICAL :: T = .TRUE., F = .FALSE.
1014 DATA a / Z'F' /, b / Z'3' /
1016 WRITE (*,*) AND(T, T), AND(T, F), AND(F, T), AND(F, F)
1017 WRITE (*,*) AND(a, b)
1021 @item @emph{See also}:
1022 F95 elemental function: @ref{IAND}
1028 @section @code{ANINT} --- Nearest whole number
1032 @cindex rounding, ceiling
1035 @item @emph{Description}:
1036 @code{ANINT(X [, KIND])} rounds its argument to the nearest whole number.
1038 @item @emph{Standard}:
1044 @item @emph{Syntax}:
1045 @code{RESULT = ANINT(X [, KIND])}
1047 @item @emph{Arguments}:
1048 @multitable @columnfractions .15 .70
1049 @item @var{X} @tab The type of the argument shall be @code{REAL(*)}.
1050 @item @var{KIND} @tab (Optional) An @code{INTEGER(*)} initialization
1051 expression indicating the kind parameter of
1055 @item @emph{Return value}:
1056 The return value is of type real with the kind type parameter of the
1057 argument if the optional @var{KIND} is absent; otherwise, the kind
1058 type parameter will be given by @var{KIND}. If @var{X} is greater than
1059 zero, then @code{ANINT(X)} returns @code{AINT(X+0.5)}. If @var{X} is
1060 less than or equal to zero, then it returns @code{AINT(X-0.5)}.
1062 @item @emph{Example}:
1069 print *, anint(x4), dnint(x8)
1071 end program test_anint
1074 @item @emph{Specific names}:
1075 @multitable @columnfractions .20 .20 .20 .25
1076 @item Name @tab Argument @tab Return type @tab Standard
1077 @item @code{DNINT(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab F77 and later
1084 @section @code{ANY} --- Any value in @var{MASK} along @var{DIM} is true
1086 @cindex array, apply condition
1087 @cindex array, condition testing
1090 @item @emph{Description}:
1091 @code{ANY(MASK [, DIM])} determines if any of the values in the logical array
1092 @var{MASK} along dimension @var{DIM} are @code{.TRUE.}.
1094 @item @emph{Standard}:
1098 Transformational function
1100 @item @emph{Syntax}:
1101 @code{RESULT = ANY(MASK [, DIM])}
1103 @item @emph{Arguments}:
1104 @multitable @columnfractions .15 .70
1105 @item @var{MASK} @tab The type of the argument shall be @code{LOGICAL(*)} and
1106 it shall not be scalar.
1107 @item @var{DIM} @tab (Optional) @var{DIM} shall be a scalar integer
1108 with a value that lies between one and the rank of @var{MASK}.
1111 @item @emph{Return value}:
1112 @code{ANY(MASK)} returns a scalar value of type @code{LOGICAL(*)} where
1113 the kind type parameter is the same as the kind type parameter of
1114 @var{MASK}. If @var{DIM} is present, then @code{ANY(MASK, DIM)} returns
1115 an array with the rank of @var{MASK} minus 1. The shape is determined from
1116 the shape of @var{MASK} where the @var{DIM} dimension is elided.
1120 @code{ANY(MASK)} is true if any element of @var{MASK} is true;
1121 otherwise, it is false. It also is false if @var{MASK} has zero size.
1123 If the rank of @var{MASK} is one, then @code{ANY(MASK,DIM)} is equivalent
1124 to @code{ANY(MASK)}. If the rank is greater than one, then @code{ANY(MASK,DIM)}
1125 is determined by applying @code{ANY} to the array sections.
1128 @item @emph{Example}:
1132 l = any((/.true., .true., .true./))
1137 integer a(2,3), b(2,3)
1141 print *, any(a .eq. b, 1)
1142 print *, any(a .eq. b, 2)
1143 end subroutine section
1144 end program test_any
1151 @section @code{ASIN} --- Arcsine function
1154 @cindex trigonometric function, sine, inverse
1155 @cindex sine, inverse
1158 @item @emph{Description}:
1159 @code{ASIN(X)} computes the arcsine of its @var{X} (inverse of @code{SIN(X)}).
1161 @item @emph{Standard}:
1167 @item @emph{Syntax}:
1168 @code{RESULT = ASIN(X)}
1170 @item @emph{Arguments}:
1171 @multitable @columnfractions .15 .70
1172 @item @var{X} @tab The type shall be @code{REAL(*)}, and a magnitude that is
1176 @item @emph{Return value}:
1177 The return value is of type @code{REAL(*)} and it lies in the
1178 range @math{-\pi / 2 \leq \asin (x) \leq \pi / 2}. The kind type
1179 parameter is the same as @var{X}.
1181 @item @emph{Example}:
1184 real(8) :: x = 0.866_8
1186 end program test_asin
1189 @item @emph{Specific names}:
1190 @multitable @columnfractions .20 .20 .20 .25
1191 @item Name @tab Argument @tab Return type @tab Standard
1192 @item @code{DASIN(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab F77 and later
1195 @item @emph{See also}:
1196 Inverse function: @ref{SIN}
1203 @section @code{ASINH} --- Hyperbolic arcsine function
1206 @cindex area hyperbolic sine
1207 @cindex hyperbolic arcsine
1208 @cindex hyperbolic function, sine, inverse
1209 @cindex sine, hyperbolic, inverse
1212 @item @emph{Description}:
1213 @code{ASINH(X)} computes the hyperbolic arcsine of @var{X} (inverse of @code{SINH(X)}).
1215 @item @emph{Standard}:
1221 @item @emph{Syntax}:
1222 @code{RESULT = ASINH(X)}
1224 @item @emph{Arguments}:
1225 @multitable @columnfractions .15 .70
1226 @item @var{X} @tab The type shall be @code{REAL(*)}, with @var{X} a real number.
1229 @item @emph{Return value}:
1230 The return value is of type @code{REAL(*)} and it lies in the
1231 range @math{-\infty \leq \asinh (x) \leq \infty}.
1233 @item @emph{Example}:
1236 REAL(8), DIMENSION(3) :: x = (/ -1.0, 0.0, 1.0 /)
1237 WRITE (*,*) ASINH(x)
1241 @item @emph{Specific names}:
1242 @multitable @columnfractions .20 .20 .20 .25
1243 @item Name @tab Argument @tab Return type @tab Standard
1244 @item @code{DASINH(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU extension.
1247 @item @emph{See also}:
1248 Inverse function: @ref{SINH}
1254 @section @code{ASSOCIATED} --- Status of a pointer or pointer/target pair
1256 @cindex pointer, status
1257 @cindex association status
1260 @item @emph{Description}:
1261 @code{ASSOCIATED(PTR [, TGT])} determines the status of the pointer @var{PTR}
1262 or if @var{PTR} is associated with the target @var{TGT}.
1264 @item @emph{Standard}:
1270 @item @emph{Syntax}:
1271 @code{RESULT = ASSOCIATED(PTR [, TGT])}
1273 @item @emph{Arguments}:
1274 @multitable @columnfractions .15 .70
1275 @item @var{PTR} @tab @var{PTR} shall have the @code{POINTER} attribute and
1276 it can be of any type.
1277 @item @var{TGT} @tab (Optional) @var{TGT} shall be a @code{POINTER} or
1278 a @code{TARGET}. It must have the same type, kind type parameter, and
1279 array rank as @var{PTR}.
1281 The status of neither @var{PTR} nor @var{TGT} can be undefined.
1283 @item @emph{Return value}:
1284 @code{ASSOCIATED(PTR)} returns a scalar value of type @code{LOGICAL(4)}.
1285 There are several cases:
1287 @item (A) If the optional @var{TGT} is not present, then @code{ASSOCIATED(PTR)}
1288 is true if @var{PTR} is associated with a target; otherwise, it returns false.
1289 @item (B) If @var{TGT} is present and a scalar target, the result is true if
1291 is not a 0 sized storage sequence and the target associated with @var{PTR}
1292 occupies the same storage units. If @var{PTR} is disassociated, then the
1294 @item (C) If @var{TGT} is present and an array target, the result is true if
1295 @var{TGT} and @var{PTR} have the same shape, are not 0 sized arrays, are
1296 arrays whose elements are not 0 sized storage sequences, and @var{TGT} and
1297 @var{PTR} occupy the same storage units in array element order.
1298 As in case(B), the result is false, if @var{PTR} is disassociated.
1299 @item (D) If @var{TGT} is present and an scalar pointer, the result is true if
1300 target associated with @var{PTR} and the target associated with @var{TGT}
1301 are not 0 sized storage sequences and occupy the same storage units.
1302 The result is false, if either @var{TGT} or @var{PTR} is disassociated.
1303 @item (E) If @var{TGT} is present and an array pointer, the result is true if
1304 target associated with @var{PTR} and the target associated with @var{TGT}
1305 have the same shape, are not 0 sized arrays, are arrays whose elements are
1306 not 0 sized storage sequences, and @var{TGT} and @var{PTR} occupy the same
1307 storage units in array element order.
1308 The result is false, if either @var{TGT} or @var{PTR} is disassociated.
1311 @item @emph{Example}:
1313 program test_associated
1315 real, target :: tgt(2) = (/1., 2./)
1316 real, pointer :: ptr(:)
1318 if (associated(ptr) .eqv. .false.) call abort
1319 if (associated(ptr,tgt) .eqv. .false.) call abort
1320 end program test_associated
1323 @item @emph{See also}:
1330 @section @code{ATAN} --- Arctangent function
1333 @cindex trigonometric function, tangent, inverse
1334 @cindex tangent, inverse
1337 @item @emph{Description}:
1338 @code{ATAN(X)} computes the arctangent of @var{X}.
1340 @item @emph{Standard}:
1346 @item @emph{Syntax}:
1347 @code{RESULT = ATAN(X)}
1349 @item @emph{Arguments}:
1350 @multitable @columnfractions .15 .70
1351 @item @var{X} @tab The type shall be @code{REAL(*)}.
1354 @item @emph{Return value}:
1355 The return value is of type @code{REAL(*)} and it lies in the
1356 range @math{ - \pi / 2 \leq \atan (x) \leq \pi / 2}.
1358 @item @emph{Example}:
1361 real(8) :: x = 2.866_8
1363 end program test_atan
1366 @item @emph{Specific names}:
1367 @multitable @columnfractions .20 .20 .20 .25
1368 @item Name @tab Argument @tab Return type @tab Standard
1369 @item @code{DATAN(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab F77 and later
1372 @item @emph{See also}:
1373 Inverse function: @ref{TAN}
1380 @section @code{ATAN2} --- Arctangent function
1383 @cindex trigonometric function, tangent, inverse
1384 @cindex tangent, inverse
1387 @item @emph{Description}:
1388 @code{ATAN2(Y,X)} computes the arctangent of the complex number
1391 @item @emph{Standard}:
1397 @item @emph{Syntax}:
1398 @code{RESULT = ATAN2(Y,X)}
1400 @item @emph{Arguments}:
1401 @multitable @columnfractions .15 .70
1402 @item @var{Y} @tab The type shall be @code{REAL(*)}.
1403 @item @var{X} @tab The type and kind type parameter shall be the same as @var{Y}.
1404 If @var{Y} is zero, then @var{X} must be nonzero.
1407 @item @emph{Return value}:
1408 The return value has the same type and kind type parameter as @var{Y}.
1409 It is the principal value of the complex number @math{X + i Y}. If
1410 @var{X} is nonzero, then it lies in the range @math{-\pi \le \atan (x) \leq \pi}.
1411 The sign is positive if @var{Y} is positive. If @var{Y} is zero, then
1412 the return value is zero if @var{X} is positive and @math{\pi} if @var{X}
1413 is negative. Finally, if @var{X} is zero, then the magnitude of the result
1416 @item @emph{Example}:
1419 real(4) :: x = 1.e0_4, y = 0.5e0_4
1421 end program test_atan2
1424 @item @emph{Specific names}:
1425 @multitable @columnfractions .20 .20 .20 .25
1426 @item Name @tab Argument @tab Return type @tab Standard
1427 @item @code{DATAN2(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab F77 and later
1434 @section @code{ATANH} --- Hyperbolic arctangent function
1437 @cindex area hyperbolic tangent
1438 @cindex hyperbolic arctangent
1439 @cindex hyperbolic function, tangent, inverse
1440 @cindex tangent, hyperbolic, inverse
1443 @item @emph{Description}:
1444 @code{ATANH(X)} computes the hyperbolic arctangent of @var{X} (inverse
1447 @item @emph{Standard}:
1453 @item @emph{Syntax}:
1454 @code{RESULT = ATANH(X)}
1456 @item @emph{Arguments}:
1457 @multitable @columnfractions .15 .70
1458 @item @var{X} @tab The type shall be @code{REAL(*)} with a magnitude
1459 that is less than or equal to one.
1462 @item @emph{Return value}:
1463 The return value is of type @code{REAL(*)} and it lies in the
1464 range @math{-\infty \leq \atanh(x) \leq \infty}.
1466 @item @emph{Example}:
1469 REAL, DIMENSION(3) :: x = (/ -1.0, 0.0, 1.0 /)
1470 WRITE (*,*) ATANH(x)
1474 @item @emph{Specific names}:
1475 @multitable @columnfractions .20 .20 .20 .25
1476 @item Name @tab Argument @tab Return type @tab Standard
1477 @item @code{DATANH(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU extension
1480 @item @emph{See also}:
1481 Inverse function: @ref{TANH}
1487 @section @code{BESJ0} --- Bessel function of the first kind of order 0
1490 @cindex Bessel function, first kind
1493 @item @emph{Description}:
1494 @code{BESJ0(X)} computes the Bessel function of the first kind of order 0
1497 @item @emph{Standard}:
1503 @item @emph{Syntax}:
1504 @code{RESULT = BESJ0(X)}
1506 @item @emph{Arguments}:
1507 @multitable @columnfractions .15 .70
1508 @item @var{X} @tab The type shall be @code{REAL(*)}, and it shall be scalar.
1511 @item @emph{Return value}:
1512 The return value is of type @code{REAL(*)} and it lies in the
1513 range @math{ - 0.4027... \leq Bessel (0,x) \leq 1}.
1515 @item @emph{Example}:
1518 real(8) :: x = 0.0_8
1520 end program test_besj0
1523 @item @emph{Specific names}:
1524 @multitable @columnfractions .20 .20 .20 .25
1525 @item Name @tab Argument @tab Return type @tab Standard
1526 @item @code{DBESJ0(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU extension
1533 @section @code{BESJ1} --- Bessel function of the first kind of order 1
1536 @cindex Bessel function, first kind
1539 @item @emph{Description}:
1540 @code{BESJ1(X)} computes the Bessel function of the first kind of order 1
1543 @item @emph{Standard}:
1549 @item @emph{Syntax}:
1550 @code{RESULT = BESJ1(X)}
1552 @item @emph{Arguments}:
1553 @multitable @columnfractions .15 .70
1554 @item @var{X} @tab The type shall be @code{REAL(*)}, and it shall be scalar.
1557 @item @emph{Return value}:
1558 The return value is of type @code{REAL(*)} and it lies in the
1559 range @math{ - 0.5818... \leq Bessel (0,x) \leq 0.5818 }.
1561 @item @emph{Example}:
1564 real(8) :: x = 1.0_8
1566 end program test_besj1
1569 @item @emph{Specific names}:
1570 @multitable @columnfractions .20 .20 .20 .25
1571 @item Name @tab Argument @tab Return type @tab Standard
1572 @item @code{DBESJ1(X)}@tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU extension
1579 @section @code{BESJN} --- Bessel function of the first kind
1582 @cindex Bessel function, first kind
1585 @item @emph{Description}:
1586 @code{BESJN(N, X)} computes the Bessel function of the first kind of order
1589 If both arguments are arrays, their ranks and shapes shall conform.
1591 @item @emph{Standard}:
1597 @item @emph{Syntax}:
1598 @code{RESULT = BESJN(N, X)}
1600 @item @emph{Arguments}:
1601 @multitable @columnfractions .15 .70
1602 @item @var{N} @tab Shall be a scalar or an array of type @code{INTEGER(*)}.
1603 @item @var{X} @tab Shall be a scalar or an array of type @code{REAL(*)}.
1606 @item @emph{Return value}:
1607 The return value is a scalar of type @code{REAL(*)}.
1609 @item @emph{Example}:
1612 real(8) :: x = 1.0_8
1614 end program test_besjn
1617 @item @emph{Specific names}:
1618 @multitable @columnfractions .20 .20 .20 .25
1619 @item Name @tab Argument @tab Return type @tab Standard
1620 @item @code{DBESJN(X)} @tab @code{INTEGER(*) N} @tab @code{REAL(8)} @tab GNU extension
1621 @item @tab @code{REAL(8) X} @tab @tab
1628 @section @code{BESY0} --- Bessel function of the second kind of order 0
1631 @cindex Bessel function, second kind
1634 @item @emph{Description}:
1635 @code{BESY0(X)} computes the Bessel function of the second kind of order 0
1638 @item @emph{Standard}:
1644 @item @emph{Syntax}:
1645 @code{RESULT = BESY0(X)}
1647 @item @emph{Arguments}:
1648 @multitable @columnfractions .15 .70
1649 @item @var{X} @tab The type shall be @code{REAL(*)}, and it shall be scalar.
1652 @item @emph{Return value}:
1653 The return value is a scalar of type @code{REAL(*)}.
1655 @item @emph{Example}:
1658 real(8) :: x = 0.0_8
1660 end program test_besy0
1663 @item @emph{Specific names}:
1664 @multitable @columnfractions .20 .20 .20 .25
1665 @item Name @tab Argument @tab Return type @tab Standard
1666 @item @code{DBESY0(X)}@tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU extension
1673 @section @code{BESY1} --- Bessel function of the second kind of order 1
1676 @cindex Bessel function, second kind
1679 @item @emph{Description}:
1680 @code{BESY1(X)} computes the Bessel function of the second kind of order 1
1683 @item @emph{Standard}:
1689 @item @emph{Syntax}:
1690 @code{RESULT = BESY1(X)}
1692 @item @emph{Arguments}:
1693 @multitable @columnfractions .15 .70
1694 @item @var{X} @tab The type shall be @code{REAL(*)}, and it shall be scalar.
1697 @item @emph{Return value}:
1698 The return value is a scalar of type @code{REAL(*)}.
1700 @item @emph{Example}:
1703 real(8) :: x = 1.0_8
1705 end program test_besy1
1708 @item @emph{Specific names}:
1709 @multitable @columnfractions .20 .20 .20 .25
1710 @item Name @tab Argument @tab Return type @tab Standard
1711 @item @code{DBESY1(X)}@tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU extension
1718 @section @code{BESYN} --- Bessel function of the second kind
1721 @cindex Bessel function, second kind
1724 @item @emph{Description}:
1725 @code{BESYN(N, X)} computes the Bessel function of the second kind of order
1728 If both arguments are arrays, their ranks and shapes shall conform.
1730 @item @emph{Standard}:
1736 @item @emph{Syntax}:
1737 @code{RESULT = BESYN(N, X)}
1739 @item @emph{Arguments}:
1740 @multitable @columnfractions .15 .70
1741 @item @var{N} @tab Shall be a scalar or an array of type @code{INTEGER(*)}.
1742 @item @var{X} @tab Shall be a scalar or an array of type @code{REAL(*)}.
1745 @item @emph{Return value}:
1746 The return value is a scalar of type @code{REAL(*)}.
1748 @item @emph{Example}:
1751 real(8) :: x = 1.0_8
1753 end program test_besyn
1756 @item @emph{Specific names}:
1757 @multitable @columnfractions .20 .20 .20 .25
1758 @item Name @tab Argument @tab Return type @tab Standard
1759 @item @code{DBESYN(N,X)} @tab @code{INTEGER(*) N} @tab @code{REAL(8)} @tab GNU extension
1760 @item @tab @code{REAL(8) X} @tab @tab
1767 @section @code{BIT_SIZE} --- Bit size inquiry function
1769 @cindex bits, number of
1770 @cindex size of a variable, in bits
1773 @item @emph{Description}:
1774 @code{BIT_SIZE(I)} returns the number of bits (integer precision plus sign bit)
1775 represented by the type of @var{I}.
1777 @item @emph{Standard}:
1783 @item @emph{Syntax}:
1784 @code{RESULT = BIT_SIZE(I)}
1786 @item @emph{Arguments}:
1787 @multitable @columnfractions .15 .70
1788 @item @var{I} @tab The type shall be @code{INTEGER(*)}.
1791 @item @emph{Return value}:
1792 The return value is of type @code{INTEGER(*)}
1794 @item @emph{Example}:
1796 program test_bit_size
1801 end program test_bit_size
1808 @section @code{BTEST} --- Bit test function
1810 @cindex bits, testing
1813 @item @emph{Description}:
1814 @code{BTEST(I,POS)} returns logical @code{.TRUE.} if the bit at @var{POS}
1817 @item @emph{Standard}:
1823 @item @emph{Syntax}:
1824 @code{RESULT = BTEST(I, POS)}
1826 @item @emph{Arguments}:
1827 @multitable @columnfractions .15 .70
1828 @item @var{I} @tab The type shall be @code{INTEGER(*)}.
1829 @item @var{POS} @tab The type shall be @code{INTEGER(*)}.
1832 @item @emph{Return value}:
1833 The return value is of type @code{LOGICAL}
1835 @item @emph{Example}:
1838 integer :: i = 32768 + 1024 + 64
1842 bool = btest(i, pos)
1845 end program test_btest
1851 @section @code{C_ASSOCIATED} --- Status of a C pointer
1852 @fnindex C_ASSOCIATED
1853 @cindex association status, C pointer
1854 @cindex pointer, C association status
1857 @item @emph{Description}:
1858 @code{C_ASSOICATED(c_prt1[, c_ptr2])} determines the status of the C pointer @var{c_ptr1}
1859 or if @var{c_ptr1} is associated with the target @var{c_ptr2}.
1861 @item @emph{Standard}:
1867 @item @emph{Syntax}:
1868 @code{RESULT = C_ASSOICATED(c_prt1[, c_ptr2])}
1870 @item @emph{Arguments}:
1871 @multitable @columnfractions .15 .70
1872 @item @var{c_ptr1} @tab Scalar of the type @code{C_PTR} or @code{C_FUNPTR}.
1873 @item @var{c_ptr2} @tab (Optional) Scalar of the same type as @var{c_ptr1}.
1876 @item @emph{Return value}:
1877 The return value is of type @code{LOGICAL}; it is @code{.false.} if either
1878 @var{c_ptr1} is a C NULL pointer or if @var{c_ptr1} and @var{c_ptr2}
1879 point to different addresses.
1881 @item @emph{Example}:
1883 subroutine association_test(a,b)
1884 use iso_c_binding, only: c_associated, c_loc, c_ptr
1888 if(c_associated(b, c_loc(a))) &
1889 stop 'b and a do not point to same target'
1890 end subroutine association_test
1893 @item @emph{See also}:
1894 @ref{C_LOC}, @ref{C_FUNLOC}
1899 @section @code{C_FUNLOC} --- Obtain the C address of a procedure
1901 @cindex pointer, C address of procedures
1904 @item @emph{Description}:
1905 @code{C_FUNLOC(x)} determines the C address of the argument.
1907 @item @emph{Standard}:
1913 @item @emph{Syntax}:
1914 @code{RESULT = C_FUNLOC(x)}
1916 @item @emph{Arguments}:
1917 @multitable @columnfractions .15 .70
1918 @item @var{x} @tab Interoperable function or pointer to such function.
1921 @item @emph{Return value}:
1922 The return value is of type @code{C_FUNPTR} and contains the C address
1925 @item @emph{Example}:
1931 subroutine sub(a) bind(c)
1941 subroutine my_routine(p) bind(c,name='myC_func')
1943 type(c_funptr), intent(in) :: p
1946 call my_routine(c_funloc(sub))
1950 @item @emph{See also}:
1951 @ref{C_ASSOCIATED}, @ref{C_LOC}, @ref{C_F_POINTER}, @ref{C_F_PROCPOINTER}
1955 @node C_F_PROCPOINTER
1956 @section @code{C_F_PROCPOINTER} --- Convert C into Fortran procedure pointer
1957 @fnindex C_F_PROCPOINTER
1958 @cindex pointer, C address of pointers
1961 @item @emph{Description}:
1962 @code{C_F_PROCPOINTER(cptr, fptr)} Assign the target of the C function pointer
1963 @var{cptr} to the Fortran procedure pointer @var{fptr}.
1965 Note: Due to the currently lacking support of procedure pointers in GNU Fortran
1966 this function is not fully operable.
1968 @item @emph{Standard}:
1974 @item @emph{Syntax}:
1975 @code{CALL C_F_PROCPOINTER(cptr, fptr)}
1977 @item @emph{Arguments}:
1978 @multitable @columnfractions .15 .70
1979 @item @var{cptr} @tab scalar of the type @code{C_FUNPTR}. It is
1981 @item @var{fptr} @tab procedure pointer interoperable with @var{cptr}. It is
1985 @item @emph{Example}:
1993 real(c_float), intent(in) :: a
1994 real(c_float) :: func
1998 function getIterFunc() bind(c,name="getIterFunc")
2000 type(c_funptr) :: getIterFunc
2003 type(c_funptr) :: cfunptr
2004 procedure(func), pointer :: myFunc
2005 cfunptr = getIterFunc()
2006 call c_f_procpointer(cfunptr, myFunc)
2010 @item @emph{See also}:
2011 @ref{C_LOC}, @ref{C_F_POINTER}
2016 @section @code{C_F_POINTER} --- Convert C into Fortran pointer
2017 @fnindex C_F_POINTER
2018 @cindex pointer, convert C to Fortran
2021 @item @emph{Description}:
2022 @code{C_F_POINTER(cptr, fptr[, shape])} Assign the target the C pointer
2023 @var{cptr} to the Fortran pointer @var{fptr} and specify its
2026 @item @emph{Standard}:
2032 @item @emph{Syntax}:
2033 @code{CALL C_F_POINTER(cptr, fptr[, shape])}
2035 @item @emph{Arguments}:
2036 @multitable @columnfractions .15 .70
2037 @item @var{cptr} @tab scalar of the type @code{C_PTR}. It is
2039 @item @var{fptr} @tab pointer interoperable with @var{cptr}. It is
2041 @item @var{shape} @tab (Optional) Rank-one array of type @code{INTEGER}
2042 with @code{INTENT(IN)}. It shall be present
2043 if and only if @var{fptr} is an array. The size
2044 must be equal to the rank of @var{fptr}.
2047 @item @emph{Example}:
2053 subroutine my_routine(p) bind(c,name='myC_func')
2055 type(c_ptr), intent(out) :: p
2059 real,pointer :: a(:)
2060 call my_routine(cptr)
2061 call c_f_pointer(cptr, a, [12])
2065 @item @emph{See also}:
2066 @ref{C_LOC}, @ref{C_F_PROCPOINTER}
2071 @section @code{C_LOC} --- Obtain the C address of an object
2073 @cindex procedure pointer, convert C to Fortran
2076 @item @emph{Description}:
2077 @code{C_LOC(x)} determines the C address of the argument.
2079 @item @emph{Standard}:
2085 @item @emph{Syntax}:
2086 @code{RESULT = C_LOC(x)}
2088 @item @emph{Arguments}:
2089 @multitable @columnfractions .15 .70
2090 @item @var{x} @tab Associated scalar pointer or interoperable scalar
2091 or allocated allocatable variable with @code{TARGET}
2095 @item @emph{Return value}:
2096 The return value is of type @code{C_PTR} and contains the C address
2099 @item @emph{Example}:
2101 subroutine association_test(a,b)
2102 use iso_c_binding, only: c_associated, c_loc, c_ptr
2106 if(c_associated(b, c_loc(a))) &
2107 stop 'b and a do not point to same target'
2108 end subroutine association_test
2111 @item @emph{See also}:
2112 @ref{C_ASSOCIATED}, @ref{C_FUNLOC}, @ref{C_F_POINTER}, @ref{C_F_PROCPOINTER}
2117 @section @code{CEILING} --- Integer ceiling function
2120 @cindex rounding, ceiling
2123 @item @emph{Description}:
2124 @code{CEILING(X)} returns the least integer greater than or equal to @var{X}.
2126 @item @emph{Standard}:
2132 @item @emph{Syntax}:
2133 @code{RESULT = CEILING(X [, KIND])}
2135 @item @emph{Arguments}:
2136 @multitable @columnfractions .15 .70
2137 @item @var{X} @tab The type shall be @code{REAL(*)}.
2138 @item @var{KIND} @tab (Optional) An @code{INTEGER(*)} initialization
2139 expression indicating the kind parameter of
2143 @item @emph{Return value}:
2144 The return value is of type @code{INTEGER(KIND)}
2146 @item @emph{Example}:
2148 program test_ceiling
2151 print *, ceiling(x) ! returns 64
2152 print *, ceiling(y) ! returns -63
2153 end program test_ceiling
2156 @item @emph{See also}:
2157 @ref{FLOOR}, @ref{NINT}
2164 @section @code{CHAR} --- Character conversion function
2166 @cindex conversion, to character
2169 @item @emph{Description}:
2170 @code{CHAR(I [, KIND])} returns the character represented by the integer @var{I}.
2172 @item @emph{Standard}:
2178 @item @emph{Syntax}:
2179 @code{RESULT = CHAR(I [, KIND])}
2181 @item @emph{Arguments}:
2182 @multitable @columnfractions .15 .70
2183 @item @var{I} @tab The type shall be @code{INTEGER(*)}.
2184 @item @var{KIND} @tab (Optional) An @code{INTEGER(*)} initialization
2185 expression indicating the kind parameter of
2189 @item @emph{Return value}:
2190 The return value is of type @code{CHARACTER(1)}
2192 @item @emph{Example}:
2198 print *, i, c ! returns 'J'
2199 end program test_char
2203 See @ref{ICHAR} for a discussion of converting between numerical values
2204 and formatted string representations.
2206 @item @emph{See also}:
2207 @ref{ACHAR}, @ref{IACHAR}, @ref{ICHAR}
2214 @section @code{CHDIR} --- Change working directory
2216 @cindex system, working directory
2219 @item @emph{Description}:
2220 Change current working directory to a specified path.
2222 This intrinsic is provided in both subroutine and function forms; however,
2223 only one form can be used in any given program unit.
2225 @item @emph{Standard}:
2229 Subroutine, function
2231 @item @emph{Syntax}:
2232 @multitable @columnfractions .80
2233 @item @code{CALL CHDIR(NAME [, STATUS])}
2234 @item @code{STATUS = CHDIR(NAME)}
2237 @item @emph{Arguments}:
2238 @multitable @columnfractions .15 .70
2239 @item @var{NAME} @tab The type shall be @code{CHARACTER(*)} and shall
2240 specify a valid path within the file system.
2241 @item @var{STATUS} @tab (Optional) @code{INTEGER} status flag of the default
2242 kind. Returns 0 on success, and a system specific
2243 and nonzero error code otherwise.
2246 @item @emph{Example}:
2249 CHARACTER(len=255) :: path
2251 WRITE(*,*) TRIM(path)
2254 WRITE(*,*) TRIM(path)
2258 @item @emph{See also}:
2265 @section @code{CHMOD} --- Change access permissions of files
2267 @cindex file system, change access mode
2270 @item @emph{Description}:
2271 @code{CHMOD} changes the permissions of a file. This function invokes
2272 @code{/bin/chmod} and might therefore not work on all platforms.
2274 This intrinsic is provided in both subroutine and function forms; however,
2275 only one form can be used in any given program unit.
2277 @item @emph{Standard}:
2281 Subroutine, function
2283 @item @emph{Syntax}:
2284 @multitable @columnfractions .80
2285 @item @code{CALL CHMOD(NAME, MODE[, STATUS])}
2286 @item @code{STATUS = CHMOD(NAME, MODE)}
2289 @item @emph{Arguments}:
2290 @multitable @columnfractions .15 .70
2291 @item @var{NAME} @tab Scalar @code{CHARACTER} with the file name.
2292 Trailing blanks are ignored unless the character @code{achar(0)} is
2293 present, then all characters up to and excluding @code{achar(0)} are
2294 used as the file name.
2296 @item @var{MODE} @tab Scalar @code{CHARACTER} giving the file permission.
2297 @var{MODE} uses the same syntax as the @var{MODE} argument of
2300 @item @var{STATUS} @tab (optional) scalar @code{INTEGER}, which is
2301 @code{0} on success and nonzero otherwise.
2304 @item @emph{Return value}:
2305 In either syntax, @var{STATUS} is set to @code{0} on success and nonzero
2308 @item @emph{Example}:
2309 @code{CHMOD} as subroutine
2314 call chmod('test.dat','u+x',status)
2315 print *, 'Status: ', status
2316 end program chmod_test
2318 @code{CHMOD} as function:
2323 status = chmod('test.dat','u+x')
2324 print *, 'Status: ', status
2325 end program chmod_test
2333 @section @code{CMPLX} --- Complex conversion function
2335 @cindex complex numbers, conversion to
2336 @cindex conversion, to complex
2339 @item @emph{Description}:
2340 @code{CMPLX(X [, Y [, KIND]])} returns a complex number where @var{X} is converted to
2341 the real component. If @var{Y} is present it is converted to the imaginary
2342 component. If @var{Y} is not present then the imaginary component is set to
2343 0.0. If @var{X} is complex then @var{Y} must not be present.
2345 @item @emph{Standard}:
2351 @item @emph{Syntax}:
2352 @code{RESULT = CMPLX(X [, Y [, KIND]])}
2354 @item @emph{Arguments}:
2355 @multitable @columnfractions .15 .70
2356 @item @var{X} @tab The type may be @code{INTEGER(*)}, @code{REAL(*)},
2357 or @code{COMPLEX(*)}.
2358 @item @var{Y} @tab (Optional; only allowed if @var{X} is not
2359 @code{COMPLEX(*)}.) May be @code{INTEGER(*)}
2361 @item @var{KIND} @tab (Optional) An @code{INTEGER(*)} initialization
2362 expression indicating the kind parameter of
2366 @item @emph{Return value}:
2367 The return value is of @code{COMPLEX} type, with a kind equal to
2368 @var{KIND} if it is specified. If @var{KIND} is not specified, the
2369 result is of the default @code{COMPLEX} kind, regardless of the kinds of
2370 @var{X} and @var{Y}.
2372 @item @emph{Example}:
2379 print *, z, cmplx(x)
2380 end program test_cmplx
2383 @item @emph{See also}:
2389 @node COMMAND_ARGUMENT_COUNT
2390 @section @code{COMMAND_ARGUMENT_COUNT} --- Get number of command line arguments
2391 @fnindex COMMAND_ARGUMENT_COUNT
2392 @cindex command-line arguments
2393 @cindex command-line arguments, number of
2394 @cindex arguments, to program
2397 @item @emph{Description}:
2398 @code{COMMAND_ARGUMENT_COUNT()} returns the number of arguments passed on the
2399 command line when the containing program was invoked.
2401 @item @emph{Standard}:
2407 @item @emph{Syntax}:
2408 @code{RESULT = COMMAND_ARGUMENT_COUNT()}
2410 @item @emph{Arguments}:
2411 @multitable @columnfractions .15 .70
2415 @item @emph{Return value}:
2416 The return value is of type @code{INTEGER(4)}
2418 @item @emph{Example}:
2420 program test_command_argument_count
2422 count = command_argument_count()
2424 end program test_command_argument_count
2427 @item @emph{See also}:
2428 @ref{GET_COMMAND}, @ref{GET_COMMAND_ARGUMENT}
2434 @section @code{COMPLEX} --- Complex conversion function
2436 @cindex complex numbers, conversion to
2437 @cindex conversion, to complex
2440 @item @emph{Description}:
2441 @code{COMPLEX(X, Y)} returns a complex number where @var{X} is converted
2442 to the real component and @var{Y} is converted to the imaginary
2445 @item @emph{Standard}:
2451 @item @emph{Syntax}:
2452 @code{RESULT = COMPLEX(X, Y)}
2454 @item @emph{Arguments}:
2455 @multitable @columnfractions .15 .70
2456 @item @var{X} @tab The type may be @code{INTEGER(*)} or @code{REAL(*)}.
2457 @item @var{Y} @tab The type may be @code{INTEGER(*)} or @code{REAL(*)}.
2460 @item @emph{Return value}:
2461 If @var{X} and @var{Y} are both of @code{INTEGER} type, then the return
2462 value is of default @code{COMPLEX} type.
2464 If @var{X} and @var{Y} are of @code{REAL} type, or one is of @code{REAL}
2465 type and one is of @code{INTEGER} type, then the return value is of
2466 @code{COMPLEX} type with a kind equal to that of the @code{REAL}
2467 argument with the highest precision.
2469 @item @emph{Example}:
2471 program test_complex
2474 print *, complex(i, x)
2475 end program test_complex
2478 @item @emph{See also}:
2485 @section @code{CONJG} --- Complex conjugate function
2488 @cindex complex conjugate
2491 @item @emph{Description}:
2492 @code{CONJG(Z)} returns the conjugate of @var{Z}. If @var{Z} is @code{(x, y)}
2493 then the result is @code{(x, -y)}
2495 @item @emph{Standard}:
2496 F77 and later, has overloads that are GNU extensions
2501 @item @emph{Syntax}:
2504 @item @emph{Arguments}:
2505 @multitable @columnfractions .15 .70
2506 @item @var{Z} @tab The type shall be @code{COMPLEX(*)}.
2509 @item @emph{Return value}:
2510 The return value is of type @code{COMPLEX(*)}.
2512 @item @emph{Example}:
2515 complex :: z = (2.0, 3.0)
2516 complex(8) :: dz = (2.71_8, -3.14_8)
2521 end program test_conjg
2524 @item @emph{Specific names}:
2525 @multitable @columnfractions .20 .20 .20 .25
2526 @item Name @tab Argument @tab Return type @tab Standard
2527 @item @code{DCONJG(Z)} @tab @code{COMPLEX(8) Z} @tab @code{COMPLEX(8)} @tab GNU extension
2534 @section @code{COS} --- Cosine function
2540 @cindex trigonometric function, cosine
2544 @item @emph{Description}:
2545 @code{COS(X)} computes the cosine of @var{X}.
2547 @item @emph{Standard}:
2548 F77 and later, has overloads that are GNU extensions
2553 @item @emph{Syntax}:
2554 @code{RESULT = COS(X)}
2556 @item @emph{Arguments}:
2557 @multitable @columnfractions .15 .70
2558 @item @var{X} @tab The type shall be @code{REAL(*)} or
2562 @item @emph{Return value}:
2563 The return value is of type @code{REAL(*)} and it lies in the
2564 range @math{ -1 \leq \cos (x) \leq 1}. The kind type
2565 parameter is the same as @var{X}.
2567 @item @emph{Example}:
2572 end program test_cos
2575 @item @emph{Specific names}:
2576 @multitable @columnfractions .20 .20 .20 .25
2577 @item Name @tab Argument @tab Return type @tab Standard
2578 @item @code{DCOS(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab F77 and later
2579 @item @code{CCOS(X)} @tab @code{COMPLEX(4) X} @tab @code{COMPLEX(4)} @tab F77 and later
2580 @item @code{ZCOS(X)} @tab @code{COMPLEX(8) X} @tab @code{COMPLEX(8)} @tab GNU extension
2581 @item @code{CDCOS(X)} @tab @code{COMPLEX(8) X} @tab @code{COMPLEX(8)} @tab GNU extension
2584 @item @emph{See also}:
2585 Inverse function: @ref{ACOS}
2592 @section @code{COSH} --- Hyperbolic cosine function
2595 @cindex hyperbolic cosine
2596 @cindex hyperbolic function, cosine
2597 @cindex cosine, hyperbolic
2600 @item @emph{Description}:
2601 @code{COSH(X)} computes the hyperbolic cosine of @var{X}.
2603 @item @emph{Standard}:
2609 @item @emph{Syntax}:
2612 @item @emph{Arguments}:
2613 @multitable @columnfractions .15 .70
2614 @item @var{X} @tab The type shall be @code{REAL(*)}.
2617 @item @emph{Return value}:
2618 The return value is of type @code{REAL(*)} and it is positive
2619 (@math{ \cosh (x) \geq 0 }.
2621 @item @emph{Example}:
2624 real(8) :: x = 1.0_8
2626 end program test_cosh
2629 @item @emph{Specific names}:
2630 @multitable @columnfractions .20 .20 .20 .25
2631 @item Name @tab Argument @tab Return type @tab Standard
2632 @item @code{DCOSH(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab F77 and later
2635 @item @emph{See also}:
2636 Inverse function: @ref{ACOSH}
2643 @section @code{COUNT} --- Count function
2645 @cindex array, conditionally count elements
2646 @cindex array, element counting
2647 @cindex array, number of elements
2650 @item @emph{Description}:
2652 @code{COUNT(MASK [, DIM [, KIND]])} counts the number of @code{.TRUE.}
2653 elements of @var{MASK} along the dimension of @var{DIM}. If @var{DIM} is
2654 omitted it is taken to be @code{1}. @var{DIM} is a scaler of type
2655 @code{INTEGER} in the range of @math{1 /leq DIM /leq n)} where @math{n}
2656 is the rank of @var{MASK}.
2658 @item @emph{Standard}:
2662 Transformational function
2664 @item @emph{Syntax}:
2665 @code{RESULT = COUNT(MASK [, DIM [, KIND]])}
2667 @item @emph{Arguments}:
2668 @multitable @columnfractions .15 .70
2669 @item @var{MASK} @tab The type shall be @code{LOGICAL}.
2670 @item @var{DIM} @tab (Optional) The type shall be @code{INTEGER}.
2671 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
2672 expression indicating the kind parameter of
2676 @item @emph{Return value}:
2677 The return value is of type @code{INTEGER} and of kind @var{KIND}. If
2678 @var{KIND} is absent, the return value is of default integer kind.
2679 The result has a rank equal to that of @var{MASK}.
2681 @item @emph{Example}:
2684 integer, dimension(2,3) :: a, b
2685 logical, dimension(2,3) :: mask
2686 a = reshape( (/ 1, 2, 3, 4, 5, 6 /), (/ 2, 3 /))
2687 b = reshape( (/ 0, 7, 3, 4, 5, 8 /), (/ 2, 3 /))
2688 print '(3i3)', a(1,:)
2689 print '(3i3)', a(2,:)
2691 print '(3i3)', b(1,:)
2692 print '(3i3)', b(2,:)
2695 print '(3l3)', mask(1,:)
2696 print '(3l3)', mask(2,:)
2698 print '(3i3)', count(mask)
2700 print '(3i3)', count(mask, 1)
2702 print '(3i3)', count(mask, 2)
2703 end program test_count
2710 @section @code{CPU_TIME} --- CPU elapsed time in seconds
2712 @cindex time, elapsed
2715 @item @emph{Description}:
2716 Returns a @code{REAL(*)} value representing the elapsed CPU time in
2717 seconds. This is useful for testing segments of code to determine
2720 If a time source is available, time will be reported with microsecond
2721 resolution. If no time source is available, @var{TIME} is set to
2724 Note that @var{TIME} may contain a, system dependent, arbitrary offset
2725 and may not start with @code{0.0}. For @code{CPU_TIME}, the absolute
2726 value is meaningless, only differences between subsequent calls to
2727 this subroutine, as shown in the example below, should be used.
2730 @item @emph{Standard}:
2736 @item @emph{Syntax}:
2737 @code{CALL CPU_TIME(TIME)}
2739 @item @emph{Arguments}:
2740 @multitable @columnfractions .15 .70
2741 @item @var{TIME} @tab The type shall be @code{REAL(*)} with @code{INTENT(OUT)}.
2744 @item @emph{Return value}:
2747 @item @emph{Example}:
2749 program test_cpu_time
2750 real :: start, finish
2751 call cpu_time(start)
2752 ! put code to test here
2753 call cpu_time(finish)
2754 print '("Time = ",f6.3," seconds.")',finish-start
2755 end program test_cpu_time
2758 @item @emph{See also}:
2759 @ref{SYSTEM_CLOCK}, @ref{DATE_AND_TIME}
2765 @section @code{CSHIFT} --- Circular shift elements of an array
2767 @cindex array, shift circularly
2768 @cindex array, permutation
2769 @cindex array, rotate
2772 @item @emph{Description}:
2773 @code{CSHIFT(ARRAY, SHIFT [, DIM])} performs a circular shift on elements of
2774 @var{ARRAY} along the dimension of @var{DIM}. If @var{DIM} is omitted it is
2775 taken to be @code{1}. @var{DIM} is a scaler of type @code{INTEGER} in the
2776 range of @math{1 /leq DIM /leq n)} where @math{n} is the rank of @var{ARRAY}.
2777 If the rank of @var{ARRAY} is one, then all elements of @var{ARRAY} are shifted
2778 by @var{SHIFT} places. If rank is greater than one, then all complete rank one
2779 sections of @var{ARRAY} along the given dimension are shifted. Elements
2780 shifted out one end of each rank one section are shifted back in the other end.
2782 @item @emph{Standard}:
2786 Transformational function
2788 @item @emph{Syntax}:
2789 @code{RESULT = CSHIFT(ARRAY, SHIFT [, DIM])}
2791 @item @emph{Arguments}:
2792 @multitable @columnfractions .15 .70
2793 @item @var{ARRAY} @tab Shall be an array of any type.
2794 @item @var{SHIFT} @tab The type shall be @code{INTEGER}.
2795 @item @var{DIM} @tab The type shall be @code{INTEGER}.
2798 @item @emph{Return value}:
2799 Returns an array of same type and rank as the @var{ARRAY} argument.
2801 @item @emph{Example}:
2804 integer, dimension(3,3) :: a
2805 a = reshape( (/ 1, 2, 3, 4, 5, 6, 7, 8, 9 /), (/ 3, 3 /))
2806 print '(3i3)', a(1,:)
2807 print '(3i3)', a(2,:)
2808 print '(3i3)', a(3,:)
2809 a = cshift(a, SHIFT=(/1, 2, -1/), DIM=2)
2811 print '(3i3)', a(1,:)
2812 print '(3i3)', a(2,:)
2813 print '(3i3)', a(3,:)
2814 end program test_cshift
2821 @section @code{CTIME} --- Convert a time into a string
2823 @cindex time, conversion to string
2824 @cindex conversion, to string
2827 @item @emph{Description}:
2828 @code{CTIME} converts a system time value, such as returned by
2829 @code{TIME8()}, to a string of the form @samp{Sat Aug 19 18:13:14 1995}.
2831 This intrinsic is provided in both subroutine and function forms; however,
2832 only one form can be used in any given program unit.
2834 @item @emph{Standard}:
2838 Subroutine, function
2840 @item @emph{Syntax}:
2841 @multitable @columnfractions .80
2842 @item @code{CALL CTIME(TIME, RESULT)}.
2843 @item @code{RESULT = CTIME(TIME)}, (not recommended).
2846 @item @emph{Arguments}:
2847 @multitable @columnfractions .15 .70
2848 @item @var{TIME} @tab The type shall be of type @code{INTEGER(KIND=8)}.
2849 @item @var{RESULT} @tab The type shall be of type @code{CHARACTER}.
2852 @item @emph{Return value}:
2853 The converted date and time as a string.
2855 @item @emph{Example}:
2859 character(len=30) :: date
2862 ! Do something, main part of the program
2865 print *, 'Program was started on ', date
2866 end program test_ctime
2869 @item @emph{See Also}:
2870 @ref{GMTIME}, @ref{LTIME}, @ref{TIME}, @ref{TIME8}
2876 @section @code{DATE_AND_TIME} --- Date and time subroutine
2877 @fnindex DATE_AND_TIME
2878 @cindex date, current
2879 @cindex current date
2880 @cindex time, current
2881 @cindex current time
2884 @item @emph{Description}:
2885 @code{DATE_AND_TIME(DATE, TIME, ZONE, VALUES)} gets the corresponding date and
2886 time information from the real-time system clock. @var{DATE} is
2887 @code{INTENT(OUT)} and has form ccyymmdd. @var{TIME} is @code{INTENT(OUT)} and
2888 has form hhmmss.sss. @var{ZONE} is @code{INTENT(OUT)} and has form (+-)hhmm,
2889 representing the difference with respect to Coordinated Universal Time (UTC).
2890 Unavailable time and date parameters return blanks.
2892 @var{VALUES} is @code{INTENT(OUT)} and provides the following:
2894 @multitable @columnfractions .15 .30 .40
2895 @item @tab @code{VALUE(1)}: @tab The year
2896 @item @tab @code{VALUE(2)}: @tab The month
2897 @item @tab @code{VALUE(3)}: @tab The day of the month
2898 @item @tab @code{VALUE(4)}: @tab Time difference with UTC in minutes
2899 @item @tab @code{VALUE(5)}: @tab The hour of the day
2900 @item @tab @code{VALUE(6)}: @tab The minutes of the hour
2901 @item @tab @code{VALUE(7)}: @tab The seconds of the minute
2902 @item @tab @code{VALUE(8)}: @tab The milliseconds of the second
2905 @item @emph{Standard}:
2911 @item @emph{Syntax}:
2912 @code{CALL DATE_AND_TIME([DATE, TIME, ZONE, VALUES])}
2914 @item @emph{Arguments}:
2915 @multitable @columnfractions .15 .70
2916 @item @var{DATE} @tab (Optional) The type shall be @code{CHARACTER(8)} or larger.
2917 @item @var{TIME} @tab (Optional) The type shall be @code{CHARACTER(10)} or larger.
2918 @item @var{ZONE} @tab (Optional) The type shall be @code{CHARACTER(5)} or larger.
2919 @item @var{VALUES}@tab (Optional) The type shall be @code{INTEGER(8)}.
2922 @item @emph{Return value}:
2925 @item @emph{Example}:
2927 program test_time_and_date
2928 character(8) :: date
2929 character(10) :: time
2930 character(5) :: zone
2931 integer,dimension(8) :: values
2932 ! using keyword arguments
2933 call date_and_time(date,time,zone,values)
2934 call date_and_time(DATE=date,ZONE=zone)
2935 call date_and_time(TIME=time)
2936 call date_and_time(VALUES=values)
2937 print '(a,2x,a,2x,a)', date, time, zone
2938 print '(8i5))', values
2939 end program test_time_and_date
2942 @item @emph{See also}:
2943 @ref{CPU_TIME}, @ref{SYSTEM_CLOCK}
2949 @section @code{DBLE} --- Double conversion function
2951 @cindex conversion, to real
2954 @item @emph{Description}:
2955 @code{DBLE(X)} Converts @var{X} to double precision real type.
2957 @item @emph{Standard}:
2963 @item @emph{Syntax}:
2964 @code{RESULT = DBLE(X)}
2966 @item @emph{Arguments}:
2967 @multitable @columnfractions .15 .70
2968 @item @var{X} @tab The type shall be @code{INTEGER(*)}, @code{REAL(*)},
2969 or @code{COMPLEX(*)}.
2972 @item @emph{Return value}:
2973 The return value is of type double precision real.
2975 @item @emph{Example}:
2980 complex :: z = (2.3,1.14)
2981 print *, dble(x), dble(i), dble(z)
2982 end program test_dble
2985 @item @emph{See also}:
2986 @ref{DFLOAT}, @ref{FLOAT}, @ref{REAL}
2992 @section @code{DCMPLX} --- Double complex conversion function
2994 @cindex complex numbers, conversion to
2995 @cindex conversion, to complex
2998 @item @emph{Description}:
2999 @code{DCMPLX(X [,Y])} returns a double complex number where @var{X} is
3000 converted to the real component. If @var{Y} is present it is converted to the
3001 imaginary component. If @var{Y} is not present then the imaginary component is
3002 set to 0.0. If @var{X} is complex then @var{Y} must not be present.
3004 @item @emph{Standard}:
3010 @item @emph{Syntax}:
3011 @code{RESULT = DCMPLX(X [, Y])}
3013 @item @emph{Arguments}:
3014 @multitable @columnfractions .15 .70
3015 @item @var{X} @tab The type may be @code{INTEGER(*)}, @code{REAL(*)},
3016 or @code{COMPLEX(*)}.
3017 @item @var{Y} @tab (Optional if @var{X} is not @code{COMPLEX(*)}.) May be
3018 @code{INTEGER(*)} or @code{REAL(*)}.
3021 @item @emph{Return value}:
3022 The return value is of type @code{COMPLEX(8)}
3024 @item @emph{Example}:
3034 print *, dcmplx(x,i)
3035 end program test_dcmplx
3042 @section @code{DFLOAT} --- Double conversion function
3044 @cindex conversion, to real
3047 @item @emph{Description}:
3048 @code{DFLOAT(X)} Converts @var{X} to double precision real type.
3050 @item @emph{Standard}:
3056 @item @emph{Syntax}:
3057 @code{RESULT = DFLOAT(X)}
3059 @item @emph{Arguments}:
3060 @multitable @columnfractions .15 .70
3061 @item @var{X} @tab The type shall be @code{INTEGER(*)}.
3064 @item @emph{Return value}:
3065 The return value is of type double precision real.
3067 @item @emph{Example}:
3072 end program test_dfloat
3075 @item @emph{See also}:
3076 @ref{DBLE}, @ref{FLOAT}, @ref{REAL}
3082 @section @code{DIGITS} --- Significant digits function
3084 @cindex model representation, significant digits
3087 @item @emph{Description}:
3088 @code{DIGITS(X)} returns the number of significant digits of the internal model
3089 representation of @var{X}. For example, on a system using a 32-bit
3090 floating point representation, a default real number would likely return 24.
3092 @item @emph{Standard}:
3098 @item @emph{Syntax}:
3099 @code{RESULT = DIGITS(X)}
3101 @item @emph{Arguments}:
3102 @multitable @columnfractions .15 .70
3103 @item @var{X} @tab The type may be @code{INTEGER(*)} or @code{REAL(*)}.
3106 @item @emph{Return value}:
3107 The return value is of type @code{INTEGER}.
3109 @item @emph{Example}:
3112 integer :: i = 12345
3118 end program test_digits
3125 @section @code{DIM} --- Positive difference
3129 @cindex positive difference
3132 @item @emph{Description}:
3133 @code{DIM(X,Y)} returns the difference @code{X-Y} if the result is positive;
3134 otherwise returns zero.
3136 @item @emph{Standard}:
3142 @item @emph{Syntax}:
3143 @code{RESULT = DIM(X, Y)}
3145 @item @emph{Arguments}:
3146 @multitable @columnfractions .15 .70
3147 @item @var{X} @tab The type shall be @code{INTEGER(*)} or @code{REAL(*)}
3148 @item @var{Y} @tab The type shall be the same type and kind as @var{X}.
3151 @item @emph{Return value}:
3152 The return value is of type @code{INTEGER(*)} or @code{REAL(*)}.
3154 @item @emph{Example}:
3160 x = dim(4.345_8, 2.111_8)
3163 end program test_dim
3166 @item @emph{Specific names}:
3167 @multitable @columnfractions .20 .20 .20 .25
3168 @item Name @tab Argument @tab Return type @tab Standard
3169 @item @code{IDIM(X,Y)} @tab @code{INTEGER(4) X,Y} @tab @code{INTEGER(4)} @tab F77 and later
3170 @item @code{DDIM(X,Y)} @tab @code{REAL(8) X,Y} @tab @code{REAL(8)} @tab F77 and later
3177 @section @code{DOT_PRODUCT} --- Dot product function
3178 @fnindex DOT_PRODUCT
3180 @cindex vector product
3181 @cindex product, vector
3184 @item @emph{Description}:
3185 @code{DOT_PRODUCT(X,Y)} computes the dot product multiplication of two vectors
3186 @var{X} and @var{Y}. The two vectors may be either numeric or logical
3187 and must be arrays of rank one and of equal size. If the vectors are
3188 @code{INTEGER(*)} or @code{REAL(*)}, the result is @code{SUM(X*Y)}. If the
3189 vectors are @code{COMPLEX(*)}, the result is @code{SUM(CONJG(X)*Y)}. If the
3190 vectors are @code{LOGICAL}, the result is @code{ANY(X.AND.Y)}.
3192 @item @emph{Standard}:
3196 Transformational function
3198 @item @emph{Syntax}:
3199 @code{RESULT = DOT_PRODUCT(X, Y)}
3201 @item @emph{Arguments}:
3202 @multitable @columnfractions .15 .70
3203 @item @var{X} @tab The type shall be numeric or @code{LOGICAL}, rank 1.
3204 @item @var{Y} @tab The type shall be numeric or @code{LOGICAL}, rank 1.
3207 @item @emph{Return value}:
3208 If the arguments are numeric, the return value is a scaler of numeric type,
3209 @code{INTEGER(*)}, @code{REAL(*)}, or @code{COMPLEX(*)}. If the arguments are
3210 @code{LOGICAL}, the return value is @code{.TRUE.} or @code{.FALSE.}.
3212 @item @emph{Example}:
3214 program test_dot_prod
3215 integer, dimension(3) :: a, b
3222 print *, dot_product(a,b)
3223 end program test_dot_prod
3230 @section @code{DPROD} --- Double product function
3232 @cindex product, double-precision
3235 @item @emph{Description}:
3236 @code{DPROD(X,Y)} returns the product @code{X*Y}.
3238 @item @emph{Standard}:
3244 @item @emph{Syntax}:
3245 @code{RESULT = DPROD(X, Y)}
3247 @item @emph{Arguments}:
3248 @multitable @columnfractions .15 .70
3249 @item @var{X} @tab The type shall be @code{REAL}.
3250 @item @var{Y} @tab The type shall be @code{REAL}.
3253 @item @emph{Return value}:
3254 The return value is of type @code{REAL(8)}.
3256 @item @emph{Example}:
3264 end program test_dprod
3271 @section @code{DREAL} --- Double real part function
3273 @cindex complex numbers, real part
3276 @item @emph{Description}:
3277 @code{DREAL(Z)} returns the real part of complex variable @var{Z}.
3279 @item @emph{Standard}:
3285 @item @emph{Syntax}:
3286 @code{RESULT = DREAL(Z)}
3288 @item @emph{Arguments}:
3289 @multitable @columnfractions .15 .70
3290 @item @var{Z} @tab The type shall be @code{COMPLEX(8)}.
3293 @item @emph{Return value}:
3294 The return value is of type @code{REAL(8)}.
3296 @item @emph{Example}:
3299 complex(8) :: z = (1.3_8,7.2_8)
3301 end program test_dreal
3304 @item @emph{See also}:
3312 @section @code{DTIME} --- Execution time subroutine (or function)
3314 @cindex time, elapsed
3315 @cindex elapsed time
3318 @item @emph{Description}:
3319 @code{DTIME(TARRAY, RESULT)} initially returns the number of seconds of runtime
3320 since the start of the process's execution in @var{RESULT}. @var{TARRAY}
3321 returns the user and system components of this time in @code{TARRAY(1)} and
3322 @code{TARRAY(2)} respectively. @var{RESULT} is equal to @code{TARRAY(1) +
3325 Subsequent invocations of @code{DTIME} return values accumulated since the
3326 previous invocation.
3328 On some systems, the underlying timings are represented using types with
3329 sufficiently small limits that overflows (wrap around) are possible, such as
3330 32-bit types. Therefore, the values returned by this intrinsic might be, or
3331 become, negative, or numerically less than previous values, during a single
3332 run of the compiled program.
3334 Please note, that this implementation is thread safe if used within OpenMP
3335 directives, i. e. its state will be consistent while called from multiple
3336 threads. However, if @code{DTIME} is called from multiple threads, the result
3337 is still the time since the last invocation. This may not give the intended
3338 results. If possible, use @code{CPU_TIME} instead.
3340 This intrinsic is provided in both subroutine and function forms; however,
3341 only one form can be used in any given program unit.
3343 @var{TARRAY} and @var{RESULT} are @code{INTENT(OUT)} and provide the following:
3345 @multitable @columnfractions .15 .30 .40
3346 @item @tab @code{TARRAY(1)}: @tab User time in seconds.
3347 @item @tab @code{TARRAY(2)}: @tab System time in seconds.
3348 @item @tab @code{RESULT}: @tab Run time since start in seconds.
3351 @item @emph{Standard}:
3355 Subroutine, function
3357 @item @emph{Syntax}:
3358 @multitable @columnfractions .80
3359 @item @code{CALL DTIME(TARRAY, RESULT)}.
3360 @item @code{RESULT = DTIME(TARRAY)}, (not recommended).
3363 @item @emph{Arguments}:
3364 @multitable @columnfractions .15 .70
3365 @item @var{TARRAY}@tab The type shall be @code{REAL, DIMENSION(2)}.
3366 @item @var{RESULT}@tab The type shall be @code{REAL}.
3369 @item @emph{Return value}:
3370 Elapsed time in seconds since the last invocation or since the start of program
3371 execution if not called before.
3373 @item @emph{Example}:
3377 real, dimension(2) :: tarray
3379 call dtime(tarray, result)
3383 do i=1,100000000 ! Just a delay
3386 call dtime(tarray, result)
3390 end program test_dtime
3393 @item @emph{See also}:
3401 @section @code{EOSHIFT} --- End-off shift elements of an array
3403 @cindex array, shift
3406 @item @emph{Description}:
3407 @code{EOSHIFT(ARRAY, SHIFT[,BOUNDARY, DIM])} performs an end-off shift on
3408 elements of @var{ARRAY} along the dimension of @var{DIM}. If @var{DIM} is
3409 omitted it is taken to be @code{1}. @var{DIM} is a scaler of type
3410 @code{INTEGER} in the range of @math{1 /leq DIM /leq n)} where @math{n} is the
3411 rank of @var{ARRAY}. If the rank of @var{ARRAY} is one, then all elements of
3412 @var{ARRAY} are shifted by @var{SHIFT} places. If rank is greater than one,
3413 then all complete rank one sections of @var{ARRAY} along the given dimension are
3414 shifted. Elements shifted out one end of each rank one section are dropped. If
3415 @var{BOUNDARY} is present then the corresponding value of from @var{BOUNDARY}
3416 is copied back in the other end. If @var{BOUNDARY} is not present then the
3417 following are copied in depending on the type of @var{ARRAY}.
3419 @multitable @columnfractions .15 .80
3420 @item @emph{Array Type} @tab @emph{Boundary Value}
3421 @item Numeric @tab 0 of the type and kind of @var{ARRAY}.
3422 @item Logical @tab @code{.FALSE.}.
3423 @item Character(@var{len}) @tab @var{len} blanks.
3426 @item @emph{Standard}:
3430 Transformational function
3432 @item @emph{Syntax}:
3433 @code{RESULT = EOSHIFT(ARRAY, SHIFT [, BOUNDARY, DIM])}
3435 @item @emph{Arguments}:
3436 @multitable @columnfractions .15 .70
3437 @item @var{ARRAY} @tab May be any type, not scaler.
3438 @item @var{SHIFT} @tab The type shall be @code{INTEGER}.
3439 @item @var{BOUNDARY} @tab Same type as @var{ARRAY}.
3440 @item @var{DIM} @tab The type shall be @code{INTEGER}.
3443 @item @emph{Return value}:
3444 Returns an array of same type and rank as the @var{ARRAY} argument.
3446 @item @emph{Example}:
3448 program test_eoshift
3449 integer, dimension(3,3) :: a
3450 a = reshape( (/ 1, 2, 3, 4, 5, 6, 7, 8, 9 /), (/ 3, 3 /))
3451 print '(3i3)', a(1,:)
3452 print '(3i3)', a(2,:)
3453 print '(3i3)', a(3,:)
3454 a = EOSHIFT(a, SHIFT=(/1, 2, 1/), BOUNDARY=-5, DIM=2)
3456 print '(3i3)', a(1,:)
3457 print '(3i3)', a(2,:)
3458 print '(3i3)', a(3,:)
3459 end program test_eoshift
3466 @section @code{EPSILON} --- Epsilon function
3468 @cindex model representation, epsilon
3471 @item @emph{Description}:
3472 @code{EPSILON(X)} returns a nearly negligible number relative to @code{1}.
3474 @item @emph{Standard}:
3480 @item @emph{Syntax}:
3481 @code{RESULT = EPSILON(X)}
3483 @item @emph{Arguments}:
3484 @multitable @columnfractions .15 .70
3485 @item @var{X} @tab The type shall be @code{REAL(*)}.
3488 @item @emph{Return value}:
3489 The return value is of same type as the argument.
3491 @item @emph{Example}:
3493 program test_epsilon
3498 end program test_epsilon
3505 @section @code{ERF} --- Error function
3507 @cindex error function
3510 @item @emph{Description}:
3511 @code{ERF(X)} computes the error function of @var{X}.
3513 @item @emph{Standard}:
3519 @item @emph{Syntax}:
3520 @code{RESULT = ERF(X)}
3522 @item @emph{Arguments}:
3523 @multitable @columnfractions .15 .70
3524 @item @var{X} @tab The type shall be @code{REAL(*)}, and it shall be scalar.
3527 @item @emph{Return value}:
3528 The return value is a scalar of type @code{REAL(*)} and it is positive
3529 (@math{ - 1 \leq erf (x) \leq 1 }.
3531 @item @emph{Example}:
3534 real(8) :: x = 0.17_8
3536 end program test_erf
3539 @item @emph{Specific names}:
3540 @multitable @columnfractions .20 .20 .20 .25
3541 @item Name @tab Argument @tab Return type @tab Standard
3542 @item @code{DERF(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU extension
3549 @section @code{ERFC} --- Error function
3551 @cindex error function, complementary
3554 @item @emph{Description}:
3555 @code{ERFC(X)} computes the complementary error function of @var{X}.
3557 @item @emph{Standard}:
3563 @item @emph{Syntax}:
3564 @code{RESULT = ERFC(X)}
3566 @item @emph{Arguments}:
3567 @multitable @columnfractions .15 .70
3568 @item @var{X} @tab The type shall be @code{REAL(*)}, and it shall be scalar.
3571 @item @emph{Return value}:
3572 The return value is a scalar of type @code{REAL(*)} and it is positive
3573 (@math{ 0 \leq erfc (x) \leq 2 }.
3575 @item @emph{Example}:
3578 real(8) :: x = 0.17_8
3580 end program test_erfc
3583 @item @emph{Specific names}:
3584 @multitable @columnfractions .20 .20 .20 .25
3585 @item Name @tab Argument @tab Return type @tab Standard
3586 @item @code{DERFC(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU extension
3593 @section @code{ETIME} --- Execution time subroutine (or function)
3595 @cindex time, elapsed
3598 @item @emph{Description}:
3599 @code{ETIME(TARRAY, RESULT)} returns the number of seconds of runtime
3600 since the start of the process's execution in @var{RESULT}. @var{TARRAY}
3601 returns the user and system components of this time in @code{TARRAY(1)} and
3602 @code{TARRAY(2)} respectively. @var{RESULT} is equal to @code{TARRAY(1) + TARRAY(2)}.
3604 On some systems, the underlying timings are represented using types with
3605 sufficiently small limits that overflows (wrap around) are possible, such as
3606 32-bit types. Therefore, the values returned by this intrinsic might be, or
3607 become, negative, or numerically less than previous values, during a single
3608 run of the compiled program.
3610 This intrinsic is provided in both subroutine and function forms; however,
3611 only one form can be used in any given program unit.
3613 @var{TARRAY} and @var{RESULT} are @code{INTENT(OUT)} and provide the following:
3615 @multitable @columnfractions .15 .30 .60
3616 @item @tab @code{TARRAY(1)}: @tab User time in seconds.
3617 @item @tab @code{TARRAY(2)}: @tab System time in seconds.
3618 @item @tab @code{RESULT}: @tab Run time since start in seconds.
3621 @item @emph{Standard}:
3625 Subroutine, function
3627 @item @emph{Syntax}:
3628 @multitable @columnfractions .80
3629 @item @code{CALL ETIME(TARRAY, RESULT)}.
3630 @item @code{RESULT = ETIME(TARRAY)}, (not recommended).
3633 @item @emph{Arguments}:
3634 @multitable @columnfractions .15 .70
3635 @item @var{TARRAY}@tab The type shall be @code{REAL, DIMENSION(2)}.
3636 @item @var{RESULT}@tab The type shall be @code{REAL}.
3639 @item @emph{Return value}:
3640 Elapsed time in seconds since the start of program execution.
3642 @item @emph{Example}:
3646 real, dimension(2) :: tarray
3648 call ETIME(tarray, result)
3652 do i=1,100000000 ! Just a delay
3655 call ETIME(tarray, result)
3659 end program test_etime
3662 @item @emph{See also}:
3670 @section @code{EXIT} --- Exit the program with status.
3672 @cindex program termination
3673 @cindex terminate program
3676 @item @emph{Description}:
3677 @code{EXIT} causes immediate termination of the program with status. If status
3678 is omitted it returns the canonical @emph{success} for the system. All Fortran
3679 I/O units are closed.
3681 @item @emph{Standard}:
3687 @item @emph{Syntax}:
3688 @code{CALL EXIT([STATUS])}
3690 @item @emph{Arguments}:
3691 @multitable @columnfractions .15 .70
3692 @item @var{STATUS} @tab Shall be an @code{INTEGER} of the default kind.
3695 @item @emph{Return value}:
3696 @code{STATUS} is passed to the parent process on exit.
3698 @item @emph{Example}:
3701 integer :: STATUS = 0
3702 print *, 'This program is going to exit.'
3704 end program test_exit
3707 @item @emph{See also}:
3708 @ref{ABORT}, @ref{KILL}
3714 @section @code{EXP} --- Exponential function
3720 @cindex exponential function
3721 @cindex logarithmic function, inverse
3724 @item @emph{Description}:
3725 @code{EXP(X)} computes the base @math{e} exponential of @var{X}.
3727 @item @emph{Standard}:
3728 F77 and later, has overloads that are GNU extensions
3733 @item @emph{Syntax}:
3734 @code{RESULT = EXP(X)}
3736 @item @emph{Arguments}:
3737 @multitable @columnfractions .15 .70
3738 @item @var{X} @tab The type shall be @code{REAL(*)} or
3742 @item @emph{Return value}:
3743 The return value has same type and kind as @var{X}.
3745 @item @emph{Example}:
3750 end program test_exp
3753 @item @emph{Specific names}:
3754 @multitable @columnfractions .20 .20 .20 .25
3755 @item Name @tab Argument @tab Return type @tab Standard
3756 @item @code{DEXP(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab F77 and later
3757 @item @code{CEXP(X)} @tab @code{COMPLEX(4) X} @tab @code{COMPLEX(4)} @tab F77 and later
3758 @item @code{ZEXP(X)} @tab @code{COMPLEX(8) X} @tab @code{COMPLEX(8)} @tab GNU extension
3759 @item @code{CDEXP(X)} @tab @code{COMPLEX(8) X} @tab @code{COMPLEX(8)} @tab GNU extension
3766 @section @code{EXPONENT} --- Exponent function
3768 @cindex real number, exponent
3769 @cindex floating point, exponent
3772 @item @emph{Description}:
3773 @code{EXPONENT(X)} returns the value of the exponent part of @var{X}. If @var{X}
3774 is zero the value returned is zero.
3776 @item @emph{Standard}:
3782 @item @emph{Syntax}:
3783 @code{RESULT = EXPONENT(X)}
3785 @item @emph{Arguments}:
3786 @multitable @columnfractions .15 .70
3787 @item @var{X} @tab The type shall be @code{REAL(*)}.
3790 @item @emph{Return value}:
3791 The return value is of type default @code{INTEGER}.
3793 @item @emph{Example}:
3795 program test_exponent
3800 print *, exponent(0.0)
3801 end program test_exponent
3808 @section @code{FDATE} --- Get the current time as a string
3810 @cindex time, current
3811 @cindex current time
3812 @cindex date, current
3813 @cindex current date
3816 @item @emph{Description}:
3817 @code{FDATE(DATE)} returns the current date (using the same format as
3818 @code{CTIME}) in @var{DATE}. It is equivalent to @code{CALL CTIME(DATE,
3821 This intrinsic is provided in both subroutine and function forms; however,
3822 only one form can be used in any given program unit.
3824 @var{DATE} is an @code{INTENT(OUT)} @code{CHARACTER} variable.
3826 @item @emph{Standard}:
3830 Subroutine, function
3832 @item @emph{Syntax}:
3833 @multitable @columnfractions .80
3834 @item @code{CALL FDATE(DATE)}.
3835 @item @code{DATE = FDATE()}, (not recommended).
3838 @item @emph{Arguments}:
3839 @multitable @columnfractions .15 .70
3840 @item @var{DATE}@tab The type shall be of type @code{CHARACTER}.
3843 @item @emph{Return value}:
3844 The current date as a string.
3846 @item @emph{Example}:
3850 character(len=30) :: date
3852 print *, 'Program started on ', date
3853 do i = 1, 100000000 ! Just a delay
3857 print *, 'Program ended on ', date
3858 end program test_fdate
3865 @section @code{FLOAT} --- Convert integer to default real
3867 @cindex conversion, to real
3870 @item @emph{Description}:
3871 @code{FLOAT(I)} converts the integer @var{I} to a default real value.
3873 @item @emph{Standard}:
3879 @item @emph{Syntax}:
3880 @code{RESULT = FLOAT(I)}
3882 @item @emph{Arguments}:
3883 @multitable @columnfractions .15 .70
3884 @item @var{I} @tab The type shall be @code{INTEGER(*)}.
3887 @item @emph{Return value}:
3888 The return value is of type default @code{REAL}.
3890 @item @emph{Example}:
3894 if (float(i) /= 1.) call abort
3895 end program test_float
3898 @item @emph{See also}:
3899 @ref{DBLE}, @ref{DFLOAT}, @ref{REAL}
3905 @section @code{FGET} --- Read a single character in stream mode from stdin
3907 @cindex read character, stream mode
3908 @cindex stream mode, read character
3909 @cindex file operation, read character
3912 @item @emph{Description}:
3913 Read a single character in stream mode from stdin by bypassing normal
3914 formatted output. Stream I/O should not be mixed with normal record-oriented
3915 (formatted or unformatted) I/O on the same unit; the results are unpredictable.
3917 This intrinsic is provided in both subroutine and function forms; however,
3918 only one form can be used in any given program unit.
3920 Note that the @code{FGET} intrinsic is provided for backwards compatibility with
3921 @command{g77}. GNU Fortran provides the Fortran 2003 Stream facility.
3922 Programmers should consider the use of new stream IO feature in new code
3923 for future portability. See also @ref{Fortran 2003 status}.
3925 @item @emph{Standard}:
3929 Subroutine, function
3931 @item @emph{Syntax}:
3932 @code{CALL FGET(C [, STATUS])}
3934 @item @emph{Arguments}:
3935 @multitable @columnfractions .15 .70
3936 @item @var{C} @tab The type shall be @code{CHARACTER}.
3937 @item @var{STATUS} @tab (Optional) status flag of type @code{INTEGER}.
3938 Returns 0 on success, -1 on end-of-file, and a
3939 system specific positive error code otherwise.
3942 @item @emph{Example}:
3945 INTEGER, PARAMETER :: strlen = 100
3946 INTEGER :: status, i = 1
3947 CHARACTER(len=strlen) :: str = ""
3949 WRITE (*,*) 'Enter text:'
3951 CALL fget(str(i:i), status)
3952 if (status /= 0 .OR. i > strlen) exit
3955 WRITE (*,*) TRIM(str)
3959 @item @emph{See also}:
3960 @ref{FGETC}, @ref{FPUT}, @ref{FPUTC}
3966 @section @code{FGETC} --- Read a single character in stream mode
3968 @cindex read character, stream mode
3969 @cindex stream mode, read character
3970 @cindex file operation, read character
3973 @item @emph{Description}:
3974 Read a single character in stream mode by bypassing normal formatted output.
3975 Stream I/O should not be mixed with normal record-oriented (formatted or
3976 unformatted) I/O on the same unit; the results are unpredictable.
3978 This intrinsic is provided in both subroutine and function forms; however,
3979 only one form can be used in any given program unit.
3981 Note that the @code{FGET} intrinsic is provided for backwards compatibility
3982 with @command{g77}. GNU Fortran provides the Fortran 2003 Stream facility.
3983 Programmers should consider the use of new stream IO feature in new code
3984 for future portability. See also @ref{Fortran 2003 status}.
3986 @item @emph{Standard}:
3990 Subroutine, function
3992 @item @emph{Syntax}:
3993 @code{CALL FGETC(UNIT, C [, STATUS])}
3995 @item @emph{Arguments}:
3996 @multitable @columnfractions .15 .70
3997 @item @var{UNIT} @tab The type shall be @code{INTEGER}.
3998 @item @var{C} @tab The type shall be @code{CHARACTER}.
3999 @item @var{STATUS} @tab (Optional) status flag of type @code{INTEGER}. Returns 0 on success,
4000 -1 on end-of-file and a system specific positive error code otherwise.
4003 @item @emph{Example}:
4006 INTEGER :: fd = 42, status
4009 OPEN(UNIT=fd, FILE="/etc/passwd", ACTION="READ", STATUS = "OLD")
4011 CALL fgetc(fd, c, status)
4012 IF (status /= 0) EXIT
4019 @item @emph{See also}:
4020 @ref{FGET}, @ref{FPUT}, @ref{FPUTC}
4026 @section @code{FLOOR} --- Integer floor function
4029 @cindex rounding, floor
4032 @item @emph{Description}:
4033 @code{FLOOR(X)} returns the greatest integer less than or equal to @var{X}.
4035 @item @emph{Standard}:
4041 @item @emph{Syntax}:
4042 @code{RESULT = FLOOR(X [, KIND])}
4044 @item @emph{Arguments}:
4045 @multitable @columnfractions .15 .70
4046 @item @var{X} @tab The type shall be @code{REAL(*)}.
4047 @item @var{KIND} @tab (Optional) An @code{INTEGER(*)} initialization
4048 expression indicating the kind parameter of
4052 @item @emph{Return value}:
4053 The return value is of type @code{INTEGER(KIND)}
4055 @item @emph{Example}:
4060 print *, floor(x) ! returns 63
4061 print *, floor(y) ! returns -64
4062 end program test_floor
4065 @item @emph{See also}:
4066 @ref{CEILING}, @ref{NINT}
4073 @section @code{FLUSH} --- Flush I/O unit(s)
4075 @cindex file operation, flush
4078 @item @emph{Description}:
4079 Flushes Fortran unit(s) currently open for output. Without the optional
4080 argument, all units are flushed, otherwise just the unit specified.
4082 @item @emph{Standard}:
4088 @item @emph{Syntax}:
4089 @code{CALL FLUSH(UNIT)}
4091 @item @emph{Arguments}:
4092 @multitable @columnfractions .15 .70
4093 @item @var{UNIT} @tab (Optional) The type shall be @code{INTEGER}.
4097 Beginning with the Fortran 2003 standard, there is a @code{FLUSH}
4098 statement that should be preferred over the @code{FLUSH} intrinsic.
4105 @section @code{FNUM} --- File number function
4107 @cindex file operation, file number
4110 @item @emph{Description}:
4111 @code{FNUM(UNIT)} returns the POSIX file descriptor number corresponding to the
4112 open Fortran I/O unit @code{UNIT}.
4114 @item @emph{Standard}:
4120 @item @emph{Syntax}:
4121 @code{RESULT = FNUM(UNIT)}
4123 @item @emph{Arguments}:
4124 @multitable @columnfractions .15 .70
4125 @item @var{UNIT} @tab The type shall be @code{INTEGER}.
4128 @item @emph{Return value}:
4129 The return value is of type @code{INTEGER}
4131 @item @emph{Example}:
4135 open (unit=10, status = "scratch")
4139 end program test_fnum
4146 @section @code{FPUT} --- Write a single character in stream mode to stdout
4148 @cindex write character, stream mode
4149 @cindex stream mode, write character
4150 @cindex file operation, write character
4153 @item @emph{Description}:
4154 Write a single character in stream mode to stdout by bypassing normal
4155 formatted output. Stream I/O should not be mixed with normal record-oriented
4156 (formatted or unformatted) I/O on the same unit; the results are unpredictable.
4158 This intrinsic is provided in both subroutine and function forms; however,
4159 only one form can be used in any given program unit.
4161 Note that the @code{FGET} intrinsic is provided for backwards compatibility with
4162 @command{g77}. GNU Fortran provides the Fortran 2003 Stream facility.
4163 Programmers should consider the use of new stream IO feature in new code
4164 for future portability. See also @ref{Fortran 2003 status}.
4166 @item @emph{Standard}:
4170 Subroutine, function
4172 @item @emph{Syntax}:
4173 @code{CALL FPUT(C [, STATUS])}
4175 @item @emph{Arguments}:
4176 @multitable @columnfractions .15 .70
4177 @item @var{C} @tab The type shall be @code{CHARACTER}.
4178 @item @var{STATUS} @tab (Optional) status flag of type @code{INTEGER}. Returns 0 on success,
4179 -1 on end-of-file and a system specific positive error code otherwise.
4182 @item @emph{Example}:
4185 CHARACTER(len=10) :: str = "gfortran"
4187 DO i = 1, len_trim(str)
4193 @item @emph{See also}:
4194 @ref{FPUTC}, @ref{FGET}, @ref{FGETC}
4200 @section @code{FPUTC} --- Write a single character in stream mode
4202 @cindex write character, stream mode
4203 @cindex stream mode, write character
4204 @cindex file operation, write character
4207 @item @emph{Description}:
4208 Write a single character in stream mode by bypassing normal formatted
4209 output. Stream I/O should not be mixed with normal record-oriented
4210 (formatted or unformatted) I/O on the same unit; the results are unpredictable.
4212 This intrinsic is provided in both subroutine and function forms; however,
4213 only one form can be used in any given program unit.
4215 Note that the @code{FGET} intrinsic is provided for backwards compatibility with
4216 @command{g77}. GNU Fortran provides the Fortran 2003 Stream facility.
4217 Programmers should consider the use of new stream IO feature in new code
4218 for future portability. See also @ref{Fortran 2003 status}.
4220 @item @emph{Standard}:
4224 Subroutine, function
4226 @item @emph{Syntax}:
4227 @code{CALL FPUTC(UNIT, C [, STATUS])}
4229 @item @emph{Arguments}:
4230 @multitable @columnfractions .15 .70
4231 @item @var{UNIT} @tab The type shall be @code{INTEGER}.
4232 @item @var{C} @tab The type shall be @code{CHARACTER}.
4233 @item @var{STATUS} @tab (Optional) status flag of type @code{INTEGER}. Returns 0 on success,
4234 -1 on end-of-file and a system specific positive error code otherwise.
4237 @item @emph{Example}:
4240 CHARACTER(len=10) :: str = "gfortran"
4241 INTEGER :: fd = 42, i
4243 OPEN(UNIT = fd, FILE = "out", ACTION = "WRITE", STATUS="NEW")
4244 DO i = 1, len_trim(str)
4245 CALL fputc(fd, str(i:i))
4251 @item @emph{See also}:
4252 @ref{FPUT}, @ref{FGET}, @ref{FGETC}
4258 @section @code{FRACTION} --- Fractional part of the model representation
4260 @cindex real number, fraction
4261 @cindex floating point, fraction
4264 @item @emph{Description}:
4265 @code{FRACTION(X)} returns the fractional part of the model
4266 representation of @code{X}.
4268 @item @emph{Standard}:
4274 @item @emph{Syntax}:
4275 @code{Y = FRACTION(X)}
4277 @item @emph{Arguments}:
4278 @multitable @columnfractions .15 .70
4279 @item @var{X} @tab The type of the argument shall be a @code{REAL}.
4282 @item @emph{Return value}:
4283 The return value is of the same type and kind as the argument.
4284 The fractional part of the model representation of @code{X} is returned;
4285 it is @code{X * RADIX(X)**(-EXPONENT(X))}.
4287 @item @emph{Example}:
4289 program test_fraction
4292 print *, fraction(x), x * radix(x)**(-exponent(x))
4293 end program test_fraction
4301 @section @code{FREE} --- Frees memory
4303 @cindex pointer, cray
4306 @item @emph{Description}:
4307 Frees memory previously allocated by @code{MALLOC()}. The @code{FREE}
4308 intrinsic is an extension intended to be used with Cray pointers, and is
4309 provided in GNU Fortran to allow user to compile legacy code. For
4310 new code using Fortran 95 pointers, the memory de-allocation intrinsic is
4313 @item @emph{Standard}:
4319 @item @emph{Syntax}:
4320 @code{CALL FREE(PTR)}
4322 @item @emph{Arguments}:
4323 @multitable @columnfractions .15 .70
4324 @item @var{PTR} @tab The type shall be @code{INTEGER}. It represents the
4325 location of the memory that should be de-allocated.
4328 @item @emph{Return value}:
4331 @item @emph{Example}:
4332 See @code{MALLOC} for an example.
4334 @item @emph{See also}:
4341 @section @code{FSEEK} --- Low level file positioning subroutine
4343 @cindex file operation, seek
4344 @cindex file operation, position
4347 @item @emph{Description}:
4348 Moves @var{UNIT} to the specified @var{OFFSET}. If @var{WHENCE}
4349 is set to 0, the @var{OFFSET} is taken as an absolute value @code{SEEK_SET},
4350 if set to 1, @var{OFFSET} is taken to be relative to the current position
4351 @code{SEEK_CUR}, and if set to 2 relative to the end of the file @code{SEEK_END}.
4352 On error, @var{STATUS} is set to a nonzero value. If @var{STATUS} the seek
4355 This intrinsic routine is not fully backwards compatible with @command{g77}.
4356 In @command{g77}, the @code{FSEEK} takes a statement label instead of a
4357 @var{STATUS} variable. If FSEEK is used in old code, change
4359 CALL FSEEK(UNIT, OFFSET, WHENCE, *label)
4364 CALL FSEEK(UNIT, OFFSET, WHENCE, status)
4365 IF (status /= 0) GOTO label
4368 Please note that GNU Fortran provides the Fortran 2003 Stream facility.
4369 Programmers should consider the use of new stream IO feature in new code
4370 for future portability. See also @ref{Fortran 2003 status}.
4372 @item @emph{Standard}:
4378 @item @emph{Syntax}:
4379 @code{CALL FSEEK(UNIT, OFFSET, WHENCE[, STATUS])}
4381 @item @emph{Arguments}:
4382 @multitable @columnfractions .15 .70
4383 @item @var{UNIT} @tab Shall be a scalar of type @code{INTEGER}.
4384 @item @var{OFFSET} @tab Shall be a scalar of type @code{INTEGER}.
4385 @item @var{WHENCE} @tab Shall be a scalar of type @code{INTEGER}.
4386 Its value shall be either 0, 1 or 2.
4387 @item @var{STATUS} @tab (Optional) shall be a scalar of type
4391 @item @emph{Example}:
4394 INTEGER, PARAMETER :: SEEK_SET = 0, SEEK_CUR = 1, SEEK_END = 2
4395 INTEGER :: fd, offset, ierr
4401 OPEN(UNIT=fd, FILE="fseek.test")
4402 CALL FSEEK(fd, offset, SEEK_SET, ierr) ! move to OFFSET
4403 print *, FTELL(fd), ierr
4405 CALL FSEEK(fd, 0, SEEK_END, ierr) ! move to end
4406 print *, FTELL(fd), ierr
4408 CALL FSEEK(fd, 0, SEEK_SET, ierr) ! move to beginning
4409 print *, FTELL(fd), ierr
4415 @item @emph{See also}:
4422 @section @code{FSTAT} --- Get file status
4424 @cindex file system, file status
4427 @item @emph{Description}:
4428 @code{FSTAT} is identical to @ref{STAT}, except that information about an
4429 already opened file is obtained.
4431 The elements in @code{BUFF} are the same as described by @ref{STAT}.
4433 This intrinsic is provided in both subroutine and function forms; however,
4434 only one form can be used in any given program unit.
4436 @item @emph{Standard}:
4440 Subroutine, function
4442 @item @emph{Syntax}:
4443 @code{CALL FSTAT(UNIT, BUFF [, STATUS])}
4445 @item @emph{Arguments}:
4446 @multitable @columnfractions .15 .70
4447 @item @var{UNIT} @tab An open I/O unit number of type @code{INTEGER}.
4448 @item @var{BUFF} @tab The type shall be @code{INTEGER(4), DIMENSION(13)}.
4449 @item @var{STATUS} @tab (Optional) status flag of type @code{INTEGER(4)}. Returns 0
4450 on success and a system specific error code otherwise.
4453 @item @emph{Example}:
4454 See @ref{STAT} for an example.
4456 @item @emph{See also}:
4457 To stat a link: @ref{LSTAT}, to stat a file: @ref{STAT}
4463 @section @code{FTELL} --- Current stream position
4465 @cindex file operation, position
4468 @item @emph{Description}:
4469 Retrieves the current position within an open file.
4471 This intrinsic is provided in both subroutine and function forms; however,
4472 only one form can be used in any given program unit.
4474 @item @emph{Standard}:
4478 Subroutine, function
4480 @item @emph{Syntax}:
4481 @multitable @columnfractions .80
4482 @item @code{CALL FTELL(UNIT, OFFSET)}
4483 @item @code{OFFSET = FTELL(UNIT)}
4486 @item @emph{Arguments}:
4487 @multitable @columnfractions .15 .70
4488 @item @var{OFFSET} @tab Shall of type @code{INTEGER}.
4489 @item @var{UNIT} @tab Shall of type @code{INTEGER}.
4492 @item @emph{Return value}:
4493 In either syntax, @var{OFFSET} is set to the current offset of unit
4494 number @var{UNIT}, or to @math{-1} if the unit is not currently open.
4496 @item @emph{Example}:
4500 OPEN(10, FILE="temp.dat")
4506 @item @emph{See also}:
4513 @section @code{GAMMA} --- Gamma function
4516 @cindex Gamma function
4517 @cindex Factorial function
4520 @item @emph{Description}:
4521 @code{GAMMA(X)} computes Gamma (@math{\Gamma}) of @var{X}. For positive,
4522 integer values of @var{X} the Gamma function simplifies to the factorial
4523 function @math{\Gamma(x)=(x-1)!}.
4527 \Gamma(x) = \int_0^\infty t^{x-1}{\rm e}^{-t}\,{\rm d}t
4531 @item @emph{Standard}:
4537 @item @emph{Syntax}:
4540 @item @emph{Arguments}:
4541 @multitable @columnfractions .15 .70
4542 @item @var{X} @tab Shall be of type @code{REAL} and neither zero
4543 nor a negative integer.
4546 @item @emph{Return value}:
4547 The return value is of type @code{REAL} of the same kind as @var{X}.
4549 @item @emph{Example}:
4553 x = gamma(x) ! returns 1.0
4554 end program test_gamma
4557 @item @emph{Specific names}:
4558 @multitable @columnfractions .20 .20 .20 .25
4559 @item Name @tab Argument @tab Return type @tab Standard
4560 @item @code{GAMMA(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab GNU Extension
4561 @item @code{DGAMMA(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU Extension
4564 @item @emph{See also}:
4565 Logarithm of the Gamma function: @ref{LGAMMA}
4572 @section @code{GERROR} --- Get last system error message
4574 @cindex system, error handling
4577 @item @emph{Description}:
4578 Returns the system error message corresponding to the last system error.
4579 This resembles the functionality of @code{strerror(3)} in C.
4581 @item @emph{Standard}:
4587 @item @emph{Syntax}:
4588 @code{CALL GERROR(RESULT)}
4590 @item @emph{Arguments}:
4591 @multitable @columnfractions .15 .70
4592 @item @var{RESULT} @tab Shall of type @code{CHARACTER(*)}.
4595 @item @emph{Example}:
4598 CHARACTER(len=100) :: msg
4604 @item @emph{See also}:
4605 @ref{IERRNO}, @ref{PERROR}
4611 @section @code{GETARG} --- Get command line arguments
4613 @cindex command-line arguments
4614 @cindex arguments, to program
4617 @item @emph{Description}:
4618 Retrieve the @var{N}th argument that was passed on the
4619 command line when the containing program was invoked.
4621 This intrinsic routine is provided for backwards compatibility with
4622 GNU Fortran 77. In new code, programmers should consider the use of
4623 the @ref{GET_COMMAND_ARGUMENT} intrinsic defined by the Fortran 2003
4626 @item @emph{Standard}:
4632 @item @emph{Syntax}:
4633 @code{CALL GETARG(POS, VALUE)}
4635 @item @emph{Arguments}:
4636 @multitable @columnfractions .15 .70
4637 @item @var{POS} @tab Shall be of type @code{INTEGER} and not wider than
4638 the default integer kind; @math{@var{POS} \geq 0}
4639 @item @var{VALUE} @tab Shall be of type @code{CHARACTER(*)}.
4642 @item @emph{Return value}:
4643 After @code{GETARG} returns, the @var{VALUE} argument holds the
4644 @var{POS}th command line argument. If @var{VALUE} can not hold the
4645 argument, it is truncated to fit the length of @var{VALUE}. If there are
4646 less than @var{POS} arguments specified at the command line, @var{VALUE}
4647 will be filled with blanks. If @math{@var{POS} = 0}, @var{VALUE} is set
4648 to the name of the program (on systems that support this feature).
4650 @item @emph{Example}:
4654 CHARACTER(len=32) :: arg
4663 @item @emph{See also}:
4664 GNU Fortran 77 compatibility function: @ref{IARGC}
4666 F2003 functions and subroutines: @ref{GET_COMMAND}, @ref{GET_COMMAND_ARGUMENT},
4667 @ref{COMMAND_ARGUMENT_COUNT}
4673 @section @code{GET_COMMAND} --- Get the entire command line
4674 @fnindex GET_COMMAND
4675 @cindex command-line arguments
4676 @cindex arguments, to program
4679 @item @emph{Description}:
4680 Retrieve the entire command line that was used to invoke the program.
4682 @item @emph{Standard}:
4688 @item @emph{Syntax}:
4689 @code{CALL GET_COMMAND(CMD)}
4691 @item @emph{Arguments}:
4692 @multitable @columnfractions .15 .70
4693 @item @var{CMD} @tab Shall be of type @code{CHARACTER(*)}.
4696 @item @emph{Return value}:
4697 Stores the entire command line that was used to invoke the program in @var{ARG}.
4698 If @var{ARG} is not large enough, the command will be truncated.
4700 @item @emph{Example}:
4702 PROGRAM test_get_command
4703 CHARACTER(len=255) :: cmd
4704 CALL get_command(cmd)
4705 WRITE (*,*) TRIM(cmd)
4709 @item @emph{See also}:
4710 @ref{GET_COMMAND_ARGUMENT}, @ref{COMMAND_ARGUMENT_COUNT}
4715 @node GET_COMMAND_ARGUMENT
4716 @section @code{GET_COMMAND_ARGUMENT} --- Get command line arguments
4717 @fnindex GET_COMMAND_ARGUMENT
4718 @cindex command-line arguments
4719 @cindex arguments, to program
4722 @item @emph{Description}:
4723 Retrieve the @var{N}th argument that was passed on the
4724 command line when the containing program was invoked.
4726 @item @emph{Standard}:
4732 @item @emph{Syntax}:
4733 @code{CALL GET_COMMAND_ARGUMENT(N, ARG)}
4735 @item @emph{Arguments}:
4736 @multitable @columnfractions .15 .70
4737 @item @var{N} @tab Shall be of type @code{INTEGER(4)}, @math{@var{N} \geq 0}
4738 @item @var{ARG} @tab Shall be of type @code{CHARACTER(*)}.
4741 @item @emph{Return value}:
4742 After @code{GET_COMMAND_ARGUMENT} returns, the @var{ARG} argument holds the
4743 @var{N}th command line argument. If @var{ARG} can not hold the argument, it is
4744 truncated to fit the length of @var{ARG}. If there are less than @var{N}
4745 arguments specified at the command line, @var{ARG} will be filled with blanks.
4746 If @math{@var{N} = 0}, @var{ARG} is set to the name of the program (on systems
4747 that support this feature).
4749 @item @emph{Example}:
4751 PROGRAM test_get_command_argument
4753 CHARACTER(len=32) :: arg
4757 CALL get_command_argument(i, arg)
4758 IF (LEN_TRIM(arg) == 0) EXIT
4760 WRITE (*,*) TRIM(arg)
4766 @item @emph{See also}:
4767 @ref{GET_COMMAND}, @ref{COMMAND_ARGUMENT_COUNT}
4773 @section @code{GETCWD} --- Get current working directory
4775 @cindex system, working directory
4778 @item @emph{Description}:
4779 Get current working directory.
4781 This intrinsic is provided in both subroutine and function forms; however,
4782 only one form can be used in any given program unit.
4784 @item @emph{Standard}:
4788 Subroutine, function
4790 @item @emph{Syntax}:
4791 @code{CALL GETCWD(CWD [, STATUS])}
4793 @item @emph{Arguments}:
4794 @multitable @columnfractions .15 .70
4795 @item @var{CWD} @tab The type shall be @code{CHARACTER(*)}.
4796 @item @var{STATUS} @tab (Optional) status flag. Returns 0 on success,
4797 a system specific and nonzero error code otherwise.
4800 @item @emph{Example}:
4803 CHARACTER(len=255) :: cwd
4805 WRITE(*,*) TRIM(cwd)
4809 @item @emph{See also}:
4816 @section @code{GETENV} --- Get an environmental variable
4818 @cindex environment variable
4821 @item @emph{Description}:
4822 Get the @var{VALUE} of the environmental variable @var{ENVVAR}.
4824 This intrinsic routine is provided for backwards compatibility with
4825 GNU Fortran 77. In new code, programmers should consider the use of
4826 the @ref{GET_ENVIRONMENT_VARIABLE} intrinsic defined by the Fortran
4829 @item @emph{Standard}:
4835 @item @emph{Syntax}:
4836 @code{CALL GETENV(ENVVAR, VALUE)}
4838 @item @emph{Arguments}:
4839 @multitable @columnfractions .15 .70
4840 @item @var{ENVVAR} @tab Shall be of type @code{CHARACTER(*)}.
4841 @item @var{VALUE} @tab Shall be of type @code{CHARACTER(*)}.
4844 @item @emph{Return value}:
4845 Stores the value of @var{ENVVAR} in @var{VALUE}. If @var{VALUE} is
4846 not large enough to hold the data, it is truncated. If @var{ENVVAR}
4847 is not set, @var{VALUE} will be filled with blanks.
4849 @item @emph{Example}:
4852 CHARACTER(len=255) :: homedir
4853 CALL getenv("HOME", homedir)
4854 WRITE (*,*) TRIM(homedir)
4858 @item @emph{See also}:
4859 @ref{GET_ENVIRONMENT_VARIABLE}
4864 @node GET_ENVIRONMENT_VARIABLE
4865 @section @code{GET_ENVIRONMENT_VARIABLE} --- Get an environmental variable
4866 @fnindex GET_ENVIRONMENT_VARIABLE
4867 @cindex environment variable
4870 @item @emph{Description}:
4871 Get the @var{VALUE} of the environmental variable @var{ENVVAR}.
4873 @item @emph{Standard}:
4879 @item @emph{Syntax}:
4880 @code{CALL GET_ENVIRONMENT_VARIABLE(ENVVAR, VALUE)}
4882 @item @emph{Arguments}:
4883 @multitable @columnfractions .15 .70
4884 @item @var{ENVVAR} @tab Shall be of type @code{CHARACTER(*)}.
4885 @item @var{VALUE} @tab Shall be of type @code{CHARACTER(*)}.
4888 @item @emph{Return value}:
4889 Stores the value of @var{ENVVAR} in @var{VALUE}. If @var{VALUE} is
4890 not large enough to hold the data, it is truncated. If @var{ENVVAR}
4891 is not set, @var{VALUE} will be filled with blanks.
4893 @item @emph{Example}:
4896 CHARACTER(len=255) :: homedir
4897 CALL get_environment_variable("HOME", homedir)
4898 WRITE (*,*) TRIM(homedir)
4906 @section @code{GETGID} --- Group ID function
4908 @cindex system, group id
4911 @item @emph{Description}:
4912 Returns the numerical group ID of the current process.
4914 @item @emph{Standard}:
4920 @item @emph{Syntax}:
4921 @code{RESULT = GETGID()}
4923 @item @emph{Return value}:
4924 The return value of @code{GETGID} is an @code{INTEGER} of the default
4928 @item @emph{Example}:
4929 See @code{GETPID} for an example.
4931 @item @emph{See also}:
4932 @ref{GETPID}, @ref{GETUID}
4938 @section @code{GETLOG} --- Get login name
4940 @cindex system, login name
4944 @item @emph{Description}:
4945 Gets the username under which the program is running.
4947 @item @emph{Standard}:
4953 @item @emph{Syntax}:
4954 @code{CALL GETLOG(LOGIN)}
4956 @item @emph{Arguments}:
4957 @multitable @columnfractions .15 .70
4958 @item @var{LOGIN} @tab Shall be of type @code{CHARACTER(*)}.
4961 @item @emph{Return value}:
4962 Stores the current user name in @var{LOGIN}. (On systems where POSIX
4963 functions @code{geteuid} and @code{getpwuid} are not available, and
4964 the @code{getlogin} function is not implemented either, this will
4965 return a blank string.)
4967 @item @emph{Example}:
4970 CHARACTER(32) :: login
4976 @item @emph{See also}:
4983 @section @code{GETPID} --- Process ID function
4985 @cindex system, process id
4989 @item @emph{Description}:
4990 Returns the numerical process identifier of the current process.
4992 @item @emph{Standard}:
4998 @item @emph{Syntax}:
4999 @code{RESULT = GETPID()}
5001 @item @emph{Return value}:
5002 The return value of @code{GETPID} is an @code{INTEGER} of the default
5006 @item @emph{Example}:
5009 print *, "The current process ID is ", getpid()
5010 print *, "Your numerical user ID is ", getuid()
5011 print *, "Your numerical group ID is ", getgid()
5015 @item @emph{See also}:
5016 @ref{GETGID}, @ref{GETUID}
5022 @section @code{GETUID} --- User ID function
5024 @cindex system, user id
5028 @item @emph{Description}:
5029 Returns the numerical user ID of the current process.
5031 @item @emph{Standard}:
5037 @item @emph{Syntax}:
5038 @code{RESULT = GETUID()}
5040 @item @emph{Return value}:
5041 The return value of @code{GETUID} is an @code{INTEGER} of the default
5045 @item @emph{Example}:
5046 See @code{GETPID} for an example.
5048 @item @emph{See also}:
5049 @ref{GETPID}, @ref{GETLOG}
5055 @section @code{GMTIME} --- Convert time to GMT info
5057 @cindex time, conversion to GMT info
5060 @item @emph{Description}:
5061 Given a system time value @var{STIME} (as provided by the @code{TIME8()}
5062 intrinsic), fills @var{TARRAY} with values extracted from it appropriate
5063 to the UTC time zone (Universal Coordinated Time, also known in some
5064 countries as GMT, Greenwich Mean Time), using @code{gmtime(3)}.
5066 @item @emph{Standard}:
5072 @item @emph{Syntax}:
5073 @code{CALL GMTIME(STIME, TARRAY)}
5075 @item @emph{Arguments}:
5076 @multitable @columnfractions .15 .70
5077 @item @var{STIME} @tab An @code{INTEGER(*)} scalar expression
5078 corresponding to a system time, with
5080 @item @var{TARRAY} @tab A default @code{INTEGER} array with 9 elements,
5081 with @code{INTENT(OUT)}.
5084 @item @emph{Return value}:
5085 The elements of @var{TARRAY} are assigned as follows:
5087 @item Seconds after the minute, range 0--59 or 0--61 to allow for leap
5089 @item Minutes after the hour, range 0--59
5090 @item Hours past midnight, range 0--23
5091 @item Day of month, range 0--31
5092 @item Number of months since January, range 0--12
5093 @item Years since 1900
5094 @item Number of days since Sunday, range 0--6
5095 @item Days since January 1
5096 @item Daylight savings indicator: positive if daylight savings is in
5097 effect, zero if not, and negative if the information is not
5101 @item @emph{See also}:
5102 @ref{CTIME}, @ref{LTIME}, @ref{TIME}, @ref{TIME8}
5109 @section @code{HOSTNM} --- Get system host name
5111 @cindex system, host name
5114 @item @emph{Description}:
5115 Retrieves the host name of the system on which the program is running.
5117 This intrinsic is provided in both subroutine and function forms; however,
5118 only one form can be used in any given program unit.
5120 @item @emph{Standard}:
5124 Subroutine, function
5126 @item @emph{Syntax}:
5127 @multitable @columnfractions .80
5128 @item @code{CALL HOSTNM(NAME[, STATUS])}
5129 @item @code{STATUS = HOSTNM(NAME)}
5132 @item @emph{Arguments}:
5133 @multitable @columnfractions .15 .70
5134 @item @var{NAME} @tab Shall of type @code{CHARACTER(*)}.
5135 @item @var{STATUS} @tab (Optional) status flag of type @code{INTEGER}.
5136 Returns 0 on success, or a system specific error
5140 @item @emph{Return value}:
5141 In either syntax, @var{NAME} is set to the current hostname if it can
5142 be obtained, or to a blank string otherwise.
5149 @section @code{HUGE} --- Largest number of a kind
5151 @cindex limits, largest number
5152 @cindex model representation, largest number
5155 @item @emph{Description}:
5156 @code{HUGE(X)} returns the largest number that is not an infinity in
5157 the model of the type of @code{X}.
5159 @item @emph{Standard}:
5165 @item @emph{Syntax}:
5166 @code{RESULT = HUGE(X)}
5168 @item @emph{Arguments}:
5169 @multitable @columnfractions .15 .70
5170 @item @var{X} @tab Shall be of type @code{REAL} or @code{INTEGER}.
5173 @item @emph{Return value}:
5174 The return value is of the same type and kind as @var{X}
5176 @item @emph{Example}:
5178 program test_huge_tiny
5179 print *, huge(0), huge(0.0), huge(0.0d0)
5180 print *, tiny(0.0), tiny(0.0d0)
5181 end program test_huge_tiny
5188 @section @code{IACHAR} --- Code in @acronym{ASCII} collating sequence
5190 @cindex @acronym{ASCII} collating sequence
5191 @cindex collating sequence, @acronym{ASCII}
5192 @cindex conversion, to integer
5195 @item @emph{Description}:
5196 @code{IACHAR(C)} returns the code for the @acronym{ASCII} character
5197 in the first character position of @code{C}.
5199 @item @emph{Standard}:
5205 @item @emph{Syntax}:
5206 @code{RESULT = IACHAR(C [, KIND])}
5208 @item @emph{Arguments}:
5209 @multitable @columnfractions .15 .70
5210 @item @var{C} @tab Shall be a scalar @code{CHARACTER}, with @code{INTENT(IN)}
5211 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
5212 expression indicating the kind parameter of
5216 @item @emph{Return value}:
5217 The return value is of type @code{INTEGER} and of kind @var{KIND}. If
5218 @var{KIND} is absent, the return value is of default integer kind.
5220 @item @emph{Example}:
5225 end program test_iachar
5229 See @ref{ICHAR} for a discussion of converting between numerical values
5230 and formatted string representations.
5232 @item @emph{See also}:
5233 @ref{ACHAR}, @ref{CHAR}, @ref{ICHAR}
5240 @section @code{IAND} --- Bitwise logical and
5242 @cindex bitwise logical and
5243 @cindex logical and, bitwise
5246 @item @emph{Description}:
5247 Bitwise logical @code{AND}.
5249 @item @emph{Standard}:
5255 @item @emph{Syntax}:
5256 @code{RESULT = IAND(I, J)}
5258 @item @emph{Arguments}:
5259 @multitable @columnfractions .15 .70
5260 @item @var{I} @tab The type shall be @code{INTEGER(*)}.
5261 @item @var{J} @tab The type shall be @code{INTEGER(*)}, of the same
5262 kind as @var{I}. (As a GNU extension, different kinds are also
5266 @item @emph{Return value}:
5267 The return type is @code{INTEGER(*)}, of the same kind as the
5268 arguments. (If the argument kinds differ, it is of the same kind as
5269 the larger argument.)
5271 @item @emph{Example}:
5275 DATA a / Z'F' /, b / Z'3' /
5276 WRITE (*,*) IAND(a, b)
5280 @item @emph{See also}:
5281 @ref{IOR}, @ref{IEOR}, @ref{IBITS}, @ref{IBSET}, @ref{IBCLR}, @ref{NOT}
5288 @section @code{IARGC} --- Get the number of command line arguments
5290 @cindex command-line arguments
5291 @cindex command-line arguments, number of
5292 @cindex arguments, to program
5295 @item @emph{Description}:
5296 @code{IARGC()} returns the number of arguments passed on the
5297 command line when the containing program was invoked.
5299 This intrinsic routine is provided for backwards compatibility with
5300 GNU Fortran 77. In new code, programmers should consider the use of
5301 the @ref{COMMAND_ARGUMENT_COUNT} intrinsic defined by the Fortran 2003
5304 @item @emph{Standard}:
5310 @item @emph{Syntax}:
5311 @code{RESULT = IARGC()}
5313 @item @emph{Arguments}:
5316 @item @emph{Return value}:
5317 The number of command line arguments, type @code{INTEGER(4)}.
5319 @item @emph{Example}:
5322 @item @emph{See also}:
5323 GNU Fortran 77 compatibility subroutine: @ref{GETARG}
5325 F2003 functions and subroutines: @ref{GET_COMMAND}, @ref{GET_COMMAND_ARGUMENT},
5326 @ref{COMMAND_ARGUMENT_COUNT}
5332 @section @code{IBCLR} --- Clear bit
5338 @item @emph{Description}:
5339 @code{IBCLR} returns the value of @var{I} with the bit at position
5340 @var{POS} set to zero.
5342 @item @emph{Standard}:
5348 @item @emph{Syntax}:
5349 @code{RESULT = IBCLR(I, POS)}
5351 @item @emph{Arguments}:
5352 @multitable @columnfractions .15 .70
5353 @item @var{I} @tab The type shall be @code{INTEGER(*)}.
5354 @item @var{POS} @tab The type shall be @code{INTEGER(*)}.
5357 @item @emph{Return value}:
5358 The return value is of type @code{INTEGER(*)} and of the same kind as
5361 @item @emph{See also}:
5362 @ref{IBITS}, @ref{IBSET}, @ref{IAND}, @ref{IOR}, @ref{IEOR}, @ref{MVBITS}
5369 @section @code{IBITS} --- Bit extraction
5372 @cindex bits, extract
5375 @item @emph{Description}:
5376 @code{IBITS} extracts a field of length @var{LEN} from @var{I},
5377 starting from bit position @var{POS} and extending left for @var{LEN}
5378 bits. The result is right-justified and the remaining bits are
5379 zeroed. The value of @code{POS+LEN} must be less than or equal to the
5380 value @code{BIT_SIZE(I)}.
5382 @item @emph{Standard}:
5388 @item @emph{Syntax}:
5389 @code{RESULT = IBITS(I, POS, LEN)}
5391 @item @emph{Arguments}:
5392 @multitable @columnfractions .15 .70
5393 @item @var{I} @tab The type shall be @code{INTEGER(*)}.
5394 @item @var{POS} @tab The type shall be @code{INTEGER(*)}.
5395 @item @var{LEN} @tab The type shall be @code{INTEGER(*)}.
5398 @item @emph{Return value}:
5399 The return value is of type @code{INTEGER(*)} and of the same kind as
5402 @item @emph{See also}:
5403 @ref{BIT_SIZE}, @ref{IBCLR}, @ref{IBSET}, @ref{IAND}, @ref{IOR}, @ref{IEOR}
5409 @section @code{IBSET} --- Set bit
5414 @item @emph{Description}:
5415 @code{IBSET} returns the value of @var{I} with the bit at position
5416 @var{POS} set to one.
5418 @item @emph{Standard}:
5424 @item @emph{Syntax}:
5425 @code{RESULT = IBSET(I, POS)}
5427 @item @emph{Arguments}:
5428 @multitable @columnfractions .15 .70
5429 @item @var{I} @tab The type shall be @code{INTEGER(*)}.
5430 @item @var{POS} @tab The type shall be @code{INTEGER(*)}.
5433 @item @emph{Return value}:
5434 The return value is of type @code{INTEGER(*)} and of the same kind as
5437 @item @emph{See also}:
5438 @ref{IBCLR}, @ref{IBITS}, @ref{IAND}, @ref{IOR}, @ref{IEOR}, @ref{MVBITS}
5445 @section @code{ICHAR} --- Character-to-integer conversion function
5447 @cindex conversion, to integer
5450 @item @emph{Description}:
5451 @code{ICHAR(C)} returns the code for the character in the first character
5452 position of @code{C} in the system's native character set.
5453 The correspondence between characters and their codes is not necessarily
5454 the same across different GNU Fortran implementations.
5456 @item @emph{Standard}:
5462 @item @emph{Syntax}:
5463 @code{RESULT = ICHAR(C [, KIND])}
5465 @item @emph{Arguments}:
5466 @multitable @columnfractions .15 .70
5467 @item @var{C} @tab Shall be a scalar @code{CHARACTER}, with @code{INTENT(IN)}
5468 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
5469 expression indicating the kind parameter of
5473 @item @emph{Return value}:
5474 The return value is of type @code{INTEGER} and of kind @var{KIND}. If
5475 @var{KIND} is absent, the return value is of default integer kind.
5477 @item @emph{Example}:
5482 end program test_ichar
5486 No intrinsic exists to convert between a numeric value and a formatted
5487 character string representation -- for instance, given the
5488 @code{CHARACTER} value @code{'154'}, obtaining an @code{INTEGER} or
5489 @code{REAL} value with the value 154, or vice versa. Instead, this
5490 functionality is provided by internal-file I/O, as in the following
5495 character(len=10) string, string2
5498 ! Convert a string to a numeric value
5499 read (string,'(I10)') value
5502 ! Convert a value to a formatted string
5503 write (string2,'(I10)') value
5505 end program read_val
5508 @item @emph{See also}:
5509 @ref{ACHAR}, @ref{CHAR}, @ref{IACHAR}
5516 @section @code{IDATE} --- Get current local time subroutine (day/month/year)
5518 @cindex date, current
5519 @cindex current date
5522 @item @emph{Description}:
5523 @code{IDATE(TARRAY)} Fills @var{TARRAY} with the numerical values at the
5524 current local time. The day (in the range 1-31), month (in the range 1-12),
5525 and year appear in elements 1, 2, and 3 of @var{TARRAY}, respectively.
5526 The year has four significant digits.
5528 @item @emph{Standard}:
5534 @item @emph{Syntax}:
5535 @code{CALL IDATE(TARRAY)}
5537 @item @emph{Arguments}:
5538 @multitable @columnfractions .15 .70
5539 @item @var{TARRAY} @tab The type shall be @code{INTEGER, DIMENSION(3)} and
5540 the kind shall be the default integer kind.
5543 @item @emph{Return value}:
5546 @item @emph{Example}:
5549 integer, dimension(3) :: tarray
5554 end program test_idate
5561 @section @code{IEOR} --- Bitwise logical exclusive or
5563 @cindex bitwise logical exclusive or
5564 @cindex logical exclusive or, bitwise
5567 @item @emph{Description}:
5568 @code{IEOR} returns the bitwise boolean exclusive-OR of @var{I} and
5571 @item @emph{Standard}:
5577 @item @emph{Syntax}:
5578 @code{RESULT = IEOR(I, J)}
5580 @item @emph{Arguments}:
5581 @multitable @columnfractions .15 .70
5582 @item @var{I} @tab The type shall be @code{INTEGER(*)}.
5583 @item @var{J} @tab The type shall be @code{INTEGER(*)}, of the same
5584 kind as @var{I}. (As a GNU extension, different kinds are also
5588 @item @emph{Return value}:
5589 The return type is @code{INTEGER(*)}, of the same kind as the
5590 arguments. (If the argument kinds differ, it is of the same kind as
5591 the larger argument.)
5593 @item @emph{See also}:
5594 @ref{IOR}, @ref{IAND}, @ref{IBITS}, @ref{IBSET}, @ref{IBCLR}, @ref{NOT}
5600 @section @code{IERRNO} --- Get the last system error number
5602 @cindex system, error handling
5605 @item @emph{Description}:
5606 Returns the last system error number, as given by the C @code{errno()}
5609 @item @emph{Standard}:
5615 @item @emph{Syntax}:
5616 @code{RESULT = IERRNO()}
5618 @item @emph{Arguments}:
5621 @item @emph{Return value}:
5622 The return value is of type @code{INTEGER} and of the default integer
5625 @item @emph{See also}:
5631 @node INDEX intrinsic
5632 @section @code{INDEX} --- Position of a substring within a string
5634 @cindex substring position
5635 @cindex string, find substring
5638 @item @emph{Description}:
5639 Returns the position of the start of the first occurrence of string
5640 @var{SUBSTRING} as a substring in @var{STRING}, counting from one. If
5641 @var{SUBSTRING} is not present in @var{STRING}, zero is returned. If
5642 the @var{BACK} argument is present and true, the return value is the
5643 start of the last occurrence rather than the first.
5645 @item @emph{Standard}:
5651 @item @emph{Syntax}:
5652 @code{RESULT = INDEX(STRING, SUBSTRING [, BACK [, KIND]])}
5654 @item @emph{Arguments}:
5655 @multitable @columnfractions .15 .70
5656 @item @var{STRING} @tab Shall be a scalar @code{CHARACTER(*)}, with
5658 @item @var{SUBSTRING} @tab Shall be a scalar @code{CHARACTER(*)}, with
5660 @item @var{BACK} @tab (Optional) Shall be a scalar @code{LOGICAL(*)}, with
5662 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
5663 expression indicating the kind parameter of
5667 @item @emph{Return value}:
5668 The return value is of type @code{INTEGER} and of kind @var{KIND}. If
5669 @var{KIND} is absent, the return value is of default integer kind.
5671 @item @emph{See also}:
5672 @ref{SCAN}, @ref{VERIFY}
5678 @section @code{INT} --- Convert to integer type
5682 @cindex conversion, to integer
5685 @item @emph{Description}:
5686 Convert to integer type
5688 @item @emph{Standard}:
5694 @item @emph{Syntax}:
5695 @code{RESULT = INT(A [, KIND))}
5697 @item @emph{Arguments}:
5698 @multitable @columnfractions .15 .70
5699 @item @var{A} @tab Shall be of type @code{INTEGER(*)},
5700 @code{REAL(*)}, or @code{COMPLEX(*)}.
5701 @item @var{KIND} @tab (Optional) An @code{INTEGER(*)} initialization
5702 expression indicating the kind parameter of
5706 @item @emph{Return value}:
5707 These functions return a @code{INTEGER(*)} variable or array under
5708 the following rules:
5712 If @var{A} is of type @code{INTEGER(*)}, @code{INT(A) = A}
5714 If @var{A} is of type @code{REAL(*)} and @math{|A| < 1}, @code{INT(A)} equals @code{0}.
5715 If @math{|A| \geq 1}, then @code{INT(A)} equals the largest integer that does not exceed
5716 the range of @var{A} and whose sign is the same as the sign of @var{A}.
5718 If @var{A} is of type @code{COMPLEX(*)}, rule B is applied to the real part of @var{A}.
5721 @item @emph{Example}:
5725 complex :: z = (-3.7, 1.0)
5727 print *, int(z), int(z,8)
5731 @item @emph{Specific names}:
5732 @multitable @columnfractions .20 .20 .20 .25
5733 @item Name @tab Argument @tab Return type @tab Standard
5734 @item @code{IFIX(A)} @tab @code{REAL(4) A} @tab @code{INTEGER} @tab F77 and later
5735 @item @code{IDINT(A)} @tab @code{REAL(8) A} @tab @code{INTEGER} @tab F77 and later
5743 @section @code{INT2} --- Convert to 16-bit integer type
5746 @cindex conversion, to integer
5749 @item @emph{Description}:
5750 Convert to a @code{KIND=2} integer type. This is equivalent to the
5751 standard @code{INT} intrinsic with an optional argument of
5752 @code{KIND=2}, and is only included for backwards compatibility.
5754 The @code{SHORT} intrinsic is equivalent to @code{INT2}.
5756 @item @emph{Standard}:
5762 @item @emph{Syntax}:
5763 @code{RESULT = INT2(A)}
5765 @item @emph{Arguments}:
5766 @multitable @columnfractions .15 .70
5767 @item @var{A} @tab Shall be of type @code{INTEGER(*)},
5768 @code{REAL(*)}, or @code{COMPLEX(*)}.
5771 @item @emph{Return value}:
5772 The return value is a @code{INTEGER(2)} variable.
5774 @item @emph{See also}:
5775 @ref{INT}, @ref{INT8}, @ref{LONG}
5781 @section @code{INT8} --- Convert to 64-bit integer type
5783 @cindex conversion, to integer
5786 @item @emph{Description}:
5787 Convert to a @code{KIND=8} integer type. This is equivalent to the
5788 standard @code{INT} intrinsic with an optional argument of
5789 @code{KIND=8}, and is only included for backwards compatibility.
5791 @item @emph{Standard}:
5797 @item @emph{Syntax}:
5798 @code{RESULT = INT8(A)}
5800 @item @emph{Arguments}:
5801 @multitable @columnfractions .15 .70
5802 @item @var{A} @tab Shall be of type @code{INTEGER(*)},
5803 @code{REAL(*)}, or @code{COMPLEX(*)}.
5806 @item @emph{Return value}:
5807 The return value is a @code{INTEGER(8)} variable.
5809 @item @emph{See also}:
5810 @ref{INT}, @ref{INT2}, @ref{LONG}
5816 @section @code{IOR} --- Bitwise logical or
5818 @cindex bitwise logical or
5819 @cindex logical or, bitwise
5822 @item @emph{Description}:
5823 @code{IOR} returns the bitwise boolean inclusive-OR of @var{I} and
5826 @item @emph{Standard}:
5832 @item @emph{Syntax}:
5833 @code{RESULT = IOR(I, J)}
5835 @item @emph{Arguments}:
5836 @multitable @columnfractions .15 .70
5837 @item @var{I} @tab The type shall be @code{INTEGER(*)}.
5838 @item @var{J} @tab The type shall be @code{INTEGER(*)}, of the same
5839 kind as @var{I}. (As a GNU extension, different kinds are also
5843 @item @emph{Return value}:
5844 The return type is @code{INTEGER(*)}, of the same kind as the
5845 arguments. (If the argument kinds differ, it is of the same kind as
5846 the larger argument.)
5848 @item @emph{See also}:
5849 @ref{IEOR}, @ref{IAND}, @ref{IBITS}, @ref{IBSET}, @ref{IBCLR}, @ref{NOT}
5855 @section @code{IRAND} --- Integer pseudo-random number
5857 @cindex random number generation
5860 @item @emph{Description}:
5861 @code{IRAND(FLAG)} returns a pseudo-random number from a uniform
5862 distribution between 0 and a system-dependent limit (which is in most
5863 cases 2147483647). If @var{FLAG} is 0, the next number
5864 in the current sequence is returned; if @var{FLAG} is 1, the generator
5865 is restarted by @code{CALL SRAND(0)}; if @var{FLAG} has any other value,
5866 it is used as a new seed with @code{SRAND}.
5868 This intrinsic routine is provided for backwards compatibility with
5869 GNU Fortran 77. It implements a simple modulo generator as provided
5870 by @command{g77}. For new code, one should consider the use of
5871 @ref{RANDOM_NUMBER} as it implements a superior algorithm.
5873 @item @emph{Standard}:
5879 @item @emph{Syntax}:
5880 @code{RESULT = IRAND(FLAG)}
5882 @item @emph{Arguments}:
5883 @multitable @columnfractions .15 .70
5884 @item @var{FLAG} @tab Shall be a scalar @code{INTEGER} of kind 4.
5887 @item @emph{Return value}:
5888 The return value is of @code{INTEGER(kind=4)} type.
5890 @item @emph{Example}:
5893 integer,parameter :: seed = 86456
5896 print *, irand(), irand(), irand(), irand()
5897 print *, irand(seed), irand(), irand(), irand()
5898 end program test_irand
5906 @section @code{IS_IOSTAT_END} --- Test for end-of-file value
5907 @fnindex IS_IOSTAT_END
5908 @cindex IOSTAT, end of file
5911 @item @emph{Description}:
5912 @code{IS_IOSTAT_END} tests whether an variable has the value of the I/O
5913 status ``end of file''. The function is equivalent to comparing the variable
5914 with the @code{IOSTAT_END} parameter of the intrinsic module
5915 @code{ISO_FORTRAN_ENV}.
5917 @item @emph{Standard}:
5923 @item @emph{Syntax}:
5924 @code{RESULT = IS_IOSTAT_END(I)}
5926 @item @emph{Arguments}:
5927 @multitable @columnfractions .15 .70
5928 @item @var{I} @tab Shall be of the type @code{INTEGER}.
5931 @item @emph{Return value}:
5932 Returns a @code{LOGICAL} of the default kind, which @code{.TRUE.} if
5933 @var{I} has the value which indicates an end of file condition for
5934 IOSTAT= specifiers, and is @code{.FALSE.} otherwise.
5936 @item @emph{Example}:
5941 OPEN(88, FILE='test.dat')
5942 READ(88, *, IOSTAT=stat) i
5943 IF(IS_IOSTAT_END(stat)) STOP 'END OF FILE'
5951 @section @code{IS_IOSTAT_EOR} --- Test for end-of-record value
5952 @fnindex IS_IOSTAT_EOR
5953 @cindex IOSTAT, end of record
5956 @item @emph{Description}:
5957 @code{IS_IOSTAT_EOR} tests whether an variable has the value of the I/O
5958 status ``end of record''. The function is equivalent to comparing the
5959 variable with the @code{IOSTAT_EOR} parameter of the intrinsic module
5960 @code{ISO_FORTRAN_ENV}.
5962 @item @emph{Standard}:
5968 @item @emph{Syntax}:
5969 @code{RESULT = IS_IOSTAT_EOR(I)}
5971 @item @emph{Arguments}:
5972 @multitable @columnfractions .15 .70
5973 @item @var{I} @tab Shall be of the type @code{INTEGER}.
5976 @item @emph{Return value}:
5977 Returns a @code{LOGICAL} of the default kind, which @code{.TRUE.} if
5978 @var{I} has the value which indicates an end of file condition for
5979 IOSTAT= specifiers, and is @code{.FALSE.} otherwise.
5981 @item @emph{Example}:
5985 INTEGER :: stat, i(50)
5986 OPEN(88, FILE='test.dat', FORM='UNFORMATTED')
5987 READ(88, IOSTAT=stat) i
5988 IF(IS_IOSTAT_EOR(stat)) STOP 'END OF RECORD'
5996 @section @code{ISATTY} --- Whether a unit is a terminal device.
5998 @cindex system, terminal
6001 @item @emph{Description}:
6002 Determine whether a unit is connected to a terminal device.
6004 @item @emph{Standard}:
6010 @item @emph{Syntax}:
6011 @code{RESULT = ISATTY(UNIT)}
6013 @item @emph{Arguments}:
6014 @multitable @columnfractions .15 .70
6015 @item @var{UNIT} @tab Shall be a scalar @code{INTEGER(*)}.
6018 @item @emph{Return value}:
6019 Returns @code{.TRUE.} if the @var{UNIT} is connected to a terminal
6020 device, @code{.FALSE.} otherwise.
6022 @item @emph{Example}:
6025 INTEGER(kind=1) :: unit
6027 write(*,*) isatty(unit=unit)
6031 @item @emph{See also}:
6038 @section @code{ISHFT} --- Shift bits
6043 @item @emph{Description}:
6044 @code{ISHFT} returns a value corresponding to @var{I} with all of the
6045 bits shifted @var{SHIFT} places. A value of @var{SHIFT} greater than
6046 zero corresponds to a left shift, a value of zero corresponds to no
6047 shift, and a value less than zero corresponds to a right shift. If the
6048 absolute value of @var{SHIFT} is greater than @code{BIT_SIZE(I)}, the
6049 value is undefined. Bits shifted out from the left end or right end are
6050 lost; zeros are shifted in from the opposite end.
6052 @item @emph{Standard}:
6058 @item @emph{Syntax}:
6059 @code{RESULT = ISHFT(I, SHIFT)}
6061 @item @emph{Arguments}:
6062 @multitable @columnfractions .15 .70
6063 @item @var{I} @tab The type shall be @code{INTEGER(*)}.
6064 @item @var{SHIFT} @tab The type shall be @code{INTEGER(*)}.
6067 @item @emph{Return value}:
6068 The return value is of type @code{INTEGER(*)} and of the same kind as
6071 @item @emph{See also}:
6078 @section @code{ISHFTC} --- Shift bits circularly
6080 @cindex bits, shift circular
6083 @item @emph{Description}:
6084 @code{ISHFTC} returns a value corresponding to @var{I} with the
6085 rightmost @var{SIZE} bits shifted circularly @var{SHIFT} places; that
6086 is, bits shifted out one end are shifted into the opposite end. A value
6087 of @var{SHIFT} greater than zero corresponds to a left shift, a value of
6088 zero corresponds to no shift, and a value less than zero corresponds to
6089 a right shift. The absolute value of @var{SHIFT} must be less than
6090 @var{SIZE}. If the @var{SIZE} argument is omitted, it is taken to be
6091 equivalent to @code{BIT_SIZE(I)}.
6093 @item @emph{Standard}:
6099 @item @emph{Syntax}:
6100 @code{RESULT = ISHFTC(I, SHIFT [, SIZE])}
6102 @item @emph{Arguments}:
6103 @multitable @columnfractions .15 .70
6104 @item @var{I} @tab The type shall be @code{INTEGER(*)}.
6105 @item @var{SHIFT} @tab The type shall be @code{INTEGER(*)}.
6106 @item @var{SIZE} @tab (Optional) The type shall be @code{INTEGER(*)};
6107 the value must be greater than zero and less than or equal to
6111 @item @emph{Return value}:
6112 The return value is of type @code{INTEGER(*)} and of the same kind as
6115 @item @emph{See also}:
6122 @section @code{ISNAN} --- Test for a NaN
6127 @item @emph{Description}:
6128 @code{ISNAN} tests whether a floating-point value is an IEEE
6130 @item @emph{Standard}:
6136 @item @emph{Syntax}:
6139 @item @emph{Arguments}:
6140 @multitable @columnfractions .15 .70
6141 @item @var{X} @tab Variable of the type @code{REAL}.
6145 @item @emph{Return value}:
6146 Returns a default-kind @code{LOGICAL}. The returned value is @code{TRUE}
6147 if @var{X} is a NaN and @code{FALSE} otherwise.
6149 @item @emph{Example}:
6156 if (isnan(x)) stop '"x" is a NaN'
6157 end program test_nan
6164 @section @code{ITIME} --- Get current local time subroutine (hour/minutes/seconds)
6166 @cindex time, current
6167 @cindex current time
6170 @item @emph{Description}:
6171 @code{IDATE(TARRAY)} Fills @var{TARRAY} with the numerical values at the
6172 current local time. The hour (in the range 1-24), minute (in the range 1-60),
6173 and seconds (in the range 1-60) appear in elements 1, 2, and 3 of @var{TARRAY},
6176 @item @emph{Standard}:
6182 @item @emph{Syntax}:
6183 @code{CALL ITIME(TARRAY)}
6185 @item @emph{Arguments}:
6186 @multitable @columnfractions .15 .70
6187 @item @var{TARRAY} @tab The type shall be @code{INTEGER, DIMENSION(3)}
6188 and the kind shall be the default integer kind.
6191 @item @emph{Return value}:
6195 @item @emph{Example}:
6198 integer, dimension(3) :: tarray
6203 end program test_itime
6210 @section @code{KILL} --- Send a signal to a process
6214 @item @emph{Description}:
6215 @item @emph{Standard}:
6216 Sends the signal specified by @var{SIGNAL} to the process @var{PID}.
6219 This intrinsic is provided in both subroutine and function forms; however,
6220 only one form can be used in any given program unit.
6223 Subroutine, function
6225 @item @emph{Syntax}:
6226 @code{CALL KILL(PID, SIGNAL [, STATUS])}
6228 @item @emph{Arguments}:
6229 @multitable @columnfractions .15 .70
6230 @item @var{PID} @tab Shall be a scalar @code{INTEGER}, with
6232 @item @var{SIGNAL} @tab Shall be a scalar @code{INTEGER}, with
6234 @item @var{STATUS} @tab (Optional) status flag of type @code{INTEGER(4)} or
6235 @code{INTEGER(8)}. Returns 0 on success, or a
6236 system-specific error code otherwise.
6239 @item @emph{See also}:
6240 @ref{ABORT}, @ref{EXIT}
6246 @section @code{KIND} --- Kind of an entity
6251 @item @emph{Description}:
6252 @code{KIND(X)} returns the kind value of the entity @var{X}.
6254 @item @emph{Standard}:
6260 @item @emph{Syntax}:
6263 @item @emph{Arguments}:
6264 @multitable @columnfractions .15 .70
6265 @item @var{X} @tab Shall be of type @code{LOGICAL}, @code{INTEGER},
6266 @code{REAL}, @code{COMPLEX} or @code{CHARACTER}.
6269 @item @emph{Return value}:
6270 The return value is a scalar of type @code{INTEGER} and of the default
6273 @item @emph{Example}:
6276 integer,parameter :: kc = kind(' ')
6277 integer,parameter :: kl = kind(.true.)
6279 print *, "The default character kind is ", kc
6280 print *, "The default logical kind is ", kl
6281 end program test_kind
6289 @section @code{LBOUND} --- Lower dimension bounds of an array
6291 @cindex array, lower bound
6294 @item @emph{Description}:
6295 Returns the lower bounds of an array, or a single lower bound
6296 along the @var{DIM} dimension.
6297 @item @emph{Standard}:
6303 @item @emph{Syntax}:
6304 @code{RESULT = LBOUND(ARRAY [, DIM [, KIND]])}
6306 @item @emph{Arguments}:
6307 @multitable @columnfractions .15 .70
6308 @item @var{ARRAY} @tab Shall be an array, of any type.
6309 @item @var{DIM} @tab (Optional) Shall be a scalar @code{INTEGER(*)}.
6310 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
6311 expression indicating the kind parameter of
6315 @item @emph{Return value}:
6316 The return value is of type @code{INTEGER} and of kind @var{KIND}. If
6317 @var{KIND} is absent, the return value is of default integer kind.
6318 If @var{DIM} is absent, the result is an array of the lower bounds of
6319 @var{ARRAY}. If @var{DIM} is present, the result is a scalar
6320 corresponding to the lower bound of the array along that dimension. If
6321 @var{ARRAY} is an expression rather than a whole array or array
6322 structure component, or if it has a zero extent along the relevant
6323 dimension, the lower bound is taken to be 1.
6325 @item @emph{See also}:
6332 @section @code{LEN} --- Length of a character entity
6334 @cindex string, length
6337 @item @emph{Description}:
6338 Returns the length of a character string. If @var{STRING} is an array,
6339 the length of an element of @var{STRING} is returned. Note that
6340 @var{STRING} need not be defined when this intrinsic is invoked, since
6341 only the length, not the content, of @var{STRING} is needed.
6343 @item @emph{Standard}:
6349 @item @emph{Syntax}:
6350 @code{L = LEN(STRING [, KIND])}
6352 @item @emph{Arguments}:
6353 @multitable @columnfractions .15 .70
6354 @item @var{STRING} @tab Shall be a scalar or array of type
6355 @code{CHARACTER(*)}, with @code{INTENT(IN)}
6356 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
6357 expression indicating the kind parameter of
6361 @item @emph{Return value}:
6362 The return value is of type @code{INTEGER} and of kind @var{KIND}. If
6363 @var{KIND} is absent, the return value is of default integer kind.
6365 @item @emph{See also}:
6366 @ref{LEN_TRIM}, @ref{ADJUSTL}, @ref{ADJUSTR}
6372 @section @code{LEN_TRIM} --- Length of a character entity without trailing blank characters
6374 @cindex string, length, without trailing whitespace
6377 @item @emph{Description}:
6378 Returns the length of a character string, ignoring any trailing blanks.
6380 @item @emph{Standard}:
6386 @item @emph{Syntax}:
6387 @code{RESULT = LEN_TRIM(STRING [, KIND])}
6389 @item @emph{Arguments}:
6390 @multitable @columnfractions .15 .70
6391 @item @var{STRING} @tab Shall be a scalar of type @code{CHARACTER(*)},
6392 with @code{INTENT(IN)}
6393 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
6394 expression indicating the kind parameter of
6398 @item @emph{Return value}:
6399 The return value is of type @code{INTEGER} and of kind @var{KIND}. If
6400 @var{KIND} is absent, the return value is of default integer kind.
6402 @item @emph{See also}:
6403 @ref{LEN}, @ref{ADJUSTL}, @ref{ADJUSTR}
6409 @section @code{LGAMMA} --- Logarithm of the Gamma function
6413 @cindex Gamma function, logarithm of
6416 @item @emph{Description}:
6417 @code{GAMMA(X)} computes the natural logrithm of the absolute value of the
6418 Gamma (@math{\Gamma}) function.
6420 @item @emph{Standard}:
6426 @item @emph{Syntax}:
6427 @code{X = LGAMMA(X)}
6429 @item @emph{Arguments}:
6430 @multitable @columnfractions .15 .70
6431 @item @var{X} @tab Shall be of type @code{REAL} and neither zero
6432 nor a negative integer.
6435 @item @emph{Return value}:
6436 The return value is of type @code{REAL} of the same kind as @var{X}.
6438 @item @emph{Example}:
6440 program test_log_gamma
6442 x = lgamma(x) ! returns 0.0
6443 end program test_log_gamma
6446 @item @emph{Specific names}:
6447 @multitable @columnfractions .20 .20 .20 .25
6448 @item Name @tab Argument @tab Return type @tab Standard
6449 @item @code{LGAMMA(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab GNU Extension
6450 @item @code{ALGAMA(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab GNU Extension
6451 @item @code{DLGAMA(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU Extension
6454 @item @emph{See also}:
6455 Gamma function: @ref{GAMMA}
6462 @section @code{LGE} --- Lexical greater than or equal
6464 @cindex lexical comparison of strings
6465 @cindex string, comparison
6468 @item @emph{Description}:
6469 Determines whether one string is lexically greater than or equal to
6470 another string, where the two strings are interpreted as containing
6471 ASCII character codes. If the String A and String B are not the same
6472 length, the shorter is compared as if spaces were appended to it to form
6473 a value that has the same length as the longer.
6475 In general, the lexical comparison intrinsics @code{LGE}, @code{LGT},
6476 @code{LLE}, and @code{LLT} differ from the corresponding intrinsic
6477 operators @code{.GE.}, @code{.GT.}, @code{.LE.}, and @code{.LT.}, in
6478 that the latter use the processor's character ordering (which is not
6479 ASCII on some targets), whereas the former always use the ASCII
6482 @item @emph{Standard}:
6488 @item @emph{Syntax}:
6489 @code{RESULT = LGE(STRING_A, STRING_B)}
6491 @item @emph{Arguments}:
6492 @multitable @columnfractions .15 .70
6493 @item @var{STRING_A} @tab Shall be of default @code{CHARACTER} type.
6494 @item @var{STRING_B} @tab Shall be of default @code{CHARACTER} type.
6497 @item @emph{Return value}:
6498 Returns @code{.TRUE.} if @code{STRING_A >= STRING_B}, and @code{.FALSE.}
6499 otherwise, based on the ASCII ordering.
6501 @item @emph{See also}:
6502 @ref{LGT}, @ref{LLE}, @ref{LLT}
6508 @section @code{LGT} --- Lexical greater than
6510 @cindex lexical comparison of strings
6511 @cindex string, comparison
6514 @item @emph{Description}:
6515 Determines whether one string is lexically greater than another string,
6516 where the two strings are interpreted as containing ASCII character
6517 codes. If the String A and String B are not the same length, the
6518 shorter is compared as if spaces were appended to it to form a value
6519 that has the same length as the longer.
6521 In general, the lexical comparison intrinsics @code{LGE}, @code{LGT},
6522 @code{LLE}, and @code{LLT} differ from the corresponding intrinsic
6523 operators @code{.GE.}, @code{.GT.}, @code{.LE.}, and @code{.LT.}, in
6524 that the latter use the processor's character ordering (which is not
6525 ASCII on some targets), whereas the former always use the ASCII
6528 @item @emph{Standard}:
6534 @item @emph{Syntax}:
6535 @code{RESULT = LGT(STRING_A, STRING_B)}
6537 @item @emph{Arguments}:
6538 @multitable @columnfractions .15 .70
6539 @item @var{STRING_A} @tab Shall be of default @code{CHARACTER} type.
6540 @item @var{STRING_B} @tab Shall be of default @code{CHARACTER} type.
6543 @item @emph{Return value}:
6544 Returns @code{.TRUE.} if @code{STRING_A > STRING_B}, and @code{.FALSE.}
6545 otherwise, based on the ASCII ordering.
6547 @item @emph{See also}:
6548 @ref{LGE}, @ref{LLE}, @ref{LLT}
6554 @section @code{LINK} --- Create a hard link
6556 @cindex file system, create link
6557 @cindex file system, hard link
6560 @item @emph{Description}:
6561 Makes a (hard) link from file @var{PATH1} to @var{PATH2}. A null
6562 character (@code{CHAR(0)}) can be used to mark the end of the names in
6563 @var{PATH1} and @var{PATH2}; otherwise, trailing blanks in the file
6564 names are ignored. If the @var{STATUS} argument is supplied, it
6565 contains 0 on success or a nonzero error code upon return; see
6568 This intrinsic is provided in both subroutine and function forms;
6569 however, only one form can be used in any given program unit.
6571 @item @emph{Standard}:
6575 Subroutine, function
6577 @item @emph{Syntax}:
6578 @multitable @columnfractions .80
6579 @item @code{CALL LINK(PATH1, PATH2 [, STATUS])}
6580 @item @code{STATUS = LINK(PATH1, PATH2)}
6583 @item @emph{Arguments}:
6584 @multitable @columnfractions .15 .70
6585 @item @var{PATH1} @tab Shall be of default @code{CHARACTER} type.
6586 @item @var{PATH2} @tab Shall be of default @code{CHARACTER} type.
6587 @item @var{STATUS} @tab (Optional) Shall be of default @code{INTEGER} type.
6590 @item @emph{See also}:
6591 @ref{SYMLNK}, @ref{UNLINK}
6597 @section @code{LLE} --- Lexical less than or equal
6599 @cindex lexical comparison of strings
6600 @cindex string, comparison
6603 @item @emph{Description}:
6604 Determines whether one string is lexically less than or equal to another
6605 string, where the two strings are interpreted as containing ASCII
6606 character codes. If the String A and String B are not the same length,
6607 the shorter is compared as if spaces were appended to it to form a value
6608 that has the same length as the longer.
6610 In general, the lexical comparison intrinsics @code{LGE}, @code{LGT},
6611 @code{LLE}, and @code{LLT} differ from the corresponding intrinsic
6612 operators @code{.GE.}, @code{.GT.}, @code{.LE.}, and @code{.LT.}, in
6613 that the latter use the processor's character ordering (which is not
6614 ASCII on some targets), whereas the former always use the ASCII
6617 @item @emph{Standard}:
6623 @item @emph{Syntax}:
6624 @code{RESULT = LLE(STRING_A, STRING_B)}
6626 @item @emph{Arguments}:
6627 @multitable @columnfractions .15 .70
6628 @item @var{STRING_A} @tab Shall be of default @code{CHARACTER} type.
6629 @item @var{STRING_B} @tab Shall be of default @code{CHARACTER} type.
6632 @item @emph{Return value}:
6633 Returns @code{.TRUE.} if @code{STRING_A <= STRING_B}, and @code{.FALSE.}
6634 otherwise, based on the ASCII ordering.
6636 @item @emph{See also}:
6637 @ref{LGE}, @ref{LGT}, @ref{LLT}
6643 @section @code{LLT} --- Lexical less than
6645 @cindex lexical comparison of strings
6646 @cindex string, comparison
6649 @item @emph{Description}:
6650 Determines whether one string is lexically less than another string,
6651 where the two strings are interpreted as containing ASCII character
6652 codes. If the String A and String B are not the same length, the
6653 shorter is compared as if spaces were appended to it to form a value
6654 that has the same length as the longer.
6656 In general, the lexical comparison intrinsics @code{LGE}, @code{LGT},
6657 @code{LLE}, and @code{LLT} differ from the corresponding intrinsic
6658 operators @code{.GE.}, @code{.GT.}, @code{.LE.}, and @code{.LT.}, in
6659 that the latter use the processor's character ordering (which is not
6660 ASCII on some targets), whereas the former always use the ASCII
6663 @item @emph{Standard}:
6669 @item @emph{Syntax}:
6670 @code{RESULT = LLT(STRING_A, STRING_B)}
6672 @item @emph{Arguments}:
6673 @multitable @columnfractions .15 .70
6674 @item @var{STRING_A} @tab Shall be of default @code{CHARACTER} type.
6675 @item @var{STRING_B} @tab Shall be of default @code{CHARACTER} type.
6678 @item @emph{Return value}:
6679 Returns @code{.TRUE.} if @code{STRING_A < STRING_B}, and @code{.FALSE.}
6680 otherwise, based on the ASCII ordering.
6682 @item @emph{See also}:
6683 @ref{LGE}, @ref{LGT}, @ref{LLE}
6689 @section @code{LNBLNK} --- Index of the last non-blank character in a string
6691 @cindex string, find non-blank character
6694 @item @emph{Description}:
6695 Returns the length of a character string, ignoring any trailing blanks.
6696 This is identical to the standard @code{LEN_TRIM} intrinsic, and is only
6697 included for backwards compatibility.
6699 @item @emph{Standard}:
6705 @item @emph{Syntax}:
6706 @code{RESULT = LNBLNK(STRING)}
6708 @item @emph{Arguments}:
6709 @multitable @columnfractions .15 .70
6710 @item @var{STRING} @tab Shall be a scalar of type @code{CHARACTER(*)},
6711 with @code{INTENT(IN)}
6714 @item @emph{Return value}:
6715 The return value is of @code{INTEGER(kind=4)} type.
6717 @item @emph{See also}:
6718 @ref{INDEX intrinsic}, @ref{LEN_TRIM}
6724 @section @code{LOC} --- Returns the address of a variable
6726 @cindex location of a variable in memory
6729 @item @emph{Description}:
6730 @code{LOC(X)} returns the address of @var{X} as an integer.
6732 @item @emph{Standard}:
6738 @item @emph{Syntax}:
6739 @code{RESULT = LOC(X)}
6741 @item @emph{Arguments}:
6742 @multitable @columnfractions .15 .70
6743 @item @var{X} @tab Variable of any type.
6746 @item @emph{Return value}:
6747 The return value is of type @code{INTEGER}, with a @code{KIND}
6748 corresponding to the size (in bytes) of a memory address on the target
6751 @item @emph{Example}:
6758 end program test_loc
6765 @section @code{LOG} --- Logarithm function
6772 @cindex exponential function, inverse
6773 @cindex logarithmic function
6776 @item @emph{Description}:
6777 @code{LOG(X)} computes the logarithm of @var{X}.
6779 @item @emph{Standard}:
6785 @item @emph{Syntax}:
6786 @code{RESULT = LOG(X)}
6788 @item @emph{Arguments}:
6789 @multitable @columnfractions .15 .70
6790 @item @var{X} @tab The type shall be @code{REAL(*)} or
6794 @item @emph{Return value}:
6795 The return value is of type @code{REAL(*)} or @code{COMPLEX(*)}.
6796 The kind type parameter is the same as @var{X}.
6798 @item @emph{Example}:
6801 real(8) :: x = 1.0_8
6802 complex :: z = (1.0, 2.0)
6805 end program test_log
6808 @item @emph{Specific names}:
6809 @multitable @columnfractions .20 .20 .20 .25
6810 @item Name @tab Argument @tab Return type @tab Standard
6811 @item @code{ALOG(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab f95, gnu
6812 @item @code{DLOG(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab f95, gnu
6813 @item @code{CLOG(X)} @tab @code{COMPLEX(4) X} @tab @code{COMPLEX(4)} @tab f95, gnu
6814 @item @code{ZLOG(X)} @tab @code{COMPLEX(8) X} @tab @code{COMPLEX(8)} @tab f95, gnu
6815 @item @code{CDLOG(X)} @tab @code{COMPLEX(8) X} @tab @code{COMPLEX(8)} @tab f95, gnu
6822 @section @code{LOG10} --- Base 10 logarithm function
6826 @cindex exponential function, inverse
6827 @cindex logarithmic function
6830 @item @emph{Description}:
6831 @code{LOG10(X)} computes the base 10 logarithm of @var{X}.
6833 @item @emph{Standard}:
6839 @item @emph{Syntax}:
6840 @code{RESULT = LOG10(X)}
6842 @item @emph{Arguments}:
6843 @multitable @columnfractions .15 .70
6844 @item @var{X} @tab The type shall be @code{REAL(*)}.
6847 @item @emph{Return value}:
6848 The return value is of type @code{REAL(*)} or @code{COMPLEX(*)}.
6849 The kind type parameter is the same as @var{X}.
6851 @item @emph{Example}:
6854 real(8) :: x = 10.0_8
6856 end program test_log10
6859 @item @emph{Specific names}:
6860 @multitable @columnfractions .20 .20 .20 .25
6861 @item Name @tab Argument @tab Return type @tab Standard
6862 @item @code{ALOG10(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab F95 and later
6863 @item @code{DLOG10(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab F95 and later
6870 @section @code{LOGICAL} --- Convert to logical type
6872 @cindex conversion, to logical
6875 @item @emph{Description}:
6876 Converts one kind of @code{LOGICAL} variable to another.
6878 @item @emph{Standard}:
6884 @item @emph{Syntax}:
6885 @code{RESULT = LOGICAL(L [, KIND])}
6887 @item @emph{Arguments}:
6888 @multitable @columnfractions .15 .70
6889 @item @var{L} @tab The type shall be @code{LOGICAL(*)}.
6890 @item @var{KIND} @tab (Optional) An @code{INTEGER(*)} initialization
6891 expression indicating the kind parameter of
6895 @item @emph{Return value}:
6896 The return value is a @code{LOGICAL} value equal to @var{L}, with a
6897 kind corresponding to @var{KIND}, or of the default logical kind if
6898 @var{KIND} is not given.
6900 @item @emph{See also}:
6901 @ref{INT}, @ref{REAL}, @ref{CMPLX}
6907 @section @code{LONG} --- Convert to integer type
6909 @cindex conversion, to integer
6912 @item @emph{Description}:
6913 Convert to a @code{KIND=4} integer type, which is the same size as a C
6914 @code{long} integer. This is equivalent to the standard @code{INT}
6915 intrinsic with an optional argument of @code{KIND=4}, and is only
6916 included for backwards compatibility.
6918 @item @emph{Standard}:
6924 @item @emph{Syntax}:
6925 @code{RESULT = LONG(A)}
6927 @item @emph{Arguments}:
6928 @multitable @columnfractions .15 .70
6929 @item @var{A} @tab Shall be of type @code{INTEGER(*)},
6930 @code{REAL(*)}, or @code{COMPLEX(*)}.
6933 @item @emph{Return value}:
6934 The return value is a @code{INTEGER(4)} variable.
6936 @item @emph{See also}:
6937 @ref{INT}, @ref{INT2}, @ref{INT8}
6943 @section @code{LSHIFT} --- Left shift bits
6945 @cindex bits, shift left
6948 @item @emph{Description}:
6949 @code{LSHIFT} returns a value corresponding to @var{I} with all of the
6950 bits shifted left by @var{SHIFT} places. If the absolute value of
6951 @var{SHIFT} is greater than @code{BIT_SIZE(I)}, the value is undefined.
6952 Bits shifted out from the left end are lost; zeros are shifted in from
6955 This function has been superseded by the @code{ISHFT} intrinsic, which
6956 is standard in Fortran 95 and later.
6958 @item @emph{Standard}:
6964 @item @emph{Syntax}:
6965 @code{RESULT = LSHIFT(I, SHIFT)}
6967 @item @emph{Arguments}:
6968 @multitable @columnfractions .15 .70
6969 @item @var{I} @tab The type shall be @code{INTEGER(*)}.
6970 @item @var{SHIFT} @tab The type shall be @code{INTEGER(*)}.
6973 @item @emph{Return value}:
6974 The return value is of type @code{INTEGER(*)} and of the same kind as
6977 @item @emph{See also}:
6978 @ref{ISHFT}, @ref{ISHFTC}, @ref{RSHIFT}
6985 @section @code{LSTAT} --- Get file status
6987 @cindex file system, file status
6990 @item @emph{Description}:
6991 @code{LSTAT} is identical to @ref{STAT}, except that if path is a symbolic link,
6992 then the link itself is statted, not the file that it refers to.
6994 The elements in @code{BUFF} are the same as described by @ref{STAT}.
6996 This intrinsic is provided in both subroutine and function forms; however,
6997 only one form can be used in any given program unit.
6999 @item @emph{Standard}:
7003 Subroutine, function
7005 @item @emph{Syntax}:
7006 @code{CALL LSTAT(FILE, BUFF [, STATUS])}
7008 @item @emph{Arguments}:
7009 @multitable @columnfractions .15 .70
7010 @item @var{FILE} @tab The type shall be @code{CHARACTER(*)}, a valid path within the file system.
7011 @item @var{BUFF} @tab The type shall be @code{INTEGER(4), DIMENSION(13)}.
7012 @item @var{STATUS} @tab (Optional) status flag of type @code{INTEGER(4)}. Returns 0
7013 on success and a system specific error code otherwise.
7016 @item @emph{Example}:
7017 See @ref{STAT} for an example.
7019 @item @emph{See also}:
7020 To stat an open file: @ref{FSTAT}, to stat a file: @ref{STAT}
7026 @section @code{LTIME} --- Convert time to local time info
7028 @cindex time, conversion to local time info
7031 @item @emph{Description}:
7032 Given a system time value @var{STIME} (as provided by the @code{TIME8()}
7033 intrinsic), fills @var{TARRAY} with values extracted from it appropriate
7034 to the local time zone using @code{localtime(3)}.
7036 @item @emph{Standard}:
7042 @item @emph{Syntax}:
7043 @code{CALL LTIME(STIME, TARRAY)}
7045 @item @emph{Arguments}:
7046 @multitable @columnfractions .15 .70
7047 @item @var{STIME} @tab An @code{INTEGER(*)} scalar expression
7048 corresponding to a system time, with
7050 @item @var{TARRAY} @tab A default @code{INTEGER} array with 9 elements,
7051 with @code{INTENT(OUT)}.
7054 @item @emph{Return value}:
7055 The elements of @var{TARRAY} are assigned as follows:
7057 @item Seconds after the minute, range 0--59 or 0--61 to allow for leap
7059 @item Minutes after the hour, range 0--59
7060 @item Hours past midnight, range 0--23
7061 @item Day of month, range 0--31
7062 @item Number of months since January, range 0--12
7063 @item Years since 1900
7064 @item Number of days since Sunday, range 0--6
7065 @item Days since January 1
7066 @item Daylight savings indicator: positive if daylight savings is in
7067 effect, zero if not, and negative if the information is not
7071 @item @emph{See also}:
7072 @ref{CTIME}, @ref{GMTIME}, @ref{TIME}, @ref{TIME8}
7079 @section @code{MALLOC} --- Allocate dynamic memory
7081 @cindex pointer, cray
7084 @item @emph{Description}:
7085 @code{MALLOC(SIZE)} allocates @var{SIZE} bytes of dynamic memory and
7086 returns the address of the allocated memory. The @code{MALLOC} intrinsic
7087 is an extension intended to be used with Cray pointers, and is provided
7088 in GNU Fortran to allow the user to compile legacy code. For new code
7089 using Fortran 95 pointers, the memory allocation intrinsic is
7092 @item @emph{Standard}:
7098 @item @emph{Syntax}:
7099 @code{PTR = MALLOC(SIZE)}
7101 @item @emph{Arguments}:
7102 @multitable @columnfractions .15 .70
7103 @item @var{SIZE} @tab The type shall be @code{INTEGER(*)}.
7106 @item @emph{Return value}:
7107 The return value is of type @code{INTEGER(K)}, with @var{K} such that
7108 variables of type @code{INTEGER(K)} have the same size as
7109 C pointers (@code{sizeof(void *)}).
7111 @item @emph{Example}:
7112 The following example demonstrates the use of @code{MALLOC} and
7113 @code{FREE} with Cray pointers. This example is intended to run on
7114 32-bit systems, where the default integer kind is suitable to store
7115 pointers; on 64-bit systems, ptr_x would need to be declared as
7116 @code{integer(kind=8)}.
7125 ptr_x = malloc(20*8)
7127 x(i) = sqrt(1.0d0 / i)
7135 end program test_malloc
7138 @item @emph{See also}:
7145 @section @code{MATMUL} --- matrix multiplication
7147 @cindex matrix multiplication
7148 @cindex product, matrix
7151 @item @emph{Description}:
7152 Performs a matrix multiplication on numeric or logical arguments.
7154 @item @emph{Standard}:
7158 Transformational function
7160 @item @emph{Syntax}:
7161 @code{RESULT = MATMUL(MATRIX_A, MATRIX_B)}
7163 @item @emph{Arguments}:
7164 @multitable @columnfractions .15 .70
7165 @item @var{MATRIX_A} @tab An array of @code{INTEGER(*)},
7166 @code{REAL(*)}, @code{COMPLEX(*)}, or
7167 @code{LOGICAL(*)} type, with a rank of
7169 @item @var{MATRIX_B} @tab An array of @code{INTEGER(*)},
7170 @code{REAL(*)}, or @code{COMPLEX(*)} type if
7171 @var{MATRIX_A} is of a numeric type;
7172 otherwise, an array of @code{LOGICAL(*)}
7173 type. The rank shall be one or two, and the
7174 first (or only) dimension of @var{MATRIX_B}
7175 shall be equal to the last (or only)
7176 dimension of @var{MATRIX_A}.
7179 @item @emph{Return value}:
7180 The matrix product of @var{MATRIX_A} and @var{MATRIX_B}. The type and
7181 kind of the result follow the usual type and kind promotion rules, as
7182 for the @code{*} or @code{.AND.} operators.
7184 @item @emph{See also}:
7190 @section @code{MAX} --- Maximum value of an argument list
7197 @cindex maximum value
7200 @item @emph{Description}:
7201 Returns the argument with the largest (most positive) value.
7203 @item @emph{Standard}:
7209 @item @emph{Syntax}:
7210 @code{RESULT = MAX(A1, A2 [, A3 [, ...]])}
7212 @item @emph{Arguments}:
7213 @multitable @columnfractions .15 .70
7214 @item @var{A1} @tab The type shall be @code{INTEGER(*)} or
7216 @item @var{A2}, @var{A3}, ... @tab An expression of the same type and kind
7217 as @var{A1}. (As a GNU extension,
7218 arguments of different kinds are
7222 @item @emph{Return value}:
7223 The return value corresponds to the maximum value among the arguments,
7224 and has the same type and kind as the first argument.
7226 @item @emph{Specific names}:
7227 @multitable @columnfractions .20 .20 .20 .25
7228 @item Name @tab Argument @tab Return type @tab Standard
7229 @item @code{MAX0(I)} @tab @code{INTEGER(4) I} @tab @code{INTEGER(4)} @tab F77 and later
7230 @item @code{AMAX0(I)} @tab @code{INTEGER(4) I} @tab @code{REAL(MAX(X))} @tab F77 and later
7231 @item @code{MAX1(X)} @tab @code{REAL(*) X} @tab @code{INT(MAX(X))} @tab F77 and later
7232 @item @code{AMAX1(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab F77 and later
7233 @item @code{DMAX1(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab F77 and later
7236 @item @emph{See also}:
7237 @ref{MAXLOC} @ref{MAXVAL}, @ref{MIN}
7244 @section @code{MAXEXPONENT} --- Maximum exponent of a real kind
7245 @fnindex MAXEXPONENT
7246 @cindex model representation, maximum exponent
7249 @item @emph{Description}:
7250 @code{MAXEXPONENT(X)} returns the maximum exponent in the model of the
7253 @item @emph{Standard}:
7259 @item @emph{Syntax}:
7260 @code{RESULT = MAXEXPONENT(X)}
7262 @item @emph{Arguments}:
7263 @multitable @columnfractions .15 .70
7264 @item @var{X} @tab Shall be of type @code{REAL}.
7267 @item @emph{Return value}:
7268 The return value is of type @code{INTEGER} and of the default integer
7271 @item @emph{Example}:
7277 print *, minexponent(x), maxexponent(x)
7278 print *, minexponent(y), maxexponent(y)
7279 end program exponents
7286 @section @code{MAXLOC} --- Location of the maximum value within an array
7288 @cindex array, location of maximum element
7291 @item @emph{Description}:
7292 Determines the location of the element in the array with the maximum
7293 value, or, if the @var{DIM} argument is supplied, determines the
7294 locations of the maximum element along each row of the array in the
7295 @var{DIM} direction. If @var{MASK} is present, only the elements for
7296 which @var{MASK} is @code{.TRUE.} are considered. If more than one
7297 element in the array has the maximum value, the location returned is
7298 that of the first such element in array element order. If the array has
7299 zero size, or all of the elements of @var{MASK} are @code{.FALSE.}, then
7300 the result is an array of zeroes. Similarly, if @var{DIM} is supplied
7301 and all of the elements of @var{MASK} along a given row are zero, the
7302 result value for that row is zero.
7304 @item @emph{Standard}:
7308 Transformational function
7310 @item @emph{Syntax}:
7311 @multitable @columnfractions .80
7312 @item @code{RESULT = MAXLOC(ARRAY, DIM [, MASK])}
7313 @item @code{RESULT = MAXLOC(ARRAY [, MASK])}
7316 @item @emph{Arguments}:
7317 @multitable @columnfractions .15 .70
7318 @item @var{ARRAY} @tab Shall be an array of type @code{INTEGER(*)},
7319 @code{REAL(*)}, or @code{CHARACTER(*)}.
7320 @item @var{DIM} @tab (Optional) Shall be a scalar of type
7321 @code{INTEGER(*)}, with a value between one
7322 and the rank of @var{ARRAY}, inclusive. It
7323 may not be an optional dummy argument.
7324 @item @var{MASK} @tab Shall be an array of type @code{LOGICAL(*)},
7325 and conformable with @var{ARRAY}.
7328 @item @emph{Return value}:
7329 If @var{DIM} is absent, the result is a rank-one array with a length
7330 equal to the rank of @var{ARRAY}. If @var{DIM} is present, the result
7331 is an array with a rank one less than the rank of @var{ARRAY}, and a
7332 size corresponding to the size of @var{ARRAY} with the @var{DIM}
7333 dimension removed. If @var{DIM} is present and @var{ARRAY} has a rank
7334 of one, the result is a scalar. In all cases, the result is of default
7335 @code{INTEGER} type.
7337 @item @emph{See also}:
7338 @ref{MAX}, @ref{MAXVAL}
7345 @section @code{MAXVAL} --- Maximum value of an array
7347 @cindex array, maximum value
7348 @cindex maximum value
7351 @item @emph{Description}:
7352 Determines the maximum value of the elements in an array value, or, if
7353 the @var{DIM} argument is supplied, determines the maximum value along
7354 each row of the array in the @var{DIM} direction. If @var{MASK} is
7355 present, only the elements for which @var{MASK} is @code{.TRUE.} are
7356 considered. If the array has zero size, or all of the elements of
7357 @var{MASK} are @code{.FALSE.}, then the result is the most negative
7358 number of the type and kind of @var{ARRAY} if @var{ARRAY} is numeric, or
7359 a string of nulls if @var{ARRAY} is of character type.
7361 @item @emph{Standard}:
7365 Transformational function
7367 @item @emph{Syntax}:
7368 @multitable @columnfractions .80
7369 @item @code{RESULT = MAXVAL(ARRAY, DIM [, MASK])}
7370 @item @code{RESULT = MAXVAL(ARRAY [, MASK])}
7373 @item @emph{Arguments}:
7374 @multitable @columnfractions .15 .70
7375 @item @var{ARRAY} @tab Shall be an array of type @code{INTEGER(*)},
7376 @code{REAL(*)}, or @code{CHARACTER(*)}.
7377 @item @var{DIM} @tab (Optional) Shall be a scalar of type
7378 @code{INTEGER(*)}, with a value between one
7379 and the rank of @var{ARRAY}, inclusive. It
7380 may not be an optional dummy argument.
7381 @item @var{MASK} @tab Shall be an array of type @code{LOGICAL(*)},
7382 and conformable with @var{ARRAY}.
7385 @item @emph{Return value}:
7386 If @var{DIM} is absent, or if @var{ARRAY} has a rank of one, the result
7387 is a scalar. If @var{DIM} is present, the result is an array with a
7388 rank one less than the rank of @var{ARRAY}, and a size corresponding to
7389 the size of @var{ARRAY} with the @var{DIM} dimension removed. In all
7390 cases, the result is of the same type and kind as @var{ARRAY}.
7392 @item @emph{See also}:
7393 @ref{MAX}, @ref{MAXLOC}
7399 @section @code{MCLOCK} --- Time function
7401 @cindex time, clock ticks
7405 @item @emph{Description}:
7406 Returns the number of clock ticks since the start of the process, based
7407 on the UNIX function @code{clock(3)}.
7409 This intrinsic is not fully portable, such as to systems with 32-bit
7410 @code{INTEGER} types but supporting times wider than 32 bits. Therefore,
7411 the values returned by this intrinsic might be, or become, negative, or
7412 numerically less than previous values, during a single run of the
7415 @item @emph{Standard}:
7421 @item @emph{Syntax}:
7422 @code{RESULT = MCLOCK()}
7424 @item @emph{Return value}:
7425 The return value is a scalar of type @code{INTEGER(4)}, equal to the
7426 number of clock ticks since the start of the process, or @code{-1} if
7427 the system does not support @code{clock(3)}.
7429 @item @emph{See also}:
7430 @ref{CTIME}, @ref{GMTIME}, @ref{LTIME}, @ref{MCLOCK}, @ref{TIME}
7437 @section @code{MCLOCK8} --- Time function (64-bit)
7439 @cindex time, clock ticks
7443 @item @emph{Description}:
7444 Returns the number of clock ticks since the start of the process, based
7445 on the UNIX function @code{clock(3)}.
7447 @emph{Warning:} this intrinsic does not increase the range of the timing
7448 values over that returned by @code{clock(3)}. On a system with a 32-bit
7449 @code{clock(3)}, @code{MCLOCK8()} will return a 32-bit value, even though
7450 it is converted to a 64-bit @code{INTEGER(8)} value. That means
7451 overflows of the 32-bit value can still occur. Therefore, the values
7452 returned by this intrinsic might be or become negative or numerically
7453 less than previous values during a single run of the compiled program.
7455 @item @emph{Standard}:
7461 @item @emph{Syntax}:
7462 @code{RESULT = MCLOCK8()}
7464 @item @emph{Return value}:
7465 The return value is a scalar of type @code{INTEGER(8)}, equal to the
7466 number of clock ticks since the start of the process, or @code{-1} if
7467 the system does not support @code{clock(3)}.
7469 @item @emph{See also}:
7470 @ref{CTIME}, @ref{GMTIME}, @ref{LTIME}, @ref{MCLOCK}, @ref{TIME8}
7477 @section @code{MERGE} --- Merge variables
7479 @cindex array, merge arrays
7480 @cindex array, combine arrays
7483 @item @emph{Description}:
7484 Select values from two arrays according to a logical mask. The result
7485 is equal to @var{TSOURCE} if @var{MASK} is @code{.TRUE.}, or equal to
7486 @var{FSOURCE} if it is @code{.FALSE.}.
7488 @item @emph{Standard}:
7494 @item @emph{Syntax}:
7495 @code{RESULT = MERGE(TSOURCE, FSOURCE, MASK)}
7497 @item @emph{Arguments}:
7498 @multitable @columnfractions .15 .70
7499 @item @var{TSOURCE} @tab May be of any type.
7500 @item @var{FSOURCE} @tab Shall be of the same type and type parameters
7502 @item @var{MASK} @tab Shall be of type @code{LOGICAL(*)}.
7505 @item @emph{Return value}:
7506 The result is of the same type and type parameters as @var{TSOURCE}.
7513 @section @code{MIN} --- Minimum value of an argument list
7520 @cindex minimum value
7523 @item @emph{Description}:
7524 Returns the argument with the smallest (most negative) value.
7526 @item @emph{Standard}:
7532 @item @emph{Syntax}:
7533 @code{RESULT = MIN(A1, A2 [, A3, ...])}
7535 @item @emph{Arguments}:
7536 @multitable @columnfractions .15 .70
7537 @item @var{A1} @tab The type shall be @code{INTEGER(*)} or
7539 @item @var{A2}, @var{A3}, ... @tab An expression of the same type and kind
7540 as @var{A1}. (As a GNU extension,
7541 arguments of different kinds are
7545 @item @emph{Return value}:
7546 The return value corresponds to the maximum value among the arguments,
7547 and has the same type and kind as the first argument.
7549 @item @emph{Specific names}:
7550 @multitable @columnfractions .20 .20 .20 .25
7551 @item Name @tab Argument @tab Return type @tab Standard
7552 @item @code{MIN0(I)} @tab @code{INTEGER(4) I} @tab @code{INTEGER(4)} @tab F77 and later
7553 @item @code{AMIN0(I)} @tab @code{INTEGER(4) I} @tab @code{REAL(MIN(X))} @tab F77 and later
7554 @item @code{MIN1(X)} @tab @code{REAL(*) X} @tab @code{INT(MIN(X))} @tab F77 and later
7555 @item @code{AMIN1(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab F77 and later
7556 @item @code{DMIN1(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab F77 and later
7559 @item @emph{See also}:
7560 @ref{MAX}, @ref{MINLOC}, @ref{MINVAL}
7566 @section @code{MINEXPONENT} --- Minimum exponent of a real kind
7567 @fnindex MINEXPONENT
7568 @cindex model representation, minimum exponent
7571 @item @emph{Description}:
7572 @code{MINEXPONENT(X)} returns the minimum exponent in the model of the
7575 @item @emph{Standard}:
7581 @item @emph{Syntax}:
7582 @code{RESULT = MINEXPONENT(X)}
7584 @item @emph{Arguments}:
7585 @multitable @columnfractions .15 .70
7586 @item @var{X} @tab Shall be of type @code{REAL}.
7589 @item @emph{Return value}:
7590 The return value is of type @code{INTEGER} and of the default integer
7593 @item @emph{Example}:
7594 See @code{MAXEXPONENT} for an example.
7600 @section @code{MINLOC} --- Location of the minimum value within an array
7602 @cindex array, location of minimum element
7605 @item @emph{Description}:
7606 Determines the location of the element in the array with the minimum
7607 value, or, if the @var{DIM} argument is supplied, determines the
7608 locations of the minimum element along each row of the array in the
7609 @var{DIM} direction. If @var{MASK} is present, only the elements for
7610 which @var{MASK} is @code{.TRUE.} are considered. If more than one
7611 element in the array has the minimum value, the location returned is
7612 that of the first such element in array element order. If the array has
7613 zero size, or all of the elements of @var{MASK} are @code{.FALSE.}, then
7614 the result is an array of zeroes. Similarly, if @var{DIM} is supplied
7615 and all of the elements of @var{MASK} along a given row are zero, the
7616 result value for that row is zero.
7618 @item @emph{Standard}:
7622 Transformational function
7624 @item @emph{Syntax}:
7625 @multitable @columnfractions .80
7626 @item @code{RESULT = MINLOC(ARRAY, DIM [, MASK])}
7627 @item @code{RESULT = MINLOC(ARRAY [, MASK])}
7630 @item @emph{Arguments}:
7631 @multitable @columnfractions .15 .70
7632 @item @var{ARRAY} @tab Shall be an array of type @code{INTEGER(*)},
7633 @code{REAL(*)}, or @code{CHARACTER(*)}.
7634 @item @var{DIM} @tab (Optional) Shall be a scalar of type
7635 @code{INTEGER(*)}, with a value between one
7636 and the rank of @var{ARRAY}, inclusive. It
7637 may not be an optional dummy argument.
7638 @item @var{MASK} @tab Shall be an array of type @code{LOGICAL(*)},
7639 and conformable with @var{ARRAY}.
7642 @item @emph{Return value}:
7643 If @var{DIM} is absent, the result is a rank-one array with a length
7644 equal to the rank of @var{ARRAY}. If @var{DIM} is present, the result
7645 is an array with a rank one less than the rank of @var{ARRAY}, and a
7646 size corresponding to the size of @var{ARRAY} with the @var{DIM}
7647 dimension removed. If @var{DIM} is present and @var{ARRAY} has a rank
7648 of one, the result is a scalar. In all cases, the result is of default
7649 @code{INTEGER} type.
7651 @item @emph{See also}:
7652 @ref{MIN}, @ref{MINVAL}
7659 @section @code{MINVAL} --- Minimum value of an array
7661 @cindex array, minimum value
7662 @cindex minimum value
7665 @item @emph{Description}:
7666 Determines the minimum value of the elements in an array value, or, if
7667 the @var{DIM} argument is supplied, determines the minimum value along
7668 each row of the array in the @var{DIM} direction. If @var{MASK} is
7669 present, only the elements for which @var{MASK} is @code{.TRUE.} are
7670 considered. If the array has zero size, or all of the elements of
7671 @var{MASK} are @code{.FALSE.}, then the result is @code{HUGE(ARRAY)} if
7672 @var{ARRAY} is numeric, or a string of @code{CHAR(255)} characters if
7673 @var{ARRAY} is of character type.
7675 @item @emph{Standard}:
7679 Transformational function
7681 @item @emph{Syntax}:
7682 @multitable @columnfractions .80
7683 @item @code{RESULT = MINVAL(ARRAY, DIM [, MASK])}
7684 @item @code{RESULT = MINVAL(ARRAY [, MASK])}
7687 @item @emph{Arguments}:
7688 @multitable @columnfractions .15 .70
7689 @item @var{ARRAY} @tab Shall be an array of type @code{INTEGER(*)},
7690 @code{REAL(*)}, or @code{CHARACTER(*)}.
7691 @item @var{DIM} @tab (Optional) Shall be a scalar of type
7692 @code{INTEGER(*)}, with a value between one
7693 and the rank of @var{ARRAY}, inclusive. It
7694 may not be an optional dummy argument.
7695 @item @var{MASK} @tab Shall be an array of type @code{LOGICAL(*)},
7696 and conformable with @var{ARRAY}.
7699 @item @emph{Return value}:
7700 If @var{DIM} is absent, or if @var{ARRAY} has a rank of one, the result
7701 is a scalar. If @var{DIM} is present, the result is an array with a
7702 rank one less than the rank of @var{ARRAY}, and a size corresponding to
7703 the size of @var{ARRAY} with the @var{DIM} dimension removed. In all
7704 cases, the result is of the same type and kind as @var{ARRAY}.
7706 @item @emph{See also}:
7707 @ref{MIN}, @ref{MINLOC}
7714 @section @code{MOD} --- Remainder function
7719 @cindex division, remainder
7722 @item @emph{Description}:
7723 @code{MOD(A,P)} computes the remainder of the division of A by P. It is
7724 calculated as @code{A - (INT(A/P) * P)}.
7726 @item @emph{Standard}:
7732 @item @emph{Syntax}:
7733 @code{RESULT = MOD(A, P)}
7735 @item @emph{Arguments}:
7736 @multitable @columnfractions .15 .70
7737 @item @var{A} @tab Shall be a scalar of type @code{INTEGER} or @code{REAL}
7738 @item @var{P} @tab Shall be a scalar of the same type as @var{A} and not
7742 @item @emph{Return value}:
7743 The kind of the return value is the result of cross-promoting
7744 the kinds of the arguments.
7746 @item @emph{Example}:
7750 print *, mod(17.5,5.5)
7751 print *, mod(17.5d0,5.5)
7752 print *, mod(17.5,5.5d0)
7755 print *, mod(-17.5,5.5)
7756 print *, mod(-17.5d0,5.5)
7757 print *, mod(-17.5,5.5d0)
7760 print *, mod(17.5,-5.5)
7761 print *, mod(17.5d0,-5.5)
7762 print *, mod(17.5,-5.5d0)
7763 end program test_mod
7766 @item @emph{Specific names}:
7767 @multitable @columnfractions .20 .20 .20 .25
7768 @item Name @tab Arguments @tab Return type @tab Standard
7769 @item @code{AMOD(A,P)} @tab @code{REAL(4)} @tab @code{REAL(4)} @tab F95 and later
7770 @item @code{DMOD(A,P)} @tab @code{REAL(8)} @tab @code{REAL(8)} @tab F95 and later
7777 @section @code{MODULO} --- Modulo function
7780 @cindex division, modulo
7783 @item @emph{Description}:
7784 @code{MODULO(A,P)} computes the @var{A} modulo @var{P}.
7786 @item @emph{Standard}:
7792 @item @emph{Syntax}:
7793 @code{RESULT = MODULO(A, P)}
7795 @item @emph{Arguments}:
7796 @multitable @columnfractions .15 .70
7797 @item @var{A} @tab Shall be a scalar of type @code{INTEGER} or @code{REAL}
7798 @item @var{P} @tab Shall be a scalar of the same type and kind as @var{A}
7801 @item @emph{Return value}:
7802 The type and kind of the result are those of the arguments.
7804 @item If @var{A} and @var{P} are of type @code{INTEGER}:
7805 @code{MODULO(A,P)} has the value @var{R} such that @code{A=Q*P+R}, where
7806 @var{Q} is an integer and @var{R} is between 0 (inclusive) and @var{P}
7808 @item If @var{A} and @var{P} are of type @code{REAL}:
7809 @code{MODULO(A,P)} has the value of @code{A - FLOOR (A / P) * P}.
7811 In all cases, if @var{P} is zero the result is processor-dependent.
7813 @item @emph{Example}:
7816 print *, modulo(17,3)
7817 print *, modulo(17.5,5.5)
7819 print *, modulo(-17,3)
7820 print *, modulo(-17.5,5.5)
7822 print *, modulo(17,-3)
7823 print *, modulo(17.5,-5.5)
7832 @section @code{MOVE_ALLOC} --- Move allocation from one object to another
7834 @cindex moving allocation
7835 @cindex allocation, moving
7838 @item @emph{Description}:
7839 @code{MOVE_ALLOC(SRC, DEST)} moves the allocation from @var{SRC} to
7840 @var{DEST}. @var{SRC} will become deallocated in the process.
7842 @item @emph{Standard}:
7848 @item @emph{Syntax}:
7849 @code{CALL MOVE_ALLOC(SRC, DEST)}
7851 @item @emph{Arguments}:
7852 @multitable @columnfractions .15 .70
7853 @item @var{SRC} @tab @code{ALLOCATABLE}, @code{INTENT(INOUT)}, may be
7854 of any type and kind.
7855 @item @var{DEST} @tab @code{ALLOCATABLE}, @code{INTENT(OUT)}, shall be
7856 of the same type, kind and rank as @var{SRC}
7859 @item @emph{Return value}:
7862 @item @emph{Example}:
7864 program test_move_alloc
7865 integer, allocatable :: a(:), b(:)
7869 call move_alloc(a, b)
7870 print *, allocated(a), allocated(b)
7872 end program test_move_alloc
7879 @section @code{MVBITS} --- Move bits from one integer to another
7884 @item @emph{Description}:
7885 Moves @var{LEN} bits from positions @var{FROMPOS} through
7886 @code{FROMPOS+LEN-1} of @var{FROM} to positions @var{TOPOS} through
7887 @code{TOPOS+LEN-1} of @var{TO}. The portion of argument @var{TO} not
7888 affected by the movement of bits is unchanged. The values of
7889 @code{FROMPOS+LEN-1} and @code{TOPOS+LEN-1} must be less than
7890 @code{BIT_SIZE(FROM)}.
7892 @item @emph{Standard}:
7896 Elemental subroutine
7898 @item @emph{Syntax}:
7899 @code{CALL MVBITS(FROM, FROMPOS, LEN, TO, TOPOS)}
7901 @item @emph{Arguments}:
7902 @multitable @columnfractions .15 .70
7903 @item @var{FROM} @tab The type shall be @code{INTEGER(*)}.
7904 @item @var{FROMPOS} @tab The type shall be @code{INTEGER(*)}.
7905 @item @var{LEN} @tab The type shall be @code{INTEGER(*)}.
7906 @item @var{TO} @tab The type shall be @code{INTEGER(*)}, of the
7907 same kind as @var{FROM}.
7908 @item @var{TOPOS} @tab The type shall be @code{INTEGER(*)}.
7911 @item @emph{See also}:
7912 @ref{IBCLR}, @ref{IBSET}, @ref{IBITS}, @ref{IAND}, @ref{IOR}, @ref{IEOR}
7918 @section @code{NEAREST} --- Nearest representable number
7920 @cindex real number, nearest different
7921 @cindex floating point, nearest different
7924 @item @emph{Description}:
7925 @code{NEAREST(X, S)} returns the processor-representable number nearest
7926 to @code{X} in the direction indicated by the sign of @code{S}.
7928 @item @emph{Standard}:
7934 @item @emph{Syntax}:
7935 @code{RESULT = NEAREST(X, S)}
7937 @item @emph{Arguments}:
7938 @multitable @columnfractions .15 .70
7939 @item @var{X} @tab Shall be of type @code{REAL}.
7940 @item @var{S} @tab (Optional) shall be of type @code{REAL} and
7944 @item @emph{Return value}:
7945 The return value is of the same type as @code{X}. If @code{S} is
7946 positive, @code{NEAREST} returns the processor-representable number
7947 greater than @code{X} and nearest to it. If @code{S} is negative,
7948 @code{NEAREST} returns the processor-representable number smaller than
7949 @code{X} and nearest to it.
7951 @item @emph{Example}:
7953 program test_nearest
7955 x = nearest(42.0, 1.0)
7956 y = nearest(42.0, -1.0)
7957 write (*,"(3(G20.15))") x, y, x - y
7958 end program test_nearest
7965 @section @code{NEW_LINE} --- New line character
7968 @cindex output, newline
7971 @item @emph{Description}:
7972 @code{NEW_LINE(C)} returns the new-line character.
7974 @item @emph{Standard}:
7980 @item @emph{Syntax}:
7981 @code{RESULT = NEW_LINE(C)}
7983 @item @emph{Arguments}:
7984 @multitable @columnfractions .15 .70
7985 @item @var{C} @tab The argument shall be a scalar or array of the
7986 type @code{CHARACTER}.
7989 @item @emph{Return value}:
7990 Returns a @var{CHARACTER} scalar of length one with the new-line character of
7991 the same kind as parameter @var{C}.
7993 @item @emph{Example}:
7997 write(*,'(A)') 'This is record 1.'//NEW_LINE('A')//'This is record 2.'
8005 @section @code{NINT} --- Nearest whole number
8008 @cindex rounding, nearest whole number
8011 @item @emph{Description}:
8012 @code{NINT(X)} rounds its argument to the nearest whole number.
8014 @item @emph{Standard}:
8020 @item @emph{Syntax}:
8021 @code{RESULT = NINT(X)}
8023 @item @emph{Arguments}:
8024 @multitable @columnfractions .15 .70
8025 @item @var{X} @tab The type of the argument shall be @code{REAL}.
8028 @item @emph{Return value}:
8029 Returns @var{A} with the fractional portion of its magnitude eliminated by
8030 rounding to the nearest whole number and with its sign preserved,
8031 converted to an @code{INTEGER} of the default kind.
8033 @item @emph{Example}:
8040 print *, nint(x4), idnint(x8)
8041 end program test_nint
8044 @item @emph{Specific names}:
8045 @multitable @columnfractions .25 .25 .25
8046 @item Name @tab Argument @tab Standard
8047 @item @code{IDNINT(X)} @tab @code{REAL(8)} @tab F95 and later
8050 @item @emph{See also}:
8051 @ref{CEILING}, @ref{FLOOR}
8058 @section @code{NOT} --- Logical negation
8060 @cindex bits, negate
8061 @cindex bitwise logical not
8062 @cindex logical not, bitwise
8065 @item @emph{Description}:
8066 @code{NOT} returns the bitwise boolean inverse of @var{I}.
8068 @item @emph{Standard}:
8074 @item @emph{Syntax}:
8075 @code{RESULT = NOT(I)}
8077 @item @emph{Arguments}:
8078 @multitable @columnfractions .15 .70
8079 @item @var{I} @tab The type shall be @code{INTEGER(*)}.
8082 @item @emph{Return value}:
8083 The return type is @code{INTEGER(*)}, of the same kind as the
8086 @item @emph{See also}:
8087 @ref{IAND}, @ref{IEOR}, @ref{IOR}, @ref{IBITS}, @ref{IBSET}, @ref{IBCLR}
8094 @section @code{NULL} --- Function that returns an disassociated pointer
8096 @cindex pointer, status
8097 @cindex pointer, disassociated
8100 @item @emph{Description}:
8101 Returns a disassociated pointer.
8103 If @var{MOLD} is present, a dissassociated pointer of the same type is
8104 returned, otherwise the type is determined by context.
8106 In Fortran 95, @var{MOLD} is optional. Please note that F2003 includes
8107 cases where it is required.
8109 @item @emph{Standard}:
8113 Transformational function
8115 @item @emph{Syntax}:
8116 @code{PTR => NULL([MOLD])}
8118 @item @emph{Arguments}:
8119 @multitable @columnfractions .15 .70
8120 @item @var{MOLD} @tab (Optional) shall be a pointer of any association
8121 status and of any type.
8124 @item @emph{Return value}:
8125 A disassociated pointer.
8127 @item @emph{Example}:
8129 REAL, POINTER, DIMENSION(:) :: VEC => NULL ()
8132 @item @emph{See also}:
8139 @section @code{OR} --- Bitwise logical OR
8141 @cindex bitwise logical or
8142 @cindex logical or, bitwise
8145 @item @emph{Description}:
8146 Bitwise logical @code{OR}.
8148 This intrinsic routine is provided for backwards compatibility with
8149 GNU Fortran 77. For integer arguments, programmers should consider
8150 the use of the @ref{IOR} intrinsic defined by the Fortran standard.
8152 @item @emph{Standard}:
8158 @item @emph{Syntax}:
8159 @code{RESULT = OR(X, Y)}
8161 @item @emph{Arguments}:
8162 @multitable @columnfractions .15 .70
8163 @item @var{X} @tab The type shall be either @code{INTEGER(*)} or @code{LOGICAL}.
8164 @item @var{Y} @tab The type shall be either @code{INTEGER(*)} or @code{LOGICAL}.
8167 @item @emph{Return value}:
8168 The return type is either @code{INTEGER(*)} or @code{LOGICAL}
8169 after cross-promotion of the arguments.
8171 @item @emph{Example}:
8174 LOGICAL :: T = .TRUE., F = .FALSE.
8176 DATA a / Z'F' /, b / Z'3' /
8178 WRITE (*,*) OR(T, T), OR(T, F), OR(F, T), OR(F, F)
8179 WRITE (*,*) OR(a, b)
8183 @item @emph{See also}:
8184 F95 elemental function: @ref{IOR}
8190 @section @code{PACK} --- Pack an array into an array of rank one
8192 @cindex array, packing
8193 @cindex array, reduce dimension
8194 @cindex array, gather elements
8197 @item @emph{Description}:
8198 Stores the elements of @var{ARRAY} in an array of rank one.
8200 The beginning of the resulting array is made up of elements whose @var{MASK}
8201 equals @code{TRUE}. Afterwards, positions are filled with elements taken from
8204 @item @emph{Standard}:
8208 Transformational function
8210 @item @emph{Syntax}:
8211 @code{RESULT = PACK(ARRAY, MASK[,VECTOR]}
8213 @item @emph{Arguments}:
8214 @multitable @columnfractions .15 .70
8215 @item @var{ARRAY} @tab Shall be an array of any type.
8216 @item @var{MASK} @tab Shall be an array of type @code{LOGICAL} and
8217 of the same size as @var{ARRAY}. Alternatively, it may be a @code{LOGICAL}
8219 @item @var{VECTOR} @tab (Optional) shall be an array of the same type
8220 as @var{ARRAY} and of rank one. If present, the number of elements in
8221 @var{VECTOR} shall be equal to or greater than the number of true elements
8222 in @var{MASK}. If @var{MASK} is scalar, the number of elements in
8223 @var{VECTOR} shall be equal to or greater than the number of elements in
8227 @item @emph{Return value}:
8228 The result is an array of rank one and the same type as that of @var{ARRAY}.
8229 If @var{VECTOR} is present, the result size is that of @var{VECTOR}, the
8230 number of @code{TRUE} values in @var{MASK} otherwise.
8232 @item @emph{Example}:
8233 Gathering nonzero elements from an array:
8237 m = (/ 1, 0, 0, 0, 5, 0 /)
8238 WRITE(*, FMT="(6(I0, ' '))") pack(m, m /= 0) ! "1 5"
8242 Gathering nonzero elements from an array and appending elements from @var{VECTOR}:
8246 m = (/ 1, 0, 0, 2 /)
8247 WRITE(*, FMT="(4(I0, ' '))") pack(m, m /= 0, (/ 0, 0, 3, 4 /)) ! "1 2 3 4"
8251 @item @emph{See also}:
8258 @section @code{PERROR} --- Print system error message
8260 @cindex system, error handling
8263 @item @emph{Description}:
8264 Prints (on the C @code{stderr} stream) a newline-terminated error
8265 message corresponding to the last system error. This is prefixed by
8266 @var{STRING}, a colon and a space. See @code{perror(3)}.
8268 @item @emph{Standard}:
8274 @item @emph{Syntax}:
8275 @code{CALL PERROR(STRING)}
8277 @item @emph{Arguments}:
8278 @multitable @columnfractions .15 .70
8279 @item @var{STRING} @tab A scalar of default @code{CHARACTER} type.
8282 @item @emph{See also}:
8289 @section @code{PRECISION} --- Decimal precision of a real kind
8291 @cindex model representation, precision
8294 @item @emph{Description}:
8295 @code{PRECISION(X)} returns the decimal precision in the model of the
8298 @item @emph{Standard}:
8304 @item @emph{Syntax}:
8305 @code{RESULT = PRECISION(X)}
8307 @item @emph{Arguments}:
8308 @multitable @columnfractions .15 .70
8309 @item @var{X} @tab Shall be of type @code{REAL} or @code{COMPLEX}.
8312 @item @emph{Return value}:
8313 The return value is of type @code{INTEGER} and of the default integer
8316 @item @emph{Example}:
8318 program prec_and_range
8319 real(kind=4) :: x(2)
8320 complex(kind=8) :: y
8322 print *, precision(x), range(x)
8323 print *, precision(y), range(y)
8324 end program prec_and_range
8331 @section @code{PRESENT} --- Determine whether an optional dummy argument is specified
8335 @item @emph{Description}:
8336 Determines whether an optional dummy argument is present.
8338 @item @emph{Standard}:
8344 @item @emph{Syntax}:
8345 @code{RESULT = PRESENT(A)}
8347 @item @emph{Arguments}:
8348 @multitable @columnfractions .15 .70
8349 @item @var{A} @tab May be of any type and may be a pointer, scalar or array
8350 value, or a dummy procedure. It shall be the name of an optional dummy argument
8351 accessible within the current subroutine or function.
8354 @item @emph{Return value}:
8355 Returns either @code{TRUE} if the optional argument @var{A} is present, or
8356 @code{FALSE} otherwise.
8358 @item @emph{Example}:
8360 PROGRAM test_present
8361 WRITE(*,*) f(), f(42) ! "F T"
8363 LOGICAL FUNCTION f(x)
8364 INTEGER, INTENT(IN), OPTIONAL :: x
8374 @section @code{PRODUCT} --- Product of array elements
8376 @cindex array, product
8377 @cindex array, multiply elements
8378 @cindex array, conditionally multiply elements
8379 @cindex multiply array elements
8382 @item @emph{Description}:
8383 Multiplies the elements of @var{ARRAY} along dimension @var{DIM} if
8384 the corresponding element in @var{MASK} is @code{TRUE}.
8386 @item @emph{Standard}:
8390 Transformational function
8392 @item @emph{Syntax}:
8393 @code{RESULT = PRODUCT(ARRAY[, MASK])}
8394 @code{RESULT = PRODUCT(ARRAY, DIM[, MASK])}
8396 @item @emph{Arguments}:
8397 @multitable @columnfractions .15 .70
8398 @item @var{ARRAY} @tab Shall be an array of type @code{INTEGER(*)},
8399 @code{REAL(*)} or @code{COMPLEX(*)}.
8400 @item @var{DIM} @tab (Optional) shall be a scalar of type
8401 @code{INTEGER} with a value in the range from 1 to n, where n
8402 equals the rank of @var{ARRAY}.
8403 @item @var{MASK} @tab (Optional) shall be of type @code{LOGICAL}
8404 and either be a scalar or an array of the same shape as @var{ARRAY}.
8407 @item @emph{Return value}:
8408 The result is of the same type as @var{ARRAY}.
8410 If @var{DIM} is absent, a scalar with the product of all elements in
8411 @var{ARRAY} is returned. Otherwise, an array of rank n-1, where n equals
8412 the rank of @var{ARRAY}, and a shape similar to that of @var{ARRAY} with
8413 dimension @var{DIM} dropped is returned.
8416 @item @emph{Example}:
8418 PROGRAM test_product
8419 INTEGER :: x(5) = (/ 1, 2, 3, 4 ,5 /)
8420 print *, PRODUCT(x) ! all elements, product = 120
8421 print *, PRODUCT(x, MASK=MOD(x, 2)==1) ! odd elements, product = 15
8425 @item @emph{See also}:
8432 @section @code{RADIX} --- Base of a model number
8434 @cindex model representation, base
8435 @cindex model representation, radix
8438 @item @emph{Description}:
8439 @code{RADIX(X)} returns the base of the model representing the entity @var{X}.
8441 @item @emph{Standard}:
8447 @item @emph{Syntax}:
8448 @code{RESULT = RADIX(X)}
8450 @item @emph{Arguments}:
8451 @multitable @columnfractions .15 .70
8452 @item @var{X} @tab Shall be of type @code{INTEGER} or @code{REAL}
8455 @item @emph{Return value}:
8456 The return value is a scalar of type @code{INTEGER} and of the default
8459 @item @emph{Example}:
8462 print *, "The radix for the default integer kind is", radix(0)
8463 print *, "The radix for the default real kind is", radix(0.0)
8464 end program test_radix
8472 @section @code{RAN} --- Real pseudo-random number
8474 @cindex random number generation
8477 @item @emph{Description}:
8478 For compatibility with HP FORTRAN 77/iX, the @code{RAN} intrinsic is
8479 provided as an alias for @code{RAND}. See @ref{RAND} for complete
8482 @item @emph{Standard}:
8488 @item @emph{See also}:
8489 @ref{RAND}, @ref{RANDOM_NUMBER}
8495 @section @code{RAND} --- Real pseudo-random number
8497 @cindex random number generation
8500 @item @emph{Description}:
8501 @code{RAND(FLAG)} returns a pseudo-random number from a uniform
8502 distribution between 0 and 1. If @var{FLAG} is 0, the next number
8503 in the current sequence is returned; if @var{FLAG} is 1, the generator
8504 is restarted by @code{CALL SRAND(0)}; if @var{FLAG} has any other value,
8505 it is used as a new seed with @code{SRAND}.
8507 This intrinsic routine is provided for backwards compatibility with
8508 GNU Fortran 77. It implements a simple modulo generator as provided
8509 by @command{g77}. For new code, one should consider the use of
8510 @ref{RANDOM_NUMBER} as it implements a superior algorithm.
8512 @item @emph{Standard}:
8518 @item @emph{Syntax}:
8519 @code{RESULT = RAND(FLAG)}
8521 @item @emph{Arguments}:
8522 @multitable @columnfractions .15 .70
8523 @item @var{FLAG} @tab Shall be a scalar @code{INTEGER} of kind 4.
8526 @item @emph{Return value}:
8527 The return value is of @code{REAL} type and the default kind.
8529 @item @emph{Example}:
8532 integer,parameter :: seed = 86456
8535 print *, rand(), rand(), rand(), rand()
8536 print *, rand(seed), rand(), rand(), rand()
8537 end program test_rand
8540 @item @emph{See also}:
8541 @ref{SRAND}, @ref{RANDOM_NUMBER}
8548 @section @code{RANDOM_NUMBER} --- Pseudo-random number
8549 @fnindex RANDOM_NUMBER
8550 @cindex random number generation
8553 @item @emph{Description}:
8554 Returns a single pseudorandom number or an array of pseudorandom numbers
8555 from the uniform distribution over the range @math{ 0 \leq x < 1}.
8557 The runtime-library implements George Marsaglia's KISS (Keep It Simple
8558 Stupid) random number generator (RNG). This RNG combines:
8560 @item The congruential generator @math{x(n) = 69069 \cdot x(n-1) + 1327217885}
8561 with a period of @math{2^{32}},
8562 @item A 3-shift shift-register generator with a period of @math{2^{32} - 1},
8563 @item Two 16-bit multiply-with-carry generators with a period of
8564 @math{597273182964842497 > 2^{59}}.
8566 The overall period exceeds @math{2^{123}}.
8568 Please note, this RNG is thread safe if used within OpenMP directives,
8569 i. e. its state will be consistent while called from multiple threads.
8570 However, the KISS generator does not create random numbers in parallel
8571 from multiple sources, but in sequence from a single source. If an
8572 OpenMP-enabled application heavily relies on random numbers, one should
8573 consider employing a dedicated parallel random number generator instead.
8575 @item @emph{Standard}:
8581 @item @emph{Syntax}:
8582 @code{RANDOM_NUMBER(HARVEST)}
8584 @item @emph{Arguments}:
8585 @multitable @columnfractions .15 .70
8586 @item @var{HARVEST} @tab Shall be a scalar or an array of type @code{REAL(*)}.
8589 @item @emph{Example}:
8591 program test_random_number
8593 CALL init_random_seed() ! see example of RANDOM_SEED
8594 CALL RANDOM_NUMBER(r)
8598 @item @emph{See also}:
8605 @section @code{RANDOM_SEED} --- Initialize a pseudo-random number sequence
8606 @fnindex RANDOM_SEED
8607 @cindex random number generation, seeding
8608 @cindex seeding a random number generator
8611 @item @emph{Description}:
8612 Restarts or queries the state of the pseudorandom number generator used by
8613 @code{RANDOM_NUMBER}.
8615 If @code{RANDOM_SEED} is called without arguments, it is initialized to
8616 a default state. The example below shows how to initialize the random
8617 seed based on the system's time.
8619 @item @emph{Standard}:
8625 @item @emph{Syntax}:
8626 @code{CALL RANDOM_SEED(SIZE, PUT, GET)}
8628 @item @emph{Arguments}:
8629 @multitable @columnfractions .15 .70
8630 @item @var{SIZE} @tab (Optional) Shall be a scalar and of type default
8631 @code{INTEGER}, with @code{INTENT(OUT)}. It specifies the minimum size
8632 of the arrays used with the @var{PUT} and @var{GET} arguments.
8633 @item @var{PUT} @tab (Optional) Shall be an array of type default
8634 @code{INTEGER} and rank one. It is @code{INTENT(IN)} and the size of
8635 the array must be larger than or equal to the number returned by the
8636 @var{SIZE} argument.
8637 @item @var{GET} @tab (Optional) Shall be an array of type default
8638 @code{INTEGER} and rank one. It is @code{INTENT(OUT)} and the size
8639 of the array must be larger than or equal to the number returned by
8640 the @var{SIZE} argument.
8643 @item @emph{Example}:
8645 SUBROUTINE init_random_seed()
8646 INTEGER :: i, n, clock
8647 INTEGER, DIMENSION(:), ALLOCATABLE :: seed
8649 CALL RANDOM_SEED(size = n)
8652 CALL SYSTEM_CLOCK(COUNT=clock)
8654 seed = clock + 37 * (/ (i - 1, i = 1, n) /)
8655 CALL RANDOM_SEED(PUT = seed)
8661 @item @emph{See also}:
8668 @section @code{RANGE} --- Decimal exponent range of a real kind
8670 @cindex model representation, range
8673 @item @emph{Description}:
8674 @code{RANGE(X)} returns the decimal exponent range in the model of the
8677 @item @emph{Standard}:
8683 @item @emph{Syntax}:
8684 @code{RESULT = RANGE(X)}
8686 @item @emph{Arguments}:
8687 @multitable @columnfractions .15 .70
8688 @item @var{X} @tab Shall be of type @code{REAL} or @code{COMPLEX}.
8691 @item @emph{Return value}:
8692 The return value is of type @code{INTEGER} and of the default integer
8695 @item @emph{Example}:
8696 See @code{PRECISION} for an example.
8702 @section @code{REAL} --- Convert to real type
8705 @cindex conversion, to real
8706 @cindex complex numbers, real part
8709 @item @emph{Description}:
8710 @code{REAL(X [, KIND])} converts its argument @var{X} to a real type. The
8711 @code{REALPART(X)} function is provided for compatibility with @command{g77},
8712 and its use is strongly discouraged.
8714 @item @emph{Standard}:
8720 @item @emph{Syntax}:
8721 @multitable @columnfractions .80
8722 @item @code{RESULT = REAL(X [, KIND])}
8723 @item @code{RESULT = REALPART(Z)}
8726 @item @emph{Arguments}:
8727 @multitable @columnfractions .15 .70
8728 @item @var{X} @tab Shall be @code{INTEGER(*)}, @code{REAL(*)}, or
8730 @item @var{KIND} @tab (Optional) An @code{INTEGER(*)} initialization
8731 expression indicating the kind parameter of
8735 @item @emph{Return value}:
8736 These functions return a @code{REAL(*)} variable or array under
8737 the following rules:
8741 @code{REAL(X)} is converted to a default real type if @var{X} is an
8742 integer or real variable.
8744 @code{REAL(X)} is converted to a real type with the kind type parameter
8745 of @var{X} if @var{X} is a complex variable.
8747 @code{REAL(X, KIND)} is converted to a real type with kind type
8748 parameter @var{KIND} if @var{X} is a complex, integer, or real
8752 @item @emph{Example}:
8755 complex :: x = (1.0, 2.0)
8756 print *, real(x), real(x,8), realpart(x)
8757 end program test_real
8760 @item @emph{See also}:
8761 @ref{DBLE}, @ref{DFLOAT}, @ref{FLOAT}
8768 @section @code{RENAME} --- Rename a file
8770 @cindex file system, rename file
8773 @item @emph{Description}:
8774 Renames a file from file @var{PATH1} to @var{PATH2}. A null
8775 character (@code{CHAR(0)}) can be used to mark the end of the names in
8776 @var{PATH1} and @var{PATH2}; otherwise, trailing blanks in the file
8777 names are ignored. If the @var{STATUS} argument is supplied, it
8778 contains 0 on success or a nonzero error code upon return; see
8781 This intrinsic is provided in both subroutine and function forms;
8782 however, only one form can be used in any given program unit.
8784 @item @emph{Standard}:
8788 Subroutine, function
8790 @item @emph{Syntax}:
8791 @multitable @columnfractions .80
8792 @item @code{CALL RENAME(PATH1, PATH2 [, STATUS])}
8793 @item @code{STATUS = RENAME(PATH1, PATH2)}
8796 @item @emph{Arguments}:
8797 @multitable @columnfractions .15 .70
8798 @item @var{PATH1} @tab Shall be of default @code{CHARACTER} type.
8799 @item @var{PATH2} @tab Shall be of default @code{CHARACTER} type.
8800 @item @var{STATUS} @tab (Optional) Shall be of default @code{INTEGER} type.
8803 @item @emph{See also}:
8811 @section @code{REPEAT} --- Repeated string concatenation
8813 @cindex string, repeat
8814 @cindex string, concatenate
8817 @item @emph{Description}:
8818 Concatenates @var{NCOPIES} copies of a string.
8820 @item @emph{Standard}:
8824 Transformational function
8826 @item @emph{Syntax}:
8827 @code{RESULT = REPEAT(STRING, NCOPIES)}
8829 @item @emph{Arguments}:
8830 @multitable @columnfractions .15 .70
8831 @item @var{STRING} @tab Shall be scalar and of type @code{CHARACTER(*)}.
8832 @item @var{NCOPIES} @tab Shall be scalar and of type @code{INTEGER(*)}.
8835 @item @emph{Return value}:
8836 A new scalar of type @code{CHARACTER} built up from @var{NCOPIES} copies
8839 @item @emph{Example}:
8842 write(*,*) repeat("x", 5) ! "xxxxx"
8850 @section @code{RESHAPE} --- Function to reshape an array
8852 @cindex array, change dimensions
8853 @cindex array, transmogrify
8856 @item @emph{Description}:
8857 Reshapes @var{SOURCE} to correspond to @var{SHAPE}. If necessary,
8858 the new array may be padded with elements from @var{PAD} or permuted
8859 as defined by @var{ORDER}.
8861 @item @emph{Standard}:
8865 Transformational function
8867 @item @emph{Syntax}:
8868 @code{RESULT = RESHAPE(SOURCE, SHAPE[, PAD, ORDER])}
8870 @item @emph{Arguments}:
8871 @multitable @columnfractions .15 .70
8872 @item @var{SOURCE} @tab Shall be an array of any type.
8873 @item @var{SHAPE} @tab Shall be of type @code{INTEGER} and an
8874 array of rank one. Its values must be positive or zero.
8875 @item @var{PAD} @tab (Optional) shall be an array of the same
8876 type as @var{SOURCE}.
8877 @item @var{ORDER} @tab (Optional) shall be of type @code{INTEGER}
8878 and an array of the same shape as @var{SHAPE}. Its values shall
8879 be a permutation of the numbers from 1 to n, where n is the size of
8880 @var{SHAPE}. If @var{ORDER} is absent, the natural ordering shall
8884 @item @emph{Return value}:
8885 The result is an array of shape @var{SHAPE} with the same type as
8888 @item @emph{Example}:
8890 PROGRAM test_reshape
8891 INTEGER, DIMENSION(4) :: x
8892 WRITE(*,*) SHAPE(x) ! prints "4"
8893 WRITE(*,*) SHAPE(RESHAPE(x, (/2, 2/))) ! prints "2 2"
8897 @item @emph{See also}:
8904 @section @code{RRSPACING} --- Reciprocal of the relative spacing
8906 @cindex real number, relative spacing
8907 @cindex floating point, relative spacing
8911 @item @emph{Description}:
8912 @code{RRSPACING(X)} returns the reciprocal of the relative spacing of
8913 model numbers near @var{X}.
8915 @item @emph{Standard}:
8921 @item @emph{Syntax}:
8922 @code{RESULT = RRSPACING(X)}
8924 @item @emph{Arguments}:
8925 @multitable @columnfractions .15 .70
8926 @item @var{X} @tab Shall be of type @code{REAL}.
8929 @item @emph{Return value}:
8930 The return value is of the same type and kind as @var{X}.
8931 The value returned is equal to
8932 @code{ABS(FRACTION(X)) * FLOAT(RADIX(X))**DIGITS(X)}.
8934 @item @emph{See also}:
8941 @section @code{RSHIFT} --- Right shift bits
8943 @cindex bits, shift right
8946 @item @emph{Description}:
8947 @code{RSHIFT} returns a value corresponding to @var{I} with all of the
8948 bits shifted right by @var{SHIFT} places. If the absolute value of
8949 @var{SHIFT} is greater than @code{BIT_SIZE(I)}, the value is undefined.
8950 Bits shifted out from the left end are lost; zeros are shifted in from
8953 This function has been superseded by the @code{ISHFT} intrinsic, which
8954 is standard in Fortran 95 and later.
8956 @item @emph{Standard}:
8962 @item @emph{Syntax}:
8963 @code{RESULT = RSHIFT(I, SHIFT)}
8965 @item @emph{Arguments}:
8966 @multitable @columnfractions .15 .70
8967 @item @var{I} @tab The type shall be @code{INTEGER(*)}.
8968 @item @var{SHIFT} @tab The type shall be @code{INTEGER(*)}.
8971 @item @emph{Return value}:
8972 The return value is of type @code{INTEGER(*)} and of the same kind as
8975 @item @emph{See also}:
8976 @ref{ISHFT}, @ref{ISHFTC}, @ref{LSHIFT}
8983 @section @code{SCALE} --- Scale a real value
8985 @cindex real number, scale
8986 @cindex floating point, scale
8989 @item @emph{Description}:
8990 @code{SCALE(X,I)} returns @code{X * RADIX(X)**I}.
8992 @item @emph{Standard}:
8998 @item @emph{Syntax}:
8999 @code{RESULT = SCALE(X, I)}
9001 @item @emph{Arguments}:
9002 @multitable @columnfractions .15 .70
9003 @item @var{X} @tab The type of the argument shall be a @code{REAL}.
9004 @item @var{I} @tab The type of the argument shall be a @code{INTEGER}.
9007 @item @emph{Return value}:
9008 The return value is of the same type and kind as @var{X}.
9009 Its value is @code{X * RADIX(X)**I}.
9011 @item @emph{Example}:
9014 real :: x = 178.1387e-4
9016 print *, scale(x,i), x*radix(x)**i
9017 end program test_scale
9025 @section @code{SCAN} --- Scan a string for the presence of a set of characters
9027 @cindex string, find subset
9030 @item @emph{Description}:
9031 Scans a @var{STRING} for any of the characters in a @var{SET}
9034 If @var{BACK} is either absent or equals @code{FALSE}, this function
9035 returns the position of the leftmost character of @var{STRING} that is
9036 in @var{SET}. If @var{BACK} equals @code{TRUE}, the rightmost position
9037 is returned. If no character of @var{SET} is found in @var{STRING}, the
9040 @item @emph{Standard}:
9046 @item @emph{Syntax}:
9047 @code{RESULT = SCAN(STRING, SET[, BACK [, KIND]])}
9049 @item @emph{Arguments}:
9050 @multitable @columnfractions .15 .70
9051 @item @var{STRING} @tab Shall be of type @code{CHARACTER(*)}.
9052 @item @var{SET} @tab Shall be of type @code{CHARACTER(*)}.
9053 @item @var{BACK} @tab (Optional) shall be of type @code{LOGICAL}.
9054 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
9055 expression indicating the kind parameter of
9059 @item @emph{Return value}:
9060 The return value is of type @code{INTEGER} and of kind @var{KIND}. If
9061 @var{KIND} is absent, the return value is of default integer kind.
9063 @item @emph{Example}:
9066 WRITE(*,*) SCAN("FORTRAN", "AO") ! 2, found 'O'
9067 WRITE(*,*) SCAN("FORTRAN", "AO", .TRUE.) ! 6, found 'A'
9068 WRITE(*,*) SCAN("FORTRAN", "C++") ! 0, found none
9072 @item @emph{See also}:
9073 @ref{INDEX intrinsic}, @ref{VERIFY}
9079 @section @code{SECNDS} --- Time function
9081 @cindex time, elapsed
9082 @cindex elapsed time
9085 @item @emph{Description}:
9086 @code{SECNDS(X)} gets the time in seconds from the real-time system clock.
9087 @var{X} is a reference time, also in seconds. If this is zero, the time in
9088 seconds from midnight is returned. This function is non-standard and its
9091 @item @emph{Standard}:
9097 @item @emph{Syntax}:
9098 @code{RESULT = SECNDS (X)}
9100 @item @emph{Arguments}:
9101 @multitable @columnfractions .15 .70
9102 @item @var{T} @tab Shall be of type @code{REAL(4)}.
9103 @item @var{X} @tab Shall be of type @code{REAL(4)}.
9106 @item @emph{Return value}:
9109 @item @emph{Example}:
9114 print *, secnds (0.0) ! seconds since midnight
9115 t1 = secnds (0.0) ! reference time
9116 do i = 1, 10000000 ! do something
9118 t2 = secnds (t1) ! elapsed time
9119 print *, "Something took ", t2, " seconds."
9120 end program test_secnds
9127 @section @code{SECOND} --- CPU time function
9129 @cindex time, elapsed
9130 @cindex elapsed time
9133 @item @emph{Description}:
9134 Returns a @code{REAL(4)} value representing the elapsed CPU time in
9135 seconds. This provides the same functionality as the standard
9136 @code{CPU_TIME} intrinsic, and is only included for backwards
9139 This intrinsic is provided in both subroutine and function forms;
9140 however, only one form can be used in any given program unit.
9142 @item @emph{Standard}:
9146 Subroutine, function
9148 @item @emph{Syntax}:
9149 @multitable @columnfractions .80
9150 @item @code{CALL SECOND(TIME)}
9151 @item @code{TIME = SECOND()}
9154 @item @emph{Arguments}:
9155 @multitable @columnfractions .15 .70
9156 @item @var{TIME} @tab Shall be of type @code{REAL(4)}.
9159 @item @emph{Return value}:
9160 In either syntax, @var{TIME} is set to the process's current runtime in
9163 @item @emph{See also}:
9170 @node SELECTED_INT_KIND
9171 @section @code{SELECTED_INT_KIND} --- Choose integer kind
9172 @fnindex SELECTED_INT_KIND
9173 @cindex integer kind
9174 @cindex kind, integer
9177 @item @emph{Description}:
9178 @code{SELECTED_INT_KIND(I)} return the kind value of the smallest integer
9179 type that can represent all values ranging from @math{-10^I} (exclusive)
9180 to @math{10^I} (exclusive). If there is no integer kind that accommodates
9181 this range, @code{SELECTED_INT_KIND} returns @math{-1}.
9183 @item @emph{Standard}:
9187 Transformational function
9189 @item @emph{Syntax}:
9190 @code{RESULT = SELECTED_INT_KIND(I)}
9192 @item @emph{Arguments}:
9193 @multitable @columnfractions .15 .70
9194 @item @var{I} @tab Shall be a scalar and of type @code{INTEGER}.
9197 @item @emph{Example}:
9199 program large_integers
9200 integer,parameter :: k5 = selected_int_kind(5)
9201 integer,parameter :: k15 = selected_int_kind(15)
9202 integer(kind=k5) :: i5
9203 integer(kind=k15) :: i15
9205 print *, huge(i5), huge(i15)
9207 ! The following inequalities are always true
9208 print *, huge(i5) >= 10_k5**5-1
9209 print *, huge(i15) >= 10_k15**15-1
9210 end program large_integers
9216 @node SELECTED_REAL_KIND
9217 @section @code{SELECTED_REAL_KIND} --- Choose real kind
9218 @fnindex SELECTED_REAL_KIND
9223 @item @emph{Description}:
9224 @code{SELECTED_REAL_KIND(P,R)} return the kind value of a real data type
9225 with decimal precision greater of at least @code{P} digits and exponent
9226 range greater at least @code{R}.
9228 @item @emph{Standard}:
9232 Transformational function
9234 @item @emph{Syntax}:
9235 @code{RESULT = SELECTED_REAL_KIND(P, R)}
9237 @item @emph{Arguments}:
9238 @multitable @columnfractions .15 .70
9239 @item @var{P} @tab (Optional) shall be a scalar and of type @code{INTEGER}.
9240 @item @var{R} @tab (Optional) shall be a scalar and of type @code{INTEGER}.
9242 At least one argument shall be present.
9244 @item @emph{Return value}:
9246 @code{SELECTED_REAL_KIND} returns the value of the kind type parameter of
9247 a real data type with decimal precision of at least @code{P} digits and a
9248 decimal exponent range of at least @code{R}. If more than one real data
9249 type meet the criteria, the kind of the data type with the smallest
9250 decimal precision is returned. If no real data type matches the criteria,
9253 @item -1 if the processor does not support a real data type with a
9254 precision greater than or equal to @code{P}
9255 @item -2 if the processor does not support a real type with an exponent
9256 range greater than or equal to @code{R}
9257 @item -3 if neither is supported.
9260 @item @emph{Example}:
9263 integer,parameter :: p6 = selected_real_kind(6)
9264 integer,parameter :: p10r100 = selected_real_kind(10,100)
9265 integer,parameter :: r400 = selected_real_kind(r=400)
9267 real(kind=p10r100) :: y
9268 real(kind=r400) :: z
9270 print *, precision(x), range(x)
9271 print *, precision(y), range(y)
9272 print *, precision(z), range(z)
9273 end program real_kinds
9280 @section @code{SET_EXPONENT} --- Set the exponent of the model
9281 @fnindex SET_EXPONENT
9282 @cindex real number, set exponent
9283 @cindex floating point, set exponent
9286 @item @emph{Description}:
9287 @code{SET_EXPONENT(X, I)} returns the real number whose fractional part
9288 is that that of @var{X} and whose exponent part is @var{I}.
9290 @item @emph{Standard}:
9296 @item @emph{Syntax}:
9297 @code{RESULT = SET_EXPONENT(X, I)}
9299 @item @emph{Arguments}:
9300 @multitable @columnfractions .15 .70
9301 @item @var{X} @tab Shall be of type @code{REAL}.
9302 @item @var{I} @tab Shall be of type @code{INTEGER}.
9305 @item @emph{Return value}:
9306 The return value is of the same type and kind as @var{X}.
9307 The real number whose fractional part
9308 is that that of @var{X} and whose exponent part if @var{I} is returned;
9309 it is @code{FRACTION(X) * RADIX(X)**I}.
9311 @item @emph{Example}:
9314 REAL :: x = 178.1387e-4
9316 PRINT *, SET_EXPONENT(x, i), FRACTION(x) * RADIX(x)**i
9325 @section @code{SHAPE} --- Determine the shape of an array
9327 @cindex array, shape
9330 @item @emph{Description}:
9331 Determines the shape of an array.
9333 @item @emph{Standard}:
9339 @item @emph{Syntax}:
9340 @code{RESULT = SHAPE(SOURCE)}
9342 @item @emph{Arguments}:
9343 @multitable @columnfractions .15 .70
9344 @item @var{SOURCE} @tab Shall be an array or scalar of any type.
9345 If @var{SOURCE} is a pointer it must be associated and allocatable
9346 arrays must be allocated.
9349 @item @emph{Return value}:
9350 An @code{INTEGER} array of rank one with as many elements as @var{SOURCE}
9351 has dimensions. The elements of the resulting array correspond to the extend
9352 of @var{SOURCE} along the respective dimensions. If @var{SOURCE} is a scalar,
9353 the result is the rank one array of size zero.
9355 @item @emph{Example}:
9358 INTEGER, DIMENSION(-1:1, -1:2) :: A
9359 WRITE(*,*) SHAPE(A) ! (/ 3, 4 /)
9360 WRITE(*,*) SIZE(SHAPE(42)) ! (/ /)
9364 @item @emph{See also}:
9365 @ref{RESHAPE}, @ref{SIZE}
9371 @section @code{SIGN} --- Sign copying function
9375 @cindex sign copying
9378 @item @emph{Description}:
9379 @code{SIGN(A,B)} returns the value of @var{A} with the sign of @var{B}.
9381 @item @emph{Standard}:
9387 @item @emph{Syntax}:
9388 @code{RESULT = SIGN(A, B)}
9390 @item @emph{Arguments}:
9391 @multitable @columnfractions .15 .70
9392 @item @var{A} @tab Shall be of type @code{INTEGER} or @code{REAL}
9393 @item @var{B} @tab Shall be of the same type and kind as @var{A}
9396 @item @emph{Return value}:
9397 The kind of the return value is that of @var{A} and @var{B}.
9398 If @math{B\ge 0} then the result is @code{ABS(A)}, else
9399 it is @code{-ABS(A)}.
9401 @item @emph{Example}:
9404 print *, sign(-12,1)
9405 print *, sign(-12,0)
9406 print *, sign(-12,-1)
9408 print *, sign(-12.,1.)
9409 print *, sign(-12.,0.)
9410 print *, sign(-12.,-1.)
9411 end program test_sign
9414 @item @emph{Specific names}:
9415 @multitable @columnfractions .20 .20 .20 .25
9416 @item Name @tab Arguments @tab Return type @tab Standard
9417 @item @code{ISIGN(A,P)} @tab @code{INTEGER(4)} @tab @code{INTEGER(4)} @tab f95, gnu
9418 @item @code{DSIGN(A,P)} @tab @code{REAL(8)} @tab @code{REAL(8)} @tab f95, gnu
9425 @section @code{SIGNAL} --- Signal handling subroutine (or function)
9427 @cindex system, signal handling
9430 @item @emph{Description}:
9431 @code{SIGNAL(NUMBER, HANDLER [, STATUS])} causes external subroutine
9432 @var{HANDLER} to be executed with a single integer argument when signal
9433 @var{NUMBER} occurs. If @var{HANDLER} is an integer, it can be used to
9434 turn off handling of signal @var{NUMBER} or revert to its default
9435 action. See @code{signal(2)}.
9437 If @code{SIGNAL} is called as a subroutine and the @var{STATUS} argument
9438 is supplied, it is set to the value returned by @code{signal(2)}.
9440 @item @emph{Standard}:
9444 Subroutine, function
9446 @item @emph{Syntax}:
9447 @multitable @columnfractions .80
9448 @item @code{CALL SIGNAL(NUMBER, HANDLER [, STATUS])}
9449 @item @code{STATUS = SIGNAL(NUMBER, HANDLER)}
9452 @item @emph{Arguments}:
9453 @multitable @columnfractions .15 .70
9454 @item @var{NUMBER} @tab Shall be a scalar integer, with @code{INTENT(IN)}
9455 @item @var{HANDLER}@tab Signal handler (@code{INTEGER FUNCTION} or
9456 @code{SUBROUTINE}) or dummy/global @code{INTEGER} scalar.
9457 @code{INTEGER}. It is @code{INTENT(IN)}.
9458 @item @var{STATUS} @tab (Optional) @var{STATUS} shall be a scalar
9459 integer. It has @code{INTENT(OUT)}.
9462 @item @emph{Return value}:
9463 The @code{SIGNAL} function returns the value returned by @code{signal(2)}.
9465 @item @emph{Example}:
9469 external handler_print
9471 call signal (12, handler_print)
9475 end program test_signal
9482 @section @code{SIN} --- Sine function
9488 @cindex trigonometric function, sine
9492 @item @emph{Description}:
9493 @code{SIN(X)} computes the sine of @var{X}.
9495 @item @emph{Standard}:
9501 @item @emph{Syntax}:
9502 @code{RESULT = SIN(X)}
9504 @item @emph{Arguments}:
9505 @multitable @columnfractions .15 .70
9506 @item @var{X} @tab The type shall be @code{REAL(*)} or
9510 @item @emph{Return value}:
9511 The return value has same type and kind as @var{X}.
9513 @item @emph{Example}:
9518 end program test_sin
9521 @item @emph{Specific names}:
9522 @multitable @columnfractions .20 .20 .20 .25
9523 @item Name @tab Argument @tab Return type @tab Standard
9524 @item @code{DSIN(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab f95, gnu
9525 @item @code{CSIN(X)} @tab @code{COMPLEX(4) X} @tab @code{COMPLEX(4)} @tab f95, gnu
9526 @item @code{ZSIN(X)} @tab @code{COMPLEX(8) X} @tab @code{COMPLEX(8)} @tab f95, gnu
9527 @item @code{CDSIN(X)} @tab @code{COMPLEX(8) X} @tab @code{COMPLEX(8)} @tab f95, gnu
9530 @item @emph{See also}:
9537 @section @code{SINH} --- Hyperbolic sine function
9540 @cindex hyperbolic sine
9541 @cindex hyperbolic function, sine
9542 @cindex sine, hyperbolic
9545 @item @emph{Description}:
9546 @code{SINH(X)} computes the hyperbolic sine of @var{X}.
9548 @item @emph{Standard}:
9554 @item @emph{Syntax}:
9555 @code{RESULT = SINH(X)}
9557 @item @emph{Arguments}:
9558 @multitable @columnfractions .15 .70
9559 @item @var{X} @tab The type shall be @code{REAL(*)}.
9562 @item @emph{Return value}:
9563 The return value is of type @code{REAL(*)}.
9565 @item @emph{Example}:
9568 real(8) :: x = - 1.0_8
9570 end program test_sinh
9573 @item @emph{Specific names}:
9574 @multitable @columnfractions .20 .20 .20 .25
9575 @item Name @tab Argument @tab Return type @tab Standard
9576 @item @code{DSINH(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab F95 and later
9579 @item @emph{See also}:
9586 @section @code{SIZE} --- Determine the size of an array
9589 @cindex array, number of elements
9590 @cindex array, count elements
9593 @item @emph{Description}:
9594 Determine the extent of @var{ARRAY} along a specified dimension @var{DIM},
9595 or the total number of elements in @var{ARRAY} if @var{DIM} is absent.
9597 @item @emph{Standard}:
9603 @item @emph{Syntax}:
9604 @code{RESULT = SIZE(ARRAY[, DIM [, KIND]])}
9606 @item @emph{Arguments}:
9607 @multitable @columnfractions .15 .70
9608 @item @var{ARRAY} @tab Shall be an array of any type. If @var{ARRAY} is
9609 a pointer it must be associated and allocatable arrays must be allocated.
9610 @item @var{DIM} @tab (Optional) shall be a scalar of type @code{INTEGER}
9611 and its value shall be in the range from 1 to n, where n equals the rank
9613 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
9614 expression indicating the kind parameter of
9618 @item @emph{Return value}:
9619 The return value is of type @code{INTEGER} and of kind @var{KIND}. If
9620 @var{KIND} is absent, the return value is of default integer kind.
9622 @item @emph{Example}:
9625 WRITE(*,*) SIZE((/ 1, 2 /)) ! 2
9629 @item @emph{See also}:
9630 @ref{SHAPE}, @ref{RESHAPE}
9635 @section @code{SIZEOF} --- Size in bytes of an expression
9637 @cindex expression size
9638 @cindex size of an expression
9641 @item @emph{Description}:
9642 @code{SIZEOF(X)} calculates the number of bytes of storage the
9643 expression @code{X} occupies.
9645 @item @emph{Standard}:
9651 @item @emph{Syntax}:
9652 @code{N = SIZEOF(X)}
9654 @item @emph{Arguments}:
9655 @multitable @columnfractions .15 .70
9656 @item @var{X} @tab The argument shall be of any type, rank or shape.
9659 @item @emph{Return value}:
9660 The return value is of type integer and of the system-dependent kind
9661 @var{C_SIZE_T} (from the @var{ISO_C_BINDING} module). Its value is the
9662 number of bytes occupied by the argument. If the argument has the
9663 @code{POINTER} attribute, the number of bytes of the storage area pointed
9664 to is returned. If the argument is of a derived type with @code{POINTER}
9665 or @code{ALLOCATABLE} components, the return value doesn't account for
9666 the sizes of the data pointed to by these components.
9668 @item @emph{Example}:
9672 print *, (sizeof(s)/sizeof(r) == 5)
9675 The example will print @code{.TRUE.} unless you are using a platform
9676 where default @code{REAL} variables are unusually padded.
9680 @section @code{SLEEP} --- Sleep for the specified number of seconds
9682 @cindex delayed execution
9685 @item @emph{Description}:
9686 Calling this subroutine causes the process to pause for @var{SECONDS} seconds.
9688 @item @emph{Standard}:
9694 @item @emph{Syntax}:
9695 @code{CALL SLEEP(SECONDS)}
9697 @item @emph{Arguments}:
9698 @multitable @columnfractions .15 .70
9699 @item @var{SECONDS} @tab The type shall be of default @code{INTEGER}.
9702 @item @emph{Example}:
9713 @section @code{SNGL} --- Convert double precision real to default real
9715 @cindex conversion, to real
9718 @item @emph{Description}:
9719 @code{SNGL(A)} converts the double precision real @var{A}
9720 to a default real value. This is an archaic form of @code{REAL}
9721 that is specific to one type for @var{A}.
9723 @item @emph{Standard}:
9729 @item @emph{Syntax}:
9730 @code{RESULT = SNGL(A)}
9732 @item @emph{Arguments}:
9733 @multitable @columnfractions .15 .70
9734 @item @var{A} @tab The type shall be a double precision @code{REAL}.
9737 @item @emph{Return value}:
9738 The return value is of type default @code{REAL}.
9740 @item @emph{See also}:
9747 @section @code{SPACING} --- Smallest distance between two numbers of a given type
9749 @cindex real number, relative spacing
9750 @cindex floating point, relative spacing
9753 @item @emph{Description}:
9754 Determines the distance between the argument @var{X} and the nearest
9755 adjacent number of the same type.
9757 @item @emph{Standard}:
9763 @item @emph{Syntax}:
9764 @code{RESULT = SPACING(X)}
9766 @item @emph{Arguments}:
9767 @multitable @columnfractions .15 .70
9768 @item @var{X} @tab Shall be of type @code{REAL(*)}.
9771 @item @emph{Return value}:
9772 The result is of the same type as the input argument @var{X}.
9774 @item @emph{Example}:
9776 PROGRAM test_spacing
9777 INTEGER, PARAMETER :: SGL = SELECTED_REAL_KIND(p=6, r=37)
9778 INTEGER, PARAMETER :: DBL = SELECTED_REAL_KIND(p=13, r=200)
9780 WRITE(*,*) spacing(1.0_SGL) ! "1.1920929E-07" on i686
9781 WRITE(*,*) spacing(1.0_DBL) ! "2.220446049250313E-016" on i686
9785 @item @emph{See also}:
9792 @section @code{SPREAD} --- Add a dimension to an array
9794 @cindex array, increase dimension
9795 @cindex array, duplicate elements
9796 @cindex array, duplicate dimensions
9799 @item @emph{Description}:
9800 Replicates a @var{SOURCE} array @var{NCOPIES} times along a specified
9801 dimension @var{DIM}.
9803 @item @emph{Standard}:
9807 Transformational function
9809 @item @emph{Syntax}:
9810 @code{RESULT = SPREAD(SOURCE, DIM, NCOPIES)}
9812 @item @emph{Arguments}:
9813 @multitable @columnfractions .15 .70
9814 @item @var{SOURCE} @tab Shall be a scalar or an array of any type and
9815 a rank less than seven.
9816 @item @var{DIM} @tab Shall be a scalar of type @code{INTEGER} with a
9817 value in the range from 1 to n+1, where n equals the rank of @var{SOURCE}.
9818 @item @var{NCOPIES} @tab Shall be a scalar of type @code{INTEGER}.
9821 @item @emph{Return value}:
9822 The result is an array of the same type as @var{SOURCE} and has rank n+1
9823 where n equals the rank of @var{SOURCE}.
9825 @item @emph{Example}:
9828 INTEGER :: a = 1, b(2) = (/ 1, 2 /)
9829 WRITE(*,*) SPREAD(A, 1, 2) ! "1 1"
9830 WRITE(*,*) SPREAD(B, 1, 2) ! "1 1 2 2"
9834 @item @emph{See also}:
9841 @section @code{SQRT} --- Square-root function
9851 @item @emph{Description}:
9852 @code{SQRT(X)} computes the square root of @var{X}.
9854 @item @emph{Standard}:
9860 @item @emph{Syntax}:
9861 @code{RESULT = SQRT(X)}
9863 @item @emph{Arguments}:
9864 @multitable @columnfractions .15 .70
9865 @item @var{X} @tab The type shall be @code{REAL(*)} or
9869 @item @emph{Return value}:
9870 The return value is of type @code{REAL(*)} or @code{COMPLEX(*)}.
9871 The kind type parameter is the same as @var{X}.
9873 @item @emph{Example}:
9876 real(8) :: x = 2.0_8
9877 complex :: z = (1.0, 2.0)
9880 end program test_sqrt
9883 @item @emph{Specific names}:
9884 @multitable @columnfractions .20 .20 .20 .25
9885 @item Name @tab Argument @tab Return type @tab Standard
9886 @item @code{DSQRT(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab F95 and later
9887 @item @code{CSQRT(X)} @tab @code{COMPLEX(4) X} @tab @code{COMPLEX(4)} @tab F95 and later
9888 @item @code{ZSQRT(X)} @tab @code{COMPLEX(8) X} @tab @code{COMPLEX(8)} @tab GNU extension
9889 @item @code{CDSQRT(X)} @tab @code{COMPLEX(8) X} @tab @code{COMPLEX(8)} @tab GNU extension
9896 @section @code{SRAND} --- Reinitialize the random number generator
9898 @cindex random number generation, seeding
9899 @cindex seeding a random number generator
9902 @item @emph{Description}:
9903 @code{SRAND} reinitializes the pseudo-random number generator
9904 called by @code{RAND} and @code{IRAND}. The new seed used by the
9905 generator is specified by the required argument @var{SEED}.
9907 @item @emph{Standard}:
9913 @item @emph{Syntax}:
9914 @code{CALL SRAND(SEED)}
9916 @item @emph{Arguments}:
9917 @multitable @columnfractions .15 .70
9918 @item @var{SEED} @tab Shall be a scalar @code{INTEGER(kind=4)}.
9921 @item @emph{Return value}:
9924 @item @emph{Example}:
9925 See @code{RAND} and @code{IRAND} for examples.
9928 The Fortran 2003 standard specifies the intrinsic @code{RANDOM_SEED} to
9929 initialize the pseudo-random numbers generator and @code{RANDOM_NUMBER}
9930 to generate pseudo-random numbers. Please note that in
9931 GNU Fortran, these two sets of intrinsics (@code{RAND},
9932 @code{IRAND} and @code{SRAND} on the one hand, @code{RANDOM_NUMBER} and
9933 @code{RANDOM_SEED} on the other hand) access two independent
9934 pseudo-random number generators.
9936 @item @emph{See also}:
9937 @ref{RAND}, @ref{RANDOM_SEED}, @ref{RANDOM_NUMBER}
9944 @section @code{STAT} --- Get file status
9946 @cindex file system, file status
9949 @item @emph{Description}:
9950 This function returns information about a file. No permissions are required on
9951 the file itself, but execute (search) permission is required on all of the
9952 directories in path that lead to the file.
9954 The elements that are obtained and stored in the array @code{BUFF}:
9955 @multitable @columnfractions .15 .70
9956 @item @code{buff(1)} @tab Device ID
9957 @item @code{buff(2)} @tab Inode number
9958 @item @code{buff(3)} @tab File mode
9959 @item @code{buff(4)} @tab Number of links
9960 @item @code{buff(5)} @tab Owner's uid
9961 @item @code{buff(6)} @tab Owner's gid
9962 @item @code{buff(7)} @tab ID of device containing directory entry for file (0 if not available)
9963 @item @code{buff(8)} @tab File size (bytes)
9964 @item @code{buff(9)} @tab Last access time
9965 @item @code{buff(10)} @tab Last modification time
9966 @item @code{buff(11)} @tab Last file status change time
9967 @item @code{buff(12)} @tab Preferred I/O block size (-1 if not available)
9968 @item @code{buff(13)} @tab Number of blocks allocated (-1 if not available)
9971 Not all these elements are relevant on all systems.
9972 If an element is not relevant, it is returned as 0.
9974 This intrinsic is provided in both subroutine and function forms; however,
9975 only one form can be used in any given program unit.
9977 @item @emph{Standard}:
9981 Subroutine, function
9983 @item @emph{Syntax}:
9984 @code{CALL STAT(FILE,BUFF[,STATUS])}
9986 @item @emph{Arguments}:
9987 @multitable @columnfractions .15 .70
9988 @item @var{FILE} @tab The type shall be @code{CHARACTER(*)}, a valid path within the file system.
9989 @item @var{BUFF} @tab The type shall be @code{INTEGER(4), DIMENSION(13)}.
9990 @item @var{STATUS} @tab (Optional) status flag of type @code{INTEGER(4)}. Returns 0
9991 on success and a system specific error code otherwise.
9994 @item @emph{Example}:
9997 INTEGER, DIMENSION(13) :: buff
10000 CALL STAT("/etc/passwd", buff, status)
10002 IF (status == 0) THEN
10003 WRITE (*, FMT="('Device ID:', T30, I19)") buff(1)
10004 WRITE (*, FMT="('Inode number:', T30, I19)") buff(2)
10005 WRITE (*, FMT="('File mode (octal):', T30, O19)") buff(3)
10006 WRITE (*, FMT="('Number of links:', T30, I19)") buff(4)
10007 WRITE (*, FMT="('Owner''s uid:', T30, I19)") buff(5)
10008 WRITE (*, FMT="('Owner''s gid:', T30, I19)") buff(6)
10009 WRITE (*, FMT="('Device where located:', T30, I19)") buff(7)
10010 WRITE (*, FMT="('File size:', T30, I19)") buff(8)
10011 WRITE (*, FMT="('Last access time:', T30, A19)") CTIME(buff(9))
10012 WRITE (*, FMT="('Last modification time', T30, A19)") CTIME(buff(10))
10013 WRITE (*, FMT="('Last status change time:', T30, A19)") CTIME(buff(11))
10014 WRITE (*, FMT="('Preferred block size:', T30, I19)") buff(12)
10015 WRITE (*, FMT="('No. of blocks allocated:', T30, I19)") buff(13)
10020 @item @emph{See also}:
10021 To stat an open file: @ref{FSTAT}, to stat a link: @ref{LSTAT}
10027 @section @code{SUM} --- Sum of array elements
10030 @cindex array, add elements
10031 @cindex array, conditionally add elements
10032 @cindex sum array elements
10035 @item @emph{Description}:
10036 Adds the elements of @var{ARRAY} along dimension @var{DIM} if
10037 the corresponding element in @var{MASK} is @code{TRUE}.
10039 @item @emph{Standard}:
10042 @item @emph{Class}:
10043 Transformational function
10045 @item @emph{Syntax}:
10046 @code{RESULT = SUM(ARRAY[, MASK])}
10047 @code{RESULT = SUM(ARRAY, DIM[, MASK])}
10049 @item @emph{Arguments}:
10050 @multitable @columnfractions .15 .70
10051 @item @var{ARRAY} @tab Shall be an array of type @code{INTEGER(*)},
10052 @code{REAL(*)} or @code{COMPLEX(*)}.
10053 @item @var{DIM} @tab (Optional) shall be a scalar of type
10054 @code{INTEGER} with a value in the range from 1 to n, where n
10055 equals the rank of @var{ARRAY}.
10056 @item @var{MASK} @tab (Optional) shall be of type @code{LOGICAL}
10057 and either be a scalar or an array of the same shape as @var{ARRAY}.
10060 @item @emph{Return value}:
10061 The result is of the same type as @var{ARRAY}.
10063 If @var{DIM} is absent, a scalar with the sum of all elements in @var{ARRAY}
10064 is returned. Otherwise, an array of rank n-1, where n equals the rank of
10065 @var{ARRAY},and a shape similar to that of @var{ARRAY} with dimension @var{DIM}
10066 dropped is returned.
10068 @item @emph{Example}:
10071 INTEGER :: x(5) = (/ 1, 2, 3, 4 ,5 /)
10072 print *, SUM(x) ! all elements, sum = 15
10073 print *, SUM(x, MASK=MOD(x, 2)==1) ! odd elements, sum = 9
10077 @item @emph{See also}:
10084 @section @code{SYMLNK} --- Create a symbolic link
10086 @cindex file system, create link
10087 @cindex file system, soft link
10090 @item @emph{Description}:
10091 Makes a symbolic link from file @var{PATH1} to @var{PATH2}. A null
10092 character (@code{CHAR(0)}) can be used to mark the end of the names in
10093 @var{PATH1} and @var{PATH2}; otherwise, trailing blanks in the file
10094 names are ignored. If the @var{STATUS} argument is supplied, it
10095 contains 0 on success or a nonzero error code upon return; see
10096 @code{symlink(2)}. If the system does not supply @code{symlink(2)},
10097 @code{ENOSYS} is returned.
10099 This intrinsic is provided in both subroutine and function forms;
10100 however, only one form can be used in any given program unit.
10102 @item @emph{Standard}:
10105 @item @emph{Class}:
10106 Subroutine, function
10108 @item @emph{Syntax}:
10109 @multitable @columnfractions .80
10110 @item @code{CALL SYMLNK(PATH1, PATH2 [, STATUS])}
10111 @item @code{STATUS = SYMLNK(PATH1, PATH2)}
10114 @item @emph{Arguments}:
10115 @multitable @columnfractions .15 .70
10116 @item @var{PATH1} @tab Shall be of default @code{CHARACTER} type.
10117 @item @var{PATH2} @tab Shall be of default @code{CHARACTER} type.
10118 @item @var{STATUS} @tab (Optional) Shall be of default @code{INTEGER} type.
10121 @item @emph{See also}:
10122 @ref{LINK}, @ref{UNLINK}
10129 @section @code{SYSTEM} --- Execute a shell command
10131 @cindex system, system call
10134 @item @emph{Description}:
10135 Passes the command @var{COMMAND} to a shell (see @code{system(3)}). If
10136 argument @var{STATUS} is present, it contains the value returned by
10137 @code{system(3)}, which is presumably 0 if the shell command succeeded.
10138 Note that which shell is used to invoke the command is system-dependent
10139 and environment-dependent.
10141 This intrinsic is provided in both subroutine and function forms;
10142 however, only one form can be used in any given program unit.
10144 @item @emph{Standard}:
10147 @item @emph{Class}:
10148 Subroutine, function
10150 @item @emph{Syntax}:
10151 @multitable @columnfractions .80
10152 @item @code{CALL SYSTEM(COMMAND [, STATUS])}
10153 @item @code{STATUS = SYSTEM(COMMAND)}
10156 @item @emph{Arguments}:
10157 @multitable @columnfractions .15 .70
10158 @item @var{COMMAND} @tab Shall be of default @code{CHARACTER} type.
10159 @item @var{STATUS} @tab (Optional) Shall be of default @code{INTEGER} type.
10162 @item @emph{See also}:
10168 @section @code{SYSTEM_CLOCK} --- Time function
10169 @fnindex SYSTEM_CLOCK
10170 @cindex time, clock ticks
10171 @cindex clock ticks
10174 @item @emph{Description}:
10175 Determines the @var{COUNT} of milliseconds of wall clock time since
10176 the Epoch (00:00:00 UTC, January 1, 1970) modulo @var{COUNT_MAX},
10177 @var{COUNT_RATE} determines the number of clock ticks per second.
10178 @var{COUNT_RATE} and @var{COUNT_MAX} are constant and specific to
10179 @command{gfortran}.
10181 If there is no clock, @var{COUNT} is set to @code{-HUGE(COUNT)}, and
10182 @var{COUNT_RATE} and @var{COUNT_MAX} are set to zero
10184 @item @emph{Standard}:
10187 @item @emph{Class}:
10190 @item @emph{Syntax}:
10191 @code{CALL SYSTEM_CLOCK([COUNT, COUNT_RATE, COUNT_MAX])}
10193 @item @emph{Arguments}:
10194 @item @emph{Arguments}:
10195 @multitable @columnfractions .15 .70
10196 @item @var{COUNT} @tab (Optional) shall be a scalar of type default
10197 @code{INTEGER} with @code{INTENT(OUT)}.
10198 @item @var{COUNT_RATE} @tab (Optional) shall be a scalar of type default
10199 @code{INTEGER} with @code{INTENT(OUT)}.
10200 @item @var{COUNT_MAX} @tab (Optional) shall be a scalar of type default
10201 @code{INTEGER} with @code{INTENT(OUT)}.
10204 @item @emph{Example}:
10206 PROGRAM test_system_clock
10207 INTEGER :: count, count_rate, count_max
10208 CALL SYSTEM_CLOCK(count, count_rate, count_max)
10209 WRITE(*,*) count, count_rate, count_max
10213 @item @emph{See also}:
10214 @ref{DATE_AND_TIME}, @ref{CPU_TIME}
10220 @section @code{TAN} --- Tangent function
10223 @cindex trigonometric function, tangent
10227 @item @emph{Description}:
10228 @code{TAN(X)} computes the tangent of @var{X}.
10230 @item @emph{Standard}:
10233 @item @emph{Class}:
10236 @item @emph{Syntax}:
10237 @code{RESULT = TAN(X)}
10239 @item @emph{Arguments}:
10240 @multitable @columnfractions .15 .70
10241 @item @var{X} @tab The type shall be @code{REAL(*)}.
10244 @item @emph{Return value}:
10245 The return value is of type @code{REAL(*)}. The kind type parameter is
10246 the same as @var{X}.
10248 @item @emph{Example}:
10251 real(8) :: x = 0.165_8
10253 end program test_tan
10256 @item @emph{Specific names}:
10257 @multitable @columnfractions .20 .20 .20 .25
10258 @item Name @tab Argument @tab Return type @tab Standard
10259 @item @code{DTAN(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab F95 and later
10262 @item @emph{See also}:
10269 @section @code{TANH} --- Hyperbolic tangent function
10272 @cindex hyperbolic tangent
10273 @cindex hyperbolic function, tangent
10274 @cindex tangent, hyperbolic
10277 @item @emph{Description}:
10278 @code{TANH(X)} computes the hyperbolic tangent of @var{X}.
10280 @item @emph{Standard}:
10283 @item @emph{Class}:
10286 @item @emph{Syntax}:
10289 @item @emph{Arguments}:
10290 @multitable @columnfractions .15 .70
10291 @item @var{X} @tab The type shall be @code{REAL(*)}.
10294 @item @emph{Return value}:
10295 The return value is of type @code{REAL(*)} and lies in the range
10296 @math{ - 1 \leq tanh(x) \leq 1 }.
10298 @item @emph{Example}:
10301 real(8) :: x = 2.1_8
10303 end program test_tanh
10306 @item @emph{Specific names}:
10307 @multitable @columnfractions .20 .20 .20 .25
10308 @item Name @tab Argument @tab Return type @tab Standard
10309 @item @code{DTANH(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab F95 and later
10312 @item @emph{See also}:
10319 @section @code{TIME} --- Time function
10321 @cindex time, current
10322 @cindex current time
10325 @item @emph{Description}:
10326 Returns the current time encoded as an integer (in the manner of the
10327 UNIX function @code{time(3)}). This value is suitable for passing to
10328 @code{CTIME()}, @code{GMTIME()}, and @code{LTIME()}.
10330 This intrinsic is not fully portable, such as to systems with 32-bit
10331 @code{INTEGER} types but supporting times wider than 32 bits. Therefore,
10332 the values returned by this intrinsic might be, or become, negative, or
10333 numerically less than previous values, during a single run of the
10336 See @ref{TIME8}, for information on a similar intrinsic that might be
10337 portable to more GNU Fortran implementations, though to fewer Fortran
10340 @item @emph{Standard}:
10343 @item @emph{Class}:
10346 @item @emph{Syntax}:
10347 @code{RESULT = TIME()}
10349 @item @emph{Return value}:
10350 The return value is a scalar of type @code{INTEGER(4)}.
10352 @item @emph{See also}:
10353 @ref{CTIME}, @ref{GMTIME}, @ref{LTIME}, @ref{MCLOCK}, @ref{TIME8}
10360 @section @code{TIME8} --- Time function (64-bit)
10362 @cindex time, current
10363 @cindex current time
10366 @item @emph{Description}:
10367 Returns the current time encoded as an integer (in the manner of the
10368 UNIX function @code{time(3)}). This value is suitable for passing to
10369 @code{CTIME()}, @code{GMTIME()}, and @code{LTIME()}.
10371 @emph{Warning:} this intrinsic does not increase the range of the timing
10372 values over that returned by @code{time(3)}. On a system with a 32-bit
10373 @code{time(3)}, @code{TIME8()} will return a 32-bit value, even though
10374 it is converted to a 64-bit @code{INTEGER(8)} value. That means
10375 overflows of the 32-bit value can still occur. Therefore, the values
10376 returned by this intrinsic might be or become negative or numerically
10377 less than previous values during a single run of the compiled program.
10379 @item @emph{Standard}:
10382 @item @emph{Class}:
10385 @item @emph{Syntax}:
10386 @code{RESULT = TIME8()}
10388 @item @emph{Return value}:
10389 The return value is a scalar of type @code{INTEGER(8)}.
10391 @item @emph{See also}:
10392 @ref{CTIME}, @ref{GMTIME}, @ref{LTIME}, @ref{MCLOCK8}, @ref{TIME}
10399 @section @code{TINY} --- Smallest positive number of a real kind
10401 @cindex limits, smallest number
10402 @cindex model representation, smallest number
10405 @item @emph{Description}:
10406 @code{TINY(X)} returns the smallest positive (non zero) number
10407 in the model of the type of @code{X}.
10409 @item @emph{Standard}:
10412 @item @emph{Class}:
10415 @item @emph{Syntax}:
10416 @code{RESULT = TINY(X)}
10418 @item @emph{Arguments}:
10419 @multitable @columnfractions .15 .70
10420 @item @var{X} @tab Shall be of type @code{REAL}.
10423 @item @emph{Return value}:
10424 The return value is of the same type and kind as @var{X}
10426 @item @emph{Example}:
10427 See @code{HUGE} for an example.
10433 @section @code{TRANSFER} --- Transfer bit patterns
10439 @item @emph{Description}:
10440 Interprets the bitwise representation of @var{SOURCE} in memory as if it
10441 is the representation of a variable or array of the same type and type
10442 parameters as @var{MOLD}.
10444 This is approximately equivalent to the C concept of @emph{casting} one
10447 @item @emph{Standard}:
10450 @item @emph{Class}:
10451 Transformational function
10453 @item @emph{Syntax}:
10454 @code{RESULT = TRANSFER(SOURCE, MOLD[, SIZE])}
10456 @item @emph{Arguments}:
10457 @multitable @columnfractions .15 .70
10458 @item @var{SOURCE} @tab Shall be a scalar or an array of any type.
10459 @item @var{MOLD} @tab Shall be a scalar or an array of any type.
10460 @item @var{SIZE} @tab (Optional) shall be a scalar of type
10464 @item @emph{Return value}:
10465 The result has the same type as @var{MOLD}, with the bit level
10466 representation of @var{SOURCE}. If @var{SIZE} is present, the result is
10467 a one-dimensional array of length @var{SIZE}. If @var{SIZE} is absent
10468 but @var{MOLD} is an array (of any size or shape), the result is a one-
10469 dimensional array of the minimum length needed to contain the entirety
10470 of the bitwise representation of @var{SOURCE}. If @var{SIZE} is absent
10471 and @var{MOLD} is a scalar, the result is a scalar.
10473 If the bitwise representation of the result is longer than that of
10474 @var{SOURCE}, then the leading bits of the result correspond to those of
10475 @var{SOURCE} and any trailing bits are filled arbitrarily.
10477 When the resulting bit representation does not correspond to a valid
10478 representation of a variable of the same type as @var{MOLD}, the results
10479 are undefined, and subsequent operations on the result cannot be
10480 guaranteed to produce sensible behavior. For example, it is possible to
10481 create @code{LOGICAL} variables for which @code{@var{VAR}} and
10482 @code{.NOT.@var{VAR}} both appear to be true.
10484 @item @emph{Example}:
10486 PROGRAM test_transfer
10487 integer :: x = 2143289344
10488 print *, transfer(x, 1.0) ! prints "NaN" on i686
10496 @section @code{TRANSPOSE} --- Transpose an array of rank two
10498 @cindex array, transpose
10499 @cindex matrix, transpose
10503 @item @emph{Description}:
10504 Transpose an array of rank two. Element (i, j) of the result has the value
10505 @code{MATRIX(j, i)}, for all i, j.
10507 @item @emph{Standard}:
10510 @item @emph{Class}:
10511 Transformational function
10513 @item @emph{Syntax}:
10514 @code{RESULT = TRANSPOSE(MATRIX)}
10516 @item @emph{Arguments}:
10517 @multitable @columnfractions .15 .70
10518 @item @var{MATRIX} @tab Shall be an array of any type and have a rank of two.
10521 @item @emph{Return value}:
10522 The result has the the same type as @var{MATRIX}, and has shape
10523 @code{(/ m, n /)} if @var{MATRIX} has shape @code{(/ n, m /)}.
10529 @section @code{TRIM} --- Remove trailing blank characters of a string
10531 @cindex string, remove trailing whitespace
10534 @item @emph{Description}:
10535 Removes trailing blank characters of a string.
10537 @item @emph{Standard}:
10540 @item @emph{Class}:
10541 Transformational function
10543 @item @emph{Syntax}:
10544 @code{RESULT = TRIM(STRING)}
10546 @item @emph{Arguments}:
10547 @multitable @columnfractions .15 .70
10548 @item @var{STRING} @tab Shall be a scalar of type @code{CHARACTER(*)}.
10551 @item @emph{Return value}:
10552 A scalar of type @code{CHARACTER(*)} which length is that of @var{STRING}
10553 less the number of trailing blanks.
10555 @item @emph{Example}:
10558 CHARACTER(len=10), PARAMETER :: s = "GFORTRAN "
10559 WRITE(*,*) LEN(s), LEN(TRIM(s)) ! "10 8", with/without trailing blanks
10563 @item @emph{See also}:
10564 @ref{ADJUSTL}, @ref{ADJUSTR}
10570 @section @code{TTYNAM} --- Get the name of a terminal device.
10572 @cindex system, terminal
10575 @item @emph{Description}:
10576 Get the name of a terminal device. For more information,
10577 see @code{ttyname(3)}.
10579 This intrinsic is provided in both subroutine and function forms;
10580 however, only one form can be used in any given program unit.
10582 @item @emph{Standard}:
10585 @item @emph{Class}:
10586 Subroutine, function
10588 @item @emph{Syntax}:
10589 @multitable @columnfractions .80
10590 @item @code{CALL TTYNAM(UNIT, NAME)}
10591 @item @code{NAME = TTYNAM(UNIT)}
10594 @item @emph{Arguments}:
10595 @multitable @columnfractions .15 .70
10596 @item @var{UNIT} @tab Shall be a scalar @code{INTEGER(*)}.
10597 @item @var{NAME} @tab Shall be of type @code{CHARACTER(*)}.
10600 @item @emph{Example}:
10602 PROGRAM test_ttynam
10605 IF (isatty(unit=unit)) write(*,*) ttynam(unit)
10610 @item @emph{See also}:
10617 @section @code{UBOUND} --- Upper dimension bounds of an array
10619 @cindex array, upper bound
10622 @item @emph{Description}:
10623 Returns the upper bounds of an array, or a single upper bound
10624 along the @var{DIM} dimension.
10625 @item @emph{Standard}:
10628 @item @emph{Class}:
10631 @item @emph{Syntax}:
10632 @code{RESULT = UBOUND(ARRAY [, DIM [, KIND]])}
10634 @item @emph{Arguments}:
10635 @multitable @columnfractions .15 .70
10636 @item @var{ARRAY} @tab Shall be an array, of any type.
10637 @item @var{DIM} @tab (Optional) Shall be a scalar @code{INTEGER(*)}.
10638 @item @var{KIND}@tab (Optional) An @code{INTEGER} initialization
10639 expression indicating the kind parameter of
10643 @item @emph{Return value}:
10644 The return value is of type @code{INTEGER} and of kind @var{KIND}. If
10645 @var{KIND} is absent, the return value is of default integer kind.
10646 If @var{DIM} is absent, the result is an array of the upper bounds of
10647 @var{ARRAY}. If @var{DIM} is present, the result is a scalar
10648 corresponding to the upper bound of the array along that dimension. If
10649 @var{ARRAY} is an expression rather than a whole array or array
10650 structure component, or if it has a zero extent along the relevant
10651 dimension, the upper bound is taken to be the number of elements along
10652 the relevant dimension.
10654 @item @emph{See also}:
10661 @section @code{UMASK} --- Set the file creation mask
10663 @cindex file system, file creation mask
10666 @item @emph{Description}:
10667 Sets the file creation mask to @var{MASK} and returns the old value in
10668 argument @var{OLD} if it is supplied. See @code{umask(2)}.
10670 @item @emph{Standard}:
10673 @item @emph{Class}:
10676 @item @emph{Syntax}:
10677 @code{CALL UMASK(MASK [, OLD])}
10679 @item @emph{Arguments}:
10680 @multitable @columnfractions .15 .70
10681 @item @var{MASK} @tab Shall be a scalar of type @code{INTEGER(*)}.
10682 @item @var{MASK} @tab (Optional) Shall be a scalar of type
10691 @section @code{UNLINK} --- Remove a file from the file system
10693 @cindex file system, remove file
10696 @item @emph{Description}:
10697 Unlinks the file @var{PATH}. A null character (@code{CHAR(0)}) can be
10698 used to mark the end of the name in @var{PATH}; otherwise, trailing
10699 blanks in the file name are ignored. If the @var{STATUS} argument is
10700 supplied, it contains 0 on success or a nonzero error code upon return;
10701 see @code{unlink(2)}.
10703 This intrinsic is provided in both subroutine and function forms;
10704 however, only one form can be used in any given program unit.
10706 @item @emph{Standard}:
10709 @item @emph{Class}:
10710 Subroutine, function
10712 @item @emph{Syntax}:
10713 @multitable @columnfractions .80
10714 @item @code{CALL UNLINK(PATH [, STATUS])}
10715 @item @code{STATUS = UNLINK(PATH)}
10718 @item @emph{Arguments}:
10719 @multitable @columnfractions .15 .70
10720 @item @var{PATH} @tab Shall be of default @code{CHARACTER} type.
10721 @item @var{STATUS} @tab (Optional) Shall be of default @code{INTEGER} type.
10724 @item @emph{See also}:
10725 @ref{LINK}, @ref{SYMLNK}
10731 @section @code{UNPACK} --- Unpack an array of rank one into an array
10733 @cindex array, unpacking
10734 @cindex array, increase dimension
10735 @cindex array, scatter elements
10738 @item @emph{Description}:
10739 Store the elements of @var{VECTOR} in an array of higher rank.
10741 @item @emph{Standard}:
10744 @item @emph{Class}:
10745 Transformational function
10747 @item @emph{Syntax}:
10748 @code{RESULT = UNPACK(VECTOR, MASK, FIELD)}
10750 @item @emph{Arguments}:
10751 @multitable @columnfractions .15 .70
10752 @item @var{VECTOR} @tab Shall be an array of any type and rank one. It
10753 shall have at least as many elements as @var{MASK} has @code{TRUE} values.
10754 @item @var{MASK} @tab Shall be an array of type @code{LOGICAL}.
10755 @item @var{FIELD} @tab Shall be of the sam type as @var{VECTOR} and have
10756 the same shape as @var{MASK}.
10759 @item @emph{Return value}:
10760 The resulting array corresponds to @var{FIELD} with @code{TRUE} elements
10761 of @var{MASK} replaced by values from @var{VECTOR} in array element order.
10763 @item @emph{Example}:
10765 PROGRAM test_unpack
10766 integer :: vector(2) = (/1,1/)
10767 logical :: mask(4) = (/ .TRUE., .FALSE., .FALSE., .TRUE. /)
10768 integer :: field(2,2) = 0, unity(2,2)
10770 ! result: unity matrix
10771 unity = unpack(vector, reshape(mask, (/2,2/)), field)
10775 @item @emph{See also}:
10776 @ref{PACK}, @ref{SPREAD}
10782 @section @code{VERIFY} --- Scan a string for the absence of a set of characters
10784 @cindex string, find missing set
10787 @item @emph{Description}:
10788 Verifies that all the characters in a @var{SET} are present in a @var{STRING}.
10790 If @var{BACK} is either absent or equals @code{FALSE}, this function
10791 returns the position of the leftmost character of @var{STRING} that is
10792 not in @var{SET}. If @var{BACK} equals @code{TRUE}, the rightmost position
10793 is returned. If all characters of @var{SET} are found in @var{STRING}, the
10796 @item @emph{Standard}:
10799 @item @emph{Class}:
10802 @item @emph{Syntax}:
10803 @code{RESULT = VERIFY(STRING, SET[, BACK [, KIND]])}
10805 @item @emph{Arguments}:
10806 @multitable @columnfractions .15 .70
10807 @item @var{STRING} @tab Shall be of type @code{CHARACTER(*)}.
10808 @item @var{SET} @tab Shall be of type @code{CHARACTER(*)}.
10809 @item @var{BACK} @tab (Optional) shall be of type @code{LOGICAL}.
10810 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
10811 expression indicating the kind parameter of
10815 @item @emph{Return value}:
10816 The return value is of type @code{INTEGER} and of kind @var{KIND}. If
10817 @var{KIND} is absent, the return value is of default integer kind.
10819 @item @emph{Example}:
10821 PROGRAM test_verify
10822 WRITE(*,*) VERIFY("FORTRAN", "AO") ! 1, found 'F'
10823 WRITE(*,*) VERIFY("FORTRAN", "FOO") ! 3, found 'R'
10824 WRITE(*,*) VERIFY("FORTRAN", "C++") ! 1, found 'F'
10825 WRITE(*,*) VERIFY("FORTRAN", "C++", .TRUE.) ! 7, found 'N'
10826 WRITE(*,*) VERIFY("FORTRAN", "FORTRAN") ! 0' found none
10830 @item @emph{See also}:
10831 @ref{SCAN}, @ref{INDEX intrinsic}
10837 @section @code{XOR} --- Bitwise logical exclusive OR
10839 @cindex bitwise logical exclusive or
10840 @cindex logical exclusive or, bitwise
10843 @item @emph{Description}:
10844 Bitwise logical exclusive or.
10846 This intrinsic routine is provided for backwards compatibility with
10847 GNU Fortran 77. For integer arguments, programmers should consider
10848 the use of the @ref{IEOR} intrinsic defined by the Fortran standard.
10850 @item @emph{Standard}:
10853 @item @emph{Class}:
10856 @item @emph{Syntax}:
10857 @code{RESULT = XOR(X, Y)}
10859 @item @emph{Arguments}:
10860 @multitable @columnfractions .15 .70
10861 @item @var{X} @tab The type shall be either @code{INTEGER(*)} or @code{LOGICAL}.
10862 @item @var{Y} @tab The type shall be either @code{INTEGER(*)} or @code{LOGICAL}.
10865 @item @emph{Return value}:
10866 The return type is either @code{INTEGER(*)} or @code{LOGICAL}
10867 after cross-promotion of the arguments.
10869 @item @emph{Example}:
10872 LOGICAL :: T = .TRUE., F = .FALSE.
10874 DATA a / Z'F' /, b / Z'3' /
10876 WRITE (*,*) XOR(T, T), XOR(T, F), XOR(F, T), XOR(F, F)
10877 WRITE (*,*) XOR(a, b)
10881 @item @emph{See also}:
10882 F95 elemental function: @ref{IEOR}
10887 @node Intrinsic Modules
10888 @chapter Intrinsic Modules
10889 @cindex intrinsic Modules
10891 @c @node ISO_FORTRAN_ENV
10892 @section @code{ISO_FORTRAN_ENV}
10894 @item @emph{Standard}:
10898 The @code{ISO_FORTRAN_ENV} module provides the following scalar default-integer
10902 @item @code{CHARACTER_STORAGE_SIZE}:
10903 Size in bits of the character storage unit.
10905 @item @code{ERROR_UNIT}:
10906 Indentifies the preconnected unit used for error reporting.
10908 @item @code{FILE_STORAGE_SIZE}:
10909 Size in bits of the file-storage unit.
10911 @item @code{INPUT_UNIT}:
10912 Indentifies the preconnected unit indentified by the asterisk
10913 (@code{*}) in @code{READ} statement.
10915 @item @code{IOSTAT_END}:
10916 The value assigned to the variable passed to the IOSTAT= specifier of
10917 an input/output statement if an end-of-file condition occurred.
10919 @item @code{IOSTAT_EOR}:
10920 The value assigned to the variable passed to the IOSTAT= specifier of
10921 an input/output statement if an end-of-record condition occurred.
10923 @item @code{NUMERIC_STORAGE_SIZE}:
10924 The size in bits of the numeric storage unit.
10926 @item @code{OUTPUT_UNIT}:
10927 Indentifies the preconnected unit indentified by the asterisk
10928 (@code{*}) in @code{WRITE} statement.
10931 @c @node ISO_C_BINDING
10932 @section @code{ISO_C_BINDING}
10934 @item @emph{Standard}:
10938 The following intrinsic procedures are provided by the module; their
10939 definition can be found in the section Intrinsic Procedures of this
10943 @item @code{C_ASSOCIATED}
10944 @item @code{C_F_POINTER}
10945 @item @code{C_F_PROCPOINTER}
10946 @item @code{C_FUNLOC}
10950 The @code{ISO_C_BINDING} module provides the following named constants of the
10951 type integer, which can be used as KIND type parameter. Note that GNU
10952 Fortran currently does not support the @code{C_INT_FAST...} KIND type
10953 parameters (marked by an asterix (@code{*}) in the list below).
10954 The @code{C_INT_FAST...} parameters have therefore the value @math{-2}
10955 and cannot be used as KIND type parameter of the @code{INTEGER} type.
10957 @multitable @columnfractions .15 .35 .35
10958 @item Fortran Type @tab Named constant @tab C type
10959 @item @code{INTEGER}@tab @code{C_INT} @tab @code{int}
10960 @item @code{INTEGER}@tab @code{C_SHORT} @tab @code{short int}
10961 @item @code{INTEGER}@tab @code{C_LONG} @tab @code{long int}
10962 @item @code{INTEGER}@tab @code{C_LONG_LONG} @tab @code{long long int}
10963 @item @code{INTEGER}@tab @code{C_SIGNED_CHAR} @tab @code{signed char}/@code{unsigned char}
10964 @item @code{INTEGER}@tab @code{C_SIZE_T} @tab @code{size_t}
10965 @item @code{INTEGER}@tab @code{C_INT8_T} @tab @code{int8_t}
10966 @item @code{INTEGER}@tab @code{C_INT16_T} @tab @code{int16_t}
10967 @item @code{INTEGER}@tab @code{C_INT32_T} @tab @code{int32_t}
10968 @item @code{INTEGER}@tab @code{C_INT64_T} @tab @code{int64_t}
10969 @item @code{INTEGER}@tab @code{C_INT_LEAST8_T} @tab @code{int_least8_t}
10970 @item @code{INTEGER}@tab @code{C_INT_LEAST16_T} @tab @code{int_least16_t}
10971 @item @code{INTEGER}@tab @code{C_INT_LEAST32_T} @tab @code{int_least32_t}
10972 @item @code{INTEGER}@tab @code{C_INT_LEAST64_T} @tab @code{int_least64_t}
10973 @item @code{INTEGER}@tab @code{C_INT_FAST8_T}* @tab @code{int_fast8_t}
10974 @item @code{INTEGER}@tab @code{C_INT_FAST16_T}* @tab @code{int_fast16_t}
10975 @item @code{INTEGER}@tab @code{C_INT_FAST32_T}* @tab @code{int_fast32_t}
10976 @item @code{INTEGER}@tab @code{C_INT_FAST64_T}* @tab @code{int_fast64_t}
10977 @item @code{INTEGER}@tab @code{C_INTMAX_T} @tab @code{intmax_t}
10978 @item @code{INTEGER}@tab @code{C_INTPTR_T} @tab @code{intptr_t}
10979 @item @code{REAL} @tab @code{C_FLOAT} @tab @code{float}
10980 @item @code{REAL} @tab @code{C_DOUBLE} @tab @code{double}
10981 @item @code{REAL} @tab @code{C_LONG_DOUBLE} @tab @code{long double}
10982 @item @code{COMPLEX}@tab @code{C_FLOAT_COMPLEX} @tab @code{float _Complex}
10983 @item @code{COMPLEX}@tab @code{C_DOUBLE_COMPLEX}@tab @code{double _Complex}
10984 @item @code{COMPLEX}@tab @code{C_LONG_DOUBLE_COMPLEX}@tab @code{long double _Complex}
10985 @item @code{LOGICAL}@tab @code{C_BOOL} @tab @code{_Bool}
10986 @item @code{CHARACTER}@tab @code{C_CHAR} @tab @code{char}
10989 Additionally, the following @code{(CHARACTER(KIND=C_CHAR)} are
10992 @multitable @columnfractions .20 .45 .15
10993 @item Name @tab C definition @tab Value
10994 @item @code{C_NULL_CHAR} @tab null character @tab @code{'\0'}
10995 @item @code{C_ALERT} @tab alert @tab @code{'\a'}
10996 @item @code{C_BACKSPACE} @tab backspace @tab @code{'\b'}
10997 @item @code{C_FORM_FEED} @tab form feed @tab @code{'\f'}
10998 @item @code{C_NEW_LINE} @tab new line @tab @code{'\n'}
10999 @item @code{C_CARRIAGE_RETURN} @tab carriage return @tab @code{'\r'}
11000 @item @code{C_HORIZONTAL_TAB} @tab horizontal tab @tab @code{'\t'}
11001 @item @code{C_VERTICAL_TAB} @tab vertical tab @tab @code{'\v'}
11004 @c @node OpenMP Modules OMP_LIB and OMP_LIB_KINDS
11005 @section OpenMP Modules @code{OMP_LIB} and @code{OMP_LIB_KINDS}
11007 @item @emph{Standard}:
11008 OpenMP Application Program Interface v2.5
11012 The OpenMP Fortran runtime library routines are provided both in
11013 a form of two Fortran 90 modules, named @code{OMP_LIB} and
11014 @code{OMP_LIB_KINDS}, and in a form of a Fortran @code{include} file named
11015 @file{omp_lib.h}. The procedures provided by @code{OMP_LIB} can be found
11016 in the @ref{Top,,Introduction,libgomp,GNU OpenMP runtime library} manual,
11017 the named constants defined in the @code{OMP_LIB_KINDS} module are listed
11020 For details refer to the actual
11021 @uref{http://www.openmp.org/drupal/mp-documents/spec25.pdf,
11022 OpenMP Application Program Interface v2.5}.
11024 @code{OMP_LIB_KINDS} provides the following scalar default-integer
11028 @item @code{omp_integer_kind}
11029 @item @code{omp_logical_kind}
11030 @item @code{omp_lock_kind}
11031 @item @code{omp_nest_lock_kind}