2 Copyright (C) 2005, 2006, 2007, 2008
3 Free Software Foundation, Inc.
4 This is part of the GNU Fortran manual.
5 For copying conditions, see the file gfortran.texi.
7 Permission is granted to copy, distribute and/or modify this document
8 under the terms of the GNU Free Documentation License, Version 1.2 or
9 any later version published by the Free Software Foundation; with the
10 Invariant Sections being ``GNU General Public License'' and ``Funding
11 Free Software'', the Front-Cover texts being (a) (see below), and with
12 the Back-Cover Texts being (b) (see below). A copy of the license is
13 included in the gfdl(7) man page.
16 Some basic guidelines for editing this document:
18 (1) The intrinsic procedures are to be listed in alphabetical order.
19 (2) The generic name is to be used.
20 (3) The specific names are included in the function index and in a
21 table at the end of the node (See ABS entry).
22 (4) Try to maintain the same style for each entry.
28 \gdef\acos{\mathop{\rm acos}\nolimits}
29 \gdef\asin{\mathop{\rm asin}\nolimits}
30 \gdef\atan{\mathop{\rm atan}\nolimits}
31 \gdef\acosh{\mathop{\rm acosh}\nolimits}
32 \gdef\asinh{\mathop{\rm asinh}\nolimits}
33 \gdef\atanh{\mathop{\rm atanh}\nolimits}
37 @node Intrinsic Procedures
38 @chapter Intrinsic Procedures
39 @cindex intrinsic procedures
42 * Introduction: Introduction to Intrinsics
43 * @code{ABORT}: ABORT, Abort the program
44 * @code{ABS}: ABS, Absolute value
45 * @code{ACCESS}: ACCESS, Checks file access modes
46 * @code{ACHAR}: ACHAR, Character in @acronym{ASCII} collating sequence
47 * @code{ACOS}: ACOS, Arccosine function
48 * @code{ACOSH}: ACOSH, Hyperbolic arccosine function
49 * @code{ADJUSTL}: ADJUSTL, Left adjust a string
50 * @code{ADJUSTR}: ADJUSTR, Right adjust a string
51 * @code{AIMAG}: AIMAG, Imaginary part of complex number
52 * @code{AINT}: AINT, Truncate to a whole number
53 * @code{ALARM}: ALARM, Set an alarm clock
54 * @code{ALL}: ALL, Determine if all values are true
55 * @code{ALLOCATED}: ALLOCATED, Status of allocatable entity
56 * @code{AND}: AND, Bitwise logical AND
57 * @code{ANINT}: ANINT, Nearest whole number
58 * @code{ANY}: ANY, Determine if any values are true
59 * @code{ASIN}: ASIN, Arcsine function
60 * @code{ASINH}: ASINH, Hyperbolic arcsine function
61 * @code{ASSOCIATED}: ASSOCIATED, Status of a pointer or pointer/target pair
62 * @code{ATAN}: ATAN, Arctangent function
63 * @code{ATAN2}: ATAN2, Arctangent function
64 * @code{ATANH}: ATANH, Hyperbolic arctangent function
65 * @code{BESSEL_J0}: BESSEL_J0, Bessel function of the first kind of order 0
66 * @code{BESSEL_J1}: BESSEL_J1, Bessel function of the first kind of order 1
67 * @code{BESSEL_JN}: BESSEL_JN, Bessel function of the first kind
68 * @code{BESSEL_Y0}: BESSEL_Y0, Bessel function of the second kind of order 0
69 * @code{BESSEL_Y1}: BESSEL_Y1, Bessel function of the second kind of order 1
70 * @code{BESSEL_YN}: BESSEL_YN, Bessel function of the second kind
71 * @code{BIT_SIZE}: BIT_SIZE, Bit size inquiry function
72 * @code{BTEST}: BTEST, Bit test function
73 * @code{C_ASSOCIATED}: C_ASSOCIATED, Status of a C pointer
74 * @code{C_F_POINTER}: C_F_POINTER, Convert C into Fortran pointer
75 * @code{C_F_PROCPOINTER}: C_F_PROCPOINTER, Convert C into Fortran procedure pointer
76 * @code{C_FUNLOC}: C_FUNLOC, Obtain the C address of a procedure
77 * @code{C_LOC}: C_LOC, Obtain the C address of an object
78 * @code{CEILING}: CEILING, Integer ceiling function
79 * @code{CHAR}: CHAR, Integer-to-character conversion function
80 * @code{CHDIR}: CHDIR, Change working directory
81 * @code{CHMOD}: CHMOD, Change access permissions of files
82 * @code{CMPLX}: CMPLX, Complex conversion function
83 * @code{COMMAND_ARGUMENT_COUNT}: COMMAND_ARGUMENT_COUNT, Get number of command line arguments
84 * @code{COMPLEX}: COMPLEX, Complex conversion function
85 * @code{CONJG}: CONJG, Complex conjugate function
86 * @code{COS}: COS, Cosine function
87 * @code{COSH}: COSH, Hyperbolic cosine function
88 * @code{COUNT}: COUNT, Count occurrences of TRUE in an array
89 * @code{CPU_TIME}: CPU_TIME, CPU time subroutine
90 * @code{CSHIFT}: CSHIFT, Circular shift elements of an array
91 * @code{CTIME}: CTIME, Subroutine (or function) to convert a time into a string
92 * @code{DATE_AND_TIME}: DATE_AND_TIME, Date and time subroutine
93 * @code{DBLE}: DBLE, Double precision conversion function
94 * @code{DCMPLX}: DCMPLX, Double complex conversion function
95 * @code{DFLOAT}: DFLOAT, Double precision conversion function
96 * @code{DIGITS}: DIGITS, Significant digits function
97 * @code{DIM}: DIM, Positive difference
98 * @code{DOT_PRODUCT}: DOT_PRODUCT, Dot product function
99 * @code{DPROD}: DPROD, Double product function
100 * @code{DREAL}: DREAL, Double real part function
101 * @code{DTIME}: DTIME, Execution time subroutine (or function)
102 * @code{EOSHIFT}: EOSHIFT, End-off shift elements of an array
103 * @code{EPSILON}: EPSILON, Epsilon function
104 * @code{ERF}: ERF, Error function
105 * @code{ERFC}: ERFC, Complementary error function
106 * @code{ERFC_SCALED}: ERFC_SCALED, Exponentially-scaled complementary error function
107 * @code{ETIME}: ETIME, Execution time subroutine (or function)
108 * @code{EXIT}: EXIT, Exit the program with status.
109 * @code{EXP}: EXP, Exponential function
110 * @code{EXPONENT}: EXPONENT, Exponent function
111 * @code{FDATE}: FDATE, Subroutine (or function) to get the current time as a string
112 * @code{FGET}: FGET, Read a single character in stream mode from stdin
113 * @code{FGETC}: FGETC, Read a single character in stream mode
114 * @code{FLOAT}: FLOAT, Convert integer to default real
115 * @code{FLOOR}: FLOOR, Integer floor function
116 * @code{FLUSH}: FLUSH, Flush I/O unit(s)
117 * @code{FNUM}: FNUM, File number function
118 * @code{FPUT}: FPUT, Write a single character in stream mode to stdout
119 * @code{FPUTC}: FPUTC, Write a single character in stream mode
120 * @code{FRACTION}: FRACTION, Fractional part of the model representation
121 * @code{FREE}: FREE, Memory de-allocation subroutine
122 * @code{FSEEK}: FSEEK, Low level file positioning subroutine
123 * @code{FSTAT}: FSTAT, Get file status
124 * @code{FTELL}: FTELL, Current stream position
125 * @code{GAMMA}: GAMMA, Gamma function
126 * @code{GERROR}: GERROR, Get last system error message
127 * @code{GETARG}: GETARG, Get command line arguments
128 * @code{GET_COMMAND}: GET_COMMAND, Get the entire command line
129 * @code{GET_COMMAND_ARGUMENT}: GET_COMMAND_ARGUMENT, Get command line arguments
130 * @code{GETCWD}: GETCWD, Get current working directory
131 * @code{GETENV}: GETENV, Get an environmental variable
132 * @code{GET_ENVIRONMENT_VARIABLE}: GET_ENVIRONMENT_VARIABLE, Get an environmental variable
133 * @code{GETGID}: GETGID, Group ID function
134 * @code{GETLOG}: GETLOG, Get login name
135 * @code{GETPID}: GETPID, Process ID function
136 * @code{GETUID}: GETUID, User ID function
137 * @code{GMTIME}: GMTIME, Convert time to GMT info
138 * @code{HOSTNM}: HOSTNM, Get system host name
139 * @code{HUGE}: HUGE, Largest number of a kind
140 * @code{HYPOT}: HYPOT, Euclidian distance function
141 * @code{IACHAR}: IACHAR, Code in @acronym{ASCII} collating sequence
142 * @code{IAND}: IAND, Bitwise logical and
143 * @code{IARGC}: IARGC, Get the number of command line arguments
144 * @code{IBCLR}: IBCLR, Clear bit
145 * @code{IBITS}: IBITS, Bit extraction
146 * @code{IBSET}: IBSET, Set bit
147 * @code{ICHAR}: ICHAR, Character-to-integer conversion function
148 * @code{IDATE}: IDATE, Current local time (day/month/year)
149 * @code{IEOR}: IEOR, Bitwise logical exclusive or
150 * @code{IERRNO}: IERRNO, Function to get the last system error number
151 * @code{INDEX}: INDEX intrinsic, Position of a substring within a string
152 * @code{INT}: INT, Convert to integer type
153 * @code{INT2}: INT2, Convert to 16-bit integer type
154 * @code{INT8}: INT8, Convert to 64-bit integer type
155 * @code{IOR}: IOR, Bitwise logical or
156 * @code{IRAND}: IRAND, Integer pseudo-random number
157 * @code{IS_IOSTAT_END}: IS_IOSTAT_END, Test for end-of-file value
158 * @code{IS_IOSTAT_EOR}: IS_IOSTAT_EOR, Test for end-of-record value
159 * @code{ISATTY}: ISATTY, Whether a unit is a terminal device
160 * @code{ISHFT}: ISHFT, Shift bits
161 * @code{ISHFTC}: ISHFTC, Shift bits circularly
162 * @code{ISNAN}: ISNAN, Tests for a NaN
163 * @code{ITIME}: ITIME, Current local time (hour/minutes/seconds)
164 * @code{KILL}: KILL, Send a signal to a process
165 * @code{KIND}: KIND, Kind of an entity
166 * @code{LBOUND}: LBOUND, Lower dimension bounds of an array
167 * @code{LEN}: LEN, Length of a character entity
168 * @code{LEN_TRIM}: LEN_TRIM, Length of a character entity without trailing blank characters
169 * @code{LOG_GAMMA}: LOG_GAMMA, Logarithm of the Gamma function
170 * @code{LGE}: LGE, Lexical greater than or equal
171 * @code{LGT}: LGT, Lexical greater than
172 * @code{LINK}: LINK, Create a hard link
173 * @code{LLE}: LLE, Lexical less than or equal
174 * @code{LLT}: LLT, Lexical less than
175 * @code{LNBLNK}: LNBLNK, Index of the last non-blank character in a string
176 * @code{LOC}: LOC, Returns the address of a variable
177 * @code{LOG}: LOG, Logarithm function
178 * @code{LOG10}: LOG10, Base 10 logarithm function
179 * @code{LOGICAL}: LOGICAL, Convert to logical type
180 * @code{LONG}: LONG, Convert to integer type
181 * @code{LSHIFT}: LSHIFT, Left shift bits
182 * @code{LSTAT}: LSTAT, Get file status
183 * @code{LTIME}: LTIME, Convert time to local time info
184 * @code{MALLOC}: MALLOC, Dynamic memory allocation function
185 * @code{MATMUL}: MATMUL, matrix multiplication
186 * @code{MAX}: MAX, Maximum value of an argument list
187 * @code{MAXEXPONENT}: MAXEXPONENT, Maximum exponent of a real kind
188 * @code{MAXLOC}: MAXLOC, Location of the maximum value within an array
189 * @code{MAXVAL}: MAXVAL, Maximum value of an array
190 * @code{MCLOCK}: MCLOCK, Time function
191 * @code{MCLOCK8}: MCLOCK8, Time function (64-bit)
192 * @code{MERGE}: MERGE, Merge arrays
193 * @code{MIN}: MIN, Minimum value of an argument list
194 * @code{MINEXPONENT}: MINEXPONENT, Minimum exponent of a real kind
195 * @code{MINLOC}: MINLOC, Location of the minimum value within an array
196 * @code{MINVAL}: MINVAL, Minimum value of an array
197 * @code{MOD}: MOD, Remainder function
198 * @code{MODULO}: MODULO, Modulo function
199 * @code{MOVE_ALLOC}: MOVE_ALLOC, Move allocation from one object to another
200 * @code{MVBITS}: MVBITS, Move bits from one integer to another
201 * @code{NEAREST}: NEAREST, Nearest representable number
202 * @code{NEW_LINE}: NEW_LINE, New line character
203 * @code{NINT}: NINT, Nearest whole number
204 * @code{NOT}: NOT, Logical negation
205 * @code{NULL}: NULL, Function that returns an disassociated pointer
206 * @code{OR}: OR, Bitwise logical OR
207 * @code{PACK}: PACK, Pack an array into an array of rank one
208 * @code{PERROR}: PERROR, Print system error message
209 * @code{PRECISION}: PRECISION, Decimal precision of a real kind
210 * @code{PRESENT}: PRESENT, Determine whether an optional dummy argument is specified
211 * @code{PRODUCT}: PRODUCT, Product of array elements
212 * @code{RADIX}: RADIX, Base of a data model
213 * @code{RANDOM_NUMBER}: RANDOM_NUMBER, Pseudo-random number
214 * @code{RANDOM_SEED}: RANDOM_SEED, Initialize a pseudo-random number sequence
215 * @code{RAND}: RAND, Real pseudo-random number
216 * @code{RANGE}: RANGE, Decimal exponent range of a real kind
217 * @code{RAN}: RAN, Real pseudo-random number
218 * @code{REAL}: REAL, Convert to real type
219 * @code{RENAME}: RENAME, Rename a file
220 * @code{REPEAT}: REPEAT, Repeated string concatenation
221 * @code{RESHAPE}: RESHAPE, Function to reshape an array
222 * @code{RRSPACING}: RRSPACING, Reciprocal of the relative spacing
223 * @code{RSHIFT}: RSHIFT, Right shift bits
224 * @code{SCALE}: SCALE, Scale a real value
225 * @code{SCAN}: SCAN, Scan a string for the presence of a set of characters
226 * @code{SECNDS}: SECNDS, Time function
227 * @code{SECOND}: SECOND, CPU time function
228 * @code{SELECTED_CHAR_KIND}: SELECTED_CHAR_KIND, Choose character kind
229 * @code{SELECTED_INT_KIND}: SELECTED_INT_KIND, Choose integer kind
230 * @code{SELECTED_REAL_KIND}: SELECTED_REAL_KIND, Choose real kind
231 * @code{SET_EXPONENT}: SET_EXPONENT, Set the exponent of the model
232 * @code{SHAPE}: SHAPE, Determine the shape of an array
233 * @code{SIGN}: SIGN, Sign copying function
234 * @code{SIGNAL}: SIGNAL, Signal handling subroutine (or function)
235 * @code{SIN}: SIN, Sine function
236 * @code{SINH}: SINH, Hyperbolic sine function
237 * @code{SIZE}: SIZE, Function to determine the size of an array
238 * @code{SIZEOF}: SIZEOF, Determine the size in bytes of an expression
239 * @code{SLEEP}: SLEEP, Sleep for the specified number of seconds
240 * @code{SNGL}: SNGL, Convert double precision real to default real
241 * @code{SPACING}: SPACING, Smallest distance between two numbers of a given type
242 * @code{SPREAD}: SPREAD, Add a dimension to an array
243 * @code{SQRT}: SQRT, Square-root function
244 * @code{SRAND}: SRAND, Reinitialize the random number generator
245 * @code{STAT}: STAT, Get file status
246 * @code{SUM}: SUM, Sum of array elements
247 * @code{SYMLNK}: SYMLNK, Create a symbolic link
248 * @code{SYSTEM}: SYSTEM, Execute a shell command
249 * @code{SYSTEM_CLOCK}: SYSTEM_CLOCK, Time function
250 * @code{TAN}: TAN, Tangent function
251 * @code{TANH}: TANH, Hyperbolic tangent function
252 * @code{TIME}: TIME, Time function
253 * @code{TIME8}: TIME8, Time function (64-bit)
254 * @code{TINY}: TINY, Smallest positive number of a real kind
255 * @code{TRANSFER}: TRANSFER, Transfer bit patterns
256 * @code{TRANSPOSE}: TRANSPOSE, Transpose an array of rank two
257 * @code{TRIM}: TRIM, Remove trailing blank characters of a string
258 * @code{TTYNAM}: TTYNAM, Get the name of a terminal device.
259 * @code{UBOUND}: UBOUND, Upper dimension bounds of an array
260 * @code{UMASK}: UMASK, Set the file creation mask
261 * @code{UNLINK}: UNLINK, Remove a file from the file system
262 * @code{UNPACK}: UNPACK, Unpack an array of rank one into an array
263 * @code{VERIFY}: VERIFY, Scan a string for the absence of a set of characters
264 * @code{XOR}: XOR, Bitwise logical exclusive or
267 @node Introduction to Intrinsics
268 @section Introduction to intrinsic procedures
270 The intrinsic procedures provided by GNU Fortran include all of the
271 intrinsic procedures required by the Fortran 95 standard, a set of
272 intrinsic procedures for backwards compatibility with G77, and a
273 selection of intrinsic procedures from the Fortran 2003 and Fortran 2008
274 standards. Any conflict between a description here and a description in
275 either the Fortran 95 standard, the Fortran 2003 standard or the Fortran
276 2008 standard is unintentional, and the standard(s) should be considered
279 The enumeration of the @code{KIND} type parameter is processor defined in
280 the Fortran 95 standard. GNU Fortran defines the default integer type and
281 default real type by @code{INTEGER(KIND=4)} and @code{REAL(KIND=4)},
282 respectively. The standard mandates that both data types shall have
283 another kind, which have more precision. On typical target architectures
284 supported by @command{gfortran}, this kind type parameter is @code{KIND=8}.
285 Hence, @code{REAL(KIND=8)} and @code{DOUBLE PRECISION} are equivalent.
286 In the description of generic intrinsic procedures, the kind type parameter
287 will be specified by @code{KIND=*}, and in the description of specific
288 names for an intrinsic procedure the kind type parameter will be explicitly
289 given (e.g., @code{REAL(KIND=4)} or @code{REAL(KIND=8)}). Finally, for
290 brevity the optional @code{KIND=} syntax will be omitted.
292 Many of the intrinsic procedures take one or more optional arguments.
293 This document follows the convention used in the Fortran 95 standard,
294 and denotes such arguments by square brackets.
296 GNU Fortran offers the @option{-std=f95} and @option{-std=gnu} options,
297 which can be used to restrict the set of intrinsic procedures to a
298 given standard. By default, @command{gfortran} sets the @option{-std=gnu}
299 option, and so all intrinsic procedures described here are accepted. There
300 is one caveat. For a select group of intrinsic procedures, @command{g77}
301 implemented both a function and a subroutine. Both classes
302 have been implemented in @command{gfortran} for backwards compatibility
303 with @command{g77}. It is noted here that these functions and subroutines
304 cannot be intermixed in a given subprogram. In the descriptions that follow,
305 the applicable standard for each intrinsic procedure is noted.
310 @section @code{ABORT} --- Abort the program
312 @cindex program termination, with core dump
313 @cindex terminate program, with core dump
317 @item @emph{Description}:
318 @code{ABORT} causes immediate termination of the program. On operating
319 systems that support a core dump, @code{ABORT} will produce a core dump,
320 which is suitable for debugging purposes.
322 @item @emph{Standard}:
331 @item @emph{Return value}:
334 @item @emph{Example}:
337 integer :: i = 1, j = 2
338 if (i /= j) call abort
339 end program test_abort
342 @item @emph{See also}:
343 @ref{EXIT}, @ref{KILL}
350 @section @code{ABS} --- Absolute value
357 @cindex absolute value
360 @item @emph{Description}:
361 @code{ABS(X)} computes the absolute value of @code{X}.
363 @item @emph{Standard}:
364 F77 and later, has overloads that are GNU extensions
370 @code{RESULT = ABS(X)}
372 @item @emph{Arguments}:
373 @multitable @columnfractions .15 .70
374 @item @var{X} @tab The type of the argument shall be an @code{INTEGER(*)},
375 @code{REAL(*)}, or @code{COMPLEX(*)}.
378 @item @emph{Return value}:
379 The return value is of the same type and
380 kind as the argument except the return value is @code{REAL(*)} for a
381 @code{COMPLEX(*)} argument.
383 @item @emph{Example}:
388 complex :: z = (-1.e0,0.e0)
395 @item @emph{Specific names}:
396 @multitable @columnfractions .20 .20 .20 .25
397 @item Name @tab Argument @tab Return type @tab Standard
398 @item @code{CABS(Z)} @tab @code{COMPLEX(4) Z} @tab @code{REAL(4)} @tab F77 and later
399 @item @code{DABS(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab F77 and later
400 @item @code{IABS(I)} @tab @code{INTEGER(4) I} @tab @code{INTEGER(4)} @tab F77 and later
401 @item @code{ZABS(Z)} @tab @code{COMPLEX(8) Z} @tab @code{COMPLEX(8)} @tab GNU extension
402 @item @code{CDABS(Z)} @tab @code{COMPLEX(8) Z} @tab @code{COMPLEX(8)} @tab GNU extension
409 @section @code{ACCESS} --- Checks file access modes
411 @cindex file system, access mode
414 @item @emph{Description}:
415 @code{ACCESS(NAME, MODE)} checks whether the file @var{NAME}
416 exists, is readable, writable or executable. Except for the
417 executable check, @code{ACCESS} can be replaced by
418 Fortran 95's @code{INQUIRE}.
420 @item @emph{Standard}:
427 @code{RESULT = ACCESS(NAME, MODE)}
429 @item @emph{Arguments}:
430 @multitable @columnfractions .15 .70
431 @item @var{NAME} @tab Scalar @code{CHARACTER} with the file name.
432 Tailing blank are ignored unless the character @code{achar(0)} is
433 present, then all characters up to and excluding @code{achar(0)} are
435 @item @var{MODE} @tab Scalar @code{CHARACTER} with the file access mode,
436 may be any concatenation of @code{"r"} (readable), @code{"w"} (writable)
437 and @code{"x"} (executable), or @code{" "} to check for existence.
440 @item @emph{Return value}:
441 Returns a scalar @code{INTEGER}, which is @code{0} if the file is
442 accessible in the given mode; otherwise or if an invalid argument
443 has been given for @code{MODE} the value @code{1} is returned.
445 @item @emph{Example}:
449 character(len=*), parameter :: file = 'test.dat'
450 character(len=*), parameter :: file2 = 'test.dat '//achar(0)
451 if(access(file,' ') == 0) print *, trim(file),' is exists'
452 if(access(file,'r') == 0) print *, trim(file),' is readable'
453 if(access(file,'w') == 0) print *, trim(file),' is writable'
454 if(access(file,'x') == 0) print *, trim(file),' is executable'
455 if(access(file2,'rwx') == 0) &
456 print *, trim(file2),' is readable, writable and executable'
457 end program access_test
459 @item @emph{Specific names}:
460 @item @emph{See also}:
467 @section @code{ACHAR} --- Character in @acronym{ASCII} collating sequence
469 @cindex @acronym{ASCII} collating sequence
470 @cindex collating sequence, @acronym{ASCII}
473 @item @emph{Description}:
474 @code{ACHAR(I)} returns the character located at position @code{I}
475 in the @acronym{ASCII} collating sequence.
477 @item @emph{Standard}:
484 @code{RESULT = ACHAR(I)}
486 @item @emph{Arguments}:
487 @multitable @columnfractions .15 .70
488 @item @var{I} @tab The type shall be @code{INTEGER(*)}.
491 @item @emph{Return value}:
492 The return value is of type @code{CHARACTER} with a length of one. The
493 kind type parameter is the same as @code{KIND('A')}.
495 @item @emph{Example}:
500 end program test_achar
504 See @ref{ICHAR} for a discussion of converting between numerical values
505 and formatted string representations.
507 @item @emph{See also}:
508 @ref{CHAR}, @ref{IACHAR}, @ref{ICHAR}
515 @section @code{ACOS} --- Arccosine function
518 @cindex trigonometric function, cosine, inverse
519 @cindex cosine, inverse
522 @item @emph{Description}:
523 @code{ACOS(X)} computes the arccosine of @var{X} (inverse of @code{COS(X)}).
525 @item @emph{Standard}:
532 @code{RESULT = ACOS(X)}
534 @item @emph{Arguments}:
535 @multitable @columnfractions .15 .70
536 @item @var{X} @tab The type shall be @code{REAL(*)} with a magnitude that is
540 @item @emph{Return value}:
541 The return value is of type @code{REAL(*)} and it lies in the
542 range @math{ 0 \leq \acos(x) \leq \pi}. The kind type parameter
543 is the same as @var{X}.
545 @item @emph{Example}:
548 real(8) :: x = 0.866_8
550 end program test_acos
553 @item @emph{Specific names}:
554 @multitable @columnfractions .20 .20 .20 .25
555 @item Name @tab Argument @tab Return type @tab Standard
556 @item @code{DACOS(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab F77 and later
559 @item @emph{See also}:
560 Inverse function: @ref{COS}
567 @section @code{ACOSH} --- Hyperbolic arccosine function
570 @cindex area hyperbolic cosine
571 @cindex hyperbolic arccosine
572 @cindex hyperbolic function, cosine, inverse
573 @cindex cosine, hyperbolic, inverse
576 @item @emph{Description}:
577 @code{ACOSH(X)} computes the hyperbolic arccosine of @var{X} (inverse of
580 @item @emph{Standard}:
581 Fortran 2008 and later
587 @code{RESULT = ACOSH(X)}
589 @item @emph{Arguments}:
590 @multitable @columnfractions .15 .70
591 @item @var{X} @tab The type shall be @code{REAL} or @code{COMPLEX}.
594 @item @emph{Return value}:
595 The return value has the same type and kind as @var{X}
597 @item @emph{Example}:
600 REAL(8), DIMENSION(3) :: x = (/ 1.0, 2.0, 3.0 /)
605 @item @emph{Specific names}:
606 @multitable @columnfractions .20 .20 .20 .25
607 @item Name @tab Argument @tab Return type @tab Standard
608 @item @code{DACOSH(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU extension
611 @item @emph{See also}:
612 Inverse function: @ref{COSH}
618 @section @code{ADJUSTL} --- Left adjust a string
620 @cindex string, adjust left
621 @cindex adjust string
624 @item @emph{Description}:
625 @code{ADJUSTL(STR)} will left adjust a string by removing leading spaces.
626 Spaces are inserted at the end of the string as needed.
628 @item @emph{Standard}:
635 @code{RESULT = ADJUSTL(STR)}
637 @item @emph{Arguments}:
638 @multitable @columnfractions .15 .70
639 @item @var{STR} @tab The type shall be @code{CHARACTER}.
642 @item @emph{Return value}:
643 The return value is of type @code{CHARACTER} where leading spaces
644 are removed and the same number of spaces are inserted on the end
647 @item @emph{Example}:
650 character(len=20) :: str = ' gfortran'
653 end program test_adjustl
656 @item @emph{See also}:
657 @ref{ADJUSTR}, @ref{TRIM}
663 @section @code{ADJUSTR} --- Right adjust a string
665 @cindex string, adjust right
666 @cindex adjust string
669 @item @emph{Description}:
670 @code{ADJUSTR(STR)} will right adjust a string by removing trailing spaces.
671 Spaces are inserted at the start of the string as needed.
673 @item @emph{Standard}:
680 @code{RESULT = ADJUSTR(STR)}
682 @item @emph{Arguments}:
683 @multitable @columnfractions .15 .70
684 @item @var{STR} @tab The type shall be @code{CHARACTER}.
687 @item @emph{Return value}:
688 The return value is of type @code{CHARACTER} where trailing spaces
689 are removed and the same number of spaces are inserted at the start
692 @item @emph{Example}:
695 character(len=20) :: str = 'gfortran'
698 end program test_adjustr
701 @item @emph{See also}:
702 @ref{ADJUSTL}, @ref{TRIM}
708 @section @code{AIMAG} --- Imaginary part of complex number
713 @cindex complex numbers, imaginary part
716 @item @emph{Description}:
717 @code{AIMAG(Z)} yields the imaginary part of complex argument @code{Z}.
718 The @code{IMAG(Z)} and @code{IMAGPART(Z)} intrinsic functions are provided
719 for compatibility with @command{g77}, and their use in new code is
720 strongly discouraged.
722 @item @emph{Standard}:
723 F77 and later, has overloads that are GNU extensions
729 @code{RESULT = AIMAG(Z)}
731 @item @emph{Arguments}:
732 @multitable @columnfractions .15 .70
733 @item @var{Z} @tab The type of the argument shall be @code{COMPLEX(*)}.
736 @item @emph{Return value}:
737 The return value is of type real with the
738 kind type parameter of the argument.
740 @item @emph{Example}:
745 z4 = cmplx(1.e0_4, 0.e0_4)
746 z8 = cmplx(0.e0_8, 1.e0_8)
747 print *, aimag(z4), dimag(z8)
748 end program test_aimag
751 @item @emph{Specific names}:
752 @multitable @columnfractions .20 .20 .20 .25
753 @item Name @tab Argument @tab Return type @tab Standard
754 @item @code{DIMAG(Z)} @tab @code{COMPLEX(8) Z} @tab @code{REAL(8)} @tab GNU extension
755 @item @code{IMAG(Z)} @tab @code{COMPLEX(*) Z} @tab @code{REAL(*)} @tab GNU extension
756 @item @code{IMAGPART(Z)} @tab @code{COMPLEX(*) Z} @tab @code{REAL(*)} @tab GNU extension
763 @section @code{AINT} --- Truncate to a whole number
767 @cindex rounding, floor
770 @item @emph{Description}:
771 @code{AINT(X [, KIND])} truncates its argument to a whole number.
773 @item @emph{Standard}:
780 @code{RESULT = AINT(X [, KIND])}
782 @item @emph{Arguments}:
783 @multitable @columnfractions .15 .70
784 @item @var{X} @tab The type of the argument shall be @code{REAL(*)}.
785 @item @var{KIND} @tab (Optional) An @code{INTEGER(*)} initialization
786 expression indicating the kind parameter of
790 @item @emph{Return value}:
791 The return value is of type real with the kind type parameter of the
792 argument if the optional @var{KIND} is absent; otherwise, the kind
793 type parameter will be given by @var{KIND}. If the magnitude of
794 @var{X} is less than one, then @code{AINT(X)} returns zero. If the
795 magnitude is equal to or greater than one, then it returns the largest
796 whole number that does not exceed its magnitude. The sign is the same
797 as the sign of @var{X}.
799 @item @emph{Example}:
806 print *, aint(x4), dint(x8)
808 end program test_aint
811 @item @emph{Specific names}:
812 @multitable @columnfractions .20 .20 .20 .25
813 @item Name @tab Argument @tab Return type @tab Standard
814 @item @code{DINT(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab F77 and later
821 @section @code{ALARM} --- Execute a routine after a given delay
823 @cindex delayed execution
826 @item @emph{Description}:
827 @code{ALARM(SECONDS, HANDLER [, STATUS])} causes external subroutine @var{HANDLER}
828 to be executed after a delay of @var{SECONDS} by using @code{alarm(2)} to
829 set up a signal and @code{signal(2)} to catch it. If @var{STATUS} is
830 supplied, it will be returned with the number of seconds remaining until
831 any previously scheduled alarm was due to be delivered, or zero if there
832 was no previously scheduled alarm.
834 @item @emph{Standard}:
841 @code{CALL ALARM(SECONDS, HANDLER [, STATUS])}
843 @item @emph{Arguments}:
844 @multitable @columnfractions .15 .70
845 @item @var{SECONDS} @tab The type of the argument shall be a scalar
846 @code{INTEGER}. It is @code{INTENT(IN)}.
847 @item @var{HANDLER} @tab Signal handler (@code{INTEGER FUNCTION} or
848 @code{SUBROUTINE}) or dummy/global @code{INTEGER} scalar. The scalar
849 values may be either @code{SIG_IGN=1} to ignore the alarm generated
850 or @code{SIG_DFL=0} to set the default action. It is @code{INTENT(IN)}.
851 @item @var{STATUS} @tab (Optional) @var{STATUS} shall be a scalar
852 variable of the default @code{INTEGER} kind. It is @code{INTENT(OUT)}.
855 @item @emph{Example}:
858 external handler_print
860 call alarm (3, handler_print, i)
863 end program test_alarm
865 This will cause the external routine @var{handler_print} to be called
872 @section @code{ALL} --- All values in @var{MASK} along @var{DIM} are true
874 @cindex array, apply condition
875 @cindex array, condition testing
878 @item @emph{Description}:
879 @code{ALL(MASK [, DIM])} determines if all the values are true in @var{MASK}
880 in the array along dimension @var{DIM}.
882 @item @emph{Standard}:
886 Transformational function
889 @code{RESULT = ALL(MASK [, DIM])}
891 @item @emph{Arguments}:
892 @multitable @columnfractions .15 .70
893 @item @var{MASK} @tab The type of the argument shall be @code{LOGICAL(*)} and
894 it shall not be scalar.
895 @item @var{DIM} @tab (Optional) @var{DIM} shall be a scalar integer
896 with a value that lies between one and the rank of @var{MASK}.
899 @item @emph{Return value}:
900 @code{ALL(MASK)} returns a scalar value of type @code{LOGICAL(*)} where
901 the kind type parameter is the same as the kind type parameter of
902 @var{MASK}. If @var{DIM} is present, then @code{ALL(MASK, DIM)} returns
903 an array with the rank of @var{MASK} minus 1. The shape is determined from
904 the shape of @var{MASK} where the @var{DIM} dimension is elided.
908 @code{ALL(MASK)} is true if all elements of @var{MASK} are true.
909 It also is true if @var{MASK} has zero size; otherwise, it is false.
911 If the rank of @var{MASK} is one, then @code{ALL(MASK,DIM)} is equivalent
912 to @code{ALL(MASK)}. If the rank is greater than one, then @code{ALL(MASK,DIM)}
913 is determined by applying @code{ALL} to the array sections.
916 @item @emph{Example}:
920 l = all((/.true., .true., .true./))
925 integer a(2,3), b(2,3)
929 print *, all(a .eq. b, 1)
930 print *, all(a .eq. b, 2)
931 end subroutine section
939 @section @code{ALLOCATED} --- Status of an allocatable entity
941 @cindex allocation, status
944 @item @emph{Description}:
945 @code{ALLOCATED(X)} checks the status of whether @var{X} is allocated.
947 @item @emph{Standard}:
954 @code{RESULT = ALLOCATED(X)}
956 @item @emph{Arguments}:
957 @multitable @columnfractions .15 .70
958 @item @var{X} @tab The argument shall be an @code{ALLOCATABLE} array.
961 @item @emph{Return value}:
962 The return value is a scalar @code{LOGICAL} with the default logical
963 kind type parameter. If @var{X} is allocated, @code{ALLOCATED(X)}
964 is @code{.TRUE.}; otherwise, it returns @code{.FALSE.}
966 @item @emph{Example}:
968 program test_allocated
970 real(4), allocatable :: x(:)
971 if (allocated(x) .eqv. .false.) allocate(x(i))
972 end program test_allocated
979 @section @code{AND} --- Bitwise logical AND
981 @cindex bitwise logical and
982 @cindex logical and, bitwise
985 @item @emph{Description}:
986 Bitwise logical @code{AND}.
988 This intrinsic routine is provided for backwards compatibility with
989 GNU Fortran 77. For integer arguments, programmers should consider
990 the use of the @ref{IAND} intrinsic defined by the Fortran standard.
992 @item @emph{Standard}:
999 @code{RESULT = AND(I, J)}
1001 @item @emph{Arguments}:
1002 @multitable @columnfractions .15 .70
1003 @item @var{I} @tab The type shall be either a scalar @code{INTEGER(*)}
1004 type or a scalar @code{LOGICAL} type.
1005 @item @var{J} @tab The type shall be the same as the type of @var{I}.
1008 @item @emph{Return value}:
1009 The return type is either a scalar @code{INTEGER(*)} or a scalar
1010 @code{LOGICAL}. If the kind type parameters differ, then the
1011 smaller kind type is implicitly converted to larger kind, and the
1012 return has the larger kind.
1014 @item @emph{Example}:
1017 LOGICAL :: T = .TRUE., F = .FALSE.
1019 DATA a / Z'F' /, b / Z'3' /
1021 WRITE (*,*) AND(T, T), AND(T, F), AND(F, T), AND(F, F)
1022 WRITE (*,*) AND(a, b)
1026 @item @emph{See also}:
1027 F95 elemental function: @ref{IAND}
1033 @section @code{ANINT} --- Nearest whole number
1037 @cindex rounding, ceiling
1040 @item @emph{Description}:
1041 @code{ANINT(X [, KIND])} rounds its argument to the nearest whole number.
1043 @item @emph{Standard}:
1049 @item @emph{Syntax}:
1050 @code{RESULT = ANINT(X [, KIND])}
1052 @item @emph{Arguments}:
1053 @multitable @columnfractions .15 .70
1054 @item @var{X} @tab The type of the argument shall be @code{REAL(*)}.
1055 @item @var{KIND} @tab (Optional) An @code{INTEGER(*)} initialization
1056 expression indicating the kind parameter of
1060 @item @emph{Return value}:
1061 The return value is of type real with the kind type parameter of the
1062 argument if the optional @var{KIND} is absent; otherwise, the kind
1063 type parameter will be given by @var{KIND}. If @var{X} is greater than
1064 zero, then @code{ANINT(X)} returns @code{AINT(X+0.5)}. If @var{X} is
1065 less than or equal to zero, then it returns @code{AINT(X-0.5)}.
1067 @item @emph{Example}:
1074 print *, anint(x4), dnint(x8)
1076 end program test_anint
1079 @item @emph{Specific names}:
1080 @multitable @columnfractions .20 .20 .20 .25
1081 @item Name @tab Argument @tab Return type @tab Standard
1082 @item @code{DNINT(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab F77 and later
1089 @section @code{ANY} --- Any value in @var{MASK} along @var{DIM} is true
1091 @cindex array, apply condition
1092 @cindex array, condition testing
1095 @item @emph{Description}:
1096 @code{ANY(MASK [, DIM])} determines if any of the values in the logical array
1097 @var{MASK} along dimension @var{DIM} are @code{.TRUE.}.
1099 @item @emph{Standard}:
1103 Transformational function
1105 @item @emph{Syntax}:
1106 @code{RESULT = ANY(MASK [, DIM])}
1108 @item @emph{Arguments}:
1109 @multitable @columnfractions .15 .70
1110 @item @var{MASK} @tab The type of the argument shall be @code{LOGICAL(*)} and
1111 it shall not be scalar.
1112 @item @var{DIM} @tab (Optional) @var{DIM} shall be a scalar integer
1113 with a value that lies between one and the rank of @var{MASK}.
1116 @item @emph{Return value}:
1117 @code{ANY(MASK)} returns a scalar value of type @code{LOGICAL(*)} where
1118 the kind type parameter is the same as the kind type parameter of
1119 @var{MASK}. If @var{DIM} is present, then @code{ANY(MASK, DIM)} returns
1120 an array with the rank of @var{MASK} minus 1. The shape is determined from
1121 the shape of @var{MASK} where the @var{DIM} dimension is elided.
1125 @code{ANY(MASK)} is true if any element of @var{MASK} is true;
1126 otherwise, it is false. It also is false if @var{MASK} has zero size.
1128 If the rank of @var{MASK} is one, then @code{ANY(MASK,DIM)} is equivalent
1129 to @code{ANY(MASK)}. If the rank is greater than one, then @code{ANY(MASK,DIM)}
1130 is determined by applying @code{ANY} to the array sections.
1133 @item @emph{Example}:
1137 l = any((/.true., .true., .true./))
1142 integer a(2,3), b(2,3)
1146 print *, any(a .eq. b, 1)
1147 print *, any(a .eq. b, 2)
1148 end subroutine section
1149 end program test_any
1156 @section @code{ASIN} --- Arcsine function
1159 @cindex trigonometric function, sine, inverse
1160 @cindex sine, inverse
1163 @item @emph{Description}:
1164 @code{ASIN(X)} computes the arcsine of its @var{X} (inverse of @code{SIN(X)}).
1166 @item @emph{Standard}:
1172 @item @emph{Syntax}:
1173 @code{RESULT = ASIN(X)}
1175 @item @emph{Arguments}:
1176 @multitable @columnfractions .15 .70
1177 @item @var{X} @tab The type shall be @code{REAL(*)}, and a magnitude that is
1181 @item @emph{Return value}:
1182 The return value is of type @code{REAL(*)} and it lies in the
1183 range @math{-\pi / 2 \leq \asin (x) \leq \pi / 2}. The kind type
1184 parameter is the same as @var{X}.
1186 @item @emph{Example}:
1189 real(8) :: x = 0.866_8
1191 end program test_asin
1194 @item @emph{Specific names}:
1195 @multitable @columnfractions .20 .20 .20 .25
1196 @item Name @tab Argument @tab Return type @tab Standard
1197 @item @code{DASIN(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab F77 and later
1200 @item @emph{See also}:
1201 Inverse function: @ref{SIN}
1208 @section @code{ASINH} --- Hyperbolic arcsine function
1211 @cindex area hyperbolic sine
1212 @cindex hyperbolic arcsine
1213 @cindex hyperbolic function, sine, inverse
1214 @cindex sine, hyperbolic, inverse
1217 @item @emph{Description}:
1218 @code{ASINH(X)} computes the hyperbolic arcsine of @var{X} (inverse of @code{SINH(X)}).
1220 @item @emph{Standard}:
1221 Fortran 2008 and later
1226 @item @emph{Syntax}:
1227 @code{RESULT = ASINH(X)}
1229 @item @emph{Arguments}:
1230 @multitable @columnfractions .15 .70
1231 @item @var{X} @tab The type shall be @code{REAL} or @code{COMPLEX}.
1234 @item @emph{Return value}:
1235 The return value is of the same type and kind as @var{X}.
1237 @item @emph{Example}:
1240 REAL(8), DIMENSION(3) :: x = (/ -1.0, 0.0, 1.0 /)
1241 WRITE (*,*) ASINH(x)
1245 @item @emph{Specific names}:
1246 @multitable @columnfractions .20 .20 .20 .25
1247 @item Name @tab Argument @tab Return type @tab Standard
1248 @item @code{DASINH(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU extension.
1251 @item @emph{See also}:
1252 Inverse function: @ref{SINH}
1258 @section @code{ASSOCIATED} --- Status of a pointer or pointer/target pair
1260 @cindex pointer, status
1261 @cindex association status
1264 @item @emph{Description}:
1265 @code{ASSOCIATED(PTR [, TGT])} determines the status of the pointer @var{PTR}
1266 or if @var{PTR} is associated with the target @var{TGT}.
1268 @item @emph{Standard}:
1274 @item @emph{Syntax}:
1275 @code{RESULT = ASSOCIATED(PTR [, TGT])}
1277 @item @emph{Arguments}:
1278 @multitable @columnfractions .15 .70
1279 @item @var{PTR} @tab @var{PTR} shall have the @code{POINTER} attribute and
1280 it can be of any type.
1281 @item @var{TGT} @tab (Optional) @var{TGT} shall be a @code{POINTER} or
1282 a @code{TARGET}. It must have the same type, kind type parameter, and
1283 array rank as @var{PTR}.
1285 The status of neither @var{PTR} nor @var{TGT} can be undefined.
1287 @item @emph{Return value}:
1288 @code{ASSOCIATED(PTR)} returns a scalar value of type @code{LOGICAL(4)}.
1289 There are several cases:
1291 @item (A) If the optional @var{TGT} is not present, then @code{ASSOCIATED(PTR)}
1292 is true if @var{PTR} is associated with a target; otherwise, it returns false.
1293 @item (B) If @var{TGT} is present and a scalar target, the result is true if
1295 is not a 0 sized storage sequence and the target associated with @var{PTR}
1296 occupies the same storage units. If @var{PTR} is disassociated, then the
1298 @item (C) If @var{TGT} is present and an array target, the result is true if
1299 @var{TGT} and @var{PTR} have the same shape, are not 0 sized arrays, are
1300 arrays whose elements are not 0 sized storage sequences, and @var{TGT} and
1301 @var{PTR} occupy the same storage units in array element order.
1302 As in case(B), the result is false, if @var{PTR} is disassociated.
1303 @item (D) If @var{TGT} is present and an scalar pointer, the result is true if
1304 target associated with @var{PTR} and the target associated with @var{TGT}
1305 are not 0 sized storage sequences and occupy the same storage units.
1306 The result is false, if either @var{TGT} or @var{PTR} is disassociated.
1307 @item (E) If @var{TGT} is present and an array pointer, the result is true if
1308 target associated with @var{PTR} and the target associated with @var{TGT}
1309 have the same shape, are not 0 sized arrays, are arrays whose elements are
1310 not 0 sized storage sequences, and @var{TGT} and @var{PTR} occupy the same
1311 storage units in array element order.
1312 The result is false, if either @var{TGT} or @var{PTR} is disassociated.
1315 @item @emph{Example}:
1317 program test_associated
1319 real, target :: tgt(2) = (/1., 2./)
1320 real, pointer :: ptr(:)
1322 if (associated(ptr) .eqv. .false.) call abort
1323 if (associated(ptr,tgt) .eqv. .false.) call abort
1324 end program test_associated
1327 @item @emph{See also}:
1334 @section @code{ATAN} --- Arctangent function
1337 @cindex trigonometric function, tangent, inverse
1338 @cindex tangent, inverse
1341 @item @emph{Description}:
1342 @code{ATAN(X)} computes the arctangent of @var{X}.
1344 @item @emph{Standard}:
1350 @item @emph{Syntax}:
1351 @code{RESULT = ATAN(X)}
1353 @item @emph{Arguments}:
1354 @multitable @columnfractions .15 .70
1355 @item @var{X} @tab The type shall be @code{REAL(*)}.
1358 @item @emph{Return value}:
1359 The return value is of type @code{REAL(*)} and it lies in the
1360 range @math{ - \pi / 2 \leq \atan (x) \leq \pi / 2}.
1362 @item @emph{Example}:
1365 real(8) :: x = 2.866_8
1367 end program test_atan
1370 @item @emph{Specific names}:
1371 @multitable @columnfractions .20 .20 .20 .25
1372 @item Name @tab Argument @tab Return type @tab Standard
1373 @item @code{DATAN(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab F77 and later
1376 @item @emph{See also}:
1377 Inverse function: @ref{TAN}
1384 @section @code{ATAN2} --- Arctangent function
1387 @cindex trigonometric function, tangent, inverse
1388 @cindex tangent, inverse
1391 @item @emph{Description}:
1392 @code{ATAN2(Y,X)} computes the arctangent of the complex number
1395 @item @emph{Standard}:
1401 @item @emph{Syntax}:
1402 @code{RESULT = ATAN2(Y,X)}
1404 @item @emph{Arguments}:
1405 @multitable @columnfractions .15 .70
1406 @item @var{Y} @tab The type shall be @code{REAL(*)}.
1407 @item @var{X} @tab The type and kind type parameter shall be the same as @var{Y}.
1408 If @var{Y} is zero, then @var{X} must be nonzero.
1411 @item @emph{Return value}:
1412 The return value has the same type and kind type parameter as @var{Y}.
1413 It is the principal value of the complex number @math{X + i Y}. If
1414 @var{X} is nonzero, then it lies in the range @math{-\pi \le \atan (x) \leq \pi}.
1415 The sign is positive if @var{Y} is positive. If @var{Y} is zero, then
1416 the return value is zero if @var{X} is positive and @math{\pi} if @var{X}
1417 is negative. Finally, if @var{X} is zero, then the magnitude of the result
1420 @item @emph{Example}:
1423 real(4) :: x = 1.e0_4, y = 0.5e0_4
1425 end program test_atan2
1428 @item @emph{Specific names}:
1429 @multitable @columnfractions .20 .20 .20 .25
1430 @item Name @tab Argument @tab Return type @tab Standard
1431 @item @code{DATAN2(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab F77 and later
1438 @section @code{ATANH} --- Hyperbolic arctangent function
1441 @cindex area hyperbolic tangent
1442 @cindex hyperbolic arctangent
1443 @cindex hyperbolic function, tangent, inverse
1444 @cindex tangent, hyperbolic, inverse
1447 @item @emph{Description}:
1448 @code{ATANH(X)} computes the hyperbolic arctangent of @var{X} (inverse
1451 @item @emph{Standard}:
1452 Fortran 2008 and later
1457 @item @emph{Syntax}:
1458 @code{RESULT = ATANH(X)}
1460 @item @emph{Arguments}:
1461 @multitable @columnfractions .15 .70
1462 @item @var{X} @tab The type shall be @code{REAL} or @code{COMPLEX}.
1465 @item @emph{Return value}:
1466 The return value has same type and kind as @var{X}.
1468 @item @emph{Example}:
1471 REAL, DIMENSION(3) :: x = (/ -1.0, 0.0, 1.0 /)
1472 WRITE (*,*) ATANH(x)
1476 @item @emph{Specific names}:
1477 @multitable @columnfractions .20 .20 .20 .25
1478 @item Name @tab Argument @tab Return type @tab Standard
1479 @item @code{DATANH(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU extension
1482 @item @emph{See also}:
1483 Inverse function: @ref{TANH}
1489 @section @code{BESSEL_J0} --- Bessel function of the first kind of order 0
1493 @cindex Bessel function, first kind
1496 @item @emph{Description}:
1497 @code{BESSEL_J0(X)} computes the Bessel function of the first kind of
1498 order 0 of @var{X}. This function is available under the name
1499 @code{BESJ0} as a GNU extension.
1501 @item @emph{Standard}:
1502 Fortran 2008 and later
1507 @item @emph{Syntax}:
1508 @code{RESULT = BESSEL_J0(X)}
1510 @item @emph{Arguments}:
1511 @multitable @columnfractions .15 .70
1512 @item @var{X} @tab The type shall be @code{REAL(*)}, and it shall be scalar.
1515 @item @emph{Return value}:
1516 The return value is of type @code{REAL(*)} and it lies in the
1517 range @math{ - 0.4027... \leq Bessel (0,x) \leq 1}.
1519 @item @emph{Example}:
1522 real(8) :: x = 0.0_8
1524 end program test_besj0
1527 @item @emph{Specific names}:
1528 @multitable @columnfractions .20 .20 .20 .25
1529 @item Name @tab Argument @tab Return type @tab Standard
1530 @item @code{DBESJ0(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU extension
1537 @section @code{BESEL_J1} --- Bessel function of the first kind of order 1
1541 @cindex Bessel function, first kind
1544 @item @emph{Description}:
1545 @code{BESSEL_J1(X)} computes the Bessel function of the first kind of
1546 order 1 of @var{X}. This function is available under the name
1547 @code{BESJ1} as a GNU extension.
1549 @item @emph{Standard}:
1555 @item @emph{Syntax}:
1556 @code{RESULT = BESSEL_J1(X)}
1558 @item @emph{Arguments}:
1559 @multitable @columnfractions .15 .70
1560 @item @var{X} @tab The type shall be @code{REAL(*)}, and it shall be scalar.
1563 @item @emph{Return value}:
1564 The return value is of type @code{REAL(*)} and it lies in the
1565 range @math{ - 0.5818... \leq Bessel (0,x) \leq 0.5818 }.
1567 @item @emph{Example}:
1570 real(8) :: x = 1.0_8
1572 end program test_besj1
1575 @item @emph{Specific names}:
1576 @multitable @columnfractions .20 .20 .20 .25
1577 @item Name @tab Argument @tab Return type @tab Standard
1578 @item @code{DBESJ1(X)}@tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU extension
1585 @section @code{BESSEL_JN} --- Bessel function of the first kind
1589 @cindex Bessel function, first kind
1592 @item @emph{Description}:
1593 @code{BESSEL_JN(N, X)} computes the Bessel function of the first kind of
1594 order @var{N} of @var{X}. This function is available under the name
1595 @code{BESJN} as a GNU extension.
1597 If both arguments are arrays, their ranks and shapes shall conform.
1599 @item @emph{Standard}:
1600 Fortran 2008 and later
1605 @item @emph{Syntax}:
1606 @code{RESULT = BESSEL_JN(N, X)}
1608 @item @emph{Arguments}:
1609 @multitable @columnfractions .15 .70
1610 @item @var{N} @tab Shall be a scalar or an array of type @code{INTEGER(*)}.
1611 @item @var{X} @tab Shall be a scalar or an array of type @code{REAL(*)}.
1614 @item @emph{Return value}:
1615 The return value is a scalar of type @code{REAL(*)}.
1617 @item @emph{Example}:
1620 real(8) :: x = 1.0_8
1622 end program test_besjn
1625 @item @emph{Specific names}:
1626 @multitable @columnfractions .20 .20 .20 .25
1627 @item Name @tab Argument @tab Return type @tab Standard
1628 @item @code{DBESJN(X)} @tab @code{INTEGER(*) N} @tab @code{REAL(8)} @tab GNU extension
1629 @item @tab @code{REAL(8) X} @tab @tab
1636 @section @code{BESSEL_Y0} --- Bessel function of the second kind of order 0
1640 @cindex Bessel function, second kind
1643 @item @emph{Description}:
1644 @code{BESSEL_Y0(X)} computes the Bessel function of the second kind of
1645 order 0 of @var{X}. This function is available under the name
1646 @code{BESY0} as a GNU extension.
1648 @item @emph{Standard}:
1649 Fortran 2008 and later
1654 @item @emph{Syntax}:
1655 @code{RESULT = BESSEL_Y0(X)}
1657 @item @emph{Arguments}:
1658 @multitable @columnfractions .15 .70
1659 @item @var{X} @tab The type shall be @code{REAL(*)}, and it shall be scalar.
1662 @item @emph{Return value}:
1663 The return value is a scalar of type @code{REAL(*)}.
1665 @item @emph{Example}:
1668 real(8) :: x = 0.0_8
1670 end program test_besy0
1673 @item @emph{Specific names}:
1674 @multitable @columnfractions .20 .20 .20 .25
1675 @item Name @tab Argument @tab Return type @tab Standard
1676 @item @code{DBESY0(X)}@tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU extension
1683 @section @code{BESSEL_Y1} --- Bessel function of the second kind of order 1
1687 @cindex Bessel function, second kind
1690 @item @emph{Description}:
1691 @code{BESSEL_Y1(X)} computes the Bessel function of the second kind of
1692 order 1 of @var{X}. This function is available under the name
1693 @code{BESY1} as a GNU extension.
1695 @item @emph{Standard}:
1696 Fortran 2008 and later
1701 @item @emph{Syntax}:
1702 @code{RESULT = BESSEL_Y1(X)}
1704 @item @emph{Arguments}:
1705 @multitable @columnfractions .15 .70
1706 @item @var{X} @tab The type shall be @code{REAL(*)}, and it shall be scalar.
1709 @item @emph{Return value}:
1710 The return value is a scalar of type @code{REAL(*)}.
1712 @item @emph{Example}:
1715 real(8) :: x = 1.0_8
1717 end program test_besy1
1720 @item @emph{Specific names}:
1721 @multitable @columnfractions .20 .20 .20 .25
1722 @item Name @tab Argument @tab Return type @tab Standard
1723 @item @code{DBESY1(X)}@tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU extension
1730 @section @code{BESSEL_YN} --- Bessel function of the second kind
1734 @cindex Bessel function, second kind
1737 @item @emph{Description}:
1738 @code{BESSEL_YN(N, X)} computes the Bessel function of the second kind of
1739 order @var{N} of @var{X}. This function is available under the name
1740 @code{BESYN} as a GNU extension.
1742 If both arguments are arrays, their ranks and shapes shall conform.
1744 @item @emph{Standard}:
1745 Fortran 2008 and later
1750 @item @emph{Syntax}:
1751 @code{RESULT = BESSEL_YN(N, X)}
1753 @item @emph{Arguments}:
1754 @multitable @columnfractions .15 .70
1755 @item @var{N} @tab Shall be a scalar or an array of type @code{INTEGER(*)}.
1756 @item @var{X} @tab Shall be a scalar or an array of type @code{REAL(*)}.
1759 @item @emph{Return value}:
1760 The return value is a scalar of type @code{REAL(*)}.
1762 @item @emph{Example}:
1765 real(8) :: x = 1.0_8
1767 end program test_besyn
1770 @item @emph{Specific names}:
1771 @multitable @columnfractions .20 .20 .20 .25
1772 @item Name @tab Argument @tab Return type @tab Standard
1773 @item @code{DBESYN(N,X)} @tab @code{INTEGER(*) N} @tab @code{REAL(8)} @tab GNU extension
1774 @item @tab @code{REAL(8) X} @tab @tab
1781 @section @code{BIT_SIZE} --- Bit size inquiry function
1783 @cindex bits, number of
1784 @cindex size of a variable, in bits
1787 @item @emph{Description}:
1788 @code{BIT_SIZE(I)} returns the number of bits (integer precision plus sign bit)
1789 represented by the type of @var{I}.
1791 @item @emph{Standard}:
1797 @item @emph{Syntax}:
1798 @code{RESULT = BIT_SIZE(I)}
1800 @item @emph{Arguments}:
1801 @multitable @columnfractions .15 .70
1802 @item @var{I} @tab The type shall be @code{INTEGER(*)}.
1805 @item @emph{Return value}:
1806 The return value is of type @code{INTEGER(*)}
1808 @item @emph{Example}:
1810 program test_bit_size
1815 end program test_bit_size
1822 @section @code{BTEST} --- Bit test function
1824 @cindex bits, testing
1827 @item @emph{Description}:
1828 @code{BTEST(I,POS)} returns logical @code{.TRUE.} if the bit at @var{POS}
1831 @item @emph{Standard}:
1837 @item @emph{Syntax}:
1838 @code{RESULT = BTEST(I, POS)}
1840 @item @emph{Arguments}:
1841 @multitable @columnfractions .15 .70
1842 @item @var{I} @tab The type shall be @code{INTEGER(*)}.
1843 @item @var{POS} @tab The type shall be @code{INTEGER(*)}.
1846 @item @emph{Return value}:
1847 The return value is of type @code{LOGICAL}
1849 @item @emph{Example}:
1852 integer :: i = 32768 + 1024 + 64
1856 bool = btest(i, pos)
1859 end program test_btest
1865 @section @code{C_ASSOCIATED} --- Status of a C pointer
1866 @fnindex C_ASSOCIATED
1867 @cindex association status, C pointer
1868 @cindex pointer, C association status
1871 @item @emph{Description}:
1872 @code{C_ASSOCIATED(c_prt1[, c_ptr2])} determines the status of the C pointer @var{c_ptr1}
1873 or if @var{c_ptr1} is associated with the target @var{c_ptr2}.
1875 @item @emph{Standard}:
1876 Fortran 2003 and later
1881 @item @emph{Syntax}:
1882 @code{RESULT = C_ASSOCIATED(c_prt1[, c_ptr2])}
1884 @item @emph{Arguments}:
1885 @multitable @columnfractions .15 .70
1886 @item @var{c_ptr1} @tab Scalar of the type @code{C_PTR} or @code{C_FUNPTR}.
1887 @item @var{c_ptr2} @tab (Optional) Scalar of the same type as @var{c_ptr1}.
1890 @item @emph{Return value}:
1891 The return value is of type @code{LOGICAL}; it is @code{.false.} if either
1892 @var{c_ptr1} is a C NULL pointer or if @var{c_ptr1} and @var{c_ptr2}
1893 point to different addresses.
1895 @item @emph{Example}:
1897 subroutine association_test(a,b)
1898 use iso_c_binding, only: c_associated, c_loc, c_ptr
1902 if(c_associated(b, c_loc(a))) &
1903 stop 'b and a do not point to same target'
1904 end subroutine association_test
1907 @item @emph{See also}:
1908 @ref{C_LOC}, @ref{C_FUNLOC}
1913 @section @code{C_FUNLOC} --- Obtain the C address of a procedure
1915 @cindex pointer, C address of procedures
1918 @item @emph{Description}:
1919 @code{C_FUNLOC(x)} determines the C address of the argument.
1921 @item @emph{Standard}:
1922 Fortran 2003 and later
1927 @item @emph{Syntax}:
1928 @code{RESULT = C_FUNLOC(x)}
1930 @item @emph{Arguments}:
1931 @multitable @columnfractions .15 .70
1932 @item @var{x} @tab Interoperable function or pointer to such function.
1935 @item @emph{Return value}:
1936 The return value is of type @code{C_FUNPTR} and contains the C address
1939 @item @emph{Example}:
1945 subroutine sub(a) bind(c)
1955 subroutine my_routine(p) bind(c,name='myC_func')
1957 type(c_funptr), intent(in) :: p
1960 call my_routine(c_funloc(sub))
1964 @item @emph{See also}:
1965 @ref{C_ASSOCIATED}, @ref{C_LOC}, @ref{C_F_POINTER}, @ref{C_F_PROCPOINTER}
1969 @node C_F_PROCPOINTER
1970 @section @code{C_F_PROCPOINTER} --- Convert C into Fortran procedure pointer
1971 @fnindex C_F_PROCPOINTER
1972 @cindex pointer, C address of pointers
1975 @item @emph{Description}:
1976 @code{C_F_PROCPOINTER(cptr, fptr)} Assign the target of the C function pointer
1977 @var{cptr} to the Fortran procedure pointer @var{fptr}.
1979 Note: Due to the currently lacking support of procedure pointers in GNU Fortran
1980 this function is not fully operable.
1982 @item @emph{Standard}:
1983 Fortran 2003 and later
1988 @item @emph{Syntax}:
1989 @code{CALL C_F_PROCPOINTER(cptr, fptr)}
1991 @item @emph{Arguments}:
1992 @multitable @columnfractions .15 .70
1993 @item @var{cptr} @tab scalar of the type @code{C_FUNPTR}. It is
1995 @item @var{fptr} @tab procedure pointer interoperable with @var{cptr}. It is
1999 @item @emph{Example}:
2007 real(c_float), intent(in) :: a
2008 real(c_float) :: func
2012 function getIterFunc() bind(c,name="getIterFunc")
2014 type(c_funptr) :: getIterFunc
2017 type(c_funptr) :: cfunptr
2018 procedure(func), pointer :: myFunc
2019 cfunptr = getIterFunc()
2020 call c_f_procpointer(cfunptr, myFunc)
2024 @item @emph{See also}:
2025 @ref{C_LOC}, @ref{C_F_POINTER}
2030 @section @code{C_F_POINTER} --- Convert C into Fortran pointer
2031 @fnindex C_F_POINTER
2032 @cindex pointer, convert C to Fortran
2035 @item @emph{Description}:
2036 @code{C_F_POINTER(cptr, fptr[, shape])} Assign the target the C pointer
2037 @var{cptr} to the Fortran pointer @var{fptr} and specify its
2040 @item @emph{Standard}:
2041 Fortran 2003 and later
2046 @item @emph{Syntax}:
2047 @code{CALL C_F_POINTER(cptr, fptr[, shape])}
2049 @item @emph{Arguments}:
2050 @multitable @columnfractions .15 .70
2051 @item @var{cptr} @tab scalar of the type @code{C_PTR}. It is
2053 @item @var{fptr} @tab pointer interoperable with @var{cptr}. It is
2055 @item @var{shape} @tab (Optional) Rank-one array of type @code{INTEGER}
2056 with @code{INTENT(IN)}. It shall be present
2057 if and only if @var{fptr} is an array. The size
2058 must be equal to the rank of @var{fptr}.
2061 @item @emph{Example}:
2067 subroutine my_routine(p) bind(c,name='myC_func')
2069 type(c_ptr), intent(out) :: p
2073 real,pointer :: a(:)
2074 call my_routine(cptr)
2075 call c_f_pointer(cptr, a, [12])
2079 @item @emph{See also}:
2080 @ref{C_LOC}, @ref{C_F_PROCPOINTER}
2085 @section @code{C_LOC} --- Obtain the C address of an object
2087 @cindex procedure pointer, convert C to Fortran
2090 @item @emph{Description}:
2091 @code{C_LOC(x)} determines the C address of the argument.
2093 @item @emph{Standard}:
2094 Fortran 2003 and later
2099 @item @emph{Syntax}:
2100 @code{RESULT = C_LOC(x)}
2102 @item @emph{Arguments}:
2103 @multitable @columnfractions .15 .70
2104 @item @var{x} @tab Associated scalar pointer or interoperable scalar
2105 or allocated allocatable variable with @code{TARGET}
2109 @item @emph{Return value}:
2110 The return value is of type @code{C_PTR} and contains the C address
2113 @item @emph{Example}:
2115 subroutine association_test(a,b)
2116 use iso_c_binding, only: c_associated, c_loc, c_ptr
2120 if(c_associated(b, c_loc(a))) &
2121 stop 'b and a do not point to same target'
2122 end subroutine association_test
2125 @item @emph{See also}:
2126 @ref{C_ASSOCIATED}, @ref{C_FUNLOC}, @ref{C_F_POINTER}, @ref{C_F_PROCPOINTER}
2131 @section @code{CEILING} --- Integer ceiling function
2134 @cindex rounding, ceiling
2137 @item @emph{Description}:
2138 @code{CEILING(X)} returns the least integer greater than or equal to @var{X}.
2140 @item @emph{Standard}:
2146 @item @emph{Syntax}:
2147 @code{RESULT = CEILING(X [, KIND])}
2149 @item @emph{Arguments}:
2150 @multitable @columnfractions .15 .70
2151 @item @var{X} @tab The type shall be @code{REAL(*)}.
2152 @item @var{KIND} @tab (Optional) An @code{INTEGER(*)} initialization
2153 expression indicating the kind parameter of
2157 @item @emph{Return value}:
2158 The return value is of type @code{INTEGER(KIND)}
2160 @item @emph{Example}:
2162 program test_ceiling
2165 print *, ceiling(x) ! returns 64
2166 print *, ceiling(y) ! returns -63
2167 end program test_ceiling
2170 @item @emph{See also}:
2171 @ref{FLOOR}, @ref{NINT}
2178 @section @code{CHAR} --- Character conversion function
2180 @cindex conversion, to character
2183 @item @emph{Description}:
2184 @code{CHAR(I [, KIND])} returns the character represented by the integer @var{I}.
2186 @item @emph{Standard}:
2192 @item @emph{Syntax}:
2193 @code{RESULT = CHAR(I [, KIND])}
2195 @item @emph{Arguments}:
2196 @multitable @columnfractions .15 .70
2197 @item @var{I} @tab The type shall be @code{INTEGER(*)}.
2198 @item @var{KIND} @tab (Optional) An @code{INTEGER(*)} initialization
2199 expression indicating the kind parameter of
2203 @item @emph{Return value}:
2204 The return value is of type @code{CHARACTER(1)}
2206 @item @emph{Example}:
2212 print *, i, c ! returns 'J'
2213 end program test_char
2217 See @ref{ICHAR} for a discussion of converting between numerical values
2218 and formatted string representations.
2220 @item @emph{See also}:
2221 @ref{ACHAR}, @ref{IACHAR}, @ref{ICHAR}
2228 @section @code{CHDIR} --- Change working directory
2230 @cindex system, working directory
2233 @item @emph{Description}:
2234 Change current working directory to a specified path.
2236 This intrinsic is provided in both subroutine and function forms; however,
2237 only one form can be used in any given program unit.
2239 @item @emph{Standard}:
2243 Subroutine, function
2245 @item @emph{Syntax}:
2246 @multitable @columnfractions .80
2247 @item @code{CALL CHDIR(NAME [, STATUS])}
2248 @item @code{STATUS = CHDIR(NAME)}
2251 @item @emph{Arguments}:
2252 @multitable @columnfractions .15 .70
2253 @item @var{NAME} @tab The type shall be @code{CHARACTER(*)} and shall
2254 specify a valid path within the file system.
2255 @item @var{STATUS} @tab (Optional) @code{INTEGER} status flag of the default
2256 kind. Returns 0 on success, and a system specific
2257 and nonzero error code otherwise.
2260 @item @emph{Example}:
2263 CHARACTER(len=255) :: path
2265 WRITE(*,*) TRIM(path)
2268 WRITE(*,*) TRIM(path)
2272 @item @emph{See also}:
2279 @section @code{CHMOD} --- Change access permissions of files
2281 @cindex file system, change access mode
2284 @item @emph{Description}:
2285 @code{CHMOD} changes the permissions of a file. This function invokes
2286 @code{/bin/chmod} and might therefore not work on all platforms.
2288 This intrinsic is provided in both subroutine and function forms; however,
2289 only one form can be used in any given program unit.
2291 @item @emph{Standard}:
2295 Subroutine, function
2297 @item @emph{Syntax}:
2298 @multitable @columnfractions .80
2299 @item @code{CALL CHMOD(NAME, MODE[, STATUS])}
2300 @item @code{STATUS = CHMOD(NAME, MODE)}
2303 @item @emph{Arguments}:
2304 @multitable @columnfractions .15 .70
2305 @item @var{NAME} @tab Scalar @code{CHARACTER} with the file name.
2306 Trailing blanks are ignored unless the character @code{achar(0)} is
2307 present, then all characters up to and excluding @code{achar(0)} are
2308 used as the file name.
2310 @item @var{MODE} @tab Scalar @code{CHARACTER} giving the file permission.
2311 @var{MODE} uses the same syntax as the @var{MODE} argument of
2314 @item @var{STATUS} @tab (optional) scalar @code{INTEGER}, which is
2315 @code{0} on success and nonzero otherwise.
2318 @item @emph{Return value}:
2319 In either syntax, @var{STATUS} is set to @code{0} on success and nonzero
2322 @item @emph{Example}:
2323 @code{CHMOD} as subroutine
2328 call chmod('test.dat','u+x',status)
2329 print *, 'Status: ', status
2330 end program chmod_test
2332 @code{CHMOD} as function:
2337 status = chmod('test.dat','u+x')
2338 print *, 'Status: ', status
2339 end program chmod_test
2347 @section @code{CMPLX} --- Complex conversion function
2349 @cindex complex numbers, conversion to
2350 @cindex conversion, to complex
2353 @item @emph{Description}:
2354 @code{CMPLX(X [, Y [, KIND]])} returns a complex number where @var{X} is converted to
2355 the real component. If @var{Y} is present it is converted to the imaginary
2356 component. If @var{Y} is not present then the imaginary component is set to
2357 0.0. If @var{X} is complex then @var{Y} must not be present.
2359 @item @emph{Standard}:
2365 @item @emph{Syntax}:
2366 @code{RESULT = CMPLX(X [, Y [, KIND]])}
2368 @item @emph{Arguments}:
2369 @multitable @columnfractions .15 .70
2370 @item @var{X} @tab The type may be @code{INTEGER(*)}, @code{REAL(*)},
2371 or @code{COMPLEX(*)}.
2372 @item @var{Y} @tab (Optional; only allowed if @var{X} is not
2373 @code{COMPLEX(*)}.) May be @code{INTEGER(*)}
2375 @item @var{KIND} @tab (Optional) An @code{INTEGER(*)} initialization
2376 expression indicating the kind parameter of
2380 @item @emph{Return value}:
2381 The return value is of @code{COMPLEX} type, with a kind equal to
2382 @var{KIND} if it is specified. If @var{KIND} is not specified, the
2383 result is of the default @code{COMPLEX} kind, regardless of the kinds of
2384 @var{X} and @var{Y}.
2386 @item @emph{Example}:
2393 print *, z, cmplx(x)
2394 end program test_cmplx
2397 @item @emph{See also}:
2403 @node COMMAND_ARGUMENT_COUNT
2404 @section @code{COMMAND_ARGUMENT_COUNT} --- Get number of command line arguments
2405 @fnindex COMMAND_ARGUMENT_COUNT
2406 @cindex command-line arguments
2407 @cindex command-line arguments, number of
2408 @cindex arguments, to program
2411 @item @emph{Description}:
2412 @code{COMMAND_ARGUMENT_COUNT()} returns the number of arguments passed on the
2413 command line when the containing program was invoked.
2415 @item @emph{Standard}:
2416 Fortran 2003 and later
2421 @item @emph{Syntax}:
2422 @code{RESULT = COMMAND_ARGUMENT_COUNT()}
2424 @item @emph{Arguments}:
2425 @multitable @columnfractions .15 .70
2429 @item @emph{Return value}:
2430 The return value is of type @code{INTEGER(4)}
2432 @item @emph{Example}:
2434 program test_command_argument_count
2436 count = command_argument_count()
2438 end program test_command_argument_count
2441 @item @emph{See also}:
2442 @ref{GET_COMMAND}, @ref{GET_COMMAND_ARGUMENT}
2448 @section @code{COMPLEX} --- Complex conversion function
2450 @cindex complex numbers, conversion to
2451 @cindex conversion, to complex
2454 @item @emph{Description}:
2455 @code{COMPLEX(X, Y)} returns a complex number where @var{X} is converted
2456 to the real component and @var{Y} is converted to the imaginary
2459 @item @emph{Standard}:
2465 @item @emph{Syntax}:
2466 @code{RESULT = COMPLEX(X, Y)}
2468 @item @emph{Arguments}:
2469 @multitable @columnfractions .15 .70
2470 @item @var{X} @tab The type may be @code{INTEGER(*)} or @code{REAL(*)}.
2471 @item @var{Y} @tab The type may be @code{INTEGER(*)} or @code{REAL(*)}.
2474 @item @emph{Return value}:
2475 If @var{X} and @var{Y} are both of @code{INTEGER} type, then the return
2476 value is of default @code{COMPLEX} type.
2478 If @var{X} and @var{Y} are of @code{REAL} type, or one is of @code{REAL}
2479 type and one is of @code{INTEGER} type, then the return value is of
2480 @code{COMPLEX} type with a kind equal to that of the @code{REAL}
2481 argument with the highest precision.
2483 @item @emph{Example}:
2485 program test_complex
2488 print *, complex(i, x)
2489 end program test_complex
2492 @item @emph{See also}:
2499 @section @code{CONJG} --- Complex conjugate function
2502 @cindex complex conjugate
2505 @item @emph{Description}:
2506 @code{CONJG(Z)} returns the conjugate of @var{Z}. If @var{Z} is @code{(x, y)}
2507 then the result is @code{(x, -y)}
2509 @item @emph{Standard}:
2510 F77 and later, has overloads that are GNU extensions
2515 @item @emph{Syntax}:
2518 @item @emph{Arguments}:
2519 @multitable @columnfractions .15 .70
2520 @item @var{Z} @tab The type shall be @code{COMPLEX(*)}.
2523 @item @emph{Return value}:
2524 The return value is of type @code{COMPLEX(*)}.
2526 @item @emph{Example}:
2529 complex :: z = (2.0, 3.0)
2530 complex(8) :: dz = (2.71_8, -3.14_8)
2535 end program test_conjg
2538 @item @emph{Specific names}:
2539 @multitable @columnfractions .20 .20 .20 .25
2540 @item Name @tab Argument @tab Return type @tab Standard
2541 @item @code{DCONJG(Z)} @tab @code{COMPLEX(8) Z} @tab @code{COMPLEX(8)} @tab GNU extension
2548 @section @code{COS} --- Cosine function
2554 @cindex trigonometric function, cosine
2558 @item @emph{Description}:
2559 @code{COS(X)} computes the cosine of @var{X}.
2561 @item @emph{Standard}:
2562 F77 and later, has overloads that are GNU extensions
2567 @item @emph{Syntax}:
2568 @code{RESULT = COS(X)}
2570 @item @emph{Arguments}:
2571 @multitable @columnfractions .15 .70
2572 @item @var{X} @tab The type shall be @code{REAL(*)} or
2576 @item @emph{Return value}:
2577 The return value is of type @code{REAL(*)} and it lies in the
2578 range @math{ -1 \leq \cos (x) \leq 1}. The kind type
2579 parameter is the same as @var{X}.
2581 @item @emph{Example}:
2586 end program test_cos
2589 @item @emph{Specific names}:
2590 @multitable @columnfractions .20 .20 .20 .25
2591 @item Name @tab Argument @tab Return type @tab Standard
2592 @item @code{DCOS(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab F77 and later
2593 @item @code{CCOS(X)} @tab @code{COMPLEX(4) X} @tab @code{COMPLEX(4)} @tab F77 and later
2594 @item @code{ZCOS(X)} @tab @code{COMPLEX(8) X} @tab @code{COMPLEX(8)} @tab GNU extension
2595 @item @code{CDCOS(X)} @tab @code{COMPLEX(8) X} @tab @code{COMPLEX(8)} @tab GNU extension
2598 @item @emph{See also}:
2599 Inverse function: @ref{ACOS}
2606 @section @code{COSH} --- Hyperbolic cosine function
2609 @cindex hyperbolic cosine
2610 @cindex hyperbolic function, cosine
2611 @cindex cosine, hyperbolic
2614 @item @emph{Description}:
2615 @code{COSH(X)} computes the hyperbolic cosine of @var{X}.
2617 @item @emph{Standard}:
2623 @item @emph{Syntax}:
2626 @item @emph{Arguments}:
2627 @multitable @columnfractions .15 .70
2628 @item @var{X} @tab The type shall be @code{REAL(*)}.
2631 @item @emph{Return value}:
2632 The return value is of type @code{REAL(*)} and it is positive
2633 (@math{ \cosh (x) \geq 0 }.
2635 @item @emph{Example}:
2638 real(8) :: x = 1.0_8
2640 end program test_cosh
2643 @item @emph{Specific names}:
2644 @multitable @columnfractions .20 .20 .20 .25
2645 @item Name @tab Argument @tab Return type @tab Standard
2646 @item @code{DCOSH(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab F77 and later
2649 @item @emph{See also}:
2650 Inverse function: @ref{ACOSH}
2657 @section @code{COUNT} --- Count function
2659 @cindex array, conditionally count elements
2660 @cindex array, element counting
2661 @cindex array, number of elements
2664 @item @emph{Description}:
2666 @code{COUNT(MASK [, DIM [, KIND]])} counts the number of @code{.TRUE.}
2667 elements of @var{MASK} along the dimension of @var{DIM}. If @var{DIM} is
2668 omitted it is taken to be @code{1}. @var{DIM} is a scaler of type
2669 @code{INTEGER} in the range of @math{1 /leq DIM /leq n)} where @math{n}
2670 is the rank of @var{MASK}.
2672 @item @emph{Standard}:
2676 Transformational function
2678 @item @emph{Syntax}:
2679 @code{RESULT = COUNT(MASK [, DIM [, KIND]])}
2681 @item @emph{Arguments}:
2682 @multitable @columnfractions .15 .70
2683 @item @var{MASK} @tab The type shall be @code{LOGICAL}.
2684 @item @var{DIM} @tab (Optional) The type shall be @code{INTEGER}.
2685 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
2686 expression indicating the kind parameter of
2690 @item @emph{Return value}:
2691 The return value is of type @code{INTEGER} and of kind @var{KIND}. If
2692 @var{KIND} is absent, the return value is of default integer kind.
2693 The result has a rank equal to that of @var{MASK}.
2695 @item @emph{Example}:
2698 integer, dimension(2,3) :: a, b
2699 logical, dimension(2,3) :: mask
2700 a = reshape( (/ 1, 2, 3, 4, 5, 6 /), (/ 2, 3 /))
2701 b = reshape( (/ 0, 7, 3, 4, 5, 8 /), (/ 2, 3 /))
2702 print '(3i3)', a(1,:)
2703 print '(3i3)', a(2,:)
2705 print '(3i3)', b(1,:)
2706 print '(3i3)', b(2,:)
2709 print '(3l3)', mask(1,:)
2710 print '(3l3)', mask(2,:)
2712 print '(3i3)', count(mask)
2714 print '(3i3)', count(mask, 1)
2716 print '(3i3)', count(mask, 2)
2717 end program test_count
2724 @section @code{CPU_TIME} --- CPU elapsed time in seconds
2726 @cindex time, elapsed
2729 @item @emph{Description}:
2730 Returns a @code{REAL(*)} value representing the elapsed CPU time in
2731 seconds. This is useful for testing segments of code to determine
2734 If a time source is available, time will be reported with microsecond
2735 resolution. If no time source is available, @var{TIME} is set to
2738 Note that @var{TIME} may contain a, system dependent, arbitrary offset
2739 and may not start with @code{0.0}. For @code{CPU_TIME}, the absolute
2740 value is meaningless, only differences between subsequent calls to
2741 this subroutine, as shown in the example below, should be used.
2744 @item @emph{Standard}:
2750 @item @emph{Syntax}:
2751 @code{CALL CPU_TIME(TIME)}
2753 @item @emph{Arguments}:
2754 @multitable @columnfractions .15 .70
2755 @item @var{TIME} @tab The type shall be @code{REAL(*)} with @code{INTENT(OUT)}.
2758 @item @emph{Return value}:
2761 @item @emph{Example}:
2763 program test_cpu_time
2764 real :: start, finish
2765 call cpu_time(start)
2766 ! put code to test here
2767 call cpu_time(finish)
2768 print '("Time = ",f6.3," seconds.")',finish-start
2769 end program test_cpu_time
2772 @item @emph{See also}:
2773 @ref{SYSTEM_CLOCK}, @ref{DATE_AND_TIME}
2779 @section @code{CSHIFT} --- Circular shift elements of an array
2781 @cindex array, shift circularly
2782 @cindex array, permutation
2783 @cindex array, rotate
2786 @item @emph{Description}:
2787 @code{CSHIFT(ARRAY, SHIFT [, DIM])} performs a circular shift on elements of
2788 @var{ARRAY} along the dimension of @var{DIM}. If @var{DIM} is omitted it is
2789 taken to be @code{1}. @var{DIM} is a scaler of type @code{INTEGER} in the
2790 range of @math{1 /leq DIM /leq n)} where @math{n} is the rank of @var{ARRAY}.
2791 If the rank of @var{ARRAY} is one, then all elements of @var{ARRAY} are shifted
2792 by @var{SHIFT} places. If rank is greater than one, then all complete rank one
2793 sections of @var{ARRAY} along the given dimension are shifted. Elements
2794 shifted out one end of each rank one section are shifted back in the other end.
2796 @item @emph{Standard}:
2800 Transformational function
2802 @item @emph{Syntax}:
2803 @code{RESULT = CSHIFT(ARRAY, SHIFT [, DIM])}
2805 @item @emph{Arguments}:
2806 @multitable @columnfractions .15 .70
2807 @item @var{ARRAY} @tab Shall be an array of any type.
2808 @item @var{SHIFT} @tab The type shall be @code{INTEGER}.
2809 @item @var{DIM} @tab The type shall be @code{INTEGER}.
2812 @item @emph{Return value}:
2813 Returns an array of same type and rank as the @var{ARRAY} argument.
2815 @item @emph{Example}:
2818 integer, dimension(3,3) :: a
2819 a = reshape( (/ 1, 2, 3, 4, 5, 6, 7, 8, 9 /), (/ 3, 3 /))
2820 print '(3i3)', a(1,:)
2821 print '(3i3)', a(2,:)
2822 print '(3i3)', a(3,:)
2823 a = cshift(a, SHIFT=(/1, 2, -1/), DIM=2)
2825 print '(3i3)', a(1,:)
2826 print '(3i3)', a(2,:)
2827 print '(3i3)', a(3,:)
2828 end program test_cshift
2835 @section @code{CTIME} --- Convert a time into a string
2837 @cindex time, conversion to string
2838 @cindex conversion, to string
2841 @item @emph{Description}:
2842 @code{CTIME} converts a system time value, such as returned by
2843 @code{TIME8()}, to a string of the form @samp{Sat Aug 19 18:13:14 1995}.
2845 This intrinsic is provided in both subroutine and function forms; however,
2846 only one form can be used in any given program unit.
2848 @item @emph{Standard}:
2852 Subroutine, function
2854 @item @emph{Syntax}:
2855 @multitable @columnfractions .80
2856 @item @code{CALL CTIME(TIME, RESULT)}.
2857 @item @code{RESULT = CTIME(TIME)}, (not recommended).
2860 @item @emph{Arguments}:
2861 @multitable @columnfractions .15 .70
2862 @item @var{TIME} @tab The type shall be of type @code{INTEGER(KIND=8)}.
2863 @item @var{RESULT} @tab The type shall be of type @code{CHARACTER}.
2866 @item @emph{Return value}:
2867 The converted date and time as a string.
2869 @item @emph{Example}:
2873 character(len=30) :: date
2876 ! Do something, main part of the program
2879 print *, 'Program was started on ', date
2880 end program test_ctime
2883 @item @emph{See Also}:
2884 @ref{GMTIME}, @ref{LTIME}, @ref{TIME}, @ref{TIME8}
2890 @section @code{DATE_AND_TIME} --- Date and time subroutine
2891 @fnindex DATE_AND_TIME
2892 @cindex date, current
2893 @cindex current date
2894 @cindex time, current
2895 @cindex current time
2898 @item @emph{Description}:
2899 @code{DATE_AND_TIME(DATE, TIME, ZONE, VALUES)} gets the corresponding date and
2900 time information from the real-time system clock. @var{DATE} is
2901 @code{INTENT(OUT)} and has form ccyymmdd. @var{TIME} is @code{INTENT(OUT)} and
2902 has form hhmmss.sss. @var{ZONE} is @code{INTENT(OUT)} and has form (+-)hhmm,
2903 representing the difference with respect to Coordinated Universal Time (UTC).
2904 Unavailable time and date parameters return blanks.
2906 @var{VALUES} is @code{INTENT(OUT)} and provides the following:
2908 @multitable @columnfractions .15 .30 .40
2909 @item @tab @code{VALUE(1)}: @tab The year
2910 @item @tab @code{VALUE(2)}: @tab The month
2911 @item @tab @code{VALUE(3)}: @tab The day of the month
2912 @item @tab @code{VALUE(4)}: @tab Time difference with UTC in minutes
2913 @item @tab @code{VALUE(5)}: @tab The hour of the day
2914 @item @tab @code{VALUE(6)}: @tab The minutes of the hour
2915 @item @tab @code{VALUE(7)}: @tab The seconds of the minute
2916 @item @tab @code{VALUE(8)}: @tab The milliseconds of the second
2919 @item @emph{Standard}:
2925 @item @emph{Syntax}:
2926 @code{CALL DATE_AND_TIME([DATE, TIME, ZONE, VALUES])}
2928 @item @emph{Arguments}:
2929 @multitable @columnfractions .15 .70
2930 @item @var{DATE} @tab (Optional) The type shall be @code{CHARACTER(8)} or larger.
2931 @item @var{TIME} @tab (Optional) The type shall be @code{CHARACTER(10)} or larger.
2932 @item @var{ZONE} @tab (Optional) The type shall be @code{CHARACTER(5)} or larger.
2933 @item @var{VALUES}@tab (Optional) The type shall be @code{INTEGER(8)}.
2936 @item @emph{Return value}:
2939 @item @emph{Example}:
2941 program test_time_and_date
2942 character(8) :: date
2943 character(10) :: time
2944 character(5) :: zone
2945 integer,dimension(8) :: values
2946 ! using keyword arguments
2947 call date_and_time(date,time,zone,values)
2948 call date_and_time(DATE=date,ZONE=zone)
2949 call date_and_time(TIME=time)
2950 call date_and_time(VALUES=values)
2951 print '(a,2x,a,2x,a)', date, time, zone
2952 print '(8i5))', values
2953 end program test_time_and_date
2956 @item @emph{See also}:
2957 @ref{CPU_TIME}, @ref{SYSTEM_CLOCK}
2963 @section @code{DBLE} --- Double conversion function
2965 @cindex conversion, to real
2968 @item @emph{Description}:
2969 @code{DBLE(X)} Converts @var{X} to double precision real type.
2971 @item @emph{Standard}:
2977 @item @emph{Syntax}:
2978 @code{RESULT = DBLE(X)}
2980 @item @emph{Arguments}:
2981 @multitable @columnfractions .15 .70
2982 @item @var{X} @tab The type shall be @code{INTEGER(*)}, @code{REAL(*)},
2983 or @code{COMPLEX(*)}.
2986 @item @emph{Return value}:
2987 The return value is of type double precision real.
2989 @item @emph{Example}:
2994 complex :: z = (2.3,1.14)
2995 print *, dble(x), dble(i), dble(z)
2996 end program test_dble
2999 @item @emph{See also}:
3000 @ref{DFLOAT}, @ref{FLOAT}, @ref{REAL}
3006 @section @code{DCMPLX} --- Double complex conversion function
3008 @cindex complex numbers, conversion to
3009 @cindex conversion, to complex
3012 @item @emph{Description}:
3013 @code{DCMPLX(X [,Y])} returns a double complex number where @var{X} is
3014 converted to the real component. If @var{Y} is present it is converted to the
3015 imaginary component. If @var{Y} is not present then the imaginary component is
3016 set to 0.0. If @var{X} is complex then @var{Y} must not be present.
3018 @item @emph{Standard}:
3024 @item @emph{Syntax}:
3025 @code{RESULT = DCMPLX(X [, Y])}
3027 @item @emph{Arguments}:
3028 @multitable @columnfractions .15 .70
3029 @item @var{X} @tab The type may be @code{INTEGER(*)}, @code{REAL(*)},
3030 or @code{COMPLEX(*)}.
3031 @item @var{Y} @tab (Optional if @var{X} is not @code{COMPLEX(*)}.) May be
3032 @code{INTEGER(*)} or @code{REAL(*)}.
3035 @item @emph{Return value}:
3036 The return value is of type @code{COMPLEX(8)}
3038 @item @emph{Example}:
3048 print *, dcmplx(x,i)
3049 end program test_dcmplx
3056 @section @code{DFLOAT} --- Double conversion function
3058 @cindex conversion, to real
3061 @item @emph{Description}:
3062 @code{DFLOAT(X)} Converts @var{X} to double precision real type.
3064 @item @emph{Standard}:
3070 @item @emph{Syntax}:
3071 @code{RESULT = DFLOAT(X)}
3073 @item @emph{Arguments}:
3074 @multitable @columnfractions .15 .70
3075 @item @var{X} @tab The type shall be @code{INTEGER(*)}.
3078 @item @emph{Return value}:
3079 The return value is of type double precision real.
3081 @item @emph{Example}:
3086 end program test_dfloat
3089 @item @emph{See also}:
3090 @ref{DBLE}, @ref{FLOAT}, @ref{REAL}
3096 @section @code{DIGITS} --- Significant digits function
3098 @cindex model representation, significant digits
3101 @item @emph{Description}:
3102 @code{DIGITS(X)} returns the number of significant digits of the internal model
3103 representation of @var{X}. For example, on a system using a 32-bit
3104 floating point representation, a default real number would likely return 24.
3106 @item @emph{Standard}:
3112 @item @emph{Syntax}:
3113 @code{RESULT = DIGITS(X)}
3115 @item @emph{Arguments}:
3116 @multitable @columnfractions .15 .70
3117 @item @var{X} @tab The type may be @code{INTEGER(*)} or @code{REAL(*)}.
3120 @item @emph{Return value}:
3121 The return value is of type @code{INTEGER}.
3123 @item @emph{Example}:
3126 integer :: i = 12345
3132 end program test_digits
3139 @section @code{DIM} --- Positive difference
3143 @cindex positive difference
3146 @item @emph{Description}:
3147 @code{DIM(X,Y)} returns the difference @code{X-Y} if the result is positive;
3148 otherwise returns zero.
3150 @item @emph{Standard}:
3156 @item @emph{Syntax}:
3157 @code{RESULT = DIM(X, Y)}
3159 @item @emph{Arguments}:
3160 @multitable @columnfractions .15 .70
3161 @item @var{X} @tab The type shall be @code{INTEGER(*)} or @code{REAL(*)}
3162 @item @var{Y} @tab The type shall be the same type and kind as @var{X}.
3165 @item @emph{Return value}:
3166 The return value is of type @code{INTEGER(*)} or @code{REAL(*)}.
3168 @item @emph{Example}:
3174 x = dim(4.345_8, 2.111_8)
3177 end program test_dim
3180 @item @emph{Specific names}:
3181 @multitable @columnfractions .20 .20 .20 .25
3182 @item Name @tab Argument @tab Return type @tab Standard
3183 @item @code{IDIM(X,Y)} @tab @code{INTEGER(4) X,Y} @tab @code{INTEGER(4)} @tab F77 and later
3184 @item @code{DDIM(X,Y)} @tab @code{REAL(8) X,Y} @tab @code{REAL(8)} @tab F77 and later
3191 @section @code{DOT_PRODUCT} --- Dot product function
3192 @fnindex DOT_PRODUCT
3194 @cindex vector product
3195 @cindex product, vector
3198 @item @emph{Description}:
3199 @code{DOT_PRODUCT(X,Y)} computes the dot product multiplication of two vectors
3200 @var{X} and @var{Y}. The two vectors may be either numeric or logical
3201 and must be arrays of rank one and of equal size. If the vectors are
3202 @code{INTEGER(*)} or @code{REAL(*)}, the result is @code{SUM(X*Y)}. If the
3203 vectors are @code{COMPLEX(*)}, the result is @code{SUM(CONJG(X)*Y)}. If the
3204 vectors are @code{LOGICAL}, the result is @code{ANY(X.AND.Y)}.
3206 @item @emph{Standard}:
3210 Transformational function
3212 @item @emph{Syntax}:
3213 @code{RESULT = DOT_PRODUCT(X, Y)}
3215 @item @emph{Arguments}:
3216 @multitable @columnfractions .15 .70
3217 @item @var{X} @tab The type shall be numeric or @code{LOGICAL}, rank 1.
3218 @item @var{Y} @tab The type shall be numeric or @code{LOGICAL}, rank 1.
3221 @item @emph{Return value}:
3222 If the arguments are numeric, the return value is a scaler of numeric type,
3223 @code{INTEGER(*)}, @code{REAL(*)}, or @code{COMPLEX(*)}. If the arguments are
3224 @code{LOGICAL}, the return value is @code{.TRUE.} or @code{.FALSE.}.
3226 @item @emph{Example}:
3228 program test_dot_prod
3229 integer, dimension(3) :: a, b
3236 print *, dot_product(a,b)
3237 end program test_dot_prod
3244 @section @code{DPROD} --- Double product function
3246 @cindex product, double-precision
3249 @item @emph{Description}:
3250 @code{DPROD(X,Y)} returns the product @code{X*Y}.
3252 @item @emph{Standard}:
3258 @item @emph{Syntax}:
3259 @code{RESULT = DPROD(X, Y)}
3261 @item @emph{Arguments}:
3262 @multitable @columnfractions .15 .70
3263 @item @var{X} @tab The type shall be @code{REAL}.
3264 @item @var{Y} @tab The type shall be @code{REAL}.
3267 @item @emph{Return value}:
3268 The return value is of type @code{REAL(8)}.
3270 @item @emph{Example}:
3278 end program test_dprod
3285 @section @code{DREAL} --- Double real part function
3287 @cindex complex numbers, real part
3290 @item @emph{Description}:
3291 @code{DREAL(Z)} returns the real part of complex variable @var{Z}.
3293 @item @emph{Standard}:
3299 @item @emph{Syntax}:
3300 @code{RESULT = DREAL(Z)}
3302 @item @emph{Arguments}:
3303 @multitable @columnfractions .15 .70
3304 @item @var{Z} @tab The type shall be @code{COMPLEX(8)}.
3307 @item @emph{Return value}:
3308 The return value is of type @code{REAL(8)}.
3310 @item @emph{Example}:
3313 complex(8) :: z = (1.3_8,7.2_8)
3315 end program test_dreal
3318 @item @emph{See also}:
3326 @section @code{DTIME} --- Execution time subroutine (or function)
3328 @cindex time, elapsed
3329 @cindex elapsed time
3332 @item @emph{Description}:
3333 @code{DTIME(TARRAY, RESULT)} initially returns the number of seconds of runtime
3334 since the start of the process's execution in @var{RESULT}. @var{TARRAY}
3335 returns the user and system components of this time in @code{TARRAY(1)} and
3336 @code{TARRAY(2)} respectively. @var{RESULT} is equal to @code{TARRAY(1) +
3339 Subsequent invocations of @code{DTIME} return values accumulated since the
3340 previous invocation.
3342 On some systems, the underlying timings are represented using types with
3343 sufficiently small limits that overflows (wrap around) are possible, such as
3344 32-bit types. Therefore, the values returned by this intrinsic might be, or
3345 become, negative, or numerically less than previous values, during a single
3346 run of the compiled program.
3348 Please note, that this implementation is thread safe if used within OpenMP
3349 directives, i.e., its state will be consistent while called from multiple
3350 threads. However, if @code{DTIME} is called from multiple threads, the result
3351 is still the time since the last invocation. This may not give the intended
3352 results. If possible, use @code{CPU_TIME} instead.
3354 This intrinsic is provided in both subroutine and function forms; however,
3355 only one form can be used in any given program unit.
3357 @var{TARRAY} and @var{RESULT} are @code{INTENT(OUT)} and provide the following:
3359 @multitable @columnfractions .15 .30 .40
3360 @item @tab @code{TARRAY(1)}: @tab User time in seconds.
3361 @item @tab @code{TARRAY(2)}: @tab System time in seconds.
3362 @item @tab @code{RESULT}: @tab Run time since start in seconds.
3365 @item @emph{Standard}:
3369 Subroutine, function
3371 @item @emph{Syntax}:
3372 @multitable @columnfractions .80
3373 @item @code{CALL DTIME(TARRAY, RESULT)}.
3374 @item @code{RESULT = DTIME(TARRAY)}, (not recommended).
3377 @item @emph{Arguments}:
3378 @multitable @columnfractions .15 .70
3379 @item @var{TARRAY}@tab The type shall be @code{REAL, DIMENSION(2)}.
3380 @item @var{RESULT}@tab The type shall be @code{REAL}.
3383 @item @emph{Return value}:
3384 Elapsed time in seconds since the last invocation or since the start of program
3385 execution if not called before.
3387 @item @emph{Example}:
3391 real, dimension(2) :: tarray
3393 call dtime(tarray, result)
3397 do i=1,100000000 ! Just a delay
3400 call dtime(tarray, result)
3404 end program test_dtime
3407 @item @emph{See also}:
3415 @section @code{EOSHIFT} --- End-off shift elements of an array
3417 @cindex array, shift
3420 @item @emph{Description}:
3421 @code{EOSHIFT(ARRAY, SHIFT[,BOUNDARY, DIM])} performs an end-off shift on
3422 elements of @var{ARRAY} along the dimension of @var{DIM}. If @var{DIM} is
3423 omitted it is taken to be @code{1}. @var{DIM} is a scaler of type
3424 @code{INTEGER} in the range of @math{1 /leq DIM /leq n)} where @math{n} is the
3425 rank of @var{ARRAY}. If the rank of @var{ARRAY} is one, then all elements of
3426 @var{ARRAY} are shifted by @var{SHIFT} places. If rank is greater than one,
3427 then all complete rank one sections of @var{ARRAY} along the given dimension are
3428 shifted. Elements shifted out one end of each rank one section are dropped. If
3429 @var{BOUNDARY} is present then the corresponding value of from @var{BOUNDARY}
3430 is copied back in the other end. If @var{BOUNDARY} is not present then the
3431 following are copied in depending on the type of @var{ARRAY}.
3433 @multitable @columnfractions .15 .80
3434 @item @emph{Array Type} @tab @emph{Boundary Value}
3435 @item Numeric @tab 0 of the type and kind of @var{ARRAY}.
3436 @item Logical @tab @code{.FALSE.}.
3437 @item Character(@var{len}) @tab @var{len} blanks.
3440 @item @emph{Standard}:
3444 Transformational function
3446 @item @emph{Syntax}:
3447 @code{RESULT = EOSHIFT(ARRAY, SHIFT [, BOUNDARY, DIM])}
3449 @item @emph{Arguments}:
3450 @multitable @columnfractions .15 .70
3451 @item @var{ARRAY} @tab May be any type, not scaler.
3452 @item @var{SHIFT} @tab The type shall be @code{INTEGER}.
3453 @item @var{BOUNDARY} @tab Same type as @var{ARRAY}.
3454 @item @var{DIM} @tab The type shall be @code{INTEGER}.
3457 @item @emph{Return value}:
3458 Returns an array of same type and rank as the @var{ARRAY} argument.
3460 @item @emph{Example}:
3462 program test_eoshift
3463 integer, dimension(3,3) :: a
3464 a = reshape( (/ 1, 2, 3, 4, 5, 6, 7, 8, 9 /), (/ 3, 3 /))
3465 print '(3i3)', a(1,:)
3466 print '(3i3)', a(2,:)
3467 print '(3i3)', a(3,:)
3468 a = EOSHIFT(a, SHIFT=(/1, 2, 1/), BOUNDARY=-5, DIM=2)
3470 print '(3i3)', a(1,:)
3471 print '(3i3)', a(2,:)
3472 print '(3i3)', a(3,:)
3473 end program test_eoshift
3480 @section @code{EPSILON} --- Epsilon function
3482 @cindex model representation, epsilon
3485 @item @emph{Description}:
3486 @code{EPSILON(X)} returns a nearly negligible number relative to @code{1}.
3488 @item @emph{Standard}:
3494 @item @emph{Syntax}:
3495 @code{RESULT = EPSILON(X)}
3497 @item @emph{Arguments}:
3498 @multitable @columnfractions .15 .70
3499 @item @var{X} @tab The type shall be @code{REAL(*)}.
3502 @item @emph{Return value}:
3503 The return value is of same type as the argument.
3505 @item @emph{Example}:
3507 program test_epsilon
3512 end program test_epsilon
3519 @section @code{ERF} --- Error function
3521 @cindex error function
3524 @item @emph{Description}:
3525 @code{ERF(X)} computes the error function of @var{X}.
3527 @item @emph{Standard}:
3528 Fortran 2008 and later
3533 @item @emph{Syntax}:
3534 @code{RESULT = ERF(X)}
3536 @item @emph{Arguments}:
3537 @multitable @columnfractions .15 .70
3538 @item @var{X} @tab The type shall be @code{REAL}.
3541 @item @emph{Return value}:
3542 The return value is of type @code{REAL}, of the same kind as
3543 @var{X} and lies in the range @math{-1 \leq erf (x) \leq 1 }.
3545 @item @emph{Example}:
3548 real(8) :: x = 0.17_8
3550 end program test_erf
3553 @item @emph{Specific names}:
3554 @multitable @columnfractions .20 .20 .20 .25
3555 @item Name @tab Argument @tab Return type @tab Standard
3556 @item @code{DERF(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU extension
3563 @section @code{ERFC} --- Error function
3565 @cindex error function, complementary
3568 @item @emph{Description}:
3569 @code{ERFC(X)} computes the complementary error function of @var{X}.
3571 @item @emph{Standard}:
3572 Fortran 2008 and later
3577 @item @emph{Syntax}:
3578 @code{RESULT = ERFC(X)}
3580 @item @emph{Arguments}:
3581 @multitable @columnfractions .15 .70
3582 @item @var{X} @tab The type shall be @code{REAL}.
3585 @item @emph{Return value}:
3586 The return value is of type @code{REAL} and of the same kind as @var{X}.
3587 It lies in the range @math{ 0 \leq erfc (x) \leq 2 }.
3589 @item @emph{Example}:
3592 real(8) :: x = 0.17_8
3594 end program test_erfc
3597 @item @emph{Specific names}:
3598 @multitable @columnfractions .20 .20 .20 .25
3599 @item Name @tab Argument @tab Return type @tab Standard
3600 @item @code{DERFC(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU extension
3607 @section @code{ERFC_SCALED} --- Error function
3608 @fnindex ERFC_SCALED
3609 @cindex error function, complementary, exponentially-scaled
3612 @item @emph{Description}:
3613 @code{ERFC_SCALED(X)} computes the exponentially-scaled complementary
3614 error function of @var{X}.
3616 @item @emph{Standard}:
3617 Fortran 2008 and later
3622 @item @emph{Syntax}:
3623 @code{RESULT = ERFC_SCALED(X)}
3625 @item @emph{Arguments}:
3626 @multitable @columnfractions .15 .70
3627 @item @var{X} @tab The type shall be @code{REAL}.
3630 @item @emph{Return value}:
3631 The return value is of type @code{REAL} and of the same kind as @var{X}.
3633 @item @emph{Example}:
3635 program test_erfc_scaled
3636 real(8) :: x = 0.17_8
3638 end program test_erfc_scaled
3645 @section @code{ETIME} --- Execution time subroutine (or function)
3647 @cindex time, elapsed
3650 @item @emph{Description}:
3651 @code{ETIME(TARRAY, RESULT)} returns the number of seconds of runtime
3652 since the start of the process's execution in @var{RESULT}. @var{TARRAY}
3653 returns the user and system components of this time in @code{TARRAY(1)} and
3654 @code{TARRAY(2)} respectively. @var{RESULT} is equal to @code{TARRAY(1) + TARRAY(2)}.
3656 On some systems, the underlying timings are represented using types with
3657 sufficiently small limits that overflows (wrap around) are possible, such as
3658 32-bit types. Therefore, the values returned by this intrinsic might be, or
3659 become, negative, or numerically less than previous values, during a single
3660 run of the compiled program.
3662 This intrinsic is provided in both subroutine and function forms; however,
3663 only one form can be used in any given program unit.
3665 @var{TARRAY} and @var{RESULT} are @code{INTENT(OUT)} and provide the following:
3667 @multitable @columnfractions .15 .30 .60
3668 @item @tab @code{TARRAY(1)}: @tab User time in seconds.
3669 @item @tab @code{TARRAY(2)}: @tab System time in seconds.
3670 @item @tab @code{RESULT}: @tab Run time since start in seconds.
3673 @item @emph{Standard}:
3677 Subroutine, function
3679 @item @emph{Syntax}:
3680 @multitable @columnfractions .80
3681 @item @code{CALL ETIME(TARRAY, RESULT)}.
3682 @item @code{RESULT = ETIME(TARRAY)}, (not recommended).
3685 @item @emph{Arguments}:
3686 @multitable @columnfractions .15 .70
3687 @item @var{TARRAY}@tab The type shall be @code{REAL, DIMENSION(2)}.
3688 @item @var{RESULT}@tab The type shall be @code{REAL}.
3691 @item @emph{Return value}:
3692 Elapsed time in seconds since the start of program execution.
3694 @item @emph{Example}:
3698 real, dimension(2) :: tarray
3700 call ETIME(tarray, result)
3704 do i=1,100000000 ! Just a delay
3707 call ETIME(tarray, result)
3711 end program test_etime
3714 @item @emph{See also}:
3722 @section @code{EXIT} --- Exit the program with status.
3724 @cindex program termination
3725 @cindex terminate program
3728 @item @emph{Description}:
3729 @code{EXIT} causes immediate termination of the program with status. If status
3730 is omitted it returns the canonical @emph{success} for the system. All Fortran
3731 I/O units are closed.
3733 @item @emph{Standard}:
3739 @item @emph{Syntax}:
3740 @code{CALL EXIT([STATUS])}
3742 @item @emph{Arguments}:
3743 @multitable @columnfractions .15 .70
3744 @item @var{STATUS} @tab Shall be an @code{INTEGER} of the default kind.
3747 @item @emph{Return value}:
3748 @code{STATUS} is passed to the parent process on exit.
3750 @item @emph{Example}:
3753 integer :: STATUS = 0
3754 print *, 'This program is going to exit.'
3756 end program test_exit
3759 @item @emph{See also}:
3760 @ref{ABORT}, @ref{KILL}
3766 @section @code{EXP} --- Exponential function
3772 @cindex exponential function
3773 @cindex logarithmic function, inverse
3776 @item @emph{Description}:
3777 @code{EXP(X)} computes the base @math{e} exponential of @var{X}.
3779 @item @emph{Standard}:
3780 F77 and later, has overloads that are GNU extensions
3785 @item @emph{Syntax}:
3786 @code{RESULT = EXP(X)}
3788 @item @emph{Arguments}:
3789 @multitable @columnfractions .15 .70
3790 @item @var{X} @tab The type shall be @code{REAL(*)} or
3794 @item @emph{Return value}:
3795 The return value has same type and kind as @var{X}.
3797 @item @emph{Example}:
3802 end program test_exp
3805 @item @emph{Specific names}:
3806 @multitable @columnfractions .20 .20 .20 .25
3807 @item Name @tab Argument @tab Return type @tab Standard
3808 @item @code{DEXP(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab F77 and later
3809 @item @code{CEXP(X)} @tab @code{COMPLEX(4) X} @tab @code{COMPLEX(4)} @tab F77 and later
3810 @item @code{ZEXP(X)} @tab @code{COMPLEX(8) X} @tab @code{COMPLEX(8)} @tab GNU extension
3811 @item @code{CDEXP(X)} @tab @code{COMPLEX(8) X} @tab @code{COMPLEX(8)} @tab GNU extension
3818 @section @code{EXPONENT} --- Exponent function
3820 @cindex real number, exponent
3821 @cindex floating point, exponent
3824 @item @emph{Description}:
3825 @code{EXPONENT(X)} returns the value of the exponent part of @var{X}. If @var{X}
3826 is zero the value returned is zero.
3828 @item @emph{Standard}:
3834 @item @emph{Syntax}:
3835 @code{RESULT = EXPONENT(X)}
3837 @item @emph{Arguments}:
3838 @multitable @columnfractions .15 .70
3839 @item @var{X} @tab The type shall be @code{REAL(*)}.
3842 @item @emph{Return value}:
3843 The return value is of type default @code{INTEGER}.
3845 @item @emph{Example}:
3847 program test_exponent
3852 print *, exponent(0.0)
3853 end program test_exponent
3860 @section @code{FDATE} --- Get the current time as a string
3862 @cindex time, current
3863 @cindex current time
3864 @cindex date, current
3865 @cindex current date
3868 @item @emph{Description}:
3869 @code{FDATE(DATE)} returns the current date (using the same format as
3870 @code{CTIME}) in @var{DATE}. It is equivalent to @code{CALL CTIME(DATE,
3873 This intrinsic is provided in both subroutine and function forms; however,
3874 only one form can be used in any given program unit.
3876 @var{DATE} is an @code{INTENT(OUT)} @code{CHARACTER} variable.
3878 @item @emph{Standard}:
3882 Subroutine, function
3884 @item @emph{Syntax}:
3885 @multitable @columnfractions .80
3886 @item @code{CALL FDATE(DATE)}.
3887 @item @code{DATE = FDATE()}, (not recommended).
3890 @item @emph{Arguments}:
3891 @multitable @columnfractions .15 .70
3892 @item @var{DATE}@tab The type shall be of type @code{CHARACTER}.
3895 @item @emph{Return value}:
3896 The current date as a string.
3898 @item @emph{Example}:
3902 character(len=30) :: date
3904 print *, 'Program started on ', date
3905 do i = 1, 100000000 ! Just a delay
3909 print *, 'Program ended on ', date
3910 end program test_fdate
3917 @section @code{FLOAT} --- Convert integer to default real
3919 @cindex conversion, to real
3922 @item @emph{Description}:
3923 @code{FLOAT(I)} converts the integer @var{I} to a default real value.
3925 @item @emph{Standard}:
3931 @item @emph{Syntax}:
3932 @code{RESULT = FLOAT(I)}
3934 @item @emph{Arguments}:
3935 @multitable @columnfractions .15 .70
3936 @item @var{I} @tab The type shall be @code{INTEGER(*)}.
3939 @item @emph{Return value}:
3940 The return value is of type default @code{REAL}.
3942 @item @emph{Example}:
3946 if (float(i) /= 1.) call abort
3947 end program test_float
3950 @item @emph{See also}:
3951 @ref{DBLE}, @ref{DFLOAT}, @ref{REAL}
3957 @section @code{FGET} --- Read a single character in stream mode from stdin
3959 @cindex read character, stream mode
3960 @cindex stream mode, read character
3961 @cindex file operation, read character
3964 @item @emph{Description}:
3965 Read a single character in stream mode from stdin by bypassing normal
3966 formatted output. Stream I/O should not be mixed with normal record-oriented
3967 (formatted or unformatted) I/O on the same unit; the results are unpredictable.
3969 This intrinsic is provided in both subroutine and function forms; however,
3970 only one form can be used in any given program unit.
3972 Note that the @code{FGET} intrinsic is provided for backwards compatibility with
3973 @command{g77}. GNU Fortran provides the Fortran 2003 Stream facility.
3974 Programmers should consider the use of new stream IO feature in new code
3975 for future portability. See also @ref{Fortran 2003 status}.
3977 @item @emph{Standard}:
3981 Subroutine, function
3983 @item @emph{Syntax}:
3984 @code{CALL FGET(C [, STATUS])}
3986 @item @emph{Arguments}:
3987 @multitable @columnfractions .15 .70
3988 @item @var{C} @tab The type shall be @code{CHARACTER}.
3989 @item @var{STATUS} @tab (Optional) status flag of type @code{INTEGER}.
3990 Returns 0 on success, -1 on end-of-file, and a
3991 system specific positive error code otherwise.
3994 @item @emph{Example}:
3997 INTEGER, PARAMETER :: strlen = 100
3998 INTEGER :: status, i = 1
3999 CHARACTER(len=strlen) :: str = ""
4001 WRITE (*,*) 'Enter text:'
4003 CALL fget(str(i:i), status)
4004 if (status /= 0 .OR. i > strlen) exit
4007 WRITE (*,*) TRIM(str)
4011 @item @emph{See also}:
4012 @ref{FGETC}, @ref{FPUT}, @ref{FPUTC}
4018 @section @code{FGETC} --- Read a single character in stream mode
4020 @cindex read character, stream mode
4021 @cindex stream mode, read character
4022 @cindex file operation, read character
4025 @item @emph{Description}:
4026 Read a single character in stream mode by bypassing normal formatted output.
4027 Stream I/O should not be mixed with normal record-oriented (formatted or
4028 unformatted) I/O on the same unit; the results are unpredictable.
4030 This intrinsic is provided in both subroutine and function forms; however,
4031 only one form can be used in any given program unit.
4033 Note that the @code{FGET} intrinsic is provided for backwards compatibility
4034 with @command{g77}. GNU Fortran provides the Fortran 2003 Stream facility.
4035 Programmers should consider the use of new stream IO feature in new code
4036 for future portability. See also @ref{Fortran 2003 status}.
4038 @item @emph{Standard}:
4042 Subroutine, function
4044 @item @emph{Syntax}:
4045 @code{CALL FGETC(UNIT, C [, STATUS])}
4047 @item @emph{Arguments}:
4048 @multitable @columnfractions .15 .70
4049 @item @var{UNIT} @tab The type shall be @code{INTEGER}.
4050 @item @var{C} @tab The type shall be @code{CHARACTER}.
4051 @item @var{STATUS} @tab (Optional) status flag of type @code{INTEGER}. Returns 0 on success,
4052 -1 on end-of-file and a system specific positive error code otherwise.
4055 @item @emph{Example}:
4058 INTEGER :: fd = 42, status
4061 OPEN(UNIT=fd, FILE="/etc/passwd", ACTION="READ", STATUS = "OLD")
4063 CALL fgetc(fd, c, status)
4064 IF (status /= 0) EXIT
4071 @item @emph{See also}:
4072 @ref{FGET}, @ref{FPUT}, @ref{FPUTC}
4078 @section @code{FLOOR} --- Integer floor function
4081 @cindex rounding, floor
4084 @item @emph{Description}:
4085 @code{FLOOR(X)} returns the greatest integer less than or equal to @var{X}.
4087 @item @emph{Standard}:
4093 @item @emph{Syntax}:
4094 @code{RESULT = FLOOR(X [, KIND])}
4096 @item @emph{Arguments}:
4097 @multitable @columnfractions .15 .70
4098 @item @var{X} @tab The type shall be @code{REAL(*)}.
4099 @item @var{KIND} @tab (Optional) An @code{INTEGER(*)} initialization
4100 expression indicating the kind parameter of
4104 @item @emph{Return value}:
4105 The return value is of type @code{INTEGER(KIND)}
4107 @item @emph{Example}:
4112 print *, floor(x) ! returns 63
4113 print *, floor(y) ! returns -64
4114 end program test_floor
4117 @item @emph{See also}:
4118 @ref{CEILING}, @ref{NINT}
4125 @section @code{FLUSH} --- Flush I/O unit(s)
4127 @cindex file operation, flush
4130 @item @emph{Description}:
4131 Flushes Fortran unit(s) currently open for output. Without the optional
4132 argument, all units are flushed, otherwise just the unit specified.
4134 @item @emph{Standard}:
4140 @item @emph{Syntax}:
4141 @code{CALL FLUSH(UNIT)}
4143 @item @emph{Arguments}:
4144 @multitable @columnfractions .15 .70
4145 @item @var{UNIT} @tab (Optional) The type shall be @code{INTEGER}.
4149 Beginning with the Fortran 2003 standard, there is a @code{FLUSH}
4150 statement that should be preferred over the @code{FLUSH} intrinsic.
4157 @section @code{FNUM} --- File number function
4159 @cindex file operation, file number
4162 @item @emph{Description}:
4163 @code{FNUM(UNIT)} returns the POSIX file descriptor number corresponding to the
4164 open Fortran I/O unit @code{UNIT}.
4166 @item @emph{Standard}:
4172 @item @emph{Syntax}:
4173 @code{RESULT = FNUM(UNIT)}
4175 @item @emph{Arguments}:
4176 @multitable @columnfractions .15 .70
4177 @item @var{UNIT} @tab The type shall be @code{INTEGER}.
4180 @item @emph{Return value}:
4181 The return value is of type @code{INTEGER}
4183 @item @emph{Example}:
4187 open (unit=10, status = "scratch")
4191 end program test_fnum
4198 @section @code{FPUT} --- Write a single character in stream mode to stdout
4200 @cindex write character, stream mode
4201 @cindex stream mode, write character
4202 @cindex file operation, write character
4205 @item @emph{Description}:
4206 Write a single character in stream mode to stdout by bypassing normal
4207 formatted output. Stream I/O should not be mixed with normal record-oriented
4208 (formatted or unformatted) I/O on the same unit; the results are unpredictable.
4210 This intrinsic is provided in both subroutine and function forms; however,
4211 only one form can be used in any given program unit.
4213 Note that the @code{FGET} intrinsic is provided for backwards compatibility with
4214 @command{g77}. GNU Fortran provides the Fortran 2003 Stream facility.
4215 Programmers should consider the use of new stream IO feature in new code
4216 for future portability. See also @ref{Fortran 2003 status}.
4218 @item @emph{Standard}:
4222 Subroutine, function
4224 @item @emph{Syntax}:
4225 @code{CALL FPUT(C [, STATUS])}
4227 @item @emph{Arguments}:
4228 @multitable @columnfractions .15 .70
4229 @item @var{C} @tab The type shall be @code{CHARACTER}.
4230 @item @var{STATUS} @tab (Optional) status flag of type @code{INTEGER}. Returns 0 on success,
4231 -1 on end-of-file and a system specific positive error code otherwise.
4234 @item @emph{Example}:
4237 CHARACTER(len=10) :: str = "gfortran"
4239 DO i = 1, len_trim(str)
4245 @item @emph{See also}:
4246 @ref{FPUTC}, @ref{FGET}, @ref{FGETC}
4252 @section @code{FPUTC} --- Write a single character in stream mode
4254 @cindex write character, stream mode
4255 @cindex stream mode, write character
4256 @cindex file operation, write character
4259 @item @emph{Description}:
4260 Write a single character in stream mode by bypassing normal formatted
4261 output. Stream I/O should not be mixed with normal record-oriented
4262 (formatted or unformatted) I/O on the same unit; the results are unpredictable.
4264 This intrinsic is provided in both subroutine and function forms; however,
4265 only one form can be used in any given program unit.
4267 Note that the @code{FGET} intrinsic is provided for backwards compatibility with
4268 @command{g77}. GNU Fortran provides the Fortran 2003 Stream facility.
4269 Programmers should consider the use of new stream IO feature in new code
4270 for future portability. See also @ref{Fortran 2003 status}.
4272 @item @emph{Standard}:
4276 Subroutine, function
4278 @item @emph{Syntax}:
4279 @code{CALL FPUTC(UNIT, C [, STATUS])}
4281 @item @emph{Arguments}:
4282 @multitable @columnfractions .15 .70
4283 @item @var{UNIT} @tab The type shall be @code{INTEGER}.
4284 @item @var{C} @tab The type shall be @code{CHARACTER}.
4285 @item @var{STATUS} @tab (Optional) status flag of type @code{INTEGER}. Returns 0 on success,
4286 -1 on end-of-file and a system specific positive error code otherwise.
4289 @item @emph{Example}:
4292 CHARACTER(len=10) :: str = "gfortran"
4293 INTEGER :: fd = 42, i
4295 OPEN(UNIT = fd, FILE = "out", ACTION = "WRITE", STATUS="NEW")
4296 DO i = 1, len_trim(str)
4297 CALL fputc(fd, str(i:i))
4303 @item @emph{See also}:
4304 @ref{FPUT}, @ref{FGET}, @ref{FGETC}
4310 @section @code{FRACTION} --- Fractional part of the model representation
4312 @cindex real number, fraction
4313 @cindex floating point, fraction
4316 @item @emph{Description}:
4317 @code{FRACTION(X)} returns the fractional part of the model
4318 representation of @code{X}.
4320 @item @emph{Standard}:
4326 @item @emph{Syntax}:
4327 @code{Y = FRACTION(X)}
4329 @item @emph{Arguments}:
4330 @multitable @columnfractions .15 .70
4331 @item @var{X} @tab The type of the argument shall be a @code{REAL}.
4334 @item @emph{Return value}:
4335 The return value is of the same type and kind as the argument.
4336 The fractional part of the model representation of @code{X} is returned;
4337 it is @code{X * RADIX(X)**(-EXPONENT(X))}.
4339 @item @emph{Example}:
4341 program test_fraction
4344 print *, fraction(x), x * radix(x)**(-exponent(x))
4345 end program test_fraction
4353 @section @code{FREE} --- Frees memory
4355 @cindex pointer, cray
4358 @item @emph{Description}:
4359 Frees memory previously allocated by @code{MALLOC()}. The @code{FREE}
4360 intrinsic is an extension intended to be used with Cray pointers, and is
4361 provided in GNU Fortran to allow user to compile legacy code. For
4362 new code using Fortran 95 pointers, the memory de-allocation intrinsic is
4365 @item @emph{Standard}:
4371 @item @emph{Syntax}:
4372 @code{CALL FREE(PTR)}
4374 @item @emph{Arguments}:
4375 @multitable @columnfractions .15 .70
4376 @item @var{PTR} @tab The type shall be @code{INTEGER}. It represents the
4377 location of the memory that should be de-allocated.
4380 @item @emph{Return value}:
4383 @item @emph{Example}:
4384 See @code{MALLOC} for an example.
4386 @item @emph{See also}:
4393 @section @code{FSEEK} --- Low level file positioning subroutine
4395 @cindex file operation, seek
4396 @cindex file operation, position
4399 @item @emph{Description}:
4400 Moves @var{UNIT} to the specified @var{OFFSET}. If @var{WHENCE}
4401 is set to 0, the @var{OFFSET} is taken as an absolute value @code{SEEK_SET},
4402 if set to 1, @var{OFFSET} is taken to be relative to the current position
4403 @code{SEEK_CUR}, and if set to 2 relative to the end of the file @code{SEEK_END}.
4404 On error, @var{STATUS} is set to a nonzero value. If @var{STATUS} the seek
4407 This intrinsic routine is not fully backwards compatible with @command{g77}.
4408 In @command{g77}, the @code{FSEEK} takes a statement label instead of a
4409 @var{STATUS} variable. If FSEEK is used in old code, change
4411 CALL FSEEK(UNIT, OFFSET, WHENCE, *label)
4416 CALL FSEEK(UNIT, OFFSET, WHENCE, status)
4417 IF (status /= 0) GOTO label
4420 Please note that GNU Fortran provides the Fortran 2003 Stream facility.
4421 Programmers should consider the use of new stream IO feature in new code
4422 for future portability. See also @ref{Fortran 2003 status}.
4424 @item @emph{Standard}:
4430 @item @emph{Syntax}:
4431 @code{CALL FSEEK(UNIT, OFFSET, WHENCE[, STATUS])}
4433 @item @emph{Arguments}:
4434 @multitable @columnfractions .15 .70
4435 @item @var{UNIT} @tab Shall be a scalar of type @code{INTEGER}.
4436 @item @var{OFFSET} @tab Shall be a scalar of type @code{INTEGER}.
4437 @item @var{WHENCE} @tab Shall be a scalar of type @code{INTEGER}.
4438 Its value shall be either 0, 1 or 2.
4439 @item @var{STATUS} @tab (Optional) shall be a scalar of type
4443 @item @emph{Example}:
4446 INTEGER, PARAMETER :: SEEK_SET = 0, SEEK_CUR = 1, SEEK_END = 2
4447 INTEGER :: fd, offset, ierr
4453 OPEN(UNIT=fd, FILE="fseek.test")
4454 CALL FSEEK(fd, offset, SEEK_SET, ierr) ! move to OFFSET
4455 print *, FTELL(fd), ierr
4457 CALL FSEEK(fd, 0, SEEK_END, ierr) ! move to end
4458 print *, FTELL(fd), ierr
4460 CALL FSEEK(fd, 0, SEEK_SET, ierr) ! move to beginning
4461 print *, FTELL(fd), ierr
4467 @item @emph{See also}:
4474 @section @code{FSTAT} --- Get file status
4476 @cindex file system, file status
4479 @item @emph{Description}:
4480 @code{FSTAT} is identical to @ref{STAT}, except that information about an
4481 already opened file is obtained.
4483 The elements in @code{BUFF} are the same as described by @ref{STAT}.
4485 This intrinsic is provided in both subroutine and function forms; however,
4486 only one form can be used in any given program unit.
4488 @item @emph{Standard}:
4492 Subroutine, function
4494 @item @emph{Syntax}:
4495 @code{CALL FSTAT(UNIT, BUFF [, STATUS])}
4497 @item @emph{Arguments}:
4498 @multitable @columnfractions .15 .70
4499 @item @var{UNIT} @tab An open I/O unit number of type @code{INTEGER}.
4500 @item @var{BUFF} @tab The type shall be @code{INTEGER(4), DIMENSION(13)}.
4501 @item @var{STATUS} @tab (Optional) status flag of type @code{INTEGER(4)}. Returns 0
4502 on success and a system specific error code otherwise.
4505 @item @emph{Example}:
4506 See @ref{STAT} for an example.
4508 @item @emph{See also}:
4509 To stat a link: @ref{LSTAT}, to stat a file: @ref{STAT}
4515 @section @code{FTELL} --- Current stream position
4517 @cindex file operation, position
4520 @item @emph{Description}:
4521 Retrieves the current position within an open file.
4523 This intrinsic is provided in both subroutine and function forms; however,
4524 only one form can be used in any given program unit.
4526 @item @emph{Standard}:
4530 Subroutine, function
4532 @item @emph{Syntax}:
4533 @multitable @columnfractions .80
4534 @item @code{CALL FTELL(UNIT, OFFSET)}
4535 @item @code{OFFSET = FTELL(UNIT)}
4538 @item @emph{Arguments}:
4539 @multitable @columnfractions .15 .70
4540 @item @var{OFFSET} @tab Shall of type @code{INTEGER}.
4541 @item @var{UNIT} @tab Shall of type @code{INTEGER}.
4544 @item @emph{Return value}:
4545 In either syntax, @var{OFFSET} is set to the current offset of unit
4546 number @var{UNIT}, or to @math{-1} if the unit is not currently open.
4548 @item @emph{Example}:
4552 OPEN(10, FILE="temp.dat")
4558 @item @emph{See also}:
4565 @section @code{GAMMA} --- Gamma function
4568 @cindex Gamma function
4569 @cindex Factorial function
4572 @item @emph{Description}:
4573 @code{GAMMA(X)} computes Gamma (@math{\Gamma}) of @var{X}. For positive,
4574 integer values of @var{X} the Gamma function simplifies to the factorial
4575 function @math{\Gamma(x)=(x-1)!}.
4579 \Gamma(x) = \int_0^\infty t^{x-1}{\rm e}^{-t}\,{\rm d}t
4583 @item @emph{Standard}:
4584 Fortran 2008 and later
4589 @item @emph{Syntax}:
4592 @item @emph{Arguments}:
4593 @multitable @columnfractions .15 .70
4594 @item @var{X} @tab Shall be of type @code{REAL} and neither zero
4595 nor a negative integer.
4598 @item @emph{Return value}:
4599 The return value is of type @code{REAL} of the same kind as @var{X}.
4601 @item @emph{Example}:
4605 x = gamma(x) ! returns 1.0
4606 end program test_gamma
4609 @item @emph{Specific names}:
4610 @multitable @columnfractions .20 .20 .20 .25
4611 @item Name @tab Argument @tab Return type @tab Standard
4612 @item @code{GAMMA(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab GNU Extension
4613 @item @code{DGAMMA(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU Extension
4616 @item @emph{See also}:
4617 Logarithm of the Gamma function: @ref{LOG_GAMMA}
4624 @section @code{GERROR} --- Get last system error message
4626 @cindex system, error handling
4629 @item @emph{Description}:
4630 Returns the system error message corresponding to the last system error.
4631 This resembles the functionality of @code{strerror(3)} in C.
4633 @item @emph{Standard}:
4639 @item @emph{Syntax}:
4640 @code{CALL GERROR(RESULT)}
4642 @item @emph{Arguments}:
4643 @multitable @columnfractions .15 .70
4644 @item @var{RESULT} @tab Shall of type @code{CHARACTER(*)}.
4647 @item @emph{Example}:
4650 CHARACTER(len=100) :: msg
4656 @item @emph{See also}:
4657 @ref{IERRNO}, @ref{PERROR}
4663 @section @code{GETARG} --- Get command line arguments
4665 @cindex command-line arguments
4666 @cindex arguments, to program
4669 @item @emph{Description}:
4670 Retrieve the @var{N}th argument that was passed on the
4671 command line when the containing program was invoked.
4673 This intrinsic routine is provided for backwards compatibility with
4674 GNU Fortran 77. In new code, programmers should consider the use of
4675 the @ref{GET_COMMAND_ARGUMENT} intrinsic defined by the Fortran 2003
4678 @item @emph{Standard}:
4684 @item @emph{Syntax}:
4685 @code{CALL GETARG(POS, VALUE)}
4687 @item @emph{Arguments}:
4688 @multitable @columnfractions .15 .70
4689 @item @var{POS} @tab Shall be of type @code{INTEGER} and not wider than
4690 the default integer kind; @math{@var{POS} \geq 0}
4691 @item @var{VALUE} @tab Shall be of type @code{CHARACTER(*)}.
4694 @item @emph{Return value}:
4695 After @code{GETARG} returns, the @var{VALUE} argument holds the
4696 @var{POS}th command line argument. If @var{VALUE} can not hold the
4697 argument, it is truncated to fit the length of @var{VALUE}. If there are
4698 less than @var{POS} arguments specified at the command line, @var{VALUE}
4699 will be filled with blanks. If @math{@var{POS} = 0}, @var{VALUE} is set
4700 to the name of the program (on systems that support this feature).
4702 @item @emph{Example}:
4706 CHARACTER(len=32) :: arg
4715 @item @emph{See also}:
4716 GNU Fortran 77 compatibility function: @ref{IARGC}
4718 Fortran 2003 functions and subroutines: @ref{GET_COMMAND},
4719 @ref{GET_COMMAND_ARGUMENT}, @ref{COMMAND_ARGUMENT_COUNT}
4725 @section @code{GET_COMMAND} --- Get the entire command line
4726 @fnindex GET_COMMAND
4727 @cindex command-line arguments
4728 @cindex arguments, to program
4731 @item @emph{Description}:
4732 Retrieve the entire command line that was used to invoke the program.
4734 @item @emph{Standard}:
4735 Fortran 2003 and later
4740 @item @emph{Syntax}:
4741 @code{CALL GET_COMMAND(CMD)}
4743 @item @emph{Arguments}:
4744 @multitable @columnfractions .15 .70
4745 @item @var{CMD} @tab Shall be of type @code{CHARACTER(*)}.
4748 @item @emph{Return value}:
4749 Stores the entire command line that was used to invoke the program in @var{ARG}.
4750 If @var{ARG} is not large enough, the command will be truncated.
4752 @item @emph{Example}:
4754 PROGRAM test_get_command
4755 CHARACTER(len=255) :: cmd
4756 CALL get_command(cmd)
4757 WRITE (*,*) TRIM(cmd)
4761 @item @emph{See also}:
4762 @ref{GET_COMMAND_ARGUMENT}, @ref{COMMAND_ARGUMENT_COUNT}
4767 @node GET_COMMAND_ARGUMENT
4768 @section @code{GET_COMMAND_ARGUMENT} --- Get command line arguments
4769 @fnindex GET_COMMAND_ARGUMENT
4770 @cindex command-line arguments
4771 @cindex arguments, to program
4774 @item @emph{Description}:
4775 Retrieve the @var{N}th argument that was passed on the
4776 command line when the containing program was invoked.
4778 @item @emph{Standard}:
4779 Fortran 2003 and later
4784 @item @emph{Syntax}:
4785 @code{CALL GET_COMMAND_ARGUMENT(N, ARG)}
4787 @item @emph{Arguments}:
4788 @multitable @columnfractions .15 .70
4789 @item @var{N} @tab Shall be of type @code{INTEGER(4)}, @math{@var{N} \geq 0}
4790 @item @var{ARG} @tab Shall be of type @code{CHARACTER(*)}.
4793 @item @emph{Return value}:
4794 After @code{GET_COMMAND_ARGUMENT} returns, the @var{ARG} argument holds the
4795 @var{N}th command line argument. If @var{ARG} can not hold the argument, it is
4796 truncated to fit the length of @var{ARG}. If there are less than @var{N}
4797 arguments specified at the command line, @var{ARG} will be filled with blanks.
4798 If @math{@var{N} = 0}, @var{ARG} is set to the name of the program (on systems
4799 that support this feature).
4801 @item @emph{Example}:
4803 PROGRAM test_get_command_argument
4805 CHARACTER(len=32) :: arg
4809 CALL get_command_argument(i, arg)
4810 IF (LEN_TRIM(arg) == 0) EXIT
4812 WRITE (*,*) TRIM(arg)
4818 @item @emph{See also}:
4819 @ref{GET_COMMAND}, @ref{COMMAND_ARGUMENT_COUNT}
4825 @section @code{GETCWD} --- Get current working directory
4827 @cindex system, working directory
4830 @item @emph{Description}:
4831 Get current working directory.
4833 This intrinsic is provided in both subroutine and function forms; however,
4834 only one form can be used in any given program unit.
4836 @item @emph{Standard}:
4840 Subroutine, function
4842 @item @emph{Syntax}:
4843 @code{CALL GETCWD(CWD [, STATUS])}
4845 @item @emph{Arguments}:
4846 @multitable @columnfractions .15 .70
4847 @item @var{CWD} @tab The type shall be @code{CHARACTER(*)}.
4848 @item @var{STATUS} @tab (Optional) status flag. Returns 0 on success,
4849 a system specific and nonzero error code otherwise.
4852 @item @emph{Example}:
4855 CHARACTER(len=255) :: cwd
4857 WRITE(*,*) TRIM(cwd)
4861 @item @emph{See also}:
4868 @section @code{GETENV} --- Get an environmental variable
4870 @cindex environment variable
4873 @item @emph{Description}:
4874 Get the @var{VALUE} of the environmental variable @var{ENVVAR}.
4876 This intrinsic routine is provided for backwards compatibility with
4877 GNU Fortran 77. In new code, programmers should consider the use of
4878 the @ref{GET_ENVIRONMENT_VARIABLE} intrinsic defined by the Fortran
4881 @item @emph{Standard}:
4887 @item @emph{Syntax}:
4888 @code{CALL GETENV(ENVVAR, VALUE)}
4890 @item @emph{Arguments}:
4891 @multitable @columnfractions .15 .70
4892 @item @var{ENVVAR} @tab Shall be of type @code{CHARACTER(*)}.
4893 @item @var{VALUE} @tab Shall be of type @code{CHARACTER(*)}.
4896 @item @emph{Return value}:
4897 Stores the value of @var{ENVVAR} in @var{VALUE}. If @var{VALUE} is
4898 not large enough to hold the data, it is truncated. If @var{ENVVAR}
4899 is not set, @var{VALUE} will be filled with blanks.
4901 @item @emph{Example}:
4904 CHARACTER(len=255) :: homedir
4905 CALL getenv("HOME", homedir)
4906 WRITE (*,*) TRIM(homedir)
4910 @item @emph{See also}:
4911 @ref{GET_ENVIRONMENT_VARIABLE}
4916 @node GET_ENVIRONMENT_VARIABLE
4917 @section @code{GET_ENVIRONMENT_VARIABLE} --- Get an environmental variable
4918 @fnindex GET_ENVIRONMENT_VARIABLE
4919 @cindex environment variable
4922 @item @emph{Description}:
4923 Get the @var{VALUE} of the environmental variable @var{ENVVAR}.
4925 @item @emph{Standard}:
4926 Fortran 2003 and later
4931 @item @emph{Syntax}:
4932 @code{CALL GET_ENVIRONMENT_VARIABLE(ENVVAR, VALUE)}
4934 @item @emph{Arguments}:
4935 @multitable @columnfractions .15 .70
4936 @item @var{ENVVAR} @tab Shall be of type @code{CHARACTER(*)}.
4937 @item @var{VALUE} @tab Shall be of type @code{CHARACTER(*)}.
4940 @item @emph{Return value}:
4941 Stores the value of @var{ENVVAR} in @var{VALUE}. If @var{VALUE} is
4942 not large enough to hold the data, it is truncated. If @var{ENVVAR}
4943 is not set, @var{VALUE} will be filled with blanks.
4945 @item @emph{Example}:
4948 CHARACTER(len=255) :: homedir
4949 CALL get_environment_variable("HOME", homedir)
4950 WRITE (*,*) TRIM(homedir)
4958 @section @code{GETGID} --- Group ID function
4960 @cindex system, group id
4963 @item @emph{Description}:
4964 Returns the numerical group ID of the current process.
4966 @item @emph{Standard}:
4972 @item @emph{Syntax}:
4973 @code{RESULT = GETGID()}
4975 @item @emph{Return value}:
4976 The return value of @code{GETGID} is an @code{INTEGER} of the default
4980 @item @emph{Example}:
4981 See @code{GETPID} for an example.
4983 @item @emph{See also}:
4984 @ref{GETPID}, @ref{GETUID}
4990 @section @code{GETLOG} --- Get login name
4992 @cindex system, login name
4996 @item @emph{Description}:
4997 Gets the username under which the program is running.
4999 @item @emph{Standard}:
5005 @item @emph{Syntax}:
5006 @code{CALL GETLOG(LOGIN)}
5008 @item @emph{Arguments}:
5009 @multitable @columnfractions .15 .70
5010 @item @var{LOGIN} @tab Shall be of type @code{CHARACTER(*)}.
5013 @item @emph{Return value}:
5014 Stores the current user name in @var{LOGIN}. (On systems where POSIX
5015 functions @code{geteuid} and @code{getpwuid} are not available, and
5016 the @code{getlogin} function is not implemented either, this will
5017 return a blank string.)
5019 @item @emph{Example}:
5022 CHARACTER(32) :: login
5028 @item @emph{See also}:
5035 @section @code{GETPID} --- Process ID function
5037 @cindex system, process id
5041 @item @emph{Description}:
5042 Returns the numerical process identifier of the current process.
5044 @item @emph{Standard}:
5050 @item @emph{Syntax}:
5051 @code{RESULT = GETPID()}
5053 @item @emph{Return value}:
5054 The return value of @code{GETPID} is an @code{INTEGER} of the default
5058 @item @emph{Example}:
5061 print *, "The current process ID is ", getpid()
5062 print *, "Your numerical user ID is ", getuid()
5063 print *, "Your numerical group ID is ", getgid()
5067 @item @emph{See also}:
5068 @ref{GETGID}, @ref{GETUID}
5074 @section @code{GETUID} --- User ID function
5076 @cindex system, user id
5080 @item @emph{Description}:
5081 Returns the numerical user ID of the current process.
5083 @item @emph{Standard}:
5089 @item @emph{Syntax}:
5090 @code{RESULT = GETUID()}
5092 @item @emph{Return value}:
5093 The return value of @code{GETUID} is an @code{INTEGER} of the default
5097 @item @emph{Example}:
5098 See @code{GETPID} for an example.
5100 @item @emph{See also}:
5101 @ref{GETPID}, @ref{GETLOG}
5107 @section @code{GMTIME} --- Convert time to GMT info
5109 @cindex time, conversion to GMT info
5112 @item @emph{Description}:
5113 Given a system time value @var{STIME} (as provided by the @code{TIME8()}
5114 intrinsic), fills @var{TARRAY} with values extracted from it appropriate
5115 to the UTC time zone (Universal Coordinated Time, also known in some
5116 countries as GMT, Greenwich Mean Time), using @code{gmtime(3)}.
5118 @item @emph{Standard}:
5124 @item @emph{Syntax}:
5125 @code{CALL GMTIME(STIME, TARRAY)}
5127 @item @emph{Arguments}:
5128 @multitable @columnfractions .15 .70
5129 @item @var{STIME} @tab An @code{INTEGER(*)} scalar expression
5130 corresponding to a system time, with
5132 @item @var{TARRAY} @tab A default @code{INTEGER} array with 9 elements,
5133 with @code{INTENT(OUT)}.
5136 @item @emph{Return value}:
5137 The elements of @var{TARRAY} are assigned as follows:
5139 @item Seconds after the minute, range 0--59 or 0--61 to allow for leap
5141 @item Minutes after the hour, range 0--59
5142 @item Hours past midnight, range 0--23
5143 @item Day of month, range 0--31
5144 @item Number of months since January, range 0--12
5145 @item Years since 1900
5146 @item Number of days since Sunday, range 0--6
5147 @item Days since January 1
5148 @item Daylight savings indicator: positive if daylight savings is in
5149 effect, zero if not, and negative if the information is not
5153 @item @emph{See also}:
5154 @ref{CTIME}, @ref{LTIME}, @ref{TIME}, @ref{TIME8}
5161 @section @code{HOSTNM} --- Get system host name
5163 @cindex system, host name
5166 @item @emph{Description}:
5167 Retrieves the host name of the system on which the program is running.
5169 This intrinsic is provided in both subroutine and function forms; however,
5170 only one form can be used in any given program unit.
5172 @item @emph{Standard}:
5176 Subroutine, function
5178 @item @emph{Syntax}:
5179 @multitable @columnfractions .80
5180 @item @code{CALL HOSTNM(NAME[, STATUS])}
5181 @item @code{STATUS = HOSTNM(NAME)}
5184 @item @emph{Arguments}:
5185 @multitable @columnfractions .15 .70
5186 @item @var{NAME} @tab Shall of type @code{CHARACTER(*)}.
5187 @item @var{STATUS} @tab (Optional) status flag of type @code{INTEGER}.
5188 Returns 0 on success, or a system specific error
5192 @item @emph{Return value}:
5193 In either syntax, @var{NAME} is set to the current hostname if it can
5194 be obtained, or to a blank string otherwise.
5201 @section @code{HUGE} --- Largest number of a kind
5203 @cindex limits, largest number
5204 @cindex model representation, largest number
5207 @item @emph{Description}:
5208 @code{HUGE(X)} returns the largest number that is not an infinity in
5209 the model of the type of @code{X}.
5211 @item @emph{Standard}:
5217 @item @emph{Syntax}:
5218 @code{RESULT = HUGE(X)}
5220 @item @emph{Arguments}:
5221 @multitable @columnfractions .15 .70
5222 @item @var{X} @tab Shall be of type @code{REAL} or @code{INTEGER}.
5225 @item @emph{Return value}:
5226 The return value is of the same type and kind as @var{X}
5228 @item @emph{Example}:
5230 program test_huge_tiny
5231 print *, huge(0), huge(0.0), huge(0.0d0)
5232 print *, tiny(0.0), tiny(0.0d0)
5233 end program test_huge_tiny
5240 @section @code{HYPOT} --- Euclidean distance function
5242 @cindex Euclidean distance
5245 @item @emph{Description}:
5246 @code{HYPOT(X,Y)} is the Euclidean distance function. It is equal to
5247 @math{\sqrt{X^2 + Y^2}}, without undue underflow or overflow.
5249 @item @emph{Standard}:
5250 Fortran 2008 and later
5255 @item @emph{Syntax}:
5256 @code{RESULT = HYPOT(X,Y)}
5258 @item @emph{Arguments}:
5259 @multitable @columnfractions .15 .70
5260 @item @var{X} @tab The type shall be @code{REAL}.
5261 @item @var{Y} @tab The type and kind type parameter shall be the same as
5265 @item @emph{Return value}:
5266 The return value has the same type and kind type parameter as @var{X}.
5268 @item @emph{Example}:
5271 real(4) :: x = 1.e0_4, y = 0.5e0_4
5273 end program test_hypot
5280 @section @code{IACHAR} --- Code in @acronym{ASCII} collating sequence
5282 @cindex @acronym{ASCII} collating sequence
5283 @cindex collating sequence, @acronym{ASCII}
5284 @cindex conversion, to integer
5287 @item @emph{Description}:
5288 @code{IACHAR(C)} returns the code for the @acronym{ASCII} character
5289 in the first character position of @code{C}.
5291 @item @emph{Standard}:
5297 @item @emph{Syntax}:
5298 @code{RESULT = IACHAR(C [, KIND])}
5300 @item @emph{Arguments}:
5301 @multitable @columnfractions .15 .70
5302 @item @var{C} @tab Shall be a scalar @code{CHARACTER}, with @code{INTENT(IN)}
5303 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
5304 expression indicating the kind parameter of
5308 @item @emph{Return value}:
5309 The return value is of type @code{INTEGER} and of kind @var{KIND}. If
5310 @var{KIND} is absent, the return value is of default integer kind.
5312 @item @emph{Example}:
5317 end program test_iachar
5321 See @ref{ICHAR} for a discussion of converting between numerical values
5322 and formatted string representations.
5324 @item @emph{See also}:
5325 @ref{ACHAR}, @ref{CHAR}, @ref{ICHAR}
5332 @section @code{IAND} --- Bitwise logical and
5334 @cindex bitwise logical and
5335 @cindex logical and, bitwise
5338 @item @emph{Description}:
5339 Bitwise logical @code{AND}.
5341 @item @emph{Standard}:
5347 @item @emph{Syntax}:
5348 @code{RESULT = IAND(I, J)}
5350 @item @emph{Arguments}:
5351 @multitable @columnfractions .15 .70
5352 @item @var{I} @tab The type shall be @code{INTEGER(*)}.
5353 @item @var{J} @tab The type shall be @code{INTEGER(*)}, of the same
5354 kind as @var{I}. (As a GNU extension, different kinds are also
5358 @item @emph{Return value}:
5359 The return type is @code{INTEGER(*)}, of the same kind as the
5360 arguments. (If the argument kinds differ, it is of the same kind as
5361 the larger argument.)
5363 @item @emph{Example}:
5367 DATA a / Z'F' /, b / Z'3' /
5368 WRITE (*,*) IAND(a, b)
5372 @item @emph{See also}:
5373 @ref{IOR}, @ref{IEOR}, @ref{IBITS}, @ref{IBSET}, @ref{IBCLR}, @ref{NOT}
5380 @section @code{IARGC} --- Get the number of command line arguments
5382 @cindex command-line arguments
5383 @cindex command-line arguments, number of
5384 @cindex arguments, to program
5387 @item @emph{Description}:
5388 @code{IARGC()} returns the number of arguments passed on the
5389 command line when the containing program was invoked.
5391 This intrinsic routine is provided for backwards compatibility with
5392 GNU Fortran 77. In new code, programmers should consider the use of
5393 the @ref{COMMAND_ARGUMENT_COUNT} intrinsic defined by the Fortran 2003
5396 @item @emph{Standard}:
5402 @item @emph{Syntax}:
5403 @code{RESULT = IARGC()}
5405 @item @emph{Arguments}:
5408 @item @emph{Return value}:
5409 The number of command line arguments, type @code{INTEGER(4)}.
5411 @item @emph{Example}:
5414 @item @emph{See also}:
5415 GNU Fortran 77 compatibility subroutine: @ref{GETARG}
5417 Fortran 2003 functions and subroutines: @ref{GET_COMMAND},
5418 @ref{GET_COMMAND_ARGUMENT}, @ref{COMMAND_ARGUMENT_COUNT}
5424 @section @code{IBCLR} --- Clear bit
5430 @item @emph{Description}:
5431 @code{IBCLR} returns the value of @var{I} with the bit at position
5432 @var{POS} set to zero.
5434 @item @emph{Standard}:
5440 @item @emph{Syntax}:
5441 @code{RESULT = IBCLR(I, POS)}
5443 @item @emph{Arguments}:
5444 @multitable @columnfractions .15 .70
5445 @item @var{I} @tab The type shall be @code{INTEGER(*)}.
5446 @item @var{POS} @tab The type shall be @code{INTEGER(*)}.
5449 @item @emph{Return value}:
5450 The return value is of type @code{INTEGER(*)} and of the same kind as
5453 @item @emph{See also}:
5454 @ref{IBITS}, @ref{IBSET}, @ref{IAND}, @ref{IOR}, @ref{IEOR}, @ref{MVBITS}
5461 @section @code{IBITS} --- Bit extraction
5464 @cindex bits, extract
5467 @item @emph{Description}:
5468 @code{IBITS} extracts a field of length @var{LEN} from @var{I},
5469 starting from bit position @var{POS} and extending left for @var{LEN}
5470 bits. The result is right-justified and the remaining bits are
5471 zeroed. The value of @code{POS+LEN} must be less than or equal to the
5472 value @code{BIT_SIZE(I)}.
5474 @item @emph{Standard}:
5480 @item @emph{Syntax}:
5481 @code{RESULT = IBITS(I, POS, LEN)}
5483 @item @emph{Arguments}:
5484 @multitable @columnfractions .15 .70
5485 @item @var{I} @tab The type shall be @code{INTEGER(*)}.
5486 @item @var{POS} @tab The type shall be @code{INTEGER(*)}.
5487 @item @var{LEN} @tab The type shall be @code{INTEGER(*)}.
5490 @item @emph{Return value}:
5491 The return value is of type @code{INTEGER(*)} and of the same kind as
5494 @item @emph{See also}:
5495 @ref{BIT_SIZE}, @ref{IBCLR}, @ref{IBSET}, @ref{IAND}, @ref{IOR}, @ref{IEOR}
5501 @section @code{IBSET} --- Set bit
5506 @item @emph{Description}:
5507 @code{IBSET} returns the value of @var{I} with the bit at position
5508 @var{POS} set to one.
5510 @item @emph{Standard}:
5516 @item @emph{Syntax}:
5517 @code{RESULT = IBSET(I, POS)}
5519 @item @emph{Arguments}:
5520 @multitable @columnfractions .15 .70
5521 @item @var{I} @tab The type shall be @code{INTEGER(*)}.
5522 @item @var{POS} @tab The type shall be @code{INTEGER(*)}.
5525 @item @emph{Return value}:
5526 The return value is of type @code{INTEGER(*)} and of the same kind as
5529 @item @emph{See also}:
5530 @ref{IBCLR}, @ref{IBITS}, @ref{IAND}, @ref{IOR}, @ref{IEOR}, @ref{MVBITS}
5537 @section @code{ICHAR} --- Character-to-integer conversion function
5539 @cindex conversion, to integer
5542 @item @emph{Description}:
5543 @code{ICHAR(C)} returns the code for the character in the first character
5544 position of @code{C} in the system's native character set.
5545 The correspondence between characters and their codes is not necessarily
5546 the same across different GNU Fortran implementations.
5548 @item @emph{Standard}:
5554 @item @emph{Syntax}:
5555 @code{RESULT = ICHAR(C [, KIND])}
5557 @item @emph{Arguments}:
5558 @multitable @columnfractions .15 .70
5559 @item @var{C} @tab Shall be a scalar @code{CHARACTER}, with @code{INTENT(IN)}
5560 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
5561 expression indicating the kind parameter of
5565 @item @emph{Return value}:
5566 The return value is of type @code{INTEGER} and of kind @var{KIND}. If
5567 @var{KIND} is absent, the return value is of default integer kind.
5569 @item @emph{Example}:
5574 end program test_ichar
5578 No intrinsic exists to convert between a numeric value and a formatted
5579 character string representation -- for instance, given the
5580 @code{CHARACTER} value @code{'154'}, obtaining an @code{INTEGER} or
5581 @code{REAL} value with the value 154, or vice versa. Instead, this
5582 functionality is provided by internal-file I/O, as in the following
5587 character(len=10) string, string2
5590 ! Convert a string to a numeric value
5591 read (string,'(I10)') value
5594 ! Convert a value to a formatted string
5595 write (string2,'(I10)') value
5597 end program read_val
5600 @item @emph{See also}:
5601 @ref{ACHAR}, @ref{CHAR}, @ref{IACHAR}
5608 @section @code{IDATE} --- Get current local time subroutine (day/month/year)
5610 @cindex date, current
5611 @cindex current date
5614 @item @emph{Description}:
5615 @code{IDATE(TARRAY)} Fills @var{TARRAY} with the numerical values at the
5616 current local time. The day (in the range 1-31), month (in the range 1-12),
5617 and year appear in elements 1, 2, and 3 of @var{TARRAY}, respectively.
5618 The year has four significant digits.
5620 @item @emph{Standard}:
5626 @item @emph{Syntax}:
5627 @code{CALL IDATE(TARRAY)}
5629 @item @emph{Arguments}:
5630 @multitable @columnfractions .15 .70
5631 @item @var{TARRAY} @tab The type shall be @code{INTEGER, DIMENSION(3)} and
5632 the kind shall be the default integer kind.
5635 @item @emph{Return value}:
5638 @item @emph{Example}:
5641 integer, dimension(3) :: tarray
5646 end program test_idate
5653 @section @code{IEOR} --- Bitwise logical exclusive or
5655 @cindex bitwise logical exclusive or
5656 @cindex logical exclusive or, bitwise
5659 @item @emph{Description}:
5660 @code{IEOR} returns the bitwise boolean exclusive-OR of @var{I} and
5663 @item @emph{Standard}:
5669 @item @emph{Syntax}:
5670 @code{RESULT = IEOR(I, J)}
5672 @item @emph{Arguments}:
5673 @multitable @columnfractions .15 .70
5674 @item @var{I} @tab The type shall be @code{INTEGER(*)}.
5675 @item @var{J} @tab The type shall be @code{INTEGER(*)}, of the same
5676 kind as @var{I}. (As a GNU extension, different kinds are also
5680 @item @emph{Return value}:
5681 The return type is @code{INTEGER(*)}, of the same kind as the
5682 arguments. (If the argument kinds differ, it is of the same kind as
5683 the larger argument.)
5685 @item @emph{See also}:
5686 @ref{IOR}, @ref{IAND}, @ref{IBITS}, @ref{IBSET}, @ref{IBCLR}, @ref{NOT}
5692 @section @code{IERRNO} --- Get the last system error number
5694 @cindex system, error handling
5697 @item @emph{Description}:
5698 Returns the last system error number, as given by the C @code{errno()}
5701 @item @emph{Standard}:
5707 @item @emph{Syntax}:
5708 @code{RESULT = IERRNO()}
5710 @item @emph{Arguments}:
5713 @item @emph{Return value}:
5714 The return value is of type @code{INTEGER} and of the default integer
5717 @item @emph{See also}:
5723 @node INDEX intrinsic
5724 @section @code{INDEX} --- Position of a substring within a string
5726 @cindex substring position
5727 @cindex string, find substring
5730 @item @emph{Description}:
5731 Returns the position of the start of the first occurrence of string
5732 @var{SUBSTRING} as a substring in @var{STRING}, counting from one. If
5733 @var{SUBSTRING} is not present in @var{STRING}, zero is returned. If
5734 the @var{BACK} argument is present and true, the return value is the
5735 start of the last occurrence rather than the first.
5737 @item @emph{Standard}:
5743 @item @emph{Syntax}:
5744 @code{RESULT = INDEX(STRING, SUBSTRING [, BACK [, KIND]])}
5746 @item @emph{Arguments}:
5747 @multitable @columnfractions .15 .70
5748 @item @var{STRING} @tab Shall be a scalar @code{CHARACTER(*)}, with
5750 @item @var{SUBSTRING} @tab Shall be a scalar @code{CHARACTER(*)}, with
5752 @item @var{BACK} @tab (Optional) Shall be a scalar @code{LOGICAL(*)}, with
5754 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
5755 expression indicating the kind parameter of
5759 @item @emph{Return value}:
5760 The return value is of type @code{INTEGER} and of kind @var{KIND}. If
5761 @var{KIND} is absent, the return value is of default integer kind.
5763 @item @emph{See also}:
5764 @ref{SCAN}, @ref{VERIFY}
5770 @section @code{INT} --- Convert to integer type
5774 @cindex conversion, to integer
5777 @item @emph{Description}:
5778 Convert to integer type
5780 @item @emph{Standard}:
5786 @item @emph{Syntax}:
5787 @code{RESULT = INT(A [, KIND))}
5789 @item @emph{Arguments}:
5790 @multitable @columnfractions .15 .70
5791 @item @var{A} @tab Shall be of type @code{INTEGER(*)},
5792 @code{REAL(*)}, or @code{COMPLEX(*)}.
5793 @item @var{KIND} @tab (Optional) An @code{INTEGER(*)} initialization
5794 expression indicating the kind parameter of
5798 @item @emph{Return value}:
5799 These functions return a @code{INTEGER(*)} variable or array under
5800 the following rules:
5804 If @var{A} is of type @code{INTEGER(*)}, @code{INT(A) = A}
5806 If @var{A} is of type @code{REAL(*)} and @math{|A| < 1}, @code{INT(A)} equals @code{0}.
5807 If @math{|A| \geq 1}, then @code{INT(A)} equals the largest integer that does not exceed
5808 the range of @var{A} and whose sign is the same as the sign of @var{A}.
5810 If @var{A} is of type @code{COMPLEX(*)}, rule B is applied to the real part of @var{A}.
5813 @item @emph{Example}:
5817 complex :: z = (-3.7, 1.0)
5819 print *, int(z), int(z,8)
5823 @item @emph{Specific names}:
5824 @multitable @columnfractions .20 .20 .20 .25
5825 @item Name @tab Argument @tab Return type @tab Standard
5826 @item @code{IFIX(A)} @tab @code{REAL(4) A} @tab @code{INTEGER} @tab F77 and later
5827 @item @code{IDINT(A)} @tab @code{REAL(8) A} @tab @code{INTEGER} @tab F77 and later
5835 @section @code{INT2} --- Convert to 16-bit integer type
5838 @cindex conversion, to integer
5841 @item @emph{Description}:
5842 Convert to a @code{KIND=2} integer type. This is equivalent to the
5843 standard @code{INT} intrinsic with an optional argument of
5844 @code{KIND=2}, and is only included for backwards compatibility.
5846 The @code{SHORT} intrinsic is equivalent to @code{INT2}.
5848 @item @emph{Standard}:
5854 @item @emph{Syntax}:
5855 @code{RESULT = INT2(A)}
5857 @item @emph{Arguments}:
5858 @multitable @columnfractions .15 .70
5859 @item @var{A} @tab Shall be of type @code{INTEGER(*)},
5860 @code{REAL(*)}, or @code{COMPLEX(*)}.
5863 @item @emph{Return value}:
5864 The return value is a @code{INTEGER(2)} variable.
5866 @item @emph{See also}:
5867 @ref{INT}, @ref{INT8}, @ref{LONG}
5873 @section @code{INT8} --- Convert to 64-bit integer type
5875 @cindex conversion, to integer
5878 @item @emph{Description}:
5879 Convert to a @code{KIND=8} integer type. This is equivalent to the
5880 standard @code{INT} intrinsic with an optional argument of
5881 @code{KIND=8}, and is only included for backwards compatibility.
5883 @item @emph{Standard}:
5889 @item @emph{Syntax}:
5890 @code{RESULT = INT8(A)}
5892 @item @emph{Arguments}:
5893 @multitable @columnfractions .15 .70
5894 @item @var{A} @tab Shall be of type @code{INTEGER(*)},
5895 @code{REAL(*)}, or @code{COMPLEX(*)}.
5898 @item @emph{Return value}:
5899 The return value is a @code{INTEGER(8)} variable.
5901 @item @emph{See also}:
5902 @ref{INT}, @ref{INT2}, @ref{LONG}
5908 @section @code{IOR} --- Bitwise logical or
5910 @cindex bitwise logical or
5911 @cindex logical or, bitwise
5914 @item @emph{Description}:
5915 @code{IOR} returns the bitwise boolean inclusive-OR of @var{I} and
5918 @item @emph{Standard}:
5924 @item @emph{Syntax}:
5925 @code{RESULT = IOR(I, J)}
5927 @item @emph{Arguments}:
5928 @multitable @columnfractions .15 .70
5929 @item @var{I} @tab The type shall be @code{INTEGER(*)}.
5930 @item @var{J} @tab The type shall be @code{INTEGER(*)}, of the same
5931 kind as @var{I}. (As a GNU extension, different kinds are also
5935 @item @emph{Return value}:
5936 The return type is @code{INTEGER(*)}, of the same kind as the
5937 arguments. (If the argument kinds differ, it is of the same kind as
5938 the larger argument.)
5940 @item @emph{See also}:
5941 @ref{IEOR}, @ref{IAND}, @ref{IBITS}, @ref{IBSET}, @ref{IBCLR}, @ref{NOT}
5947 @section @code{IRAND} --- Integer pseudo-random number
5949 @cindex random number generation
5952 @item @emph{Description}:
5953 @code{IRAND(FLAG)} returns a pseudo-random number from a uniform
5954 distribution between 0 and a system-dependent limit (which is in most
5955 cases 2147483647). If @var{FLAG} is 0, the next number
5956 in the current sequence is returned; if @var{FLAG} is 1, the generator
5957 is restarted by @code{CALL SRAND(0)}; if @var{FLAG} has any other value,
5958 it is used as a new seed with @code{SRAND}.
5960 This intrinsic routine is provided for backwards compatibility with
5961 GNU Fortran 77. It implements a simple modulo generator as provided
5962 by @command{g77}. For new code, one should consider the use of
5963 @ref{RANDOM_NUMBER} as it implements a superior algorithm.
5965 @item @emph{Standard}:
5971 @item @emph{Syntax}:
5972 @code{RESULT = IRAND(FLAG)}
5974 @item @emph{Arguments}:
5975 @multitable @columnfractions .15 .70
5976 @item @var{FLAG} @tab Shall be a scalar @code{INTEGER} of kind 4.
5979 @item @emph{Return value}:
5980 The return value is of @code{INTEGER(kind=4)} type.
5982 @item @emph{Example}:
5985 integer,parameter :: seed = 86456
5988 print *, irand(), irand(), irand(), irand()
5989 print *, irand(seed), irand(), irand(), irand()
5990 end program test_irand
5998 @section @code{IS_IOSTAT_END} --- Test for end-of-file value
5999 @fnindex IS_IOSTAT_END
6000 @cindex IOSTAT, end of file
6003 @item @emph{Description}:
6004 @code{IS_IOSTAT_END} tests whether an variable has the value of the I/O
6005 status ``end of file''. The function is equivalent to comparing the variable
6006 with the @code{IOSTAT_END} parameter of the intrinsic module
6007 @code{ISO_FORTRAN_ENV}.
6009 @item @emph{Standard}:
6010 Fortran 2003 and later
6015 @item @emph{Syntax}:
6016 @code{RESULT = IS_IOSTAT_END(I)}
6018 @item @emph{Arguments}:
6019 @multitable @columnfractions .15 .70
6020 @item @var{I} @tab Shall be of the type @code{INTEGER}.
6023 @item @emph{Return value}:
6024 Returns a @code{LOGICAL} of the default kind, which @code{.TRUE.} if
6025 @var{I} has the value which indicates an end of file condition for
6026 IOSTAT= specifiers, and is @code{.FALSE.} otherwise.
6028 @item @emph{Example}:
6033 OPEN(88, FILE='test.dat')
6034 READ(88, *, IOSTAT=stat) i
6035 IF(IS_IOSTAT_END(stat)) STOP 'END OF FILE'
6043 @section @code{IS_IOSTAT_EOR} --- Test for end-of-record value
6044 @fnindex IS_IOSTAT_EOR
6045 @cindex IOSTAT, end of record
6048 @item @emph{Description}:
6049 @code{IS_IOSTAT_EOR} tests whether an variable has the value of the I/O
6050 status ``end of record''. The function is equivalent to comparing the
6051 variable with the @code{IOSTAT_EOR} parameter of the intrinsic module
6052 @code{ISO_FORTRAN_ENV}.
6054 @item @emph{Standard}:
6055 Fortran 2003 and later
6060 @item @emph{Syntax}:
6061 @code{RESULT = IS_IOSTAT_EOR(I)}
6063 @item @emph{Arguments}:
6064 @multitable @columnfractions .15 .70
6065 @item @var{I} @tab Shall be of the type @code{INTEGER}.
6068 @item @emph{Return value}:
6069 Returns a @code{LOGICAL} of the default kind, which @code{.TRUE.} if
6070 @var{I} has the value which indicates an end of file condition for
6071 IOSTAT= specifiers, and is @code{.FALSE.} otherwise.
6073 @item @emph{Example}:
6077 INTEGER :: stat, i(50)
6078 OPEN(88, FILE='test.dat', FORM='UNFORMATTED')
6079 READ(88, IOSTAT=stat) i
6080 IF(IS_IOSTAT_EOR(stat)) STOP 'END OF RECORD'
6088 @section @code{ISATTY} --- Whether a unit is a terminal device.
6090 @cindex system, terminal
6093 @item @emph{Description}:
6094 Determine whether a unit is connected to a terminal device.
6096 @item @emph{Standard}:
6102 @item @emph{Syntax}:
6103 @code{RESULT = ISATTY(UNIT)}
6105 @item @emph{Arguments}:
6106 @multitable @columnfractions .15 .70
6107 @item @var{UNIT} @tab Shall be a scalar @code{INTEGER(*)}.
6110 @item @emph{Return value}:
6111 Returns @code{.TRUE.} if the @var{UNIT} is connected to a terminal
6112 device, @code{.FALSE.} otherwise.
6114 @item @emph{Example}:
6117 INTEGER(kind=1) :: unit
6119 write(*,*) isatty(unit=unit)
6123 @item @emph{See also}:
6130 @section @code{ISHFT} --- Shift bits
6135 @item @emph{Description}:
6136 @code{ISHFT} returns a value corresponding to @var{I} with all of the
6137 bits shifted @var{SHIFT} places. A value of @var{SHIFT} greater than
6138 zero corresponds to a left shift, a value of zero corresponds to no
6139 shift, and a value less than zero corresponds to a right shift. If the
6140 absolute value of @var{SHIFT} is greater than @code{BIT_SIZE(I)}, the
6141 value is undefined. Bits shifted out from the left end or right end are
6142 lost; zeros are shifted in from the opposite end.
6144 @item @emph{Standard}:
6150 @item @emph{Syntax}:
6151 @code{RESULT = ISHFT(I, SHIFT)}
6153 @item @emph{Arguments}:
6154 @multitable @columnfractions .15 .70
6155 @item @var{I} @tab The type shall be @code{INTEGER(*)}.
6156 @item @var{SHIFT} @tab The type shall be @code{INTEGER(*)}.
6159 @item @emph{Return value}:
6160 The return value is of type @code{INTEGER(*)} and of the same kind as
6163 @item @emph{See also}:
6170 @section @code{ISHFTC} --- Shift bits circularly
6172 @cindex bits, shift circular
6175 @item @emph{Description}:
6176 @code{ISHFTC} returns a value corresponding to @var{I} with the
6177 rightmost @var{SIZE} bits shifted circularly @var{SHIFT} places; that
6178 is, bits shifted out one end are shifted into the opposite end. A value
6179 of @var{SHIFT} greater than zero corresponds to a left shift, a value of
6180 zero corresponds to no shift, and a value less than zero corresponds to
6181 a right shift. The absolute value of @var{SHIFT} must be less than
6182 @var{SIZE}. If the @var{SIZE} argument is omitted, it is taken to be
6183 equivalent to @code{BIT_SIZE(I)}.
6185 @item @emph{Standard}:
6191 @item @emph{Syntax}:
6192 @code{RESULT = ISHFTC(I, SHIFT [, SIZE])}
6194 @item @emph{Arguments}:
6195 @multitable @columnfractions .15 .70
6196 @item @var{I} @tab The type shall be @code{INTEGER(*)}.
6197 @item @var{SHIFT} @tab The type shall be @code{INTEGER(*)}.
6198 @item @var{SIZE} @tab (Optional) The type shall be @code{INTEGER(*)};
6199 the value must be greater than zero and less than or equal to
6203 @item @emph{Return value}:
6204 The return value is of type @code{INTEGER(*)} and of the same kind as
6207 @item @emph{See also}:
6214 @section @code{ISNAN} --- Test for a NaN
6219 @item @emph{Description}:
6220 @code{ISNAN} tests whether a floating-point value is an IEEE
6222 @item @emph{Standard}:
6228 @item @emph{Syntax}:
6231 @item @emph{Arguments}:
6232 @multitable @columnfractions .15 .70
6233 @item @var{X} @tab Variable of the type @code{REAL}.
6237 @item @emph{Return value}:
6238 Returns a default-kind @code{LOGICAL}. The returned value is @code{TRUE}
6239 if @var{X} is a NaN and @code{FALSE} otherwise.
6241 @item @emph{Example}:
6248 if (isnan(x)) stop '"x" is a NaN'
6249 end program test_nan
6256 @section @code{ITIME} --- Get current local time subroutine (hour/minutes/seconds)
6258 @cindex time, current
6259 @cindex current time
6262 @item @emph{Description}:
6263 @code{IDATE(TARRAY)} Fills @var{TARRAY} with the numerical values at the
6264 current local time. The hour (in the range 1-24), minute (in the range 1-60),
6265 and seconds (in the range 1-60) appear in elements 1, 2, and 3 of @var{TARRAY},
6268 @item @emph{Standard}:
6274 @item @emph{Syntax}:
6275 @code{CALL ITIME(TARRAY)}
6277 @item @emph{Arguments}:
6278 @multitable @columnfractions .15 .70
6279 @item @var{TARRAY} @tab The type shall be @code{INTEGER, DIMENSION(3)}
6280 and the kind shall be the default integer kind.
6283 @item @emph{Return value}:
6287 @item @emph{Example}:
6290 integer, dimension(3) :: tarray
6295 end program test_itime
6302 @section @code{KILL} --- Send a signal to a process
6306 @item @emph{Description}:
6307 @item @emph{Standard}:
6308 Sends the signal specified by @var{SIGNAL} to the process @var{PID}.
6311 This intrinsic is provided in both subroutine and function forms; however,
6312 only one form can be used in any given program unit.
6315 Subroutine, function
6317 @item @emph{Syntax}:
6318 @code{CALL KILL(PID, SIGNAL [, STATUS])}
6320 @item @emph{Arguments}:
6321 @multitable @columnfractions .15 .70
6322 @item @var{PID} @tab Shall be a scalar @code{INTEGER}, with
6324 @item @var{SIGNAL} @tab Shall be a scalar @code{INTEGER}, with
6326 @item @var{STATUS} @tab (Optional) status flag of type @code{INTEGER(4)} or
6327 @code{INTEGER(8)}. Returns 0 on success, or a
6328 system-specific error code otherwise.
6331 @item @emph{See also}:
6332 @ref{ABORT}, @ref{EXIT}
6338 @section @code{KIND} --- Kind of an entity
6343 @item @emph{Description}:
6344 @code{KIND(X)} returns the kind value of the entity @var{X}.
6346 @item @emph{Standard}:
6352 @item @emph{Syntax}:
6355 @item @emph{Arguments}:
6356 @multitable @columnfractions .15 .70
6357 @item @var{X} @tab Shall be of type @code{LOGICAL}, @code{INTEGER},
6358 @code{REAL}, @code{COMPLEX} or @code{CHARACTER}.
6361 @item @emph{Return value}:
6362 The return value is a scalar of type @code{INTEGER} and of the default
6365 @item @emph{Example}:
6368 integer,parameter :: kc = kind(' ')
6369 integer,parameter :: kl = kind(.true.)
6371 print *, "The default character kind is ", kc
6372 print *, "The default logical kind is ", kl
6373 end program test_kind
6381 @section @code{LBOUND} --- Lower dimension bounds of an array
6383 @cindex array, lower bound
6386 @item @emph{Description}:
6387 Returns the lower bounds of an array, or a single lower bound
6388 along the @var{DIM} dimension.
6389 @item @emph{Standard}:
6395 @item @emph{Syntax}:
6396 @code{RESULT = LBOUND(ARRAY [, DIM [, KIND]])}
6398 @item @emph{Arguments}:
6399 @multitable @columnfractions .15 .70
6400 @item @var{ARRAY} @tab Shall be an array, of any type.
6401 @item @var{DIM} @tab (Optional) Shall be a scalar @code{INTEGER(*)}.
6402 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
6403 expression indicating the kind parameter of
6407 @item @emph{Return value}:
6408 The return value is of type @code{INTEGER} and of kind @var{KIND}. If
6409 @var{KIND} is absent, the return value is of default integer kind.
6410 If @var{DIM} is absent, the result is an array of the lower bounds of
6411 @var{ARRAY}. If @var{DIM} is present, the result is a scalar
6412 corresponding to the lower bound of the array along that dimension. If
6413 @var{ARRAY} is an expression rather than a whole array or array
6414 structure component, or if it has a zero extent along the relevant
6415 dimension, the lower bound is taken to be 1.
6417 @item @emph{See also}:
6424 @section @code{LEN} --- Length of a character entity
6426 @cindex string, length
6429 @item @emph{Description}:
6430 Returns the length of a character string. If @var{STRING} is an array,
6431 the length of an element of @var{STRING} is returned. Note that
6432 @var{STRING} need not be defined when this intrinsic is invoked, since
6433 only the length, not the content, of @var{STRING} is needed.
6435 @item @emph{Standard}:
6441 @item @emph{Syntax}:
6442 @code{L = LEN(STRING [, KIND])}
6444 @item @emph{Arguments}:
6445 @multitable @columnfractions .15 .70
6446 @item @var{STRING} @tab Shall be a scalar or array of type
6447 @code{CHARACTER(*)}, with @code{INTENT(IN)}
6448 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
6449 expression indicating the kind parameter of
6453 @item @emph{Return value}:
6454 The return value is of type @code{INTEGER} and of kind @var{KIND}. If
6455 @var{KIND} is absent, the return value is of default integer kind.
6457 @item @emph{See also}:
6458 @ref{LEN_TRIM}, @ref{ADJUSTL}, @ref{ADJUSTR}
6464 @section @code{LEN_TRIM} --- Length of a character entity without trailing blank characters
6466 @cindex string, length, without trailing whitespace
6469 @item @emph{Description}:
6470 Returns the length of a character string, ignoring any trailing blanks.
6472 @item @emph{Standard}:
6478 @item @emph{Syntax}:
6479 @code{RESULT = LEN_TRIM(STRING [, KIND])}
6481 @item @emph{Arguments}:
6482 @multitable @columnfractions .15 .70
6483 @item @var{STRING} @tab Shall be a scalar of type @code{CHARACTER(*)},
6484 with @code{INTENT(IN)}
6485 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
6486 expression indicating the kind parameter of
6490 @item @emph{Return value}:
6491 The return value is of type @code{INTEGER} and of kind @var{KIND}. If
6492 @var{KIND} is absent, the return value is of default integer kind.
6494 @item @emph{See also}:
6495 @ref{LEN}, @ref{ADJUSTL}, @ref{ADJUSTR}
6501 @section @code{LOG_GAMMA} --- Logarithm of the Gamma function
6506 @cindex Gamma function, logarithm of
6509 @item @emph{Description}:
6510 @code{LOG_GAMMA(X)} computes the natural logarithm of the absolute value
6511 of the Gamma (@math{\Gamma}) function.
6513 @item @emph{Standard}:
6514 Fortran 2008 and later
6519 @item @emph{Syntax}:
6520 @code{X = LOG_GAMMA(X)}
6522 @item @emph{Arguments}:
6523 @multitable @columnfractions .15 .70
6524 @item @var{X} @tab Shall be of type @code{REAL} and neither zero
6525 nor a negative integer.
6528 @item @emph{Return value}:
6529 The return value is of type @code{REAL} of the same kind as @var{X}.
6531 @item @emph{Example}:
6533 program test_log_gamma
6535 x = lgamma(x) ! returns 0.0
6536 end program test_log_gamma
6539 @item @emph{Specific names}:
6540 @multitable @columnfractions .20 .20 .20 .25
6541 @item Name @tab Argument @tab Return type @tab Standard
6542 @item @code{LGAMMA(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab GNU Extension
6543 @item @code{ALGAMA(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab GNU Extension
6544 @item @code{DLGAMA(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU Extension
6547 @item @emph{See also}:
6548 Gamma function: @ref{GAMMA}
6555 @section @code{LGE} --- Lexical greater than or equal
6557 @cindex lexical comparison of strings
6558 @cindex string, comparison
6561 @item @emph{Description}:
6562 Determines whether one string is lexically greater than or equal to
6563 another string, where the two strings are interpreted as containing
6564 ASCII character codes. If the String A and String B are not the same
6565 length, the shorter is compared as if spaces were appended to it to form
6566 a value that has the same length as the longer.
6568 In general, the lexical comparison intrinsics @code{LGE}, @code{LGT},
6569 @code{LLE}, and @code{LLT} differ from the corresponding intrinsic
6570 operators @code{.GE.}, @code{.GT.}, @code{.LE.}, and @code{.LT.}, in
6571 that the latter use the processor's character ordering (which is not
6572 ASCII on some targets), whereas the former always use the ASCII
6575 @item @emph{Standard}:
6581 @item @emph{Syntax}:
6582 @code{RESULT = LGE(STRING_A, STRING_B)}
6584 @item @emph{Arguments}:
6585 @multitable @columnfractions .15 .70
6586 @item @var{STRING_A} @tab Shall be of default @code{CHARACTER} type.
6587 @item @var{STRING_B} @tab Shall be of default @code{CHARACTER} type.
6590 @item @emph{Return value}:
6591 Returns @code{.TRUE.} if @code{STRING_A >= STRING_B}, and @code{.FALSE.}
6592 otherwise, based on the ASCII ordering.
6594 @item @emph{See also}:
6595 @ref{LGT}, @ref{LLE}, @ref{LLT}
6601 @section @code{LGT} --- Lexical greater than
6603 @cindex lexical comparison of strings
6604 @cindex string, comparison
6607 @item @emph{Description}:
6608 Determines whether one string is lexically greater than another string,
6609 where the two strings are interpreted as containing ASCII character
6610 codes. If the String A and String B are not the same length, the
6611 shorter is compared as if spaces were appended to it to form a value
6612 that has the same length as the longer.
6614 In general, the lexical comparison intrinsics @code{LGE}, @code{LGT},
6615 @code{LLE}, and @code{LLT} differ from the corresponding intrinsic
6616 operators @code{.GE.}, @code{.GT.}, @code{.LE.}, and @code{.LT.}, in
6617 that the latter use the processor's character ordering (which is not
6618 ASCII on some targets), whereas the former always use the ASCII
6621 @item @emph{Standard}:
6627 @item @emph{Syntax}:
6628 @code{RESULT = LGT(STRING_A, STRING_B)}
6630 @item @emph{Arguments}:
6631 @multitable @columnfractions .15 .70
6632 @item @var{STRING_A} @tab Shall be of default @code{CHARACTER} type.
6633 @item @var{STRING_B} @tab Shall be of default @code{CHARACTER} type.
6636 @item @emph{Return value}:
6637 Returns @code{.TRUE.} if @code{STRING_A > STRING_B}, and @code{.FALSE.}
6638 otherwise, based on the ASCII ordering.
6640 @item @emph{See also}:
6641 @ref{LGE}, @ref{LLE}, @ref{LLT}
6647 @section @code{LINK} --- Create a hard link
6649 @cindex file system, create link
6650 @cindex file system, hard link
6653 @item @emph{Description}:
6654 Makes a (hard) link from file @var{PATH1} to @var{PATH2}. A null
6655 character (@code{CHAR(0)}) can be used to mark the end of the names in
6656 @var{PATH1} and @var{PATH2}; otherwise, trailing blanks in the file
6657 names are ignored. If the @var{STATUS} argument is supplied, it
6658 contains 0 on success or a nonzero error code upon return; see
6661 This intrinsic is provided in both subroutine and function forms;
6662 however, only one form can be used in any given program unit.
6664 @item @emph{Standard}:
6668 Subroutine, function
6670 @item @emph{Syntax}:
6671 @multitable @columnfractions .80
6672 @item @code{CALL LINK(PATH1, PATH2 [, STATUS])}
6673 @item @code{STATUS = LINK(PATH1, PATH2)}
6676 @item @emph{Arguments}:
6677 @multitable @columnfractions .15 .70
6678 @item @var{PATH1} @tab Shall be of default @code{CHARACTER} type.
6679 @item @var{PATH2} @tab Shall be of default @code{CHARACTER} type.
6680 @item @var{STATUS} @tab (Optional) Shall be of default @code{INTEGER} type.
6683 @item @emph{See also}:
6684 @ref{SYMLNK}, @ref{UNLINK}
6690 @section @code{LLE} --- Lexical less than or equal
6692 @cindex lexical comparison of strings
6693 @cindex string, comparison
6696 @item @emph{Description}:
6697 Determines whether one string is lexically less than or equal to another
6698 string, where the two strings are interpreted as containing ASCII
6699 character codes. If the String A and String B are not the same length,
6700 the shorter is compared as if spaces were appended to it to form a value
6701 that has the same length as the longer.
6703 In general, the lexical comparison intrinsics @code{LGE}, @code{LGT},
6704 @code{LLE}, and @code{LLT} differ from the corresponding intrinsic
6705 operators @code{.GE.}, @code{.GT.}, @code{.LE.}, and @code{.LT.}, in
6706 that the latter use the processor's character ordering (which is not
6707 ASCII on some targets), whereas the former always use the ASCII
6710 @item @emph{Standard}:
6716 @item @emph{Syntax}:
6717 @code{RESULT = LLE(STRING_A, STRING_B)}
6719 @item @emph{Arguments}:
6720 @multitable @columnfractions .15 .70
6721 @item @var{STRING_A} @tab Shall be of default @code{CHARACTER} type.
6722 @item @var{STRING_B} @tab Shall be of default @code{CHARACTER} type.
6725 @item @emph{Return value}:
6726 Returns @code{.TRUE.} if @code{STRING_A <= STRING_B}, and @code{.FALSE.}
6727 otherwise, based on the ASCII ordering.
6729 @item @emph{See also}:
6730 @ref{LGE}, @ref{LGT}, @ref{LLT}
6736 @section @code{LLT} --- Lexical less than
6738 @cindex lexical comparison of strings
6739 @cindex string, comparison
6742 @item @emph{Description}:
6743 Determines whether one string is lexically less than another string,
6744 where the two strings are interpreted as containing ASCII character
6745 codes. If the String A and String B are not the same length, the
6746 shorter is compared as if spaces were appended to it to form a value
6747 that has the same length as the longer.
6749 In general, the lexical comparison intrinsics @code{LGE}, @code{LGT},
6750 @code{LLE}, and @code{LLT} differ from the corresponding intrinsic
6751 operators @code{.GE.}, @code{.GT.}, @code{.LE.}, and @code{.LT.}, in
6752 that the latter use the processor's character ordering (which is not
6753 ASCII on some targets), whereas the former always use the ASCII
6756 @item @emph{Standard}:
6762 @item @emph{Syntax}:
6763 @code{RESULT = LLT(STRING_A, STRING_B)}
6765 @item @emph{Arguments}:
6766 @multitable @columnfractions .15 .70
6767 @item @var{STRING_A} @tab Shall be of default @code{CHARACTER} type.
6768 @item @var{STRING_B} @tab Shall be of default @code{CHARACTER} type.
6771 @item @emph{Return value}:
6772 Returns @code{.TRUE.} if @code{STRING_A < STRING_B}, and @code{.FALSE.}
6773 otherwise, based on the ASCII ordering.
6775 @item @emph{See also}:
6776 @ref{LGE}, @ref{LGT}, @ref{LLE}
6782 @section @code{LNBLNK} --- Index of the last non-blank character in a string
6784 @cindex string, find non-blank character
6787 @item @emph{Description}:
6788 Returns the length of a character string, ignoring any trailing blanks.
6789 This is identical to the standard @code{LEN_TRIM} intrinsic, and is only
6790 included for backwards compatibility.
6792 @item @emph{Standard}:
6798 @item @emph{Syntax}:
6799 @code{RESULT = LNBLNK(STRING)}
6801 @item @emph{Arguments}:
6802 @multitable @columnfractions .15 .70
6803 @item @var{STRING} @tab Shall be a scalar of type @code{CHARACTER(*)},
6804 with @code{INTENT(IN)}
6807 @item @emph{Return value}:
6808 The return value is of @code{INTEGER(kind=4)} type.
6810 @item @emph{See also}:
6811 @ref{INDEX intrinsic}, @ref{LEN_TRIM}
6817 @section @code{LOC} --- Returns the address of a variable
6819 @cindex location of a variable in memory
6822 @item @emph{Description}:
6823 @code{LOC(X)} returns the address of @var{X} as an integer.
6825 @item @emph{Standard}:
6831 @item @emph{Syntax}:
6832 @code{RESULT = LOC(X)}
6834 @item @emph{Arguments}:
6835 @multitable @columnfractions .15 .70
6836 @item @var{X} @tab Variable of any type.
6839 @item @emph{Return value}:
6840 The return value is of type @code{INTEGER}, with a @code{KIND}
6841 corresponding to the size (in bytes) of a memory address on the target
6844 @item @emph{Example}:
6851 end program test_loc
6858 @section @code{LOG} --- Logarithm function
6865 @cindex exponential function, inverse
6866 @cindex logarithmic function
6869 @item @emph{Description}:
6870 @code{LOG(X)} computes the logarithm of @var{X}.
6872 @item @emph{Standard}:
6878 @item @emph{Syntax}:
6879 @code{RESULT = LOG(X)}
6881 @item @emph{Arguments}:
6882 @multitable @columnfractions .15 .70
6883 @item @var{X} @tab The type shall be @code{REAL(*)} or
6887 @item @emph{Return value}:
6888 The return value is of type @code{REAL(*)} or @code{COMPLEX(*)}.
6889 The kind type parameter is the same as @var{X}.
6891 @item @emph{Example}:
6894 real(8) :: x = 1.0_8
6895 complex :: z = (1.0, 2.0)
6898 end program test_log
6901 @item @emph{Specific names}:
6902 @multitable @columnfractions .20 .20 .20 .25
6903 @item Name @tab Argument @tab Return type @tab Standard
6904 @item @code{ALOG(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab f95, gnu
6905 @item @code{DLOG(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab f95, gnu
6906 @item @code{CLOG(X)} @tab @code{COMPLEX(4) X} @tab @code{COMPLEX(4)} @tab f95, gnu
6907 @item @code{ZLOG(X)} @tab @code{COMPLEX(8) X} @tab @code{COMPLEX(8)} @tab f95, gnu
6908 @item @code{CDLOG(X)} @tab @code{COMPLEX(8) X} @tab @code{COMPLEX(8)} @tab f95, gnu
6915 @section @code{LOG10} --- Base 10 logarithm function
6919 @cindex exponential function, inverse
6920 @cindex logarithmic function
6923 @item @emph{Description}:
6924 @code{LOG10(X)} computes the base 10 logarithm of @var{X}.
6926 @item @emph{Standard}:
6932 @item @emph{Syntax}:
6933 @code{RESULT = LOG10(X)}
6935 @item @emph{Arguments}:
6936 @multitable @columnfractions .15 .70
6937 @item @var{X} @tab The type shall be @code{REAL(*)}.
6940 @item @emph{Return value}:
6941 The return value is of type @code{REAL(*)} or @code{COMPLEX(*)}.
6942 The kind type parameter is the same as @var{X}.
6944 @item @emph{Example}:
6947 real(8) :: x = 10.0_8
6949 end program test_log10
6952 @item @emph{Specific names}:
6953 @multitable @columnfractions .20 .20 .20 .25
6954 @item Name @tab Argument @tab Return type @tab Standard
6955 @item @code{ALOG10(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab F95 and later
6956 @item @code{DLOG10(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab F95 and later
6963 @section @code{LOGICAL} --- Convert to logical type
6965 @cindex conversion, to logical
6968 @item @emph{Description}:
6969 Converts one kind of @code{LOGICAL} variable to another.
6971 @item @emph{Standard}:
6977 @item @emph{Syntax}:
6978 @code{RESULT = LOGICAL(L [, KIND])}
6980 @item @emph{Arguments}:
6981 @multitable @columnfractions .15 .70
6982 @item @var{L} @tab The type shall be @code{LOGICAL(*)}.
6983 @item @var{KIND} @tab (Optional) An @code{INTEGER(*)} initialization
6984 expression indicating the kind parameter of
6988 @item @emph{Return value}:
6989 The return value is a @code{LOGICAL} value equal to @var{L}, with a
6990 kind corresponding to @var{KIND}, or of the default logical kind if
6991 @var{KIND} is not given.
6993 @item @emph{See also}:
6994 @ref{INT}, @ref{REAL}, @ref{CMPLX}
7000 @section @code{LONG} --- Convert to integer type
7002 @cindex conversion, to integer
7005 @item @emph{Description}:
7006 Convert to a @code{KIND=4} integer type, which is the same size as a C
7007 @code{long} integer. This is equivalent to the standard @code{INT}
7008 intrinsic with an optional argument of @code{KIND=4}, and is only
7009 included for backwards compatibility.
7011 @item @emph{Standard}:
7017 @item @emph{Syntax}:
7018 @code{RESULT = LONG(A)}
7020 @item @emph{Arguments}:
7021 @multitable @columnfractions .15 .70
7022 @item @var{A} @tab Shall be of type @code{INTEGER(*)},
7023 @code{REAL(*)}, or @code{COMPLEX(*)}.
7026 @item @emph{Return value}:
7027 The return value is a @code{INTEGER(4)} variable.
7029 @item @emph{See also}:
7030 @ref{INT}, @ref{INT2}, @ref{INT8}
7036 @section @code{LSHIFT} --- Left shift bits
7038 @cindex bits, shift left
7041 @item @emph{Description}:
7042 @code{LSHIFT} returns a value corresponding to @var{I} with all of the
7043 bits shifted left by @var{SHIFT} places. If the absolute value of
7044 @var{SHIFT} is greater than @code{BIT_SIZE(I)}, the value is undefined.
7045 Bits shifted out from the left end are lost; zeros are shifted in from
7048 This function has been superseded by the @code{ISHFT} intrinsic, which
7049 is standard in Fortran 95 and later.
7051 @item @emph{Standard}:
7057 @item @emph{Syntax}:
7058 @code{RESULT = LSHIFT(I, SHIFT)}
7060 @item @emph{Arguments}:
7061 @multitable @columnfractions .15 .70
7062 @item @var{I} @tab The type shall be @code{INTEGER(*)}.
7063 @item @var{SHIFT} @tab The type shall be @code{INTEGER(*)}.
7066 @item @emph{Return value}:
7067 The return value is of type @code{INTEGER(*)} and of the same kind as
7070 @item @emph{See also}:
7071 @ref{ISHFT}, @ref{ISHFTC}, @ref{RSHIFT}
7078 @section @code{LSTAT} --- Get file status
7080 @cindex file system, file status
7083 @item @emph{Description}:
7084 @code{LSTAT} is identical to @ref{STAT}, except that if path is a symbolic link,
7085 then the link itself is statted, not the file that it refers to.
7087 The elements in @code{BUFF} are the same as described by @ref{STAT}.
7089 This intrinsic is provided in both subroutine and function forms; however,
7090 only one form can be used in any given program unit.
7092 @item @emph{Standard}:
7096 Subroutine, function
7098 @item @emph{Syntax}:
7099 @code{CALL LSTAT(FILE, BUFF [, STATUS])}
7101 @item @emph{Arguments}:
7102 @multitable @columnfractions .15 .70
7103 @item @var{FILE} @tab The type shall be @code{CHARACTER(*)}, a valid path within the file system.
7104 @item @var{BUFF} @tab The type shall be @code{INTEGER(4), DIMENSION(13)}.
7105 @item @var{STATUS} @tab (Optional) status flag of type @code{INTEGER(4)}. Returns 0
7106 on success and a system specific error code otherwise.
7109 @item @emph{Example}:
7110 See @ref{STAT} for an example.
7112 @item @emph{See also}:
7113 To stat an open file: @ref{FSTAT}, to stat a file: @ref{STAT}
7119 @section @code{LTIME} --- Convert time to local time info
7121 @cindex time, conversion to local time info
7124 @item @emph{Description}:
7125 Given a system time value @var{STIME} (as provided by the @code{TIME8()}
7126 intrinsic), fills @var{TARRAY} with values extracted from it appropriate
7127 to the local time zone using @code{localtime(3)}.
7129 @item @emph{Standard}:
7135 @item @emph{Syntax}:
7136 @code{CALL LTIME(STIME, TARRAY)}
7138 @item @emph{Arguments}:
7139 @multitable @columnfractions .15 .70
7140 @item @var{STIME} @tab An @code{INTEGER(*)} scalar expression
7141 corresponding to a system time, with
7143 @item @var{TARRAY} @tab A default @code{INTEGER} array with 9 elements,
7144 with @code{INTENT(OUT)}.
7147 @item @emph{Return value}:
7148 The elements of @var{TARRAY} are assigned as follows:
7150 @item Seconds after the minute, range 0--59 or 0--61 to allow for leap
7152 @item Minutes after the hour, range 0--59
7153 @item Hours past midnight, range 0--23
7154 @item Day of month, range 0--31
7155 @item Number of months since January, range 0--12
7156 @item Years since 1900
7157 @item Number of days since Sunday, range 0--6
7158 @item Days since January 1
7159 @item Daylight savings indicator: positive if daylight savings is in
7160 effect, zero if not, and negative if the information is not
7164 @item @emph{See also}:
7165 @ref{CTIME}, @ref{GMTIME}, @ref{TIME}, @ref{TIME8}
7172 @section @code{MALLOC} --- Allocate dynamic memory
7174 @cindex pointer, cray
7177 @item @emph{Description}:
7178 @code{MALLOC(SIZE)} allocates @var{SIZE} bytes of dynamic memory and
7179 returns the address of the allocated memory. The @code{MALLOC} intrinsic
7180 is an extension intended to be used with Cray pointers, and is provided
7181 in GNU Fortran to allow the user to compile legacy code. For new code
7182 using Fortran 95 pointers, the memory allocation intrinsic is
7185 @item @emph{Standard}:
7191 @item @emph{Syntax}:
7192 @code{PTR = MALLOC(SIZE)}
7194 @item @emph{Arguments}:
7195 @multitable @columnfractions .15 .70
7196 @item @var{SIZE} @tab The type shall be @code{INTEGER(*)}.
7199 @item @emph{Return value}:
7200 The return value is of type @code{INTEGER(K)}, with @var{K} such that
7201 variables of type @code{INTEGER(K)} have the same size as
7202 C pointers (@code{sizeof(void *)}).
7204 @item @emph{Example}:
7205 The following example demonstrates the use of @code{MALLOC} and
7206 @code{FREE} with Cray pointers. This example is intended to run on
7207 32-bit systems, where the default integer kind is suitable to store
7208 pointers; on 64-bit systems, ptr_x would need to be declared as
7209 @code{integer(kind=8)}.
7218 ptr_x = malloc(20*8)
7220 x(i) = sqrt(1.0d0 / i)
7228 end program test_malloc
7231 @item @emph{See also}:
7238 @section @code{MATMUL} --- matrix multiplication
7240 @cindex matrix multiplication
7241 @cindex product, matrix
7244 @item @emph{Description}:
7245 Performs a matrix multiplication on numeric or logical arguments.
7247 @item @emph{Standard}:
7251 Transformational function
7253 @item @emph{Syntax}:
7254 @code{RESULT = MATMUL(MATRIX_A, MATRIX_B)}
7256 @item @emph{Arguments}:
7257 @multitable @columnfractions .15 .70
7258 @item @var{MATRIX_A} @tab An array of @code{INTEGER(*)},
7259 @code{REAL(*)}, @code{COMPLEX(*)}, or
7260 @code{LOGICAL(*)} type, with a rank of
7262 @item @var{MATRIX_B} @tab An array of @code{INTEGER(*)},
7263 @code{REAL(*)}, or @code{COMPLEX(*)} type if
7264 @var{MATRIX_A} is of a numeric type;
7265 otherwise, an array of @code{LOGICAL(*)}
7266 type. The rank shall be one or two, and the
7267 first (or only) dimension of @var{MATRIX_B}
7268 shall be equal to the last (or only)
7269 dimension of @var{MATRIX_A}.
7272 @item @emph{Return value}:
7273 The matrix product of @var{MATRIX_A} and @var{MATRIX_B}. The type and
7274 kind of the result follow the usual type and kind promotion rules, as
7275 for the @code{*} or @code{.AND.} operators.
7277 @item @emph{See also}:
7283 @section @code{MAX} --- Maximum value of an argument list
7290 @cindex maximum value
7293 @item @emph{Description}:
7294 Returns the argument with the largest (most positive) value.
7296 @item @emph{Standard}:
7302 @item @emph{Syntax}:
7303 @code{RESULT = MAX(A1, A2 [, A3 [, ...]])}
7305 @item @emph{Arguments}:
7306 @multitable @columnfractions .15 .70
7307 @item @var{A1} @tab The type shall be @code{INTEGER(*)} or
7309 @item @var{A2}, @var{A3}, ... @tab An expression of the same type and kind
7310 as @var{A1}. (As a GNU extension,
7311 arguments of different kinds are
7315 @item @emph{Return value}:
7316 The return value corresponds to the maximum value among the arguments,
7317 and has the same type and kind as the first argument.
7319 @item @emph{Specific names}:
7320 @multitable @columnfractions .20 .20 .20 .25
7321 @item Name @tab Argument @tab Return type @tab Standard
7322 @item @code{MAX0(I)} @tab @code{INTEGER(4) I} @tab @code{INTEGER(4)} @tab F77 and later
7323 @item @code{AMAX0(I)} @tab @code{INTEGER(4) I} @tab @code{REAL(MAX(X))} @tab F77 and later
7324 @item @code{MAX1(X)} @tab @code{REAL(*) X} @tab @code{INT(MAX(X))} @tab F77 and later
7325 @item @code{AMAX1(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab F77 and later
7326 @item @code{DMAX1(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab F77 and later
7329 @item @emph{See also}:
7330 @ref{MAXLOC} @ref{MAXVAL}, @ref{MIN}
7337 @section @code{MAXEXPONENT} --- Maximum exponent of a real kind
7338 @fnindex MAXEXPONENT
7339 @cindex model representation, maximum exponent
7342 @item @emph{Description}:
7343 @code{MAXEXPONENT(X)} returns the maximum exponent in the model of the
7346 @item @emph{Standard}:
7352 @item @emph{Syntax}:
7353 @code{RESULT = MAXEXPONENT(X)}
7355 @item @emph{Arguments}:
7356 @multitable @columnfractions .15 .70
7357 @item @var{X} @tab Shall be of type @code{REAL}.
7360 @item @emph{Return value}:
7361 The return value is of type @code{INTEGER} and of the default integer
7364 @item @emph{Example}:
7370 print *, minexponent(x), maxexponent(x)
7371 print *, minexponent(y), maxexponent(y)
7372 end program exponents
7379 @section @code{MAXLOC} --- Location of the maximum value within an array
7381 @cindex array, location of maximum element
7384 @item @emph{Description}:
7385 Determines the location of the element in the array with the maximum
7386 value, or, if the @var{DIM} argument is supplied, determines the
7387 locations of the maximum element along each row of the array in the
7388 @var{DIM} direction. If @var{MASK} is present, only the elements for
7389 which @var{MASK} is @code{.TRUE.} are considered. If more than one
7390 element in the array has the maximum value, the location returned is
7391 that of the first such element in array element order. If the array has
7392 zero size, or all of the elements of @var{MASK} are @code{.FALSE.}, then
7393 the result is an array of zeroes. Similarly, if @var{DIM} is supplied
7394 and all of the elements of @var{MASK} along a given row are zero, the
7395 result value for that row is zero.
7397 @item @emph{Standard}:
7401 Transformational function
7403 @item @emph{Syntax}:
7404 @multitable @columnfractions .80
7405 @item @code{RESULT = MAXLOC(ARRAY, DIM [, MASK])}
7406 @item @code{RESULT = MAXLOC(ARRAY [, MASK])}
7409 @item @emph{Arguments}:
7410 @multitable @columnfractions .15 .70
7411 @item @var{ARRAY} @tab Shall be an array of type @code{INTEGER(*)},
7412 @code{REAL(*)}, or @code{CHARACTER(*)}.
7413 @item @var{DIM} @tab (Optional) Shall be a scalar of type
7414 @code{INTEGER(*)}, with a value between one
7415 and the rank of @var{ARRAY}, inclusive. It
7416 may not be an optional dummy argument.
7417 @item @var{MASK} @tab Shall be an array of type @code{LOGICAL(*)},
7418 and conformable with @var{ARRAY}.
7421 @item @emph{Return value}:
7422 If @var{DIM} is absent, the result is a rank-one array with a length
7423 equal to the rank of @var{ARRAY}. If @var{DIM} is present, the result
7424 is an array with a rank one less than the rank of @var{ARRAY}, and a
7425 size corresponding to the size of @var{ARRAY} with the @var{DIM}
7426 dimension removed. If @var{DIM} is present and @var{ARRAY} has a rank
7427 of one, the result is a scalar. In all cases, the result is of default
7428 @code{INTEGER} type.
7430 @item @emph{See also}:
7431 @ref{MAX}, @ref{MAXVAL}
7438 @section @code{MAXVAL} --- Maximum value of an array
7440 @cindex array, maximum value
7441 @cindex maximum value
7444 @item @emph{Description}:
7445 Determines the maximum value of the elements in an array value, or, if
7446 the @var{DIM} argument is supplied, determines the maximum value along
7447 each row of the array in the @var{DIM} direction. If @var{MASK} is
7448 present, only the elements for which @var{MASK} is @code{.TRUE.} are
7449 considered. If the array has zero size, or all of the elements of
7450 @var{MASK} are @code{.FALSE.}, then the result is the most negative
7451 number of the type and kind of @var{ARRAY} if @var{ARRAY} is numeric, or
7452 a string of nulls if @var{ARRAY} is of character type.
7454 @item @emph{Standard}:
7458 Transformational function
7460 @item @emph{Syntax}:
7461 @multitable @columnfractions .80
7462 @item @code{RESULT = MAXVAL(ARRAY, DIM [, MASK])}
7463 @item @code{RESULT = MAXVAL(ARRAY [, MASK])}
7466 @item @emph{Arguments}:
7467 @multitable @columnfractions .15 .70
7468 @item @var{ARRAY} @tab Shall be an array of type @code{INTEGER(*)},
7469 @code{REAL(*)}, or @code{CHARACTER(*)}.
7470 @item @var{DIM} @tab (Optional) Shall be a scalar of type
7471 @code{INTEGER(*)}, with a value between one
7472 and the rank of @var{ARRAY}, inclusive. It
7473 may not be an optional dummy argument.
7474 @item @var{MASK} @tab Shall be an array of type @code{LOGICAL(*)},
7475 and conformable with @var{ARRAY}.
7478 @item @emph{Return value}:
7479 If @var{DIM} is absent, or if @var{ARRAY} has a rank of one, the result
7480 is a scalar. If @var{DIM} is present, the result is an array with a
7481 rank one less than the rank of @var{ARRAY}, and a size corresponding to
7482 the size of @var{ARRAY} with the @var{DIM} dimension removed. In all
7483 cases, the result is of the same type and kind as @var{ARRAY}.
7485 @item @emph{See also}:
7486 @ref{MAX}, @ref{MAXLOC}
7492 @section @code{MCLOCK} --- Time function
7494 @cindex time, clock ticks
7498 @item @emph{Description}:
7499 Returns the number of clock ticks since the start of the process, based
7500 on the UNIX function @code{clock(3)}.
7502 This intrinsic is not fully portable, such as to systems with 32-bit
7503 @code{INTEGER} types but supporting times wider than 32 bits. Therefore,
7504 the values returned by this intrinsic might be, or become, negative, or
7505 numerically less than previous values, during a single run of the
7508 @item @emph{Standard}:
7514 @item @emph{Syntax}:
7515 @code{RESULT = MCLOCK()}
7517 @item @emph{Return value}:
7518 The return value is a scalar of type @code{INTEGER(4)}, equal to the
7519 number of clock ticks since the start of the process, or @code{-1} if
7520 the system does not support @code{clock(3)}.
7522 @item @emph{See also}:
7523 @ref{CTIME}, @ref{GMTIME}, @ref{LTIME}, @ref{MCLOCK}, @ref{TIME}
7530 @section @code{MCLOCK8} --- Time function (64-bit)
7532 @cindex time, clock ticks
7536 @item @emph{Description}:
7537 Returns the number of clock ticks since the start of the process, based
7538 on the UNIX function @code{clock(3)}.
7540 @emph{Warning:} this intrinsic does not increase the range of the timing
7541 values over that returned by @code{clock(3)}. On a system with a 32-bit
7542 @code{clock(3)}, @code{MCLOCK8()} will return a 32-bit value, even though
7543 it is converted to a 64-bit @code{INTEGER(8)} value. That means
7544 overflows of the 32-bit value can still occur. Therefore, the values
7545 returned by this intrinsic might be or become negative or numerically
7546 less than previous values during a single run of the compiled program.
7548 @item @emph{Standard}:
7554 @item @emph{Syntax}:
7555 @code{RESULT = MCLOCK8()}
7557 @item @emph{Return value}:
7558 The return value is a scalar of type @code{INTEGER(8)}, equal to the
7559 number of clock ticks since the start of the process, or @code{-1} if
7560 the system does not support @code{clock(3)}.
7562 @item @emph{See also}:
7563 @ref{CTIME}, @ref{GMTIME}, @ref{LTIME}, @ref{MCLOCK}, @ref{TIME8}
7570 @section @code{MERGE} --- Merge variables
7572 @cindex array, merge arrays
7573 @cindex array, combine arrays
7576 @item @emph{Description}:
7577 Select values from two arrays according to a logical mask. The result
7578 is equal to @var{TSOURCE} if @var{MASK} is @code{.TRUE.}, or equal to
7579 @var{FSOURCE} if it is @code{.FALSE.}.
7581 @item @emph{Standard}:
7587 @item @emph{Syntax}:
7588 @code{RESULT = MERGE(TSOURCE, FSOURCE, MASK)}
7590 @item @emph{Arguments}:
7591 @multitable @columnfractions .15 .70
7592 @item @var{TSOURCE} @tab May be of any type.
7593 @item @var{FSOURCE} @tab Shall be of the same type and type parameters
7595 @item @var{MASK} @tab Shall be of type @code{LOGICAL(*)}.
7598 @item @emph{Return value}:
7599 The result is of the same type and type parameters as @var{TSOURCE}.
7606 @section @code{MIN} --- Minimum value of an argument list
7613 @cindex minimum value
7616 @item @emph{Description}:
7617 Returns the argument with the smallest (most negative) value.
7619 @item @emph{Standard}:
7625 @item @emph{Syntax}:
7626 @code{RESULT = MIN(A1, A2 [, A3, ...])}
7628 @item @emph{Arguments}:
7629 @multitable @columnfractions .15 .70
7630 @item @var{A1} @tab The type shall be @code{INTEGER(*)} or
7632 @item @var{A2}, @var{A3}, ... @tab An expression of the same type and kind
7633 as @var{A1}. (As a GNU extension,
7634 arguments of different kinds are
7638 @item @emph{Return value}:
7639 The return value corresponds to the maximum value among the arguments,
7640 and has the same type and kind as the first argument.
7642 @item @emph{Specific names}:
7643 @multitable @columnfractions .20 .20 .20 .25
7644 @item Name @tab Argument @tab Return type @tab Standard
7645 @item @code{MIN0(I)} @tab @code{INTEGER(4) I} @tab @code{INTEGER(4)} @tab F77 and later
7646 @item @code{AMIN0(I)} @tab @code{INTEGER(4) I} @tab @code{REAL(MIN(X))} @tab F77 and later
7647 @item @code{MIN1(X)} @tab @code{REAL(*) X} @tab @code{INT(MIN(X))} @tab F77 and later
7648 @item @code{AMIN1(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab F77 and later
7649 @item @code{DMIN1(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab F77 and later
7652 @item @emph{See also}:
7653 @ref{MAX}, @ref{MINLOC}, @ref{MINVAL}
7659 @section @code{MINEXPONENT} --- Minimum exponent of a real kind
7660 @fnindex MINEXPONENT
7661 @cindex model representation, minimum exponent
7664 @item @emph{Description}:
7665 @code{MINEXPONENT(X)} returns the minimum exponent in the model of the
7668 @item @emph{Standard}:
7674 @item @emph{Syntax}:
7675 @code{RESULT = MINEXPONENT(X)}
7677 @item @emph{Arguments}:
7678 @multitable @columnfractions .15 .70
7679 @item @var{X} @tab Shall be of type @code{REAL}.
7682 @item @emph{Return value}:
7683 The return value is of type @code{INTEGER} and of the default integer
7686 @item @emph{Example}:
7687 See @code{MAXEXPONENT} for an example.
7693 @section @code{MINLOC} --- Location of the minimum value within an array
7695 @cindex array, location of minimum element
7698 @item @emph{Description}:
7699 Determines the location of the element in the array with the minimum
7700 value, or, if the @var{DIM} argument is supplied, determines the
7701 locations of the minimum element along each row of the array in the
7702 @var{DIM} direction. If @var{MASK} is present, only the elements for
7703 which @var{MASK} is @code{.TRUE.} are considered. If more than one
7704 element in the array has the minimum value, the location returned is
7705 that of the first such element in array element order. If the array has
7706 zero size, or all of the elements of @var{MASK} are @code{.FALSE.}, then
7707 the result is an array of zeroes. Similarly, if @var{DIM} is supplied
7708 and all of the elements of @var{MASK} along a given row are zero, the
7709 result value for that row is zero.
7711 @item @emph{Standard}:
7715 Transformational function
7717 @item @emph{Syntax}:
7718 @multitable @columnfractions .80
7719 @item @code{RESULT = MINLOC(ARRAY, DIM [, MASK])}
7720 @item @code{RESULT = MINLOC(ARRAY [, MASK])}
7723 @item @emph{Arguments}:
7724 @multitable @columnfractions .15 .70
7725 @item @var{ARRAY} @tab Shall be an array of type @code{INTEGER(*)},
7726 @code{REAL(*)}, or @code{CHARACTER(*)}.
7727 @item @var{DIM} @tab (Optional) Shall be a scalar of type
7728 @code{INTEGER(*)}, with a value between one
7729 and the rank of @var{ARRAY}, inclusive. It
7730 may not be an optional dummy argument.
7731 @item @var{MASK} @tab Shall be an array of type @code{LOGICAL(*)},
7732 and conformable with @var{ARRAY}.
7735 @item @emph{Return value}:
7736 If @var{DIM} is absent, the result is a rank-one array with a length
7737 equal to the rank of @var{ARRAY}. If @var{DIM} is present, the result
7738 is an array with a rank one less than the rank of @var{ARRAY}, and a
7739 size corresponding to the size of @var{ARRAY} with the @var{DIM}
7740 dimension removed. If @var{DIM} is present and @var{ARRAY} has a rank
7741 of one, the result is a scalar. In all cases, the result is of default
7742 @code{INTEGER} type.
7744 @item @emph{See also}:
7745 @ref{MIN}, @ref{MINVAL}
7752 @section @code{MINVAL} --- Minimum value of an array
7754 @cindex array, minimum value
7755 @cindex minimum value
7758 @item @emph{Description}:
7759 Determines the minimum value of the elements in an array value, or, if
7760 the @var{DIM} argument is supplied, determines the minimum value along
7761 each row of the array in the @var{DIM} direction. If @var{MASK} is
7762 present, only the elements for which @var{MASK} is @code{.TRUE.} are
7763 considered. If the array has zero size, or all of the elements of
7764 @var{MASK} are @code{.FALSE.}, then the result is @code{HUGE(ARRAY)} if
7765 @var{ARRAY} is numeric, or a string of @code{CHAR(255)} characters if
7766 @var{ARRAY} is of character type.
7768 @item @emph{Standard}:
7772 Transformational function
7774 @item @emph{Syntax}:
7775 @multitable @columnfractions .80
7776 @item @code{RESULT = MINVAL(ARRAY, DIM [, MASK])}
7777 @item @code{RESULT = MINVAL(ARRAY [, MASK])}
7780 @item @emph{Arguments}:
7781 @multitable @columnfractions .15 .70
7782 @item @var{ARRAY} @tab Shall be an array of type @code{INTEGER(*)},
7783 @code{REAL(*)}, or @code{CHARACTER(*)}.
7784 @item @var{DIM} @tab (Optional) Shall be a scalar of type
7785 @code{INTEGER(*)}, with a value between one
7786 and the rank of @var{ARRAY}, inclusive. It
7787 may not be an optional dummy argument.
7788 @item @var{MASK} @tab Shall be an array of type @code{LOGICAL(*)},
7789 and conformable with @var{ARRAY}.
7792 @item @emph{Return value}:
7793 If @var{DIM} is absent, or if @var{ARRAY} has a rank of one, the result
7794 is a scalar. If @var{DIM} is present, the result is an array with a
7795 rank one less than the rank of @var{ARRAY}, and a size corresponding to
7796 the size of @var{ARRAY} with the @var{DIM} dimension removed. In all
7797 cases, the result is of the same type and kind as @var{ARRAY}.
7799 @item @emph{See also}:
7800 @ref{MIN}, @ref{MINLOC}
7807 @section @code{MOD} --- Remainder function
7812 @cindex division, remainder
7815 @item @emph{Description}:
7816 @code{MOD(A,P)} computes the remainder of the division of A by P@. It is
7817 calculated as @code{A - (INT(A/P) * P)}.
7819 @item @emph{Standard}:
7825 @item @emph{Syntax}:
7826 @code{RESULT = MOD(A, P)}
7828 @item @emph{Arguments}:
7829 @multitable @columnfractions .15 .70
7830 @item @var{A} @tab Shall be a scalar of type @code{INTEGER} or @code{REAL}
7831 @item @var{P} @tab Shall be a scalar of the same type as @var{A} and not
7835 @item @emph{Return value}:
7836 The kind of the return value is the result of cross-promoting
7837 the kinds of the arguments.
7839 @item @emph{Example}:
7843 print *, mod(17.5,5.5)
7844 print *, mod(17.5d0,5.5)
7845 print *, mod(17.5,5.5d0)
7848 print *, mod(-17.5,5.5)
7849 print *, mod(-17.5d0,5.5)
7850 print *, mod(-17.5,5.5d0)
7853 print *, mod(17.5,-5.5)
7854 print *, mod(17.5d0,-5.5)
7855 print *, mod(17.5,-5.5d0)
7856 end program test_mod
7859 @item @emph{Specific names}:
7860 @multitable @columnfractions .20 .20 .20 .25
7861 @item Name @tab Arguments @tab Return type @tab Standard
7862 @item @code{AMOD(A,P)} @tab @code{REAL(4)} @tab @code{REAL(4)} @tab F95 and later
7863 @item @code{DMOD(A,P)} @tab @code{REAL(8)} @tab @code{REAL(8)} @tab F95 and later
7870 @section @code{MODULO} --- Modulo function
7873 @cindex division, modulo
7876 @item @emph{Description}:
7877 @code{MODULO(A,P)} computes the @var{A} modulo @var{P}.
7879 @item @emph{Standard}:
7885 @item @emph{Syntax}:
7886 @code{RESULT = MODULO(A, P)}
7888 @item @emph{Arguments}:
7889 @multitable @columnfractions .15 .70
7890 @item @var{A} @tab Shall be a scalar of type @code{INTEGER} or @code{REAL}
7891 @item @var{P} @tab Shall be a scalar of the same type and kind as @var{A}
7894 @item @emph{Return value}:
7895 The type and kind of the result are those of the arguments.
7897 @item If @var{A} and @var{P} are of type @code{INTEGER}:
7898 @code{MODULO(A,P)} has the value @var{R} such that @code{A=Q*P+R}, where
7899 @var{Q} is an integer and @var{R} is between 0 (inclusive) and @var{P}
7901 @item If @var{A} and @var{P} are of type @code{REAL}:
7902 @code{MODULO(A,P)} has the value of @code{A - FLOOR (A / P) * P}.
7904 In all cases, if @var{P} is zero the result is processor-dependent.
7906 @item @emph{Example}:
7909 print *, modulo(17,3)
7910 print *, modulo(17.5,5.5)
7912 print *, modulo(-17,3)
7913 print *, modulo(-17.5,5.5)
7915 print *, modulo(17,-3)
7916 print *, modulo(17.5,-5.5)
7925 @section @code{MOVE_ALLOC} --- Move allocation from one object to another
7927 @cindex moving allocation
7928 @cindex allocation, moving
7931 @item @emph{Description}:
7932 @code{MOVE_ALLOC(SRC, DEST)} moves the allocation from @var{SRC} to
7933 @var{DEST}. @var{SRC} will become deallocated in the process.
7935 @item @emph{Standard}:
7936 Fortran 2003 and later
7941 @item @emph{Syntax}:
7942 @code{CALL MOVE_ALLOC(SRC, DEST)}
7944 @item @emph{Arguments}:
7945 @multitable @columnfractions .15 .70
7946 @item @var{SRC} @tab @code{ALLOCATABLE}, @code{INTENT(INOUT)}, may be
7947 of any type and kind.
7948 @item @var{DEST} @tab @code{ALLOCATABLE}, @code{INTENT(OUT)}, shall be
7949 of the same type, kind and rank as @var{SRC}
7952 @item @emph{Return value}:
7955 @item @emph{Example}:
7957 program test_move_alloc
7958 integer, allocatable :: a(:), b(:)
7962 call move_alloc(a, b)
7963 print *, allocated(a), allocated(b)
7965 end program test_move_alloc
7972 @section @code{MVBITS} --- Move bits from one integer to another
7977 @item @emph{Description}:
7978 Moves @var{LEN} bits from positions @var{FROMPOS} through
7979 @code{FROMPOS+LEN-1} of @var{FROM} to positions @var{TOPOS} through
7980 @code{TOPOS+LEN-1} of @var{TO}. The portion of argument @var{TO} not
7981 affected by the movement of bits is unchanged. The values of
7982 @code{FROMPOS+LEN-1} and @code{TOPOS+LEN-1} must be less than
7983 @code{BIT_SIZE(FROM)}.
7985 @item @emph{Standard}:
7989 Elemental subroutine
7991 @item @emph{Syntax}:
7992 @code{CALL MVBITS(FROM, FROMPOS, LEN, TO, TOPOS)}
7994 @item @emph{Arguments}:
7995 @multitable @columnfractions .15 .70
7996 @item @var{FROM} @tab The type shall be @code{INTEGER(*)}.
7997 @item @var{FROMPOS} @tab The type shall be @code{INTEGER(*)}.
7998 @item @var{LEN} @tab The type shall be @code{INTEGER(*)}.
7999 @item @var{TO} @tab The type shall be @code{INTEGER(*)}, of the
8000 same kind as @var{FROM}.
8001 @item @var{TOPOS} @tab The type shall be @code{INTEGER(*)}.
8004 @item @emph{See also}:
8005 @ref{IBCLR}, @ref{IBSET}, @ref{IBITS}, @ref{IAND}, @ref{IOR}, @ref{IEOR}
8011 @section @code{NEAREST} --- Nearest representable number
8013 @cindex real number, nearest different
8014 @cindex floating point, nearest different
8017 @item @emph{Description}:
8018 @code{NEAREST(X, S)} returns the processor-representable number nearest
8019 to @code{X} in the direction indicated by the sign of @code{S}.
8021 @item @emph{Standard}:
8027 @item @emph{Syntax}:
8028 @code{RESULT = NEAREST(X, S)}
8030 @item @emph{Arguments}:
8031 @multitable @columnfractions .15 .70
8032 @item @var{X} @tab Shall be of type @code{REAL}.
8033 @item @var{S} @tab (Optional) shall be of type @code{REAL} and
8037 @item @emph{Return value}:
8038 The return value is of the same type as @code{X}. If @code{S} is
8039 positive, @code{NEAREST} returns the processor-representable number
8040 greater than @code{X} and nearest to it. If @code{S} is negative,
8041 @code{NEAREST} returns the processor-representable number smaller than
8042 @code{X} and nearest to it.
8044 @item @emph{Example}:
8046 program test_nearest
8048 x = nearest(42.0, 1.0)
8049 y = nearest(42.0, -1.0)
8050 write (*,"(3(G20.15))") x, y, x - y
8051 end program test_nearest
8058 @section @code{NEW_LINE} --- New line character
8061 @cindex output, newline
8064 @item @emph{Description}:
8065 @code{NEW_LINE(C)} returns the new-line character.
8067 @item @emph{Standard}:
8068 Fortran 2003 and later
8073 @item @emph{Syntax}:
8074 @code{RESULT = NEW_LINE(C)}
8076 @item @emph{Arguments}:
8077 @multitable @columnfractions .15 .70
8078 @item @var{C} @tab The argument shall be a scalar or array of the
8079 type @code{CHARACTER}.
8082 @item @emph{Return value}:
8083 Returns a @var{CHARACTER} scalar of length one with the new-line character of
8084 the same kind as parameter @var{C}.
8086 @item @emph{Example}:
8090 write(*,'(A)') 'This is record 1.'//NEW_LINE('A')//'This is record 2.'
8098 @section @code{NINT} --- Nearest whole number
8101 @cindex rounding, nearest whole number
8104 @item @emph{Description}:
8105 @code{NINT(X)} rounds its argument to the nearest whole number.
8107 @item @emph{Standard}:
8113 @item @emph{Syntax}:
8114 @code{RESULT = NINT(X)}
8116 @item @emph{Arguments}:
8117 @multitable @columnfractions .15 .70
8118 @item @var{X} @tab The type of the argument shall be @code{REAL}.
8121 @item @emph{Return value}:
8122 Returns @var{A} with the fractional portion of its magnitude eliminated by
8123 rounding to the nearest whole number and with its sign preserved,
8124 converted to an @code{INTEGER} of the default kind.
8126 @item @emph{Example}:
8133 print *, nint(x4), idnint(x8)
8134 end program test_nint
8137 @item @emph{Specific names}:
8138 @multitable @columnfractions .25 .25 .25
8139 @item Name @tab Argument @tab Standard
8140 @item @code{IDNINT(X)} @tab @code{REAL(8)} @tab F95 and later
8143 @item @emph{See also}:
8144 @ref{CEILING}, @ref{FLOOR}
8151 @section @code{NOT} --- Logical negation
8153 @cindex bits, negate
8154 @cindex bitwise logical not
8155 @cindex logical not, bitwise
8158 @item @emph{Description}:
8159 @code{NOT} returns the bitwise boolean inverse of @var{I}.
8161 @item @emph{Standard}:
8167 @item @emph{Syntax}:
8168 @code{RESULT = NOT(I)}
8170 @item @emph{Arguments}:
8171 @multitable @columnfractions .15 .70
8172 @item @var{I} @tab The type shall be @code{INTEGER(*)}.
8175 @item @emph{Return value}:
8176 The return type is @code{INTEGER(*)}, of the same kind as the
8179 @item @emph{See also}:
8180 @ref{IAND}, @ref{IEOR}, @ref{IOR}, @ref{IBITS}, @ref{IBSET}, @ref{IBCLR}
8187 @section @code{NULL} --- Function that returns an disassociated pointer
8189 @cindex pointer, status
8190 @cindex pointer, disassociated
8193 @item @emph{Description}:
8194 Returns a disassociated pointer.
8196 If @var{MOLD} is present, a dissassociated pointer of the same type is
8197 returned, otherwise the type is determined by context.
8199 In Fortran 95, @var{MOLD} is optional. Please note that Fortran 2003
8200 includes cases where it is required.
8202 @item @emph{Standard}:
8206 Transformational function
8208 @item @emph{Syntax}:
8209 @code{PTR => NULL([MOLD])}
8211 @item @emph{Arguments}:
8212 @multitable @columnfractions .15 .70
8213 @item @var{MOLD} @tab (Optional) shall be a pointer of any association
8214 status and of any type.
8217 @item @emph{Return value}:
8218 A disassociated pointer.
8220 @item @emph{Example}:
8222 REAL, POINTER, DIMENSION(:) :: VEC => NULL ()
8225 @item @emph{See also}:
8232 @section @code{OR} --- Bitwise logical OR
8234 @cindex bitwise logical or
8235 @cindex logical or, bitwise
8238 @item @emph{Description}:
8239 Bitwise logical @code{OR}.
8241 This intrinsic routine is provided for backwards compatibility with
8242 GNU Fortran 77. For integer arguments, programmers should consider
8243 the use of the @ref{IOR} intrinsic defined by the Fortran standard.
8245 @item @emph{Standard}:
8251 @item @emph{Syntax}:
8252 @code{RESULT = OR(X, Y)}
8254 @item @emph{Arguments}:
8255 @multitable @columnfractions .15 .70
8256 @item @var{X} @tab The type shall be either a scalar @code{INTEGER(*)}
8257 type or a scalar @code{LOGICAL} type.
8258 @item @var{Y} @tab The type shall be the same as the type of @var{X}.
8261 @item @emph{Return value}:
8262 The return type is either a scalar @code{INTEGER(*)} or a scalar
8263 @code{LOGICAL}. If the kind type parameters differ, then the
8264 smaller kind type is implicitly converted to larger kind, and the
8265 return has the larger kind.
8267 @item @emph{Example}:
8270 LOGICAL :: T = .TRUE., F = .FALSE.
8272 DATA a / Z'F' /, b / Z'3' /
8274 WRITE (*,*) OR(T, T), OR(T, F), OR(F, T), OR(F, F)
8275 WRITE (*,*) OR(a, b)
8279 @item @emph{See also}:
8280 F95 elemental function: @ref{IOR}
8286 @section @code{PACK} --- Pack an array into an array of rank one
8288 @cindex array, packing
8289 @cindex array, reduce dimension
8290 @cindex array, gather elements
8293 @item @emph{Description}:
8294 Stores the elements of @var{ARRAY} in an array of rank one.
8296 The beginning of the resulting array is made up of elements whose @var{MASK}
8297 equals @code{TRUE}. Afterwards, positions are filled with elements taken from
8300 @item @emph{Standard}:
8304 Transformational function
8306 @item @emph{Syntax}:
8307 @code{RESULT = PACK(ARRAY, MASK[,VECTOR]}
8309 @item @emph{Arguments}:
8310 @multitable @columnfractions .15 .70
8311 @item @var{ARRAY} @tab Shall be an array of any type.
8312 @item @var{MASK} @tab Shall be an array of type @code{LOGICAL} and
8313 of the same size as @var{ARRAY}. Alternatively, it may be a @code{LOGICAL}
8315 @item @var{VECTOR} @tab (Optional) shall be an array of the same type
8316 as @var{ARRAY} and of rank one. If present, the number of elements in
8317 @var{VECTOR} shall be equal to or greater than the number of true elements
8318 in @var{MASK}. If @var{MASK} is scalar, the number of elements in
8319 @var{VECTOR} shall be equal to or greater than the number of elements in
8323 @item @emph{Return value}:
8324 The result is an array of rank one and the same type as that of @var{ARRAY}.
8325 If @var{VECTOR} is present, the result size is that of @var{VECTOR}, the
8326 number of @code{TRUE} values in @var{MASK} otherwise.
8328 @item @emph{Example}:
8329 Gathering nonzero elements from an array:
8333 m = (/ 1, 0, 0, 0, 5, 0 /)
8334 WRITE(*, FMT="(6(I0, ' '))") pack(m, m /= 0) ! "1 5"
8338 Gathering nonzero elements from an array and appending elements from @var{VECTOR}:
8342 m = (/ 1, 0, 0, 2 /)
8343 WRITE(*, FMT="(4(I0, ' '))") pack(m, m /= 0, (/ 0, 0, 3, 4 /)) ! "1 2 3 4"
8347 @item @emph{See also}:
8354 @section @code{PERROR} --- Print system error message
8356 @cindex system, error handling
8359 @item @emph{Description}:
8360 Prints (on the C @code{stderr} stream) a newline-terminated error
8361 message corresponding to the last system error. This is prefixed by
8362 @var{STRING}, a colon and a space. See @code{perror(3)}.
8364 @item @emph{Standard}:
8370 @item @emph{Syntax}:
8371 @code{CALL PERROR(STRING)}
8373 @item @emph{Arguments}:
8374 @multitable @columnfractions .15 .70
8375 @item @var{STRING} @tab A scalar of default @code{CHARACTER} type.
8378 @item @emph{See also}:
8385 @section @code{PRECISION} --- Decimal precision of a real kind
8387 @cindex model representation, precision
8390 @item @emph{Description}:
8391 @code{PRECISION(X)} returns the decimal precision in the model of the
8394 @item @emph{Standard}:
8400 @item @emph{Syntax}:
8401 @code{RESULT = PRECISION(X)}
8403 @item @emph{Arguments}:
8404 @multitable @columnfractions .15 .70
8405 @item @var{X} @tab Shall be of type @code{REAL} or @code{COMPLEX}.
8408 @item @emph{Return value}:
8409 The return value is of type @code{INTEGER} and of the default integer
8412 @item @emph{Example}:
8414 program prec_and_range
8415 real(kind=4) :: x(2)
8416 complex(kind=8) :: y
8418 print *, precision(x), range(x)
8419 print *, precision(y), range(y)
8420 end program prec_and_range
8427 @section @code{PRESENT} --- Determine whether an optional dummy argument is specified
8431 @item @emph{Description}:
8432 Determines whether an optional dummy argument is present.
8434 @item @emph{Standard}:
8440 @item @emph{Syntax}:
8441 @code{RESULT = PRESENT(A)}
8443 @item @emph{Arguments}:
8444 @multitable @columnfractions .15 .70
8445 @item @var{A} @tab May be of any type and may be a pointer, scalar or array
8446 value, or a dummy procedure. It shall be the name of an optional dummy argument
8447 accessible within the current subroutine or function.
8450 @item @emph{Return value}:
8451 Returns either @code{TRUE} if the optional argument @var{A} is present, or
8452 @code{FALSE} otherwise.
8454 @item @emph{Example}:
8456 PROGRAM test_present
8457 WRITE(*,*) f(), f(42) ! "F T"
8459 LOGICAL FUNCTION f(x)
8460 INTEGER, INTENT(IN), OPTIONAL :: x
8470 @section @code{PRODUCT} --- Product of array elements
8472 @cindex array, product
8473 @cindex array, multiply elements
8474 @cindex array, conditionally multiply elements
8475 @cindex multiply array elements
8478 @item @emph{Description}:
8479 Multiplies the elements of @var{ARRAY} along dimension @var{DIM} if
8480 the corresponding element in @var{MASK} is @code{TRUE}.
8482 @item @emph{Standard}:
8486 Transformational function
8488 @item @emph{Syntax}:
8489 @code{RESULT = PRODUCT(ARRAY[, MASK])}
8490 @code{RESULT = PRODUCT(ARRAY, DIM[, MASK])}
8492 @item @emph{Arguments}:
8493 @multitable @columnfractions .15 .70
8494 @item @var{ARRAY} @tab Shall be an array of type @code{INTEGER(*)},
8495 @code{REAL(*)} or @code{COMPLEX(*)}.
8496 @item @var{DIM} @tab (Optional) shall be a scalar of type
8497 @code{INTEGER} with a value in the range from 1 to n, where n
8498 equals the rank of @var{ARRAY}.
8499 @item @var{MASK} @tab (Optional) shall be of type @code{LOGICAL}
8500 and either be a scalar or an array of the same shape as @var{ARRAY}.
8503 @item @emph{Return value}:
8504 The result is of the same type as @var{ARRAY}.
8506 If @var{DIM} is absent, a scalar with the product of all elements in
8507 @var{ARRAY} is returned. Otherwise, an array of rank n-1, where n equals
8508 the rank of @var{ARRAY}, and a shape similar to that of @var{ARRAY} with
8509 dimension @var{DIM} dropped is returned.
8512 @item @emph{Example}:
8514 PROGRAM test_product
8515 INTEGER :: x(5) = (/ 1, 2, 3, 4 ,5 /)
8516 print *, PRODUCT(x) ! all elements, product = 120
8517 print *, PRODUCT(x, MASK=MOD(x, 2)==1) ! odd elements, product = 15
8521 @item @emph{See also}:
8528 @section @code{RADIX} --- Base of a model number
8530 @cindex model representation, base
8531 @cindex model representation, radix
8534 @item @emph{Description}:
8535 @code{RADIX(X)} returns the base of the model representing the entity @var{X}.
8537 @item @emph{Standard}:
8543 @item @emph{Syntax}:
8544 @code{RESULT = RADIX(X)}
8546 @item @emph{Arguments}:
8547 @multitable @columnfractions .15 .70
8548 @item @var{X} @tab Shall be of type @code{INTEGER} or @code{REAL}
8551 @item @emph{Return value}:
8552 The return value is a scalar of type @code{INTEGER} and of the default
8555 @item @emph{Example}:
8558 print *, "The radix for the default integer kind is", radix(0)
8559 print *, "The radix for the default real kind is", radix(0.0)
8560 end program test_radix
8568 @section @code{RAN} --- Real pseudo-random number
8570 @cindex random number generation
8573 @item @emph{Description}:
8574 For compatibility with HP FORTRAN 77/iX, the @code{RAN} intrinsic is
8575 provided as an alias for @code{RAND}. See @ref{RAND} for complete
8578 @item @emph{Standard}:
8584 @item @emph{See also}:
8585 @ref{RAND}, @ref{RANDOM_NUMBER}
8591 @section @code{RAND} --- Real pseudo-random number
8593 @cindex random number generation
8596 @item @emph{Description}:
8597 @code{RAND(FLAG)} returns a pseudo-random number from a uniform
8598 distribution between 0 and 1. If @var{FLAG} is 0, the next number
8599 in the current sequence is returned; if @var{FLAG} is 1, the generator
8600 is restarted by @code{CALL SRAND(0)}; if @var{FLAG} has any other value,
8601 it is used as a new seed with @code{SRAND}.
8603 This intrinsic routine is provided for backwards compatibility with
8604 GNU Fortran 77. It implements a simple modulo generator as provided
8605 by @command{g77}. For new code, one should consider the use of
8606 @ref{RANDOM_NUMBER} as it implements a superior algorithm.
8608 @item @emph{Standard}:
8614 @item @emph{Syntax}:
8615 @code{RESULT = RAND(FLAG)}
8617 @item @emph{Arguments}:
8618 @multitable @columnfractions .15 .70
8619 @item @var{FLAG} @tab Shall be a scalar @code{INTEGER} of kind 4.
8622 @item @emph{Return value}:
8623 The return value is of @code{REAL} type and the default kind.
8625 @item @emph{Example}:
8628 integer,parameter :: seed = 86456
8631 print *, rand(), rand(), rand(), rand()
8632 print *, rand(seed), rand(), rand(), rand()
8633 end program test_rand
8636 @item @emph{See also}:
8637 @ref{SRAND}, @ref{RANDOM_NUMBER}
8644 @section @code{RANDOM_NUMBER} --- Pseudo-random number
8645 @fnindex RANDOM_NUMBER
8646 @cindex random number generation
8649 @item @emph{Description}:
8650 Returns a single pseudorandom number or an array of pseudorandom numbers
8651 from the uniform distribution over the range @math{ 0 \leq x < 1}.
8653 The runtime-library implements George Marsaglia's KISS (Keep It Simple
8654 Stupid) random number generator (RNG). This RNG combines:
8656 @item The congruential generator @math{x(n) = 69069 \cdot x(n-1) + 1327217885}
8657 with a period of @math{2^{32}},
8658 @item A 3-shift shift-register generator with a period of @math{2^{32} - 1},
8659 @item Two 16-bit multiply-with-carry generators with a period of
8660 @math{597273182964842497 > 2^{59}}.
8662 The overall period exceeds @math{2^{123}}.
8664 Please note, this RNG is thread safe if used within OpenMP directives,
8665 i.e., its state will be consistent while called from multiple threads.
8666 However, the KISS generator does not create random numbers in parallel
8667 from multiple sources, but in sequence from a single source. If an
8668 OpenMP-enabled application heavily relies on random numbers, one should
8669 consider employing a dedicated parallel random number generator instead.
8671 @item @emph{Standard}:
8677 @item @emph{Syntax}:
8678 @code{RANDOM_NUMBER(HARVEST)}
8680 @item @emph{Arguments}:
8681 @multitable @columnfractions .15 .70
8682 @item @var{HARVEST} @tab Shall be a scalar or an array of type @code{REAL(*)}.
8685 @item @emph{Example}:
8687 program test_random_number
8689 CALL init_random_seed() ! see example of RANDOM_SEED
8690 CALL RANDOM_NUMBER(r)
8694 @item @emph{See also}:
8701 @section @code{RANDOM_SEED} --- Initialize a pseudo-random number sequence
8702 @fnindex RANDOM_SEED
8703 @cindex random number generation, seeding
8704 @cindex seeding a random number generator
8707 @item @emph{Description}:
8708 Restarts or queries the state of the pseudorandom number generator used by
8709 @code{RANDOM_NUMBER}.
8711 If @code{RANDOM_SEED} is called without arguments, it is initialized to
8712 a default state. The example below shows how to initialize the random
8713 seed based on the system's time.
8715 @item @emph{Standard}:
8721 @item @emph{Syntax}:
8722 @code{CALL RANDOM_SEED(SIZE, PUT, GET)}
8724 @item @emph{Arguments}:
8725 @multitable @columnfractions .15 .70
8726 @item @var{SIZE} @tab (Optional) Shall be a scalar and of type default
8727 @code{INTEGER}, with @code{INTENT(OUT)}. It specifies the minimum size
8728 of the arrays used with the @var{PUT} and @var{GET} arguments.
8729 @item @var{PUT} @tab (Optional) Shall be an array of type default
8730 @code{INTEGER} and rank one. It is @code{INTENT(IN)} and the size of
8731 the array must be larger than or equal to the number returned by the
8732 @var{SIZE} argument.
8733 @item @var{GET} @tab (Optional) Shall be an array of type default
8734 @code{INTEGER} and rank one. It is @code{INTENT(OUT)} and the size
8735 of the array must be larger than or equal to the number returned by
8736 the @var{SIZE} argument.
8739 @item @emph{Example}:
8741 SUBROUTINE init_random_seed()
8742 INTEGER :: i, n, clock
8743 INTEGER, DIMENSION(:), ALLOCATABLE :: seed
8745 CALL RANDOM_SEED(size = n)
8748 CALL SYSTEM_CLOCK(COUNT=clock)
8750 seed = clock + 37 * (/ (i - 1, i = 1, n) /)
8751 CALL RANDOM_SEED(PUT = seed)
8757 @item @emph{See also}:
8764 @section @code{RANGE} --- Decimal exponent range of a real kind
8766 @cindex model representation, range
8769 @item @emph{Description}:
8770 @code{RANGE(X)} returns the decimal exponent range in the model of the
8773 @item @emph{Standard}:
8779 @item @emph{Syntax}:
8780 @code{RESULT = RANGE(X)}
8782 @item @emph{Arguments}:
8783 @multitable @columnfractions .15 .70
8784 @item @var{X} @tab Shall be of type @code{REAL} or @code{COMPLEX}.
8787 @item @emph{Return value}:
8788 The return value is of type @code{INTEGER} and of the default integer
8791 @item @emph{Example}:
8792 See @code{PRECISION} for an example.
8798 @section @code{REAL} --- Convert to real type
8801 @cindex conversion, to real
8802 @cindex complex numbers, real part
8805 @item @emph{Description}:
8806 @code{REAL(X [, KIND])} converts its argument @var{X} to a real type. The
8807 @code{REALPART(X)} function is provided for compatibility with @command{g77},
8808 and its use is strongly discouraged.
8810 @item @emph{Standard}:
8816 @item @emph{Syntax}:
8817 @multitable @columnfractions .80
8818 @item @code{RESULT = REAL(X [, KIND])}
8819 @item @code{RESULT = REALPART(Z)}
8822 @item @emph{Arguments}:
8823 @multitable @columnfractions .15 .70
8824 @item @var{X} @tab Shall be @code{INTEGER(*)}, @code{REAL(*)}, or
8826 @item @var{KIND} @tab (Optional) An @code{INTEGER(*)} initialization
8827 expression indicating the kind parameter of
8831 @item @emph{Return value}:
8832 These functions return a @code{REAL(*)} variable or array under
8833 the following rules:
8837 @code{REAL(X)} is converted to a default real type if @var{X} is an
8838 integer or real variable.
8840 @code{REAL(X)} is converted to a real type with the kind type parameter
8841 of @var{X} if @var{X} is a complex variable.
8843 @code{REAL(X, KIND)} is converted to a real type with kind type
8844 parameter @var{KIND} if @var{X} is a complex, integer, or real
8848 @item @emph{Example}:
8851 complex :: x = (1.0, 2.0)
8852 print *, real(x), real(x,8), realpart(x)
8853 end program test_real
8856 @item @emph{See also}:
8857 @ref{DBLE}, @ref{DFLOAT}, @ref{FLOAT}
8864 @section @code{RENAME} --- Rename a file
8866 @cindex file system, rename file
8869 @item @emph{Description}:
8870 Renames a file from file @var{PATH1} to @var{PATH2}. A null
8871 character (@code{CHAR(0)}) can be used to mark the end of the names in
8872 @var{PATH1} and @var{PATH2}; otherwise, trailing blanks in the file
8873 names are ignored. If the @var{STATUS} argument is supplied, it
8874 contains 0 on success or a nonzero error code upon return; see
8877 This intrinsic is provided in both subroutine and function forms;
8878 however, only one form can be used in any given program unit.
8880 @item @emph{Standard}:
8884 Subroutine, function
8886 @item @emph{Syntax}:
8887 @multitable @columnfractions .80
8888 @item @code{CALL RENAME(PATH1, PATH2 [, STATUS])}
8889 @item @code{STATUS = RENAME(PATH1, PATH2)}
8892 @item @emph{Arguments}:
8893 @multitable @columnfractions .15 .70
8894 @item @var{PATH1} @tab Shall be of default @code{CHARACTER} type.
8895 @item @var{PATH2} @tab Shall be of default @code{CHARACTER} type.
8896 @item @var{STATUS} @tab (Optional) Shall be of default @code{INTEGER} type.
8899 @item @emph{See also}:
8907 @section @code{REPEAT} --- Repeated string concatenation
8909 @cindex string, repeat
8910 @cindex string, concatenate
8913 @item @emph{Description}:
8914 Concatenates @var{NCOPIES} copies of a string.
8916 @item @emph{Standard}:
8920 Transformational function
8922 @item @emph{Syntax}:
8923 @code{RESULT = REPEAT(STRING, NCOPIES)}
8925 @item @emph{Arguments}:
8926 @multitable @columnfractions .15 .70
8927 @item @var{STRING} @tab Shall be scalar and of type @code{CHARACTER(*)}.
8928 @item @var{NCOPIES} @tab Shall be scalar and of type @code{INTEGER(*)}.
8931 @item @emph{Return value}:
8932 A new scalar of type @code{CHARACTER} built up from @var{NCOPIES} copies
8935 @item @emph{Example}:
8938 write(*,*) repeat("x", 5) ! "xxxxx"
8946 @section @code{RESHAPE} --- Function to reshape an array
8948 @cindex array, change dimensions
8949 @cindex array, transmogrify
8952 @item @emph{Description}:
8953 Reshapes @var{SOURCE} to correspond to @var{SHAPE}. If necessary,
8954 the new array may be padded with elements from @var{PAD} or permuted
8955 as defined by @var{ORDER}.
8957 @item @emph{Standard}:
8961 Transformational function
8963 @item @emph{Syntax}:
8964 @code{RESULT = RESHAPE(SOURCE, SHAPE[, PAD, ORDER])}
8966 @item @emph{Arguments}:
8967 @multitable @columnfractions .15 .70
8968 @item @var{SOURCE} @tab Shall be an array of any type.
8969 @item @var{SHAPE} @tab Shall be of type @code{INTEGER} and an
8970 array of rank one. Its values must be positive or zero.
8971 @item @var{PAD} @tab (Optional) shall be an array of the same
8972 type as @var{SOURCE}.
8973 @item @var{ORDER} @tab (Optional) shall be of type @code{INTEGER}
8974 and an array of the same shape as @var{SHAPE}. Its values shall
8975 be a permutation of the numbers from 1 to n, where n is the size of
8976 @var{SHAPE}. If @var{ORDER} is absent, the natural ordering shall
8980 @item @emph{Return value}:
8981 The result is an array of shape @var{SHAPE} with the same type as
8984 @item @emph{Example}:
8986 PROGRAM test_reshape
8987 INTEGER, DIMENSION(4) :: x
8988 WRITE(*,*) SHAPE(x) ! prints "4"
8989 WRITE(*,*) SHAPE(RESHAPE(x, (/2, 2/))) ! prints "2 2"
8993 @item @emph{See also}:
9000 @section @code{RRSPACING} --- Reciprocal of the relative spacing
9002 @cindex real number, relative spacing
9003 @cindex floating point, relative spacing
9007 @item @emph{Description}:
9008 @code{RRSPACING(X)} returns the reciprocal of the relative spacing of
9009 model numbers near @var{X}.
9011 @item @emph{Standard}:
9017 @item @emph{Syntax}:
9018 @code{RESULT = RRSPACING(X)}
9020 @item @emph{Arguments}:
9021 @multitable @columnfractions .15 .70
9022 @item @var{X} @tab Shall be of type @code{REAL}.
9025 @item @emph{Return value}:
9026 The return value is of the same type and kind as @var{X}.
9027 The value returned is equal to
9028 @code{ABS(FRACTION(X)) * FLOAT(RADIX(X))**DIGITS(X)}.
9030 @item @emph{See also}:
9037 @section @code{RSHIFT} --- Right shift bits
9039 @cindex bits, shift right
9042 @item @emph{Description}:
9043 @code{RSHIFT} returns a value corresponding to @var{I} with all of the
9044 bits shifted right by @var{SHIFT} places. If the absolute value of
9045 @var{SHIFT} is greater than @code{BIT_SIZE(I)}, the value is undefined.
9046 Bits shifted out from the left end are lost; zeros are shifted in from
9049 This function has been superseded by the @code{ISHFT} intrinsic, which
9050 is standard in Fortran 95 and later.
9052 @item @emph{Standard}:
9058 @item @emph{Syntax}:
9059 @code{RESULT = RSHIFT(I, SHIFT)}
9061 @item @emph{Arguments}:
9062 @multitable @columnfractions .15 .70
9063 @item @var{I} @tab The type shall be @code{INTEGER(*)}.
9064 @item @var{SHIFT} @tab The type shall be @code{INTEGER(*)}.
9067 @item @emph{Return value}:
9068 The return value is of type @code{INTEGER(*)} and of the same kind as
9071 @item @emph{See also}:
9072 @ref{ISHFT}, @ref{ISHFTC}, @ref{LSHIFT}
9079 @section @code{SCALE} --- Scale a real value
9081 @cindex real number, scale
9082 @cindex floating point, scale
9085 @item @emph{Description}:
9086 @code{SCALE(X,I)} returns @code{X * RADIX(X)**I}.
9088 @item @emph{Standard}:
9094 @item @emph{Syntax}:
9095 @code{RESULT = SCALE(X, I)}
9097 @item @emph{Arguments}:
9098 @multitable @columnfractions .15 .70
9099 @item @var{X} @tab The type of the argument shall be a @code{REAL}.
9100 @item @var{I} @tab The type of the argument shall be a @code{INTEGER}.
9103 @item @emph{Return value}:
9104 The return value is of the same type and kind as @var{X}.
9105 Its value is @code{X * RADIX(X)**I}.
9107 @item @emph{Example}:
9110 real :: x = 178.1387e-4
9112 print *, scale(x,i), x*radix(x)**i
9113 end program test_scale
9121 @section @code{SCAN} --- Scan a string for the presence of a set of characters
9123 @cindex string, find subset
9126 @item @emph{Description}:
9127 Scans a @var{STRING} for any of the characters in a @var{SET}
9130 If @var{BACK} is either absent or equals @code{FALSE}, this function
9131 returns the position of the leftmost character of @var{STRING} that is
9132 in @var{SET}. If @var{BACK} equals @code{TRUE}, the rightmost position
9133 is returned. If no character of @var{SET} is found in @var{STRING}, the
9136 @item @emph{Standard}:
9142 @item @emph{Syntax}:
9143 @code{RESULT = SCAN(STRING, SET[, BACK [, KIND]])}
9145 @item @emph{Arguments}:
9146 @multitable @columnfractions .15 .70
9147 @item @var{STRING} @tab Shall be of type @code{CHARACTER(*)}.
9148 @item @var{SET} @tab Shall be of type @code{CHARACTER(*)}.
9149 @item @var{BACK} @tab (Optional) shall be of type @code{LOGICAL}.
9150 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
9151 expression indicating the kind parameter of
9155 @item @emph{Return value}:
9156 The return value is of type @code{INTEGER} and of kind @var{KIND}. If
9157 @var{KIND} is absent, the return value is of default integer kind.
9159 @item @emph{Example}:
9162 WRITE(*,*) SCAN("FORTRAN", "AO") ! 2, found 'O'
9163 WRITE(*,*) SCAN("FORTRAN", "AO", .TRUE.) ! 6, found 'A'
9164 WRITE(*,*) SCAN("FORTRAN", "C++") ! 0, found none
9168 @item @emph{See also}:
9169 @ref{INDEX intrinsic}, @ref{VERIFY}
9175 @section @code{SECNDS} --- Time function
9177 @cindex time, elapsed
9178 @cindex elapsed time
9181 @item @emph{Description}:
9182 @code{SECNDS(X)} gets the time in seconds from the real-time system clock.
9183 @var{X} is a reference time, also in seconds. If this is zero, the time in
9184 seconds from midnight is returned. This function is non-standard and its
9187 @item @emph{Standard}:
9193 @item @emph{Syntax}:
9194 @code{RESULT = SECNDS (X)}
9196 @item @emph{Arguments}:
9197 @multitable @columnfractions .15 .70
9198 @item @var{T} @tab Shall be of type @code{REAL(4)}.
9199 @item @var{X} @tab Shall be of type @code{REAL(4)}.
9202 @item @emph{Return value}:
9205 @item @emph{Example}:
9210 print *, secnds (0.0) ! seconds since midnight
9211 t1 = secnds (0.0) ! reference time
9212 do i = 1, 10000000 ! do something
9214 t2 = secnds (t1) ! elapsed time
9215 print *, "Something took ", t2, " seconds."
9216 end program test_secnds
9223 @section @code{SECOND} --- CPU time function
9225 @cindex time, elapsed
9226 @cindex elapsed time
9229 @item @emph{Description}:
9230 Returns a @code{REAL(4)} value representing the elapsed CPU time in
9231 seconds. This provides the same functionality as the standard
9232 @code{CPU_TIME} intrinsic, and is only included for backwards
9235 This intrinsic is provided in both subroutine and function forms;
9236 however, only one form can be used in any given program unit.
9238 @item @emph{Standard}:
9242 Subroutine, function
9244 @item @emph{Syntax}:
9245 @multitable @columnfractions .80
9246 @item @code{CALL SECOND(TIME)}
9247 @item @code{TIME = SECOND()}
9250 @item @emph{Arguments}:
9251 @multitable @columnfractions .15 .70
9252 @item @var{TIME} @tab Shall be of type @code{REAL(4)}.
9255 @item @emph{Return value}:
9256 In either syntax, @var{TIME} is set to the process's current runtime in
9259 @item @emph{See also}:
9266 @node SELECTED_CHAR_KIND
9267 @section @code{SELECTED_CHAR_KIND} --- Choose character kind
9268 @fnindex SELECTED_CHAR_KIND
9269 @cindex character kind
9270 @cindex kind, character
9273 @item @emph{Description}:
9275 @code{SELECTED_CHAR_KIND(NAME)} returns the kind value for the character
9276 set named @var{NAME}, if a character set with such a name is supported,
9277 or @math{-1} otherwise. Currently, supported character sets include
9278 ``ASCII'' and ``DEFAULT'', which are equivalent.
9280 @item @emph{Standard}:
9281 Fortran 2003 and later
9284 Transformational function
9286 @item @emph{Syntax}:
9287 @code{RESULT = SELECTED_CHAR_KIND(NAME)}
9289 @item @emph{Arguments}:
9290 @multitable @columnfractions .15 .70
9291 @item @var{NAME} @tab Shall be a scalar and of the default character type.
9294 @item @emph{Example}:
9297 integer,parameter :: ascii = selected_char_kind("ascii")
9298 character(kind=ascii, len=26) :: s
9300 s = ascii_"abcdefghijklmnopqrstuvwxyz"
9302 end program ascii_kind
9308 @node SELECTED_INT_KIND
9309 @section @code{SELECTED_INT_KIND} --- Choose integer kind
9310 @fnindex SELECTED_INT_KIND
9311 @cindex integer kind
9312 @cindex kind, integer
9315 @item @emph{Description}:
9316 @code{SELECTED_INT_KIND(I)} return the kind value of the smallest integer
9317 type that can represent all values ranging from @math{-10^I} (exclusive)
9318 to @math{10^I} (exclusive). If there is no integer kind that accommodates
9319 this range, @code{SELECTED_INT_KIND} returns @math{-1}.
9321 @item @emph{Standard}:
9325 Transformational function
9327 @item @emph{Syntax}:
9328 @code{RESULT = SELECTED_INT_KIND(I)}
9330 @item @emph{Arguments}:
9331 @multitable @columnfractions .15 .70
9332 @item @var{I} @tab Shall be a scalar and of type @code{INTEGER}.
9335 @item @emph{Example}:
9337 program large_integers
9338 integer,parameter :: k5 = selected_int_kind(5)
9339 integer,parameter :: k15 = selected_int_kind(15)
9340 integer(kind=k5) :: i5
9341 integer(kind=k15) :: i15
9343 print *, huge(i5), huge(i15)
9345 ! The following inequalities are always true
9346 print *, huge(i5) >= 10_k5**5-1
9347 print *, huge(i15) >= 10_k15**15-1
9348 end program large_integers
9354 @node SELECTED_REAL_KIND
9355 @section @code{SELECTED_REAL_KIND} --- Choose real kind
9356 @fnindex SELECTED_REAL_KIND
9361 @item @emph{Description}:
9362 @code{SELECTED_REAL_KIND(P,R)} return the kind value of a real data type
9363 with decimal precision greater of at least @code{P} digits and exponent
9364 range greater at least @code{R}.
9366 @item @emph{Standard}:
9370 Transformational function
9372 @item @emph{Syntax}:
9373 @code{RESULT = SELECTED_REAL_KIND(P, R)}
9375 @item @emph{Arguments}:
9376 @multitable @columnfractions .15 .70
9377 @item @var{P} @tab (Optional) shall be a scalar and of type @code{INTEGER}.
9378 @item @var{R} @tab (Optional) shall be a scalar and of type @code{INTEGER}.
9380 At least one argument shall be present.
9382 @item @emph{Return value}:
9384 @code{SELECTED_REAL_KIND} returns the value of the kind type parameter of
9385 a real data type with decimal precision of at least @code{P} digits and a
9386 decimal exponent range of at least @code{R}. If more than one real data
9387 type meet the criteria, the kind of the data type with the smallest
9388 decimal precision is returned. If no real data type matches the criteria,
9391 @item -1 if the processor does not support a real data type with a
9392 precision greater than or equal to @code{P}
9393 @item -2 if the processor does not support a real type with an exponent
9394 range greater than or equal to @code{R}
9395 @item -3 if neither is supported.
9398 @item @emph{Example}:
9401 integer,parameter :: p6 = selected_real_kind(6)
9402 integer,parameter :: p10r100 = selected_real_kind(10,100)
9403 integer,parameter :: r400 = selected_real_kind(r=400)
9405 real(kind=p10r100) :: y
9406 real(kind=r400) :: z
9408 print *, precision(x), range(x)
9409 print *, precision(y), range(y)
9410 print *, precision(z), range(z)
9411 end program real_kinds
9418 @section @code{SET_EXPONENT} --- Set the exponent of the model
9419 @fnindex SET_EXPONENT
9420 @cindex real number, set exponent
9421 @cindex floating point, set exponent
9424 @item @emph{Description}:
9425 @code{SET_EXPONENT(X, I)} returns the real number whose fractional part
9426 is that that of @var{X} and whose exponent part is @var{I}.
9428 @item @emph{Standard}:
9434 @item @emph{Syntax}:
9435 @code{RESULT = SET_EXPONENT(X, I)}
9437 @item @emph{Arguments}:
9438 @multitable @columnfractions .15 .70
9439 @item @var{X} @tab Shall be of type @code{REAL}.
9440 @item @var{I} @tab Shall be of type @code{INTEGER}.
9443 @item @emph{Return value}:
9444 The return value is of the same type and kind as @var{X}.
9445 The real number whose fractional part
9446 is that that of @var{X} and whose exponent part if @var{I} is returned;
9447 it is @code{FRACTION(X) * RADIX(X)**I}.
9449 @item @emph{Example}:
9452 REAL :: x = 178.1387e-4
9454 PRINT *, SET_EXPONENT(x, i), FRACTION(x) * RADIX(x)**i
9463 @section @code{SHAPE} --- Determine the shape of an array
9465 @cindex array, shape
9468 @item @emph{Description}:
9469 Determines the shape of an array.
9471 @item @emph{Standard}:
9477 @item @emph{Syntax}:
9478 @code{RESULT = SHAPE(SOURCE)}
9480 @item @emph{Arguments}:
9481 @multitable @columnfractions .15 .70
9482 @item @var{SOURCE} @tab Shall be an array or scalar of any type.
9483 If @var{SOURCE} is a pointer it must be associated and allocatable
9484 arrays must be allocated.
9487 @item @emph{Return value}:
9488 An @code{INTEGER} array of rank one with as many elements as @var{SOURCE}
9489 has dimensions. The elements of the resulting array correspond to the extend
9490 of @var{SOURCE} along the respective dimensions. If @var{SOURCE} is a scalar,
9491 the result is the rank one array of size zero.
9493 @item @emph{Example}:
9496 INTEGER, DIMENSION(-1:1, -1:2) :: A
9497 WRITE(*,*) SHAPE(A) ! (/ 3, 4 /)
9498 WRITE(*,*) SIZE(SHAPE(42)) ! (/ /)
9502 @item @emph{See also}:
9503 @ref{RESHAPE}, @ref{SIZE}
9509 @section @code{SIGN} --- Sign copying function
9513 @cindex sign copying
9516 @item @emph{Description}:
9517 @code{SIGN(A,B)} returns the value of @var{A} with the sign of @var{B}.
9519 @item @emph{Standard}:
9525 @item @emph{Syntax}:
9526 @code{RESULT = SIGN(A, B)}
9528 @item @emph{Arguments}:
9529 @multitable @columnfractions .15 .70
9530 @item @var{A} @tab Shall be of type @code{INTEGER} or @code{REAL}
9531 @item @var{B} @tab Shall be of the same type and kind as @var{A}
9534 @item @emph{Return value}:
9535 The kind of the return value is that of @var{A} and @var{B}.
9536 If @math{B\ge 0} then the result is @code{ABS(A)}, else
9537 it is @code{-ABS(A)}.
9539 @item @emph{Example}:
9542 print *, sign(-12,1)
9543 print *, sign(-12,0)
9544 print *, sign(-12,-1)
9546 print *, sign(-12.,1.)
9547 print *, sign(-12.,0.)
9548 print *, sign(-12.,-1.)
9549 end program test_sign
9552 @item @emph{Specific names}:
9553 @multitable @columnfractions .20 .20 .20 .25
9554 @item Name @tab Arguments @tab Return type @tab Standard
9555 @item @code{ISIGN(A,P)} @tab @code{INTEGER(4)} @tab @code{INTEGER(4)} @tab f95, gnu
9556 @item @code{DSIGN(A,P)} @tab @code{REAL(8)} @tab @code{REAL(8)} @tab f95, gnu
9563 @section @code{SIGNAL} --- Signal handling subroutine (or function)
9565 @cindex system, signal handling
9568 @item @emph{Description}:
9569 @code{SIGNAL(NUMBER, HANDLER [, STATUS])} causes external subroutine
9570 @var{HANDLER} to be executed with a single integer argument when signal
9571 @var{NUMBER} occurs. If @var{HANDLER} is an integer, it can be used to
9572 turn off handling of signal @var{NUMBER} or revert to its default
9573 action. See @code{signal(2)}.
9575 If @code{SIGNAL} is called as a subroutine and the @var{STATUS} argument
9576 is supplied, it is set to the value returned by @code{signal(2)}.
9578 @item @emph{Standard}:
9582 Subroutine, function
9584 @item @emph{Syntax}:
9585 @multitable @columnfractions .80
9586 @item @code{CALL SIGNAL(NUMBER, HANDLER [, STATUS])}
9587 @item @code{STATUS = SIGNAL(NUMBER, HANDLER)}
9590 @item @emph{Arguments}:
9591 @multitable @columnfractions .15 .70
9592 @item @var{NUMBER} @tab Shall be a scalar integer, with @code{INTENT(IN)}
9593 @item @var{HANDLER}@tab Signal handler (@code{INTEGER FUNCTION} or
9594 @code{SUBROUTINE}) or dummy/global @code{INTEGER} scalar.
9595 @code{INTEGER}. It is @code{INTENT(IN)}.
9596 @item @var{STATUS} @tab (Optional) @var{STATUS} shall be a scalar
9597 integer. It has @code{INTENT(OUT)}.
9600 @item @emph{Return value}:
9601 The @code{SIGNAL} function returns the value returned by @code{signal(2)}.
9603 @item @emph{Example}:
9607 external handler_print
9609 call signal (12, handler_print)
9613 end program test_signal
9620 @section @code{SIN} --- Sine function
9626 @cindex trigonometric function, sine
9630 @item @emph{Description}:
9631 @code{SIN(X)} computes the sine of @var{X}.
9633 @item @emph{Standard}:
9639 @item @emph{Syntax}:
9640 @code{RESULT = SIN(X)}
9642 @item @emph{Arguments}:
9643 @multitable @columnfractions .15 .70
9644 @item @var{X} @tab The type shall be @code{REAL(*)} or
9648 @item @emph{Return value}:
9649 The return value has same type and kind as @var{X}.
9651 @item @emph{Example}:
9656 end program test_sin
9659 @item @emph{Specific names}:
9660 @multitable @columnfractions .20 .20 .20 .25
9661 @item Name @tab Argument @tab Return type @tab Standard
9662 @item @code{DSIN(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab f95, gnu
9663 @item @code{CSIN(X)} @tab @code{COMPLEX(4) X} @tab @code{COMPLEX(4)} @tab f95, gnu
9664 @item @code{ZSIN(X)} @tab @code{COMPLEX(8) X} @tab @code{COMPLEX(8)} @tab f95, gnu
9665 @item @code{CDSIN(X)} @tab @code{COMPLEX(8) X} @tab @code{COMPLEX(8)} @tab f95, gnu
9668 @item @emph{See also}:
9675 @section @code{SINH} --- Hyperbolic sine function
9678 @cindex hyperbolic sine
9679 @cindex hyperbolic function, sine
9680 @cindex sine, hyperbolic
9683 @item @emph{Description}:
9684 @code{SINH(X)} computes the hyperbolic sine of @var{X}.
9686 @item @emph{Standard}:
9692 @item @emph{Syntax}:
9693 @code{RESULT = SINH(X)}
9695 @item @emph{Arguments}:
9696 @multitable @columnfractions .15 .70
9697 @item @var{X} @tab The type shall be @code{REAL(*)}.
9700 @item @emph{Return value}:
9701 The return value is of type @code{REAL(*)}.
9703 @item @emph{Example}:
9706 real(8) :: x = - 1.0_8
9708 end program test_sinh
9711 @item @emph{Specific names}:
9712 @multitable @columnfractions .20 .20 .20 .25
9713 @item Name @tab Argument @tab Return type @tab Standard
9714 @item @code{DSINH(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab F95 and later
9717 @item @emph{See also}:
9724 @section @code{SIZE} --- Determine the size of an array
9727 @cindex array, number of elements
9728 @cindex array, count elements
9731 @item @emph{Description}:
9732 Determine the extent of @var{ARRAY} along a specified dimension @var{DIM},
9733 or the total number of elements in @var{ARRAY} if @var{DIM} is absent.
9735 @item @emph{Standard}:
9741 @item @emph{Syntax}:
9742 @code{RESULT = SIZE(ARRAY[, DIM [, KIND]])}
9744 @item @emph{Arguments}:
9745 @multitable @columnfractions .15 .70
9746 @item @var{ARRAY} @tab Shall be an array of any type. If @var{ARRAY} is
9747 a pointer it must be associated and allocatable arrays must be allocated.
9748 @item @var{DIM} @tab (Optional) shall be a scalar of type @code{INTEGER}
9749 and its value shall be in the range from 1 to n, where n equals the rank
9751 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
9752 expression indicating the kind parameter of
9756 @item @emph{Return value}:
9757 The return value is of type @code{INTEGER} and of kind @var{KIND}. If
9758 @var{KIND} is absent, the return value is of default integer kind.
9760 @item @emph{Example}:
9763 WRITE(*,*) SIZE((/ 1, 2 /)) ! 2
9767 @item @emph{See also}:
9768 @ref{SHAPE}, @ref{RESHAPE}
9773 @section @code{SIZEOF} --- Size in bytes of an expression
9775 @cindex expression size
9776 @cindex size of an expression
9779 @item @emph{Description}:
9780 @code{SIZEOF(X)} calculates the number of bytes of storage the
9781 expression @code{X} occupies.
9783 @item @emph{Standard}:
9789 @item @emph{Syntax}:
9790 @code{N = SIZEOF(X)}
9792 @item @emph{Arguments}:
9793 @multitable @columnfractions .15 .70
9794 @item @var{X} @tab The argument shall be of any type, rank or shape.
9797 @item @emph{Return value}:
9798 The return value is of type integer and of the system-dependent kind
9799 @var{C_SIZE_T} (from the @var{ISO_C_BINDING} module). Its value is the
9800 number of bytes occupied by the argument. If the argument has the
9801 @code{POINTER} attribute, the number of bytes of the storage area pointed
9802 to is returned. If the argument is of a derived type with @code{POINTER}
9803 or @code{ALLOCATABLE} components, the return value doesn't account for
9804 the sizes of the data pointed to by these components.
9806 @item @emph{Example}:
9810 print *, (sizeof(s)/sizeof(r) == 5)
9813 The example will print @code{.TRUE.} unless you are using a platform
9814 where default @code{REAL} variables are unusually padded.
9818 @section @code{SLEEP} --- Sleep for the specified number of seconds
9820 @cindex delayed execution
9823 @item @emph{Description}:
9824 Calling this subroutine causes the process to pause for @var{SECONDS} seconds.
9826 @item @emph{Standard}:
9832 @item @emph{Syntax}:
9833 @code{CALL SLEEP(SECONDS)}
9835 @item @emph{Arguments}:
9836 @multitable @columnfractions .15 .70
9837 @item @var{SECONDS} @tab The type shall be of default @code{INTEGER}.
9840 @item @emph{Example}:
9851 @section @code{SNGL} --- Convert double precision real to default real
9853 @cindex conversion, to real
9856 @item @emph{Description}:
9857 @code{SNGL(A)} converts the double precision real @var{A}
9858 to a default real value. This is an archaic form of @code{REAL}
9859 that is specific to one type for @var{A}.
9861 @item @emph{Standard}:
9867 @item @emph{Syntax}:
9868 @code{RESULT = SNGL(A)}
9870 @item @emph{Arguments}:
9871 @multitable @columnfractions .15 .70
9872 @item @var{A} @tab The type shall be a double precision @code{REAL}.
9875 @item @emph{Return value}:
9876 The return value is of type default @code{REAL}.
9878 @item @emph{See also}:
9885 @section @code{SPACING} --- Smallest distance between two numbers of a given type
9887 @cindex real number, relative spacing
9888 @cindex floating point, relative spacing
9891 @item @emph{Description}:
9892 Determines the distance between the argument @var{X} and the nearest
9893 adjacent number of the same type.
9895 @item @emph{Standard}:
9901 @item @emph{Syntax}:
9902 @code{RESULT = SPACING(X)}
9904 @item @emph{Arguments}:
9905 @multitable @columnfractions .15 .70
9906 @item @var{X} @tab Shall be of type @code{REAL(*)}.
9909 @item @emph{Return value}:
9910 The result is of the same type as the input argument @var{X}.
9912 @item @emph{Example}:
9914 PROGRAM test_spacing
9915 INTEGER, PARAMETER :: SGL = SELECTED_REAL_KIND(p=6, r=37)
9916 INTEGER, PARAMETER :: DBL = SELECTED_REAL_KIND(p=13, r=200)
9918 WRITE(*,*) spacing(1.0_SGL) ! "1.1920929E-07" on i686
9919 WRITE(*,*) spacing(1.0_DBL) ! "2.220446049250313E-016" on i686
9923 @item @emph{See also}:
9930 @section @code{SPREAD} --- Add a dimension to an array
9932 @cindex array, increase dimension
9933 @cindex array, duplicate elements
9934 @cindex array, duplicate dimensions
9937 @item @emph{Description}:
9938 Replicates a @var{SOURCE} array @var{NCOPIES} times along a specified
9939 dimension @var{DIM}.
9941 @item @emph{Standard}:
9945 Transformational function
9947 @item @emph{Syntax}:
9948 @code{RESULT = SPREAD(SOURCE, DIM, NCOPIES)}
9950 @item @emph{Arguments}:
9951 @multitable @columnfractions .15 .70
9952 @item @var{SOURCE} @tab Shall be a scalar or an array of any type and
9953 a rank less than seven.
9954 @item @var{DIM} @tab Shall be a scalar of type @code{INTEGER} with a
9955 value in the range from 1 to n+1, where n equals the rank of @var{SOURCE}.
9956 @item @var{NCOPIES} @tab Shall be a scalar of type @code{INTEGER}.
9959 @item @emph{Return value}:
9960 The result is an array of the same type as @var{SOURCE} and has rank n+1
9961 where n equals the rank of @var{SOURCE}.
9963 @item @emph{Example}:
9966 INTEGER :: a = 1, b(2) = (/ 1, 2 /)
9967 WRITE(*,*) SPREAD(A, 1, 2) ! "1 1"
9968 WRITE(*,*) SPREAD(B, 1, 2) ! "1 1 2 2"
9972 @item @emph{See also}:
9979 @section @code{SQRT} --- Square-root function
9989 @item @emph{Description}:
9990 @code{SQRT(X)} computes the square root of @var{X}.
9992 @item @emph{Standard}:
9998 @item @emph{Syntax}:
9999 @code{RESULT = SQRT(X)}
10001 @item @emph{Arguments}:
10002 @multitable @columnfractions .15 .70
10003 @item @var{X} @tab The type shall be @code{REAL(*)} or
10007 @item @emph{Return value}:
10008 The return value is of type @code{REAL(*)} or @code{COMPLEX(*)}.
10009 The kind type parameter is the same as @var{X}.
10011 @item @emph{Example}:
10014 real(8) :: x = 2.0_8
10015 complex :: z = (1.0, 2.0)
10018 end program test_sqrt
10021 @item @emph{Specific names}:
10022 @multitable @columnfractions .20 .20 .20 .25
10023 @item Name @tab Argument @tab Return type @tab Standard
10024 @item @code{DSQRT(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab F95 and later
10025 @item @code{CSQRT(X)} @tab @code{COMPLEX(4) X} @tab @code{COMPLEX(4)} @tab F95 and later
10026 @item @code{ZSQRT(X)} @tab @code{COMPLEX(8) X} @tab @code{COMPLEX(8)} @tab GNU extension
10027 @item @code{CDSQRT(X)} @tab @code{COMPLEX(8) X} @tab @code{COMPLEX(8)} @tab GNU extension
10034 @section @code{SRAND} --- Reinitialize the random number generator
10036 @cindex random number generation, seeding
10037 @cindex seeding a random number generator
10040 @item @emph{Description}:
10041 @code{SRAND} reinitializes the pseudo-random number generator
10042 called by @code{RAND} and @code{IRAND}. The new seed used by the
10043 generator is specified by the required argument @var{SEED}.
10045 @item @emph{Standard}:
10048 @item @emph{Class}:
10051 @item @emph{Syntax}:
10052 @code{CALL SRAND(SEED)}
10054 @item @emph{Arguments}:
10055 @multitable @columnfractions .15 .70
10056 @item @var{SEED} @tab Shall be a scalar @code{INTEGER(kind=4)}.
10059 @item @emph{Return value}:
10062 @item @emph{Example}:
10063 See @code{RAND} and @code{IRAND} for examples.
10065 @item @emph{Notes}:
10066 The Fortran 2003 standard specifies the intrinsic @code{RANDOM_SEED} to
10067 initialize the pseudo-random numbers generator and @code{RANDOM_NUMBER}
10068 to generate pseudo-random numbers. Please note that in
10069 GNU Fortran, these two sets of intrinsics (@code{RAND},
10070 @code{IRAND} and @code{SRAND} on the one hand, @code{RANDOM_NUMBER} and
10071 @code{RANDOM_SEED} on the other hand) access two independent
10072 pseudo-random number generators.
10074 @item @emph{See also}:
10075 @ref{RAND}, @ref{RANDOM_SEED}, @ref{RANDOM_NUMBER}
10082 @section @code{STAT} --- Get file status
10084 @cindex file system, file status
10087 @item @emph{Description}:
10088 This function returns information about a file. No permissions are required on
10089 the file itself, but execute (search) permission is required on all of the
10090 directories in path that lead to the file.
10092 The elements that are obtained and stored in the array @code{BUFF}:
10093 @multitable @columnfractions .15 .70
10094 @item @code{buff(1)} @tab Device ID
10095 @item @code{buff(2)} @tab Inode number
10096 @item @code{buff(3)} @tab File mode
10097 @item @code{buff(4)} @tab Number of links
10098 @item @code{buff(5)} @tab Owner's uid
10099 @item @code{buff(6)} @tab Owner's gid
10100 @item @code{buff(7)} @tab ID of device containing directory entry for file (0 if not available)
10101 @item @code{buff(8)} @tab File size (bytes)
10102 @item @code{buff(9)} @tab Last access time
10103 @item @code{buff(10)} @tab Last modification time
10104 @item @code{buff(11)} @tab Last file status change time
10105 @item @code{buff(12)} @tab Preferred I/O block size (-1 if not available)
10106 @item @code{buff(13)} @tab Number of blocks allocated (-1 if not available)
10109 Not all these elements are relevant on all systems.
10110 If an element is not relevant, it is returned as 0.
10112 This intrinsic is provided in both subroutine and function forms; however,
10113 only one form can be used in any given program unit.
10115 @item @emph{Standard}:
10118 @item @emph{Class}:
10119 Subroutine, function
10121 @item @emph{Syntax}:
10122 @code{CALL STAT(FILE,BUFF[,STATUS])}
10124 @item @emph{Arguments}:
10125 @multitable @columnfractions .15 .70
10126 @item @var{FILE} @tab The type shall be @code{CHARACTER(*)}, a valid path within the file system.
10127 @item @var{BUFF} @tab The type shall be @code{INTEGER(4), DIMENSION(13)}.
10128 @item @var{STATUS} @tab (Optional) status flag of type @code{INTEGER(4)}. Returns 0
10129 on success and a system specific error code otherwise.
10132 @item @emph{Example}:
10135 INTEGER, DIMENSION(13) :: buff
10138 CALL STAT("/etc/passwd", buff, status)
10140 IF (status == 0) THEN
10141 WRITE (*, FMT="('Device ID:', T30, I19)") buff(1)
10142 WRITE (*, FMT="('Inode number:', T30, I19)") buff(2)
10143 WRITE (*, FMT="('File mode (octal):', T30, O19)") buff(3)
10144 WRITE (*, FMT="('Number of links:', T30, I19)") buff(4)
10145 WRITE (*, FMT="('Owner''s uid:', T30, I19)") buff(5)
10146 WRITE (*, FMT="('Owner''s gid:', T30, I19)") buff(6)
10147 WRITE (*, FMT="('Device where located:', T30, I19)") buff(7)
10148 WRITE (*, FMT="('File size:', T30, I19)") buff(8)
10149 WRITE (*, FMT="('Last access time:', T30, A19)") CTIME(buff(9))
10150 WRITE (*, FMT="('Last modification time', T30, A19)") CTIME(buff(10))
10151 WRITE (*, FMT="('Last status change time:', T30, A19)") CTIME(buff(11))
10152 WRITE (*, FMT="('Preferred block size:', T30, I19)") buff(12)
10153 WRITE (*, FMT="('No. of blocks allocated:', T30, I19)") buff(13)
10158 @item @emph{See also}:
10159 To stat an open file: @ref{FSTAT}, to stat a link: @ref{LSTAT}
10165 @section @code{SUM} --- Sum of array elements
10168 @cindex array, add elements
10169 @cindex array, conditionally add elements
10170 @cindex sum array elements
10173 @item @emph{Description}:
10174 Adds the elements of @var{ARRAY} along dimension @var{DIM} if
10175 the corresponding element in @var{MASK} is @code{TRUE}.
10177 @item @emph{Standard}:
10180 @item @emph{Class}:
10181 Transformational function
10183 @item @emph{Syntax}:
10184 @code{RESULT = SUM(ARRAY[, MASK])}
10185 @code{RESULT = SUM(ARRAY, DIM[, MASK])}
10187 @item @emph{Arguments}:
10188 @multitable @columnfractions .15 .70
10189 @item @var{ARRAY} @tab Shall be an array of type @code{INTEGER(*)},
10190 @code{REAL(*)} or @code{COMPLEX(*)}.
10191 @item @var{DIM} @tab (Optional) shall be a scalar of type
10192 @code{INTEGER} with a value in the range from 1 to n, where n
10193 equals the rank of @var{ARRAY}.
10194 @item @var{MASK} @tab (Optional) shall be of type @code{LOGICAL}
10195 and either be a scalar or an array of the same shape as @var{ARRAY}.
10198 @item @emph{Return value}:
10199 The result is of the same type as @var{ARRAY}.
10201 If @var{DIM} is absent, a scalar with the sum of all elements in @var{ARRAY}
10202 is returned. Otherwise, an array of rank n-1, where n equals the rank of
10203 @var{ARRAY},and a shape similar to that of @var{ARRAY} with dimension @var{DIM}
10204 dropped is returned.
10206 @item @emph{Example}:
10209 INTEGER :: x(5) = (/ 1, 2, 3, 4 ,5 /)
10210 print *, SUM(x) ! all elements, sum = 15
10211 print *, SUM(x, MASK=MOD(x, 2)==1) ! odd elements, sum = 9
10215 @item @emph{See also}:
10222 @section @code{SYMLNK} --- Create a symbolic link
10224 @cindex file system, create link
10225 @cindex file system, soft link
10228 @item @emph{Description}:
10229 Makes a symbolic link from file @var{PATH1} to @var{PATH2}. A null
10230 character (@code{CHAR(0)}) can be used to mark the end of the names in
10231 @var{PATH1} and @var{PATH2}; otherwise, trailing blanks in the file
10232 names are ignored. If the @var{STATUS} argument is supplied, it
10233 contains 0 on success or a nonzero error code upon return; see
10234 @code{symlink(2)}. If the system does not supply @code{symlink(2)},
10235 @code{ENOSYS} is returned.
10237 This intrinsic is provided in both subroutine and function forms;
10238 however, only one form can be used in any given program unit.
10240 @item @emph{Standard}:
10243 @item @emph{Class}:
10244 Subroutine, function
10246 @item @emph{Syntax}:
10247 @multitable @columnfractions .80
10248 @item @code{CALL SYMLNK(PATH1, PATH2 [, STATUS])}
10249 @item @code{STATUS = SYMLNK(PATH1, PATH2)}
10252 @item @emph{Arguments}:
10253 @multitable @columnfractions .15 .70
10254 @item @var{PATH1} @tab Shall be of default @code{CHARACTER} type.
10255 @item @var{PATH2} @tab Shall be of default @code{CHARACTER} type.
10256 @item @var{STATUS} @tab (Optional) Shall be of default @code{INTEGER} type.
10259 @item @emph{See also}:
10260 @ref{LINK}, @ref{UNLINK}
10267 @section @code{SYSTEM} --- Execute a shell command
10269 @cindex system, system call
10272 @item @emph{Description}:
10273 Passes the command @var{COMMAND} to a shell (see @code{system(3)}). If
10274 argument @var{STATUS} is present, it contains the value returned by
10275 @code{system(3)}, which is presumably 0 if the shell command succeeded.
10276 Note that which shell is used to invoke the command is system-dependent
10277 and environment-dependent.
10279 This intrinsic is provided in both subroutine and function forms;
10280 however, only one form can be used in any given program unit.
10282 @item @emph{Standard}:
10285 @item @emph{Class}:
10286 Subroutine, function
10288 @item @emph{Syntax}:
10289 @multitable @columnfractions .80
10290 @item @code{CALL SYSTEM(COMMAND [, STATUS])}
10291 @item @code{STATUS = SYSTEM(COMMAND)}
10294 @item @emph{Arguments}:
10295 @multitable @columnfractions .15 .70
10296 @item @var{COMMAND} @tab Shall be of default @code{CHARACTER} type.
10297 @item @var{STATUS} @tab (Optional) Shall be of default @code{INTEGER} type.
10300 @item @emph{See also}:
10306 @section @code{SYSTEM_CLOCK} --- Time function
10307 @fnindex SYSTEM_CLOCK
10308 @cindex time, clock ticks
10309 @cindex clock ticks
10312 @item @emph{Description}:
10313 Determines the @var{COUNT} of milliseconds of wall clock time since
10314 the Epoch (00:00:00 UTC, January 1, 1970) modulo @var{COUNT_MAX},
10315 @var{COUNT_RATE} determines the number of clock ticks per second.
10316 @var{COUNT_RATE} and @var{COUNT_MAX} are constant and specific to
10317 @command{gfortran}.
10319 If there is no clock, @var{COUNT} is set to @code{-HUGE(COUNT)}, and
10320 @var{COUNT_RATE} and @var{COUNT_MAX} are set to zero
10322 @item @emph{Standard}:
10325 @item @emph{Class}:
10328 @item @emph{Syntax}:
10329 @code{CALL SYSTEM_CLOCK([COUNT, COUNT_RATE, COUNT_MAX])}
10331 @item @emph{Arguments}:
10332 @item @emph{Arguments}:
10333 @multitable @columnfractions .15 .70
10334 @item @var{COUNT} @tab (Optional) shall be a scalar of type default
10335 @code{INTEGER} with @code{INTENT(OUT)}.
10336 @item @var{COUNT_RATE} @tab (Optional) shall be a scalar of type default
10337 @code{INTEGER} with @code{INTENT(OUT)}.
10338 @item @var{COUNT_MAX} @tab (Optional) shall be a scalar of type default
10339 @code{INTEGER} with @code{INTENT(OUT)}.
10342 @item @emph{Example}:
10344 PROGRAM test_system_clock
10345 INTEGER :: count, count_rate, count_max
10346 CALL SYSTEM_CLOCK(count, count_rate, count_max)
10347 WRITE(*,*) count, count_rate, count_max
10351 @item @emph{See also}:
10352 @ref{DATE_AND_TIME}, @ref{CPU_TIME}
10358 @section @code{TAN} --- Tangent function
10361 @cindex trigonometric function, tangent
10365 @item @emph{Description}:
10366 @code{TAN(X)} computes the tangent of @var{X}.
10368 @item @emph{Standard}:
10371 @item @emph{Class}:
10374 @item @emph{Syntax}:
10375 @code{RESULT = TAN(X)}
10377 @item @emph{Arguments}:
10378 @multitable @columnfractions .15 .70
10379 @item @var{X} @tab The type shall be @code{REAL(*)}.
10382 @item @emph{Return value}:
10383 The return value is of type @code{REAL(*)}. The kind type parameter is
10384 the same as @var{X}.
10386 @item @emph{Example}:
10389 real(8) :: x = 0.165_8
10391 end program test_tan
10394 @item @emph{Specific names}:
10395 @multitable @columnfractions .20 .20 .20 .25
10396 @item Name @tab Argument @tab Return type @tab Standard
10397 @item @code{DTAN(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab F95 and later
10400 @item @emph{See also}:
10407 @section @code{TANH} --- Hyperbolic tangent function
10410 @cindex hyperbolic tangent
10411 @cindex hyperbolic function, tangent
10412 @cindex tangent, hyperbolic
10415 @item @emph{Description}:
10416 @code{TANH(X)} computes the hyperbolic tangent of @var{X}.
10418 @item @emph{Standard}:
10421 @item @emph{Class}:
10424 @item @emph{Syntax}:
10427 @item @emph{Arguments}:
10428 @multitable @columnfractions .15 .70
10429 @item @var{X} @tab The type shall be @code{REAL(*)}.
10432 @item @emph{Return value}:
10433 The return value is of type @code{REAL(*)} and lies in the range
10434 @math{ - 1 \leq tanh(x) \leq 1 }.
10436 @item @emph{Example}:
10439 real(8) :: x = 2.1_8
10441 end program test_tanh
10444 @item @emph{Specific names}:
10445 @multitable @columnfractions .20 .20 .20 .25
10446 @item Name @tab Argument @tab Return type @tab Standard
10447 @item @code{DTANH(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab F95 and later
10450 @item @emph{See also}:
10457 @section @code{TIME} --- Time function
10459 @cindex time, current
10460 @cindex current time
10463 @item @emph{Description}:
10464 Returns the current time encoded as an integer (in the manner of the
10465 UNIX function @code{time(3)}). This value is suitable for passing to
10466 @code{CTIME()}, @code{GMTIME()}, and @code{LTIME()}.
10468 This intrinsic is not fully portable, such as to systems with 32-bit
10469 @code{INTEGER} types but supporting times wider than 32 bits. Therefore,
10470 the values returned by this intrinsic might be, or become, negative, or
10471 numerically less than previous values, during a single run of the
10474 See @ref{TIME8}, for information on a similar intrinsic that might be
10475 portable to more GNU Fortran implementations, though to fewer Fortran
10478 @item @emph{Standard}:
10481 @item @emph{Class}:
10484 @item @emph{Syntax}:
10485 @code{RESULT = TIME()}
10487 @item @emph{Return value}:
10488 The return value is a scalar of type @code{INTEGER(4)}.
10490 @item @emph{See also}:
10491 @ref{CTIME}, @ref{GMTIME}, @ref{LTIME}, @ref{MCLOCK}, @ref{TIME8}
10498 @section @code{TIME8} --- Time function (64-bit)
10500 @cindex time, current
10501 @cindex current time
10504 @item @emph{Description}:
10505 Returns the current time encoded as an integer (in the manner of the
10506 UNIX function @code{time(3)}). This value is suitable for passing to
10507 @code{CTIME()}, @code{GMTIME()}, and @code{LTIME()}.
10509 @emph{Warning:} this intrinsic does not increase the range of the timing
10510 values over that returned by @code{time(3)}. On a system with a 32-bit
10511 @code{time(3)}, @code{TIME8()} will return a 32-bit value, even though
10512 it is converted to a 64-bit @code{INTEGER(8)} value. That means
10513 overflows of the 32-bit value can still occur. Therefore, the values
10514 returned by this intrinsic might be or become negative or numerically
10515 less than previous values during a single run of the compiled program.
10517 @item @emph{Standard}:
10520 @item @emph{Class}:
10523 @item @emph{Syntax}:
10524 @code{RESULT = TIME8()}
10526 @item @emph{Return value}:
10527 The return value is a scalar of type @code{INTEGER(8)}.
10529 @item @emph{See also}:
10530 @ref{CTIME}, @ref{GMTIME}, @ref{LTIME}, @ref{MCLOCK8}, @ref{TIME}
10537 @section @code{TINY} --- Smallest positive number of a real kind
10539 @cindex limits, smallest number
10540 @cindex model representation, smallest number
10543 @item @emph{Description}:
10544 @code{TINY(X)} returns the smallest positive (non zero) number
10545 in the model of the type of @code{X}.
10547 @item @emph{Standard}:
10550 @item @emph{Class}:
10553 @item @emph{Syntax}:
10554 @code{RESULT = TINY(X)}
10556 @item @emph{Arguments}:
10557 @multitable @columnfractions .15 .70
10558 @item @var{X} @tab Shall be of type @code{REAL}.
10561 @item @emph{Return value}:
10562 The return value is of the same type and kind as @var{X}
10564 @item @emph{Example}:
10565 See @code{HUGE} for an example.
10571 @section @code{TRANSFER} --- Transfer bit patterns
10577 @item @emph{Description}:
10578 Interprets the bitwise representation of @var{SOURCE} in memory as if it
10579 is the representation of a variable or array of the same type and type
10580 parameters as @var{MOLD}.
10582 This is approximately equivalent to the C concept of @emph{casting} one
10585 @item @emph{Standard}:
10588 @item @emph{Class}:
10589 Transformational function
10591 @item @emph{Syntax}:
10592 @code{RESULT = TRANSFER(SOURCE, MOLD[, SIZE])}
10594 @item @emph{Arguments}:
10595 @multitable @columnfractions .15 .70
10596 @item @var{SOURCE} @tab Shall be a scalar or an array of any type.
10597 @item @var{MOLD} @tab Shall be a scalar or an array of any type.
10598 @item @var{SIZE} @tab (Optional) shall be a scalar of type
10602 @item @emph{Return value}:
10603 The result has the same type as @var{MOLD}, with the bit level
10604 representation of @var{SOURCE}. If @var{SIZE} is present, the result is
10605 a one-dimensional array of length @var{SIZE}. If @var{SIZE} is absent
10606 but @var{MOLD} is an array (of any size or shape), the result is a one-
10607 dimensional array of the minimum length needed to contain the entirety
10608 of the bitwise representation of @var{SOURCE}. If @var{SIZE} is absent
10609 and @var{MOLD} is a scalar, the result is a scalar.
10611 If the bitwise representation of the result is longer than that of
10612 @var{SOURCE}, then the leading bits of the result correspond to those of
10613 @var{SOURCE} and any trailing bits are filled arbitrarily.
10615 When the resulting bit representation does not correspond to a valid
10616 representation of a variable of the same type as @var{MOLD}, the results
10617 are undefined, and subsequent operations on the result cannot be
10618 guaranteed to produce sensible behavior. For example, it is possible to
10619 create @code{LOGICAL} variables for which @code{@var{VAR}} and
10620 @code{.NOT.@var{VAR}} both appear to be true.
10622 @item @emph{Example}:
10624 PROGRAM test_transfer
10625 integer :: x = 2143289344
10626 print *, transfer(x, 1.0) ! prints "NaN" on i686
10634 @section @code{TRANSPOSE} --- Transpose an array of rank two
10636 @cindex array, transpose
10637 @cindex matrix, transpose
10641 @item @emph{Description}:
10642 Transpose an array of rank two. Element (i, j) of the result has the value
10643 @code{MATRIX(j, i)}, for all i, j.
10645 @item @emph{Standard}:
10648 @item @emph{Class}:
10649 Transformational function
10651 @item @emph{Syntax}:
10652 @code{RESULT = TRANSPOSE(MATRIX)}
10654 @item @emph{Arguments}:
10655 @multitable @columnfractions .15 .70
10656 @item @var{MATRIX} @tab Shall be an array of any type and have a rank of two.
10659 @item @emph{Return value}:
10660 The result has the same type as @var{MATRIX}, and has shape
10661 @code{(/ m, n /)} if @var{MATRIX} has shape @code{(/ n, m /)}.
10667 @section @code{TRIM} --- Remove trailing blank characters of a string
10669 @cindex string, remove trailing whitespace
10672 @item @emph{Description}:
10673 Removes trailing blank characters of a string.
10675 @item @emph{Standard}:
10678 @item @emph{Class}:
10679 Transformational function
10681 @item @emph{Syntax}:
10682 @code{RESULT = TRIM(STRING)}
10684 @item @emph{Arguments}:
10685 @multitable @columnfractions .15 .70
10686 @item @var{STRING} @tab Shall be a scalar of type @code{CHARACTER(*)}.
10689 @item @emph{Return value}:
10690 A scalar of type @code{CHARACTER(*)} which length is that of @var{STRING}
10691 less the number of trailing blanks.
10693 @item @emph{Example}:
10696 CHARACTER(len=10), PARAMETER :: s = "GFORTRAN "
10697 WRITE(*,*) LEN(s), LEN(TRIM(s)) ! "10 8", with/without trailing blanks
10701 @item @emph{See also}:
10702 @ref{ADJUSTL}, @ref{ADJUSTR}
10708 @section @code{TTYNAM} --- Get the name of a terminal device.
10710 @cindex system, terminal
10713 @item @emph{Description}:
10714 Get the name of a terminal device. For more information,
10715 see @code{ttyname(3)}.
10717 This intrinsic is provided in both subroutine and function forms;
10718 however, only one form can be used in any given program unit.
10720 @item @emph{Standard}:
10723 @item @emph{Class}:
10724 Subroutine, function
10726 @item @emph{Syntax}:
10727 @multitable @columnfractions .80
10728 @item @code{CALL TTYNAM(UNIT, NAME)}
10729 @item @code{NAME = TTYNAM(UNIT)}
10732 @item @emph{Arguments}:
10733 @multitable @columnfractions .15 .70
10734 @item @var{UNIT} @tab Shall be a scalar @code{INTEGER(*)}.
10735 @item @var{NAME} @tab Shall be of type @code{CHARACTER(*)}.
10738 @item @emph{Example}:
10740 PROGRAM test_ttynam
10743 IF (isatty(unit=unit)) write(*,*) ttynam(unit)
10748 @item @emph{See also}:
10755 @section @code{UBOUND} --- Upper dimension bounds of an array
10757 @cindex array, upper bound
10760 @item @emph{Description}:
10761 Returns the upper bounds of an array, or a single upper bound
10762 along the @var{DIM} dimension.
10763 @item @emph{Standard}:
10766 @item @emph{Class}:
10769 @item @emph{Syntax}:
10770 @code{RESULT = UBOUND(ARRAY [, DIM [, KIND]])}
10772 @item @emph{Arguments}:
10773 @multitable @columnfractions .15 .70
10774 @item @var{ARRAY} @tab Shall be an array, of any type.
10775 @item @var{DIM} @tab (Optional) Shall be a scalar @code{INTEGER(*)}.
10776 @item @var{KIND}@tab (Optional) An @code{INTEGER} initialization
10777 expression indicating the kind parameter of
10781 @item @emph{Return value}:
10782 The return value is of type @code{INTEGER} and of kind @var{KIND}. If
10783 @var{KIND} is absent, the return value is of default integer kind.
10784 If @var{DIM} is absent, the result is an array of the upper bounds of
10785 @var{ARRAY}. If @var{DIM} is present, the result is a scalar
10786 corresponding to the upper bound of the array along that dimension. If
10787 @var{ARRAY} is an expression rather than a whole array or array
10788 structure component, or if it has a zero extent along the relevant
10789 dimension, the upper bound is taken to be the number of elements along
10790 the relevant dimension.
10792 @item @emph{See also}:
10799 @section @code{UMASK} --- Set the file creation mask
10801 @cindex file system, file creation mask
10804 @item @emph{Description}:
10805 Sets the file creation mask to @var{MASK} and returns the old value in
10806 argument @var{OLD} if it is supplied. See @code{umask(2)}.
10808 @item @emph{Standard}:
10811 @item @emph{Class}:
10814 @item @emph{Syntax}:
10815 @code{CALL UMASK(MASK [, OLD])}
10817 @item @emph{Arguments}:
10818 @multitable @columnfractions .15 .70
10819 @item @var{MASK} @tab Shall be a scalar of type @code{INTEGER(*)}.
10820 @item @var{MASK} @tab (Optional) Shall be a scalar of type
10829 @section @code{UNLINK} --- Remove a file from the file system
10831 @cindex file system, remove file
10834 @item @emph{Description}:
10835 Unlinks the file @var{PATH}. A null character (@code{CHAR(0)}) can be
10836 used to mark the end of the name in @var{PATH}; otherwise, trailing
10837 blanks in the file name are ignored. If the @var{STATUS} argument is
10838 supplied, it contains 0 on success or a nonzero error code upon return;
10839 see @code{unlink(2)}.
10841 This intrinsic is provided in both subroutine and function forms;
10842 however, only one form can be used in any given program unit.
10844 @item @emph{Standard}:
10847 @item @emph{Class}:
10848 Subroutine, function
10850 @item @emph{Syntax}:
10851 @multitable @columnfractions .80
10852 @item @code{CALL UNLINK(PATH [, STATUS])}
10853 @item @code{STATUS = UNLINK(PATH)}
10856 @item @emph{Arguments}:
10857 @multitable @columnfractions .15 .70
10858 @item @var{PATH} @tab Shall be of default @code{CHARACTER} type.
10859 @item @var{STATUS} @tab (Optional) Shall be of default @code{INTEGER} type.
10862 @item @emph{See also}:
10863 @ref{LINK}, @ref{SYMLNK}
10869 @section @code{UNPACK} --- Unpack an array of rank one into an array
10871 @cindex array, unpacking
10872 @cindex array, increase dimension
10873 @cindex array, scatter elements
10876 @item @emph{Description}:
10877 Store the elements of @var{VECTOR} in an array of higher rank.
10879 @item @emph{Standard}:
10882 @item @emph{Class}:
10883 Transformational function
10885 @item @emph{Syntax}:
10886 @code{RESULT = UNPACK(VECTOR, MASK, FIELD)}
10888 @item @emph{Arguments}:
10889 @multitable @columnfractions .15 .70
10890 @item @var{VECTOR} @tab Shall be an array of any type and rank one. It
10891 shall have at least as many elements as @var{MASK} has @code{TRUE} values.
10892 @item @var{MASK} @tab Shall be an array of type @code{LOGICAL}.
10893 @item @var{FIELD} @tab Shall be of the same type as @var{VECTOR} and have
10894 the same shape as @var{MASK}.
10897 @item @emph{Return value}:
10898 The resulting array corresponds to @var{FIELD} with @code{TRUE} elements
10899 of @var{MASK} replaced by values from @var{VECTOR} in array element order.
10901 @item @emph{Example}:
10903 PROGRAM test_unpack
10904 integer :: vector(2) = (/1,1/)
10905 logical :: mask(4) = (/ .TRUE., .FALSE., .FALSE., .TRUE. /)
10906 integer :: field(2,2) = 0, unity(2,2)
10908 ! result: unity matrix
10909 unity = unpack(vector, reshape(mask, (/2,2/)), field)
10913 @item @emph{See also}:
10914 @ref{PACK}, @ref{SPREAD}
10920 @section @code{VERIFY} --- Scan a string for the absence of a set of characters
10922 @cindex string, find missing set
10925 @item @emph{Description}:
10926 Verifies that all the characters in a @var{SET} are present in a @var{STRING}.
10928 If @var{BACK} is either absent or equals @code{FALSE}, this function
10929 returns the position of the leftmost character of @var{STRING} that is
10930 not in @var{SET}. If @var{BACK} equals @code{TRUE}, the rightmost position
10931 is returned. If all characters of @var{SET} are found in @var{STRING}, the
10934 @item @emph{Standard}:
10937 @item @emph{Class}:
10940 @item @emph{Syntax}:
10941 @code{RESULT = VERIFY(STRING, SET[, BACK [, KIND]])}
10943 @item @emph{Arguments}:
10944 @multitable @columnfractions .15 .70
10945 @item @var{STRING} @tab Shall be of type @code{CHARACTER(*)}.
10946 @item @var{SET} @tab Shall be of type @code{CHARACTER(*)}.
10947 @item @var{BACK} @tab (Optional) shall be of type @code{LOGICAL}.
10948 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
10949 expression indicating the kind parameter of
10953 @item @emph{Return value}:
10954 The return value is of type @code{INTEGER} and of kind @var{KIND}. If
10955 @var{KIND} is absent, the return value is of default integer kind.
10957 @item @emph{Example}:
10959 PROGRAM test_verify
10960 WRITE(*,*) VERIFY("FORTRAN", "AO") ! 1, found 'F'
10961 WRITE(*,*) VERIFY("FORTRAN", "FOO") ! 3, found 'R'
10962 WRITE(*,*) VERIFY("FORTRAN", "C++") ! 1, found 'F'
10963 WRITE(*,*) VERIFY("FORTRAN", "C++", .TRUE.) ! 7, found 'N'
10964 WRITE(*,*) VERIFY("FORTRAN", "FORTRAN") ! 0' found none
10968 @item @emph{See also}:
10969 @ref{SCAN}, @ref{INDEX intrinsic}
10975 @section @code{XOR} --- Bitwise logical exclusive OR
10977 @cindex bitwise logical exclusive or
10978 @cindex logical exclusive or, bitwise
10981 @item @emph{Description}:
10982 Bitwise logical exclusive or.
10984 This intrinsic routine is provided for backwards compatibility with
10985 GNU Fortran 77. For integer arguments, programmers should consider
10986 the use of the @ref{IEOR} intrinsic defined by the Fortran standard.
10988 @item @emph{Standard}:
10991 @item @emph{Class}:
10994 @item @emph{Syntax}:
10995 @code{RESULT = XOR(X, Y)}
10997 @item @emph{Arguments}:
10998 @multitable @columnfractions .15 .70
10999 @item @var{X} @tab The type shall be either a scalar @code{INTEGER(*)}
11000 type or a scalar @code{LOGICAL} type.
11001 @item @var{Y} @tab The type shall be the same as the type of @var{I}.
11004 @item @emph{Return value}:
11005 The return type is either a scalar @code{INTEGER(*)} or a scalar
11006 @code{LOGICAL}. If the kind type parameters differ, then the
11007 smaller kind type is implicitly converted to larger kind, and the
11008 return has the larger kind.
11010 @item @emph{Example}:
11013 LOGICAL :: T = .TRUE., F = .FALSE.
11015 DATA a / Z'F' /, b / Z'3' /
11017 WRITE (*,*) XOR(T, T), XOR(T, F), XOR(F, T), XOR(F, F)
11018 WRITE (*,*) XOR(a, b)
11022 @item @emph{See also}:
11023 F95 elemental function: @ref{IEOR}
11028 @node Intrinsic Modules
11029 @chapter Intrinsic Modules
11030 @cindex intrinsic Modules
11032 @c @node ISO_FORTRAN_ENV
11033 @section @code{ISO_FORTRAN_ENV}
11035 @item @emph{Standard}:
11036 Fortran 2003 and later
11039 The @code{ISO_FORTRAN_ENV} module provides the following scalar default-integer
11043 @item @code{CHARACTER_STORAGE_SIZE}:
11044 Size in bits of the character storage unit.
11046 @item @code{ERROR_UNIT}:
11047 Identifies the preconnected unit used for error reporting.
11049 @item @code{FILE_STORAGE_SIZE}:
11050 Size in bits of the file-storage unit.
11052 @item @code{INPUT_UNIT}:
11053 Identifies the preconnected unit identified by the asterisk
11054 (@code{*}) in @code{READ} statement.
11056 @item @code{IOSTAT_END}:
11057 The value assigned to the variable passed to the IOSTAT= specifier of
11058 an input/output statement if an end-of-file condition occurred.
11060 @item @code{IOSTAT_EOR}:
11061 The value assigned to the variable passed to the IOSTAT= specifier of
11062 an input/output statement if an end-of-record condition occurred.
11064 @item @code{NUMERIC_STORAGE_SIZE}:
11065 The size in bits of the numeric storage unit.
11067 @item @code{OUTPUT_UNIT}:
11068 Identifies the preconnected unit identified by the asterisk
11069 (@code{*}) in @code{WRITE} statement.
11072 @c @node ISO_C_BINDING
11073 @section @code{ISO_C_BINDING}
11075 @item @emph{Standard}:
11076 Fortran 2003 and later, GNU extensions
11079 The following intrinsic procedures are provided by the module; their
11080 definition can be found in the section Intrinsic Procedures of this
11084 @item @code{C_ASSOCIATED}
11085 @item @code{C_F_POINTER}
11086 @item @code{C_F_PROCPOINTER}
11087 @item @code{C_FUNLOC}
11091 The @code{ISO_C_BINDING} module provides the following named constants of the
11092 type integer, which can be used as KIND type parameter. Note that GNU
11093 Fortran currently does not support the @code{C_INT_FAST...} KIND type
11094 parameters (marked by an asterisk (@code{*}) in the list below).
11095 The @code{C_INT_FAST...} parameters have therefore the value @math{-2}
11096 and cannot be used as KIND type parameter of the @code{INTEGER} type.
11098 In addition to the integer named constants required by the Fortran 2003
11099 standard, GNU Fortran provides as an extension named constants for the
11100 128-bit integer types supported by the C compiler: @code{C_INT128_T,
11101 C_INT_LEAST128_T, C_INT_FAST128_T}.
11103 @multitable @columnfractions .15 .35 .35 .35
11104 @item Fortran Type @tab Named constant @tab C type @tab Extension
11105 @item @code{INTEGER}@tab @code{C_INT} @tab @code{int}
11106 @item @code{INTEGER}@tab @code{C_SHORT} @tab @code{short int}
11107 @item @code{INTEGER}@tab @code{C_LONG} @tab @code{long int}
11108 @item @code{INTEGER}@tab @code{C_LONG_LONG} @tab @code{long long int}
11109 @item @code{INTEGER}@tab @code{C_SIGNED_CHAR} @tab @code{signed char}/@code{unsigned char}
11110 @item @code{INTEGER}@tab @code{C_SIZE_T} @tab @code{size_t}
11111 @item @code{INTEGER}@tab @code{C_INT8_T} @tab @code{int8_t}
11112 @item @code{INTEGER}@tab @code{C_INT16_T} @tab @code{int16_t}
11113 @item @code{INTEGER}@tab @code{C_INT32_T} @tab @code{int32_t}
11114 @item @code{INTEGER}@tab @code{C_INT64_T} @tab @code{int64_t}
11115 @item @code{INTEGER}@tab @code{C_INT128_T} @tab @code{int128_t} @tab Ext.
11116 @item @code{INTEGER}@tab @code{C_INT_LEAST8_T} @tab @code{int_least8_t}
11117 @item @code{INTEGER}@tab @code{C_INT_LEAST16_T} @tab @code{int_least16_t}
11118 @item @code{INTEGER}@tab @code{C_INT_LEAST32_T} @tab @code{int_least32_t}
11119 @item @code{INTEGER}@tab @code{C_INT_LEAST64_T} @tab @code{int_least64_t}
11120 @item @code{INTEGER}@tab @code{C_INT_LEAST128_T} @tab @code{int_least128_t} @tab Ext.
11121 @item @code{INTEGER}@tab @code{C_INT_FAST8_T}* @tab @code{int_fast8_t}
11122 @item @code{INTEGER}@tab @code{C_INT_FAST16_T}* @tab @code{int_fast16_t}
11123 @item @code{INTEGER}@tab @code{C_INT_FAST32_T}* @tab @code{int_fast32_t}
11124 @item @code{INTEGER}@tab @code{C_INT_FAST64_T}* @tab @code{int_fast64_t}
11125 @item @code{INTEGER}@tab @code{C_INT_FAST128_T}* @tab @code{int_fast128_t} @tab Ext.
11126 @item @code{INTEGER}@tab @code{C_INTMAX_T} @tab @code{intmax_t}
11127 @item @code{INTEGER}@tab @code{C_INTPTR_T} @tab @code{intptr_t}
11128 @item @code{REAL} @tab @code{C_FLOAT} @tab @code{float}
11129 @item @code{REAL} @tab @code{C_DOUBLE} @tab @code{double}
11130 @item @code{REAL} @tab @code{C_LONG_DOUBLE} @tab @code{long double}
11131 @item @code{COMPLEX}@tab @code{C_FLOAT_COMPLEX} @tab @code{float _Complex}
11132 @item @code{COMPLEX}@tab @code{C_DOUBLE_COMPLEX}@tab @code{double _Complex}
11133 @item @code{COMPLEX}@tab @code{C_LONG_DOUBLE_COMPLEX}@tab @code{long double _Complex}
11134 @item @code{LOGICAL}@tab @code{C_BOOL} @tab @code{_Bool}
11135 @item @code{CHARACTER}@tab @code{C_CHAR} @tab @code{char}
11138 Additionally, the following @code{(CHARACTER(KIND=C_CHAR)} are
11141 @multitable @columnfractions .20 .45 .15
11142 @item Name @tab C definition @tab Value
11143 @item @code{C_NULL_CHAR} @tab null character @tab @code{'\0'}
11144 @item @code{C_ALERT} @tab alert @tab @code{'\a'}
11145 @item @code{C_BACKSPACE} @tab backspace @tab @code{'\b'}
11146 @item @code{C_FORM_FEED} @tab form feed @tab @code{'\f'}
11147 @item @code{C_NEW_LINE} @tab new line @tab @code{'\n'}
11148 @item @code{C_CARRIAGE_RETURN} @tab carriage return @tab @code{'\r'}
11149 @item @code{C_HORIZONTAL_TAB} @tab horizontal tab @tab @code{'\t'}
11150 @item @code{C_VERTICAL_TAB} @tab vertical tab @tab @code{'\v'}
11153 @c @node OpenMP Modules OMP_LIB and OMP_LIB_KINDS
11154 @section OpenMP Modules @code{OMP_LIB} and @code{OMP_LIB_KINDS}
11156 @item @emph{Standard}:
11157 OpenMP Application Program Interface v2.5
11161 The OpenMP Fortran runtime library routines are provided both in
11162 a form of two Fortran 90 modules, named @code{OMP_LIB} and
11163 @code{OMP_LIB_KINDS}, and in a form of a Fortran @code{include} file named
11164 @file{omp_lib.h}. The procedures provided by @code{OMP_LIB} can be found
11165 in the @ref{Top,,Introduction,libgomp,GNU OpenMP runtime library} manual,
11166 the named constants defined in the @code{OMP_LIB_KINDS} module are listed
11169 For details refer to the actual
11170 @uref{http://www.openmp.org/drupal/mp-documents/spec25.pdf,
11171 OpenMP Application Program Interface v2.5}.
11173 @code{OMP_LIB_KINDS} provides the following scalar default-integer
11177 @item @code{omp_integer_kind}
11178 @item @code{omp_logical_kind}
11179 @item @code{omp_lock_kind}
11180 @item @code{omp_nest_lock_kind}