2 Copyright (C) 2005, 2006, 2007
3 Free Software Foundation, Inc.
4 This is part of the GNU Fortran manual.
5 For copying conditions, see the file gfortran.texi.
7 Permission is granted to copy, distribute and/or modify this document
8 under the terms of the GNU Free Documentation License, Version 1.2 or
9 any later version published by the Free Software Foundation; with the
10 Invariant Sections being ``GNU General Public License'' and ``Funding
11 Free Software'', the Front-Cover texts being (a) (see below), and with
12 the Back-Cover Texts being (b) (see below). A copy of the license is
13 included in the gfdl(7) man page.
16 Some basic guidelines for editing this document:
18 (1) The intrinsic procedures are to be listed in alphabetical order.
19 (2) The generic name is to be used.
20 (3) The specific names are included in the function index and in a
21 table at the end of the node (See ABS entry).
22 (4) Try to maintain the same style for each entry.
28 \gdef\acos{\mathop{\rm acos}\nolimits}
29 \gdef\asin{\mathop{\rm asin}\nolimits}
30 \gdef\atan{\mathop{\rm atan}\nolimits}
31 \gdef\acosh{\mathop{\rm acosh}\nolimits}
32 \gdef\asinh{\mathop{\rm asinh}\nolimits}
33 \gdef\atanh{\mathop{\rm atanh}\nolimits}
37 @node Intrinsic Procedures
38 @chapter Intrinsic Procedures
39 @cindex intrinsic procedures
42 * Introduction: Introduction to Intrinsics
43 * @code{ABORT}: ABORT, Abort the program
44 * @code{ABS}: ABS, Absolute value
45 * @code{ACCESS}: ACCESS, Checks file access modes
46 * @code{ACHAR}: ACHAR, Character in @acronym{ASCII} collating sequence
47 * @code{ACOS}: ACOS, Arccosine function
48 * @code{ACOSH}: ACOSH, Hyperbolic arccosine function
49 * @code{ADJUSTL}: ADJUSTL, Left adjust a string
50 * @code{ADJUSTR}: ADJUSTR, Right adjust a string
51 * @code{AIMAG}: AIMAG, Imaginary part of complex number
52 * @code{AINT}: AINT, Truncate to a whole number
53 * @code{ALARM}: ALARM, Set an alarm clock
54 * @code{ALL}: ALL, Determine if all values are true
55 * @code{ALLOCATED}: ALLOCATED, Status of allocatable entity
56 * @code{AND}: AND, Bitwise logical AND
57 * @code{ANINT}: ANINT, Nearest whole number
58 * @code{ANY}: ANY, Determine if any values are true
59 * @code{ASIN}: ASIN, Arcsine function
60 * @code{ASINH}: ASINH, Hyperbolic arcsine function
61 * @code{ASSOCIATED}: ASSOCIATED, Status of a pointer or pointer/target pair
62 * @code{ATAN}: ATAN, Arctangent function
63 * @code{ATAN2}: ATAN2, Arctangent function
64 * @code{ATANH}: ATANH, Hyperbolic arctangent function
65 * @code{BESJ0}: BESJ0, Bessel function of the first kind of order 0
66 * @code{BESJ1}: BESJ1, Bessel function of the first kind of order 1
67 * @code{BESJN}: BESJN, Bessel function of the first kind
68 * @code{BESY0}: BESY0, Bessel function of the second kind of order 0
69 * @code{BESY1}: BESY1, Bessel function of the second kind of order 1
70 * @code{BESYN}: BESYN, Bessel function of the second kind
71 * @code{BIT_SIZE}: BIT_SIZE, Bit size inquiry function
72 * @code{BTEST}: BTEST, Bit test function
73 * @code{CEILING}: CEILING, Integer ceiling function
74 * @code{CHAR}: CHAR, Integer-to-character conversion function
75 * @code{CHDIR}: CHDIR, Change working directory
76 * @code{CHMOD}: CHMOD, Change access permissions of files
77 * @code{CMPLX}: CMPLX, Complex conversion function
78 * @code{COMMAND_ARGUMENT_COUNT}: COMMAND_ARGUMENT_COUNT, Get number of command line arguments
79 * @code{COMPLEX}: COMPLEX, Complex conversion function
80 * @code{CONJG}: CONJG, Complex conjugate function
81 * @code{COS}: COS, Cosine function
82 * @code{COSH}: COSH, Hyperbolic cosine function
83 * @code{COUNT}: COUNT, Count occurrences of TRUE in an array
84 * @code{CPU_TIME}: CPU_TIME, CPU time subroutine
85 * @code{CSHIFT}: CSHIFT, Circular shift elements of an array
86 * @code{CTIME}: CTIME, Subroutine (or function) to convert a time into a string
87 * @code{DATE_AND_TIME}: DATE_AND_TIME, Date and time subroutine
88 * @code{DBLE}: DBLE, Double precision conversion function
89 * @code{DCMPLX}: DCMPLX, Double complex conversion function
90 * @code{DFLOAT}: DFLOAT, Double precision conversion function
91 * @code{DIGITS}: DIGITS, Significant digits function
92 * @code{DIM}: DIM, Positive difference
93 * @code{DOT_PRODUCT}: DOT_PRODUCT, Dot product function
94 * @code{DPROD}: DPROD, Double product function
95 * @code{DREAL}: DREAL, Double real part function
96 * @code{DTIME}: DTIME, Execution time subroutine (or function)
97 * @code{EOSHIFT}: EOSHIFT, End-off shift elements of an array
98 * @code{EPSILON}: EPSILON, Epsilon function
99 * @code{ERF}: ERF, Error function
100 * @code{ERFC}: ERFC, Complementary error function
101 * @code{ETIME}: ETIME, Execution time subroutine (or function)
102 * @code{EXIT}: EXIT, Exit the program with status.
103 * @code{EXP}: EXP, Exponential function
104 * @code{EXPONENT}: EXPONENT, Exponent function
105 * @code{FDATE}: FDATE, Subroutine (or function) to get the current time as a string
106 * @code{FGET}: FGET, Read a single character in stream mode from stdin
107 * @code{FGETC}: FGETC, Read a single character in stream mode
108 * @code{FLOAT}: FLOAT, Convert integer to default real
109 * @code{FLOOR}: FLOOR, Integer floor function
110 * @code{FLUSH}: FLUSH, Flush I/O unit(s)
111 * @code{FNUM}: FNUM, File number function
112 * @code{FPUT}: FPUT, Write a single character in stream mode to stdout
113 * @code{FPUTC}: FPUTC, Write a single character in stream mode
114 * @code{FRACTION}: FRACTION, Fractional part of the model representation
115 * @code{FREE}: FREE, Memory de-allocation subroutine
116 * @code{FSEEK}: FSEEK, Low level file positioning subroutine
117 * @code{FSTAT}: FSTAT, Get file status
118 * @code{FTELL}: FTELL, Current stream position
119 * @code{GERROR}: GERROR, Get last system error message
120 * @code{GETARG}: GETARG, Get command line arguments
121 * @code{GET_COMMAND}: GET_COMMAND, Get the entire command line
122 * @code{GET_COMMAND_ARGUMENT}: GET_COMMAND_ARGUMENT, Get command line arguments
123 * @code{GETCWD}: GETCWD, Get current working directory
124 * @code{GETENV}: GETENV, Get an environmental variable
125 * @code{GET_ENVIRONMENT_VARIABLE}: GET_ENVIRONMENT_VARIABLE, Get an environmental variable
126 * @code{GETGID}: GETGID, Group ID function
127 * @code{GETLOG}: GETLOG, Get login name
128 * @code{GETPID}: GETPID, Process ID function
129 * @code{GETUID}: GETUID, User ID function
130 * @code{GMTIME}: GMTIME, Convert time to GMT info
131 * @code{HOSTNM}: HOSTNM, Get system host name
132 * @code{HUGE}: HUGE, Largest number of a kind
133 * @code{IACHAR}: IACHAR, Code in @acronym{ASCII} collating sequence
134 * @code{IAND}: IAND, Bitwise logical and
135 * @code{IARGC}: IARGC, Get the number of command line arguments
136 * @code{IBCLR}: IBCLR, Clear bit
137 * @code{IBITS}: IBITS, Bit extraction
138 * @code{IBSET}: IBSET, Set bit
139 * @code{ICHAR}: ICHAR, Character-to-integer conversion function
140 * @code{IDATE}: IDATE, Current local time (day/month/year)
141 * @code{IEOR}: IEOR, Bitwise logical exclusive or
142 * @code{IERRNO}: IERRNO, Function to get the last system error number
143 * @code{INDEX}: INDEX, Position of a substring within a string
144 * @code{INT}: INT, Convert to integer type
145 * @code{INT2}: INT2, Convert to 16-bit integer type
146 * @code{INT8}: INT8, Convert to 64-bit integer type
147 * @code{IOR}: IOR, Bitwise logical or
148 * @code{IRAND}: IRAND, Integer pseudo-random number
149 * @code{ISATTY}: ISATTY, Whether a unit is a terminal device
150 * @code{ISHFT}: ISHFT, Shift bits
151 * @code{ISHFTC}: ISHFTC, Shift bits circularly
152 * @code{ITIME}: ITIME, Current local time (hour/minutes/seconds)
153 * @code{KILL}: KILL, Send a signal to a process
154 * @code{KIND}: KIND, Kind of an entity
155 * @code{LBOUND}: LBOUND, Lower dimension bounds of an array
156 * @code{LEN}: LEN, Length of a character entity
157 * @code{LEN_TRIM}: LEN_TRIM, Length of a character entity without trailing blank characters
158 * @code{LGE}: LGE, Lexical greater than or equal
159 * @code{LGT}: LGT, Lexical greater than
160 * @code{LINK}: LINK, Create a hard link
161 * @code{LLE}: LLE, Lexical less than or equal
162 * @code{LLT}: LLT, Lexical less than
163 * @code{LNBLNK}: LNBLNK, Index of the last non-blank character in a string
164 * @code{LOC}: LOC, Returns the address of a variable
165 * @code{LOG}: LOG, Logarithm function
166 * @code{LOG10}: LOG10, Base 10 logarithm function
167 * @code{LOGICAL}: LOGICAL, Convert to logical type
168 * @code{LONG}: LONG, Convert to integer type
169 * @code{LSHIFT}: LSHIFT, Left shift bits
170 * @code{LSTAT}: LSTAT, Get file status
171 * @code{LTIME}: LTIME, Convert time to local time info
172 * @code{MALLOC}: MALLOC, Dynamic memory allocation function
173 * @code{MATMUL}: MATMUL, matrix multiplication
174 * @code{MAX}: MAX, Maximum value of an argument list
175 * @code{MAXEXPONENT}: MAXEXPONENT, Maximum exponent of a real kind
176 * @code{MAXLOC}: MAXLOC, Location of the maximum value within an array
177 * @code{MAXVAL}: MAXVAL, Maximum value of an array
178 * @code{MCLOCK}: MCLOCK, Time function
179 * @code{MCLOCK8}: MCLOCK8, Time function (64-bit)
180 * @code{MERGE}: MERGE, Merge arrays
181 * @code{MIN}: MIN, Minimum value of an argument list
182 * @code{MINEXPONENT}: MINEXPONENT, Minimum exponent of a real kind
183 * @code{MINLOC}: MINLOC, Location of the minimum value within an array
184 * @code{MINVAL}: MINVAL, Minimum value of an array
185 * @code{MOD}: MOD, Remainder function
186 * @code{MODULO}: MODULO, Modulo function
187 * @code{MOVE_ALLOC}: MOVE_ALLOC, Move allocation from one object to another
188 * @code{MVBITS}: MVBITS, Move bits from one integer to another
189 * @code{NEAREST}: NEAREST, Nearest representable number
190 * @code{NEW_LINE}: NEW_LINE, New line character
191 * @code{NINT}: NINT, Nearest whole number
192 * @code{NOT}: NOT, Logical negation
193 * @code{NULL}: NULL, Function that returns an disassociated pointer
194 * @code{OR}: OR, Bitwise logical OR
195 * @code{PACK}: PACK, Pack an array into an array of rank one
196 * @code{PERROR}: PERROR, Print system error message
197 * @code{PRECISION}: PRECISION, Decimal precision of a real kind
198 * @code{PRESENT}: PRESENT, Determine whether an optional dummy argument is specified
199 * @code{PRODUCT}: PRODUCT, Product of array elements
200 * @code{RADIX}: RADIX, Base of a data model
201 * @code{RANDOM_NUMBER}: RANDOM_NUMBER, Pseudo-random number
202 * @code{RANDOM_SEED}: RANDOM_SEED, Initialize a pseudo-random number sequence
203 * @code{RAND}: RAND, Real pseudo-random number
204 * @code{RANGE}: RANGE, Decimal exponent range of a real kind
205 * @code{RAN}: RAN, Real pseudo-random number
206 * @code{REAL}: REAL, Convert to real type
207 * @code{RENAME}: RENAME, Rename a file
208 * @code{REPEAT}: REPEAT, Repeated string concatenation
209 * @code{RESHAPE}: RESHAPE, Function to reshape an array
210 * @code{RRSPACING}: RRSPACING, Reciprocal of the relative spacing
211 * @code{RSHIFT}: RSHIFT, Right shift bits
212 * @code{SCALE}: SCALE, Scale a real value
213 * @code{SCAN}: SCAN, Scan a string for the presence of a set of characters
214 * @code{SECNDS}: SECNDS, Time function
215 * @code{SECOND}: SECOND, CPU time function
216 * @code{SELECTED_INT_KIND}: SELECTED_INT_KIND, Choose integer kind
217 * @code{SELECTED_REAL_KIND}: SELECTED_REAL_KIND, Choose real kind
218 * @code{SET_EXPONENT}: SET_EXPONENT, Set the exponent of the model
219 * @code{SHAPE}: SHAPE, Determine the shape of an array
220 * @code{SIGN}: SIGN, Sign copying function
221 * @code{SIGNAL}: SIGNAL, Signal handling subroutine (or function)
222 * @code{SIN}: SIN, Sine function
223 * @code{SINH}: SINH, Hyperbolic sine function
224 * @code{SIZE}: SIZE, Function to determine the size of an array
225 * @code{SIZEOF}: SIZEOF, Determine the size in bytes of an expression
226 * @code{SLEEP}: SLEEP, Sleep for the specified number of seconds
227 * @code{SNGL}: SNGL, Convert double precision real to default real
228 * @code{SPACING}: SPACING, Smallest distance between two numbers of a given type
229 * @code{SPREAD}: SPREAD, Add a dimension to an array
230 * @code{SQRT}: SQRT, Square-root function
231 * @code{SRAND}: SRAND, Reinitialize the random number generator
232 * @code{STAT}: STAT, Get file status
233 * @code{SUM}: SUM, Sum of array elements
234 * @code{SYMLNK}: SYMLNK, Create a symbolic link
235 * @code{SYSTEM}: SYSTEM, Execute a shell command
236 * @code{SYSTEM_CLOCK}: SYSTEM_CLOCK, Time function
237 * @code{TAN}: TAN, Tangent function
238 * @code{TANH}: TANH, Hyperbolic tangent function
239 * @code{TIME}: TIME, Time function
240 * @code{TIME8}: TIME8, Time function (64-bit)
241 * @code{TINY}: TINY, Smallest positive number of a real kind
242 * @code{TRANSFER}: TRANSFER, Transfer bit patterns
243 * @code{TRANSPOSE}: TRANSPOSE, Transpose an array of rank two
244 * @code{TRIM}: TRIM, Remove trailing blank characters of a string
245 * @code{TTYNAM}: TTYNAM, Get the name of a terminal device.
246 * @code{UBOUND}: UBOUND, Upper dimension bounds of an array
247 * @code{UMASK}: UMASK, Set the file creation mask
248 * @code{UNLINK}: UNLINK, Remove a file from the file system
249 * @code{UNPACK}: UNPACK, Unpack an array of rank one into an array
250 * @code{VERIFY}: VERIFY, Scan a string for the absence of a set of characters
251 * @code{XOR}: XOR, Bitwise logical exclusive or
254 @node Introduction to Intrinsics
255 @section Introduction to intrinsic procedures
257 The intrinsic procedures provided by GNU Fortran include all of the
258 intrinsic procedures required by the Fortran 95 standard, a set of
259 intrinsic procedures for backwards compatibility with G77, and a small
260 selection of intrinsic procedures from the Fortran 2003 standard. Any
261 conflict between a description here and a description in either the
262 Fortran 95 standard or the Fortran 2003 standard is unintentional, and
263 the standard(s) should be considered authoritative.
265 The enumeration of the @code{KIND} type parameter is processor defined in
266 the Fortran 95 standard. GNU Fortran defines the default integer type and
267 default real type by @code{INTEGER(KIND=4)} and @code{REAL(KIND=4)},
268 respectively. The standard mandates that both data types shall have
269 another kind, which have more precision. On typical target architectures
270 supported by @command{gfortran}, this kind type parameter is @code{KIND=8}.
271 Hence, @code{REAL(KIND=8)} and @code{DOUBLE PRECISION} are equivalent.
272 In the description of generic intrinsic procedures, the kind type parameter
273 will be specified by @code{KIND=*}, and in the description of specific
274 names for an intrinsic procedure the kind type parameter will be explicitly
275 given (e.g., @code{REAL(KIND=4)} or @code{REAL(KIND=8)}). Finally, for
276 brevity the optional @code{KIND=} syntax will be omitted.
278 Many of the intrinsic procedures take one or more optional arguments.
279 This document follows the convention used in the Fortran 95 standard,
280 and denotes such arguments by square brackets.
282 GNU Fortran offers the @option{-std=f95} and @option{-std=gnu} options,
283 which can be used to restrict the set of intrinsic procedures to a
284 given standard. By default, @command{gfortran} sets the @option{-std=gnu}
285 option, and so all intrinsic procedures described here are accepted. There
286 is one caveat. For a select group of intrinsic procedures, @command{g77}
287 implemented both a function and a subroutine. Both classes
288 have been implemented in @command{gfortran} for backwards compatibility
289 with @command{g77}. It is noted here that these functions and subroutines
290 cannot be intermixed in a given subprogram. In the descriptions that follow,
291 the applicable standard for each intrinsic procedure is noted.
296 @section @code{ABORT} --- Abort the program
298 @cindex program termination, with core dump
299 @cindex terminate program, with core dump
303 @item @emph{Description}:
304 @code{ABORT} causes immediate termination of the program. On operating
305 systems that support a core dump, @code{ABORT} will produce a core dump,
306 which is suitable for debugging purposes.
308 @item @emph{Standard}:
312 Non-elemental subroutine
317 @item @emph{Return value}:
320 @item @emph{Example}:
323 integer :: i = 1, j = 2
324 if (i /= j) call abort
325 end program test_abort
328 @item @emph{See also}:
329 @ref{EXIT}, @ref{KILL}
336 @section @code{ABS} --- Absolute value
343 @cindex absolute value
346 @item @emph{Description}:
347 @code{ABS(X)} computes the absolute value of @code{X}.
349 @item @emph{Standard}:
350 F77 and later, has overloads that are GNU extensions
356 @code{RESULT = ABS(X)}
358 @item @emph{Arguments}:
359 @multitable @columnfractions .15 .70
360 @item @var{X} @tab The type of the argument shall be an @code{INTEGER(*)},
361 @code{REAL(*)}, or @code{COMPLEX(*)}.
364 @item @emph{Return value}:
365 The return value is of the same type and
366 kind as the argument except the return value is @code{REAL(*)} for a
367 @code{COMPLEX(*)} argument.
369 @item @emph{Example}:
374 complex :: z = (-1.e0,0.e0)
381 @item @emph{Specific names}:
382 @multitable @columnfractions .20 .20 .20 .25
383 @item Name @tab Argument @tab Return type @tab Standard
384 @item @code{CABS(Z)} @tab @code{COMPLEX(4) Z} @tab @code{REAL(4)} @tab F77 and later
385 @item @code{DABS(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab F77 and later
386 @item @code{IABS(I)} @tab @code{INTEGER(4) I} @tab @code{INTEGER(4)} @tab F77 and later
387 @item @code{ZABS(Z)} @tab @code{COMPLEX(8) Z} @tab @code{COMPLEX(8)} @tab GNU extension
388 @item @code{CDABS(Z)} @tab @code{COMPLEX(8) Z} @tab @code{COMPLEX(8)} @tab GNU extension
395 @section @code{ACCESS} --- Checks file access modes
397 @cindex file system, access mode
400 @item @emph{Description}:
401 @code{ACCESS(NAME, MODE)} checks whether the file @var{NAME}
402 exists, is readable, writable or executable. Except for the
403 executable check, @code{ACCESS} can be replaced by
404 Fortran 95's @code{INQUIRE}.
406 @item @emph{Standard}:
413 @code{RESULT = ACCESS(NAME, MODE)}
415 @item @emph{Arguments}:
416 @multitable @columnfractions .15 .70
417 @item @var{NAME} @tab Scalar @code{CHARACTER} with the file name.
418 Tailing blank are ignored unless the character @code{achar(0)} is
419 present, then all characters up to and excluding @code{achar(0)} are
421 @item @var{MODE} @tab Scalar @code{CHARACTER} with the file access mode,
422 may be any concatenation of @code{"r"} (readable), @code{"w"} (writable)
423 and @code{"x"} (executable), or @code{" "} to check for existence.
426 @item @emph{Return value}:
427 Returns a scalar @code{INTEGER}, which is @code{0} if the file is
428 accessible in the given mode; otherwise or if an invalid argument
429 has been given for @code{MODE} the value @code{1} is returned.
431 @item @emph{Example}:
435 character(len=*), parameter :: file = 'test.dat'
436 character(len=*), parameter :: file2 = 'test.dat '//achar(0)
437 if(access(file,' ') == 0) print *, trim(file),' is exists'
438 if(access(file,'r') == 0) print *, trim(file),' is readable'
439 if(access(file,'w') == 0) print *, trim(file),' is writable'
440 if(access(file,'x') == 0) print *, trim(file),' is executable'
441 if(access(file2,'rwx') == 0) &
442 print *, trim(file2),' is readable, writable and executable'
443 end program access_test
445 @item @emph{Specific names}:
446 @item @emph{See also}:
453 @section @code{ACHAR} --- Character in @acronym{ASCII} collating sequence
455 @cindex @acronym{ASCII} collating sequence
456 @cindex collating sequence, @acronym{ASCII}
459 @item @emph{Description}:
460 @code{ACHAR(I)} returns the character located at position @code{I}
461 in the @acronym{ASCII} collating sequence.
463 @item @emph{Standard}:
470 @code{RESULT = ACHAR(I)}
472 @item @emph{Arguments}:
473 @multitable @columnfractions .15 .70
474 @item @var{I} @tab The type shall be @code{INTEGER(*)}.
477 @item @emph{Return value}:
478 The return value is of type @code{CHARACTER} with a length of one. The
479 kind type parameter is the same as @code{KIND('A')}.
481 @item @emph{Example}:
486 end program test_achar
490 See @ref{ICHAR} for a discussion of converting between numerical values
491 and formatted string representations.
493 @item @emph{See also}:
494 @ref{CHAR}, @ref{IACHAR}, @ref{ICHAR}
501 @section @code{ACOS} --- Arccosine function
504 @cindex trigonometric function, cosine, inverse
505 @cindex cosine, inverse
508 @item @emph{Description}:
509 @code{ACOS(X)} computes the arccosine of @var{X} (inverse of @code{COS(X)}).
511 @item @emph{Standard}:
518 @code{RESULT = ACOS(X)}
520 @item @emph{Arguments}:
521 @multitable @columnfractions .15 .70
522 @item @var{X} @tab The type shall be @code{REAL(*)} with a magnitude that is
526 @item @emph{Return value}:
527 The return value is of type @code{REAL(*)} and it lies in the
528 range @math{ 0 \leq \acos(x) \leq \pi}. The kind type parameter
529 is the same as @var{X}.
531 @item @emph{Example}:
534 real(8) :: x = 0.866_8
536 end program test_acos
539 @item @emph{Specific names}:
540 @multitable @columnfractions .20 .20 .20 .25
541 @item Name @tab Argument @tab Return type @tab Standard
542 @item @code{DACOS(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab F77 and later
545 @item @emph{See also}:
546 Inverse function: @ref{COS}
553 @section @code{ACOSH} --- Hyperbolic arccosine function
556 @cindex area hyperbolic cosine
557 @cindex hyperbolic arccosine
558 @cindex hyperbolic function, cosine, inverse
559 @cindex cosine, hyperbolic, inverse
562 @item @emph{Description}:
563 @code{ACOSH(X)} computes the hyperbolic arccosine of @var{X} (inverse of
566 @item @emph{Standard}:
573 @code{RESULT = ACOSH(X)}
575 @item @emph{Arguments}:
576 @multitable @columnfractions .15 .70
577 @item @var{X} @tab The type shall be @code{REAL(*)} with a magnitude that is
578 greater or equal to one.
581 @item @emph{Return value}:
582 The return value is of type @code{REAL(*)} and it lies in the
583 range @math{0 \leq \acosh (x) \leq \infty}.
585 @item @emph{Example}:
588 REAL(8), DIMENSION(3) :: x = (/ 1.0, 2.0, 3.0 /)
593 @item @emph{Specific names}:
594 @multitable @columnfractions .20 .20 .20 .25
595 @item Name @tab Argument @tab Return type @tab Standard
596 @item @code{DACOSH(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU extension
599 @item @emph{See also}:
600 Inverse function: @ref{COSH}
606 @section @code{ADJUSTL} --- Left adjust a string
608 @cindex string, adjust left
609 @cindex adjust string
612 @item @emph{Description}:
613 @code{ADJUSTL(STR)} will left adjust a string by removing leading spaces.
614 Spaces are inserted at the end of the string as needed.
616 @item @emph{Standard}:
623 @code{RESULT = ADJUSTL(STR)}
625 @item @emph{Arguments}:
626 @multitable @columnfractions .15 .70
627 @item @var{STR} @tab The type shall be @code{CHARACTER}.
630 @item @emph{Return value}:
631 The return value is of type @code{CHARACTER} where leading spaces
632 are removed and the same number of spaces are inserted on the end
635 @item @emph{Example}:
638 character(len=20) :: str = ' gfortran'
641 end program test_adjustl
644 @item @emph{See also}:
645 @ref{ADJUSTR}, @ref{TRIM}
651 @section @code{ADJUSTR} --- Right adjust a string
653 @cindex string, adjust right
654 @cindex adjust string
657 @item @emph{Description}:
658 @code{ADJUSTR(STR)} will right adjust a string by removing trailing spaces.
659 Spaces are inserted at the start of the string as needed.
661 @item @emph{Standard}:
668 @code{RESULT = ADJUSTR(STR)}
670 @item @emph{Arguments}:
671 @multitable @columnfractions .15 .70
672 @item @var{STR} @tab The type shall be @code{CHARACTER}.
675 @item @emph{Return value}:
676 The return value is of type @code{CHARACTER} where trailing spaces
677 are removed and the same number of spaces are inserted at the start
680 @item @emph{Example}:
683 character(len=20) :: str = 'gfortran'
686 end program test_adjustr
689 @item @emph{See also}:
690 @ref{ADJUSTL}, @ref{TRIM}
696 @section @code{AIMAG} --- Imaginary part of complex number
701 @cindex complex numbers, imaginary part
704 @item @emph{Description}:
705 @code{AIMAG(Z)} yields the imaginary part of complex argument @code{Z}.
706 The @code{IMAG(Z)} and @code{IMAGPART(Z)} intrinsic functions are provided
707 for compatibility with @command{g77}, and their use in new code is
708 strongly discouraged.
710 @item @emph{Standard}:
711 F77 and later, has overloads that are GNU extensions
717 @code{RESULT = AIMAG(Z)}
719 @item @emph{Arguments}:
720 @multitable @columnfractions .15 .70
721 @item @var{Z} @tab The type of the argument shall be @code{COMPLEX(*)}.
724 @item @emph{Return value}:
725 The return value is of type real with the
726 kind type parameter of the argument.
728 @item @emph{Example}:
733 z4 = cmplx(1.e0_4, 0.e0_4)
734 z8 = cmplx(0.e0_8, 1.e0_8)
735 print *, aimag(z4), dimag(z8)
736 end program test_aimag
739 @item @emph{Specific names}:
740 @multitable @columnfractions .20 .20 .20 .25
741 @item Name @tab Argument @tab Return type @tab Standard
742 @item @code{DIMAG(Z)} @tab @code{COMPLEX(8) Z} @tab @code{REAL(8)} @tab GNU extension
743 @item @code{IMAG(Z)} @tab @code{COMPLEX(*) Z} @tab @code{REAL(*)} @tab GNU extension
744 @item @code{IMAGPART(Z)} @tab @code{COMPLEX(*) Z} @tab @code{REAL(*)} @tab GNU extension
751 @section @code{AINT} --- Truncate to a whole number
755 @cindex rounding, floor
758 @item @emph{Description}:
759 @code{AINT(X [, KIND])} truncates its argument to a whole number.
761 @item @emph{Standard}:
768 @code{RESULT = AINT(X [, KIND])}
770 @item @emph{Arguments}:
771 @multitable @columnfractions .15 .70
772 @item @var{X} @tab The type of the argument shall be @code{REAL(*)}.
773 @item @var{KIND} @tab (Optional) An @code{INTEGER(*)} initialization
774 expression indicating the kind parameter of
778 @item @emph{Return value}:
779 The return value is of type real with the kind type parameter of the
780 argument if the optional @var{KIND} is absent; otherwise, the kind
781 type parameter will be given by @var{KIND}. If the magnitude of
782 @var{X} is less than one, then @code{AINT(X)} returns zero. If the
783 magnitude is equal to or greater than one, then it returns the largest
784 whole number that does not exceed its magnitude. The sign is the same
785 as the sign of @var{X}.
787 @item @emph{Example}:
794 print *, aint(x4), dint(x8)
796 end program test_aint
799 @item @emph{Specific names}:
800 @multitable @columnfractions .20 .20 .20 .25
801 @item Name @tab Argument @tab Return type @tab Standard
802 @item @code{DINT(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab F77 and later
809 @section @code{ALARM} --- Execute a routine after a given delay
811 @cindex delayed execution
814 @item @emph{Description}:
815 @code{ALARM(SECONDS, HANDLER [, STATUS])} causes external subroutine @var{HANDLER}
816 to be executed after a delay of @var{SECONDS} by using @code{alarm(2)} to
817 set up a signal and @code{signal(2)} to catch it. If @var{STATUS} is
818 supplied, it will be returned with the number of seconds remaining until
819 any previously scheduled alarm was due to be delivered, or zero if there
820 was no previously scheduled alarm.
822 @item @emph{Standard}:
829 @code{CALL ALARM(SECONDS, HANDLER [, STATUS])}
831 @item @emph{Arguments}:
832 @multitable @columnfractions .15 .70
833 @item @var{SECONDS} @tab The type of the argument shall be a scalar
834 @code{INTEGER}. It is @code{INTENT(IN)}.
835 @item @var{HANDLER} @tab Signal handler (@code{INTEGER FUNCTION} or
836 @code{SUBROUTINE}) or dummy/global @code{INTEGER} scalar. The scalar
837 values may be either @code{SIG_IGN=1} to ignore the alarm generated
838 or @code{SIG_DFL=0} to set the default action. It is @code{INTENT(IN)}.
839 @item @var{STATUS} @tab (Optional) @var{STATUS} shall be a scalar
840 variable of the default @code{INTEGER} kind. It is @code{INTENT(OUT)}.
843 @item @emph{Example}:
846 external handler_print
848 call alarm (3, handler_print, i)
851 end program test_alarm
853 This will cause the external routine @var{handler_print} to be called
860 @section @code{ALL} --- All values in @var{MASK} along @var{DIM} are true
862 @cindex array, apply condition
863 @cindex array, condition testing
866 @item @emph{Description}:
867 @code{ALL(MASK [, DIM])} determines if all the values are true in @var{MASK}
868 in the array along dimension @var{DIM}.
870 @item @emph{Standard}:
874 transformational function
877 @code{RESULT = ALL(MASK [, DIM])}
879 @item @emph{Arguments}:
880 @multitable @columnfractions .15 .70
881 @item @var{MASK} @tab The type of the argument shall be @code{LOGICAL(*)} and
882 it shall not be scalar.
883 @item @var{DIM} @tab (Optional) @var{DIM} shall be a scalar integer
884 with a value that lies between one and the rank of @var{MASK}.
887 @item @emph{Return value}:
888 @code{ALL(MASK)} returns a scalar value of type @code{LOGICAL(*)} where
889 the kind type parameter is the same as the kind type parameter of
890 @var{MASK}. If @var{DIM} is present, then @code{ALL(MASK, DIM)} returns
891 an array with the rank of @var{MASK} minus 1. The shape is determined from
892 the shape of @var{MASK} where the @var{DIM} dimension is elided.
896 @code{ALL(MASK)} is true if all elements of @var{MASK} are true.
897 It also is true if @var{MASK} has zero size; otherwise, it is false.
899 If the rank of @var{MASK} is one, then @code{ALL(MASK,DIM)} is equivalent
900 to @code{ALL(MASK)}. If the rank is greater than one, then @code{ALL(MASK,DIM)}
901 is determined by applying @code{ALL} to the array sections.
904 @item @emph{Example}:
908 l = all((/.true., .true., .true./))
913 integer a(2,3), b(2,3)
917 print *, all(a .eq. b, 1)
918 print *, all(a .eq. b, 2)
919 end subroutine section
927 @section @code{ALLOCATED} --- Status of an allocatable entity
929 @cindex allocation, status
932 @item @emph{Description}:
933 @code{ALLOCATED(X)} checks the status of whether @var{X} is allocated.
935 @item @emph{Standard}:
942 @code{RESULT = ALLOCATED(X)}
944 @item @emph{Arguments}:
945 @multitable @columnfractions .15 .70
946 @item @var{X} @tab The argument shall be an @code{ALLOCATABLE} array.
949 @item @emph{Return value}:
950 The return value is a scalar @code{LOGICAL} with the default logical
951 kind type parameter. If @var{X} is allocated, @code{ALLOCATED(X)}
952 is @code{.TRUE.}; otherwise, it returns the @code{.TRUE.}
954 @item @emph{Example}:
956 program test_allocated
958 real(4), allocatable :: x(:)
959 if (allocated(x) .eqv. .false.) allocate(x(i))
960 end program test_allocated
967 @section @code{AND} --- Bitwise logical AND
969 @cindex bitwise logical and
970 @cindex logical and, bitwise
973 @item @emph{Description}:
974 Bitwise logical @code{AND}.
976 This intrinsic routine is provided for backwards compatibility with
977 GNU Fortran 77. For integer arguments, programmers should consider
978 the use of the @ref{IAND} intrinsic defined by the Fortran standard.
980 @item @emph{Standard}:
984 Non-elemental function
987 @code{RESULT = AND(I, J)}
989 @item @emph{Arguments}:
990 @multitable @columnfractions .15 .70
991 @item @var{I} @tab The type shall be either @code{INTEGER(*)} or @code{LOGICAL}.
992 @item @var{J} @tab The type shall be either @code{INTEGER(*)} or @code{LOGICAL}.
995 @item @emph{Return value}:
996 The return type is either @code{INTEGER(*)} or @code{LOGICAL} after
997 cross-promotion of the arguments.
999 @item @emph{Example}:
1002 LOGICAL :: T = .TRUE., F = .FALSE.
1004 DATA a / Z'F' /, b / Z'3' /
1006 WRITE (*,*) AND(T, T), AND(T, F), AND(F, T), AND(F, F)
1007 WRITE (*,*) AND(a, b)
1011 @item @emph{See also}:
1012 F95 elemental function: @ref{IAND}
1018 @section @code{ANINT} --- Nearest whole number
1022 @cindex rounding, ceiling
1025 @item @emph{Description}:
1026 @code{ANINT(X [, KIND])} rounds its argument to the nearest whole number.
1028 @item @emph{Standard}:
1034 @item @emph{Syntax}:
1035 @code{RESULT = ANINT(X [, KIND])}
1037 @item @emph{Arguments}:
1038 @multitable @columnfractions .15 .70
1039 @item @var{X} @tab The type of the argument shall be @code{REAL(*)}.
1040 @item @var{KIND} @tab (Optional) An @code{INTEGER(*)} initialization
1041 expression indicating the kind parameter of
1045 @item @emph{Return value}:
1046 The return value is of type real with the kind type parameter of the
1047 argument if the optional @var{KIND} is absent; otherwise, the kind
1048 type parameter will be given by @var{KIND}. If @var{X} is greater than
1049 zero, then @code{ANINT(X)} returns @code{AINT(X+0.5)}. If @var{X} is
1050 less than or equal to zero, then it returns @code{AINT(X-0.5)}.
1052 @item @emph{Example}:
1059 print *, anint(x4), dnint(x8)
1061 end program test_anint
1064 @item @emph{Specific names}:
1065 @multitable @columnfractions .20 .20 .20 .25
1066 @item Name @tab Argument @tab Return type @tab Standard
1067 @item @code{DNINT(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab F77 and later
1074 @section @code{ANY} --- Any value in @var{MASK} along @var{DIM} is true
1076 @cindex array, apply condition
1077 @cindex array, condition testing
1080 @item @emph{Description}:
1081 @code{ANY(MASK [, DIM])} determines if any of the values in the logical array
1082 @var{MASK} along dimension @var{DIM} are @code{.TRUE.}.
1084 @item @emph{Standard}:
1088 transformational function
1090 @item @emph{Syntax}:
1091 @code{RESULT = ANY(MASK [, DIM])}
1093 @item @emph{Arguments}:
1094 @multitable @columnfractions .15 .70
1095 @item @var{MASK} @tab The type of the argument shall be @code{LOGICAL(*)} and
1096 it shall not be scalar.
1097 @item @var{DIM} @tab (Optional) @var{DIM} shall be a scalar integer
1098 with a value that lies between one and the rank of @var{MASK}.
1101 @item @emph{Return value}:
1102 @code{ANY(MASK)} returns a scalar value of type @code{LOGICAL(*)} where
1103 the kind type parameter is the same as the kind type parameter of
1104 @var{MASK}. If @var{DIM} is present, then @code{ANY(MASK, DIM)} returns
1105 an array with the rank of @var{MASK} minus 1. The shape is determined from
1106 the shape of @var{MASK} where the @var{DIM} dimension is elided.
1110 @code{ANY(MASK)} is true if any element of @var{MASK} is true;
1111 otherwise, it is false. It also is false if @var{MASK} has zero size.
1113 If the rank of @var{MASK} is one, then @code{ANY(MASK,DIM)} is equivalent
1114 to @code{ANY(MASK)}. If the rank is greater than one, then @code{ANY(MASK,DIM)}
1115 is determined by applying @code{ANY} to the array sections.
1118 @item @emph{Example}:
1122 l = any((/.true., .true., .true./))
1127 integer a(2,3), b(2,3)
1131 print *, any(a .eq. b, 1)
1132 print *, any(a .eq. b, 2)
1133 end subroutine section
1134 end program test_any
1141 @section @code{ASIN} --- Arcsine function
1144 @cindex trigonometric function, sine, inverse
1145 @cindex sine, inverse
1148 @item @emph{Description}:
1149 @code{ASIN(X)} computes the arcsine of its @var{X} (inverse of @code{SIN(X)}).
1151 @item @emph{Standard}:
1157 @item @emph{Syntax}:
1158 @code{RESULT = ASIN(X)}
1160 @item @emph{Arguments}:
1161 @multitable @columnfractions .15 .70
1162 @item @var{X} @tab The type shall be @code{REAL(*)}, and a magnitude that is
1166 @item @emph{Return value}:
1167 The return value is of type @code{REAL(*)} and it lies in the
1168 range @math{-\pi / 2 \leq \asin (x) \leq \pi / 2}. The kind type
1169 parameter is the same as @var{X}.
1171 @item @emph{Example}:
1174 real(8) :: x = 0.866_8
1176 end program test_asin
1179 @item @emph{Specific names}:
1180 @multitable @columnfractions .20 .20 .20 .25
1181 @item Name @tab Argument @tab Return type @tab Standard
1182 @item @code{DASIN(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab F77 and later
1185 @item @emph{See also}:
1186 Inverse function: @ref{SIN}
1193 @section @code{ASINH} --- Hyperbolic arcsine function
1196 @cindex area hyperbolic sine
1197 @cindex hyperbolic arcsine
1198 @cindex hyperbolic function, sine, inverse
1199 @cindex sine, hyperbolic, inverse
1202 @item @emph{Description}:
1203 @code{ASINH(X)} computes the hyperbolic arcsine of @var{X} (inverse of @code{SINH(X)}).
1205 @item @emph{Standard}:
1211 @item @emph{Syntax}:
1212 @code{RESULT = ASINH(X)}
1214 @item @emph{Arguments}:
1215 @multitable @columnfractions .15 .70
1216 @item @var{X} @tab The type shall be @code{REAL(*)}, with @var{X} a real number.
1219 @item @emph{Return value}:
1220 The return value is of type @code{REAL(*)} and it lies in the
1221 range @math{-\infty \leq \asinh (x) \leq \infty}.
1223 @item @emph{Example}:
1226 REAL(8), DIMENSION(3) :: x = (/ -1.0, 0.0, 1.0 /)
1227 WRITE (*,*) ASINH(x)
1231 @item @emph{Specific names}:
1232 @multitable @columnfractions .20 .20 .20 .25
1233 @item Name @tab Argument @tab Return type @tab Standard
1234 @item @code{DASINH(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU extension.
1237 @item @emph{See also}:
1238 Inverse function: @ref{SINH}
1244 @section @code{ASSOCIATED} --- Status of a pointer or pointer/target pair
1246 @cindex pointer, status
1247 @cindex association status
1250 @item @emph{Description}:
1251 @code{ASSOCIATED(PTR [, TGT])} determines the status of the pointer @var{PTR}
1252 or if @var{PTR} is associated with the target @var{TGT}.
1254 @item @emph{Standard}:
1260 @item @emph{Syntax}:
1261 @code{RESULT = ASSOCIATED(PTR [, TGT])}
1263 @item @emph{Arguments}:
1264 @multitable @columnfractions .15 .70
1265 @item @var{PTR} @tab @var{PTR} shall have the @code{POINTER} attribute and
1266 it can be of any type.
1267 @item @var{TGT} @tab (Optional) @var{TGT} shall be a @code{POINTER} or
1268 a @code{TARGET}. It must have the same type, kind type parameter, and
1269 array rank as @var{PTR}.
1271 The status of neither @var{PTR} nor @var{TGT} can be undefined.
1273 @item @emph{Return value}:
1274 @code{ASSOCIATED(PTR)} returns a scalar value of type @code{LOGICAL(4)}.
1275 There are several cases:
1277 @item (A) If the optional @var{TGT} is not present, then @code{ASSOCIATED(PTR)}
1278 is true if @var{PTR} is associated with a target; otherwise, it returns false.
1279 @item (B) If @var{TGT} is present and a scalar target, the result is true if
1281 is not a 0 sized storage sequence and the target associated with @var{PTR}
1282 occupies the same storage units. If @var{PTR} is disassociated, then the
1284 @item (C) If @var{TGT} is present and an array target, the result is true if
1285 @var{TGT} and @var{PTR} have the same shape, are not 0 sized arrays, are
1286 arrays whose elements are not 0 sized storage sequences, and @var{TGT} and
1287 @var{PTR} occupy the same storage units in array element order.
1288 As in case(B), the result is false, if @var{PTR} is disassociated.
1289 @item (D) If @var{TGT} is present and an scalar pointer, the result is true if
1290 target associated with @var{PTR} and the target associated with @var{TGT}
1291 are not 0 sized storage sequences and occupy the same storage units.
1292 The result is false, if either @var{TGT} or @var{PTR} is disassociated.
1293 @item (E) If @var{TGT} is present and an array pointer, the result is true if
1294 target associated with @var{PTR} and the target associated with @var{TGT}
1295 have the same shape, are not 0 sized arrays, are arrays whose elements are
1296 not 0 sized storage sequences, and @var{TGT} and @var{PTR} occupy the same
1297 storage units in array element order.
1298 The result is false, if either @var{TGT} or @var{PTR} is disassociated.
1301 @item @emph{Example}:
1303 program test_associated
1305 real, target :: tgt(2) = (/1., 2./)
1306 real, pointer :: ptr(:)
1308 if (associated(ptr) .eqv. .false.) call abort
1309 if (associated(ptr,tgt) .eqv. .false.) call abort
1310 end program test_associated
1313 @item @emph{See also}:
1320 @section @code{ATAN} --- Arctangent function
1323 @cindex trigonometric function, tangent, inverse
1324 @cindex tangent, inverse
1327 @item @emph{Description}:
1328 @code{ATAN(X)} computes the arctangent of @var{X}.
1330 @item @emph{Standard}:
1336 @item @emph{Syntax}:
1337 @code{RESULT = ATAN(X)}
1339 @item @emph{Arguments}:
1340 @multitable @columnfractions .15 .70
1341 @item @var{X} @tab The type shall be @code{REAL(*)}.
1344 @item @emph{Return value}:
1345 The return value is of type @code{REAL(*)} and it lies in the
1346 range @math{ - \pi / 2 \leq \atan (x) \leq \pi / 2}.
1348 @item @emph{Example}:
1351 real(8) :: x = 2.866_8
1353 end program test_atan
1356 @item @emph{Specific names}:
1357 @multitable @columnfractions .20 .20 .20 .25
1358 @item Name @tab Argument @tab Return type @tab Standard
1359 @item @code{DATAN(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab F77 and later
1362 @item @emph{See also}:
1363 Inverse function: @ref{TAN}
1370 @section @code{ATAN2} --- Arctangent function
1373 @cindex trigonometric function, tangent, inverse
1374 @cindex tangent, inverse
1377 @item @emph{Description}:
1378 @code{ATAN2(Y,X)} computes the arctangent of the complex number
1381 @item @emph{Standard}:
1387 @item @emph{Syntax}:
1388 @code{RESULT = ATAN2(Y,X)}
1390 @item @emph{Arguments}:
1391 @multitable @columnfractions .15 .70
1392 @item @var{Y} @tab The type shall be @code{REAL(*)}.
1393 @item @var{X} @tab The type and kind type parameter shall be the same as @var{Y}.
1394 If @var{Y} is zero, then @var{X} must be nonzero.
1397 @item @emph{Return value}:
1398 The return value has the same type and kind type parameter as @var{Y}.
1399 It is the principal value of the complex number @math{X + i Y}. If
1400 @var{X} is nonzero, then it lies in the range @math{-\pi \le \atan (x) \leq \pi}.
1401 The sign is positive if @var{Y} is positive. If @var{Y} is zero, then
1402 the return value is zero if @var{X} is positive and @math{\pi} if @var{X}
1403 is negative. Finally, if @var{X} is zero, then the magnitude of the result
1406 @item @emph{Example}:
1409 real(4) :: x = 1.e0_4, y = 0.5e0_4
1411 end program test_atan2
1414 @item @emph{Specific names}:
1415 @multitable @columnfractions .20 .20 .20 .25
1416 @item Name @tab Argument @tab Return type @tab Standard
1417 @item @code{DATAN2(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab F77 and later
1424 @section @code{ATANH} --- Hyperbolic arctangent function
1427 @cindex area hyperbolic tangent
1428 @cindex hyperbolic arctangent
1429 @cindex hyperbolic function, tangent, inverse
1430 @cindex tangent, hyperbolic, inverse
1433 @item @emph{Description}:
1434 @code{ATANH(X)} computes the hyperbolic arctangent of @var{X} (inverse
1437 @item @emph{Standard}:
1443 @item @emph{Syntax}:
1444 @code{RESULT = ATANH(X)}
1446 @item @emph{Arguments}:
1447 @multitable @columnfractions .15 .70
1448 @item @var{X} @tab The type shall be @code{REAL(*)} with a magnitude
1449 that is less than or equal to one.
1452 @item @emph{Return value}:
1453 The return value is of type @code{REAL(*)} and it lies in the
1454 range @math{-\infty \leq \atanh(x) \leq \infty}.
1456 @item @emph{Example}:
1459 REAL, DIMENSION(3) :: x = (/ -1.0, 0.0, 1.0 /)
1460 WRITE (*,*) ATANH(x)
1464 @item @emph{Specific names}:
1465 @multitable @columnfractions .20 .20 .20 .25
1466 @item Name @tab Argument @tab Return type @tab Standard
1467 @item @code{DATANH(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU extension
1470 @item @emph{See also}:
1471 Inverse function: @ref{TANH}
1477 @section @code{BESJ0} --- Bessel function of the first kind of order 0
1480 @cindex Bessel function, first kind
1483 @item @emph{Description}:
1484 @code{BESJ0(X)} computes the Bessel function of the first kind of order 0
1487 @item @emph{Standard}:
1493 @item @emph{Syntax}:
1494 @code{RESULT = BESJ0(X)}
1496 @item @emph{Arguments}:
1497 @multitable @columnfractions .15 .70
1498 @item @var{X} @tab The type shall be @code{REAL(*)}, and it shall be scalar.
1501 @item @emph{Return value}:
1502 The return value is of type @code{REAL(*)} and it lies in the
1503 range @math{ - 0.4027... \leq Bessel (0,x) \leq 1}.
1505 @item @emph{Example}:
1508 real(8) :: x = 0.0_8
1510 end program test_besj0
1513 @item @emph{Specific names}:
1514 @multitable @columnfractions .20 .20 .20 .25
1515 @item Name @tab Argument @tab Return type @tab Standard
1516 @item @code{DBESJ0(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU extension
1523 @section @code{BESJ1} --- Bessel function of the first kind of order 1
1526 @cindex Bessel function, first kind
1529 @item @emph{Description}:
1530 @code{BESJ1(X)} computes the Bessel function of the first kind of order 1
1533 @item @emph{Standard}:
1539 @item @emph{Syntax}:
1540 @code{RESULT = BESJ1(X)}
1542 @item @emph{Arguments}:
1543 @multitable @columnfractions .15 .70
1544 @item @var{X} @tab The type shall be @code{REAL(*)}, and it shall be scalar.
1547 @item @emph{Return value}:
1548 The return value is of type @code{REAL(*)} and it lies in the
1549 range @math{ - 0.5818... \leq Bessel (0,x) \leq 0.5818 }.
1551 @item @emph{Example}:
1554 real(8) :: x = 1.0_8
1556 end program test_besj1
1559 @item @emph{Specific names}:
1560 @multitable @columnfractions .20 .20 .20 .25
1561 @item Name @tab Argument @tab Return type @tab Standard
1562 @item @code{DBESJ1(X)}@tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU extension
1569 @section @code{BESJN} --- Bessel function of the first kind
1572 @cindex Bessel function, first kind
1575 @item @emph{Description}:
1576 @code{BESJN(N, X)} computes the Bessel function of the first kind of order
1579 If both arguments are arrays, their ranks and shapes shall conform.
1581 @item @emph{Standard}:
1587 @item @emph{Syntax}:
1588 @code{RESULT = BESJN(N, X)}
1590 @item @emph{Arguments}:
1591 @multitable @columnfractions .15 .70
1592 @item @var{N} @tab Shall be a scalar or an array of type @code{INTEGER(*)}.
1593 @item @var{X} @tab Shall be a scalar or an array of type @code{REAL(*)}.
1596 @item @emph{Return value}:
1597 The return value is a scalar of type @code{REAL(*)}.
1599 @item @emph{Example}:
1602 real(8) :: x = 1.0_8
1604 end program test_besjn
1607 @item @emph{Specific names}:
1608 @multitable @columnfractions .20 .20 .20 .25
1609 @item Name @tab Argument @tab Return type @tab Standard
1610 @item @code{DBESJN(X)} @tab @code{INTEGER(*) N} @tab @code{REAL(8)} @tab GNU extension
1611 @item @tab @code{REAL(8) X} @tab @tab
1618 @section @code{BESY0} --- Bessel function of the second kind of order 0
1621 @cindex Bessel function, second kind
1624 @item @emph{Description}:
1625 @code{BESY0(X)} computes the Bessel function of the second kind of order 0
1628 @item @emph{Standard}:
1634 @item @emph{Syntax}:
1635 @code{RESULT = BESY0(X)}
1637 @item @emph{Arguments}:
1638 @multitable @columnfractions .15 .70
1639 @item @var{X} @tab The type shall be @code{REAL(*)}, and it shall be scalar.
1642 @item @emph{Return value}:
1643 The return value is a scalar of type @code{REAL(*)}.
1645 @item @emph{Example}:
1648 real(8) :: x = 0.0_8
1650 end program test_besy0
1653 @item @emph{Specific names}:
1654 @multitable @columnfractions .20 .20 .20 .25
1655 @item Name @tab Argument @tab Return type @tab Standard
1656 @item @code{DBESY0(X)}@tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU extension
1663 @section @code{BESY1} --- Bessel function of the second kind of order 1
1666 @cindex Bessel function, second kind
1669 @item @emph{Description}:
1670 @code{BESY1(X)} computes the Bessel function of the second kind of order 1
1673 @item @emph{Standard}:
1679 @item @emph{Syntax}:
1680 @code{RESULT = BESY1(X)}
1682 @item @emph{Arguments}:
1683 @multitable @columnfractions .15 .70
1684 @item @var{X} @tab The type shall be @code{REAL(*)}, and it shall be scalar.
1687 @item @emph{Return value}:
1688 The return value is a scalar of type @code{REAL(*)}.
1690 @item @emph{Example}:
1693 real(8) :: x = 1.0_8
1695 end program test_besy1
1698 @item @emph{Specific names}:
1699 @multitable @columnfractions .20 .20 .20 .25
1700 @item Name @tab Argument @tab Return type @tab Standard
1701 @item @code{DBESY1(X)}@tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU extension
1708 @section @code{BESYN} --- Bessel function of the second kind
1711 @cindex Bessel function, second kind
1714 @item @emph{Description}:
1715 @code{BESYN(N, X)} computes the Bessel function of the second kind of order
1718 If both arguments are arrays, their ranks and shapes shall conform.
1720 @item @emph{Standard}:
1726 @item @emph{Syntax}:
1727 @code{RESULT = BESYN(N, X)}
1729 @item @emph{Arguments}:
1730 @multitable @columnfractions .15 .70
1731 @item @var{N} @tab Shall be a scalar or an array of type @code{INTEGER(*)}.
1732 @item @var{X} @tab Shall be a scalar or an array of type @code{REAL(*)}.
1735 @item @emph{Return value}:
1736 The return value is a scalar of type @code{REAL(*)}.
1738 @item @emph{Example}:
1741 real(8) :: x = 1.0_8
1743 end program test_besyn
1746 @item @emph{Specific names}:
1747 @multitable @columnfractions .20 .20 .20 .25
1748 @item Name @tab Argument @tab Return type @tab Standard
1749 @item @code{DBESYN(N,X)} @tab @code{INTEGER(*) N} @tab @code{REAL(8)} @tab GNU extension
1750 @item @tab @code{REAL(8) X} @tab @tab
1757 @section @code{BIT_SIZE} --- Bit size inquiry function
1759 @cindex bits, number of
1760 @cindex size of a variable, in bits
1763 @item @emph{Description}:
1764 @code{BIT_SIZE(I)} returns the number of bits (integer precision plus sign bit)
1765 represented by the type of @var{I}.
1767 @item @emph{Standard}:
1773 @item @emph{Syntax}:
1774 @code{RESULT = BIT_SIZE(I)}
1776 @item @emph{Arguments}:
1777 @multitable @columnfractions .15 .70
1778 @item @var{I} @tab The type shall be @code{INTEGER(*)}.
1781 @item @emph{Return value}:
1782 The return value is of type @code{INTEGER(*)}
1784 @item @emph{Example}:
1786 program test_bit_size
1791 end program test_bit_size
1798 @section @code{BTEST} --- Bit test function
1800 @cindex bits, testing
1803 @item @emph{Description}:
1804 @code{BTEST(I,POS)} returns logical @code{.TRUE.} if the bit at @var{POS}
1807 @item @emph{Standard}:
1813 @item @emph{Syntax}:
1814 @code{RESULT = BTEST(I, POS)}
1816 @item @emph{Arguments}:
1817 @multitable @columnfractions .15 .70
1818 @item @var{I} @tab The type shall be @code{INTEGER(*)}.
1819 @item @var{POS} @tab The type shall be @code{INTEGER(*)}.
1822 @item @emph{Return value}:
1823 The return value is of type @code{LOGICAL}
1825 @item @emph{Example}:
1828 integer :: i = 32768 + 1024 + 64
1832 bool = btest(i, pos)
1835 end program test_btest
1842 @section @code{CEILING} --- Integer ceiling function
1845 @cindex rounding, ceiling
1848 @item @emph{Description}:
1849 @code{CEILING(X)} returns the least integer greater than or equal to @var{X}.
1851 @item @emph{Standard}:
1857 @item @emph{Syntax}:
1858 @code{RESULT = CEILING(X [, KIND])}
1860 @item @emph{Arguments}:
1861 @multitable @columnfractions .15 .70
1862 @item @var{X} @tab The type shall be @code{REAL(*)}.
1863 @item @var{KIND} @tab (Optional) An @code{INTEGER(*)} initialization
1864 expression indicating the kind parameter of
1868 @item @emph{Return value}:
1869 The return value is of type @code{INTEGER(KIND)}
1871 @item @emph{Example}:
1873 program test_ceiling
1876 print *, ceiling(x) ! returns 64
1877 print *, ceiling(y) ! returns -63
1878 end program test_ceiling
1881 @item @emph{See also}:
1882 @ref{FLOOR}, @ref{NINT}
1889 @section @code{CHAR} --- Character conversion function
1891 @cindex conversion, to character
1894 @item @emph{Description}:
1895 @code{CHAR(I [, KIND])} returns the character represented by the integer @var{I}.
1897 @item @emph{Standard}:
1903 @item @emph{Syntax}:
1904 @code{RESULT = CHAR(I [, KIND])}
1906 @item @emph{Arguments}:
1907 @multitable @columnfractions .15 .70
1908 @item @var{I} @tab The type shall be @code{INTEGER(*)}.
1909 @item @var{KIND} @tab (Optional) An @code{INTEGER(*)} initialization
1910 expression indicating the kind parameter of
1914 @item @emph{Return value}:
1915 The return value is of type @code{CHARACTER(1)}
1917 @item @emph{Example}:
1923 print *, i, c ! returns 'J'
1924 end program test_char
1928 See @ref{ICHAR} for a discussion of converting between numerical values
1929 and formatted string representations.
1931 @item @emph{See also}:
1932 @ref{ACHAR}, @ref{IACHAR}, @ref{ICHAR}
1939 @section @code{CHDIR} --- Change working directory
1941 @cindex system, working directory
1944 @item @emph{Description}:
1945 Change current working directory to a specified path.
1947 This intrinsic is provided in both subroutine and function forms; however,
1948 only one form can be used in any given program unit.
1950 @item @emph{Standard}:
1954 Subroutine, non-elemental function
1956 @item @emph{Syntax}:
1957 @multitable @columnfractions .80
1958 @item @code{CALL CHDIR(NAME [, STATUS])}
1959 @item @code{STATUS = CHDIR(NAME)}
1962 @item @emph{Arguments}:
1963 @multitable @columnfractions .15 .70
1964 @item @var{NAME} @tab The type shall be @code{CHARACTER(*)} and shall
1965 specify a valid path within the file system.
1966 @item @var{STATUS} @tab (Optional) @code{INTEGER} status flag of the default
1967 kind. Returns 0 on success, and a system specific
1968 and non-zero error code otherwise.
1971 @item @emph{Example}:
1974 CHARACTER(len=255) :: path
1976 WRITE(*,*) TRIM(path)
1979 WRITE(*,*) TRIM(path)
1983 @item @emph{See also}:
1990 @section @code{CHMOD} --- Change access permissions of files
1992 @cindex file system, change access mode
1995 @item @emph{Description}:
1996 @code{CHMOD} changes the permissions of a file. This function invokes
1997 @code{/bin/chmod} and might therefore not work on all platforms.
1999 This intrinsic is provided in both subroutine and function forms; however,
2000 only one form can be used in any given program unit.
2002 @item @emph{Standard}:
2006 Subroutine, non-elemental function
2008 @item @emph{Syntax}:
2009 @multitable @columnfractions .80
2010 @item @code{CALL CHMOD(NAME, MODE[, STATUS])}
2011 @item @code{STATUS = CHMOD(NAME, MODE)}
2014 @item @emph{Arguments}:
2015 @multitable @columnfractions .15 .70
2016 @item @var{NAME} @tab Scalar @code{CHARACTER} with the file name.
2017 Trailing blanks are ignored unless the character @code{achar(0)} is
2018 present, then all characters up to and excluding @code{achar(0)} are
2019 used as the file name.
2021 @item @var{MODE} @tab Scalar @code{CHARACTER} giving the file permission.
2022 @var{MODE} uses the same syntax as the @var{MODE} argument of
2025 @item @var{STATUS} @tab (optional) scalar @code{INTEGER}, which is
2026 @code{0} on success and non-zero otherwise.
2029 @item @emph{Return value}:
2030 In either syntax, @var{STATUS} is set to @code{0} on success and non-zero
2033 @item @emph{Example}:
2034 @code{CHMOD} as subroutine
2039 call chmod('test.dat','u+x',status)
2040 print *, 'Status: ', status
2041 end program chmod_test
2043 @code{CHMOD} as non-elemental function:
2048 status = chmod('test.dat','u+x')
2049 print *, 'Status: ', status
2050 end program chmod_test
2058 @section @code{CMPLX} --- Complex conversion function
2060 @cindex complex numbers, conversion to
2061 @cindex conversion, to complex
2064 @item @emph{Description}:
2065 @code{CMPLX(X [, Y [, KIND]])} returns a complex number where @var{X} is converted to
2066 the real component. If @var{Y} is present it is converted to the imaginary
2067 component. If @var{Y} is not present then the imaginary component is set to
2068 0.0. If @var{X} is complex then @var{Y} must not be present.
2070 @item @emph{Standard}:
2076 @item @emph{Syntax}:
2077 @code{RESULT = CMPLX(X [, Y [, KIND]])}
2079 @item @emph{Arguments}:
2080 @multitable @columnfractions .15 .70
2081 @item @var{X} @tab The type may be @code{INTEGER(*)}, @code{REAL(*)},
2082 or @code{COMPLEX(*)}.
2083 @item @var{Y} @tab (Optional; only allowed if @var{X} is not
2084 @code{COMPLEX(*)}.) May be @code{INTEGER(*)}
2086 @item @var{KIND} @tab (Optional) An @code{INTEGER(*)} initialization
2087 expression indicating the kind parameter of
2091 @item @emph{Return value}:
2092 The return value is of @code{COMPLEX} type, with a kind equal to
2093 @var{KIND} if it is specified. If @var{KIND} is not specified, the
2094 result is of the default @code{COMPLEX} kind, regardless of the kinds of
2095 @var{X} and @var{Y}.
2097 @item @emph{Example}:
2104 print *, z, cmplx(x)
2105 end program test_cmplx
2108 @item @emph{See also}:
2114 @node COMMAND_ARGUMENT_COUNT
2115 @section @code{COMMAND_ARGUMENT_COUNT} --- Get number of command line arguments
2116 @fnindex COMMAND_ARGUMENT_COUNT
2117 @cindex command-line arguments
2118 @cindex command-line arguments, number of
2119 @cindex arguments, to program
2122 @item @emph{Description}:
2123 @code{COMMAND_ARGUMENT_COUNT()} returns the number of arguments passed on the
2124 command line when the containing program was invoked.
2126 @item @emph{Standard}:
2132 @item @emph{Syntax}:
2133 @code{RESULT = COMMAND_ARGUMENT_COUNT()}
2135 @item @emph{Arguments}:
2136 @multitable @columnfractions .15 .70
2140 @item @emph{Return value}:
2141 The return value is of type @code{INTEGER(4)}
2143 @item @emph{Example}:
2145 program test_command_argument_count
2147 count = command_argument_count()
2149 end program test_command_argument_count
2152 @item @emph{See also}:
2153 @ref{GET_COMMAND}, @ref{GET_COMMAND_ARGUMENT}
2159 @section @code{COMPLEX} --- Complex conversion function
2161 @cindex complex numbers, conversion to
2162 @cindex conversion, to complex
2165 @item @emph{Description}:
2166 @code{COMPLEX(X, Y)} returns a complex number where @var{X} is converted
2167 to the real component and @var{Y} is converted to the imaginary
2170 @item @emph{Standard}:
2176 @item @emph{Syntax}:
2177 @code{RESULT = COMPLEX(X, Y)}
2179 @item @emph{Arguments}:
2180 @multitable @columnfractions .15 .70
2181 @item @var{X} @tab The type may be @code{INTEGER(*)} or @code{REAL(*)}.
2182 @item @var{Y} @tab The type may be @code{INTEGER(*)} or @code{REAL(*)}.
2185 @item @emph{Return value}:
2186 If @var{X} and @var{Y} are both of @code{INTEGER} type, then the return
2187 value is of default @code{COMPLEX} type.
2189 If @var{X} and @var{Y} are of @code{REAL} type, or one is of @code{REAL}
2190 type and one is of @code{INTEGER} type, then the return value is of
2191 @code{COMPLEX} type with a kind equal to that of the @code{REAL}
2192 argument with the highest precision.
2194 @item @emph{Example}:
2196 program test_complex
2199 print *, complex(i, x)
2200 end program test_complex
2203 @item @emph{See also}:
2210 @section @code{CONJG} --- Complex conjugate function
2213 @cindex complex conjugate
2216 @item @emph{Description}:
2217 @code{CONJG(Z)} returns the conjugate of @var{Z}. If @var{Z} is @code{(x, y)}
2218 then the result is @code{(x, -y)}
2220 @item @emph{Standard}:
2221 F77 and later, has overloads that are GNU extensions
2226 @item @emph{Syntax}:
2229 @item @emph{Arguments}:
2230 @multitable @columnfractions .15 .70
2231 @item @var{Z} @tab The type shall be @code{COMPLEX(*)}.
2234 @item @emph{Return value}:
2235 The return value is of type @code{COMPLEX(*)}.
2237 @item @emph{Example}:
2240 complex :: z = (2.0, 3.0)
2241 complex(8) :: dz = (2.71_8, -3.14_8)
2246 end program test_conjg
2249 @item @emph{Specific names}:
2250 @multitable @columnfractions .20 .20 .20 .25
2251 @item Name @tab Argument @tab Return type @tab Standard
2252 @item @code{DCONJG(Z)} @tab @code{COMPLEX(8) Z} @tab @code{COMPLEX(8)} @tab GNU extension
2259 @section @code{COS} --- Cosine function
2265 @cindex trigonometric function, cosine
2269 @item @emph{Description}:
2270 @code{COS(X)} computes the cosine of @var{X}.
2272 @item @emph{Standard}:
2273 F77 and later, has overloads that are GNU extensions
2278 @item @emph{Syntax}:
2279 @code{RESULT = COS(X)}
2281 @item @emph{Arguments}:
2282 @multitable @columnfractions .15 .70
2283 @item @var{X} @tab The type shall be @code{REAL(*)} or
2287 @item @emph{Return value}:
2288 The return value is of type @code{REAL(*)} and it lies in the
2289 range @math{ -1 \leq \cos (x) \leq 1}. The kind type
2290 parameter is the same as @var{X}.
2292 @item @emph{Example}:
2297 end program test_cos
2300 @item @emph{Specific names}:
2301 @multitable @columnfractions .20 .20 .20 .25
2302 @item Name @tab Argument @tab Return type @tab Standard
2303 @item @code{DCOS(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab F77 and later
2304 @item @code{CCOS(X)} @tab @code{COMPLEX(4) X} @tab @code{COMPLEX(4)} @tab F77 and later
2305 @item @code{ZCOS(X)} @tab @code{COMPLEX(8) X} @tab @code{COMPLEX(8)} @tab GNU extension
2306 @item @code{CDCOS(X)} @tab @code{COMPLEX(8) X} @tab @code{COMPLEX(8)} @tab GNU extension
2309 @item @emph{See also}:
2310 Inverse function: @ref{ACOS}
2317 @section @code{COSH} --- Hyperbolic cosine function
2320 @cindex hyperbolic cosine
2321 @cindex hyperbolic function, cosine
2322 @cindex cosine, hyperbolic
2325 @item @emph{Description}:
2326 @code{COSH(X)} computes the hyperbolic cosine of @var{X}.
2328 @item @emph{Standard}:
2334 @item @emph{Syntax}:
2337 @item @emph{Arguments}:
2338 @multitable @columnfractions .15 .70
2339 @item @var{X} @tab The type shall be @code{REAL(*)}.
2342 @item @emph{Return value}:
2343 The return value is of type @code{REAL(*)} and it is positive
2344 (@math{ \cosh (x) \geq 0 }.
2346 @item @emph{Example}:
2349 real(8) :: x = 1.0_8
2351 end program test_cosh
2354 @item @emph{Specific names}:
2355 @multitable @columnfractions .20 .20 .20 .25
2356 @item Name @tab Argument @tab Return type @tab Standard
2357 @item @code{DCOSH(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab F77 and later
2360 @item @emph{See also}:
2361 Inverse function: @ref{ACOSH}
2368 @section @code{COUNT} --- Count function
2370 @cindex array, conditionally count elements
2371 @cindex array, element counting
2372 @cindex array, number of elements
2375 @item @emph{Description}:
2376 @code{COUNT(MASK [, DIM])} counts the number of @code{.TRUE.} elements of
2377 @var{MASK} along the dimension of @var{DIM}. If @var{DIM} is omitted it is
2378 taken to be @code{1}. @var{DIM} is a scaler of type @code{INTEGER} in the
2379 range of @math{1 /leq DIM /leq n)} where @math{n} is the rank of @var{MASK}.
2381 @item @emph{Standard}:
2385 transformational function
2387 @item @emph{Syntax}:
2388 @code{RESULT = COUNT(MASK [, DIM])}
2390 @item @emph{Arguments}:
2391 @multitable @columnfractions .15 .70
2392 @item @var{MASK} @tab The type shall be @code{LOGICAL}.
2393 @item @var{DIM} @tab The type shall be @code{INTEGER}.
2396 @item @emph{Return value}:
2397 The return value is of type @code{INTEGER} with rank equal to that of
2400 @item @emph{Example}:
2403 integer, dimension(2,3) :: a, b
2404 logical, dimension(2,3) :: mask
2405 a = reshape( (/ 1, 2, 3, 4, 5, 6 /), (/ 2, 3 /))
2406 b = reshape( (/ 0, 7, 3, 4, 5, 8 /), (/ 2, 3 /))
2407 print '(3i3)', a(1,:)
2408 print '(3i3)', a(2,:)
2410 print '(3i3)', b(1,:)
2411 print '(3i3)', b(2,:)
2414 print '(3l3)', mask(1,:)
2415 print '(3l3)', mask(2,:)
2417 print '(3i3)', count(mask)
2419 print '(3i3)', count(mask, 1)
2421 print '(3i3)', count(mask, 2)
2422 end program test_count
2429 @section @code{CPU_TIME} --- CPU elapsed time in seconds
2431 @cindex time, elapsed
2434 @item @emph{Description}:
2435 Returns a @code{REAL(*)} value representing the elapsed CPU time in
2436 seconds. This is useful for testing segments of code to determine
2439 @item @emph{Standard}:
2445 @item @emph{Syntax}:
2446 @code{CALL CPU_TIME(TIME)}
2448 @item @emph{Arguments}:
2449 @multitable @columnfractions .15 .70
2450 @item @var{TIME} @tab The type shall be @code{REAL(*)} with @code{INTENT(OUT)}.
2453 @item @emph{Return value}:
2456 @item @emph{Example}:
2458 program test_cpu_time
2459 real :: start, finish
2460 call cpu_time(start)
2461 ! put code to test here
2462 call cpu_time(finish)
2463 print '("Time = ",f6.3," seconds.")',finish-start
2464 end program test_cpu_time
2467 @item @emph{See also}:
2468 @ref{SYSTEM_CLOCK}, @ref{DATE_AND_TIME}
2474 @section @code{CSHIFT} --- Circular shift elements of an array
2476 @cindex array, shift circularly
2477 @cindex array, permutation
2478 @cindex array, rotate
2481 @item @emph{Description}:
2482 @code{CSHIFT(ARRAY, SHIFT [, DIM])} performs a circular shift on elements of
2483 @var{ARRAY} along the dimension of @var{DIM}. If @var{DIM} is omitted it is
2484 taken to be @code{1}. @var{DIM} is a scaler of type @code{INTEGER} in the
2485 range of @math{1 /leq DIM /leq n)} where @math{n} is the rank of @var{ARRAY}.
2486 If the rank of @var{ARRAY} is one, then all elements of @var{ARRAY} are shifted
2487 by @var{SHIFT} places. If rank is greater than one, then all complete rank one
2488 sections of @var{ARRAY} along the given dimension are shifted. Elements
2489 shifted out one end of each rank one section are shifted back in the other end.
2491 @item @emph{Standard}:
2495 Transformational function
2497 @item @emph{Syntax}:
2498 @code{RESULT = CSHIFT(ARRAY, SHIFT [, DIM])}
2500 @item @emph{Arguments}:
2501 @multitable @columnfractions .15 .70
2502 @item @var{ARRAY} @tab Shall be an array of any type.
2503 @item @var{SHIFT} @tab The type shall be @code{INTEGER}.
2504 @item @var{DIM} @tab The type shall be @code{INTEGER}.
2507 @item @emph{Return value}:
2508 Returns an array of same type and rank as the @var{ARRAY} argument.
2510 @item @emph{Example}:
2513 integer, dimension(3,3) :: a
2514 a = reshape( (/ 1, 2, 3, 4, 5, 6, 7, 8, 9 /), (/ 3, 3 /))
2515 print '(3i3)', a(1,:)
2516 print '(3i3)', a(2,:)
2517 print '(3i3)', a(3,:)
2518 a = cshift(a, SHIFT=(/1, 2, -1/), DIM=2)
2520 print '(3i3)', a(1,:)
2521 print '(3i3)', a(2,:)
2522 print '(3i3)', a(3,:)
2523 end program test_cshift
2530 @section @code{CTIME} --- Convert a time into a string
2532 @cindex time, conversion to string
2533 @cindex conversion, to string
2536 @item @emph{Description}:
2537 @code{CTIME} converts a system time value, such as returned by
2538 @code{TIME8()}, to a string of the form @samp{Sat Aug 19 18:13:14 1995}.
2540 This intrinsic is provided in both subroutine and function forms; however,
2541 only one form can be used in any given program unit.
2543 @item @emph{Standard}:
2549 @item @emph{Syntax}:
2550 @multitable @columnfractions .80
2551 @item @code{CALL CTIME(TIME, RESULT)}.
2552 @item @code{RESULT = CTIME(TIME)}, (not recommended).
2555 @item @emph{Arguments}:
2556 @multitable @columnfractions .15 .70
2557 @item @var{TIME} @tab The type shall be of type @code{INTEGER(KIND=8)}.
2558 @item @var{RESULT} @tab The type shall be of type @code{CHARACTER}.
2561 @item @emph{Return value}:
2562 The converted date and time as a string.
2564 @item @emph{Example}:
2568 character(len=30) :: date
2571 ! Do something, main part of the program
2574 print *, 'Program was started on ', date
2575 end program test_ctime
2578 @item @emph{See Also}:
2579 @ref{GMTIME}, @ref{LTIME}, @ref{TIME}, @ref{TIME8}
2585 @section @code{DATE_AND_TIME} --- Date and time subroutine
2586 @fnindex DATE_AND_TIME
2587 @cindex date, current
2588 @cindex current date
2589 @cindex time, current
2590 @cindex current time
2593 @item @emph{Description}:
2594 @code{DATE_AND_TIME(DATE, TIME, ZONE, VALUES)} gets the corresponding date and
2595 time information from the real-time system clock. @var{DATE} is
2596 @code{INTENT(OUT)} and has form ccyymmdd. @var{TIME} is @code{INTENT(OUT)} and
2597 has form hhmmss.sss. @var{ZONE} is @code{INTENT(OUT)} and has form (+-)hhmm,
2598 representing the difference with respect to Coordinated Universal Time (UTC).
2599 Unavailable time and date parameters return blanks.
2601 @var{VALUES} is @code{INTENT(OUT)} and provides the following:
2603 @multitable @columnfractions .15 .30 .40
2604 @item @tab @code{VALUE(1)}: @tab The year
2605 @item @tab @code{VALUE(2)}: @tab The month
2606 @item @tab @code{VALUE(3)}: @tab The day of the month
2607 @item @tab @code{VALUE(4)}: @tab Time difference with UTC in minutes
2608 @item @tab @code{VALUE(5)}: @tab The hour of the day
2609 @item @tab @code{VALUE(6)}: @tab The minutes of the hour
2610 @item @tab @code{VALUE(7)}: @tab The seconds of the minute
2611 @item @tab @code{VALUE(8)}: @tab The milliseconds of the second
2614 @item @emph{Standard}:
2620 @item @emph{Syntax}:
2621 @code{CALL DATE_AND_TIME([DATE, TIME, ZONE, VALUES])}
2623 @item @emph{Arguments}:
2624 @multitable @columnfractions .15 .70
2625 @item @var{DATE} @tab (Optional) The type shall be @code{CHARACTER(8)} or larger.
2626 @item @var{TIME} @tab (Optional) The type shall be @code{CHARACTER(10)} or larger.
2627 @item @var{ZONE} @tab (Optional) The type shall be @code{CHARACTER(5)} or larger.
2628 @item @var{VALUES}@tab (Optional) The type shall be @code{INTEGER(8)}.
2631 @item @emph{Return value}:
2634 @item @emph{Example}:
2636 program test_time_and_date
2637 character(8) :: date
2638 character(10) :: time
2639 character(5) :: zone
2640 integer,dimension(8) :: values
2641 ! using keyword arguments
2642 call date_and_time(date,time,zone,values)
2643 call date_and_time(DATE=date,ZONE=zone)
2644 call date_and_time(TIME=time)
2645 call date_and_time(VALUES=values)
2646 print '(a,2x,a,2x,a)', date, time, zone
2647 print '(8i5))', values
2648 end program test_time_and_date
2651 @item @emph{See also}:
2652 @ref{CPU_TIME}, @ref{SYSTEM_CLOCK}
2658 @section @code{DBLE} --- Double conversion function
2660 @cindex conversion, to real
2663 @item @emph{Description}:
2664 @code{DBLE(X)} Converts @var{X} to double precision real type.
2666 @item @emph{Standard}:
2672 @item @emph{Syntax}:
2673 @code{RESULT = DBLE(X)}
2675 @item @emph{Arguments}:
2676 @multitable @columnfractions .15 .70
2677 @item @var{X} @tab The type shall be @code{INTEGER(*)}, @code{REAL(*)},
2678 or @code{COMPLEX(*)}.
2681 @item @emph{Return value}:
2682 The return value is of type double precision real.
2684 @item @emph{Example}:
2689 complex :: z = (2.3,1.14)
2690 print *, dble(x), dble(i), dble(z)
2691 end program test_dble
2694 @item @emph{See also}:
2695 @ref{DFLOAT}, @ref{FLOAT}, @ref{REAL}
2701 @section @code{DCMPLX} --- Double complex conversion function
2703 @cindex complex numbers, conversion to
2704 @cindex conversion, to complex
2707 @item @emph{Description}:
2708 @code{DCMPLX(X [,Y])} returns a double complex number where @var{X} is
2709 converted to the real component. If @var{Y} is present it is converted to the
2710 imaginary component. If @var{Y} is not present then the imaginary component is
2711 set to 0.0. If @var{X} is complex then @var{Y} must not be present.
2713 @item @emph{Standard}:
2719 @item @emph{Syntax}:
2720 @code{RESULT = DCMPLX(X [, Y])}
2722 @item @emph{Arguments}:
2723 @multitable @columnfractions .15 .70
2724 @item @var{X} @tab The type may be @code{INTEGER(*)}, @code{REAL(*)},
2725 or @code{COMPLEX(*)}.
2726 @item @var{Y} @tab (Optional if @var{X} is not @code{COMPLEX(*)}.) May be
2727 @code{INTEGER(*)} or @code{REAL(*)}.
2730 @item @emph{Return value}:
2731 The return value is of type @code{COMPLEX(8)}
2733 @item @emph{Example}:
2743 print *, dcmplx(x,i)
2744 end program test_dcmplx
2751 @section @code{DFLOAT} --- Double conversion function
2753 @cindex conversion, to real
2756 @item @emph{Description}:
2757 @code{DFLOAT(X)} Converts @var{X} to double precision real type.
2759 @item @emph{Standard}:
2765 @item @emph{Syntax}:
2766 @code{RESULT = DFLOAT(X)}
2768 @item @emph{Arguments}:
2769 @multitable @columnfractions .15 .70
2770 @item @var{X} @tab The type shall be @code{INTEGER(*)}.
2773 @item @emph{Return value}:
2774 The return value is of type double precision real.
2776 @item @emph{Example}:
2781 end program test_dfloat
2784 @item @emph{See also}:
2785 @ref{DBLE}, @ref{FLOAT}, @ref{REAL}
2791 @section @code{DIGITS} --- Significant digits function
2793 @cindex model representation, significant digits
2796 @item @emph{Description}:
2797 @code{DIGITS(X)} returns the number of significant digits of the internal model
2798 representation of @var{X}. For example, on a system using a 32-bit
2799 floating point representation, a default real number would likely return 24.
2801 @item @emph{Standard}:
2807 @item @emph{Syntax}:
2808 @code{RESULT = DIGITS(X)}
2810 @item @emph{Arguments}:
2811 @multitable @columnfractions .15 .70
2812 @item @var{X} @tab The type may be @code{INTEGER(*)} or @code{REAL(*)}.
2815 @item @emph{Return value}:
2816 The return value is of type @code{INTEGER}.
2818 @item @emph{Example}:
2821 integer :: i = 12345
2827 end program test_digits
2834 @section @code{DIM} --- Positive difference
2838 @cindex positive difference
2841 @item @emph{Description}:
2842 @code{DIM(X,Y)} returns the difference @code{X-Y} if the result is positive;
2843 otherwise returns zero.
2845 @item @emph{Standard}:
2851 @item @emph{Syntax}:
2852 @code{RESULT = DIM(X, Y)}
2854 @item @emph{Arguments}:
2855 @multitable @columnfractions .15 .70
2856 @item @var{X} @tab The type shall be @code{INTEGER(*)} or @code{REAL(*)}
2857 @item @var{Y} @tab The type shall be the same type and kind as @var{X}.
2860 @item @emph{Return value}:
2861 The return value is of type @code{INTEGER(*)} or @code{REAL(*)}.
2863 @item @emph{Example}:
2869 x = dim(4.345_8, 2.111_8)
2872 end program test_dim
2875 @item @emph{Specific names}:
2876 @multitable @columnfractions .20 .20 .20 .25
2877 @item Name @tab Argument @tab Return type @tab Standard
2878 @item @code{IDIM(X,Y)} @tab @code{INTEGER(4) X,Y} @tab @code{INTEGER(4)} @tab F77 and later
2879 @item @code{DDIM(X,Y)} @tab @code{REAL(8) X,Y} @tab @code{REAL(8)} @tab F77 and later
2886 @section @code{DOT_PRODUCT} --- Dot product function
2887 @fnindex DOT_PRODUCT
2889 @cindex vector product
2890 @cindex product, vector
2893 @item @emph{Description}:
2894 @code{DOT_PRODUCT(X,Y)} computes the dot product multiplication of two vectors
2895 @var{X} and @var{Y}. The two vectors may be either numeric or logical
2896 and must be arrays of rank one and of equal size. If the vectors are
2897 @code{INTEGER(*)} or @code{REAL(*)}, the result is @code{SUM(X*Y)}. If the
2898 vectors are @code{COMPLEX(*)}, the result is @code{SUM(CONJG(X)*Y)}. If the
2899 vectors are @code{LOGICAL}, the result is @code{ANY(X.AND.Y)}.
2901 @item @emph{Standard}:
2905 transformational function
2907 @item @emph{Syntax}:
2908 @code{RESULT = DOT_PRODUCT(X, Y)}
2910 @item @emph{Arguments}:
2911 @multitable @columnfractions .15 .70
2912 @item @var{X} @tab The type shall be numeric or @code{LOGICAL}, rank 1.
2913 @item @var{Y} @tab The type shall be numeric or @code{LOGICAL}, rank 1.
2916 @item @emph{Return value}:
2917 If the arguments are numeric, the return value is a scaler of numeric type,
2918 @code{INTEGER(*)}, @code{REAL(*)}, or @code{COMPLEX(*)}. If the arguments are
2919 @code{LOGICAL}, the return value is @code{.TRUE.} or @code{.FALSE.}.
2921 @item @emph{Example}:
2923 program test_dot_prod
2924 integer, dimension(3) :: a, b
2931 print *, dot_product(a,b)
2932 end program test_dot_prod
2939 @section @code{DPROD} --- Double product function
2941 @cindex product, double-precision
2944 @item @emph{Description}:
2945 @code{DPROD(X,Y)} returns the product @code{X*Y}.
2947 @item @emph{Standard}:
2953 @item @emph{Syntax}:
2954 @code{RESULT = DPROD(X, Y)}
2956 @item @emph{Arguments}:
2957 @multitable @columnfractions .15 .70
2958 @item @var{X} @tab The type shall be @code{REAL}.
2959 @item @var{Y} @tab The type shall be @code{REAL}.
2962 @item @emph{Return value}:
2963 The return value is of type @code{REAL(8)}.
2965 @item @emph{Example}:
2973 end program test_dprod
2980 @section @code{DREAL} --- Double real part function
2982 @cindex complex numbers, real part
2985 @item @emph{Description}:
2986 @code{DREAL(Z)} returns the real part of complex variable @var{Z}.
2988 @item @emph{Standard}:
2994 @item @emph{Syntax}:
2995 @code{RESULT = DREAL(Z)}
2997 @item @emph{Arguments}:
2998 @multitable @columnfractions .15 .70
2999 @item @var{Z} @tab The type shall be @code{COMPLEX(8)}.
3002 @item @emph{Return value}:
3003 The return value is of type @code{REAL(8)}.
3005 @item @emph{Example}:
3008 complex(8) :: z = (1.3_8,7.2_8)
3010 end program test_dreal
3013 @item @emph{See also}:
3021 @section @code{DTIME} --- Execution time subroutine (or function)
3023 @cindex time, elapsed
3024 @cindex elapsed time
3027 @item @emph{Description}:
3028 @code{DTIME(TARRAY, RESULT)} initially returns the number of seconds of runtime
3029 since the start of the process's execution in @var{RESULT}. @var{TARRAY}
3030 returns the user and system components of this time in @code{TARRAY(1)} and
3031 @code{TARRAY(2)} respectively. @var{RESULT} is equal to @code{TARRAY(1) +
3034 Subsequent invocations of @code{DTIME} return values accumulated since the
3035 previous invocation.
3037 On some systems, the underlying timings are represented using types with
3038 sufficiently small limits that overflows (wrap around) are possible, such as
3039 32-bit types. Therefore, the values returned by this intrinsic might be, or
3040 become, negative, or numerically less than previous values, during a single
3041 run of the compiled program.
3043 If @code{DTIME} is invoked as a function, it can not be invoked as a
3044 subroutine, and vice versa.
3046 @var{TARRAY} and @var{RESULT} are @code{INTENT(OUT)} and provide the following:
3048 @multitable @columnfractions .15 .30 .40
3049 @item @tab @code{TARRAY(1)}: @tab User time in seconds.
3050 @item @tab @code{TARRAY(2)}: @tab System time in seconds.
3051 @item @tab @code{RESULT}: @tab Run time since start in seconds.
3054 @item @emph{Standard}:
3060 @item @emph{Syntax}:
3061 @multitable @columnfractions .80
3062 @item @code{CALL DTIME(TARRAY, RESULT)}.
3063 @item @code{RESULT = DTIME(TARRAY)}, (not recommended).
3066 @item @emph{Arguments}:
3067 @multitable @columnfractions .15 .70
3068 @item @var{TARRAY}@tab The type shall be @code{REAL, DIMENSION(2)}.
3069 @item @var{RESULT}@tab The type shall be @code{REAL}.
3072 @item @emph{Return value}:
3073 Elapsed time in seconds since the start of program execution.
3075 @item @emph{Example}:
3079 real, dimension(2) :: tarray
3081 call dtime(tarray, result)
3085 do i=1,100000000 ! Just a delay
3088 call dtime(tarray, result)
3092 end program test_dtime
3099 @section @code{EOSHIFT} --- End-off shift elements of an array
3101 @cindex array, shift
3104 @item @emph{Description}:
3105 @code{EOSHIFT(ARRAY, SHIFT[,BOUNDARY, DIM])} performs an end-off shift on
3106 elements of @var{ARRAY} along the dimension of @var{DIM}. If @var{DIM} is
3107 omitted it is taken to be @code{1}. @var{DIM} is a scaler of type
3108 @code{INTEGER} in the range of @math{1 /leq DIM /leq n)} where @math{n} is the
3109 rank of @var{ARRAY}. If the rank of @var{ARRAY} is one, then all elements of
3110 @var{ARRAY} are shifted by @var{SHIFT} places. If rank is greater than one,
3111 then all complete rank one sections of @var{ARRAY} along the given dimension are
3112 shifted. Elements shifted out one end of each rank one section are dropped. If
3113 @var{BOUNDARY} is present then the corresponding value of from @var{BOUNDARY}
3114 is copied back in the other end. If @var{BOUNDARY} is not present then the
3115 following are copied in depending on the type of @var{ARRAY}.
3117 @multitable @columnfractions .15 .80
3118 @item @emph{Array Type} @tab @emph{Boundary Value}
3119 @item Numeric @tab 0 of the type and kind of @var{ARRAY}.
3120 @item Logical @tab @code{.FALSE.}.
3121 @item Character(@var{len}) @tab @var{len} blanks.
3124 @item @emph{Standard}:
3128 Transformational function
3130 @item @emph{Syntax}:
3131 @code{RESULT = EOSHIFT(ARRAY, SHIFT [, BOUNDARY, DIM])}
3133 @item @emph{Arguments}:
3134 @multitable @columnfractions .15 .70
3135 @item @var{ARRAY} @tab May be any type, not scaler.
3136 @item @var{SHIFT} @tab The type shall be @code{INTEGER}.
3137 @item @var{BOUNDARY} @tab Same type as @var{ARRAY}.
3138 @item @var{DIM} @tab The type shall be @code{INTEGER}.
3141 @item @emph{Return value}:
3142 Returns an array of same type and rank as the @var{ARRAY} argument.
3144 @item @emph{Example}:
3146 program test_eoshift
3147 integer, dimension(3,3) :: a
3148 a = reshape( (/ 1, 2, 3, 4, 5, 6, 7, 8, 9 /), (/ 3, 3 /))
3149 print '(3i3)', a(1,:)
3150 print '(3i3)', a(2,:)
3151 print '(3i3)', a(3,:)
3152 a = EOSHIFT(a, SHIFT=(/1, 2, 1/), BOUNDARY=-5, DIM=2)
3154 print '(3i3)', a(1,:)
3155 print '(3i3)', a(2,:)
3156 print '(3i3)', a(3,:)
3157 end program test_eoshift
3164 @section @code{EPSILON} --- Epsilon function
3166 @cindex model representation, epsilon
3169 @item @emph{Description}:
3170 @code{EPSILON(X)} returns a nearly negligible number relative to @code{1}.
3172 @item @emph{Standard}:
3178 @item @emph{Syntax}:
3179 @code{RESULT = EPSILON(X)}
3181 @item @emph{Arguments}:
3182 @multitable @columnfractions .15 .70
3183 @item @var{X} @tab The type shall be @code{REAL(*)}.
3186 @item @emph{Return value}:
3187 The return value is of same type as the argument.
3189 @item @emph{Example}:
3191 program test_epsilon
3196 end program test_epsilon
3203 @section @code{ERF} --- Error function
3205 @cindex error function
3208 @item @emph{Description}:
3209 @code{ERF(X)} computes the error function of @var{X}.
3211 @item @emph{Standard}:
3217 @item @emph{Syntax}:
3218 @code{RESULT = ERF(X)}
3220 @item @emph{Arguments}:
3221 @multitable @columnfractions .15 .70
3222 @item @var{X} @tab The type shall be @code{REAL(*)}, and it shall be scalar.
3225 @item @emph{Return value}:
3226 The return value is a scalar of type @code{REAL(*)} and it is positive
3227 (@math{ - 1 \leq erf (x) \leq 1 }.
3229 @item @emph{Example}:
3232 real(8) :: x = 0.17_8
3234 end program test_erf
3237 @item @emph{Specific names}:
3238 @multitable @columnfractions .20 .20 .20 .25
3239 @item Name @tab Argument @tab Return type @tab Standard
3240 @item @code{DERF(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU extension
3247 @section @code{ERFC} --- Error function
3249 @cindex error function, complementary
3252 @item @emph{Description}:
3253 @code{ERFC(X)} computes the complementary error function of @var{X}.
3255 @item @emph{Standard}:
3261 @item @emph{Syntax}:
3262 @code{RESULT = ERFC(X)}
3264 @item @emph{Arguments}:
3265 @multitable @columnfractions .15 .70
3266 @item @var{X} @tab The type shall be @code{REAL(*)}, and it shall be scalar.
3269 @item @emph{Return value}:
3270 The return value is a scalar of type @code{REAL(*)} and it is positive
3271 (@math{ 0 \leq erfc (x) \leq 2 }.
3273 @item @emph{Example}:
3276 real(8) :: x = 0.17_8
3278 end program test_erfc
3281 @item @emph{Specific names}:
3282 @multitable @columnfractions .20 .20 .20 .25
3283 @item Name @tab Argument @tab Return type @tab Standard
3284 @item @code{DERFC(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab GNU extension
3291 @section @code{ETIME} --- Execution time subroutine (or function)
3293 @cindex time, elapsed
3296 @item @emph{Description}:
3297 @code{ETIME(TARRAY, RESULT)} returns the number of seconds of runtime
3298 since the start of the process's execution in @var{RESULT}. @var{TARRAY}
3299 returns the user and system components of this time in @code{TARRAY(1)} and
3300 @code{TARRAY(2)} respectively. @var{RESULT} is equal to @code{TARRAY(1) + TARRAY(2)}.
3302 On some systems, the underlying timings are represented using types with
3303 sufficiently small limits that overflows (wrap around) are possible, such as
3304 32-bit types. Therefore, the values returned by this intrinsic might be, or
3305 become, negative, or numerically less than previous values, during a single
3306 run of the compiled program.
3308 If @code{ETIME} is invoked as a function, it can not be invoked as a
3309 subroutine, and vice versa.
3311 @var{TARRAY} and @var{RESULT} are @code{INTENT(OUT)} and provide the following:
3313 @multitable @columnfractions .15 .30 .60
3314 @item @tab @code{TARRAY(1)}: @tab User time in seconds.
3315 @item @tab @code{TARRAY(2)}: @tab System time in seconds.
3316 @item @tab @code{RESULT}: @tab Run time since start in seconds.
3319 @item @emph{Standard}:
3325 @item @emph{Syntax}:
3326 @multitable @columnfractions .80
3327 @item @code{CALL ETIME(TARRAY, RESULT)}.
3328 @item @code{RESULT = ETIME(TARRAY)}, (not recommended).
3331 @item @emph{Arguments}:
3332 @multitable @columnfractions .15 .70
3333 @item @var{TARRAY}@tab The type shall be @code{REAL, DIMENSION(2)}.
3334 @item @var{RESULT}@tab The type shall be @code{REAL}.
3337 @item @emph{Return value}:
3338 Elapsed time in seconds since the start of program execution.
3340 @item @emph{Example}:
3344 real, dimension(2) :: tarray
3346 call ETIME(tarray, result)
3350 do i=1,100000000 ! Just a delay
3353 call ETIME(tarray, result)
3357 end program test_etime
3360 @item @emph{See also}:
3368 @section @code{EXIT} --- Exit the program with status.
3370 @cindex program termination
3371 @cindex terminate program
3374 @item @emph{Description}:
3375 @code{EXIT} causes immediate termination of the program with status. If status
3376 is omitted it returns the canonical @emph{success} for the system. All Fortran
3377 I/O units are closed.
3379 @item @emph{Standard}:
3385 @item @emph{Syntax}:
3386 @code{CALL EXIT([STATUS])}
3388 @item @emph{Arguments}:
3389 @multitable @columnfractions .15 .70
3390 @item @var{STATUS} @tab Shall be an @code{INTEGER} of the default kind.
3393 @item @emph{Return value}:
3394 @code{STATUS} is passed to the parent process on exit.
3396 @item @emph{Example}:
3399 integer :: STATUS = 0
3400 print *, 'This program is going to exit.'
3402 end program test_exit
3405 @item @emph{See also}:
3406 @ref{ABORT}, @ref{KILL}
3412 @section @code{EXP} --- Exponential function
3418 @cindex exponential function
3419 @cindex logarithmic function, inverse
3422 @item @emph{Description}:
3423 @code{EXP(X)} computes the base @math{e} exponential of @var{X}.
3425 @item @emph{Standard}:
3426 F77 and later, has overloads that are GNU extensions
3431 @item @emph{Syntax}:
3432 @code{RESULT = EXP(X)}
3434 @item @emph{Arguments}:
3435 @multitable @columnfractions .15 .70
3436 @item @var{X} @tab The type shall be @code{REAL(*)} or
3440 @item @emph{Return value}:
3441 The return value has same type and kind as @var{X}.
3443 @item @emph{Example}:
3448 end program test_exp
3451 @item @emph{Specific names}:
3452 @multitable @columnfractions .20 .20 .20 .25
3453 @item Name @tab Argument @tab Return type @tab Standard
3454 @item @code{DEXP(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab F77 and later
3455 @item @code{CEXP(X)} @tab @code{COMPLEX(4) X} @tab @code{COMPLEX(4)} @tab F77 and later
3456 @item @code{ZEXP(X)} @tab @code{COMPLEX(8) X} @tab @code{COMPLEX(8)} @tab GNU extension
3457 @item @code{CDEXP(X)} @tab @code{COMPLEX(8) X} @tab @code{COMPLEX(8)} @tab GNU extension
3464 @section @code{EXPONENT} --- Exponent function
3466 @cindex real number, exponent
3467 @cindex floating point, exponent
3470 @item @emph{Description}:
3471 @code{EXPONENT(X)} returns the value of the exponent part of @var{X}. If @var{X}
3472 is zero the value returned is zero.
3474 @item @emph{Standard}:
3480 @item @emph{Syntax}:
3481 @code{RESULT = EXPONENT(X)}
3483 @item @emph{Arguments}:
3484 @multitable @columnfractions .15 .70
3485 @item @var{X} @tab The type shall be @code{REAL(*)}.
3488 @item @emph{Return value}:
3489 The return value is of type default @code{INTEGER}.
3491 @item @emph{Example}:
3493 program test_exponent
3498 print *, exponent(0.0)
3499 end program test_exponent
3506 @section @code{FDATE} --- Get the current time as a string
3508 @cindex time, current
3509 @cindex current time
3510 @cindex date, current
3511 @cindex current date
3514 @item @emph{Description}:
3515 @code{FDATE(DATE)} returns the current date (using the same format as
3516 @code{CTIME}) in @var{DATE}. It is equivalent to @code{CALL CTIME(DATE,
3519 If @code{FDATE} is invoked as a function, it can not be invoked as a
3520 subroutine, and vice versa.
3522 @var{DATE} is an @code{INTENT(OUT)} @code{CHARACTER} variable.
3524 @item @emph{Standard}:
3530 @item @emph{Syntax}:
3531 @multitable @columnfractions .80
3532 @item @code{CALL FDATE(DATE)}.
3533 @item @code{DATE = FDATE()}, (not recommended).
3536 @item @emph{Arguments}:
3537 @multitable @columnfractions .15 .70
3538 @item @var{DATE}@tab The type shall be of type @code{CHARACTER}.
3541 @item @emph{Return value}:
3542 The current date as a string.
3544 @item @emph{Example}:
3548 character(len=30) :: date
3550 print *, 'Program started on ', date
3551 do i = 1, 100000000 ! Just a delay
3555 print *, 'Program ended on ', date
3556 end program test_fdate
3563 @section @code{FLOAT} --- Convert integer to default real
3565 @cindex conversion, to real
3568 @item @emph{Description}:
3569 @code{FLOAT(I)} converts the integer @var{I} to a default real value.
3571 @item @emph{Standard}:
3577 @item @emph{Syntax}:
3578 @code{RESULT = FLOAT(I)}
3580 @item @emph{Arguments}:
3581 @multitable @columnfractions .15 .70
3582 @item @var{I} @tab The type shall be @code{INTEGER(*)}.
3585 @item @emph{Return value}:
3586 The return value is of type default @code{REAL}.
3588 @item @emph{Example}:
3592 if (float(i) /= 1.) call abort
3593 end program test_float
3596 @item @emph{See also}:
3597 @ref{DBLE}, @ref{DFLOAT}, @ref{REAL}
3603 @section @code{FGET} --- Read a single character in stream mode from stdin
3605 @cindex read character, stream mode
3606 @cindex stream mode, read character
3607 @cindex file operation, read character
3610 @item @emph{Description}:
3611 Read a single character in stream mode from stdin by bypassing normal
3612 formatted output. Stream I/O should not be mixed with normal record-oriented
3613 (formatted or unformatted) I/O on the same unit; the results are unpredictable.
3615 This intrinsic routine is provided for backwards compatibility with
3616 @command{g77}. GNU Fortran provides the Fortran 2003 Stream facility.
3617 Programmers should consider the use of new stream IO feature in new code
3618 for future portability. See also @ref{Fortran 2003 status}.
3620 @item @emph{Standard}:
3624 Non-elemental subroutine
3626 @item @emph{Syntax}:
3627 @code{CALL FGET(C [, STATUS])}
3629 @item @emph{Arguments}:
3630 @multitable @columnfractions .15 .70
3631 @item @var{C} @tab The type shall be @code{CHARACTER}.
3632 @item @var{STATUS} @tab (Optional) status flag of type @code{INTEGER}.
3633 Returns 0 on success, -1 on end-of-file, and a
3634 system specific positive error code otherwise.
3637 @item @emph{Example}:
3640 INTEGER, PARAMETER :: strlen = 100
3641 INTEGER :: status, i = 1
3642 CHARACTER(len=strlen) :: str = ""
3644 WRITE (*,*) 'Enter text:'
3646 CALL fget(str(i:i), status)
3647 if (status /= 0 .OR. i > strlen) exit
3650 WRITE (*,*) TRIM(str)
3654 @item @emph{See also}:
3655 @ref{FGETC}, @ref{FPUT}, @ref{FPUTC}
3661 @section @code{FGETC} --- Read a single character in stream mode
3663 @cindex read character, stream mode
3664 @cindex stream mode, read character
3665 @cindex file operation, read character
3668 @item @emph{Description}:
3669 Read a single character in stream mode by bypassing normal formatted output.
3670 Stream I/O should not be mixed with normal record-oriented (formatted or
3671 unformatted) I/O on the same unit; the results are unpredictable.
3673 This intrinsic routine is provided for backwards compatibility with
3674 @command{g77}. GNU Fortran provides the Fortran 2003 Stream facility.
3675 Programmers should consider the use of new stream IO feature in new code
3676 for future portability. See also @ref{Fortran 2003 status}.
3678 @item @emph{Standard}:
3682 Non-elemental subroutine
3684 @item @emph{Syntax}:
3685 @code{CALL FGETC(UNIT, C [, STATUS])}
3687 @item @emph{Arguments}:
3688 @multitable @columnfractions .15 .70
3689 @item @var{UNIT} @tab The type shall be @code{INTEGER}.
3690 @item @var{C} @tab The type shall be @code{CHARACTER}.
3691 @item @var{STATUS} @tab (Optional) status flag of type @code{INTEGER}. Returns 0 on success,
3692 -1 on end-of-file and a system specific positive error code otherwise.
3695 @item @emph{Example}:
3698 INTEGER :: fd = 42, status
3701 OPEN(UNIT=fd, FILE="/etc/passwd", ACTION="READ", STATUS = "OLD")
3703 CALL fgetc(fd, c, status)
3704 IF (status /= 0) EXIT
3711 @item @emph{See also}:
3712 @ref{FGET}, @ref{FPUT}, @ref{FPUTC}
3718 @section @code{FLOOR} --- Integer floor function
3721 @cindex rounding, floor
3724 @item @emph{Description}:
3725 @code{FLOOR(X)} returns the greatest integer less than or equal to @var{X}.
3727 @item @emph{Standard}:
3733 @item @emph{Syntax}:
3734 @code{RESULT = FLOOR(X [, KIND])}
3736 @item @emph{Arguments}:
3737 @multitable @columnfractions .15 .70
3738 @item @var{X} @tab The type shall be @code{REAL(*)}.
3739 @item @var{KIND} @tab (Optional) An @code{INTEGER(*)} initialization
3740 expression indicating the kind parameter of
3744 @item @emph{Return value}:
3745 The return value is of type @code{INTEGER(KIND)}
3747 @item @emph{Example}:
3752 print *, floor(x) ! returns 63
3753 print *, floor(y) ! returns -64
3754 end program test_floor
3757 @item @emph{See also}:
3758 @ref{CEILING}, @ref{NINT}
3765 @section @code{FLUSH} --- Flush I/O unit(s)
3767 @cindex file operation, flush
3770 @item @emph{Description}:
3771 Flushes Fortran unit(s) currently open for output. Without the optional
3772 argument, all units are flushed, otherwise just the unit specified.
3774 @item @emph{Standard}:
3778 Non-elemental subroutine
3780 @item @emph{Syntax}:
3781 @code{CALL FLUSH(UNIT)}
3783 @item @emph{Arguments}:
3784 @multitable @columnfractions .15 .70
3785 @item @var{UNIT} @tab (Optional) The type shall be @code{INTEGER}.
3789 Beginning with the Fortran 2003 standard, there is a @code{FLUSH}
3790 statement that should be preferred over the @code{FLUSH} intrinsic.
3797 @section @code{FNUM} --- File number function
3799 @cindex file operation, file number
3802 @item @emph{Description}:
3803 @code{FNUM(UNIT)} returns the POSIX file descriptor number corresponding to the
3804 open Fortran I/O unit @code{UNIT}.
3806 @item @emph{Standard}:
3810 Non-elemental function
3812 @item @emph{Syntax}:
3813 @code{RESULT = FNUM(UNIT)}
3815 @item @emph{Arguments}:
3816 @multitable @columnfractions .15 .70
3817 @item @var{UNIT} @tab The type shall be @code{INTEGER}.
3820 @item @emph{Return value}:
3821 The return value is of type @code{INTEGER}
3823 @item @emph{Example}:
3827 open (unit=10, status = "scratch")
3831 end program test_fnum
3838 @section @code{FPUT} --- Write a single character in stream mode to stdout
3840 @cindex write character, stream mode
3841 @cindex stream mode, write character
3842 @cindex file operation, write character
3845 @item @emph{Description}:
3846 Write a single character in stream mode to stdout by bypassing normal
3847 formatted output. Stream I/O should not be mixed with normal record-oriented
3848 (formatted or unformatted) I/O on the same unit; the results are unpredictable.
3850 This intrinsic routine is provided for backwards compatibility with
3851 @command{g77}. GNU Fortran provides the Fortran 2003 Stream facility.
3852 Programmers should consider the use of new stream IO feature in new code
3853 for future portability. See also @ref{Fortran 2003 status}.
3855 @item @emph{Standard}:
3859 Non-elemental subroutine
3861 @item @emph{Syntax}:
3862 @code{CALL FPUT(C [, STATUS])}
3864 @item @emph{Arguments}:
3865 @multitable @columnfractions .15 .70
3866 @item @var{C} @tab The type shall be @code{CHARACTER}.
3867 @item @var{STATUS} @tab (Optional) status flag of type @code{INTEGER}. Returns 0 on success,
3868 -1 on end-of-file and a system specific positive error code otherwise.
3871 @item @emph{Example}:
3874 CHARACTER(len=10) :: str = "gfortran"
3876 DO i = 1, len_trim(str)
3882 @item @emph{See also}:
3883 @ref{FPUTC}, @ref{FGET}, @ref{FGETC}
3889 @section @code{FPUTC} --- Write a single character in stream mode
3891 @cindex write character, stream mode
3892 @cindex stream mode, write character
3893 @cindex file operation, write character
3896 @item @emph{Description}:
3897 Write a single character in stream mode by bypassing normal formatted
3898 output. Stream I/O should not be mixed with normal record-oriented
3899 (formatted or unformatted) I/O on the same unit; the results are unpredictable.
3901 This intrinsic routine is provided for backwards compatibility with
3902 @command{g77}. GNU Fortran provides the Fortran 2003 Stream facility.
3903 Programmers should consider the use of new stream IO feature in new code
3904 for future portability. See also @ref{Fortran 2003 status}.
3906 @item @emph{Standard}:
3910 Non-elemental subroutine
3912 @item @emph{Syntax}:
3913 @code{CALL FPUTC(UNIT, C [, STATUS])}
3915 @item @emph{Arguments}:
3916 @multitable @columnfractions .15 .70
3917 @item @var{UNIT} @tab The type shall be @code{INTEGER}.
3918 @item @var{C} @tab The type shall be @code{CHARACTER}.
3919 @item @var{STATUS} @tab (Optional) status flag of type @code{INTEGER}. Returns 0 on success,
3920 -1 on end-of-file and a system specific positive error code otherwise.
3923 @item @emph{Example}:
3926 CHARACTER(len=10) :: str = "gfortran"
3927 INTEGER :: fd = 42, i
3929 OPEN(UNIT = fd, FILE = "out", ACTION = "WRITE", STATUS="NEW")
3930 DO i = 1, len_trim(str)
3931 CALL fputc(fd, str(i:i))
3937 @item @emph{See also}:
3938 @ref{FPUT}, @ref{FGET}, @ref{FGETC}
3944 @section @code{FRACTION} --- Fractional part of the model representation
3946 @cindex real number, fraction
3947 @cindex floating point, fraction
3950 @item @emph{Description}:
3951 @code{FRACTION(X)} returns the fractional part of the model
3952 representation of @code{X}.
3954 @item @emph{Standard}:
3960 @item @emph{Syntax}:
3961 @code{Y = FRACTION(X)}
3963 @item @emph{Arguments}:
3964 @multitable @columnfractions .15 .70
3965 @item @var{X} @tab The type of the argument shall be a @code{REAL}.
3968 @item @emph{Return value}:
3969 The return value is of the same type and kind as the argument.
3970 The fractional part of the model representation of @code{X} is returned;
3971 it is @code{X * RADIX(X)**(-EXPONENT(X))}.
3973 @item @emph{Example}:
3975 program test_fraction
3978 print *, fraction(x), x * radix(x)**(-exponent(x))
3979 end program test_fraction
3987 @section @code{FREE} --- Frees memory
3989 @cindex pointer, cray
3992 @item @emph{Description}:
3993 Frees memory previously allocated by @code{MALLOC()}. The @code{FREE}
3994 intrinsic is an extension intended to be used with Cray pointers, and is
3995 provided in GNU Fortran to allow user to compile legacy code. For
3996 new code using Fortran 95 pointers, the memory de-allocation intrinsic is
3999 @item @emph{Standard}:
4005 @item @emph{Syntax}:
4006 @code{CALL FREE(PTR)}
4008 @item @emph{Arguments}:
4009 @multitable @columnfractions .15 .70
4010 @item @var{PTR} @tab The type shall be @code{INTEGER}. It represents the
4011 location of the memory that should be de-allocated.
4014 @item @emph{Return value}:
4017 @item @emph{Example}:
4018 See @code{MALLOC} for an example.
4020 @item @emph{See also}:
4027 @section @code{FSEEK} --- Low level file positioning subroutine
4029 @cindex file operation, seek
4030 @cindex file operation, position
4033 @item @emph{Description}:
4034 Moves @var{UNIT} to the specified @var{OFFSET}. If @var{WHENCE}
4035 is set to 0, the @var{OFFSET} is taken as an absolute value @code{SEEK_SET},
4036 if set to 1, @var{OFFSET} is taken to be relative to the current position
4037 @code{SEEK_CUR}, and if set to 2 relative to the end of the file @code{SEEK_END}.
4038 On error, @var{STATUS} is set to a non-zero value. If @var{STATUS} the seek
4041 This intrinsic routine is not fully backwards compatible with @command{g77}.
4042 In @command{g77}, the @code{FSEEK} takes a statement label instead of a
4043 @var{STATUS} variable. If FSEEK is used in old code, change
4045 CALL FSEEK(UNIT, OFFSET, WHENCE, *label)
4050 CALL FSEEK(UNIT, OFFSET, WHENCE, status)
4051 IF (status /= 0) GOTO label
4054 Please note that GNU Fortran provides the Fortran 2003 Stream facility.
4055 Programmers should consider the use of new stream IO feature in new code
4056 for future portability. See also @ref{Fortran 2003 status}.
4058 @item @emph{Standard}:
4064 @item @emph{Syntax}:
4065 @code{CALL FSEEK(UNIT, OFFSET, WHENCE[, STATUS])}
4067 @item @emph{Arguments}:
4068 @multitable @columnfractions .15 .70
4069 @item @var{UNIT} @tab Shall be a scalar of type @code{INTEGER}.
4070 @item @var{OFFSET} @tab Shall be a scalar of type @code{INTEGER}.
4071 @item @var{WHENCE} @tab Shall be a scalar of type @code{INTEGER}.
4072 Its value shall be either 0, 1 or 2.
4073 @item @var{STATUS} @tab (Optional) shall be a scalar of type
4077 @item @emph{Example}:
4080 INTEGER, PARAMETER :: SEEK_SET = 0, SEEK_CUR = 1, SEEK_END = 2
4081 INTEGER :: fd, offset, ierr
4087 OPEN(UNIT=fd, FILE="fseek.test")
4088 CALL FSEEK(fd, offset, SEEK_SET, ierr) ! move to OFFSET
4089 print *, FTELL(fd), ierr
4091 CALL FSEEK(fd, 0, SEEK_END, ierr) ! move to end
4092 print *, FTELL(fd), ierr
4094 CALL FSEEK(fd, 0, SEEK_SET, ierr) ! move to beginning
4095 print *, FTELL(fd), ierr
4101 @item @emph{See also}:
4108 @section @code{FSTAT} --- Get file status
4110 @cindex file system, file status
4113 @item @emph{Description}:
4114 @code{FSTAT} is identical to @ref{STAT}, except that information about an
4115 already opened file is obtained.
4117 The elements in @code{BUFF} are the same as described by @ref{STAT}.
4119 @item @emph{Standard}:
4123 Non-elemental subroutine
4125 @item @emph{Syntax}:
4126 @code{CALL FSTAT(UNIT, BUFF [, STATUS])}
4128 @item @emph{Arguments}:
4129 @multitable @columnfractions .15 .70
4130 @item @var{UNIT} @tab An open I/O unit number of type @code{INTEGER}.
4131 @item @var{BUFF} @tab The type shall be @code{INTEGER(4), DIMENSION(13)}.
4132 @item @var{STATUS} @tab (Optional) status flag of type @code{INTEGER(4)}. Returns 0
4133 on success and a system specific error code otherwise.
4136 @item @emph{Example}:
4137 See @ref{STAT} for an example.
4139 @item @emph{See also}:
4140 To stat a link: @ref{LSTAT}, to stat a file: @ref{STAT}
4146 @section @code{FTELL} --- Current stream position
4148 @cindex file operation, position
4151 @item @emph{Description}:
4152 Retrieves the current position within an open file.
4154 This intrinsic is provided in both subroutine and function forms; however,
4155 only one form can be used in any given program unit.
4157 @item @emph{Standard}:
4161 Subroutine, function
4163 @item @emph{Syntax}:
4164 @multitable @columnfractions .80
4165 @item @code{CALL FTELL(UNIT, OFFSET)}
4166 @item @code{OFFSET = FTELL(UNIT)}
4169 @item @emph{Arguments}:
4170 @multitable @columnfractions .15 .70
4171 @item @var{OFFSET} @tab Shall of type @code{INTEGER}.
4172 @item @var{UNIT} @tab Shall of type @code{INTEGER}.
4175 @item @emph{Return value}:
4176 In either syntax, @var{OFFSET} is set to the current offset of unit
4177 number @var{UNIT}, or to @math{-1} if the unit is not currently open.
4179 @item @emph{Example}:
4183 OPEN(10, FILE="temp.dat")
4189 @item @emph{See also}:
4196 @section @code{GERROR} --- Get last system error message
4198 @cindex system, error handling
4201 @item @emph{Description}:
4202 Returns the system error message corresponding to the last system error.
4203 This resembles the functionality of @code{strerror(3)} in C.
4205 @item @emph{Standard}:
4211 @item @emph{Syntax}:
4212 @code{CALL GERROR(RESULT)}
4214 @item @emph{Arguments}:
4215 @multitable @columnfractions .15 .70
4216 @item @var{RESULT} @tab Shall of type @code{CHARACTER(*)}.
4219 @item @emph{Example}:
4222 CHARACTER(len=100) :: msg
4228 @item @emph{See also}:
4229 @ref{IERRNO}, @ref{PERROR}
4235 @section @code{GETARG} --- Get command line arguments
4237 @cindex command-line arguments
4238 @cindex arguments, to program
4241 @item @emph{Description}:
4242 Retrieve the @var{N}th argument that was passed on the
4243 command line when the containing program was invoked.
4245 This intrinsic routine is provided for backwards compatibility with
4246 GNU Fortran 77. In new code, programmers should consider the use of
4247 the @ref{GET_COMMAND_ARGUMENT} intrinsic defined by the Fortran 2003
4250 @item @emph{Standard}:
4256 @item @emph{Syntax}:
4257 @code{CALL GETARG(N, ARG)}
4259 @item @emph{Arguments}:
4260 @multitable @columnfractions .15 .70
4261 @item @var{N} @tab Shall be of type @code{INTEGER(4)}, @math{@var{N} \geq 0}
4262 @item @var{ARG} @tab Shall be of type @code{CHARACTER(*)}.
4265 @item @emph{Return value}:
4266 After @code{GETARG} returns, the @var{ARG} argument holds the @var{N}th
4267 command line argument. If @var{ARG} can not hold the argument, it is
4268 truncated to fit the length of @var{ARG}. If there are less than @var{N}
4269 arguments specified at the command line, @var{ARG} will be filled with blanks.
4270 If @math{@var{N} = 0}, @var{ARG} is set to the name of the program (on systems
4271 that support this feature).
4273 @item @emph{Example}:
4277 CHARACTER(len=32) :: arg
4286 @item @emph{See also}:
4287 GNU Fortran 77 compatibility function: @ref{IARGC}
4289 F2003 functions and subroutines: @ref{GET_COMMAND}, @ref{GET_COMMAND_ARGUMENT},
4290 @ref{COMMAND_ARGUMENT_COUNT}
4296 @section @code{GET_COMMAND} --- Get the entire command line
4297 @fnindex GET_COMMAND
4298 @cindex command-line arguments
4299 @cindex arguments, to program
4302 @item @emph{Description}:
4303 Retrieve the entire command line that was used to invoke the program.
4305 @item @emph{Standard}:
4311 @item @emph{Syntax}:
4312 @code{CALL GET_COMMAND(CMD)}
4314 @item @emph{Arguments}:
4315 @multitable @columnfractions .15 .70
4316 @item @var{CMD} @tab Shall be of type @code{CHARACTER(*)}.
4319 @item @emph{Return value}:
4320 Stores the entire command line that was used to invoke the program in @var{ARG}.
4321 If @var{ARG} is not large enough, the command will be truncated.
4323 @item @emph{Example}:
4325 PROGRAM test_get_command
4326 CHARACTER(len=255) :: cmd
4327 CALL get_command(cmd)
4328 WRITE (*,*) TRIM(cmd)
4332 @item @emph{See also}:
4333 @ref{GET_COMMAND_ARGUMENT}, @ref{COMMAND_ARGUMENT_COUNT}
4338 @node GET_COMMAND_ARGUMENT
4339 @section @code{GET_COMMAND_ARGUMENT} --- Get command line arguments
4340 @fnindex GET_COMMAND_ARGUMENT
4341 @cindex command-line arguments
4342 @cindex arguments, to program
4345 @item @emph{Description}:
4346 Retrieve the @var{N}th argument that was passed on the
4347 command line when the containing program was invoked.
4349 @item @emph{Standard}:
4355 @item @emph{Syntax}:
4356 @code{CALL GET_COMMAND_ARGUMENT(N, ARG)}
4358 @item @emph{Arguments}:
4359 @multitable @columnfractions .15 .70
4360 @item @var{N} @tab Shall be of type @code{INTEGER(4)}, @math{@var{N} \geq 0}
4361 @item @var{ARG} @tab Shall be of type @code{CHARACTER(*)}.
4364 @item @emph{Return value}:
4365 After @code{GET_COMMAND_ARGUMENT} returns, the @var{ARG} argument holds the
4366 @var{N}th command line argument. If @var{ARG} can not hold the argument, it is
4367 truncated to fit the length of @var{ARG}. If there are less than @var{N}
4368 arguments specified at the command line, @var{ARG} will be filled with blanks.
4369 If @math{@var{N} = 0}, @var{ARG} is set to the name of the program (on systems
4370 that support this feature).
4372 @item @emph{Example}:
4374 PROGRAM test_get_command_argument
4376 CHARACTER(len=32) :: arg
4380 CALL get_command_argument(i, arg)
4381 IF (LEN_TRIM(arg) == 0) EXIT
4383 WRITE (*,*) TRIM(arg)
4389 @item @emph{See also}:
4390 @ref{GET_COMMAND}, @ref{COMMAND_ARGUMENT_COUNT}
4396 @section @code{GETCWD} --- Get current working directory
4398 @cindex system, working directory
4401 @item @emph{Description}:
4402 Get current working directory.
4404 @item @emph{Standard}:
4408 Non-elemental subroutine.
4410 @item @emph{Syntax}:
4411 @code{CALL GETCWD(CWD [, STATUS])}
4413 @item @emph{Arguments}:
4414 @multitable @columnfractions .15 .70
4415 @item @var{CWD} @tab The type shall be @code{CHARACTER(*)}.
4416 @item @var{STATUS} @tab (Optional) status flag. Returns 0 on success,
4417 a system specific and non-zero error code otherwise.
4420 @item @emph{Example}:
4423 CHARACTER(len=255) :: cwd
4425 WRITE(*,*) TRIM(cwd)
4429 @item @emph{See also}:
4436 @section @code{GETENV} --- Get an environmental variable
4438 @cindex environment variable
4441 @item @emph{Description}:
4442 Get the @var{VALUE} of the environmental variable @var{ENVVAR}.
4444 This intrinsic routine is provided for backwards compatibility with
4445 GNU Fortran 77. In new code, programmers should consider the use of
4446 the @ref{GET_ENVIRONMENT_VARIABLE} intrinsic defined by the Fortran
4449 @item @emph{Standard}:
4455 @item @emph{Syntax}:
4456 @code{CALL GETENV(ENVVAR, VALUE)}
4458 @item @emph{Arguments}:
4459 @multitable @columnfractions .15 .70
4460 @item @var{ENVVAR} @tab Shall be of type @code{CHARACTER(*)}.
4461 @item @var{VALUE} @tab Shall be of type @code{CHARACTER(*)}.
4464 @item @emph{Return value}:
4465 Stores the value of @var{ENVVAR} in @var{VALUE}. If @var{VALUE} is
4466 not large enough to hold the data, it is truncated. If @var{ENVVAR}
4467 is not set, @var{VALUE} will be filled with blanks.
4469 @item @emph{Example}:
4472 CHARACTER(len=255) :: homedir
4473 CALL getenv("HOME", homedir)
4474 WRITE (*,*) TRIM(homedir)
4478 @item @emph{See also}:
4479 @ref{GET_ENVIRONMENT_VARIABLE}
4484 @node GET_ENVIRONMENT_VARIABLE
4485 @section @code{GET_ENVIRONMENT_VARIABLE} --- Get an environmental variable
4486 @fnindex GET_ENVIRONMENT_VARIABLE
4487 @cindex environment variable
4490 @item @emph{Description}:
4491 Get the @var{VALUE} of the environmental variable @var{ENVVAR}.
4493 @item @emph{Standard}:
4499 @item @emph{Syntax}:
4500 @code{CALL GET_ENVIRONMENT_VARIABLE(ENVVAR, VALUE)}
4502 @item @emph{Arguments}:
4503 @multitable @columnfractions .15 .70
4504 @item @var{ENVVAR} @tab Shall be of type @code{CHARACTER(*)}.
4505 @item @var{VALUE} @tab Shall be of type @code{CHARACTER(*)}.
4508 @item @emph{Return value}:
4509 Stores the value of @var{ENVVAR} in @var{VALUE}. If @var{VALUE} is
4510 not large enough to hold the data, it is truncated. If @var{ENVVAR}
4511 is not set, @var{VALUE} will be filled with blanks.
4513 @item @emph{Example}:
4516 CHARACTER(len=255) :: homedir
4517 CALL get_environment_variable("HOME", homedir)
4518 WRITE (*,*) TRIM(homedir)
4526 @section @code{GETGID} --- Group ID function
4528 @cindex system, group id
4531 @item @emph{Description}:
4532 Returns the numerical group ID of the current process.
4534 @item @emph{Standard}:
4540 @item @emph{Syntax}:
4541 @code{RESULT = GETGID()}
4543 @item @emph{Return value}:
4544 The return value of @code{GETGID} is an @code{INTEGER} of the default
4548 @item @emph{Example}:
4549 See @code{GETPID} for an example.
4551 @item @emph{See also}:
4552 @ref{GETPID}, @ref{GETUID}
4558 @section @code{GETLOG} --- Get login name
4560 @cindex system, login name
4564 @item @emph{Description}:
4565 Gets the username under which the program is running.
4567 @item @emph{Standard}:
4573 @item @emph{Syntax}:
4574 @code{CALL GETLOG(LOGIN)}
4576 @item @emph{Arguments}:
4577 @multitable @columnfractions .15 .70
4578 @item @var{LOGIN} @tab Shall be of type @code{CHARACTER(*)}.
4581 @item @emph{Return value}:
4582 Stores the current user name in @var{LOGIN}. (On systems where POSIX
4583 functions @code{geteuid} and @code{getpwuid} are not available, and
4584 the @code{getlogin} function is not implemented either, this will
4585 return a blank string.)
4587 @item @emph{Example}:
4590 CHARACTER(32) :: login
4596 @item @emph{See also}:
4603 @section @code{GETPID} --- Process ID function
4605 @cindex system, process id
4609 @item @emph{Description}:
4610 Returns the numerical process identifier of the current process.
4612 @item @emph{Standard}:
4618 @item @emph{Syntax}:
4619 @code{RESULT = GETPID()}
4621 @item @emph{Return value}:
4622 The return value of @code{GETPID} is an @code{INTEGER} of the default
4626 @item @emph{Example}:
4629 print *, "The current process ID is ", getpid()
4630 print *, "Your numerical user ID is ", getuid()
4631 print *, "Your numerical group ID is ", getgid()
4635 @item @emph{See also}:
4636 @ref{GETGID}, @ref{GETUID}
4642 @section @code{GETUID} --- User ID function
4644 @cindex system, user id
4648 @item @emph{Description}:
4649 Returns the numerical user ID of the current process.
4651 @item @emph{Standard}:
4657 @item @emph{Syntax}:
4658 @code{RESULT = GETUID()}
4660 @item @emph{Return value}:
4661 The return value of @code{GETUID} is an @code{INTEGER} of the default
4665 @item @emph{Example}:
4666 See @code{GETPID} for an example.
4668 @item @emph{See also}:
4669 @ref{GETPID}, @ref{GETLOG}
4675 @section @code{GMTIME} --- Convert time to GMT info
4677 @cindex time, conversion to GMT info
4680 @item @emph{Description}:
4681 Given a system time value @var{STIME} (as provided by the @code{TIME8()}
4682 intrinsic), fills @var{TARRAY} with values extracted from it appropriate
4683 to the UTC time zone (Universal Coordinated Time, also known in some
4684 countries as GMT, Greenwich Mean Time), using @code{gmtime(3)}.
4686 @item @emph{Standard}:
4692 @item @emph{Syntax}:
4693 @code{CALL GMTIME(STIME, TARRAY)}
4695 @item @emph{Arguments}:
4696 @multitable @columnfractions .15 .70
4697 @item @var{STIME} @tab An @code{INTEGER(*)} scalar expression
4698 corresponding to a system time, with
4700 @item @var{TARRAY} @tab A default @code{INTEGER} array with 9 elements,
4701 with @code{INTENT(OUT)}.
4704 @item @emph{Return value}:
4705 The elements of @var{TARRAY} are assigned as follows:
4707 @item Seconds after the minute, range 0--59 or 0--61 to allow for leap
4709 @item Minutes after the hour, range 0--59
4710 @item Hours past midnight, range 0--23
4711 @item Day of month, range 0--31
4712 @item Number of months since January, range 0--12
4713 @item Years since 1900
4714 @item Number of days since Sunday, range 0--6
4715 @item Days since January 1
4716 @item Daylight savings indicator: positive if daylight savings is in
4717 effect, zero if not, and negative if the information is not
4721 @item @emph{See also}:
4722 @ref{CTIME}, @ref{LTIME}, @ref{TIME}, @ref{TIME8}
4729 @section @code{HOSTNM} --- Get system host name
4731 @cindex system, host name
4734 @item @emph{Description}:
4735 Retrieves the host name of the system on which the program is running.
4737 This intrinsic is provided in both subroutine and function forms; however,
4738 only one form can be used in any given program unit.
4740 @item @emph{Standard}:
4744 Subroutine, function
4746 @item @emph{Syntax}:
4747 @multitable @columnfractions .80
4748 @item @code{CALL HOSTNM(NAME[, STATUS])}
4749 @item @code{STATUS = HOSTNM(NAME)}
4752 @item @emph{Arguments}:
4753 @multitable @columnfractions .15 .70
4754 @item @var{NAME} @tab Shall of type @code{CHARACTER(*)}.
4755 @item @var{STATUS} @tab (Optional) status flag of type @code{INTEGER}.
4756 Returns 0 on success, or a system specific error
4760 @item @emph{Return value}:
4761 In either syntax, @var{NAME} is set to the current hostname if it can
4762 be obtained, or to a blank string otherwise.
4769 @section @code{HUGE} --- Largest number of a kind
4771 @cindex limits, largest number
4772 @cindex model representation, largest number
4775 @item @emph{Description}:
4776 @code{HUGE(X)} returns the largest number that is not an infinity in
4777 the model of the type of @code{X}.
4779 @item @emph{Standard}:
4785 @item @emph{Syntax}:
4786 @code{RESULT = HUGE(X)}
4788 @item @emph{Arguments}:
4789 @multitable @columnfractions .15 .70
4790 @item @var{X} @tab Shall be of type @code{REAL} or @code{INTEGER}.
4793 @item @emph{Return value}:
4794 The return value is of the same type and kind as @var{X}
4796 @item @emph{Example}:
4798 program test_huge_tiny
4799 print *, huge(0), huge(0.0), huge(0.0d0)
4800 print *, tiny(0.0), tiny(0.0d0)
4801 end program test_huge_tiny
4808 @section @code{IACHAR} --- Code in @acronym{ASCII} collating sequence
4810 @cindex @acronym{ASCII} collating sequence
4811 @cindex collating sequence, @acronym{ASCII}
4812 @cindex conversion, to integer
4815 @item @emph{Description}:
4816 @code{IACHAR(C)} returns the code for the @acronym{ASCII} character
4817 in the first character position of @code{C}.
4819 @item @emph{Standard}:
4825 @item @emph{Syntax}:
4826 @code{RESULT = IACHAR(C)}
4828 @item @emph{Arguments}:
4829 @multitable @columnfractions .15 .70
4830 @item @var{C} @tab Shall be a scalar @code{CHARACTER}, with @code{INTENT(IN)}
4833 @item @emph{Return value}:
4834 The return value is of type @code{INTEGER} and of the default integer
4837 @item @emph{Example}:
4842 end program test_iachar
4846 See @ref{ICHAR} for a discussion of converting between numerical values
4847 and formatted string representations.
4849 @item @emph{See also}:
4850 @ref{ACHAR}, @ref{CHAR}, @ref{ICHAR}
4857 @section @code{IAND} --- Bitwise logical and
4859 @cindex bitwise logical and
4860 @cindex logical and, bitwise
4863 @item @emph{Description}:
4864 Bitwise logical @code{AND}.
4866 @item @emph{Standard}:
4872 @item @emph{Syntax}:
4873 @code{RESULT = IAND(I, J)}
4875 @item @emph{Arguments}:
4876 @multitable @columnfractions .15 .70
4877 @item @var{I} @tab The type shall be @code{INTEGER(*)}.
4878 @item @var{J} @tab The type shall be @code{INTEGER(*)}, of the same
4879 kind as @var{I}. (As a GNU extension, different kinds are also
4883 @item @emph{Return value}:
4884 The return type is @code{INTEGER(*)}, of the same kind as the
4885 arguments. (If the argument kinds differ, it is of the same kind as
4886 the larger argument.)
4888 @item @emph{Example}:
4892 DATA a / Z'F' /, b / Z'3' /
4893 WRITE (*,*) IAND(a, b)
4897 @item @emph{See also}:
4898 @ref{IOR}, @ref{IEOR}, @ref{IBITS}, @ref{IBSET}, @ref{IBCLR}, @ref{NOT}
4905 @section @code{IARGC} --- Get the number of command line arguments
4907 @cindex command-line arguments
4908 @cindex command-line arguments, number of
4909 @cindex arguments, to program
4912 @item @emph{Description}:
4913 @code{IARGC()} returns the number of arguments passed on the
4914 command line when the containing program was invoked.
4916 This intrinsic routine is provided for backwards compatibility with
4917 GNU Fortran 77. In new code, programmers should consider the use of
4918 the @ref{COMMAND_ARGUMENT_COUNT} intrinsic defined by the Fortran 2003
4921 @item @emph{Standard}:
4925 Non-elemental Function
4927 @item @emph{Syntax}:
4928 @code{RESULT = IARGC()}
4930 @item @emph{Arguments}:
4933 @item @emph{Return value}:
4934 The number of command line arguments, type @code{INTEGER(4)}.
4936 @item @emph{Example}:
4939 @item @emph{See also}:
4940 GNU Fortran 77 compatibility subroutine: @ref{GETARG}
4942 F2003 functions and subroutines: @ref{GET_COMMAND}, @ref{GET_COMMAND_ARGUMENT},
4943 @ref{COMMAND_ARGUMENT_COUNT}
4949 @section @code{IBCLR} --- Clear bit
4955 @item @emph{Description}:
4956 @code{IBCLR} returns the value of @var{I} with the bit at position
4957 @var{POS} set to zero.
4959 @item @emph{Standard}:
4965 @item @emph{Syntax}:
4966 @code{RESULT = IBCLR(I, POS)}
4968 @item @emph{Arguments}:
4969 @multitable @columnfractions .15 .70
4970 @item @var{I} @tab The type shall be @code{INTEGER(*)}.
4971 @item @var{POS} @tab The type shall be @code{INTEGER(*)}.
4974 @item @emph{Return value}:
4975 The return value is of type @code{INTEGER(*)} and of the same kind as
4978 @item @emph{See also}:
4979 @ref{IBITS}, @ref{IBSET}, @ref{IAND}, @ref{IOR}, @ref{IEOR}, @ref{MVBITS}
4986 @section @code{IBITS} --- Bit extraction
4989 @cindex bits, extract
4992 @item @emph{Description}:
4993 @code{IBITS} extracts a field of length @var{LEN} from @var{I},
4994 starting from bit position @var{POS} and extending left for @var{LEN}
4995 bits. The result is right-justified and the remaining bits are
4996 zeroed. The value of @code{POS+LEN} must be less than or equal to the
4997 value @code{BIT_SIZE(I)}.
4999 @item @emph{Standard}:
5005 @item @emph{Syntax}:
5006 @code{RESULT = IBITS(I, POS, LEN)}
5008 @item @emph{Arguments}:
5009 @multitable @columnfractions .15 .70
5010 @item @var{I} @tab The type shall be @code{INTEGER(*)}.
5011 @item @var{POS} @tab The type shall be @code{INTEGER(*)}.
5012 @item @var{LEN} @tab The type shall be @code{INTEGER(*)}.
5015 @item @emph{Return value}:
5016 The return value is of type @code{INTEGER(*)} and of the same kind as
5019 @item @emph{See also}:
5020 @ref{BIT_SIZE}, @ref{IBCLR}, @ref{IBSET}, @ref{IAND}, @ref{IOR}, @ref{IEOR}
5026 @section @code{IBSET} --- Set bit
5031 @item @emph{Description}:
5032 @code{IBSET} returns the value of @var{I} with the bit at position
5033 @var{POS} set to one.
5035 @item @emph{Standard}:
5041 @item @emph{Syntax}:
5042 @code{RESULT = IBSET(I, POS)}
5044 @item @emph{Arguments}:
5045 @multitable @columnfractions .15 .70
5046 @item @var{I} @tab The type shall be @code{INTEGER(*)}.
5047 @item @var{POS} @tab The type shall be @code{INTEGER(*)}.
5050 @item @emph{Return value}:
5051 The return value is of type @code{INTEGER(*)} and of the same kind as
5054 @item @emph{See also}:
5055 @ref{IBCLR}, @ref{IBITS}, @ref{IAND}, @ref{IOR}, @ref{IEOR}, @ref{MVBITS}
5062 @section @code{ICHAR} --- Character-to-integer conversion function
5064 @cindex conversion, to integer
5067 @item @emph{Description}:
5068 @code{ICHAR(C)} returns the code for the character in the first character
5069 position of @code{C} in the system's native character set.
5070 The correspondence between characters and their codes is not necessarily
5071 the same across different GNU Fortran implementations.
5073 @item @emph{Standard}:
5079 @item @emph{Syntax}:
5080 @code{RESULT = ICHAR(C)}
5082 @item @emph{Arguments}:
5083 @multitable @columnfractions .15 .70
5084 @item @var{C} @tab Shall be a scalar @code{CHARACTER}, with @code{INTENT(IN)}
5087 @item @emph{Return value}:
5088 The return value is of type @code{INTEGER} and of the default integer
5091 @item @emph{Example}:
5096 end program test_ichar
5100 No intrinsic exists to convert between a numeric value and a formatted
5101 character string representation -- for instance, given the
5102 @code{CHARACTER} value @code{'154'}, obtaining an @code{INTEGER} or
5103 @code{REAL} value with the value 154, or vice versa. Instead, this
5104 functionality is provided by internal-file I/O, as in the following
5109 character(len=10) string, string2
5112 ! Convert a string to a numeric value
5113 read (string,'(I10)') value
5116 ! Convert a value to a formatted string
5117 write (string2,'(I10)') value
5119 end program read_val
5122 @item @emph{See also}:
5123 @ref{ACHAR}, @ref{CHAR}, @ref{IACHAR}
5130 @section @code{IDATE} --- Get current local time subroutine (day/month/year)
5132 @cindex date, current
5133 @cindex current date
5136 @item @emph{Description}:
5137 @code{IDATE(TARRAY)} Fills @var{TARRAY} with the numerical values at the
5138 current local time. The day (in the range 1-31), month (in the range 1-12),
5139 and year appear in elements 1, 2, and 3 of @var{TARRAY}, respectively.
5140 The year has four significant digits.
5142 @item @emph{Standard}:
5148 @item @emph{Syntax}:
5149 @code{CALL IDATE(TARRAY)}
5151 @item @emph{Arguments}:
5152 @multitable @columnfractions .15 .70
5153 @item @var{TARRAY} @tab The type shall be @code{INTEGER, DIMENSION(3)} and
5154 the kind shall be the default integer kind.
5157 @item @emph{Return value}:
5160 @item @emph{Example}:
5163 integer, dimension(3) :: tarray
5168 end program test_idate
5175 @section @code{IEOR} --- Bitwise logical exclusive or
5177 @cindex bitwise logical exclusive or
5178 @cindex logical exclusive or, bitwise
5181 @item @emph{Description}:
5182 @code{IEOR} returns the bitwise boolean exclusive-OR of @var{I} and
5185 @item @emph{Standard}:
5191 @item @emph{Syntax}:
5192 @code{RESULT = IEOR(I, J)}
5194 @item @emph{Arguments}:
5195 @multitable @columnfractions .15 .70
5196 @item @var{I} @tab The type shall be @code{INTEGER(*)}.
5197 @item @var{J} @tab The type shall be @code{INTEGER(*)}, of the same
5198 kind as @var{I}. (As a GNU extension, different kinds are also
5202 @item @emph{Return value}:
5203 The return type is @code{INTEGER(*)}, of the same kind as the
5204 arguments. (If the argument kinds differ, it is of the same kind as
5205 the larger argument.)
5207 @item @emph{See also}:
5208 @ref{IOR}, @ref{IAND}, @ref{IBITS}, @ref{IBSET}, @ref{IBCLR}, @ref{NOT}
5214 @section @code{IERRNO} --- Get the last system error number
5216 @cindex system, error handling
5219 @item @emph{Description}:
5220 Returns the last system error number, as given by the C @code{errno()}
5223 @item @emph{Standard}:
5227 Non-elemental function
5229 @item @emph{Syntax}:
5230 @code{RESULT = IERRNO()}
5232 @item @emph{Arguments}:
5235 @item @emph{Return value}:
5236 The return value is of type @code{INTEGER} and of the default integer
5239 @item @emph{See also}:
5246 @section @code{INDEX} --- Position of a substring within a string
5248 @cindex substring position
5249 @cindex string, find substring
5252 @item @emph{Description}:
5253 Returns the position of the start of the first occurrence of string
5254 @var{SUBSTRING} as a substring in @var{STRING}, counting from one. If
5255 @var{SUBSTRING} is not present in @var{STRING}, zero is returned. If
5256 the @var{BACK} argument is present and true, the return value is the
5257 start of the last occurrence rather than the first.
5259 @item @emph{Standard}:
5265 @item @emph{Syntax}:
5266 @code{RESULT = INDEX(STRING, SUBSTRING [, BACK])}
5268 @item @emph{Arguments}:
5269 @multitable @columnfractions .15 .70
5270 @item @var{STRING} @tab Shall be a scalar @code{CHARACTER(*)}, with
5272 @item @var{SUBSTRING} @tab Shall be a scalar @code{CHARACTER(*)}, with
5274 @item @var{BACK} @tab (Optional) Shall be a scalar @code{LOGICAL(*)}, with
5278 @item @emph{Return value}:
5279 The return value is of type @code{INTEGER} and of the default integer
5282 @item @emph{See also}:
5283 @ref{SCAN}, @ref{VERIFY}
5289 @section @code{INT} --- Convert to integer type
5293 @cindex conversion, to integer
5296 @item @emph{Description}:
5297 Convert to integer type
5299 @item @emph{Standard}:
5305 @item @emph{Syntax}:
5306 @code{RESULT = INT(A [, KIND))}
5308 @item @emph{Arguments}:
5309 @multitable @columnfractions .15 .70
5310 @item @var{A} @tab Shall be of type @code{INTEGER(*)},
5311 @code{REAL(*)}, or @code{COMPLEX(*)}.
5312 @item @var{KIND} @tab (Optional) An @code{INTEGER(*)} initialization
5313 expression indicating the kind parameter of
5317 @item @emph{Return value}:
5318 These functions return a @code{INTEGER(*)} variable or array under
5319 the following rules:
5323 If @var{A} is of type @code{INTEGER(*)}, @code{INT(A) = A}
5325 If @var{A} is of type @code{REAL(*)} and @math{|A| < 1}, @code{INT(A)} equals @code{0}.
5326 If @math{|A| \geq 1}, then @code{INT(A)} equals the largest integer that does not exceed
5327 the range of @var{A} and whose sign is the same as the sign of @var{A}.
5329 If @var{A} is of type @code{COMPLEX(*)}, rule B is applied to the real part of @var{A}.
5332 @item @emph{Example}:
5336 complex :: z = (-3.7, 1.0)
5338 print *, int(z), int(z,8)
5342 @item @emph{Specific names}:
5343 @multitable @columnfractions .20 .20 .20 .25
5344 @item Name @tab Argument @tab Return type @tab Standard
5345 @item @code{IFIX(A)} @tab @code{REAL(4) A} @tab @code{INTEGER} @tab F77 and later
5346 @item @code{IDINT(A)} @tab @code{REAL(8) A} @tab @code{INTEGER} @tab F77 and later
5354 @section @code{INT2} --- Convert to 16-bit integer type
5357 @cindex conversion, to integer
5360 @item @emph{Description}:
5361 Convert to a @code{KIND=2} integer type. This is equivalent to the
5362 standard @code{INT} intrinsic with an optional argument of
5363 @code{KIND=2}, and is only included for backwards compatibility.
5365 The @code{SHORT} intrinsic is equivalent to @code{INT2}.
5367 @item @emph{Standard}:
5373 @item @emph{Syntax}:
5374 @code{RESULT = INT2(A)}
5376 @item @emph{Arguments}:
5377 @multitable @columnfractions .15 .70
5378 @item @var{A} @tab Shall be of type @code{INTEGER(*)},
5379 @code{REAL(*)}, or @code{COMPLEX(*)}.
5382 @item @emph{Return value}:
5383 The return value is a @code{INTEGER(2)} variable.
5385 @item @emph{See also}:
5386 @ref{INT}, @ref{INT8}, @ref{LONG}
5392 @section @code{INT8} --- Convert to 64-bit integer type
5394 @cindex conversion, to integer
5397 @item @emph{Description}:
5398 Convert to a @code{KIND=8} integer type. This is equivalent to the
5399 standard @code{INT} intrinsic with an optional argument of
5400 @code{KIND=8}, and is only included for backwards compatibility.
5402 @item @emph{Standard}:
5408 @item @emph{Syntax}:
5409 @code{RESULT = INT8(A)}
5411 @item @emph{Arguments}:
5412 @multitable @columnfractions .15 .70
5413 @item @var{A} @tab Shall be of type @code{INTEGER(*)},
5414 @code{REAL(*)}, or @code{COMPLEX(*)}.
5417 @item @emph{Return value}:
5418 The return value is a @code{INTEGER(8)} variable.
5420 @item @emph{See also}:
5421 @ref{INT}, @ref{INT2}, @ref{LONG}
5427 @section @code{IOR} --- Bitwise logical or
5429 @cindex bitwise logical or
5430 @cindex logical or, bitwise
5433 @item @emph{Description}:
5434 @code{IEOR} returns the bitwise boolean OR of @var{I} and
5437 @item @emph{Standard}:
5443 @item @emph{Syntax}:
5444 @code{RESULT = IEOR(I, J)}
5446 @item @emph{Arguments}:
5447 @multitable @columnfractions .15 .70
5448 @item @var{I} @tab The type shall be @code{INTEGER(*)}.
5449 @item @var{J} @tab The type shall be @code{INTEGER(*)}, of the same
5450 kind as @var{I}. (As a GNU extension, different kinds are also
5454 @item @emph{Return value}:
5455 The return type is @code{INTEGER(*)}, of the same kind as the
5456 arguments. (If the argument kinds differ, it is of the same kind as
5457 the larger argument.)
5459 @item @emph{See also}:
5460 @ref{IEOR}, @ref{IAND}, @ref{IBITS}, @ref{IBSET}, @ref{IBCLR}, @ref{NOT}
5466 @section @code{IRAND} --- Integer pseudo-random number
5468 @cindex random number generation
5471 @item @emph{Description}:
5472 @code{IRAND(FLAG)} returns a pseudo-random number from a uniform
5473 distribution between 0 and a system-dependent limit (which is in most
5474 cases 2147483647). If @var{FLAG} is 0, the next number
5475 in the current sequence is returned; if @var{FLAG} is 1, the generator
5476 is restarted by @code{CALL SRAND(0)}; if @var{FLAG} has any other value,
5477 it is used as a new seed with @code{SRAND}.
5479 @item @emph{Standard}:
5483 Non-elemental function
5485 @item @emph{Syntax}:
5486 @code{RESULT = IRAND(FLAG)}
5488 @item @emph{Arguments}:
5489 @multitable @columnfractions .15 .70
5490 @item @var{FLAG} @tab Shall be a scalar @code{INTEGER} of kind 4.
5493 @item @emph{Return value}:
5494 The return value is of @code{INTEGER(kind=4)} type.
5496 @item @emph{Example}:
5499 integer,parameter :: seed = 86456
5502 print *, irand(), irand(), irand(), irand()
5503 print *, irand(seed), irand(), irand(), irand()
5504 end program test_irand
5512 @section @code{ISATTY} --- Whether a unit is a terminal device.
5514 @cindex system, terminal
5517 @item @emph{Description}:
5518 Determine whether a unit is connected to a terminal device.
5520 @item @emph{Standard}:
5524 Non-elemental function.
5526 @item @emph{Syntax}:
5527 @code{RESULT = ISATTY(UNIT)}
5529 @item @emph{Arguments}:
5530 @multitable @columnfractions .15 .70
5531 @item @var{UNIT} @tab Shall be a scalar @code{INTEGER(*)}.
5534 @item @emph{Return value}:
5535 Returns @code{.TRUE.} if the @var{UNIT} is connected to a terminal
5536 device, @code{.FALSE.} otherwise.
5538 @item @emph{Example}:
5541 INTEGER(kind=1) :: unit
5543 write(*,*) isatty(unit=unit)
5547 @item @emph{See also}:
5554 @section @code{ISHFT} --- Shift bits
5559 @item @emph{Description}:
5560 @code{ISHFT} returns a value corresponding to @var{I} with all of the
5561 bits shifted @var{SHIFT} places. A value of @var{SHIFT} greater than
5562 zero corresponds to a left shift, a value of zero corresponds to no
5563 shift, and a value less than zero corresponds to a right shift. If the
5564 absolute value of @var{SHIFT} is greater than @code{BIT_SIZE(I)}, the
5565 value is undefined. Bits shifted out from the left end or right end are
5566 lost; zeros are shifted in from the opposite end.
5568 @item @emph{Standard}:
5574 @item @emph{Syntax}:
5575 @code{RESULT = ISHFT(I, SHIFT)}
5577 @item @emph{Arguments}:
5578 @multitable @columnfractions .15 .70
5579 @item @var{I} @tab The type shall be @code{INTEGER(*)}.
5580 @item @var{SHIFT} @tab The type shall be @code{INTEGER(*)}.
5583 @item @emph{Return value}:
5584 The return value is of type @code{INTEGER(*)} and of the same kind as
5587 @item @emph{See also}:
5594 @section @code{ISHFTC} --- Shift bits circularly
5596 @cindex bits, shift circular
5599 @item @emph{Description}:
5600 @code{ISHFTC} returns a value corresponding to @var{I} with the
5601 rightmost @var{SIZE} bits shifted circularly @var{SHIFT} places; that
5602 is, bits shifted out one end are shifted into the opposite end. A value
5603 of @var{SHIFT} greater than zero corresponds to a left shift, a value of
5604 zero corresponds to no shift, and a value less than zero corresponds to
5605 a right shift. The absolute value of @var{SHIFT} must be less than
5606 @var{SIZE}. If the @var{SIZE} argument is omitted, it is taken to be
5607 equivalent to @code{BIT_SIZE(I)}.
5609 @item @emph{Standard}:
5615 @item @emph{Syntax}:
5616 @code{RESULT = ISHFTC(I, SHIFT [, SIZE])}
5618 @item @emph{Arguments}:
5619 @multitable @columnfractions .15 .70
5620 @item @var{I} @tab The type shall be @code{INTEGER(*)}.
5621 @item @var{SHIFT} @tab The type shall be @code{INTEGER(*)}.
5622 @item @var{SIZE} @tab (Optional) The type shall be @code{INTEGER(*)};
5623 the value must be greater than zero and less than or equal to
5627 @item @emph{Return value}:
5628 The return value is of type @code{INTEGER(*)} and of the same kind as
5631 @item @emph{See also}:
5638 @section @code{ITIME} --- Get current local time subroutine (hour/minutes/seconds)
5640 @cindex time, current
5641 @cindex current time
5644 @item @emph{Description}:
5645 @code{IDATE(TARRAY)} Fills @var{TARRAY} with the numerical values at the
5646 current local time. The hour (in the range 1-24), minute (in the range 1-60),
5647 and seconds (in the range 1-60) appear in elements 1, 2, and 3 of @var{TARRAY},
5650 @item @emph{Standard}:
5656 @item @emph{Syntax}:
5657 @code{CALL ITIME(TARRAY)}
5659 @item @emph{Arguments}:
5660 @multitable @columnfractions .15 .70
5661 @item @var{TARRAY} @tab The type shall be @code{INTEGER, DIMENSION(3)}
5662 and the kind shall be the default integer kind.
5665 @item @emph{Return value}:
5669 @item @emph{Example}:
5672 integer, dimension(3) :: tarray
5677 end program test_itime
5684 @section @code{KILL} --- Send a signal to a process
5688 @item @emph{Description}:
5689 @item @emph{Standard}:
5690 Sends the signal specified by @var{SIGNAL} to the process @var{PID}.
5696 @item @emph{Syntax}:
5697 @code{CALL KILL(PID, SIGNAL [, STATUS])}
5699 @item @emph{Arguments}:
5700 @multitable @columnfractions .15 .70
5701 @item @var{PID} @tab Shall be a scalar @code{INTEGER}, with
5703 @item @var{SIGNAL} @tab Shall be a scalar @code{INTEGER}, with
5705 @item @var{STATUS} @tab (Optional) status flag of type @code{INTEGER(4)} or
5706 @code{INTEGER(8)}. Returns 0 on success, or a
5707 system-specific error code otherwise.
5710 @item @emph{See also}:
5711 @ref{ABORT}, @ref{EXIT}
5717 @section @code{KIND} --- Kind of an entity
5722 @item @emph{Description}:
5723 @code{KIND(X)} returns the kind value of the entity @var{X}.
5725 @item @emph{Standard}:
5731 @item @emph{Syntax}:
5734 @item @emph{Arguments}:
5735 @multitable @columnfractions .15 .70
5736 @item @var{X} @tab Shall be of type @code{LOGICAL}, @code{INTEGER},
5737 @code{REAL}, @code{COMPLEX} or @code{CHARACTER}.
5740 @item @emph{Return value}:
5741 The return value is a scalar of type @code{INTEGER} and of the default
5744 @item @emph{Example}:
5747 integer,parameter :: kc = kind(' ')
5748 integer,parameter :: kl = kind(.true.)
5750 print *, "The default character kind is ", kc
5751 print *, "The default logical kind is ", kl
5752 end program test_kind
5760 @section @code{LBOUND} --- Lower dimension bounds of an array
5762 @cindex array, lower bound
5765 @item @emph{Description}:
5766 Returns the lower bounds of an array, or a single lower bound
5767 along the @var{DIM} dimension.
5768 @item @emph{Standard}:
5774 @item @emph{Syntax}:
5775 @code{RESULT = LBOUND(ARRAY [, DIM])}
5777 @item @emph{Arguments}:
5778 @multitable @columnfractions .15 .70
5779 @item @var{ARRAY} @tab Shall be an array, of any type.
5780 @item @var{DIM} @tab (Optional) Shall be a scalar @code{INTEGER(*)}.
5783 @item @emph{Return value}:
5784 If @var{DIM} is absent, the result is an array of the lower bounds of
5785 @var{ARRAY}. If @var{DIM} is present, the result is a scalar
5786 corresponding to the lower bound of the array along that dimension. If
5787 @var{ARRAY} is an expression rather than a whole array or array
5788 structure component, or if it has a zero extent along the relevant
5789 dimension, the lower bound is taken to be 1.
5791 @item @emph{See also}:
5798 @section @code{LEN} --- Length of a character entity
5800 @cindex string, length
5803 @item @emph{Description}:
5804 Returns the length of a character string. If @var{STRING} is an array,
5805 the length of an element of @var{STRING} is returned. Note that
5806 @var{STRING} need not be defined when this intrinsic is invoked, since
5807 only the length, not the content, of @var{STRING} is needed.
5809 @item @emph{Standard}:
5815 @item @emph{Syntax}:
5816 @code{L = LEN(STRING)}
5818 @item @emph{Arguments}:
5819 @multitable @columnfractions .15 .70
5820 @item @var{STRING} @tab Shall be a scalar or array of type
5821 @code{CHARACTER(*)}, with @code{INTENT(IN)}
5824 @item @emph{Return value}:
5825 The return value is an @code{INTEGER} of the default kind.
5827 @item @emph{See also}:
5828 @ref{LEN_TRIM}, @ref{ADJUSTL}, @ref{ADJUSTR}
5834 @section @code{LEN_TRIM} --- Length of a character entity without trailing blank characters
5836 @cindex string, length, without trailing whitespace
5839 @item @emph{Description}:
5840 Returns the length of a character string, ignoring any trailing blanks.
5842 @item @emph{Standard}:
5848 @item @emph{Syntax}:
5849 @code{RESULT = LEN_TRIM(STRING)}
5851 @item @emph{Arguments}:
5852 @multitable @columnfractions .15 .70
5853 @item @var{STRING} @tab Shall be a scalar of type @code{CHARACTER(*)},
5854 with @code{INTENT(IN)}
5857 @item @emph{Return value}:
5858 The return value is an @code{INTEGER} of the default kind.
5860 @item @emph{See also}:
5861 @ref{LEN}, @ref{ADJUSTL}, @ref{ADJUSTR}
5867 @section @code{LGE} --- Lexical greater than or equal
5869 @cindex lexical comparison of strings
5870 @cindex string, comparison
5873 @item @emph{Description}:
5874 Determines whether one string is lexically greater than or equal to
5875 another string, where the two strings are interpreted as containing
5876 ASCII character codes. If the String A and String B are not the same
5877 length, the shorter is compared as if spaces were appended to it to form
5878 a value that has the same length as the longer.
5880 In general, the lexical comparison intrinsics @code{LGE}, @code{LGT},
5881 @code{LLE}, and @code{LLT} differ from the corresponding intrinsic
5882 operators @code{.GE.}, @code{.GT.}, @code{.LE.}, and @code{.LT.}, in
5883 that the latter use the processor's character ordering (which is not
5884 ASCII on some targets), whereas the former always use the ASCII
5887 @item @emph{Standard}:
5893 @item @emph{Syntax}:
5894 @code{RESULT = LGE(STRING_A, STRING_B)}
5896 @item @emph{Arguments}:
5897 @multitable @columnfractions .15 .70
5898 @item @var{STRING_A} @tab Shall be of default @code{CHARACTER} type.
5899 @item @var{STRING_B} @tab Shall be of default @code{CHARACTER} type.
5902 @item @emph{Return value}:
5903 Returns @code{.TRUE.} if @code{STRING_A >= STRING_B}, and @code{.FALSE.}
5904 otherwise, based on the ASCII ordering.
5906 @item @emph{See also}:
5907 @ref{LGT}, @ref{LLE}, @ref{LLT}
5913 @section @code{LGT} --- Lexical greater than
5915 @cindex lexical comparison of strings
5916 @cindex string, comparison
5919 @item @emph{Description}:
5920 Determines whether one string is lexically greater than another string,
5921 where the two strings are interpreted as containing ASCII character
5922 codes. If the String A and String B are not the same length, the
5923 shorter is compared as if spaces were appended to it to form a value
5924 that has the same length as the longer.
5926 In general, the lexical comparison intrinsics @code{LGE}, @code{LGT},
5927 @code{LLE}, and @code{LLT} differ from the corresponding intrinsic
5928 operators @code{.GE.}, @code{.GT.}, @code{.LE.}, and @code{.LT.}, in
5929 that the latter use the processor's character ordering (which is not
5930 ASCII on some targets), whereas the former always use the ASCII
5933 @item @emph{Standard}:
5939 @item @emph{Syntax}:
5940 @code{RESULT = LGT(STRING_A, STRING_B)}
5942 @item @emph{Arguments}:
5943 @multitable @columnfractions .15 .70
5944 @item @var{STRING_A} @tab Shall be of default @code{CHARACTER} type.
5945 @item @var{STRING_B} @tab Shall be of default @code{CHARACTER} type.
5948 @item @emph{Return value}:
5949 Returns @code{.TRUE.} if @code{STRING_A > STRING_B}, and @code{.FALSE.}
5950 otherwise, based on the ASCII ordering.
5952 @item @emph{See also}:
5953 @ref{LGE}, @ref{LLE}, @ref{LLT}
5959 @section @code{LINK} --- Create a hard link
5961 @cindex file system, create link
5962 @cindex file system, hard link
5965 @item @emph{Description}:
5966 Makes a (hard) link from file @var{PATH1} to @var{PATH2}. A null
5967 character (@code{CHAR(0)}) can be used to mark the end of the names in
5968 @var{PATH1} and @var{PATH2}; otherwise, trailing blanks in the file
5969 names are ignored. If the @var{STATUS} argument is supplied, it
5970 contains 0 on success or a nonzero error code upon return; see
5973 This intrinsic is provided in both subroutine and function forms;
5974 however, only one form can be used in any given program unit.
5976 @item @emph{Standard}:
5980 Subroutine, non-elemental function
5982 @item @emph{Syntax}:
5983 @multitable @columnfractions .80
5984 @item @code{CALL LINK(PATH1, PATH2 [, STATUS])}
5985 @item @code{STATUS = LINK(PATH1, PATH2)}
5988 @item @emph{Arguments}:
5989 @multitable @columnfractions .15 .70
5990 @item @var{PATH1} @tab Shall be of default @code{CHARACTER} type.
5991 @item @var{PATH2} @tab Shall be of default @code{CHARACTER} type.
5992 @item @var{STATUS} @tab (Optional) Shall be of default @code{INTEGER} type.
5995 @item @emph{See also}:
5996 @ref{SYMLNK}, @ref{UNLINK}
6002 @section @code{LLE} --- Lexical less than or equal
6004 @cindex lexical comparison of strings
6005 @cindex string, comparison
6008 @item @emph{Description}:
6009 Determines whether one string is lexically less than or equal to another
6010 string, where the two strings are interpreted as containing ASCII
6011 character codes. If the String A and String B are not the same length,
6012 the shorter is compared as if spaces were appended to it to form a value
6013 that has the same length as the longer.
6015 In general, the lexical comparison intrinsics @code{LGE}, @code{LGT},
6016 @code{LLE}, and @code{LLT} differ from the corresponding intrinsic
6017 operators @code{.GE.}, @code{.GT.}, @code{.LE.}, and @code{.LT.}, in
6018 that the latter use the processor's character ordering (which is not
6019 ASCII on some targets), whereas the former always use the ASCII
6022 @item @emph{Standard}:
6028 @item @emph{Syntax}:
6029 @code{RESULT = LLE(STRING_A, STRING_B)}
6031 @item @emph{Arguments}:
6032 @multitable @columnfractions .15 .70
6033 @item @var{STRING_A} @tab Shall be of default @code{CHARACTER} type.
6034 @item @var{STRING_B} @tab Shall be of default @code{CHARACTER} type.
6037 @item @emph{Return value}:
6038 Returns @code{.TRUE.} if @code{STRING_A <= STRING_B}, and @code{.FALSE.}
6039 otherwise, based on the ASCII ordering.
6041 @item @emph{See also}:
6042 @ref{LGE}, @ref{LGT}, @ref{LLT}
6048 @section @code{LLT} --- Lexical less than
6050 @cindex lexical comparison of strings
6051 @cindex string, comparison
6054 @item @emph{Description}:
6055 Determines whether one string is lexically less than another string,
6056 where the two strings are interpreted as containing ASCII character
6057 codes. If the String A and String B are not the same length, the
6058 shorter is compared as if spaces were appended to it to form a value
6059 that has the same length as the longer.
6061 In general, the lexical comparison intrinsics @code{LGE}, @code{LGT},
6062 @code{LLE}, and @code{LLT} differ from the corresponding intrinsic
6063 operators @code{.GE.}, @code{.GT.}, @code{.LE.}, and @code{.LT.}, in
6064 that the latter use the processor's character ordering (which is not
6065 ASCII on some targets), whereas the former always use the ASCII
6068 @item @emph{Standard}:
6074 @item @emph{Syntax}:
6075 @code{RESULT = LLT(STRING_A, STRING_B)}
6077 @item @emph{Arguments}:
6078 @multitable @columnfractions .15 .70
6079 @item @var{STRING_A} @tab Shall be of default @code{CHARACTER} type.
6080 @item @var{STRING_B} @tab Shall be of default @code{CHARACTER} type.
6083 @item @emph{Return value}:
6084 Returns @code{.TRUE.} if @code{STRING_A < STRING_B}, and @code{.FALSE.}
6085 otherwise, based on the ASCII ordering.
6087 @item @emph{See also}:
6088 @ref{LGE}, @ref{LGT}, @ref{LLE}
6094 @section @code{LNBLNK} --- Index of the last non-blank character in a string
6096 @cindex string, find non-blank character
6099 @item @emph{Description}:
6100 Returns the length of a character string, ignoring any trailing blanks.
6101 This is identical to the standard @code{LEN_TRIM} intrinsic, and is only
6102 included for backwards compatibility.
6104 @item @emph{Standard}:
6110 @item @emph{Syntax}:
6111 @code{RESULT = LNBLNK(STRING)}
6113 @item @emph{Arguments}:
6114 @multitable @columnfractions .15 .70
6115 @item @var{STRING} @tab Shall be a scalar of type @code{CHARACTER(*)},
6116 with @code{INTENT(IN)}
6119 @item @emph{Return value}:
6120 The return value is of @code{INTEGER(kind=4)} type.
6122 @item @emph{See also}:
6123 @ref{INDEX}, @ref{LEN_TRIM}
6129 @section @code{LOC} --- Returns the address of a variable
6131 @cindex location of a variable in memory
6134 @item @emph{Description}:
6135 @code{LOC(X)} returns the address of @var{X} as an integer.
6137 @item @emph{Standard}:
6143 @item @emph{Syntax}:
6144 @code{RESULT = LOC(X)}
6146 @item @emph{Arguments}:
6147 @multitable @columnfractions .15 .70
6148 @item @var{X} @tab Variable of any type.
6151 @item @emph{Return value}:
6152 The return value is of type @code{INTEGER}, with a @code{KIND}
6153 corresponding to the size (in bytes) of a memory address on the target
6156 @item @emph{Example}:
6163 end program test_loc
6170 @section @code{LOG} --- Logarithm function
6177 @cindex exponential function, inverse
6178 @cindex logarithmic function
6181 @item @emph{Description}:
6182 @code{LOG(X)} computes the logarithm of @var{X}.
6184 @item @emph{Standard}:
6190 @item @emph{Syntax}:
6191 @code{RESULT = LOG(X)}
6193 @item @emph{Arguments}:
6194 @multitable @columnfractions .15 .70
6195 @item @var{X} @tab The type shall be @code{REAL(*)} or
6199 @item @emph{Return value}:
6200 The return value is of type @code{REAL(*)} or @code{COMPLEX(*)}.
6201 The kind type parameter is the same as @var{X}.
6203 @item @emph{Example}:
6206 real(8) :: x = 1.0_8
6207 complex :: z = (1.0, 2.0)
6210 end program test_log
6213 @item @emph{Specific names}:
6214 @multitable @columnfractions .20 .20 .20 .25
6215 @item Name @tab Argument @tab Return type @tab Standard
6216 @item @code{ALOG(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab f95, gnu
6217 @item @code{DLOG(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab f95, gnu
6218 @item @code{CLOG(X)} @tab @code{COMPLEX(4) X} @tab @code{COMPLEX(4)} @tab f95, gnu
6219 @item @code{ZLOG(X)} @tab @code{COMPLEX(8) X} @tab @code{COMPLEX(8)} @tab f95, gnu
6220 @item @code{CDLOG(X)} @tab @code{COMPLEX(8) X} @tab @code{COMPLEX(8)} @tab f95, gnu
6227 @section @code{LOG10} --- Base 10 logarithm function
6231 @cindex exponential function, inverse
6232 @cindex logarithmic function
6235 @item @emph{Description}:
6236 @code{LOG10(X)} computes the base 10 logarithm of @var{X}.
6238 @item @emph{Standard}:
6244 @item @emph{Syntax}:
6245 @code{RESULT = LOG10(X)}
6247 @item @emph{Arguments}:
6248 @multitable @columnfractions .15 .70
6249 @item @var{X} @tab The type shall be @code{REAL(*)}.
6252 @item @emph{Return value}:
6253 The return value is of type @code{REAL(*)} or @code{COMPLEX(*)}.
6254 The kind type parameter is the same as @var{X}.
6256 @item @emph{Example}:
6259 real(8) :: x = 10.0_8
6261 end program test_log10
6264 @item @emph{Specific names}:
6265 @multitable @columnfractions .20 .20 .20 .25
6266 @item Name @tab Argument @tab Return type @tab Standard
6267 @item @code{ALOG10(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab F95 and later
6268 @item @code{DLOG10(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab F95 and later
6275 @section @code{LOGICAL} --- Convert to logical type
6277 @cindex conversion, to logical
6280 @item @emph{Description}:
6281 Converts one kind of @code{LOGICAL} variable to another.
6283 @item @emph{Standard}:
6289 @item @emph{Syntax}:
6290 @code{RESULT = LOGICAL(L [, KIND])}
6292 @item @emph{Arguments}:
6293 @multitable @columnfractions .15 .70
6294 @item @var{L} @tab The type shall be @code{LOGICAL(*)}.
6295 @item @var{KIND} @tab (Optional) An @code{INTEGER(*)} initialization
6296 expression indicating the kind parameter of
6300 @item @emph{Return value}:
6301 The return value is a @code{LOGICAL} value equal to @var{L}, with a
6302 kind corresponding to @var{KIND}, or of the default logical kind if
6303 @var{KIND} is not given.
6305 @item @emph{See also}:
6306 @ref{INT}, @ref{REAL}, @ref{CMPLX}
6312 @section @code{LONG} --- Convert to integer type
6314 @cindex conversion, to integer
6317 @item @emph{Description}:
6318 Convert to a @code{KIND=4} integer type, which is the same size as a C
6319 @code{long} integer. This is equivalent to the standard @code{INT}
6320 intrinsic with an optional argument of @code{KIND=4}, and is only
6321 included for backwards compatibility.
6323 @item @emph{Standard}:
6329 @item @emph{Syntax}:
6330 @code{RESULT = LONG(A)}
6332 @item @emph{Arguments}:
6333 @multitable @columnfractions .15 .70
6334 @item @var{A} @tab Shall be of type @code{INTEGER(*)},
6335 @code{REAL(*)}, or @code{COMPLEX(*)}.
6338 @item @emph{Return value}:
6339 The return value is a @code{INTEGER(4)} variable.
6341 @item @emph{See also}:
6342 @ref{INT}, @ref{INT2}, @ref{INT8}
6348 @section @code{LSHIFT} --- Left shift bits
6350 @cindex bits, shift left
6353 @item @emph{Description}:
6354 @code{LSHIFT} returns a value corresponding to @var{I} with all of the
6355 bits shifted left by @var{SHIFT} places. If the absolute value of
6356 @var{SHIFT} is greater than @code{BIT_SIZE(I)}, the value is undefined.
6357 Bits shifted out from the left end are lost; zeros are shifted in from
6360 This function has been superseded by the @code{ISHFT} intrinsic, which
6361 is standard in Fortran 95 and later.
6363 @item @emph{Standard}:
6369 @item @emph{Syntax}:
6370 @code{RESULT = LSHIFT(I, SHIFT)}
6372 @item @emph{Arguments}:
6373 @multitable @columnfractions .15 .70
6374 @item @var{I} @tab The type shall be @code{INTEGER(*)}.
6375 @item @var{SHIFT} @tab The type shall be @code{INTEGER(*)}.
6378 @item @emph{Return value}:
6379 The return value is of type @code{INTEGER(*)} and of the same kind as
6382 @item @emph{See also}:
6383 @ref{ISHFT}, @ref{ISHFTC}, @ref{RSHIFT}
6390 @section @code{LSTAT} --- Get file status
6392 @cindex file system, file status
6395 @item @emph{Description}:
6396 @code{LSTAT} is identical to @ref{STAT}, except that if path is a symbolic link,
6397 then the link itself is statted, not the file that it refers to.
6399 The elements in @code{BUFF} are the same as described by @ref{STAT}.
6401 @item @emph{Standard}:
6405 Non-elemental subroutine
6407 @item @emph{Syntax}:
6408 @code{CALL LSTAT(FILE, BUFF [, STATUS])}
6410 @item @emph{Arguments}:
6411 @multitable @columnfractions .15 .70
6412 @item @var{FILE} @tab The type shall be @code{CHARACTER(*)}, a valid path within the file system.
6413 @item @var{BUFF} @tab The type shall be @code{INTEGER(4), DIMENSION(13)}.
6414 @item @var{STATUS} @tab (Optional) status flag of type @code{INTEGER(4)}. Returns 0
6415 on success and a system specific error code otherwise.
6418 @item @emph{Example}:
6419 See @ref{STAT} for an example.
6421 @item @emph{See also}:
6422 To stat an open file: @ref{FSTAT}, to stat a file: @ref{STAT}
6428 @section @code{LTIME} --- Convert time to local time info
6430 @cindex time, conversion to local time info
6433 @item @emph{Description}:
6434 Given a system time value @var{STIME} (as provided by the @code{TIME8()}
6435 intrinsic), fills @var{TARRAY} with values extracted from it appropriate
6436 to the local time zone using @code{localtime(3)}.
6438 @item @emph{Standard}:
6444 @item @emph{Syntax}:
6445 @code{CALL LTIME(STIME, TARRAY)}
6447 @item @emph{Arguments}:
6448 @multitable @columnfractions .15 .70
6449 @item @var{STIME} @tab An @code{INTEGER(*)} scalar expression
6450 corresponding to a system time, with
6452 @item @var{TARRAY} @tab A default @code{INTEGER} array with 9 elements,
6453 with @code{INTENT(OUT)}.
6456 @item @emph{Return value}:
6457 The elements of @var{TARRAY} are assigned as follows:
6459 @item Seconds after the minute, range 0--59 or 0--61 to allow for leap
6461 @item Minutes after the hour, range 0--59
6462 @item Hours past midnight, range 0--23
6463 @item Day of month, range 0--31
6464 @item Number of months since January, range 0--12
6465 @item Years since 1900
6466 @item Number of days since Sunday, range 0--6
6467 @item Days since January 1
6468 @item Daylight savings indicator: positive if daylight savings is in
6469 effect, zero if not, and negative if the information is not
6473 @item @emph{See also}:
6474 @ref{CTIME}, @ref{GMTIME}, @ref{TIME}, @ref{TIME8}
6481 @section @code{MALLOC} --- Allocate dynamic memory
6483 @cindex pointer, cray
6486 @item @emph{Description}:
6487 @code{MALLOC(SIZE)} allocates @var{SIZE} bytes of dynamic memory and
6488 returns the address of the allocated memory. The @code{MALLOC} intrinsic
6489 is an extension intended to be used with Cray pointers, and is provided
6490 in GNU Fortran to allow the user to compile legacy code. For new code
6491 using Fortran 95 pointers, the memory allocation intrinsic is
6494 @item @emph{Standard}:
6498 Non-elemental function
6500 @item @emph{Syntax}:
6501 @code{PTR = MALLOC(SIZE)}
6503 @item @emph{Arguments}:
6504 @multitable @columnfractions .15 .70
6505 @item @var{SIZE} @tab The type shall be @code{INTEGER(*)}.
6508 @item @emph{Return value}:
6509 The return value is of type @code{INTEGER(K)}, with @var{K} such that
6510 variables of type @code{INTEGER(K)} have the same size as
6511 C pointers (@code{sizeof(void *)}).
6513 @item @emph{Example}:
6514 The following example demonstrates the use of @code{MALLOC} and
6515 @code{FREE} with Cray pointers. This example is intended to run on
6516 32-bit systems, where the default integer kind is suitable to store
6517 pointers; on 64-bit systems, ptr_x would need to be declared as
6518 @code{integer(kind=8)}.
6527 ptr_x = malloc(20*8)
6529 x(i) = sqrt(1.0d0 / i)
6537 end program test_malloc
6540 @item @emph{See also}:
6547 @section @code{MATMUL} --- matrix multiplication
6549 @cindex matrix multiplication
6550 @cindex product, matrix
6553 @item @emph{Description}:
6554 Performs a matrix multiplication on numeric or logical arguments.
6556 @item @emph{Standard}:
6560 Transformational function
6562 @item @emph{Syntax}:
6563 @code{RESULT = MATMUL(MATRIX_A, MATRIX_B)}
6565 @item @emph{Arguments}:
6566 @multitable @columnfractions .15 .70
6567 @item @var{MATRIX_A} @tab An array of @code{INTEGER(*)},
6568 @code{REAL(*)}, @code{COMPLEX(*)}, or
6569 @code{LOGICAL(*)} type, with a rank of
6571 @item @var{MATRIX_B} @tab An array of @code{INTEGER(*)},
6572 @code{REAL(*)}, or @code{COMPLEX(*)} type if
6573 @var{MATRIX_A} is of a numeric type;
6574 otherwise, an array of @code{LOGICAL(*)}
6575 type. The rank shall be one or two, and the
6576 first (or only) dimension of @var{MATRIX_B}
6577 shall be equal to the last (or only)
6578 dimension of @var{MATRIX_A}.
6581 @item @emph{Return value}:
6582 The matrix product of @var{MATRIX_A} and @var{MATRIX_B}. The type and
6583 kind of the result follow the usual type and kind promotion rules, as
6584 for the @code{*} or @code{.AND.} operators.
6586 @item @emph{See also}:
6592 @section @code{MAX} --- Maximum value of an argument list
6599 @cindex maximum value
6602 @item @emph{Description}:
6603 Returns the argument with the largest (most positive) value.
6605 @item @emph{Standard}:
6611 @item @emph{Syntax}:
6612 @code{RESULT = MAX(A1, A2 [, A3 [, ...]])}
6614 @item @emph{Arguments}:
6615 @multitable @columnfractions .15 .70
6616 @item @var{A1} @tab The type shall be @code{INTEGER(*)} or
6618 @item @var{A2}, @var{A3}, ... @tab An expression of the same type and kind
6619 as @var{A1}. (As a GNU extension,
6620 arguments of different kinds are
6624 @item @emph{Return value}:
6625 The return value corresponds to the maximum value among the arguments,
6626 and has the same type and kind as the first argument.
6628 @item @emph{Specific names}:
6629 @multitable @columnfractions .20 .20 .20 .25
6630 @item Name @tab Argument @tab Return type @tab Standard
6631 @item @code{MAX0(I)} @tab @code{INTEGER(4) I} @tab @code{INTEGER(4)} @tab F77 and later
6632 @item @code{AMAX0(I)} @tab @code{INTEGER(4) I} @tab @code{REAL(MAX(X))} @tab F77 and later
6633 @item @code{MAX1(X)} @tab @code{REAL(*) X} @tab @code{INT(MAX(X))} @tab F77 and later
6634 @item @code{AMAX1(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab F77 and later
6635 @item @code{DMAX1(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab F77 and later
6638 @item @emph{See also}:
6639 @ref{MAXLOC} @ref{MAXVAL}, @ref{MIN}
6646 @section @code{MAXEXPONENT} --- Maximum exponent of a real kind
6647 @fnindex MAXEXPONENT
6648 @cindex model representation, maximum exponent
6651 @item @emph{Description}:
6652 @code{MAXEXPONENT(X)} returns the maximum exponent in the model of the
6655 @item @emph{Standard}:
6661 @item @emph{Syntax}:
6662 @code{RESULT = MAXEXPONENT(X)}
6664 @item @emph{Arguments}:
6665 @multitable @columnfractions .15 .70
6666 @item @var{X} @tab Shall be of type @code{REAL}.
6669 @item @emph{Return value}:
6670 The return value is of type @code{INTEGER} and of the default integer
6673 @item @emph{Example}:
6679 print *, minexponent(x), maxexponent(x)
6680 print *, minexponent(y), maxexponent(y)
6681 end program exponents
6688 @section @code{MAXLOC} --- Location of the maximum value within an array
6690 @cindex array, location of maximum element
6693 @item @emph{Description}:
6694 Determines the location of the element in the array with the maximum
6695 value, or, if the @var{DIM} argument is supplied, determines the
6696 locations of the maximum element along each row of the array in the
6697 @var{DIM} direction. If @var{MASK} is present, only the elements for
6698 which @var{MASK} is @code{.TRUE.} are considered. If more than one
6699 element in the array has the maximum value, the location returned is
6700 that of the first such element in array element order. If the array has
6701 zero size, or all of the elements of @var{MASK} are @code{.FALSE.}, then
6702 the result is an array of zeroes. Similarly, if @var{DIM} is supplied
6703 and all of the elements of @var{MASK} along a given row are zero, the
6704 result value for that row is zero.
6706 @item @emph{Standard}:
6710 Transformational function
6712 @item @emph{Syntax}:
6713 @multitable @columnfractions .80
6714 @item @code{RESULT = MAXLOC(ARRAY, DIM [, MASK])}
6715 @item @code{RESULT = MAXLOC(ARRAY [, MASK])}
6718 @item @emph{Arguments}:
6719 @multitable @columnfractions .15 .70
6720 @item @var{ARRAY} @tab Shall be an array of type @code{INTEGER(*)},
6721 @code{REAL(*)}, or @code{CHARACTER(*)}.
6722 @item @var{DIM} @tab (Optional) Shall be a scalar of type
6723 @code{INTEGER(*)}, with a value between one
6724 and the rank of @var{ARRAY}, inclusive. It
6725 may not be an optional dummy argument.
6726 @item @var{MASK} @tab Shall be an array of type @code{LOGICAL(*)},
6727 and conformable with @var{ARRAY}.
6730 @item @emph{Return value}:
6731 If @var{DIM} is absent, the result is a rank-one array with a length
6732 equal to the rank of @var{ARRAY}. If @var{DIM} is present, the result
6733 is an array with a rank one less than the rank of @var{ARRAY}, and a
6734 size corresponding to the size of @var{ARRAY} with the @var{DIM}
6735 dimension removed. If @var{DIM} is present and @var{ARRAY} has a rank
6736 of one, the result is a scalar. In all cases, the result is of default
6737 @code{INTEGER} type.
6739 @item @emph{See also}:
6740 @ref{MAX}, @ref{MAXVAL}
6747 @section @code{MAXVAL} --- Maximum value of an array
6749 @cindex array, maximum value
6750 @cindex maximum value
6753 @item @emph{Description}:
6754 Determines the maximum value of the elements in an array value, or, if
6755 the @var{DIM} argument is supplied, determines the maximum value along
6756 each row of the array in the @var{DIM} direction. If @var{MASK} is
6757 present, only the elements for which @var{MASK} is @code{.TRUE.} are
6758 considered. If the array has zero size, or all of the elements of
6759 @var{MASK} are @code{.FALSE.}, then the result is the most negative
6760 number of the type and kind of @var{ARRAY} if @var{ARRAY} is numeric, or
6761 a string of nulls if @var{ARRAY} is of character type.
6763 @item @emph{Standard}:
6767 Transformational function
6769 @item @emph{Syntax}:
6770 @multitable @columnfractions .80
6771 @item @code{RESULT = MAXVAL(ARRAY, DIM [, MASK])}
6772 @item @code{RESULT = MAXVAL(ARRAY [, MASK])}
6775 @item @emph{Arguments}:
6776 @multitable @columnfractions .15 .70
6777 @item @var{ARRAY} @tab Shall be an array of type @code{INTEGER(*)},
6778 @code{REAL(*)}, or @code{CHARACTER(*)}.
6779 @item @var{DIM} @tab (Optional) Shall be a scalar of type
6780 @code{INTEGER(*)}, with a value between one
6781 and the rank of @var{ARRAY}, inclusive. It
6782 may not be an optional dummy argument.
6783 @item @var{MASK} @tab Shall be an array of type @code{LOGICAL(*)},
6784 and conformable with @var{ARRAY}.
6787 @item @emph{Return value}:
6788 If @var{DIM} is absent, or if @var{ARRAY} has a rank of one, the result
6789 is a scalar. If @var{DIM} is present, the result is an array with a
6790 rank one less than the rank of @var{ARRAY}, and a size corresponding to
6791 the size of @var{ARRAY} with the @var{DIM} dimension removed. In all
6792 cases, the result is of the same type and kind as @var{ARRAY}.
6794 @item @emph{See also}:
6795 @ref{MAX}, @ref{MAXLOC}
6801 @section @code{MCLOCK} --- Time function
6803 @cindex time, clock ticks
6807 @item @emph{Description}:
6808 Returns the number of clock ticks since the start of the process, based
6809 on the UNIX function @code{clock(3)}.
6811 This intrinsic is not fully portable, such as to systems with 32-bit
6812 @code{INTEGER} types but supporting times wider than 32 bits. Therefore,
6813 the values returned by this intrinsic might be, or become, negative, or
6814 numerically less than previous values, during a single run of the
6817 @item @emph{Standard}:
6821 Non-elemental function
6823 @item @emph{Syntax}:
6824 @code{RESULT = MCLOCK()}
6826 @item @emph{Return value}:
6827 The return value is a scalar of type @code{INTEGER(4)}, equal to the
6828 number of clock ticks since the start of the process, or @code{-1} if
6829 the system does not support @code{clock(3)}.
6831 @item @emph{See also}:
6832 @ref{CTIME}, @ref{GMTIME}, @ref{LTIME}, @ref{MCLOCK}, @ref{TIME}
6839 @section @code{MCLOCK8} --- Time function (64-bit)
6841 @cindex time, clock ticks
6845 @item @emph{Description}:
6846 Returns the number of clock ticks since the start of the process, based
6847 on the UNIX function @code{clock(3)}.
6849 @emph{Warning:} this intrinsic does not increase the range of the timing
6850 values over that returned by @code{clock(3)}. On a system with a 32-bit
6851 @code{clock(3)}, @code{MCLOCK8()} will return a 32-bit value, even though
6852 it is converted to a 64-bit @code{INTEGER(8)} value. That means
6853 overflows of the 32-bit value can still occur. Therefore, the values
6854 returned by this intrinsic might be or become negative or numerically
6855 less than previous values during a single run of the compiled program.
6857 @item @emph{Standard}:
6861 Non-elemental function
6863 @item @emph{Syntax}:
6864 @code{RESULT = MCLOCK8()}
6866 @item @emph{Return value}:
6867 The return value is a scalar of type @code{INTEGER(8)}, equal to the
6868 number of clock ticks since the start of the process, or @code{-1} if
6869 the system does not support @code{clock(3)}.
6871 @item @emph{See also}:
6872 @ref{CTIME}, @ref{GMTIME}, @ref{LTIME}, @ref{MCLOCK}, @ref{TIME8}
6879 @section @code{MERGE} --- Merge variables
6881 @cindex array, merge arrays
6882 @cindex array, combine arrays
6885 @item @emph{Description}:
6886 Select values from two arrays according to a logical mask. The result
6887 is equal to @var{TSOURCE} if @var{MASK} is @code{.TRUE.}, or equal to
6888 @var{FSOURCE} if it is @code{.FALSE.}.
6890 @item @emph{Standard}:
6896 @item @emph{Syntax}:
6897 @code{RESULT = MERGE(TSOURCE, FSOURCE, MASK)}
6899 @item @emph{Arguments}:
6900 @multitable @columnfractions .15 .70
6901 @item @var{TSOURCE} @tab May be of any type.
6902 @item @var{FSOURCE} @tab Shall be of the same type and type parameters
6904 @item @var{MASK} @tab Shall be of type @code{LOGICAL(*)}.
6907 @item @emph{Return value}:
6908 The result is of the same type and type parameters as @var{TSOURCE}.
6915 @section @code{MIN} --- Minimum value of an argument list
6922 @cindex minimum value
6925 @item @emph{Description}:
6926 Returns the argument with the smallest (most negative) value.
6928 @item @emph{Standard}:
6934 @item @emph{Syntax}:
6935 @code{RESULT = MIN(A1, A2 [, A3, ...])}
6937 @item @emph{Arguments}:
6938 @multitable @columnfractions .15 .70
6939 @item @var{A1} @tab The type shall be @code{INTEGER(*)} or
6941 @item @var{A2}, @var{A3}, ... @tab An expression of the same type and kind
6942 as @var{A1}. (As a GNU extension,
6943 arguments of different kinds are
6947 @item @emph{Return value}:
6948 The return value corresponds to the maximum value among the arguments,
6949 and has the same type and kind as the first argument.
6951 @item @emph{Specific names}:
6952 @multitable @columnfractions .20 .20 .20 .25
6953 @item Name @tab Argument @tab Return type @tab Standard
6954 @item @code{MIN0(I)} @tab @code{INTEGER(4) I} @tab @code{INTEGER(4)} @tab F77 and later
6955 @item @code{AMIN0(I)} @tab @code{INTEGER(4) I} @tab @code{REAL(MIN(X))} @tab F77 and later
6956 @item @code{MIN1(X)} @tab @code{REAL(*) X} @tab @code{INT(MIN(X))} @tab F77 and later
6957 @item @code{AMIN1(X)} @tab @code{REAL(4) X} @tab @code{REAL(4)} @tab F77 and later
6958 @item @code{DMIN1(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab F77 and later
6961 @item @emph{See also}:
6962 @ref{MAX}, @ref{MINLOC}, @ref{MINVAL}
6968 @section @code{MINEXPONENT} --- Minimum exponent of a real kind
6969 @fnindex MINEXPONENT
6970 @cindex model representation, minimum exponent
6973 @item @emph{Description}:
6974 @code{MINEXPONENT(X)} returns the minimum exponent in the model of the
6977 @item @emph{Standard}:
6983 @item @emph{Syntax}:
6984 @code{RESULT = MINEXPONENT(X)}
6986 @item @emph{Arguments}:
6987 @multitable @columnfractions .15 .70
6988 @item @var{X} @tab Shall be of type @code{REAL}.
6991 @item @emph{Return value}:
6992 The return value is of type @code{INTEGER} and of the default integer
6995 @item @emph{Example}:
6996 See @code{MAXEXPONENT} for an example.
7002 @section @code{MINLOC} --- Location of the minimum value within an array
7004 @cindex array, location of minimum element
7007 @item @emph{Description}:
7008 Determines the location of the element in the array with the minimum
7009 value, or, if the @var{DIM} argument is supplied, determines the
7010 locations of the minimum element along each row of the array in the
7011 @var{DIM} direction. If @var{MASK} is present, only the elements for
7012 which @var{MASK} is @code{.TRUE.} are considered. If more than one
7013 element in the array has the minimum value, the location returned is
7014 that of the first such element in array element order. If the array has
7015 zero size, or all of the elements of @var{MASK} are @code{.FALSE.}, then
7016 the result is an array of zeroes. Similarly, if @var{DIM} is supplied
7017 and all of the elements of @var{MASK} along a given row are zero, the
7018 result value for that row is zero.
7020 @item @emph{Standard}:
7024 Transformational function
7026 @item @emph{Syntax}:
7027 @multitable @columnfractions .80
7028 @item @code{RESULT = MINLOC(ARRAY, DIM [, MASK])}
7029 @item @code{RESULT = MINLOC(ARRAY [, MASK])}
7032 @item @emph{Arguments}:
7033 @multitable @columnfractions .15 .70
7034 @item @var{ARRAY} @tab Shall be an array of type @code{INTEGER(*)},
7035 @code{REAL(*)}, or @code{CHARACTER(*)}.
7036 @item @var{DIM} @tab (Optional) Shall be a scalar of type
7037 @code{INTEGER(*)}, with a value between one
7038 and the rank of @var{ARRAY}, inclusive. It
7039 may not be an optional dummy argument.
7040 @item @var{MASK} @tab Shall be an array of type @code{LOGICAL(*)},
7041 and conformable with @var{ARRAY}.
7044 @item @emph{Return value}:
7045 If @var{DIM} is absent, the result is a rank-one array with a length
7046 equal to the rank of @var{ARRAY}. If @var{DIM} is present, the result
7047 is an array with a rank one less than the rank of @var{ARRAY}, and a
7048 size corresponding to the size of @var{ARRAY} with the @var{DIM}
7049 dimension removed. If @var{DIM} is present and @var{ARRAY} has a rank
7050 of one, the result is a scalar. In all cases, the result is of default
7051 @code{INTEGER} type.
7053 @item @emph{See also}:
7054 @ref{MIN}, @ref{MINVAL}
7061 @section @code{MINVAL} --- Minimum value of an array
7063 @cindex array, minimum value
7064 @cindex minimum value
7067 @item @emph{Description}:
7068 Determines the minimum value of the elements in an array value, or, if
7069 the @var{DIM} argument is supplied, determines the minimum value along
7070 each row of the array in the @var{DIM} direction. If @var{MASK} is
7071 present, only the elements for which @var{MASK} is @code{.TRUE.} are
7072 considered. If the array has zero size, or all of the elements of
7073 @var{MASK} are @code{.FALSE.}, then the result is @code{HUGE(ARRAY)} if
7074 @var{ARRAY} is numeric, or a string of @code{CHAR(255)} characters if
7075 @var{ARRAY} is of character type.
7077 @item @emph{Standard}:
7081 Transformational function
7083 @item @emph{Syntax}:
7084 @multitable @columnfractions .80
7085 @item @code{RESULT = MINVAL(ARRAY, DIM [, MASK])}
7086 @item @code{RESULT = MINVAL(ARRAY [, MASK])}
7089 @item @emph{Arguments}:
7090 @multitable @columnfractions .15 .70
7091 @item @var{ARRAY} @tab Shall be an array of type @code{INTEGER(*)},
7092 @code{REAL(*)}, or @code{CHARACTER(*)}.
7093 @item @var{DIM} @tab (Optional) Shall be a scalar of type
7094 @code{INTEGER(*)}, with a value between one
7095 and the rank of @var{ARRAY}, inclusive. It
7096 may not be an optional dummy argument.
7097 @item @var{MASK} @tab Shall be an array of type @code{LOGICAL(*)},
7098 and conformable with @var{ARRAY}.
7101 @item @emph{Return value}:
7102 If @var{DIM} is absent, or if @var{ARRAY} has a rank of one, the result
7103 is a scalar. If @var{DIM} is present, the result is an array with a
7104 rank one less than the rank of @var{ARRAY}, and a size corresponding to
7105 the size of @var{ARRAY} with the @var{DIM} dimension removed. In all
7106 cases, the result is of the same type and kind as @var{ARRAY}.
7108 @item @emph{See also}:
7109 @ref{MIN}, @ref{MINLOC}
7116 @section @code{MOD} --- Remainder function
7121 @cindex division, remainder
7124 @item @emph{Description}:
7125 @code{MOD(A,P)} computes the remainder of the division of A by P. It is
7126 calculated as @code{A - (INT(A/P) * P)}.
7128 @item @emph{Standard}:
7134 @item @emph{Syntax}:
7135 @code{RESULT = MOD(A, P)}
7137 @item @emph{Arguments}:
7138 @multitable @columnfractions .15 .70
7139 @item @var{A} @tab Shall be a scalar of type @code{INTEGER} or @code{REAL}
7140 @item @var{P} @tab Shall be a scalar of the same type as @var{A} and not
7144 @item @emph{Return value}:
7145 The kind of the return value is the result of cross-promoting
7146 the kinds of the arguments.
7148 @item @emph{Example}:
7152 print *, mod(17.5,5.5)
7153 print *, mod(17.5d0,5.5)
7154 print *, mod(17.5,5.5d0)
7157 print *, mod(-17.5,5.5)
7158 print *, mod(-17.5d0,5.5)
7159 print *, mod(-17.5,5.5d0)
7162 print *, mod(17.5,-5.5)
7163 print *, mod(17.5d0,-5.5)
7164 print *, mod(17.5,-5.5d0)
7165 end program test_mod
7168 @item @emph{Specific names}:
7169 @multitable @columnfractions .20 .20 .20 .25
7170 @item Name @tab Arguments @tab Return type @tab Standard
7171 @item @code{AMOD(A,P)} @tab @code{REAL(4)} @tab @code{REAL(4)} @tab F95 and later
7172 @item @code{DMOD(A,P)} @tab @code{REAL(8)} @tab @code{REAL(8)} @tab F95 and later
7179 @section @code{MODULO} --- Modulo function
7182 @cindex division, modulo
7185 @item @emph{Description}:
7186 @code{MODULO(A,P)} computes the @var{A} modulo @var{P}.
7188 @item @emph{Standard}:
7194 @item @emph{Syntax}:
7195 @code{RESULT = MODULO(A, P)}
7197 @item @emph{Arguments}:
7198 @multitable @columnfractions .15 .70
7199 @item @var{A} @tab Shall be a scalar of type @code{INTEGER} or @code{REAL}
7200 @item @var{P} @tab Shall be a scalar of the same type and kind as @var{A}
7203 @item @emph{Return value}:
7204 The type and kind of the result are those of the arguments.
7206 @item If @var{A} and @var{P} are of type @code{INTEGER}:
7207 @code{MODULO(A,P)} has the value @var{R} such that @code{A=Q*P+R}, where
7208 @var{Q} is an integer and @var{R} is between 0 (inclusive) and @var{P}
7210 @item If @var{A} and @var{P} are of type @code{REAL}:
7211 @code{MODULO(A,P)} has the value of @code{A - FLOOR (A / P) * P}.
7213 In all cases, if @var{P} is zero the result is processor-dependent.
7215 @item @emph{Example}:
7218 print *, modulo(17,3)
7219 print *, modulo(17.5,5.5)
7221 print *, modulo(-17,3)
7222 print *, modulo(-17.5,5.5)
7224 print *, modulo(17,-3)
7225 print *, modulo(17.5,-5.5)
7234 @section @code{MOVE_ALLOC} --- Move allocation from one object to another
7236 @cindex moving allocation
7237 @cindex allocation, moving
7240 @item @emph{Description}:
7241 @code{MOVE_ALLOC(SRC, DEST)} moves the allocation from @var{SRC} to
7242 @var{DEST}. @var{SRC} will become deallocated in the process.
7244 @item @emph{Standard}:
7250 @item @emph{Syntax}:
7251 @code{CALL MOVE_ALLOC(SRC, DEST)}
7253 @item @emph{Arguments}:
7254 @multitable @columnfractions .15 .70
7255 @item @var{SRC} @tab @code{ALLOCATABLE}, @code{INTENT(INOUT)}, may be
7256 of any type and kind.
7257 @item @var{DEST} @tab @code{ALLOCATABLE}, @code{INTENT(OUT)}, shall be
7258 of the same type, kind and rank as @var{SRC}
7261 @item @emph{Return value}:
7264 @item @emph{Example}:
7266 program test_move_alloc
7267 integer, allocatable :: a(:), b(:)
7271 call move_alloc(a, b)
7272 print *, allocated(a), allocated(b)
7274 end program test_move_alloc
7281 @section @code{MVBITS} --- Move bits from one integer to another
7286 @item @emph{Description}:
7287 Moves @var{LEN} bits from positions @var{FROMPOS} through
7288 @code{FROMPOS+LEN-1} of @var{FROM} to positions @var{TOPOS} through
7289 @code{TOPOS+LEN-1} of @var{TO}. The portion of argument @var{TO} not
7290 affected by the movement of bits is unchanged. The values of
7291 @code{FROMPOS+LEN-1} and @code{TOPOS+LEN-1} must be less than
7292 @code{BIT_SIZE(FROM)}.
7294 @item @emph{Standard}:
7298 Elemental subroutine
7300 @item @emph{Syntax}:
7301 @code{CALL MVBITS(FROM, FROMPOS, LEN, TO, TOPOS)}
7303 @item @emph{Arguments}:
7304 @multitable @columnfractions .15 .70
7305 @item @var{FROM} @tab The type shall be @code{INTEGER(*)}.
7306 @item @var{FROMPOS} @tab The type shall be @code{INTEGER(*)}.
7307 @item @var{LEN} @tab The type shall be @code{INTEGER(*)}.
7308 @item @var{TO} @tab The type shall be @code{INTEGER(*)}, of the
7309 same kind as @var{FROM}.
7310 @item @var{TOPOS} @tab The type shall be @code{INTEGER(*)}.
7313 @item @emph{See also}:
7314 @ref{IBCLR}, @ref{IBSET}, @ref{IBITS}, @ref{IAND}, @ref{IOR}, @ref{IEOR}
7320 @section @code{NEAREST} --- Nearest representable number
7322 @cindex real number, nearest different
7323 @cindex floating point, nearest different
7326 @item @emph{Description}:
7327 @code{NEAREST(X, S)} returns the processor-representable number nearest
7328 to @code{X} in the direction indicated by the sign of @code{S}.
7330 @item @emph{Standard}:
7336 @item @emph{Syntax}:
7337 @code{RESULT = NEAREST(X, S)}
7339 @item @emph{Arguments}:
7340 @multitable @columnfractions .15 .70
7341 @item @var{X} @tab Shall be of type @code{REAL}.
7342 @item @var{S} @tab (Optional) shall be of type @code{REAL} and
7346 @item @emph{Return value}:
7347 The return value is of the same type as @code{X}. If @code{S} is
7348 positive, @code{NEAREST} returns the processor-representable number
7349 greater than @code{X} and nearest to it. If @code{S} is negative,
7350 @code{NEAREST} returns the processor-representable number smaller than
7351 @code{X} and nearest to it.
7353 @item @emph{Example}:
7355 program test_nearest
7357 x = nearest(42.0, 1.0)
7358 y = nearest(42.0, -1.0)
7359 write (*,"(3(G20.15))") x, y, x - y
7360 end program test_nearest
7367 @section @code{NEW_LINE} --- New line character
7370 @cindex output, newline
7373 @item @emph{Description}:
7374 @code{NEW_LINE(C)} returns the new-line character.
7376 @item @emph{Standard}:
7382 @item @emph{Syntax}:
7383 @code{RESULT = NEW_LINE(C)}
7385 @item @emph{Arguments}:
7386 @multitable @columnfractions .15 .70
7387 @item @var{C} @tab The argument shall be a scalar or array of the
7388 type @code{CHARACTER}.
7391 @item @emph{Return value}:
7392 Returns a @var{CHARACTER} scalar of length one with the new-line character of
7393 the same kind as parameter @var{C}.
7395 @item @emph{Example}:
7399 write(*,'(A)') 'This is record 1.'//NEW_LINE('A')//'This is record 2.'
7407 @section @code{NINT} --- Nearest whole number
7410 @cindex rounding, nearest whole number
7413 @item @emph{Description}:
7414 @code{NINT(X)} rounds its argument to the nearest whole number.
7416 @item @emph{Standard}:
7422 @item @emph{Syntax}:
7423 @code{RESULT = NINT(X)}
7425 @item @emph{Arguments}:
7426 @multitable @columnfractions .15 .70
7427 @item @var{X} @tab The type of the argument shall be @code{REAL}.
7430 @item @emph{Return value}:
7431 Returns @var{A} with the fractional portion of its magnitude eliminated by
7432 rounding to the nearest whole number and with its sign preserved,
7433 converted to an @code{INTEGER} of the default kind.
7435 @item @emph{Example}:
7442 print *, nint(x4), idnint(x8)
7443 end program test_nint
7446 @item @emph{Specific names}:
7447 @multitable @columnfractions .25 .25 .25
7448 @item Name @tab Argument @tab Standard
7449 @item @code{IDNINT(X)} @tab @code{REAL(8)} @tab F95 and later
7452 @item @emph{See also}:
7453 @ref{CEILING}, @ref{FLOOR}
7460 @section @code{NOT} --- Logical negation
7462 @cindex bits, negate
7463 @cindex bitwise logical not
7464 @cindex logical not, bitwise
7467 @item @emph{Description}:
7468 @code{NOT} returns the bitwise boolean inverse of @var{I}.
7470 @item @emph{Standard}:
7476 @item @emph{Syntax}:
7477 @code{RESULT = NOT(I)}
7479 @item @emph{Arguments}:
7480 @multitable @columnfractions .15 .70
7481 @item @var{I} @tab The type shall be @code{INTEGER(*)}.
7484 @item @emph{Return value}:
7485 The return type is @code{INTEGER(*)}, of the same kind as the
7488 @item @emph{See also}:
7489 @ref{IAND}, @ref{IEOR}, @ref{IOR}, @ref{IBITS}, @ref{IBSET}, @ref{IBCLR}
7496 @section @code{NULL} --- Function that returns an disassociated pointer
7498 @cindex pointer, status
7499 @cindex pointer, disassociated
7502 @item @emph{Description}:
7503 Returns a disassociated pointer.
7505 If @var{MOLD} is present, a dissassociated pointer of the same type is
7506 returned, otherwise the type is determined by context.
7508 In Fortran 95, @var{MOLD} is optional. Please note that F2003 includes
7509 cases where it is required.
7511 @item @emph{Standard}:
7515 Transformational function
7517 @item @emph{Syntax}:
7518 @code{PTR => NULL([MOLD])}
7520 @item @emph{Arguments}:
7521 @multitable @columnfractions .15 .70
7522 @item @var{MOLD} @tab (Optional) shall be a pointer of any association
7523 status and of any type.
7526 @item @emph{Return value}:
7527 A disassociated pointer.
7529 @item @emph{Example}:
7531 REAL, POINTER, DIMENSION(:) :: VEC => NULL ()
7534 @item @emph{See also}:
7541 @section @code{OR} --- Bitwise logical OR
7543 @cindex bitwise logical or
7544 @cindex logical or, bitwise
7547 @item @emph{Description}:
7548 Bitwise logical @code{OR}.
7550 This intrinsic routine is provided for backwards compatibility with
7551 GNU Fortran 77. For integer arguments, programmers should consider
7552 the use of the @ref{IOR} intrinsic defined by the Fortran standard.
7554 @item @emph{Standard}:
7558 Non-elemental function
7560 @item @emph{Syntax}:
7561 @code{RESULT = OR(X, Y)}
7563 @item @emph{Arguments}:
7564 @multitable @columnfractions .15 .70
7565 @item @var{X} @tab The type shall be either @code{INTEGER(*)} or @code{LOGICAL}.
7566 @item @var{Y} @tab The type shall be either @code{INTEGER(*)} or @code{LOGICAL}.
7569 @item @emph{Return value}:
7570 The return type is either @code{INTEGER(*)} or @code{LOGICAL}
7571 after cross-promotion of the arguments.
7573 @item @emph{Example}:
7576 LOGICAL :: T = .TRUE., F = .FALSE.
7578 DATA a / Z'F' /, b / Z'3' /
7580 WRITE (*,*) OR(T, T), OR(T, F), OR(F, T), OR(F, F)
7581 WRITE (*,*) OR(a, b)
7585 @item @emph{See also}:
7586 F95 elemental function: @ref{IOR}
7592 @section @code{PACK} --- Pack an array into an array of rank one
7594 @cindex array, packing
7595 @cindex array, reduce dimension
7596 @cindex array, gather elements
7599 @item @emph{Description}:
7600 Stores the elements of @var{ARRAY} in an array of rank one.
7602 The beginning of the resulting array is made up of elements whose @var{MASK}
7603 equals @code{TRUE}. Afterwards, positions are filled with elements taken from
7606 @item @emph{Standard}:
7610 Transformational function
7612 @item @emph{Syntax}:
7613 @code{RESULT = PACK(ARRAY, MASK[,VECTOR]}
7615 @item @emph{Arguments}:
7616 @multitable @columnfractions .15 .70
7617 @item @var{ARRAY} @tab Shall be an array of any type.
7618 @item @var{MASK} @tab Shall be an array of type @code{LOGICAL} and
7619 of the same size as @var{ARRAY}. Alternatively, it may be a @code{LOGICAL}
7621 @item @var{VECTOR} @tab (Optional) shall be an array of the same type
7622 as @var{ARRAY} and of rank one. If present, the number of elements in
7623 @var{VECTOR} shall be equal to or greater than the number of true elements
7624 in @var{MASK}. If @var{MASK} is scalar, the number of elements in
7625 @var{VECTOR} shall be equal to or greater than the number of elements in
7629 @item @emph{Return value}:
7630 The result is an array of rank one and the same type as that of @var{ARRAY}.
7631 If @var{VECTOR} is present, the result size is that of @var{VECTOR}, the
7632 number of @code{TRUE} values in @var{MASK} otherwise.
7634 @item @emph{Example}:
7635 Gathering non-zero elements from an array:
7639 m = (/ 1, 0, 0, 0, 5, 0 /)
7640 WRITE(*, FMT="(6(I0, ' '))") pack(m, m /= 0) ! "1 5"
7644 Gathering non-zero elements from an array and appending elements from @var{VECTOR}:
7648 m = (/ 1, 0, 0, 2 /)
7649 WRITE(*, FMT="(4(I0, ' '))") pack(m, m /= 0, (/ 0, 0, 3, 4 /)) ! "1 2 3 4"
7653 @item @emph{See also}:
7660 @section @code{PERROR} --- Print system error message
7662 @cindex system, error handling
7665 @item @emph{Description}:
7666 Prints (on the C @code{stderr} stream) a newline-terminated error
7667 message corresponding to the last system error. This is prefixed by
7668 @var{STRING}, a colon and a space. See @code{perror(3)}.
7670 @item @emph{Standard}:
7676 @item @emph{Syntax}:
7677 @code{CALL PERROR(STRING)}
7679 @item @emph{Arguments}:
7680 @multitable @columnfractions .15 .70
7681 @item @var{STRING} @tab A scalar of default @code{CHARACTER} type.
7684 @item @emph{See also}:
7691 @section @code{PRECISION} --- Decimal precision of a real kind
7693 @cindex model representation, precision
7696 @item @emph{Description}:
7697 @code{PRECISION(X)} returns the decimal precision in the model of the
7700 @item @emph{Standard}:
7706 @item @emph{Syntax}:
7707 @code{RESULT = PRECISION(X)}
7709 @item @emph{Arguments}:
7710 @multitable @columnfractions .15 .70
7711 @item @var{X} @tab Shall be of type @code{REAL} or @code{COMPLEX}.
7714 @item @emph{Return value}:
7715 The return value is of type @code{INTEGER} and of the default integer
7718 @item @emph{Example}:
7720 program prec_and_range
7721 real(kind=4) :: x(2)
7722 complex(kind=8) :: y
7724 print *, precision(x), range(x)
7725 print *, precision(y), range(y)
7726 end program prec_and_range
7733 @section @code{PRESENT} --- Determine whether an optional dummy argument is specified
7737 @item @emph{Description}:
7738 Determines whether an optional dummy argument is present.
7740 @item @emph{Standard}:
7746 @item @emph{Syntax}:
7747 @code{RESULT = PRESENT(A)}
7749 @item @emph{Arguments}:
7750 @multitable @columnfractions .15 .70
7751 @item @var{A} @tab May be of any type and may be a pointer, scalar or array
7752 value, or a dummy procedure. It shall be the name of an optional dummy argument
7753 accessible within the current subroutine or function.
7756 @item @emph{Return value}:
7757 Returns either @code{TRUE} if the optional argument @var{A} is present, or
7758 @code{FALSE} otherwise.
7760 @item @emph{Example}:
7762 PROGRAM test_present
7763 WRITE(*,*) f(), f(42) ! "F T"
7765 LOGICAL FUNCTION f(x)
7766 INTEGER, INTENT(IN), OPTIONAL :: x
7776 @section @code{PRODUCT} --- Product of array elements
7778 @cindex array, product
7779 @cindex array, multiply elements
7780 @cindex array, conditionally multiply elements
7781 @cindex multiply array elements
7784 @item @emph{Description}:
7785 Multiplies the elements of @var{ARRAY} along dimension @var{DIM} if
7786 the corresponding element in @var{MASK} is @code{TRUE}.
7788 @item @emph{Standard}:
7792 Transformational function
7794 @item @emph{Syntax}:
7795 @code{RESULT = PRODUCT(ARRAY[, MASK])}
7796 @code{RESULT = PRODUCT(ARRAY, DIM[, MASK])}
7798 @item @emph{Arguments}:
7799 @multitable @columnfractions .15 .70
7800 @item @var{ARRAY} @tab Shall be an array of type @code{INTEGER(*)},
7801 @code{REAL(*)} or @code{COMPLEX(*)}.
7802 @item @var{DIM} @tab (Optional) shall be a scalar of type
7803 @code{INTEGER} with a value in the range from 1 to n, where n
7804 equals the rank of @var{ARRAY}.
7805 @item @var{MASK} @tab (Optional) shall be of type @code{LOGICAL}
7806 and either be a scalar or an array of the same shape as @var{ARRAY}.
7809 @item @emph{Return value}:
7810 The result is of the same type as @var{ARRAY}.
7812 If @var{DIM} is absent, a scalar with the product of all elements in
7813 @var{ARRAY} is returned. Otherwise, an array of rank n-1, where n equals
7814 the rank of @var{ARRAY}, and a shape similar to that of @var{ARRAY} with
7815 dimension @var{DIM} dropped is returned.
7818 @item @emph{Example}:
7820 PROGRAM test_product
7821 INTEGER :: x(5) = (/ 1, 2, 3, 4 ,5 /)
7822 print *, PRODUCT(x) ! all elements, product = 120
7823 print *, PRODUCT(x, MASK=MOD(x, 2)==1) ! odd elements, product = 15
7827 @item @emph{See also}:
7834 @section @code{RADIX} --- Base of a model number
7836 @cindex model representation, base
7837 @cindex model representation, radix
7840 @item @emph{Description}:
7841 @code{RADIX(X)} returns the base of the model representing the entity @var{X}.
7843 @item @emph{Standard}:
7849 @item @emph{Syntax}:
7850 @code{RESULT = RADIX(X)}
7852 @item @emph{Arguments}:
7853 @multitable @columnfractions .15 .70
7854 @item @var{X} @tab Shall be of type @code{INTEGER} or @code{REAL}
7857 @item @emph{Return value}:
7858 The return value is a scalar of type @code{INTEGER} and of the default
7861 @item @emph{Example}:
7864 print *, "The radix for the default integer kind is", radix(0)
7865 print *, "The radix for the default real kind is", radix(0.0)
7866 end program test_radix
7874 @section @code{RAN} --- Real pseudo-random number
7876 @cindex random number generation
7879 @item @emph{Description}:
7880 For compatibility with HP FORTRAN 77/iX, the @code{RAN} intrinsic is
7881 provided as an alias for @code{RAND}. See @ref{RAND} for complete
7884 @item @emph{Standard}:
7888 Non-elemental function
7890 @item @emph{See also}:
7891 @ref{RAND}, @ref{RANDOM_NUMBER}
7897 @section @code{RAND} --- Real pseudo-random number
7899 @cindex random number generation
7902 @item @emph{Description}:
7903 @code{RAND(FLAG)} returns a pseudo-random number from a uniform
7904 distribution between 0 and 1. If @var{FLAG} is 0, the next number
7905 in the current sequence is returned; if @var{FLAG} is 1, the generator
7906 is restarted by @code{CALL SRAND(0)}; if @var{FLAG} has any other value,
7907 it is used as a new seed with @code{SRAND}.
7909 @item @emph{Standard}:
7913 Non-elemental function
7915 @item @emph{Syntax}:
7916 @code{RESULT = RAND(FLAG)}
7918 @item @emph{Arguments}:
7919 @multitable @columnfractions .15 .70
7920 @item @var{FLAG} @tab Shall be a scalar @code{INTEGER} of kind 4.
7923 @item @emph{Return value}:
7924 The return value is of @code{REAL} type and the default kind.
7926 @item @emph{Example}:
7929 integer,parameter :: seed = 86456
7932 print *, rand(), rand(), rand(), rand()
7933 print *, rand(seed), rand(), rand(), rand()
7934 end program test_rand
7937 @item @emph{See also}:
7938 @ref{SRAND}, @ref{RANDOM_NUMBER}
7945 @section @code{RANDOM_NUMBER} --- Pseudo-random number
7946 @fnindex RANDOM_NUMBER
7947 @cindex random number generation
7950 @item @emph{Description}:
7951 Returns a single pseudorandom number or an array of pseudorandom numbers
7952 from the uniform distribution over the range @math{ 0 \leq x < 1}.
7954 @item @emph{Standard}:
7960 @item @emph{Syntax}:
7961 @code{RANDOM_NUMBER(HARVEST)}
7963 @item @emph{Arguments}:
7964 @multitable @columnfractions .15 .70
7965 @item @var{HARVEST} @tab Shall be a scalar or an array of type @code{REAL(*)}.
7968 @item @emph{Example}:
7970 program test_random_number
7972 CALL init_random_seed() ! see example of RANDOM_SEED
7973 CALL RANDOM_NUMBER(r)
7978 The implemented random number generator is thread safe if used within
7979 OpenMP directives, i. e. its state will be consistent while called from
7980 multiple threads. Please note that the currently implemented KISS generator
7981 does not create random numbers in parallel from multiple sources, but in
7982 sequence from a single source. If your OpenMP-enabled application heavily
7983 relies on random numbers, you should consider employing a dedicated parallel
7984 random number generator instead.
7986 @item @emph{See also}:
7993 @section @code{RANDOM_SEED} --- Initialize a pseudo-random number sequence
7994 @fnindex RANDOM_SEED
7995 @cindex random number generation, seeding
7996 @cindex seeding a random number generator
7999 @item @emph{Description}:
8000 Restarts or queries the state of the pseudorandom number generator used by
8001 @code{RANDOM_NUMBER}.
8003 If @code{RANDOM_SEED} is called without arguments, it is initialized to
8004 a default state. The example below shows how to initialize the random
8005 seed based on the system's time.
8007 @item @emph{Standard}:
8013 @item @emph{Syntax}:
8014 @code{CALL RANDOM_SEED(SIZE, PUT, GET)}
8016 @item @emph{Arguments}:
8017 @multitable @columnfractions .15 .70
8018 @item @var{SIZE} @tab (Optional) Shall be a scalar and of type default
8019 @code{INTEGER}, with @code{INTENT(OUT)}. It specifies the minimum size
8020 of the arrays used with the @var{PUT} and @var{GET} arguments.
8021 @item @var{PUT} @tab (Optional) Shall be an array of type default
8022 @code{INTEGER} and rank one. It is @code{INTENT(IN)} and the size of
8023 the array must be larger than or equal to the number returned by the
8024 @var{SIZE} argument.
8025 @item @var{GET} @tab (Optional) Shall be an array of type default
8026 @code{INTEGER} and rank one. It is @code{INTENT(OUT)} and the size
8027 of the array must be larger than or equal to the number returned by
8028 the @var{SIZE} argument.
8031 @item @emph{Example}:
8033 SUBROUTINE init_random_seed()
8034 INTEGER :: i, n, clock
8035 INTEGER, DIMENSION(:), ALLOCATABLE :: seed
8037 CALL RANDOM_SEED(size = n)
8040 CALL SYSTEM_CLOCK(COUNT=clock)
8042 seed = clock + 37 * (/ (i - 1, i = 1, n) /)
8043 CALL RANDOM_SEED(PUT = seed)
8049 @item @emph{See also}:
8056 @section @code{RANGE} --- Decimal exponent range of a real kind
8058 @cindex model representation, range
8061 @item @emph{Description}:
8062 @code{RANGE(X)} returns the decimal exponent range in the model of the
8065 @item @emph{Standard}:
8071 @item @emph{Syntax}:
8072 @code{RESULT = RANGE(X)}
8074 @item @emph{Arguments}:
8075 @multitable @columnfractions .15 .70
8076 @item @var{X} @tab Shall be of type @code{REAL} or @code{COMPLEX}.
8079 @item @emph{Return value}:
8080 The return value is of type @code{INTEGER} and of the default integer
8083 @item @emph{Example}:
8084 See @code{PRECISION} for an example.
8090 @section @code{REAL} --- Convert to real type
8093 @cindex conversion, to real
8094 @cindex complex numbers, real part
8097 @item @emph{Description}:
8098 @code{REAL(X [, KIND])} converts its argument @var{X} to a real type. The
8099 @code{REALPART(X)} function is provided for compatibility with @command{g77},
8100 and its use is strongly discouraged.
8102 @item @emph{Standard}:
8108 @item @emph{Syntax}:
8109 @multitable @columnfractions .80
8110 @item @code{RESULT = REAL(X [, KIND])}
8111 @item @code{RESULT = REALPART(Z)}
8114 @item @emph{Arguments}:
8115 @multitable @columnfractions .15 .70
8116 @item @var{X} @tab Shall be @code{INTEGER(*)}, @code{REAL(*)}, or
8118 @item @var{KIND} @tab (Optional) An @code{INTEGER(*)} initialization
8119 expression indicating the kind parameter of
8123 @item @emph{Return value}:
8124 These functions return a @code{REAL(*)} variable or array under
8125 the following rules:
8129 @code{REAL(X)} is converted to a default real type if @var{X} is an
8130 integer or real variable.
8132 @code{REAL(X)} is converted to a real type with the kind type parameter
8133 of @var{X} if @var{X} is a complex variable.
8135 @code{REAL(X, KIND)} is converted to a real type with kind type
8136 parameter @var{KIND} if @var{X} is a complex, integer, or real
8140 @item @emph{Example}:
8143 complex :: x = (1.0, 2.0)
8144 print *, real(x), real(x,8), realpart(x)
8145 end program test_real
8148 @item @emph{See also}:
8149 @ref{DBLE}, @ref{DFLOAT}, @ref{FLOAT}
8156 @section @code{RENAME} --- Rename a file
8158 @cindex file system, rename file
8161 @item @emph{Description}:
8162 Renames a file from file @var{PATH1} to @var{PATH2}. A null
8163 character (@code{CHAR(0)}) can be used to mark the end of the names in
8164 @var{PATH1} and @var{PATH2}; otherwise, trailing blanks in the file
8165 names are ignored. If the @var{STATUS} argument is supplied, it
8166 contains 0 on success or a nonzero error code upon return; see
8169 This intrinsic is provided in both subroutine and function forms;
8170 however, only one form can be used in any given program unit.
8172 @item @emph{Standard}:
8176 Subroutine, non-elemental function
8178 @item @emph{Syntax}:
8179 @multitable @columnfractions .80
8180 @item @code{CALL RENAME(PATH1, PATH2 [, STATUS])}
8181 @item @code{STATUS = RENAME(PATH1, PATH2)}
8184 @item @emph{Arguments}:
8185 @multitable @columnfractions .15 .70
8186 @item @var{PATH1} @tab Shall be of default @code{CHARACTER} type.
8187 @item @var{PATH2} @tab Shall be of default @code{CHARACTER} type.
8188 @item @var{STATUS} @tab (Optional) Shall be of default @code{INTEGER} type.
8191 @item @emph{See also}:
8199 @section @code{REPEAT} --- Repeated string concatenation
8201 @cindex string, repeat
8202 @cindex string, concatenate
8205 @item @emph{Description}:
8206 Concatenates @var{NCOPIES} copies of a string.
8208 @item @emph{Standard}:
8212 Transformational function
8214 @item @emph{Syntax}:
8215 @code{RESULT = REPEAT(STRING, NCOPIES)}
8217 @item @emph{Arguments}:
8218 @multitable @columnfractions .15 .70
8219 @item @var{STRING} @tab Shall be scalar and of type @code{CHARACTER(*)}.
8220 @item @var{NCOPIES} @tab Shall be scalar and of type @code{INTEGER(*)}.
8223 @item @emph{Return value}:
8224 A new scalar of type @code{CHARACTER} built up from @var{NCOPIES} copies
8227 @item @emph{Example}:
8230 write(*,*) repeat("x", 5) ! "xxxxx"
8238 @section @code{RESHAPE} --- Function to reshape an array
8240 @cindex array, change dimensions
8241 @cindex array, transmogrify
8244 @item @emph{Description}:
8245 Reshapes @var{SOURCE} to correspond to @var{SHAPE}. If necessary,
8246 the new array may be padded with elements from @var{PAD} or permuted
8247 as defined by @var{ORDER}.
8249 @item @emph{Standard}:
8253 Transformational function
8255 @item @emph{Syntax}:
8256 @code{RESULT = RESHAPE(SOURCE, SHAPE[, PAD, ORDER])}
8258 @item @emph{Arguments}:
8259 @multitable @columnfractions .15 .70
8260 @item @var{SOURCE} @tab Shall be an array of any type.
8261 @item @var{SHAPE} @tab Shall be of type @code{INTEGER} and an
8262 array of rank one. Its values must be positive or zero.
8263 @item @var{PAD} @tab (Optional) shall be an array of the same
8264 type as @var{SOURCE}.
8265 @item @var{ORDER} @tab (Optional) shall be of type @code{INTEGER}
8266 and an array of the same shape as @var{SHAPE}. Its values shall
8267 be a permutation of the numbers from 1 to n, where n is the size of
8268 @var{SHAPE}. If @var{ORDER} is absent, the natural ordering shall
8272 @item @emph{Return value}:
8273 The result is an array of shape @var{SHAPE} with the same type as
8276 @item @emph{Example}:
8278 PROGRAM test_reshape
8279 INTEGER, DIMENSION(4) :: x
8280 WRITE(*,*) SHAPE(x) ! prints "4"
8281 WRITE(*,*) SHAPE(RESHAPE(x, (/2, 2/))) ! prints "2 2"
8285 @item @emph{See also}:
8292 @section @code{RRSPACING} --- Reciprocal of the relative spacing
8294 @cindex real number, relative spacing
8295 @cindex floating point, relative spacing
8299 @item @emph{Description}:
8300 @code{RRSPACING(X)} returns the reciprocal of the relative spacing of
8301 model numbers near @var{X}.
8303 @item @emph{Standard}:
8309 @item @emph{Syntax}:
8310 @code{RESULT = RRSPACING(X)}
8312 @item @emph{Arguments}:
8313 @multitable @columnfractions .15 .70
8314 @item @var{X} @tab Shall be of type @code{REAL}.
8317 @item @emph{Return value}:
8318 The return value is of the same type and kind as @var{X}.
8319 The value returned is equal to
8320 @code{ABS(FRACTION(X)) * FLOAT(RADIX(X))**DIGITS(X)}.
8322 @item @emph{See also}:
8329 @section @code{RSHIFT} --- Right shift bits
8331 @cindex bits, shift right
8334 @item @emph{Description}:
8335 @code{RSHIFT} returns a value corresponding to @var{I} with all of the
8336 bits shifted right by @var{SHIFT} places. If the absolute value of
8337 @var{SHIFT} is greater than @code{BIT_SIZE(I)}, the value is undefined.
8338 Bits shifted out from the left end are lost; zeros are shifted in from
8341 This function has been superseded by the @code{ISHFT} intrinsic, which
8342 is standard in Fortran 95 and later.
8344 @item @emph{Standard}:
8350 @item @emph{Syntax}:
8351 @code{RESULT = RSHIFT(I, SHIFT)}
8353 @item @emph{Arguments}:
8354 @multitable @columnfractions .15 .70
8355 @item @var{I} @tab The type shall be @code{INTEGER(*)}.
8356 @item @var{SHIFT} @tab The type shall be @code{INTEGER(*)}.
8359 @item @emph{Return value}:
8360 The return value is of type @code{INTEGER(*)} and of the same kind as
8363 @item @emph{See also}:
8364 @ref{ISHFT}, @ref{ISHFTC}, @ref{LSHIFT}
8371 @section @code{SCALE} --- Scale a real value
8373 @cindex real number, scale
8374 @cindex floating point, scale
8377 @item @emph{Description}:
8378 @code{SCALE(X,I)} returns @code{X * RADIX(X)**I}.
8380 @item @emph{Standard}:
8386 @item @emph{Syntax}:
8387 @code{RESULT = SCALE(X, I)}
8389 @item @emph{Arguments}:
8390 @multitable @columnfractions .15 .70
8391 @item @var{X} @tab The type of the argument shall be a @code{REAL}.
8392 @item @var{I} @tab The type of the argument shall be a @code{INTEGER}.
8395 @item @emph{Return value}:
8396 The return value is of the same type and kind as @var{X}.
8397 Its value is @code{X * RADIX(X)**I}.
8399 @item @emph{Example}:
8402 real :: x = 178.1387e-4
8404 print *, scale(x,i), x*radix(x)**i
8405 end program test_scale
8413 @section @code{SCAN} --- Scan a string for the presence of a set of characters
8415 @cindex string, find subset
8418 @item @emph{Description}:
8419 Scans a @var{STRING} for any of the characters in a @var{SET}
8422 If @var{BACK} is either absent or equals @code{FALSE}, this function
8423 returns the position of the leftmost character of @var{STRING} that is
8424 in @var{SET}. If @var{BACK} equals @code{TRUE}, the rightmost position
8425 is returned. If no character of @var{SET} is found in @var{STRING}, the
8428 @item @emph{Standard}:
8434 @item @emph{Syntax}:
8435 @code{RESULT = SCAN(STRING, SET[, BACK])}
8437 @item @emph{Arguments}:
8438 @multitable @columnfractions .15 .70
8439 @item @var{STRING} @tab Shall be of type @code{CHARACTER(*)}.
8440 @item @var{SET} @tab Shall be of type @code{CHARACTER(*)}.
8441 @item @var{BACK} @tab (Optional) shall be of type @code{LOGICAL}.
8444 @item @emph{Return value}:
8445 The return value is of type @code{INTEGER} and of the default
8448 @item @emph{Example}:
8451 WRITE(*,*) SCAN("FORTRAN", "AO") ! 2, found 'O'
8452 WRITE(*,*) SCAN("FORTRAN", "AO", .TRUE.) ! 6, found 'A'
8453 WRITE(*,*) SCAN("FORTRAN", "C++") ! 0, found none
8457 @item @emph{See also}:
8458 @ref{INDEX}, @ref{VERIFY}
8464 @section @code{SECNDS} --- Time function
8466 @cindex time, elapsed
8467 @cindex elapsed time
8470 @item @emph{Description}:
8471 @code{SECNDS(X)} gets the time in seconds from the real-time system clock.
8472 @var{X} is a reference time, also in seconds. If this is zero, the time in
8473 seconds from midnight is returned. This function is non-standard and its
8476 @item @emph{Standard}:
8480 Non-elemental function
8482 @item @emph{Syntax}:
8483 @code{RESULT = SECNDS (X)}
8485 @item @emph{Arguments}:
8486 @multitable @columnfractions .15 .70
8487 @item @var{T} @tab Shall be of type @code{REAL(4)}.
8488 @item @var{X} @tab Shall be of type @code{REAL(4)}.
8491 @item @emph{Return value}:
8494 @item @emph{Example}:
8499 print *, secnds (0.0) ! seconds since midnight
8500 t1 = secnds (0.0) ! reference time
8501 do i = 1, 10000000 ! do something
8503 t2 = secnds (t1) ! elapsed time
8504 print *, "Something took ", t2, " seconds."
8505 end program test_secnds
8512 @section @code{SECOND} --- CPU time function
8514 @cindex time, elapsed
8515 @cindex elapsed time
8518 @item @emph{Description}:
8519 Returns a @code{REAL(4)} value representing the elapsed CPU time in
8520 seconds. This provides the same functionality as the standard
8521 @code{CPU_TIME} intrinsic, and is only included for backwards
8524 This intrinsic is provided in both subroutine and function forms;
8525 however, only one form can be used in any given program unit.
8527 @item @emph{Standard}:
8531 Subroutine, non-elemental function
8533 @item @emph{Syntax}:
8534 @multitable @columnfractions .80
8535 @item @code{CALL SECOND(TIME)}
8536 @item @code{TIME = SECOND()}
8539 @item @emph{Arguments}:
8540 @multitable @columnfractions .15 .70
8541 @item @var{TIME} @tab Shall be of type @code{REAL(4)}.
8544 @item @emph{Return value}:
8545 In either syntax, @var{TIME} is set to the process's current runtime in
8548 @item @emph{See also}:
8555 @node SELECTED_INT_KIND
8556 @section @code{SELECTED_INT_KIND} --- Choose integer kind
8557 @fnindex SELECTED_INT_KIND
8558 @cindex integer kind
8559 @cindex kind, integer
8562 @item @emph{Description}:
8563 @code{SELECTED_INT_KIND(I)} return the kind value of the smallest integer
8564 type that can represent all values ranging from @math{-10^I} (exclusive)
8565 to @math{10^I} (exclusive). If there is no integer kind that accommodates
8566 this range, @code{SELECTED_INT_KIND} returns @math{-1}.
8568 @item @emph{Standard}:
8572 Transformational function
8574 @item @emph{Syntax}:
8575 @code{RESULT = SELECTED_INT_KIND(I)}
8577 @item @emph{Arguments}:
8578 @multitable @columnfractions .15 .70
8579 @item @var{I} @tab Shall be a scalar and of type @code{INTEGER}.
8582 @item @emph{Example}:
8584 program large_integers
8585 integer,parameter :: k5 = selected_int_kind(5)
8586 integer,parameter :: k15 = selected_int_kind(15)
8587 integer(kind=k5) :: i5
8588 integer(kind=k15) :: i15
8590 print *, huge(i5), huge(i15)
8592 ! The following inequalities are always true
8593 print *, huge(i5) >= 10_k5**5-1
8594 print *, huge(i15) >= 10_k15**15-1
8595 end program large_integers
8601 @node SELECTED_REAL_KIND
8602 @section @code{SELECTED_REAL_KIND} --- Choose real kind
8603 @fnindex SELECTED_REAL_KIND
8608 @item @emph{Description}:
8609 @code{SELECTED_REAL_KIND(P,R)} return the kind value of a real data type
8610 with decimal precision greater of at least @code{P} digits and exponent
8611 range greater at least @code{R}.
8613 @item @emph{Standard}:
8617 Transformational function
8619 @item @emph{Syntax}:
8620 @code{RESULT = SELECTED_REAL_KIND(P, R)}
8622 @item @emph{Arguments}:
8623 @multitable @columnfractions .15 .70
8624 @item @var{P} @tab (Optional) shall be a scalar and of type @code{INTEGER}.
8625 @item @var{R} @tab (Optional) shall be a scalar and of type @code{INTEGER}.
8627 At least one argument shall be present.
8629 @item @emph{Return value}:
8631 @code{SELECTED_REAL_KIND} returns the value of the kind type parameter of
8632 a real data type with decimal precision of at least @code{P} digits and a
8633 decimal exponent range of at least @code{R}. If more than one real data
8634 type meet the criteria, the kind of the data type with the smallest
8635 decimal precision is returned. If no real data type matches the criteria,
8638 @item -1 if the processor does not support a real data type with a
8639 precision greater than or equal to @code{P}
8640 @item -2 if the processor does not support a real type with an exponent
8641 range greater than or equal to @code{R}
8642 @item -3 if neither is supported.
8645 @item @emph{Example}:
8648 integer,parameter :: p6 = selected_real_kind(6)
8649 integer,parameter :: p10r100 = selected_real_kind(10,100)
8650 integer,parameter :: r400 = selected_real_kind(r=400)
8652 real(kind=p10r100) :: y
8653 real(kind=r400) :: z
8655 print *, precision(x), range(x)
8656 print *, precision(y), range(y)
8657 print *, precision(z), range(z)
8658 end program real_kinds
8665 @section @code{SET_EXPONENT} --- Set the exponent of the model
8666 @fnindex SET_EXPONENT
8667 @cindex real number, set exponent
8668 @cindex floating point, set exponent
8671 @item @emph{Description}:
8672 @code{SET_EXPONENT(X, I)} returns the real number whose fractional part
8673 is that that of @var{X} and whose exponent part is @var{I}.
8675 @item @emph{Standard}:
8681 @item @emph{Syntax}:
8682 @code{RESULT = SET_EXPONENT(X, I)}
8684 @item @emph{Arguments}:
8685 @multitable @columnfractions .15 .70
8686 @item @var{X} @tab Shall be of type @code{REAL}.
8687 @item @var{I} @tab Shall be of type @code{INTEGER}.
8690 @item @emph{Return value}:
8691 The return value is of the same type and kind as @var{X}.
8692 The real number whose fractional part
8693 is that that of @var{X} and whose exponent part if @var{I} is returned;
8694 it is @code{FRACTION(X) * RADIX(X)**I}.
8696 @item @emph{Example}:
8699 REAL :: x = 178.1387e-4
8701 PRINT *, SET_EXPONENT(x, i), FRACTION(x) * RADIX(x)**i
8710 @section @code{SHAPE} --- Determine the shape of an array
8712 @cindex array, shape
8715 @item @emph{Description}:
8716 Determines the shape of an array.
8718 @item @emph{Standard}:
8724 @item @emph{Syntax}:
8725 @code{RESULT = SHAPE(SOURCE)}
8727 @item @emph{Arguments}:
8728 @multitable @columnfractions .15 .70
8729 @item @var{SOURCE} @tab Shall be an array or scalar of any type.
8730 If @var{SOURCE} is a pointer it must be associated and allocatable
8731 arrays must be allocated.
8734 @item @emph{Return value}:
8735 An @code{INTEGER} array of rank one with as many elements as @var{SOURCE}
8736 has dimensions. The elements of the resulting array correspond to the extend
8737 of @var{SOURCE} along the respective dimensions. If @var{SOURCE} is a scalar,
8738 the result is the rank one array of size zero.
8740 @item @emph{Example}:
8743 INTEGER, DIMENSION(-1:1, -1:2) :: A
8744 WRITE(*,*) SHAPE(A) ! (/ 3, 4 /)
8745 WRITE(*,*) SIZE(SHAPE(42)) ! (/ /)
8749 @item @emph{See also}:
8750 @ref{RESHAPE}, @ref{SIZE}
8756 @section @code{SIGN} --- Sign copying function
8760 @cindex sign copying
8763 @item @emph{Description}:
8764 @code{SIGN(A,B)} returns the value of @var{A} with the sign of @var{B}.
8766 @item @emph{Standard}:
8772 @item @emph{Syntax}:
8773 @code{RESULT = SIGN(A, B)}
8775 @item @emph{Arguments}:
8776 @multitable @columnfractions .15 .70
8777 @item @var{A} @tab Shall be of type @code{INTEGER} or @code{REAL}
8778 @item @var{B} @tab Shall be of the same type and kind as @var{A}
8781 @item @emph{Return value}:
8782 The kind of the return value is that of @var{A} and @var{B}.
8783 If @math{B\ge 0} then the result is @code{ABS(A)}, else
8784 it is @code{-ABS(A)}.
8786 @item @emph{Example}:
8789 print *, sign(-12,1)
8790 print *, sign(-12,0)
8791 print *, sign(-12,-1)
8793 print *, sign(-12.,1.)
8794 print *, sign(-12.,0.)
8795 print *, sign(-12.,-1.)
8796 end program test_sign
8799 @item @emph{Specific names}:
8800 @multitable @columnfractions .20 .20 .20 .25
8801 @item Name @tab Arguments @tab Return type @tab Standard
8802 @item @code{ISIGN(A,P)} @tab @code{INTEGER(4)} @tab @code{INTEGER(4)} @tab f95, gnu
8803 @item @code{DSIGN(A,P)} @tab @code{REAL(8)} @tab @code{REAL(8)} @tab f95, gnu
8810 @section @code{SIGNAL} --- Signal handling subroutine (or function)
8812 @cindex system, signal handling
8815 @item @emph{Description}:
8816 @code{SIGNAL(NUMBER, HANDLER [, STATUS])} causes external subroutine
8817 @var{HANDLER} to be executed with a single integer argument when signal
8818 @var{NUMBER} occurs. If @var{HANDLER} is an integer, it can be used to
8819 turn off handling of signal @var{NUMBER} or revert to its default
8820 action. See @code{signal(2)}.
8822 If @code{SIGNAL} is called as a subroutine and the @var{STATUS} argument
8823 is supplied, it is set to the value returned by @code{signal(2)}.
8825 @item @emph{Standard}:
8829 Subroutine, non-elemental function
8831 @item @emph{Syntax}:
8832 @multitable @columnfractions .80
8833 @item @code{CALL SIGNAL(NUMBER, HANDLER [, STATUS])}
8834 @item @code{STATUS = SIGNAL(NUMBER, HANDLER)}
8837 @item @emph{Arguments}:
8838 @multitable @columnfractions .15 .70
8839 @item @var{NUMBER} @tab Shall be a scalar integer, with @code{INTENT(IN)}
8840 @item @var{HANDLER}@tab Signal handler (@code{INTEGER FUNCTION} or
8841 @code{SUBROUTINE}) or dummy/global @code{INTEGER} scalar.
8842 @code{INTEGER}. It is @code{INTENT(IN)}.
8843 @item @var{STATUS} @tab (Optional) @var{STATUS} shall be a scalar
8844 integer. It has @code{INTENT(OUT)}.
8847 @item @emph{Return value}:
8848 The @code{SIGNAL} function returns the value returned by @code{signal(2)}.
8850 @item @emph{Example}:
8854 external handler_print
8856 call signal (12, handler_print)
8860 end program test_signal
8867 @section @code{SIN} --- Sine function
8873 @cindex trigonometric function, sine
8877 @item @emph{Description}:
8878 @code{SIN(X)} computes the sine of @var{X}.
8880 @item @emph{Standard}:
8886 @item @emph{Syntax}:
8887 @code{RESULT = SIN(X)}
8889 @item @emph{Arguments}:
8890 @multitable @columnfractions .15 .70
8891 @item @var{X} @tab The type shall be @code{REAL(*)} or
8895 @item @emph{Return value}:
8896 The return value has same type and kind as @var{X}.
8898 @item @emph{Example}:
8903 end program test_sin
8906 @item @emph{Specific names}:
8907 @multitable @columnfractions .20 .20 .20 .25
8908 @item Name @tab Argument @tab Return type @tab Standard
8909 @item @code{DSIN(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab f95, gnu
8910 @item @code{CSIN(X)} @tab @code{COMPLEX(4) X} @tab @code{COMPLEX(4)} @tab f95, gnu
8911 @item @code{ZSIN(X)} @tab @code{COMPLEX(8) X} @tab @code{COMPLEX(8)} @tab f95, gnu
8912 @item @code{CDSIN(X)} @tab @code{COMPLEX(8) X} @tab @code{COMPLEX(8)} @tab f95, gnu
8915 @item @emph{See also}:
8922 @section @code{SINH} --- Hyperbolic sine function
8925 @cindex hyperbolic sine
8926 @cindex hyperbolic function, sine
8927 @cindex sine, hyperbolic
8930 @item @emph{Description}:
8931 @code{SINH(X)} computes the hyperbolic sine of @var{X}.
8933 @item @emph{Standard}:
8939 @item @emph{Syntax}:
8940 @code{RESULT = SINH(X)}
8942 @item @emph{Arguments}:
8943 @multitable @columnfractions .15 .70
8944 @item @var{X} @tab The type shall be @code{REAL(*)}.
8947 @item @emph{Return value}:
8948 The return value is of type @code{REAL(*)}.
8950 @item @emph{Example}:
8953 real(8) :: x = - 1.0_8
8955 end program test_sinh
8958 @item @emph{Specific names}:
8959 @multitable @columnfractions .20 .20 .20 .25
8960 @item Name @tab Argument @tab Return type @tab Standard
8961 @item @code{DSINH(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab F95 and later
8964 @item @emph{See also}:
8971 @section @code{SIZE} --- Determine the size of an array
8974 @cindex array, number of elements
8975 @cindex array, count elements
8978 @item @emph{Description}:
8979 Determine the extent of @var{ARRAY} along a specified dimension @var{DIM},
8980 or the total number of elements in @var{ARRAY} if @var{DIM} is absent.
8982 @item @emph{Standard}:
8988 @item @emph{Syntax}:
8989 @code{RESULT = SIZE(ARRAY[, DIM])}
8991 @item @emph{Arguments}:
8992 @multitable @columnfractions .15 .70
8993 @item @var{ARRAY} @tab Shall be an array of any type. If @var{ARRAY} is
8994 a pointer it must be associated and allocatable arrays must be allocated.
8995 @item @var{DIM} @tab (Optional) shall be a scalar of type @code{INTEGER}
8996 and its value shall be in the range from 1 to n, where n equals the rank
9000 @item @emph{Return value}:
9001 The return value is of type @code{INTEGER} and of the default
9004 @item @emph{Example}:
9007 WRITE(*,*) SIZE((/ 1, 2 /)) ! 2
9011 @item @emph{See also}:
9012 @ref{SHAPE}, @ref{RESHAPE}
9017 @section @code{SIZEOF} --- Size in bytes of an expression
9019 @cindex expression size
9020 @cindex size of an expression
9023 @item @emph{Description}:
9024 @code{SIZEOF(X)} calculates the number of bytes of storage the
9025 expression @code{X} occupies.
9027 @item @emph{Standard}:
9033 @item @emph{Syntax}:
9034 @code{N = SIZEOF(X)}
9036 @item @emph{Arguments}:
9037 @multitable @columnfractions .15 .70
9038 @item @var{X} @tab The argument shall be of any type, rank or shape.
9041 @item @emph{Return value}:
9042 The return value is of type integer. Its value is the number of bytes
9043 occupied by the argument. If the argument has the @code{POINTER}
9044 attribute, the number of bytes of the storage area pointed to is
9045 returned. If the argument is of a derived type with @code{POINTER} or
9046 @code{ALLOCATABLE} components, the return value doesn't account for
9047 the sizes of the data pointed to by these components.
9049 @item @emph{Example}:
9053 print *, (sizeof(s)/sizeof(r) == 5)
9056 The example will print @code{.TRUE.} unless you are using a platform
9057 where default @code{REAL} variables are unusually padded.
9061 @section @code{SLEEP} --- Sleep for the specified number of seconds
9063 @cindex delayed execution
9066 @item @emph{Description}:
9067 Calling this subroutine causes the process to pause for @var{SECONDS} seconds.
9069 @item @emph{Standard}:
9075 @item @emph{Syntax}:
9076 @code{CALL SLEEP(SECONDS)}
9078 @item @emph{Arguments}:
9079 @multitable @columnfractions .15 .70
9080 @item @var{SECONDS} @tab The type shall be of default @code{INTEGER}.
9083 @item @emph{Example}:
9094 @section @code{SNGL} --- Convert double precision real to default real
9096 @cindex conversion, to real
9099 @item @emph{Description}:
9100 @code{SNGL(A)} converts the double precision real @var{A}
9101 to a default real value. This is an archaic form of @code{REAL}
9102 that is specific to one type for @var{A}.
9104 @item @emph{Standard}:
9110 @item @emph{Syntax}:
9111 @code{RESULT = SNGL(A)}
9113 @item @emph{Arguments}:
9114 @multitable @columnfractions .15 .70
9115 @item @var{A} @tab The type shall be a double precision @code{REAL}.
9118 @item @emph{Return value}:
9119 The return value is of type default @code{REAL}.
9121 @item @emph{See also}:
9128 @section @code{SPACING} --- Smallest distance between two numbers of a given type
9130 @cindex real number, relative spacing
9131 @cindex floating point, relative spacing
9134 @item @emph{Description}:
9135 Determines the distance between the argument @var{X} and the nearest
9136 adjacent number of the same type.
9138 @item @emph{Standard}:
9144 @item @emph{Syntax}:
9145 @code{RESULT = SPACING(X)}
9147 @item @emph{Arguments}:
9148 @multitable @columnfractions .15 .70
9149 @item @var{X} @tab Shall be of type @code{REAL(*)}.
9152 @item @emph{Return value}:
9153 The result is of the same type as the input argument @var{X}.
9155 @item @emph{Example}:
9157 PROGRAM test_spacing
9158 INTEGER, PARAMETER :: SGL = SELECTED_REAL_KIND(p=6, r=37)
9159 INTEGER, PARAMETER :: DBL = SELECTED_REAL_KIND(p=13, r=200)
9161 WRITE(*,*) spacing(1.0_SGL) ! "1.1920929E-07" on i686
9162 WRITE(*,*) spacing(1.0_DBL) ! "2.220446049250313E-016" on i686
9166 @item @emph{See also}:
9173 @section @code{SPREAD} --- Add a dimension to an array
9175 @cindex array, increase dimension
9176 @cindex array, duplicate elements
9177 @cindex array, duplicate dimensions
9180 @item @emph{Description}:
9181 Replicates a @var{SOURCE} array @var{NCOPIES} times along a specified
9182 dimension @var{DIM}.
9184 @item @emph{Standard}:
9188 Transformational function
9190 @item @emph{Syntax}:
9191 @code{RESULT = SPREAD(SOURCE, DIM, NCOPIES)}
9193 @item @emph{Arguments}:
9194 @multitable @columnfractions .15 .70
9195 @item @var{SOURCE} @tab Shall be a scalar or an array of any type and
9196 a rank less than seven.
9197 @item @var{DIM} @tab Shall be a scalar of type @code{INTEGER} with a
9198 value in the range from 1 to n+1, where n equals the rank of @var{SOURCE}.
9199 @item @var{NCOPIES} @tab Shall be a scalar of type @code{INTEGER}.
9202 @item @emph{Return value}:
9203 The result is an array of the same type as @var{SOURCE} and has rank n+1
9204 where n equals the rank of @var{SOURCE}.
9206 @item @emph{Example}:
9209 INTEGER :: a = 1, b(2) = (/ 1, 2 /)
9210 WRITE(*,*) SPREAD(A, 1, 2) ! "1 1"
9211 WRITE(*,*) SPREAD(B, 1, 2) ! "1 1 2 2"
9215 @item @emph{See also}:
9222 @section @code{SQRT} --- Square-root function
9232 @item @emph{Description}:
9233 @code{SQRT(X)} computes the square root of @var{X}.
9235 @item @emph{Standard}:
9241 @item @emph{Syntax}:
9242 @code{RESULT = SQRT(X)}
9244 @item @emph{Arguments}:
9245 @multitable @columnfractions .15 .70
9246 @item @var{X} @tab The type shall be @code{REAL(*)} or
9250 @item @emph{Return value}:
9251 The return value is of type @code{REAL(*)} or @code{COMPLEX(*)}.
9252 The kind type parameter is the same as @var{X}.
9254 @item @emph{Example}:
9257 real(8) :: x = 2.0_8
9258 complex :: z = (1.0, 2.0)
9261 end program test_sqrt
9264 @item @emph{Specific names}:
9265 @multitable @columnfractions .20 .20 .20 .25
9266 @item Name @tab Argument @tab Return type @tab Standard
9267 @item @code{DSQRT(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab F95 and later
9268 @item @code{CSQRT(X)} @tab @code{COMPLEX(4) X} @tab @code{COMPLEX(4)} @tab F95 and later
9269 @item @code{ZSQRT(X)} @tab @code{COMPLEX(8) X} @tab @code{COMPLEX(8)} @tab GNU extension
9270 @item @code{CDSQRT(X)} @tab @code{COMPLEX(8) X} @tab @code{COMPLEX(8)} @tab GNU extension
9277 @section @code{SRAND} --- Reinitialize the random number generator
9279 @cindex random number generation, seeding
9280 @cindex seeding a random number generator
9283 @item @emph{Description}:
9284 @code{SRAND} reinitializes the pseudo-random number generator
9285 called by @code{RAND} and @code{IRAND}. The new seed used by the
9286 generator is specified by the required argument @var{SEED}.
9288 @item @emph{Standard}:
9292 Non-elemental subroutine
9294 @item @emph{Syntax}:
9295 @code{CALL SRAND(SEED)}
9297 @item @emph{Arguments}:
9298 @multitable @columnfractions .15 .70
9299 @item @var{SEED} @tab Shall be a scalar @code{INTEGER(kind=4)}.
9302 @item @emph{Return value}:
9305 @item @emph{Example}:
9306 See @code{RAND} and @code{IRAND} for examples.
9309 The Fortran 2003 standard specifies the intrinsic @code{RANDOM_SEED} to
9310 initialize the pseudo-random numbers generator and @code{RANDOM_NUMBER}
9311 to generate pseudo-random numbers. Please note that in
9312 GNU Fortran, these two sets of intrinsics (@code{RAND},
9313 @code{IRAND} and @code{SRAND} on the one hand, @code{RANDOM_NUMBER} and
9314 @code{RANDOM_SEED} on the other hand) access two independent
9315 pseudo-random number generators.
9317 @item @emph{See also}:
9318 @ref{RAND}, @ref{RANDOM_SEED}, @ref{RANDOM_NUMBER}
9325 @section @code{STAT} --- Get file status
9327 @cindex file system, file status
9330 @item @emph{Description}:
9331 This function returns information about a file. No permissions are required on
9332 the file itself, but execute (search) permission is required on all of the
9333 directories in path that lead to the file.
9335 The elements that are obtained and stored in the array @code{BUFF}:
9336 @multitable @columnfractions .15 .70
9337 @item @code{buff(1)} @tab Device ID
9338 @item @code{buff(2)} @tab Inode number
9339 @item @code{buff(3)} @tab File mode
9340 @item @code{buff(4)} @tab Number of links
9341 @item @code{buff(5)} @tab Owner's uid
9342 @item @code{buff(6)} @tab Owner's gid
9343 @item @code{buff(7)} @tab ID of device containing directory entry for file (0 if not available)
9344 @item @code{buff(8)} @tab File size (bytes)
9345 @item @code{buff(9)} @tab Last access time
9346 @item @code{buff(10)} @tab Last modification time
9347 @item @code{buff(11)} @tab Last file status change time
9348 @item @code{buff(12)} @tab Preferred I/O block size (-1 if not available)
9349 @item @code{buff(13)} @tab Number of blocks allocated (-1 if not available)
9352 Not all these elements are relevant on all systems.
9353 If an element is not relevant, it is returned as 0.
9356 @item @emph{Standard}:
9360 Non-elemental subroutine
9362 @item @emph{Syntax}:
9363 @code{CALL STAT(FILE,BUFF[,STATUS])}
9365 @item @emph{Arguments}:
9366 @multitable @columnfractions .15 .70
9367 @item @var{FILE} @tab The type shall be @code{CHARACTER(*)}, a valid path within the file system.
9368 @item @var{BUFF} @tab The type shall be @code{INTEGER(4), DIMENSION(13)}.
9369 @item @var{STATUS} @tab (Optional) status flag of type @code{INTEGER(4)}. Returns 0
9370 on success and a system specific error code otherwise.
9373 @item @emph{Example}:
9376 INTEGER, DIMENSION(13) :: buff
9379 CALL STAT("/etc/passwd", buff, status)
9381 IF (status == 0) THEN
9382 WRITE (*, FMT="('Device ID:', T30, I19)") buff(1)
9383 WRITE (*, FMT="('Inode number:', T30, I19)") buff(2)
9384 WRITE (*, FMT="('File mode (octal):', T30, O19)") buff(3)
9385 WRITE (*, FMT="('Number of links:', T30, I19)") buff(4)
9386 WRITE (*, FMT="('Owner''s uid:', T30, I19)") buff(5)
9387 WRITE (*, FMT="('Owner''s gid:', T30, I19)") buff(6)
9388 WRITE (*, FMT="('Device where located:', T30, I19)") buff(7)
9389 WRITE (*, FMT="('File size:', T30, I19)") buff(8)
9390 WRITE (*, FMT="('Last access time:', T30, A19)") CTIME(buff(9))
9391 WRITE (*, FMT="('Last modification time', T30, A19)") CTIME(buff(10))
9392 WRITE (*, FMT="('Last status change time:', T30, A19)") CTIME(buff(11))
9393 WRITE (*, FMT="('Preferred block size:', T30, I19)") buff(12)
9394 WRITE (*, FMT="('No. of blocks allocated:', T30, I19)") buff(13)
9399 @item @emph{See also}:
9400 To stat an open file: @ref{FSTAT}, to stat a link: @ref{LSTAT}
9406 @section @code{SUM} --- Sum of array elements
9409 @cindex array, add elements
9410 @cindex array, conditionally add elements
9411 @cindex sum array elements
9414 @item @emph{Description}:
9415 Adds the elements of @var{ARRAY} along dimension @var{DIM} if
9416 the corresponding element in @var{MASK} is @code{TRUE}.
9418 @item @emph{Standard}:
9422 Transformational function
9424 @item @emph{Syntax}:
9425 @code{RESULT = SUM(ARRAY[, MASK])}
9426 @code{RESULT = SUM(ARRAY, DIM[, MASK])}
9428 @item @emph{Arguments}:
9429 @multitable @columnfractions .15 .70
9430 @item @var{ARRAY} @tab Shall be an array of type @code{INTEGER(*)},
9431 @code{REAL(*)} or @code{COMPLEX(*)}.
9432 @item @var{DIM} @tab (Optional) shall be a scalar of type
9433 @code{INTEGER} with a value in the range from 1 to n, where n
9434 equals the rank of @var{ARRAY}.
9435 @item @var{MASK} @tab (Optional) shall be of type @code{LOGICAL}
9436 and either be a scalar or an array of the same shape as @var{ARRAY}.
9439 @item @emph{Return value}:
9440 The result is of the same type as @var{ARRAY}.
9442 If @var{DIM} is absent, a scalar with the sum of all elements in @var{ARRAY}
9443 is returned. Otherwise, an array of rank n-1, where n equals the rank of
9444 @var{ARRAY},and a shape similar to that of @var{ARRAY} with dimension @var{DIM}
9445 dropped is returned.
9447 @item @emph{Example}:
9450 INTEGER :: x(5) = (/ 1, 2, 3, 4 ,5 /)
9451 print *, SUM(x) ! all elements, sum = 15
9452 print *, SUM(x, MASK=MOD(x, 2)==1) ! odd elements, sum = 9
9456 @item @emph{See also}:
9463 @section @code{SYMLNK} --- Create a symbolic link
9465 @cindex file system, create link
9466 @cindex file system, soft link
9469 @item @emph{Description}:
9470 Makes a symbolic link from file @var{PATH1} to @var{PATH2}. A null
9471 character (@code{CHAR(0)}) can be used to mark the end of the names in
9472 @var{PATH1} and @var{PATH2}; otherwise, trailing blanks in the file
9473 names are ignored. If the @var{STATUS} argument is supplied, it
9474 contains 0 on success or a nonzero error code upon return; see
9475 @code{symlink(2)}. If the system does not supply @code{symlink(2)},
9476 @code{ENOSYS} is returned.
9478 This intrinsic is provided in both subroutine and function forms;
9479 however, only one form can be used in any given program unit.
9481 @item @emph{Standard}:
9485 Subroutine, non-elemental function
9487 @item @emph{Syntax}:
9488 @multitable @columnfractions .80
9489 @item @code{CALL SYMLNK(PATH1, PATH2 [, STATUS])}
9490 @item @code{STATUS = SYMLNK(PATH1, PATH2)}
9493 @item @emph{Arguments}:
9494 @multitable @columnfractions .15 .70
9495 @item @var{PATH1} @tab Shall be of default @code{CHARACTER} type.
9496 @item @var{PATH2} @tab Shall be of default @code{CHARACTER} type.
9497 @item @var{STATUS} @tab (Optional) Shall be of default @code{INTEGER} type.
9500 @item @emph{See also}:
9501 @ref{LINK}, @ref{UNLINK}
9508 @section @code{SYSTEM} --- Execute a shell command
9510 @cindex system, system call
9513 @item @emph{Description}:
9514 Passes the command @var{COMMAND} to a shell (see @code{system(3)}). If
9515 argument @var{STATUS} is present, it contains the value returned by
9516 @code{system(3)}, which is presumably 0 if the shell command succeeded.
9517 Note that which shell is used to invoke the command is system-dependent
9518 and environment-dependent.
9520 This intrinsic is provided in both subroutine and function forms;
9521 however, only one form can be used in any given program unit.
9523 @item @emph{Standard}:
9527 Subroutine, non-elemental function
9529 @item @emph{Syntax}:
9530 @multitable @columnfractions .80
9531 @item @code{CALL SYSTEM(COMMAND [, STATUS])}
9532 @item @code{STATUS = SYSTEM(COMMAND)}
9535 @item @emph{Arguments}:
9536 @multitable @columnfractions .15 .70
9537 @item @var{COMMAND} @tab Shall be of default @code{CHARACTER} type.
9538 @item @var{STATUS} @tab (Optional) Shall be of default @code{INTEGER} type.
9541 @item @emph{See also}:
9547 @section @code{SYSTEM_CLOCK} --- Time function
9548 @fnindex SYSTEM_CLOCK
9549 @cindex time, clock ticks
9553 @item @emph{Description}:
9554 Determines the @var{COUNT} of milliseconds of wall clock time since
9555 the Epoch (00:00:00 UTC, January 1, 1970) modulo @var{COUNT_MAX},
9556 @var{COUNT_RATE} determines the number of clock ticks per second.
9557 @var{COUNT_RATE} and @var{COUNT_MAX} are constant and specific to
9560 If there is no clock, @var{COUNT} is set to @code{-HUGE(COUNT)}, and
9561 @var{COUNT_RATE} and @var{COUNT_MAX} are set to zero
9563 @item @emph{Standard}:
9569 @item @emph{Syntax}:
9570 @code{CALL SYSTEM_CLOCK([COUNT, COUNT_RATE, COUNT_MAX])}
9572 @item @emph{Arguments}:
9573 @item @emph{Arguments}:
9574 @multitable @columnfractions .15 .70
9575 @item @var{COUNT} @tab (Optional) shall be a scalar of type default
9576 @code{INTEGER} with @code{INTENT(OUT)}.
9577 @item @var{COUNT_RATE} @tab (Optional) shall be a scalar of type default
9578 @code{INTEGER} with @code{INTENT(OUT)}.
9579 @item @var{COUNT_MAX} @tab (Optional) shall be a scalar of type default
9580 @code{INTEGER} with @code{INTENT(OUT)}.
9583 @item @emph{Example}:
9585 PROGRAM test_system_clock
9586 INTEGER :: count, count_rate, count_max
9587 CALL SYSTEM_CLOCK(count, count_rate, count_max)
9588 WRITE(*,*) count, count_rate, count_max
9592 @item @emph{See also}:
9593 @ref{DATE_AND_TIME}, @ref{CPU_TIME}
9599 @section @code{TAN} --- Tangent function
9602 @cindex trigonometric function, tangent
9606 @item @emph{Description}:
9607 @code{TAN(X)} computes the tangent of @var{X}.
9609 @item @emph{Standard}:
9615 @item @emph{Syntax}:
9616 @code{RESULT = TAN(X)}
9618 @item @emph{Arguments}:
9619 @multitable @columnfractions .15 .70
9620 @item @var{X} @tab The type shall be @code{REAL(*)}.
9623 @item @emph{Return value}:
9624 The return value is of type @code{REAL(*)}. The kind type parameter is
9625 the same as @var{X}.
9627 @item @emph{Example}:
9630 real(8) :: x = 0.165_8
9632 end program test_tan
9635 @item @emph{Specific names}:
9636 @multitable @columnfractions .20 .20 .20 .25
9637 @item Name @tab Argument @tab Return type @tab Standard
9638 @item @code{DTAN(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab F95 and later
9641 @item @emph{See also}:
9648 @section @code{TANH} --- Hyperbolic tangent function
9651 @cindex hyperbolic tangent
9652 @cindex hyperbolic function, tangent
9653 @cindex tangent, hyperbolic
9656 @item @emph{Description}:
9657 @code{TANH(X)} computes the hyperbolic tangent of @var{X}.
9659 @item @emph{Standard}:
9665 @item @emph{Syntax}:
9668 @item @emph{Arguments}:
9669 @multitable @columnfractions .15 .70
9670 @item @var{X} @tab The type shall be @code{REAL(*)}.
9673 @item @emph{Return value}:
9674 The return value is of type @code{REAL(*)} and lies in the range
9675 @math{ - 1 \leq tanh(x) \leq 1 }.
9677 @item @emph{Example}:
9680 real(8) :: x = 2.1_8
9682 end program test_tanh
9685 @item @emph{Specific names}:
9686 @multitable @columnfractions .20 .20 .20 .25
9687 @item Name @tab Argument @tab Return type @tab Standard
9688 @item @code{DTANH(X)} @tab @code{REAL(8) X} @tab @code{REAL(8)} @tab F95 and later
9691 @item @emph{See also}:
9698 @section @code{TIME} --- Time function
9700 @cindex time, current
9701 @cindex current time
9704 @item @emph{Description}:
9705 Returns the current time encoded as an integer (in the manner of the
9706 UNIX function @code{time(3)}). This value is suitable for passing to
9707 @code{CTIME()}, @code{GMTIME()}, and @code{LTIME()}.
9709 This intrinsic is not fully portable, such as to systems with 32-bit
9710 @code{INTEGER} types but supporting times wider than 32 bits. Therefore,
9711 the values returned by this intrinsic might be, or become, negative, or
9712 numerically less than previous values, during a single run of the
9715 See @ref{TIME8}, for information on a similar intrinsic that might be
9716 portable to more GNU Fortran implementations, though to fewer Fortran
9719 @item @emph{Standard}:
9723 Non-elemental function
9725 @item @emph{Syntax}:
9726 @code{RESULT = TIME()}
9728 @item @emph{Return value}:
9729 The return value is a scalar of type @code{INTEGER(4)}.
9731 @item @emph{See also}:
9732 @ref{CTIME}, @ref{GMTIME}, @ref{LTIME}, @ref{MCLOCK}, @ref{TIME8}
9739 @section @code{TIME8} --- Time function (64-bit)
9741 @cindex time, current
9742 @cindex current time
9745 @item @emph{Description}:
9746 Returns the current time encoded as an integer (in the manner of the
9747 UNIX function @code{time(3)}). This value is suitable for passing to
9748 @code{CTIME()}, @code{GMTIME()}, and @code{LTIME()}.
9750 @emph{Warning:} this intrinsic does not increase the range of the timing
9751 values over that returned by @code{time(3)}. On a system with a 32-bit
9752 @code{time(3)}, @code{TIME8()} will return a 32-bit value, even though
9753 it is converted to a 64-bit @code{INTEGER(8)} value. That means
9754 overflows of the 32-bit value can still occur. Therefore, the values
9755 returned by this intrinsic might be or become negative or numerically
9756 less than previous values during a single run of the compiled program.
9758 @item @emph{Standard}:
9762 Non-elemental function
9764 @item @emph{Syntax}:
9765 @code{RESULT = TIME8()}
9767 @item @emph{Return value}:
9768 The return value is a scalar of type @code{INTEGER(8)}.
9770 @item @emph{See also}:
9771 @ref{CTIME}, @ref{GMTIME}, @ref{LTIME}, @ref{MCLOCK8}, @ref{TIME}
9778 @section @code{TINY} --- Smallest positive number of a real kind
9780 @cindex limits, smallest number
9781 @cindex model representation, smallest number
9784 @item @emph{Description}:
9785 @code{TINY(X)} returns the smallest positive (non zero) number
9786 in the model of the type of @code{X}.
9788 @item @emph{Standard}:
9794 @item @emph{Syntax}:
9795 @code{RESULT = TINY(X)}
9797 @item @emph{Arguments}:
9798 @multitable @columnfractions .15 .70
9799 @item @var{X} @tab Shall be of type @code{REAL}.
9802 @item @emph{Return value}:
9803 The return value is of the same type and kind as @var{X}
9805 @item @emph{Example}:
9806 See @code{HUGE} for an example.
9812 @section @code{TRANSFER} --- Transfer bit patterns
9818 @item @emph{Description}:
9819 Interprets the bitwise representation of @var{SOURCE} in memory as if it
9820 is the representation of a variable or array of the same type and type
9821 parameters as @var{MOLD}.
9823 This is approximately equivalent to the C concept of @emph{casting} one
9826 @item @emph{Standard}:
9830 Transformational function
9832 @item @emph{Syntax}:
9833 @code{RESULT = TRANSFER(SOURCE, MOLD[, SIZE])}
9835 @item @emph{Arguments}:
9836 @multitable @columnfractions .15 .70
9837 @item @var{SOURCE} @tab Shall be a scalar or an array of any type.
9838 @item @var{MOLD} @tab Shall be a scalar or an array of any type.
9839 @item @var{SIZE} @tab (Optional) shall be a scalar of type
9843 @item @emph{Return value}:
9844 The result has the same type as @var{MOLD}, with the bit level
9845 representation of @var{SOURCE}. If @var{SIZE} is present, the result is
9846 a one-dimensional array of length @var{SIZE}. If @var{SIZE} is absent
9847 but @var{MOLD} is an array (of any size or shape), the result is a one-
9848 dimensional array of the minimum length needed to contain the entirety
9849 of the bitwise representation of @var{SOURCE}. If @var{SIZE} is absent
9850 and @var{MOLD} is a scalar, the result is a scalar.
9852 If the bitwise representation of the result is longer than that of
9853 @var{SOURCE}, then the leading bits of the result correspond to those of
9854 @var{SOURCE} and any trailing bits are filled arbitrarily.
9856 When the resulting bit representation does not correspond to a valid
9857 representation of a variable of the same type as @var{MOLD}, the results
9858 are undefined, and subsequent operations on the result cannot be
9859 guaranteed to produce sensible behavior. For example, it is possible to
9860 create @code{LOGICAL} variables for which @code{@var{VAR}} and
9861 @code{.NOT.@var{VAR}} both appear to be true.
9863 @item @emph{Example}:
9865 PROGRAM test_transfer
9866 integer :: x = 2143289344
9867 print *, transfer(x, 1.0) ! prints "NaN" on i686
9875 @section @code{TRANSPOSE} --- Transpose an array of rank two
9877 @cindex array, transpose
9878 @cindex matrix, transpose
9882 @item @emph{Description}:
9883 Transpose an array of rank two. Element (i, j) of the result has the value
9884 @code{MATRIX(j, i)}, for all i, j.
9886 @item @emph{Standard}:
9890 Transformational function
9892 @item @emph{Syntax}:
9893 @code{RESULT = TRANSPOSE(MATRIX)}
9895 @item @emph{Arguments}:
9896 @multitable @columnfractions .15 .70
9897 @item @var{MATRIX} @tab Shall be an array of any type and have a rank of two.
9900 @item @emph{Return value}:
9901 The result has the the same type as @var{MATRIX}, and has shape
9902 @code{(/ m, n /)} if @var{MATRIX} has shape @code{(/ n, m /)}.
9908 @section @code{TRIM} --- Remove trailing blank characters of a string
9910 @cindex string, remove trailing whitespace
9913 @item @emph{Description}:
9914 Removes trailing blank characters of a string.
9916 @item @emph{Standard}:
9920 Transformational function
9922 @item @emph{Syntax}:
9923 @code{RESULT = TRIM(STRING)}
9925 @item @emph{Arguments}:
9926 @multitable @columnfractions .15 .70
9927 @item @var{STRING} @tab Shall be a scalar of type @code{CHARACTER(*)}.
9930 @item @emph{Return value}:
9931 A scalar of type @code{CHARACTER(*)} which length is that of @var{STRING}
9932 less the number of trailing blanks.
9934 @item @emph{Example}:
9937 CHARACTER(len=10), PARAMETER :: s = "GFORTRAN "
9938 WRITE(*,*) LEN(s), LEN(TRIM(s)) ! "10 8", with/without trailing blanks
9942 @item @emph{See also}:
9943 @ref{ADJUSTL}, @ref{ADJUSTR}
9949 @section @code{TTYNAM} --- Get the name of a terminal device.
9951 @cindex system, terminal
9954 @item @emph{Description}:
9955 Get the name of a terminal device. For more information,
9956 see @code{ttyname(3)}.
9958 This intrinsic is provided in both subroutine and function forms;
9959 however, only one form can be used in any given program unit.
9961 @item @emph{Standard}:
9965 Subroutine, non-elemental function
9967 @item @emph{Syntax}:
9968 @multitable @columnfractions .80
9969 @item @code{CALL TTYNAM(UNIT, NAME)}
9970 @item @code{NAME = TTYNAM(UNIT)}
9973 @item @emph{Arguments}:
9974 @multitable @columnfractions .15 .70
9975 @item @var{UNIT} @tab Shall be a scalar @code{INTEGER(*)}.
9976 @item @var{NAME} @tab Shall be of type @code{CHARACTER(*)}.
9979 @item @emph{Example}:
9984 IF (isatty(unit=unit)) write(*,*) ttynam(unit)
9989 @item @emph{See also}:
9996 @section @code{UBOUND} --- Upper dimension bounds of an array
9998 @cindex array, upper bound
10001 @item @emph{Description}:
10002 Returns the upper bounds of an array, or a single upper bound
10003 along the @var{DIM} dimension.
10004 @item @emph{Standard}:
10007 @item @emph{Class}:
10010 @item @emph{Syntax}:
10011 @code{RESULT = UBOUND(ARRAY [, DIM])}
10013 @item @emph{Arguments}:
10014 @multitable @columnfractions .15 .70
10015 @item @var{ARRAY} @tab Shall be an array, of any type.
10016 @item @var{DIM} @tab (Optional) Shall be a scalar @code{INTEGER(*)}.
10019 @item @emph{Return value}:
10020 If @var{DIM} is absent, the result is an array of the upper bounds of
10021 @var{ARRAY}. If @var{DIM} is present, the result is a scalar
10022 corresponding to the upper bound of the array along that dimension. If
10023 @var{ARRAY} is an expression rather than a whole array or array
10024 structure component, or if it has a zero extent along the relevant
10025 dimension, the upper bound is taken to be the number of elements along
10026 the relevant dimension.
10028 @item @emph{See also}:
10035 @section @code{UMASK} --- Set the file creation mask
10037 @cindex file system, file creation mask
10040 @item @emph{Description}:
10041 Sets the file creation mask to @var{MASK} and returns the old value in
10042 argument @var{OLD} if it is supplied. See @code{umask(2)}.
10044 @item @emph{Standard}:
10047 @item @emph{Class}:
10050 @item @emph{Syntax}:
10051 @code{CALL UMASK(MASK [, OLD])}
10053 @item @emph{Arguments}:
10054 @multitable @columnfractions .15 .70
10055 @item @var{MASK} @tab Shall be a scalar of type @code{INTEGER(*)}.
10056 @item @var{MASK} @tab (Optional) Shall be a scalar of type
10065 @section @code{UNLINK} --- Remove a file from the file system
10067 @cindex file system, remove file
10070 @item @emph{Description}:
10071 Unlinks the file @var{PATH}. A null character (@code{CHAR(0)}) can be
10072 used to mark the end of the name in @var{PATH}; otherwise, trailing
10073 blanks in the file name are ignored. If the @var{STATUS} argument is
10074 supplied, it contains 0 on success or a nonzero error code upon return;
10075 see @code{unlink(2)}.
10077 This intrinsic is provided in both subroutine and function forms;
10078 however, only one form can be used in any given program unit.
10080 @item @emph{Standard}:
10083 @item @emph{Class}:
10084 Subroutine, non-elemental function
10086 @item @emph{Syntax}:
10087 @multitable @columnfractions .80
10088 @item @code{CALL UNLINK(PATH [, STATUS])}
10089 @item @code{STATUS = UNLINK(PATH)}
10092 @item @emph{Arguments}:
10093 @multitable @columnfractions .15 .70
10094 @item @var{PATH} @tab Shall be of default @code{CHARACTER} type.
10095 @item @var{STATUS} @tab (Optional) Shall be of default @code{INTEGER} type.
10098 @item @emph{See also}:
10099 @ref{LINK}, @ref{SYMLNK}
10105 @section @code{UNPACK} --- Unpack an array of rank one into an array
10107 @cindex array, unpacking
10108 @cindex array, increase dimension
10109 @cindex array, scatter elements
10112 @item @emph{Description}:
10113 Store the elements of @var{VECTOR} in an array of higher rank.
10115 @item @emph{Standard}:
10118 @item @emph{Class}:
10119 Transformational function
10121 @item @emph{Syntax}:
10122 @code{RESULT = UNPACK(VECTOR, MASK, FIELD)}
10124 @item @emph{Arguments}:
10125 @multitable @columnfractions .15 .70
10126 @item @var{VECTOR} @tab Shall be an array of any type and rank one. It
10127 shall have at least as many elements as @var{MASK} has @code{TRUE} values.
10128 @item @var{MASK} @tab Shall be an array of type @code{LOGICAL}.
10129 @item @var{FIELD} @tab Shall be of the sam type as @var{VECTOR} and have
10130 the same shape as @var{MASK}.
10133 @item @emph{Return value}:
10134 The resulting array corresponds to @var{FIELD} with @code{TRUE} elements
10135 of @var{MASK} replaced by values from @var{VECTOR} in array element order.
10137 @item @emph{Example}:
10139 PROGRAM test_unpack
10140 integer :: vector(2) = (/1,1/)
10141 logical :: mask(4) = (/ .TRUE., .FALSE., .FALSE., .TRUE. /)
10142 integer :: field(2,2) = 0, unity(2,2)
10144 ! result: unity matrix
10145 unity = unpack(vector, reshape(mask, (/2,2/)), field)
10149 @item @emph{See also}:
10150 @ref{PACK}, @ref{SPREAD}
10156 @section @code{VERIFY} --- Scan a string for the absence of a set of characters
10158 @cindex string, find missing set
10161 @item @emph{Description}:
10162 Verifies that all the characters in a @var{SET} are present in a @var{STRING}.
10164 If @var{BACK} is either absent or equals @code{FALSE}, this function
10165 returns the position of the leftmost character of @var{STRING} that is
10166 not in @var{SET}. If @var{BACK} equals @code{TRUE}, the rightmost position
10167 is returned. If all characters of @var{SET} are found in @var{STRING}, the
10170 @item @emph{Standard}:
10173 @item @emph{Class}:
10176 @item @emph{Syntax}:
10177 @code{RESULT = VERFIY(STRING, SET[, BACK])}
10179 @item @emph{Arguments}:
10180 @multitable @columnfractions .15 .70
10181 @item @var{STRING} @tab Shall be of type @code{CHARACTER(*)}.
10182 @item @var{SET} @tab Shall be of type @code{CHARACTER(*)}.
10183 @item @var{BACK} @tab (Optional) shall be of type @code{LOGICAL}.
10186 @item @emph{Return value}:
10187 The return value is of type @code{INTEGER} and of the default
10190 @item @emph{Example}:
10192 PROGRAM test_verify
10193 WRITE(*,*) VERIFY("FORTRAN", "AO") ! 1, found 'F'
10194 WRITE(*,*) VERIFY("FORTRAN", "FOO") ! 3, found 'R'
10195 WRITE(*,*) VERIFY("FORTRAN", "C++") ! 1, found 'F'
10196 WRITE(*,*) VERIFY("FORTRAN", "C++", .TRUE.) ! 7, found 'N'
10197 WRITE(*,*) VERIFY("FORTRAN", "FORTRAN") ! 0' found none
10201 @item @emph{See also}:
10202 @ref{SCAN}, @ref{INDEX}
10208 @section @code{XOR} --- Bitwise logical exclusive OR
10210 @cindex bitwise logical exclusive or
10211 @cindex logical exclusive or, bitwise
10214 @item @emph{Description}:
10215 Bitwise logical exclusive or.
10217 This intrinsic routine is provided for backwards compatibility with
10218 GNU Fortran 77. For integer arguments, programmers should consider
10219 the use of the @ref{IEOR} intrinsic defined by the Fortran standard.
10221 @item @emph{Standard}:
10224 @item @emph{Class}:
10225 Non-elemental function
10227 @item @emph{Syntax}:
10228 @code{RESULT = XOR(X, Y)}
10230 @item @emph{Arguments}:
10231 @multitable @columnfractions .15 .70
10232 @item @var{X} @tab The type shall be either @code{INTEGER(*)} or @code{LOGICAL}.
10233 @item @var{Y} @tab The type shall be either @code{INTEGER(*)} or @code{LOGICAL}.
10236 @item @emph{Return value}:
10237 The return type is either @code{INTEGER(*)} or @code{LOGICAL}
10238 after cross-promotion of the arguments.
10240 @item @emph{Example}:
10243 LOGICAL :: T = .TRUE., F = .FALSE.
10245 DATA a / Z'F' /, b / Z'3' /
10247 WRITE (*,*) XOR(T, T), XOR(T, F), XOR(F, T), XOR(F, F)
10248 WRITE (*,*) XOR(a, b)
10252 @item @emph{See also}:
10253 F95 elemental function: @ref{IEOR}