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{EXIT}: EXIT, Exit the program with status.
108 * @code{EXP}: EXP, Exponential function
109 * @code{EXPONENT}: EXPONENT, Exponent function
110 * @code{EXTENDS_TYPE_OF}: EXTENDS_TYPE_OF, Query dynamic type for extension
111 * @code{FDATE}: FDATE, Subroutine (or function) to get the current time as a string
112 * @code{FGET}: FGET, Read a single character in stream mode from stdin
113 * @code{FGETC}: FGETC, Read a single character in stream mode
114 * @code{FLOOR}: FLOOR, Integer floor function
115 * @code{FLUSH}: FLUSH, Flush I/O unit(s)
116 * @code{FNUM}: FNUM, File number function
117 * @code{FPUT}: FPUT, Write a single character in stream mode to stdout
118 * @code{FPUTC}: FPUTC, Write a single character in stream mode
119 * @code{FRACTION}: FRACTION, Fractional part of the model representation
120 * @code{FREE}: FREE, Memory de-allocation subroutine
121 * @code{FSEEK}: FSEEK, Low level file positioning subroutine
122 * @code{FSTAT}: FSTAT, Get file status
123 * @code{FTELL}: FTELL, Current stream position
124 * @code{GAMMA}: GAMMA, Gamma function
125 * @code{GERROR}: GERROR, Get last system error message
126 * @code{GETARG}: GETARG, Get command line arguments
127 * @code{GET_COMMAND}: GET_COMMAND, Get the entire command line
128 * @code{GET_COMMAND_ARGUMENT}: GET_COMMAND_ARGUMENT, Get command line arguments
129 * @code{GETCWD}: GETCWD, Get current working directory
130 * @code{GETENV}: GETENV, Get an environmental variable
131 * @code{GET_ENVIRONMENT_VARIABLE}: GET_ENVIRONMENT_VARIABLE, Get an environmental variable
132 * @code{GETGID}: GETGID, Group ID function
133 * @code{GETLOG}: GETLOG, Get login name
134 * @code{GETPID}: GETPID, Process ID function
135 * @code{GETUID}: GETUID, User ID function
136 * @code{GMTIME}: GMTIME, Convert time to GMT info
137 * @code{HOSTNM}: HOSTNM, Get system host name
138 * @code{HUGE}: HUGE, Largest number of a kind
139 * @code{HYPOT}: HYPOT, Euclidian distance function
140 * @code{IACHAR}: IACHAR, Code in @acronym{ASCII} collating sequence
141 * @code{IAND}: IAND, Bitwise logical and
142 * @code{IARGC}: IARGC, Get the number of command line arguments
143 * @code{IBCLR}: IBCLR, Clear bit
144 * @code{IBITS}: IBITS, Bit extraction
145 * @code{IBSET}: IBSET, Set bit
146 * @code{ICHAR}: ICHAR, Character-to-integer conversion function
147 * @code{IDATE}: IDATE, Current local time (day/month/year)
148 * @code{IEOR}: IEOR, Bitwise logical exclusive or
149 * @code{IERRNO}: IERRNO, Function to get the last system error number
150 * @code{INDEX}: INDEX intrinsic, Position of a substring within a string
151 * @code{INT}: INT, Convert to integer type
152 * @code{INT2}: INT2, Convert to 16-bit integer type
153 * @code{INT8}: INT8, Convert to 64-bit integer type
154 * @code{IOR}: IOR, Bitwise logical or
155 * @code{IRAND}: IRAND, Integer pseudo-random number
156 * @code{IMAGE_INDEX}: IMAGE_INDEX, Cosubscript to image index convertion
157 * @code{IS_IOSTAT_END}: IS_IOSTAT_END, Test for end-of-file value
158 * @code{IS_IOSTAT_EOR}: IS_IOSTAT_EOR, Test for end-of-record value
159 * @code{ISATTY}: ISATTY, Whether a unit is a terminal device
160 * @code{ISHFT}: ISHFT, Shift bits
161 * @code{ISHFTC}: ISHFTC, Shift bits circularly
162 * @code{ISNAN}: ISNAN, Tests for a NaN
163 * @code{ITIME}: ITIME, Current local time (hour/minutes/seconds)
164 * @code{KILL}: KILL, Send a signal to a process
165 * @code{KIND}: KIND, Kind of an entity
166 * @code{LBOUND}: LBOUND, Lower dimension bounds of an array
167 * @code{LCOBOUND}: LCOBOUND, Lower codimension bounds of an array
168 * @code{LEADZ}: LEADZ, Number of leading zero bits of an integer
169 * @code{LEN}: LEN, Length of a character entity
170 * @code{LEN_TRIM}: LEN_TRIM, Length of a character entity without trailing blank characters
171 * @code{LGE}: LGE, Lexical greater than or equal
172 * @code{LGT}: LGT, Lexical greater than
173 * @code{LINK}: LINK, Create a hard link
174 * @code{LLE}: LLE, Lexical less than or equal
175 * @code{LLT}: LLT, Lexical less than
176 * @code{LNBLNK}: LNBLNK, Index of the last non-blank character in a string
177 * @code{LOC}: LOC, Returns the address of a variable
178 * @code{LOG}: LOG, Logarithm function
179 * @code{LOG10}: LOG10, Base 10 logarithm function
180 * @code{LOG_GAMMA}: LOG_GAMMA, Logarithm of the Gamma function
181 * @code{LOGICAL}: LOGICAL, Convert to logical type
182 * @code{LONG}: LONG, Convert to integer type
183 * @code{LSHIFT}: LSHIFT, Left shift bits
184 * @code{LSTAT}: LSTAT, Get file status
185 * @code{LTIME}: LTIME, Convert time to local time info
186 * @code{MALLOC}: MALLOC, Dynamic memory allocation function
187 * @code{MATMUL}: MATMUL, matrix multiplication
188 * @code{MAX}: MAX, Maximum value of an argument list
189 * @code{MAXEXPONENT}: MAXEXPONENT, Maximum exponent of a real kind
190 * @code{MAXLOC}: MAXLOC, Location of the maximum value within an array
191 * @code{MAXVAL}: MAXVAL, Maximum value of an array
192 * @code{MCLOCK}: MCLOCK, Time function
193 * @code{MCLOCK8}: MCLOCK8, Time function (64-bit)
194 * @code{MERGE}: MERGE, Merge arrays
195 * @code{MIN}: MIN, Minimum value of an argument list
196 * @code{MINEXPONENT}: MINEXPONENT, Minimum exponent of a real kind
197 * @code{MINLOC}: MINLOC, Location of the minimum value within an array
198 * @code{MINVAL}: MINVAL, Minimum value of an array
199 * @code{MOD}: MOD, Remainder function
200 * @code{MODULO}: MODULO, Modulo function
201 * @code{MOVE_ALLOC}: MOVE_ALLOC, Move allocation from one object to another
202 * @code{MVBITS}: MVBITS, Move bits from one integer to another
203 * @code{NEAREST}: NEAREST, Nearest representable number
204 * @code{NEW_LINE}: NEW_LINE, New line character
205 * @code{NINT}: NINT, Nearest whole number
206 * @code{NORM2}: NORM2, Euclidean vector norm
207 * @code{NOT}: NOT, Logical negation
208 * @code{NULL}: NULL, Function that returns an disassociated pointer
209 * @code{NUM_IMAGES}: NUM_IMAGES, Number of images
210 * @code{OR}: OR, Bitwise logical OR
211 * @code{PACK}: PACK, Pack an array into an array of rank one
212 * @code{PARITY}: PARITY, Reduction with exclusive OR
213 * @code{PERROR}: PERROR, Print system error message
214 * @code{POPCNT}: POPCNT, Number of bits set
215 * @code{POPPAR}: POPPAR, Parity of the number of bits set
216 * @code{PRECISION}: PRECISION, Decimal precision of a real kind
217 * @code{PRESENT}: PRESENT, Determine whether an optional dummy argument is specified
218 * @code{PRODUCT}: PRODUCT, Product of array elements
219 * @code{RADIX}: RADIX, Base of a data model
220 * @code{RANDOM_NUMBER}: RANDOM_NUMBER, Pseudo-random number
221 * @code{RANDOM_SEED}: RANDOM_SEED, Initialize a pseudo-random number sequence
222 * @code{RAND}: RAND, Real pseudo-random number
223 * @code{RANGE}: RANGE, Decimal exponent range
224 * @code{RAN}: RAN, Real pseudo-random number
225 * @code{REAL}: REAL, Convert to real type
226 * @code{RENAME}: RENAME, Rename a file
227 * @code{REPEAT}: REPEAT, Repeated string concatenation
228 * @code{RESHAPE}: RESHAPE, Function to reshape an array
229 * @code{RRSPACING}: RRSPACING, Reciprocal of the relative spacing
230 * @code{RSHIFT}: RSHIFT, Right shift bits
231 * @code{SAME_TYPE_AS}: SAME_TYPE_AS, Query dynamic types for equality
232 * @code{SCALE}: SCALE, Scale a real value
233 * @code{SCAN}: SCAN, Scan a string for the presence of a set of characters
234 * @code{SECNDS}: SECNDS, Time function
235 * @code{SECOND}: SECOND, CPU time function
236 * @code{SELECTED_CHAR_KIND}: SELECTED_CHAR_KIND, Choose character kind
237 * @code{SELECTED_INT_KIND}: SELECTED_INT_KIND, Choose integer kind
238 * @code{SELECTED_REAL_KIND}: SELECTED_REAL_KIND, Choose real kind
239 * @code{SET_EXPONENT}: SET_EXPONENT, Set the exponent of the model
240 * @code{SHAPE}: SHAPE, Determine the shape of an array
241 * @code{SIGN}: SIGN, Sign copying function
242 * @code{SIGNAL}: SIGNAL, Signal handling subroutine (or function)
243 * @code{SIN}: SIN, Sine function
244 * @code{SINH}: SINH, Hyperbolic sine function
245 * @code{SIZE}: SIZE, Function to determine the size of an array
246 * @code{SIZEOF}: SIZEOF, Determine the size in bytes of an expression
247 * @code{SLEEP}: SLEEP, Sleep for the specified number of seconds
248 * @code{SPACING}: SPACING, Smallest distance between two numbers of a given type
249 * @code{SPREAD}: SPREAD, Add a dimension to an array
250 * @code{SQRT}: SQRT, Square-root function
251 * @code{SRAND}: SRAND, Reinitialize the random number generator
252 * @code{STAT}: STAT, Get file status
253 * @code{STORAGE_SIZE}: STORAGE_SIZE, Storage size in bits
254 * @code{SUM}: SUM, Sum of array elements
255 * @code{SYMLNK}: SYMLNK, Create a symbolic link
256 * @code{SYSTEM}: SYSTEM, Execute a shell command
257 * @code{SYSTEM_CLOCK}: SYSTEM_CLOCK, Time function
258 * @code{TAN}: TAN, Tangent function
259 * @code{TANH}: TANH, Hyperbolic tangent function
260 * @code{THIS_IMAGE}: THIS_IMAGE, Cosubscript index of this image
261 * @code{TIME}: TIME, Time function
262 * @code{TIME8}: TIME8, Time function (64-bit)
263 * @code{TINY}: TINY, Smallest positive number of a real kind
264 * @code{TRAILZ}: TRAILZ, Number of trailing zero bits of an integer
265 * @code{TRANSFER}: TRANSFER, Transfer bit patterns
266 * @code{TRANSPOSE}: TRANSPOSE, Transpose an array of rank two
267 * @code{TRIM}: TRIM, Remove trailing blank characters of a string
268 * @code{TTYNAM}: TTYNAM, Get the name of a terminal device.
269 * @code{UBOUND}: UBOUND, Upper dimension bounds of an array
270 * @code{UCOBOUND}: UCOBOUND, Upper codimension bounds of an array
271 * @code{UMASK}: UMASK, Set the file creation mask
272 * @code{UNLINK}: UNLINK, Remove a file from the file system
273 * @code{UNPACK}: UNPACK, Unpack an array of rank one into an array
274 * @code{VERIFY}: VERIFY, Scan a string for the absence of a set of characters
275 * @code{XOR}: XOR, Bitwise logical exclusive or
278 @node Introduction to Intrinsics
279 @section Introduction to intrinsic procedures
281 The intrinsic procedures provided by GNU Fortran include all of the
282 intrinsic procedures required by the Fortran 95 standard, a set of
283 intrinsic procedures for backwards compatibility with G77, and a
284 selection of intrinsic procedures from the Fortran 2003 and Fortran 2008
285 standards. Any conflict between a description here and a description in
286 either the Fortran 95 standard, the Fortran 2003 standard or the Fortran
287 2008 standard is unintentional, and the standard(s) should be considered
290 The enumeration of the @code{KIND} type parameter is processor defined in
291 the Fortran 95 standard. GNU Fortran defines the default integer type and
292 default real type by @code{INTEGER(KIND=4)} and @code{REAL(KIND=4)},
293 respectively. The standard mandates that both data types shall have
294 another kind, which have more precision. On typical target architectures
295 supported by @command{gfortran}, this kind type parameter is @code{KIND=8}.
296 Hence, @code{REAL(KIND=8)} and @code{DOUBLE PRECISION} are equivalent.
297 In the description of generic intrinsic procedures, the kind type parameter
298 will be specified by @code{KIND=*}, and in the description of specific
299 names for an intrinsic procedure the kind type parameter will be explicitly
300 given (e.g., @code{REAL(KIND=4)} or @code{REAL(KIND=8)}). Finally, for
301 brevity the optional @code{KIND=} syntax will be omitted.
303 Many of the intrinsic procedures take one or more optional arguments.
304 This document follows the convention used in the Fortran 95 standard,
305 and denotes such arguments by square brackets.
307 GNU Fortran offers the @option{-std=f95} and @option{-std=gnu} options,
308 which can be used to restrict the set of intrinsic procedures to a
309 given standard. By default, @command{gfortran} sets the @option{-std=gnu}
310 option, and so all intrinsic procedures described here are accepted. There
311 is one caveat. For a select group of intrinsic procedures, @command{g77}
312 implemented both a function and a subroutine. Both classes
313 have been implemented in @command{gfortran} for backwards compatibility
314 with @command{g77}. It is noted here that these functions and subroutines
315 cannot be intermixed in a given subprogram. In the descriptions that follow,
316 the applicable standard for each intrinsic procedure is noted.
321 @section @code{ABORT} --- Abort the program
323 @cindex program termination, with core dump
324 @cindex terminate program, with core dump
328 @item @emph{Description}:
329 @code{ABORT} causes immediate termination of the program. On operating
330 systems that support a core dump, @code{ABORT} will produce a core dump even if
331 the option @option{-fno-dump-core} is in effect, which is suitable for debugging
333 @c TODO: Check if this (with -fno-dump-core) is correct.
335 @item @emph{Standard}:
344 @item @emph{Return value}:
347 @item @emph{Example}:
350 integer :: i = 1, j = 2
351 if (i /= j) call abort
352 end program test_abort
355 @item @emph{See also}:
356 @ref{EXIT}, @ref{KILL}
363 @section @code{ABS} --- Absolute value
370 @cindex absolute value
373 @item @emph{Description}:
374 @code{ABS(A)} computes the absolute value of @code{A}.
376 @item @emph{Standard}:
377 Fortran 77 and later, has overloads that are GNU extensions
383 @code{RESULT = ABS(A)}
385 @item @emph{Arguments}:
386 @multitable @columnfractions .15 .70
387 @item @var{A} @tab The type of the argument shall be an @code{INTEGER},
388 @code{REAL}, or @code{COMPLEX}.
391 @item @emph{Return value}:
392 The return value is of the same type and
393 kind as the argument except the return value is @code{REAL} for a
394 @code{COMPLEX} argument.
396 @item @emph{Example}:
401 complex :: z = (-1.e0,0.e0)
408 @item @emph{Specific names}:
409 @multitable @columnfractions .20 .20 .20 .25
410 @item Name @tab Argument @tab Return type @tab Standard
411 @item @code{ABS(A)} @tab @code{REAL(4) A} @tab @code{REAL(4)} @tab Fortran 77 and later
412 @item @code{CABS(A)} @tab @code{COMPLEX(4) A} @tab @code{REAL(4)} @tab Fortran 77 and later
413 @item @code{DABS(A)} @tab @code{REAL(8) A} @tab @code{REAL(8)} @tab Fortran 77 and later
414 @item @code{IABS(A)} @tab @code{INTEGER(4) A} @tab @code{INTEGER(4)} @tab Fortran 77 and later
415 @item @code{ZABS(A)} @tab @code{COMPLEX(8) A} @tab @code{COMPLEX(8)} @tab GNU extension
416 @item @code{CDABS(A)} @tab @code{COMPLEX(8) A} @tab @code{COMPLEX(8)} @tab GNU extension
423 @section @code{ACCESS} --- Checks file access modes
425 @cindex file system, access mode
428 @item @emph{Description}:
429 @code{ACCESS(NAME, MODE)} checks whether the file @var{NAME}
430 exists, is readable, writable or executable. Except for the
431 executable check, @code{ACCESS} can be replaced by
432 Fortran 95's @code{INQUIRE}.
434 @item @emph{Standard}:
441 @code{RESULT = ACCESS(NAME, MODE)}
443 @item @emph{Arguments}:
444 @multitable @columnfractions .15 .70
445 @item @var{NAME} @tab Scalar @code{CHARACTER} of default kind with the
446 file name. Tailing blank are ignored unless the character @code{achar(0)}
447 is present, then all characters up to and excluding @code{achar(0)} are
449 @item @var{MODE} @tab Scalar @code{CHARACTER} of default kind with the
450 file access mode, may be any concatenation of @code{"r"} (readable),
451 @code{"w"} (writable) and @code{"x"} (executable), or @code{" "} to check
455 @item @emph{Return value}:
456 Returns a scalar @code{INTEGER}, which is @code{0} if the file is
457 accessible in the given mode; otherwise or if an invalid argument
458 has been given for @code{MODE} the value @code{1} is returned.
460 @item @emph{Example}:
464 character(len=*), parameter :: file = 'test.dat'
465 character(len=*), parameter :: file2 = 'test.dat '//achar(0)
466 if(access(file,' ') == 0) print *, trim(file),' is exists'
467 if(access(file,'r') == 0) print *, trim(file),' is readable'
468 if(access(file,'w') == 0) print *, trim(file),' is writable'
469 if(access(file,'x') == 0) print *, trim(file),' is executable'
470 if(access(file2,'rwx') == 0) &
471 print *, trim(file2),' is readable, writable and executable'
472 end program access_test
474 @item @emph{Specific names}:
475 @item @emph{See also}:
482 @section @code{ACHAR} --- Character in @acronym{ASCII} collating sequence
484 @cindex @acronym{ASCII} collating sequence
485 @cindex collating sequence, @acronym{ASCII}
488 @item @emph{Description}:
489 @code{ACHAR(I)} returns the character located at position @code{I}
490 in the @acronym{ASCII} collating sequence.
492 @item @emph{Standard}:
493 Fortran 77 and later, with @var{KIND} argument Fortran 2003 and later
499 @code{RESULT = ACHAR(I [, KIND])}
501 @item @emph{Arguments}:
502 @multitable @columnfractions .15 .70
503 @item @var{I} @tab The type shall be @code{INTEGER}.
504 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
505 expression indicating the kind parameter of the result.
508 @item @emph{Return value}:
509 The return value is of type @code{CHARACTER} with a length of one.
510 If the @var{KIND} argument is present, the return value is of the
511 specified kind and of the default kind otherwise.
513 @item @emph{Example}:
518 end program test_achar
522 See @ref{ICHAR} for a discussion of converting between numerical values
523 and formatted string representations.
525 @item @emph{See also}:
526 @ref{CHAR}, @ref{IACHAR}, @ref{ICHAR}
533 @section @code{ACOS} --- Arccosine function
536 @cindex trigonometric function, cosine, inverse
537 @cindex cosine, inverse
540 @item @emph{Description}:
541 @code{ACOS(X)} computes the arccosine of @var{X} (inverse of @code{COS(X)}).
543 @item @emph{Standard}:
544 Fortran 77 and later, for a complex argument Fortran 2008 or later
550 @code{RESULT = ACOS(X)}
552 @item @emph{Arguments}:
553 @multitable @columnfractions .15 .70
554 @item @var{X} @tab The type shall either be @code{REAL} with a magnitude that is
555 less than or equal to one - or the type shall be @code{COMPLEX}.
558 @item @emph{Return value}:
559 The return value is of the same type and kind as @var{X}.
560 The real part of the result is in radians and lies in the range
561 @math{0 \leq \Re \acos(x) \leq \pi}.
563 @item @emph{Example}:
566 real(8) :: x = 0.866_8
568 end program test_acos
571 @item @emph{Specific names}:
572 @multitable @columnfractions .20 .20 .20 .25
573 @item Name @tab Argument @tab Return type @tab Standard
574 @item @code{ACOS(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab Fortran 77 and later
575 @item @code{DACOS(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab Fortran 77 and later
578 @item @emph{See also}:
579 Inverse function: @ref{COS}
586 @section @code{ACOSH} --- Inverse hyperbolic cosine function
589 @cindex area hyperbolic cosine
590 @cindex inverse hyperbolic cosine
591 @cindex hyperbolic function, cosine, inverse
592 @cindex cosine, hyperbolic, inverse
595 @item @emph{Description}:
596 @code{ACOSH(X)} computes the inverse hyperbolic cosine of @var{X}.
598 @item @emph{Standard}:
599 Fortran 2008 and later
605 @code{RESULT = ACOSH(X)}
607 @item @emph{Arguments}:
608 @multitable @columnfractions .15 .70
609 @item @var{X} @tab The type shall be @code{REAL} or @code{COMPLEX}.
612 @item @emph{Return value}:
613 The return value has the same type and kind as @var{X}. If @var{X} is
614 complex, the imaginary part of the result is in radians and lies between
615 @math{ 0 \leq \Im \acosh(x) \leq \pi}.
617 @item @emph{Example}:
620 REAL(8), DIMENSION(3) :: x = (/ 1.0, 2.0, 3.0 /)
625 @item @emph{Specific names}:
626 @multitable @columnfractions .20 .20 .20 .25
627 @item Name @tab Argument @tab Return type @tab Standard
628 @item @code{DACOSH(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU extension
631 @item @emph{See also}:
632 Inverse function: @ref{COSH}
638 @section @code{ADJUSTL} --- Left adjust a string
640 @cindex string, adjust left
641 @cindex adjust string
644 @item @emph{Description}:
645 @code{ADJUSTL(STRING)} will left adjust a string by removing leading spaces.
646 Spaces are inserted at the end of the string as needed.
648 @item @emph{Standard}:
655 @code{RESULT = ADJUSTL(STRING)}
657 @item @emph{Arguments}:
658 @multitable @columnfractions .15 .70
659 @item @var{STRING} @tab The type shall be @code{CHARACTER}.
662 @item @emph{Return value}:
663 The return value is of type @code{CHARACTER} and of the same kind as
664 @var{STRING} where leading spaces are removed and the same number of
665 spaces are inserted on the end of @var{STRING}.
667 @item @emph{Example}:
670 character(len=20) :: str = ' gfortran'
673 end program test_adjustl
676 @item @emph{See also}:
677 @ref{ADJUSTR}, @ref{TRIM}
683 @section @code{ADJUSTR} --- Right adjust a string
685 @cindex string, adjust right
686 @cindex adjust string
689 @item @emph{Description}:
690 @code{ADJUSTR(STRING)} will right adjust a string by removing trailing spaces.
691 Spaces are inserted at the start of the string as needed.
693 @item @emph{Standard}:
700 @code{RESULT = ADJUSTR(STRING)}
702 @item @emph{Arguments}:
703 @multitable @columnfractions .15 .70
704 @item @var{STR} @tab The type shall be @code{CHARACTER}.
707 @item @emph{Return value}:
708 The return value is of type @code{CHARACTER} and of the same kind as
709 @var{STRING} where trailing spaces are removed and the same number of
710 spaces are inserted at the start of @var{STRING}.
712 @item @emph{Example}:
715 character(len=20) :: str = 'gfortran'
718 end program test_adjustr
721 @item @emph{See also}:
722 @ref{ADJUSTL}, @ref{TRIM}
728 @section @code{AIMAG} --- Imaginary part of complex number
733 @cindex complex numbers, imaginary part
736 @item @emph{Description}:
737 @code{AIMAG(Z)} yields the imaginary part of complex argument @code{Z}.
738 The @code{IMAG(Z)} and @code{IMAGPART(Z)} intrinsic functions are provided
739 for compatibility with @command{g77}, and their use in new code is
740 strongly discouraged.
742 @item @emph{Standard}:
743 Fortran 77 and later, has overloads that are GNU extensions
749 @code{RESULT = AIMAG(Z)}
751 @item @emph{Arguments}:
752 @multitable @columnfractions .15 .70
753 @item @var{Z} @tab The type of the argument shall be @code{COMPLEX}.
756 @item @emph{Return value}:
757 The return value is of type @code{REAL} with the
758 kind type parameter of the argument.
760 @item @emph{Example}:
765 z4 = cmplx(1.e0_4, 0.e0_4)
766 z8 = cmplx(0.e0_8, 1.e0_8)
767 print *, aimag(z4), dimag(z8)
768 end program test_aimag
771 @item @emph{Specific names}:
772 @multitable @columnfractions .20 .20 .20 .25
773 @item Name @tab Argument @tab Return type @tab Standard
774 @item @code{AIMAG(Z)} @tab @code{COMPLEX Z} @tab @code{REAL} @tab GNU extension
775 @item @code{DIMAG(Z)} @tab @code{COMPLEX(8) Z} @tab @code{REAL(8)} @tab GNU extension
776 @item @code{IMAG(Z)} @tab @code{COMPLEX Z} @tab @code{REAL} @tab GNU extension
777 @item @code{IMAGPART(Z)} @tab @code{COMPLEX Z} @tab @code{REAL} @tab GNU extension
784 @section @code{AINT} --- Truncate to a whole number
788 @cindex rounding, floor
791 @item @emph{Description}:
792 @code{AINT(A [, KIND])} truncates its argument to a whole number.
794 @item @emph{Standard}:
801 @code{RESULT = AINT(A [, KIND])}
803 @item @emph{Arguments}:
804 @multitable @columnfractions .15 .70
805 @item @var{A} @tab The type of the argument shall be @code{REAL}.
806 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
807 expression indicating the kind parameter of the result.
810 @item @emph{Return value}:
811 The return value is of type @code{REAL} with the kind type parameter of the
812 argument if the optional @var{KIND} is absent; otherwise, the kind
813 type parameter will be given by @var{KIND}. If the magnitude of
814 @var{X} is less than one, @code{AINT(X)} returns zero. If the
815 magnitude is equal to or greater than one then it returns the largest
816 whole number that does not exceed its magnitude. The sign is the same
817 as the sign of @var{X}.
819 @item @emph{Example}:
826 print *, aint(x4), dint(x8)
828 end program test_aint
831 @item @emph{Specific names}:
832 @multitable @columnfractions .20 .20 .20 .25
833 @item Name @tab Argument @tab Return type @tab Standard
834 @item @code{AINT(A)} @tab @code{REAL(4) A} @tab @code{REAL(4)} @tab Fortran 77 and later
835 @item @code{DINT(A)} @tab @code{REAL(8) A} @tab @code{REAL(8)} @tab Fortran 77 and later
842 @section @code{ALARM} --- Execute a routine after a given delay
844 @cindex delayed execution
847 @item @emph{Description}:
848 @code{ALARM(SECONDS, HANDLER [, STATUS])} causes external subroutine @var{HANDLER}
849 to be executed after a delay of @var{SECONDS} by using @code{alarm(2)} to
850 set up a signal and @code{signal(2)} to catch it. If @var{STATUS} is
851 supplied, it will be returned with the number of seconds remaining until
852 any previously scheduled alarm was due to be delivered, or zero if there
853 was no previously scheduled alarm.
855 @item @emph{Standard}:
862 @code{CALL ALARM(SECONDS, HANDLER [, STATUS])}
864 @item @emph{Arguments}:
865 @multitable @columnfractions .15 .70
866 @item @var{SECONDS} @tab The type of the argument shall be a scalar
867 @code{INTEGER}. It is @code{INTENT(IN)}.
868 @item @var{HANDLER} @tab Signal handler (@code{INTEGER FUNCTION} or
869 @code{SUBROUTINE}) or dummy/global @code{INTEGER} scalar. The scalar
870 values may be either @code{SIG_IGN=1} to ignore the alarm generated
871 or @code{SIG_DFL=0} to set the default action. It is @code{INTENT(IN)}.
872 @item @var{STATUS} @tab (Optional) @var{STATUS} shall be a scalar
873 variable of the default @code{INTEGER} kind. It is @code{INTENT(OUT)}.
876 @item @emph{Example}:
879 external handler_print
881 call alarm (3, handler_print, i)
884 end program test_alarm
886 This will cause the external routine @var{handler_print} to be called
893 @section @code{ALL} --- All values in @var{MASK} along @var{DIM} are true
895 @cindex array, apply condition
896 @cindex array, condition testing
899 @item @emph{Description}:
900 @code{ALL(MASK [, DIM])} determines if all the values are true in @var{MASK}
901 in the array along dimension @var{DIM}.
903 @item @emph{Standard}:
907 Transformational function
910 @code{RESULT = ALL(MASK [, DIM])}
912 @item @emph{Arguments}:
913 @multitable @columnfractions .15 .70
914 @item @var{MASK} @tab The type of the argument shall be @code{LOGICAL} and
915 it shall not be scalar.
916 @item @var{DIM} @tab (Optional) @var{DIM} shall be a scalar integer
917 with a value that lies between one and the rank of @var{MASK}.
920 @item @emph{Return value}:
921 @code{ALL(MASK)} returns a scalar value of type @code{LOGICAL} where
922 the kind type parameter is the same as the kind type parameter of
923 @var{MASK}. If @var{DIM} is present, then @code{ALL(MASK, DIM)} returns
924 an array with the rank of @var{MASK} minus 1. The shape is determined from
925 the shape of @var{MASK} where the @var{DIM} dimension is elided.
929 @code{ALL(MASK)} is true if all elements of @var{MASK} are true.
930 It also is true if @var{MASK} has zero size; otherwise, it is false.
932 If the rank of @var{MASK} is one, then @code{ALL(MASK,DIM)} is equivalent
933 to @code{ALL(MASK)}. If the rank is greater than one, then @code{ALL(MASK,DIM)}
934 is determined by applying @code{ALL} to the array sections.
937 @item @emph{Example}:
941 l = all((/.true., .true., .true./))
946 integer a(2,3), b(2,3)
950 print *, all(a .eq. b, 1)
951 print *, all(a .eq. b, 2)
952 end subroutine section
960 @section @code{ALLOCATED} --- Status of an allocatable entity
962 @cindex allocation, status
965 @item @emph{Description}:
966 @code{ALLOCATED(ARRAY)} and @code{ALLOCATED(SCALAR)} check the allocation
967 status of @var{ARRAY} and @var{SCALAR}, respectively.
969 @item @emph{Standard}:
970 Fortran 95 and later. Note, the @code{SCALAR=} keyword and allocatable
971 scalar entities are available in Fortran 2003 and later.
977 @code{RESULT = ALLOCATED(ARRAY)} or @code{RESULT = ALLOCATED(SCALAR)}
979 @item @emph{Arguments}:
980 @multitable @columnfractions .15 .70
981 @item @var{ARRAY} @tab The argument shall be an @code{ALLOCATABLE} array.
982 @item @var{SCALAR} @tab The argument shall be an @code{ALLOCATABLE} scalar.
985 @item @emph{Return value}:
986 The return value is a scalar @code{LOGICAL} with the default logical
987 kind type parameter. If the argument is allocated, then the result is
988 @code{.TRUE.}; otherwise, it returns @code{.FALSE.}
990 @item @emph{Example}:
992 program test_allocated
994 real(4), allocatable :: x(:)
995 if (.not. allocated(x)) allocate(x(i))
996 end program test_allocated
1003 @section @code{AND} --- Bitwise logical AND
1005 @cindex bitwise logical and
1006 @cindex logical and, bitwise
1009 @item @emph{Description}:
1010 Bitwise logical @code{AND}.
1012 This intrinsic routine is provided for backwards compatibility with
1013 GNU Fortran 77. For integer arguments, programmers should consider
1014 the use of the @ref{IAND} intrinsic defined by the Fortran standard.
1016 @item @emph{Standard}:
1022 @item @emph{Syntax}:
1023 @code{RESULT = AND(I, J)}
1025 @item @emph{Arguments}:
1026 @multitable @columnfractions .15 .70
1027 @item @var{I} @tab The type shall be either a scalar @code{INTEGER}
1028 type or a scalar @code{LOGICAL} type.
1029 @item @var{J} @tab The type shall be the same as the type of @var{I}.
1032 @item @emph{Return value}:
1033 The return type is either a scalar @code{INTEGER} or a scalar
1034 @code{LOGICAL}. If the kind type parameters differ, then the
1035 smaller kind type is implicitly converted to larger kind, and the
1036 return has the larger kind.
1038 @item @emph{Example}:
1041 LOGICAL :: T = .TRUE., F = .FALSE.
1043 DATA a / Z'F' /, b / Z'3' /
1045 WRITE (*,*) AND(T, T), AND(T, F), AND(F, T), AND(F, F)
1046 WRITE (*,*) AND(a, b)
1050 @item @emph{See also}:
1051 Fortran 95 elemental function: @ref{IAND}
1057 @section @code{ANINT} --- Nearest whole number
1061 @cindex rounding, ceiling
1064 @item @emph{Description}:
1065 @code{ANINT(A [, KIND])} rounds its argument to the nearest whole number.
1067 @item @emph{Standard}:
1068 Fortran 77 and later
1073 @item @emph{Syntax}:
1074 @code{RESULT = ANINT(A [, KIND])}
1076 @item @emph{Arguments}:
1077 @multitable @columnfractions .15 .70
1078 @item @var{A} @tab The type of the argument shall be @code{REAL}.
1079 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
1080 expression indicating the kind parameter of the result.
1083 @item @emph{Return value}:
1084 The return value is of type real with the kind type parameter of the
1085 argument if the optional @var{KIND} is absent; otherwise, the kind
1086 type parameter will be given by @var{KIND}. If @var{A} is greater than
1087 zero, @code{ANINT(A)} returns @code{AINT(X+0.5)}. If @var{A} is
1088 less than or equal to zero then it returns @code{AINT(X-0.5)}.
1090 @item @emph{Example}:
1097 print *, anint(x4), dnint(x8)
1099 end program test_anint
1102 @item @emph{Specific names}:
1103 @multitable @columnfractions .20 .20 .20 .25
1104 @item Name @tab Argument @tab Return type @tab Standard
1105 @item @code{AINT(A)} @tab @code{REAL(4) A} @tab @code{REAL(4)} @tab Fortran 77 and later
1106 @item @code{DNINT(A)} @tab @code{REAL(8) A} @tab @code{REAL(8)} @tab Fortran 77 and later
1113 @section @code{ANY} --- Any value in @var{MASK} along @var{DIM} is true
1115 @cindex array, apply condition
1116 @cindex array, condition testing
1119 @item @emph{Description}:
1120 @code{ANY(MASK [, DIM])} determines if any of the values in the logical array
1121 @var{MASK} along dimension @var{DIM} are @code{.TRUE.}.
1123 @item @emph{Standard}:
1124 Fortran 95 and later
1127 Transformational function
1129 @item @emph{Syntax}:
1130 @code{RESULT = ANY(MASK [, DIM])}
1132 @item @emph{Arguments}:
1133 @multitable @columnfractions .15 .70
1134 @item @var{MASK} @tab The type of the argument shall be @code{LOGICAL} and
1135 it shall not be scalar.
1136 @item @var{DIM} @tab (Optional) @var{DIM} shall be a scalar integer
1137 with a value that lies between one and the rank of @var{MASK}.
1140 @item @emph{Return value}:
1141 @code{ANY(MASK)} returns a scalar value of type @code{LOGICAL} where
1142 the kind type parameter is the same as the kind type parameter of
1143 @var{MASK}. If @var{DIM} is present, then @code{ANY(MASK, DIM)} returns
1144 an array with the rank of @var{MASK} minus 1. The shape is determined from
1145 the shape of @var{MASK} where the @var{DIM} dimension is elided.
1149 @code{ANY(MASK)} is true if any element of @var{MASK} is true;
1150 otherwise, it is false. It also is false if @var{MASK} has zero size.
1152 If the rank of @var{MASK} is one, then @code{ANY(MASK,DIM)} is equivalent
1153 to @code{ANY(MASK)}. If the rank is greater than one, then @code{ANY(MASK,DIM)}
1154 is determined by applying @code{ANY} to the array sections.
1157 @item @emph{Example}:
1161 l = any((/.true., .true., .true./))
1166 integer a(2,3), b(2,3)
1170 print *, any(a .eq. b, 1)
1171 print *, any(a .eq. b, 2)
1172 end subroutine section
1173 end program test_any
1180 @section @code{ASIN} --- Arcsine function
1183 @cindex trigonometric function, sine, inverse
1184 @cindex sine, inverse
1187 @item @emph{Description}:
1188 @code{ASIN(X)} computes the arcsine of its @var{X} (inverse of @code{SIN(X)}).
1190 @item @emph{Standard}:
1191 Fortran 77 and later, for a complex argument Fortran 2008 or later
1196 @item @emph{Syntax}:
1197 @code{RESULT = ASIN(X)}
1199 @item @emph{Arguments}:
1200 @multitable @columnfractions .15 .70
1201 @item @var{X} @tab The type shall be either @code{REAL} and a magnitude that is
1202 less than or equal to one - or be @code{COMPLEX}.
1205 @item @emph{Return value}:
1206 The return value is of the same type and kind as @var{X}.
1207 The real part of the result is in radians and lies in the range
1208 @math{-\pi/2 \leq \Re \asin(x) \leq \pi/2}.
1210 @item @emph{Example}:
1213 real(8) :: x = 0.866_8
1215 end program test_asin
1218 @item @emph{Specific names}:
1219 @multitable @columnfractions .20 .20 .20 .25
1220 @item Name @tab Argument @tab Return type @tab Standard
1221 @item @code{ASIN(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab Fortran 77 and later
1222 @item @code{DASIN(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab Fortran 77 and later
1225 @item @emph{See also}:
1226 Inverse function: @ref{SIN}
1233 @section @code{ASINH} --- Inverse hyperbolic sine function
1236 @cindex area hyperbolic sine
1237 @cindex inverse hyperbolic sine
1238 @cindex hyperbolic function, sine, inverse
1239 @cindex sine, hyperbolic, inverse
1242 @item @emph{Description}:
1243 @code{ASINH(X)} computes the inverse hyperbolic sine of @var{X}.
1245 @item @emph{Standard}:
1246 Fortran 2008 and later
1251 @item @emph{Syntax}:
1252 @code{RESULT = ASINH(X)}
1254 @item @emph{Arguments}:
1255 @multitable @columnfractions .15 .70
1256 @item @var{X} @tab The type shall be @code{REAL} or @code{COMPLEX}.
1259 @item @emph{Return value}:
1260 The return value is of the same type and kind as @var{X}. If @var{X} is
1261 complex, the imaginary part of the result is in radians and lies between
1262 @math{-\pi/2 \leq \Im \asinh(x) \leq \pi/2}.
1264 @item @emph{Example}:
1267 REAL(8), DIMENSION(3) :: x = (/ -1.0, 0.0, 1.0 /)
1268 WRITE (*,*) ASINH(x)
1272 @item @emph{Specific names}:
1273 @multitable @columnfractions .20 .20 .20 .25
1274 @item Name @tab Argument @tab Return type @tab Standard
1275 @item @code{DASINH(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU extension.
1278 @item @emph{See also}:
1279 Inverse function: @ref{SINH}
1285 @section @code{ASSOCIATED} --- Status of a pointer or pointer/target pair
1287 @cindex pointer, status
1288 @cindex association status
1291 @item @emph{Description}:
1292 @code{ASSOCIATED(POINTER [, TARGET])} determines the status of the pointer
1293 @var{POINTER} or if @var{POINTER} is associated with the target @var{TARGET}.
1295 @item @emph{Standard}:
1296 Fortran 95 and later
1301 @item @emph{Syntax}:
1302 @code{RESULT = ASSOCIATED(POINTER [, TARGET])}
1304 @item @emph{Arguments}:
1305 @multitable @columnfractions .15 .70
1306 @item @var{POINTER} @tab @var{POINTER} shall have the @code{POINTER} attribute
1307 and it can be of any type.
1308 @item @var{TARGET} @tab (Optional) @var{TARGET} shall be a pointer or
1309 a target. It must have the same type, kind type parameter, and
1310 array rank as @var{POINTER}.
1312 The association status of neither @var{POINTER} nor @var{TARGET} shall be
1315 @item @emph{Return value}:
1316 @code{ASSOCIATED(POINTER)} returns a scalar value of type @code{LOGICAL(4)}.
1317 There are several cases:
1319 @item (A) When the optional @var{TARGET} is not present then
1320 @code{ASSOCIATED(POINTER)} is true if @var{POINTER} is associated with a target; otherwise, it returns false.
1321 @item (B) If @var{TARGET} is present and a scalar target, the result is true if
1322 @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
1323 disassociated, the result is false.
1324 @item (C) If @var{TARGET} is present and an array target, the result is true if
1325 @var{TARGET} and @var{POINTER} have the same shape, are not zero-sized arrays,
1326 are arrays whose elements are not zero-sized storage sequences, and
1327 @var{TARGET} and @var{POINTER} occupy the same storage units in array element
1329 As in case(B), the result is false, if @var{POINTER} is disassociated.
1330 @item (D) If @var{TARGET} is present and an scalar pointer, the result is true
1331 if @var{TARGET} is associated with @var{POINTER}, the target associated with
1332 @var{TARGET} are not zero-sized storage sequences and occupy the same storage
1334 The result is false, if either @var{TARGET} or @var{POINTER} is disassociated.
1335 @item (E) If @var{TARGET} is present and an array pointer, the result is true if
1336 target associated with @var{POINTER} and the target associated with @var{TARGET}
1337 have the same shape, are not zero-sized arrays, are arrays whose elements are
1338 not zero-sized storage sequences, and @var{TARGET} and @var{POINTER} occupy
1339 the same storage units in array element order.
1340 The result is false, if either @var{TARGET} or @var{POINTER} is disassociated.
1343 @item @emph{Example}:
1345 program test_associated
1347 real, target :: tgt(2) = (/1., 2./)
1348 real, pointer :: ptr(:)
1350 if (associated(ptr) .eqv. .false.) call abort
1351 if (associated(ptr,tgt) .eqv. .false.) call abort
1352 end program test_associated
1355 @item @emph{See also}:
1362 @section @code{ATAN} --- Arctangent function
1365 @cindex trigonometric function, tangent, inverse
1366 @cindex tangent, inverse
1369 @item @emph{Description}:
1370 @code{ATAN(X)} computes the arctangent of @var{X}.
1372 @item @emph{Standard}:
1373 Fortran 77 and later, for a complex argument and for two arguments
1374 Fortran 2008 or later
1379 @item @emph{Syntax}:
1380 @code{RESULT = ATAN(X)}
1381 @code{RESULT = ATAN(Y, X)}
1383 @item @emph{Arguments}:
1384 @multitable @columnfractions .15 .70
1385 @item @var{X} @tab The type shall be @code{REAL} or @code{COMPLEX};
1386 if @var{Y} is present, @var{X} shall be REAL.
1387 @item @var{Y} shall be of the same type and kind as @var{X}.
1390 @item @emph{Return value}:
1391 The return value is of the same type and kind as @var{X}.
1392 If @var{Y} is present, the result is identical to @code{ATAN2(Y,X)}.
1393 Otherwise, it the arcus tangent of @var{X}, where the real part of
1394 the result is in radians and lies in the range
1395 @math{-\pi/2 \leq \Re \atan(x) \leq \pi/2}.
1397 @item @emph{Example}:
1400 real(8) :: x = 2.866_8
1402 end program test_atan
1405 @item @emph{Specific names}:
1406 @multitable @columnfractions .20 .20 .20 .25
1407 @item Name @tab Argument @tab Return type @tab Standard
1408 @item @code{ATAN(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab Fortran 77 and later
1409 @item @code{DATAN(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab Fortran 77 and later
1412 @item @emph{See also}:
1413 Inverse function: @ref{TAN}
1420 @section @code{ATAN2} --- Arctangent function
1423 @cindex trigonometric function, tangent, inverse
1424 @cindex tangent, inverse
1427 @item @emph{Description}:
1428 @code{ATAN2(Y, X)} computes the principal value of the argument
1429 function of the complex number @math{X + i Y}. This function can
1430 be used to transform from carthesian into polar coordinates and
1431 allows to determine the angle in the correct quadrant.
1433 @item @emph{Standard}:
1434 Fortran 77 and later
1439 @item @emph{Syntax}:
1440 @code{RESULT = ATAN2(Y, X)}
1442 @item @emph{Arguments}:
1443 @multitable @columnfractions .15 .70
1444 @item @var{Y} @tab The type shall be @code{REAL}.
1445 @item @var{X} @tab The type and kind type parameter shall be the same as @var{Y}.
1446 If @var{Y} is zero, then @var{X} must be nonzero.
1449 @item @emph{Return value}:
1450 The return value has the same type and kind type parameter as @var{Y}.
1451 It is the principal value of the complex number @math{X + i Y}. If
1452 @var{X} is nonzero, then it lies in the range @math{-\pi \le \atan (x) \leq \pi}.
1453 The sign is positive if @var{Y} is positive. If @var{Y} is zero, then
1454 the return value is zero if @var{X} is positive and @math{\pi} if @var{X}
1455 is negative. Finally, if @var{X} is zero, then the magnitude of the result
1458 @item @emph{Example}:
1461 real(4) :: x = 1.e0_4, y = 0.5e0_4
1463 end program test_atan2
1466 @item @emph{Specific names}:
1467 @multitable @columnfractions .20 .20 .20 .25
1468 @item Name @tab Argument @tab Return type @tab Standard
1469 @item @code{ATAN2(X, Y)} @tab @code{REAL(4) X, Y} @tab @code{REAL(4)} @tab Fortran 77 and later
1470 @item @code{DATAN2(X, Y)} @tab @code{REAL(8) X, Y} @tab @code{REAL(8)} @tab Fortran 77 and later
1477 @section @code{ATANH} --- Inverse hyperbolic tangent function
1480 @cindex area hyperbolic tangent
1481 @cindex inverse hyperbolic tangent
1482 @cindex hyperbolic function, tangent, inverse
1483 @cindex tangent, hyperbolic, inverse
1486 @item @emph{Description}:
1487 @code{ATANH(X)} computes the inverse hyperbolic tangent of @var{X}.
1489 @item @emph{Standard}:
1490 Fortran 2008 and later
1495 @item @emph{Syntax}:
1496 @code{RESULT = ATANH(X)}
1498 @item @emph{Arguments}:
1499 @multitable @columnfractions .15 .70
1500 @item @var{X} @tab The type shall be @code{REAL} or @code{COMPLEX}.
1503 @item @emph{Return value}:
1504 The return value has same type and kind as @var{X}. If @var{X} is
1505 complex, the imaginary part of the result is in radians and lies between
1506 @math{-\pi/2 \leq \Im \atanh(x) \leq \pi/2}.
1508 @item @emph{Example}:
1511 REAL, DIMENSION(3) :: x = (/ -1.0, 0.0, 1.0 /)
1512 WRITE (*,*) ATANH(x)
1516 @item @emph{Specific names}:
1517 @multitable @columnfractions .20 .20 .20 .25
1518 @item Name @tab Argument @tab Return type @tab Standard
1519 @item @code{DATANH(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU extension
1522 @item @emph{See also}:
1523 Inverse function: @ref{TANH}
1529 @section @code{BESSEL_J0} --- Bessel function of the first kind of order 0
1533 @cindex Bessel function, first kind
1536 @item @emph{Description}:
1537 @code{BESSEL_J0(X)} computes the Bessel function of the first kind of
1538 order 0 of @var{X}. This function is available under the name
1539 @code{BESJ0} as a GNU extension.
1541 @item @emph{Standard}:
1542 Fortran 2008 and later
1547 @item @emph{Syntax}:
1548 @code{RESULT = BESSEL_J0(X)}
1550 @item @emph{Arguments}:
1551 @multitable @columnfractions .15 .70
1552 @item @var{X} @tab The type shall be @code{REAL}, and it shall be scalar.
1555 @item @emph{Return value}:
1556 The return value is of type @code{REAL} and lies in the
1557 range @math{ - 0.4027... \leq Bessel (0,x) \leq 1}. It has the same
1560 @item @emph{Example}:
1563 real(8) :: x = 0.0_8
1565 end program test_besj0
1568 @item @emph{Specific names}:
1569 @multitable @columnfractions .20 .20 .20 .25
1570 @item Name @tab Argument @tab Return type @tab Standard
1571 @item @code{DBESJ0(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU extension
1578 @section @code{BESSEL_J1} --- Bessel function of the first kind of order 1
1582 @cindex Bessel function, first kind
1585 @item @emph{Description}:
1586 @code{BESSEL_J1(X)} computes the Bessel function of the first kind of
1587 order 1 of @var{X}. This function is available under the name
1588 @code{BESJ1} as a GNU extension.
1590 @item @emph{Standard}:
1596 @item @emph{Syntax}:
1597 @code{RESULT = BESSEL_J1(X)}
1599 @item @emph{Arguments}:
1600 @multitable @columnfractions .15 .70
1601 @item @var{X} @tab The type shall be @code{REAL}, and it shall be scalar.
1604 @item @emph{Return value}:
1605 The return value is of type @code{REAL} and it lies in the
1606 range @math{ - 0.5818... \leq Bessel (0,x) \leq 0.5818 }. It has the same
1609 @item @emph{Example}:
1612 real(8) :: x = 1.0_8
1614 end program test_besj1
1617 @item @emph{Specific names}:
1618 @multitable @columnfractions .20 .20 .20 .25
1619 @item Name @tab Argument @tab Return type @tab Standard
1620 @item @code{DBESJ1(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU extension
1627 @section @code{BESSEL_JN} --- Bessel function of the first kind
1631 @cindex Bessel function, first kind
1634 @item @emph{Description}:
1635 @code{BESSEL_JN(N, X)} computes the Bessel function of the first kind of
1636 order @var{N} of @var{X}. This function is available under the name
1637 @code{BESJN} as a GNU extension. If @var{N} and @var{X} are arrays,
1638 their ranks and shapes shall conform.
1640 @code{BESSEL_JN(N1, N2, X)} returns an array with the Bessel functions
1641 of the first kind of the orders @var{N1} to @var{N2}.
1643 @item @emph{Standard}:
1644 Fortran 2008 and later, negative @var{N} is allowed as GNU extension
1647 Elemental function, except for the tranformational function
1648 @code{BESSEL_JN(N1, N2, X)}
1650 @item @emph{Syntax}:
1651 @code{RESULT = BESSEL_JN(N, X)}
1652 @code{RESULT = BESSEL_JN(N1, N2, X)}
1654 @item @emph{Arguments}:
1655 @multitable @columnfractions .15 .70
1656 @item @var{N} @tab Shall be a scalar or an array of type @code{INTEGER}.
1657 @item @var{N1} @tab Shall be a non-negative scalar of type @code{INTEGER}.
1658 @item @var{N2} @tab Shall be a non-negative scalar of type @code{INTEGER}.
1659 @item @var{X} @tab Shall be a scalar or an array of type @code{REAL};
1660 for @code{BESSEL_JN(N1, N2, X)} it shall be scalar.
1663 @item @emph{Return value}:
1664 The return value is a scalar of type @code{REAL}. It has the same
1668 The transformational function uses a recurrence algorithm which might,
1669 for some values of @var{X}, lead to different results than calls to
1670 the elemental function.
1672 @item @emph{Example}:
1675 real(8) :: x = 1.0_8
1677 end program test_besjn
1680 @item @emph{Specific names}:
1681 @multitable @columnfractions .20 .20 .20 .25
1682 @item Name @tab Argument @tab Return type @tab Standard
1683 @item @code{DBESJN(N, X)} @tab @code{INTEGER N} @tab @code{REAL(8)} @tab GNU extension
1684 @item @tab @code{REAL(8) X} @tab @tab
1691 @section @code{BESSEL_Y0} --- Bessel function of the second kind of order 0
1695 @cindex Bessel function, second kind
1698 @item @emph{Description}:
1699 @code{BESSEL_Y0(X)} computes the Bessel function of the second kind of
1700 order 0 of @var{X}. This function is available under the name
1701 @code{BESY0} as a GNU extension.
1703 @item @emph{Standard}:
1704 Fortran 2008 and later
1709 @item @emph{Syntax}:
1710 @code{RESULT = BESSEL_Y0(X)}
1712 @item @emph{Arguments}:
1713 @multitable @columnfractions .15 .70
1714 @item @var{X} @tab The type shall be @code{REAL}, and it shall be scalar.
1717 @item @emph{Return value}:
1718 The return value is a scalar of type @code{REAL}. It has the same
1721 @item @emph{Example}:
1724 real(8) :: x = 0.0_8
1726 end program test_besy0
1729 @item @emph{Specific names}:
1730 @multitable @columnfractions .20 .20 .20 .25
1731 @item Name @tab Argument @tab Return type @tab Standard
1732 @item @code{DBESY0(X)}@tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU extension
1739 @section @code{BESSEL_Y1} --- Bessel function of the second kind of order 1
1743 @cindex Bessel function, second kind
1746 @item @emph{Description}:
1747 @code{BESSEL_Y1(X)} computes the Bessel function of the second kind of
1748 order 1 of @var{X}. This function is available under the name
1749 @code{BESY1} as a GNU extension.
1751 @item @emph{Standard}:
1752 Fortran 2008 and later
1757 @item @emph{Syntax}:
1758 @code{RESULT = BESSEL_Y1(X)}
1760 @item @emph{Arguments}:
1761 @multitable @columnfractions .15 .70
1762 @item @var{X} @tab The type shall be @code{REAL}, and it shall be scalar.
1765 @item @emph{Return value}:
1766 The return value is a scalar of type @code{REAL}. It has the same
1769 @item @emph{Example}:
1772 real(8) :: x = 1.0_8
1774 end program test_besy1
1777 @item @emph{Specific names}:
1778 @multitable @columnfractions .20 .20 .20 .25
1779 @item Name @tab Argument @tab Return type @tab Standard
1780 @item @code{DBESY1(X)}@tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU extension
1787 @section @code{BESSEL_YN} --- Bessel function of the second kind
1791 @cindex Bessel function, second kind
1794 @item @emph{Description}:
1795 @code{BESSEL_YN(N, X)} computes the Bessel function of the second kind of
1796 order @var{N} of @var{X}. This function is available under the name
1797 @code{BESYN} as a GNU extension. If @var{N} and @var{X} are arrays,
1798 their ranks and shapes shall conform.
1800 @code{BESSEL_YN(N1, N2, X)} returns an array with the Bessel functions
1801 of the first kind of the orders @var{N1} to @var{N2}.
1803 @item @emph{Standard}:
1804 Fortran 2008 and later, negative @var{N} is allowed as GNU extension
1807 Elemental function, except for the tranformational function
1808 @code{BESSEL_YN(N1, N2, X)}
1810 @item @emph{Syntax}:
1811 @code{RESULT = BESSEL_YN(N, X)}
1812 @code{RESULT = BESSEL_YN(N1, N2, X)}
1814 @item @emph{Arguments}:
1815 @multitable @columnfractions .15 .70
1816 @item @var{N} @tab Shall be a scalar or an array of type @code{INTEGER} .
1817 @item @var{N1} @tab Shall be a non-negative scalar of type @code{INTEGER}.
1818 @item @var{N2} @tab Shall be a non-negative scalar of type @code{INTEGER}.
1819 @item @var{X} @tab Shall be a scalar or an array of type @code{REAL};
1820 for @code{BESSEL_YN(N1, N2, X)} it shall be scalar.
1823 @item @emph{Return value}:
1824 The return value is a scalar of type @code{REAL}. It has the same
1828 The transformational function uses a recurrence algorithm which might,
1829 for some values of @var{X}, lead to different results than calls to
1830 the elemental function.
1832 @item @emph{Example}:
1835 real(8) :: x = 1.0_8
1837 end program test_besyn
1840 @item @emph{Specific names}:
1841 @multitable @columnfractions .20 .20 .20 .25
1842 @item Name @tab Argument @tab Return type @tab Standard
1843 @item @code{DBESYN(N,X)} @tab @code{INTEGER N} @tab @code{REAL(8)} @tab GNU extension
1844 @item @tab @code{REAL(8) X} @tab @tab
1851 @section @code{BIT_SIZE} --- Bit size inquiry function
1853 @cindex bits, number of
1854 @cindex size of a variable, in bits
1857 @item @emph{Description}:
1858 @code{BIT_SIZE(I)} returns the number of bits (integer precision plus sign bit)
1859 represented by the type of @var{I}. The result of @code{BIT_SIZE(I)} is
1860 independent of the actual value of @var{I}.
1862 @item @emph{Standard}:
1863 Fortran 95 and later
1868 @item @emph{Syntax}:
1869 @code{RESULT = BIT_SIZE(I)}
1871 @item @emph{Arguments}:
1872 @multitable @columnfractions .15 .70
1873 @item @var{I} @tab The type shall be @code{INTEGER}.
1876 @item @emph{Return value}:
1877 The return value is of type @code{INTEGER}
1879 @item @emph{Example}:
1881 program test_bit_size
1886 end program test_bit_size
1893 @section @code{BTEST} --- Bit test function
1895 @cindex bits, testing
1898 @item @emph{Description}:
1899 @code{BTEST(I,POS)} returns logical @code{.TRUE.} if the bit at @var{POS}
1900 in @var{I} is set. The counting of the bits starts at 0.
1902 @item @emph{Standard}:
1903 Fortran 95 and later
1908 @item @emph{Syntax}:
1909 @code{RESULT = BTEST(I, POS)}
1911 @item @emph{Arguments}:
1912 @multitable @columnfractions .15 .70
1913 @item @var{I} @tab The type shall be @code{INTEGER}.
1914 @item @var{POS} @tab The type shall be @code{INTEGER}.
1917 @item @emph{Return value}:
1918 The return value is of type @code{LOGICAL}
1920 @item @emph{Example}:
1923 integer :: i = 32768 + 1024 + 64
1927 bool = btest(i, pos)
1930 end program test_btest
1936 @section @code{C_ASSOCIATED} --- Status of a C pointer
1937 @fnindex C_ASSOCIATED
1938 @cindex association status, C pointer
1939 @cindex pointer, C association status
1942 @item @emph{Description}:
1943 @code{C_ASSOCIATED(c_prt_1[, c_ptr_2])} determines the status of the C pointer
1944 @var{c_ptr_1} or if @var{c_ptr_1} is associated with the target @var{c_ptr_2}.
1946 @item @emph{Standard}:
1947 Fortran 2003 and later
1952 @item @emph{Syntax}:
1953 @code{RESULT = C_ASSOCIATED(c_prt_1[, c_ptr_2])}
1955 @item @emph{Arguments}:
1956 @multitable @columnfractions .15 .70
1957 @item @var{c_ptr_1} @tab Scalar of the type @code{C_PTR} or @code{C_FUNPTR}.
1958 @item @var{c_ptr_2} @tab (Optional) Scalar of the same type as @var{c_ptr_1}.
1961 @item @emph{Return value}:
1962 The return value is of type @code{LOGICAL}; it is @code{.false.} if either
1963 @var{c_ptr_1} is a C NULL pointer or if @var{c_ptr1} and @var{c_ptr_2}
1964 point to different addresses.
1966 @item @emph{Example}:
1968 subroutine association_test(a,b)
1969 use iso_c_binding, only: c_associated, c_loc, c_ptr
1973 if(c_associated(b, c_loc(a))) &
1974 stop 'b and a do not point to same target'
1975 end subroutine association_test
1978 @item @emph{See also}:
1979 @ref{C_LOC}, @ref{C_FUNLOC}
1984 @section @code{C_FUNLOC} --- Obtain the C address of a procedure
1986 @cindex pointer, C address of procedures
1989 @item @emph{Description}:
1990 @code{C_FUNLOC(x)} determines the C address of the argument.
1992 @item @emph{Standard}:
1993 Fortran 2003 and later
1998 @item @emph{Syntax}:
1999 @code{RESULT = C_FUNLOC(x)}
2001 @item @emph{Arguments}:
2002 @multitable @columnfractions .15 .70
2003 @item @var{x} @tab Interoperable function or pointer to such function.
2006 @item @emph{Return value}:
2007 The return value is of type @code{C_FUNPTR} and contains the C address
2010 @item @emph{Example}:
2016 subroutine sub(a) bind(c)
2026 subroutine my_routine(p) bind(c,name='myC_func')
2028 type(c_funptr), intent(in) :: p
2031 call my_routine(c_funloc(sub))
2035 @item @emph{See also}:
2036 @ref{C_ASSOCIATED}, @ref{C_LOC}, @ref{C_F_POINTER}, @ref{C_F_PROCPOINTER}
2040 @node C_F_PROCPOINTER
2041 @section @code{C_F_PROCPOINTER} --- Convert C into Fortran procedure pointer
2042 @fnindex C_F_PROCPOINTER
2043 @cindex pointer, C address of pointers
2046 @item @emph{Description}:
2047 @code{C_F_PROCPOINTER(CPTR, FPTR)} Assign the target of the C function pointer
2048 @var{CPTR} to the Fortran procedure pointer @var{FPTR}.
2050 @item @emph{Standard}:
2051 Fortran 2003 and later
2056 @item @emph{Syntax}:
2057 @code{CALL C_F_PROCPOINTER(cptr, fptr)}
2059 @item @emph{Arguments}:
2060 @multitable @columnfractions .15 .70
2061 @item @var{CPTR} @tab scalar of the type @code{C_FUNPTR}. It is
2063 @item @var{FPTR} @tab procedure pointer interoperable with @var{cptr}. It is
2067 @item @emph{Example}:
2075 real(c_float), intent(in) :: a
2076 real(c_float) :: func
2080 function getIterFunc() bind(c,name="getIterFunc")
2082 type(c_funptr) :: getIterFunc
2085 type(c_funptr) :: cfunptr
2086 procedure(func), pointer :: myFunc
2087 cfunptr = getIterFunc()
2088 call c_f_procpointer(cfunptr, myFunc)
2092 @item @emph{See also}:
2093 @ref{C_LOC}, @ref{C_F_POINTER}
2098 @section @code{C_F_POINTER} --- Convert C into Fortran pointer
2099 @fnindex C_F_POINTER
2100 @cindex pointer, convert C to Fortran
2103 @item @emph{Description}:
2104 @code{C_F_POINTER(CPTR, FPTR[, SHAPE])} Assign the target the C pointer
2105 @var{CPTR} to the Fortran pointer @var{FPTR} and specify its
2108 @item @emph{Standard}:
2109 Fortran 2003 and later
2114 @item @emph{Syntax}:
2115 @code{CALL C_F_POINTER(CPTR, FPTR[, SHAPE])}
2117 @item @emph{Arguments}:
2118 @multitable @columnfractions .15 .70
2119 @item @var{CPTR} @tab scalar of the type @code{C_PTR}. It is
2121 @item @var{FPTR} @tab pointer interoperable with @var{cptr}. It is
2123 @item @var{SHAPE} @tab (Optional) Rank-one array of type @code{INTEGER}
2124 with @code{INTENT(IN)}. It shall be present
2125 if and only if @var{fptr} is an array. The size
2126 must be equal to the rank of @var{fptr}.
2129 @item @emph{Example}:
2135 subroutine my_routine(p) bind(c,name='myC_func')
2137 type(c_ptr), intent(out) :: p
2141 real,pointer :: a(:)
2142 call my_routine(cptr)
2143 call c_f_pointer(cptr, a, [12])
2147 @item @emph{See also}:
2148 @ref{C_LOC}, @ref{C_F_PROCPOINTER}
2153 @section @code{C_LOC} --- Obtain the C address of an object
2155 @cindex procedure pointer, convert C to Fortran
2158 @item @emph{Description}:
2159 @code{C_LOC(X)} determines the C address of the argument.
2161 @item @emph{Standard}:
2162 Fortran 2003 and later
2167 @item @emph{Syntax}:
2168 @code{RESULT = C_LOC(X)}
2170 @item @emph{Arguments}:
2171 @multitable @columnfractions .10 .75
2172 @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.
2176 @item @emph{Return value}:
2177 The return value is of type @code{C_PTR} and contains the C address
2180 @item @emph{Example}:
2182 subroutine association_test(a,b)
2183 use iso_c_binding, only: c_associated, c_loc, c_ptr
2187 if(c_associated(b, c_loc(a))) &
2188 stop 'b and a do not point to same target'
2189 end subroutine association_test
2192 @item @emph{See also}:
2193 @ref{C_ASSOCIATED}, @ref{C_FUNLOC}, @ref{C_F_POINTER}, @ref{C_F_PROCPOINTER}
2198 @section @code{C_SIZEOF} --- Size in bytes of an expression
2200 @cindex expression size
2201 @cindex size of an expression
2204 @item @emph{Description}:
2205 @code{C_SIZEOF(X)} calculates the number of bytes of storage the
2206 expression @code{X} occupies.
2208 @item @emph{Standard}:
2214 @item @emph{Syntax}:
2215 @code{N = C_SIZEOF(X)}
2217 @item @emph{Arguments}:
2218 @multitable @columnfractions .15 .70
2219 @item @var{X} @tab The argument shall be an interoperable data entity.
2222 @item @emph{Return value}:
2223 The return value is of type integer and of the system-dependent kind
2224 @var{C_SIZE_T} (from the @var{ISO_C_BINDING} module). Its value is the
2225 number of bytes occupied by the argument. If the argument has the
2226 @code{POINTER} attribute, the number of bytes of the storage area pointed
2227 to is returned. If the argument is of a derived type with @code{POINTER}
2228 or @code{ALLOCATABLE} components, the return value doesn't account for
2229 the sizes of the data pointed to by these components.
2231 @item @emph{Example}:
2235 real(c_float) :: r, s(5)
2236 print *, (c_sizeof(s)/c_sizeof(r) == 5)
2239 The example will print @code{.TRUE.} unless you are using a platform
2240 where default @code{REAL} variables are unusually padded.
2242 @item @emph{See also}:
2243 @ref{SIZEOF}, @ref{STORAGE_SIZE}
2248 @section @code{CEILING} --- Integer ceiling function
2251 @cindex rounding, ceiling
2254 @item @emph{Description}:
2255 @code{CEILING(A)} returns the least integer greater than or equal to @var{A}.
2257 @item @emph{Standard}:
2258 Fortran 95 and later
2263 @item @emph{Syntax}:
2264 @code{RESULT = CEILING(A [, KIND])}
2266 @item @emph{Arguments}:
2267 @multitable @columnfractions .15 .70
2268 @item @var{A} @tab The type shall be @code{REAL}.
2269 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
2270 expression indicating the kind parameter of the result.
2273 @item @emph{Return value}:
2274 The return value is of type @code{INTEGER(KIND)} if @var{KIND} is present
2275 and a default-kind @code{INTEGER} otherwise.
2277 @item @emph{Example}:
2279 program test_ceiling
2282 print *, ceiling(x) ! returns 64
2283 print *, ceiling(y) ! returns -63
2284 end program test_ceiling
2287 @item @emph{See also}:
2288 @ref{FLOOR}, @ref{NINT}
2295 @section @code{CHAR} --- Character conversion function
2297 @cindex conversion, to character
2300 @item @emph{Description}:
2301 @code{CHAR(I [, KIND])} returns the character represented by the integer @var{I}.
2303 @item @emph{Standard}:
2304 Fortran 77 and later
2309 @item @emph{Syntax}:
2310 @code{RESULT = CHAR(I [, KIND])}
2312 @item @emph{Arguments}:
2313 @multitable @columnfractions .15 .70
2314 @item @var{I} @tab The type shall be @code{INTEGER}.
2315 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
2316 expression indicating the kind parameter of the result.
2319 @item @emph{Return value}:
2320 The return value is of type @code{CHARACTER(1)}
2322 @item @emph{Example}:
2328 print *, i, c ! returns 'J'
2329 end program test_char
2332 @item @emph{Specific names}:
2333 @multitable @columnfractions .20 .20 .20 .25
2334 @item Name @tab Argument @tab Return type @tab Standard
2335 @item @code{CHAR(I)} @tab @code{INTEGER I} @tab @code{CHARACTER(LEN=1)} @tab F77 and later
2339 See @ref{ICHAR} for a discussion of converting between numerical values
2340 and formatted string representations.
2342 @item @emph{See also}:
2343 @ref{ACHAR}, @ref{IACHAR}, @ref{ICHAR}
2350 @section @code{CHDIR} --- Change working directory
2352 @cindex system, working directory
2355 @item @emph{Description}:
2356 Change current working directory to a specified path.
2358 This intrinsic is provided in both subroutine and function forms; however,
2359 only one form can be used in any given program unit.
2361 @item @emph{Standard}:
2365 Subroutine, function
2367 @item @emph{Syntax}:
2368 @multitable @columnfractions .80
2369 @item @code{CALL CHDIR(NAME [, STATUS])}
2370 @item @code{STATUS = CHDIR(NAME)}
2373 @item @emph{Arguments}:
2374 @multitable @columnfractions .15 .70
2375 @item @var{NAME} @tab The type shall be @code{CHARACTER} of default
2376 kind and shall specify a valid path within the file system.
2377 @item @var{STATUS} @tab (Optional) @code{INTEGER} status flag of the default
2378 kind. Returns 0 on success, and a system specific and nonzero error code
2382 @item @emph{Example}:
2385 CHARACTER(len=255) :: path
2387 WRITE(*,*) TRIM(path)
2390 WRITE(*,*) TRIM(path)
2394 @item @emph{See also}:
2401 @section @code{CHMOD} --- Change access permissions of files
2403 @cindex file system, change access mode
2406 @item @emph{Description}:
2407 @code{CHMOD} changes the permissions of a file. This function invokes
2408 @code{/bin/chmod} and might therefore not work on all platforms.
2410 This intrinsic is provided in both subroutine and function forms; however,
2411 only one form can be used in any given program unit.
2413 @item @emph{Standard}:
2417 Subroutine, function
2419 @item @emph{Syntax}:
2420 @multitable @columnfractions .80
2421 @item @code{CALL CHMOD(NAME, MODE[, STATUS])}
2422 @item @code{STATUS = CHMOD(NAME, MODE)}
2425 @item @emph{Arguments}:
2426 @multitable @columnfractions .15 .70
2428 @item @var{NAME} @tab Scalar @code{CHARACTER} of default kind with the
2429 file name. Trailing blanks are ignored unless the character
2430 @code{achar(0)} is present, then all characters up to and excluding
2431 @code{achar(0)} are used as the file name.
2433 @item @var{MODE} @tab Scalar @code{CHARACTER} of default kind giving the
2434 file permission. @var{MODE} uses the same syntax as the @var{MODE}
2435 argument of @code{/bin/chmod}.
2437 @item @var{STATUS} @tab (optional) scalar @code{INTEGER}, which is
2438 @code{0} on success and nonzero otherwise.
2441 @item @emph{Return value}:
2442 In either syntax, @var{STATUS} is set to @code{0} on success and nonzero
2445 @item @emph{Example}:
2446 @code{CHMOD} as subroutine
2451 call chmod('test.dat','u+x',status)
2452 print *, 'Status: ', status
2453 end program chmod_test
2455 @code{CHMOD} as function:
2460 status = chmod('test.dat','u+x')
2461 print *, 'Status: ', status
2462 end program chmod_test
2470 @section @code{CMPLX} --- Complex conversion function
2472 @cindex complex numbers, conversion to
2473 @cindex conversion, to complex
2476 @item @emph{Description}:
2477 @code{CMPLX(X [, Y [, KIND]])} returns a complex number where @var{X} is converted to
2478 the real component. If @var{Y} is present it is converted to the imaginary
2479 component. If @var{Y} is not present then the imaginary component is set to
2480 0.0. If @var{X} is complex then @var{Y} must not be present.
2482 @item @emph{Standard}:
2483 Fortran 77 and later
2488 @item @emph{Syntax}:
2489 @code{RESULT = CMPLX(X [, Y [, KIND]])}
2491 @item @emph{Arguments}:
2492 @multitable @columnfractions .15 .70
2493 @item @var{X} @tab The type may be @code{INTEGER}, @code{REAL},
2495 @item @var{Y} @tab (Optional; only allowed if @var{X} is not
2496 @code{COMPLEX}.) May be @code{INTEGER} or @code{REAL}.
2497 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
2498 expression indicating the kind parameter of the result.
2501 @item @emph{Return value}:
2502 The return value is of @code{COMPLEX} type, with a kind equal to
2503 @var{KIND} if it is specified. If @var{KIND} is not specified, the
2504 result is of the default @code{COMPLEX} kind, regardless of the kinds of
2505 @var{X} and @var{Y}.
2507 @item @emph{Example}:
2514 print *, z, cmplx(x)
2515 end program test_cmplx
2518 @item @emph{See also}:
2524 @node COMMAND_ARGUMENT_COUNT
2525 @section @code{COMMAND_ARGUMENT_COUNT} --- Get number of command line arguments
2526 @fnindex COMMAND_ARGUMENT_COUNT
2527 @cindex command-line arguments
2528 @cindex command-line arguments, number of
2529 @cindex arguments, to program
2532 @item @emph{Description}:
2533 @code{COMMAND_ARGUMENT_COUNT()} returns the number of arguments passed on the
2534 command line when the containing program was invoked.
2536 @item @emph{Standard}:
2537 Fortran 2003 and later
2542 @item @emph{Syntax}:
2543 @code{RESULT = COMMAND_ARGUMENT_COUNT()}
2545 @item @emph{Arguments}:
2546 @multitable @columnfractions .15 .70
2550 @item @emph{Return value}:
2551 The return value is an @code{INTEGER} of default kind.
2553 @item @emph{Example}:
2555 program test_command_argument_count
2557 count = command_argument_count()
2559 end program test_command_argument_count
2562 @item @emph{See also}:
2563 @ref{GET_COMMAND}, @ref{GET_COMMAND_ARGUMENT}
2569 @section @code{COMPLEX} --- Complex conversion function
2571 @cindex complex numbers, conversion to
2572 @cindex conversion, to complex
2575 @item @emph{Description}:
2576 @code{COMPLEX(X, Y)} returns a complex number where @var{X} is converted
2577 to the real component and @var{Y} is converted to the imaginary
2580 @item @emph{Standard}:
2586 @item @emph{Syntax}:
2587 @code{RESULT = COMPLEX(X, Y)}
2589 @item @emph{Arguments}:
2590 @multitable @columnfractions .15 .70
2591 @item @var{X} @tab The type may be @code{INTEGER} or @code{REAL}.
2592 @item @var{Y} @tab The type may be @code{INTEGER} or @code{REAL}.
2595 @item @emph{Return value}:
2596 If @var{X} and @var{Y} are both of @code{INTEGER} type, then the return
2597 value is of default @code{COMPLEX} type.
2599 If @var{X} and @var{Y} are of @code{REAL} type, or one is of @code{REAL}
2600 type and one is of @code{INTEGER} type, then the return value is of
2601 @code{COMPLEX} type with a kind equal to that of the @code{REAL}
2602 argument with the highest precision.
2604 @item @emph{Example}:
2606 program test_complex
2609 print *, complex(i, x)
2610 end program test_complex
2613 @item @emph{See also}:
2620 @section @code{CONJG} --- Complex conjugate function
2623 @cindex complex conjugate
2626 @item @emph{Description}:
2627 @code{CONJG(Z)} returns the conjugate of @var{Z}. If @var{Z} is @code{(x, y)}
2628 then the result is @code{(x, -y)}
2630 @item @emph{Standard}:
2631 Fortran 77 and later, has overloads that are GNU extensions
2636 @item @emph{Syntax}:
2639 @item @emph{Arguments}:
2640 @multitable @columnfractions .15 .70
2641 @item @var{Z} @tab The type shall be @code{COMPLEX}.
2644 @item @emph{Return value}:
2645 The return value is of type @code{COMPLEX}.
2647 @item @emph{Example}:
2650 complex :: z = (2.0, 3.0)
2651 complex(8) :: dz = (2.71_8, -3.14_8)
2656 end program test_conjg
2659 @item @emph{Specific names}:
2660 @multitable @columnfractions .20 .20 .20 .25
2661 @item Name @tab Argument @tab Return type @tab Standard
2662 @item @code{CONJG(Z)} @tab @code{COMPLEX Z} @tab @code{COMPLEX} @tab GNU extension
2663 @item @code{DCONJG(Z)} @tab @code{COMPLEX(8) Z} @tab @code{COMPLEX(8)} @tab GNU extension
2670 @section @code{COS} --- Cosine function
2676 @cindex trigonometric function, cosine
2680 @item @emph{Description}:
2681 @code{COS(X)} computes the cosine of @var{X}.
2683 @item @emph{Standard}:
2684 Fortran 77 and later, has overloads that are GNU extensions
2689 @item @emph{Syntax}:
2690 @code{RESULT = COS(X)}
2692 @item @emph{Arguments}:
2693 @multitable @columnfractions .15 .70
2694 @item @var{X} @tab The type shall be @code{REAL} or
2698 @item @emph{Return value}:
2699 The return value is of the same type and kind as @var{X}. The real part
2700 of the result is in radians. If @var{X} is of the type @code{REAL},
2701 the return value lies in the range @math{ -1 \leq \cos (x) \leq 1}.
2703 @item @emph{Example}:
2708 end program test_cos
2711 @item @emph{Specific names}:
2712 @multitable @columnfractions .20 .20 .20 .25
2713 @item Name @tab Argument @tab Return type @tab Standard
2714 @item @code{COS(X)} n@tab @code{REAL(4) X} @tab @code{REAL(4)} @tab Fortran 77 and later
2715 @item @code{DCOS(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab Fortran 77 and later
2716 @item @code{CCOS(X)} @tab @code{COMPLEX(4) X} @tab @code{COMPLEX(4)} @tab Fortran 77 and later
2717 @item @code{ZCOS(X)} @tab @code{COMPLEX(8) X} @tab @code{COMPLEX(8)} @tab GNU extension
2718 @item @code{CDCOS(X)} @tab @code{COMPLEX(8) X} @tab @code{COMPLEX(8)} @tab GNU extension
2721 @item @emph{See also}:
2722 Inverse function: @ref{ACOS}
2729 @section @code{COSH} --- Hyperbolic cosine function
2732 @cindex hyperbolic cosine
2733 @cindex hyperbolic function, cosine
2734 @cindex cosine, hyperbolic
2737 @item @emph{Description}:
2738 @code{COSH(X)} computes the hyperbolic cosine of @var{X}.
2740 @item @emph{Standard}:
2741 Fortran 77 and later, for a complex argument Fortran 2008 or later
2746 @item @emph{Syntax}:
2749 @item @emph{Arguments}:
2750 @multitable @columnfractions .15 .70
2751 @item @var{X} @tab The type shall be @code{REAL} or @code{COMPLEX}.
2754 @item @emph{Return value}:
2755 The return value has same type and kind as @var{X}. If @var{X} is
2756 complex, the imaginary part of the result is in radians. If @var{X}
2757 is @code{REAL}, the return value has a lower bound of one,
2758 @math{\cosh (x) \geq 1}.
2760 @item @emph{Example}:
2763 real(8) :: x = 1.0_8
2765 end program test_cosh
2768 @item @emph{Specific names}:
2769 @multitable @columnfractions .20 .20 .20 .25
2770 @item Name @tab Argument @tab Return type @tab Standard
2771 @item @code{COSH(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab Fortran 77 and later
2772 @item @code{DCOSH(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab Fortran 77 and later
2775 @item @emph{See also}:
2776 Inverse function: @ref{ACOSH}
2783 @section @code{COUNT} --- Count function
2785 @cindex array, conditionally count elements
2786 @cindex array, element counting
2787 @cindex array, number of elements
2790 @item @emph{Description}:
2792 Counts the number of @code{.TRUE.} elements in a logical @var{MASK},
2793 or, if the @var{DIM} argument is supplied, counts the number of
2794 elements along each row of the array in the @var{DIM} direction.
2795 If the array has zero size, or all of the elements of @var{MASK} are
2796 @code{.FALSE.}, then the result is @code{0}.
2798 @item @emph{Standard}:
2799 Fortran 95 and later, with @var{KIND} argument Fortran 2003 and later
2802 Transformational function
2804 @item @emph{Syntax}:
2805 @code{RESULT = COUNT(MASK [, DIM, KIND])}
2807 @item @emph{Arguments}:
2808 @multitable @columnfractions .15 .70
2809 @item @var{MASK} @tab The type shall be @code{LOGICAL}.
2810 @item @var{DIM} @tab (Optional) The type shall be @code{INTEGER}.
2811 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
2812 expression indicating the kind parameter of the result.
2815 @item @emph{Return value}:
2816 The return value is of type @code{INTEGER} and of kind @var{KIND}. If
2817 @var{KIND} is absent, the return value is of default integer kind.
2818 If @var{DIM} is present, the result is an array with a rank one less
2819 than the rank of @var{ARRAY}, and a size corresponding to the shape
2820 of @var{ARRAY} with the @var{DIM} dimension removed.
2822 @item @emph{Example}:
2825 integer, dimension(2,3) :: a, b
2826 logical, dimension(2,3) :: mask
2827 a = reshape( (/ 1, 2, 3, 4, 5, 6 /), (/ 2, 3 /))
2828 b = reshape( (/ 0, 7, 3, 4, 5, 8 /), (/ 2, 3 /))
2829 print '(3i3)', a(1,:)
2830 print '(3i3)', a(2,:)
2832 print '(3i3)', b(1,:)
2833 print '(3i3)', b(2,:)
2836 print '(3l3)', mask(1,:)
2837 print '(3l3)', mask(2,:)
2839 print '(3i3)', count(mask)
2841 print '(3i3)', count(mask, 1)
2843 print '(3i3)', count(mask, 2)
2844 end program test_count
2851 @section @code{CPU_TIME} --- CPU elapsed time in seconds
2853 @cindex time, elapsed
2856 @item @emph{Description}:
2857 Returns a @code{REAL} value representing the elapsed CPU time in
2858 seconds. This is useful for testing segments of code to determine
2861 If a time source is available, time will be reported with microsecond
2862 resolution. If no time source is available, @var{TIME} is set to
2865 Note that @var{TIME} may contain a, system dependent, arbitrary offset
2866 and may not start with @code{0.0}. For @code{CPU_TIME}, the absolute
2867 value is meaningless, only differences between subsequent calls to
2868 this subroutine, as shown in the example below, should be used.
2871 @item @emph{Standard}:
2872 Fortran 95 and later
2877 @item @emph{Syntax}:
2878 @code{CALL CPU_TIME(TIME)}
2880 @item @emph{Arguments}:
2881 @multitable @columnfractions .15 .70
2882 @item @var{TIME} @tab The type shall be @code{REAL} with @code{INTENT(OUT)}.
2885 @item @emph{Return value}:
2888 @item @emph{Example}:
2890 program test_cpu_time
2891 real :: start, finish
2892 call cpu_time(start)
2893 ! put code to test here
2894 call cpu_time(finish)
2895 print '("Time = ",f6.3," seconds.")',finish-start
2896 end program test_cpu_time
2899 @item @emph{See also}:
2900 @ref{SYSTEM_CLOCK}, @ref{DATE_AND_TIME}
2906 @section @code{CSHIFT} --- Circular shift elements of an array
2908 @cindex array, shift circularly
2909 @cindex array, permutation
2910 @cindex array, rotate
2913 @item @emph{Description}:
2914 @code{CSHIFT(ARRAY, SHIFT [, DIM])} performs a circular shift on elements of
2915 @var{ARRAY} along the dimension of @var{DIM}. If @var{DIM} is omitted it is
2916 taken to be @code{1}. @var{DIM} is a scalar of type @code{INTEGER} in the
2917 range of @math{1 \leq DIM \leq n)} where @math{n} is the rank of @var{ARRAY}.
2918 If the rank of @var{ARRAY} is one, then all elements of @var{ARRAY} are shifted
2919 by @var{SHIFT} places. If rank is greater than one, then all complete rank one
2920 sections of @var{ARRAY} along the given dimension are shifted. Elements
2921 shifted out one end of each rank one section are shifted back in the other end.
2923 @item @emph{Standard}:
2924 Fortran 95 and later
2927 Transformational function
2929 @item @emph{Syntax}:
2930 @code{RESULT = CSHIFT(ARRAY, SHIFT [, DIM])}
2932 @item @emph{Arguments}:
2933 @multitable @columnfractions .15 .70
2934 @item @var{ARRAY} @tab Shall be an array of any type.
2935 @item @var{SHIFT} @tab The type shall be @code{INTEGER}.
2936 @item @var{DIM} @tab The type shall be @code{INTEGER}.
2939 @item @emph{Return value}:
2940 Returns an array of same type and rank as the @var{ARRAY} argument.
2942 @item @emph{Example}:
2945 integer, dimension(3,3) :: a
2946 a = reshape( (/ 1, 2, 3, 4, 5, 6, 7, 8, 9 /), (/ 3, 3 /))
2947 print '(3i3)', a(1,:)
2948 print '(3i3)', a(2,:)
2949 print '(3i3)', a(3,:)
2950 a = cshift(a, SHIFT=(/1, 2, -1/), DIM=2)
2952 print '(3i3)', a(1,:)
2953 print '(3i3)', a(2,:)
2954 print '(3i3)', a(3,:)
2955 end program test_cshift
2962 @section @code{CTIME} --- Convert a time into a string
2964 @cindex time, conversion to string
2965 @cindex conversion, to string
2968 @item @emph{Description}:
2969 @code{CTIME} converts a system time value, such as returned by
2970 @code{TIME8()}, to a string of the form @samp{Sat Aug 19 18:13:14 1995}.
2972 This intrinsic is provided in both subroutine and function forms; however,
2973 only one form can be used in any given program unit.
2975 @item @emph{Standard}:
2979 Subroutine, function
2981 @item @emph{Syntax}:
2982 @multitable @columnfractions .80
2983 @item @code{CALL CTIME(TIME, RESULT)}.
2984 @item @code{RESULT = CTIME(TIME)}, (not recommended).
2987 @item @emph{Arguments}:
2988 @multitable @columnfractions .15 .70
2989 @item @var{TIME} @tab The type shall be of type @code{INTEGER(KIND=8)}.
2990 @item @var{RESULT} @tab The type shall be of type @code{CHARACTER} and
2994 @item @emph{Return value}:
2995 The converted date and time as a string.
2997 @item @emph{Example}:
3001 character(len=30) :: date
3004 ! Do something, main part of the program
3007 print *, 'Program was started on ', date
3008 end program test_ctime
3011 @item @emph{See Also}:
3012 @ref{GMTIME}, @ref{LTIME}, @ref{TIME}, @ref{TIME8}
3018 @section @code{DATE_AND_TIME} --- Date and time subroutine
3019 @fnindex DATE_AND_TIME
3020 @cindex date, current
3021 @cindex current date
3022 @cindex time, current
3023 @cindex current time
3026 @item @emph{Description}:
3027 @code{DATE_AND_TIME(DATE, TIME, ZONE, VALUES)} gets the corresponding date and
3028 time information from the real-time system clock. @var{DATE} is
3029 @code{INTENT(OUT)} and has form ccyymmdd. @var{TIME} is @code{INTENT(OUT)} and
3030 has form hhmmss.sss. @var{ZONE} is @code{INTENT(OUT)} and has form (+-)hhmm,
3031 representing the difference with respect to Coordinated Universal Time (UTC).
3032 Unavailable time and date parameters return blanks.
3034 @var{VALUES} is @code{INTENT(OUT)} and provides the following:
3036 @multitable @columnfractions .15 .30 .40
3037 @item @tab @code{VALUE(1)}: @tab The year
3038 @item @tab @code{VALUE(2)}: @tab The month
3039 @item @tab @code{VALUE(3)}: @tab The day of the month
3040 @item @tab @code{VALUE(4)}: @tab Time difference with UTC in minutes
3041 @item @tab @code{VALUE(5)}: @tab The hour of the day
3042 @item @tab @code{VALUE(6)}: @tab The minutes of the hour
3043 @item @tab @code{VALUE(7)}: @tab The seconds of the minute
3044 @item @tab @code{VALUE(8)}: @tab The milliseconds of the second
3047 @item @emph{Standard}:
3048 Fortran 95 and later
3053 @item @emph{Syntax}:
3054 @code{CALL DATE_AND_TIME([DATE, TIME, ZONE, VALUES])}
3056 @item @emph{Arguments}:
3057 @multitable @columnfractions .15 .70
3058 @item @var{DATE} @tab (Optional) The type shall be @code{CHARACTER(LEN=8)}
3059 or larger, and of default kind.
3060 @item @var{TIME} @tab (Optional) The type shall be @code{CHARACTER(LEN=10)}
3061 or larger, and of default kind.
3062 @item @var{ZONE} @tab (Optional) The type shall be @code{CHARACTER(LEN=5)}
3063 or larger, and of default kind.
3064 @item @var{VALUES}@tab (Optional) The type shall be @code{INTEGER(8)}.
3067 @item @emph{Return value}:
3070 @item @emph{Example}:
3072 program test_time_and_date
3073 character(8) :: date
3074 character(10) :: time
3075 character(5) :: zone
3076 integer,dimension(8) :: values
3077 ! using keyword arguments
3078 call date_and_time(date,time,zone,values)
3079 call date_and_time(DATE=date,ZONE=zone)
3080 call date_and_time(TIME=time)
3081 call date_and_time(VALUES=values)
3082 print '(a,2x,a,2x,a)', date, time, zone
3083 print '(8i5))', values
3084 end program test_time_and_date
3087 @item @emph{See also}:
3088 @ref{CPU_TIME}, @ref{SYSTEM_CLOCK}
3094 @section @code{DBLE} --- Double conversion function
3096 @cindex conversion, to real
3099 @item @emph{Description}:
3100 @code{DBLE(A)} Converts @var{A} to double precision real type.
3102 @item @emph{Standard}:
3103 Fortran 77 and later
3108 @item @emph{Syntax}:
3109 @code{RESULT = DBLE(A)}
3111 @item @emph{Arguments}:
3112 @multitable @columnfractions .15 .70
3113 @item @var{A} @tab The type shall be @code{INTEGER}, @code{REAL},
3117 @item @emph{Return value}:
3118 The return value is of type double precision real.
3120 @item @emph{Example}:
3125 complex :: z = (2.3,1.14)
3126 print *, dble(x), dble(i), dble(z)
3127 end program test_dble
3130 @item @emph{See also}:
3137 @section @code{DCMPLX} --- Double complex conversion function
3139 @cindex complex numbers, conversion to
3140 @cindex conversion, to complex
3143 @item @emph{Description}:
3144 @code{DCMPLX(X [,Y])} returns a double complex number where @var{X} is
3145 converted to the real component. If @var{Y} is present it is converted to the
3146 imaginary component. If @var{Y} is not present then the imaginary component is
3147 set to 0.0. If @var{X} is complex then @var{Y} must not be present.
3149 @item @emph{Standard}:
3155 @item @emph{Syntax}:
3156 @code{RESULT = DCMPLX(X [, Y])}
3158 @item @emph{Arguments}:
3159 @multitable @columnfractions .15 .70
3160 @item @var{X} @tab The type may be @code{INTEGER}, @code{REAL},
3162 @item @var{Y} @tab (Optional if @var{X} is not @code{COMPLEX}.) May be
3163 @code{INTEGER} or @code{REAL}.
3166 @item @emph{Return value}:
3167 The return value is of type @code{COMPLEX(8)}
3169 @item @emph{Example}:
3179 print *, dcmplx(x,i)
3180 end program test_dcmplx
3186 @section @code{DIGITS} --- Significant binary digits function
3188 @cindex model representation, significant digits
3191 @item @emph{Description}:
3192 @code{DIGITS(X)} returns the number of significant binary digits of the internal
3193 model representation of @var{X}. For example, on a system using a 32-bit
3194 floating point representation, a default real number would likely return 24.
3196 @item @emph{Standard}:
3197 Fortran 95 and later
3202 @item @emph{Syntax}:
3203 @code{RESULT = DIGITS(X)}
3205 @item @emph{Arguments}:
3206 @multitable @columnfractions .15 .70
3207 @item @var{X} @tab The type may be @code{INTEGER} or @code{REAL}.
3210 @item @emph{Return value}:
3211 The return value is of type @code{INTEGER}.
3213 @item @emph{Example}:
3216 integer :: i = 12345
3222 end program test_digits
3229 @section @code{DIM} --- Positive difference
3233 @cindex positive difference
3236 @item @emph{Description}:
3237 @code{DIM(X,Y)} returns the difference @code{X-Y} if the result is positive;
3238 otherwise returns zero.
3240 @item @emph{Standard}:
3241 Fortran 77 and later
3246 @item @emph{Syntax}:
3247 @code{RESULT = DIM(X, Y)}
3249 @item @emph{Arguments}:
3250 @multitable @columnfractions .15 .70
3251 @item @var{X} @tab The type shall be @code{INTEGER} or @code{REAL}
3252 @item @var{Y} @tab The type shall be the same type and kind as @var{X}.
3255 @item @emph{Return value}:
3256 The return value is of type @code{INTEGER} or @code{REAL}.
3258 @item @emph{Example}:
3264 x = dim(4.345_8, 2.111_8)
3267 end program test_dim
3270 @item @emph{Specific names}:
3271 @multitable @columnfractions .20 .20 .20 .25
3272 @item Name @tab Argument @tab Return type @tab Standard
3273 @item @code{DIM(X,Y)} @tab @code{REAL(4) X, Y} @tab @code{REAL(4)} @tab Fortran 77 and later
3274 @item @code{IDIM(X,Y)} @tab @code{INTEGER(4) X, Y} @tab @code{INTEGER(4)} @tab Fortran 77 and later
3275 @item @code{DDIM(X,Y)} @tab @code{REAL(8) X, Y} @tab @code{REAL(8)} @tab Fortran 77 and later
3282 @section @code{DOT_PRODUCT} --- Dot product function
3283 @fnindex DOT_PRODUCT
3285 @cindex vector product
3286 @cindex product, vector
3289 @item @emph{Description}:
3290 @code{DOT_PRODUCT(VECTOR_A, VECTOR_B)} computes the dot product multiplication
3291 of two vectors @var{VECTOR_A} and @var{VECTOR_B}. The two vectors may be
3292 either numeric or logical and must be arrays of rank one and of equal size. If
3293 the vectors are @code{INTEGER} or @code{REAL}, the result is
3294 @code{SUM(VECTOR_A*VECTOR_B)}. If the vectors are @code{COMPLEX}, the result
3295 is @code{SUM(CONJG(VECTOR_A)*VECTOR_B)}. If the vectors are @code{LOGICAL},
3296 the result is @code{ANY(VECTOR_A .AND. VECTOR_B)}.
3298 @item @emph{Standard}:
3299 Fortran 95 and later
3302 Transformational function
3304 @item @emph{Syntax}:
3305 @code{RESULT = DOT_PRODUCT(VECTOR_A, VECTOR_B)}
3307 @item @emph{Arguments}:
3308 @multitable @columnfractions .15 .70
3309 @item @var{VECTOR_A} @tab The type shall be numeric or @code{LOGICAL}, rank 1.
3310 @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.
3313 @item @emph{Return value}:
3314 If the arguments are numeric, the return value is a scalar of numeric type,
3315 @code{INTEGER}, @code{REAL}, or @code{COMPLEX}. If the arguments are
3316 @code{LOGICAL}, the return value is @code{.TRUE.} or @code{.FALSE.}.
3318 @item @emph{Example}:
3320 program test_dot_prod
3321 integer, dimension(3) :: a, b
3328 print *, dot_product(a,b)
3329 end program test_dot_prod
3336 @section @code{DPROD} --- Double product function
3338 @cindex product, double-precision
3341 @item @emph{Description}:
3342 @code{DPROD(X,Y)} returns the product @code{X*Y}.
3344 @item @emph{Standard}:
3345 Fortran 77 and later
3350 @item @emph{Syntax}:
3351 @code{RESULT = DPROD(X, Y)}
3353 @item @emph{Arguments}:
3354 @multitable @columnfractions .15 .70
3355 @item @var{X} @tab The type shall be @code{REAL}.
3356 @item @var{Y} @tab The type shall be @code{REAL}.
3359 @item @emph{Return value}:
3360 The return value is of type @code{REAL(8)}.
3362 @item @emph{Example}:
3370 end program test_dprod
3373 @item @emph{Specific names}:
3374 @multitable @columnfractions .20 .20 .20 .25
3375 @item Name @tab Argument @tab Return type @tab Standard
3376 @item @code{DPROD(X,Y)} @tab @code{REAL(4) X, Y} @tab @code{REAL(4)} @tab Fortran 77 and later
3383 @section @code{DREAL} --- Double real part function
3385 @cindex complex numbers, real part
3388 @item @emph{Description}:
3389 @code{DREAL(Z)} returns the real part of complex variable @var{Z}.
3391 @item @emph{Standard}:
3397 @item @emph{Syntax}:
3398 @code{RESULT = DREAL(A)}
3400 @item @emph{Arguments}:
3401 @multitable @columnfractions .15 .70
3402 @item @var{A} @tab The type shall be @code{COMPLEX(8)}.
3405 @item @emph{Return value}:
3406 The return value is of type @code{REAL(8)}.
3408 @item @emph{Example}:
3411 complex(8) :: z = (1.3_8,7.2_8)
3413 end program test_dreal
3416 @item @emph{See also}:
3424 @section @code{DTIME} --- Execution time subroutine (or function)
3426 @cindex time, elapsed
3427 @cindex elapsed time
3430 @item @emph{Description}:
3431 @code{DTIME(VALUES, TIME)} initially returns the number of seconds of runtime
3432 since the start of the process's execution in @var{TIME}. @var{VALUES}
3433 returns the user and system components of this time in @code{VALUES(1)} and
3434 @code{VALUES(2)} respectively. @var{TIME} is equal to @code{VALUES(1) +
3437 Subsequent invocations of @code{DTIME} return values accumulated since the
3438 previous invocation.
3440 On some systems, the underlying timings are represented using types with
3441 sufficiently small limits that overflows (wrap around) are possible, such as
3442 32-bit types. Therefore, the values returned by this intrinsic might be, or
3443 become, negative, or numerically less than previous values, during a single
3444 run of the compiled program.
3446 Please note, that this implementation is thread safe if used within OpenMP
3447 directives, i.e., its state will be consistent while called from multiple
3448 threads. However, if @code{DTIME} is called from multiple threads, the result
3449 is still the time since the last invocation. This may not give the intended
3450 results. If possible, use @code{CPU_TIME} instead.
3452 This intrinsic is provided in both subroutine and function forms; however,
3453 only one form can be used in any given program unit.
3455 @var{VALUES} and @var{TIME} are @code{INTENT(OUT)} and provide the following:
3457 @multitable @columnfractions .15 .30 .40
3458 @item @tab @code{VALUES(1)}: @tab User time in seconds.
3459 @item @tab @code{VALUES(2)}: @tab System time in seconds.
3460 @item @tab @code{TIME}: @tab Run time since start in seconds.
3463 @item @emph{Standard}:
3467 Subroutine, function
3469 @item @emph{Syntax}:
3470 @multitable @columnfractions .80
3471 @item @code{CALL DTIME(VALUES, TIME)}.
3472 @item @code{TIME = DTIME(VALUES)}, (not recommended).
3475 @item @emph{Arguments}:
3476 @multitable @columnfractions .15 .70
3477 @item @var{VALUES}@tab The type shall be @code{REAL(4), DIMENSION(2)}.
3478 @item @var{TIME}@tab The type shall be @code{REAL(4)}.
3481 @item @emph{Return value}:
3482 Elapsed time in seconds since the last invocation or since the start of program
3483 execution if not called before.
3485 @item @emph{Example}:
3489 real, dimension(2) :: tarray
3491 call dtime(tarray, result)
3495 do i=1,100000000 ! Just a delay
3498 call dtime(tarray, result)
3502 end program test_dtime
3505 @item @emph{See also}:
3513 @section @code{EOSHIFT} --- End-off shift elements of an array
3515 @cindex array, shift
3518 @item @emph{Description}:
3519 @code{EOSHIFT(ARRAY, SHIFT[, BOUNDARY, DIM])} performs an end-off shift on
3520 elements of @var{ARRAY} along the dimension of @var{DIM}. If @var{DIM} is
3521 omitted it is taken to be @code{1}. @var{DIM} is a scalar of type
3522 @code{INTEGER} in the range of @math{1 \leq DIM \leq n)} where @math{n} is the
3523 rank of @var{ARRAY}. If the rank of @var{ARRAY} is one, then all elements of
3524 @var{ARRAY} are shifted by @var{SHIFT} places. If rank is greater than one,
3525 then all complete rank one sections of @var{ARRAY} along the given dimension are
3526 shifted. Elements shifted out one end of each rank one section are dropped. If
3527 @var{BOUNDARY} is present then the corresponding value of from @var{BOUNDARY}
3528 is copied back in the other end. If @var{BOUNDARY} is not present then the
3529 following are copied in depending on the type of @var{ARRAY}.
3531 @multitable @columnfractions .15 .80
3532 @item @emph{Array Type} @tab @emph{Boundary Value}
3533 @item Numeric @tab 0 of the type and kind of @var{ARRAY}.
3534 @item Logical @tab @code{.FALSE.}.
3535 @item Character(@var{len}) @tab @var{len} blanks.
3538 @item @emph{Standard}:
3539 Fortran 95 and later
3542 Transformational function
3544 @item @emph{Syntax}:
3545 @code{RESULT = EOSHIFT(ARRAY, SHIFT [, BOUNDARY, DIM])}
3547 @item @emph{Arguments}:
3548 @multitable @columnfractions .15 .70
3549 @item @var{ARRAY} @tab May be any type, not scalar.
3550 @item @var{SHIFT} @tab The type shall be @code{INTEGER}.
3551 @item @var{BOUNDARY} @tab Same type as @var{ARRAY}.
3552 @item @var{DIM} @tab The type shall be @code{INTEGER}.
3555 @item @emph{Return value}:
3556 Returns an array of same type and rank as the @var{ARRAY} argument.
3558 @item @emph{Example}:
3560 program test_eoshift
3561 integer, dimension(3,3) :: a
3562 a = reshape( (/ 1, 2, 3, 4, 5, 6, 7, 8, 9 /), (/ 3, 3 /))
3563 print '(3i3)', a(1,:)
3564 print '(3i3)', a(2,:)
3565 print '(3i3)', a(3,:)
3566 a = EOSHIFT(a, SHIFT=(/1, 2, 1/), BOUNDARY=-5, DIM=2)
3568 print '(3i3)', a(1,:)
3569 print '(3i3)', a(2,:)
3570 print '(3i3)', a(3,:)
3571 end program test_eoshift
3578 @section @code{EPSILON} --- Epsilon function
3580 @cindex model representation, epsilon
3583 @item @emph{Description}:
3584 @code{EPSILON(X)} returns the smallest number @var{E} of the same kind
3585 as @var{X} such that @math{1 + E > 1}.
3587 @item @emph{Standard}:
3588 Fortran 95 and later
3593 @item @emph{Syntax}:
3594 @code{RESULT = EPSILON(X)}
3596 @item @emph{Arguments}:
3597 @multitable @columnfractions .15 .70
3598 @item @var{X} @tab The type shall be @code{REAL}.
3601 @item @emph{Return value}:
3602 The return value is of same type as the argument.
3604 @item @emph{Example}:
3606 program test_epsilon
3611 end program test_epsilon
3618 @section @code{ERF} --- Error function
3620 @cindex error function
3623 @item @emph{Description}:
3624 @code{ERF(X)} computes the error function of @var{X}.
3626 @item @emph{Standard}:
3627 Fortran 2008 and later
3632 @item @emph{Syntax}:
3633 @code{RESULT = ERF(X)}
3635 @item @emph{Arguments}:
3636 @multitable @columnfractions .15 .70
3637 @item @var{X} @tab The type shall be @code{REAL}.
3640 @item @emph{Return value}:
3641 The return value is of type @code{REAL}, of the same kind as
3642 @var{X} and lies in the range @math{-1 \leq erf (x) \leq 1 }.
3644 @item @emph{Example}:
3647 real(8) :: x = 0.17_8
3649 end program test_erf
3652 @item @emph{Specific names}:
3653 @multitable @columnfractions .20 .20 .20 .25
3654 @item Name @tab Argument @tab Return type @tab Standard
3655 @item @code{DERF(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU extension
3662 @section @code{ERFC} --- Error function
3664 @cindex error function, complementary
3667 @item @emph{Description}:
3668 @code{ERFC(X)} computes the complementary error function of @var{X}.
3670 @item @emph{Standard}:
3671 Fortran 2008 and later
3676 @item @emph{Syntax}:
3677 @code{RESULT = ERFC(X)}
3679 @item @emph{Arguments}:
3680 @multitable @columnfractions .15 .70
3681 @item @var{X} @tab The type shall be @code{REAL}.
3684 @item @emph{Return value}:
3685 The return value is of type @code{REAL} and of the same kind as @var{X}.
3686 It lies in the range @math{ 0 \leq erfc (x) \leq 2 }.
3688 @item @emph{Example}:
3691 real(8) :: x = 0.17_8
3693 end program test_erfc
3696 @item @emph{Specific names}:
3697 @multitable @columnfractions .20 .20 .20 .25
3698 @item Name @tab Argument @tab Return type @tab Standard
3699 @item @code{DERFC(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU extension
3706 @section @code{ERFC_SCALED} --- Error function
3707 @fnindex ERFC_SCALED
3708 @cindex error function, complementary, exponentially-scaled
3711 @item @emph{Description}:
3712 @code{ERFC_SCALED(X)} computes the exponentially-scaled complementary
3713 error function of @var{X}.
3715 @item @emph{Standard}:
3716 Fortran 2008 and later
3721 @item @emph{Syntax}:
3722 @code{RESULT = ERFC_SCALED(X)}
3724 @item @emph{Arguments}:
3725 @multitable @columnfractions .15 .70
3726 @item @var{X} @tab The type shall be @code{REAL}.
3729 @item @emph{Return value}:
3730 The return value is of type @code{REAL} and of the same kind as @var{X}.
3732 @item @emph{Example}:
3734 program test_erfc_scaled
3735 real(8) :: x = 0.17_8
3737 end program test_erfc_scaled
3744 @section @code{ETIME} --- Execution time subroutine (or function)
3746 @cindex time, elapsed
3749 @item @emph{Description}:
3750 @code{ETIME(VALUES, TIME)} returns the number of seconds of runtime
3751 since the start of the process's execution in @var{TIME}. @var{VALUES}
3752 returns the user and system components of this time in @code{VALUES(1)} and
3753 @code{VALUES(2)} respectively. @var{TIME} is equal to @code{VALUES(1) + VALUES(2)}.
3755 On some systems, the underlying timings are represented using types with
3756 sufficiently small limits that overflows (wrap around) are possible, such as
3757 32-bit types. Therefore, the values returned by this intrinsic might be, or
3758 become, negative, or numerically less than previous values, during a single
3759 run of the compiled program.
3761 This intrinsic is provided in both subroutine and function forms; however,
3762 only one form can be used in any given program unit.
3764 @var{VALUES} and @var{TIME} are @code{INTENT(OUT)} and provide the following:
3766 @multitable @columnfractions .15 .30 .60
3767 @item @tab @code{VALUES(1)}: @tab User time in seconds.
3768 @item @tab @code{VALUES(2)}: @tab System time in seconds.
3769 @item @tab @code{TIME}: @tab Run time since start in seconds.
3772 @item @emph{Standard}:
3776 Subroutine, function
3778 @item @emph{Syntax}:
3779 @multitable @columnfractions .80
3780 @item @code{CALL ETIME(VALUES, TIME)}.
3781 @item @code{TIME = ETIME(VALUES)}, (not recommended).
3784 @item @emph{Arguments}:
3785 @multitable @columnfractions .15 .70
3786 @item @var{VALUES}@tab The type shall be @code{REAL(4), DIMENSION(2)}.
3787 @item @var{TIME}@tab The type shall be @code{REAL(4)}.
3790 @item @emph{Return value}:
3791 Elapsed time in seconds since the start of program execution.
3793 @item @emph{Example}:
3797 real, dimension(2) :: tarray
3799 call ETIME(tarray, result)
3803 do i=1,100000000 ! Just a delay
3806 call ETIME(tarray, result)
3810 end program test_etime
3813 @item @emph{See also}:
3821 @section @code{EXIT} --- Exit the program with status.
3823 @cindex program termination
3824 @cindex terminate program
3827 @item @emph{Description}:
3828 @code{EXIT} causes immediate termination of the program with status. If status
3829 is omitted it returns the canonical @emph{success} for the system. All Fortran
3830 I/O units are closed.
3832 @item @emph{Standard}:
3838 @item @emph{Syntax}:
3839 @code{CALL EXIT([STATUS])}
3841 @item @emph{Arguments}:
3842 @multitable @columnfractions .15 .70
3843 @item @var{STATUS} @tab Shall be an @code{INTEGER} of the default kind.
3846 @item @emph{Return value}:
3847 @code{STATUS} is passed to the parent process on exit.
3849 @item @emph{Example}:
3852 integer :: STATUS = 0
3853 print *, 'This program is going to exit.'
3855 end program test_exit
3858 @item @emph{See also}:
3859 @ref{ABORT}, @ref{KILL}
3865 @section @code{EXP} --- Exponential function
3871 @cindex exponential function
3872 @cindex logarithmic function, inverse
3875 @item @emph{Description}:
3876 @code{EXP(X)} computes the base @math{e} exponential of @var{X}.
3878 @item @emph{Standard}:
3879 Fortran 77 and later, has overloads that are GNU extensions
3884 @item @emph{Syntax}:
3885 @code{RESULT = EXP(X)}
3887 @item @emph{Arguments}:
3888 @multitable @columnfractions .15 .70
3889 @item @var{X} @tab The type shall be @code{REAL} or
3893 @item @emph{Return value}:
3894 The return value has same type and kind as @var{X}.
3896 @item @emph{Example}:
3901 end program test_exp
3904 @item @emph{Specific names}:
3905 @multitable @columnfractions .20 .20 .20 .25
3906 @item Name @tab Argument @tab Return type @tab Standard
3907 @item @code{EXP(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab Fortran 77 and later
3908 @item @code{DEXP(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab Fortran 77 and later
3909 @item @code{CEXP(X)} @tab @code{COMPLEX(4) X} @tab @code{COMPLEX(4)} @tab Fortran 77 and later
3910 @item @code{ZEXP(X)} @tab @code{COMPLEX(8) X} @tab @code{COMPLEX(8)} @tab GNU extension
3911 @item @code{CDEXP(X)} @tab @code{COMPLEX(8) X} @tab @code{COMPLEX(8)} @tab GNU extension
3918 @section @code{EXPONENT} --- Exponent function
3920 @cindex real number, exponent
3921 @cindex floating point, exponent
3924 @item @emph{Description}:
3925 @code{EXPONENT(X)} returns the value of the exponent part of @var{X}. If @var{X}
3926 is zero the value returned is zero.
3928 @item @emph{Standard}:
3929 Fortran 95 and later
3934 @item @emph{Syntax}:
3935 @code{RESULT = EXPONENT(X)}
3937 @item @emph{Arguments}:
3938 @multitable @columnfractions .15 .70
3939 @item @var{X} @tab The type shall be @code{REAL}.
3942 @item @emph{Return value}:
3943 The return value is of type default @code{INTEGER}.
3945 @item @emph{Example}:
3947 program test_exponent
3952 print *, exponent(0.0)
3953 end program test_exponent
3959 @node EXTENDS_TYPE_OF
3960 @section @code{EXTENDS_TYPE_OF} --- Query dynamic type for extension
3961 @fnindex EXTENDS_TYPE_OF
3964 @item @emph{Description}:
3965 Query dynamic type for extension.
3967 @item @emph{Standard}:
3968 Fortran 2003 and later
3973 @item @emph{Syntax}:
3974 @code{RESULT = EXTENDS_TYPE_OF(A, MOLD)}
3976 @item @emph{Arguments}:
3977 @multitable @columnfractions .15 .70
3978 @item @var{A} @tab Shall be an object of extensible declared type or
3979 unlimited polymorphic.
3980 @item @var{MOLD} @tab Shall be an object of extensible declared type or
3981 unlimited polymorphic.
3984 @item @emph{Return value}:
3985 The return value is a scalar of type default logical. It is true if and only if
3986 the dynamic type of A is an extension type of the dynamic type of MOLD.
3989 @item @emph{See also}:
3996 @section @code{FDATE} --- Get the current time as a string
3998 @cindex time, current
3999 @cindex current time
4000 @cindex date, current
4001 @cindex current date
4004 @item @emph{Description}:
4005 @code{FDATE(DATE)} returns the current date (using the same format as
4006 @code{CTIME}) in @var{DATE}. It is equivalent to @code{CALL CTIME(DATE,
4009 This intrinsic is provided in both subroutine and function forms; however,
4010 only one form can be used in any given program unit.
4012 @var{DATE} is an @code{INTENT(OUT)} @code{CHARACTER} variable of the
4015 @item @emph{Standard}:
4019 Subroutine, function
4021 @item @emph{Syntax}:
4022 @multitable @columnfractions .80
4023 @item @code{CALL FDATE(DATE)}.
4024 @item @code{DATE = FDATE()}, (not recommended).
4027 @item @emph{Arguments}:
4028 @multitable @columnfractions .15 .70
4029 @item @var{DATE}@tab The type shall be of type @code{CHARACTER} of the
4033 @item @emph{Return value}:
4034 The current date as a string.
4036 @item @emph{Example}:
4040 character(len=30) :: date
4042 print *, 'Program started on ', date
4043 do i = 1, 100000000 ! Just a delay
4047 print *, 'Program ended on ', date
4048 end program test_fdate
4055 @section @code{FGET} --- Read a single character in stream mode from stdin
4057 @cindex read character, stream mode
4058 @cindex stream mode, read character
4059 @cindex file operation, read character
4062 @item @emph{Description}:
4063 Read a single character in stream mode from stdin by bypassing normal
4064 formatted output. Stream I/O should not be mixed with normal record-oriented
4065 (formatted or unformatted) I/O on the same unit; the results are unpredictable.
4067 This intrinsic is provided in both subroutine and function forms; however,
4068 only one form can be used in any given program unit.
4070 Note that the @code{FGET} intrinsic is provided for backwards compatibility with
4071 @command{g77}. GNU Fortran provides the Fortran 2003 Stream facility.
4072 Programmers should consider the use of new stream IO feature in new code
4073 for future portability. See also @ref{Fortran 2003 status}.
4075 @item @emph{Standard}:
4079 Subroutine, function
4081 @item @emph{Syntax}:
4082 @code{CALL FGET(C [, STATUS])}
4084 @item @emph{Arguments}:
4085 @multitable @columnfractions .15 .70
4086 @item @var{C} @tab The type shall be @code{CHARACTER} and of default
4088 @item @var{STATUS} @tab (Optional) status flag of type @code{INTEGER}.
4089 Returns 0 on success, -1 on end-of-file, and a system specific positive
4090 error code otherwise.
4093 @item @emph{Example}:
4096 INTEGER, PARAMETER :: strlen = 100
4097 INTEGER :: status, i = 1
4098 CHARACTER(len=strlen) :: str = ""
4100 WRITE (*,*) 'Enter text:'
4102 CALL fget(str(i:i), status)
4103 if (status /= 0 .OR. i > strlen) exit
4106 WRITE (*,*) TRIM(str)
4110 @item @emph{See also}:
4111 @ref{FGETC}, @ref{FPUT}, @ref{FPUTC}
4117 @section @code{FGETC} --- Read a single character in stream mode
4119 @cindex read character, stream mode
4120 @cindex stream mode, read character
4121 @cindex file operation, read character
4124 @item @emph{Description}:
4125 Read a single character in stream mode by bypassing normal formatted output.
4126 Stream I/O should not be mixed with normal record-oriented (formatted or
4127 unformatted) I/O on the same unit; the results are unpredictable.
4129 This intrinsic is provided in both subroutine and function forms; however,
4130 only one form can be used in any given program unit.
4132 Note that the @code{FGET} intrinsic is provided for backwards compatibility
4133 with @command{g77}. GNU Fortran provides the Fortran 2003 Stream facility.
4134 Programmers should consider the use of new stream IO feature in new code
4135 for future portability. See also @ref{Fortran 2003 status}.
4137 @item @emph{Standard}:
4141 Subroutine, function
4143 @item @emph{Syntax}:
4144 @code{CALL FGETC(UNIT, C [, STATUS])}
4146 @item @emph{Arguments}:
4147 @multitable @columnfractions .15 .70
4148 @item @var{UNIT} @tab The type shall be @code{INTEGER}.
4149 @item @var{C} @tab The type shall be @code{CHARACTER} and of default
4151 @item @var{STATUS} @tab (Optional) status flag of type @code{INTEGER}.
4152 Returns 0 on success, -1 on end-of-file and a system specific positive
4153 error code otherwise.
4156 @item @emph{Example}:
4159 INTEGER :: fd = 42, status
4162 OPEN(UNIT=fd, FILE="/etc/passwd", ACTION="READ", STATUS = "OLD")
4164 CALL fgetc(fd, c, status)
4165 IF (status /= 0) EXIT
4172 @item @emph{See also}:
4173 @ref{FGET}, @ref{FPUT}, @ref{FPUTC}
4179 @section @code{FLOOR} --- Integer floor function
4182 @cindex rounding, floor
4185 @item @emph{Description}:
4186 @code{FLOOR(A)} returns the greatest integer less than or equal to @var{X}.
4188 @item @emph{Standard}:
4189 Fortran 95 and later
4194 @item @emph{Syntax}:
4195 @code{RESULT = FLOOR(A [, KIND])}
4197 @item @emph{Arguments}:
4198 @multitable @columnfractions .15 .70
4199 @item @var{A} @tab The type shall be @code{REAL}.
4200 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
4201 expression indicating the kind parameter of the result.
4204 @item @emph{Return value}:
4205 The return value is of type @code{INTEGER(KIND)} if @var{KIND} is present
4206 and of default-kind @code{INTEGER} otherwise.
4208 @item @emph{Example}:
4213 print *, floor(x) ! returns 63
4214 print *, floor(y) ! returns -64
4215 end program test_floor
4218 @item @emph{See also}:
4219 @ref{CEILING}, @ref{NINT}
4226 @section @code{FLUSH} --- Flush I/O unit(s)
4228 @cindex file operation, flush
4231 @item @emph{Description}:
4232 Flushes Fortran unit(s) currently open for output. Without the optional
4233 argument, all units are flushed, otherwise just the unit specified.
4235 @item @emph{Standard}:
4241 @item @emph{Syntax}:
4242 @code{CALL FLUSH(UNIT)}
4244 @item @emph{Arguments}:
4245 @multitable @columnfractions .15 .70
4246 @item @var{UNIT} @tab (Optional) The type shall be @code{INTEGER}.
4250 Beginning with the Fortran 2003 standard, there is a @code{FLUSH}
4251 statement that should be preferred over the @code{FLUSH} intrinsic.
4253 The @code{FLUSH} intrinsic and the Fortran 2003 @code{FLUSH} statement
4254 have identical effect: they flush the runtime library's I/O buffer so
4255 that the data becomes visible to other processes. This does not guarantee
4256 that the data is committed to disk.
4258 On POSIX systems, you can request that all data is transferred to the
4259 storage device by calling the @code{fsync} function, with the POSIX file
4260 descriptor of the I/O unit as argument (retrieved with GNU intrinsic
4261 @code{FNUM}). The following example shows how:
4264 ! Declare the interface for POSIX fsync function
4266 function fsync (fd) bind(c,name="fsync")
4267 use iso_c_binding, only: c_int
4268 integer(c_int), value :: fd
4269 integer(c_int) :: fsync
4273 ! Variable declaration
4277 open (10,file="foo")
4280 ! Perform I/O on unit 10
4285 ret = fsync(fnum(10))
4287 ! Handle possible error
4288 if (ret /= 0) stop "Error calling FSYNC"
4296 @section @code{FNUM} --- File number function
4298 @cindex file operation, file number
4301 @item @emph{Description}:
4302 @code{FNUM(UNIT)} returns the POSIX file descriptor number corresponding to the
4303 open Fortran I/O unit @code{UNIT}.
4305 @item @emph{Standard}:
4311 @item @emph{Syntax}:
4312 @code{RESULT = FNUM(UNIT)}
4314 @item @emph{Arguments}:
4315 @multitable @columnfractions .15 .70
4316 @item @var{UNIT} @tab The type shall be @code{INTEGER}.
4319 @item @emph{Return value}:
4320 The return value is of type @code{INTEGER}
4322 @item @emph{Example}:
4326 open (unit=10, status = "scratch")
4330 end program test_fnum
4337 @section @code{FPUT} --- Write a single character in stream mode to stdout
4339 @cindex write character, stream mode
4340 @cindex stream mode, write character
4341 @cindex file operation, write character
4344 @item @emph{Description}:
4345 Write a single character in stream mode to stdout by bypassing normal
4346 formatted output. Stream I/O should not be mixed with normal record-oriented
4347 (formatted or unformatted) I/O on the same unit; the results are unpredictable.
4349 This intrinsic is provided in both subroutine and function forms; however,
4350 only one form can be used in any given program unit.
4352 Note that the @code{FGET} intrinsic is provided for backwards compatibility with
4353 @command{g77}. GNU Fortran provides the Fortran 2003 Stream facility.
4354 Programmers should consider the use of new stream IO feature in new code
4355 for future portability. See also @ref{Fortran 2003 status}.
4357 @item @emph{Standard}:
4361 Subroutine, function
4363 @item @emph{Syntax}:
4364 @code{CALL FPUT(C [, STATUS])}
4366 @item @emph{Arguments}:
4367 @multitable @columnfractions .15 .70
4368 @item @var{C} @tab The type shall be @code{CHARACTER} and of default
4370 @item @var{STATUS} @tab (Optional) status flag of type @code{INTEGER}.
4371 Returns 0 on success, -1 on end-of-file and a system specific positive
4372 error code otherwise.
4375 @item @emph{Example}:
4378 CHARACTER(len=10) :: str = "gfortran"
4380 DO i = 1, len_trim(str)
4386 @item @emph{See also}:
4387 @ref{FPUTC}, @ref{FGET}, @ref{FGETC}
4393 @section @code{FPUTC} --- Write a single character in stream mode
4395 @cindex write character, stream mode
4396 @cindex stream mode, write character
4397 @cindex file operation, write character
4400 @item @emph{Description}:
4401 Write a single character in stream mode by bypassing normal formatted
4402 output. Stream I/O should not be mixed with normal record-oriented
4403 (formatted or unformatted) I/O on the same unit; the results are unpredictable.
4405 This intrinsic is provided in both subroutine and function forms; however,
4406 only one form can be used in any given program unit.
4408 Note that the @code{FGET} intrinsic is provided for backwards compatibility with
4409 @command{g77}. GNU Fortran provides the Fortran 2003 Stream facility.
4410 Programmers should consider the use of new stream IO feature in new code
4411 for future portability. See also @ref{Fortran 2003 status}.
4413 @item @emph{Standard}:
4417 Subroutine, function
4419 @item @emph{Syntax}:
4420 @code{CALL FPUTC(UNIT, C [, STATUS])}
4422 @item @emph{Arguments}:
4423 @multitable @columnfractions .15 .70
4424 @item @var{UNIT} @tab The type shall be @code{INTEGER}.
4425 @item @var{C} @tab The type shall be @code{CHARACTER} and of default
4427 @item @var{STATUS} @tab (Optional) status flag of type @code{INTEGER}.
4428 Returns 0 on success, -1 on end-of-file and a system specific positive
4429 error code otherwise.
4432 @item @emph{Example}:
4435 CHARACTER(len=10) :: str = "gfortran"
4436 INTEGER :: fd = 42, i
4438 OPEN(UNIT = fd, FILE = "out", ACTION = "WRITE", STATUS="NEW")
4439 DO i = 1, len_trim(str)
4440 CALL fputc(fd, str(i:i))
4446 @item @emph{See also}:
4447 @ref{FPUT}, @ref{FGET}, @ref{FGETC}
4453 @section @code{FRACTION} --- Fractional part of the model representation
4455 @cindex real number, fraction
4456 @cindex floating point, fraction
4459 @item @emph{Description}:
4460 @code{FRACTION(X)} returns the fractional part of the model
4461 representation of @code{X}.
4463 @item @emph{Standard}:
4464 Fortran 95 and later
4469 @item @emph{Syntax}:
4470 @code{Y = FRACTION(X)}
4472 @item @emph{Arguments}:
4473 @multitable @columnfractions .15 .70
4474 @item @var{X} @tab The type of the argument shall be a @code{REAL}.
4477 @item @emph{Return value}:
4478 The return value is of the same type and kind as the argument.
4479 The fractional part of the model representation of @code{X} is returned;
4480 it is @code{X * RADIX(X)**(-EXPONENT(X))}.
4482 @item @emph{Example}:
4484 program test_fraction
4487 print *, fraction(x), x * radix(x)**(-exponent(x))
4488 end program test_fraction
4496 @section @code{FREE} --- Frees memory
4498 @cindex pointer, cray
4501 @item @emph{Description}:
4502 Frees memory previously allocated by @code{MALLOC()}. The @code{FREE}
4503 intrinsic is an extension intended to be used with Cray pointers, and is
4504 provided in GNU Fortran to allow user to compile legacy code. For
4505 new code using Fortran 95 pointers, the memory de-allocation intrinsic is
4508 @item @emph{Standard}:
4514 @item @emph{Syntax}:
4515 @code{CALL FREE(PTR)}
4517 @item @emph{Arguments}:
4518 @multitable @columnfractions .15 .70
4519 @item @var{PTR} @tab The type shall be @code{INTEGER}. It represents the
4520 location of the memory that should be de-allocated.
4523 @item @emph{Return value}:
4526 @item @emph{Example}:
4527 See @code{MALLOC} for an example.
4529 @item @emph{See also}:
4536 @section @code{FSEEK} --- Low level file positioning subroutine
4538 @cindex file operation, seek
4539 @cindex file operation, position
4542 @item @emph{Description}:
4543 Moves @var{UNIT} to the specified @var{OFFSET}. If @var{WHENCE}
4544 is set to 0, the @var{OFFSET} is taken as an absolute value @code{SEEK_SET},
4545 if set to 1, @var{OFFSET} is taken to be relative to the current position
4546 @code{SEEK_CUR}, and if set to 2 relative to the end of the file @code{SEEK_END}.
4547 On error, @var{STATUS} is set to a nonzero value. If @var{STATUS} the seek
4550 This intrinsic routine is not fully backwards compatible with @command{g77}.
4551 In @command{g77}, the @code{FSEEK} takes a statement label instead of a
4552 @var{STATUS} variable. If FSEEK is used in old code, change
4554 CALL FSEEK(UNIT, OFFSET, WHENCE, *label)
4559 CALL FSEEK(UNIT, OFFSET, WHENCE, status)
4560 IF (status /= 0) GOTO label
4563 Please note that GNU Fortran provides the Fortran 2003 Stream facility.
4564 Programmers should consider the use of new stream IO feature in new code
4565 for future portability. See also @ref{Fortran 2003 status}.
4567 @item @emph{Standard}:
4573 @item @emph{Syntax}:
4574 @code{CALL FSEEK(UNIT, OFFSET, WHENCE[, STATUS])}
4576 @item @emph{Arguments}:
4577 @multitable @columnfractions .15 .70
4578 @item @var{UNIT} @tab Shall be a scalar of type @code{INTEGER}.
4579 @item @var{OFFSET} @tab Shall be a scalar of type @code{INTEGER}.
4580 @item @var{WHENCE} @tab Shall be a scalar of type @code{INTEGER}.
4581 Its value shall be either 0, 1 or 2.
4582 @item @var{STATUS} @tab (Optional) shall be a scalar of type
4586 @item @emph{Example}:
4589 INTEGER, PARAMETER :: SEEK_SET = 0, SEEK_CUR = 1, SEEK_END = 2
4590 INTEGER :: fd, offset, ierr
4596 OPEN(UNIT=fd, FILE="fseek.test")
4597 CALL FSEEK(fd, offset, SEEK_SET, ierr) ! move to OFFSET
4598 print *, FTELL(fd), ierr
4600 CALL FSEEK(fd, 0, SEEK_END, ierr) ! move to end
4601 print *, FTELL(fd), ierr
4603 CALL FSEEK(fd, 0, SEEK_SET, ierr) ! move to beginning
4604 print *, FTELL(fd), ierr
4610 @item @emph{See also}:
4617 @section @code{FSTAT} --- Get file status
4619 @cindex file system, file status
4622 @item @emph{Description}:
4623 @code{FSTAT} is identical to @ref{STAT}, except that information about an
4624 already opened file is obtained.
4626 The elements in @code{VALUES} are the same as described by @ref{STAT}.
4628 This intrinsic is provided in both subroutine and function forms; however,
4629 only one form can be used in any given program unit.
4631 @item @emph{Standard}:
4635 Subroutine, function
4637 @item @emph{Syntax}:
4638 @code{CALL FSTAT(UNIT, VALUES [, STATUS])}
4640 @item @emph{Arguments}:
4641 @multitable @columnfractions .15 .70
4642 @item @var{UNIT} @tab An open I/O unit number of type @code{INTEGER}.
4643 @item @var{VALUES} @tab The type shall be @code{INTEGER(4), DIMENSION(13)}.
4644 @item @var{STATUS} @tab (Optional) status flag of type @code{INTEGER(4)}. Returns 0
4645 on success and a system specific error code otherwise.
4648 @item @emph{Example}:
4649 See @ref{STAT} for an example.
4651 @item @emph{See also}:
4652 To stat a link: @ref{LSTAT}, to stat a file: @ref{STAT}
4658 @section @code{FTELL} --- Current stream position
4660 @cindex file operation, position
4663 @item @emph{Description}:
4664 Retrieves the current position within an open file.
4666 This intrinsic is provided in both subroutine and function forms; however,
4667 only one form can be used in any given program unit.
4669 @item @emph{Standard}:
4673 Subroutine, function
4675 @item @emph{Syntax}:
4676 @multitable @columnfractions .80
4677 @item @code{CALL FTELL(UNIT, OFFSET)}
4678 @item @code{OFFSET = FTELL(UNIT)}
4681 @item @emph{Arguments}:
4682 @multitable @columnfractions .15 .70
4683 @item @var{OFFSET} @tab Shall of type @code{INTEGER}.
4684 @item @var{UNIT} @tab Shall of type @code{INTEGER}.
4687 @item @emph{Return value}:
4688 In either syntax, @var{OFFSET} is set to the current offset of unit
4689 number @var{UNIT}, or to @math{-1} if the unit is not currently open.
4691 @item @emph{Example}:
4695 OPEN(10, FILE="temp.dat")
4701 @item @emph{See also}:
4708 @section @code{GAMMA} --- Gamma function
4711 @cindex Gamma function
4712 @cindex Factorial function
4715 @item @emph{Description}:
4716 @code{GAMMA(X)} computes Gamma (@math{\Gamma}) of @var{X}. For positive,
4717 integer values of @var{X} the Gamma function simplifies to the factorial
4718 function @math{\Gamma(x)=(x-1)!}.
4722 \Gamma(x) = \int_0^\infty t^{x-1}{\rm e}^{-t}\,{\rm d}t
4726 @item @emph{Standard}:
4727 Fortran 2008 and later
4732 @item @emph{Syntax}:
4735 @item @emph{Arguments}:
4736 @multitable @columnfractions .15 .70
4737 @item @var{X} @tab Shall be of type @code{REAL} and neither zero
4738 nor a negative integer.
4741 @item @emph{Return value}:
4742 The return value is of type @code{REAL} of the same kind as @var{X}.
4744 @item @emph{Example}:
4748 x = gamma(x) ! returns 1.0
4749 end program test_gamma
4752 @item @emph{Specific names}:
4753 @multitable @columnfractions .20 .20 .20 .25
4754 @item Name @tab Argument @tab Return type @tab Standard
4755 @item @code{GAMMA(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab GNU Extension
4756 @item @code{DGAMMA(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU Extension
4759 @item @emph{See also}:
4760 Logarithm of the Gamma function: @ref{LOG_GAMMA}
4767 @section @code{GERROR} --- Get last system error message
4769 @cindex system, error handling
4772 @item @emph{Description}:
4773 Returns the system error message corresponding to the last system error.
4774 This resembles the functionality of @code{strerror(3)} in C.
4776 @item @emph{Standard}:
4782 @item @emph{Syntax}:
4783 @code{CALL GERROR(RESULT)}
4785 @item @emph{Arguments}:
4786 @multitable @columnfractions .15 .70
4787 @item @var{RESULT} @tab Shall of type @code{CHARACTER} and of default
4790 @item @emph{Example}:
4793 CHARACTER(len=100) :: msg
4799 @item @emph{See also}:
4800 @ref{IERRNO}, @ref{PERROR}
4806 @section @code{GETARG} --- Get command line arguments
4808 @cindex command-line arguments
4809 @cindex arguments, to program
4812 @item @emph{Description}:
4813 Retrieve the @var{POS}-th argument that was passed on the
4814 command line when the containing program was invoked.
4816 This intrinsic routine is provided for backwards compatibility with
4817 GNU Fortran 77. In new code, programmers should consider the use of
4818 the @ref{GET_COMMAND_ARGUMENT} intrinsic defined by the Fortran 2003
4821 @item @emph{Standard}:
4827 @item @emph{Syntax}:
4828 @code{CALL GETARG(POS, VALUE)}
4830 @item @emph{Arguments}:
4831 @multitable @columnfractions .15 .70
4832 @item @var{POS} @tab Shall be of type @code{INTEGER} and not wider than
4833 the default integer kind; @math{@var{POS} \geq 0}
4834 @item @var{VALUE} @tab Shall be of type @code{CHARACTER} and of default
4836 @item @var{VALUE} @tab Shall be of type @code{CHARACTER}.
4839 @item @emph{Return value}:
4840 After @code{GETARG} returns, the @var{VALUE} argument holds the
4841 @var{POS}th command line argument. If @var{VALUE} can not hold the
4842 argument, it is truncated to fit the length of @var{VALUE}. If there are
4843 less than @var{POS} arguments specified at the command line, @var{VALUE}
4844 will be filled with blanks. If @math{@var{POS} = 0}, @var{VALUE} is set
4845 to the name of the program (on systems that support this feature).
4847 @item @emph{Example}:
4851 CHARACTER(len=32) :: arg
4860 @item @emph{See also}:
4861 GNU Fortran 77 compatibility function: @ref{IARGC}
4863 Fortran 2003 functions and subroutines: @ref{GET_COMMAND},
4864 @ref{GET_COMMAND_ARGUMENT}, @ref{COMMAND_ARGUMENT_COUNT}
4870 @section @code{GET_COMMAND} --- Get the entire command line
4871 @fnindex GET_COMMAND
4872 @cindex command-line arguments
4873 @cindex arguments, to program
4876 @item @emph{Description}:
4877 Retrieve the entire command line that was used to invoke the program.
4879 @item @emph{Standard}:
4880 Fortran 2003 and later
4885 @item @emph{Syntax}:
4886 @code{CALL GET_COMMAND([COMMAND, LENGTH, STATUS])}
4888 @item @emph{Arguments}:
4889 @multitable @columnfractions .15 .70
4890 @item @var{COMMAND} @tab (Optional) shall be of type @code{CHARACTER} and
4892 @item @var{LENGTH} @tab (Optional) Shall be of type @code{INTEGER} and of
4894 @item @var{STATUS} @tab (Optional) Shall be of type @code{INTEGER} and of
4898 @item @emph{Return value}:
4899 If @var{COMMAND} is present, stores the entire command line that was used
4900 to invoke the program in @var{COMMAND}. If @var{LENGTH} is present, it is
4901 assigned the length of the command line. If @var{STATUS} is present, it
4902 is assigned 0 upon success of the command, -1 if @var{COMMAND} is too
4903 short to store the command line, or a positive value in case of an error.
4905 @item @emph{Example}:
4907 PROGRAM test_get_command
4908 CHARACTER(len=255) :: cmd
4909 CALL get_command(cmd)
4910 WRITE (*,*) TRIM(cmd)
4914 @item @emph{See also}:
4915 @ref{GET_COMMAND_ARGUMENT}, @ref{COMMAND_ARGUMENT_COUNT}
4920 @node GET_COMMAND_ARGUMENT
4921 @section @code{GET_COMMAND_ARGUMENT} --- Get command line arguments
4922 @fnindex GET_COMMAND_ARGUMENT
4923 @cindex command-line arguments
4924 @cindex arguments, to program
4927 @item @emph{Description}:
4928 Retrieve the @var{NUMBER}-th argument that was passed on the
4929 command line when the containing program was invoked.
4931 @item @emph{Standard}:
4932 Fortran 2003 and later
4937 @item @emph{Syntax}:
4938 @code{CALL GET_COMMAND_ARGUMENT(NUMBER [, VALUE, LENGTH, STATUS])}
4940 @item @emph{Arguments}:
4941 @multitable @columnfractions .15 .70
4942 @item @var{NUMBER} @tab Shall be a scalar of type @code{INTEGER} and of
4943 default kind, @math{@var{NUMBER} \geq 0}
4944 @item @var{VALUE} @tab Shall be a scalar of type @code{CHARACTER}
4945 and of default kind.
4946 @item @var{LENGTH} @tab (Option) Shall be a scalar of type @code{INTEGER}
4947 and of default kind.
4948 @item @var{STATUS} @tab (Option) Shall be a scalar of type @code{INTEGER}
4949 and of default kind.
4952 @item @emph{Return value}:
4953 After @code{GET_COMMAND_ARGUMENT} returns, the @var{VALUE} argument holds the
4954 @var{NUMBER}-th command line argument. If @var{VALUE} can not hold the argument, it is
4955 truncated to fit the length of @var{VALUE}. If there are less than @var{NUMBER}
4956 arguments specified at the command line, @var{VALUE} will be filled with blanks.
4957 If @math{@var{NUMBER} = 0}, @var{VALUE} is set to the name of the program (on
4958 systems that support this feature). The @var{LENGTH} argument contains the
4959 length of the @var{NUMBER}-th command line argument. If the argument retrieval
4960 fails, @var{STATUS} is a positive number; if @var{VALUE} contains a truncated
4961 command line argument, @var{STATUS} is -1; and otherwise the @var{STATUS} is
4964 @item @emph{Example}:
4966 PROGRAM test_get_command_argument
4968 CHARACTER(len=32) :: arg
4972 CALL get_command_argument(i, arg)
4973 IF (LEN_TRIM(arg) == 0) EXIT
4975 WRITE (*,*) TRIM(arg)
4981 @item @emph{See also}:
4982 @ref{GET_COMMAND}, @ref{COMMAND_ARGUMENT_COUNT}
4988 @section @code{GETCWD} --- Get current working directory
4990 @cindex system, working directory
4993 @item @emph{Description}:
4994 Get current working directory.
4996 This intrinsic is provided in both subroutine and function forms; however,
4997 only one form can be used in any given program unit.
4999 @item @emph{Standard}:
5003 Subroutine, function
5005 @item @emph{Syntax}:
5006 @code{CALL GETCWD(C [, STATUS])}
5008 @item @emph{Arguments}:
5009 @multitable @columnfractions .15 .70
5010 @item @var{C} @tab The type shall be @code{CHARACTER} and of default kind.
5011 @item @var{STATUS} @tab (Optional) status flag. Returns 0 on success,
5012 a system specific and nonzero error code otherwise.
5015 @item @emph{Example}:
5018 CHARACTER(len=255) :: cwd
5020 WRITE(*,*) TRIM(cwd)
5024 @item @emph{See also}:
5031 @section @code{GETENV} --- Get an environmental variable
5033 @cindex environment variable
5036 @item @emph{Description}:
5037 Get the @var{VALUE} of the environmental variable @var{NAME}.
5039 This intrinsic routine is provided for backwards compatibility with
5040 GNU Fortran 77. In new code, programmers should consider the use of
5041 the @ref{GET_ENVIRONMENT_VARIABLE} intrinsic defined by the Fortran
5044 @item @emph{Standard}:
5050 @item @emph{Syntax}:
5051 @code{CALL GETENV(NAME, VALUE)}
5053 @item @emph{Arguments}:
5054 @multitable @columnfractions .15 .70
5055 @item @var{NAME} @tab Shall be of type @code{CHARACTER} and of default kind.
5056 @item @var{VALUE} @tab Shall be of type @code{CHARACTER} and of default kind.
5059 @item @emph{Return value}:
5060 Stores the value of @var{NAME} in @var{VALUE}. If @var{VALUE} is
5061 not large enough to hold the data, it is truncated. If @var{NAME}
5062 is not set, @var{VALUE} will be filled with blanks.
5064 @item @emph{Example}:
5067 CHARACTER(len=255) :: homedir
5068 CALL getenv("HOME", homedir)
5069 WRITE (*,*) TRIM(homedir)
5073 @item @emph{See also}:
5074 @ref{GET_ENVIRONMENT_VARIABLE}
5079 @node GET_ENVIRONMENT_VARIABLE
5080 @section @code{GET_ENVIRONMENT_VARIABLE} --- Get an environmental variable
5081 @fnindex GET_ENVIRONMENT_VARIABLE
5082 @cindex environment variable
5085 @item @emph{Description}:
5086 Get the @var{VALUE} of the environmental variable @var{NAME}.
5088 @item @emph{Standard}:
5089 Fortran 2003 and later
5094 @item @emph{Syntax}:
5095 @code{CALL GET_ENVIRONMENT_VARIABLE(NAME[, VALUE, LENGTH, STATUS, TRIM_NAME)}
5097 @item @emph{Arguments}:
5098 @multitable @columnfractions .15 .70
5099 @item @var{NAME} @tab Shall be a scalar of type @code{CHARACTER}
5100 and of default kind.
5101 @item @var{VALUE} @tab Shall be a scalar of type @code{CHARACTER}
5102 and of default kind.
5103 @item @var{LENGTH} @tab Shall be a scalar of type @code{INTEGER}
5104 and of default kind.
5105 @item @var{STATUS} @tab Shall be a scalar of type @code{INTEGER}
5106 and of default kind.
5107 @item @var{TRIM_NAME} @tab Shall be a scalar of type @code{LOGICAL}
5108 and of default kind.
5111 @item @emph{Return value}:
5112 Stores the value of @var{NAME} in @var{VALUE}. If @var{VALUE} is
5113 not large enough to hold the data, it is truncated. If @var{NAME}
5114 is not set, @var{VALUE} will be filled with blanks. Argument @var{LENGTH}
5115 contains the length needed for storing the environment variable @var{NAME}
5116 or zero if it is not present. @var{STATUS} is -1 if @var{VALUE} is present
5117 but too short for the environment variable; it is 1 if the environment
5118 variable does not exist and 2 if the processor does not support environment
5119 variables; in all other cases @var{STATUS} is zero. If @var{TRIM_NAME} is
5120 present with the value @code{.FALSE.}, the trailing blanks in @var{NAME}
5121 are significant; otherwise they are not part of the environment variable
5124 @item @emph{Example}:
5127 CHARACTER(len=255) :: homedir
5128 CALL get_environment_variable("HOME", homedir)
5129 WRITE (*,*) TRIM(homedir)
5137 @section @code{GETGID} --- Group ID function
5139 @cindex system, group id
5142 @item @emph{Description}:
5143 Returns the numerical group ID of the current process.
5145 @item @emph{Standard}:
5151 @item @emph{Syntax}:
5152 @code{RESULT = GETGID()}
5154 @item @emph{Return value}:
5155 The return value of @code{GETGID} is an @code{INTEGER} of the default
5159 @item @emph{Example}:
5160 See @code{GETPID} for an example.
5162 @item @emph{See also}:
5163 @ref{GETPID}, @ref{GETUID}
5169 @section @code{GETLOG} --- Get login name
5171 @cindex system, login name
5175 @item @emph{Description}:
5176 Gets the username under which the program is running.
5178 @item @emph{Standard}:
5184 @item @emph{Syntax}:
5185 @code{CALL GETLOG(C)}
5187 @item @emph{Arguments}:
5188 @multitable @columnfractions .15 .70
5189 @item @var{C} @tab Shall be of type @code{CHARACTER} and of default kind.
5192 @item @emph{Return value}:
5193 Stores the current user name in @var{LOGIN}. (On systems where POSIX
5194 functions @code{geteuid} and @code{getpwuid} are not available, and
5195 the @code{getlogin} function is not implemented either, this will
5196 return a blank string.)
5198 @item @emph{Example}:
5201 CHARACTER(32) :: login
5207 @item @emph{See also}:
5214 @section @code{GETPID} --- Process ID function
5216 @cindex system, process id
5220 @item @emph{Description}:
5221 Returns the numerical process identifier of the current process.
5223 @item @emph{Standard}:
5229 @item @emph{Syntax}:
5230 @code{RESULT = GETPID()}
5232 @item @emph{Return value}:
5233 The return value of @code{GETPID} is an @code{INTEGER} of the default
5237 @item @emph{Example}:
5240 print *, "The current process ID is ", getpid()
5241 print *, "Your numerical user ID is ", getuid()
5242 print *, "Your numerical group ID is ", getgid()
5246 @item @emph{See also}:
5247 @ref{GETGID}, @ref{GETUID}
5253 @section @code{GETUID} --- User ID function
5255 @cindex system, user id
5259 @item @emph{Description}:
5260 Returns the numerical user ID of the current process.
5262 @item @emph{Standard}:
5268 @item @emph{Syntax}:
5269 @code{RESULT = GETUID()}
5271 @item @emph{Return value}:
5272 The return value of @code{GETUID} is an @code{INTEGER} of the default
5276 @item @emph{Example}:
5277 See @code{GETPID} for an example.
5279 @item @emph{See also}:
5280 @ref{GETPID}, @ref{GETLOG}
5286 @section @code{GMTIME} --- Convert time to GMT info
5288 @cindex time, conversion to GMT info
5291 @item @emph{Description}:
5292 Given a system time value @var{TIME} (as provided by the @code{TIME8()}
5293 intrinsic), fills @var{VALUES} with values extracted from it appropriate
5294 to the UTC time zone (Universal Coordinated Time, also known in some
5295 countries as GMT, Greenwich Mean Time), using @code{gmtime(3)}.
5297 @item @emph{Standard}:
5303 @item @emph{Syntax}:
5304 @code{CALL GMTIME(TIME, VALUES)}
5306 @item @emph{Arguments}:
5307 @multitable @columnfractions .15 .70
5308 @item @var{TIME} @tab An @code{INTEGER} scalar expression
5309 corresponding to a system time, with @code{INTENT(IN)}.
5310 @item @var{VALUES} @tab A default @code{INTEGER} array with 9 elements,
5311 with @code{INTENT(OUT)}.
5314 @item @emph{Return value}:
5315 The elements of @var{VALUES} are assigned as follows:
5317 @item Seconds after the minute, range 0--59 or 0--61 to allow for leap
5319 @item Minutes after the hour, range 0--59
5320 @item Hours past midnight, range 0--23
5321 @item Day of month, range 0--31
5322 @item Number of months since January, range 0--12
5323 @item Years since 1900
5324 @item Number of days since Sunday, range 0--6
5325 @item Days since January 1
5326 @item Daylight savings indicator: positive if daylight savings is in
5327 effect, zero if not, and negative if the information is not available.
5330 @item @emph{See also}:
5331 @ref{CTIME}, @ref{LTIME}, @ref{TIME}, @ref{TIME8}
5338 @section @code{HOSTNM} --- Get system host name
5340 @cindex system, host name
5343 @item @emph{Description}:
5344 Retrieves the host name of the system on which the program is running.
5346 This intrinsic is provided in both subroutine and function forms; however,
5347 only one form can be used in any given program unit.
5349 @item @emph{Standard}:
5353 Subroutine, function
5355 @item @emph{Syntax}:
5356 @multitable @columnfractions .80
5357 @item @code{CALL HOSTNM(C [, STATUS])}
5358 @item @code{STATUS = HOSTNM(NAME)}
5361 @item @emph{Arguments}:
5362 @multitable @columnfractions .15 .70
5363 @item @var{C} @tab Shall of type @code{CHARACTER} and of default kind.
5364 @item @var{STATUS} @tab (Optional) status flag of type @code{INTEGER}.
5365 Returns 0 on success, or a system specific error code otherwise.
5368 @item @emph{Return value}:
5369 In either syntax, @var{NAME} is set to the current hostname if it can
5370 be obtained, or to a blank string otherwise.
5377 @section @code{HUGE} --- Largest number of a kind
5379 @cindex limits, largest number
5380 @cindex model representation, largest number
5383 @item @emph{Description}:
5384 @code{HUGE(X)} returns the largest number that is not an infinity in
5385 the model of the type of @code{X}.
5387 @item @emph{Standard}:
5388 Fortran 95 and later
5393 @item @emph{Syntax}:
5394 @code{RESULT = HUGE(X)}
5396 @item @emph{Arguments}:
5397 @multitable @columnfractions .15 .70
5398 @item @var{X} @tab Shall be of type @code{REAL} or @code{INTEGER}.
5401 @item @emph{Return value}:
5402 The return value is of the same type and kind as @var{X}
5404 @item @emph{Example}:
5406 program test_huge_tiny
5407 print *, huge(0), huge(0.0), huge(0.0d0)
5408 print *, tiny(0.0), tiny(0.0d0)
5409 end program test_huge_tiny
5416 @section @code{HYPOT} --- Euclidean distance function
5418 @cindex Euclidean distance
5421 @item @emph{Description}:
5422 @code{HYPOT(X,Y)} is the Euclidean distance function. It is equal to
5423 @math{\sqrt{X^2 + Y^2}}, without undue underflow or overflow.
5425 @item @emph{Standard}:
5426 Fortran 2008 and later
5431 @item @emph{Syntax}:
5432 @code{RESULT = HYPOT(X, Y)}
5434 @item @emph{Arguments}:
5435 @multitable @columnfractions .15 .70
5436 @item @var{X} @tab The type shall be @code{REAL}.
5437 @item @var{Y} @tab The type and kind type parameter shall be the same as
5441 @item @emph{Return value}:
5442 The return value has the same type and kind type parameter as @var{X}.
5444 @item @emph{Example}:
5447 real(4) :: x = 1.e0_4, y = 0.5e0_4
5449 end program test_hypot
5456 @section @code{IACHAR} --- Code in @acronym{ASCII} collating sequence
5458 @cindex @acronym{ASCII} collating sequence
5459 @cindex collating sequence, @acronym{ASCII}
5460 @cindex conversion, to integer
5463 @item @emph{Description}:
5464 @code{IACHAR(C)} returns the code for the @acronym{ASCII} character
5465 in the first character position of @code{C}.
5467 @item @emph{Standard}:
5468 Fortran 95 and later, with @var{KIND} argument Fortran 2003 and later
5473 @item @emph{Syntax}:
5474 @code{RESULT = IACHAR(C [, KIND])}
5476 @item @emph{Arguments}:
5477 @multitable @columnfractions .15 .70
5478 @item @var{C} @tab Shall be a scalar @code{CHARACTER}, with @code{INTENT(IN)}
5479 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
5480 expression indicating the kind parameter of the result.
5483 @item @emph{Return value}:
5484 The return value is of type @code{INTEGER} and of kind @var{KIND}. If
5485 @var{KIND} is absent, the return value is of default integer kind.
5487 @item @emph{Example}:
5492 end program test_iachar
5496 See @ref{ICHAR} for a discussion of converting between numerical values
5497 and formatted string representations.
5499 @item @emph{See also}:
5500 @ref{ACHAR}, @ref{CHAR}, @ref{ICHAR}
5507 @section @code{IAND} --- Bitwise logical and
5509 @cindex bitwise logical and
5510 @cindex logical and, bitwise
5513 @item @emph{Description}:
5514 Bitwise logical @code{AND}.
5516 @item @emph{Standard}:
5517 Fortran 95 and later
5522 @item @emph{Syntax}:
5523 @code{RESULT = IAND(I, J)}
5525 @item @emph{Arguments}:
5526 @multitable @columnfractions .15 .70
5527 @item @var{I} @tab The type shall be @code{INTEGER}.
5528 @item @var{J} @tab The type shall be @code{INTEGER}, of the same
5529 kind as @var{I}. (As a GNU extension, different kinds are also
5533 @item @emph{Return value}:
5534 The return type is @code{INTEGER}, of the same kind as the
5535 arguments. (If the argument kinds differ, it is of the same kind as
5536 the larger argument.)
5538 @item @emph{Example}:
5542 DATA a / Z'F' /, b / Z'3' /
5543 WRITE (*,*) IAND(a, b)
5547 @item @emph{See also}:
5548 @ref{IOR}, @ref{IEOR}, @ref{IBITS}, @ref{IBSET}, @ref{IBCLR}, @ref{NOT}
5555 @section @code{IARGC} --- Get the number of command line arguments
5557 @cindex command-line arguments
5558 @cindex command-line arguments, number of
5559 @cindex arguments, to program
5562 @item @emph{Description}:
5563 @code{IARGC()} returns the number of arguments passed on the
5564 command line when the containing program was invoked.
5566 This intrinsic routine is provided for backwards compatibility with
5567 GNU Fortran 77. In new code, programmers should consider the use of
5568 the @ref{COMMAND_ARGUMENT_COUNT} intrinsic defined by the Fortran 2003
5571 @item @emph{Standard}:
5577 @item @emph{Syntax}:
5578 @code{RESULT = IARGC()}
5580 @item @emph{Arguments}:
5583 @item @emph{Return value}:
5584 The number of command line arguments, type @code{INTEGER(4)}.
5586 @item @emph{Example}:
5589 @item @emph{See also}:
5590 GNU Fortran 77 compatibility subroutine: @ref{GETARG}
5592 Fortran 2003 functions and subroutines: @ref{GET_COMMAND},
5593 @ref{GET_COMMAND_ARGUMENT}, @ref{COMMAND_ARGUMENT_COUNT}
5599 @section @code{IBCLR} --- Clear bit
5605 @item @emph{Description}:
5606 @code{IBCLR} returns the value of @var{I} with the bit at position
5607 @var{POS} set to zero.
5609 @item @emph{Standard}:
5610 Fortran 95 and later
5615 @item @emph{Syntax}:
5616 @code{RESULT = IBCLR(I, POS)}
5618 @item @emph{Arguments}:
5619 @multitable @columnfractions .15 .70
5620 @item @var{I} @tab The type shall be @code{INTEGER}.
5621 @item @var{POS} @tab The type shall be @code{INTEGER}.
5624 @item @emph{Return value}:
5625 The return value is of type @code{INTEGER} and of the same kind as
5628 @item @emph{See also}:
5629 @ref{IBITS}, @ref{IBSET}, @ref{IAND}, @ref{IOR}, @ref{IEOR}, @ref{MVBITS}
5636 @section @code{IBITS} --- Bit extraction
5639 @cindex bits, extract
5642 @item @emph{Description}:
5643 @code{IBITS} extracts a field of length @var{LEN} from @var{I},
5644 starting from bit position @var{POS} and extending left for @var{LEN}
5645 bits. The result is right-justified and the remaining bits are
5646 zeroed. The value of @code{POS+LEN} must be less than or equal to the
5647 value @code{BIT_SIZE(I)}.
5649 @item @emph{Standard}:
5650 Fortran 95 and later
5655 @item @emph{Syntax}:
5656 @code{RESULT = IBITS(I, POS, LEN)}
5658 @item @emph{Arguments}:
5659 @multitable @columnfractions .15 .70
5660 @item @var{I} @tab The type shall be @code{INTEGER}.
5661 @item @var{POS} @tab The type shall be @code{INTEGER}.
5662 @item @var{LEN} @tab The type shall be @code{INTEGER}.
5665 @item @emph{Return value}:
5666 The return value is of type @code{INTEGER} and of the same kind as
5669 @item @emph{See also}:
5670 @ref{BIT_SIZE}, @ref{IBCLR}, @ref{IBSET}, @ref{IAND}, @ref{IOR}, @ref{IEOR}
5676 @section @code{IBSET} --- Set bit
5681 @item @emph{Description}:
5682 @code{IBSET} returns the value of @var{I} with the bit at position
5683 @var{POS} set to one.
5685 @item @emph{Standard}:
5686 Fortran 95 and later
5691 @item @emph{Syntax}:
5692 @code{RESULT = IBSET(I, POS)}
5694 @item @emph{Arguments}:
5695 @multitable @columnfractions .15 .70
5696 @item @var{I} @tab The type shall be @code{INTEGER}.
5697 @item @var{POS} @tab The type shall be @code{INTEGER}.
5700 @item @emph{Return value}:
5701 The return value is of type @code{INTEGER} and of the same kind as
5704 @item @emph{See also}:
5705 @ref{IBCLR}, @ref{IBITS}, @ref{IAND}, @ref{IOR}, @ref{IEOR}, @ref{MVBITS}
5712 @section @code{ICHAR} --- Character-to-integer conversion function
5714 @cindex conversion, to integer
5717 @item @emph{Description}:
5718 @code{ICHAR(C)} returns the code for the character in the first character
5719 position of @code{C} in the system's native character set.
5720 The correspondence between characters and their codes is not necessarily
5721 the same across different GNU Fortran implementations.
5723 @item @emph{Standard}:
5724 Fortan 95 and later, with @var{KIND} argument Fortran 2003 and later
5729 @item @emph{Syntax}:
5730 @code{RESULT = ICHAR(C [, KIND])}
5732 @item @emph{Arguments}:
5733 @multitable @columnfractions .15 .70
5734 @item @var{C} @tab Shall be a scalar @code{CHARACTER}, with @code{INTENT(IN)}
5735 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
5736 expression indicating the kind parameter of the result.
5739 @item @emph{Return value}:
5740 The return value is of type @code{INTEGER} and of kind @var{KIND}. If
5741 @var{KIND} is absent, the return value is of default integer kind.
5743 @item @emph{Example}:
5748 end program test_ichar
5751 @item @emph{Specific names}:
5752 @multitable @columnfractions .20 .20 .20 .25
5753 @item Name @tab Argument @tab Return type @tab Standard
5754 @item @code{ICHAR(C)} @tab @code{CHARACTER C} @tab @code{INTEGER(4)} @tab Fortran 77 and later
5758 No intrinsic exists to convert between a numeric value and a formatted
5759 character string representation -- for instance, given the
5760 @code{CHARACTER} value @code{'154'}, obtaining an @code{INTEGER} or
5761 @code{REAL} value with the value 154, or vice versa. Instead, this
5762 functionality is provided by internal-file I/O, as in the following
5767 character(len=10) string, string2
5770 ! Convert a string to a numeric value
5771 read (string,'(I10)') value
5774 ! Convert a value to a formatted string
5775 write (string2,'(I10)') value
5777 end program read_val
5780 @item @emph{See also}:
5781 @ref{ACHAR}, @ref{CHAR}, @ref{IACHAR}
5788 @section @code{IDATE} --- Get current local time subroutine (day/month/year)
5790 @cindex date, current
5791 @cindex current date
5794 @item @emph{Description}:
5795 @code{IDATE(VALUES)} Fills @var{VALUES} with the numerical values at the
5796 current local time. The day (in the range 1-31), month (in the range 1-12),
5797 and year appear in elements 1, 2, and 3 of @var{VALUES}, respectively.
5798 The year has four significant digits.
5800 @item @emph{Standard}:
5806 @item @emph{Syntax}:
5807 @code{CALL IDATE(VALUES)}
5809 @item @emph{Arguments}:
5810 @multitable @columnfractions .15 .70
5811 @item @var{VALUES} @tab The type shall be @code{INTEGER, DIMENSION(3)} and
5812 the kind shall be the default integer kind.
5815 @item @emph{Return value}:
5816 Does not return anything.
5818 @item @emph{Example}:
5821 integer, dimension(3) :: tarray
5826 end program test_idate
5833 @section @code{IEOR} --- Bitwise logical exclusive or
5835 @cindex bitwise logical exclusive or
5836 @cindex logical exclusive or, bitwise
5839 @item @emph{Description}:
5840 @code{IEOR} returns the bitwise boolean exclusive-OR of @var{I} and
5843 @item @emph{Standard}:
5844 Fortran 95 and later
5849 @item @emph{Syntax}:
5850 @code{RESULT = IEOR(I, J)}
5852 @item @emph{Arguments}:
5853 @multitable @columnfractions .15 .70
5854 @item @var{I} @tab The type shall be @code{INTEGER}.
5855 @item @var{J} @tab The type shall be @code{INTEGER}, of the same
5856 kind as @var{I}. (As a GNU extension, different kinds are also
5860 @item @emph{Return value}:
5861 The return type is @code{INTEGER}, of the same kind as the
5862 arguments. (If the argument kinds differ, it is of the same kind as
5863 the larger argument.)
5865 @item @emph{See also}:
5866 @ref{IOR}, @ref{IAND}, @ref{IBITS}, @ref{IBSET}, @ref{IBCLR}, @ref{NOT}
5872 @section @code{IERRNO} --- Get the last system error number
5874 @cindex system, error handling
5877 @item @emph{Description}:
5878 Returns the last system error number, as given by the C @code{errno()}
5881 @item @emph{Standard}:
5887 @item @emph{Syntax}:
5888 @code{RESULT = IERRNO()}
5890 @item @emph{Arguments}:
5893 @item @emph{Return value}:
5894 The return value is of type @code{INTEGER} and of the default integer
5897 @item @emph{See also}:
5903 @node INDEX intrinsic
5904 @section @code{INDEX} --- Position of a substring within a string
5906 @cindex substring position
5907 @cindex string, find substring
5910 @item @emph{Description}:
5911 Returns the position of the start of the first occurrence of string
5912 @var{SUBSTRING} as a substring in @var{STRING}, counting from one. If
5913 @var{SUBSTRING} is not present in @var{STRING}, zero is returned. If
5914 the @var{BACK} argument is present and true, the return value is the
5915 start of the last occurrence rather than the first.
5917 @item @emph{Standard}:
5918 Fortran 77 and later, with @var{KIND} argument Fortran 2003 and later
5923 @item @emph{Syntax}:
5924 @code{RESULT = INDEX(STRING, SUBSTRING [, BACK [, KIND]])}
5926 @item @emph{Arguments}:
5927 @multitable @columnfractions .15 .70
5928 @item @var{STRING} @tab Shall be a scalar @code{CHARACTER}, with
5930 @item @var{SUBSTRING} @tab Shall be a scalar @code{CHARACTER}, with
5932 @item @var{BACK} @tab (Optional) Shall be a scalar @code{LOGICAL}, with
5934 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
5935 expression indicating the kind parameter of the result.
5938 @item @emph{Return value}:
5939 The return value is of type @code{INTEGER} and of kind @var{KIND}. If
5940 @var{KIND} is absent, the return value is of default integer kind.
5942 @item @emph{Specific names}:
5943 @multitable @columnfractions .20 .20 .20 .25
5944 @item Name @tab Argument @tab Return type @tab Standard
5945 @item @code{INDEX(STRING, SUBSTRING)} @tab @code{CHARACTER} @tab @code{INTEGER(4)} @tab Fortran 77 and later
5948 @item @emph{See also}:
5949 @ref{SCAN}, @ref{VERIFY}
5955 @section @code{INT} --- Convert to integer type
5959 @cindex conversion, to integer
5962 @item @emph{Description}:
5963 Convert to integer type
5965 @item @emph{Standard}:
5966 Fortran 77 and later
5971 @item @emph{Syntax}:
5972 @code{RESULT = INT(A [, KIND))}
5974 @item @emph{Arguments}:
5975 @multitable @columnfractions .15 .70
5976 @item @var{A} @tab Shall be of type @code{INTEGER},
5977 @code{REAL}, or @code{COMPLEX}.
5978 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
5979 expression indicating the kind parameter of the result.
5982 @item @emph{Return value}:
5983 These functions return a @code{INTEGER} variable or array under
5984 the following rules:
5988 If @var{A} is of type @code{INTEGER}, @code{INT(A) = A}
5990 If @var{A} is of type @code{REAL} and @math{|A| < 1}, @code{INT(A)} equals @code{0}.
5991 If @math{|A| \geq 1}, then @code{INT(A)} equals the largest integer that does not exceed
5992 the range of @var{A} and whose sign is the same as the sign of @var{A}.
5994 If @var{A} is of type @code{COMPLEX}, rule B is applied to the real part of @var{A}.
5997 @item @emph{Example}:
6001 complex :: z = (-3.7, 1.0)
6003 print *, int(z), int(z,8)
6007 @item @emph{Specific names}:
6008 @multitable @columnfractions .20 .20 .20 .25
6009 @item Name @tab Argument @tab Return type @tab Standard
6010 @item @code{INT(A)} @tab @code{REAL(4) A} @tab @code{INTEGER} @tab Fortran 77 and later
6011 @item @code{IFIX(A)} @tab @code{REAL(4) A} @tab @code{INTEGER} @tab Fortran 77 and later
6012 @item @code{IDINT(A)} @tab @code{REAL(8) A} @tab @code{INTEGER} @tab Fortran 77 and later
6019 @section @code{INT2} --- Convert to 16-bit integer type
6022 @cindex conversion, to integer
6025 @item @emph{Description}:
6026 Convert to a @code{KIND=2} integer type. This is equivalent to the
6027 standard @code{INT} intrinsic with an optional argument of
6028 @code{KIND=2}, and is only included for backwards compatibility.
6030 The @code{SHORT} intrinsic is equivalent to @code{INT2}.
6032 @item @emph{Standard}:
6038 @item @emph{Syntax}:
6039 @code{RESULT = INT2(A)}
6041 @item @emph{Arguments}:
6042 @multitable @columnfractions .15 .70
6043 @item @var{A} @tab Shall be of type @code{INTEGER},
6044 @code{REAL}, or @code{COMPLEX}.
6047 @item @emph{Return value}:
6048 The return value is a @code{INTEGER(2)} variable.
6050 @item @emph{See also}:
6051 @ref{INT}, @ref{INT8}, @ref{LONG}
6057 @section @code{INT8} --- Convert to 64-bit integer type
6059 @cindex conversion, to integer
6062 @item @emph{Description}:
6063 Convert to a @code{KIND=8} integer type. This is equivalent to the
6064 standard @code{INT} intrinsic with an optional argument of
6065 @code{KIND=8}, and is only included for backwards compatibility.
6067 @item @emph{Standard}:
6073 @item @emph{Syntax}:
6074 @code{RESULT = INT8(A)}
6076 @item @emph{Arguments}:
6077 @multitable @columnfractions .15 .70
6078 @item @var{A} @tab Shall be of type @code{INTEGER},
6079 @code{REAL}, or @code{COMPLEX}.
6082 @item @emph{Return value}:
6083 The return value is a @code{INTEGER(8)} variable.
6085 @item @emph{See also}:
6086 @ref{INT}, @ref{INT2}, @ref{LONG}
6092 @section @code{IOR} --- Bitwise logical or
6094 @cindex bitwise logical or
6095 @cindex logical or, bitwise
6098 @item @emph{Description}:
6099 @code{IOR} returns the bitwise boolean inclusive-OR of @var{I} and
6102 @item @emph{Standard}:
6103 Fortran 95 and later
6108 @item @emph{Syntax}:
6109 @code{RESULT = IOR(I, J)}
6111 @item @emph{Arguments}:
6112 @multitable @columnfractions .15 .70
6113 @item @var{I} @tab The type shall be @code{INTEGER}.
6114 @item @var{J} @tab The type shall be @code{INTEGER}, of the same
6115 kind as @var{I}. (As a GNU extension, different kinds are also
6119 @item @emph{Return value}:
6120 The return type is @code{INTEGER}, of the same kind as the
6121 arguments. (If the argument kinds differ, it is of the same kind as
6122 the larger argument.)
6124 @item @emph{See also}:
6125 @ref{IEOR}, @ref{IAND}, @ref{IBITS}, @ref{IBSET}, @ref{IBCLR}, @ref{NOT}
6131 @section @code{IRAND} --- Integer pseudo-random number
6133 @cindex random number generation
6136 @item @emph{Description}:
6137 @code{IRAND(FLAG)} returns a pseudo-random number from a uniform
6138 distribution between 0 and a system-dependent limit (which is in most
6139 cases 2147483647). If @var{FLAG} is 0, the next number
6140 in the current sequence is returned; if @var{FLAG} is 1, the generator
6141 is restarted by @code{CALL SRAND(0)}; if @var{FLAG} has any other value,
6142 it is used as a new seed with @code{SRAND}.
6144 This intrinsic routine is provided for backwards compatibility with
6145 GNU Fortran 77. It implements a simple modulo generator as provided
6146 by @command{g77}. For new code, one should consider the use of
6147 @ref{RANDOM_NUMBER} as it implements a superior algorithm.
6149 @item @emph{Standard}:
6155 @item @emph{Syntax}:
6156 @code{RESULT = IRAND(I)}
6158 @item @emph{Arguments}:
6159 @multitable @columnfractions .15 .70
6160 @item @var{I} @tab Shall be a scalar @code{INTEGER} of kind 4.
6163 @item @emph{Return value}:
6164 The return value is of @code{INTEGER(kind=4)} type.
6166 @item @emph{Example}:
6169 integer,parameter :: seed = 86456
6172 print *, irand(), irand(), irand(), irand()
6173 print *, irand(seed), irand(), irand(), irand()
6174 end program test_irand
6182 @section @code{IMAGE_INDEX} --- Function that converts a cosubscript to an image index
6183 @fnindex IMAGE_INDEX
6184 @cindex coarray, IMAGE_INDEX
6185 @cindex images, cosubscript to image index conversion
6188 @item @emph{Description}:
6189 Returns the image index belonging to a cosubscript.
6191 @item @emph{Standard}:
6192 Fortran 2008 and later
6197 @item @emph{Syntax}:
6198 @code{RESULT = IMAGE_INDEX(COARRAY, SUB)}
6200 @item @emph{Arguments}: None.
6201 @multitable @columnfractions .15 .70
6202 @item @var{COARRAY} @tab Coarray of any type.
6203 @item @var{SUB} @tab default integer rank-1 array of a size equal to
6204 the corank of @var{COARRAY}.
6208 @item @emph{Return value}:
6209 Scalar default integer with the value of the image index which corresponds
6210 to the cosubscripts. For invalid cosubscripts the result is zero.
6212 @item @emph{Example}:
6214 INTEGER :: array[2,-1:4,8,*]
6215 ! Writes 28 (or 0 if there are fewer than 28 images)
6216 WRITE (*,*) IMAGE_INDEX (array, [2,0,3,1])
6219 @item @emph{See also}:
6220 @ref{THIS_IMAGE}, @ref{NUM_IMAGES}
6226 @section @code{IS_IOSTAT_END} --- Test for end-of-file value
6227 @fnindex IS_IOSTAT_END
6228 @cindex IOSTAT, end of file
6231 @item @emph{Description}:
6232 @code{IS_IOSTAT_END} tests whether an variable has the value of the I/O
6233 status ``end of file''. The function is equivalent to comparing the variable
6234 with the @code{IOSTAT_END} parameter of the intrinsic module
6235 @code{ISO_FORTRAN_ENV}.
6237 @item @emph{Standard}:
6238 Fortran 2003 and later
6243 @item @emph{Syntax}:
6244 @code{RESULT = IS_IOSTAT_END(I)}
6246 @item @emph{Arguments}:
6247 @multitable @columnfractions .15 .70
6248 @item @var{I} @tab Shall be of the type @code{INTEGER}.
6251 @item @emph{Return value}:
6252 Returns a @code{LOGICAL} of the default kind, which @code{.TRUE.} if
6253 @var{I} has the value which indicates an end of file condition for
6254 IOSTAT= specifiers, and is @code{.FALSE.} otherwise.
6256 @item @emph{Example}:
6261 OPEN(88, FILE='test.dat')
6262 READ(88, *, IOSTAT=stat) i
6263 IF(IS_IOSTAT_END(stat)) STOP 'END OF FILE'
6271 @section @code{IS_IOSTAT_EOR} --- Test for end-of-record value
6272 @fnindex IS_IOSTAT_EOR
6273 @cindex IOSTAT, end of record
6276 @item @emph{Description}:
6277 @code{IS_IOSTAT_EOR} tests whether an variable has the value of the I/O
6278 status ``end of record''. The function is equivalent to comparing the
6279 variable with the @code{IOSTAT_EOR} parameter of the intrinsic module
6280 @code{ISO_FORTRAN_ENV}.
6282 @item @emph{Standard}:
6283 Fortran 2003 and later
6288 @item @emph{Syntax}:
6289 @code{RESULT = IS_IOSTAT_EOR(I)}
6291 @item @emph{Arguments}:
6292 @multitable @columnfractions .15 .70
6293 @item @var{I} @tab Shall be of the type @code{INTEGER}.
6296 @item @emph{Return value}:
6297 Returns a @code{LOGICAL} of the default kind, which @code{.TRUE.} if
6298 @var{I} has the value which indicates an end of file condition for
6299 IOSTAT= specifiers, and is @code{.FALSE.} otherwise.
6301 @item @emph{Example}:
6305 INTEGER :: stat, i(50)
6306 OPEN(88, FILE='test.dat', FORM='UNFORMATTED')
6307 READ(88, IOSTAT=stat) i
6308 IF(IS_IOSTAT_EOR(stat)) STOP 'END OF RECORD'
6316 @section @code{ISATTY} --- Whether a unit is a terminal device.
6318 @cindex system, terminal
6321 @item @emph{Description}:
6322 Determine whether a unit is connected to a terminal device.
6324 @item @emph{Standard}:
6330 @item @emph{Syntax}:
6331 @code{RESULT = ISATTY(UNIT)}
6333 @item @emph{Arguments}:
6334 @multitable @columnfractions .15 .70
6335 @item @var{UNIT} @tab Shall be a scalar @code{INTEGER}.
6338 @item @emph{Return value}:
6339 Returns @code{.TRUE.} if the @var{UNIT} is connected to a terminal
6340 device, @code{.FALSE.} otherwise.
6342 @item @emph{Example}:
6345 INTEGER(kind=1) :: unit
6347 write(*,*) isatty(unit=unit)
6351 @item @emph{See also}:
6358 @section @code{ISHFT} --- Shift bits
6363 @item @emph{Description}:
6364 @code{ISHFT} returns a value corresponding to @var{I} with all of the
6365 bits shifted @var{SHIFT} places. A value of @var{SHIFT} greater than
6366 zero corresponds to a left shift, a value of zero corresponds to no
6367 shift, and a value less than zero corresponds to a right shift. If the
6368 absolute value of @var{SHIFT} is greater than @code{BIT_SIZE(I)}, the
6369 value is undefined. Bits shifted out from the left end or right end are
6370 lost; zeros are shifted in from the opposite end.
6372 @item @emph{Standard}:
6373 Fortran 95 and later
6378 @item @emph{Syntax}:
6379 @code{RESULT = ISHFT(I, SHIFT)}
6381 @item @emph{Arguments}:
6382 @multitable @columnfractions .15 .70
6383 @item @var{I} @tab The type shall be @code{INTEGER}.
6384 @item @var{SHIFT} @tab The type shall be @code{INTEGER}.
6387 @item @emph{Return value}:
6388 The return value is of type @code{INTEGER} and of the same kind as
6391 @item @emph{See also}:
6398 @section @code{ISHFTC} --- Shift bits circularly
6400 @cindex bits, shift circular
6403 @item @emph{Description}:
6404 @code{ISHFTC} returns a value corresponding to @var{I} with the
6405 rightmost @var{SIZE} bits shifted circularly @var{SHIFT} places; that
6406 is, bits shifted out one end are shifted into the opposite end. A value
6407 of @var{SHIFT} greater than zero corresponds to a left shift, a value of
6408 zero corresponds to no shift, and a value less than zero corresponds to
6409 a right shift. The absolute value of @var{SHIFT} must be less than
6410 @var{SIZE}. If the @var{SIZE} argument is omitted, it is taken to be
6411 equivalent to @code{BIT_SIZE(I)}.
6413 @item @emph{Standard}:
6414 Fortran 95 and later
6419 @item @emph{Syntax}:
6420 @code{RESULT = ISHFTC(I, SHIFT [, SIZE])}
6422 @item @emph{Arguments}:
6423 @multitable @columnfractions .15 .70
6424 @item @var{I} @tab The type shall be @code{INTEGER}.
6425 @item @var{SHIFT} @tab The type shall be @code{INTEGER}.
6426 @item @var{SIZE} @tab (Optional) The type shall be @code{INTEGER};
6427 the value must be greater than zero and less than or equal to
6431 @item @emph{Return value}:
6432 The return value is of type @code{INTEGER} and of the same kind as
6435 @item @emph{See also}:
6442 @section @code{ISNAN} --- Test for a NaN
6447 @item @emph{Description}:
6448 @code{ISNAN} tests whether a floating-point value is an IEEE
6450 @item @emph{Standard}:
6456 @item @emph{Syntax}:
6459 @item @emph{Arguments}:
6460 @multitable @columnfractions .15 .70
6461 @item @var{X} @tab Variable of the type @code{REAL}.
6465 @item @emph{Return value}:
6466 Returns a default-kind @code{LOGICAL}. The returned value is @code{TRUE}
6467 if @var{X} is a NaN and @code{FALSE} otherwise.
6469 @item @emph{Example}:
6476 if (isnan(x)) stop '"x" is a NaN'
6477 end program test_nan
6484 @section @code{ITIME} --- Get current local time subroutine (hour/minutes/seconds)
6486 @cindex time, current
6487 @cindex current time
6490 @item @emph{Description}:
6491 @code{IDATE(VALUES)} Fills @var{VALUES} with the numerical values at the
6492 current local time. The hour (in the range 1-24), minute (in the range 1-60),
6493 and seconds (in the range 1-60) appear in elements 1, 2, and 3 of @var{VALUES},
6496 @item @emph{Standard}:
6502 @item @emph{Syntax}:
6503 @code{CALL ITIME(VALUES)}
6505 @item @emph{Arguments}:
6506 @multitable @columnfractions .15 .70
6507 @item @var{VALUES} @tab The type shall be @code{INTEGER, DIMENSION(3)}
6508 and the kind shall be the default integer kind.
6511 @item @emph{Return value}:
6512 Does not return anything.
6515 @item @emph{Example}:
6518 integer, dimension(3) :: tarray
6523 end program test_itime
6530 @section @code{KILL} --- Send a signal to a process
6534 @item @emph{Description}:
6535 @item @emph{Standard}:
6536 Sends the signal specified by @var{SIGNAL} to the process @var{PID}.
6539 This intrinsic is provided in both subroutine and function forms; however,
6540 only one form can be used in any given program unit.
6543 Subroutine, function
6545 @item @emph{Syntax}:
6546 @code{CALL KILL(C, VALUE [, STATUS])}
6548 @item @emph{Arguments}:
6549 @multitable @columnfractions .15 .70
6550 @item @var{C} @tab Shall be a scalar @code{INTEGER}, with
6552 @item @var{VALUE} @tab Shall be a scalar @code{INTEGER}, with
6554 @item @var{STATUS} @tab (Optional) status flag of type @code{INTEGER(4)} or
6555 @code{INTEGER(8)}. Returns 0 on success, or a system-specific error code
6559 @item @emph{See also}:
6560 @ref{ABORT}, @ref{EXIT}
6566 @section @code{KIND} --- Kind of an entity
6571 @item @emph{Description}:
6572 @code{KIND(X)} returns the kind value of the entity @var{X}.
6574 @item @emph{Standard}:
6575 Fortran 95 and later
6580 @item @emph{Syntax}:
6583 @item @emph{Arguments}:
6584 @multitable @columnfractions .15 .70
6585 @item @var{X} @tab Shall be of type @code{LOGICAL}, @code{INTEGER},
6586 @code{REAL}, @code{COMPLEX} or @code{CHARACTER}.
6589 @item @emph{Return value}:
6590 The return value is a scalar of type @code{INTEGER} and of the default
6593 @item @emph{Example}:
6596 integer,parameter :: kc = kind(' ')
6597 integer,parameter :: kl = kind(.true.)
6599 print *, "The default character kind is ", kc
6600 print *, "The default logical kind is ", kl
6601 end program test_kind
6609 @section @code{LBOUND} --- Lower dimension bounds of an array
6611 @cindex array, lower bound
6614 @item @emph{Description}:
6615 Returns the lower bounds of an array, or a single lower bound
6616 along the @var{DIM} dimension.
6617 @item @emph{Standard}:
6618 Fortran 95 and later, with @var{KIND} argument Fortran 2003 and later
6623 @item @emph{Syntax}:
6624 @code{RESULT = LBOUND(ARRAY [, DIM [, KIND]])}
6626 @item @emph{Arguments}:
6627 @multitable @columnfractions .15 .70
6628 @item @var{ARRAY} @tab Shall be an array, of any type.
6629 @item @var{DIM} @tab (Optional) Shall be a scalar @code{INTEGER}.
6630 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
6631 expression indicating the kind parameter of the result.
6634 @item @emph{Return value}:
6635 The return value is of type @code{INTEGER} and of kind @var{KIND}. If
6636 @var{KIND} is absent, the return value is of default integer kind.
6637 If @var{DIM} is absent, the result is an array of the lower bounds of
6638 @var{ARRAY}. If @var{DIM} is present, the result is a scalar
6639 corresponding to the lower bound of the array along that dimension. If
6640 @var{ARRAY} is an expression rather than a whole array or array
6641 structure component, or if it has a zero extent along the relevant
6642 dimension, the lower bound is taken to be 1.
6644 @item @emph{See also}:
6645 @ref{UBOUND}, @ref{LCOBOUND}
6651 @section @code{LCOBOUND} --- Lower codimension bounds of an array
6653 @cindex coarray, lower bound
6656 @item @emph{Description}:
6657 Returns the lower bounds of a coarray, or a single lower cobound
6658 along the @var{DIM} codimension.
6659 @item @emph{Standard}:
6660 Fortran 2008 and later
6665 @item @emph{Syntax}:
6666 @code{RESULT = LCOBOUND(COARRAY [, DIM [, KIND]])}
6668 @item @emph{Arguments}:
6669 @multitable @columnfractions .15 .70
6670 @item @var{ARRAY} @tab Shall be an coarray, of any type.
6671 @item @var{DIM} @tab (Optional) Shall be a scalar @code{INTEGER}.
6672 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
6673 expression indicating the kind parameter of the result.
6676 @item @emph{Return value}:
6677 The return value is of type @code{INTEGER} and of kind @var{KIND}. If
6678 @var{KIND} is absent, the return value is of default integer kind.
6679 If @var{DIM} is absent, the result is an array of the lower cobounds of
6680 @var{COARRAY}. If @var{DIM} is present, the result is a scalar
6681 corresponding to the lower cobound of the array along that codimension.
6683 @item @emph{See also}:
6684 @ref{UCOBOUND}, @ref{LBOUND}
6690 @section @code{LEADZ} --- Number of leading zero bits of an integer
6695 @item @emph{Description}:
6696 @code{LEADZ} returns the number of leading zero bits of an integer.
6698 @item @emph{Standard}:
6699 Fortran 2008 and later
6704 @item @emph{Syntax}:
6705 @code{RESULT = LEADZ(I)}
6707 @item @emph{Arguments}:
6708 @multitable @columnfractions .15 .70
6709 @item @var{I} @tab Shall be of type @code{INTEGER}.
6712 @item @emph{Return value}:
6713 The type of the return value is the default @code{INTEGER}.
6714 If all the bits of @code{I} are zero, the result value is @code{BIT_SIZE(I)}.
6716 @item @emph{Example}:
6719 WRITE (*,*) LEADZ(1) ! prints 8 if BITSIZE(I) has the value 32
6723 @item @emph{See also}:
6724 @ref{BIT_SIZE}, @ref{TRAILZ}, @ref{POPCNT}, @ref{POPPAR}
6730 @section @code{LEN} --- Length of a character entity
6732 @cindex string, length
6735 @item @emph{Description}:
6736 Returns the length of a character string. If @var{STRING} is an array,
6737 the length of an element of @var{STRING} is returned. Note that
6738 @var{STRING} need not be defined when this intrinsic is invoked, since
6739 only the length, not the content, of @var{STRING} is needed.
6741 @item @emph{Standard}:
6742 Fortran 77 and later, with @var{KIND} argument Fortran 2003 and later
6747 @item @emph{Syntax}:
6748 @code{L = LEN(STRING [, KIND])}
6750 @item @emph{Arguments}:
6751 @multitable @columnfractions .15 .70
6752 @item @var{STRING} @tab Shall be a scalar or array of type
6753 @code{CHARACTER}, with @code{INTENT(IN)}
6754 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
6755 expression indicating the kind parameter of the result.
6758 @item @emph{Return value}:
6759 The return value is of type @code{INTEGER} and of kind @var{KIND}. If
6760 @var{KIND} is absent, the return value is of default integer kind.
6763 @item @emph{Specific names}:
6764 @multitable @columnfractions .20 .20 .20 .25
6765 @item Name @tab Argument @tab Return type @tab Standard
6766 @item @code{LEN(STRING)} @tab @code{CHARACTER} @tab @code{INTEGER} @tab Fortran 77 and later
6770 @item @emph{See also}:
6771 @ref{LEN_TRIM}, @ref{ADJUSTL}, @ref{ADJUSTR}
6777 @section @code{LEN_TRIM} --- Length of a character entity without trailing blank characters
6779 @cindex string, length, without trailing whitespace
6782 @item @emph{Description}:
6783 Returns the length of a character string, ignoring any trailing blanks.
6785 @item @emph{Standard}:
6786 Fortran 95 and later, with @var{KIND} argument Fortran 2003 and later
6791 @item @emph{Syntax}:
6792 @code{RESULT = LEN_TRIM(STRING [, KIND])}
6794 @item @emph{Arguments}:
6795 @multitable @columnfractions .15 .70
6796 @item @var{STRING} @tab Shall be a scalar of type @code{CHARACTER},
6797 with @code{INTENT(IN)}
6798 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
6799 expression indicating the kind parameter of the result.
6802 @item @emph{Return value}:
6803 The return value is of type @code{INTEGER} and of kind @var{KIND}. If
6804 @var{KIND} is absent, the return value is of default integer kind.
6806 @item @emph{See also}:
6807 @ref{LEN}, @ref{ADJUSTL}, @ref{ADJUSTR}
6813 @section @code{LGE} --- Lexical greater than or equal
6815 @cindex lexical comparison of strings
6816 @cindex string, comparison
6819 @item @emph{Description}:
6820 Determines whether one string is lexically greater than or equal to
6821 another string, where the two strings are interpreted as containing
6822 ASCII character codes. If the String A and String B are not the same
6823 length, the shorter is compared as if spaces were appended to it to form
6824 a value that has the same length as the longer.
6826 In general, the lexical comparison intrinsics @code{LGE}, @code{LGT},
6827 @code{LLE}, and @code{LLT} differ from the corresponding intrinsic
6828 operators @code{.GE.}, @code{.GT.}, @code{.LE.}, and @code{.LT.}, in
6829 that the latter use the processor's character ordering (which is not
6830 ASCII on some targets), whereas the former always use the ASCII
6833 @item @emph{Standard}:
6834 Fortran 77 and later
6839 @item @emph{Syntax}:
6840 @code{RESULT = LGE(STRING_A, STRING_B)}
6842 @item @emph{Arguments}:
6843 @multitable @columnfractions .15 .70
6844 @item @var{STRING_A} @tab Shall be of default @code{CHARACTER} type.
6845 @item @var{STRING_B} @tab Shall be of default @code{CHARACTER} type.
6848 @item @emph{Return value}:
6849 Returns @code{.TRUE.} if @code{STRING_A >= STRING_B}, and @code{.FALSE.}
6850 otherwise, based on the ASCII ordering.
6852 @item @emph{Specific names}:
6853 @multitable @columnfractions .20 .20 .20 .25
6854 @item Name @tab Argument @tab Return type @tab Standard
6855 @item @code{LGE(STRING_A, STRING_B)} @tab @code{CHARACTER} @tab @code{LOGICAL} @tab Fortran 77 and later
6858 @item @emph{See also}:
6859 @ref{LGT}, @ref{LLE}, @ref{LLT}
6865 @section @code{LGT} --- Lexical greater than
6867 @cindex lexical comparison of strings
6868 @cindex string, comparison
6871 @item @emph{Description}:
6872 Determines whether one string is lexically greater than another string,
6873 where the two strings are interpreted as containing ASCII character
6874 codes. If the String A and String B are not the same length, the
6875 shorter is compared as if spaces were appended to it to form a value
6876 that has the same length as the longer.
6878 In general, the lexical comparison intrinsics @code{LGE}, @code{LGT},
6879 @code{LLE}, and @code{LLT} differ from the corresponding intrinsic
6880 operators @code{.GE.}, @code{.GT.}, @code{.LE.}, and @code{.LT.}, in
6881 that the latter use the processor's character ordering (which is not
6882 ASCII on some targets), whereas the former always use the ASCII
6885 @item @emph{Standard}:
6886 Fortran 77 and later
6891 @item @emph{Syntax}:
6892 @code{RESULT = LGT(STRING_A, STRING_B)}
6894 @item @emph{Arguments}:
6895 @multitable @columnfractions .15 .70
6896 @item @var{STRING_A} @tab Shall be of default @code{CHARACTER} type.
6897 @item @var{STRING_B} @tab Shall be of default @code{CHARACTER} type.
6900 @item @emph{Return value}:
6901 Returns @code{.TRUE.} if @code{STRING_A > STRING_B}, and @code{.FALSE.}
6902 otherwise, based on the ASCII ordering.
6904 @item @emph{Specific names}:
6905 @multitable @columnfractions .20 .20 .20 .25
6906 @item Name @tab Argument @tab Return type @tab Standard
6907 @item @code{LGT(STRING_A, STRING_B)} @tab @code{CHARACTER} @tab @code{LOGICAL} @tab Fortran 77 and later
6910 @item @emph{See also}:
6911 @ref{LGE}, @ref{LLE}, @ref{LLT}
6917 @section @code{LINK} --- Create a hard link
6919 @cindex file system, create link
6920 @cindex file system, hard link
6923 @item @emph{Description}:
6924 Makes a (hard) link from file @var{PATH1} to @var{PATH2}. A null
6925 character (@code{CHAR(0)}) can be used to mark the end of the names in
6926 @var{PATH1} and @var{PATH2}; otherwise, trailing blanks in the file
6927 names are ignored. If the @var{STATUS} argument is supplied, it
6928 contains 0 on success or a nonzero error code upon return; see
6931 This intrinsic is provided in both subroutine and function forms;
6932 however, only one form can be used in any given program unit.
6934 @item @emph{Standard}:
6938 Subroutine, function
6940 @item @emph{Syntax}:
6941 @multitable @columnfractions .80
6942 @item @code{CALL LINK(PATH1, PATH2 [, STATUS])}
6943 @item @code{STATUS = LINK(PATH1, PATH2)}
6946 @item @emph{Arguments}:
6947 @multitable @columnfractions .15 .70
6948 @item @var{PATH1} @tab Shall be of default @code{CHARACTER} type.
6949 @item @var{PATH2} @tab Shall be of default @code{CHARACTER} type.
6950 @item @var{STATUS} @tab (Optional) Shall be of default @code{INTEGER} type.
6953 @item @emph{See also}:
6954 @ref{SYMLNK}, @ref{UNLINK}
6960 @section @code{LLE} --- Lexical less than or equal
6962 @cindex lexical comparison of strings
6963 @cindex string, comparison
6966 @item @emph{Description}:
6967 Determines whether one string is lexically less than or equal to another
6968 string, where the two strings are interpreted as containing ASCII
6969 character codes. If the String A and String B are not the same length,
6970 the shorter is compared as if spaces were appended to it to form a value
6971 that has the same length as the longer.
6973 In general, the lexical comparison intrinsics @code{LGE}, @code{LGT},
6974 @code{LLE}, and @code{LLT} differ from the corresponding intrinsic
6975 operators @code{.GE.}, @code{.GT.}, @code{.LE.}, and @code{.LT.}, in
6976 that the latter use the processor's character ordering (which is not
6977 ASCII on some targets), whereas the former always use the ASCII
6980 @item @emph{Standard}:
6981 Fortran 77 and later
6986 @item @emph{Syntax}:
6987 @code{RESULT = LLE(STRING_A, STRING_B)}
6989 @item @emph{Arguments}:
6990 @multitable @columnfractions .15 .70
6991 @item @var{STRING_A} @tab Shall be of default @code{CHARACTER} type.
6992 @item @var{STRING_B} @tab Shall be of default @code{CHARACTER} type.
6995 @item @emph{Return value}:
6996 Returns @code{.TRUE.} if @code{STRING_A <= STRING_B}, and @code{.FALSE.}
6997 otherwise, based on the ASCII ordering.
6999 @item @emph{Specific names}:
7000 @multitable @columnfractions .20 .20 .20 .25
7001 @item Name @tab Argument @tab Return type @tab Standard
7002 @item @code{LLE(STRING_A, STRING_B)} @tab @code{CHARACTER} @tab @code{LOGICAL} @tab Fortran 77 and later
7005 @item @emph{See also}:
7006 @ref{LGE}, @ref{LGT}, @ref{LLT}
7012 @section @code{LLT} --- Lexical less than
7014 @cindex lexical comparison of strings
7015 @cindex string, comparison
7018 @item @emph{Description}:
7019 Determines whether one string is lexically less than another string,
7020 where the two strings are interpreted as containing ASCII character
7021 codes. If the String A and String B are not the same length, the
7022 shorter is compared as if spaces were appended to it to form a value
7023 that has the same length as the longer.
7025 In general, the lexical comparison intrinsics @code{LGE}, @code{LGT},
7026 @code{LLE}, and @code{LLT} differ from the corresponding intrinsic
7027 operators @code{.GE.}, @code{.GT.}, @code{.LE.}, and @code{.LT.}, in
7028 that the latter use the processor's character ordering (which is not
7029 ASCII on some targets), whereas the former always use the ASCII
7032 @item @emph{Standard}:
7033 Fortran 77 and later
7038 @item @emph{Syntax}:
7039 @code{RESULT = LLT(STRING_A, STRING_B)}
7041 @item @emph{Arguments}:
7042 @multitable @columnfractions .15 .70
7043 @item @var{STRING_A} @tab Shall be of default @code{CHARACTER} type.
7044 @item @var{STRING_B} @tab Shall be of default @code{CHARACTER} type.
7047 @item @emph{Return value}:
7048 Returns @code{.TRUE.} if @code{STRING_A < STRING_B}, and @code{.FALSE.}
7049 otherwise, based on the ASCII ordering.
7051 @item @emph{Specific names}:
7052 @multitable @columnfractions .20 .20 .20 .25
7053 @item Name @tab Argument @tab Return type @tab Standard
7054 @item @code{LLT(STRING_A, STRING_B)} @tab @code{CHARACTER} @tab @code{LOGICAL} @tab Fortran 77 and later
7057 @item @emph{See also}:
7058 @ref{LGE}, @ref{LGT}, @ref{LLE}
7064 @section @code{LNBLNK} --- Index of the last non-blank character in a string
7066 @cindex string, find non-blank character
7069 @item @emph{Description}:
7070 Returns the length of a character string, ignoring any trailing blanks.
7071 This is identical to the standard @code{LEN_TRIM} intrinsic, and is only
7072 included for backwards compatibility.
7074 @item @emph{Standard}:
7080 @item @emph{Syntax}:
7081 @code{RESULT = LNBLNK(STRING)}
7083 @item @emph{Arguments}:
7084 @multitable @columnfractions .15 .70
7085 @item @var{STRING} @tab Shall be a scalar of type @code{CHARACTER},
7086 with @code{INTENT(IN)}
7089 @item @emph{Return value}:
7090 The return value is of @code{INTEGER(kind=4)} type.
7092 @item @emph{See also}:
7093 @ref{INDEX intrinsic}, @ref{LEN_TRIM}
7099 @section @code{LOC} --- Returns the address of a variable
7101 @cindex location of a variable in memory
7104 @item @emph{Description}:
7105 @code{LOC(X)} returns the address of @var{X} as an integer.
7107 @item @emph{Standard}:
7113 @item @emph{Syntax}:
7114 @code{RESULT = LOC(X)}
7116 @item @emph{Arguments}:
7117 @multitable @columnfractions .15 .70
7118 @item @var{X} @tab Variable of any type.
7121 @item @emph{Return value}:
7122 The return value is of type @code{INTEGER}, with a @code{KIND}
7123 corresponding to the size (in bytes) of a memory address on the target
7126 @item @emph{Example}:
7133 end program test_loc
7140 @section @code{LOG} --- Logarithm function
7147 @cindex exponential function, inverse
7148 @cindex logarithmic function
7151 @item @emph{Description}:
7152 @code{LOG(X)} computes the logarithm of @var{X}.
7154 @item @emph{Standard}:
7155 Fortran 77 and later
7160 @item @emph{Syntax}:
7161 @code{RESULT = LOG(X)}
7163 @item @emph{Arguments}:
7164 @multitable @columnfractions .15 .70
7165 @item @var{X} @tab The type shall be @code{REAL} or
7169 @item @emph{Return value}:
7170 The return value is of type @code{REAL} or @code{COMPLEX}.
7171 The kind type parameter is the same as @var{X}.
7172 If @var{X} is @code{COMPLEX}, the imaginary part @math{\omega} is in the range
7173 @math{-\pi \leq \omega \leq \pi}.
7175 @item @emph{Example}:
7178 real(8) :: x = 1.0_8
7179 complex :: z = (1.0, 2.0)
7182 end program test_log
7185 @item @emph{Specific names}:
7186 @multitable @columnfractions .20 .20 .20 .25
7187 @item Name @tab Argument @tab Return type @tab Standard
7188 @item @code{ALOG(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab f95, gnu
7189 @item @code{DLOG(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab f95, gnu
7190 @item @code{CLOG(X)} @tab @code{COMPLEX(4) X} @tab @code{COMPLEX(4)} @tab f95, gnu
7191 @item @code{ZLOG(X)} @tab @code{COMPLEX(8) X} @tab @code{COMPLEX(8)} @tab f95, gnu
7192 @item @code{CDLOG(X)} @tab @code{COMPLEX(8) X} @tab @code{COMPLEX(8)} @tab f95, gnu
7199 @section @code{LOG10} --- Base 10 logarithm function
7203 @cindex exponential function, inverse
7204 @cindex logarithmic function
7207 @item @emph{Description}:
7208 @code{LOG10(X)} computes the base 10 logarithm of @var{X}.
7210 @item @emph{Standard}:
7211 Fortran 77 and later
7216 @item @emph{Syntax}:
7217 @code{RESULT = LOG10(X)}
7219 @item @emph{Arguments}:
7220 @multitable @columnfractions .15 .70
7221 @item @var{X} @tab The type shall be @code{REAL}.
7224 @item @emph{Return value}:
7225 The return value is of type @code{REAL} or @code{COMPLEX}.
7226 The kind type parameter is the same as @var{X}.
7228 @item @emph{Example}:
7231 real(8) :: x = 10.0_8
7233 end program test_log10
7236 @item @emph{Specific names}:
7237 @multitable @columnfractions .20 .20 .20 .25
7238 @item Name @tab Argument @tab Return type @tab Standard
7239 @item @code{ALOG10(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab Fortran 95 and later
7240 @item @code{DLOG10(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab Fortran 95 and later
7247 @section @code{LOG_GAMMA} --- Logarithm of the Gamma function
7252 @cindex Gamma function, logarithm of
7255 @item @emph{Description}:
7256 @code{LOG_GAMMA(X)} computes the natural logarithm of the absolute value
7257 of the Gamma (@math{\Gamma}) function.
7259 @item @emph{Standard}:
7260 Fortran 2008 and later
7265 @item @emph{Syntax}:
7266 @code{X = LOG_GAMMA(X)}
7268 @item @emph{Arguments}:
7269 @multitable @columnfractions .15 .70
7270 @item @var{X} @tab Shall be of type @code{REAL} and neither zero
7271 nor a negative integer.
7274 @item @emph{Return value}:
7275 The return value is of type @code{REAL} of the same kind as @var{X}.
7277 @item @emph{Example}:
7279 program test_log_gamma
7281 x = lgamma(x) ! returns 0.0
7282 end program test_log_gamma
7285 @item @emph{Specific names}:
7286 @multitable @columnfractions .20 .20 .20 .25
7287 @item Name @tab Argument @tab Return type @tab Standard
7288 @item @code{LGAMMA(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab GNU Extension
7289 @item @code{ALGAMA(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab GNU Extension
7290 @item @code{DLGAMA(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU Extension
7293 @item @emph{See also}:
7294 Gamma function: @ref{GAMMA}
7301 @section @code{LOGICAL} --- Convert to logical type
7303 @cindex conversion, to logical
7306 @item @emph{Description}:
7307 Converts one kind of @code{LOGICAL} variable to another.
7309 @item @emph{Standard}:
7310 Fortran 95 and later
7315 @item @emph{Syntax}:
7316 @code{RESULT = LOGICAL(L [, KIND])}
7318 @item @emph{Arguments}:
7319 @multitable @columnfractions .15 .70
7320 @item @var{L} @tab The type shall be @code{LOGICAL}.
7321 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
7322 expression indicating the kind parameter of the result.
7325 @item @emph{Return value}:
7326 The return value is a @code{LOGICAL} value equal to @var{L}, with a
7327 kind corresponding to @var{KIND}, or of the default logical kind if
7328 @var{KIND} is not given.
7330 @item @emph{See also}:
7331 @ref{INT}, @ref{REAL}, @ref{CMPLX}
7337 @section @code{LONG} --- Convert to integer type
7339 @cindex conversion, to integer
7342 @item @emph{Description}:
7343 Convert to a @code{KIND=4} integer type, which is the same size as a C
7344 @code{long} integer. This is equivalent to the standard @code{INT}
7345 intrinsic with an optional argument of @code{KIND=4}, and is only
7346 included for backwards compatibility.
7348 @item @emph{Standard}:
7354 @item @emph{Syntax}:
7355 @code{RESULT = LONG(A)}
7357 @item @emph{Arguments}:
7358 @multitable @columnfractions .15 .70
7359 @item @var{A} @tab Shall be of type @code{INTEGER},
7360 @code{REAL}, or @code{COMPLEX}.
7363 @item @emph{Return value}:
7364 The return value is a @code{INTEGER(4)} variable.
7366 @item @emph{See also}:
7367 @ref{INT}, @ref{INT2}, @ref{INT8}
7373 @section @code{LSHIFT} --- Left shift bits
7375 @cindex bits, shift left
7378 @item @emph{Description}:
7379 @code{LSHIFT} returns a value corresponding to @var{I} with all of the
7380 bits shifted left by @var{SHIFT} places. If the absolute value of
7381 @var{SHIFT} is greater than @code{BIT_SIZE(I)}, the value is undefined.
7382 Bits shifted out from the left end are lost; zeros are shifted in from
7385 This function has been superseded by the @code{ISHFT} intrinsic, which
7386 is standard in Fortran 95 and later.
7388 @item @emph{Standard}:
7394 @item @emph{Syntax}:
7395 @code{RESULT = LSHIFT(I, SHIFT)}
7397 @item @emph{Arguments}:
7398 @multitable @columnfractions .15 .70
7399 @item @var{I} @tab The type shall be @code{INTEGER}.
7400 @item @var{SHIFT} @tab The type shall be @code{INTEGER}.
7403 @item @emph{Return value}:
7404 The return value is of type @code{INTEGER} and of the same kind as
7407 @item @emph{See also}:
7408 @ref{ISHFT}, @ref{ISHFTC}, @ref{RSHIFT}
7415 @section @code{LSTAT} --- Get file status
7417 @cindex file system, file status
7420 @item @emph{Description}:
7421 @code{LSTAT} is identical to @ref{STAT}, except that if path is a
7422 symbolic link, then the link itself is statted, not the file that it
7425 The elements in @code{VALUES} are the same as described by @ref{STAT}.
7427 This intrinsic is provided in both subroutine and function forms;
7428 however, only one form can be used in any given program unit.
7430 @item @emph{Standard}:
7434 Subroutine, function
7436 @item @emph{Syntax}:
7437 @code{CALL LSTAT(NAME, VALUES [, STATUS])}
7439 @item @emph{Arguments}:
7440 @multitable @columnfractions .15 .70
7441 @item @var{NAME} @tab The type shall be @code{CHARACTER} of the default
7442 kind, a valid path within the file system.
7443 @item @var{VALUES} @tab The type shall be @code{INTEGER(4), DIMENSION(13)}.
7444 @item @var{STATUS} @tab (Optional) status flag of type @code{INTEGER(4)}.
7445 Returns 0 on success and a system specific error code otherwise.
7448 @item @emph{Example}:
7449 See @ref{STAT} for an example.
7451 @item @emph{See also}:
7452 To stat an open file: @ref{FSTAT}, to stat a file: @ref{STAT}
7458 @section @code{LTIME} --- Convert time to local time info
7460 @cindex time, conversion to local time info
7463 @item @emph{Description}:
7464 Given a system time value @var{TIME} (as provided by the @code{TIME8()}
7465 intrinsic), fills @var{VALUES} with values extracted from it appropriate
7466 to the local time zone using @code{localtime(3)}.
7468 @item @emph{Standard}:
7474 @item @emph{Syntax}:
7475 @code{CALL LTIME(TIME, VALUES)}
7477 @item @emph{Arguments}:
7478 @multitable @columnfractions .15 .70
7479 @item @var{TIME} @tab An @code{INTEGER} scalar expression
7480 corresponding to a system time, with @code{INTENT(IN)}.
7481 @item @var{VALUES} @tab A default @code{INTEGER} array with 9 elements,
7482 with @code{INTENT(OUT)}.
7485 @item @emph{Return value}:
7486 The elements of @var{VALUES} are assigned as follows:
7488 @item Seconds after the minute, range 0--59 or 0--61 to allow for leap
7490 @item Minutes after the hour, range 0--59
7491 @item Hours past midnight, range 0--23
7492 @item Day of month, range 0--31
7493 @item Number of months since January, range 0--12
7494 @item Years since 1900
7495 @item Number of days since Sunday, range 0--6
7496 @item Days since January 1
7497 @item Daylight savings indicator: positive if daylight savings is in
7498 effect, zero if not, and negative if the information is not available.
7501 @item @emph{See also}:
7502 @ref{CTIME}, @ref{GMTIME}, @ref{TIME}, @ref{TIME8}
7509 @section @code{MALLOC} --- Allocate dynamic memory
7511 @cindex pointer, cray
7514 @item @emph{Description}:
7515 @code{MALLOC(SIZE)} allocates @var{SIZE} bytes of dynamic memory and
7516 returns the address of the allocated memory. The @code{MALLOC} intrinsic
7517 is an extension intended to be used with Cray pointers, and is provided
7518 in GNU Fortran to allow the user to compile legacy code. For new code
7519 using Fortran 95 pointers, the memory allocation intrinsic is
7522 @item @emph{Standard}:
7528 @item @emph{Syntax}:
7529 @code{PTR = MALLOC(SIZE)}
7531 @item @emph{Arguments}:
7532 @multitable @columnfractions .15 .70
7533 @item @var{SIZE} @tab The type shall be @code{INTEGER}.
7536 @item @emph{Return value}:
7537 The return value is of type @code{INTEGER(K)}, with @var{K} such that
7538 variables of type @code{INTEGER(K)} have the same size as
7539 C pointers (@code{sizeof(void *)}).
7541 @item @emph{Example}:
7542 The following example demonstrates the use of @code{MALLOC} and
7543 @code{FREE} with Cray pointers.
7552 ptr_x = malloc(20*8)
7554 x(i) = sqrt(1.0d0 / i)
7562 end program test_malloc
7565 @item @emph{See also}:
7572 @section @code{MATMUL} --- matrix multiplication
7574 @cindex matrix multiplication
7575 @cindex product, matrix
7578 @item @emph{Description}:
7579 Performs a matrix multiplication on numeric or logical arguments.
7581 @item @emph{Standard}:
7582 Fortran 95 and later
7585 Transformational function
7587 @item @emph{Syntax}:
7588 @code{RESULT = MATMUL(MATRIX_A, MATRIX_B)}
7590 @item @emph{Arguments}:
7591 @multitable @columnfractions .15 .70
7592 @item @var{MATRIX_A} @tab An array of @code{INTEGER},
7593 @code{REAL}, @code{COMPLEX}, or @code{LOGICAL} type, with a rank of
7595 @item @var{MATRIX_B} @tab An array of @code{INTEGER},
7596 @code{REAL}, or @code{COMPLEX} type if @var{MATRIX_A} is of a numeric
7597 type; otherwise, an array of @code{LOGICAL} type. The rank shall be one
7598 or two, and the first (or only) dimension of @var{MATRIX_B} shall be
7599 equal to the last (or only) dimension of @var{MATRIX_A}.
7602 @item @emph{Return value}:
7603 The matrix product of @var{MATRIX_A} and @var{MATRIX_B}. The type and
7604 kind of the result follow the usual type and kind promotion rules, as
7605 for the @code{*} or @code{.AND.} operators.
7607 @item @emph{See also}:
7613 @section @code{MAX} --- Maximum value of an argument list
7620 @cindex maximum value
7623 @item @emph{Description}:
7624 Returns the argument with the largest (most positive) value.
7626 @item @emph{Standard}:
7627 Fortran 77 and later
7632 @item @emph{Syntax}:
7633 @code{RESULT = MAX(A1, A2 [, A3 [, ...]])}
7635 @item @emph{Arguments}:
7636 @multitable @columnfractions .15 .70
7637 @item @var{A1} @tab The type shall be @code{INTEGER} or
7639 @item @var{A2}, @var{A3}, ... @tab An expression of the same type and kind
7640 as @var{A1}. (As a GNU extension, arguments of different kinds are
7644 @item @emph{Return value}:
7645 The return value corresponds to the maximum value among the arguments,
7646 and has the same type and kind as the first argument.
7648 @item @emph{Specific names}:
7649 @multitable @columnfractions .20 .20 .20 .25
7650 @item Name @tab Argument @tab Return type @tab Standard
7651 @item @code{MAX0(A1)} @tab @code{INTEGER(4) A1} @tab @code{INTEGER(4)} @tab Fortran 77 and later
7652 @item @code{AMAX0(A1)} @tab @code{INTEGER(4) A1} @tab @code{REAL(MAX(X))} @tab Fortran 77 and later
7653 @item @code{MAX1(A1)} @tab @code{REAL A1} @tab @code{INT(MAX(X))} @tab Fortran 77 and later
7654 @item @code{AMAX1(A1)} @tab @code{REAL(4) A1} @tab @code{REAL(4)} @tab Fortran 77 and later
7655 @item @code{DMAX1(A1)} @tab @code{REAL(8) A1} @tab @code{REAL(8)} @tab Fortran 77 and later
7658 @item @emph{See also}:
7659 @ref{MAXLOC} @ref{MAXVAL}, @ref{MIN}
7666 @section @code{MAXEXPONENT} --- Maximum exponent of a real kind
7667 @fnindex MAXEXPONENT
7668 @cindex model representation, maximum exponent
7671 @item @emph{Description}:
7672 @code{MAXEXPONENT(X)} returns the maximum exponent in the model of the
7675 @item @emph{Standard}:
7676 Fortran 95 and later
7681 @item @emph{Syntax}:
7682 @code{RESULT = MAXEXPONENT(X)}
7684 @item @emph{Arguments}:
7685 @multitable @columnfractions .15 .70
7686 @item @var{X} @tab Shall be of type @code{REAL}.
7689 @item @emph{Return value}:
7690 The return value is of type @code{INTEGER} and of the default integer
7693 @item @emph{Example}:
7699 print *, minexponent(x), maxexponent(x)
7700 print *, minexponent(y), maxexponent(y)
7701 end program exponents
7708 @section @code{MAXLOC} --- Location of the maximum value within an array
7710 @cindex array, location of maximum element
7713 @item @emph{Description}:
7714 Determines the location of the element in the array with the maximum
7715 value, or, if the @var{DIM} argument is supplied, determines the
7716 locations of the maximum element along each row of the array in the
7717 @var{DIM} direction. If @var{MASK} is present, only the elements for
7718 which @var{MASK} is @code{.TRUE.} are considered. If more than one
7719 element in the array has the maximum value, the location returned is
7720 that of the first such element in array element order. If the array has
7721 zero size, or all of the elements of @var{MASK} are @code{.FALSE.}, then
7722 the result is an array of zeroes. Similarly, if @var{DIM} is supplied
7723 and all of the elements of @var{MASK} along a given row are zero, the
7724 result value for that row is zero.
7726 @item @emph{Standard}:
7727 Fortran 95 and later
7730 Transformational function
7732 @item @emph{Syntax}:
7733 @multitable @columnfractions .80
7734 @item @code{RESULT = MAXLOC(ARRAY, DIM [, MASK])}
7735 @item @code{RESULT = MAXLOC(ARRAY [, MASK])}
7738 @item @emph{Arguments}:
7739 @multitable @columnfractions .15 .70
7740 @item @var{ARRAY} @tab Shall be an array of type @code{INTEGER} or
7742 @item @var{DIM} @tab (Optional) Shall be a scalar of type
7743 @code{INTEGER}, with a value between one and the rank of @var{ARRAY},
7744 inclusive. It may not be an optional dummy argument.
7745 @item @var{MASK} @tab Shall be an array of type @code{LOGICAL},
7746 and conformable with @var{ARRAY}.
7749 @item @emph{Return value}:
7750 If @var{DIM} is absent, the result is a rank-one array with a length
7751 equal to the rank of @var{ARRAY}. If @var{DIM} is present, the result
7752 is an array with a rank one less than the rank of @var{ARRAY}, and a
7753 size corresponding to the size of @var{ARRAY} with the @var{DIM}
7754 dimension removed. If @var{DIM} is present and @var{ARRAY} has a rank
7755 of one, the result is a scalar. In all cases, the result is of default
7756 @code{INTEGER} type.
7758 @item @emph{See also}:
7759 @ref{MAX}, @ref{MAXVAL}
7766 @section @code{MAXVAL} --- Maximum value of an array
7768 @cindex array, maximum value
7769 @cindex maximum value
7772 @item @emph{Description}:
7773 Determines the maximum value of the elements in an array value, or, if
7774 the @var{DIM} argument is supplied, determines the maximum value along
7775 each row of the array in the @var{DIM} direction. If @var{MASK} is
7776 present, only the elements for which @var{MASK} is @code{.TRUE.} are
7777 considered. If the array has zero size, or all of the elements of
7778 @var{MASK} are @code{.FALSE.}, then the result is @code{-HUGE(ARRAY)}
7779 if @var{ARRAY} is numeric, or a string of nulls if @var{ARRAY} is of character
7782 @item @emph{Standard}:
7783 Fortran 95 and later
7786 Transformational function
7788 @item @emph{Syntax}:
7789 @multitable @columnfractions .80
7790 @item @code{RESULT = MAXVAL(ARRAY, DIM [, MASK])}
7791 @item @code{RESULT = MAXVAL(ARRAY [, MASK])}
7794 @item @emph{Arguments}:
7795 @multitable @columnfractions .15 .70
7796 @item @var{ARRAY} @tab Shall be an array of type @code{INTEGER} or
7798 @item @var{DIM} @tab (Optional) Shall be a scalar of type
7799 @code{INTEGER}, with a value between one and the rank of @var{ARRAY},
7800 inclusive. It may not be an optional dummy argument.
7801 @item @var{MASK} @tab Shall be an array of type @code{LOGICAL},
7802 and conformable with @var{ARRAY}.
7805 @item @emph{Return value}:
7806 If @var{DIM} is absent, or if @var{ARRAY} has a rank of one, the result
7807 is a scalar. If @var{DIM} is present, the result is an array with a
7808 rank one less than the rank of @var{ARRAY}, and a size corresponding to
7809 the size of @var{ARRAY} with the @var{DIM} dimension removed. In all
7810 cases, the result is of the same type and kind as @var{ARRAY}.
7812 @item @emph{See also}:
7813 @ref{MAX}, @ref{MAXLOC}
7819 @section @code{MCLOCK} --- Time function
7821 @cindex time, clock ticks
7825 @item @emph{Description}:
7826 Returns the number of clock ticks since the start of the process, based
7827 on the UNIX function @code{clock(3)}.
7829 This intrinsic is not fully portable, such as to systems with 32-bit
7830 @code{INTEGER} types but supporting times wider than 32 bits. Therefore,
7831 the values returned by this intrinsic might be, or become, negative, or
7832 numerically less than previous values, during a single run of the
7835 @item @emph{Standard}:
7841 @item @emph{Syntax}:
7842 @code{RESULT = MCLOCK()}
7844 @item @emph{Return value}:
7845 The return value is a scalar of type @code{INTEGER(4)}, equal to the
7846 number of clock ticks since the start of the process, or @code{-1} if
7847 the system does not support @code{clock(3)}.
7849 @item @emph{See also}:
7850 @ref{CTIME}, @ref{GMTIME}, @ref{LTIME}, @ref{MCLOCK}, @ref{TIME}
7857 @section @code{MCLOCK8} --- Time function (64-bit)
7859 @cindex time, clock ticks
7863 @item @emph{Description}:
7864 Returns the number of clock ticks since the start of the process, based
7865 on the UNIX function @code{clock(3)}.
7867 @emph{Warning:} this intrinsic does not increase the range of the timing
7868 values over that returned by @code{clock(3)}. On a system with a 32-bit
7869 @code{clock(3)}, @code{MCLOCK8()} will return a 32-bit value, even though
7870 it is converted to a 64-bit @code{INTEGER(8)} value. That means
7871 overflows of the 32-bit value can still occur. Therefore, the values
7872 returned by this intrinsic might be or become negative or numerically
7873 less than previous values during a single run of the compiled program.
7875 @item @emph{Standard}:
7881 @item @emph{Syntax}:
7882 @code{RESULT = MCLOCK8()}
7884 @item @emph{Return value}:
7885 The return value is a scalar of type @code{INTEGER(8)}, equal to the
7886 number of clock ticks since the start of the process, or @code{-1} if
7887 the system does not support @code{clock(3)}.
7889 @item @emph{See also}:
7890 @ref{CTIME}, @ref{GMTIME}, @ref{LTIME}, @ref{MCLOCK}, @ref{TIME8}
7897 @section @code{MERGE} --- Merge variables
7899 @cindex array, merge arrays
7900 @cindex array, combine arrays
7903 @item @emph{Description}:
7904 Select values from two arrays according to a logical mask. The result
7905 is equal to @var{TSOURCE} if @var{MASK} is @code{.TRUE.}, or equal to
7906 @var{FSOURCE} if it is @code{.FALSE.}.
7908 @item @emph{Standard}:
7909 Fortran 95 and later
7914 @item @emph{Syntax}:
7915 @code{RESULT = MERGE(TSOURCE, FSOURCE, MASK)}
7917 @item @emph{Arguments}:
7918 @multitable @columnfractions .15 .70
7919 @item @var{TSOURCE} @tab May be of any type.
7920 @item @var{FSOURCE} @tab Shall be of the same type and type parameters
7922 @item @var{MASK} @tab Shall be of type @code{LOGICAL}.
7925 @item @emph{Return value}:
7926 The result is of the same type and type parameters as @var{TSOURCE}.
7933 @section @code{MIN} --- Minimum value of an argument list
7940 @cindex minimum value
7943 @item @emph{Description}:
7944 Returns the argument with the smallest (most negative) value.
7946 @item @emph{Standard}:
7947 Fortran 77 and later
7952 @item @emph{Syntax}:
7953 @code{RESULT = MIN(A1, A2 [, A3, ...])}
7955 @item @emph{Arguments}:
7956 @multitable @columnfractions .15 .70
7957 @item @var{A1} @tab The type shall be @code{INTEGER} or
7959 @item @var{A2}, @var{A3}, ... @tab An expression of the same type and kind
7960 as @var{A1}. (As a GNU extension, arguments of different kinds are
7964 @item @emph{Return value}:
7965 The return value corresponds to the maximum value among the arguments,
7966 and has the same type and kind as the first argument.
7968 @item @emph{Specific names}:
7969 @multitable @columnfractions .20 .20 .20 .25
7970 @item Name @tab Argument @tab Return type @tab Standard
7971 @item @code{MIN0(A1)} @tab @code{INTEGER(4) A1} @tab @code{INTEGER(4)} @tab Fortran 77 and later
7972 @item @code{AMIN0(A1)} @tab @code{INTEGER(4) A1} @tab @code{REAL(4)} @tab Fortran 77 and later
7973 @item @code{MIN1(A1)} @tab @code{REAL A1} @tab @code{INTEGER(4)} @tab Fortran 77 and later
7974 @item @code{AMIN1(A1)} @tab @code{REAL(4) A1} @tab @code{REAL(4)} @tab Fortran 77 and later
7975 @item @code{DMIN1(A1)} @tab @code{REAL(8) A1} @tab @code{REAL(8)} @tab Fortran 77 and later
7978 @item @emph{See also}:
7979 @ref{MAX}, @ref{MINLOC}, @ref{MINVAL}
7985 @section @code{MINEXPONENT} --- Minimum exponent of a real kind
7986 @fnindex MINEXPONENT
7987 @cindex model representation, minimum exponent
7990 @item @emph{Description}:
7991 @code{MINEXPONENT(X)} returns the minimum exponent in the model of the
7994 @item @emph{Standard}:
7995 Fortran 95 and later
8000 @item @emph{Syntax}:
8001 @code{RESULT = MINEXPONENT(X)}
8003 @item @emph{Arguments}:
8004 @multitable @columnfractions .15 .70
8005 @item @var{X} @tab Shall be of type @code{REAL}.
8008 @item @emph{Return value}:
8009 The return value is of type @code{INTEGER} and of the default integer
8012 @item @emph{Example}:
8013 See @code{MAXEXPONENT} for an example.
8019 @section @code{MINLOC} --- Location of the minimum value within an array
8021 @cindex array, location of minimum element
8024 @item @emph{Description}:
8025 Determines the location of the element in the array with the minimum
8026 value, or, if the @var{DIM} argument is supplied, determines the
8027 locations of the minimum element along each row of the array in the
8028 @var{DIM} direction. If @var{MASK} is present, only the elements for
8029 which @var{MASK} is @code{.TRUE.} are considered. If more than one
8030 element in the array has the minimum value, the location returned is
8031 that of the first such element in array element order. If the array has
8032 zero size, or all of the elements of @var{MASK} are @code{.FALSE.}, then
8033 the result is an array of zeroes. Similarly, if @var{DIM} is supplied
8034 and all of the elements of @var{MASK} along a given row are zero, the
8035 result value for that row is zero.
8037 @item @emph{Standard}:
8038 Fortran 95 and later
8041 Transformational function
8043 @item @emph{Syntax}:
8044 @multitable @columnfractions .80
8045 @item @code{RESULT = MINLOC(ARRAY, DIM [, MASK])}
8046 @item @code{RESULT = MINLOC(ARRAY [, MASK])}
8049 @item @emph{Arguments}:
8050 @multitable @columnfractions .15 .70
8051 @item @var{ARRAY} @tab Shall be an array of type @code{INTEGER} or
8053 @item @var{DIM} @tab (Optional) Shall be a scalar of type
8054 @code{INTEGER}, with a value between one and the rank of @var{ARRAY},
8055 inclusive. It may not be an optional dummy argument.
8056 @item @var{MASK} @tab Shall be an array of type @code{LOGICAL},
8057 and conformable with @var{ARRAY}.
8060 @item @emph{Return value}:
8061 If @var{DIM} is absent, the result is a rank-one array with a length
8062 equal to the rank of @var{ARRAY}. If @var{DIM} is present, the result
8063 is an array with a rank one less than the rank of @var{ARRAY}, and a
8064 size corresponding to the size of @var{ARRAY} with the @var{DIM}
8065 dimension removed. If @var{DIM} is present and @var{ARRAY} has a rank
8066 of one, the result is a scalar. In all cases, the result is of default
8067 @code{INTEGER} type.
8069 @item @emph{See also}:
8070 @ref{MIN}, @ref{MINVAL}
8077 @section @code{MINVAL} --- Minimum value of an array
8079 @cindex array, minimum value
8080 @cindex minimum value
8083 @item @emph{Description}:
8084 Determines the minimum value of the elements in an array value, or, if
8085 the @var{DIM} argument is supplied, determines the minimum value along
8086 each row of the array in the @var{DIM} direction. If @var{MASK} is
8087 present, only the elements for which @var{MASK} is @code{.TRUE.} are
8088 considered. If the array has zero size, or all of the elements of
8089 @var{MASK} are @code{.FALSE.}, then the result is @code{HUGE(ARRAY)} if
8090 @var{ARRAY} is numeric, or a string of @code{CHAR(255)} characters if
8091 @var{ARRAY} is of character type.
8093 @item @emph{Standard}:
8094 Fortran 95 and later
8097 Transformational function
8099 @item @emph{Syntax}:
8100 @multitable @columnfractions .80
8101 @item @code{RESULT = MINVAL(ARRAY, DIM [, MASK])}
8102 @item @code{RESULT = MINVAL(ARRAY [, MASK])}
8105 @item @emph{Arguments}:
8106 @multitable @columnfractions .15 .70
8107 @item @var{ARRAY} @tab Shall be an array of type @code{INTEGER} or
8109 @item @var{DIM} @tab (Optional) Shall be a scalar of type
8110 @code{INTEGER}, with a value between one and the rank of @var{ARRAY},
8111 inclusive. It may not be an optional dummy argument.
8112 @item @var{MASK} @tab Shall be an array of type @code{LOGICAL},
8113 and conformable with @var{ARRAY}.
8116 @item @emph{Return value}:
8117 If @var{DIM} is absent, or if @var{ARRAY} has a rank of one, the result
8118 is a scalar. If @var{DIM} is present, the result is an array with a
8119 rank one less than the rank of @var{ARRAY}, and a size corresponding to
8120 the size of @var{ARRAY} with the @var{DIM} dimension removed. In all
8121 cases, the result is of the same type and kind as @var{ARRAY}.
8123 @item @emph{See also}:
8124 @ref{MIN}, @ref{MINLOC}
8131 @section @code{MOD} --- Remainder function
8136 @cindex division, remainder
8139 @item @emph{Description}:
8140 @code{MOD(A,P)} computes the remainder of the division of A by P@. It is
8141 calculated as @code{A - (INT(A/P) * P)}.
8143 @item @emph{Standard}:
8144 Fortran 77 and later
8149 @item @emph{Syntax}:
8150 @code{RESULT = MOD(A, P)}
8152 @item @emph{Arguments}:
8153 @multitable @columnfractions .15 .70
8154 @item @var{A} @tab Shall be a scalar of type @code{INTEGER} or @code{REAL}
8155 @item @var{P} @tab Shall be a scalar of the same type as @var{A} and not
8159 @item @emph{Return value}:
8160 The kind of the return value is the result of cross-promoting
8161 the kinds of the arguments.
8163 @item @emph{Example}:
8167 print *, mod(17.5,5.5)
8168 print *, mod(17.5d0,5.5)
8169 print *, mod(17.5,5.5d0)
8172 print *, mod(-17.5,5.5)
8173 print *, mod(-17.5d0,5.5)
8174 print *, mod(-17.5,5.5d0)
8177 print *, mod(17.5,-5.5)
8178 print *, mod(17.5d0,-5.5)
8179 print *, mod(17.5,-5.5d0)
8180 end program test_mod
8183 @item @emph{Specific names}:
8184 @multitable @columnfractions .20 .20 .20 .25
8185 @item Name @tab Arguments @tab Return type @tab Standard
8186 @item @code{MOD(A,P)} @tab @code{INTEGER A,P} @tab @code{INTEGER} @tab Fortran 95 and later
8187 @item @code{AMOD(A,P)} @tab @code{REAL(4) A,P} @tab @code{REAL(4)} @tab Fortran 95 and later
8188 @item @code{DMOD(A,P)} @tab @code{REAL(8) A,P} @tab @code{REAL(8)} @tab Fortran 95 and later
8195 @section @code{MODULO} --- Modulo function
8198 @cindex division, modulo
8201 @item @emph{Description}:
8202 @code{MODULO(A,P)} computes the @var{A} modulo @var{P}.
8204 @item @emph{Standard}:
8205 Fortran 95 and later
8210 @item @emph{Syntax}:
8211 @code{RESULT = MODULO(A, P)}
8213 @item @emph{Arguments}:
8214 @multitable @columnfractions .15 .70
8215 @item @var{A} @tab Shall be a scalar of type @code{INTEGER} or @code{REAL}
8216 @item @var{P} @tab Shall be a scalar of the same type and kind as @var{A}
8219 @item @emph{Return value}:
8220 The type and kind of the result are those of the arguments.
8222 @item If @var{A} and @var{P} are of type @code{INTEGER}:
8223 @code{MODULO(A,P)} has the value @var{R} such that @code{A=Q*P+R}, where
8224 @var{Q} is an integer and @var{R} is between 0 (inclusive) and @var{P}
8226 @item If @var{A} and @var{P} are of type @code{REAL}:
8227 @code{MODULO(A,P)} has the value of @code{A - FLOOR (A / P) * P}.
8229 In all cases, if @var{P} is zero the result is processor-dependent.
8231 @item @emph{Example}:
8234 print *, modulo(17,3)
8235 print *, modulo(17.5,5.5)
8237 print *, modulo(-17,3)
8238 print *, modulo(-17.5,5.5)
8240 print *, modulo(17,-3)
8241 print *, modulo(17.5,-5.5)
8250 @section @code{MOVE_ALLOC} --- Move allocation from one object to another
8252 @cindex moving allocation
8253 @cindex allocation, moving
8256 @item @emph{Description}:
8257 @code{MOVE_ALLOC(FROM, TO)} moves the allocation from @var{FROM} to
8258 @var{TO}. @var{FROM} will become deallocated in the process.
8260 @item @emph{Standard}:
8261 Fortran 2003 and later
8266 @item @emph{Syntax}:
8267 @code{CALL MOVE_ALLOC(FROM, TO)}
8269 @item @emph{Arguments}:
8270 @multitable @columnfractions .15 .70
8271 @item @var{FROM} @tab @code{ALLOCATABLE}, @code{INTENT(INOUT)}, may be
8272 of any type and kind.
8273 @item @var{TO} @tab @code{ALLOCATABLE}, @code{INTENT(OUT)}, shall be
8274 of the same type, kind and rank as @var{FROM}.
8277 @item @emph{Return value}:
8280 @item @emph{Example}:
8282 program test_move_alloc
8283 integer, allocatable :: a(:), b(:)
8287 call move_alloc(a, b)
8288 print *, allocated(a), allocated(b)
8290 end program test_move_alloc
8297 @section @code{MVBITS} --- Move bits from one integer to another
8302 @item @emph{Description}:
8303 Moves @var{LEN} bits from positions @var{FROMPOS} through
8304 @code{FROMPOS+LEN-1} of @var{FROM} to positions @var{TOPOS} through
8305 @code{TOPOS+LEN-1} of @var{TO}. The portion of argument @var{TO} not
8306 affected by the movement of bits is unchanged. The values of
8307 @code{FROMPOS+LEN-1} and @code{TOPOS+LEN-1} must be less than
8308 @code{BIT_SIZE(FROM)}.
8310 @item @emph{Standard}:
8311 Fortran 95 and later
8314 Elemental subroutine
8316 @item @emph{Syntax}:
8317 @code{CALL MVBITS(FROM, FROMPOS, LEN, TO, TOPOS)}
8319 @item @emph{Arguments}:
8320 @multitable @columnfractions .15 .70
8321 @item @var{FROM} @tab The type shall be @code{INTEGER}.
8322 @item @var{FROMPOS} @tab The type shall be @code{INTEGER}.
8323 @item @var{LEN} @tab The type shall be @code{INTEGER}.
8324 @item @var{TO} @tab The type shall be @code{INTEGER}, of the
8325 same kind as @var{FROM}.
8326 @item @var{TOPOS} @tab The type shall be @code{INTEGER}.
8329 @item @emph{See also}:
8330 @ref{IBCLR}, @ref{IBSET}, @ref{IBITS}, @ref{IAND}, @ref{IOR}, @ref{IEOR}
8336 @section @code{NEAREST} --- Nearest representable number
8338 @cindex real number, nearest different
8339 @cindex floating point, nearest different
8342 @item @emph{Description}:
8343 @code{NEAREST(X, S)} returns the processor-representable number nearest
8344 to @code{X} in the direction indicated by the sign of @code{S}.
8346 @item @emph{Standard}:
8347 Fortran 95 and later
8352 @item @emph{Syntax}:
8353 @code{RESULT = NEAREST(X, S)}
8355 @item @emph{Arguments}:
8356 @multitable @columnfractions .15 .70
8357 @item @var{X} @tab Shall be of type @code{REAL}.
8358 @item @var{S} @tab (Optional) shall be of type @code{REAL} and
8362 @item @emph{Return value}:
8363 The return value is of the same type as @code{X}. If @code{S} is
8364 positive, @code{NEAREST} returns the processor-representable number
8365 greater than @code{X} and nearest to it. If @code{S} is negative,
8366 @code{NEAREST} returns the processor-representable number smaller than
8367 @code{X} and nearest to it.
8369 @item @emph{Example}:
8371 program test_nearest
8373 x = nearest(42.0, 1.0)
8374 y = nearest(42.0, -1.0)
8375 write (*,"(3(G20.15))") x, y, x - y
8376 end program test_nearest
8383 @section @code{NEW_LINE} --- New line character
8386 @cindex output, newline
8389 @item @emph{Description}:
8390 @code{NEW_LINE(C)} returns the new-line character.
8392 @item @emph{Standard}:
8393 Fortran 2003 and later
8398 @item @emph{Syntax}:
8399 @code{RESULT = NEW_LINE(C)}
8401 @item @emph{Arguments}:
8402 @multitable @columnfractions .15 .70
8403 @item @var{C} @tab The argument shall be a scalar or array of the
8404 type @code{CHARACTER}.
8407 @item @emph{Return value}:
8408 Returns a @var{CHARACTER} scalar of length one with the new-line character of
8409 the same kind as parameter @var{C}.
8411 @item @emph{Example}:
8415 write(*,'(A)') 'This is record 1.'//NEW_LINE('A')//'This is record 2.'
8423 @section @code{NINT} --- Nearest whole number
8426 @cindex rounding, nearest whole number
8429 @item @emph{Description}:
8430 @code{NINT(A)} rounds its argument to the nearest whole number.
8432 @item @emph{Standard}:
8433 Fortran 77 and later, with @var{KIND} argument Fortran 90 and later
8438 @item @emph{Syntax}:
8439 @code{RESULT = NINT(A [, KIND])}
8441 @item @emph{Arguments}:
8442 @multitable @columnfractions .15 .70
8443 @item @var{A} @tab The type of the argument shall be @code{REAL}.
8444 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
8445 expression indicating the kind parameter of the result.
8448 @item @emph{Return value}:
8449 Returns @var{A} with the fractional portion of its magnitude eliminated by
8450 rounding to the nearest whole number and with its sign preserved,
8451 converted to an @code{INTEGER} of the default kind.
8453 @item @emph{Example}:
8460 print *, nint(x4), idnint(x8)
8461 end program test_nint
8464 @item @emph{Specific names}:
8465 @multitable @columnfractions .20 .20 .20 .25
8466 @item Name @tab Argument @tab Return Type @tab Standard
8467 @item @code{NINT(A)} @tab @code{REAL(4) A} @tab @code{INTEGER} @tab Fortran 95 and later
8468 @item @code{IDNINT(A)} @tab @code{REAL(8) A} @tab @code{INTEGER} @tab Fortran 95 and later
8471 @item @emph{See also}:
8472 @ref{CEILING}, @ref{FLOOR}
8479 @section @code{NORM2} --- Euclidean vector norms
8481 @cindex Euclidean vector norm
8482 @cindex L2 vector norm
8483 @cindex norm, Euclidean
8486 @item @emph{Description}:
8487 Calculates the Euclidean vector norm (@math{L_2}) norm of
8488 of @var{ARRAY} along dimension @var{DIM}.
8490 @item @emph{Standard}:
8491 Fortran 2008 and later
8494 Transformational function
8496 @item @emph{Syntax}:
8497 @multitable @columnfractions .80
8498 @item @code{RESULT = NORM2(ARRAY[, DIM])}
8501 @item @emph{Arguments}:
8502 @multitable @columnfractions .15 .70
8503 @item @var{ARRAY} @tab Shall be an array of type @code{REAL}
8504 @item @var{DIM} @tab (Optional) shall be a scalar of type
8505 @code{INTEGER} with a value in the range from 1 to n, where n
8506 equals the rank of @var{ARRAY}.
8509 @item @emph{Return value}:
8510 The result is of the same type as @var{ARRAY}.
8512 If @var{DIM} is absent, a scalar with the square root of the sum of all
8513 elements in @var{ARRAY} squared is returned. Otherwise, an array of
8514 rank @math{n-1}, where @math{n} equals the rank of @var{ARRAY}, and a
8515 shape similar to that of @var{ARRAY} with dimension @var{DIM} dropped
8518 @item @emph{Example}:
8521 REAL :: x(5) = [ real :: 1, 2, 3, 4, 5 ]
8522 print *, NORM2(x) ! = sqrt(55.) ~ 7.416
8530 @section @code{NOT} --- Logical negation
8532 @cindex bits, negate
8533 @cindex bitwise logical not
8534 @cindex logical not, bitwise
8537 @item @emph{Description}:
8538 @code{NOT} returns the bitwise boolean inverse of @var{I}.
8540 @item @emph{Standard}:
8541 Fortran 95 and later
8546 @item @emph{Syntax}:
8547 @code{RESULT = NOT(I)}
8549 @item @emph{Arguments}:
8550 @multitable @columnfractions .15 .70
8551 @item @var{I} @tab The type shall be @code{INTEGER}.
8554 @item @emph{Return value}:
8555 The return type is @code{INTEGER}, of the same kind as the
8558 @item @emph{See also}:
8559 @ref{IAND}, @ref{IEOR}, @ref{IOR}, @ref{IBITS}, @ref{IBSET}, @ref{IBCLR}
8566 @section @code{NULL} --- Function that returns an disassociated pointer
8568 @cindex pointer, status
8569 @cindex pointer, disassociated
8572 @item @emph{Description}:
8573 Returns a disassociated pointer.
8575 If @var{MOLD} is present, a dissassociated pointer of the same type is
8576 returned, otherwise the type is determined by context.
8578 In Fortran 95, @var{MOLD} is optional. Please note that Fortran 2003
8579 includes cases where it is required.
8581 @item @emph{Standard}:
8582 Fortran 95 and later
8585 Transformational function
8587 @item @emph{Syntax}:
8588 @code{PTR => NULL([MOLD])}
8590 @item @emph{Arguments}:
8591 @multitable @columnfractions .15 .70
8592 @item @var{MOLD} @tab (Optional) shall be a pointer of any association
8593 status and of any type.
8596 @item @emph{Return value}:
8597 A disassociated pointer.
8599 @item @emph{Example}:
8601 REAL, POINTER, DIMENSION(:) :: VEC => NULL ()
8604 @item @emph{See also}:
8611 @section @code{NUM_IMAGES} --- Function that returns the number of images
8613 @cindex coarray, NUM_IMAGES
8614 @cindex images, number of
8617 @item @emph{Description}:
8618 Returns the number of images.
8620 @item @emph{Standard}:
8621 Fortran 2008 and later
8624 Transformational function
8626 @item @emph{Syntax}:
8627 @code{RESULT = NUM_IMAGES()}
8629 @item @emph{Arguments}: None.
8631 @item @emph{Return value}:
8632 Scalar default-kind integer.
8634 @item @emph{Example}:
8638 value = THIS_IMAGE()
8640 IF (THIS_IMAGE() == 1) THEN
8641 DO i = 1, NUM_IMAGES()
8642 WRITE(*,'(2(a,i0))') 'value[', i, '] is ', value[i]
8647 @item @emph{See also}:
8648 @ref{THIS_IMAGE}, @ref{IMAGE_INDEX}
8654 @section @code{OR} --- Bitwise logical OR
8656 @cindex bitwise logical or
8657 @cindex logical or, bitwise
8660 @item @emph{Description}:
8661 Bitwise logical @code{OR}.
8663 This intrinsic routine is provided for backwards compatibility with
8664 GNU Fortran 77. For integer arguments, programmers should consider
8665 the use of the @ref{IOR} intrinsic defined by the Fortran standard.
8667 @item @emph{Standard}:
8673 @item @emph{Syntax}:
8674 @code{RESULT = OR(I, J)}
8676 @item @emph{Arguments}:
8677 @multitable @columnfractions .15 .70
8678 @item @var{I} @tab The type shall be either a scalar @code{INTEGER}
8679 type or a scalar @code{LOGICAL} type.
8680 @item @var{J} @tab The type shall be the same as the type of @var{J}.
8683 @item @emph{Return value}:
8684 The return type is either a scalar @code{INTEGER} or a scalar
8685 @code{LOGICAL}. If the kind type parameters differ, then the
8686 smaller kind type is implicitly converted to larger kind, and the
8687 return has the larger kind.
8689 @item @emph{Example}:
8692 LOGICAL :: T = .TRUE., F = .FALSE.
8694 DATA a / Z'F' /, b / Z'3' /
8696 WRITE (*,*) OR(T, T), OR(T, F), OR(F, T), OR(F, F)
8697 WRITE (*,*) OR(a, b)
8701 @item @emph{See also}:
8702 Fortran 95 elemental function: @ref{IOR}
8708 @section @code{PACK} --- Pack an array into an array of rank one
8710 @cindex array, packing
8711 @cindex array, reduce dimension
8712 @cindex array, gather elements
8715 @item @emph{Description}:
8716 Stores the elements of @var{ARRAY} in an array of rank one.
8718 The beginning of the resulting array is made up of elements whose @var{MASK}
8719 equals @code{TRUE}. Afterwards, positions are filled with elements taken from
8722 @item @emph{Standard}:
8723 Fortran 95 and later
8726 Transformational function
8728 @item @emph{Syntax}:
8729 @code{RESULT = PACK(ARRAY, MASK[,VECTOR]}
8731 @item @emph{Arguments}:
8732 @multitable @columnfractions .15 .70
8733 @item @var{ARRAY} @tab Shall be an array of any type.
8734 @item @var{MASK} @tab Shall be an array of type @code{LOGICAL} and
8735 of the same size as @var{ARRAY}. Alternatively, it may be a @code{LOGICAL}
8737 @item @var{VECTOR} @tab (Optional) shall be an array of the same type
8738 as @var{ARRAY} and of rank one. If present, the number of elements in
8739 @var{VECTOR} shall be equal to or greater than the number of true elements
8740 in @var{MASK}. If @var{MASK} is scalar, the number of elements in
8741 @var{VECTOR} shall be equal to or greater than the number of elements in
8745 @item @emph{Return value}:
8746 The result is an array of rank one and the same type as that of @var{ARRAY}.
8747 If @var{VECTOR} is present, the result size is that of @var{VECTOR}, the
8748 number of @code{TRUE} values in @var{MASK} otherwise.
8750 @item @emph{Example}:
8751 Gathering nonzero elements from an array:
8755 m = (/ 1, 0, 0, 0, 5, 0 /)
8756 WRITE(*, FMT="(6(I0, ' '))") pack(m, m /= 0) ! "1 5"
8760 Gathering nonzero elements from an array and appending elements from @var{VECTOR}:
8764 m = (/ 1, 0, 0, 2 /)
8765 WRITE(*, FMT="(4(I0, ' '))") pack(m, m /= 0, (/ 0, 0, 3, 4 /)) ! "1 2 3 4"
8769 @item @emph{See also}:
8776 @section @code{PARITY} --- Reduction with exclusive OR
8779 @cindex Reduction, XOR
8780 @cindex XOR reduction
8783 @item @emph{Description}:
8784 Calculates the partity, i.e. the reduction using @code{.XOR.},
8785 of @var{MASK} along dimension @var{DIM}.
8787 @item @emph{Standard}:
8788 Fortran 2008 and later
8791 Transformational function
8793 @item @emph{Syntax}:
8794 @multitable @columnfractions .80
8795 @item @code{RESULT = PARITY(MASK[, DIM])}
8798 @item @emph{Arguments}:
8799 @multitable @columnfractions .15 .70
8800 @item @var{LOGICAL} @tab Shall be an array of type @code{LOGICAL}
8801 @item @var{DIM} @tab (Optional) shall be a scalar of type
8802 @code{INTEGER} with a value in the range from 1 to n, where n
8803 equals the rank of @var{MASK}.
8806 @item @emph{Return value}:
8807 The result is of the same type as @var{MASK}.
8809 If @var{DIM} is absent, a scalar with the parity of all elements in
8810 @var{MASK} is returned, i.e. true if an odd number of elements is
8811 @code{.true.} and false otherwise. If @var{DIM} is present, an array
8812 of rank @math{n-1}, where @math{n} equals the rank of @var{ARRAY},
8813 and a shape similar to that of @var{MASK} with dimension @var{DIM}
8814 dropped is returned.
8816 @item @emph{Example}:
8819 LOGICAL :: x(2) = [ .true., .false. ]
8820 print *, PARITY(x) ! prints "T" (true).
8828 @section @code{PERROR} --- Print system error message
8830 @cindex system, error handling
8833 @item @emph{Description}:
8834 Prints (on the C @code{stderr} stream) a newline-terminated error
8835 message corresponding to the last system error. This is prefixed by
8836 @var{STRING}, a colon and a space. See @code{perror(3)}.
8838 @item @emph{Standard}:
8844 @item @emph{Syntax}:
8845 @code{CALL PERROR(STRING)}
8847 @item @emph{Arguments}:
8848 @multitable @columnfractions .15 .70
8849 @item @var{STRING} @tab A scalar of type @code{CHARACTER} and of the
8853 @item @emph{See also}:
8860 @section @code{PRECISION} --- Decimal precision of a real kind
8862 @cindex model representation, precision
8865 @item @emph{Description}:
8866 @code{PRECISION(X)} returns the decimal precision in the model of the
8869 @item @emph{Standard}:
8870 Fortran 95 and later
8875 @item @emph{Syntax}:
8876 @code{RESULT = PRECISION(X)}
8878 @item @emph{Arguments}:
8879 @multitable @columnfractions .15 .70
8880 @item @var{X} @tab Shall be of type @code{REAL} or @code{COMPLEX}.
8883 @item @emph{Return value}:
8884 The return value is of type @code{INTEGER} and of the default integer
8887 @item @emph{See also}:
8888 @ref{SELECTED_REAL_KIND}, @ref{RANGE}
8890 @item @emph{Example}:
8892 program prec_and_range
8893 real(kind=4) :: x(2)
8894 complex(kind=8) :: y
8896 print *, precision(x), range(x)
8897 print *, precision(y), range(y)
8898 end program prec_and_range
8905 @section @code{POPCNT} --- Number of bits set
8907 @cindex binary representation
8911 @item @emph{Description}:
8912 @code{POPCNT(I)} returns the number of bits set ('1' bits) in the binary
8913 representation of @code{I}.
8915 @item @emph{Standard}:
8916 Fortran 2008 and later
8921 @item @emph{Syntax}:
8922 @code{RESULT = POPCNT(I)}
8924 @item @emph{Arguments}:
8925 @multitable @columnfractions .15 .70
8926 @item @var{I} @tab Shall be of type @code{INTEGER}.
8929 @item @emph{Return value}:
8930 The return value is of type @code{INTEGER} and of the default integer
8933 @item @emph{See also}:
8934 @ref{POPPAR}, @ref{LEADZ}, @ref{TRAILZ}
8936 @item @emph{Example}:
8938 program test_population
8939 print *, popcnt(127), poppar(127)
8940 print *, popcnt(huge(0_4)), poppar(huge(0_4))
8941 print *, popcnt(huge(0_8)), poppar(huge(0_8))
8942 end program test_population
8948 @section @code{POPPAR} --- Parity of the number of bits set
8950 @cindex binary representation
8954 @item @emph{Description}:
8955 @code{POPPAR(I)} returns parity of the integer @code{I}, i.e. the parity
8956 of the number of bits set ('1' bits) in the binary representation of
8957 @code{I}. It is equal to 0 if @code{I} has an even number of bits set,
8958 and 1 for an odd number of '1' bits.
8960 @item @emph{Standard}:
8961 Fortran 2008 and later
8966 @item @emph{Syntax}:
8967 @code{RESULT = POPPAR(I)}
8969 @item @emph{Arguments}:
8970 @multitable @columnfractions .15 .70
8971 @item @var{I} @tab Shall be of type @code{INTEGER}.
8974 @item @emph{Return value}:
8975 The return value is of type @code{INTEGER} and of the default integer
8978 @item @emph{See also}:
8979 @ref{POPCNT}, @ref{LEADZ}, @ref{TRAILZ}
8981 @item @emph{Example}:
8983 program test_population
8984 print *, popcnt(127), poppar(127)
8985 print *, popcnt(huge(0_4)), poppar(huge(0_4))
8986 print *, popcnt(huge(0_8)), poppar(huge(0_8))
8987 end program test_population
8994 @section @code{PRESENT} --- Determine whether an optional dummy argument is specified
8998 @item @emph{Description}:
8999 Determines whether an optional dummy argument is present.
9001 @item @emph{Standard}:
9002 Fortran 95 and later
9007 @item @emph{Syntax}:
9008 @code{RESULT = PRESENT(A)}
9010 @item @emph{Arguments}:
9011 @multitable @columnfractions .15 .70
9012 @item @var{A} @tab May be of any type and may be a pointer, scalar or array
9013 value, or a dummy procedure. It shall be the name of an optional dummy argument
9014 accessible within the current subroutine or function.
9017 @item @emph{Return value}:
9018 Returns either @code{TRUE} if the optional argument @var{A} is present, or
9019 @code{FALSE} otherwise.
9021 @item @emph{Example}:
9023 PROGRAM test_present
9024 WRITE(*,*) f(), f(42) ! "F T"
9026 LOGICAL FUNCTION f(x)
9027 INTEGER, INTENT(IN), OPTIONAL :: x
9037 @section @code{PRODUCT} --- Product of array elements
9039 @cindex array, product
9040 @cindex array, multiply elements
9041 @cindex array, conditionally multiply elements
9042 @cindex multiply array elements
9045 @item @emph{Description}:
9046 Multiplies the elements of @var{ARRAY} along dimension @var{DIM} if
9047 the corresponding element in @var{MASK} is @code{TRUE}.
9049 @item @emph{Standard}:
9050 Fortran 95 and later
9053 Transformational function
9055 @item @emph{Syntax}:
9056 @multitable @columnfractions .80
9057 @item @code{RESULT = PRODUCT(ARRAY[, MASK])}
9058 @item @code{RESULT = PRODUCT(ARRAY, DIM[, MASK])}
9061 @item @emph{Arguments}:
9062 @multitable @columnfractions .15 .70
9063 @item @var{ARRAY} @tab Shall be an array of type @code{INTEGER},
9064 @code{REAL} or @code{COMPLEX}.
9065 @item @var{DIM} @tab (Optional) shall be a scalar of type
9066 @code{INTEGER} with a value in the range from 1 to n, where n
9067 equals the rank of @var{ARRAY}.
9068 @item @var{MASK} @tab (Optional) shall be of type @code{LOGICAL}
9069 and either be a scalar or an array of the same shape as @var{ARRAY}.
9072 @item @emph{Return value}:
9073 The result is of the same type as @var{ARRAY}.
9075 If @var{DIM} is absent, a scalar with the product of all elements in
9076 @var{ARRAY} is returned. Otherwise, an array of rank n-1, where n equals
9077 the rank of @var{ARRAY}, and a shape similar to that of @var{ARRAY} with
9078 dimension @var{DIM} dropped is returned.
9081 @item @emph{Example}:
9083 PROGRAM test_product
9084 INTEGER :: x(5) = (/ 1, 2, 3, 4 ,5 /)
9085 print *, PRODUCT(x) ! all elements, product = 120
9086 print *, PRODUCT(x, MASK=MOD(x, 2)==1) ! odd elements, product = 15
9090 @item @emph{See also}:
9097 @section @code{RADIX} --- Base of a model number
9099 @cindex model representation, base
9100 @cindex model representation, radix
9103 @item @emph{Description}:
9104 @code{RADIX(X)} returns the base of the model representing the entity @var{X}.
9106 @item @emph{Standard}:
9107 Fortran 95 and later
9112 @item @emph{Syntax}:
9113 @code{RESULT = RADIX(X)}
9115 @item @emph{Arguments}:
9116 @multitable @columnfractions .15 .70
9117 @item @var{X} @tab Shall be of type @code{INTEGER} or @code{REAL}
9120 @item @emph{Return value}:
9121 The return value is a scalar of type @code{INTEGER} and of the default
9124 @item @emph{See also}:
9125 @ref{SELECTED_REAL_KIND}
9127 @item @emph{Example}:
9130 print *, "The radix for the default integer kind is", radix(0)
9131 print *, "The radix for the default real kind is", radix(0.0)
9132 end program test_radix
9140 @section @code{RAN} --- Real pseudo-random number
9142 @cindex random number generation
9145 @item @emph{Description}:
9146 For compatibility with HP FORTRAN 77/iX, the @code{RAN} intrinsic is
9147 provided as an alias for @code{RAND}. See @ref{RAND} for complete
9150 @item @emph{Standard}:
9156 @item @emph{See also}:
9157 @ref{RAND}, @ref{RANDOM_NUMBER}
9163 @section @code{RAND} --- Real pseudo-random number
9165 @cindex random number generation
9168 @item @emph{Description}:
9169 @code{RAND(FLAG)} returns a pseudo-random number from a uniform
9170 distribution between 0 and 1. If @var{FLAG} is 0, the next number
9171 in the current sequence is returned; if @var{FLAG} is 1, the generator
9172 is restarted by @code{CALL SRAND(0)}; if @var{FLAG} has any other value,
9173 it is used as a new seed with @code{SRAND}.
9175 This intrinsic routine is provided for backwards compatibility with
9176 GNU Fortran 77. It implements a simple modulo generator as provided
9177 by @command{g77}. For new code, one should consider the use of
9178 @ref{RANDOM_NUMBER} as it implements a superior algorithm.
9180 @item @emph{Standard}:
9186 @item @emph{Syntax}:
9187 @code{RESULT = RAND(I)}
9189 @item @emph{Arguments}:
9190 @multitable @columnfractions .15 .70
9191 @item @var{I} @tab Shall be a scalar @code{INTEGER} of kind 4.
9194 @item @emph{Return value}:
9195 The return value is of @code{REAL} type and the default kind.
9197 @item @emph{Example}:
9200 integer,parameter :: seed = 86456
9203 print *, rand(), rand(), rand(), rand()
9204 print *, rand(seed), rand(), rand(), rand()
9205 end program test_rand
9208 @item @emph{See also}:
9209 @ref{SRAND}, @ref{RANDOM_NUMBER}
9216 @section @code{RANDOM_NUMBER} --- Pseudo-random number
9217 @fnindex RANDOM_NUMBER
9218 @cindex random number generation
9221 @item @emph{Description}:
9222 Returns a single pseudorandom number or an array of pseudorandom numbers
9223 from the uniform distribution over the range @math{ 0 \leq x < 1}.
9225 The runtime-library implements George Marsaglia's KISS (Keep It Simple
9226 Stupid) random number generator (RNG). This RNG combines:
9228 @item The congruential generator @math{x(n) = 69069 \cdot x(n-1) + 1327217885}
9229 with a period of @math{2^{32}},
9230 @item A 3-shift shift-register generator with a period of @math{2^{32} - 1},
9231 @item Two 16-bit multiply-with-carry generators with a period of
9232 @math{597273182964842497 > 2^{59}}.
9234 The overall period exceeds @math{2^{123}}.
9236 Please note, this RNG is thread safe if used within OpenMP directives,
9237 i.e., its state will be consistent while called from multiple threads.
9238 However, the KISS generator does not create random numbers in parallel
9239 from multiple sources, but in sequence from a single source. If an
9240 OpenMP-enabled application heavily relies on random numbers, one should
9241 consider employing a dedicated parallel random number generator instead.
9243 @item @emph{Standard}:
9244 Fortran 95 and later
9249 @item @emph{Syntax}:
9250 @code{RANDOM_NUMBER(HARVEST)}
9252 @item @emph{Arguments}:
9253 @multitable @columnfractions .15 .70
9254 @item @var{HARVEST} @tab Shall be a scalar or an array of type @code{REAL}.
9257 @item @emph{Example}:
9259 program test_random_number
9261 CALL init_random_seed() ! see example of RANDOM_SEED
9262 CALL RANDOM_NUMBER(r)
9266 @item @emph{See also}:
9273 @section @code{RANDOM_SEED} --- Initialize a pseudo-random number sequence
9274 @fnindex RANDOM_SEED
9275 @cindex random number generation, seeding
9276 @cindex seeding a random number generator
9279 @item @emph{Description}:
9280 Restarts or queries the state of the pseudorandom number generator used by
9281 @code{RANDOM_NUMBER}.
9283 If @code{RANDOM_SEED} is called without arguments, it is initialized to
9284 a default state. The example below shows how to initialize the random
9285 seed based on the system's time.
9287 @item @emph{Standard}:
9288 Fortran 95 and later
9293 @item @emph{Syntax}:
9294 @code{CALL RANDOM_SEED([SIZE, PUT, GET])}
9296 @item @emph{Arguments}:
9297 @multitable @columnfractions .15 .70
9298 @item @var{SIZE} @tab (Optional) Shall be a scalar and of type default
9299 @code{INTEGER}, with @code{INTENT(OUT)}. It specifies the minimum size
9300 of the arrays used with the @var{PUT} and @var{GET} arguments.
9301 @item @var{PUT} @tab (Optional) Shall be an array of type default
9302 @code{INTEGER} and rank one. It is @code{INTENT(IN)} and the size of
9303 the array must be larger than or equal to the number returned by the
9304 @var{SIZE} argument.
9305 @item @var{GET} @tab (Optional) Shall be an array of type default
9306 @code{INTEGER} and rank one. It is @code{INTENT(OUT)} and the size
9307 of the array must be larger than or equal to the number returned by
9308 the @var{SIZE} argument.
9311 @item @emph{Example}:
9313 SUBROUTINE init_random_seed()
9314 INTEGER :: i, n, clock
9315 INTEGER, DIMENSION(:), ALLOCATABLE :: seed
9317 CALL RANDOM_SEED(size = n)
9320 CALL SYSTEM_CLOCK(COUNT=clock)
9322 seed = clock + 37 * (/ (i - 1, i = 1, n) /)
9323 CALL RANDOM_SEED(PUT = seed)
9329 @item @emph{See also}:
9336 @section @code{RANGE} --- Decimal exponent range
9338 @cindex model representation, range
9341 @item @emph{Description}:
9342 @code{RANGE(X)} returns the decimal exponent range in the model of the
9345 @item @emph{Standard}:
9346 Fortran 95 and later
9351 @item @emph{Syntax}:
9352 @code{RESULT = RANGE(X)}
9354 @item @emph{Arguments}:
9355 @multitable @columnfractions .15 .70
9356 @item @var{X} @tab Shall be of type @code{INTEGER}, @code{REAL}
9360 @item @emph{Return value}:
9361 The return value is of type @code{INTEGER} and of the default integer
9364 @item @emph{See also}:
9365 @ref{SELECTED_REAL_KIND}, @ref{PRECISION}
9367 @item @emph{Example}:
9368 See @code{PRECISION} for an example.
9374 @section @code{REAL} --- Convert to real type
9380 @cindex conversion, to real
9381 @cindex complex numbers, real part
9384 @item @emph{Description}:
9385 @code{REAL(A [, KIND])} converts its argument @var{A} to a real type. The
9386 @code{REALPART} function is provided for compatibility with @command{g77},
9387 and its use is strongly discouraged.
9389 @item @emph{Standard}:
9390 Fortran 77 and later
9395 @item @emph{Syntax}:
9396 @multitable @columnfractions .80
9397 @item @code{RESULT = REAL(A [, KIND])}
9398 @item @code{RESULT = REALPART(Z)}
9401 @item @emph{Arguments}:
9402 @multitable @columnfractions .15 .70
9403 @item @var{A} @tab Shall be @code{INTEGER}, @code{REAL}, or
9405 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
9406 expression indicating the kind parameter of the result.
9409 @item @emph{Return value}:
9410 These functions return a @code{REAL} variable or array under
9411 the following rules:
9415 @code{REAL(A)} is converted to a default real type if @var{A} is an
9416 integer or real variable.
9418 @code{REAL(A)} is converted to a real type with the kind type parameter
9419 of @var{A} if @var{A} is a complex variable.
9421 @code{REAL(A, KIND)} is converted to a real type with kind type
9422 parameter @var{KIND} if @var{A} is a complex, integer, or real
9426 @item @emph{Example}:
9429 complex :: x = (1.0, 2.0)
9430 print *, real(x), real(x,8), realpart(x)
9431 end program test_real
9434 @item @emph{Specific names}:
9435 @multitable @columnfractions .20 .20 .20 .25
9436 @item Name @tab Argument @tab Return type @tab Standard
9437 @item @code{FLOAT(A)} @tab @code{INTEGER(4)} @tab @code{REAL(4)} @tab Fortran 77 and later
9438 @item @code{DFLOAT(A)} @tab @code{INTEGER(4)} @tab @code{REAL(8)} @tab GNU extension
9439 @item @code{SNGL(A)} @tab @code{INTEGER(8)} @tab @code{REAL(4)} @tab Fortran 77 and later
9443 @item @emph{See also}:
9451 @section @code{RENAME} --- Rename a file
9453 @cindex file system, rename file
9456 @item @emph{Description}:
9457 Renames a file from file @var{PATH1} to @var{PATH2}. A null
9458 character (@code{CHAR(0)}) can be used to mark the end of the names in
9459 @var{PATH1} and @var{PATH2}; otherwise, trailing blanks in the file
9460 names are ignored. If the @var{STATUS} argument is supplied, it
9461 contains 0 on success or a nonzero error code upon return; see
9464 This intrinsic is provided in both subroutine and function forms;
9465 however, only one form can be used in any given program unit.
9467 @item @emph{Standard}:
9471 Subroutine, function
9473 @item @emph{Syntax}:
9474 @multitable @columnfractions .80
9475 @item @code{CALL RENAME(PATH1, PATH2 [, STATUS])}
9476 @item @code{STATUS = RENAME(PATH1, PATH2)}
9479 @item @emph{Arguments}:
9480 @multitable @columnfractions .15 .70
9481 @item @var{PATH1} @tab Shall be of default @code{CHARACTER} type.
9482 @item @var{PATH2} @tab Shall be of default @code{CHARACTER} type.
9483 @item @var{STATUS} @tab (Optional) Shall be of default @code{INTEGER} type.
9486 @item @emph{See also}:
9494 @section @code{REPEAT} --- Repeated string concatenation
9496 @cindex string, repeat
9497 @cindex string, concatenate
9500 @item @emph{Description}:
9501 Concatenates @var{NCOPIES} copies of a string.
9503 @item @emph{Standard}:
9504 Fortran 95 and later
9507 Transformational function
9509 @item @emph{Syntax}:
9510 @code{RESULT = REPEAT(STRING, NCOPIES)}
9512 @item @emph{Arguments}:
9513 @multitable @columnfractions .15 .70
9514 @item @var{STRING} @tab Shall be scalar and of type @code{CHARACTER}.
9515 @item @var{NCOPIES} @tab Shall be scalar and of type @code{INTEGER}.
9518 @item @emph{Return value}:
9519 A new scalar of type @code{CHARACTER} built up from @var{NCOPIES} copies
9522 @item @emph{Example}:
9525 write(*,*) repeat("x", 5) ! "xxxxx"
9533 @section @code{RESHAPE} --- Function to reshape an array
9535 @cindex array, change dimensions
9536 @cindex array, transmogrify
9539 @item @emph{Description}:
9540 Reshapes @var{SOURCE} to correspond to @var{SHAPE}. If necessary,
9541 the new array may be padded with elements from @var{PAD} or permuted
9542 as defined by @var{ORDER}.
9544 @item @emph{Standard}:
9545 Fortran 95 and later
9548 Transformational function
9550 @item @emph{Syntax}:
9551 @code{RESULT = RESHAPE(SOURCE, SHAPE[, PAD, ORDER])}
9553 @item @emph{Arguments}:
9554 @multitable @columnfractions .15 .70
9555 @item @var{SOURCE} @tab Shall be an array of any type.
9556 @item @var{SHAPE} @tab Shall be of type @code{INTEGER} and an
9557 array of rank one. Its values must be positive or zero.
9558 @item @var{PAD} @tab (Optional) shall be an array of the same
9559 type as @var{SOURCE}.
9560 @item @var{ORDER} @tab (Optional) shall be of type @code{INTEGER}
9561 and an array of the same shape as @var{SHAPE}. Its values shall
9562 be a permutation of the numbers from 1 to n, where n is the size of
9563 @var{SHAPE}. If @var{ORDER} is absent, the natural ordering shall
9567 @item @emph{Return value}:
9568 The result is an array of shape @var{SHAPE} with the same type as
9571 @item @emph{Example}:
9573 PROGRAM test_reshape
9574 INTEGER, DIMENSION(4) :: x
9575 WRITE(*,*) SHAPE(x) ! prints "4"
9576 WRITE(*,*) SHAPE(RESHAPE(x, (/2, 2/))) ! prints "2 2"
9580 @item @emph{See also}:
9587 @section @code{RRSPACING} --- Reciprocal of the relative spacing
9589 @cindex real number, relative spacing
9590 @cindex floating point, relative spacing
9594 @item @emph{Description}:
9595 @code{RRSPACING(X)} returns the reciprocal of the relative spacing of
9596 model numbers near @var{X}.
9598 @item @emph{Standard}:
9599 Fortran 95 and later
9604 @item @emph{Syntax}:
9605 @code{RESULT = RRSPACING(X)}
9607 @item @emph{Arguments}:
9608 @multitable @columnfractions .15 .70
9609 @item @var{X} @tab Shall be of type @code{REAL}.
9612 @item @emph{Return value}:
9613 The return value is of the same type and kind as @var{X}.
9614 The value returned is equal to
9615 @code{ABS(FRACTION(X)) * FLOAT(RADIX(X))**DIGITS(X)}.
9617 @item @emph{See also}:
9624 @section @code{RSHIFT} --- Right shift bits
9626 @cindex bits, shift right
9629 @item @emph{Description}:
9630 @code{RSHIFT} returns a value corresponding to @var{I} with all of the
9631 bits shifted right by @var{SHIFT} places. If the absolute value of
9632 @var{SHIFT} is greater than @code{BIT_SIZE(I)}, the value is undefined.
9633 Bits shifted out from the left end are lost; zeros are shifted in from
9636 This function has been superseded by the @code{ISHFT} intrinsic, which
9637 is standard in Fortran 95 and later.
9639 @item @emph{Standard}:
9645 @item @emph{Syntax}:
9646 @code{RESULT = RSHIFT(I, SHIFT)}
9648 @item @emph{Arguments}:
9649 @multitable @columnfractions .15 .70
9650 @item @var{I} @tab The type shall be @code{INTEGER}.
9651 @item @var{SHIFT} @tab The type shall be @code{INTEGER}.
9654 @item @emph{Return value}:
9655 The return value is of type @code{INTEGER} and of the same kind as
9658 @item @emph{See also}:
9659 @ref{ISHFT}, @ref{ISHFTC}, @ref{LSHIFT}
9666 @section @code{SAME_TYPE_AS} --- Query dynamic types for equality
9667 @fnindex SAME_TYPE_AS
9670 @item @emph{Description}:
9671 Query dynamic types for equality.
9673 @item @emph{Standard}:
9674 Fortran 2003 and later
9679 @item @emph{Syntax}:
9680 @code{RESULT = SAME_TYPE_AS(A, B)}
9682 @item @emph{Arguments}:
9683 @multitable @columnfractions .15 .70
9684 @item @var{A} @tab Shall be an object of extensible declared type or
9685 unlimited polymorphic.
9686 @item @var{B} @tab Shall be an object of extensible declared type or
9687 unlimited polymorphic.
9690 @item @emph{Return value}:
9691 The return value is a scalar of type default logical. It is true if and
9692 only if the dynamic type of A is the same as the dynamic type of B.
9694 @item @emph{See also}:
9695 @ref{EXTENDS_TYPE_OF}
9702 @section @code{SCALE} --- Scale a real value
9704 @cindex real number, scale
9705 @cindex floating point, scale
9708 @item @emph{Description}:
9709 @code{SCALE(X,I)} returns @code{X * RADIX(X)**I}.
9711 @item @emph{Standard}:
9712 Fortran 95 and later
9717 @item @emph{Syntax}:
9718 @code{RESULT = SCALE(X, I)}
9720 @item @emph{Arguments}:
9721 @multitable @columnfractions .15 .70
9722 @item @var{X} @tab The type of the argument shall be a @code{REAL}.
9723 @item @var{I} @tab The type of the argument shall be a @code{INTEGER}.
9726 @item @emph{Return value}:
9727 The return value is of the same type and kind as @var{X}.
9728 Its value is @code{X * RADIX(X)**I}.
9730 @item @emph{Example}:
9733 real :: x = 178.1387e-4
9735 print *, scale(x,i), x*radix(x)**i
9736 end program test_scale
9744 @section @code{SCAN} --- Scan a string for the presence of a set of characters
9746 @cindex string, find subset
9749 @item @emph{Description}:
9750 Scans a @var{STRING} for any of the characters in a @var{SET}
9753 If @var{BACK} is either absent or equals @code{FALSE}, this function
9754 returns the position of the leftmost character of @var{STRING} that is
9755 in @var{SET}. If @var{BACK} equals @code{TRUE}, the rightmost position
9756 is returned. If no character of @var{SET} is found in @var{STRING}, the
9759 @item @emph{Standard}:
9760 Fortran 95 and later, with @var{KIND} argument Fortran 2003 and later
9765 @item @emph{Syntax}:
9766 @code{RESULT = SCAN(STRING, SET[, BACK [, KIND]])}
9768 @item @emph{Arguments}:
9769 @multitable @columnfractions .15 .70
9770 @item @var{STRING} @tab Shall be of type @code{CHARACTER}.
9771 @item @var{SET} @tab Shall be of type @code{CHARACTER}.
9772 @item @var{BACK} @tab (Optional) shall be of type @code{LOGICAL}.
9773 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
9774 expression indicating the kind parameter of the result.
9777 @item @emph{Return value}:
9778 The return value is of type @code{INTEGER} and of kind @var{KIND}. If
9779 @var{KIND} is absent, the return value is of default integer kind.
9781 @item @emph{Example}:
9784 WRITE(*,*) SCAN("FORTRAN", "AO") ! 2, found 'O'
9785 WRITE(*,*) SCAN("FORTRAN", "AO", .TRUE.) ! 6, found 'A'
9786 WRITE(*,*) SCAN("FORTRAN", "C++") ! 0, found none
9790 @item @emph{See also}:
9791 @ref{INDEX intrinsic}, @ref{VERIFY}
9797 @section @code{SECNDS} --- Time function
9799 @cindex time, elapsed
9800 @cindex elapsed time
9803 @item @emph{Description}:
9804 @code{SECNDS(X)} gets the time in seconds from the real-time system clock.
9805 @var{X} is a reference time, also in seconds. If this is zero, the time in
9806 seconds from midnight is returned. This function is non-standard and its
9809 @item @emph{Standard}:
9815 @item @emph{Syntax}:
9816 @code{RESULT = SECNDS (X)}
9818 @item @emph{Arguments}:
9819 @multitable @columnfractions .15 .70
9820 @item @var{T} @tab Shall be of type @code{REAL(4)}.
9821 @item @var{X} @tab Shall be of type @code{REAL(4)}.
9824 @item @emph{Return value}:
9827 @item @emph{Example}:
9832 print *, secnds (0.0) ! seconds since midnight
9833 t1 = secnds (0.0) ! reference time
9834 do i = 1, 10000000 ! do something
9836 t2 = secnds (t1) ! elapsed time
9837 print *, "Something took ", t2, " seconds."
9838 end program test_secnds
9845 @section @code{SECOND} --- CPU time function
9847 @cindex time, elapsed
9848 @cindex elapsed time
9851 @item @emph{Description}:
9852 Returns a @code{REAL(4)} value representing the elapsed CPU time in
9853 seconds. This provides the same functionality as the standard
9854 @code{CPU_TIME} intrinsic, and is only included for backwards
9857 This intrinsic is provided in both subroutine and function forms;
9858 however, only one form can be used in any given program unit.
9860 @item @emph{Standard}:
9864 Subroutine, function
9866 @item @emph{Syntax}:
9867 @multitable @columnfractions .80
9868 @item @code{CALL SECOND(TIME)}
9869 @item @code{TIME = SECOND()}
9872 @item @emph{Arguments}:
9873 @multitable @columnfractions .15 .70
9874 @item @var{TIME} @tab Shall be of type @code{REAL(4)}.
9877 @item @emph{Return value}:
9878 In either syntax, @var{TIME} is set to the process's current runtime in
9881 @item @emph{See also}:
9888 @node SELECTED_CHAR_KIND
9889 @section @code{SELECTED_CHAR_KIND} --- Choose character kind
9890 @fnindex SELECTED_CHAR_KIND
9891 @cindex character kind
9892 @cindex kind, character
9895 @item @emph{Description}:
9897 @code{SELECTED_CHAR_KIND(NAME)} returns the kind value for the character
9898 set named @var{NAME}, if a character set with such a name is supported,
9899 or @math{-1} otherwise. Currently, supported character sets include
9900 ``ASCII'' and ``DEFAULT'', which are equivalent, and ``ISO_10646''
9901 (Universal Character Set, UCS-4) which is commonly known as Unicode.
9903 @item @emph{Standard}:
9904 Fortran 2003 and later
9907 Transformational function
9909 @item @emph{Syntax}:
9910 @code{RESULT = SELECTED_CHAR_KIND(NAME)}
9912 @item @emph{Arguments}:
9913 @multitable @columnfractions .15 .70
9914 @item @var{NAME} @tab Shall be a scalar and of the default character type.
9917 @item @emph{Example}:
9919 program character_kind
9922 integer, parameter :: ascii = selected_char_kind ("ascii")
9923 integer, parameter :: ucs4 = selected_char_kind ('ISO_10646')
9925 character(kind=ascii, len=26) :: alphabet
9926 character(kind=ucs4, len=30) :: hello_world
9928 alphabet = ascii_"abcdefghijklmnopqrstuvwxyz"
9929 hello_world = ucs4_'Hello World and Ni Hao -- ' &
9930 // char (int (z'4F60'), ucs4) &
9931 // char (int (z'597D'), ucs4)
9933 write (*,*) alphabet
9935 open (output_unit, encoding='UTF-8')
9936 write (*,*) trim (hello_world)
9937 end program character_kind
9943 @node SELECTED_INT_KIND
9944 @section @code{SELECTED_INT_KIND} --- Choose integer kind
9945 @fnindex SELECTED_INT_KIND
9946 @cindex integer kind
9947 @cindex kind, integer
9950 @item @emph{Description}:
9951 @code{SELECTED_INT_KIND(R)} return the kind value of the smallest integer
9952 type that can represent all values ranging from @math{-10^R} (exclusive)
9953 to @math{10^R} (exclusive). If there is no integer kind that accommodates
9954 this range, @code{SELECTED_INT_KIND} returns @math{-1}.
9956 @item @emph{Standard}:
9957 Fortran 95 and later
9960 Transformational function
9962 @item @emph{Syntax}:
9963 @code{RESULT = SELECTED_INT_KIND(R)}
9965 @item @emph{Arguments}:
9966 @multitable @columnfractions .15 .70
9967 @item @var{R} @tab Shall be a scalar and of type @code{INTEGER}.
9970 @item @emph{Example}:
9972 program large_integers
9973 integer,parameter :: k5 = selected_int_kind(5)
9974 integer,parameter :: k15 = selected_int_kind(15)
9975 integer(kind=k5) :: i5
9976 integer(kind=k15) :: i15
9978 print *, huge(i5), huge(i15)
9980 ! The following inequalities are always true
9981 print *, huge(i5) >= 10_k5**5-1
9982 print *, huge(i15) >= 10_k15**15-1
9983 end program large_integers
9989 @node SELECTED_REAL_KIND
9990 @section @code{SELECTED_REAL_KIND} --- Choose real kind
9991 @fnindex SELECTED_REAL_KIND
9997 @item @emph{Description}:
9998 @code{SELECTED_REAL_KIND(P,R)} returns the kind value of a real data type
9999 with decimal precision of at least @code{P} digits, exponent range of
10000 at least @code{R}, and with a radix of @code{RADIX}.
10002 @item @emph{Standard}:
10003 Fortran 95 and later, with @code{RADIX} Fortran 2008 or later
10005 @item @emph{Class}:
10006 Transformational function
10008 @item @emph{Syntax}:
10009 @code{RESULT = SELECTED_REAL_KIND([P, R, RADIX])}
10011 @item @emph{Arguments}:
10012 @multitable @columnfractions .15 .70
10013 @item @var{P} @tab (Optional) shall be a scalar and of type @code{INTEGER}.
10014 @item @var{R} @tab (Optional) shall be a scalar and of type @code{INTEGER}.
10015 @item @var{RADIX} @tab (Optional) shall be a scalar and of type @code{INTEGER}.
10017 Before Fortran 2008, at least one of the arguments @var{R} or @var{P} shall
10018 be present; since Fortran 2008, they are assumed to be zero if absent.
10020 @item @emph{Return value}:
10022 @code{SELECTED_REAL_KIND} returns the value of the kind type parameter of
10023 a real data type with decimal precision of at least @code{P} digits, a
10024 decimal exponent range of at least @code{R}, and with the requested
10025 @code{RADIX}. If the @code{RADIX} parameter is absent, real kinds with
10026 any radix can be returned. If more than one real data type meet the
10027 criteria, the kind of the data type with the smallest decimal precision
10028 is returned. If no real data type matches the criteria, the result is
10030 @item -1 if the processor does not support a real data type with a
10031 precision greater than or equal to @code{P}, but the @code{R} and
10032 @code{RADIX} requirements can be fulfilled
10033 @item -2 if the processor does not support a real type with an exponent
10034 range greater than or equal to @code{R}, but @code{P} and @code{RADIX}
10036 @item -3 if @code{RADIX} but not @code{P} and @code{R} requirements
10038 @item -4 if @code{RADIX} and either @code{P} or @code{R} requirements
10040 @item -5 if there is no real type with the given @code{RADIX}
10043 @item @emph{See also}:
10044 @ref{PRECISION}, @ref{RANGE}, @ref{RADIX}
10046 @item @emph{Example}:
10049 integer,parameter :: p6 = selected_real_kind(6)
10050 integer,parameter :: p10r100 = selected_real_kind(10,100)
10051 integer,parameter :: r400 = selected_real_kind(r=400)
10053 real(kind=p10r100) :: y
10054 real(kind=r400) :: z
10056 print *, precision(x), range(x)
10057 print *, precision(y), range(y)
10058 print *, precision(z), range(z)
10059 end program real_kinds
10066 @section @code{SET_EXPONENT} --- Set the exponent of the model
10067 @fnindex SET_EXPONENT
10068 @cindex real number, set exponent
10069 @cindex floating point, set exponent
10072 @item @emph{Description}:
10073 @code{SET_EXPONENT(X, I)} returns the real number whose fractional part
10074 is that that of @var{X} and whose exponent part is @var{I}.
10076 @item @emph{Standard}:
10077 Fortran 95 and later
10079 @item @emph{Class}:
10082 @item @emph{Syntax}:
10083 @code{RESULT = SET_EXPONENT(X, I)}
10085 @item @emph{Arguments}:
10086 @multitable @columnfractions .15 .70
10087 @item @var{X} @tab Shall be of type @code{REAL}.
10088 @item @var{I} @tab Shall be of type @code{INTEGER}.
10091 @item @emph{Return value}:
10092 The return value is of the same type and kind as @var{X}.
10093 The real number whose fractional part
10094 is that that of @var{X} and whose exponent part if @var{I} is returned;
10095 it is @code{FRACTION(X) * RADIX(X)**I}.
10097 @item @emph{Example}:
10099 PROGRAM test_setexp
10100 REAL :: x = 178.1387e-4
10102 PRINT *, SET_EXPONENT(x, i), FRACTION(x) * RADIX(x)**i
10111 @section @code{SHAPE} --- Determine the shape of an array
10113 @cindex array, shape
10116 @item @emph{Description}:
10117 Determines the shape of an array.
10119 @item @emph{Standard}:
10120 Fortran 95 and later
10122 @item @emph{Class}:
10125 @item @emph{Syntax}:
10126 @code{RESULT = SHAPE(SOURCE)}
10128 @item @emph{Arguments}:
10129 @multitable @columnfractions .15 .70
10130 @item @var{SOURCE} @tab Shall be an array or scalar of any type.
10131 If @var{SOURCE} is a pointer it must be associated and allocatable
10132 arrays must be allocated.
10135 @item @emph{Return value}:
10136 An @code{INTEGER} array of rank one with as many elements as @var{SOURCE}
10137 has dimensions. The elements of the resulting array correspond to the extend
10138 of @var{SOURCE} along the respective dimensions. If @var{SOURCE} is a scalar,
10139 the result is the rank one array of size zero.
10141 @item @emph{Example}:
10144 INTEGER, DIMENSION(-1:1, -1:2) :: A
10145 WRITE(*,*) SHAPE(A) ! (/ 3, 4 /)
10146 WRITE(*,*) SIZE(SHAPE(42)) ! (/ /)
10150 @item @emph{See also}:
10151 @ref{RESHAPE}, @ref{SIZE}
10157 @section @code{SIGN} --- Sign copying function
10161 @cindex sign copying
10164 @item @emph{Description}:
10165 @code{SIGN(A,B)} returns the value of @var{A} with the sign of @var{B}.
10167 @item @emph{Standard}:
10168 Fortran 77 and later
10170 @item @emph{Class}:
10173 @item @emph{Syntax}:
10174 @code{RESULT = SIGN(A, B)}
10176 @item @emph{Arguments}:
10177 @multitable @columnfractions .15 .70
10178 @item @var{A} @tab Shall be of type @code{INTEGER} or @code{REAL}
10179 @item @var{B} @tab Shall be of the same type and kind as @var{A}
10182 @item @emph{Return value}:
10183 The kind of the return value is that of @var{A} and @var{B}.
10184 If @math{B\ge 0} then the result is @code{ABS(A)}, else
10185 it is @code{-ABS(A)}.
10187 @item @emph{Example}:
10190 print *, sign(-12,1)
10191 print *, sign(-12,0)
10192 print *, sign(-12,-1)
10194 print *, sign(-12.,1.)
10195 print *, sign(-12.,0.)
10196 print *, sign(-12.,-1.)
10197 end program test_sign
10200 @item @emph{Specific names}:
10201 @multitable @columnfractions .20 .20 .20 .25
10202 @item Name @tab Arguments @tab Return type @tab Standard
10203 @item @code{SIGN(A,B)} @tab @code{REAL(4) A, B} @tab @code{REAL(4)} @tab f77, gnu
10204 @item @code{ISIGN(A,B)} @tab @code{INTEGER(4) A, B} @tab @code{INTEGER(4)} @tab f77, gnu
10205 @item @code{DSIGN(A,B)} @tab @code{REAL(8) A, B} @tab @code{REAL(8)} @tab f77, gnu
10212 @section @code{SIGNAL} --- Signal handling subroutine (or function)
10214 @cindex system, signal handling
10217 @item @emph{Description}:
10218 @code{SIGNAL(NUMBER, HANDLER [, STATUS])} causes external subroutine
10219 @var{HANDLER} to be executed with a single integer argument when signal
10220 @var{NUMBER} occurs. If @var{HANDLER} is an integer, it can be used to
10221 turn off handling of signal @var{NUMBER} or revert to its default
10222 action. See @code{signal(2)}.
10224 If @code{SIGNAL} is called as a subroutine and the @var{STATUS} argument
10225 is supplied, it is set to the value returned by @code{signal(2)}.
10227 @item @emph{Standard}:
10230 @item @emph{Class}:
10231 Subroutine, function
10233 @item @emph{Syntax}:
10234 @multitable @columnfractions .80
10235 @item @code{CALL SIGNAL(NUMBER, HANDLER [, STATUS])}
10236 @item @code{STATUS = SIGNAL(NUMBER, HANDLER)}
10239 @item @emph{Arguments}:
10240 @multitable @columnfractions .15 .70
10241 @item @var{NUMBER} @tab Shall be a scalar integer, with @code{INTENT(IN)}
10242 @item @var{HANDLER}@tab Signal handler (@code{INTEGER FUNCTION} or
10243 @code{SUBROUTINE}) or dummy/global @code{INTEGER} scalar.
10244 @code{INTEGER}. It is @code{INTENT(IN)}.
10245 @item @var{STATUS} @tab (Optional) @var{STATUS} shall be a scalar
10246 integer. It has @code{INTENT(OUT)}.
10248 @c TODO: What should the interface of the handler be? Does it take arguments?
10250 @item @emph{Return value}:
10251 The @code{SIGNAL} function returns the value returned by @code{signal(2)}.
10253 @item @emph{Example}:
10255 program test_signal
10257 external handler_print
10259 call signal (12, handler_print)
10260 call signal (10, 1)
10263 end program test_signal
10270 @section @code{SIN} --- Sine function
10276 @cindex trigonometric function, sine
10280 @item @emph{Description}:
10281 @code{SIN(X)} computes the sine of @var{X}.
10283 @item @emph{Standard}:
10284 Fortran 77 and later
10286 @item @emph{Class}:
10289 @item @emph{Syntax}:
10290 @code{RESULT = SIN(X)}
10292 @item @emph{Arguments}:
10293 @multitable @columnfractions .15 .70
10294 @item @var{X} @tab The type shall be @code{REAL} or
10298 @item @emph{Return value}:
10299 The return value has same type and kind as @var{X}.
10301 @item @emph{Example}:
10306 end program test_sin
10309 @item @emph{Specific names}:
10310 @multitable @columnfractions .20 .20 .20 .25
10311 @item Name @tab Argument @tab Return type @tab Standard
10312 @item @code{SIN(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab f77, gnu
10313 @item @code{DSIN(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab f95, gnu
10314 @item @code{CSIN(X)} @tab @code{COMPLEX(4) X} @tab @code{COMPLEX(4)} @tab f95, gnu
10315 @item @code{ZSIN(X)} @tab @code{COMPLEX(8) X} @tab @code{COMPLEX(8)} @tab f95, gnu
10316 @item @code{CDSIN(X)} @tab @code{COMPLEX(8) X} @tab @code{COMPLEX(8)} @tab f95, gnu
10319 @item @emph{See also}:
10326 @section @code{SINH} --- Hyperbolic sine function
10329 @cindex hyperbolic sine
10330 @cindex hyperbolic function, sine
10331 @cindex sine, hyperbolic
10334 @item @emph{Description}:
10335 @code{SINH(X)} computes the hyperbolic sine of @var{X}.
10337 @item @emph{Standard}:
10338 Fortran 95 and later, for a complex argument Fortran 2008 or later
10340 @item @emph{Class}:
10343 @item @emph{Syntax}:
10344 @code{RESULT = SINH(X)}
10346 @item @emph{Arguments}:
10347 @multitable @columnfractions .15 .70
10348 @item @var{X} @tab The type shall be @code{REAL} or @code{COMPLEX}.
10351 @item @emph{Return value}:
10352 The return value has same type and kind as @var{X}.
10354 @item @emph{Example}:
10357 real(8) :: x = - 1.0_8
10359 end program test_sinh
10362 @item @emph{Specific names}:
10363 @multitable @columnfractions .20 .20 .20 .25
10364 @item Name @tab Argument @tab Return type @tab Standard
10365 @item @code{SINH(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab Fortran 95 and later
10366 @item @code{DSINH(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab Fortran 95 and later
10369 @item @emph{See also}:
10376 @section @code{SIZE} --- Determine the size of an array
10378 @cindex array, size
10379 @cindex array, number of elements
10380 @cindex array, count elements
10383 @item @emph{Description}:
10384 Determine the extent of @var{ARRAY} along a specified dimension @var{DIM},
10385 or the total number of elements in @var{ARRAY} if @var{DIM} is absent.
10387 @item @emph{Standard}:
10388 Fortran 95 and later, with @var{KIND} argument Fortran 2003 and later
10390 @item @emph{Class}:
10393 @item @emph{Syntax}:
10394 @code{RESULT = SIZE(ARRAY[, DIM [, KIND]])}
10396 @item @emph{Arguments}:
10397 @multitable @columnfractions .15 .70
10398 @item @var{ARRAY} @tab Shall be an array of any type. If @var{ARRAY} is
10399 a pointer it must be associated and allocatable arrays must be allocated.
10400 @item @var{DIM} @tab (Optional) shall be a scalar of type @code{INTEGER}
10401 and its value shall be in the range from 1 to n, where n equals the rank
10403 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
10404 expression indicating the kind parameter of the result.
10407 @item @emph{Return value}:
10408 The return value is of type @code{INTEGER} and of kind @var{KIND}. If
10409 @var{KIND} is absent, the return value is of default integer kind.
10411 @item @emph{Example}:
10414 WRITE(*,*) SIZE((/ 1, 2 /)) ! 2
10418 @item @emph{See also}:
10419 @ref{SHAPE}, @ref{RESHAPE}
10424 @section @code{SIZEOF} --- Size in bytes of an expression
10426 @cindex expression size
10427 @cindex size of an expression
10430 @item @emph{Description}:
10431 @code{SIZEOF(X)} calculates the number of bytes of storage the
10432 expression @code{X} occupies.
10434 @item @emph{Standard}:
10437 @item @emph{Class}:
10440 @item @emph{Syntax}:
10441 @code{N = SIZEOF(X)}
10443 @item @emph{Arguments}:
10444 @multitable @columnfractions .15 .70
10445 @item @var{X} @tab The argument shall be of any type, rank or shape.
10448 @item @emph{Return value}:
10449 The return value is of type integer and of the system-dependent kind
10450 @var{C_SIZE_T} (from the @var{ISO_C_BINDING} module). Its value is the
10451 number of bytes occupied by the argument. If the argument has the
10452 @code{POINTER} attribute, the number of bytes of the storage area pointed
10453 to is returned. If the argument is of a derived type with @code{POINTER}
10454 or @code{ALLOCATABLE} components, the return value doesn't account for
10455 the sizes of the data pointed to by these components. If the argument is
10456 polymorphic, the size according to the declared type is returned.
10458 @item @emph{Example}:
10462 print *, (sizeof(s)/sizeof(r) == 5)
10465 The example will print @code{.TRUE.} unless you are using a platform
10466 where default @code{REAL} variables are unusually padded.
10468 @item @emph{See also}:
10469 @ref{C_SIZEOF}, @ref{STORAGE_SIZE}
10474 @section @code{SLEEP} --- Sleep for the specified number of seconds
10476 @cindex delayed execution
10479 @item @emph{Description}:
10480 Calling this subroutine causes the process to pause for @var{SECONDS} seconds.
10482 @item @emph{Standard}:
10485 @item @emph{Class}:
10488 @item @emph{Syntax}:
10489 @code{CALL SLEEP(SECONDS)}
10491 @item @emph{Arguments}:
10492 @multitable @columnfractions .15 .70
10493 @item @var{SECONDS} @tab The type shall be of default @code{INTEGER}.
10496 @item @emph{Example}:
10507 @section @code{SPACING} --- Smallest distance between two numbers of a given type
10509 @cindex real number, relative spacing
10510 @cindex floating point, relative spacing
10513 @item @emph{Description}:
10514 Determines the distance between the argument @var{X} and the nearest
10515 adjacent number of the same type.
10517 @item @emph{Standard}:
10518 Fortran 95 and later
10520 @item @emph{Class}:
10523 @item @emph{Syntax}:
10524 @code{RESULT = SPACING(X)}
10526 @item @emph{Arguments}:
10527 @multitable @columnfractions .15 .70
10528 @item @var{X} @tab Shall be of type @code{REAL}.
10531 @item @emph{Return value}:
10532 The result is of the same type as the input argument @var{X}.
10534 @item @emph{Example}:
10536 PROGRAM test_spacing
10537 INTEGER, PARAMETER :: SGL = SELECTED_REAL_KIND(p=6, r=37)
10538 INTEGER, PARAMETER :: DBL = SELECTED_REAL_KIND(p=13, r=200)
10540 WRITE(*,*) spacing(1.0_SGL) ! "1.1920929E-07" on i686
10541 WRITE(*,*) spacing(1.0_DBL) ! "2.220446049250313E-016" on i686
10545 @item @emph{See also}:
10552 @section @code{SPREAD} --- Add a dimension to an array
10554 @cindex array, increase dimension
10555 @cindex array, duplicate elements
10556 @cindex array, duplicate dimensions
10559 @item @emph{Description}:
10560 Replicates a @var{SOURCE} array @var{NCOPIES} times along a specified
10561 dimension @var{DIM}.
10563 @item @emph{Standard}:
10564 Fortran 95 and later
10566 @item @emph{Class}:
10567 Transformational function
10569 @item @emph{Syntax}:
10570 @code{RESULT = SPREAD(SOURCE, DIM, NCOPIES)}
10572 @item @emph{Arguments}:
10573 @multitable @columnfractions .15 .70
10574 @item @var{SOURCE} @tab Shall be a scalar or an array of any type and
10575 a rank less than seven.
10576 @item @var{DIM} @tab Shall be a scalar of type @code{INTEGER} with a
10577 value in the range from 1 to n+1, where n equals the rank of @var{SOURCE}.
10578 @item @var{NCOPIES} @tab Shall be a scalar of type @code{INTEGER}.
10581 @item @emph{Return value}:
10582 The result is an array of the same type as @var{SOURCE} and has rank n+1
10583 where n equals the rank of @var{SOURCE}.
10585 @item @emph{Example}:
10587 PROGRAM test_spread
10588 INTEGER :: a = 1, b(2) = (/ 1, 2 /)
10589 WRITE(*,*) SPREAD(A, 1, 2) ! "1 1"
10590 WRITE(*,*) SPREAD(B, 1, 2) ! "1 1 2 2"
10594 @item @emph{See also}:
10601 @section @code{SQRT} --- Square-root function
10608 @cindex square-root
10611 @item @emph{Description}:
10612 @code{SQRT(X)} computes the square root of @var{X}.
10614 @item @emph{Standard}:
10615 Fortran 77 and later
10617 @item @emph{Class}:
10620 @item @emph{Syntax}:
10621 @code{RESULT = SQRT(X)}
10623 @item @emph{Arguments}:
10624 @multitable @columnfractions .15 .70
10625 @item @var{X} @tab The type shall be @code{REAL} or
10629 @item @emph{Return value}:
10630 The return value is of type @code{REAL} or @code{COMPLEX}.
10631 The kind type parameter is the same as @var{X}.
10633 @item @emph{Example}:
10636 real(8) :: x = 2.0_8
10637 complex :: z = (1.0, 2.0)
10640 end program test_sqrt
10643 @item @emph{Specific names}:
10644 @multitable @columnfractions .20 .20 .20 .25
10645 @item Name @tab Argument @tab Return type @tab Standard
10646 @item @code{SQRT(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab Fortran 95 and later
10647 @item @code{DSQRT(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab Fortran 95 and later
10648 @item @code{CSQRT(X)} @tab @code{COMPLEX(4) X} @tab @code{COMPLEX(4)} @tab Fortran 95 and later
10649 @item @code{ZSQRT(X)} @tab @code{COMPLEX(8) X} @tab @code{COMPLEX(8)} @tab GNU extension
10650 @item @code{CDSQRT(X)} @tab @code{COMPLEX(8) X} @tab @code{COMPLEX(8)} @tab GNU extension
10657 @section @code{SRAND} --- Reinitialize the random number generator
10659 @cindex random number generation, seeding
10660 @cindex seeding a random number generator
10663 @item @emph{Description}:
10664 @code{SRAND} reinitializes the pseudo-random number generator
10665 called by @code{RAND} and @code{IRAND}. The new seed used by the
10666 generator is specified by the required argument @var{SEED}.
10668 @item @emph{Standard}:
10671 @item @emph{Class}:
10674 @item @emph{Syntax}:
10675 @code{CALL SRAND(SEED)}
10677 @item @emph{Arguments}:
10678 @multitable @columnfractions .15 .70
10679 @item @var{SEED} @tab Shall be a scalar @code{INTEGER(kind=4)}.
10682 @item @emph{Return value}:
10683 Does not return anything.
10685 @item @emph{Example}:
10686 See @code{RAND} and @code{IRAND} for examples.
10688 @item @emph{Notes}:
10689 The Fortran 2003 standard specifies the intrinsic @code{RANDOM_SEED} to
10690 initialize the pseudo-random numbers generator and @code{RANDOM_NUMBER}
10691 to generate pseudo-random numbers. Please note that in
10692 GNU Fortran, these two sets of intrinsics (@code{RAND},
10693 @code{IRAND} and @code{SRAND} on the one hand, @code{RANDOM_NUMBER} and
10694 @code{RANDOM_SEED} on the other hand) access two independent
10695 pseudo-random number generators.
10697 @item @emph{See also}:
10698 @ref{RAND}, @ref{RANDOM_SEED}, @ref{RANDOM_NUMBER}
10705 @section @code{STAT} --- Get file status
10707 @cindex file system, file status
10710 @item @emph{Description}:
10711 This function returns information about a file. No permissions are required on
10712 the file itself, but execute (search) permission is required on all of the
10713 directories in path that lead to the file.
10715 The elements that are obtained and stored in the array @code{VALUES}:
10716 @multitable @columnfractions .15 .70
10717 @item @code{VALUES(1)} @tab Device ID
10718 @item @code{VALUES(2)} @tab Inode number
10719 @item @code{VALUES(3)} @tab File mode
10720 @item @code{VALUES(4)} @tab Number of links
10721 @item @code{VALUES(5)} @tab Owner's uid
10722 @item @code{VALUES(6)} @tab Owner's gid
10723 @item @code{VALUES(7)} @tab ID of device containing directory entry for file (0 if not available)
10724 @item @code{VALUES(8)} @tab File size (bytes)
10725 @item @code{VALUES(9)} @tab Last access time
10726 @item @code{VALUES(10)} @tab Last modification time
10727 @item @code{VALUES(11)} @tab Last file status change time
10728 @item @code{VALUES(12)} @tab Preferred I/O block size (-1 if not available)
10729 @item @code{VALUES(13)} @tab Number of blocks allocated (-1 if not available)
10732 Not all these elements are relevant on all systems.
10733 If an element is not relevant, it is returned as 0.
10735 This intrinsic is provided in both subroutine and function forms; however,
10736 only one form can be used in any given program unit.
10738 @item @emph{Standard}:
10741 @item @emph{Class}:
10742 Subroutine, function
10744 @item @emph{Syntax}:
10745 @code{CALL STAT(NAME, VALUES [, STATUS])}
10747 @item @emph{Arguments}:
10748 @multitable @columnfractions .15 .70
10749 @item @var{NAME} @tab The type shall be @code{CHARACTER}, of the
10750 default kind and a valid path within the file system.
10751 @item @var{VALUES} @tab The type shall be @code{INTEGER(4), DIMENSION(13)}.
10752 @item @var{STATUS} @tab (Optional) status flag of type @code{INTEGER(4)}. Returns 0
10753 on success and a system specific error code otherwise.
10756 @item @emph{Example}:
10759 INTEGER, DIMENSION(13) :: buff
10762 CALL STAT("/etc/passwd", buff, status)
10764 IF (status == 0) THEN
10765 WRITE (*, FMT="('Device ID:', T30, I19)") buff(1)
10766 WRITE (*, FMT="('Inode number:', T30, I19)") buff(2)
10767 WRITE (*, FMT="('File mode (octal):', T30, O19)") buff(3)
10768 WRITE (*, FMT="('Number of links:', T30, I19)") buff(4)
10769 WRITE (*, FMT="('Owner''s uid:', T30, I19)") buff(5)
10770 WRITE (*, FMT="('Owner''s gid:', T30, I19)") buff(6)
10771 WRITE (*, FMT="('Device where located:', T30, I19)") buff(7)
10772 WRITE (*, FMT="('File size:', T30, I19)") buff(8)
10773 WRITE (*, FMT="('Last access time:', T30, A19)") CTIME(buff(9))
10774 WRITE (*, FMT="('Last modification time', T30, A19)") CTIME(buff(10))
10775 WRITE (*, FMT="('Last status change time:', T30, A19)") CTIME(buff(11))
10776 WRITE (*, FMT="('Preferred block size:', T30, I19)") buff(12)
10777 WRITE (*, FMT="('No. of blocks allocated:', T30, I19)") buff(13)
10782 @item @emph{See also}:
10783 To stat an open file: @ref{FSTAT}, to stat a link: @ref{LSTAT}
10789 @section @code{STORAGE_SIZE} --- Storage size in bits
10790 @fnindex STORAGE_SIZE
10791 @cindex storage size
10794 @item @emph{Description}:
10795 Returns the storage size of argument @var{A} in bits.
10796 @item @emph{Standard}:
10797 Fortran 2008 and later
10798 @item @emph{Class}:
10800 @item @emph{Syntax}:
10801 @code{RESULT = STORAGE_SIZE(A [, KIND])}
10803 @item @emph{Arguments}:
10804 @multitable @columnfractions .15 .70
10805 @item @var{A} @tab Shall be a scalar or array of any type.
10806 @item @var{KIND} @tab (Optional) shall be a scalar integer constant expression.
10809 @item @emph{Return Value}:
10810 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
10811 has the dynamic type and type parameters of A.
10813 @item @emph{See also}:
10814 @ref{C_SIZEOF}, @ref{SIZEOF}
10820 @section @code{SUM} --- Sum of array elements
10823 @cindex array, add elements
10824 @cindex array, conditionally add elements
10825 @cindex sum array elements
10828 @item @emph{Description}:
10829 Adds the elements of @var{ARRAY} along dimension @var{DIM} if
10830 the corresponding element in @var{MASK} is @code{TRUE}.
10832 @item @emph{Standard}:
10833 Fortran 95 and later
10835 @item @emph{Class}:
10836 Transformational function
10838 @item @emph{Syntax}:
10839 @multitable @columnfractions .80
10840 @item @code{RESULT = SUM(ARRAY[, MASK])}
10841 @item @code{RESULT = SUM(ARRAY, DIM[, MASK])}
10844 @item @emph{Arguments}:
10845 @multitable @columnfractions .15 .70
10846 @item @var{ARRAY} @tab Shall be an array of type @code{INTEGER},
10847 @code{REAL} or @code{COMPLEX}.
10848 @item @var{DIM} @tab (Optional) shall be a scalar of type
10849 @code{INTEGER} with a value in the range from 1 to n, where n
10850 equals the rank of @var{ARRAY}.
10851 @item @var{MASK} @tab (Optional) shall be of type @code{LOGICAL}
10852 and either be a scalar or an array of the same shape as @var{ARRAY}.
10855 @item @emph{Return value}:
10856 The result is of the same type as @var{ARRAY}.
10858 If @var{DIM} is absent, a scalar with the sum of all elements in @var{ARRAY}
10859 is returned. Otherwise, an array of rank n-1, where n equals the rank of
10860 @var{ARRAY}, and a shape similar to that of @var{ARRAY} with dimension @var{DIM}
10861 dropped is returned.
10863 @item @emph{Example}:
10866 INTEGER :: x(5) = (/ 1, 2, 3, 4 ,5 /)
10867 print *, SUM(x) ! all elements, sum = 15
10868 print *, SUM(x, MASK=MOD(x, 2)==1) ! odd elements, sum = 9
10872 @item @emph{See also}:
10879 @section @code{SYMLNK} --- Create a symbolic link
10881 @cindex file system, create link
10882 @cindex file system, soft link
10885 @item @emph{Description}:
10886 Makes a symbolic link from file @var{PATH1} to @var{PATH2}. A null
10887 character (@code{CHAR(0)}) can be used to mark the end of the names in
10888 @var{PATH1} and @var{PATH2}; otherwise, trailing blanks in the file
10889 names are ignored. If the @var{STATUS} argument is supplied, it
10890 contains 0 on success or a nonzero error code upon return; see
10891 @code{symlink(2)}. If the system does not supply @code{symlink(2)},
10892 @code{ENOSYS} is returned.
10894 This intrinsic is provided in both subroutine and function forms;
10895 however, only one form can be used in any given program unit.
10897 @item @emph{Standard}:
10900 @item @emph{Class}:
10901 Subroutine, function
10903 @item @emph{Syntax}:
10904 @multitable @columnfractions .80
10905 @item @code{CALL SYMLNK(PATH1, PATH2 [, STATUS])}
10906 @item @code{STATUS = SYMLNK(PATH1, PATH2)}
10909 @item @emph{Arguments}:
10910 @multitable @columnfractions .15 .70
10911 @item @var{PATH1} @tab Shall be of default @code{CHARACTER} type.
10912 @item @var{PATH2} @tab Shall be of default @code{CHARACTER} type.
10913 @item @var{STATUS} @tab (Optional) Shall be of default @code{INTEGER} type.
10916 @item @emph{See also}:
10917 @ref{LINK}, @ref{UNLINK}
10924 @section @code{SYSTEM} --- Execute a shell command
10926 @cindex system, system call
10929 @item @emph{Description}:
10930 Passes the command @var{COMMAND} to a shell (see @code{system(3)}). If
10931 argument @var{STATUS} is present, it contains the value returned by
10932 @code{system(3)}, which is presumably 0 if the shell command succeeded.
10933 Note that which shell is used to invoke the command is system-dependent
10934 and environment-dependent.
10936 This intrinsic is provided in both subroutine and function forms;
10937 however, only one form can be used in any given program unit.
10939 @item @emph{Standard}:
10942 @item @emph{Class}:
10943 Subroutine, function
10945 @item @emph{Syntax}:
10946 @multitable @columnfractions .80
10947 @item @code{CALL SYSTEM(COMMAND [, STATUS])}
10948 @item @code{STATUS = SYSTEM(COMMAND)}
10951 @item @emph{Arguments}:
10952 @multitable @columnfractions .15 .70
10953 @item @var{COMMAND} @tab Shall be of default @code{CHARACTER} type.
10954 @item @var{STATUS} @tab (Optional) Shall be of default @code{INTEGER} type.
10957 @item @emph{See also}:
10963 @section @code{SYSTEM_CLOCK} --- Time function
10964 @fnindex SYSTEM_CLOCK
10965 @cindex time, clock ticks
10966 @cindex clock ticks
10969 @item @emph{Description}:
10970 Determines the @var{COUNT} of milliseconds of wall clock time since
10971 the Epoch (00:00:00 UTC, January 1, 1970) modulo @var{COUNT_MAX},
10972 @var{COUNT_RATE} determines the number of clock ticks per second.
10973 @var{COUNT_RATE} and @var{COUNT_MAX} are constant and specific to
10974 @command{gfortran}.
10976 If there is no clock, @var{COUNT} is set to @code{-HUGE(COUNT)}, and
10977 @var{COUNT_RATE} and @var{COUNT_MAX} are set to zero
10979 @item @emph{Standard}:
10980 Fortran 95 and later
10982 @item @emph{Class}:
10985 @item @emph{Syntax}:
10986 @code{CALL SYSTEM_CLOCK([COUNT, COUNT_RATE, COUNT_MAX])}
10988 @item @emph{Arguments}:
10989 @multitable @columnfractions .15 .70
10990 @item @var{COUNT} @tab (Optional) shall be a scalar of type default
10991 @code{INTEGER} with @code{INTENT(OUT)}.
10992 @item @var{COUNT_RATE} @tab (Optional) shall be a scalar of type default
10993 @code{INTEGER} with @code{INTENT(OUT)}.
10994 @item @var{COUNT_MAX} @tab (Optional) shall be a scalar of type default
10995 @code{INTEGER} with @code{INTENT(OUT)}.
10998 @item @emph{Example}:
11000 PROGRAM test_system_clock
11001 INTEGER :: count, count_rate, count_max
11002 CALL SYSTEM_CLOCK(count, count_rate, count_max)
11003 WRITE(*,*) count, count_rate, count_max
11007 @item @emph{See also}:
11008 @ref{DATE_AND_TIME}, @ref{CPU_TIME}
11014 @section @code{TAN} --- Tangent function
11017 @cindex trigonometric function, tangent
11021 @item @emph{Description}:
11022 @code{TAN(X)} computes the tangent of @var{X}.
11024 @item @emph{Standard}:
11025 Fortran 77 and later, for a complex argument Fortran 2008 or later
11027 @item @emph{Class}:
11030 @item @emph{Syntax}:
11031 @code{RESULT = TAN(X)}
11033 @item @emph{Arguments}:
11034 @multitable @columnfractions .15 .70
11035 @item @var{X} @tab The type shall be @code{REAL} or @code{COMPLEX}.
11038 @item @emph{Return value}:
11039 The return value has same type and kind as @var{X}.
11041 @item @emph{Example}:
11044 real(8) :: x = 0.165_8
11046 end program test_tan
11049 @item @emph{Specific names}:
11050 @multitable @columnfractions .20 .20 .20 .25
11051 @item Name @tab Argument @tab Return type @tab Standard
11052 @item @code{TAN(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab Fortran 95 and later
11053 @item @code{DTAN(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab Fortran 95 and later
11056 @item @emph{See also}:
11063 @section @code{TANH} --- Hyperbolic tangent function
11066 @cindex hyperbolic tangent
11067 @cindex hyperbolic function, tangent
11068 @cindex tangent, hyperbolic
11071 @item @emph{Description}:
11072 @code{TANH(X)} computes the hyperbolic tangent of @var{X}.
11074 @item @emph{Standard}:
11075 Fortran 77 and later, for a complex argument Fortran 2008 or later
11077 @item @emph{Class}:
11080 @item @emph{Syntax}:
11083 @item @emph{Arguments}:
11084 @multitable @columnfractions .15 .70
11085 @item @var{X} @tab The type shall be @code{REAL} or @code{COMPLEX}.
11088 @item @emph{Return value}:
11089 The return value has same type and kind as @var{X}. If @var{X} is
11090 complex, the imaginary part of the result is in radians. If @var{X}
11091 is @code{REAL}, the return value lies in the range
11092 @math{ - 1 \leq tanh(x) \leq 1 }.
11094 @item @emph{Example}:
11097 real(8) :: x = 2.1_8
11099 end program test_tanh
11102 @item @emph{Specific names}:
11103 @multitable @columnfractions .20 .20 .20 .25
11104 @item Name @tab Argument @tab Return type @tab Standard
11105 @item @code{TANH(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab Fortran 95 and later
11106 @item @code{DTANH(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab Fortran 95 and later
11109 @item @emph{See also}:
11116 @section @code{THIS_IMAGE} --- Function that returns the cosubscript index of this image
11117 @fnindex THIS_IMAGE
11118 @cindex coarray, THIS_IMAGE
11119 @cindex images, index of this image
11122 @item @emph{Description}:
11123 Returns the cosubscript for this image.
11125 @item @emph{Standard}:
11126 Fortran 2008 and later
11128 @item @emph{Class}:
11129 Transformational function
11131 @item @emph{Syntax}:
11132 @multitable @columnfractions .80
11133 @item @code{RESULT = THIS_IMAGE()}
11134 @item @code{RESULT = THIS_IMAGE(COARRAY [, DIM])}
11137 @item @emph{Arguments}:
11138 @multitable @columnfractions .15 .70
11139 @item @var{COARRAY} @tab Coarray of any type (optional; if @var{DIM}
11140 present, required).
11141 @item @var{DIM} @tab default integer scalar (optional). If present,
11142 @var{DIM} shall be between one and the corank of @var{COARRAY}.
11146 @item @emph{Return value}:
11147 Default integer. If @var{COARRAY} is not present, it is scalar and its value
11148 is the index of the invoking image. Otherwise, if @var{DIM} is not present,
11149 a rank-1 array with corank elements is returned, containing the cosubscripts
11150 for @var{COARRAY} specifying the invoking image. If @var{DIM} is present,
11151 a scalar is returned, with the value of the @var{DIM} element of
11152 @code{THIS_IMAGE(COARRAY)}.
11154 @item @emph{Example}:
11156 INTEGER :: value[*]
11158 value = THIS_IMAGE()
11160 IF (THIS_IMAGE() == 1) THEN
11161 DO i = 1, NUM_IMAGES()
11162 WRITE(*,'(2(a,i0))') 'value[', i, '] is ', value[i]
11167 @item @emph{See also}:
11168 @ref{NUM_IMAGES}, @ref{IMAGE_INDEX}
11174 @section @code{TIME} --- Time function
11176 @cindex time, current
11177 @cindex current time
11180 @item @emph{Description}:
11181 Returns the current time encoded as an integer (in the manner of the
11182 UNIX function @code{time(3)}). This value is suitable for passing to
11183 @code{CTIME()}, @code{GMTIME()}, and @code{LTIME()}.
11185 This intrinsic is not fully portable, such as to systems with 32-bit
11186 @code{INTEGER} types but supporting times wider than 32 bits. Therefore,
11187 the values returned by this intrinsic might be, or become, negative, or
11188 numerically less than previous values, during a single run of the
11191 See @ref{TIME8}, for information on a similar intrinsic that might be
11192 portable to more GNU Fortran implementations, though to fewer Fortran
11195 @item @emph{Standard}:
11198 @item @emph{Class}:
11201 @item @emph{Syntax}:
11202 @code{RESULT = TIME()}
11204 @item @emph{Return value}:
11205 The return value is a scalar of type @code{INTEGER(4)}.
11207 @item @emph{See also}:
11208 @ref{CTIME}, @ref{GMTIME}, @ref{LTIME}, @ref{MCLOCK}, @ref{TIME8}
11215 @section @code{TIME8} --- Time function (64-bit)
11217 @cindex time, current
11218 @cindex current time
11221 @item @emph{Description}:
11222 Returns the current time encoded as an integer (in the manner of the
11223 UNIX function @code{time(3)}). This value is suitable for passing to
11224 @code{CTIME()}, @code{GMTIME()}, and @code{LTIME()}.
11226 @emph{Warning:} this intrinsic does not increase the range of the timing
11227 values over that returned by @code{time(3)}. On a system with a 32-bit
11228 @code{time(3)}, @code{TIME8()} will return a 32-bit value, even though
11229 it is converted to a 64-bit @code{INTEGER(8)} value. That means
11230 overflows of the 32-bit value can still occur. Therefore, the values
11231 returned by this intrinsic might be or become negative or numerically
11232 less than previous values during a single run of the compiled program.
11234 @item @emph{Standard}:
11237 @item @emph{Class}:
11240 @item @emph{Syntax}:
11241 @code{RESULT = TIME8()}
11243 @item @emph{Return value}:
11244 The return value is a scalar of type @code{INTEGER(8)}.
11246 @item @emph{See also}:
11247 @ref{CTIME}, @ref{GMTIME}, @ref{LTIME}, @ref{MCLOCK8}, @ref{TIME}
11254 @section @code{TINY} --- Smallest positive number of a real kind
11256 @cindex limits, smallest number
11257 @cindex model representation, smallest number
11260 @item @emph{Description}:
11261 @code{TINY(X)} returns the smallest positive (non zero) number
11262 in the model of the type of @code{X}.
11264 @item @emph{Standard}:
11265 Fortran 95 and later
11267 @item @emph{Class}:
11270 @item @emph{Syntax}:
11271 @code{RESULT = TINY(X)}
11273 @item @emph{Arguments}:
11274 @multitable @columnfractions .15 .70
11275 @item @var{X} @tab Shall be of type @code{REAL}.
11278 @item @emph{Return value}:
11279 The return value is of the same type and kind as @var{X}
11281 @item @emph{Example}:
11282 See @code{HUGE} for an example.
11288 @section @code{TRAILZ} --- Number of trailing zero bits of an integer
11293 @item @emph{Description}:
11294 @code{TRAILZ} returns the number of trailing zero bits of an integer.
11296 @item @emph{Standard}:
11297 Fortran 2008 and later
11299 @item @emph{Class}:
11302 @item @emph{Syntax}:
11303 @code{RESULT = TRAILZ(I)}
11305 @item @emph{Arguments}:
11306 @multitable @columnfractions .15 .70
11307 @item @var{I} @tab Shall be of type @code{INTEGER}.
11310 @item @emph{Return value}:
11311 The type of the return value is the default @code{INTEGER}.
11312 If all the bits of @code{I} are zero, the result value is @code{BIT_SIZE(I)}.
11314 @item @emph{Example}:
11316 PROGRAM test_trailz
11317 WRITE (*,*) TRAILZ(8) ! prints 3
11321 @item @emph{See also}:
11322 @ref{BIT_SIZE}, @ref{LEADZ}, @ref{POPPAR}, @ref{POPCNT}
11328 @section @code{TRANSFER} --- Transfer bit patterns
11334 @item @emph{Description}:
11335 Interprets the bitwise representation of @var{SOURCE} in memory as if it
11336 is the representation of a variable or array of the same type and type
11337 parameters as @var{MOLD}.
11339 This is approximately equivalent to the C concept of @emph{casting} one
11342 @item @emph{Standard}:
11343 Fortran 95 and later
11345 @item @emph{Class}:
11346 Transformational function
11348 @item @emph{Syntax}:
11349 @code{RESULT = TRANSFER(SOURCE, MOLD[, SIZE])}
11351 @item @emph{Arguments}:
11352 @multitable @columnfractions .15 .70
11353 @item @var{SOURCE} @tab Shall be a scalar or an array of any type.
11354 @item @var{MOLD} @tab Shall be a scalar or an array of any type.
11355 @item @var{SIZE} @tab (Optional) shall be a scalar of type
11359 @item @emph{Return value}:
11360 The result has the same type as @var{MOLD}, with the bit level
11361 representation of @var{SOURCE}. If @var{SIZE} is present, the result is
11362 a one-dimensional array of length @var{SIZE}. If @var{SIZE} is absent
11363 but @var{MOLD} is an array (of any size or shape), the result is a one-
11364 dimensional array of the minimum length needed to contain the entirety
11365 of the bitwise representation of @var{SOURCE}. If @var{SIZE} is absent
11366 and @var{MOLD} is a scalar, the result is a scalar.
11368 If the bitwise representation of the result is longer than that of
11369 @var{SOURCE}, then the leading bits of the result correspond to those of
11370 @var{SOURCE} and any trailing bits are filled arbitrarily.
11372 When the resulting bit representation does not correspond to a valid
11373 representation of a variable of the same type as @var{MOLD}, the results
11374 are undefined, and subsequent operations on the result cannot be
11375 guaranteed to produce sensible behavior. For example, it is possible to
11376 create @code{LOGICAL} variables for which @code{@var{VAR}} and
11377 @code{.NOT.@var{VAR}} both appear to be true.
11379 @item @emph{Example}:
11381 PROGRAM test_transfer
11382 integer :: x = 2143289344
11383 print *, transfer(x, 1.0) ! prints "NaN" on i686
11391 @section @code{TRANSPOSE} --- Transpose an array of rank two
11393 @cindex array, transpose
11394 @cindex matrix, transpose
11398 @item @emph{Description}:
11399 Transpose an array of rank two. Element (i, j) of the result has the value
11400 @code{MATRIX(j, i)}, for all i, j.
11402 @item @emph{Standard}:
11403 Fortran 95 and later
11405 @item @emph{Class}:
11406 Transformational function
11408 @item @emph{Syntax}:
11409 @code{RESULT = TRANSPOSE(MATRIX)}
11411 @item @emph{Arguments}:
11412 @multitable @columnfractions .15 .70
11413 @item @var{MATRIX} @tab Shall be an array of any type and have a rank of two.
11416 @item @emph{Return value}:
11417 The result has the same type as @var{MATRIX}, and has shape
11418 @code{(/ m, n /)} if @var{MATRIX} has shape @code{(/ n, m /)}.
11424 @section @code{TRIM} --- Remove trailing blank characters of a string
11426 @cindex string, remove trailing whitespace
11429 @item @emph{Description}:
11430 Removes trailing blank characters of a string.
11432 @item @emph{Standard}:
11433 Fortran 95 and later
11435 @item @emph{Class}:
11436 Transformational function
11438 @item @emph{Syntax}:
11439 @code{RESULT = TRIM(STRING)}
11441 @item @emph{Arguments}:
11442 @multitable @columnfractions .15 .70
11443 @item @var{STRING} @tab Shall be a scalar of type @code{CHARACTER}.
11446 @item @emph{Return value}:
11447 A scalar of type @code{CHARACTER} which length is that of @var{STRING}
11448 less the number of trailing blanks.
11450 @item @emph{Example}:
11453 CHARACTER(len=10), PARAMETER :: s = "GFORTRAN "
11454 WRITE(*,*) LEN(s), LEN(TRIM(s)) ! "10 8", with/without trailing blanks
11458 @item @emph{See also}:
11459 @ref{ADJUSTL}, @ref{ADJUSTR}
11465 @section @code{TTYNAM} --- Get the name of a terminal device.
11467 @cindex system, terminal
11470 @item @emph{Description}:
11471 Get the name of a terminal device. For more information,
11472 see @code{ttyname(3)}.
11474 This intrinsic is provided in both subroutine and function forms;
11475 however, only one form can be used in any given program unit.
11477 @item @emph{Standard}:
11480 @item @emph{Class}:
11481 Subroutine, function
11483 @item @emph{Syntax}:
11484 @multitable @columnfractions .80
11485 @item @code{CALL TTYNAM(UNIT, NAME)}
11486 @item @code{NAME = TTYNAM(UNIT)}
11489 @item @emph{Arguments}:
11490 @multitable @columnfractions .15 .70
11491 @item @var{UNIT} @tab Shall be a scalar @code{INTEGER}.
11492 @item @var{NAME} @tab Shall be of type @code{CHARACTER}.
11495 @item @emph{Example}:
11497 PROGRAM test_ttynam
11500 IF (isatty(unit=unit)) write(*,*) ttynam(unit)
11505 @item @emph{See also}:
11512 @section @code{UBOUND} --- Upper dimension bounds of an array
11514 @cindex array, upper bound
11517 @item @emph{Description}:
11518 Returns the upper bounds of an array, or a single upper bound
11519 along the @var{DIM} dimension.
11520 @item @emph{Standard}:
11521 Fortran 95 and later, with @var{KIND} argument Fortran 2003 and later
11523 @item @emph{Class}:
11526 @item @emph{Syntax}:
11527 @code{RESULT = UBOUND(ARRAY [, DIM [, KIND]])}
11529 @item @emph{Arguments}:
11530 @multitable @columnfractions .15 .70
11531 @item @var{ARRAY} @tab Shall be an array, of any type.
11532 @item @var{DIM} @tab (Optional) Shall be a scalar @code{INTEGER}.
11533 @item @var{KIND}@tab (Optional) An @code{INTEGER} initialization
11534 expression indicating the kind parameter of the result.
11537 @item @emph{Return value}:
11538 The return value is of type @code{INTEGER} and of kind @var{KIND}. If
11539 @var{KIND} is absent, the return value is of default integer kind.
11540 If @var{DIM} is absent, the result is an array of the upper bounds of
11541 @var{ARRAY}. If @var{DIM} is present, the result is a scalar
11542 corresponding to the upper bound of the array along that dimension. If
11543 @var{ARRAY} is an expression rather than a whole array or array
11544 structure component, or if it has a zero extent along the relevant
11545 dimension, the upper bound is taken to be the number of elements along
11546 the relevant dimension.
11548 @item @emph{See also}:
11549 @ref{LBOUND}, @ref{LCOBOUND}
11555 @section @code{UCOBOUND} --- Upper codimension bounds of an array
11557 @cindex coarray, upper bound
11560 @item @emph{Description}:
11561 Returns the upper cobounds of a coarray, or a single upper cobound
11562 along the @var{DIM} codimension.
11563 @item @emph{Standard}:
11564 Fortran 2008 and later
11566 @item @emph{Class}:
11569 @item @emph{Syntax}:
11570 @code{RESULT = UCOBOUND(COARRAY [, DIM [, KIND]])}
11572 @item @emph{Arguments}:
11573 @multitable @columnfractions .15 .70
11574 @item @var{ARRAY} @tab Shall be an coarray, of any type.
11575 @item @var{DIM} @tab (Optional) Shall be a scalar @code{INTEGER}.
11576 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
11577 expression indicating the kind parameter of the result.
11580 @item @emph{Return value}:
11581 The return value is of type @code{INTEGER} and of kind @var{KIND}. If
11582 @var{KIND} is absent, the return value is of default integer kind.
11583 If @var{DIM} is absent, the result is an array of the lower cobounds of
11584 @var{COARRAY}. If @var{DIM} is present, the result is a scalar
11585 corresponding to the lower cobound of the array along that codimension.
11587 @item @emph{See also}:
11588 @ref{LCOBOUND}, @ref{LBOUND}
11594 @section @code{UMASK} --- Set the file creation mask
11596 @cindex file system, file creation mask
11599 @item @emph{Description}:
11600 Sets the file creation mask to @var{MASK}. If called as a function, it
11601 returns the old value. If called as a subroutine and argument @var{OLD}
11602 if it is supplied, it is set to the old value. See @code{umask(2)}.
11604 @item @emph{Standard}:
11607 @item @emph{Class}:
11608 Subroutine, function
11610 @item @emph{Syntax}:
11611 @code{CALL UMASK(MASK [, OLD])}
11612 @code{OLD = UMASK(MASK)}
11614 @item @emph{Arguments}:
11615 @multitable @columnfractions .15 .70
11616 @item @var{MASK} @tab Shall be a scalar of type @code{INTEGER}.
11617 @item @var{OLD} @tab (Optional) Shall be a scalar of type
11626 @section @code{UNLINK} --- Remove a file from the file system
11628 @cindex file system, remove file
11631 @item @emph{Description}:
11632 Unlinks the file @var{PATH}. A null character (@code{CHAR(0)}) can be
11633 used to mark the end of the name in @var{PATH}; otherwise, trailing
11634 blanks in the file name are ignored. If the @var{STATUS} argument is
11635 supplied, it contains 0 on success or a nonzero error code upon return;
11636 see @code{unlink(2)}.
11638 This intrinsic is provided in both subroutine and function forms;
11639 however, only one form can be used in any given program unit.
11641 @item @emph{Standard}:
11644 @item @emph{Class}:
11645 Subroutine, function
11647 @item @emph{Syntax}:
11648 @multitable @columnfractions .80
11649 @item @code{CALL UNLINK(PATH [, STATUS])}
11650 @item @code{STATUS = UNLINK(PATH)}
11653 @item @emph{Arguments}:
11654 @multitable @columnfractions .15 .70
11655 @item @var{PATH} @tab Shall be of default @code{CHARACTER} type.
11656 @item @var{STATUS} @tab (Optional) Shall be of default @code{INTEGER} type.
11659 @item @emph{See also}:
11660 @ref{LINK}, @ref{SYMLNK}
11666 @section @code{UNPACK} --- Unpack an array of rank one into an array
11668 @cindex array, unpacking
11669 @cindex array, increase dimension
11670 @cindex array, scatter elements
11673 @item @emph{Description}:
11674 Store the elements of @var{VECTOR} in an array of higher rank.
11676 @item @emph{Standard}:
11677 Fortran 95 and later
11679 @item @emph{Class}:
11680 Transformational function
11682 @item @emph{Syntax}:
11683 @code{RESULT = UNPACK(VECTOR, MASK, FIELD)}
11685 @item @emph{Arguments}:
11686 @multitable @columnfractions .15 .70
11687 @item @var{VECTOR} @tab Shall be an array of any type and rank one. It
11688 shall have at least as many elements as @var{MASK} has @code{TRUE} values.
11689 @item @var{MASK} @tab Shall be an array of type @code{LOGICAL}.
11690 @item @var{FIELD} @tab Shall be of the same type as @var{VECTOR} and have
11691 the same shape as @var{MASK}.
11694 @item @emph{Return value}:
11695 The resulting array corresponds to @var{FIELD} with @code{TRUE} elements
11696 of @var{MASK} replaced by values from @var{VECTOR} in array element order.
11698 @item @emph{Example}:
11700 PROGRAM test_unpack
11701 integer :: vector(2) = (/1,1/)
11702 logical :: mask(4) = (/ .TRUE., .FALSE., .FALSE., .TRUE. /)
11703 integer :: field(2,2) = 0, unity(2,2)
11705 ! result: unity matrix
11706 unity = unpack(vector, reshape(mask, (/2,2/)), field)
11710 @item @emph{See also}:
11711 @ref{PACK}, @ref{SPREAD}
11717 @section @code{VERIFY} --- Scan a string for the absence of a set of characters
11719 @cindex string, find missing set
11722 @item @emph{Description}:
11723 Verifies that all the characters in a @var{SET} are present in a @var{STRING}.
11725 If @var{BACK} is either absent or equals @code{FALSE}, this function
11726 returns the position of the leftmost character of @var{STRING} that is
11727 not in @var{SET}. If @var{BACK} equals @code{TRUE}, the rightmost position
11728 is returned. If all characters of @var{SET} are found in @var{STRING}, the
11731 @item @emph{Standard}:
11732 Fortran 95 and later, with @var{KIND} argument Fortran 2003 and later
11734 @item @emph{Class}:
11737 @item @emph{Syntax}:
11738 @code{RESULT = VERIFY(STRING, SET[, BACK [, KIND]])}
11740 @item @emph{Arguments}:
11741 @multitable @columnfractions .15 .70
11742 @item @var{STRING} @tab Shall be of type @code{CHARACTER}.
11743 @item @var{SET} @tab Shall be of type @code{CHARACTER}.
11744 @item @var{BACK} @tab (Optional) shall be of type @code{LOGICAL}.
11745 @item @var{KIND} @tab (Optional) An @code{INTEGER} initialization
11746 expression indicating the kind parameter of the result.
11749 @item @emph{Return value}:
11750 The return value is of type @code{INTEGER} and of kind @var{KIND}. If
11751 @var{KIND} is absent, the return value is of default integer kind.
11753 @item @emph{Example}:
11755 PROGRAM test_verify
11756 WRITE(*,*) VERIFY("FORTRAN", "AO") ! 1, found 'F'
11757 WRITE(*,*) VERIFY("FORTRAN", "FOO") ! 3, found 'R'
11758 WRITE(*,*) VERIFY("FORTRAN", "C++") ! 1, found 'F'
11759 WRITE(*,*) VERIFY("FORTRAN", "C++", .TRUE.) ! 7, found 'N'
11760 WRITE(*,*) VERIFY("FORTRAN", "FORTRAN") ! 0' found none
11764 @item @emph{See also}:
11765 @ref{SCAN}, @ref{INDEX intrinsic}
11771 @section @code{XOR} --- Bitwise logical exclusive OR
11773 @cindex bitwise logical exclusive or
11774 @cindex logical exclusive or, bitwise
11777 @item @emph{Description}:
11778 Bitwise logical exclusive or.
11780 This intrinsic routine is provided for backwards compatibility with
11781 GNU Fortran 77. For integer arguments, programmers should consider
11782 the use of the @ref{IEOR} intrinsic and for logical arguments the
11783 @code{.NEQV.} operator, which are both defined by the Fortran standard.
11785 @item @emph{Standard}:
11788 @item @emph{Class}:
11791 @item @emph{Syntax}:
11792 @code{RESULT = XOR(I, J)}
11794 @item @emph{Arguments}:
11795 @multitable @columnfractions .15 .70
11796 @item @var{I} @tab The type shall be either a scalar @code{INTEGER}
11797 type or a scalar @code{LOGICAL} type.
11798 @item @var{J} @tab The type shall be the same as the type of @var{I}.
11801 @item @emph{Return value}:
11802 The return type is either a scalar @code{INTEGER} or a scalar
11803 @code{LOGICAL}. If the kind type parameters differ, then the
11804 smaller kind type is implicitly converted to larger kind, and the
11805 return has the larger kind.
11807 @item @emph{Example}:
11810 LOGICAL :: T = .TRUE., F = .FALSE.
11812 DATA a / Z'F' /, b / Z'3' /
11814 WRITE (*,*) XOR(T, T), XOR(T, F), XOR(F, T), XOR(F, F)
11815 WRITE (*,*) XOR(a, b)
11819 @item @emph{See also}:
11820 Fortran 95 elemental function: @ref{IEOR}
11825 @node Intrinsic Modules
11826 @chapter Intrinsic Modules
11827 @cindex intrinsic Modules
11830 * ISO_FORTRAN_ENV::
11832 * OpenMP Modules OMP_LIB and OMP_LIB_KINDS::
11835 @node ISO_FORTRAN_ENV
11836 @section @code{ISO_FORTRAN_ENV}
11838 @item @emph{Standard}:
11839 Fortran 2003 and later, except when otherwise noted
11842 The @code{ISO_FORTRAN_ENV} module provides the following scalar default-integer
11846 @item @code{ATOMIC_INT_KIND}:
11847 Default-kind integer constant to be used as kind parameter when defining
11848 integer variables used in atomic operations. (Fortran 2008 or later.)
11850 @item @code{ATOMIC_LOGICAL_KIND}:
11851 Default-kind integer constant to be used as kind parameter when defining
11852 logical variables used in atomic operations. (Fortran 2008 or later.)
11854 @item @code{CHARACTER_STORAGE_SIZE}:
11855 Size in bits of the character storage unit.
11857 @item @code{ERROR_UNIT}:
11858 Identifies the preconnected unit used for error reporting.
11860 @item @code{FILE_STORAGE_SIZE}:
11861 Size in bits of the file-storage unit.
11863 @item @code{INPUT_UNIT}:
11864 Identifies the preconnected unit identified by the asterisk
11865 (@code{*}) in @code{READ} statement.
11867 @item @code{INT8}, @code{INT16}, @code{INT32}, @code{INT64}:
11868 Kind type parameters to specify an INTEGER type with a storage
11869 size of 16, 32, and 64 bits. It is negative if a target platform
11870 does not support the particular kind. (Fortran 2008 or later.)
11872 @item @code{IOSTAT_END}:
11873 The value assigned to the variable passed to the IOSTAT= specifier of
11874 an input/output statement if an end-of-file condition occurred.
11876 @item @code{IOSTAT_EOR}:
11877 The value assigned to the variable passed to the IOSTAT= specifier of
11878 an input/output statement if an end-of-record condition occurred.
11880 @item @code{IOSTAT_INQUIRE_INTERNAL_UNIT}:
11881 Scalar default-integer constant, used by @code{INQUIRE} for the
11882 IOSTAT= specifier to denote an that a unit number identifies an
11883 internal unit. (Fortran 2008 or later.)
11885 @item @code{NUMERIC_STORAGE_SIZE}:
11886 The size in bits of the numeric storage unit.
11888 @item @code{OUTPUT_UNIT}:
11889 Identifies the preconnected unit identified by the asterisk
11890 (@code{*}) in @code{WRITE} statement.
11892 @item @code{REAL32}, @code{REAL64}, @code{REAL128}:
11893 Kind type parameters to specify a REAL type with a storage
11894 size of 32, 64, and 128 bits. It is negative if a target platform
11895 does not support the particular kind. (Fortran 2008 or later.)
11897 @item @code{STAT_LOCKED}:
11898 Scalar default-integer constant used as STAT= return value by @code{LOCK} to
11899 denote that the lock variable is locked by the executing image. (Fortran 2008
11902 @item @code{STAT_LOCKED_OTHER_IMAGE}:
11903 Scalar default-integer constant used as STAT= return value by @code{UNLOCK} to
11904 denote that the lock variable is locked by another image. (Fortran 2008 or
11907 @item @code{STAT_STOPPED_IMAGE}:
11908 Positive, scalar default-integer constant used as STAT= return value if the
11909 argument in the statement requires synchronisation with an image, which has
11910 initiated the termination of the execution. (Fortran 2008 or later.)
11912 @item @code{STAT_UNLOCKED}:
11913 Scalar default-integer constant used as STAT= return value by @code{UNLOCK} to
11914 denote that the lock variable is unlocked. (Fortran 2008 or later.)
11919 @node ISO_C_BINDING
11920 @section @code{ISO_C_BINDING}
11922 @item @emph{Standard}:
11923 Fortran 2003 and later, GNU extensions
11926 The following intrinsic procedures are provided by the module; their
11927 definition can be found in the section Intrinsic Procedures of this
11931 @item @code{C_ASSOCIATED}
11932 @item @code{C_F_POINTER}
11933 @item @code{C_F_PROCPOINTER}
11934 @item @code{C_FUNLOC}
11937 @c TODO: Vertical spacing between C_FUNLOC and C_LOC wrong in PDF,
11938 @c don't really know why.
11940 The @code{ISO_C_BINDING} module provides the following named constants of
11941 type default integer, which can be used as KIND type parameters.
11943 In addition to the integer named constants required by the Fortran 2003
11944 standard, GNU Fortran provides as an extension named constants for the
11945 128-bit integer types supported by the C compiler: @code{C_INT128_T,
11946 C_INT_LEAST128_T, C_INT_FAST128_T}.
11948 @multitable @columnfractions .15 .35 .35 .35
11949 @item Fortran Type @tab Named constant @tab C type @tab Extension
11950 @item @code{INTEGER}@tab @code{C_INT} @tab @code{int}
11951 @item @code{INTEGER}@tab @code{C_SHORT} @tab @code{short int}
11952 @item @code{INTEGER}@tab @code{C_LONG} @tab @code{long int}
11953 @item @code{INTEGER}@tab @code{C_LONG_LONG} @tab @code{long long int}
11954 @item @code{INTEGER}@tab @code{C_SIGNED_CHAR} @tab @code{signed char}/@code{unsigned char}
11955 @item @code{INTEGER}@tab @code{C_SIZE_T} @tab @code{size_t}
11956 @item @code{INTEGER}@tab @code{C_INT8_T} @tab @code{int8_t}
11957 @item @code{INTEGER}@tab @code{C_INT16_T} @tab @code{int16_t}
11958 @item @code{INTEGER}@tab @code{C_INT32_T} @tab @code{int32_t}
11959 @item @code{INTEGER}@tab @code{C_INT64_T} @tab @code{int64_t}
11960 @item @code{INTEGER}@tab @code{C_INT128_T} @tab @code{int128_t} @tab Ext.
11961 @item @code{INTEGER}@tab @code{C_INT_LEAST8_T} @tab @code{int_least8_t}
11962 @item @code{INTEGER}@tab @code{C_INT_LEAST16_T} @tab @code{int_least16_t}
11963 @item @code{INTEGER}@tab @code{C_INT_LEAST32_T} @tab @code{int_least32_t}
11964 @item @code{INTEGER}@tab @code{C_INT_LEAST64_T} @tab @code{int_least64_t}
11965 @item @code{INTEGER}@tab @code{C_INT_LEAST128_T}@tab @code{int_least128_t} @tab Ext.
11966 @item @code{INTEGER}@tab @code{C_INT_FAST8_T} @tab @code{int_fast8_t}
11967 @item @code{INTEGER}@tab @code{C_INT_FAST16_T} @tab @code{int_fast16_t}
11968 @item @code{INTEGER}@tab @code{C_INT_FAST32_T} @tab @code{int_fast32_t}
11969 @item @code{INTEGER}@tab @code{C_INT_FAST64_T} @tab @code{int_fast64_t}
11970 @item @code{INTEGER}@tab @code{C_INT_FAST128_T} @tab @code{int_fast128_t} @tab Ext.
11971 @item @code{INTEGER}@tab @code{C_INTMAX_T} @tab @code{intmax_t}
11972 @item @code{INTEGER}@tab @code{C_INTPTR_T} @tab @code{intptr_t}
11973 @item @code{REAL} @tab @code{C_FLOAT} @tab @code{float}
11974 @item @code{REAL} @tab @code{C_DOUBLE} @tab @code{double}
11975 @item @code{REAL} @tab @code{C_LONG_DOUBLE} @tab @code{long double}
11976 @item @code{COMPLEX}@tab @code{C_FLOAT_COMPLEX} @tab @code{float _Complex}
11977 @item @code{COMPLEX}@tab @code{C_DOUBLE_COMPLEX}@tab @code{double _Complex}
11978 @item @code{COMPLEX}@tab @code{C_LONG_DOUBLE_COMPLEX}@tab @code{long double _Complex}
11979 @item @code{LOGICAL}@tab @code{C_BOOL} @tab @code{_Bool}
11980 @item @code{CHARACTER}@tab @code{C_CHAR} @tab @code{char}
11983 Additionally, the following parameters of type @code{CHARACTER(KIND=C_CHAR)}
11986 @multitable @columnfractions .20 .45 .15
11987 @item Name @tab C definition @tab Value
11988 @item @code{C_NULL_CHAR} @tab null character @tab @code{'\0'}
11989 @item @code{C_ALERT} @tab alert @tab @code{'\a'}
11990 @item @code{C_BACKSPACE} @tab backspace @tab @code{'\b'}
11991 @item @code{C_FORM_FEED} @tab form feed @tab @code{'\f'}
11992 @item @code{C_NEW_LINE} @tab new line @tab @code{'\n'}
11993 @item @code{C_CARRIAGE_RETURN} @tab carriage return @tab @code{'\r'}
11994 @item @code{C_HORIZONTAL_TAB} @tab horizontal tab @tab @code{'\t'}
11995 @item @code{C_VERTICAL_TAB} @tab vertical tab @tab @code{'\v'}
11998 Moreover, the following two named constants are defined:
12000 @multitable @columnfractions .20 .80
12001 @item Name @tab Type
12002 @item @code{C_NULL_PTR} @tab @code{C_PTR}
12003 @item @code{C_NULL_FUNPTR} @tab @code{C_FUNPTR}
12006 Both are equivalent to the value @code{NULL} in C.
12008 @node OpenMP Modules OMP_LIB and OMP_LIB_KINDS
12009 @section OpenMP Modules @code{OMP_LIB} and @code{OMP_LIB_KINDS}
12011 @item @emph{Standard}:
12012 OpenMP Application Program Interface v3.0
12016 The OpenMP Fortran runtime library routines are provided both in
12017 a form of two Fortran 90 modules, named @code{OMP_LIB} and
12018 @code{OMP_LIB_KINDS}, and in a form of a Fortran @code{include} file named
12019 @file{omp_lib.h}. The procedures provided by @code{OMP_LIB} can be found
12020 in the @ref{Top,,Introduction,libgomp,GNU OpenMP runtime library} manual,
12021 the named constants defined in the @code{OMP_LIB_KINDS} module are listed
12024 For details refer to the actual
12025 @uref{http://www.openmp.org/mp-documents/spec30.pdf,
12026 OpenMP Application Program Interface v3.0}.
12028 @code{OMP_LIB_KINDS} provides the following scalar default-integer
12032 @item @code{omp_integer_kind}
12033 @item @code{omp_logical_kind}
12034 @item @code{omp_lock_kind}
12035 @item @code{omp_nest_lock_kind}
12036 @item @code{omp_sched_kind}