2 Copyright (C) 2005, 2006, 2007, 2008, 2009, 2010
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.3 or
9 any later version published by the Free Software Foundation; with the
10 Invariant Sections being ``Funding Free Software'', the Front-Cover
11 Texts being (a) (see below), and with the Back-Cover Texts being (b)
12 (see below). A copy of the license is included in the gfdl(7) man page.
15 Some basic guidelines for editing this document:
17 (1) The intrinsic procedures are to be listed in alphabetical order.
18 (2) The generic name is to be used.
19 (3) The specific names are included in the function index and in a
20 table at the end of the node (See ABS entry).
21 (4) Try to maintain the same style for each entry.
27 \gdef\acos{\mathop{\rm acos}\nolimits}
28 \gdef\asin{\mathop{\rm asin}\nolimits}
29 \gdef\atan{\mathop{\rm atan}\nolimits}
30 \gdef\acosh{\mathop{\rm acosh}\nolimits}
31 \gdef\asinh{\mathop{\rm asinh}\nolimits}
32 \gdef\atanh{\mathop{\rm atanh}\nolimits}
36 @node Intrinsic Procedures
37 @chapter Intrinsic Procedures
38 @cindex intrinsic procedures
41 * Introduction: Introduction to Intrinsics
42 * @code{ABORT}: ABORT, Abort the program
43 * @code{ABS}: ABS, Absolute value
44 * @code{ACCESS}: ACCESS, Checks file access modes
45 * @code{ACHAR}: ACHAR, Character in @acronym{ASCII} collating sequence
46 * @code{ACOS}: ACOS, Arccosine function
47 * @code{ACOSH}: ACOSH, Inverse hyperbolic cosine function
48 * @code{ADJUSTL}: ADJUSTL, Left adjust a string
49 * @code{ADJUSTR}: ADJUSTR, Right adjust a string
50 * @code{AIMAG}: AIMAG, Imaginary part of complex number
51 * @code{AINT}: AINT, Truncate to a whole number
52 * @code{ALARM}: ALARM, Set an alarm clock
53 * @code{ALL}: ALL, Determine if all values are true
54 * @code{ALLOCATED}: ALLOCATED, Status of allocatable entity
55 * @code{AND}: AND, Bitwise logical AND
56 * @code{ANINT}: ANINT, Nearest whole number
57 * @code{ANY}: ANY, Determine if any values are true
58 * @code{ASIN}: ASIN, Arcsine function
59 * @code{ASINH}: ASINH, Inverse hyperbolic sine function
60 * @code{ASSOCIATED}: ASSOCIATED, Status of a pointer or pointer/target pair
61 * @code{ATAN}: ATAN, Arctangent function
62 * @code{ATAN2}: ATAN2, Arctangent function
63 * @code{ATANH}: ATANH, Inverse hyperbolic tangent function
64 * @code{BESSEL_J0}: BESSEL_J0, Bessel function of the first kind of order 0
65 * @code{BESSEL_J1}: BESSEL_J1, Bessel function of the first kind of order 1
66 * @code{BESSEL_JN}: BESSEL_JN, Bessel function of the first kind
67 * @code{BESSEL_Y0}: BESSEL_Y0, Bessel function of the second kind of order 0
68 * @code{BESSEL_Y1}: BESSEL_Y1, Bessel function of the second kind of order 1
69 * @code{BESSEL_YN}: BESSEL_YN, Bessel function of the second kind
70 * @code{BIT_SIZE}: BIT_SIZE, Bit size inquiry function
71 * @code{BTEST}: BTEST, Bit test function
72 * @code{C_ASSOCIATED}: C_ASSOCIATED, Status of a C pointer
73 * @code{C_F_POINTER}: C_F_POINTER, Convert C into Fortran pointer
74 * @code{C_F_PROCPOINTER}: C_F_PROCPOINTER, Convert C into Fortran procedure pointer
75 * @code{C_FUNLOC}: C_FUNLOC, Obtain the C address of a procedure
76 * @code{C_LOC}: C_LOC, Obtain the C address of an object
77 * @code{C_SIZEOF}: C_SIZEOF, Size in bytes of an expression
78 * @code{CEILING}: CEILING, Integer ceiling function
79 * @code{CHAR}: CHAR, Integer-to-character conversion function
80 * @code{CHDIR}: CHDIR, Change working directory
81 * @code{CHMOD}: CHMOD, Change access permissions of files
82 * @code{CMPLX}: CMPLX, Complex conversion function
83 * @code{COMMAND_ARGUMENT_COUNT}: COMMAND_ARGUMENT_COUNT, Get number of command line arguments
84 * @code{COMPLEX}: COMPLEX, Complex conversion function
85 * @code{CONJG}: CONJG, Complex conjugate function
86 * @code{COS}: COS, Cosine function
87 * @code{COSH}: COSH, Hyperbolic cosine function
88 * @code{COUNT}: COUNT, Count occurrences of TRUE in an array
89 * @code{CPU_TIME}: CPU_TIME, CPU time subroutine
90 * @code{CSHIFT}: CSHIFT, Circular shift elements of an array
91 * @code{CTIME}: CTIME, Subroutine (or function) to convert a time into a string
92 * @code{DATE_AND_TIME}: DATE_AND_TIME, Date and time subroutine
93 * @code{DBLE}: DBLE, Double precision conversion function
94 * @code{DCMPLX}: DCMPLX, Double complex conversion function
95 * @code{DIGITS}: DIGITS, Significant digits function
96 * @code{DIM}: DIM, Positive difference
97 * @code{DOT_PRODUCT}: DOT_PRODUCT, Dot product function
98 * @code{DPROD}: DPROD, Double product function
99 * @code{DREAL}: DREAL, Double real part function
100 * @code{DTIME}: DTIME, Execution time subroutine (or function)
101 * @code{EOSHIFT}: EOSHIFT, End-off shift elements of an array
102 * @code{EPSILON}: EPSILON, Epsilon function
103 * @code{ERF}: ERF, Error function
104 * @code{ERFC}: ERFC, Complementary error function
105 * @code{ERFC_SCALED}: ERFC_SCALED, Exponentially-scaled complementary error function
106 * @code{ETIME}: ETIME, Execution time subroutine (or function)
107 * @code{EXECUTE_COMMAND_LINE}: EXECUTE_COMMAND_LINE, Execute a shell command
108 * @code{EXIT}: EXIT, Exit the program with status.
109 * @code{EXP}: EXP, Exponential function
110 * @code{EXPONENT}: EXPONENT, Exponent function
111 * @code{EXTENDS_TYPE_OF}: EXTENDS_TYPE_OF, Query dynamic type for extension
112 * @code{FDATE}: FDATE, Subroutine (or function) to get the current time as a string
113 * @code{FGET}: FGET, Read a single character in stream mode from stdin
114 * @code{FGETC}: FGETC, Read a single character in stream mode
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{IMAGE_INDEX}: IMAGE_INDEX, Cosubscript to image index convertion
158 * @code{IS_IOSTAT_END}: IS_IOSTAT_END, Test for end-of-file value
159 * @code{IS_IOSTAT_EOR}: IS_IOSTAT_EOR, Test for end-of-record value
160 * @code{ISATTY}: ISATTY, Whether a unit is a terminal device
161 * @code{ISHFT}: ISHFT, Shift bits
162 * @code{ISHFTC}: ISHFTC, Shift bits circularly
163 * @code{ISNAN}: ISNAN, Tests for a NaN
164 * @code{ITIME}: ITIME, Current local time (hour/minutes/seconds)
165 * @code{KILL}: KILL, Send a signal to a process
166 * @code{KIND}: KIND, Kind of an entity
167 * @code{LBOUND}: LBOUND, Lower dimension bounds of an array
168 * @code{LCOBOUND}: LCOBOUND, Lower codimension bounds of an array
169 * @code{LEADZ}: LEADZ, Number of leading zero bits of an integer
170 * @code{LEN}: LEN, Length of a character entity
171 * @code{LEN_TRIM}: LEN_TRIM, Length of a character entity without trailing blank characters
172 * @code{LGE}: LGE, Lexical greater than or equal
173 * @code{LGT}: LGT, Lexical greater than
174 * @code{LINK}: LINK, Create a hard link
175 * @code{LLE}: LLE, Lexical less than or equal
176 * @code{LLT}: LLT, Lexical less than
177 * @code{LNBLNK}: LNBLNK, Index of the last non-blank character in a string
178 * @code{LOC}: LOC, Returns the address of a variable
179 * @code{LOG}: LOG, Logarithm function
180 * @code{LOG10}: LOG10, Base 10 logarithm function
181 * @code{LOG_GAMMA}: LOG_GAMMA, Logarithm of the Gamma function
182 * @code{LOGICAL}: LOGICAL, Convert to logical type
183 * @code{LONG}: LONG, Convert to integer type
184 * @code{LSHIFT}: LSHIFT, Left shift bits
185 * @code{LSTAT}: LSTAT, Get file status
186 * @code{LTIME}: LTIME, Convert time to local time info
187 * @code{MALLOC}: MALLOC, Dynamic memory allocation function
188 * @code{MATMUL}: MATMUL, matrix multiplication
189 * @code{MAX}: MAX, Maximum value of an argument list
190 * @code{MAXEXPONENT}: MAXEXPONENT, Maximum exponent of a real kind
191 * @code{MAXLOC}: MAXLOC, Location of the maximum value within an array
192 * @code{MAXVAL}: MAXVAL, Maximum value of an array
193 * @code{MCLOCK}: MCLOCK, Time function
194 * @code{MCLOCK8}: MCLOCK8, Time function (64-bit)
195 * @code{MERGE}: MERGE, Merge arrays
196 * @code{MIN}: MIN, Minimum value of an argument list
197 * @code{MINEXPONENT}: MINEXPONENT, Minimum exponent of a real kind
198 * @code{MINLOC}: MINLOC, Location of the minimum value within an array
199 * @code{MINVAL}: MINVAL, Minimum value of an array
200 * @code{MOD}: MOD, Remainder function
201 * @code{MODULO}: MODULO, Modulo function
202 * @code{MOVE_ALLOC}: MOVE_ALLOC, Move allocation from one object to another
203 * @code{MVBITS}: MVBITS, Move bits from one integer to another
204 * @code{NEAREST}: NEAREST, Nearest representable number
205 * @code{NEW_LINE}: NEW_LINE, New line character
206 * @code{NINT}: NINT, Nearest whole number
207 * @code{NORM2}: NORM2, Euclidean vector norm
208 * @code{NOT}: NOT, Logical negation
209 * @code{NULL}: NULL, Function that returns an disassociated pointer
210 * @code{NUM_IMAGES}: NUM_IMAGES, Number of images
211 * @code{OR}: OR, Bitwise logical OR
212 * @code{PACK}: PACK, Pack an array into an array of rank one
213 * @code{PARITY}: PARITY, Reduction with exclusive OR
214 * @code{PERROR}: PERROR, Print system error message
215 * @code{POPCNT}: POPCNT, Number of bits set
216 * @code{POPPAR}: POPPAR, Parity of the number of bits set
217 * @code{PRECISION}: PRECISION, Decimal precision of a real kind
218 * @code{PRESENT}: PRESENT, Determine whether an optional dummy argument is specified
219 * @code{PRODUCT}: PRODUCT, Product of array elements
220 * @code{RADIX}: RADIX, Base of a data model
221 * @code{RANDOM_NUMBER}: RANDOM_NUMBER, Pseudo-random number
222 * @code{RANDOM_SEED}: RANDOM_SEED, Initialize a pseudo-random number sequence
223 * @code{RAND}: RAND, Real pseudo-random number
224 * @code{RANGE}: RANGE, Decimal exponent range
225 * @code{RAN}: RAN, Real pseudo-random number
226 * @code{REAL}: REAL, Convert to real type
227 * @code{RENAME}: RENAME, Rename a file
228 * @code{REPEAT}: REPEAT, Repeated string concatenation
229 * @code{RESHAPE}: RESHAPE, Function to reshape an array
230 * @code{RRSPACING}: RRSPACING, Reciprocal of the relative spacing
231 * @code{RSHIFT}: RSHIFT, Right shift bits
232 * @code{SAME_TYPE_AS}: SAME_TYPE_AS, Query dynamic types for equality
233 * @code{SCALE}: SCALE, Scale a real value
234 * @code{SCAN}: SCAN, Scan a string for the presence of a set of characters
235 * @code{SECNDS}: SECNDS, Time function
236 * @code{SECOND}: SECOND, CPU time function
237 * @code{SELECTED_CHAR_KIND}: SELECTED_CHAR_KIND, Choose character kind
238 * @code{SELECTED_INT_KIND}: SELECTED_INT_KIND, Choose integer kind
239 * @code{SELECTED_REAL_KIND}: SELECTED_REAL_KIND, Choose real kind
240 * @code{SET_EXPONENT}: SET_EXPONENT, Set the exponent of the model
241 * @code{SHAPE}: SHAPE, Determine the shape of an array
242 * @code{SIGN}: SIGN, Sign copying function
243 * @code{SIGNAL}: SIGNAL, Signal handling subroutine (or function)
244 * @code{SIN}: SIN, Sine function
245 * @code{SINH}: SINH, Hyperbolic sine function
246 * @code{SIZE}: SIZE, Function to determine the size of an array
247 * @code{SIZEOF}: SIZEOF, Determine the size in bytes of an expression
248 * @code{SLEEP}: SLEEP, Sleep for the specified number of seconds
249 * @code{SPACING}: SPACING, Smallest distance between two numbers of a given type
250 * @code{SPREAD}: SPREAD, Add a dimension to an array
251 * @code{SQRT}: SQRT, Square-root function
252 * @code{SRAND}: SRAND, Reinitialize the random number generator
253 * @code{STAT}: STAT, Get file status
254 * @code{STORAGE_SIZE}: STORAGE_SIZE, Storage size in bits
255 * @code{SUM}: SUM, Sum of array elements
256 * @code{SYMLNK}: SYMLNK, Create a symbolic link
257 * @code{SYSTEM}: SYSTEM, Execute a shell command
258 * @code{SYSTEM_CLOCK}: SYSTEM_CLOCK, Time function
259 * @code{TAN}: TAN, Tangent function
260 * @code{TANH}: TANH, Hyperbolic tangent function
261 * @code{THIS_IMAGE}: THIS_IMAGE, Cosubscript index of this image
262 * @code{TIME}: TIME, Time function
263 * @code{TIME8}: TIME8, Time function (64-bit)
264 * @code{TINY}: TINY, Smallest positive number of a real kind
265 * @code{TRAILZ}: TRAILZ, Number of trailing zero bits of an integer
266 * @code{TRANSFER}: TRANSFER, Transfer bit patterns
267 * @code{TRANSPOSE}: TRANSPOSE, Transpose an array of rank two
268 * @code{TRIM}: TRIM, Remove trailing blank characters of a string
269 * @code{TTYNAM}: TTYNAM, Get the name of a terminal device.
270 * @code{UBOUND}: UBOUND, Upper dimension bounds of an array
271 * @code{UCOBOUND}: UCOBOUND, Upper codimension bounds of an array
272 * @code{UMASK}: UMASK, Set the file creation mask
273 * @code{UNLINK}: UNLINK, Remove a file from the file system
274 * @code{UNPACK}: UNPACK, Unpack an array of rank one into an array
275 * @code{VERIFY}: VERIFY, Scan a string for the absence of a set of characters
276 * @code{XOR}: XOR, Bitwise logical exclusive or
279 @node Introduction to Intrinsics
280 @section Introduction to intrinsic procedures
282 The intrinsic procedures provided by GNU Fortran include all of the
283 intrinsic procedures required by the Fortran 95 standard, a set of
284 intrinsic procedures for backwards compatibility with G77, and a
285 selection of intrinsic procedures from the Fortran 2003 and Fortran 2008
286 standards. Any conflict between a description here and a description in
287 either the Fortran 95 standard, the Fortran 2003 standard or the Fortran
288 2008 standard is unintentional, and the standard(s) should be considered
291 The enumeration of the @code{KIND} type parameter is processor defined in
292 the Fortran 95 standard. GNU Fortran defines the default integer type and
293 default real type by @code{INTEGER(KIND=4)} and @code{REAL(KIND=4)},
294 respectively. The standard mandates that both data types shall have
295 another kind, which have more precision. On typical target architectures
296 supported by @command{gfortran}, this kind type parameter is @code{KIND=8}.
297 Hence, @code{REAL(KIND=8)} and @code{DOUBLE PRECISION} are equivalent.
298 In the description of generic intrinsic procedures, the kind type parameter
299 will be specified by @code{KIND=*}, and in the description of specific
300 names for an intrinsic procedure the kind type parameter will be explicitly
301 given (e.g., @code{REAL(KIND=4)} or @code{REAL(KIND=8)}). Finally, for
302 brevity the optional @code{KIND=} syntax will be omitted.
304 Many of the intrinsic procedures take one or more optional arguments.
305 This document follows the convention used in the Fortran 95 standard,
306 and denotes such arguments by square brackets.
308 GNU Fortran offers the @option{-std=f95} and @option{-std=gnu} options,
309 which can be used to restrict the set of intrinsic procedures to a
310 given standard. By default, @command{gfortran} sets the @option{-std=gnu}
311 option, and so all intrinsic procedures described here are accepted. There
312 is one caveat. For a select group of intrinsic procedures, @command{g77}
313 implemented both a function and a subroutine. Both classes
314 have been implemented in @command{gfortran} for backwards compatibility
315 with @command{g77}. It is noted here that these functions and subroutines
316 cannot be intermixed in a given subprogram. In the descriptions that follow,
317 the applicable standard for each intrinsic procedure is noted.
322 @section @code{ABORT} --- Abort the program
324 @cindex program termination, with core dump
325 @cindex terminate program, with core dump
329 @item @emph{Description}:
330 @code{ABORT} causes immediate termination of the program. On operating
331 systems that support a core dump, @code{ABORT} will produce a core dump even if
332 the option @option{-fno-dump-core} is in effect, which is suitable for debugging
334 @c TODO: Check if this (with -fno-dump-core) is correct.
336 @item @emph{Standard}:
345 @item @emph{Return value}:
348 @item @emph{Example}:
351 integer :: i = 1, j = 2
352 if (i /= j) call abort
353 end program test_abort
356 @item @emph{See also}:
357 @ref{EXIT}, @ref{KILL}
364 @section @code{ABS} --- Absolute value
371 @cindex absolute value
374 @item @emph{Description}:
375 @code{ABS(A)} computes the absolute value of @code{A}.
377 @item @emph{Standard}:
378 Fortran 77 and later, has overloads that are GNU extensions
384 @code{RESULT = ABS(A)}
386 @item @emph{Arguments}:
387 @multitable @columnfractions .15 .70
388 @item @var{A} @tab The type of the argument shall be an @code{INTEGER},
389 @code{REAL}, or @code{COMPLEX}.
392 @item @emph{Return value}:
393 The return value is of the same type and
394 kind as the argument except the return value is @code{REAL} for a
395 @code{COMPLEX} argument.
397 @item @emph{Example}:
402 complex :: z = (-1.e0,0.e0)
409 @item @emph{Specific names}:
410 @multitable @columnfractions .20 .20 .20 .25
411 @item Name @tab Argument @tab Return type @tab Standard
412 @item @code{ABS(A)} @tab @code{REAL(4) A} @tab @code{REAL(4)} @tab Fortran 77 and later
413 @item @code{CABS(A)} @tab @code{COMPLEX(4) A} @tab @code{REAL(4)} @tab Fortran 77 and later
414 @item @code{DABS(A)} @tab @code{REAL(8) A} @tab @code{REAL(8)} @tab Fortran 77 and later
415 @item @code{IABS(A)} @tab @code{INTEGER(4) A} @tab @code{INTEGER(4)} @tab Fortran 77 and later
416 @item @code{ZABS(A)} @tab @code{COMPLEX(8) A} @tab @code{COMPLEX(8)} @tab GNU extension
417 @item @code{CDABS(A)} @tab @code{COMPLEX(8) A} @tab @code{COMPLEX(8)} @tab GNU extension
424 @section @code{ACCESS} --- Checks file access modes
426 @cindex file system, access mode
429 @item @emph{Description}:
430 @code{ACCESS(NAME, MODE)} checks whether the file @var{NAME}
431 exists, is readable, writable or executable. Except for the
432 executable check, @code{ACCESS} can be replaced by
433 Fortran 95's @code{INQUIRE}.
435 @item @emph{Standard}:
442 @code{RESULT = ACCESS(NAME, MODE)}
444 @item @emph{Arguments}:
445 @multitable @columnfractions .15 .70
446 @item @var{NAME} @tab Scalar @code{CHARACTER} of default kind with the
447 file name. Tailing blank are ignored unless the character @code{achar(0)}
448 is present, then all characters up to and excluding @code{achar(0)} are
450 @item @var{MODE} @tab Scalar @code{CHARACTER} of default kind with the
451 file access mode, may be any concatenation of @code{"r"} (readable),
452 @code{"w"} (writable) and @code{"x"} (executable), or @code{" "} to check
456 @item @emph{Return value}:
457 Returns a scalar @code{INTEGER}, which is @code{0} if the file is
458 accessible in the given mode; otherwise or if an invalid argument
459 has been given for @code{MODE} the value @code{1} is returned.
461 @item @emph{Example}:
465 character(len=*), parameter :: file = 'test.dat'
466 character(len=*), parameter :: file2 = 'test.dat '//achar(0)
467 if(access(file,' ') == 0) print *, trim(file),' is exists'
468 if(access(file,'r') == 0) print *, trim(file),' is readable'
469 if(access(file,'w') == 0) print *, trim(file),' is writable'
470 if(access(file,'x') == 0) print *, trim(file),' is executable'
471 if(access(file2,'rwx') == 0) &
472 print *, trim(file2),' is readable, writable and executable'
473 end program access_test
475 @item @emph{Specific names}:
476 @item @emph{See also}:
483 @section @code{ACHAR} --- Character in @acronym{ASCII} collating sequence
485 @cindex @acronym{ASCII} collating sequence
486 @cindex collating sequence, @acronym{ASCII}
489 @item @emph{Description}:
490 @code{ACHAR(I)} returns the character located at position @code{I}
491 in the @acronym{ASCII} collating sequence.
493 @item @emph{Standard}:
494 Fortran 77 and later, with @var{KIND} argument Fortran 2003 and later
500 @code{RESULT = ACHAR(I [, KIND])}
502 @item @emph{Arguments}:
503 @multitable @columnfractions .15 .70
504 @item @var{I} @tab The type shall be @code{INTEGER}.
505 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
506 expression indicating the kind parameter of the result.
509 @item @emph{Return value}:
510 The return value is of type @code{CHARACTER} with a length of one.
511 If the @var{KIND} argument is present, the return value is of the
512 specified kind and of the default kind otherwise.
514 @item @emph{Example}:
519 end program test_achar
523 See @ref{ICHAR} for a discussion of converting between numerical values
524 and formatted string representations.
526 @item @emph{See also}:
527 @ref{CHAR}, @ref{IACHAR}, @ref{ICHAR}
534 @section @code{ACOS} --- Arccosine function
537 @cindex trigonometric function, cosine, inverse
538 @cindex cosine, inverse
541 @item @emph{Description}:
542 @code{ACOS(X)} computes the arccosine of @var{X} (inverse of @code{COS(X)}).
544 @item @emph{Standard}:
545 Fortran 77 and later, for a complex argument Fortran 2008 or later
551 @code{RESULT = ACOS(X)}
553 @item @emph{Arguments}:
554 @multitable @columnfractions .15 .70
555 @item @var{X} @tab The type shall either be @code{REAL} with a magnitude that is
556 less than or equal to one - or the type shall be @code{COMPLEX}.
559 @item @emph{Return value}:
560 The return value is of the same type and kind as @var{X}.
561 The real part of the result is in radians and lies in the range
562 @math{0 \leq \Re \acos(x) \leq \pi}.
564 @item @emph{Example}:
567 real(8) :: x = 0.866_8
569 end program test_acos
572 @item @emph{Specific names}:
573 @multitable @columnfractions .20 .20 .20 .25
574 @item Name @tab Argument @tab Return type @tab Standard
575 @item @code{ACOS(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab Fortran 77 and later
576 @item @code{DACOS(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab Fortran 77 and later
579 @item @emph{See also}:
580 Inverse function: @ref{COS}
587 @section @code{ACOSH} --- Inverse hyperbolic cosine function
590 @cindex area hyperbolic cosine
591 @cindex inverse hyperbolic cosine
592 @cindex hyperbolic function, cosine, inverse
593 @cindex cosine, hyperbolic, inverse
596 @item @emph{Description}:
597 @code{ACOSH(X)} computes the inverse hyperbolic cosine of @var{X}.
599 @item @emph{Standard}:
600 Fortran 2008 and later
606 @code{RESULT = ACOSH(X)}
608 @item @emph{Arguments}:
609 @multitable @columnfractions .15 .70
610 @item @var{X} @tab The type shall be @code{REAL} or @code{COMPLEX}.
613 @item @emph{Return value}:
614 The return value has the same type and kind as @var{X}. If @var{X} is
615 complex, the imaginary part of the result is in radians and lies between
616 @math{ 0 \leq \Im \acosh(x) \leq \pi}.
618 @item @emph{Example}:
621 REAL(8), DIMENSION(3) :: x = (/ 1.0, 2.0, 3.0 /)
626 @item @emph{Specific names}:
627 @multitable @columnfractions .20 .20 .20 .25
628 @item Name @tab Argument @tab Return type @tab Standard
629 @item @code{DACOSH(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU extension
632 @item @emph{See also}:
633 Inverse function: @ref{COSH}
639 @section @code{ADJUSTL} --- Left adjust a string
641 @cindex string, adjust left
642 @cindex adjust string
645 @item @emph{Description}:
646 @code{ADJUSTL(STRING)} will left adjust a string by removing leading spaces.
647 Spaces are inserted at the end of the string as needed.
649 @item @emph{Standard}:
656 @code{RESULT = ADJUSTL(STRING)}
658 @item @emph{Arguments}:
659 @multitable @columnfractions .15 .70
660 @item @var{STRING} @tab The type shall be @code{CHARACTER}.
663 @item @emph{Return value}:
664 The return value is of type @code{CHARACTER} and of the same kind as
665 @var{STRING} where leading spaces are removed and the same number of
666 spaces are inserted on the end of @var{STRING}.
668 @item @emph{Example}:
671 character(len=20) :: str = ' gfortran'
674 end program test_adjustl
677 @item @emph{See also}:
678 @ref{ADJUSTR}, @ref{TRIM}
684 @section @code{ADJUSTR} --- Right adjust a string
686 @cindex string, adjust right
687 @cindex adjust string
690 @item @emph{Description}:
691 @code{ADJUSTR(STRING)} will right adjust a string by removing trailing spaces.
692 Spaces are inserted at the start of the string as needed.
694 @item @emph{Standard}:
701 @code{RESULT = ADJUSTR(STRING)}
703 @item @emph{Arguments}:
704 @multitable @columnfractions .15 .70
705 @item @var{STR} @tab The type shall be @code{CHARACTER}.
708 @item @emph{Return value}:
709 The return value is of type @code{CHARACTER} and of the same kind as
710 @var{STRING} where trailing spaces are removed and the same number of
711 spaces are inserted at the start of @var{STRING}.
713 @item @emph{Example}:
716 character(len=20) :: str = 'gfortran'
719 end program test_adjustr
722 @item @emph{See also}:
723 @ref{ADJUSTL}, @ref{TRIM}
729 @section @code{AIMAG} --- Imaginary part of complex number
734 @cindex complex numbers, imaginary part
737 @item @emph{Description}:
738 @code{AIMAG(Z)} yields the imaginary part of complex argument @code{Z}.
739 The @code{IMAG(Z)} and @code{IMAGPART(Z)} intrinsic functions are provided
740 for compatibility with @command{g77}, and their use in new code is
741 strongly discouraged.
743 @item @emph{Standard}:
744 Fortran 77 and later, has overloads that are GNU extensions
750 @code{RESULT = AIMAG(Z)}
752 @item @emph{Arguments}:
753 @multitable @columnfractions .15 .70
754 @item @var{Z} @tab The type of the argument shall be @code{COMPLEX}.
757 @item @emph{Return value}:
758 The return value is of type @code{REAL} with the
759 kind type parameter of the argument.
761 @item @emph{Example}:
766 z4 = cmplx(1.e0_4, 0.e0_4)
767 z8 = cmplx(0.e0_8, 1.e0_8)
768 print *, aimag(z4), dimag(z8)
769 end program test_aimag
772 @item @emph{Specific names}:
773 @multitable @columnfractions .20 .20 .20 .25
774 @item Name @tab Argument @tab Return type @tab Standard
775 @item @code{AIMAG(Z)} @tab @code{COMPLEX Z} @tab @code{REAL} @tab GNU extension
776 @item @code{DIMAG(Z)} @tab @code{COMPLEX(8) Z} @tab @code{REAL(8)} @tab GNU extension
777 @item @code{IMAG(Z)} @tab @code{COMPLEX Z} @tab @code{REAL} @tab GNU extension
778 @item @code{IMAGPART(Z)} @tab @code{COMPLEX Z} @tab @code{REAL} @tab GNU extension
785 @section @code{AINT} --- Truncate to a whole number
789 @cindex rounding, floor
792 @item @emph{Description}:
793 @code{AINT(A [, KIND])} truncates its argument to a whole number.
795 @item @emph{Standard}:
802 @code{RESULT = AINT(A [, KIND])}
804 @item @emph{Arguments}:
805 @multitable @columnfractions .15 .70
806 @item @var{A} @tab The type of the argument shall be @code{REAL}.
807 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
808 expression indicating the kind parameter of the result.
811 @item @emph{Return value}:
812 The return value is of type @code{REAL} with the kind type parameter of the
813 argument if the optional @var{KIND} is absent; otherwise, the kind
814 type parameter will be given by @var{KIND}. If the magnitude of
815 @var{X} is less than one, @code{AINT(X)} returns zero. If the
816 magnitude is equal to or greater than one then it returns the largest
817 whole number that does not exceed its magnitude. The sign is the same
818 as the sign of @var{X}.
820 @item @emph{Example}:
827 print *, aint(x4), dint(x8)
829 end program test_aint
832 @item @emph{Specific names}:
833 @multitable @columnfractions .20 .20 .20 .25
834 @item Name @tab Argument @tab Return type @tab Standard
835 @item @code{AINT(A)} @tab @code{REAL(4) A} @tab @code{REAL(4)} @tab Fortran 77 and later
836 @item @code{DINT(A)} @tab @code{REAL(8) A} @tab @code{REAL(8)} @tab Fortran 77 and later
843 @section @code{ALARM} --- Execute a routine after a given delay
845 @cindex delayed execution
848 @item @emph{Description}:
849 @code{ALARM(SECONDS, HANDLER [, STATUS])} causes external subroutine @var{HANDLER}
850 to be executed after a delay of @var{SECONDS} by using @code{alarm(2)} to
851 set up a signal and @code{signal(2)} to catch it. If @var{STATUS} is
852 supplied, it will be returned with the number of seconds remaining until
853 any previously scheduled alarm was due to be delivered, or zero if there
854 was no previously scheduled alarm.
856 @item @emph{Standard}:
863 @code{CALL ALARM(SECONDS, HANDLER [, STATUS])}
865 @item @emph{Arguments}:
866 @multitable @columnfractions .15 .70
867 @item @var{SECONDS} @tab The type of the argument shall be a scalar
868 @code{INTEGER}. It is @code{INTENT(IN)}.
869 @item @var{HANDLER} @tab Signal handler (@code{INTEGER FUNCTION} or
870 @code{SUBROUTINE}) or dummy/global @code{INTEGER} scalar. The scalar
871 values may be either @code{SIG_IGN=1} to ignore the alarm generated
872 or @code{SIG_DFL=0} to set the default action. It is @code{INTENT(IN)}.
873 @item @var{STATUS} @tab (Optional) @var{STATUS} shall be a scalar
874 variable of the default @code{INTEGER} kind. It is @code{INTENT(OUT)}.
877 @item @emph{Example}:
880 external handler_print
882 call alarm (3, handler_print, i)
885 end program test_alarm
887 This will cause the external routine @var{handler_print} to be called
894 @section @code{ALL} --- All values in @var{MASK} along @var{DIM} are true
896 @cindex array, apply condition
897 @cindex array, condition testing
900 @item @emph{Description}:
901 @code{ALL(MASK [, DIM])} determines if all the values are true in @var{MASK}
902 in the array along dimension @var{DIM}.
904 @item @emph{Standard}:
908 Transformational function
911 @code{RESULT = ALL(MASK [, DIM])}
913 @item @emph{Arguments}:
914 @multitable @columnfractions .15 .70
915 @item @var{MASK} @tab The type of the argument shall be @code{LOGICAL} and
916 it shall not be scalar.
917 @item @var{DIM} @tab (Optional) @var{DIM} shall be a scalar integer
918 with a value that lies between one and the rank of @var{MASK}.
921 @item @emph{Return value}:
922 @code{ALL(MASK)} returns a scalar value of type @code{LOGICAL} where
923 the kind type parameter is the same as the kind type parameter of
924 @var{MASK}. If @var{DIM} is present, then @code{ALL(MASK, DIM)} returns
925 an array with the rank of @var{MASK} minus 1. The shape is determined from
926 the shape of @var{MASK} where the @var{DIM} dimension is elided.
930 @code{ALL(MASK)} is true if all elements of @var{MASK} are true.
931 It also is true if @var{MASK} has zero size; otherwise, it is false.
933 If the rank of @var{MASK} is one, then @code{ALL(MASK,DIM)} is equivalent
934 to @code{ALL(MASK)}. If the rank is greater than one, then @code{ALL(MASK,DIM)}
935 is determined by applying @code{ALL} to the array sections.
938 @item @emph{Example}:
942 l = all((/.true., .true., .true./))
947 integer a(2,3), b(2,3)
951 print *, all(a .eq. b, 1)
952 print *, all(a .eq. b, 2)
953 end subroutine section
961 @section @code{ALLOCATED} --- Status of an allocatable entity
963 @cindex allocation, status
966 @item @emph{Description}:
967 @code{ALLOCATED(ARRAY)} and @code{ALLOCATED(SCALAR)} check the allocation
968 status of @var{ARRAY} and @var{SCALAR}, respectively.
970 @item @emph{Standard}:
971 Fortran 95 and later. Note, the @code{SCALAR=} keyword and allocatable
972 scalar entities are available in Fortran 2003 and later.
978 @code{RESULT = ALLOCATED(ARRAY)} or @code{RESULT = ALLOCATED(SCALAR)}
980 @item @emph{Arguments}:
981 @multitable @columnfractions .15 .70
982 @item @var{ARRAY} @tab The argument shall be an @code{ALLOCATABLE} array.
983 @item @var{SCALAR} @tab The argument shall be an @code{ALLOCATABLE} scalar.
986 @item @emph{Return value}:
987 The return value is a scalar @code{LOGICAL} with the default logical
988 kind type parameter. If the argument is allocated, then the result is
989 @code{.TRUE.}; otherwise, it returns @code{.FALSE.}
991 @item @emph{Example}:
993 program test_allocated
995 real(4), allocatable :: x(:)
996 if (.not. allocated(x)) allocate(x(i))
997 end program test_allocated
1004 @section @code{AND} --- Bitwise logical AND
1006 @cindex bitwise logical and
1007 @cindex logical and, bitwise
1010 @item @emph{Description}:
1011 Bitwise logical @code{AND}.
1013 This intrinsic routine is provided for backwards compatibility with
1014 GNU Fortran 77. For integer arguments, programmers should consider
1015 the use of the @ref{IAND} intrinsic defined by the Fortran standard.
1017 @item @emph{Standard}:
1023 @item @emph{Syntax}:
1024 @code{RESULT = AND(I, J)}
1026 @item @emph{Arguments}:
1027 @multitable @columnfractions .15 .70
1028 @item @var{I} @tab The type shall be either a scalar @code{INTEGER}
1029 type or a scalar @code{LOGICAL} type.
1030 @item @var{J} @tab The type shall be the same as the type of @var{I}.
1033 @item @emph{Return value}:
1034 The return type is either a scalar @code{INTEGER} or a scalar
1035 @code{LOGICAL}. If the kind type parameters differ, then the
1036 smaller kind type is implicitly converted to larger kind, and the
1037 return has the larger kind.
1039 @item @emph{Example}:
1042 LOGICAL :: T = .TRUE., F = .FALSE.
1044 DATA a / Z'F' /, b / Z'3' /
1046 WRITE (*,*) AND(T, T), AND(T, F), AND(F, T), AND(F, F)
1047 WRITE (*,*) AND(a, b)
1051 @item @emph{See also}:
1052 Fortran 95 elemental function: @ref{IAND}
1058 @section @code{ANINT} --- Nearest whole number
1062 @cindex rounding, ceiling
1065 @item @emph{Description}:
1066 @code{ANINT(A [, KIND])} rounds its argument to the nearest whole number.
1068 @item @emph{Standard}:
1069 Fortran 77 and later
1074 @item @emph{Syntax}:
1075 @code{RESULT = ANINT(A [, KIND])}
1077 @item @emph{Arguments}:
1078 @multitable @columnfractions .15 .70
1079 @item @var{A} @tab The type of the argument shall be @code{REAL}.
1080 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
1081 expression indicating the kind parameter of the result.
1084 @item @emph{Return value}:
1085 The return value is of type real with the kind type parameter of the
1086 argument if the optional @var{KIND} is absent; otherwise, the kind
1087 type parameter will be given by @var{KIND}. If @var{A} is greater than
1088 zero, @code{ANINT(A)} returns @code{AINT(X+0.5)}. If @var{A} is
1089 less than or equal to zero then it returns @code{AINT(X-0.5)}.
1091 @item @emph{Example}:
1098 print *, anint(x4), dnint(x8)
1100 end program test_anint
1103 @item @emph{Specific names}:
1104 @multitable @columnfractions .20 .20 .20 .25
1105 @item Name @tab Argument @tab Return type @tab Standard
1106 @item @code{AINT(A)} @tab @code{REAL(4) A} @tab @code{REAL(4)} @tab Fortran 77 and later
1107 @item @code{DNINT(A)} @tab @code{REAL(8) A} @tab @code{REAL(8)} @tab Fortran 77 and later
1114 @section @code{ANY} --- Any value in @var{MASK} along @var{DIM} is true
1116 @cindex array, apply condition
1117 @cindex array, condition testing
1120 @item @emph{Description}:
1121 @code{ANY(MASK [, DIM])} determines if any of the values in the logical array
1122 @var{MASK} along dimension @var{DIM} are @code{.TRUE.}.
1124 @item @emph{Standard}:
1125 Fortran 95 and later
1128 Transformational function
1130 @item @emph{Syntax}:
1131 @code{RESULT = ANY(MASK [, DIM])}
1133 @item @emph{Arguments}:
1134 @multitable @columnfractions .15 .70
1135 @item @var{MASK} @tab The type of the argument shall be @code{LOGICAL} and
1136 it shall not be scalar.
1137 @item @var{DIM} @tab (Optional) @var{DIM} shall be a scalar integer
1138 with a value that lies between one and the rank of @var{MASK}.
1141 @item @emph{Return value}:
1142 @code{ANY(MASK)} returns a scalar value of type @code{LOGICAL} where
1143 the kind type parameter is the same as the kind type parameter of
1144 @var{MASK}. If @var{DIM} is present, then @code{ANY(MASK, DIM)} returns
1145 an array with the rank of @var{MASK} minus 1. The shape is determined from
1146 the shape of @var{MASK} where the @var{DIM} dimension is elided.
1150 @code{ANY(MASK)} is true if any element of @var{MASK} is true;
1151 otherwise, it is false. It also is false if @var{MASK} has zero size.
1153 If the rank of @var{MASK} is one, then @code{ANY(MASK,DIM)} is equivalent
1154 to @code{ANY(MASK)}. If the rank is greater than one, then @code{ANY(MASK,DIM)}
1155 is determined by applying @code{ANY} to the array sections.
1158 @item @emph{Example}:
1162 l = any((/.true., .true., .true./))
1167 integer a(2,3), b(2,3)
1171 print *, any(a .eq. b, 1)
1172 print *, any(a .eq. b, 2)
1173 end subroutine section
1174 end program test_any
1181 @section @code{ASIN} --- Arcsine function
1184 @cindex trigonometric function, sine, inverse
1185 @cindex sine, inverse
1188 @item @emph{Description}:
1189 @code{ASIN(X)} computes the arcsine of its @var{X} (inverse of @code{SIN(X)}).
1191 @item @emph{Standard}:
1192 Fortran 77 and later, for a complex argument Fortran 2008 or later
1197 @item @emph{Syntax}:
1198 @code{RESULT = ASIN(X)}
1200 @item @emph{Arguments}:
1201 @multitable @columnfractions .15 .70
1202 @item @var{X} @tab The type shall be either @code{REAL} and a magnitude that is
1203 less than or equal to one - or be @code{COMPLEX}.
1206 @item @emph{Return value}:
1207 The return value is of the same type and kind as @var{X}.
1208 The real part of the result is in radians and lies in the range
1209 @math{-\pi/2 \leq \Re \asin(x) \leq \pi/2}.
1211 @item @emph{Example}:
1214 real(8) :: x = 0.866_8
1216 end program test_asin
1219 @item @emph{Specific names}:
1220 @multitable @columnfractions .20 .20 .20 .25
1221 @item Name @tab Argument @tab Return type @tab Standard
1222 @item @code{ASIN(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab Fortran 77 and later
1223 @item @code{DASIN(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab Fortran 77 and later
1226 @item @emph{See also}:
1227 Inverse function: @ref{SIN}
1234 @section @code{ASINH} --- Inverse hyperbolic sine function
1237 @cindex area hyperbolic sine
1238 @cindex inverse hyperbolic sine
1239 @cindex hyperbolic function, sine, inverse
1240 @cindex sine, hyperbolic, inverse
1243 @item @emph{Description}:
1244 @code{ASINH(X)} computes the inverse hyperbolic sine of @var{X}.
1246 @item @emph{Standard}:
1247 Fortran 2008 and later
1252 @item @emph{Syntax}:
1253 @code{RESULT = ASINH(X)}
1255 @item @emph{Arguments}:
1256 @multitable @columnfractions .15 .70
1257 @item @var{X} @tab The type shall be @code{REAL} or @code{COMPLEX}.
1260 @item @emph{Return value}:
1261 The return value is of the same type and kind as @var{X}. If @var{X} is
1262 complex, the imaginary part of the result is in radians and lies between
1263 @math{-\pi/2 \leq \Im \asinh(x) \leq \pi/2}.
1265 @item @emph{Example}:
1268 REAL(8), DIMENSION(3) :: x = (/ -1.0, 0.0, 1.0 /)
1269 WRITE (*,*) ASINH(x)
1273 @item @emph{Specific names}:
1274 @multitable @columnfractions .20 .20 .20 .25
1275 @item Name @tab Argument @tab Return type @tab Standard
1276 @item @code{DASINH(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU extension.
1279 @item @emph{See also}:
1280 Inverse function: @ref{SINH}
1286 @section @code{ASSOCIATED} --- Status of a pointer or pointer/target pair
1288 @cindex pointer, status
1289 @cindex association status
1292 @item @emph{Description}:
1293 @code{ASSOCIATED(POINTER [, TARGET])} determines the status of the pointer
1294 @var{POINTER} or if @var{POINTER} is associated with the target @var{TARGET}.
1296 @item @emph{Standard}:
1297 Fortran 95 and later
1302 @item @emph{Syntax}:
1303 @code{RESULT = ASSOCIATED(POINTER [, TARGET])}
1305 @item @emph{Arguments}:
1306 @multitable @columnfractions .15 .70
1307 @item @var{POINTER} @tab @var{POINTER} shall have the @code{POINTER} attribute
1308 and it can be of any type.
1309 @item @var{TARGET} @tab (Optional) @var{TARGET} shall be a pointer or
1310 a target. It must have the same type, kind type parameter, and
1311 array rank as @var{POINTER}.
1313 The association status of neither @var{POINTER} nor @var{TARGET} shall be
1316 @item @emph{Return value}:
1317 @code{ASSOCIATED(POINTER)} returns a scalar value of type @code{LOGICAL(4)}.
1318 There are several cases:
1320 @item (A) When the optional @var{TARGET} is not present then
1321 @code{ASSOCIATED(POINTER)} is true if @var{POINTER} is associated with a target; otherwise, it returns false.
1322 @item (B) If @var{TARGET} is present and a scalar target, the result is true if
1323 @var{TARGET} is not a zero-sized storage sequence and the target associated with @var{POINTER} occupies the same storage units. If @var{POINTER} is
1324 disassociated, the result is false.
1325 @item (C) If @var{TARGET} is present and an array target, the result is true if
1326 @var{TARGET} and @var{POINTER} have the same shape, are not zero-sized arrays,
1327 are arrays whose elements are not zero-sized storage sequences, and
1328 @var{TARGET} and @var{POINTER} occupy the same storage units in array element
1330 As in case(B), the result is false, if @var{POINTER} is disassociated.
1331 @item (D) If @var{TARGET} is present and an scalar pointer, the result is true
1332 if @var{TARGET} is associated with @var{POINTER}, the target associated with
1333 @var{TARGET} are not zero-sized storage sequences and occupy the same storage
1335 The result is false, if either @var{TARGET} or @var{POINTER} is disassociated.
1336 @item (E) If @var{TARGET} is present and an array pointer, the result is true if
1337 target associated with @var{POINTER} and the target associated with @var{TARGET}
1338 have the same shape, are not zero-sized arrays, are arrays whose elements are
1339 not zero-sized storage sequences, and @var{TARGET} and @var{POINTER} occupy
1340 the same storage units in array element order.
1341 The result is false, if either @var{TARGET} or @var{POINTER} is disassociated.
1344 @item @emph{Example}:
1346 program test_associated
1348 real, target :: tgt(2) = (/1., 2./)
1349 real, pointer :: ptr(:)
1351 if (associated(ptr) .eqv. .false.) call abort
1352 if (associated(ptr,tgt) .eqv. .false.) call abort
1353 end program test_associated
1356 @item @emph{See also}:
1363 @section @code{ATAN} --- Arctangent function
1366 @cindex trigonometric function, tangent, inverse
1367 @cindex tangent, inverse
1370 @item @emph{Description}:
1371 @code{ATAN(X)} computes the arctangent of @var{X}.
1373 @item @emph{Standard}:
1374 Fortran 77 and later, for a complex argument and for two arguments
1375 Fortran 2008 or later
1380 @item @emph{Syntax}:
1381 @code{RESULT = ATAN(X)}
1382 @code{RESULT = ATAN(Y, X)}
1384 @item @emph{Arguments}:
1385 @multitable @columnfractions .15 .70
1386 @item @var{X} @tab The type shall be @code{REAL} or @code{COMPLEX};
1387 if @var{Y} is present, @var{X} shall be REAL.
1388 @item @var{Y} shall be of the same type and kind as @var{X}.
1391 @item @emph{Return value}:
1392 The return value is of the same type and kind as @var{X}.
1393 If @var{Y} is present, the result is identical to @code{ATAN2(Y,X)}.
1394 Otherwise, it the arcus tangent of @var{X}, where the real part of
1395 the result is in radians and lies in the range
1396 @math{-\pi/2 \leq \Re \atan(x) \leq \pi/2}.
1398 @item @emph{Example}:
1401 real(8) :: x = 2.866_8
1403 end program test_atan
1406 @item @emph{Specific names}:
1407 @multitable @columnfractions .20 .20 .20 .25
1408 @item Name @tab Argument @tab Return type @tab Standard
1409 @item @code{ATAN(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab Fortran 77 and later
1410 @item @code{DATAN(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab Fortran 77 and later
1413 @item @emph{See also}:
1414 Inverse function: @ref{TAN}
1421 @section @code{ATAN2} --- Arctangent function
1424 @cindex trigonometric function, tangent, inverse
1425 @cindex tangent, inverse
1428 @item @emph{Description}:
1429 @code{ATAN2(Y, X)} computes the principal value of the argument
1430 function of the complex number @math{X + i Y}. This function can
1431 be used to transform from carthesian into polar coordinates and
1432 allows to determine the angle in the correct quadrant.
1434 @item @emph{Standard}:
1435 Fortran 77 and later
1440 @item @emph{Syntax}:
1441 @code{RESULT = ATAN2(Y, X)}
1443 @item @emph{Arguments}:
1444 @multitable @columnfractions .15 .70
1445 @item @var{Y} @tab The type shall be @code{REAL}.
1446 @item @var{X} @tab The type and kind type parameter shall be the same as @var{Y}.
1447 If @var{Y} is zero, then @var{X} must be nonzero.
1450 @item @emph{Return value}:
1451 The return value has the same type and kind type parameter as @var{Y}.
1452 It is the principal value of the complex number @math{X + i Y}. If
1453 @var{X} is nonzero, then it lies in the range @math{-\pi \le \atan (x) \leq \pi}.
1454 The sign is positive if @var{Y} is positive. If @var{Y} is zero, then
1455 the return value is zero if @var{X} is positive and @math{\pi} if @var{X}
1456 is negative. Finally, if @var{X} is zero, then the magnitude of the result
1459 @item @emph{Example}:
1462 real(4) :: x = 1.e0_4, y = 0.5e0_4
1464 end program test_atan2
1467 @item @emph{Specific names}:
1468 @multitable @columnfractions .20 .20 .20 .25
1469 @item Name @tab Argument @tab Return type @tab Standard
1470 @item @code{ATAN2(X, Y)} @tab @code{REAL(4) X, Y} @tab @code{REAL(4)} @tab Fortran 77 and later
1471 @item @code{DATAN2(X, Y)} @tab @code{REAL(8) X, Y} @tab @code{REAL(8)} @tab Fortran 77 and later
1478 @section @code{ATANH} --- Inverse hyperbolic tangent function
1481 @cindex area hyperbolic tangent
1482 @cindex inverse hyperbolic tangent
1483 @cindex hyperbolic function, tangent, inverse
1484 @cindex tangent, hyperbolic, inverse
1487 @item @emph{Description}:
1488 @code{ATANH(X)} computes the inverse hyperbolic tangent of @var{X}.
1490 @item @emph{Standard}:
1491 Fortran 2008 and later
1496 @item @emph{Syntax}:
1497 @code{RESULT = ATANH(X)}
1499 @item @emph{Arguments}:
1500 @multitable @columnfractions .15 .70
1501 @item @var{X} @tab The type shall be @code{REAL} or @code{COMPLEX}.
1504 @item @emph{Return value}:
1505 The return value has same type and kind as @var{X}. If @var{X} is
1506 complex, the imaginary part of the result is in radians and lies between
1507 @math{-\pi/2 \leq \Im \atanh(x) \leq \pi/2}.
1509 @item @emph{Example}:
1512 REAL, DIMENSION(3) :: x = (/ -1.0, 0.0, 1.0 /)
1513 WRITE (*,*) ATANH(x)
1517 @item @emph{Specific names}:
1518 @multitable @columnfractions .20 .20 .20 .25
1519 @item Name @tab Argument @tab Return type @tab Standard
1520 @item @code{DATANH(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU extension
1523 @item @emph{See also}:
1524 Inverse function: @ref{TANH}
1530 @section @code{BESSEL_J0} --- Bessel function of the first kind of order 0
1534 @cindex Bessel function, first kind
1537 @item @emph{Description}:
1538 @code{BESSEL_J0(X)} computes the Bessel function of the first kind of
1539 order 0 of @var{X}. This function is available under the name
1540 @code{BESJ0} as a GNU extension.
1542 @item @emph{Standard}:
1543 Fortran 2008 and later
1548 @item @emph{Syntax}:
1549 @code{RESULT = BESSEL_J0(X)}
1551 @item @emph{Arguments}:
1552 @multitable @columnfractions .15 .70
1553 @item @var{X} @tab The type shall be @code{REAL}, and it shall be scalar.
1556 @item @emph{Return value}:
1557 The return value is of type @code{REAL} and lies in the
1558 range @math{ - 0.4027... \leq Bessel (0,x) \leq 1}. It has the same
1561 @item @emph{Example}:
1564 real(8) :: x = 0.0_8
1566 end program test_besj0
1569 @item @emph{Specific names}:
1570 @multitable @columnfractions .20 .20 .20 .25
1571 @item Name @tab Argument @tab Return type @tab Standard
1572 @item @code{DBESJ0(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU extension
1579 @section @code{BESSEL_J1} --- Bessel function of the first kind of order 1
1583 @cindex Bessel function, first kind
1586 @item @emph{Description}:
1587 @code{BESSEL_J1(X)} computes the Bessel function of the first kind of
1588 order 1 of @var{X}. This function is available under the name
1589 @code{BESJ1} as a GNU extension.
1591 @item @emph{Standard}:
1597 @item @emph{Syntax}:
1598 @code{RESULT = BESSEL_J1(X)}
1600 @item @emph{Arguments}:
1601 @multitable @columnfractions .15 .70
1602 @item @var{X} @tab The type shall be @code{REAL}, and it shall be scalar.
1605 @item @emph{Return value}:
1606 The return value is of type @code{REAL} and it lies in the
1607 range @math{ - 0.5818... \leq Bessel (0,x) \leq 0.5818 }. It has the same
1610 @item @emph{Example}:
1613 real(8) :: x = 1.0_8
1615 end program test_besj1
1618 @item @emph{Specific names}:
1619 @multitable @columnfractions .20 .20 .20 .25
1620 @item Name @tab Argument @tab Return type @tab Standard
1621 @item @code{DBESJ1(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU extension
1628 @section @code{BESSEL_JN} --- Bessel function of the first kind
1632 @cindex Bessel function, first kind
1635 @item @emph{Description}:
1636 @code{BESSEL_JN(N, X)} computes the Bessel function of the first kind of
1637 order @var{N} of @var{X}. This function is available under the name
1638 @code{BESJN} as a GNU extension. If @var{N} and @var{X} are arrays,
1639 their ranks and shapes shall conform.
1641 @code{BESSEL_JN(N1, N2, X)} returns an array with the Bessel functions
1642 of the first kind of the orders @var{N1} to @var{N2}.
1644 @item @emph{Standard}:
1645 Fortran 2008 and later, negative @var{N} is allowed as GNU extension
1648 Elemental function, except for the tranformational function
1649 @code{BESSEL_JN(N1, N2, X)}
1651 @item @emph{Syntax}:
1652 @code{RESULT = BESSEL_JN(N, X)}
1653 @code{RESULT = BESSEL_JN(N1, N2, X)}
1655 @item @emph{Arguments}:
1656 @multitable @columnfractions .15 .70
1657 @item @var{N} @tab Shall be a scalar or an array of type @code{INTEGER}.
1658 @item @var{N1} @tab Shall be a non-negative scalar of type @code{INTEGER}.
1659 @item @var{N2} @tab Shall be a non-negative scalar of type @code{INTEGER}.
1660 @item @var{X} @tab Shall be a scalar or an array of type @code{REAL};
1661 for @code{BESSEL_JN(N1, N2, X)} it shall be scalar.
1664 @item @emph{Return value}:
1665 The return value is a scalar of type @code{REAL}. It has the same
1669 The transformational function uses a recurrence algorithm which might,
1670 for some values of @var{X}, lead to different results than calls to
1671 the elemental function.
1673 @item @emph{Example}:
1676 real(8) :: x = 1.0_8
1678 end program test_besjn
1681 @item @emph{Specific names}:
1682 @multitable @columnfractions .20 .20 .20 .25
1683 @item Name @tab Argument @tab Return type @tab Standard
1684 @item @code{DBESJN(N, X)} @tab @code{INTEGER N} @tab @code{REAL(8)} @tab GNU extension
1685 @item @tab @code{REAL(8) X} @tab @tab
1692 @section @code{BESSEL_Y0} --- Bessel function of the second kind of order 0
1696 @cindex Bessel function, second kind
1699 @item @emph{Description}:
1700 @code{BESSEL_Y0(X)} computes the Bessel function of the second kind of
1701 order 0 of @var{X}. This function is available under the name
1702 @code{BESY0} as a GNU extension.
1704 @item @emph{Standard}:
1705 Fortran 2008 and later
1710 @item @emph{Syntax}:
1711 @code{RESULT = BESSEL_Y0(X)}
1713 @item @emph{Arguments}:
1714 @multitable @columnfractions .15 .70
1715 @item @var{X} @tab The type shall be @code{REAL}, and it shall be scalar.
1718 @item @emph{Return value}:
1719 The return value is a scalar of type @code{REAL}. It has the same
1722 @item @emph{Example}:
1725 real(8) :: x = 0.0_8
1727 end program test_besy0
1730 @item @emph{Specific names}:
1731 @multitable @columnfractions .20 .20 .20 .25
1732 @item Name @tab Argument @tab Return type @tab Standard
1733 @item @code{DBESY0(X)}@tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU extension
1740 @section @code{BESSEL_Y1} --- Bessel function of the second kind of order 1
1744 @cindex Bessel function, second kind
1747 @item @emph{Description}:
1748 @code{BESSEL_Y1(X)} computes the Bessel function of the second kind of
1749 order 1 of @var{X}. This function is available under the name
1750 @code{BESY1} as a GNU extension.
1752 @item @emph{Standard}:
1753 Fortran 2008 and later
1758 @item @emph{Syntax}:
1759 @code{RESULT = BESSEL_Y1(X)}
1761 @item @emph{Arguments}:
1762 @multitable @columnfractions .15 .70
1763 @item @var{X} @tab The type shall be @code{REAL}, and it shall be scalar.
1766 @item @emph{Return value}:
1767 The return value is a scalar of type @code{REAL}. It has the same
1770 @item @emph{Example}:
1773 real(8) :: x = 1.0_8
1775 end program test_besy1
1778 @item @emph{Specific names}:
1779 @multitable @columnfractions .20 .20 .20 .25
1780 @item Name @tab Argument @tab Return type @tab Standard
1781 @item @code{DBESY1(X)}@tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU extension
1788 @section @code{BESSEL_YN} --- Bessel function of the second kind
1792 @cindex Bessel function, second kind
1795 @item @emph{Description}:
1796 @code{BESSEL_YN(N, X)} computes the Bessel function of the second kind of
1797 order @var{N} of @var{X}. This function is available under the name
1798 @code{BESYN} as a GNU extension. If @var{N} and @var{X} are arrays,
1799 their ranks and shapes shall conform.
1801 @code{BESSEL_YN(N1, N2, X)} returns an array with the Bessel functions
1802 of the first kind of the orders @var{N1} to @var{N2}.
1804 @item @emph{Standard}:
1805 Fortran 2008 and later, negative @var{N} is allowed as GNU extension
1808 Elemental function, except for the tranformational function
1809 @code{BESSEL_YN(N1, N2, X)}
1811 @item @emph{Syntax}:
1812 @code{RESULT = BESSEL_YN(N, X)}
1813 @code{RESULT = BESSEL_YN(N1, N2, X)}
1815 @item @emph{Arguments}:
1816 @multitable @columnfractions .15 .70
1817 @item @var{N} @tab Shall be a scalar or an array of type @code{INTEGER} .
1818 @item @var{N1} @tab Shall be a non-negative scalar of type @code{INTEGER}.
1819 @item @var{N2} @tab Shall be a non-negative scalar of type @code{INTEGER}.
1820 @item @var{X} @tab Shall be a scalar or an array of type @code{REAL};
1821 for @code{BESSEL_YN(N1, N2, X)} it shall be scalar.
1824 @item @emph{Return value}:
1825 The return value is a scalar of type @code{REAL}. It has the same
1829 The transformational function uses a recurrence algorithm which might,
1830 for some values of @var{X}, lead to different results than calls to
1831 the elemental function.
1833 @item @emph{Example}:
1836 real(8) :: x = 1.0_8
1838 end program test_besyn
1841 @item @emph{Specific names}:
1842 @multitable @columnfractions .20 .20 .20 .25
1843 @item Name @tab Argument @tab Return type @tab Standard
1844 @item @code{DBESYN(N,X)} @tab @code{INTEGER N} @tab @code{REAL(8)} @tab GNU extension
1845 @item @tab @code{REAL(8) X} @tab @tab
1852 @section @code{BIT_SIZE} --- Bit size inquiry function
1854 @cindex bits, number of
1855 @cindex size of a variable, in bits
1858 @item @emph{Description}:
1859 @code{BIT_SIZE(I)} returns the number of bits (integer precision plus sign bit)
1860 represented by the type of @var{I}. The result of @code{BIT_SIZE(I)} is
1861 independent of the actual value of @var{I}.
1863 @item @emph{Standard}:
1864 Fortran 95 and later
1869 @item @emph{Syntax}:
1870 @code{RESULT = BIT_SIZE(I)}
1872 @item @emph{Arguments}:
1873 @multitable @columnfractions .15 .70
1874 @item @var{I} @tab The type shall be @code{INTEGER}.
1877 @item @emph{Return value}:
1878 The return value is of type @code{INTEGER}
1880 @item @emph{Example}:
1882 program test_bit_size
1887 end program test_bit_size
1894 @section @code{BTEST} --- Bit test function
1896 @cindex bits, testing
1899 @item @emph{Description}:
1900 @code{BTEST(I,POS)} returns logical @code{.TRUE.} if the bit at @var{POS}
1901 in @var{I} is set. The counting of the bits starts at 0.
1903 @item @emph{Standard}:
1904 Fortran 95 and later
1909 @item @emph{Syntax}:
1910 @code{RESULT = BTEST(I, POS)}
1912 @item @emph{Arguments}:
1913 @multitable @columnfractions .15 .70
1914 @item @var{I} @tab The type shall be @code{INTEGER}.
1915 @item @var{POS} @tab The type shall be @code{INTEGER}.
1918 @item @emph{Return value}:
1919 The return value is of type @code{LOGICAL}
1921 @item @emph{Example}:
1924 integer :: i = 32768 + 1024 + 64
1928 bool = btest(i, pos)
1931 end program test_btest
1937 @section @code{C_ASSOCIATED} --- Status of a C pointer
1938 @fnindex C_ASSOCIATED
1939 @cindex association status, C pointer
1940 @cindex pointer, C association status
1943 @item @emph{Description}:
1944 @code{C_ASSOCIATED(c_prt_1[, c_ptr_2])} determines the status of the C pointer
1945 @var{c_ptr_1} or if @var{c_ptr_1} is associated with the target @var{c_ptr_2}.
1947 @item @emph{Standard}:
1948 Fortran 2003 and later
1953 @item @emph{Syntax}:
1954 @code{RESULT = C_ASSOCIATED(c_prt_1[, c_ptr_2])}
1956 @item @emph{Arguments}:
1957 @multitable @columnfractions .15 .70
1958 @item @var{c_ptr_1} @tab Scalar of the type @code{C_PTR} or @code{C_FUNPTR}.
1959 @item @var{c_ptr_2} @tab (Optional) Scalar of the same type as @var{c_ptr_1}.
1962 @item @emph{Return value}:
1963 The return value is of type @code{LOGICAL}; it is @code{.false.} if either
1964 @var{c_ptr_1} is a C NULL pointer or if @var{c_ptr1} and @var{c_ptr_2}
1965 point to different addresses.
1967 @item @emph{Example}:
1969 subroutine association_test(a,b)
1970 use iso_c_binding, only: c_associated, c_loc, c_ptr
1974 if(c_associated(b, c_loc(a))) &
1975 stop 'b and a do not point to same target'
1976 end subroutine association_test
1979 @item @emph{See also}:
1980 @ref{C_LOC}, @ref{C_FUNLOC}
1985 @section @code{C_FUNLOC} --- Obtain the C address of a procedure
1987 @cindex pointer, C address of procedures
1990 @item @emph{Description}:
1991 @code{C_FUNLOC(x)} determines the C address of the argument.
1993 @item @emph{Standard}:
1994 Fortran 2003 and later
1999 @item @emph{Syntax}:
2000 @code{RESULT = C_FUNLOC(x)}
2002 @item @emph{Arguments}:
2003 @multitable @columnfractions .15 .70
2004 @item @var{x} @tab Interoperable function or pointer to such function.
2007 @item @emph{Return value}:
2008 The return value is of type @code{C_FUNPTR} and contains the C address
2011 @item @emph{Example}:
2017 subroutine sub(a) bind(c)
2027 subroutine my_routine(p) bind(c,name='myC_func')
2029 type(c_funptr), intent(in) :: p
2032 call my_routine(c_funloc(sub))
2036 @item @emph{See also}:
2037 @ref{C_ASSOCIATED}, @ref{C_LOC}, @ref{C_F_POINTER}, @ref{C_F_PROCPOINTER}
2041 @node C_F_PROCPOINTER
2042 @section @code{C_F_PROCPOINTER} --- Convert C into Fortran procedure pointer
2043 @fnindex C_F_PROCPOINTER
2044 @cindex pointer, C address of pointers
2047 @item @emph{Description}:
2048 @code{C_F_PROCPOINTER(CPTR, FPTR)} Assign the target of the C function pointer
2049 @var{CPTR} to the Fortran procedure pointer @var{FPTR}.
2051 @item @emph{Standard}:
2052 Fortran 2003 and later
2057 @item @emph{Syntax}:
2058 @code{CALL C_F_PROCPOINTER(cptr, fptr)}
2060 @item @emph{Arguments}:
2061 @multitable @columnfractions .15 .70
2062 @item @var{CPTR} @tab scalar of the type @code{C_FUNPTR}. It is
2064 @item @var{FPTR} @tab procedure pointer interoperable with @var{cptr}. It is
2068 @item @emph{Example}:
2076 real(c_float), intent(in) :: a
2077 real(c_float) :: func
2081 function getIterFunc() bind(c,name="getIterFunc")
2083 type(c_funptr) :: getIterFunc
2086 type(c_funptr) :: cfunptr
2087 procedure(func), pointer :: myFunc
2088 cfunptr = getIterFunc()
2089 call c_f_procpointer(cfunptr, myFunc)
2093 @item @emph{See also}:
2094 @ref{C_LOC}, @ref{C_F_POINTER}
2099 @section @code{C_F_POINTER} --- Convert C into Fortran pointer
2100 @fnindex C_F_POINTER
2101 @cindex pointer, convert C to Fortran
2104 @item @emph{Description}:
2105 @code{C_F_POINTER(CPTR, FPTR[, SHAPE])} Assign the target the C pointer
2106 @var{CPTR} to the Fortran pointer @var{FPTR} and specify its
2109 @item @emph{Standard}:
2110 Fortran 2003 and later
2115 @item @emph{Syntax}:
2116 @code{CALL C_F_POINTER(CPTR, FPTR[, SHAPE])}
2118 @item @emph{Arguments}:
2119 @multitable @columnfractions .15 .70
2120 @item @var{CPTR} @tab scalar of the type @code{C_PTR}. It is
2122 @item @var{FPTR} @tab pointer interoperable with @var{cptr}. It is
2124 @item @var{SHAPE} @tab (Optional) Rank-one array of type @code{INTEGER}
2125 with @code{INTENT(IN)}. It shall be present
2126 if and only if @var{fptr} is an array. The size
2127 must be equal to the rank of @var{fptr}.
2130 @item @emph{Example}:
2136 subroutine my_routine(p) bind(c,name='myC_func')
2138 type(c_ptr), intent(out) :: p
2142 real,pointer :: a(:)
2143 call my_routine(cptr)
2144 call c_f_pointer(cptr, a, [12])
2148 @item @emph{See also}:
2149 @ref{C_LOC}, @ref{C_F_PROCPOINTER}
2154 @section @code{C_LOC} --- Obtain the C address of an object
2156 @cindex procedure pointer, convert C to Fortran
2159 @item @emph{Description}:
2160 @code{C_LOC(X)} determines the C address of the argument.
2162 @item @emph{Standard}:
2163 Fortran 2003 and later
2168 @item @emph{Syntax}:
2169 @code{RESULT = C_LOC(X)}
2171 @item @emph{Arguments}:
2172 @multitable @columnfractions .10 .75
2173 @item @var{X} @tab Shall have either the POINTER or TARGET attribute. It shall not be a coindexed object. It shall either be a variable with interoperable type and kind type parameters, or be a scalar, nonpolymorphic variable with no length type parameters.
2177 @item @emph{Return value}:
2178 The return value is of type @code{C_PTR} and contains the C address
2181 @item @emph{Example}:
2183 subroutine association_test(a,b)
2184 use iso_c_binding, only: c_associated, c_loc, c_ptr
2188 if(c_associated(b, c_loc(a))) &
2189 stop 'b and a do not point to same target'
2190 end subroutine association_test
2193 @item @emph{See also}:
2194 @ref{C_ASSOCIATED}, @ref{C_FUNLOC}, @ref{C_F_POINTER}, @ref{C_F_PROCPOINTER}
2199 @section @code{C_SIZEOF} --- Size in bytes of an expression
2201 @cindex expression size
2202 @cindex size of an expression
2205 @item @emph{Description}:
2206 @code{C_SIZEOF(X)} calculates the number of bytes of storage the
2207 expression @code{X} occupies.
2209 @item @emph{Standard}:
2215 @item @emph{Syntax}:
2216 @code{N = C_SIZEOF(X)}
2218 @item @emph{Arguments}:
2219 @multitable @columnfractions .15 .70
2220 @item @var{X} @tab The argument shall be an interoperable data entity.
2223 @item @emph{Return value}:
2224 The return value is of type integer and of the system-dependent kind
2225 @var{C_SIZE_T} (from the @var{ISO_C_BINDING} module). Its value is the
2226 number of bytes occupied by the argument. If the argument has the
2227 @code{POINTER} attribute, the number of bytes of the storage area pointed
2228 to is returned. If the argument is of a derived type with @code{POINTER}
2229 or @code{ALLOCATABLE} components, the return value doesn't account for
2230 the sizes of the data pointed to by these components.
2232 @item @emph{Example}:
2236 real(c_float) :: r, s(5)
2237 print *, (c_sizeof(s)/c_sizeof(r) == 5)
2240 The example will print @code{.TRUE.} unless you are using a platform
2241 where default @code{REAL} variables are unusually padded.
2243 @item @emph{See also}:
2244 @ref{SIZEOF}, @ref{STORAGE_SIZE}
2249 @section @code{CEILING} --- Integer ceiling function
2252 @cindex rounding, ceiling
2255 @item @emph{Description}:
2256 @code{CEILING(A)} returns the least integer greater than or equal to @var{A}.
2258 @item @emph{Standard}:
2259 Fortran 95 and later
2264 @item @emph{Syntax}:
2265 @code{RESULT = CEILING(A [, KIND])}
2267 @item @emph{Arguments}:
2268 @multitable @columnfractions .15 .70
2269 @item @var{A} @tab The type shall be @code{REAL}.
2270 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
2271 expression indicating the kind parameter of the result.
2274 @item @emph{Return value}:
2275 The return value is of type @code{INTEGER(KIND)} if @var{KIND} is present
2276 and a default-kind @code{INTEGER} otherwise.
2278 @item @emph{Example}:
2280 program test_ceiling
2283 print *, ceiling(x) ! returns 64
2284 print *, ceiling(y) ! returns -63
2285 end program test_ceiling
2288 @item @emph{See also}:
2289 @ref{FLOOR}, @ref{NINT}
2296 @section @code{CHAR} --- Character conversion function
2298 @cindex conversion, to character
2301 @item @emph{Description}:
2302 @code{CHAR(I [, KIND])} returns the character represented by the integer @var{I}.
2304 @item @emph{Standard}:
2305 Fortran 77 and later
2310 @item @emph{Syntax}:
2311 @code{RESULT = CHAR(I [, KIND])}
2313 @item @emph{Arguments}:
2314 @multitable @columnfractions .15 .70
2315 @item @var{I} @tab The type shall be @code{INTEGER}.
2316 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
2317 expression indicating the kind parameter of the result.
2320 @item @emph{Return value}:
2321 The return value is of type @code{CHARACTER(1)}
2323 @item @emph{Example}:
2329 print *, i, c ! returns 'J'
2330 end program test_char
2333 @item @emph{Specific names}:
2334 @multitable @columnfractions .20 .20 .20 .25
2335 @item Name @tab Argument @tab Return type @tab Standard
2336 @item @code{CHAR(I)} @tab @code{INTEGER I} @tab @code{CHARACTER(LEN=1)} @tab F77 and later
2340 See @ref{ICHAR} for a discussion of converting between numerical values
2341 and formatted string representations.
2343 @item @emph{See also}:
2344 @ref{ACHAR}, @ref{IACHAR}, @ref{ICHAR}
2351 @section @code{CHDIR} --- Change working directory
2353 @cindex system, working directory
2356 @item @emph{Description}:
2357 Change current working directory to a specified path.
2359 This intrinsic is provided in both subroutine and function forms; however,
2360 only one form can be used in any given program unit.
2362 @item @emph{Standard}:
2366 Subroutine, function
2368 @item @emph{Syntax}:
2369 @multitable @columnfractions .80
2370 @item @code{CALL CHDIR(NAME [, STATUS])}
2371 @item @code{STATUS = CHDIR(NAME)}
2374 @item @emph{Arguments}:
2375 @multitable @columnfractions .15 .70
2376 @item @var{NAME} @tab The type shall be @code{CHARACTER} of default
2377 kind and shall specify a valid path within the file system.
2378 @item @var{STATUS} @tab (Optional) @code{INTEGER} status flag of the default
2379 kind. Returns 0 on success, and a system specific and nonzero error code
2383 @item @emph{Example}:
2386 CHARACTER(len=255) :: path
2388 WRITE(*,*) TRIM(path)
2391 WRITE(*,*) TRIM(path)
2395 @item @emph{See also}:
2402 @section @code{CHMOD} --- Change access permissions of files
2404 @cindex file system, change access mode
2407 @item @emph{Description}:
2408 @code{CHMOD} changes the permissions of a file. This function invokes
2409 @code{/bin/chmod} and might therefore not work on all platforms.
2411 This intrinsic is provided in both subroutine and function forms; however,
2412 only one form can be used in any given program unit.
2414 @item @emph{Standard}:
2418 Subroutine, function
2420 @item @emph{Syntax}:
2421 @multitable @columnfractions .80
2422 @item @code{CALL CHMOD(NAME, MODE[, STATUS])}
2423 @item @code{STATUS = CHMOD(NAME, MODE)}
2426 @item @emph{Arguments}:
2427 @multitable @columnfractions .15 .70
2429 @item @var{NAME} @tab Scalar @code{CHARACTER} of default kind with the
2430 file name. Trailing blanks are ignored unless the character
2431 @code{achar(0)} is present, then all characters up to and excluding
2432 @code{achar(0)} are used as the file name.
2434 @item @var{MODE} @tab Scalar @code{CHARACTER} of default kind giving the
2435 file permission. @var{MODE} uses the same syntax as the @var{MODE}
2436 argument of @code{/bin/chmod}.
2438 @item @var{STATUS} @tab (optional) scalar @code{INTEGER}, which is
2439 @code{0} on success and nonzero otherwise.
2442 @item @emph{Return value}:
2443 In either syntax, @var{STATUS} is set to @code{0} on success and nonzero
2446 @item @emph{Example}:
2447 @code{CHMOD} as subroutine
2452 call chmod('test.dat','u+x',status)
2453 print *, 'Status: ', status
2454 end program chmod_test
2456 @code{CHMOD} as function:
2461 status = chmod('test.dat','u+x')
2462 print *, 'Status: ', status
2463 end program chmod_test
2471 @section @code{CMPLX} --- Complex conversion function
2473 @cindex complex numbers, conversion to
2474 @cindex conversion, to complex
2477 @item @emph{Description}:
2478 @code{CMPLX(X [, Y [, KIND]])} returns a complex number where @var{X} is converted to
2479 the real component. If @var{Y} is present it is converted to the imaginary
2480 component. If @var{Y} is not present then the imaginary component is set to
2481 0.0. If @var{X} is complex then @var{Y} must not be present.
2483 @item @emph{Standard}:
2484 Fortran 77 and later
2489 @item @emph{Syntax}:
2490 @code{RESULT = CMPLX(X [, Y [, KIND]])}
2492 @item @emph{Arguments}:
2493 @multitable @columnfractions .15 .70
2494 @item @var{X} @tab The type may be @code{INTEGER}, @code{REAL},
2496 @item @var{Y} @tab (Optional; only allowed if @var{X} is not
2497 @code{COMPLEX}.) May be @code{INTEGER} or @code{REAL}.
2498 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
2499 expression indicating the kind parameter of the result.
2502 @item @emph{Return value}:
2503 The return value is of @code{COMPLEX} type, with a kind equal to
2504 @var{KIND} if it is specified. If @var{KIND} is not specified, the
2505 result is of the default @code{COMPLEX} kind, regardless of the kinds of
2506 @var{X} and @var{Y}.
2508 @item @emph{Example}:
2515 print *, z, cmplx(x)
2516 end program test_cmplx
2519 @item @emph{See also}:
2525 @node COMMAND_ARGUMENT_COUNT
2526 @section @code{COMMAND_ARGUMENT_COUNT} --- Get number of command line arguments
2527 @fnindex COMMAND_ARGUMENT_COUNT
2528 @cindex command-line arguments
2529 @cindex command-line arguments, number of
2530 @cindex arguments, to program
2533 @item @emph{Description}:
2534 @code{COMMAND_ARGUMENT_COUNT()} returns the number of arguments passed on the
2535 command line when the containing program was invoked.
2537 @item @emph{Standard}:
2538 Fortran 2003 and later
2543 @item @emph{Syntax}:
2544 @code{RESULT = COMMAND_ARGUMENT_COUNT()}
2546 @item @emph{Arguments}:
2547 @multitable @columnfractions .15 .70
2551 @item @emph{Return value}:
2552 The return value is an @code{INTEGER} of default kind.
2554 @item @emph{Example}:
2556 program test_command_argument_count
2558 count = command_argument_count()
2560 end program test_command_argument_count
2563 @item @emph{See also}:
2564 @ref{GET_COMMAND}, @ref{GET_COMMAND_ARGUMENT}
2570 @section @code{COMPLEX} --- Complex conversion function
2572 @cindex complex numbers, conversion to
2573 @cindex conversion, to complex
2576 @item @emph{Description}:
2577 @code{COMPLEX(X, Y)} returns a complex number where @var{X} is converted
2578 to the real component and @var{Y} is converted to the imaginary
2581 @item @emph{Standard}:
2587 @item @emph{Syntax}:
2588 @code{RESULT = COMPLEX(X, Y)}
2590 @item @emph{Arguments}:
2591 @multitable @columnfractions .15 .70
2592 @item @var{X} @tab The type may be @code{INTEGER} or @code{REAL}.
2593 @item @var{Y} @tab The type may be @code{INTEGER} or @code{REAL}.
2596 @item @emph{Return value}:
2597 If @var{X} and @var{Y} are both of @code{INTEGER} type, then the return
2598 value is of default @code{COMPLEX} type.
2600 If @var{X} and @var{Y} are of @code{REAL} type, or one is of @code{REAL}
2601 type and one is of @code{INTEGER} type, then the return value is of
2602 @code{COMPLEX} type with a kind equal to that of the @code{REAL}
2603 argument with the highest precision.
2605 @item @emph{Example}:
2607 program test_complex
2610 print *, complex(i, x)
2611 end program test_complex
2614 @item @emph{See also}:
2621 @section @code{CONJG} --- Complex conjugate function
2624 @cindex complex conjugate
2627 @item @emph{Description}:
2628 @code{CONJG(Z)} returns the conjugate of @var{Z}. If @var{Z} is @code{(x, y)}
2629 then the result is @code{(x, -y)}
2631 @item @emph{Standard}:
2632 Fortran 77 and later, has overloads that are GNU extensions
2637 @item @emph{Syntax}:
2640 @item @emph{Arguments}:
2641 @multitable @columnfractions .15 .70
2642 @item @var{Z} @tab The type shall be @code{COMPLEX}.
2645 @item @emph{Return value}:
2646 The return value is of type @code{COMPLEX}.
2648 @item @emph{Example}:
2651 complex :: z = (2.0, 3.0)
2652 complex(8) :: dz = (2.71_8, -3.14_8)
2657 end program test_conjg
2660 @item @emph{Specific names}:
2661 @multitable @columnfractions .20 .20 .20 .25
2662 @item Name @tab Argument @tab Return type @tab Standard
2663 @item @code{CONJG(Z)} @tab @code{COMPLEX Z} @tab @code{COMPLEX} @tab GNU extension
2664 @item @code{DCONJG(Z)} @tab @code{COMPLEX(8) Z} @tab @code{COMPLEX(8)} @tab GNU extension
2671 @section @code{COS} --- Cosine function
2677 @cindex trigonometric function, cosine
2681 @item @emph{Description}:
2682 @code{COS(X)} computes the cosine of @var{X}.
2684 @item @emph{Standard}:
2685 Fortran 77 and later, has overloads that are GNU extensions
2690 @item @emph{Syntax}:
2691 @code{RESULT = COS(X)}
2693 @item @emph{Arguments}:
2694 @multitable @columnfractions .15 .70
2695 @item @var{X} @tab The type shall be @code{REAL} or
2699 @item @emph{Return value}:
2700 The return value is of the same type and kind as @var{X}. The real part
2701 of the result is in radians. If @var{X} is of the type @code{REAL},
2702 the return value lies in the range @math{ -1 \leq \cos (x) \leq 1}.
2704 @item @emph{Example}:
2709 end program test_cos
2712 @item @emph{Specific names}:
2713 @multitable @columnfractions .20 .20 .20 .25
2714 @item Name @tab Argument @tab Return type @tab Standard
2715 @item @code{COS(X)} n@tab @code{REAL(4) X} @tab @code{REAL(4)} @tab Fortran 77 and later
2716 @item @code{DCOS(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab Fortran 77 and later
2717 @item @code{CCOS(X)} @tab @code{COMPLEX(4) X} @tab @code{COMPLEX(4)} @tab Fortran 77 and later
2718 @item @code{ZCOS(X)} @tab @code{COMPLEX(8) X} @tab @code{COMPLEX(8)} @tab GNU extension
2719 @item @code{CDCOS(X)} @tab @code{COMPLEX(8) X} @tab @code{COMPLEX(8)} @tab GNU extension
2722 @item @emph{See also}:
2723 Inverse function: @ref{ACOS}
2730 @section @code{COSH} --- Hyperbolic cosine function
2733 @cindex hyperbolic cosine
2734 @cindex hyperbolic function, cosine
2735 @cindex cosine, hyperbolic
2738 @item @emph{Description}:
2739 @code{COSH(X)} computes the hyperbolic cosine of @var{X}.
2741 @item @emph{Standard}:
2742 Fortran 77 and later, for a complex argument Fortran 2008 or later
2747 @item @emph{Syntax}:
2750 @item @emph{Arguments}:
2751 @multitable @columnfractions .15 .70
2752 @item @var{X} @tab The type shall be @code{REAL} or @code{COMPLEX}.
2755 @item @emph{Return value}:
2756 The return value has same type and kind as @var{X}. If @var{X} is
2757 complex, the imaginary part of the result is in radians. If @var{X}
2758 is @code{REAL}, the return value has a lower bound of one,
2759 @math{\cosh (x) \geq 1}.
2761 @item @emph{Example}:
2764 real(8) :: x = 1.0_8
2766 end program test_cosh
2769 @item @emph{Specific names}:
2770 @multitable @columnfractions .20 .20 .20 .25
2771 @item Name @tab Argument @tab Return type @tab Standard
2772 @item @code{COSH(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab Fortran 77 and later
2773 @item @code{DCOSH(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab Fortran 77 and later
2776 @item @emph{See also}:
2777 Inverse function: @ref{ACOSH}
2784 @section @code{COUNT} --- Count function
2786 @cindex array, conditionally count elements
2787 @cindex array, element counting
2788 @cindex array, number of elements
2791 @item @emph{Description}:
2793 Counts the number of @code{.TRUE.} elements in a logical @var{MASK},
2794 or, if the @var{DIM} argument is supplied, counts the number of
2795 elements along each row of the array in the @var{DIM} direction.
2796 If the array has zero size, or all of the elements of @var{MASK} are
2797 @code{.FALSE.}, then the result is @code{0}.
2799 @item @emph{Standard}:
2800 Fortran 95 and later, with @var{KIND} argument Fortran 2003 and later
2803 Transformational function
2805 @item @emph{Syntax}:
2806 @code{RESULT = COUNT(MASK [, DIM, KIND])}
2808 @item @emph{Arguments}:
2809 @multitable @columnfractions .15 .70
2810 @item @var{MASK} @tab The type shall be @code{LOGICAL}.
2811 @item @var{DIM} @tab (Optional) The type shall be @code{INTEGER}.
2812 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
2813 expression indicating the kind parameter of the result.
2816 @item @emph{Return value}:
2817 The return value is of type @code{INTEGER} and of kind @var{KIND}. If
2818 @var{KIND} is absent, the return value is of default integer kind.
2819 If @var{DIM} is present, the result is an array with a rank one less
2820 than the rank of @var{ARRAY}, and a size corresponding to the shape
2821 of @var{ARRAY} with the @var{DIM} dimension removed.
2823 @item @emph{Example}:
2826 integer, dimension(2,3) :: a, b
2827 logical, dimension(2,3) :: mask
2828 a = reshape( (/ 1, 2, 3, 4, 5, 6 /), (/ 2, 3 /))
2829 b = reshape( (/ 0, 7, 3, 4, 5, 8 /), (/ 2, 3 /))
2830 print '(3i3)', a(1,:)
2831 print '(3i3)', a(2,:)
2833 print '(3i3)', b(1,:)
2834 print '(3i3)', b(2,:)
2837 print '(3l3)', mask(1,:)
2838 print '(3l3)', mask(2,:)
2840 print '(3i3)', count(mask)
2842 print '(3i3)', count(mask, 1)
2844 print '(3i3)', count(mask, 2)
2845 end program test_count
2852 @section @code{CPU_TIME} --- CPU elapsed time in seconds
2854 @cindex time, elapsed
2857 @item @emph{Description}:
2858 Returns a @code{REAL} value representing the elapsed CPU time in
2859 seconds. This is useful for testing segments of code to determine
2862 If a time source is available, time will be reported with microsecond
2863 resolution. If no time source is available, @var{TIME} is set to
2866 Note that @var{TIME} may contain a, system dependent, arbitrary offset
2867 and may not start with @code{0.0}. For @code{CPU_TIME}, the absolute
2868 value is meaningless, only differences between subsequent calls to
2869 this subroutine, as shown in the example below, should be used.
2872 @item @emph{Standard}:
2873 Fortran 95 and later
2878 @item @emph{Syntax}:
2879 @code{CALL CPU_TIME(TIME)}
2881 @item @emph{Arguments}:
2882 @multitable @columnfractions .15 .70
2883 @item @var{TIME} @tab The type shall be @code{REAL} with @code{INTENT(OUT)}.
2886 @item @emph{Return value}:
2889 @item @emph{Example}:
2891 program test_cpu_time
2892 real :: start, finish
2893 call cpu_time(start)
2894 ! put code to test here
2895 call cpu_time(finish)
2896 print '("Time = ",f6.3," seconds.")',finish-start
2897 end program test_cpu_time
2900 @item @emph{See also}:
2901 @ref{SYSTEM_CLOCK}, @ref{DATE_AND_TIME}
2907 @section @code{CSHIFT} --- Circular shift elements of an array
2909 @cindex array, shift circularly
2910 @cindex array, permutation
2911 @cindex array, rotate
2914 @item @emph{Description}:
2915 @code{CSHIFT(ARRAY, SHIFT [, DIM])} performs a circular shift on elements of
2916 @var{ARRAY} along the dimension of @var{DIM}. If @var{DIM} is omitted it is
2917 taken to be @code{1}. @var{DIM} is a scalar of type @code{INTEGER} in the
2918 range of @math{1 \leq DIM \leq n)} where @math{n} is the rank of @var{ARRAY}.
2919 If the rank of @var{ARRAY} is one, then all elements of @var{ARRAY} are shifted
2920 by @var{SHIFT} places. If rank is greater than one, then all complete rank one
2921 sections of @var{ARRAY} along the given dimension are shifted. Elements
2922 shifted out one end of each rank one section are shifted back in the other end.
2924 @item @emph{Standard}:
2925 Fortran 95 and later
2928 Transformational function
2930 @item @emph{Syntax}:
2931 @code{RESULT = CSHIFT(ARRAY, SHIFT [, DIM])}
2933 @item @emph{Arguments}:
2934 @multitable @columnfractions .15 .70
2935 @item @var{ARRAY} @tab Shall be an array of any type.
2936 @item @var{SHIFT} @tab The type shall be @code{INTEGER}.
2937 @item @var{DIM} @tab The type shall be @code{INTEGER}.
2940 @item @emph{Return value}:
2941 Returns an array of same type and rank as the @var{ARRAY} argument.
2943 @item @emph{Example}:
2946 integer, dimension(3,3) :: a
2947 a = reshape( (/ 1, 2, 3, 4, 5, 6, 7, 8, 9 /), (/ 3, 3 /))
2948 print '(3i3)', a(1,:)
2949 print '(3i3)', a(2,:)
2950 print '(3i3)', a(3,:)
2951 a = cshift(a, SHIFT=(/1, 2, -1/), DIM=2)
2953 print '(3i3)', a(1,:)
2954 print '(3i3)', a(2,:)
2955 print '(3i3)', a(3,:)
2956 end program test_cshift
2963 @section @code{CTIME} --- Convert a time into a string
2965 @cindex time, conversion to string
2966 @cindex conversion, to string
2969 @item @emph{Description}:
2970 @code{CTIME} converts a system time value, such as returned by
2971 @code{TIME8()}, to a string of the form @samp{Sat Aug 19 18:13:14 1995}.
2973 This intrinsic is provided in both subroutine and function forms; however,
2974 only one form can be used in any given program unit.
2976 @item @emph{Standard}:
2980 Subroutine, function
2982 @item @emph{Syntax}:
2983 @multitable @columnfractions .80
2984 @item @code{CALL CTIME(TIME, RESULT)}.
2985 @item @code{RESULT = CTIME(TIME)}, (not recommended).
2988 @item @emph{Arguments}:
2989 @multitable @columnfractions .15 .70
2990 @item @var{TIME} @tab The type shall be of type @code{INTEGER(KIND=8)}.
2991 @item @var{RESULT} @tab The type shall be of type @code{CHARACTER} and
2995 @item @emph{Return value}:
2996 The converted date and time as a string.
2998 @item @emph{Example}:
3002 character(len=30) :: date
3005 ! Do something, main part of the program
3008 print *, 'Program was started on ', date
3009 end program test_ctime
3012 @item @emph{See Also}:
3013 @ref{GMTIME}, @ref{LTIME}, @ref{TIME}, @ref{TIME8}
3019 @section @code{DATE_AND_TIME} --- Date and time subroutine
3020 @fnindex DATE_AND_TIME
3021 @cindex date, current
3022 @cindex current date
3023 @cindex time, current
3024 @cindex current time
3027 @item @emph{Description}:
3028 @code{DATE_AND_TIME(DATE, TIME, ZONE, VALUES)} gets the corresponding date and
3029 time information from the real-time system clock. @var{DATE} is
3030 @code{INTENT(OUT)} and has form ccyymmdd. @var{TIME} is @code{INTENT(OUT)} and
3031 has form hhmmss.sss. @var{ZONE} is @code{INTENT(OUT)} and has form (+-)hhmm,
3032 representing the difference with respect to Coordinated Universal Time (UTC).
3033 Unavailable time and date parameters return blanks.
3035 @var{VALUES} is @code{INTENT(OUT)} and provides the following:
3037 @multitable @columnfractions .15 .30 .40
3038 @item @tab @code{VALUE(1)}: @tab The year
3039 @item @tab @code{VALUE(2)}: @tab The month
3040 @item @tab @code{VALUE(3)}: @tab The day of the month
3041 @item @tab @code{VALUE(4)}: @tab Time difference with UTC in minutes
3042 @item @tab @code{VALUE(5)}: @tab The hour of the day
3043 @item @tab @code{VALUE(6)}: @tab The minutes of the hour
3044 @item @tab @code{VALUE(7)}: @tab The seconds of the minute
3045 @item @tab @code{VALUE(8)}: @tab The milliseconds of the second
3048 @item @emph{Standard}:
3049 Fortran 95 and later
3054 @item @emph{Syntax}:
3055 @code{CALL DATE_AND_TIME([DATE, TIME, ZONE, VALUES])}
3057 @item @emph{Arguments}:
3058 @multitable @columnfractions .15 .70
3059 @item @var{DATE} @tab (Optional) The type shall be @code{CHARACTER(LEN=8)}
3060 or larger, and of default kind.
3061 @item @var{TIME} @tab (Optional) The type shall be @code{CHARACTER(LEN=10)}
3062 or larger, and of default kind.
3063 @item @var{ZONE} @tab (Optional) The type shall be @code{CHARACTER(LEN=5)}
3064 or larger, and of default kind.
3065 @item @var{VALUES}@tab (Optional) The type shall be @code{INTEGER(8)}.
3068 @item @emph{Return value}:
3071 @item @emph{Example}:
3073 program test_time_and_date
3074 character(8) :: date
3075 character(10) :: time
3076 character(5) :: zone
3077 integer,dimension(8) :: values
3078 ! using keyword arguments
3079 call date_and_time(date,time,zone,values)
3080 call date_and_time(DATE=date,ZONE=zone)
3081 call date_and_time(TIME=time)
3082 call date_and_time(VALUES=values)
3083 print '(a,2x,a,2x,a)', date, time, zone
3084 print '(8i5))', values
3085 end program test_time_and_date
3088 @item @emph{See also}:
3089 @ref{CPU_TIME}, @ref{SYSTEM_CLOCK}
3095 @section @code{DBLE} --- Double conversion function
3097 @cindex conversion, to real
3100 @item @emph{Description}:
3101 @code{DBLE(A)} Converts @var{A} to double precision real type.
3103 @item @emph{Standard}:
3104 Fortran 77 and later
3109 @item @emph{Syntax}:
3110 @code{RESULT = DBLE(A)}
3112 @item @emph{Arguments}:
3113 @multitable @columnfractions .15 .70
3114 @item @var{A} @tab The type shall be @code{INTEGER}, @code{REAL},
3118 @item @emph{Return value}:
3119 The return value is of type double precision real.
3121 @item @emph{Example}:
3126 complex :: z = (2.3,1.14)
3127 print *, dble(x), dble(i), dble(z)
3128 end program test_dble
3131 @item @emph{See also}:
3138 @section @code{DCMPLX} --- Double complex conversion function
3140 @cindex complex numbers, conversion to
3141 @cindex conversion, to complex
3144 @item @emph{Description}:
3145 @code{DCMPLX(X [,Y])} returns a double complex number where @var{X} is
3146 converted to the real component. If @var{Y} is present it is converted to the
3147 imaginary component. If @var{Y} is not present then the imaginary component is
3148 set to 0.0. If @var{X} is complex then @var{Y} must not be present.
3150 @item @emph{Standard}:
3156 @item @emph{Syntax}:
3157 @code{RESULT = DCMPLX(X [, Y])}
3159 @item @emph{Arguments}:
3160 @multitable @columnfractions .15 .70
3161 @item @var{X} @tab The type may be @code{INTEGER}, @code{REAL},
3163 @item @var{Y} @tab (Optional if @var{X} is not @code{COMPLEX}.) May be
3164 @code{INTEGER} or @code{REAL}.
3167 @item @emph{Return value}:
3168 The return value is of type @code{COMPLEX(8)}
3170 @item @emph{Example}:
3180 print *, dcmplx(x,i)
3181 end program test_dcmplx
3187 @section @code{DIGITS} --- Significant binary digits function
3189 @cindex model representation, significant digits
3192 @item @emph{Description}:
3193 @code{DIGITS(X)} returns the number of significant binary digits of the internal
3194 model representation of @var{X}. For example, on a system using a 32-bit
3195 floating point representation, a default real number would likely return 24.
3197 @item @emph{Standard}:
3198 Fortran 95 and later
3203 @item @emph{Syntax}:
3204 @code{RESULT = DIGITS(X)}
3206 @item @emph{Arguments}:
3207 @multitable @columnfractions .15 .70
3208 @item @var{X} @tab The type may be @code{INTEGER} or @code{REAL}.
3211 @item @emph{Return value}:
3212 The return value is of type @code{INTEGER}.
3214 @item @emph{Example}:
3217 integer :: i = 12345
3223 end program test_digits
3230 @section @code{DIM} --- Positive difference
3234 @cindex positive difference
3237 @item @emph{Description}:
3238 @code{DIM(X,Y)} returns the difference @code{X-Y} if the result is positive;
3239 otherwise returns zero.
3241 @item @emph{Standard}:
3242 Fortran 77 and later
3247 @item @emph{Syntax}:
3248 @code{RESULT = DIM(X, Y)}
3250 @item @emph{Arguments}:
3251 @multitable @columnfractions .15 .70
3252 @item @var{X} @tab The type shall be @code{INTEGER} or @code{REAL}
3253 @item @var{Y} @tab The type shall be the same type and kind as @var{X}.
3256 @item @emph{Return value}:
3257 The return value is of type @code{INTEGER} or @code{REAL}.
3259 @item @emph{Example}:
3265 x = dim(4.345_8, 2.111_8)
3268 end program test_dim
3271 @item @emph{Specific names}:
3272 @multitable @columnfractions .20 .20 .20 .25
3273 @item Name @tab Argument @tab Return type @tab Standard
3274 @item @code{DIM(X,Y)} @tab @code{REAL(4) X, Y} @tab @code{REAL(4)} @tab Fortran 77 and later
3275 @item @code{IDIM(X,Y)} @tab @code{INTEGER(4) X, Y} @tab @code{INTEGER(4)} @tab Fortran 77 and later
3276 @item @code{DDIM(X,Y)} @tab @code{REAL(8) X, Y} @tab @code{REAL(8)} @tab Fortran 77 and later
3283 @section @code{DOT_PRODUCT} --- Dot product function
3284 @fnindex DOT_PRODUCT
3286 @cindex vector product
3287 @cindex product, vector
3290 @item @emph{Description}:
3291 @code{DOT_PRODUCT(VECTOR_A, VECTOR_B)} computes the dot product multiplication
3292 of two vectors @var{VECTOR_A} and @var{VECTOR_B}. The two vectors may be
3293 either numeric or logical and must be arrays of rank one and of equal size. If
3294 the vectors are @code{INTEGER} or @code{REAL}, the result is
3295 @code{SUM(VECTOR_A*VECTOR_B)}. If the vectors are @code{COMPLEX}, the result
3296 is @code{SUM(CONJG(VECTOR_A)*VECTOR_B)}. If the vectors are @code{LOGICAL},
3297 the result is @code{ANY(VECTOR_A .AND. VECTOR_B)}.
3299 @item @emph{Standard}:
3300 Fortran 95 and later
3303 Transformational function
3305 @item @emph{Syntax}:
3306 @code{RESULT = DOT_PRODUCT(VECTOR_A, VECTOR_B)}
3308 @item @emph{Arguments}:
3309 @multitable @columnfractions .15 .70
3310 @item @var{VECTOR_A} @tab The type shall be numeric or @code{LOGICAL}, rank 1.
3311 @item @var{VECTOR_B} @tab The type shall be numeric if @var{VECTOR_A} is of numeric type or @code{LOGICAL} if @var{VECTOR_A} is of type @code{LOGICAL}. @var{VECTOR_B} shall be a rank-one array.
3314 @item @emph{Return value}:
3315 If the arguments are numeric, the return value is a scalar of numeric type,
3316 @code{INTEGER}, @code{REAL}, or @code{COMPLEX}. If the arguments are
3317 @code{LOGICAL}, the return value is @code{.TRUE.} or @code{.FALSE.}.
3319 @item @emph{Example}:
3321 program test_dot_prod
3322 integer, dimension(3) :: a, b
3329 print *, dot_product(a,b)
3330 end program test_dot_prod
3337 @section @code{DPROD} --- Double product function
3339 @cindex product, double-precision
3342 @item @emph{Description}:
3343 @code{DPROD(X,Y)} returns the product @code{X*Y}.
3345 @item @emph{Standard}:
3346 Fortran 77 and later
3351 @item @emph{Syntax}:
3352 @code{RESULT = DPROD(X, Y)}
3354 @item @emph{Arguments}:
3355 @multitable @columnfractions .15 .70
3356 @item @var{X} @tab The type shall be @code{REAL}.
3357 @item @var{Y} @tab The type shall be @code{REAL}.
3360 @item @emph{Return value}:
3361 The return value is of type @code{REAL(8)}.
3363 @item @emph{Example}:
3371 end program test_dprod
3374 @item @emph{Specific names}:
3375 @multitable @columnfractions .20 .20 .20 .25
3376 @item Name @tab Argument @tab Return type @tab Standard
3377 @item @code{DPROD(X,Y)} @tab @code{REAL(4) X, Y} @tab @code{REAL(4)} @tab Fortran 77 and later
3384 @section @code{DREAL} --- Double real part function
3386 @cindex complex numbers, real part
3389 @item @emph{Description}:
3390 @code{DREAL(Z)} returns the real part of complex variable @var{Z}.
3392 @item @emph{Standard}:
3398 @item @emph{Syntax}:
3399 @code{RESULT = DREAL(A)}
3401 @item @emph{Arguments}:
3402 @multitable @columnfractions .15 .70
3403 @item @var{A} @tab The type shall be @code{COMPLEX(8)}.
3406 @item @emph{Return value}:
3407 The return value is of type @code{REAL(8)}.
3409 @item @emph{Example}:
3412 complex(8) :: z = (1.3_8,7.2_8)
3414 end program test_dreal
3417 @item @emph{See also}:
3425 @section @code{DTIME} --- Execution time subroutine (or function)
3427 @cindex time, elapsed
3428 @cindex elapsed time
3431 @item @emph{Description}:
3432 @code{DTIME(VALUES, TIME)} initially returns the number of seconds of runtime
3433 since the start of the process's execution in @var{TIME}. @var{VALUES}
3434 returns the user and system components of this time in @code{VALUES(1)} and
3435 @code{VALUES(2)} respectively. @var{TIME} is equal to @code{VALUES(1) +
3438 Subsequent invocations of @code{DTIME} return values accumulated since the
3439 previous invocation.
3441 On some systems, the underlying timings are represented using types with
3442 sufficiently small limits that overflows (wrap around) are possible, such as
3443 32-bit types. Therefore, the values returned by this intrinsic might be, or
3444 become, negative, or numerically less than previous values, during a single
3445 run of the compiled program.
3447 Please note, that this implementation is thread safe if used within OpenMP
3448 directives, i.e., its state will be consistent while called from multiple
3449 threads. However, if @code{DTIME} is called from multiple threads, the result
3450 is still the time since the last invocation. This may not give the intended
3451 results. If possible, use @code{CPU_TIME} instead.
3453 This intrinsic is provided in both subroutine and function forms; however,
3454 only one form can be used in any given program unit.
3456 @var{VALUES} and @var{TIME} are @code{INTENT(OUT)} and provide the following:
3458 @multitable @columnfractions .15 .30 .40
3459 @item @tab @code{VALUES(1)}: @tab User time in seconds.
3460 @item @tab @code{VALUES(2)}: @tab System time in seconds.
3461 @item @tab @code{TIME}: @tab Run time since start in seconds.
3464 @item @emph{Standard}:
3468 Subroutine, function
3470 @item @emph{Syntax}:
3471 @multitable @columnfractions .80
3472 @item @code{CALL DTIME(VALUES, TIME)}.
3473 @item @code{TIME = DTIME(VALUES)}, (not recommended).
3476 @item @emph{Arguments}:
3477 @multitable @columnfractions .15 .70
3478 @item @var{VALUES}@tab The type shall be @code{REAL(4), DIMENSION(2)}.
3479 @item @var{TIME}@tab The type shall be @code{REAL(4)}.
3482 @item @emph{Return value}:
3483 Elapsed time in seconds since the last invocation or since the start of program
3484 execution if not called before.
3486 @item @emph{Example}:
3490 real, dimension(2) :: tarray
3492 call dtime(tarray, result)
3496 do i=1,100000000 ! Just a delay
3499 call dtime(tarray, result)
3503 end program test_dtime
3506 @item @emph{See also}:
3514 @section @code{EOSHIFT} --- End-off shift elements of an array
3516 @cindex array, shift
3519 @item @emph{Description}:
3520 @code{EOSHIFT(ARRAY, SHIFT[, BOUNDARY, DIM])} performs an end-off shift on
3521 elements of @var{ARRAY} along the dimension of @var{DIM}. If @var{DIM} is
3522 omitted it is taken to be @code{1}. @var{DIM} is a scalar of type
3523 @code{INTEGER} in the range of @math{1 \leq DIM \leq n)} where @math{n} is the
3524 rank of @var{ARRAY}. If the rank of @var{ARRAY} is one, then all elements of
3525 @var{ARRAY} are shifted by @var{SHIFT} places. If rank is greater than one,
3526 then all complete rank one sections of @var{ARRAY} along the given dimension are
3527 shifted. Elements shifted out one end of each rank one section are dropped. If
3528 @var{BOUNDARY} is present then the corresponding value of from @var{BOUNDARY}
3529 is copied back in the other end. If @var{BOUNDARY} is not present then the
3530 following are copied in depending on the type of @var{ARRAY}.
3532 @multitable @columnfractions .15 .80
3533 @item @emph{Array Type} @tab @emph{Boundary Value}
3534 @item Numeric @tab 0 of the type and kind of @var{ARRAY}.
3535 @item Logical @tab @code{.FALSE.}.
3536 @item Character(@var{len}) @tab @var{len} blanks.
3539 @item @emph{Standard}:
3540 Fortran 95 and later
3543 Transformational function
3545 @item @emph{Syntax}:
3546 @code{RESULT = EOSHIFT(ARRAY, SHIFT [, BOUNDARY, DIM])}
3548 @item @emph{Arguments}:
3549 @multitable @columnfractions .15 .70
3550 @item @var{ARRAY} @tab May be any type, not scalar.
3551 @item @var{SHIFT} @tab The type shall be @code{INTEGER}.
3552 @item @var{BOUNDARY} @tab Same type as @var{ARRAY}.
3553 @item @var{DIM} @tab The type shall be @code{INTEGER}.
3556 @item @emph{Return value}:
3557 Returns an array of same type and rank as the @var{ARRAY} argument.
3559 @item @emph{Example}:
3561 program test_eoshift
3562 integer, dimension(3,3) :: a
3563 a = reshape( (/ 1, 2, 3, 4, 5, 6, 7, 8, 9 /), (/ 3, 3 /))
3564 print '(3i3)', a(1,:)
3565 print '(3i3)', a(2,:)
3566 print '(3i3)', a(3,:)
3567 a = EOSHIFT(a, SHIFT=(/1, 2, 1/), BOUNDARY=-5, DIM=2)
3569 print '(3i3)', a(1,:)
3570 print '(3i3)', a(2,:)
3571 print '(3i3)', a(3,:)
3572 end program test_eoshift
3579 @section @code{EPSILON} --- Epsilon function
3581 @cindex model representation, epsilon
3584 @item @emph{Description}:
3585 @code{EPSILON(X)} returns the smallest number @var{E} of the same kind
3586 as @var{X} such that @math{1 + E > 1}.
3588 @item @emph{Standard}:
3589 Fortran 95 and later
3594 @item @emph{Syntax}:
3595 @code{RESULT = EPSILON(X)}
3597 @item @emph{Arguments}:
3598 @multitable @columnfractions .15 .70
3599 @item @var{X} @tab The type shall be @code{REAL}.
3602 @item @emph{Return value}:
3603 The return value is of same type as the argument.
3605 @item @emph{Example}:
3607 program test_epsilon
3612 end program test_epsilon
3619 @section @code{ERF} --- Error function
3621 @cindex error function
3624 @item @emph{Description}:
3625 @code{ERF(X)} computes the error function of @var{X}.
3627 @item @emph{Standard}:
3628 Fortran 2008 and later
3633 @item @emph{Syntax}:
3634 @code{RESULT = ERF(X)}
3636 @item @emph{Arguments}:
3637 @multitable @columnfractions .15 .70
3638 @item @var{X} @tab The type shall be @code{REAL}.
3641 @item @emph{Return value}:
3642 The return value is of type @code{REAL}, of the same kind as
3643 @var{X} and lies in the range @math{-1 \leq erf (x) \leq 1 }.
3645 @item @emph{Example}:
3648 real(8) :: x = 0.17_8
3650 end program test_erf
3653 @item @emph{Specific names}:
3654 @multitable @columnfractions .20 .20 .20 .25
3655 @item Name @tab Argument @tab Return type @tab Standard
3656 @item @code{DERF(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU extension
3663 @section @code{ERFC} --- Error function
3665 @cindex error function, complementary
3668 @item @emph{Description}:
3669 @code{ERFC(X)} computes the complementary error function of @var{X}.
3671 @item @emph{Standard}:
3672 Fortran 2008 and later
3677 @item @emph{Syntax}:
3678 @code{RESULT = ERFC(X)}
3680 @item @emph{Arguments}:
3681 @multitable @columnfractions .15 .70
3682 @item @var{X} @tab The type shall be @code{REAL}.
3685 @item @emph{Return value}:
3686 The return value is of type @code{REAL} and of the same kind as @var{X}.
3687 It lies in the range @math{ 0 \leq erfc (x) \leq 2 }.
3689 @item @emph{Example}:
3692 real(8) :: x = 0.17_8
3694 end program test_erfc
3697 @item @emph{Specific names}:
3698 @multitable @columnfractions .20 .20 .20 .25
3699 @item Name @tab Argument @tab Return type @tab Standard
3700 @item @code{DERFC(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU extension
3707 @section @code{ERFC_SCALED} --- Error function
3708 @fnindex ERFC_SCALED
3709 @cindex error function, complementary, exponentially-scaled
3712 @item @emph{Description}:
3713 @code{ERFC_SCALED(X)} computes the exponentially-scaled complementary
3714 error function of @var{X}.
3716 @item @emph{Standard}:
3717 Fortran 2008 and later
3722 @item @emph{Syntax}:
3723 @code{RESULT = ERFC_SCALED(X)}
3725 @item @emph{Arguments}:
3726 @multitable @columnfractions .15 .70
3727 @item @var{X} @tab The type shall be @code{REAL}.
3730 @item @emph{Return value}:
3731 The return value is of type @code{REAL} and of the same kind as @var{X}.
3733 @item @emph{Example}:
3735 program test_erfc_scaled
3736 real(8) :: x = 0.17_8
3738 end program test_erfc_scaled
3745 @section @code{ETIME} --- Execution time subroutine (or function)
3747 @cindex time, elapsed
3750 @item @emph{Description}:
3751 @code{ETIME(VALUES, TIME)} returns the number of seconds of runtime
3752 since the start of the process's execution in @var{TIME}. @var{VALUES}
3753 returns the user and system components of this time in @code{VALUES(1)} and
3754 @code{VALUES(2)} respectively. @var{TIME} is equal to @code{VALUES(1) + VALUES(2)}.
3756 On some systems, the underlying timings are represented using types with
3757 sufficiently small limits that overflows (wrap around) are possible, such as
3758 32-bit types. Therefore, the values returned by this intrinsic might be, or
3759 become, negative, or numerically less than previous values, during a single
3760 run of the compiled program.
3762 This intrinsic is provided in both subroutine and function forms; however,
3763 only one form can be used in any given program unit.
3765 @var{VALUES} and @var{TIME} are @code{INTENT(OUT)} and provide the following:
3767 @multitable @columnfractions .15 .30 .60
3768 @item @tab @code{VALUES(1)}: @tab User time in seconds.
3769 @item @tab @code{VALUES(2)}: @tab System time in seconds.
3770 @item @tab @code{TIME}: @tab Run time since start in seconds.
3773 @item @emph{Standard}:
3777 Subroutine, function
3779 @item @emph{Syntax}:
3780 @multitable @columnfractions .80
3781 @item @code{CALL ETIME(VALUES, TIME)}.
3782 @item @code{TIME = ETIME(VALUES)}, (not recommended).
3785 @item @emph{Arguments}:
3786 @multitable @columnfractions .15 .70
3787 @item @var{VALUES}@tab The type shall be @code{REAL(4), DIMENSION(2)}.
3788 @item @var{TIME}@tab The type shall be @code{REAL(4)}.
3791 @item @emph{Return value}:
3792 Elapsed time in seconds since the start of program execution.
3794 @item @emph{Example}:
3798 real, dimension(2) :: tarray
3800 call ETIME(tarray, result)
3804 do i=1,100000000 ! Just a delay
3807 call ETIME(tarray, result)
3811 end program test_etime
3814 @item @emph{See also}:
3821 @node EXECUTE_COMMAND_LINE
3822 @section @code{EXECUTE_COMMAND_LINE} --- Execute a shell command
3823 @fnindex EXECUTE_COMMAND_LINE
3824 @cindex system, system call
3825 @cindex command line
3828 @item @emph{Description}:
3829 @code{EXECUTE_COMMAND_LINE} runs a shell command, synchronously or
3832 The @code{COMMAND} argument is passed to the shell and executed, using
3833 the C library's @code{system()} call. (The shell is @code{sh} on Unix
3834 systems, and @code{cmd.exe} on Windows.) If @code{WAIT} is present and
3835 has the value false, the execution of the command is asynchronous if the
3836 system supports it; otherwise, the command is executed synchronously.
3838 The three last arguments allow the user to get status information. After
3839 synchronous execution, @code{EXITSTAT} contains the integer exit code of
3840 the command, as returned by @code{system}. @code{CMDSTAT} is set to zero
3841 if the command line was executed (whatever its exit status was).
3842 @code{CMDMSG} is assigned an error message if an error has occurred.
3845 @item @emph{Standard}:
3846 Fortran 2008 and later
3851 @item @emph{Syntax}:
3852 @code{CALL EXECUTE_COMMAND_LINE(COMMAND [, WAIT, EXITSTAT, CMDSTAT, CMDMSG ])}
3854 @item @emph{Arguments}:
3855 @multitable @columnfractions .15 .70
3856 @item @var{COMMAND} @tab Shall be a default @code{CHARACTER} scalar.
3857 @item @var{WAIT} @tab (Optional) Shall be a default @code{LOGICAL} scalar.
3858 @item @var{EXITSTAT} @tab (Optional) Shall be an @code{INTEGER} of the
3860 @item @var{CMDSTAT} @tab (Optional) Shall be an @code{INTEGER} of the
3862 @item @var{CMDMSG} @tab (Optional) Shall be an @code{CHARACTER} scalar of the
3866 @item @emph{Example}:
3871 call execute_command_line ("external_prog.exe", exitstat=i)
3872 print *, "Exit status of external_prog.exe was ", i
3874 call execute_command_line ("reindex_files.exe", wait=.false.)
3875 print *, "Now reindexing files in the background"
3877 end program test_exec
3883 Because this intrinsic is implemented in terms of the @code{system()}
3884 function call, its behavior with respect to signalling is processor
3885 dependent. In particular, on POSIX-compliant systems, the SIGINT and
3886 SIGQUIT signals will be ignored, and the SIGCHLD will be blocked. As
3887 such, if the parent process is terminated, the child process might not be
3888 terminated alongside.
3891 @item @emph{See also}:
3898 @section @code{EXIT} --- Exit the program with status.
3900 @cindex program termination
3901 @cindex terminate program
3904 @item @emph{Description}:
3905 @code{EXIT} causes immediate termination of the program with status. If status
3906 is omitted it returns the canonical @emph{success} for the system. All Fortran
3907 I/O units are closed.
3909 @item @emph{Standard}:
3915 @item @emph{Syntax}:
3916 @code{CALL EXIT([STATUS])}
3918 @item @emph{Arguments}:
3919 @multitable @columnfractions .15 .70
3920 @item @var{STATUS} @tab Shall be an @code{INTEGER} of the default kind.
3923 @item @emph{Return value}:
3924 @code{STATUS} is passed to the parent process on exit.
3926 @item @emph{Example}:
3929 integer :: STATUS = 0
3930 print *, 'This program is going to exit.'
3932 end program test_exit
3935 @item @emph{See also}:
3936 @ref{ABORT}, @ref{KILL}
3942 @section @code{EXP} --- Exponential function
3948 @cindex exponential function
3949 @cindex logarithmic function, inverse
3952 @item @emph{Description}:
3953 @code{EXP(X)} computes the base @math{e} exponential of @var{X}.
3955 @item @emph{Standard}:
3956 Fortran 77 and later, has overloads that are GNU extensions
3961 @item @emph{Syntax}:
3962 @code{RESULT = EXP(X)}
3964 @item @emph{Arguments}:
3965 @multitable @columnfractions .15 .70
3966 @item @var{X} @tab The type shall be @code{REAL} or
3970 @item @emph{Return value}:
3971 The return value has same type and kind as @var{X}.
3973 @item @emph{Example}:
3978 end program test_exp
3981 @item @emph{Specific names}:
3982 @multitable @columnfractions .20 .20 .20 .25
3983 @item Name @tab Argument @tab Return type @tab Standard
3984 @item @code{EXP(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab Fortran 77 and later
3985 @item @code{DEXP(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab Fortran 77 and later
3986 @item @code{CEXP(X)} @tab @code{COMPLEX(4) X} @tab @code{COMPLEX(4)} @tab Fortran 77 and later
3987 @item @code{ZEXP(X)} @tab @code{COMPLEX(8) X} @tab @code{COMPLEX(8)} @tab GNU extension
3988 @item @code{CDEXP(X)} @tab @code{COMPLEX(8) X} @tab @code{COMPLEX(8)} @tab GNU extension
3995 @section @code{EXPONENT} --- Exponent function
3997 @cindex real number, exponent
3998 @cindex floating point, exponent
4001 @item @emph{Description}:
4002 @code{EXPONENT(X)} returns the value of the exponent part of @var{X}. If @var{X}
4003 is zero the value returned is zero.
4005 @item @emph{Standard}:
4006 Fortran 95 and later
4011 @item @emph{Syntax}:
4012 @code{RESULT = EXPONENT(X)}
4014 @item @emph{Arguments}:
4015 @multitable @columnfractions .15 .70
4016 @item @var{X} @tab The type shall be @code{REAL}.
4019 @item @emph{Return value}:
4020 The return value is of type default @code{INTEGER}.
4022 @item @emph{Example}:
4024 program test_exponent
4029 print *, exponent(0.0)
4030 end program test_exponent
4036 @node EXTENDS_TYPE_OF
4037 @section @code{EXTENDS_TYPE_OF} --- Query dynamic type for extension
4038 @fnindex EXTENDS_TYPE_OF
4041 @item @emph{Description}:
4042 Query dynamic type for extension.
4044 @item @emph{Standard}:
4045 Fortran 2003 and later
4050 @item @emph{Syntax}:
4051 @code{RESULT = EXTENDS_TYPE_OF(A, MOLD)}
4053 @item @emph{Arguments}:
4054 @multitable @columnfractions .15 .70
4055 @item @var{A} @tab Shall be an object of extensible declared type or
4056 unlimited polymorphic.
4057 @item @var{MOLD} @tab Shall be an object of extensible declared type or
4058 unlimited polymorphic.
4061 @item @emph{Return value}:
4062 The return value is a scalar of type default logical. It is true if and only if
4063 the dynamic type of A is an extension type of the dynamic type of MOLD.
4066 @item @emph{See also}:
4073 @section @code{FDATE} --- Get the current time as a string
4075 @cindex time, current
4076 @cindex current time
4077 @cindex date, current
4078 @cindex current date
4081 @item @emph{Description}:
4082 @code{FDATE(DATE)} returns the current date (using the same format as
4083 @code{CTIME}) in @var{DATE}. It is equivalent to @code{CALL CTIME(DATE,
4086 This intrinsic is provided in both subroutine and function forms; however,
4087 only one form can be used in any given program unit.
4089 @var{DATE} is an @code{INTENT(OUT)} @code{CHARACTER} variable of the
4092 @item @emph{Standard}:
4096 Subroutine, function
4098 @item @emph{Syntax}:
4099 @multitable @columnfractions .80
4100 @item @code{CALL FDATE(DATE)}.
4101 @item @code{DATE = FDATE()}, (not recommended).
4104 @item @emph{Arguments}:
4105 @multitable @columnfractions .15 .70
4106 @item @var{DATE}@tab The type shall be of type @code{CHARACTER} of the
4110 @item @emph{Return value}:
4111 The current date as a string.
4113 @item @emph{Example}:
4117 character(len=30) :: date
4119 print *, 'Program started on ', date
4120 do i = 1, 100000000 ! Just a delay
4124 print *, 'Program ended on ', date
4125 end program test_fdate
4132 @section @code{FGET} --- Read a single character in stream mode from stdin
4134 @cindex read character, stream mode
4135 @cindex stream mode, read character
4136 @cindex file operation, read character
4139 @item @emph{Description}:
4140 Read a single character in stream mode from stdin by bypassing normal
4141 formatted output. Stream I/O should not be mixed with normal record-oriented
4142 (formatted or unformatted) I/O on the same unit; the results are unpredictable.
4144 This intrinsic is provided in both subroutine and function forms; however,
4145 only one form can be used in any given program unit.
4147 Note that the @code{FGET} intrinsic is provided for backwards compatibility with
4148 @command{g77}. GNU Fortran provides the Fortran 2003 Stream facility.
4149 Programmers should consider the use of new stream IO feature in new code
4150 for future portability. See also @ref{Fortran 2003 status}.
4152 @item @emph{Standard}:
4156 Subroutine, function
4158 @item @emph{Syntax}:
4159 @code{CALL FGET(C [, STATUS])}
4161 @item @emph{Arguments}:
4162 @multitable @columnfractions .15 .70
4163 @item @var{C} @tab The type shall be @code{CHARACTER} and of default
4165 @item @var{STATUS} @tab (Optional) status flag of type @code{INTEGER}.
4166 Returns 0 on success, -1 on end-of-file, and a system specific positive
4167 error code otherwise.
4170 @item @emph{Example}:
4173 INTEGER, PARAMETER :: strlen = 100
4174 INTEGER :: status, i = 1
4175 CHARACTER(len=strlen) :: str = ""
4177 WRITE (*,*) 'Enter text:'
4179 CALL fget(str(i:i), status)
4180 if (status /= 0 .OR. i > strlen) exit
4183 WRITE (*,*) TRIM(str)
4187 @item @emph{See also}:
4188 @ref{FGETC}, @ref{FPUT}, @ref{FPUTC}
4194 @section @code{FGETC} --- Read a single character in stream mode
4196 @cindex read character, stream mode
4197 @cindex stream mode, read character
4198 @cindex file operation, read character
4201 @item @emph{Description}:
4202 Read a single character in stream mode by bypassing normal formatted output.
4203 Stream I/O should not be mixed with normal record-oriented (formatted or
4204 unformatted) I/O on the same unit; the results are unpredictable.
4206 This intrinsic is provided in both subroutine and function forms; however,
4207 only one form can be used in any given program unit.
4209 Note that the @code{FGET} intrinsic is provided for backwards compatibility
4210 with @command{g77}. GNU Fortran provides the Fortran 2003 Stream facility.
4211 Programmers should consider the use of new stream IO feature in new code
4212 for future portability. See also @ref{Fortran 2003 status}.
4214 @item @emph{Standard}:
4218 Subroutine, function
4220 @item @emph{Syntax}:
4221 @code{CALL FGETC(UNIT, C [, STATUS])}
4223 @item @emph{Arguments}:
4224 @multitable @columnfractions .15 .70
4225 @item @var{UNIT} @tab The type shall be @code{INTEGER}.
4226 @item @var{C} @tab The type shall be @code{CHARACTER} and of default
4228 @item @var{STATUS} @tab (Optional) status flag of type @code{INTEGER}.
4229 Returns 0 on success, -1 on end-of-file and a system specific positive
4230 error code otherwise.
4233 @item @emph{Example}:
4236 INTEGER :: fd = 42, status
4239 OPEN(UNIT=fd, FILE="/etc/passwd", ACTION="READ", STATUS = "OLD")
4241 CALL fgetc(fd, c, status)
4242 IF (status /= 0) EXIT
4249 @item @emph{See also}:
4250 @ref{FGET}, @ref{FPUT}, @ref{FPUTC}
4256 @section @code{FLOOR} --- Integer floor function
4259 @cindex rounding, floor
4262 @item @emph{Description}:
4263 @code{FLOOR(A)} returns the greatest integer less than or equal to @var{X}.
4265 @item @emph{Standard}:
4266 Fortran 95 and later
4271 @item @emph{Syntax}:
4272 @code{RESULT = FLOOR(A [, KIND])}
4274 @item @emph{Arguments}:
4275 @multitable @columnfractions .15 .70
4276 @item @var{A} @tab The type shall be @code{REAL}.
4277 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
4278 expression indicating the kind parameter of the result.
4281 @item @emph{Return value}:
4282 The return value is of type @code{INTEGER(KIND)} if @var{KIND} is present
4283 and of default-kind @code{INTEGER} otherwise.
4285 @item @emph{Example}:
4290 print *, floor(x) ! returns 63
4291 print *, floor(y) ! returns -64
4292 end program test_floor
4295 @item @emph{See also}:
4296 @ref{CEILING}, @ref{NINT}
4303 @section @code{FLUSH} --- Flush I/O unit(s)
4305 @cindex file operation, flush
4308 @item @emph{Description}:
4309 Flushes Fortran unit(s) currently open for output. Without the optional
4310 argument, all units are flushed, otherwise just the unit specified.
4312 @item @emph{Standard}:
4318 @item @emph{Syntax}:
4319 @code{CALL FLUSH(UNIT)}
4321 @item @emph{Arguments}:
4322 @multitable @columnfractions .15 .70
4323 @item @var{UNIT} @tab (Optional) The type shall be @code{INTEGER}.
4327 Beginning with the Fortran 2003 standard, there is a @code{FLUSH}
4328 statement that should be preferred over the @code{FLUSH} intrinsic.
4330 The @code{FLUSH} intrinsic and the Fortran 2003 @code{FLUSH} statement
4331 have identical effect: they flush the runtime library's I/O buffer so
4332 that the data becomes visible to other processes. This does not guarantee
4333 that the data is committed to disk.
4335 On POSIX systems, you can request that all data is transferred to the
4336 storage device by calling the @code{fsync} function, with the POSIX file
4337 descriptor of the I/O unit as argument (retrieved with GNU intrinsic
4338 @code{FNUM}). The following example shows how:
4341 ! Declare the interface for POSIX fsync function
4343 function fsync (fd) bind(c,name="fsync")
4344 use iso_c_binding, only: c_int
4345 integer(c_int), value :: fd
4346 integer(c_int) :: fsync
4350 ! Variable declaration
4354 open (10,file="foo")
4357 ! Perform I/O on unit 10
4362 ret = fsync(fnum(10))
4364 ! Handle possible error
4365 if (ret /= 0) stop "Error calling FSYNC"
4373 @section @code{FNUM} --- File number function
4375 @cindex file operation, file number
4378 @item @emph{Description}:
4379 @code{FNUM(UNIT)} returns the POSIX file descriptor number corresponding to the
4380 open Fortran I/O unit @code{UNIT}.
4382 @item @emph{Standard}:
4388 @item @emph{Syntax}:
4389 @code{RESULT = FNUM(UNIT)}
4391 @item @emph{Arguments}:
4392 @multitable @columnfractions .15 .70
4393 @item @var{UNIT} @tab The type shall be @code{INTEGER}.
4396 @item @emph{Return value}:
4397 The return value is of type @code{INTEGER}
4399 @item @emph{Example}:
4403 open (unit=10, status = "scratch")
4407 end program test_fnum
4414 @section @code{FPUT} --- Write a single character in stream mode to stdout
4416 @cindex write character, stream mode
4417 @cindex stream mode, write character
4418 @cindex file operation, write character
4421 @item @emph{Description}:
4422 Write a single character in stream mode to stdout by bypassing normal
4423 formatted output. Stream I/O should not be mixed with normal record-oriented
4424 (formatted or unformatted) I/O on the same unit; the results are unpredictable.
4426 This intrinsic is provided in both subroutine and function forms; however,
4427 only one form can be used in any given program unit.
4429 Note that the @code{FGET} intrinsic is provided for backwards compatibility with
4430 @command{g77}. GNU Fortran provides the Fortran 2003 Stream facility.
4431 Programmers should consider the use of new stream IO feature in new code
4432 for future portability. See also @ref{Fortran 2003 status}.
4434 @item @emph{Standard}:
4438 Subroutine, function
4440 @item @emph{Syntax}:
4441 @code{CALL FPUT(C [, STATUS])}
4443 @item @emph{Arguments}:
4444 @multitable @columnfractions .15 .70
4445 @item @var{C} @tab The type shall be @code{CHARACTER} and of default
4447 @item @var{STATUS} @tab (Optional) status flag of type @code{INTEGER}.
4448 Returns 0 on success, -1 on end-of-file and a system specific positive
4449 error code otherwise.
4452 @item @emph{Example}:
4455 CHARACTER(len=10) :: str = "gfortran"
4457 DO i = 1, len_trim(str)
4463 @item @emph{See also}:
4464 @ref{FPUTC}, @ref{FGET}, @ref{FGETC}
4470 @section @code{FPUTC} --- Write a single character in stream mode
4472 @cindex write character, stream mode
4473 @cindex stream mode, write character
4474 @cindex file operation, write character
4477 @item @emph{Description}:
4478 Write a single character in stream mode by bypassing normal formatted
4479 output. Stream I/O should not be mixed with normal record-oriented
4480 (formatted or unformatted) I/O on the same unit; the results are unpredictable.
4482 This intrinsic is provided in both subroutine and function forms; however,
4483 only one form can be used in any given program unit.
4485 Note that the @code{FGET} intrinsic is provided for backwards compatibility with
4486 @command{g77}. GNU Fortran provides the Fortran 2003 Stream facility.
4487 Programmers should consider the use of new stream IO feature in new code
4488 for future portability. See also @ref{Fortran 2003 status}.
4490 @item @emph{Standard}:
4494 Subroutine, function
4496 @item @emph{Syntax}:
4497 @code{CALL FPUTC(UNIT, C [, STATUS])}
4499 @item @emph{Arguments}:
4500 @multitable @columnfractions .15 .70
4501 @item @var{UNIT} @tab The type shall be @code{INTEGER}.
4502 @item @var{C} @tab The type shall be @code{CHARACTER} and of default
4504 @item @var{STATUS} @tab (Optional) status flag of type @code{INTEGER}.
4505 Returns 0 on success, -1 on end-of-file and a system specific positive
4506 error code otherwise.
4509 @item @emph{Example}:
4512 CHARACTER(len=10) :: str = "gfortran"
4513 INTEGER :: fd = 42, i
4515 OPEN(UNIT = fd, FILE = "out", ACTION = "WRITE", STATUS="NEW")
4516 DO i = 1, len_trim(str)
4517 CALL fputc(fd, str(i:i))
4523 @item @emph{See also}:
4524 @ref{FPUT}, @ref{FGET}, @ref{FGETC}
4530 @section @code{FRACTION} --- Fractional part of the model representation
4532 @cindex real number, fraction
4533 @cindex floating point, fraction
4536 @item @emph{Description}:
4537 @code{FRACTION(X)} returns the fractional part of the model
4538 representation of @code{X}.
4540 @item @emph{Standard}:
4541 Fortran 95 and later
4546 @item @emph{Syntax}:
4547 @code{Y = FRACTION(X)}
4549 @item @emph{Arguments}:
4550 @multitable @columnfractions .15 .70
4551 @item @var{X} @tab The type of the argument shall be a @code{REAL}.
4554 @item @emph{Return value}:
4555 The return value is of the same type and kind as the argument.
4556 The fractional part of the model representation of @code{X} is returned;
4557 it is @code{X * RADIX(X)**(-EXPONENT(X))}.
4559 @item @emph{Example}:
4561 program test_fraction
4564 print *, fraction(x), x * radix(x)**(-exponent(x))
4565 end program test_fraction
4573 @section @code{FREE} --- Frees memory
4575 @cindex pointer, cray
4578 @item @emph{Description}:
4579 Frees memory previously allocated by @code{MALLOC()}. The @code{FREE}
4580 intrinsic is an extension intended to be used with Cray pointers, and is
4581 provided in GNU Fortran to allow user to compile legacy code. For
4582 new code using Fortran 95 pointers, the memory de-allocation intrinsic is
4585 @item @emph{Standard}:
4591 @item @emph{Syntax}:
4592 @code{CALL FREE(PTR)}
4594 @item @emph{Arguments}:
4595 @multitable @columnfractions .15 .70
4596 @item @var{PTR} @tab The type shall be @code{INTEGER}. It represents the
4597 location of the memory that should be de-allocated.
4600 @item @emph{Return value}:
4603 @item @emph{Example}:
4604 See @code{MALLOC} for an example.
4606 @item @emph{See also}:
4613 @section @code{FSEEK} --- Low level file positioning subroutine
4615 @cindex file operation, seek
4616 @cindex file operation, position
4619 @item @emph{Description}:
4620 Moves @var{UNIT} to the specified @var{OFFSET}. If @var{WHENCE}
4621 is set to 0, the @var{OFFSET} is taken as an absolute value @code{SEEK_SET},
4622 if set to 1, @var{OFFSET} is taken to be relative to the current position
4623 @code{SEEK_CUR}, and if set to 2 relative to the end of the file @code{SEEK_END}.
4624 On error, @var{STATUS} is set to a nonzero value. If @var{STATUS} the seek
4627 This intrinsic routine is not fully backwards compatible with @command{g77}.
4628 In @command{g77}, the @code{FSEEK} takes a statement label instead of a
4629 @var{STATUS} variable. If FSEEK is used in old code, change
4631 CALL FSEEK(UNIT, OFFSET, WHENCE, *label)
4636 CALL FSEEK(UNIT, OFFSET, WHENCE, status)
4637 IF (status /= 0) GOTO label
4640 Please note that GNU Fortran provides the Fortran 2003 Stream facility.
4641 Programmers should consider the use of new stream IO feature in new code
4642 for future portability. See also @ref{Fortran 2003 status}.
4644 @item @emph{Standard}:
4650 @item @emph{Syntax}:
4651 @code{CALL FSEEK(UNIT, OFFSET, WHENCE[, STATUS])}
4653 @item @emph{Arguments}:
4654 @multitable @columnfractions .15 .70
4655 @item @var{UNIT} @tab Shall be a scalar of type @code{INTEGER}.
4656 @item @var{OFFSET} @tab Shall be a scalar of type @code{INTEGER}.
4657 @item @var{WHENCE} @tab Shall be a scalar of type @code{INTEGER}.
4658 Its value shall be either 0, 1 or 2.
4659 @item @var{STATUS} @tab (Optional) shall be a scalar of type
4663 @item @emph{Example}:
4666 INTEGER, PARAMETER :: SEEK_SET = 0, SEEK_CUR = 1, SEEK_END = 2
4667 INTEGER :: fd, offset, ierr
4673 OPEN(UNIT=fd, FILE="fseek.test")
4674 CALL FSEEK(fd, offset, SEEK_SET, ierr) ! move to OFFSET
4675 print *, FTELL(fd), ierr
4677 CALL FSEEK(fd, 0, SEEK_END, ierr) ! move to end
4678 print *, FTELL(fd), ierr
4680 CALL FSEEK(fd, 0, SEEK_SET, ierr) ! move to beginning
4681 print *, FTELL(fd), ierr
4687 @item @emph{See also}:
4694 @section @code{FSTAT} --- Get file status
4696 @cindex file system, file status
4699 @item @emph{Description}:
4700 @code{FSTAT} is identical to @ref{STAT}, except that information about an
4701 already opened file is obtained.
4703 The elements in @code{VALUES} are the same as described by @ref{STAT}.
4705 This intrinsic is provided in both subroutine and function forms; however,
4706 only one form can be used in any given program unit.
4708 @item @emph{Standard}:
4712 Subroutine, function
4714 @item @emph{Syntax}:
4715 @code{CALL FSTAT(UNIT, VALUES [, STATUS])}
4717 @item @emph{Arguments}:
4718 @multitable @columnfractions .15 .70
4719 @item @var{UNIT} @tab An open I/O unit number of type @code{INTEGER}.
4720 @item @var{VALUES} @tab The type shall be @code{INTEGER(4), DIMENSION(13)}.
4721 @item @var{STATUS} @tab (Optional) status flag of type @code{INTEGER(4)}. Returns 0
4722 on success and a system specific error code otherwise.
4725 @item @emph{Example}:
4726 See @ref{STAT} for an example.
4728 @item @emph{See also}:
4729 To stat a link: @ref{LSTAT}, to stat a file: @ref{STAT}
4735 @section @code{FTELL} --- Current stream position
4737 @cindex file operation, position
4740 @item @emph{Description}:
4741 Retrieves the current position within an open file.
4743 This intrinsic is provided in both subroutine and function forms; however,
4744 only one form can be used in any given program unit.
4746 @item @emph{Standard}:
4750 Subroutine, function
4752 @item @emph{Syntax}:
4753 @multitable @columnfractions .80
4754 @item @code{CALL FTELL(UNIT, OFFSET)}
4755 @item @code{OFFSET = FTELL(UNIT)}
4758 @item @emph{Arguments}:
4759 @multitable @columnfractions .15 .70
4760 @item @var{OFFSET} @tab Shall of type @code{INTEGER}.
4761 @item @var{UNIT} @tab Shall of type @code{INTEGER}.
4764 @item @emph{Return value}:
4765 In either syntax, @var{OFFSET} is set to the current offset of unit
4766 number @var{UNIT}, or to @math{-1} if the unit is not currently open.
4768 @item @emph{Example}:
4772 OPEN(10, FILE="temp.dat")
4778 @item @emph{See also}:
4785 @section @code{GAMMA} --- Gamma function
4788 @cindex Gamma function
4789 @cindex Factorial function
4792 @item @emph{Description}:
4793 @code{GAMMA(X)} computes Gamma (@math{\Gamma}) of @var{X}. For positive,
4794 integer values of @var{X} the Gamma function simplifies to the factorial
4795 function @math{\Gamma(x)=(x-1)!}.
4799 \Gamma(x) = \int_0^\infty t^{x-1}{\rm e}^{-t}\,{\rm d}t
4803 @item @emph{Standard}:
4804 Fortran 2008 and later
4809 @item @emph{Syntax}:
4812 @item @emph{Arguments}:
4813 @multitable @columnfractions .15 .70
4814 @item @var{X} @tab Shall be of type @code{REAL} and neither zero
4815 nor a negative integer.
4818 @item @emph{Return value}:
4819 The return value is of type @code{REAL} of the same kind as @var{X}.
4821 @item @emph{Example}:
4825 x = gamma(x) ! returns 1.0
4826 end program test_gamma
4829 @item @emph{Specific names}:
4830 @multitable @columnfractions .20 .20 .20 .25
4831 @item Name @tab Argument @tab Return type @tab Standard
4832 @item @code{GAMMA(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab GNU Extension
4833 @item @code{DGAMMA(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU Extension
4836 @item @emph{See also}:
4837 Logarithm of the Gamma function: @ref{LOG_GAMMA}
4844 @section @code{GERROR} --- Get last system error message
4846 @cindex system, error handling
4849 @item @emph{Description}:
4850 Returns the system error message corresponding to the last system error.
4851 This resembles the functionality of @code{strerror(3)} in C.
4853 @item @emph{Standard}:
4859 @item @emph{Syntax}:
4860 @code{CALL GERROR(RESULT)}
4862 @item @emph{Arguments}:
4863 @multitable @columnfractions .15 .70
4864 @item @var{RESULT} @tab Shall of type @code{CHARACTER} and of default
4867 @item @emph{Example}:
4870 CHARACTER(len=100) :: msg
4876 @item @emph{See also}:
4877 @ref{IERRNO}, @ref{PERROR}
4883 @section @code{GETARG} --- Get command line arguments
4885 @cindex command-line arguments
4886 @cindex arguments, to program
4889 @item @emph{Description}:
4890 Retrieve the @var{POS}-th argument that was passed on the
4891 command line when the containing program was invoked.
4893 This intrinsic routine is provided for backwards compatibility with
4894 GNU Fortran 77. In new code, programmers should consider the use of
4895 the @ref{GET_COMMAND_ARGUMENT} intrinsic defined by the Fortran 2003
4898 @item @emph{Standard}:
4904 @item @emph{Syntax}:
4905 @code{CALL GETARG(POS, VALUE)}
4907 @item @emph{Arguments}:
4908 @multitable @columnfractions .15 .70
4909 @item @var{POS} @tab Shall be of type @code{INTEGER} and not wider than
4910 the default integer kind; @math{@var{POS} \geq 0}
4911 @item @var{VALUE} @tab Shall be of type @code{CHARACTER} and of default
4913 @item @var{VALUE} @tab Shall be of type @code{CHARACTER}.
4916 @item @emph{Return value}:
4917 After @code{GETARG} returns, the @var{VALUE} argument holds the
4918 @var{POS}th command line argument. If @var{VALUE} can not hold the
4919 argument, it is truncated to fit the length of @var{VALUE}. If there are
4920 less than @var{POS} arguments specified at the command line, @var{VALUE}
4921 will be filled with blanks. If @math{@var{POS} = 0}, @var{VALUE} is set
4922 to the name of the program (on systems that support this feature).
4924 @item @emph{Example}:
4928 CHARACTER(len=32) :: arg
4937 @item @emph{See also}:
4938 GNU Fortran 77 compatibility function: @ref{IARGC}
4940 Fortran 2003 functions and subroutines: @ref{GET_COMMAND},
4941 @ref{GET_COMMAND_ARGUMENT}, @ref{COMMAND_ARGUMENT_COUNT}
4947 @section @code{GET_COMMAND} --- Get the entire command line
4948 @fnindex GET_COMMAND
4949 @cindex command-line arguments
4950 @cindex arguments, to program
4953 @item @emph{Description}:
4954 Retrieve the entire command line that was used to invoke the program.
4956 @item @emph{Standard}:
4957 Fortran 2003 and later
4962 @item @emph{Syntax}:
4963 @code{CALL GET_COMMAND([COMMAND, LENGTH, STATUS])}
4965 @item @emph{Arguments}:
4966 @multitable @columnfractions .15 .70
4967 @item @var{COMMAND} @tab (Optional) shall be of type @code{CHARACTER} and
4969 @item @var{LENGTH} @tab (Optional) Shall be of type @code{INTEGER} and of
4971 @item @var{STATUS} @tab (Optional) Shall be of type @code{INTEGER} and of
4975 @item @emph{Return value}:
4976 If @var{COMMAND} is present, stores the entire command line that was used
4977 to invoke the program in @var{COMMAND}. If @var{LENGTH} is present, it is
4978 assigned the length of the command line. If @var{STATUS} is present, it
4979 is assigned 0 upon success of the command, -1 if @var{COMMAND} is too
4980 short to store the command line, or a positive value in case of an error.
4982 @item @emph{Example}:
4984 PROGRAM test_get_command
4985 CHARACTER(len=255) :: cmd
4986 CALL get_command(cmd)
4987 WRITE (*,*) TRIM(cmd)
4991 @item @emph{See also}:
4992 @ref{GET_COMMAND_ARGUMENT}, @ref{COMMAND_ARGUMENT_COUNT}
4997 @node GET_COMMAND_ARGUMENT
4998 @section @code{GET_COMMAND_ARGUMENT} --- Get command line arguments
4999 @fnindex GET_COMMAND_ARGUMENT
5000 @cindex command-line arguments
5001 @cindex arguments, to program
5004 @item @emph{Description}:
5005 Retrieve the @var{NUMBER}-th argument that was passed on the
5006 command line when the containing program was invoked.
5008 @item @emph{Standard}:
5009 Fortran 2003 and later
5014 @item @emph{Syntax}:
5015 @code{CALL GET_COMMAND_ARGUMENT(NUMBER [, VALUE, LENGTH, STATUS])}
5017 @item @emph{Arguments}:
5018 @multitable @columnfractions .15 .70
5019 @item @var{NUMBER} @tab Shall be a scalar of type @code{INTEGER} and of
5020 default kind, @math{@var{NUMBER} \geq 0}
5021 @item @var{VALUE} @tab Shall be a scalar of type @code{CHARACTER}
5022 and of default kind.
5023 @item @var{LENGTH} @tab (Option) Shall be a scalar of type @code{INTEGER}
5024 and of default kind.
5025 @item @var{STATUS} @tab (Option) Shall be a scalar of type @code{INTEGER}
5026 and of default kind.
5029 @item @emph{Return value}:
5030 After @code{GET_COMMAND_ARGUMENT} returns, the @var{VALUE} argument holds the
5031 @var{NUMBER}-th command line argument. If @var{VALUE} can not hold the argument, it is
5032 truncated to fit the length of @var{VALUE}. If there are less than @var{NUMBER}
5033 arguments specified at the command line, @var{VALUE} will be filled with blanks.
5034 If @math{@var{NUMBER} = 0}, @var{VALUE} is set to the name of the program (on
5035 systems that support this feature). The @var{LENGTH} argument contains the
5036 length of the @var{NUMBER}-th command line argument. If the argument retrieval
5037 fails, @var{STATUS} is a positive number; if @var{VALUE} contains a truncated
5038 command line argument, @var{STATUS} is -1; and otherwise the @var{STATUS} is
5041 @item @emph{Example}:
5043 PROGRAM test_get_command_argument
5045 CHARACTER(len=32) :: arg
5049 CALL get_command_argument(i, arg)
5050 IF (LEN_TRIM(arg) == 0) EXIT
5052 WRITE (*,*) TRIM(arg)
5058 @item @emph{See also}:
5059 @ref{GET_COMMAND}, @ref{COMMAND_ARGUMENT_COUNT}
5065 @section @code{GETCWD} --- Get current working directory
5067 @cindex system, working directory
5070 @item @emph{Description}:
5071 Get current working directory.
5073 This intrinsic is provided in both subroutine and function forms; however,
5074 only one form can be used in any given program unit.
5076 @item @emph{Standard}:
5080 Subroutine, function
5082 @item @emph{Syntax}:
5083 @code{CALL GETCWD(C [, STATUS])}
5085 @item @emph{Arguments}:
5086 @multitable @columnfractions .15 .70
5087 @item @var{C} @tab The type shall be @code{CHARACTER} and of default kind.
5088 @item @var{STATUS} @tab (Optional) status flag. Returns 0 on success,
5089 a system specific and nonzero error code otherwise.
5092 @item @emph{Example}:
5095 CHARACTER(len=255) :: cwd
5097 WRITE(*,*) TRIM(cwd)
5101 @item @emph{See also}:
5108 @section @code{GETENV} --- Get an environmental variable
5110 @cindex environment variable
5113 @item @emph{Description}:
5114 Get the @var{VALUE} of the environmental variable @var{NAME}.
5116 This intrinsic routine is provided for backwards compatibility with
5117 GNU Fortran 77. In new code, programmers should consider the use of
5118 the @ref{GET_ENVIRONMENT_VARIABLE} intrinsic defined by the Fortran
5121 @item @emph{Standard}:
5127 @item @emph{Syntax}:
5128 @code{CALL GETENV(NAME, VALUE)}
5130 @item @emph{Arguments}:
5131 @multitable @columnfractions .15 .70
5132 @item @var{NAME} @tab Shall be of type @code{CHARACTER} and of default kind.
5133 @item @var{VALUE} @tab Shall be of type @code{CHARACTER} and of default kind.
5136 @item @emph{Return value}:
5137 Stores the value of @var{NAME} in @var{VALUE}. If @var{VALUE} is
5138 not large enough to hold the data, it is truncated. If @var{NAME}
5139 is not set, @var{VALUE} will be filled with blanks.
5141 @item @emph{Example}:
5144 CHARACTER(len=255) :: homedir
5145 CALL getenv("HOME", homedir)
5146 WRITE (*,*) TRIM(homedir)
5150 @item @emph{See also}:
5151 @ref{GET_ENVIRONMENT_VARIABLE}
5156 @node GET_ENVIRONMENT_VARIABLE
5157 @section @code{GET_ENVIRONMENT_VARIABLE} --- Get an environmental variable
5158 @fnindex GET_ENVIRONMENT_VARIABLE
5159 @cindex environment variable
5162 @item @emph{Description}:
5163 Get the @var{VALUE} of the environmental variable @var{NAME}.
5165 @item @emph{Standard}:
5166 Fortran 2003 and later
5171 @item @emph{Syntax}:
5172 @code{CALL GET_ENVIRONMENT_VARIABLE(NAME[, VALUE, LENGTH, STATUS, TRIM_NAME)}
5174 @item @emph{Arguments}:
5175 @multitable @columnfractions .15 .70
5176 @item @var{NAME} @tab Shall be a scalar of type @code{CHARACTER}
5177 and of default kind.
5178 @item @var{VALUE} @tab Shall be a scalar of type @code{CHARACTER}
5179 and of default kind.
5180 @item @var{LENGTH} @tab Shall be a scalar of type @code{INTEGER}
5181 and of default kind.
5182 @item @var{STATUS} @tab Shall be a scalar of type @code{INTEGER}
5183 and of default kind.
5184 @item @var{TRIM_NAME} @tab Shall be a scalar of type @code{LOGICAL}
5185 and of default kind.
5188 @item @emph{Return value}:
5189 Stores the value of @var{NAME} in @var{VALUE}. If @var{VALUE} is
5190 not large enough to hold the data, it is truncated. If @var{NAME}
5191 is not set, @var{VALUE} will be filled with blanks. Argument @var{LENGTH}
5192 contains the length needed for storing the environment variable @var{NAME}
5193 or zero if it is not present. @var{STATUS} is -1 if @var{VALUE} is present
5194 but too short for the environment variable; it is 1 if the environment
5195 variable does not exist and 2 if the processor does not support environment
5196 variables; in all other cases @var{STATUS} is zero. If @var{TRIM_NAME} is
5197 present with the value @code{.FALSE.}, the trailing blanks in @var{NAME}
5198 are significant; otherwise they are not part of the environment variable
5201 @item @emph{Example}:
5204 CHARACTER(len=255) :: homedir
5205 CALL get_environment_variable("HOME", homedir)
5206 WRITE (*,*) TRIM(homedir)
5214 @section @code{GETGID} --- Group ID function
5216 @cindex system, group id
5219 @item @emph{Description}:
5220 Returns the numerical group ID of the current process.
5222 @item @emph{Standard}:
5228 @item @emph{Syntax}:
5229 @code{RESULT = GETGID()}
5231 @item @emph{Return value}:
5232 The return value of @code{GETGID} is an @code{INTEGER} of the default
5236 @item @emph{Example}:
5237 See @code{GETPID} for an example.
5239 @item @emph{See also}:
5240 @ref{GETPID}, @ref{GETUID}
5246 @section @code{GETLOG} --- Get login name
5248 @cindex system, login name
5252 @item @emph{Description}:
5253 Gets the username under which the program is running.
5255 @item @emph{Standard}:
5261 @item @emph{Syntax}:
5262 @code{CALL GETLOG(C)}
5264 @item @emph{Arguments}:
5265 @multitable @columnfractions .15 .70
5266 @item @var{C} @tab Shall be of type @code{CHARACTER} and of default kind.
5269 @item @emph{Return value}:
5270 Stores the current user name in @var{LOGIN}. (On systems where POSIX
5271 functions @code{geteuid} and @code{getpwuid} are not available, and
5272 the @code{getlogin} function is not implemented either, this will
5273 return a blank string.)
5275 @item @emph{Example}:
5278 CHARACTER(32) :: login
5284 @item @emph{See also}:
5291 @section @code{GETPID} --- Process ID function
5293 @cindex system, process id
5297 @item @emph{Description}:
5298 Returns the numerical process identifier of the current process.
5300 @item @emph{Standard}:
5306 @item @emph{Syntax}:
5307 @code{RESULT = GETPID()}
5309 @item @emph{Return value}:
5310 The return value of @code{GETPID} is an @code{INTEGER} of the default
5314 @item @emph{Example}:
5317 print *, "The current process ID is ", getpid()
5318 print *, "Your numerical user ID is ", getuid()
5319 print *, "Your numerical group ID is ", getgid()
5323 @item @emph{See also}:
5324 @ref{GETGID}, @ref{GETUID}
5330 @section @code{GETUID} --- User ID function
5332 @cindex system, user id
5336 @item @emph{Description}:
5337 Returns the numerical user ID of the current process.
5339 @item @emph{Standard}:
5345 @item @emph{Syntax}:
5346 @code{RESULT = GETUID()}
5348 @item @emph{Return value}:
5349 The return value of @code{GETUID} is an @code{INTEGER} of the default
5353 @item @emph{Example}:
5354 See @code{GETPID} for an example.
5356 @item @emph{See also}:
5357 @ref{GETPID}, @ref{GETLOG}
5363 @section @code{GMTIME} --- Convert time to GMT info
5365 @cindex time, conversion to GMT info
5368 @item @emph{Description}:
5369 Given a system time value @var{TIME} (as provided by the @code{TIME8()}
5370 intrinsic), fills @var{VALUES} with values extracted from it appropriate
5371 to the UTC time zone (Universal Coordinated Time, also known in some
5372 countries as GMT, Greenwich Mean Time), using @code{gmtime(3)}.
5374 @item @emph{Standard}:
5380 @item @emph{Syntax}:
5381 @code{CALL GMTIME(TIME, VALUES)}
5383 @item @emph{Arguments}:
5384 @multitable @columnfractions .15 .70
5385 @item @var{TIME} @tab An @code{INTEGER} scalar expression
5386 corresponding to a system time, with @code{INTENT(IN)}.
5387 @item @var{VALUES} @tab A default @code{INTEGER} array with 9 elements,
5388 with @code{INTENT(OUT)}.
5391 @item @emph{Return value}:
5392 The elements of @var{VALUES} are assigned as follows:
5394 @item Seconds after the minute, range 0--59 or 0--61 to allow for leap
5396 @item Minutes after the hour, range 0--59
5397 @item Hours past midnight, range 0--23
5398 @item Day of month, range 0--31
5399 @item Number of months since January, range 0--12
5400 @item Years since 1900
5401 @item Number of days since Sunday, range 0--6
5402 @item Days since January 1
5403 @item Daylight savings indicator: positive if daylight savings is in
5404 effect, zero if not, and negative if the information is not available.
5407 @item @emph{See also}:
5408 @ref{CTIME}, @ref{LTIME}, @ref{TIME}, @ref{TIME8}
5415 @section @code{HOSTNM} --- Get system host name
5417 @cindex system, host name
5420 @item @emph{Description}:
5421 Retrieves the host name of the system on which the program is running.
5423 This intrinsic is provided in both subroutine and function forms; however,
5424 only one form can be used in any given program unit.
5426 @item @emph{Standard}:
5430 Subroutine, function
5432 @item @emph{Syntax}:
5433 @multitable @columnfractions .80
5434 @item @code{CALL HOSTNM(C [, STATUS])}
5435 @item @code{STATUS = HOSTNM(NAME)}
5438 @item @emph{Arguments}:
5439 @multitable @columnfractions .15 .70
5440 @item @var{C} @tab Shall of type @code{CHARACTER} and of default kind.
5441 @item @var{STATUS} @tab (Optional) status flag of type @code{INTEGER}.
5442 Returns 0 on success, or a system specific error code otherwise.
5445 @item @emph{Return value}:
5446 In either syntax, @var{NAME} is set to the current hostname if it can
5447 be obtained, or to a blank string otherwise.
5454 @section @code{HUGE} --- Largest number of a kind
5456 @cindex limits, largest number
5457 @cindex model representation, largest number
5460 @item @emph{Description}:
5461 @code{HUGE(X)} returns the largest number that is not an infinity in
5462 the model of the type of @code{X}.
5464 @item @emph{Standard}:
5465 Fortran 95 and later
5470 @item @emph{Syntax}:
5471 @code{RESULT = HUGE(X)}
5473 @item @emph{Arguments}:
5474 @multitable @columnfractions .15 .70
5475 @item @var{X} @tab Shall be of type @code{REAL} or @code{INTEGER}.
5478 @item @emph{Return value}:
5479 The return value is of the same type and kind as @var{X}
5481 @item @emph{Example}:
5483 program test_huge_tiny
5484 print *, huge(0), huge(0.0), huge(0.0d0)
5485 print *, tiny(0.0), tiny(0.0d0)
5486 end program test_huge_tiny
5493 @section @code{HYPOT} --- Euclidean distance function
5495 @cindex Euclidean distance
5498 @item @emph{Description}:
5499 @code{HYPOT(X,Y)} is the Euclidean distance function. It is equal to
5500 @math{\sqrt{X^2 + Y^2}}, without undue underflow or overflow.
5502 @item @emph{Standard}:
5503 Fortran 2008 and later
5508 @item @emph{Syntax}:
5509 @code{RESULT = HYPOT(X, Y)}
5511 @item @emph{Arguments}:
5512 @multitable @columnfractions .15 .70
5513 @item @var{X} @tab The type shall be @code{REAL}.
5514 @item @var{Y} @tab The type and kind type parameter shall be the same as
5518 @item @emph{Return value}:
5519 The return value has the same type and kind type parameter as @var{X}.
5521 @item @emph{Example}:
5524 real(4) :: x = 1.e0_4, y = 0.5e0_4
5526 end program test_hypot
5533 @section @code{IACHAR} --- Code in @acronym{ASCII} collating sequence
5535 @cindex @acronym{ASCII} collating sequence
5536 @cindex collating sequence, @acronym{ASCII}
5537 @cindex conversion, to integer
5540 @item @emph{Description}:
5541 @code{IACHAR(C)} returns the code for the @acronym{ASCII} character
5542 in the first character position of @code{C}.
5544 @item @emph{Standard}:
5545 Fortran 95 and later, with @var{KIND} argument Fortran 2003 and later
5550 @item @emph{Syntax}:
5551 @code{RESULT = IACHAR(C [, KIND])}
5553 @item @emph{Arguments}:
5554 @multitable @columnfractions .15 .70
5555 @item @var{C} @tab Shall be a scalar @code{CHARACTER}, with @code{INTENT(IN)}
5556 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
5557 expression indicating the kind parameter of the result.
5560 @item @emph{Return value}:
5561 The return value is of type @code{INTEGER} and of kind @var{KIND}. If
5562 @var{KIND} is absent, the return value is of default integer kind.
5564 @item @emph{Example}:
5569 end program test_iachar
5573 See @ref{ICHAR} for a discussion of converting between numerical values
5574 and formatted string representations.
5576 @item @emph{See also}:
5577 @ref{ACHAR}, @ref{CHAR}, @ref{ICHAR}
5584 @section @code{IAND} --- Bitwise logical and
5586 @cindex bitwise logical and
5587 @cindex logical and, bitwise
5590 @item @emph{Description}:
5591 Bitwise logical @code{AND}.
5593 @item @emph{Standard}:
5594 Fortran 95 and later
5599 @item @emph{Syntax}:
5600 @code{RESULT = IAND(I, J)}
5602 @item @emph{Arguments}:
5603 @multitable @columnfractions .15 .70
5604 @item @var{I} @tab The type shall be @code{INTEGER}.
5605 @item @var{J} @tab The type shall be @code{INTEGER}, of the same
5606 kind as @var{I}. (As a GNU extension, different kinds are also
5610 @item @emph{Return value}:
5611 The return type is @code{INTEGER}, of the same kind as the
5612 arguments. (If the argument kinds differ, it is of the same kind as
5613 the larger argument.)
5615 @item @emph{Example}:
5619 DATA a / Z'F' /, b / Z'3' /
5620 WRITE (*,*) IAND(a, b)
5624 @item @emph{See also}:
5625 @ref{IOR}, @ref{IEOR}, @ref{IBITS}, @ref{IBSET}, @ref{IBCLR}, @ref{NOT}
5632 @section @code{IARGC} --- Get the number of command line arguments
5634 @cindex command-line arguments
5635 @cindex command-line arguments, number of
5636 @cindex arguments, to program
5639 @item @emph{Description}:
5640 @code{IARGC()} returns the number of arguments passed on the
5641 command line when the containing program was invoked.
5643 This intrinsic routine is provided for backwards compatibility with
5644 GNU Fortran 77. In new code, programmers should consider the use of
5645 the @ref{COMMAND_ARGUMENT_COUNT} intrinsic defined by the Fortran 2003
5648 @item @emph{Standard}:
5654 @item @emph{Syntax}:
5655 @code{RESULT = IARGC()}
5657 @item @emph{Arguments}:
5660 @item @emph{Return value}:
5661 The number of command line arguments, type @code{INTEGER(4)}.
5663 @item @emph{Example}:
5666 @item @emph{See also}:
5667 GNU Fortran 77 compatibility subroutine: @ref{GETARG}
5669 Fortran 2003 functions and subroutines: @ref{GET_COMMAND},
5670 @ref{GET_COMMAND_ARGUMENT}, @ref{COMMAND_ARGUMENT_COUNT}
5676 @section @code{IBCLR} --- Clear bit
5682 @item @emph{Description}:
5683 @code{IBCLR} returns the value of @var{I} with the bit at position
5684 @var{POS} set to zero.
5686 @item @emph{Standard}:
5687 Fortran 95 and later
5692 @item @emph{Syntax}:
5693 @code{RESULT = IBCLR(I, POS)}
5695 @item @emph{Arguments}:
5696 @multitable @columnfractions .15 .70
5697 @item @var{I} @tab The type shall be @code{INTEGER}.
5698 @item @var{POS} @tab The type shall be @code{INTEGER}.
5701 @item @emph{Return value}:
5702 The return value is of type @code{INTEGER} and of the same kind as
5705 @item @emph{See also}:
5706 @ref{IBITS}, @ref{IBSET}, @ref{IAND}, @ref{IOR}, @ref{IEOR}, @ref{MVBITS}
5713 @section @code{IBITS} --- Bit extraction
5716 @cindex bits, extract
5719 @item @emph{Description}:
5720 @code{IBITS} extracts a field of length @var{LEN} from @var{I},
5721 starting from bit position @var{POS} and extending left for @var{LEN}
5722 bits. The result is right-justified and the remaining bits are
5723 zeroed. The value of @code{POS+LEN} must be less than or equal to the
5724 value @code{BIT_SIZE(I)}.
5726 @item @emph{Standard}:
5727 Fortran 95 and later
5732 @item @emph{Syntax}:
5733 @code{RESULT = IBITS(I, POS, LEN)}
5735 @item @emph{Arguments}:
5736 @multitable @columnfractions .15 .70
5737 @item @var{I} @tab The type shall be @code{INTEGER}.
5738 @item @var{POS} @tab The type shall be @code{INTEGER}.
5739 @item @var{LEN} @tab The type shall be @code{INTEGER}.
5742 @item @emph{Return value}:
5743 The return value is of type @code{INTEGER} and of the same kind as
5746 @item @emph{See also}:
5747 @ref{BIT_SIZE}, @ref{IBCLR}, @ref{IBSET}, @ref{IAND}, @ref{IOR}, @ref{IEOR}
5753 @section @code{IBSET} --- Set bit
5758 @item @emph{Description}:
5759 @code{IBSET} returns the value of @var{I} with the bit at position
5760 @var{POS} set to one.
5762 @item @emph{Standard}:
5763 Fortran 95 and later
5768 @item @emph{Syntax}:
5769 @code{RESULT = IBSET(I, POS)}
5771 @item @emph{Arguments}:
5772 @multitable @columnfractions .15 .70
5773 @item @var{I} @tab The type shall be @code{INTEGER}.
5774 @item @var{POS} @tab The type shall be @code{INTEGER}.
5777 @item @emph{Return value}:
5778 The return value is of type @code{INTEGER} and of the same kind as
5781 @item @emph{See also}:
5782 @ref{IBCLR}, @ref{IBITS}, @ref{IAND}, @ref{IOR}, @ref{IEOR}, @ref{MVBITS}
5789 @section @code{ICHAR} --- Character-to-integer conversion function
5791 @cindex conversion, to integer
5794 @item @emph{Description}:
5795 @code{ICHAR(C)} returns the code for the character in the first character
5796 position of @code{C} in the system's native character set.
5797 The correspondence between characters and their codes is not necessarily
5798 the same across different GNU Fortran implementations.
5800 @item @emph{Standard}:
5801 Fortan 95 and later, with @var{KIND} argument Fortran 2003 and later
5806 @item @emph{Syntax}:
5807 @code{RESULT = ICHAR(C [, KIND])}
5809 @item @emph{Arguments}:
5810 @multitable @columnfractions .15 .70
5811 @item @var{C} @tab Shall be a scalar @code{CHARACTER}, with @code{INTENT(IN)}
5812 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
5813 expression indicating the kind parameter of the result.
5816 @item @emph{Return value}:
5817 The return value is of type @code{INTEGER} and of kind @var{KIND}. If
5818 @var{KIND} is absent, the return value is of default integer kind.
5820 @item @emph{Example}:
5825 end program test_ichar
5828 @item @emph{Specific names}:
5829 @multitable @columnfractions .20 .20 .20 .25
5830 @item Name @tab Argument @tab Return type @tab Standard
5831 @item @code{ICHAR(C)} @tab @code{CHARACTER C} @tab @code{INTEGER(4)} @tab Fortran 77 and later
5835 No intrinsic exists to convert between a numeric value and a formatted
5836 character string representation -- for instance, given the
5837 @code{CHARACTER} value @code{'154'}, obtaining an @code{INTEGER} or
5838 @code{REAL} value with the value 154, or vice versa. Instead, this
5839 functionality is provided by internal-file I/O, as in the following
5844 character(len=10) string, string2
5847 ! Convert a string to a numeric value
5848 read (string,'(I10)') value
5851 ! Convert a value to a formatted string
5852 write (string2,'(I10)') value
5854 end program read_val
5857 @item @emph{See also}:
5858 @ref{ACHAR}, @ref{CHAR}, @ref{IACHAR}
5865 @section @code{IDATE} --- Get current local time subroutine (day/month/year)
5867 @cindex date, current
5868 @cindex current date
5871 @item @emph{Description}:
5872 @code{IDATE(VALUES)} Fills @var{VALUES} with the numerical values at the
5873 current local time. The day (in the range 1-31), month (in the range 1-12),
5874 and year appear in elements 1, 2, and 3 of @var{VALUES}, respectively.
5875 The year has four significant digits.
5877 @item @emph{Standard}:
5883 @item @emph{Syntax}:
5884 @code{CALL IDATE(VALUES)}
5886 @item @emph{Arguments}:
5887 @multitable @columnfractions .15 .70
5888 @item @var{VALUES} @tab The type shall be @code{INTEGER, DIMENSION(3)} and
5889 the kind shall be the default integer kind.
5892 @item @emph{Return value}:
5893 Does not return anything.
5895 @item @emph{Example}:
5898 integer, dimension(3) :: tarray
5903 end program test_idate
5910 @section @code{IEOR} --- Bitwise logical exclusive or
5912 @cindex bitwise logical exclusive or
5913 @cindex logical exclusive or, bitwise
5916 @item @emph{Description}:
5917 @code{IEOR} returns the bitwise boolean exclusive-OR of @var{I} and
5920 @item @emph{Standard}:
5921 Fortran 95 and later
5926 @item @emph{Syntax}:
5927 @code{RESULT = IEOR(I, J)}
5929 @item @emph{Arguments}:
5930 @multitable @columnfractions .15 .70
5931 @item @var{I} @tab The type shall be @code{INTEGER}.
5932 @item @var{J} @tab The type shall be @code{INTEGER}, of the same
5933 kind as @var{I}. (As a GNU extension, different kinds are also
5937 @item @emph{Return value}:
5938 The return type is @code{INTEGER}, of the same kind as the
5939 arguments. (If the argument kinds differ, it is of the same kind as
5940 the larger argument.)
5942 @item @emph{See also}:
5943 @ref{IOR}, @ref{IAND}, @ref{IBITS}, @ref{IBSET}, @ref{IBCLR}, @ref{NOT}
5949 @section @code{IERRNO} --- Get the last system error number
5951 @cindex system, error handling
5954 @item @emph{Description}:
5955 Returns the last system error number, as given by the C @code{errno()}
5958 @item @emph{Standard}:
5964 @item @emph{Syntax}:
5965 @code{RESULT = IERRNO()}
5967 @item @emph{Arguments}:
5970 @item @emph{Return value}:
5971 The return value is of type @code{INTEGER} and of the default integer
5974 @item @emph{See also}:
5980 @node INDEX intrinsic
5981 @section @code{INDEX} --- Position of a substring within a string
5983 @cindex substring position
5984 @cindex string, find substring
5987 @item @emph{Description}:
5988 Returns the position of the start of the first occurrence of string
5989 @var{SUBSTRING} as a substring in @var{STRING}, counting from one. If
5990 @var{SUBSTRING} is not present in @var{STRING}, zero is returned. If
5991 the @var{BACK} argument is present and true, the return value is the
5992 start of the last occurrence rather than the first.
5994 @item @emph{Standard}:
5995 Fortran 77 and later, with @var{KIND} argument Fortran 2003 and later
6000 @item @emph{Syntax}:
6001 @code{RESULT = INDEX(STRING, SUBSTRING [, BACK [, KIND]])}
6003 @item @emph{Arguments}:
6004 @multitable @columnfractions .15 .70
6005 @item @var{STRING} @tab Shall be a scalar @code{CHARACTER}, with
6007 @item @var{SUBSTRING} @tab Shall be a scalar @code{CHARACTER}, with
6009 @item @var{BACK} @tab (Optional) Shall be a scalar @code{LOGICAL}, with
6011 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
6012 expression indicating the kind parameter of the result.
6015 @item @emph{Return value}:
6016 The return value is of type @code{INTEGER} and of kind @var{KIND}. If
6017 @var{KIND} is absent, the return value is of default integer kind.
6019 @item @emph{Specific names}:
6020 @multitable @columnfractions .20 .20 .20 .25
6021 @item Name @tab Argument @tab Return type @tab Standard
6022 @item @code{INDEX(STRING, SUBSTRING)} @tab @code{CHARACTER} @tab @code{INTEGER(4)} @tab Fortran 77 and later
6025 @item @emph{See also}:
6026 @ref{SCAN}, @ref{VERIFY}
6032 @section @code{INT} --- Convert to integer type
6036 @cindex conversion, to integer
6039 @item @emph{Description}:
6040 Convert to integer type
6042 @item @emph{Standard}:
6043 Fortran 77 and later
6048 @item @emph{Syntax}:
6049 @code{RESULT = INT(A [, KIND))}
6051 @item @emph{Arguments}:
6052 @multitable @columnfractions .15 .70
6053 @item @var{A} @tab Shall be of type @code{INTEGER},
6054 @code{REAL}, or @code{COMPLEX}.
6055 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
6056 expression indicating the kind parameter of the result.
6059 @item @emph{Return value}:
6060 These functions return a @code{INTEGER} variable or array under
6061 the following rules:
6065 If @var{A} is of type @code{INTEGER}, @code{INT(A) = A}
6067 If @var{A} is of type @code{REAL} and @math{|A| < 1}, @code{INT(A)} equals @code{0}.
6068 If @math{|A| \geq 1}, then @code{INT(A)} equals the largest integer that does not exceed
6069 the range of @var{A} and whose sign is the same as the sign of @var{A}.
6071 If @var{A} is of type @code{COMPLEX}, rule B is applied to the real part of @var{A}.
6074 @item @emph{Example}:
6078 complex :: z = (-3.7, 1.0)
6080 print *, int(z), int(z,8)
6084 @item @emph{Specific names}:
6085 @multitable @columnfractions .20 .20 .20 .25
6086 @item Name @tab Argument @tab Return type @tab Standard
6087 @item @code{INT(A)} @tab @code{REAL(4) A} @tab @code{INTEGER} @tab Fortran 77 and later
6088 @item @code{IFIX(A)} @tab @code{REAL(4) A} @tab @code{INTEGER} @tab Fortran 77 and later
6089 @item @code{IDINT(A)} @tab @code{REAL(8) A} @tab @code{INTEGER} @tab Fortran 77 and later
6096 @section @code{INT2} --- Convert to 16-bit integer type
6099 @cindex conversion, to integer
6102 @item @emph{Description}:
6103 Convert to a @code{KIND=2} integer type. This is equivalent to the
6104 standard @code{INT} intrinsic with an optional argument of
6105 @code{KIND=2}, and is only included for backwards compatibility.
6107 The @code{SHORT} intrinsic is equivalent to @code{INT2}.
6109 @item @emph{Standard}:
6115 @item @emph{Syntax}:
6116 @code{RESULT = INT2(A)}
6118 @item @emph{Arguments}:
6119 @multitable @columnfractions .15 .70
6120 @item @var{A} @tab Shall be of type @code{INTEGER},
6121 @code{REAL}, or @code{COMPLEX}.
6124 @item @emph{Return value}:
6125 The return value is a @code{INTEGER(2)} variable.
6127 @item @emph{See also}:
6128 @ref{INT}, @ref{INT8}, @ref{LONG}
6134 @section @code{INT8} --- Convert to 64-bit integer type
6136 @cindex conversion, to integer
6139 @item @emph{Description}:
6140 Convert to a @code{KIND=8} integer type. This is equivalent to the
6141 standard @code{INT} intrinsic with an optional argument of
6142 @code{KIND=8}, and is only included for backwards compatibility.
6144 @item @emph{Standard}:
6150 @item @emph{Syntax}:
6151 @code{RESULT = INT8(A)}
6153 @item @emph{Arguments}:
6154 @multitable @columnfractions .15 .70
6155 @item @var{A} @tab Shall be of type @code{INTEGER},
6156 @code{REAL}, or @code{COMPLEX}.
6159 @item @emph{Return value}:
6160 The return value is a @code{INTEGER(8)} variable.
6162 @item @emph{See also}:
6163 @ref{INT}, @ref{INT2}, @ref{LONG}
6169 @section @code{IOR} --- Bitwise logical or
6171 @cindex bitwise logical or
6172 @cindex logical or, bitwise
6175 @item @emph{Description}:
6176 @code{IOR} returns the bitwise boolean inclusive-OR of @var{I} and
6179 @item @emph{Standard}:
6180 Fortran 95 and later
6185 @item @emph{Syntax}:
6186 @code{RESULT = IOR(I, J)}
6188 @item @emph{Arguments}:
6189 @multitable @columnfractions .15 .70
6190 @item @var{I} @tab The type shall be @code{INTEGER}.
6191 @item @var{J} @tab The type shall be @code{INTEGER}, of the same
6192 kind as @var{I}. (As a GNU extension, different kinds are also
6196 @item @emph{Return value}:
6197 The return type is @code{INTEGER}, of the same kind as the
6198 arguments. (If the argument kinds differ, it is of the same kind as
6199 the larger argument.)
6201 @item @emph{See also}:
6202 @ref{IEOR}, @ref{IAND}, @ref{IBITS}, @ref{IBSET}, @ref{IBCLR}, @ref{NOT}
6208 @section @code{IRAND} --- Integer pseudo-random number
6210 @cindex random number generation
6213 @item @emph{Description}:
6214 @code{IRAND(FLAG)} returns a pseudo-random number from a uniform
6215 distribution between 0 and a system-dependent limit (which is in most
6216 cases 2147483647). If @var{FLAG} is 0, the next number
6217 in the current sequence is returned; if @var{FLAG} is 1, the generator
6218 is restarted by @code{CALL SRAND(0)}; if @var{FLAG} has any other value,
6219 it is used as a new seed with @code{SRAND}.
6221 This intrinsic routine is provided for backwards compatibility with
6222 GNU Fortran 77. It implements a simple modulo generator as provided
6223 by @command{g77}. For new code, one should consider the use of
6224 @ref{RANDOM_NUMBER} as it implements a superior algorithm.
6226 @item @emph{Standard}:
6232 @item @emph{Syntax}:
6233 @code{RESULT = IRAND(I)}
6235 @item @emph{Arguments}:
6236 @multitable @columnfractions .15 .70
6237 @item @var{I} @tab Shall be a scalar @code{INTEGER} of kind 4.
6240 @item @emph{Return value}:
6241 The return value is of @code{INTEGER(kind=4)} type.
6243 @item @emph{Example}:
6246 integer,parameter :: seed = 86456
6249 print *, irand(), irand(), irand(), irand()
6250 print *, irand(seed), irand(), irand(), irand()
6251 end program test_irand
6259 @section @code{IMAGE_INDEX} --- Function that converts a cosubscript to an image index
6260 @fnindex IMAGE_INDEX
6261 @cindex coarray, IMAGE_INDEX
6262 @cindex images, cosubscript to image index conversion
6265 @item @emph{Description}:
6266 Returns the image index belonging to a cosubscript.
6268 @item @emph{Standard}:
6269 Fortran 2008 and later
6274 @item @emph{Syntax}:
6275 @code{RESULT = IMAGE_INDEX(COARRAY, SUB)}
6277 @item @emph{Arguments}: None.
6278 @multitable @columnfractions .15 .70
6279 @item @var{COARRAY} @tab Coarray of any type.
6280 @item @var{SUB} @tab default integer rank-1 array of a size equal to
6281 the corank of @var{COARRAY}.
6285 @item @emph{Return value}:
6286 Scalar default integer with the value of the image index which corresponds
6287 to the cosubscripts. For invalid cosubscripts the result is zero.
6289 @item @emph{Example}:
6291 INTEGER :: array[2,-1:4,8,*]
6292 ! Writes 28 (or 0 if there are fewer than 28 images)
6293 WRITE (*,*) IMAGE_INDEX (array, [2,0,3,1])
6296 @item @emph{See also}:
6297 @ref{THIS_IMAGE}, @ref{NUM_IMAGES}
6303 @section @code{IS_IOSTAT_END} --- Test for end-of-file value
6304 @fnindex IS_IOSTAT_END
6305 @cindex IOSTAT, end of file
6308 @item @emph{Description}:
6309 @code{IS_IOSTAT_END} tests whether an variable has the value of the I/O
6310 status ``end of file''. The function is equivalent to comparing the variable
6311 with the @code{IOSTAT_END} parameter of the intrinsic module
6312 @code{ISO_FORTRAN_ENV}.
6314 @item @emph{Standard}:
6315 Fortran 2003 and later
6320 @item @emph{Syntax}:
6321 @code{RESULT = IS_IOSTAT_END(I)}
6323 @item @emph{Arguments}:
6324 @multitable @columnfractions .15 .70
6325 @item @var{I} @tab Shall be of the type @code{INTEGER}.
6328 @item @emph{Return value}:
6329 Returns a @code{LOGICAL} of the default kind, which @code{.TRUE.} if
6330 @var{I} has the value which indicates an end of file condition for
6331 IOSTAT= specifiers, and is @code{.FALSE.} otherwise.
6333 @item @emph{Example}:
6338 OPEN(88, FILE='test.dat')
6339 READ(88, *, IOSTAT=stat) i
6340 IF(IS_IOSTAT_END(stat)) STOP 'END OF FILE'
6348 @section @code{IS_IOSTAT_EOR} --- Test for end-of-record value
6349 @fnindex IS_IOSTAT_EOR
6350 @cindex IOSTAT, end of record
6353 @item @emph{Description}:
6354 @code{IS_IOSTAT_EOR} tests whether an variable has the value of the I/O
6355 status ``end of record''. The function is equivalent to comparing the
6356 variable with the @code{IOSTAT_EOR} parameter of the intrinsic module
6357 @code{ISO_FORTRAN_ENV}.
6359 @item @emph{Standard}:
6360 Fortran 2003 and later
6365 @item @emph{Syntax}:
6366 @code{RESULT = IS_IOSTAT_EOR(I)}
6368 @item @emph{Arguments}:
6369 @multitable @columnfractions .15 .70
6370 @item @var{I} @tab Shall be of the type @code{INTEGER}.
6373 @item @emph{Return value}:
6374 Returns a @code{LOGICAL} of the default kind, which @code{.TRUE.} if
6375 @var{I} has the value which indicates an end of file condition for
6376 IOSTAT= specifiers, and is @code{.FALSE.} otherwise.
6378 @item @emph{Example}:
6382 INTEGER :: stat, i(50)
6383 OPEN(88, FILE='test.dat', FORM='UNFORMATTED')
6384 READ(88, IOSTAT=stat) i
6385 IF(IS_IOSTAT_EOR(stat)) STOP 'END OF RECORD'
6393 @section @code{ISATTY} --- Whether a unit is a terminal device.
6395 @cindex system, terminal
6398 @item @emph{Description}:
6399 Determine whether a unit is connected to a terminal device.
6401 @item @emph{Standard}:
6407 @item @emph{Syntax}:
6408 @code{RESULT = ISATTY(UNIT)}
6410 @item @emph{Arguments}:
6411 @multitable @columnfractions .15 .70
6412 @item @var{UNIT} @tab Shall be a scalar @code{INTEGER}.
6415 @item @emph{Return value}:
6416 Returns @code{.TRUE.} if the @var{UNIT} is connected to a terminal
6417 device, @code{.FALSE.} otherwise.
6419 @item @emph{Example}:
6422 INTEGER(kind=1) :: unit
6424 write(*,*) isatty(unit=unit)
6428 @item @emph{See also}:
6435 @section @code{ISHFT} --- Shift bits
6440 @item @emph{Description}:
6441 @code{ISHFT} returns a value corresponding to @var{I} with all of the
6442 bits shifted @var{SHIFT} places. A value of @var{SHIFT} greater than
6443 zero corresponds to a left shift, a value of zero corresponds to no
6444 shift, and a value less than zero corresponds to a right shift. If the
6445 absolute value of @var{SHIFT} is greater than @code{BIT_SIZE(I)}, the
6446 value is undefined. Bits shifted out from the left end or right end are
6447 lost; zeros are shifted in from the opposite end.
6449 @item @emph{Standard}:
6450 Fortran 95 and later
6455 @item @emph{Syntax}:
6456 @code{RESULT = ISHFT(I, SHIFT)}
6458 @item @emph{Arguments}:
6459 @multitable @columnfractions .15 .70
6460 @item @var{I} @tab The type shall be @code{INTEGER}.
6461 @item @var{SHIFT} @tab The type shall be @code{INTEGER}.
6464 @item @emph{Return value}:
6465 The return value is of type @code{INTEGER} and of the same kind as
6468 @item @emph{See also}:
6475 @section @code{ISHFTC} --- Shift bits circularly
6477 @cindex bits, shift circular
6480 @item @emph{Description}:
6481 @code{ISHFTC} returns a value corresponding to @var{I} with the
6482 rightmost @var{SIZE} bits shifted circularly @var{SHIFT} places; that
6483 is, bits shifted out one end are shifted into the opposite end. A value
6484 of @var{SHIFT} greater than zero corresponds to a left shift, a value of
6485 zero corresponds to no shift, and a value less than zero corresponds to
6486 a right shift. The absolute value of @var{SHIFT} must be less than
6487 @var{SIZE}. If the @var{SIZE} argument is omitted, it is taken to be
6488 equivalent to @code{BIT_SIZE(I)}.
6490 @item @emph{Standard}:
6491 Fortran 95 and later
6496 @item @emph{Syntax}:
6497 @code{RESULT = ISHFTC(I, SHIFT [, SIZE])}
6499 @item @emph{Arguments}:
6500 @multitable @columnfractions .15 .70
6501 @item @var{I} @tab The type shall be @code{INTEGER}.
6502 @item @var{SHIFT} @tab The type shall be @code{INTEGER}.
6503 @item @var{SIZE} @tab (Optional) The type shall be @code{INTEGER};
6504 the value must be greater than zero and less than or equal to
6508 @item @emph{Return value}:
6509 The return value is of type @code{INTEGER} and of the same kind as
6512 @item @emph{See also}:
6519 @section @code{ISNAN} --- Test for a NaN
6524 @item @emph{Description}:
6525 @code{ISNAN} tests whether a floating-point value is an IEEE
6527 @item @emph{Standard}:
6533 @item @emph{Syntax}:
6536 @item @emph{Arguments}:
6537 @multitable @columnfractions .15 .70
6538 @item @var{X} @tab Variable of the type @code{REAL}.
6542 @item @emph{Return value}:
6543 Returns a default-kind @code{LOGICAL}. The returned value is @code{TRUE}
6544 if @var{X} is a NaN and @code{FALSE} otherwise.
6546 @item @emph{Example}:
6553 if (isnan(x)) stop '"x" is a NaN'
6554 end program test_nan
6561 @section @code{ITIME} --- Get current local time subroutine (hour/minutes/seconds)
6563 @cindex time, current
6564 @cindex current time
6567 @item @emph{Description}:
6568 @code{IDATE(VALUES)} Fills @var{VALUES} with the numerical values at the
6569 current local time. The hour (in the range 1-24), minute (in the range 1-60),
6570 and seconds (in the range 1-60) appear in elements 1, 2, and 3 of @var{VALUES},
6573 @item @emph{Standard}:
6579 @item @emph{Syntax}:
6580 @code{CALL ITIME(VALUES)}
6582 @item @emph{Arguments}:
6583 @multitable @columnfractions .15 .70
6584 @item @var{VALUES} @tab The type shall be @code{INTEGER, DIMENSION(3)}
6585 and the kind shall be the default integer kind.
6588 @item @emph{Return value}:
6589 Does not return anything.
6592 @item @emph{Example}:
6595 integer, dimension(3) :: tarray
6600 end program test_itime
6607 @section @code{KILL} --- Send a signal to a process
6611 @item @emph{Description}:
6612 @item @emph{Standard}:
6613 Sends the signal specified by @var{SIGNAL} to the process @var{PID}.
6616 This intrinsic is provided in both subroutine and function forms; however,
6617 only one form can be used in any given program unit.
6620 Subroutine, function
6622 @item @emph{Syntax}:
6623 @code{CALL KILL(C, VALUE [, STATUS])}
6625 @item @emph{Arguments}:
6626 @multitable @columnfractions .15 .70
6627 @item @var{C} @tab Shall be a scalar @code{INTEGER}, with
6629 @item @var{VALUE} @tab Shall be a scalar @code{INTEGER}, with
6631 @item @var{STATUS} @tab (Optional) status flag of type @code{INTEGER(4)} or
6632 @code{INTEGER(8)}. Returns 0 on success, or a system-specific error code
6636 @item @emph{See also}:
6637 @ref{ABORT}, @ref{EXIT}
6643 @section @code{KIND} --- Kind of an entity
6648 @item @emph{Description}:
6649 @code{KIND(X)} returns the kind value of the entity @var{X}.
6651 @item @emph{Standard}:
6652 Fortran 95 and later
6657 @item @emph{Syntax}:
6660 @item @emph{Arguments}:
6661 @multitable @columnfractions .15 .70
6662 @item @var{X} @tab Shall be of type @code{LOGICAL}, @code{INTEGER},
6663 @code{REAL}, @code{COMPLEX} or @code{CHARACTER}.
6666 @item @emph{Return value}:
6667 The return value is a scalar of type @code{INTEGER} and of the default
6670 @item @emph{Example}:
6673 integer,parameter :: kc = kind(' ')
6674 integer,parameter :: kl = kind(.true.)
6676 print *, "The default character kind is ", kc
6677 print *, "The default logical kind is ", kl
6678 end program test_kind
6686 @section @code{LBOUND} --- Lower dimension bounds of an array
6688 @cindex array, lower bound
6691 @item @emph{Description}:
6692 Returns the lower bounds of an array, or a single lower bound
6693 along the @var{DIM} dimension.
6694 @item @emph{Standard}:
6695 Fortran 95 and later, with @var{KIND} argument Fortran 2003 and later
6700 @item @emph{Syntax}:
6701 @code{RESULT = LBOUND(ARRAY [, DIM [, KIND]])}
6703 @item @emph{Arguments}:
6704 @multitable @columnfractions .15 .70
6705 @item @var{ARRAY} @tab Shall be an array, of any type.
6706 @item @var{DIM} @tab (Optional) Shall be a scalar @code{INTEGER}.
6707 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
6708 expression indicating the kind parameter of the result.
6711 @item @emph{Return value}:
6712 The return value is of type @code{INTEGER} and of kind @var{KIND}. If
6713 @var{KIND} is absent, the return value is of default integer kind.
6714 If @var{DIM} is absent, the result is an array of the lower bounds of
6715 @var{ARRAY}. If @var{DIM} is present, the result is a scalar
6716 corresponding to the lower bound of the array along that dimension. If
6717 @var{ARRAY} is an expression rather than a whole array or array
6718 structure component, or if it has a zero extent along the relevant
6719 dimension, the lower bound is taken to be 1.
6721 @item @emph{See also}:
6722 @ref{UBOUND}, @ref{LCOBOUND}
6728 @section @code{LCOBOUND} --- Lower codimension bounds of an array
6730 @cindex coarray, lower bound
6733 @item @emph{Description}:
6734 Returns the lower bounds of a coarray, or a single lower cobound
6735 along the @var{DIM} codimension.
6736 @item @emph{Standard}:
6737 Fortran 2008 and later
6742 @item @emph{Syntax}:
6743 @code{RESULT = LCOBOUND(COARRAY [, DIM [, KIND]])}
6745 @item @emph{Arguments}:
6746 @multitable @columnfractions .15 .70
6747 @item @var{ARRAY} @tab Shall be an coarray, of any type.
6748 @item @var{DIM} @tab (Optional) Shall be a scalar @code{INTEGER}.
6749 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
6750 expression indicating the kind parameter of the result.
6753 @item @emph{Return value}:
6754 The return value is of type @code{INTEGER} and of kind @var{KIND}. If
6755 @var{KIND} is absent, the return value is of default integer kind.
6756 If @var{DIM} is absent, the result is an array of the lower cobounds of
6757 @var{COARRAY}. If @var{DIM} is present, the result is a scalar
6758 corresponding to the lower cobound of the array along that codimension.
6760 @item @emph{See also}:
6761 @ref{UCOBOUND}, @ref{LBOUND}
6767 @section @code{LEADZ} --- Number of leading zero bits of an integer
6772 @item @emph{Description}:
6773 @code{LEADZ} returns the number of leading zero bits of an integer.
6775 @item @emph{Standard}:
6776 Fortran 2008 and later
6781 @item @emph{Syntax}:
6782 @code{RESULT = LEADZ(I)}
6784 @item @emph{Arguments}:
6785 @multitable @columnfractions .15 .70
6786 @item @var{I} @tab Shall be of type @code{INTEGER}.
6789 @item @emph{Return value}:
6790 The type of the return value is the default @code{INTEGER}.
6791 If all the bits of @code{I} are zero, the result value is @code{BIT_SIZE(I)}.
6793 @item @emph{Example}:
6796 WRITE (*,*) LEADZ(1) ! prints 8 if BITSIZE(I) has the value 32
6800 @item @emph{See also}:
6801 @ref{BIT_SIZE}, @ref{TRAILZ}, @ref{POPCNT}, @ref{POPPAR}
6807 @section @code{LEN} --- Length of a character entity
6809 @cindex string, length
6812 @item @emph{Description}:
6813 Returns the length of a character string. If @var{STRING} is an array,
6814 the length of an element of @var{STRING} is returned. Note that
6815 @var{STRING} need not be defined when this intrinsic is invoked, since
6816 only the length, not the content, of @var{STRING} is needed.
6818 @item @emph{Standard}:
6819 Fortran 77 and later, with @var{KIND} argument Fortran 2003 and later
6824 @item @emph{Syntax}:
6825 @code{L = LEN(STRING [, KIND])}
6827 @item @emph{Arguments}:
6828 @multitable @columnfractions .15 .70
6829 @item @var{STRING} @tab Shall be a scalar or array of type
6830 @code{CHARACTER}, with @code{INTENT(IN)}
6831 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
6832 expression indicating the kind parameter of the result.
6835 @item @emph{Return value}:
6836 The return value is of type @code{INTEGER} and of kind @var{KIND}. If
6837 @var{KIND} is absent, the return value is of default integer kind.
6840 @item @emph{Specific names}:
6841 @multitable @columnfractions .20 .20 .20 .25
6842 @item Name @tab Argument @tab Return type @tab Standard
6843 @item @code{LEN(STRING)} @tab @code{CHARACTER} @tab @code{INTEGER} @tab Fortran 77 and later
6847 @item @emph{See also}:
6848 @ref{LEN_TRIM}, @ref{ADJUSTL}, @ref{ADJUSTR}
6854 @section @code{LEN_TRIM} --- Length of a character entity without trailing blank characters
6856 @cindex string, length, without trailing whitespace
6859 @item @emph{Description}:
6860 Returns the length of a character string, ignoring any trailing blanks.
6862 @item @emph{Standard}:
6863 Fortran 95 and later, with @var{KIND} argument Fortran 2003 and later
6868 @item @emph{Syntax}:
6869 @code{RESULT = LEN_TRIM(STRING [, KIND])}
6871 @item @emph{Arguments}:
6872 @multitable @columnfractions .15 .70
6873 @item @var{STRING} @tab Shall be a scalar of type @code{CHARACTER},
6874 with @code{INTENT(IN)}
6875 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
6876 expression indicating the kind parameter of the result.
6879 @item @emph{Return value}:
6880 The return value is of type @code{INTEGER} and of kind @var{KIND}. If
6881 @var{KIND} is absent, the return value is of default integer kind.
6883 @item @emph{See also}:
6884 @ref{LEN}, @ref{ADJUSTL}, @ref{ADJUSTR}
6890 @section @code{LGE} --- Lexical greater than or equal
6892 @cindex lexical comparison of strings
6893 @cindex string, comparison
6896 @item @emph{Description}:
6897 Determines whether one string is lexically greater than or equal to
6898 another string, where the two strings are interpreted as containing
6899 ASCII character codes. If the String A and String B are not the same
6900 length, the shorter is compared as if spaces were appended to it to form
6901 a value that has the same length as the longer.
6903 In general, the lexical comparison intrinsics @code{LGE}, @code{LGT},
6904 @code{LLE}, and @code{LLT} differ from the corresponding intrinsic
6905 operators @code{.GE.}, @code{.GT.}, @code{.LE.}, and @code{.LT.}, in
6906 that the latter use the processor's character ordering (which is not
6907 ASCII on some targets), whereas the former always use the ASCII
6910 @item @emph{Standard}:
6911 Fortran 77 and later
6916 @item @emph{Syntax}:
6917 @code{RESULT = LGE(STRING_A, STRING_B)}
6919 @item @emph{Arguments}:
6920 @multitable @columnfractions .15 .70
6921 @item @var{STRING_A} @tab Shall be of default @code{CHARACTER} type.
6922 @item @var{STRING_B} @tab Shall be of default @code{CHARACTER} type.
6925 @item @emph{Return value}:
6926 Returns @code{.TRUE.} if @code{STRING_A >= STRING_B}, and @code{.FALSE.}
6927 otherwise, based on the ASCII ordering.
6929 @item @emph{Specific names}:
6930 @multitable @columnfractions .20 .20 .20 .25
6931 @item Name @tab Argument @tab Return type @tab Standard
6932 @item @code{LGE(STRING_A, STRING_B)} @tab @code{CHARACTER} @tab @code{LOGICAL} @tab Fortran 77 and later
6935 @item @emph{See also}:
6936 @ref{LGT}, @ref{LLE}, @ref{LLT}
6942 @section @code{LGT} --- Lexical greater than
6944 @cindex lexical comparison of strings
6945 @cindex string, comparison
6948 @item @emph{Description}:
6949 Determines whether one string is lexically greater than another string,
6950 where the two strings are interpreted as containing ASCII character
6951 codes. If the String A and String B are not the same length, the
6952 shorter is compared as if spaces were appended to it to form a value
6953 that has the same length as the longer.
6955 In general, the lexical comparison intrinsics @code{LGE}, @code{LGT},
6956 @code{LLE}, and @code{LLT} differ from the corresponding intrinsic
6957 operators @code{.GE.}, @code{.GT.}, @code{.LE.}, and @code{.LT.}, in
6958 that the latter use the processor's character ordering (which is not
6959 ASCII on some targets), whereas the former always use the ASCII
6962 @item @emph{Standard}:
6963 Fortran 77 and later
6968 @item @emph{Syntax}:
6969 @code{RESULT = LGT(STRING_A, STRING_B)}
6971 @item @emph{Arguments}:
6972 @multitable @columnfractions .15 .70
6973 @item @var{STRING_A} @tab Shall be of default @code{CHARACTER} type.
6974 @item @var{STRING_B} @tab Shall be of default @code{CHARACTER} type.
6977 @item @emph{Return value}:
6978 Returns @code{.TRUE.} if @code{STRING_A > STRING_B}, and @code{.FALSE.}
6979 otherwise, based on the ASCII ordering.
6981 @item @emph{Specific names}:
6982 @multitable @columnfractions .20 .20 .20 .25
6983 @item Name @tab Argument @tab Return type @tab Standard
6984 @item @code{LGT(STRING_A, STRING_B)} @tab @code{CHARACTER} @tab @code{LOGICAL} @tab Fortran 77 and later
6987 @item @emph{See also}:
6988 @ref{LGE}, @ref{LLE}, @ref{LLT}
6994 @section @code{LINK} --- Create a hard link
6996 @cindex file system, create link
6997 @cindex file system, hard link
7000 @item @emph{Description}:
7001 Makes a (hard) link from file @var{PATH1} to @var{PATH2}. A null
7002 character (@code{CHAR(0)}) can be used to mark the end of the names in
7003 @var{PATH1} and @var{PATH2}; otherwise, trailing blanks in the file
7004 names are ignored. If the @var{STATUS} argument is supplied, it
7005 contains 0 on success or a nonzero error code upon return; see
7008 This intrinsic is provided in both subroutine and function forms;
7009 however, only one form can be used in any given program unit.
7011 @item @emph{Standard}:
7015 Subroutine, function
7017 @item @emph{Syntax}:
7018 @multitable @columnfractions .80
7019 @item @code{CALL LINK(PATH1, PATH2 [, STATUS])}
7020 @item @code{STATUS = LINK(PATH1, PATH2)}
7023 @item @emph{Arguments}:
7024 @multitable @columnfractions .15 .70
7025 @item @var{PATH1} @tab Shall be of default @code{CHARACTER} type.
7026 @item @var{PATH2} @tab Shall be of default @code{CHARACTER} type.
7027 @item @var{STATUS} @tab (Optional) Shall be of default @code{INTEGER} type.
7030 @item @emph{See also}:
7031 @ref{SYMLNK}, @ref{UNLINK}
7037 @section @code{LLE} --- Lexical less than or equal
7039 @cindex lexical comparison of strings
7040 @cindex string, comparison
7043 @item @emph{Description}:
7044 Determines whether one string is lexically less than or equal to another
7045 string, where the two strings are interpreted as containing ASCII
7046 character codes. If the String A and String B are not the same length,
7047 the shorter is compared as if spaces were appended to it to form a value
7048 that has the same length as the longer.
7050 In general, the lexical comparison intrinsics @code{LGE}, @code{LGT},
7051 @code{LLE}, and @code{LLT} differ from the corresponding intrinsic
7052 operators @code{.GE.}, @code{.GT.}, @code{.LE.}, and @code{.LT.}, in
7053 that the latter use the processor's character ordering (which is not
7054 ASCII on some targets), whereas the former always use the ASCII
7057 @item @emph{Standard}:
7058 Fortran 77 and later
7063 @item @emph{Syntax}:
7064 @code{RESULT = LLE(STRING_A, STRING_B)}
7066 @item @emph{Arguments}:
7067 @multitable @columnfractions .15 .70
7068 @item @var{STRING_A} @tab Shall be of default @code{CHARACTER} type.
7069 @item @var{STRING_B} @tab Shall be of default @code{CHARACTER} type.
7072 @item @emph{Return value}:
7073 Returns @code{.TRUE.} if @code{STRING_A <= STRING_B}, and @code{.FALSE.}
7074 otherwise, based on the ASCII ordering.
7076 @item @emph{Specific names}:
7077 @multitable @columnfractions .20 .20 .20 .25
7078 @item Name @tab Argument @tab Return type @tab Standard
7079 @item @code{LLE(STRING_A, STRING_B)} @tab @code{CHARACTER} @tab @code{LOGICAL} @tab Fortran 77 and later
7082 @item @emph{See also}:
7083 @ref{LGE}, @ref{LGT}, @ref{LLT}
7089 @section @code{LLT} --- Lexical less than
7091 @cindex lexical comparison of strings
7092 @cindex string, comparison
7095 @item @emph{Description}:
7096 Determines whether one string is lexically less than another string,
7097 where the two strings are interpreted as containing ASCII character
7098 codes. If the String A and String B are not the same length, the
7099 shorter is compared as if spaces were appended to it to form a value
7100 that has the same length as the longer.
7102 In general, the lexical comparison intrinsics @code{LGE}, @code{LGT},
7103 @code{LLE}, and @code{LLT} differ from the corresponding intrinsic
7104 operators @code{.GE.}, @code{.GT.}, @code{.LE.}, and @code{.LT.}, in
7105 that the latter use the processor's character ordering (which is not
7106 ASCII on some targets), whereas the former always use the ASCII
7109 @item @emph{Standard}:
7110 Fortran 77 and later
7115 @item @emph{Syntax}:
7116 @code{RESULT = LLT(STRING_A, STRING_B)}
7118 @item @emph{Arguments}:
7119 @multitable @columnfractions .15 .70
7120 @item @var{STRING_A} @tab Shall be of default @code{CHARACTER} type.
7121 @item @var{STRING_B} @tab Shall be of default @code{CHARACTER} type.
7124 @item @emph{Return value}:
7125 Returns @code{.TRUE.} if @code{STRING_A < STRING_B}, and @code{.FALSE.}
7126 otherwise, based on the ASCII ordering.
7128 @item @emph{Specific names}:
7129 @multitable @columnfractions .20 .20 .20 .25
7130 @item Name @tab Argument @tab Return type @tab Standard
7131 @item @code{LLT(STRING_A, STRING_B)} @tab @code{CHARACTER} @tab @code{LOGICAL} @tab Fortran 77 and later
7134 @item @emph{See also}:
7135 @ref{LGE}, @ref{LGT}, @ref{LLE}
7141 @section @code{LNBLNK} --- Index of the last non-blank character in a string
7143 @cindex string, find non-blank character
7146 @item @emph{Description}:
7147 Returns the length of a character string, ignoring any trailing blanks.
7148 This is identical to the standard @code{LEN_TRIM} intrinsic, and is only
7149 included for backwards compatibility.
7151 @item @emph{Standard}:
7157 @item @emph{Syntax}:
7158 @code{RESULT = LNBLNK(STRING)}
7160 @item @emph{Arguments}:
7161 @multitable @columnfractions .15 .70
7162 @item @var{STRING} @tab Shall be a scalar of type @code{CHARACTER},
7163 with @code{INTENT(IN)}
7166 @item @emph{Return value}:
7167 The return value is of @code{INTEGER(kind=4)} type.
7169 @item @emph{See also}:
7170 @ref{INDEX intrinsic}, @ref{LEN_TRIM}
7176 @section @code{LOC} --- Returns the address of a variable
7178 @cindex location of a variable in memory
7181 @item @emph{Description}:
7182 @code{LOC(X)} returns the address of @var{X} as an integer.
7184 @item @emph{Standard}:
7190 @item @emph{Syntax}:
7191 @code{RESULT = LOC(X)}
7193 @item @emph{Arguments}:
7194 @multitable @columnfractions .15 .70
7195 @item @var{X} @tab Variable of any type.
7198 @item @emph{Return value}:
7199 The return value is of type @code{INTEGER}, with a @code{KIND}
7200 corresponding to the size (in bytes) of a memory address on the target
7203 @item @emph{Example}:
7210 end program test_loc
7217 @section @code{LOG} --- Logarithm function
7224 @cindex exponential function, inverse
7225 @cindex logarithmic function
7228 @item @emph{Description}:
7229 @code{LOG(X)} computes the logarithm of @var{X}.
7231 @item @emph{Standard}:
7232 Fortran 77 and later
7237 @item @emph{Syntax}:
7238 @code{RESULT = LOG(X)}
7240 @item @emph{Arguments}:
7241 @multitable @columnfractions .15 .70
7242 @item @var{X} @tab The type shall be @code{REAL} or
7246 @item @emph{Return value}:
7247 The return value is of type @code{REAL} or @code{COMPLEX}.
7248 The kind type parameter is the same as @var{X}.
7249 If @var{X} is @code{COMPLEX}, the imaginary part @math{\omega} is in the range
7250 @math{-\pi \leq \omega \leq \pi}.
7252 @item @emph{Example}:
7255 real(8) :: x = 1.0_8
7256 complex :: z = (1.0, 2.0)
7259 end program test_log
7262 @item @emph{Specific names}:
7263 @multitable @columnfractions .20 .20 .20 .25
7264 @item Name @tab Argument @tab Return type @tab Standard
7265 @item @code{ALOG(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab f95, gnu
7266 @item @code{DLOG(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab f95, gnu
7267 @item @code{CLOG(X)} @tab @code{COMPLEX(4) X} @tab @code{COMPLEX(4)} @tab f95, gnu
7268 @item @code{ZLOG(X)} @tab @code{COMPLEX(8) X} @tab @code{COMPLEX(8)} @tab f95, gnu
7269 @item @code{CDLOG(X)} @tab @code{COMPLEX(8) X} @tab @code{COMPLEX(8)} @tab f95, gnu
7276 @section @code{LOG10} --- Base 10 logarithm function
7280 @cindex exponential function, inverse
7281 @cindex logarithmic function
7284 @item @emph{Description}:
7285 @code{LOG10(X)} computes the base 10 logarithm of @var{X}.
7287 @item @emph{Standard}:
7288 Fortran 77 and later
7293 @item @emph{Syntax}:
7294 @code{RESULT = LOG10(X)}
7296 @item @emph{Arguments}:
7297 @multitable @columnfractions .15 .70
7298 @item @var{X} @tab The type shall be @code{REAL}.
7301 @item @emph{Return value}:
7302 The return value is of type @code{REAL} or @code{COMPLEX}.
7303 The kind type parameter is the same as @var{X}.
7305 @item @emph{Example}:
7308 real(8) :: x = 10.0_8
7310 end program test_log10
7313 @item @emph{Specific names}:
7314 @multitable @columnfractions .20 .20 .20 .25
7315 @item Name @tab Argument @tab Return type @tab Standard
7316 @item @code{ALOG10(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab Fortran 95 and later
7317 @item @code{DLOG10(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab Fortran 95 and later
7324 @section @code{LOG_GAMMA} --- Logarithm of the Gamma function
7329 @cindex Gamma function, logarithm of
7332 @item @emph{Description}:
7333 @code{LOG_GAMMA(X)} computes the natural logarithm of the absolute value
7334 of the Gamma (@math{\Gamma}) function.
7336 @item @emph{Standard}:
7337 Fortran 2008 and later
7342 @item @emph{Syntax}:
7343 @code{X = LOG_GAMMA(X)}
7345 @item @emph{Arguments}:
7346 @multitable @columnfractions .15 .70
7347 @item @var{X} @tab Shall be of type @code{REAL} and neither zero
7348 nor a negative integer.
7351 @item @emph{Return value}:
7352 The return value is of type @code{REAL} of the same kind as @var{X}.
7354 @item @emph{Example}:
7356 program test_log_gamma
7358 x = lgamma(x) ! returns 0.0
7359 end program test_log_gamma
7362 @item @emph{Specific names}:
7363 @multitable @columnfractions .20 .20 .20 .25
7364 @item Name @tab Argument @tab Return type @tab Standard
7365 @item @code{LGAMMA(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab GNU Extension
7366 @item @code{ALGAMA(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab GNU Extension
7367 @item @code{DLGAMA(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU Extension
7370 @item @emph{See also}:
7371 Gamma function: @ref{GAMMA}
7378 @section @code{LOGICAL} --- Convert to logical type
7380 @cindex conversion, to logical
7383 @item @emph{Description}:
7384 Converts one kind of @code{LOGICAL} variable to another.
7386 @item @emph{Standard}:
7387 Fortran 95 and later
7392 @item @emph{Syntax}:
7393 @code{RESULT = LOGICAL(L [, KIND])}
7395 @item @emph{Arguments}:
7396 @multitable @columnfractions .15 .70
7397 @item @var{L} @tab The type shall be @code{LOGICAL}.
7398 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
7399 expression indicating the kind parameter of the result.
7402 @item @emph{Return value}:
7403 The return value is a @code{LOGICAL} value equal to @var{L}, with a
7404 kind corresponding to @var{KIND}, or of the default logical kind if
7405 @var{KIND} is not given.
7407 @item @emph{See also}:
7408 @ref{INT}, @ref{REAL}, @ref{CMPLX}
7414 @section @code{LONG} --- Convert to integer type
7416 @cindex conversion, to integer
7419 @item @emph{Description}:
7420 Convert to a @code{KIND=4} integer type, which is the same size as a C
7421 @code{long} integer. This is equivalent to the standard @code{INT}
7422 intrinsic with an optional argument of @code{KIND=4}, and is only
7423 included for backwards compatibility.
7425 @item @emph{Standard}:
7431 @item @emph{Syntax}:
7432 @code{RESULT = LONG(A)}
7434 @item @emph{Arguments}:
7435 @multitable @columnfractions .15 .70
7436 @item @var{A} @tab Shall be of type @code{INTEGER},
7437 @code{REAL}, or @code{COMPLEX}.
7440 @item @emph{Return value}:
7441 The return value is a @code{INTEGER(4)} variable.
7443 @item @emph{See also}:
7444 @ref{INT}, @ref{INT2}, @ref{INT8}
7450 @section @code{LSHIFT} --- Left shift bits
7452 @cindex bits, shift left
7455 @item @emph{Description}:
7456 @code{LSHIFT} returns a value corresponding to @var{I} with all of the
7457 bits shifted left by @var{SHIFT} places. If the absolute value of
7458 @var{SHIFT} is greater than @code{BIT_SIZE(I)}, the value is undefined.
7459 Bits shifted out from the left end are lost; zeros are shifted in from
7462 This function has been superseded by the @code{ISHFT} intrinsic, which
7463 is standard in Fortran 95 and later.
7465 @item @emph{Standard}:
7471 @item @emph{Syntax}:
7472 @code{RESULT = LSHIFT(I, SHIFT)}
7474 @item @emph{Arguments}:
7475 @multitable @columnfractions .15 .70
7476 @item @var{I} @tab The type shall be @code{INTEGER}.
7477 @item @var{SHIFT} @tab The type shall be @code{INTEGER}.
7480 @item @emph{Return value}:
7481 The return value is of type @code{INTEGER} and of the same kind as
7484 @item @emph{See also}:
7485 @ref{ISHFT}, @ref{ISHFTC}, @ref{RSHIFT}
7492 @section @code{LSTAT} --- Get file status
7494 @cindex file system, file status
7497 @item @emph{Description}:
7498 @code{LSTAT} is identical to @ref{STAT}, except that if path is a
7499 symbolic link, then the link itself is statted, not the file that it
7502 The elements in @code{VALUES} are the same as described by @ref{STAT}.
7504 This intrinsic is provided in both subroutine and function forms;
7505 however, only one form can be used in any given program unit.
7507 @item @emph{Standard}:
7511 Subroutine, function
7513 @item @emph{Syntax}:
7514 @code{CALL LSTAT(NAME, VALUES [, STATUS])}
7516 @item @emph{Arguments}:
7517 @multitable @columnfractions .15 .70
7518 @item @var{NAME} @tab The type shall be @code{CHARACTER} of the default
7519 kind, a valid path within the file system.
7520 @item @var{VALUES} @tab The type shall be @code{INTEGER(4), DIMENSION(13)}.
7521 @item @var{STATUS} @tab (Optional) status flag of type @code{INTEGER(4)}.
7522 Returns 0 on success and a system specific error code otherwise.
7525 @item @emph{Example}:
7526 See @ref{STAT} for an example.
7528 @item @emph{See also}:
7529 To stat an open file: @ref{FSTAT}, to stat a file: @ref{STAT}
7535 @section @code{LTIME} --- Convert time to local time info
7537 @cindex time, conversion to local time info
7540 @item @emph{Description}:
7541 Given a system time value @var{TIME} (as provided by the @code{TIME8()}
7542 intrinsic), fills @var{VALUES} with values extracted from it appropriate
7543 to the local time zone using @code{localtime(3)}.
7545 @item @emph{Standard}:
7551 @item @emph{Syntax}:
7552 @code{CALL LTIME(TIME, VALUES)}
7554 @item @emph{Arguments}:
7555 @multitable @columnfractions .15 .70
7556 @item @var{TIME} @tab An @code{INTEGER} scalar expression
7557 corresponding to a system time, with @code{INTENT(IN)}.
7558 @item @var{VALUES} @tab A default @code{INTEGER} array with 9 elements,
7559 with @code{INTENT(OUT)}.
7562 @item @emph{Return value}:
7563 The elements of @var{VALUES} are assigned as follows:
7565 @item Seconds after the minute, range 0--59 or 0--61 to allow for leap
7567 @item Minutes after the hour, range 0--59
7568 @item Hours past midnight, range 0--23
7569 @item Day of month, range 0--31
7570 @item Number of months since January, range 0--12
7571 @item Years since 1900
7572 @item Number of days since Sunday, range 0--6
7573 @item Days since January 1
7574 @item Daylight savings indicator: positive if daylight savings is in
7575 effect, zero if not, and negative if the information is not available.
7578 @item @emph{See also}:
7579 @ref{CTIME}, @ref{GMTIME}, @ref{TIME}, @ref{TIME8}
7586 @section @code{MALLOC} --- Allocate dynamic memory
7588 @cindex pointer, cray
7591 @item @emph{Description}:
7592 @code{MALLOC(SIZE)} allocates @var{SIZE} bytes of dynamic memory and
7593 returns the address of the allocated memory. The @code{MALLOC} intrinsic
7594 is an extension intended to be used with Cray pointers, and is provided
7595 in GNU Fortran to allow the user to compile legacy code. For new code
7596 using Fortran 95 pointers, the memory allocation intrinsic is
7599 @item @emph{Standard}:
7605 @item @emph{Syntax}:
7606 @code{PTR = MALLOC(SIZE)}
7608 @item @emph{Arguments}:
7609 @multitable @columnfractions .15 .70
7610 @item @var{SIZE} @tab The type shall be @code{INTEGER}.
7613 @item @emph{Return value}:
7614 The return value is of type @code{INTEGER(K)}, with @var{K} such that
7615 variables of type @code{INTEGER(K)} have the same size as
7616 C pointers (@code{sizeof(void *)}).
7618 @item @emph{Example}:
7619 The following example demonstrates the use of @code{MALLOC} and
7620 @code{FREE} with Cray pointers.
7629 ptr_x = malloc(20*8)
7631 x(i) = sqrt(1.0d0 / i)
7639 end program test_malloc
7642 @item @emph{See also}:
7649 @section @code{MATMUL} --- matrix multiplication
7651 @cindex matrix multiplication
7652 @cindex product, matrix
7655 @item @emph{Description}:
7656 Performs a matrix multiplication on numeric or logical arguments.
7658 @item @emph{Standard}:
7659 Fortran 95 and later
7662 Transformational function
7664 @item @emph{Syntax}:
7665 @code{RESULT = MATMUL(MATRIX_A, MATRIX_B)}
7667 @item @emph{Arguments}:
7668 @multitable @columnfractions .15 .70
7669 @item @var{MATRIX_A} @tab An array of @code{INTEGER},
7670 @code{REAL}, @code{COMPLEX}, or @code{LOGICAL} type, with a rank of
7672 @item @var{MATRIX_B} @tab An array of @code{INTEGER},
7673 @code{REAL}, or @code{COMPLEX} type if @var{MATRIX_A} is of a numeric
7674 type; otherwise, an array of @code{LOGICAL} type. The rank shall be one
7675 or two, and the first (or only) dimension of @var{MATRIX_B} shall be
7676 equal to the last (or only) dimension of @var{MATRIX_A}.
7679 @item @emph{Return value}:
7680 The matrix product of @var{MATRIX_A} and @var{MATRIX_B}. The type and
7681 kind of the result follow the usual type and kind promotion rules, as
7682 for the @code{*} or @code{.AND.} operators.
7684 @item @emph{See also}:
7690 @section @code{MAX} --- Maximum value of an argument list
7697 @cindex maximum value
7700 @item @emph{Description}:
7701 Returns the argument with the largest (most positive) value.
7703 @item @emph{Standard}:
7704 Fortran 77 and later
7709 @item @emph{Syntax}:
7710 @code{RESULT = MAX(A1, A2 [, A3 [, ...]])}
7712 @item @emph{Arguments}:
7713 @multitable @columnfractions .15 .70
7714 @item @var{A1} @tab The type shall be @code{INTEGER} or
7716 @item @var{A2}, @var{A3}, ... @tab An expression of the same type and kind
7717 as @var{A1}. (As a GNU extension, arguments of different kinds are
7721 @item @emph{Return value}:
7722 The return value corresponds to the maximum value among the arguments,
7723 and has the same type and kind as the first argument.
7725 @item @emph{Specific names}:
7726 @multitable @columnfractions .20 .20 .20 .25
7727 @item Name @tab Argument @tab Return type @tab Standard
7728 @item @code{MAX0(A1)} @tab @code{INTEGER(4) A1} @tab @code{INTEGER(4)} @tab Fortran 77 and later
7729 @item @code{AMAX0(A1)} @tab @code{INTEGER(4) A1} @tab @code{REAL(MAX(X))} @tab Fortran 77 and later
7730 @item @code{MAX1(A1)} @tab @code{REAL A1} @tab @code{INT(MAX(X))} @tab Fortran 77 and later
7731 @item @code{AMAX1(A1)} @tab @code{REAL(4) A1} @tab @code{REAL(4)} @tab Fortran 77 and later
7732 @item @code{DMAX1(A1)} @tab @code{REAL(8) A1} @tab @code{REAL(8)} @tab Fortran 77 and later
7735 @item @emph{See also}:
7736 @ref{MAXLOC} @ref{MAXVAL}, @ref{MIN}
7743 @section @code{MAXEXPONENT} --- Maximum exponent of a real kind
7744 @fnindex MAXEXPONENT
7745 @cindex model representation, maximum exponent
7748 @item @emph{Description}:
7749 @code{MAXEXPONENT(X)} returns the maximum exponent in the model of the
7752 @item @emph{Standard}:
7753 Fortran 95 and later
7758 @item @emph{Syntax}:
7759 @code{RESULT = MAXEXPONENT(X)}
7761 @item @emph{Arguments}:
7762 @multitable @columnfractions .15 .70
7763 @item @var{X} @tab Shall be of type @code{REAL}.
7766 @item @emph{Return value}:
7767 The return value is of type @code{INTEGER} and of the default integer
7770 @item @emph{Example}:
7776 print *, minexponent(x), maxexponent(x)
7777 print *, minexponent(y), maxexponent(y)
7778 end program exponents
7785 @section @code{MAXLOC} --- Location of the maximum value within an array
7787 @cindex array, location of maximum element
7790 @item @emph{Description}:
7791 Determines the location of the element in the array with the maximum
7792 value, or, if the @var{DIM} argument is supplied, determines the
7793 locations of the maximum element along each row of the array in the
7794 @var{DIM} direction. If @var{MASK} is present, only the elements for
7795 which @var{MASK} is @code{.TRUE.} are considered. If more than one
7796 element in the array has the maximum value, the location returned is
7797 that of the first such element in array element order. If the array has
7798 zero size, or all of the elements of @var{MASK} are @code{.FALSE.}, then
7799 the result is an array of zeroes. Similarly, if @var{DIM} is supplied
7800 and all of the elements of @var{MASK} along a given row are zero, the
7801 result value for that row is zero.
7803 @item @emph{Standard}:
7804 Fortran 95 and later
7807 Transformational function
7809 @item @emph{Syntax}:
7810 @multitable @columnfractions .80
7811 @item @code{RESULT = MAXLOC(ARRAY, DIM [, MASK])}
7812 @item @code{RESULT = MAXLOC(ARRAY [, MASK])}
7815 @item @emph{Arguments}:
7816 @multitable @columnfractions .15 .70
7817 @item @var{ARRAY} @tab Shall be an array of type @code{INTEGER} or
7819 @item @var{DIM} @tab (Optional) Shall be a scalar of type
7820 @code{INTEGER}, with a value between one and the rank of @var{ARRAY},
7821 inclusive. It may not be an optional dummy argument.
7822 @item @var{MASK} @tab Shall be an array of type @code{LOGICAL},
7823 and conformable with @var{ARRAY}.
7826 @item @emph{Return value}:
7827 If @var{DIM} is absent, the result is a rank-one array with a length
7828 equal to the rank of @var{ARRAY}. If @var{DIM} is present, the result
7829 is an array with a rank one less than the rank of @var{ARRAY}, and a
7830 size corresponding to the size of @var{ARRAY} with the @var{DIM}
7831 dimension removed. If @var{DIM} is present and @var{ARRAY} has a rank
7832 of one, the result is a scalar. In all cases, the result is of default
7833 @code{INTEGER} type.
7835 @item @emph{See also}:
7836 @ref{MAX}, @ref{MAXVAL}
7843 @section @code{MAXVAL} --- Maximum value of an array
7845 @cindex array, maximum value
7846 @cindex maximum value
7849 @item @emph{Description}:
7850 Determines the maximum value of the elements in an array value, or, if
7851 the @var{DIM} argument is supplied, determines the maximum value along
7852 each row of the array in the @var{DIM} direction. If @var{MASK} is
7853 present, only the elements for which @var{MASK} is @code{.TRUE.} are
7854 considered. If the array has zero size, or all of the elements of
7855 @var{MASK} are @code{.FALSE.}, then the result is @code{-HUGE(ARRAY)}
7856 if @var{ARRAY} is numeric, or a string of nulls if @var{ARRAY} is of character
7859 @item @emph{Standard}:
7860 Fortran 95 and later
7863 Transformational function
7865 @item @emph{Syntax}:
7866 @multitable @columnfractions .80
7867 @item @code{RESULT = MAXVAL(ARRAY, DIM [, MASK])}
7868 @item @code{RESULT = MAXVAL(ARRAY [, MASK])}
7871 @item @emph{Arguments}:
7872 @multitable @columnfractions .15 .70
7873 @item @var{ARRAY} @tab Shall be an array of type @code{INTEGER} or
7875 @item @var{DIM} @tab (Optional) Shall be a scalar of type
7876 @code{INTEGER}, with a value between one and the rank of @var{ARRAY},
7877 inclusive. It may not be an optional dummy argument.
7878 @item @var{MASK} @tab Shall be an array of type @code{LOGICAL},
7879 and conformable with @var{ARRAY}.
7882 @item @emph{Return value}:
7883 If @var{DIM} is absent, or if @var{ARRAY} has a rank of one, the result
7884 is a scalar. If @var{DIM} is present, the result is an array with a
7885 rank one less than the rank of @var{ARRAY}, and a size corresponding to
7886 the size of @var{ARRAY} with the @var{DIM} dimension removed. In all
7887 cases, the result is of the same type and kind as @var{ARRAY}.
7889 @item @emph{See also}:
7890 @ref{MAX}, @ref{MAXLOC}
7896 @section @code{MCLOCK} --- Time function
7898 @cindex time, clock ticks
7902 @item @emph{Description}:
7903 Returns the number of clock ticks since the start of the process, based
7904 on the UNIX function @code{clock(3)}.
7906 This intrinsic is not fully portable, such as to systems with 32-bit
7907 @code{INTEGER} types but supporting times wider than 32 bits. Therefore,
7908 the values returned by this intrinsic might be, or become, negative, or
7909 numerically less than previous values, during a single run of the
7912 @item @emph{Standard}:
7918 @item @emph{Syntax}:
7919 @code{RESULT = MCLOCK()}
7921 @item @emph{Return value}:
7922 The return value is a scalar of type @code{INTEGER(4)}, equal to the
7923 number of clock ticks since the start of the process, or @code{-1} if
7924 the system does not support @code{clock(3)}.
7926 @item @emph{See also}:
7927 @ref{CTIME}, @ref{GMTIME}, @ref{LTIME}, @ref{MCLOCK}, @ref{TIME}
7934 @section @code{MCLOCK8} --- Time function (64-bit)
7936 @cindex time, clock ticks
7940 @item @emph{Description}:
7941 Returns the number of clock ticks since the start of the process, based
7942 on the UNIX function @code{clock(3)}.
7944 @emph{Warning:} this intrinsic does not increase the range of the timing
7945 values over that returned by @code{clock(3)}. On a system with a 32-bit
7946 @code{clock(3)}, @code{MCLOCK8()} will return a 32-bit value, even though
7947 it is converted to a 64-bit @code{INTEGER(8)} value. That means
7948 overflows of the 32-bit value can still occur. Therefore, the values
7949 returned by this intrinsic might be or become negative or numerically
7950 less than previous values during a single run of the compiled program.
7952 @item @emph{Standard}:
7958 @item @emph{Syntax}:
7959 @code{RESULT = MCLOCK8()}
7961 @item @emph{Return value}:
7962 The return value is a scalar of type @code{INTEGER(8)}, equal to the
7963 number of clock ticks since the start of the process, or @code{-1} if
7964 the system does not support @code{clock(3)}.
7966 @item @emph{See also}:
7967 @ref{CTIME}, @ref{GMTIME}, @ref{LTIME}, @ref{MCLOCK}, @ref{TIME8}
7974 @section @code{MERGE} --- Merge variables
7976 @cindex array, merge arrays
7977 @cindex array, combine arrays
7980 @item @emph{Description}:
7981 Select values from two arrays according to a logical mask. The result
7982 is equal to @var{TSOURCE} if @var{MASK} is @code{.TRUE.}, or equal to
7983 @var{FSOURCE} if it is @code{.FALSE.}.
7985 @item @emph{Standard}:
7986 Fortran 95 and later
7991 @item @emph{Syntax}:
7992 @code{RESULT = MERGE(TSOURCE, FSOURCE, MASK)}
7994 @item @emph{Arguments}:
7995 @multitable @columnfractions .15 .70
7996 @item @var{TSOURCE} @tab May be of any type.
7997 @item @var{FSOURCE} @tab Shall be of the same type and type parameters
7999 @item @var{MASK} @tab Shall be of type @code{LOGICAL}.
8002 @item @emph{Return value}:
8003 The result is of the same type and type parameters as @var{TSOURCE}.
8010 @section @code{MIN} --- Minimum value of an argument list
8017 @cindex minimum value
8020 @item @emph{Description}:
8021 Returns the argument with the smallest (most negative) value.
8023 @item @emph{Standard}:
8024 Fortran 77 and later
8029 @item @emph{Syntax}:
8030 @code{RESULT = MIN(A1, A2 [, A3, ...])}
8032 @item @emph{Arguments}:
8033 @multitable @columnfractions .15 .70
8034 @item @var{A1} @tab The type shall be @code{INTEGER} or
8036 @item @var{A2}, @var{A3}, ... @tab An expression of the same type and kind
8037 as @var{A1}. (As a GNU extension, arguments of different kinds are
8041 @item @emph{Return value}:
8042 The return value corresponds to the maximum value among the arguments,
8043 and has the same type and kind as the first argument.
8045 @item @emph{Specific names}:
8046 @multitable @columnfractions .20 .20 .20 .25
8047 @item Name @tab Argument @tab Return type @tab Standard
8048 @item @code{MIN0(A1)} @tab @code{INTEGER(4) A1} @tab @code{INTEGER(4)} @tab Fortran 77 and later
8049 @item @code{AMIN0(A1)} @tab @code{INTEGER(4) A1} @tab @code{REAL(4)} @tab Fortran 77 and later
8050 @item @code{MIN1(A1)} @tab @code{REAL A1} @tab @code{INTEGER(4)} @tab Fortran 77 and later
8051 @item @code{AMIN1(A1)} @tab @code{REAL(4) A1} @tab @code{REAL(4)} @tab Fortran 77 and later
8052 @item @code{DMIN1(A1)} @tab @code{REAL(8) A1} @tab @code{REAL(8)} @tab Fortran 77 and later
8055 @item @emph{See also}:
8056 @ref{MAX}, @ref{MINLOC}, @ref{MINVAL}
8062 @section @code{MINEXPONENT} --- Minimum exponent of a real kind
8063 @fnindex MINEXPONENT
8064 @cindex model representation, minimum exponent
8067 @item @emph{Description}:
8068 @code{MINEXPONENT(X)} returns the minimum exponent in the model of the
8071 @item @emph{Standard}:
8072 Fortran 95 and later
8077 @item @emph{Syntax}:
8078 @code{RESULT = MINEXPONENT(X)}
8080 @item @emph{Arguments}:
8081 @multitable @columnfractions .15 .70
8082 @item @var{X} @tab Shall be of type @code{REAL}.
8085 @item @emph{Return value}:
8086 The return value is of type @code{INTEGER} and of the default integer
8089 @item @emph{Example}:
8090 See @code{MAXEXPONENT} for an example.
8096 @section @code{MINLOC} --- Location of the minimum value within an array
8098 @cindex array, location of minimum element
8101 @item @emph{Description}:
8102 Determines the location of the element in the array with the minimum
8103 value, or, if the @var{DIM} argument is supplied, determines the
8104 locations of the minimum element along each row of the array in the
8105 @var{DIM} direction. If @var{MASK} is present, only the elements for
8106 which @var{MASK} is @code{.TRUE.} are considered. If more than one
8107 element in the array has the minimum value, the location returned is
8108 that of the first such element in array element order. If the array has
8109 zero size, or all of the elements of @var{MASK} are @code{.FALSE.}, then
8110 the result is an array of zeroes. Similarly, if @var{DIM} is supplied
8111 and all of the elements of @var{MASK} along a given row are zero, the
8112 result value for that row is zero.
8114 @item @emph{Standard}:
8115 Fortran 95 and later
8118 Transformational function
8120 @item @emph{Syntax}:
8121 @multitable @columnfractions .80
8122 @item @code{RESULT = MINLOC(ARRAY, DIM [, MASK])}
8123 @item @code{RESULT = MINLOC(ARRAY [, MASK])}
8126 @item @emph{Arguments}:
8127 @multitable @columnfractions .15 .70
8128 @item @var{ARRAY} @tab Shall be an array of type @code{INTEGER} or
8130 @item @var{DIM} @tab (Optional) Shall be a scalar of type
8131 @code{INTEGER}, with a value between one and the rank of @var{ARRAY},
8132 inclusive. It may not be an optional dummy argument.
8133 @item @var{MASK} @tab Shall be an array of type @code{LOGICAL},
8134 and conformable with @var{ARRAY}.
8137 @item @emph{Return value}:
8138 If @var{DIM} is absent, the result is a rank-one array with a length
8139 equal to the rank of @var{ARRAY}. If @var{DIM} is present, the result
8140 is an array with a rank one less than the rank of @var{ARRAY}, and a
8141 size corresponding to the size of @var{ARRAY} with the @var{DIM}
8142 dimension removed. If @var{DIM} is present and @var{ARRAY} has a rank
8143 of one, the result is a scalar. In all cases, the result is of default
8144 @code{INTEGER} type.
8146 @item @emph{See also}:
8147 @ref{MIN}, @ref{MINVAL}
8154 @section @code{MINVAL} --- Minimum value of an array
8156 @cindex array, minimum value
8157 @cindex minimum value
8160 @item @emph{Description}:
8161 Determines the minimum value of the elements in an array value, or, if
8162 the @var{DIM} argument is supplied, determines the minimum value along
8163 each row of the array in the @var{DIM} direction. If @var{MASK} is
8164 present, only the elements for which @var{MASK} is @code{.TRUE.} are
8165 considered. If the array has zero size, or all of the elements of
8166 @var{MASK} are @code{.FALSE.}, then the result is @code{HUGE(ARRAY)} if
8167 @var{ARRAY} is numeric, or a string of @code{CHAR(255)} characters if
8168 @var{ARRAY} is of character type.
8170 @item @emph{Standard}:
8171 Fortran 95 and later
8174 Transformational function
8176 @item @emph{Syntax}:
8177 @multitable @columnfractions .80
8178 @item @code{RESULT = MINVAL(ARRAY, DIM [, MASK])}
8179 @item @code{RESULT = MINVAL(ARRAY [, MASK])}
8182 @item @emph{Arguments}:
8183 @multitable @columnfractions .15 .70
8184 @item @var{ARRAY} @tab Shall be an array of type @code{INTEGER} or
8186 @item @var{DIM} @tab (Optional) Shall be a scalar of type
8187 @code{INTEGER}, with a value between one and the rank of @var{ARRAY},
8188 inclusive. It may not be an optional dummy argument.
8189 @item @var{MASK} @tab Shall be an array of type @code{LOGICAL},
8190 and conformable with @var{ARRAY}.
8193 @item @emph{Return value}:
8194 If @var{DIM} is absent, or if @var{ARRAY} has a rank of one, the result
8195 is a scalar. If @var{DIM} is present, the result is an array with a
8196 rank one less than the rank of @var{ARRAY}, and a size corresponding to
8197 the size of @var{ARRAY} with the @var{DIM} dimension removed. In all
8198 cases, the result is of the same type and kind as @var{ARRAY}.
8200 @item @emph{See also}:
8201 @ref{MIN}, @ref{MINLOC}
8208 @section @code{MOD} --- Remainder function
8213 @cindex division, remainder
8216 @item @emph{Description}:
8217 @code{MOD(A,P)} computes the remainder of the division of A by P@. It is
8218 calculated as @code{A - (INT(A/P) * P)}.
8220 @item @emph{Standard}:
8221 Fortran 77 and later
8226 @item @emph{Syntax}:
8227 @code{RESULT = MOD(A, P)}
8229 @item @emph{Arguments}:
8230 @multitable @columnfractions .15 .70
8231 @item @var{A} @tab Shall be a scalar of type @code{INTEGER} or @code{REAL}
8232 @item @var{P} @tab Shall be a scalar of the same type as @var{A} and not
8236 @item @emph{Return value}:
8237 The kind of the return value is the result of cross-promoting
8238 the kinds of the arguments.
8240 @item @emph{Example}:
8244 print *, mod(17.5,5.5)
8245 print *, mod(17.5d0,5.5)
8246 print *, mod(17.5,5.5d0)
8249 print *, mod(-17.5,5.5)
8250 print *, mod(-17.5d0,5.5)
8251 print *, mod(-17.5,5.5d0)
8254 print *, mod(17.5,-5.5)
8255 print *, mod(17.5d0,-5.5)
8256 print *, mod(17.5,-5.5d0)
8257 end program test_mod
8260 @item @emph{Specific names}:
8261 @multitable @columnfractions .20 .20 .20 .25
8262 @item Name @tab Arguments @tab Return type @tab Standard
8263 @item @code{MOD(A,P)} @tab @code{INTEGER A,P} @tab @code{INTEGER} @tab Fortran 95 and later
8264 @item @code{AMOD(A,P)} @tab @code{REAL(4) A,P} @tab @code{REAL(4)} @tab Fortran 95 and later
8265 @item @code{DMOD(A,P)} @tab @code{REAL(8) A,P} @tab @code{REAL(8)} @tab Fortran 95 and later
8272 @section @code{MODULO} --- Modulo function
8275 @cindex division, modulo
8278 @item @emph{Description}:
8279 @code{MODULO(A,P)} computes the @var{A} modulo @var{P}.
8281 @item @emph{Standard}:
8282 Fortran 95 and later
8287 @item @emph{Syntax}:
8288 @code{RESULT = MODULO(A, P)}
8290 @item @emph{Arguments}:
8291 @multitable @columnfractions .15 .70
8292 @item @var{A} @tab Shall be a scalar of type @code{INTEGER} or @code{REAL}
8293 @item @var{P} @tab Shall be a scalar of the same type and kind as @var{A}
8296 @item @emph{Return value}:
8297 The type and kind of the result are those of the arguments.
8299 @item If @var{A} and @var{P} are of type @code{INTEGER}:
8300 @code{MODULO(A,P)} has the value @var{R} such that @code{A=Q*P+R}, where
8301 @var{Q} is an integer and @var{R} is between 0 (inclusive) and @var{P}
8303 @item If @var{A} and @var{P} are of type @code{REAL}:
8304 @code{MODULO(A,P)} has the value of @code{A - FLOOR (A / P) * P}.
8306 In all cases, if @var{P} is zero the result is processor-dependent.
8308 @item @emph{Example}:
8311 print *, modulo(17,3)
8312 print *, modulo(17.5,5.5)
8314 print *, modulo(-17,3)
8315 print *, modulo(-17.5,5.5)
8317 print *, modulo(17,-3)
8318 print *, modulo(17.5,-5.5)
8327 @section @code{MOVE_ALLOC} --- Move allocation from one object to another
8329 @cindex moving allocation
8330 @cindex allocation, moving
8333 @item @emph{Description}:
8334 @code{MOVE_ALLOC(FROM, TO)} moves the allocation from @var{FROM} to
8335 @var{TO}. @var{FROM} will become deallocated in the process.
8337 @item @emph{Standard}:
8338 Fortran 2003 and later
8343 @item @emph{Syntax}:
8344 @code{CALL MOVE_ALLOC(FROM, TO)}
8346 @item @emph{Arguments}:
8347 @multitable @columnfractions .15 .70
8348 @item @var{FROM} @tab @code{ALLOCATABLE}, @code{INTENT(INOUT)}, may be
8349 of any type and kind.
8350 @item @var{TO} @tab @code{ALLOCATABLE}, @code{INTENT(OUT)}, shall be
8351 of the same type, kind and rank as @var{FROM}.
8354 @item @emph{Return value}:
8357 @item @emph{Example}:
8359 program test_move_alloc
8360 integer, allocatable :: a(:), b(:)
8364 call move_alloc(a, b)
8365 print *, allocated(a), allocated(b)
8367 end program test_move_alloc
8374 @section @code{MVBITS} --- Move bits from one integer to another
8379 @item @emph{Description}:
8380 Moves @var{LEN} bits from positions @var{FROMPOS} through
8381 @code{FROMPOS+LEN-1} of @var{FROM} to positions @var{TOPOS} through
8382 @code{TOPOS+LEN-1} of @var{TO}. The portion of argument @var{TO} not
8383 affected by the movement of bits is unchanged. The values of
8384 @code{FROMPOS+LEN-1} and @code{TOPOS+LEN-1} must be less than
8385 @code{BIT_SIZE(FROM)}.
8387 @item @emph{Standard}:
8388 Fortran 95 and later
8391 Elemental subroutine
8393 @item @emph{Syntax}:
8394 @code{CALL MVBITS(FROM, FROMPOS, LEN, TO, TOPOS)}
8396 @item @emph{Arguments}:
8397 @multitable @columnfractions .15 .70
8398 @item @var{FROM} @tab The type shall be @code{INTEGER}.
8399 @item @var{FROMPOS} @tab The type shall be @code{INTEGER}.
8400 @item @var{LEN} @tab The type shall be @code{INTEGER}.
8401 @item @var{TO} @tab The type shall be @code{INTEGER}, of the
8402 same kind as @var{FROM}.
8403 @item @var{TOPOS} @tab The type shall be @code{INTEGER}.
8406 @item @emph{See also}:
8407 @ref{IBCLR}, @ref{IBSET}, @ref{IBITS}, @ref{IAND}, @ref{IOR}, @ref{IEOR}
8413 @section @code{NEAREST} --- Nearest representable number
8415 @cindex real number, nearest different
8416 @cindex floating point, nearest different
8419 @item @emph{Description}:
8420 @code{NEAREST(X, S)} returns the processor-representable number nearest
8421 to @code{X} in the direction indicated by the sign of @code{S}.
8423 @item @emph{Standard}:
8424 Fortran 95 and later
8429 @item @emph{Syntax}:
8430 @code{RESULT = NEAREST(X, S)}
8432 @item @emph{Arguments}:
8433 @multitable @columnfractions .15 .70
8434 @item @var{X} @tab Shall be of type @code{REAL}.
8435 @item @var{S} @tab (Optional) shall be of type @code{REAL} and
8439 @item @emph{Return value}:
8440 The return value is of the same type as @code{X}. If @code{S} is
8441 positive, @code{NEAREST} returns the processor-representable number
8442 greater than @code{X} and nearest to it. If @code{S} is negative,
8443 @code{NEAREST} returns the processor-representable number smaller than
8444 @code{X} and nearest to it.
8446 @item @emph{Example}:
8448 program test_nearest
8450 x = nearest(42.0, 1.0)
8451 y = nearest(42.0, -1.0)
8452 write (*,"(3(G20.15))") x, y, x - y
8453 end program test_nearest
8460 @section @code{NEW_LINE} --- New line character
8463 @cindex output, newline
8466 @item @emph{Description}:
8467 @code{NEW_LINE(C)} returns the new-line character.
8469 @item @emph{Standard}:
8470 Fortran 2003 and later
8475 @item @emph{Syntax}:
8476 @code{RESULT = NEW_LINE(C)}
8478 @item @emph{Arguments}:
8479 @multitable @columnfractions .15 .70
8480 @item @var{C} @tab The argument shall be a scalar or array of the
8481 type @code{CHARACTER}.
8484 @item @emph{Return value}:
8485 Returns a @var{CHARACTER} scalar of length one with the new-line character of
8486 the same kind as parameter @var{C}.
8488 @item @emph{Example}:
8492 write(*,'(A)') 'This is record 1.'//NEW_LINE('A')//'This is record 2.'
8500 @section @code{NINT} --- Nearest whole number
8503 @cindex rounding, nearest whole number
8506 @item @emph{Description}:
8507 @code{NINT(A)} rounds its argument to the nearest whole number.
8509 @item @emph{Standard}:
8510 Fortran 77 and later, with @var{KIND} argument Fortran 90 and later
8515 @item @emph{Syntax}:
8516 @code{RESULT = NINT(A [, KIND])}
8518 @item @emph{Arguments}:
8519 @multitable @columnfractions .15 .70
8520 @item @var{A} @tab The type of the argument shall be @code{REAL}.
8521 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
8522 expression indicating the kind parameter of the result.
8525 @item @emph{Return value}:
8526 Returns @var{A} with the fractional portion of its magnitude eliminated by
8527 rounding to the nearest whole number and with its sign preserved,
8528 converted to an @code{INTEGER} of the default kind.
8530 @item @emph{Example}:
8537 print *, nint(x4), idnint(x8)
8538 end program test_nint
8541 @item @emph{Specific names}:
8542 @multitable @columnfractions .20 .20 .20 .25
8543 @item Name @tab Argument @tab Return Type @tab Standard
8544 @item @code{NINT(A)} @tab @code{REAL(4) A} @tab @code{INTEGER} @tab Fortran 95 and later
8545 @item @code{IDNINT(A)} @tab @code{REAL(8) A} @tab @code{INTEGER} @tab Fortran 95 and later
8548 @item @emph{See also}:
8549 @ref{CEILING}, @ref{FLOOR}
8556 @section @code{NORM2} --- Euclidean vector norms
8558 @cindex Euclidean vector norm
8559 @cindex L2 vector norm
8560 @cindex norm, Euclidean
8563 @item @emph{Description}:
8564 Calculates the Euclidean vector norm (@math{L_2}) norm of
8565 of @var{ARRAY} along dimension @var{DIM}.
8567 @item @emph{Standard}:
8568 Fortran 2008 and later
8571 Transformational function
8573 @item @emph{Syntax}:
8574 @multitable @columnfractions .80
8575 @item @code{RESULT = NORM2(ARRAY[, DIM])}
8578 @item @emph{Arguments}:
8579 @multitable @columnfractions .15 .70
8580 @item @var{ARRAY} @tab Shall be an array of type @code{REAL}
8581 @item @var{DIM} @tab (Optional) shall be a scalar of type
8582 @code{INTEGER} with a value in the range from 1 to n, where n
8583 equals the rank of @var{ARRAY}.
8586 @item @emph{Return value}:
8587 The result is of the same type as @var{ARRAY}.
8589 If @var{DIM} is absent, a scalar with the square root of the sum of all
8590 elements in @var{ARRAY} squared is returned. Otherwise, an array of
8591 rank @math{n-1}, where @math{n} equals the rank of @var{ARRAY}, and a
8592 shape similar to that of @var{ARRAY} with dimension @var{DIM} dropped
8595 @item @emph{Example}:
8598 REAL :: x(5) = [ real :: 1, 2, 3, 4, 5 ]
8599 print *, NORM2(x) ! = sqrt(55.) ~ 7.416
8607 @section @code{NOT} --- Logical negation
8609 @cindex bits, negate
8610 @cindex bitwise logical not
8611 @cindex logical not, bitwise
8614 @item @emph{Description}:
8615 @code{NOT} returns the bitwise boolean inverse of @var{I}.
8617 @item @emph{Standard}:
8618 Fortran 95 and later
8623 @item @emph{Syntax}:
8624 @code{RESULT = NOT(I)}
8626 @item @emph{Arguments}:
8627 @multitable @columnfractions .15 .70
8628 @item @var{I} @tab The type shall be @code{INTEGER}.
8631 @item @emph{Return value}:
8632 The return type is @code{INTEGER}, of the same kind as the
8635 @item @emph{See also}:
8636 @ref{IAND}, @ref{IEOR}, @ref{IOR}, @ref{IBITS}, @ref{IBSET}, @ref{IBCLR}
8643 @section @code{NULL} --- Function that returns an disassociated pointer
8645 @cindex pointer, status
8646 @cindex pointer, disassociated
8649 @item @emph{Description}:
8650 Returns a disassociated pointer.
8652 If @var{MOLD} is present, a dissassociated pointer of the same type is
8653 returned, otherwise the type is determined by context.
8655 In Fortran 95, @var{MOLD} is optional. Please note that Fortran 2003
8656 includes cases where it is required.
8658 @item @emph{Standard}:
8659 Fortran 95 and later
8662 Transformational function
8664 @item @emph{Syntax}:
8665 @code{PTR => NULL([MOLD])}
8667 @item @emph{Arguments}:
8668 @multitable @columnfractions .15 .70
8669 @item @var{MOLD} @tab (Optional) shall be a pointer of any association
8670 status and of any type.
8673 @item @emph{Return value}:
8674 A disassociated pointer.
8676 @item @emph{Example}:
8678 REAL, POINTER, DIMENSION(:) :: VEC => NULL ()
8681 @item @emph{See also}:
8688 @section @code{NUM_IMAGES} --- Function that returns the number of images
8690 @cindex coarray, NUM_IMAGES
8691 @cindex images, number of
8694 @item @emph{Description}:
8695 Returns the number of images.
8697 @item @emph{Standard}:
8698 Fortran 2008 and later
8701 Transformational function
8703 @item @emph{Syntax}:
8704 @code{RESULT = NUM_IMAGES()}
8706 @item @emph{Arguments}: None.
8708 @item @emph{Return value}:
8709 Scalar default-kind integer.
8711 @item @emph{Example}:
8715 value = THIS_IMAGE()
8717 IF (THIS_IMAGE() == 1) THEN
8718 DO i = 1, NUM_IMAGES()
8719 WRITE(*,'(2(a,i0))') 'value[', i, '] is ', value[i]
8724 @item @emph{See also}:
8725 @ref{THIS_IMAGE}, @ref{IMAGE_INDEX}
8731 @section @code{OR} --- Bitwise logical OR
8733 @cindex bitwise logical or
8734 @cindex logical or, bitwise
8737 @item @emph{Description}:
8738 Bitwise logical @code{OR}.
8740 This intrinsic routine is provided for backwards compatibility with
8741 GNU Fortran 77. For integer arguments, programmers should consider
8742 the use of the @ref{IOR} intrinsic defined by the Fortran standard.
8744 @item @emph{Standard}:
8750 @item @emph{Syntax}:
8751 @code{RESULT = OR(I, J)}
8753 @item @emph{Arguments}:
8754 @multitable @columnfractions .15 .70
8755 @item @var{I} @tab The type shall be either a scalar @code{INTEGER}
8756 type or a scalar @code{LOGICAL} type.
8757 @item @var{J} @tab The type shall be the same as the type of @var{J}.
8760 @item @emph{Return value}:
8761 The return type is either a scalar @code{INTEGER} or a scalar
8762 @code{LOGICAL}. If the kind type parameters differ, then the
8763 smaller kind type is implicitly converted to larger kind, and the
8764 return has the larger kind.
8766 @item @emph{Example}:
8769 LOGICAL :: T = .TRUE., F = .FALSE.
8771 DATA a / Z'F' /, b / Z'3' /
8773 WRITE (*,*) OR(T, T), OR(T, F), OR(F, T), OR(F, F)
8774 WRITE (*,*) OR(a, b)
8778 @item @emph{See also}:
8779 Fortran 95 elemental function: @ref{IOR}
8785 @section @code{PACK} --- Pack an array into an array of rank one
8787 @cindex array, packing
8788 @cindex array, reduce dimension
8789 @cindex array, gather elements
8792 @item @emph{Description}:
8793 Stores the elements of @var{ARRAY} in an array of rank one.
8795 The beginning of the resulting array is made up of elements whose @var{MASK}
8796 equals @code{TRUE}. Afterwards, positions are filled with elements taken from
8799 @item @emph{Standard}:
8800 Fortran 95 and later
8803 Transformational function
8805 @item @emph{Syntax}:
8806 @code{RESULT = PACK(ARRAY, MASK[,VECTOR]}
8808 @item @emph{Arguments}:
8809 @multitable @columnfractions .15 .70
8810 @item @var{ARRAY} @tab Shall be an array of any type.
8811 @item @var{MASK} @tab Shall be an array of type @code{LOGICAL} and
8812 of the same size as @var{ARRAY}. Alternatively, it may be a @code{LOGICAL}
8814 @item @var{VECTOR} @tab (Optional) shall be an array of the same type
8815 as @var{ARRAY} and of rank one. If present, the number of elements in
8816 @var{VECTOR} shall be equal to or greater than the number of true elements
8817 in @var{MASK}. If @var{MASK} is scalar, the number of elements in
8818 @var{VECTOR} shall be equal to or greater than the number of elements in
8822 @item @emph{Return value}:
8823 The result is an array of rank one and the same type as that of @var{ARRAY}.
8824 If @var{VECTOR} is present, the result size is that of @var{VECTOR}, the
8825 number of @code{TRUE} values in @var{MASK} otherwise.
8827 @item @emph{Example}:
8828 Gathering nonzero elements from an array:
8832 m = (/ 1, 0, 0, 0, 5, 0 /)
8833 WRITE(*, FMT="(6(I0, ' '))") pack(m, m /= 0) ! "1 5"
8837 Gathering nonzero elements from an array and appending elements from @var{VECTOR}:
8841 m = (/ 1, 0, 0, 2 /)
8842 WRITE(*, FMT="(4(I0, ' '))") pack(m, m /= 0, (/ 0, 0, 3, 4 /)) ! "1 2 3 4"
8846 @item @emph{See also}:
8853 @section @code{PARITY} --- Reduction with exclusive OR
8856 @cindex Reduction, XOR
8857 @cindex XOR reduction
8860 @item @emph{Description}:
8861 Calculates the partity, i.e. the reduction using @code{.XOR.},
8862 of @var{MASK} along dimension @var{DIM}.
8864 @item @emph{Standard}:
8865 Fortran 2008 and later
8868 Transformational function
8870 @item @emph{Syntax}:
8871 @multitable @columnfractions .80
8872 @item @code{RESULT = PARITY(MASK[, DIM])}
8875 @item @emph{Arguments}:
8876 @multitable @columnfractions .15 .70
8877 @item @var{LOGICAL} @tab Shall be an array of type @code{LOGICAL}
8878 @item @var{DIM} @tab (Optional) shall be a scalar of type
8879 @code{INTEGER} with a value in the range from 1 to n, where n
8880 equals the rank of @var{MASK}.
8883 @item @emph{Return value}:
8884 The result is of the same type as @var{MASK}.
8886 If @var{DIM} is absent, a scalar with the parity of all elements in
8887 @var{MASK} is returned, i.e. true if an odd number of elements is
8888 @code{.true.} and false otherwise. If @var{DIM} is present, an array
8889 of rank @math{n-1}, where @math{n} equals the rank of @var{ARRAY},
8890 and a shape similar to that of @var{MASK} with dimension @var{DIM}
8891 dropped is returned.
8893 @item @emph{Example}:
8896 LOGICAL :: x(2) = [ .true., .false. ]
8897 print *, PARITY(x) ! prints "T" (true).
8905 @section @code{PERROR} --- Print system error message
8907 @cindex system, error handling
8910 @item @emph{Description}:
8911 Prints (on the C @code{stderr} stream) a newline-terminated error
8912 message corresponding to the last system error. This is prefixed by
8913 @var{STRING}, a colon and a space. See @code{perror(3)}.
8915 @item @emph{Standard}:
8921 @item @emph{Syntax}:
8922 @code{CALL PERROR(STRING)}
8924 @item @emph{Arguments}:
8925 @multitable @columnfractions .15 .70
8926 @item @var{STRING} @tab A scalar of type @code{CHARACTER} and of the
8930 @item @emph{See also}:
8937 @section @code{PRECISION} --- Decimal precision of a real kind
8939 @cindex model representation, precision
8942 @item @emph{Description}:
8943 @code{PRECISION(X)} returns the decimal precision in the model of the
8946 @item @emph{Standard}:
8947 Fortran 95 and later
8952 @item @emph{Syntax}:
8953 @code{RESULT = PRECISION(X)}
8955 @item @emph{Arguments}:
8956 @multitable @columnfractions .15 .70
8957 @item @var{X} @tab Shall be of type @code{REAL} or @code{COMPLEX}.
8960 @item @emph{Return value}:
8961 The return value is of type @code{INTEGER} and of the default integer
8964 @item @emph{See also}:
8965 @ref{SELECTED_REAL_KIND}, @ref{RANGE}
8967 @item @emph{Example}:
8969 program prec_and_range
8970 real(kind=4) :: x(2)
8971 complex(kind=8) :: y
8973 print *, precision(x), range(x)
8974 print *, precision(y), range(y)
8975 end program prec_and_range
8982 @section @code{POPCNT} --- Number of bits set
8984 @cindex binary representation
8988 @item @emph{Description}:
8989 @code{POPCNT(I)} returns the number of bits set ('1' bits) in the binary
8990 representation of @code{I}.
8992 @item @emph{Standard}:
8993 Fortran 2008 and later
8998 @item @emph{Syntax}:
8999 @code{RESULT = POPCNT(I)}
9001 @item @emph{Arguments}:
9002 @multitable @columnfractions .15 .70
9003 @item @var{I} @tab Shall be of type @code{INTEGER}.
9006 @item @emph{Return value}:
9007 The return value is of type @code{INTEGER} and of the default integer
9010 @item @emph{See also}:
9011 @ref{POPPAR}, @ref{LEADZ}, @ref{TRAILZ}
9013 @item @emph{Example}:
9015 program test_population
9016 print *, popcnt(127), poppar(127)
9017 print *, popcnt(huge(0_4)), poppar(huge(0_4))
9018 print *, popcnt(huge(0_8)), poppar(huge(0_8))
9019 end program test_population
9025 @section @code{POPPAR} --- Parity of the number of bits set
9027 @cindex binary representation
9031 @item @emph{Description}:
9032 @code{POPPAR(I)} returns parity of the integer @code{I}, i.e. the parity
9033 of the number of bits set ('1' bits) in the binary representation of
9034 @code{I}. It is equal to 0 if @code{I} has an even number of bits set,
9035 and 1 for an odd number of '1' bits.
9037 @item @emph{Standard}:
9038 Fortran 2008 and later
9043 @item @emph{Syntax}:
9044 @code{RESULT = POPPAR(I)}
9046 @item @emph{Arguments}:
9047 @multitable @columnfractions .15 .70
9048 @item @var{I} @tab Shall be of type @code{INTEGER}.
9051 @item @emph{Return value}:
9052 The return value is of type @code{INTEGER} and of the default integer
9055 @item @emph{See also}:
9056 @ref{POPCNT}, @ref{LEADZ}, @ref{TRAILZ}
9058 @item @emph{Example}:
9060 program test_population
9061 print *, popcnt(127), poppar(127)
9062 print *, popcnt(huge(0_4)), poppar(huge(0_4))
9063 print *, popcnt(huge(0_8)), poppar(huge(0_8))
9064 end program test_population
9071 @section @code{PRESENT} --- Determine whether an optional dummy argument is specified
9075 @item @emph{Description}:
9076 Determines whether an optional dummy argument is present.
9078 @item @emph{Standard}:
9079 Fortran 95 and later
9084 @item @emph{Syntax}:
9085 @code{RESULT = PRESENT(A)}
9087 @item @emph{Arguments}:
9088 @multitable @columnfractions .15 .70
9089 @item @var{A} @tab May be of any type and may be a pointer, scalar or array
9090 value, or a dummy procedure. It shall be the name of an optional dummy argument
9091 accessible within the current subroutine or function.
9094 @item @emph{Return value}:
9095 Returns either @code{TRUE} if the optional argument @var{A} is present, or
9096 @code{FALSE} otherwise.
9098 @item @emph{Example}:
9100 PROGRAM test_present
9101 WRITE(*,*) f(), f(42) ! "F T"
9103 LOGICAL FUNCTION f(x)
9104 INTEGER, INTENT(IN), OPTIONAL :: x
9114 @section @code{PRODUCT} --- Product of array elements
9116 @cindex array, product
9117 @cindex array, multiply elements
9118 @cindex array, conditionally multiply elements
9119 @cindex multiply array elements
9122 @item @emph{Description}:
9123 Multiplies the elements of @var{ARRAY} along dimension @var{DIM} if
9124 the corresponding element in @var{MASK} is @code{TRUE}.
9126 @item @emph{Standard}:
9127 Fortran 95 and later
9130 Transformational function
9132 @item @emph{Syntax}:
9133 @multitable @columnfractions .80
9134 @item @code{RESULT = PRODUCT(ARRAY[, MASK])}
9135 @item @code{RESULT = PRODUCT(ARRAY, DIM[, MASK])}
9138 @item @emph{Arguments}:
9139 @multitable @columnfractions .15 .70
9140 @item @var{ARRAY} @tab Shall be an array of type @code{INTEGER},
9141 @code{REAL} or @code{COMPLEX}.
9142 @item @var{DIM} @tab (Optional) shall be a scalar of type
9143 @code{INTEGER} with a value in the range from 1 to n, where n
9144 equals the rank of @var{ARRAY}.
9145 @item @var{MASK} @tab (Optional) shall be of type @code{LOGICAL}
9146 and either be a scalar or an array of the same shape as @var{ARRAY}.
9149 @item @emph{Return value}:
9150 The result is of the same type as @var{ARRAY}.
9152 If @var{DIM} is absent, a scalar with the product of all elements in
9153 @var{ARRAY} is returned. Otherwise, an array of rank n-1, where n equals
9154 the rank of @var{ARRAY}, and a shape similar to that of @var{ARRAY} with
9155 dimension @var{DIM} dropped is returned.
9158 @item @emph{Example}:
9160 PROGRAM test_product
9161 INTEGER :: x(5) = (/ 1, 2, 3, 4 ,5 /)
9162 print *, PRODUCT(x) ! all elements, product = 120
9163 print *, PRODUCT(x, MASK=MOD(x, 2)==1) ! odd elements, product = 15
9167 @item @emph{See also}:
9174 @section @code{RADIX} --- Base of a model number
9176 @cindex model representation, base
9177 @cindex model representation, radix
9180 @item @emph{Description}:
9181 @code{RADIX(X)} returns the base of the model representing the entity @var{X}.
9183 @item @emph{Standard}:
9184 Fortran 95 and later
9189 @item @emph{Syntax}:
9190 @code{RESULT = RADIX(X)}
9192 @item @emph{Arguments}:
9193 @multitable @columnfractions .15 .70
9194 @item @var{X} @tab Shall be of type @code{INTEGER} or @code{REAL}
9197 @item @emph{Return value}:
9198 The return value is a scalar of type @code{INTEGER} and of the default
9201 @item @emph{See also}:
9202 @ref{SELECTED_REAL_KIND}
9204 @item @emph{Example}:
9207 print *, "The radix for the default integer kind is", radix(0)
9208 print *, "The radix for the default real kind is", radix(0.0)
9209 end program test_radix
9217 @section @code{RAN} --- Real pseudo-random number
9219 @cindex random number generation
9222 @item @emph{Description}:
9223 For compatibility with HP FORTRAN 77/iX, the @code{RAN} intrinsic is
9224 provided as an alias for @code{RAND}. See @ref{RAND} for complete
9227 @item @emph{Standard}:
9233 @item @emph{See also}:
9234 @ref{RAND}, @ref{RANDOM_NUMBER}
9240 @section @code{RAND} --- Real pseudo-random number
9242 @cindex random number generation
9245 @item @emph{Description}:
9246 @code{RAND(FLAG)} returns a pseudo-random number from a uniform
9247 distribution between 0 and 1. If @var{FLAG} is 0, the next number
9248 in the current sequence is returned; if @var{FLAG} is 1, the generator
9249 is restarted by @code{CALL SRAND(0)}; if @var{FLAG} has any other value,
9250 it is used as a new seed with @code{SRAND}.
9252 This intrinsic routine is provided for backwards compatibility with
9253 GNU Fortran 77. It implements a simple modulo generator as provided
9254 by @command{g77}. For new code, one should consider the use of
9255 @ref{RANDOM_NUMBER} as it implements a superior algorithm.
9257 @item @emph{Standard}:
9263 @item @emph{Syntax}:
9264 @code{RESULT = RAND(I)}
9266 @item @emph{Arguments}:
9267 @multitable @columnfractions .15 .70
9268 @item @var{I} @tab Shall be a scalar @code{INTEGER} of kind 4.
9271 @item @emph{Return value}:
9272 The return value is of @code{REAL} type and the default kind.
9274 @item @emph{Example}:
9277 integer,parameter :: seed = 86456
9280 print *, rand(), rand(), rand(), rand()
9281 print *, rand(seed), rand(), rand(), rand()
9282 end program test_rand
9285 @item @emph{See also}:
9286 @ref{SRAND}, @ref{RANDOM_NUMBER}
9293 @section @code{RANDOM_NUMBER} --- Pseudo-random number
9294 @fnindex RANDOM_NUMBER
9295 @cindex random number generation
9298 @item @emph{Description}:
9299 Returns a single pseudorandom number or an array of pseudorandom numbers
9300 from the uniform distribution over the range @math{ 0 \leq x < 1}.
9302 The runtime-library implements George Marsaglia's KISS (Keep It Simple
9303 Stupid) random number generator (RNG). This RNG combines:
9305 @item The congruential generator @math{x(n) = 69069 \cdot x(n-1) + 1327217885}
9306 with a period of @math{2^{32}},
9307 @item A 3-shift shift-register generator with a period of @math{2^{32} - 1},
9308 @item Two 16-bit multiply-with-carry generators with a period of
9309 @math{597273182964842497 > 2^{59}}.
9311 The overall period exceeds @math{2^{123}}.
9313 Please note, this RNG is thread safe if used within OpenMP directives,
9314 i.e., its state will be consistent while called from multiple threads.
9315 However, the KISS generator does not create random numbers in parallel
9316 from multiple sources, but in sequence from a single source. If an
9317 OpenMP-enabled application heavily relies on random numbers, one should
9318 consider employing a dedicated parallel random number generator instead.
9320 @item @emph{Standard}:
9321 Fortran 95 and later
9326 @item @emph{Syntax}:
9327 @code{RANDOM_NUMBER(HARVEST)}
9329 @item @emph{Arguments}:
9330 @multitable @columnfractions .15 .70
9331 @item @var{HARVEST} @tab Shall be a scalar or an array of type @code{REAL}.
9334 @item @emph{Example}:
9336 program test_random_number
9338 CALL init_random_seed() ! see example of RANDOM_SEED
9339 CALL RANDOM_NUMBER(r)
9343 @item @emph{See also}:
9350 @section @code{RANDOM_SEED} --- Initialize a pseudo-random number sequence
9351 @fnindex RANDOM_SEED
9352 @cindex random number generation, seeding
9353 @cindex seeding a random number generator
9356 @item @emph{Description}:
9357 Restarts or queries the state of the pseudorandom number generator used by
9358 @code{RANDOM_NUMBER}.
9360 If @code{RANDOM_SEED} is called without arguments, it is initialized to
9361 a default state. The example below shows how to initialize the random
9362 seed based on the system's time.
9364 @item @emph{Standard}:
9365 Fortran 95 and later
9370 @item @emph{Syntax}:
9371 @code{CALL RANDOM_SEED([SIZE, PUT, GET])}
9373 @item @emph{Arguments}:
9374 @multitable @columnfractions .15 .70
9375 @item @var{SIZE} @tab (Optional) Shall be a scalar and of type default
9376 @code{INTEGER}, with @code{INTENT(OUT)}. It specifies the minimum size
9377 of the arrays used with the @var{PUT} and @var{GET} arguments.
9378 @item @var{PUT} @tab (Optional) Shall be an array of type default
9379 @code{INTEGER} and rank one. It is @code{INTENT(IN)} and the size of
9380 the array must be larger than or equal to the number returned by the
9381 @var{SIZE} argument.
9382 @item @var{GET} @tab (Optional) Shall be an array of type default
9383 @code{INTEGER} and rank one. It is @code{INTENT(OUT)} and the size
9384 of the array must be larger than or equal to the number returned by
9385 the @var{SIZE} argument.
9388 @item @emph{Example}:
9390 SUBROUTINE init_random_seed()
9391 INTEGER :: i, n, clock
9392 INTEGER, DIMENSION(:), ALLOCATABLE :: seed
9394 CALL RANDOM_SEED(size = n)
9397 CALL SYSTEM_CLOCK(COUNT=clock)
9399 seed = clock + 37 * (/ (i - 1, i = 1, n) /)
9400 CALL RANDOM_SEED(PUT = seed)
9406 @item @emph{See also}:
9413 @section @code{RANGE} --- Decimal exponent range
9415 @cindex model representation, range
9418 @item @emph{Description}:
9419 @code{RANGE(X)} returns the decimal exponent range in the model of the
9422 @item @emph{Standard}:
9423 Fortran 95 and later
9428 @item @emph{Syntax}:
9429 @code{RESULT = RANGE(X)}
9431 @item @emph{Arguments}:
9432 @multitable @columnfractions .15 .70
9433 @item @var{X} @tab Shall be of type @code{INTEGER}, @code{REAL}
9437 @item @emph{Return value}:
9438 The return value is of type @code{INTEGER} and of the default integer
9441 @item @emph{See also}:
9442 @ref{SELECTED_REAL_KIND}, @ref{PRECISION}
9444 @item @emph{Example}:
9445 See @code{PRECISION} for an example.
9451 @section @code{REAL} --- Convert to real type
9457 @cindex conversion, to real
9458 @cindex complex numbers, real part
9461 @item @emph{Description}:
9462 @code{REAL(A [, KIND])} converts its argument @var{A} to a real type. The
9463 @code{REALPART} function is provided for compatibility with @command{g77},
9464 and its use is strongly discouraged.
9466 @item @emph{Standard}:
9467 Fortran 77 and later
9472 @item @emph{Syntax}:
9473 @multitable @columnfractions .80
9474 @item @code{RESULT = REAL(A [, KIND])}
9475 @item @code{RESULT = REALPART(Z)}
9478 @item @emph{Arguments}:
9479 @multitable @columnfractions .15 .70
9480 @item @var{A} @tab Shall be @code{INTEGER}, @code{REAL}, or
9482 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
9483 expression indicating the kind parameter of the result.
9486 @item @emph{Return value}:
9487 These functions return a @code{REAL} variable or array under
9488 the following rules:
9492 @code{REAL(A)} is converted to a default real type if @var{A} is an
9493 integer or real variable.
9495 @code{REAL(A)} is converted to a real type with the kind type parameter
9496 of @var{A} if @var{A} is a complex variable.
9498 @code{REAL(A, KIND)} is converted to a real type with kind type
9499 parameter @var{KIND} if @var{A} is a complex, integer, or real
9503 @item @emph{Example}:
9506 complex :: x = (1.0, 2.0)
9507 print *, real(x), real(x,8), realpart(x)
9508 end program test_real
9511 @item @emph{Specific names}:
9512 @multitable @columnfractions .20 .20 .20 .25
9513 @item Name @tab Argument @tab Return type @tab Standard
9514 @item @code{FLOAT(A)} @tab @code{INTEGER(4)} @tab @code{REAL(4)} @tab Fortran 77 and later
9515 @item @code{DFLOAT(A)} @tab @code{INTEGER(4)} @tab @code{REAL(8)} @tab GNU extension
9516 @item @code{SNGL(A)} @tab @code{INTEGER(8)} @tab @code{REAL(4)} @tab Fortran 77 and later
9520 @item @emph{See also}:
9528 @section @code{RENAME} --- Rename a file
9530 @cindex file system, rename file
9533 @item @emph{Description}:
9534 Renames a file from file @var{PATH1} to @var{PATH2}. A null
9535 character (@code{CHAR(0)}) can be used to mark the end of the names in
9536 @var{PATH1} and @var{PATH2}; otherwise, trailing blanks in the file
9537 names are ignored. If the @var{STATUS} argument is supplied, it
9538 contains 0 on success or a nonzero error code upon return; see
9541 This intrinsic is provided in both subroutine and function forms;
9542 however, only one form can be used in any given program unit.
9544 @item @emph{Standard}:
9548 Subroutine, function
9550 @item @emph{Syntax}:
9551 @multitable @columnfractions .80
9552 @item @code{CALL RENAME(PATH1, PATH2 [, STATUS])}
9553 @item @code{STATUS = RENAME(PATH1, PATH2)}
9556 @item @emph{Arguments}:
9557 @multitable @columnfractions .15 .70
9558 @item @var{PATH1} @tab Shall be of default @code{CHARACTER} type.
9559 @item @var{PATH2} @tab Shall be of default @code{CHARACTER} type.
9560 @item @var{STATUS} @tab (Optional) Shall be of default @code{INTEGER} type.
9563 @item @emph{See also}:
9571 @section @code{REPEAT} --- Repeated string concatenation
9573 @cindex string, repeat
9574 @cindex string, concatenate
9577 @item @emph{Description}:
9578 Concatenates @var{NCOPIES} copies of a string.
9580 @item @emph{Standard}:
9581 Fortran 95 and later
9584 Transformational function
9586 @item @emph{Syntax}:
9587 @code{RESULT = REPEAT(STRING, NCOPIES)}
9589 @item @emph{Arguments}:
9590 @multitable @columnfractions .15 .70
9591 @item @var{STRING} @tab Shall be scalar and of type @code{CHARACTER}.
9592 @item @var{NCOPIES} @tab Shall be scalar and of type @code{INTEGER}.
9595 @item @emph{Return value}:
9596 A new scalar of type @code{CHARACTER} built up from @var{NCOPIES} copies
9599 @item @emph{Example}:
9602 write(*,*) repeat("x", 5) ! "xxxxx"
9610 @section @code{RESHAPE} --- Function to reshape an array
9612 @cindex array, change dimensions
9613 @cindex array, transmogrify
9616 @item @emph{Description}:
9617 Reshapes @var{SOURCE} to correspond to @var{SHAPE}. If necessary,
9618 the new array may be padded with elements from @var{PAD} or permuted
9619 as defined by @var{ORDER}.
9621 @item @emph{Standard}:
9622 Fortran 95 and later
9625 Transformational function
9627 @item @emph{Syntax}:
9628 @code{RESULT = RESHAPE(SOURCE, SHAPE[, PAD, ORDER])}
9630 @item @emph{Arguments}:
9631 @multitable @columnfractions .15 .70
9632 @item @var{SOURCE} @tab Shall be an array of any type.
9633 @item @var{SHAPE} @tab Shall be of type @code{INTEGER} and an
9634 array of rank one. Its values must be positive or zero.
9635 @item @var{PAD} @tab (Optional) shall be an array of the same
9636 type as @var{SOURCE}.
9637 @item @var{ORDER} @tab (Optional) shall be of type @code{INTEGER}
9638 and an array of the same shape as @var{SHAPE}. Its values shall
9639 be a permutation of the numbers from 1 to n, where n is the size of
9640 @var{SHAPE}. If @var{ORDER} is absent, the natural ordering shall
9644 @item @emph{Return value}:
9645 The result is an array of shape @var{SHAPE} with the same type as
9648 @item @emph{Example}:
9650 PROGRAM test_reshape
9651 INTEGER, DIMENSION(4) :: x
9652 WRITE(*,*) SHAPE(x) ! prints "4"
9653 WRITE(*,*) SHAPE(RESHAPE(x, (/2, 2/))) ! prints "2 2"
9657 @item @emph{See also}:
9664 @section @code{RRSPACING} --- Reciprocal of the relative spacing
9666 @cindex real number, relative spacing
9667 @cindex floating point, relative spacing
9671 @item @emph{Description}:
9672 @code{RRSPACING(X)} returns the reciprocal of the relative spacing of
9673 model numbers near @var{X}.
9675 @item @emph{Standard}:
9676 Fortran 95 and later
9681 @item @emph{Syntax}:
9682 @code{RESULT = RRSPACING(X)}
9684 @item @emph{Arguments}:
9685 @multitable @columnfractions .15 .70
9686 @item @var{X} @tab Shall be of type @code{REAL}.
9689 @item @emph{Return value}:
9690 The return value is of the same type and kind as @var{X}.
9691 The value returned is equal to
9692 @code{ABS(FRACTION(X)) * FLOAT(RADIX(X))**DIGITS(X)}.
9694 @item @emph{See also}:
9701 @section @code{RSHIFT} --- Right shift bits
9703 @cindex bits, shift right
9706 @item @emph{Description}:
9707 @code{RSHIFT} returns a value corresponding to @var{I} with all of the
9708 bits shifted right by @var{SHIFT} places. If the absolute value of
9709 @var{SHIFT} is greater than @code{BIT_SIZE(I)}, the value is undefined.
9710 Bits shifted out from the left end are lost; zeros are shifted in from
9713 This function has been superseded by the @code{ISHFT} intrinsic, which
9714 is standard in Fortran 95 and later.
9716 @item @emph{Standard}:
9722 @item @emph{Syntax}:
9723 @code{RESULT = RSHIFT(I, SHIFT)}
9725 @item @emph{Arguments}:
9726 @multitable @columnfractions .15 .70
9727 @item @var{I} @tab The type shall be @code{INTEGER}.
9728 @item @var{SHIFT} @tab The type shall be @code{INTEGER}.
9731 @item @emph{Return value}:
9732 The return value is of type @code{INTEGER} and of the same kind as
9735 @item @emph{See also}:
9736 @ref{ISHFT}, @ref{ISHFTC}, @ref{LSHIFT}
9743 @section @code{SAME_TYPE_AS} --- Query dynamic types for equality
9744 @fnindex SAME_TYPE_AS
9747 @item @emph{Description}:
9748 Query dynamic types for equality.
9750 @item @emph{Standard}:
9751 Fortran 2003 and later
9756 @item @emph{Syntax}:
9757 @code{RESULT = SAME_TYPE_AS(A, B)}
9759 @item @emph{Arguments}:
9760 @multitable @columnfractions .15 .70
9761 @item @var{A} @tab Shall be an object of extensible declared type or
9762 unlimited polymorphic.
9763 @item @var{B} @tab Shall be an object of extensible declared type or
9764 unlimited polymorphic.
9767 @item @emph{Return value}:
9768 The return value is a scalar of type default logical. It is true if and
9769 only if the dynamic type of A is the same as the dynamic type of B.
9771 @item @emph{See also}:
9772 @ref{EXTENDS_TYPE_OF}
9779 @section @code{SCALE} --- Scale a real value
9781 @cindex real number, scale
9782 @cindex floating point, scale
9785 @item @emph{Description}:
9786 @code{SCALE(X,I)} returns @code{X * RADIX(X)**I}.
9788 @item @emph{Standard}:
9789 Fortran 95 and later
9794 @item @emph{Syntax}:
9795 @code{RESULT = SCALE(X, I)}
9797 @item @emph{Arguments}:
9798 @multitable @columnfractions .15 .70
9799 @item @var{X} @tab The type of the argument shall be a @code{REAL}.
9800 @item @var{I} @tab The type of the argument shall be a @code{INTEGER}.
9803 @item @emph{Return value}:
9804 The return value is of the same type and kind as @var{X}.
9805 Its value is @code{X * RADIX(X)**I}.
9807 @item @emph{Example}:
9810 real :: x = 178.1387e-4
9812 print *, scale(x,i), x*radix(x)**i
9813 end program test_scale
9821 @section @code{SCAN} --- Scan a string for the presence of a set of characters
9823 @cindex string, find subset
9826 @item @emph{Description}:
9827 Scans a @var{STRING} for any of the characters in a @var{SET}
9830 If @var{BACK} is either absent or equals @code{FALSE}, this function
9831 returns the position of the leftmost character of @var{STRING} that is
9832 in @var{SET}. If @var{BACK} equals @code{TRUE}, the rightmost position
9833 is returned. If no character of @var{SET} is found in @var{STRING}, the
9836 @item @emph{Standard}:
9837 Fortran 95 and later, with @var{KIND} argument Fortran 2003 and later
9842 @item @emph{Syntax}:
9843 @code{RESULT = SCAN(STRING, SET[, BACK [, KIND]])}
9845 @item @emph{Arguments}:
9846 @multitable @columnfractions .15 .70
9847 @item @var{STRING} @tab Shall be of type @code{CHARACTER}.
9848 @item @var{SET} @tab Shall be of type @code{CHARACTER}.
9849 @item @var{BACK} @tab (Optional) shall be of type @code{LOGICAL}.
9850 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
9851 expression indicating the kind parameter of the result.
9854 @item @emph{Return value}:
9855 The return value is of type @code{INTEGER} and of kind @var{KIND}. If
9856 @var{KIND} is absent, the return value is of default integer kind.
9858 @item @emph{Example}:
9861 WRITE(*,*) SCAN("FORTRAN", "AO") ! 2, found 'O'
9862 WRITE(*,*) SCAN("FORTRAN", "AO", .TRUE.) ! 6, found 'A'
9863 WRITE(*,*) SCAN("FORTRAN", "C++") ! 0, found none
9867 @item @emph{See also}:
9868 @ref{INDEX intrinsic}, @ref{VERIFY}
9874 @section @code{SECNDS} --- Time function
9876 @cindex time, elapsed
9877 @cindex elapsed time
9880 @item @emph{Description}:
9881 @code{SECNDS(X)} gets the time in seconds from the real-time system clock.
9882 @var{X} is a reference time, also in seconds. If this is zero, the time in
9883 seconds from midnight is returned. This function is non-standard and its
9886 @item @emph{Standard}:
9892 @item @emph{Syntax}:
9893 @code{RESULT = SECNDS (X)}
9895 @item @emph{Arguments}:
9896 @multitable @columnfractions .15 .70
9897 @item @var{T} @tab Shall be of type @code{REAL(4)}.
9898 @item @var{X} @tab Shall be of type @code{REAL(4)}.
9901 @item @emph{Return value}:
9904 @item @emph{Example}:
9909 print *, secnds (0.0) ! seconds since midnight
9910 t1 = secnds (0.0) ! reference time
9911 do i = 1, 10000000 ! do something
9913 t2 = secnds (t1) ! elapsed time
9914 print *, "Something took ", t2, " seconds."
9915 end program test_secnds
9922 @section @code{SECOND} --- CPU time function
9924 @cindex time, elapsed
9925 @cindex elapsed time
9928 @item @emph{Description}:
9929 Returns a @code{REAL(4)} value representing the elapsed CPU time in
9930 seconds. This provides the same functionality as the standard
9931 @code{CPU_TIME} intrinsic, and is only included for backwards
9934 This intrinsic is provided in both subroutine and function forms;
9935 however, only one form can be used in any given program unit.
9937 @item @emph{Standard}:
9941 Subroutine, function
9943 @item @emph{Syntax}:
9944 @multitable @columnfractions .80
9945 @item @code{CALL SECOND(TIME)}
9946 @item @code{TIME = SECOND()}
9949 @item @emph{Arguments}:
9950 @multitable @columnfractions .15 .70
9951 @item @var{TIME} @tab Shall be of type @code{REAL(4)}.
9954 @item @emph{Return value}:
9955 In either syntax, @var{TIME} is set to the process's current runtime in
9958 @item @emph{See also}:
9965 @node SELECTED_CHAR_KIND
9966 @section @code{SELECTED_CHAR_KIND} --- Choose character kind
9967 @fnindex SELECTED_CHAR_KIND
9968 @cindex character kind
9969 @cindex kind, character
9972 @item @emph{Description}:
9974 @code{SELECTED_CHAR_KIND(NAME)} returns the kind value for the character
9975 set named @var{NAME}, if a character set with such a name is supported,
9976 or @math{-1} otherwise. Currently, supported character sets include
9977 ``ASCII'' and ``DEFAULT'', which are equivalent, and ``ISO_10646''
9978 (Universal Character Set, UCS-4) which is commonly known as Unicode.
9980 @item @emph{Standard}:
9981 Fortran 2003 and later
9984 Transformational function
9986 @item @emph{Syntax}:
9987 @code{RESULT = SELECTED_CHAR_KIND(NAME)}
9989 @item @emph{Arguments}:
9990 @multitable @columnfractions .15 .70
9991 @item @var{NAME} @tab Shall be a scalar and of the default character type.
9994 @item @emph{Example}:
9996 program character_kind
9999 integer, parameter :: ascii = selected_char_kind ("ascii")
10000 integer, parameter :: ucs4 = selected_char_kind ('ISO_10646')
10002 character(kind=ascii, len=26) :: alphabet
10003 character(kind=ucs4, len=30) :: hello_world
10005 alphabet = ascii_"abcdefghijklmnopqrstuvwxyz"
10006 hello_world = ucs4_'Hello World and Ni Hao -- ' &
10007 // char (int (z'4F60'), ucs4) &
10008 // char (int (z'597D'), ucs4)
10010 write (*,*) alphabet
10012 open (output_unit, encoding='UTF-8')
10013 write (*,*) trim (hello_world)
10014 end program character_kind
10020 @node SELECTED_INT_KIND
10021 @section @code{SELECTED_INT_KIND} --- Choose integer kind
10022 @fnindex SELECTED_INT_KIND
10023 @cindex integer kind
10024 @cindex kind, integer
10027 @item @emph{Description}:
10028 @code{SELECTED_INT_KIND(R)} return the kind value of the smallest integer
10029 type that can represent all values ranging from @math{-10^R} (exclusive)
10030 to @math{10^R} (exclusive). If there is no integer kind that accommodates
10031 this range, @code{SELECTED_INT_KIND} returns @math{-1}.
10033 @item @emph{Standard}:
10034 Fortran 95 and later
10036 @item @emph{Class}:
10037 Transformational function
10039 @item @emph{Syntax}:
10040 @code{RESULT = SELECTED_INT_KIND(R)}
10042 @item @emph{Arguments}:
10043 @multitable @columnfractions .15 .70
10044 @item @var{R} @tab Shall be a scalar and of type @code{INTEGER}.
10047 @item @emph{Example}:
10049 program large_integers
10050 integer,parameter :: k5 = selected_int_kind(5)
10051 integer,parameter :: k15 = selected_int_kind(15)
10052 integer(kind=k5) :: i5
10053 integer(kind=k15) :: i15
10055 print *, huge(i5), huge(i15)
10057 ! The following inequalities are always true
10058 print *, huge(i5) >= 10_k5**5-1
10059 print *, huge(i15) >= 10_k15**15-1
10060 end program large_integers
10066 @node SELECTED_REAL_KIND
10067 @section @code{SELECTED_REAL_KIND} --- Choose real kind
10068 @fnindex SELECTED_REAL_KIND
10071 @cindex radix, real
10074 @item @emph{Description}:
10075 @code{SELECTED_REAL_KIND(P,R)} returns the kind value of a real data type
10076 with decimal precision of at least @code{P} digits, exponent range of
10077 at least @code{R}, and with a radix of @code{RADIX}.
10079 @item @emph{Standard}:
10080 Fortran 95 and later, with @code{RADIX} Fortran 2008 or later
10082 @item @emph{Class}:
10083 Transformational function
10085 @item @emph{Syntax}:
10086 @code{RESULT = SELECTED_REAL_KIND([P, R, RADIX])}
10088 @item @emph{Arguments}:
10089 @multitable @columnfractions .15 .70
10090 @item @var{P} @tab (Optional) shall be a scalar and of type @code{INTEGER}.
10091 @item @var{R} @tab (Optional) shall be a scalar and of type @code{INTEGER}.
10092 @item @var{RADIX} @tab (Optional) shall be a scalar and of type @code{INTEGER}.
10094 Before Fortran 2008, at least one of the arguments @var{R} or @var{P} shall
10095 be present; since Fortran 2008, they are assumed to be zero if absent.
10097 @item @emph{Return value}:
10099 @code{SELECTED_REAL_KIND} returns the value of the kind type parameter of
10100 a real data type with decimal precision of at least @code{P} digits, a
10101 decimal exponent range of at least @code{R}, and with the requested
10102 @code{RADIX}. If the @code{RADIX} parameter is absent, real kinds with
10103 any radix can be returned. If more than one real data type meet the
10104 criteria, the kind of the data type with the smallest decimal precision
10105 is returned. If no real data type matches the criteria, the result is
10107 @item -1 if the processor does not support a real data type with a
10108 precision greater than or equal to @code{P}, but the @code{R} and
10109 @code{RADIX} requirements can be fulfilled
10110 @item -2 if the processor does not support a real type with an exponent
10111 range greater than or equal to @code{R}, but @code{P} and @code{RADIX}
10113 @item -3 if @code{RADIX} but not @code{P} and @code{R} requirements
10115 @item -4 if @code{RADIX} and either @code{P} or @code{R} requirements
10117 @item -5 if there is no real type with the given @code{RADIX}
10120 @item @emph{See also}:
10121 @ref{PRECISION}, @ref{RANGE}, @ref{RADIX}
10123 @item @emph{Example}:
10126 integer,parameter :: p6 = selected_real_kind(6)
10127 integer,parameter :: p10r100 = selected_real_kind(10,100)
10128 integer,parameter :: r400 = selected_real_kind(r=400)
10130 real(kind=p10r100) :: y
10131 real(kind=r400) :: z
10133 print *, precision(x), range(x)
10134 print *, precision(y), range(y)
10135 print *, precision(z), range(z)
10136 end program real_kinds
10143 @section @code{SET_EXPONENT} --- Set the exponent of the model
10144 @fnindex SET_EXPONENT
10145 @cindex real number, set exponent
10146 @cindex floating point, set exponent
10149 @item @emph{Description}:
10150 @code{SET_EXPONENT(X, I)} returns the real number whose fractional part
10151 is that that of @var{X} and whose exponent part is @var{I}.
10153 @item @emph{Standard}:
10154 Fortran 95 and later
10156 @item @emph{Class}:
10159 @item @emph{Syntax}:
10160 @code{RESULT = SET_EXPONENT(X, I)}
10162 @item @emph{Arguments}:
10163 @multitable @columnfractions .15 .70
10164 @item @var{X} @tab Shall be of type @code{REAL}.
10165 @item @var{I} @tab Shall be of type @code{INTEGER}.
10168 @item @emph{Return value}:
10169 The return value is of the same type and kind as @var{X}.
10170 The real number whose fractional part
10171 is that that of @var{X} and whose exponent part if @var{I} is returned;
10172 it is @code{FRACTION(X) * RADIX(X)**I}.
10174 @item @emph{Example}:
10176 PROGRAM test_setexp
10177 REAL :: x = 178.1387e-4
10179 PRINT *, SET_EXPONENT(x, i), FRACTION(x) * RADIX(x)**i
10188 @section @code{SHAPE} --- Determine the shape of an array
10190 @cindex array, shape
10193 @item @emph{Description}:
10194 Determines the shape of an array.
10196 @item @emph{Standard}:
10197 Fortran 95 and later
10199 @item @emph{Class}:
10202 @item @emph{Syntax}:
10203 @code{RESULT = SHAPE(SOURCE)}
10205 @item @emph{Arguments}:
10206 @multitable @columnfractions .15 .70
10207 @item @var{SOURCE} @tab Shall be an array or scalar of any type.
10208 If @var{SOURCE} is a pointer it must be associated and allocatable
10209 arrays must be allocated.
10212 @item @emph{Return value}:
10213 An @code{INTEGER} array of rank one with as many elements as @var{SOURCE}
10214 has dimensions. The elements of the resulting array correspond to the extend
10215 of @var{SOURCE} along the respective dimensions. If @var{SOURCE} is a scalar,
10216 the result is the rank one array of size zero.
10218 @item @emph{Example}:
10221 INTEGER, DIMENSION(-1:1, -1:2) :: A
10222 WRITE(*,*) SHAPE(A) ! (/ 3, 4 /)
10223 WRITE(*,*) SIZE(SHAPE(42)) ! (/ /)
10227 @item @emph{See also}:
10228 @ref{RESHAPE}, @ref{SIZE}
10234 @section @code{SIGN} --- Sign copying function
10238 @cindex sign copying
10241 @item @emph{Description}:
10242 @code{SIGN(A,B)} returns the value of @var{A} with the sign of @var{B}.
10244 @item @emph{Standard}:
10245 Fortran 77 and later
10247 @item @emph{Class}:
10250 @item @emph{Syntax}:
10251 @code{RESULT = SIGN(A, B)}
10253 @item @emph{Arguments}:
10254 @multitable @columnfractions .15 .70
10255 @item @var{A} @tab Shall be of type @code{INTEGER} or @code{REAL}
10256 @item @var{B} @tab Shall be of the same type and kind as @var{A}
10259 @item @emph{Return value}:
10260 The kind of the return value is that of @var{A} and @var{B}.
10261 If @math{B\ge 0} then the result is @code{ABS(A)}, else
10262 it is @code{-ABS(A)}.
10264 @item @emph{Example}:
10267 print *, sign(-12,1)
10268 print *, sign(-12,0)
10269 print *, sign(-12,-1)
10271 print *, sign(-12.,1.)
10272 print *, sign(-12.,0.)
10273 print *, sign(-12.,-1.)
10274 end program test_sign
10277 @item @emph{Specific names}:
10278 @multitable @columnfractions .20 .20 .20 .25
10279 @item Name @tab Arguments @tab Return type @tab Standard
10280 @item @code{SIGN(A,B)} @tab @code{REAL(4) A, B} @tab @code{REAL(4)} @tab f77, gnu
10281 @item @code{ISIGN(A,B)} @tab @code{INTEGER(4) A, B} @tab @code{INTEGER(4)} @tab f77, gnu
10282 @item @code{DSIGN(A,B)} @tab @code{REAL(8) A, B} @tab @code{REAL(8)} @tab f77, gnu
10289 @section @code{SIGNAL} --- Signal handling subroutine (or function)
10291 @cindex system, signal handling
10294 @item @emph{Description}:
10295 @code{SIGNAL(NUMBER, HANDLER [, STATUS])} causes external subroutine
10296 @var{HANDLER} to be executed with a single integer argument when signal
10297 @var{NUMBER} occurs. If @var{HANDLER} is an integer, it can be used to
10298 turn off handling of signal @var{NUMBER} or revert to its default
10299 action. See @code{signal(2)}.
10301 If @code{SIGNAL} is called as a subroutine and the @var{STATUS} argument
10302 is supplied, it is set to the value returned by @code{signal(2)}.
10304 @item @emph{Standard}:
10307 @item @emph{Class}:
10308 Subroutine, function
10310 @item @emph{Syntax}:
10311 @multitable @columnfractions .80
10312 @item @code{CALL SIGNAL(NUMBER, HANDLER [, STATUS])}
10313 @item @code{STATUS = SIGNAL(NUMBER, HANDLER)}
10316 @item @emph{Arguments}:
10317 @multitable @columnfractions .15 .70
10318 @item @var{NUMBER} @tab Shall be a scalar integer, with @code{INTENT(IN)}
10319 @item @var{HANDLER}@tab Signal handler (@code{INTEGER FUNCTION} or
10320 @code{SUBROUTINE}) or dummy/global @code{INTEGER} scalar.
10321 @code{INTEGER}. It is @code{INTENT(IN)}.
10322 @item @var{STATUS} @tab (Optional) @var{STATUS} shall be a scalar
10323 integer. It has @code{INTENT(OUT)}.
10325 @c TODO: What should the interface of the handler be? Does it take arguments?
10327 @item @emph{Return value}:
10328 The @code{SIGNAL} function returns the value returned by @code{signal(2)}.
10330 @item @emph{Example}:
10332 program test_signal
10334 external handler_print
10336 call signal (12, handler_print)
10337 call signal (10, 1)
10340 end program test_signal
10347 @section @code{SIN} --- Sine function
10353 @cindex trigonometric function, sine
10357 @item @emph{Description}:
10358 @code{SIN(X)} computes the sine of @var{X}.
10360 @item @emph{Standard}:
10361 Fortran 77 and later
10363 @item @emph{Class}:
10366 @item @emph{Syntax}:
10367 @code{RESULT = SIN(X)}
10369 @item @emph{Arguments}:
10370 @multitable @columnfractions .15 .70
10371 @item @var{X} @tab The type shall be @code{REAL} or
10375 @item @emph{Return value}:
10376 The return value has same type and kind as @var{X}.
10378 @item @emph{Example}:
10383 end program test_sin
10386 @item @emph{Specific names}:
10387 @multitable @columnfractions .20 .20 .20 .25
10388 @item Name @tab Argument @tab Return type @tab Standard
10389 @item @code{SIN(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab f77, gnu
10390 @item @code{DSIN(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab f95, gnu
10391 @item @code{CSIN(X)} @tab @code{COMPLEX(4) X} @tab @code{COMPLEX(4)} @tab f95, gnu
10392 @item @code{ZSIN(X)} @tab @code{COMPLEX(8) X} @tab @code{COMPLEX(8)} @tab f95, gnu
10393 @item @code{CDSIN(X)} @tab @code{COMPLEX(8) X} @tab @code{COMPLEX(8)} @tab f95, gnu
10396 @item @emph{See also}:
10403 @section @code{SINH} --- Hyperbolic sine function
10406 @cindex hyperbolic sine
10407 @cindex hyperbolic function, sine
10408 @cindex sine, hyperbolic
10411 @item @emph{Description}:
10412 @code{SINH(X)} computes the hyperbolic sine of @var{X}.
10414 @item @emph{Standard}:
10415 Fortran 95 and later, for a complex argument Fortran 2008 or later
10417 @item @emph{Class}:
10420 @item @emph{Syntax}:
10421 @code{RESULT = SINH(X)}
10423 @item @emph{Arguments}:
10424 @multitable @columnfractions .15 .70
10425 @item @var{X} @tab The type shall be @code{REAL} or @code{COMPLEX}.
10428 @item @emph{Return value}:
10429 The return value has same type and kind as @var{X}.
10431 @item @emph{Example}:
10434 real(8) :: x = - 1.0_8
10436 end program test_sinh
10439 @item @emph{Specific names}:
10440 @multitable @columnfractions .20 .20 .20 .25
10441 @item Name @tab Argument @tab Return type @tab Standard
10442 @item @code{SINH(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab Fortran 95 and later
10443 @item @code{DSINH(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab Fortran 95 and later
10446 @item @emph{See also}:
10453 @section @code{SIZE} --- Determine the size of an array
10455 @cindex array, size
10456 @cindex array, number of elements
10457 @cindex array, count elements
10460 @item @emph{Description}:
10461 Determine the extent of @var{ARRAY} along a specified dimension @var{DIM},
10462 or the total number of elements in @var{ARRAY} if @var{DIM} is absent.
10464 @item @emph{Standard}:
10465 Fortran 95 and later, with @var{KIND} argument Fortran 2003 and later
10467 @item @emph{Class}:
10470 @item @emph{Syntax}:
10471 @code{RESULT = SIZE(ARRAY[, DIM [, KIND]])}
10473 @item @emph{Arguments}:
10474 @multitable @columnfractions .15 .70
10475 @item @var{ARRAY} @tab Shall be an array of any type. If @var{ARRAY} is
10476 a pointer it must be associated and allocatable arrays must be allocated.
10477 @item @var{DIM} @tab (Optional) shall be a scalar of type @code{INTEGER}
10478 and its value shall be in the range from 1 to n, where n equals the rank
10480 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
10481 expression indicating the kind parameter of the result.
10484 @item @emph{Return value}:
10485 The return value is of type @code{INTEGER} and of kind @var{KIND}. If
10486 @var{KIND} is absent, the return value is of default integer kind.
10488 @item @emph{Example}:
10491 WRITE(*,*) SIZE((/ 1, 2 /)) ! 2
10495 @item @emph{See also}:
10496 @ref{SHAPE}, @ref{RESHAPE}
10501 @section @code{SIZEOF} --- Size in bytes of an expression
10503 @cindex expression size
10504 @cindex size of an expression
10507 @item @emph{Description}:
10508 @code{SIZEOF(X)} calculates the number of bytes of storage the
10509 expression @code{X} occupies.
10511 @item @emph{Standard}:
10514 @item @emph{Class}:
10517 @item @emph{Syntax}:
10518 @code{N = SIZEOF(X)}
10520 @item @emph{Arguments}:
10521 @multitable @columnfractions .15 .70
10522 @item @var{X} @tab The argument shall be of any type, rank or shape.
10525 @item @emph{Return value}:
10526 The return value is of type integer and of the system-dependent kind
10527 @var{C_SIZE_T} (from the @var{ISO_C_BINDING} module). Its value is the
10528 number of bytes occupied by the argument. If the argument has the
10529 @code{POINTER} attribute, the number of bytes of the storage area pointed
10530 to is returned. If the argument is of a derived type with @code{POINTER}
10531 or @code{ALLOCATABLE} components, the return value doesn't account for
10532 the sizes of the data pointed to by these components. If the argument is
10533 polymorphic, the size according to the declared type is returned.
10535 @item @emph{Example}:
10539 print *, (sizeof(s)/sizeof(r) == 5)
10542 The example will print @code{.TRUE.} unless you are using a platform
10543 where default @code{REAL} variables are unusually padded.
10545 @item @emph{See also}:
10546 @ref{C_SIZEOF}, @ref{STORAGE_SIZE}
10551 @section @code{SLEEP} --- Sleep for the specified number of seconds
10553 @cindex delayed execution
10556 @item @emph{Description}:
10557 Calling this subroutine causes the process to pause for @var{SECONDS} seconds.
10559 @item @emph{Standard}:
10562 @item @emph{Class}:
10565 @item @emph{Syntax}:
10566 @code{CALL SLEEP(SECONDS)}
10568 @item @emph{Arguments}:
10569 @multitable @columnfractions .15 .70
10570 @item @var{SECONDS} @tab The type shall be of default @code{INTEGER}.
10573 @item @emph{Example}:
10584 @section @code{SPACING} --- Smallest distance between two numbers of a given type
10586 @cindex real number, relative spacing
10587 @cindex floating point, relative spacing
10590 @item @emph{Description}:
10591 Determines the distance between the argument @var{X} and the nearest
10592 adjacent number of the same type.
10594 @item @emph{Standard}:
10595 Fortran 95 and later
10597 @item @emph{Class}:
10600 @item @emph{Syntax}:
10601 @code{RESULT = SPACING(X)}
10603 @item @emph{Arguments}:
10604 @multitable @columnfractions .15 .70
10605 @item @var{X} @tab Shall be of type @code{REAL}.
10608 @item @emph{Return value}:
10609 The result is of the same type as the input argument @var{X}.
10611 @item @emph{Example}:
10613 PROGRAM test_spacing
10614 INTEGER, PARAMETER :: SGL = SELECTED_REAL_KIND(p=6, r=37)
10615 INTEGER, PARAMETER :: DBL = SELECTED_REAL_KIND(p=13, r=200)
10617 WRITE(*,*) spacing(1.0_SGL) ! "1.1920929E-07" on i686
10618 WRITE(*,*) spacing(1.0_DBL) ! "2.220446049250313E-016" on i686
10622 @item @emph{See also}:
10629 @section @code{SPREAD} --- Add a dimension to an array
10631 @cindex array, increase dimension
10632 @cindex array, duplicate elements
10633 @cindex array, duplicate dimensions
10636 @item @emph{Description}:
10637 Replicates a @var{SOURCE} array @var{NCOPIES} times along a specified
10638 dimension @var{DIM}.
10640 @item @emph{Standard}:
10641 Fortran 95 and later
10643 @item @emph{Class}:
10644 Transformational function
10646 @item @emph{Syntax}:
10647 @code{RESULT = SPREAD(SOURCE, DIM, NCOPIES)}
10649 @item @emph{Arguments}:
10650 @multitable @columnfractions .15 .70
10651 @item @var{SOURCE} @tab Shall be a scalar or an array of any type and
10652 a rank less than seven.
10653 @item @var{DIM} @tab Shall be a scalar of type @code{INTEGER} with a
10654 value in the range from 1 to n+1, where n equals the rank of @var{SOURCE}.
10655 @item @var{NCOPIES} @tab Shall be a scalar of type @code{INTEGER}.
10658 @item @emph{Return value}:
10659 The result is an array of the same type as @var{SOURCE} and has rank n+1
10660 where n equals the rank of @var{SOURCE}.
10662 @item @emph{Example}:
10664 PROGRAM test_spread
10665 INTEGER :: a = 1, b(2) = (/ 1, 2 /)
10666 WRITE(*,*) SPREAD(A, 1, 2) ! "1 1"
10667 WRITE(*,*) SPREAD(B, 1, 2) ! "1 1 2 2"
10671 @item @emph{See also}:
10678 @section @code{SQRT} --- Square-root function
10685 @cindex square-root
10688 @item @emph{Description}:
10689 @code{SQRT(X)} computes the square root of @var{X}.
10691 @item @emph{Standard}:
10692 Fortran 77 and later
10694 @item @emph{Class}:
10697 @item @emph{Syntax}:
10698 @code{RESULT = SQRT(X)}
10700 @item @emph{Arguments}:
10701 @multitable @columnfractions .15 .70
10702 @item @var{X} @tab The type shall be @code{REAL} or
10706 @item @emph{Return value}:
10707 The return value is of type @code{REAL} or @code{COMPLEX}.
10708 The kind type parameter is the same as @var{X}.
10710 @item @emph{Example}:
10713 real(8) :: x = 2.0_8
10714 complex :: z = (1.0, 2.0)
10717 end program test_sqrt
10720 @item @emph{Specific names}:
10721 @multitable @columnfractions .20 .20 .20 .25
10722 @item Name @tab Argument @tab Return type @tab Standard
10723 @item @code{SQRT(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab Fortran 95 and later
10724 @item @code{DSQRT(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab Fortran 95 and later
10725 @item @code{CSQRT(X)} @tab @code{COMPLEX(4) X} @tab @code{COMPLEX(4)} @tab Fortran 95 and later
10726 @item @code{ZSQRT(X)} @tab @code{COMPLEX(8) X} @tab @code{COMPLEX(8)} @tab GNU extension
10727 @item @code{CDSQRT(X)} @tab @code{COMPLEX(8) X} @tab @code{COMPLEX(8)} @tab GNU extension
10734 @section @code{SRAND} --- Reinitialize the random number generator
10736 @cindex random number generation, seeding
10737 @cindex seeding a random number generator
10740 @item @emph{Description}:
10741 @code{SRAND} reinitializes the pseudo-random number generator
10742 called by @code{RAND} and @code{IRAND}. The new seed used by the
10743 generator is specified by the required argument @var{SEED}.
10745 @item @emph{Standard}:
10748 @item @emph{Class}:
10751 @item @emph{Syntax}:
10752 @code{CALL SRAND(SEED)}
10754 @item @emph{Arguments}:
10755 @multitable @columnfractions .15 .70
10756 @item @var{SEED} @tab Shall be a scalar @code{INTEGER(kind=4)}.
10759 @item @emph{Return value}:
10760 Does not return anything.
10762 @item @emph{Example}:
10763 See @code{RAND} and @code{IRAND} for examples.
10765 @item @emph{Notes}:
10766 The Fortran 2003 standard specifies the intrinsic @code{RANDOM_SEED} to
10767 initialize the pseudo-random numbers generator and @code{RANDOM_NUMBER}
10768 to generate pseudo-random numbers. Please note that in
10769 GNU Fortran, these two sets of intrinsics (@code{RAND},
10770 @code{IRAND} and @code{SRAND} on the one hand, @code{RANDOM_NUMBER} and
10771 @code{RANDOM_SEED} on the other hand) access two independent
10772 pseudo-random number generators.
10774 @item @emph{See also}:
10775 @ref{RAND}, @ref{RANDOM_SEED}, @ref{RANDOM_NUMBER}
10782 @section @code{STAT} --- Get file status
10784 @cindex file system, file status
10787 @item @emph{Description}:
10788 This function returns information about a file. No permissions are required on
10789 the file itself, but execute (search) permission is required on all of the
10790 directories in path that lead to the file.
10792 The elements that are obtained and stored in the array @code{VALUES}:
10793 @multitable @columnfractions .15 .70
10794 @item @code{VALUES(1)} @tab Device ID
10795 @item @code{VALUES(2)} @tab Inode number
10796 @item @code{VALUES(3)} @tab File mode
10797 @item @code{VALUES(4)} @tab Number of links
10798 @item @code{VALUES(5)} @tab Owner's uid
10799 @item @code{VALUES(6)} @tab Owner's gid
10800 @item @code{VALUES(7)} @tab ID of device containing directory entry for file (0 if not available)
10801 @item @code{VALUES(8)} @tab File size (bytes)
10802 @item @code{VALUES(9)} @tab Last access time
10803 @item @code{VALUES(10)} @tab Last modification time
10804 @item @code{VALUES(11)} @tab Last file status change time
10805 @item @code{VALUES(12)} @tab Preferred I/O block size (-1 if not available)
10806 @item @code{VALUES(13)} @tab Number of blocks allocated (-1 if not available)
10809 Not all these elements are relevant on all systems.
10810 If an element is not relevant, it is returned as 0.
10812 This intrinsic is provided in both subroutine and function forms; however,
10813 only one form can be used in any given program unit.
10815 @item @emph{Standard}:
10818 @item @emph{Class}:
10819 Subroutine, function
10821 @item @emph{Syntax}:
10822 @code{CALL STAT(NAME, VALUES [, STATUS])}
10824 @item @emph{Arguments}:
10825 @multitable @columnfractions .15 .70
10826 @item @var{NAME} @tab The type shall be @code{CHARACTER}, of the
10827 default kind and a valid path within the file system.
10828 @item @var{VALUES} @tab The type shall be @code{INTEGER(4), DIMENSION(13)}.
10829 @item @var{STATUS} @tab (Optional) status flag of type @code{INTEGER(4)}. Returns 0
10830 on success and a system specific error code otherwise.
10833 @item @emph{Example}:
10836 INTEGER, DIMENSION(13) :: buff
10839 CALL STAT("/etc/passwd", buff, status)
10841 IF (status == 0) THEN
10842 WRITE (*, FMT="('Device ID:', T30, I19)") buff(1)
10843 WRITE (*, FMT="('Inode number:', T30, I19)") buff(2)
10844 WRITE (*, FMT="('File mode (octal):', T30, O19)") buff(3)
10845 WRITE (*, FMT="('Number of links:', T30, I19)") buff(4)
10846 WRITE (*, FMT="('Owner''s uid:', T30, I19)") buff(5)
10847 WRITE (*, FMT="('Owner''s gid:', T30, I19)") buff(6)
10848 WRITE (*, FMT="('Device where located:', T30, I19)") buff(7)
10849 WRITE (*, FMT="('File size:', T30, I19)") buff(8)
10850 WRITE (*, FMT="('Last access time:', T30, A19)") CTIME(buff(9))
10851 WRITE (*, FMT="('Last modification time', T30, A19)") CTIME(buff(10))
10852 WRITE (*, FMT="('Last status change time:', T30, A19)") CTIME(buff(11))
10853 WRITE (*, FMT="('Preferred block size:', T30, I19)") buff(12)
10854 WRITE (*, FMT="('No. of blocks allocated:', T30, I19)") buff(13)
10859 @item @emph{See also}:
10860 To stat an open file: @ref{FSTAT}, to stat a link: @ref{LSTAT}
10866 @section @code{STORAGE_SIZE} --- Storage size in bits
10867 @fnindex STORAGE_SIZE
10868 @cindex storage size
10871 @item @emph{Description}:
10872 Returns the storage size of argument @var{A} in bits.
10873 @item @emph{Standard}:
10874 Fortran 2008 and later
10875 @item @emph{Class}:
10877 @item @emph{Syntax}:
10878 @code{RESULT = STORAGE_SIZE(A [, KIND])}
10880 @item @emph{Arguments}:
10881 @multitable @columnfractions .15 .70
10882 @item @var{A} @tab Shall be a scalar or array of any type.
10883 @item @var{KIND} @tab (Optional) shall be a scalar integer constant expression.
10886 @item @emph{Return Value}:
10887 The result is a scalar integer with the kind type parameter specified by KIND (or default integer type if KIND is missing). The result value is the size expressed in bits for an element of an array that
10888 has the dynamic type and type parameters of A.
10890 @item @emph{See also}:
10891 @ref{C_SIZEOF}, @ref{SIZEOF}
10897 @section @code{SUM} --- Sum of array elements
10900 @cindex array, add elements
10901 @cindex array, conditionally add elements
10902 @cindex sum array elements
10905 @item @emph{Description}:
10906 Adds the elements of @var{ARRAY} along dimension @var{DIM} if
10907 the corresponding element in @var{MASK} is @code{TRUE}.
10909 @item @emph{Standard}:
10910 Fortran 95 and later
10912 @item @emph{Class}:
10913 Transformational function
10915 @item @emph{Syntax}:
10916 @multitable @columnfractions .80
10917 @item @code{RESULT = SUM(ARRAY[, MASK])}
10918 @item @code{RESULT = SUM(ARRAY, DIM[, MASK])}
10921 @item @emph{Arguments}:
10922 @multitable @columnfractions .15 .70
10923 @item @var{ARRAY} @tab Shall be an array of type @code{INTEGER},
10924 @code{REAL} or @code{COMPLEX}.
10925 @item @var{DIM} @tab (Optional) shall be a scalar of type
10926 @code{INTEGER} with a value in the range from 1 to n, where n
10927 equals the rank of @var{ARRAY}.
10928 @item @var{MASK} @tab (Optional) shall be of type @code{LOGICAL}
10929 and either be a scalar or an array of the same shape as @var{ARRAY}.
10932 @item @emph{Return value}:
10933 The result is of the same type as @var{ARRAY}.
10935 If @var{DIM} is absent, a scalar with the sum of all elements in @var{ARRAY}
10936 is returned. Otherwise, an array of rank n-1, where n equals the rank of
10937 @var{ARRAY}, and a shape similar to that of @var{ARRAY} with dimension @var{DIM}
10938 dropped is returned.
10940 @item @emph{Example}:
10943 INTEGER :: x(5) = (/ 1, 2, 3, 4 ,5 /)
10944 print *, SUM(x) ! all elements, sum = 15
10945 print *, SUM(x, MASK=MOD(x, 2)==1) ! odd elements, sum = 9
10949 @item @emph{See also}:
10956 @section @code{SYMLNK} --- Create a symbolic link
10958 @cindex file system, create link
10959 @cindex file system, soft link
10962 @item @emph{Description}:
10963 Makes a symbolic link from file @var{PATH1} to @var{PATH2}. A null
10964 character (@code{CHAR(0)}) can be used to mark the end of the names in
10965 @var{PATH1} and @var{PATH2}; otherwise, trailing blanks in the file
10966 names are ignored. If the @var{STATUS} argument is supplied, it
10967 contains 0 on success or a nonzero error code upon return; see
10968 @code{symlink(2)}. If the system does not supply @code{symlink(2)},
10969 @code{ENOSYS} is returned.
10971 This intrinsic is provided in both subroutine and function forms;
10972 however, only one form can be used in any given program unit.
10974 @item @emph{Standard}:
10977 @item @emph{Class}:
10978 Subroutine, function
10980 @item @emph{Syntax}:
10981 @multitable @columnfractions .80
10982 @item @code{CALL SYMLNK(PATH1, PATH2 [, STATUS])}
10983 @item @code{STATUS = SYMLNK(PATH1, PATH2)}
10986 @item @emph{Arguments}:
10987 @multitable @columnfractions .15 .70
10988 @item @var{PATH1} @tab Shall be of default @code{CHARACTER} type.
10989 @item @var{PATH2} @tab Shall be of default @code{CHARACTER} type.
10990 @item @var{STATUS} @tab (Optional) Shall be of default @code{INTEGER} type.
10993 @item @emph{See also}:
10994 @ref{LINK}, @ref{UNLINK}
11001 @section @code{SYSTEM} --- Execute a shell command
11003 @cindex system, system call
11006 @item @emph{Description}:
11007 Passes the command @var{COMMAND} to a shell (see @code{system(3)}). If
11008 argument @var{STATUS} is present, it contains the value returned by
11009 @code{system(3)}, which is presumably 0 if the shell command succeeded.
11010 Note that which shell is used to invoke the command is system-dependent
11011 and environment-dependent.
11013 This intrinsic is provided in both subroutine and function forms;
11014 however, only one form can be used in any given program unit.
11016 @item @emph{Standard}:
11019 @item @emph{Class}:
11020 Subroutine, function
11022 @item @emph{Syntax}:
11023 @multitable @columnfractions .80
11024 @item @code{CALL SYSTEM(COMMAND [, STATUS])}
11025 @item @code{STATUS = SYSTEM(COMMAND)}
11028 @item @emph{Arguments}:
11029 @multitable @columnfractions .15 .70
11030 @item @var{COMMAND} @tab Shall be of default @code{CHARACTER} type.
11031 @item @var{STATUS} @tab (Optional) Shall be of default @code{INTEGER} type.
11034 @item @emph{See also}:
11035 @ref{EXECUTE_COMMAND_LINE}, which is part of the Fortran 2008 standard
11036 and should considered in new code for future portability.
11042 @section @code{SYSTEM_CLOCK} --- Time function
11043 @fnindex SYSTEM_CLOCK
11044 @cindex time, clock ticks
11045 @cindex clock ticks
11048 @item @emph{Description}:
11049 Determines the @var{COUNT} of milliseconds of wall clock time since
11050 the Epoch (00:00:00 UTC, January 1, 1970) modulo @var{COUNT_MAX},
11051 @var{COUNT_RATE} determines the number of clock ticks per second.
11052 @var{COUNT_RATE} and @var{COUNT_MAX} are constant and specific to
11053 @command{gfortran}.
11055 If there is no clock, @var{COUNT} is set to @code{-HUGE(COUNT)}, and
11056 @var{COUNT_RATE} and @var{COUNT_MAX} are set to zero
11058 @item @emph{Standard}:
11059 Fortran 95 and later
11061 @item @emph{Class}:
11064 @item @emph{Syntax}:
11065 @code{CALL SYSTEM_CLOCK([COUNT, COUNT_RATE, COUNT_MAX])}
11067 @item @emph{Arguments}:
11068 @multitable @columnfractions .15 .70
11069 @item @var{COUNT} @tab (Optional) shall be a scalar of type default
11070 @code{INTEGER} with @code{INTENT(OUT)}.
11071 @item @var{COUNT_RATE} @tab (Optional) shall be a scalar of type default
11072 @code{INTEGER} with @code{INTENT(OUT)}.
11073 @item @var{COUNT_MAX} @tab (Optional) shall be a scalar of type default
11074 @code{INTEGER} with @code{INTENT(OUT)}.
11077 @item @emph{Example}:
11079 PROGRAM test_system_clock
11080 INTEGER :: count, count_rate, count_max
11081 CALL SYSTEM_CLOCK(count, count_rate, count_max)
11082 WRITE(*,*) count, count_rate, count_max
11086 @item @emph{See also}:
11087 @ref{DATE_AND_TIME}, @ref{CPU_TIME}
11093 @section @code{TAN} --- Tangent function
11096 @cindex trigonometric function, tangent
11100 @item @emph{Description}:
11101 @code{TAN(X)} computes the tangent of @var{X}.
11103 @item @emph{Standard}:
11104 Fortran 77 and later, for a complex argument Fortran 2008 or later
11106 @item @emph{Class}:
11109 @item @emph{Syntax}:
11110 @code{RESULT = TAN(X)}
11112 @item @emph{Arguments}:
11113 @multitable @columnfractions .15 .70
11114 @item @var{X} @tab The type shall be @code{REAL} or @code{COMPLEX}.
11117 @item @emph{Return value}:
11118 The return value has same type and kind as @var{X}.
11120 @item @emph{Example}:
11123 real(8) :: x = 0.165_8
11125 end program test_tan
11128 @item @emph{Specific names}:
11129 @multitable @columnfractions .20 .20 .20 .25
11130 @item Name @tab Argument @tab Return type @tab Standard
11131 @item @code{TAN(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab Fortran 95 and later
11132 @item @code{DTAN(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab Fortran 95 and later
11135 @item @emph{See also}:
11142 @section @code{TANH} --- Hyperbolic tangent function
11145 @cindex hyperbolic tangent
11146 @cindex hyperbolic function, tangent
11147 @cindex tangent, hyperbolic
11150 @item @emph{Description}:
11151 @code{TANH(X)} computes the hyperbolic tangent of @var{X}.
11153 @item @emph{Standard}:
11154 Fortran 77 and later, for a complex argument Fortran 2008 or later
11156 @item @emph{Class}:
11159 @item @emph{Syntax}:
11162 @item @emph{Arguments}:
11163 @multitable @columnfractions .15 .70
11164 @item @var{X} @tab The type shall be @code{REAL} or @code{COMPLEX}.
11167 @item @emph{Return value}:
11168 The return value has same type and kind as @var{X}. If @var{X} is
11169 complex, the imaginary part of the result is in radians. If @var{X}
11170 is @code{REAL}, the return value lies in the range
11171 @math{ - 1 \leq tanh(x) \leq 1 }.
11173 @item @emph{Example}:
11176 real(8) :: x = 2.1_8
11178 end program test_tanh
11181 @item @emph{Specific names}:
11182 @multitable @columnfractions .20 .20 .20 .25
11183 @item Name @tab Argument @tab Return type @tab Standard
11184 @item @code{TANH(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab Fortran 95 and later
11185 @item @code{DTANH(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab Fortran 95 and later
11188 @item @emph{See also}:
11195 @section @code{THIS_IMAGE} --- Function that returns the cosubscript index of this image
11196 @fnindex THIS_IMAGE
11197 @cindex coarray, THIS_IMAGE
11198 @cindex images, index of this image
11201 @item @emph{Description}:
11202 Returns the cosubscript for this image.
11204 @item @emph{Standard}:
11205 Fortran 2008 and later
11207 @item @emph{Class}:
11208 Transformational function
11210 @item @emph{Syntax}:
11211 @multitable @columnfractions .80
11212 @item @code{RESULT = THIS_IMAGE()}
11213 @item @code{RESULT = THIS_IMAGE(COARRAY [, DIM])}
11216 @item @emph{Arguments}:
11217 @multitable @columnfractions .15 .70
11218 @item @var{COARRAY} @tab Coarray of any type (optional; if @var{DIM}
11219 present, required).
11220 @item @var{DIM} @tab default integer scalar (optional). If present,
11221 @var{DIM} shall be between one and the corank of @var{COARRAY}.
11225 @item @emph{Return value}:
11226 Default integer. If @var{COARRAY} is not present, it is scalar and its value
11227 is the index of the invoking image. Otherwise, if @var{DIM} is not present,
11228 a rank-1 array with corank elements is returned, containing the cosubscripts
11229 for @var{COARRAY} specifying the invoking image. If @var{DIM} is present,
11230 a scalar is returned, with the value of the @var{DIM} element of
11231 @code{THIS_IMAGE(COARRAY)}.
11233 @item @emph{Example}:
11235 INTEGER :: value[*]
11237 value = THIS_IMAGE()
11239 IF (THIS_IMAGE() == 1) THEN
11240 DO i = 1, NUM_IMAGES()
11241 WRITE(*,'(2(a,i0))') 'value[', i, '] is ', value[i]
11246 @item @emph{See also}:
11247 @ref{NUM_IMAGES}, @ref{IMAGE_INDEX}
11253 @section @code{TIME} --- Time function
11255 @cindex time, current
11256 @cindex current time
11259 @item @emph{Description}:
11260 Returns the current time encoded as an integer (in the manner of the
11261 UNIX function @code{time(3)}). This value is suitable for passing to
11262 @code{CTIME()}, @code{GMTIME()}, and @code{LTIME()}.
11264 This intrinsic is not fully portable, such as to systems with 32-bit
11265 @code{INTEGER} types but supporting times wider than 32 bits. Therefore,
11266 the values returned by this intrinsic might be, or become, negative, or
11267 numerically less than previous values, during a single run of the
11270 See @ref{TIME8}, for information on a similar intrinsic that might be
11271 portable to more GNU Fortran implementations, though to fewer Fortran
11274 @item @emph{Standard}:
11277 @item @emph{Class}:
11280 @item @emph{Syntax}:
11281 @code{RESULT = TIME()}
11283 @item @emph{Return value}:
11284 The return value is a scalar of type @code{INTEGER(4)}.
11286 @item @emph{See also}:
11287 @ref{CTIME}, @ref{GMTIME}, @ref{LTIME}, @ref{MCLOCK}, @ref{TIME8}
11294 @section @code{TIME8} --- Time function (64-bit)
11296 @cindex time, current
11297 @cindex current time
11300 @item @emph{Description}:
11301 Returns the current time encoded as an integer (in the manner of the
11302 UNIX function @code{time(3)}). This value is suitable for passing to
11303 @code{CTIME()}, @code{GMTIME()}, and @code{LTIME()}.
11305 @emph{Warning:} this intrinsic does not increase the range of the timing
11306 values over that returned by @code{time(3)}. On a system with a 32-bit
11307 @code{time(3)}, @code{TIME8()} will return a 32-bit value, even though
11308 it is converted to a 64-bit @code{INTEGER(8)} value. That means
11309 overflows of the 32-bit value can still occur. Therefore, the values
11310 returned by this intrinsic might be or become negative or numerically
11311 less than previous values during a single run of the compiled program.
11313 @item @emph{Standard}:
11316 @item @emph{Class}:
11319 @item @emph{Syntax}:
11320 @code{RESULT = TIME8()}
11322 @item @emph{Return value}:
11323 The return value is a scalar of type @code{INTEGER(8)}.
11325 @item @emph{See also}:
11326 @ref{CTIME}, @ref{GMTIME}, @ref{LTIME}, @ref{MCLOCK8}, @ref{TIME}
11333 @section @code{TINY} --- Smallest positive number of a real kind
11335 @cindex limits, smallest number
11336 @cindex model representation, smallest number
11339 @item @emph{Description}:
11340 @code{TINY(X)} returns the smallest positive (non zero) number
11341 in the model of the type of @code{X}.
11343 @item @emph{Standard}:
11344 Fortran 95 and later
11346 @item @emph{Class}:
11349 @item @emph{Syntax}:
11350 @code{RESULT = TINY(X)}
11352 @item @emph{Arguments}:
11353 @multitable @columnfractions .15 .70
11354 @item @var{X} @tab Shall be of type @code{REAL}.
11357 @item @emph{Return value}:
11358 The return value is of the same type and kind as @var{X}
11360 @item @emph{Example}:
11361 See @code{HUGE} for an example.
11367 @section @code{TRAILZ} --- Number of trailing zero bits of an integer
11372 @item @emph{Description}:
11373 @code{TRAILZ} returns the number of trailing zero bits of an integer.
11375 @item @emph{Standard}:
11376 Fortran 2008 and later
11378 @item @emph{Class}:
11381 @item @emph{Syntax}:
11382 @code{RESULT = TRAILZ(I)}
11384 @item @emph{Arguments}:
11385 @multitable @columnfractions .15 .70
11386 @item @var{I} @tab Shall be of type @code{INTEGER}.
11389 @item @emph{Return value}:
11390 The type of the return value is the default @code{INTEGER}.
11391 If all the bits of @code{I} are zero, the result value is @code{BIT_SIZE(I)}.
11393 @item @emph{Example}:
11395 PROGRAM test_trailz
11396 WRITE (*,*) TRAILZ(8) ! prints 3
11400 @item @emph{See also}:
11401 @ref{BIT_SIZE}, @ref{LEADZ}, @ref{POPPAR}, @ref{POPCNT}
11407 @section @code{TRANSFER} --- Transfer bit patterns
11413 @item @emph{Description}:
11414 Interprets the bitwise representation of @var{SOURCE} in memory as if it
11415 is the representation of a variable or array of the same type and type
11416 parameters as @var{MOLD}.
11418 This is approximately equivalent to the C concept of @emph{casting} one
11421 @item @emph{Standard}:
11422 Fortran 95 and later
11424 @item @emph{Class}:
11425 Transformational function
11427 @item @emph{Syntax}:
11428 @code{RESULT = TRANSFER(SOURCE, MOLD[, SIZE])}
11430 @item @emph{Arguments}:
11431 @multitable @columnfractions .15 .70
11432 @item @var{SOURCE} @tab Shall be a scalar or an array of any type.
11433 @item @var{MOLD} @tab Shall be a scalar or an array of any type.
11434 @item @var{SIZE} @tab (Optional) shall be a scalar of type
11438 @item @emph{Return value}:
11439 The result has the same type as @var{MOLD}, with the bit level
11440 representation of @var{SOURCE}. If @var{SIZE} is present, the result is
11441 a one-dimensional array of length @var{SIZE}. If @var{SIZE} is absent
11442 but @var{MOLD} is an array (of any size or shape), the result is a one-
11443 dimensional array of the minimum length needed to contain the entirety
11444 of the bitwise representation of @var{SOURCE}. If @var{SIZE} is absent
11445 and @var{MOLD} is a scalar, the result is a scalar.
11447 If the bitwise representation of the result is longer than that of
11448 @var{SOURCE}, then the leading bits of the result correspond to those of
11449 @var{SOURCE} and any trailing bits are filled arbitrarily.
11451 When the resulting bit representation does not correspond to a valid
11452 representation of a variable of the same type as @var{MOLD}, the results
11453 are undefined, and subsequent operations on the result cannot be
11454 guaranteed to produce sensible behavior. For example, it is possible to
11455 create @code{LOGICAL} variables for which @code{@var{VAR}} and
11456 @code{.NOT.@var{VAR}} both appear to be true.
11458 @item @emph{Example}:
11460 PROGRAM test_transfer
11461 integer :: x = 2143289344
11462 print *, transfer(x, 1.0) ! prints "NaN" on i686
11470 @section @code{TRANSPOSE} --- Transpose an array of rank two
11472 @cindex array, transpose
11473 @cindex matrix, transpose
11477 @item @emph{Description}:
11478 Transpose an array of rank two. Element (i, j) of the result has the value
11479 @code{MATRIX(j, i)}, for all i, j.
11481 @item @emph{Standard}:
11482 Fortran 95 and later
11484 @item @emph{Class}:
11485 Transformational function
11487 @item @emph{Syntax}:
11488 @code{RESULT = TRANSPOSE(MATRIX)}
11490 @item @emph{Arguments}:
11491 @multitable @columnfractions .15 .70
11492 @item @var{MATRIX} @tab Shall be an array of any type and have a rank of two.
11495 @item @emph{Return value}:
11496 The result has the same type as @var{MATRIX}, and has shape
11497 @code{(/ m, n /)} if @var{MATRIX} has shape @code{(/ n, m /)}.
11503 @section @code{TRIM} --- Remove trailing blank characters of a string
11505 @cindex string, remove trailing whitespace
11508 @item @emph{Description}:
11509 Removes trailing blank characters of a string.
11511 @item @emph{Standard}:
11512 Fortran 95 and later
11514 @item @emph{Class}:
11515 Transformational function
11517 @item @emph{Syntax}:
11518 @code{RESULT = TRIM(STRING)}
11520 @item @emph{Arguments}:
11521 @multitable @columnfractions .15 .70
11522 @item @var{STRING} @tab Shall be a scalar of type @code{CHARACTER}.
11525 @item @emph{Return value}:
11526 A scalar of type @code{CHARACTER} which length is that of @var{STRING}
11527 less the number of trailing blanks.
11529 @item @emph{Example}:
11532 CHARACTER(len=10), PARAMETER :: s = "GFORTRAN "
11533 WRITE(*,*) LEN(s), LEN(TRIM(s)) ! "10 8", with/without trailing blanks
11537 @item @emph{See also}:
11538 @ref{ADJUSTL}, @ref{ADJUSTR}
11544 @section @code{TTYNAM} --- Get the name of a terminal device.
11546 @cindex system, terminal
11549 @item @emph{Description}:
11550 Get the name of a terminal device. For more information,
11551 see @code{ttyname(3)}.
11553 This intrinsic is provided in both subroutine and function forms;
11554 however, only one form can be used in any given program unit.
11556 @item @emph{Standard}:
11559 @item @emph{Class}:
11560 Subroutine, function
11562 @item @emph{Syntax}:
11563 @multitable @columnfractions .80
11564 @item @code{CALL TTYNAM(UNIT, NAME)}
11565 @item @code{NAME = TTYNAM(UNIT)}
11568 @item @emph{Arguments}:
11569 @multitable @columnfractions .15 .70
11570 @item @var{UNIT} @tab Shall be a scalar @code{INTEGER}.
11571 @item @var{NAME} @tab Shall be of type @code{CHARACTER}.
11574 @item @emph{Example}:
11576 PROGRAM test_ttynam
11579 IF (isatty(unit=unit)) write(*,*) ttynam(unit)
11584 @item @emph{See also}:
11591 @section @code{UBOUND} --- Upper dimension bounds of an array
11593 @cindex array, upper bound
11596 @item @emph{Description}:
11597 Returns the upper bounds of an array, or a single upper bound
11598 along the @var{DIM} dimension.
11599 @item @emph{Standard}:
11600 Fortran 95 and later, with @var{KIND} argument Fortran 2003 and later
11602 @item @emph{Class}:
11605 @item @emph{Syntax}:
11606 @code{RESULT = UBOUND(ARRAY [, DIM [, KIND]])}
11608 @item @emph{Arguments}:
11609 @multitable @columnfractions .15 .70
11610 @item @var{ARRAY} @tab Shall be an array, of any type.
11611 @item @var{DIM} @tab (Optional) Shall be a scalar @code{INTEGER}.
11612 @item @var{KIND}@tab (Optional) An @code{INTEGER} initialization
11613 expression indicating the kind parameter of the result.
11616 @item @emph{Return value}:
11617 The return value is of type @code{INTEGER} and of kind @var{KIND}. If
11618 @var{KIND} is absent, the return value is of default integer kind.
11619 If @var{DIM} is absent, the result is an array of the upper bounds of
11620 @var{ARRAY}. If @var{DIM} is present, the result is a scalar
11621 corresponding to the upper bound of the array along that dimension. If
11622 @var{ARRAY} is an expression rather than a whole array or array
11623 structure component, or if it has a zero extent along the relevant
11624 dimension, the upper bound is taken to be the number of elements along
11625 the relevant dimension.
11627 @item @emph{See also}:
11628 @ref{LBOUND}, @ref{LCOBOUND}
11634 @section @code{UCOBOUND} --- Upper codimension bounds of an array
11636 @cindex coarray, upper bound
11639 @item @emph{Description}:
11640 Returns the upper cobounds of a coarray, or a single upper cobound
11641 along the @var{DIM} codimension.
11642 @item @emph{Standard}:
11643 Fortran 2008 and later
11645 @item @emph{Class}:
11648 @item @emph{Syntax}:
11649 @code{RESULT = UCOBOUND(COARRAY [, DIM [, KIND]])}
11651 @item @emph{Arguments}:
11652 @multitable @columnfractions .15 .70
11653 @item @var{ARRAY} @tab Shall be an coarray, of any type.
11654 @item @var{DIM} @tab (Optional) Shall be a scalar @code{INTEGER}.
11655 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
11656 expression indicating the kind parameter of the result.
11659 @item @emph{Return value}:
11660 The return value is of type @code{INTEGER} and of kind @var{KIND}. If
11661 @var{KIND} is absent, the return value is of default integer kind.
11662 If @var{DIM} is absent, the result is an array of the lower cobounds of
11663 @var{COARRAY}. If @var{DIM} is present, the result is a scalar
11664 corresponding to the lower cobound of the array along that codimension.
11666 @item @emph{See also}:
11667 @ref{LCOBOUND}, @ref{LBOUND}
11673 @section @code{UMASK} --- Set the file creation mask
11675 @cindex file system, file creation mask
11678 @item @emph{Description}:
11679 Sets the file creation mask to @var{MASK}. If called as a function, it
11680 returns the old value. If called as a subroutine and argument @var{OLD}
11681 if it is supplied, it is set to the old value. See @code{umask(2)}.
11683 @item @emph{Standard}:
11686 @item @emph{Class}:
11687 Subroutine, function
11689 @item @emph{Syntax}:
11690 @code{CALL UMASK(MASK [, OLD])}
11691 @code{OLD = UMASK(MASK)}
11693 @item @emph{Arguments}:
11694 @multitable @columnfractions .15 .70
11695 @item @var{MASK} @tab Shall be a scalar of type @code{INTEGER}.
11696 @item @var{OLD} @tab (Optional) Shall be a scalar of type
11705 @section @code{UNLINK} --- Remove a file from the file system
11707 @cindex file system, remove file
11710 @item @emph{Description}:
11711 Unlinks the file @var{PATH}. A null character (@code{CHAR(0)}) can be
11712 used to mark the end of the name in @var{PATH}; otherwise, trailing
11713 blanks in the file name are ignored. If the @var{STATUS} argument is
11714 supplied, it contains 0 on success or a nonzero error code upon return;
11715 see @code{unlink(2)}.
11717 This intrinsic is provided in both subroutine and function forms;
11718 however, only one form can be used in any given program unit.
11720 @item @emph{Standard}:
11723 @item @emph{Class}:
11724 Subroutine, function
11726 @item @emph{Syntax}:
11727 @multitable @columnfractions .80
11728 @item @code{CALL UNLINK(PATH [, STATUS])}
11729 @item @code{STATUS = UNLINK(PATH)}
11732 @item @emph{Arguments}:
11733 @multitable @columnfractions .15 .70
11734 @item @var{PATH} @tab Shall be of default @code{CHARACTER} type.
11735 @item @var{STATUS} @tab (Optional) Shall be of default @code{INTEGER} type.
11738 @item @emph{See also}:
11739 @ref{LINK}, @ref{SYMLNK}
11745 @section @code{UNPACK} --- Unpack an array of rank one into an array
11747 @cindex array, unpacking
11748 @cindex array, increase dimension
11749 @cindex array, scatter elements
11752 @item @emph{Description}:
11753 Store the elements of @var{VECTOR} in an array of higher rank.
11755 @item @emph{Standard}:
11756 Fortran 95 and later
11758 @item @emph{Class}:
11759 Transformational function
11761 @item @emph{Syntax}:
11762 @code{RESULT = UNPACK(VECTOR, MASK, FIELD)}
11764 @item @emph{Arguments}:
11765 @multitable @columnfractions .15 .70
11766 @item @var{VECTOR} @tab Shall be an array of any type and rank one. It
11767 shall have at least as many elements as @var{MASK} has @code{TRUE} values.
11768 @item @var{MASK} @tab Shall be an array of type @code{LOGICAL}.
11769 @item @var{FIELD} @tab Shall be of the same type as @var{VECTOR} and have
11770 the same shape as @var{MASK}.
11773 @item @emph{Return value}:
11774 The resulting array corresponds to @var{FIELD} with @code{TRUE} elements
11775 of @var{MASK} replaced by values from @var{VECTOR} in array element order.
11777 @item @emph{Example}:
11779 PROGRAM test_unpack
11780 integer :: vector(2) = (/1,1/)
11781 logical :: mask(4) = (/ .TRUE., .FALSE., .FALSE., .TRUE. /)
11782 integer :: field(2,2) = 0, unity(2,2)
11784 ! result: unity matrix
11785 unity = unpack(vector, reshape(mask, (/2,2/)), field)
11789 @item @emph{See also}:
11790 @ref{PACK}, @ref{SPREAD}
11796 @section @code{VERIFY} --- Scan a string for the absence of a set of characters
11798 @cindex string, find missing set
11801 @item @emph{Description}:
11802 Verifies that all the characters in a @var{SET} are present in a @var{STRING}.
11804 If @var{BACK} is either absent or equals @code{FALSE}, this function
11805 returns the position of the leftmost character of @var{STRING} that is
11806 not in @var{SET}. If @var{BACK} equals @code{TRUE}, the rightmost position
11807 is returned. If all characters of @var{SET} are found in @var{STRING}, the
11810 @item @emph{Standard}:
11811 Fortran 95 and later, with @var{KIND} argument Fortran 2003 and later
11813 @item @emph{Class}:
11816 @item @emph{Syntax}:
11817 @code{RESULT = VERIFY(STRING, SET[, BACK [, KIND]])}
11819 @item @emph{Arguments}:
11820 @multitable @columnfractions .15 .70
11821 @item @var{STRING} @tab Shall be of type @code{CHARACTER}.
11822 @item @var{SET} @tab Shall be of type @code{CHARACTER}.
11823 @item @var{BACK} @tab (Optional) shall be of type @code{LOGICAL}.
11824 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
11825 expression indicating the kind parameter of the result.
11828 @item @emph{Return value}:
11829 The return value is of type @code{INTEGER} and of kind @var{KIND}. If
11830 @var{KIND} is absent, the return value is of default integer kind.
11832 @item @emph{Example}:
11834 PROGRAM test_verify
11835 WRITE(*,*) VERIFY("FORTRAN", "AO") ! 1, found 'F'
11836 WRITE(*,*) VERIFY("FORTRAN", "FOO") ! 3, found 'R'
11837 WRITE(*,*) VERIFY("FORTRAN", "C++") ! 1, found 'F'
11838 WRITE(*,*) VERIFY("FORTRAN", "C++", .TRUE.) ! 7, found 'N'
11839 WRITE(*,*) VERIFY("FORTRAN", "FORTRAN") ! 0' found none
11843 @item @emph{See also}:
11844 @ref{SCAN}, @ref{INDEX intrinsic}
11850 @section @code{XOR} --- Bitwise logical exclusive OR
11852 @cindex bitwise logical exclusive or
11853 @cindex logical exclusive or, bitwise
11856 @item @emph{Description}:
11857 Bitwise logical exclusive or.
11859 This intrinsic routine is provided for backwards compatibility with
11860 GNU Fortran 77. For integer arguments, programmers should consider
11861 the use of the @ref{IEOR} intrinsic and for logical arguments the
11862 @code{.NEQV.} operator, which are both defined by the Fortran standard.
11864 @item @emph{Standard}:
11867 @item @emph{Class}:
11870 @item @emph{Syntax}:
11871 @code{RESULT = XOR(I, J)}
11873 @item @emph{Arguments}:
11874 @multitable @columnfractions .15 .70
11875 @item @var{I} @tab The type shall be either a scalar @code{INTEGER}
11876 type or a scalar @code{LOGICAL} type.
11877 @item @var{J} @tab The type shall be the same as the type of @var{I}.
11880 @item @emph{Return value}:
11881 The return type is either a scalar @code{INTEGER} or a scalar
11882 @code{LOGICAL}. If the kind type parameters differ, then the
11883 smaller kind type is implicitly converted to larger kind, and the
11884 return has the larger kind.
11886 @item @emph{Example}:
11889 LOGICAL :: T = .TRUE., F = .FALSE.
11891 DATA a / Z'F' /, b / Z'3' /
11893 WRITE (*,*) XOR(T, T), XOR(T, F), XOR(F, T), XOR(F, F)
11894 WRITE (*,*) XOR(a, b)
11898 @item @emph{See also}:
11899 Fortran 95 elemental function: @ref{IEOR}
11904 @node Intrinsic Modules
11905 @chapter Intrinsic Modules
11906 @cindex intrinsic Modules
11909 * ISO_FORTRAN_ENV::
11911 * OpenMP Modules OMP_LIB and OMP_LIB_KINDS::
11914 @node ISO_FORTRAN_ENV
11915 @section @code{ISO_FORTRAN_ENV}
11917 @item @emph{Standard}:
11918 Fortran 2003 and later, except when otherwise noted
11921 The @code{ISO_FORTRAN_ENV} module provides the following scalar default-integer
11925 @item @code{ATOMIC_INT_KIND}:
11926 Default-kind integer constant to be used as kind parameter when defining
11927 integer variables used in atomic operations. (Fortran 2008 or later.)
11929 @item @code{ATOMIC_LOGICAL_KIND}:
11930 Default-kind integer constant to be used as kind parameter when defining
11931 logical variables used in atomic operations. (Fortran 2008 or later.)
11933 @item @code{CHARACTER_STORAGE_SIZE}:
11934 Size in bits of the character storage unit.
11936 @item @code{ERROR_UNIT}:
11937 Identifies the preconnected unit used for error reporting.
11939 @item @code{FILE_STORAGE_SIZE}:
11940 Size in bits of the file-storage unit.
11942 @item @code{INPUT_UNIT}:
11943 Identifies the preconnected unit identified by the asterisk
11944 (@code{*}) in @code{READ} statement.
11946 @item @code{INT8}, @code{INT16}, @code{INT32}, @code{INT64}:
11947 Kind type parameters to specify an INTEGER type with a storage
11948 size of 16, 32, and 64 bits. It is negative if a target platform
11949 does not support the particular kind. (Fortran 2008 or later.)
11951 @item @code{IOSTAT_END}:
11952 The value assigned to the variable passed to the IOSTAT= specifier of
11953 an input/output statement if an end-of-file condition occurred.
11955 @item @code{IOSTAT_EOR}:
11956 The value assigned to the variable passed to the IOSTAT= specifier of
11957 an input/output statement if an end-of-record condition occurred.
11959 @item @code{IOSTAT_INQUIRE_INTERNAL_UNIT}:
11960 Scalar default-integer constant, used by @code{INQUIRE} for the
11961 IOSTAT= specifier to denote an that a unit number identifies an
11962 internal unit. (Fortran 2008 or later.)
11964 @item @code{NUMERIC_STORAGE_SIZE}:
11965 The size in bits of the numeric storage unit.
11967 @item @code{OUTPUT_UNIT}:
11968 Identifies the preconnected unit identified by the asterisk
11969 (@code{*}) in @code{WRITE} statement.
11971 @item @code{REAL32}, @code{REAL64}, @code{REAL128}:
11972 Kind type parameters to specify a REAL type with a storage
11973 size of 32, 64, and 128 bits. It is negative if a target platform
11974 does not support the particular kind. (Fortran 2008 or later.)
11976 @item @code{STAT_LOCKED}:
11977 Scalar default-integer constant used as STAT= return value by @code{LOCK} to
11978 denote that the lock variable is locked by the executing image. (Fortran 2008
11981 @item @code{STAT_LOCKED_OTHER_IMAGE}:
11982 Scalar default-integer constant used as STAT= return value by @code{UNLOCK} to
11983 denote that the lock variable is locked by another image. (Fortran 2008 or
11986 @item @code{STAT_STOPPED_IMAGE}:
11987 Positive, scalar default-integer constant used as STAT= return value if the
11988 argument in the statement requires synchronisation with an image, which has
11989 initiated the termination of the execution. (Fortran 2008 or later.)
11991 @item @code{STAT_UNLOCKED}:
11992 Scalar default-integer constant used as STAT= return value by @code{UNLOCK} to
11993 denote that the lock variable is unlocked. (Fortran 2008 or later.)
11998 @node ISO_C_BINDING
11999 @section @code{ISO_C_BINDING}
12001 @item @emph{Standard}:
12002 Fortran 2003 and later, GNU extensions
12005 The following intrinsic procedures are provided by the module; their
12006 definition can be found in the section Intrinsic Procedures of this
12010 @item @code{C_ASSOCIATED}
12011 @item @code{C_F_POINTER}
12012 @item @code{C_F_PROCPOINTER}
12013 @item @code{C_FUNLOC}
12016 @c TODO: Vertical spacing between C_FUNLOC and C_LOC wrong in PDF,
12017 @c don't really know why.
12019 The @code{ISO_C_BINDING} module provides the following named constants of
12020 type default integer, which can be used as KIND type parameters.
12022 In addition to the integer named constants required by the Fortran 2003
12023 standard, GNU Fortran provides as an extension named constants for the
12024 128-bit integer types supported by the C compiler: @code{C_INT128_T,
12025 C_INT_LEAST128_T, C_INT_FAST128_T}.
12027 @multitable @columnfractions .15 .35 .35 .35
12028 @item Fortran Type @tab Named constant @tab C type @tab Extension
12029 @item @code{INTEGER}@tab @code{C_INT} @tab @code{int}
12030 @item @code{INTEGER}@tab @code{C_SHORT} @tab @code{short int}
12031 @item @code{INTEGER}@tab @code{C_LONG} @tab @code{long int}
12032 @item @code{INTEGER}@tab @code{C_LONG_LONG} @tab @code{long long int}
12033 @item @code{INTEGER}@tab @code{C_SIGNED_CHAR} @tab @code{signed char}/@code{unsigned char}
12034 @item @code{INTEGER}@tab @code{C_SIZE_T} @tab @code{size_t}
12035 @item @code{INTEGER}@tab @code{C_INT8_T} @tab @code{int8_t}
12036 @item @code{INTEGER}@tab @code{C_INT16_T} @tab @code{int16_t}
12037 @item @code{INTEGER}@tab @code{C_INT32_T} @tab @code{int32_t}
12038 @item @code{INTEGER}@tab @code{C_INT64_T} @tab @code{int64_t}
12039 @item @code{INTEGER}@tab @code{C_INT128_T} @tab @code{int128_t} @tab Ext.
12040 @item @code{INTEGER}@tab @code{C_INT_LEAST8_T} @tab @code{int_least8_t}
12041 @item @code{INTEGER}@tab @code{C_INT_LEAST16_T} @tab @code{int_least16_t}
12042 @item @code{INTEGER}@tab @code{C_INT_LEAST32_T} @tab @code{int_least32_t}
12043 @item @code{INTEGER}@tab @code{C_INT_LEAST64_T} @tab @code{int_least64_t}
12044 @item @code{INTEGER}@tab @code{C_INT_LEAST128_T}@tab @code{int_least128_t} @tab Ext.
12045 @item @code{INTEGER}@tab @code{C_INT_FAST8_T} @tab @code{int_fast8_t}
12046 @item @code{INTEGER}@tab @code{C_INT_FAST16_T} @tab @code{int_fast16_t}
12047 @item @code{INTEGER}@tab @code{C_INT_FAST32_T} @tab @code{int_fast32_t}
12048 @item @code{INTEGER}@tab @code{C_INT_FAST64_T} @tab @code{int_fast64_t}
12049 @item @code{INTEGER}@tab @code{C_INT_FAST128_T} @tab @code{int_fast128_t} @tab Ext.
12050 @item @code{INTEGER}@tab @code{C_INTMAX_T} @tab @code{intmax_t}
12051 @item @code{INTEGER}@tab @code{C_INTPTR_T} @tab @code{intptr_t}
12052 @item @code{REAL} @tab @code{C_FLOAT} @tab @code{float}
12053 @item @code{REAL} @tab @code{C_DOUBLE} @tab @code{double}
12054 @item @code{REAL} @tab @code{C_LONG_DOUBLE} @tab @code{long double}
12055 @item @code{COMPLEX}@tab @code{C_FLOAT_COMPLEX} @tab @code{float _Complex}
12056 @item @code{COMPLEX}@tab @code{C_DOUBLE_COMPLEX}@tab @code{double _Complex}
12057 @item @code{COMPLEX}@tab @code{C_LONG_DOUBLE_COMPLEX}@tab @code{long double _Complex}
12058 @item @code{LOGICAL}@tab @code{C_BOOL} @tab @code{_Bool}
12059 @item @code{CHARACTER}@tab @code{C_CHAR} @tab @code{char}
12062 Additionally, the following parameters of type @code{CHARACTER(KIND=C_CHAR)}
12065 @multitable @columnfractions .20 .45 .15
12066 @item Name @tab C definition @tab Value
12067 @item @code{C_NULL_CHAR} @tab null character @tab @code{'\0'}
12068 @item @code{C_ALERT} @tab alert @tab @code{'\a'}
12069 @item @code{C_BACKSPACE} @tab backspace @tab @code{'\b'}
12070 @item @code{C_FORM_FEED} @tab form feed @tab @code{'\f'}
12071 @item @code{C_NEW_LINE} @tab new line @tab @code{'\n'}
12072 @item @code{C_CARRIAGE_RETURN} @tab carriage return @tab @code{'\r'}
12073 @item @code{C_HORIZONTAL_TAB} @tab horizontal tab @tab @code{'\t'}
12074 @item @code{C_VERTICAL_TAB} @tab vertical tab @tab @code{'\v'}
12077 Moreover, the following two named constants are defined:
12079 @multitable @columnfractions .20 .80
12080 @item Name @tab Type
12081 @item @code{C_NULL_PTR} @tab @code{C_PTR}
12082 @item @code{C_NULL_FUNPTR} @tab @code{C_FUNPTR}
12085 Both are equivalent to the value @code{NULL} in C.
12087 @node OpenMP Modules OMP_LIB and OMP_LIB_KINDS
12088 @section OpenMP Modules @code{OMP_LIB} and @code{OMP_LIB_KINDS}
12090 @item @emph{Standard}:
12091 OpenMP Application Program Interface v3.0
12095 The OpenMP Fortran runtime library routines are provided both in
12096 a form of two Fortran 90 modules, named @code{OMP_LIB} and
12097 @code{OMP_LIB_KINDS}, and in a form of a Fortran @code{include} file named
12098 @file{omp_lib.h}. The procedures provided by @code{OMP_LIB} can be found
12099 in the @ref{Top,,Introduction,libgomp,GNU OpenMP runtime library} manual,
12100 the named constants defined in the @code{OMP_LIB_KINDS} module are listed
12103 For details refer to the actual
12104 @uref{http://www.openmp.org/mp-documents/spec30.pdf,
12105 OpenMP Application Program Interface v3.0}.
12107 @code{OMP_LIB_KINDS} provides the following scalar default-integer
12111 @item @code{omp_integer_kind}
12112 @item @code{omp_logical_kind}
12113 @item @code{omp_lock_kind}
12114 @item @code{omp_nest_lock_kind}
12115 @item @code{omp_sched_kind}